1 unstable release
Uses old Rust 2015
0.0.1 | Oct 6, 2018 |
---|
#20 in #blog-post
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
andindex_url
available in the markdown as well (#5). This is useful when embedding external code or demos in the blog post.
Dependencies
~12MB
~234K SLoC