Skirnir's realm

An ageing nerd's playground.

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:

  1. Copy one of the existing pages
  2. Remove everything between header and footer
  3. Insert HTML code for the new page
  4. Add a link to the new page on one of the existing pages (or the menu)
  5. Upload the result to my website

Where I want to be

  1. Write new content in markdown
  2. 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).

Prerequisites

Let’s go!

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> and </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 footer.html:

$ 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 header.html and footer.html respectively.

Alternatively, you can do that manually with your editor.

Now we have the header.html and 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.

and type

$ pandoc -o content.html content.md

Now we can create new.html as above:

$ cat header.html content.html footer.html > content.html

Now 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 new.html.

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!