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!
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 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>
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.
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.
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!