3

I have used a few different static site generators including:

  • GitBook
  • Hexo
  • HubPress
  • Hugo
  • Jekyll
  • Pelican

and each lacked a very important feature: a flexible, powerful and well-documented templating engine. By this I mean a templating engine that:

  1. Allows for the inclusion of content from multiple files within a post, with rendering being the same as it would be if the content of the multiple files was placed in the post. For example, on my present Jekyll-powered blog I often split posts up into smaller, more manageable markdown files. Jekyll allows me, using the Liquid templating engine, to include these markdown files into the final post. If you would like to see exactly what I use and mean, here is an example post file as you can see several markdown files are included into it using {% include_relative <FILENAME> %}. Other templating engines have not afforded me this ability.

  2. Is able to be extensively programmed with using conditionals, tests, iterations, greps, seds, etc. For example, if I could check if an input given contains a string (but not necessarily being equal to that string) that would be helpful. Likewise if I could strip off everything that comes before a forward-slash / (e.g., if the input was the web address http://www.example.com, this would cut http:// out and leave me with www.example.com) in an input and use it that would be helpful. If an input was of the form a/b (e.g., games-strategy/megaglest, where a is games-strategy and b is megaglest), it would be helpful if I could split it into two parts a and b and use a and b separately in my templates.

  3. Has comprehensive documentation. I have not come across a single templating engine used by a static site generator that has comprehensive documentation, the one with the best documentation at the time of writing this question was probably Liquid but it is still not comprehensive.

Linux compatibility is also important as I would like to deploy to GitHub pages and to do so, with most SSGs (except Jekyll and HubPress) I need to be able to build the site locally (which for me is on Linux) and then push the site content to the gh-pages branch of my repo. Support for markdown posts is also a must. If pages other than posts can be included (like an about me page for the website) in the site that would also be excellent.

0

I would suggest taking a look at Jekyll's evil twin Hyde.

  • Templates via Jinja2 which has extensive documentation and includes extensive conditionals, etc.
  • Markdown is implemented in Python Markdown which has an extensive list of extensions and an extension API. One available extension using this API is markdown include.
  • All of the above tools are written in Python so Linux compatibility is not an issue
  • Hyde has 4 commands from the command line:

    • hyde create Create initial file structure
    • hyde gen Generate the pages, incrementally by default
    • hyde serve Start a local test web server with automatic (re-)generation
    • hyde publish Publish the generated files to the specified location, e.g. github pages.
  • 1
    Tempting, but I looked at its repo and there's been no commits in over a year and no releases in over a year and a half, making me wonder if it is dead... – BH2017 May 12 '17 at 7:01
  • Oh and if you provide me with HOW to setup Python Markdown to use markdown include I'd be more inclined to accept this answer. I have used Pelican before and from what I can tell it has all the same features, but I couldn't include files with it as I'm not much of a programmer I haven't the foggiest how to use Python Markdown's API to use markdown include. – BH2017 May 12 '17 at 7:38
  • pip install -U markdown markdown-include possibly prefixed with sudo should do the installation. pythonhosted.org/Markdown/cli.html gives some details on using extensions. – Steve Barnes May 12 '17 at 7:49
  • All that link tells me is how to convert markdown files into HTML output (I think though their use of the .txt file extension for what seems like markdown files is confusing) from the command-line. If I'm using an SSG I won't be converting md files manually from the command-line will I, the SSG will do it all for me with the serve command won't it? – BH2017 May 12 '17 at 7:57

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.