Skip to content

Latest commit

 

History

History
34 lines (20 loc) · 4.49 KB

CONTRIBUTING.md

File metadata and controls

34 lines (20 loc) · 4.49 KB

Contributing

So you want to help me with Lanyon-Hugo? AWESOME!

I'm not a designer, nor do I know CSS or HTML. Most of those things are coming straight out of the original Lanyon. However, the parts that make it work with Hugo, those are mine. And if you're interested, what's mine is yours. I'll explain what has changed from the original Lanyon, if you were familiar with that theme already. And I'll explain the structure of this Hugo theme, assuming you already understand some of how Hugo works.

Hugo's docs are a bit lacking in the "big picture" of how things fit together (I might submit a PR when I'm more familiar with the tool), but they're quite complete. I recommend you read them first.

Layouts

Lanyon-Hugo uses two content types, fixed and post. These are analogous to Lanyon's page and post layouts, respectively. The fixed type is meant to be very simple, for pages that don't need any of the support structure provided by a blog (no tags, no dates, etc). The post type is more detailed; it has a list view and stuff like that.

They both have single views, which are quite similar. In fact, the only difference is that post shows a date, where as fixed does not. This documentation explains how to change the date formatting. This format is set in the config.json under .Site.Params.DateForm, so you can affect the entire site at once.

Both content types call out to a set of general HTML files which provide the universal bits and pieces. These are stored in layouts/chrome, which is a Hugo convention, and they are analogous to Lanyon's _includes.

In Jekyll, you can nest layouts. Lanyon's page and post layouts are both based on a default layout. The default layout is the one that provides things like the header and the sidebar. But Hugo doesn't have this functionality, so I took the default layout, and I split it into two files: default_head.html and default_foot.html. These two are meant to be included at the top and bottom, respectively, of any other content views. You can see this in fixed/single.html and post/single.html.

Sidebar

The most interesting chrome is probably layouts/chrome/sidebar.html. This is mostly based on Lanyon's _includes/sidebar.html, but ported to Go templates instead of Liquid. We identify the homepage and postlist via .Url. Rendered pages (with a content type) do not implement the .Url variable, so it comes back as the blank string.

Any pages whose front matter sets the sidebar flag are also added to the sidebar (sorted by weight). We match the active page (if any) using its .Permalink. Both nodes and pages provide the .Permalink variable, so this lets you pin any content to the sidebar. The sidebar also retains the GitHub integration from the original Lanyon, where it lists a repository of your choice.

Homepage

Hugo implements homepages as a special layout, which does not correspond to any content type. This gets generated into a page called a node. You can see this in layouts/index.html. If you want to change the number of posts listed on the homepage, just change the pagination variable. One inconvenience of Hugo's system is that you can't include front matter for nodes (as far as I know).

The index implements a full view of each item whose content type is post. This is quite repetitive and overlaps heavily with post/single.html. I plan to add a post/summary.html in the future, which does not include the default header and footer, and which sets the post title to a link. Then, I can replace this with {{ .Render "summary" }} to reduce code repetition.

Post List

The post list is implemented using a Hugo section index, which can list pages under a certain content type (in this case, the post type). This index is defined at layouts/indexes/post.html. It renders posts using the layouts/post/li.html view, which just shows the post's time and date as a list item. Hugo indexes are also nodes, like the homepage (a node is any page in the output, that doesn't have a content type).

Statics

Jekyll will take every file in its source directory and mirror it in the destination, unless the file's name begins with an underscore. Hugo is not quite so inclusive. The contents of the static directory are mirrored into the root of the destination exactly as they are. This is where the Lanyon/Poole CSS files are placed. I have not changed those files at all (literally nothing).

If your GitHub Page has a custom name, the CNAME file should go in this directory.