Growing a website, part 1: Writing content in Markdown
This is the first post in my #100DaysToOffload series.
So now I have a minimal website. In order to add more pages, I need to be able to do this easily. Otherwise, I’d soon lose interest in this project. It’s a hobby and if your hobby turns into a chore, you just stop doing it.
This is not about fancy software development. My plan is to improve the site and the way it is handled step by step, writing and/or glueing together tools as I go.
Where I am now
When I want to publish another page here, I want it to look the same as the existing pages, which means, it should have the same header and footer as the others. To do this, I can take the following steps:
- Copy one of the existing pages
- Remove everything between header and footer
- Insert HTML code for the new page
- Add a link to the new page on one of the existing pages (or the menu)
- Upload the result to my website
Where I want to be
- Write new content in markdown
- Run make
After these two steps, the new page or article should be in the right place in HTML format with the header and footer in place and linked to by an appropriate existing page. Now I have something to do! Let’s take it one bite at a time.
Taking the first step
Today I’ll try to tackle the first step: Writing content in Markdown. In fact, I was optimistic enough to write this article in markdown. So, if you can read this, I succeeded (or cheated).
If you want to play along, you can either clone the whole webpage like this:
$ git clone https://git.envs.net/skirnir/website.git
or download my about.html page and stylesheet (You’ll have to put it in a
static/ subdirectory for this to work), or better yet, grab simplecss.org, build your own header and footer and start building your own website.
When you look at an existing page (just open
about.html in your editor), you’ll see that the content of the page is enclosed in
</main> tags. Those tags each have their own line. So, to save time, I can save the first part of the
about.html including the
<main> tag as
header.html and the last part including the
</main> tag as
$ sed '/<main>/q' about.html > header.html $ sed -n '/<\/main>/,$p' about.html > footer.html
What does this do?
You can learn about
sed here. For a quick overview see its wikipedia page. For our purpose, the first statement means “print out everything until a line contains
<main> (including that line), then quit” (that’s the ‘q’ at the end). The second statement means “find a line that contains
</main>, then print (
p) that line and everything until (
,) the end of the file (
$)”. Because sed defaults to printing each processed line, the
-n switch is needed to prevent this. Otherwise we’d get all lines up to
</main> and each line after that twice. We redirect the output to
Alternatively, you can do that manually with your editor.
Now we have the
footer.html as described above. We can create an empty page with the following command:
$ cat header.html footer.html > empty.html
If we create a file
content.html with the following contents:
<h2>New content</h2> <p>Now we have a new page.</p>
We can create a new page
new.html by typing:
$ cat header.html content.html footer.html > new.html
Open the file in your browser. It should contain the header and footer with the content of
content.html in the
<main>...</main> section. If you want to look at that file in your browser, one way to do it is to type
$ python3 -m http.server
in the directory containing the new file and pointing your browser to http://localhost:8000/new.html.
Ok, now creating a new page has become easier. We no longer need to copy an existing page manually to get a header and footer. There’s still one last task to tackle: Writing content in markdown. Fortunately, the problem of conversion of markdown to HTML has already been solved. We’ll use the pandoc package for this. On Debian-based systems, type:
$ sudo apt install pandoc
on Archlinux it’s
$ sudo pacman -S pandoc
Then create a file
content.md with the following content:
## New content Now we have a new page generated from markdown.
$ pandoc -o content.html content.md
Now we can create
new.html as above:
$ cat header.html content.html footer.html > content.html
content.html contains the HTML generated from the markdown file. Now we have to link to our new page from the start page and we’re done. That’s pretty easy as well if we rewrite the
index.html page in markdown and generate it like we just did with
That’s it for today. If you decide to build your webpage in this way, keep your markdown files. We’re going to need them when we further simplify the process!