Super Simple Static Site Generator (S4G): Convert your Markdown and AsciiDoc files into a website quickly
There are 2 objectives in creating this repository:
-
Learning. Especially various refactoring and DDD technics
-
Produce a super simple application to convert Markdown and AsciiDoc files into a static website
This repository will document my learning journey with a real example.
Towards the end of 2018, I wanted to redesign our company website. I went looking for a simple solution that could handle AsciiDoc files and couldn’t find anything as simple as I wished.
So I decided to create something quickly. It was ugly, but it served its purpose.
The working solution is in the first commit of this repository … with all its imperfections. This is good, because it is a real example of a solution that was put together quickly to satisfy a need. Which it did.
I purposely did not tidy up or improve the code before saving the first commit. It would defeat the purpose.
The code base will now serve a different purpose. I am about to embark on a journey to learn DDD and various refactoring techniques.
A journal of the lessons learned and the reasons for making certain decisions, will be kept in the wiki.
Couldn’t find something that was "super simple".
My definition of simple would roughly follow this workflow:
-
Build simple HTML templates with tokens
-
Write content in Markdown or AsciiDoc files
-
Convert the text files into HTML
-
Extract relevant areas from these HTML files based on tags, class names or IDs
-
Replace the template tokens with the extracts to create a new HTML file
The benefits are:
-
All content can be version controlled
-
Creating templates for different areas of a website becomes trivial
-
Ultimate flexibility and control over the final look and feel of the website
Please see the corresponding links for more details
-
Install latest Ruby for windows: https://rubyinstaller.org/downloads/ (Or use "cinst ruby" using Chocolatey)
-
Use all default installation options (including installing msys64)
-
-
Install AsciiDoctor: https://asciidoctor.org/docs/install-toolchain/
-
Go to C:\tools\ruby26\bin and run "gem install asciidoctor"
-
-
Install the HTML5 Semantic output gem
-
Read the "usage" section
-
Note
|
Files taken from HTML5 boilerplate |
The key to making all this work is to use regions within the AsciiDoc file.
Using these regions makes it really easy to extract the correct parts from the HTML file.