Merge branch 'release/20190120'

content/code/publishing-books-on-zola.md

@@ -0,0 +1,104 @@
++++
+title = "Publishing Books on Zola"
+date = 2015-12-18
+category = "thoughts"
+
+[taxonomies]
+tags = ["en-au", "books", "zola"]
++++
+
+A long time ago I wrote a couple of posts on a WordPress, then moved them to
+GitBook. Unfortunately, GitBook changed its layout to something a bit more
+confusing and now I'm bringing them back to this blog, which runs Zola.
+
+<!-- more -->
+
+Zola is a blog system; a static blog generator. It wasn't projected to be a
+publishing tool, but because it has support for publishing stuff without
+appearing in the main page, specialized templates for each page and
+shortcodes, I managed to come with a clever solution.
+
+But let's see how I did:
+
+## The Theme
+
+The first problem is tied to the current Zola themes: some of them lack
+support for tags, some for sections and some to both. For [After
+Dark](https://github.com/getzola/after-dark/), I
+had to add support for both, but renamed it to
+[Nighttime](https://github.com/jbiason/nighttime). This allows
+putting the books in their own sections, which helps the general organization
+of the content.
+
+## Hiding Book Posts From Main Site
+
+Each Zola section needs a `_index.md` file with the meta information for the
+section; for example, it's title.
+
+To make posts in a section not appear in the main site (you know, the site
+index), you need to set a property in its meta information: `transparent`.
+When a section is transparent, posts inside the section will not appear in the
+main index and, thus, will be contained only on the section.
+
+... unless you want to make some "episodic" chapters and allow them to appear
+in the main site. That's up for you.
+
+## Post Order in the Section
+
+By default, posts in sections are ordered from the most recent to the oldest,
+based on their published date. You can change this by changing the `sort_by`
+property in the section to `weight`, which will show posts by weight, from the
+lightest to the heaviest.
+
+Why would you want to change the order of posts in the section? 'Cause the
+section content works pretty damn fine as a general index for your book, which
+each post as a chapter.
+
+All fine and dandy, but the fact is that posts titles, with their dates and
+summaries, is not a very good index. But Zola has a workaround for this: Each
+section data can also have a `template` option, which allows using a different
+template for that section alone. In my case, I created a template on
+"Nighttime" that have all the meta information but not the posts in it, called
+`section-contentless.html`. 
+
+But what is good about a section/book with a title and an empty index? That's
+another thing Zola can do: If you add any content in the `_index.md`, it will
+be rendered normally. So you can write the index yourself (which is not
+optimal, but it works).
+
+As a side note, you can also create a template which shows only the post
+title, no summary or date, and use the weight solution.
+
+## Navigation
+
+Although you can now display the book with its chapters, it still is a bit
+hard for readers to do a nice, continuous reading if they need to go back to
+the index after reading a chapter to get to the next.
+
+For that, you can use a shortcode to add the navigation at the bottom of each
+post. Something like this:
+
+```jinja
+<div>
+	{% if prev_chapter_link %}
+		<div style="float:left">
+			&lt;&lt; <a href="{{ prev_chapter_link }}">{{ prev_chapter_title }}</a>
+		</div>
+	{% endif %}
+
+	&nbsp;
+
+	{% if next_chapter_link %}
+		<div style="float:right">
+			<a href="{{ next_chapter_link }}">{{ next_chapter_title }}</a> &gt;&gt;
+		</div>
+	{% endif %}
+</div>
+```
+
+And then, adding in the end of each post a 
+`{{ nav(prev_chapter_link="<link>", prev_chapter_title="Title", next_chapter_link="<link>", next_chapter_title="Title") }}` 
+and Zola will add the HTML (with the parameters) at the bottom of each post,
+making navigation easier.
+
+And that's basically it!

content/thoughts/one-week-with-tiler/index.md

@@ -0,0 +1,76 @@
++++
+title = "One Week with Tiler"
+date = 2019-01-19
+
+[taxonomies]
+tags = ["vim", "en-au", "plugins", "tiler", "tiling"]
++++
+
+Tiler is a tiling split manager for VIM. Here is my experience with it
+installed for one week.
+
+<!-- more -->
+
+Recently I had to work with Java (instead of Python) and one thing that happens
+when you're working with Java is that you have a bunch of files open at the
+same time. Also, I do prefer to keep things in splits 'cause there is always
+some information you need to keep visible for reference. But a lot of splits
+make visibly finding stuff very *very* hard.
+
+Then suddenly, it hit me: I could use a tiling window manager and it wouldn't
+be such a mess; on the other hand, using different windows for each VIM (with
+each file) would make copying'n'pasting a hell. So if I could actually find a
+tiling *plugin*, that would give me the best of both worlds.
+
+And that's where [Tiler](https://github.com/zhamlin/tiler.vim) gets in.
+
+Tiler is a tiling plugin for VIM. But it doesn't do anything by itself,
+meaning, it won't intercept every call to a split to do the tiling. But itadds
+new commands to manage the tiling.
+
+For example, to open a new split using the tiling, you need to use
+`:TilerOpen`. Again, Tiler won't capture every split, so you can still open
+splits with `:split` and `:vsplit`, which would break the tiling arrangements,
+so you can put everyhing back in order with `:TilerReorder`.
+
+Tiler has a layout (well, layouts, but they follow the same principle) of one
+large split for the main content and small ones for everything else. To bring
+one split to the main area, you can use `:TilerFocus`.
+
+And that's basically it.
+
+What I did was to add shortcuts to `:TilerReorder` and `:TilerFocus`. So I
+open splits like everyone else
+
+![](tiler-no-tiling.png)
+
+... and then using `<leader><space>` (the configurable leader key followed by
+space) to call `:TilerReorder` and I get a nice, tidy workspace:
+
+![](tiler-tiling.png)
+
+Although it may look cumbersome, my `leader` is defined to `space`, so to tidy
+up everything, all I have to do is press space twice in normal mode.
+
+Also, to help with the "focus on one thing" part, I also put a shortcut to the
+`:TilerFocus` command, with `<leader>f`.
+
+And here are my bindings:
+
+```vim
+nmap <Leader>f :TilerFocus<CR>
+nmap <Leader><space> :TilerReorder<CR>
+```
+
+One last thing: The size of the main area is configurable, which is good,
+since I found it a bit too large. To adjust it, you can use
+`g:tiler#master#size`, which is the size of main split. I found 55% to be a
+good size, so I put
+
+```vim
+let g:tiler#master#size = 55
+```
+
+And that's it. As usual, it takes some time to put the keybinds in "auto mode"
+(you know, day-to-day use), but I feel it helps a lot on actually put focus on
+some task without the cluttering of splits.