This website is compiled with a Makefile!

I tried a few static site genrators to generate this website you are looking at right now, but all of them felt too complicated for what I actually wanted. What I really wanted was just a very simple setup to convert Markdown files into HTML pages and copy any other file without conversion to the output directory. On this page I will explain my setup, so you can do it too!

What is Pandoc?

Pandoc is a universal document document converter. One of the things it can do is convert from Markdown to HTML. Let’s try that with a very simple Markdown file:

test.md
            
            #Hello,world!                                                           
                                                                                      
            [Lorem ipsum](https://en.wikipedia.org/wiki/Lorem_ipsum) dolor sit amet,
            consecteturadipiscing elit, sed do eiusmod tempor incididunt ut labore et
            dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
            laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in
            reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
            Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia
            deserunt mollit anim id est laborum.

We can compile this file with pandoc using this command:

pandoc --from=markdown --to=html --output=test.html test.md

Pandoc will generate a HTML file that will look something like this:

test.html
            
            <h1 id="hello-world">Hello, world!</h1>
            <p><a href="https://en.wikipedia.org/wiki/Lorem_ipsum">Lorem ipsum</a> dolor
            sit amet, consectetur adipiscing elit, sed do iusmod tempor incididunt ut
            labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
            exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute
            irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat
            nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa
            qui officia deserunt mollit anim id est laborum.</p>

The Makefile

It’s time to show you the Makefile that I actually use.

Makefile
            
            TEMPLATE     = src/template.xhtml
            MD_VERSION   = markdown
            HTML_VERSION = html4
            
            COPY_FILES   = $(shell find src -type f ! -path $(TEMPLATE))
            HTML_FILES   = $(shell find src -type f -name "*.md")
            COPY         = $(COPY_FILES:src/%=out/%)
            HTML         = $(HTML_FILES:src/%.md=out/%.xhtml)
            
            .PHONY: all
            all: $(HTML) $(COPY)
            
            # Convert Markdown file from source to HTML file in output
            out/%.xhtml: src/%.md
                @ mkdir -p $(@D)
                pandoc --from=$(MD_VERSION) --to=$(HTML_VERSION) --template=$(TEMPLATE) \
                       --output=$@ $< \
                       --metadata=original_path:$(<:src/%=/%) \
                       --metadata=original_file:$(<F) \
                       --metadata=date:"$(shell date +"%d-%m-%Y")" \
                       --metadata=time:"$(shell date +"%H:%M:%S")"
            
            # Copy file from source to output
            out/%: src/%
                @ mkdir -p $(@D)
                cp $< $@
            
            .PHONY: clean
            clean:
                rm -rf out

I have added a few extra things to the pandoc command like the path to a HTML template and some metadata used within the template.

The directory structure

For this Makefile the directory structure should look something like this (after you have generated the website):

            root
            +--- src
            |    +--- static
            |    |    +--- logo.png
            |    |    \--- style.css
            |    |
            |    +--- template.xhtml
            |    +--- favicon.ico
            |    \--- index.md
            |
            +--- out  (<-- Everyting here is generated from source files!)
            |    +--- static
            |    |    +--- logo.png
            |    |    \--- style.css
            |    |
            |    +--- favicon.ico
            |    +--- index.md
            |    \--- index.xhtml
            |
            +--- .gitattributes
            +--- .gitignore
            \--- Makefile

Note that you should add all your source files in the src directory. Everything in the src directory will automatically be copied to the out directory and Markdown files ending with .md will also be converted into HTML. If you for some reason want to add a custom HTML page to the website, you can also just add it to the src directory and it will be copied without conversion.

DIY static website template

I have made a template for those who want to experiment with this setup themselves. Feel free to use this for your own website if you want to. Perhaps you can link back to this page but you don’t have to!