1 unstable release

Uses old Rust 2015

0.0.1	Oct 6, 2018

#20 in #blog-post

CC0 license

67KB
1.5K SLoC

wellington

Wellington is a lightweight static blog generator written in Rust. You can see it in action at https://emanuelgeromin.com/blog/

Wellington allows you to write blog posts in markdown and then automatically

renders them as HTML
updates the table of contents
updates the RSS feed.

From the root directory of your website, create a new blog:

mkdir my-amazing-blog
cd my-amazing-blog
wellington init --title "My Blog" \
    --home_url "https://mysite.com \
    --desc "My blog about clogs" \
    --author "It's Me"

Then write a blog post:

mkdir post-1
touch post-1/index.md  # edit this file
wellington sync

This last command, wellington sync, automatically

renders the post as HTML at post-1/index.html
creates/updates the table of contents at index.html
creates/updates the rss feed at rss.xml

Installation

Installation is via cargo:

cargo install wellington

Markdown with Footnotes/Sidenotes

Wellington supports an extended markdown syntax. In addition to the usual markdown, you can also mark footnotes/sidenotes directly in the HTML using curly braces:


# Here is an article

Here is some text with sidenotes/footnotes{this text will render as a
footnote/sidenote}

Sidenotes are like footnotes except that they display to the right of the article instead of the bottom. See this blogpost as an example. To work, they require proper CSS. See the 'CSS' section below.

Why Wellington

There are plenty of blogging engines out there, many designed for use with static hosting services like GitHub pages. One great example is Jekyll.

I wrote wellington because I wanted support for sidenotes and require only a very simple set of features.

Relative links

Relative links in the post markdown files are automatically changed to point to the directory they're in. So for example, if my-amazing-blog/post-1/index.md contains the following:

![an image](image.png)

Then this is rendered as:

<img src="my-amazing-blog/post-1/image.png" />

This makes embedding images in the blog post easier.

CSS

Wellington's sidenotes were designed for use with tufte-css. I use a modified version on my blog. This modified version is more mobile friendly and on narrow screens, instead of displaying sidenotes, displays footnotes. You're very welcome to copy my CSS. Alternatively, as a more minimal solution, you can just hide the sidenotes if you don't require them and render only the footnotes:

.sidenote {
    display: none;
}

To display the blog posts in a mobile friendly way, by using sidenotes for desktop and footnotes for mobile, as I've done, please check the modified version of tufte-css.

Templates

To render the posts and the table of contents, wellington uses Handlebars, a templating engine. This allows for customisability of the posts and of the table of contents. There are default templates in the source code in the templates directory. These are used by default and do not require installation. To override them, provide your own templates in your blog home directory:

.index_template.html for the table of contents
.post_template.html for the posts

Take a look at the default templates and adapt them to suit your needs!

MathJax (Latex) support

Using mathjax (latex) in the blog posts requires a hack. To prevent the latex to be rendered by the markdown parser, it has to be marked as code in markdown, for example


# a markdown file

Here is some text with an equation: `\(E = mc^2\)`

By default, mathjax does not render anything wrapped in <pre> or <code> tags. To override this behaviour, in addition to the <script> tag linking to the mathjax CDN, you will have to add the following to your template <head> section:

<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  tex2jax: {
      skipTags: ["script","noscript","style","textarea"]
      }
  });
</script>

This overrides the default skipTags, allowing also latex in <pre> and <code> tags to be rendered.

If you require both rendered latex and latex code in your blog posts, then unfortunately at the moment you're out of luck. A more long term solution would be to parse latex properly in the markdown document. However, this is a more long term project as it requires modifying pulldown-cmark, the library I use for rendering markdown. Contributions are welcome!

Known Bugs

Footnotes are not rendered properly as all inline markdown formatting is lost (#3)

Roadmap

There is still much to do. The current codebase grew organically without much advance planning. This shows: the codebase is quite messy and in need of a refactor!

Feature wise, soon I hope to support

syntax highlighting (#1)
make the template variables post_url and index_url available in the markdown as well (#5). This is useful when embedding external code or demos in the blog post.

Dependencies

~12MB
~249K SLoC