XMin is the first Hugo theme I have designed. The original reason that I wrote it was I needed a minimal example of Hugo themes when I was writing the blogdown book. Basically I wanted a simple theme that supports a navigation menu, a home page, other single pages, lists of pages, blog posts, categories, tags, and RSS. That is all. Nothing fancy. In terms of CSS and JavaScript, I really want to keep them minimal. In fact, this theme does not contain any JavaScript code at all, although on this example website I did introduce some JavaScript code (still relatively simple anyway). The theme does not contain any images, either, and is pretty much a plain-text theme.

The theme name “XMin” can be interpreted as “Xie’s Minimal theme” (Xie is my last name) or “eXtremely Minimal theme”.

config.toml

For this example site, I defined permalinks for two sections, post and note, so that the links to pages under these directories will contain the date info, e.g., https://xmin.yihui.org/post/2016/02/14/a-plain-markdown-post/. This is optional, and it is up to your personal taste of URLs.

[permalinks]
    post = "/post/:year/:month/:day/:slug/"
    note = "/note/:year/:month/:day/:slug/"

You can define the menu through menu.main, e.g.,

[[menu.main]]
    name = "Home"
    url = "/"
    weight = 1
[[menu.main]]
    name = "About"
    url = "/about/"
    weight = 2
[[menu.main]]
    name = "Categories"
    url = "/categories/"
    weight = 3
[[menu.main]]
    name = "Tags"
    url = "/tags/"
    weight = 4
[[menu.main]]
    name = "Subscribe"
    url = "/index.xml"

Alternatively, you can add menu: main to the YAML metadata of any of your pages, so that these pages will appear in the menu.

The page footer can be defined in .Params.footer, and the text is treated as Markdown, e.g.,

[params]
    footer = "© [Yihui Xie](https://yihui.org) 2017"

Custom layouts

There are two layout files under layouts/partials/ that you may want to override: head_custom.html and foot_custom.html. This is how you inject arbitrary HTML code to the head and foot areas. For example, this site has a file layouts/partials/foot_custom.html to support LaTeX math via MathJax and center images automatically:

<script src="//yihui.org/js/math-code.js"></script>
<script async src="//cdn.bootcss.com/mathjax/2.7.1/MathJax.js?config=TeX-MML-AM_CHTML">
</script>

<script async src="//yihui.org/js/center-img.js"></script>

You can certainly enable highlight.js for syntax highlighting by yourself through head_custom.html and foot_custom.html if you want.

If you do not like the default fonts (e.g., Palatino), you may provide your own static/css/fonts.css under the root directory of your website to override the fonts.css in the theme.

Other features

I could have added more features to this theme, but I decided not to, since I have no intention to make this theme feature-rich. However, I will teach you how. I have prepared several examples via pull requests at https://github.com/yihui/hugo-xmin/pulls, so that you can see the implementations of these features when you check out the diffs in the pull requests. For example, you can:

• Enable Google Analytics

• Enable Disqus comments

• Enable highlight.js for syntax highlighting of code blocks

• Display categories and tags on a page

• Add a table of contents

• Add a link in the footer of each page to “Edit this page” on Github

To fully understand these examples, you have to read the section on Hugo templates in the blogdown book.

Design philosophy

Lastly, a few words about my design philosophy for this theme: I have been relying on existing frameworks like Bootstrap for years since I’m not really a designer, and I was always scared by the complexity of CSS.

When I started writing this theme, I asked myself, “What if I just write from scratch?” No Bootstrap. No Normalize.css. I don’t care about IE (life could be so much easier without IE) or inconsistencies among browsers (for personal websites). As long as the theme looks okay in Chrome, Firefox, and Safari, I’m done. Thanks to the simplicity of Markdown, you cannot really produce very complicated HTML, and I think styling the HTML output from Markdown is much simpler than general HTML documents. For example, I do not need to care much about form elements like textareas or buttons.

After I finished this theme, I started to wonder why I’d need normalize.css at all (it sounds like a religious belief). The default appearance of modern browsers actually looks pretty good in my eyes, after I tweak the typeface a little bit.

Compared to inconsistencies across browsers, I care much more about these properties of HTML elements:

• Tables should always be centered, and striped tables are easier to read especially when they are wide. Tables should not have vertical borders.
• An image should be centered if it is the only child element of a paragraph.
• The max-width of images, videos, and iframes should be 100%.

I hope you can enjoy this theme. The source code is on Github. Happy hacking!