I'm making progress with riki, although very slowly. It's a program I'd really like to have, but it's so far down my priorities that I don't work on it often. But I'm currently on holiday and have more degrees of freedom. Here are notes from today's develoment session.

Goal

My goal today is to make riki be able to render a simple site. I want this so that I can start trying riki on my various ikiwiki sites.

riki can already render a single page. Today I want to make a command like this work:

riki build src dest

This will read the directory src, load all files, process every .mdwn file as Markdown with wikitext and produce HTML for that, and write the output to dest. All other files get copied verbatim.

This is only about processing a directory tree. It's OK if links within the site do not work in the output. It's OK to not implement any additional directives or other functionality. Once I can try to render sites, I can run riki on my various sites, and other chosen test sites, and find out what I need to fix.

Plan

• Create a minimal test site to verify riki build works even for the easiest case.
• Implement the scaffolding for the riki build command.
• Implement scanning the source tree for files.
• Implement processing of .mdwn files into HTML.
• Implement writing out of output files.

Notes

Test site

• For the test site I want about two files. One is not enough. More than two seems unnecessary.
• index.mdwn and other.mdwn will both contain a meta title and some text to make it easy to verify the page contains the right stuff.

Scan source folder

• I'll use the walkdir, as it's good and I'm familiar with it.
• I'll ignore everything that isn't a regular file. Directories will be created from source file paths, symlinks are dangerous. I might add support for symlinks some day, if there's a request, but for now I'm ignoring them.
• I'll only process .mdwn files as wikitext, everything else is a blob.
• I'm reading in blobs into memory. I may later only remember the pathname and copy files without keeping them in memory, but for now this is easier.

Process .mdwn files

• This is basiclly what the render-page command I implemented earier does. A bit of copy-pasta, and done! I may later refactor this to avoid code duplication, but it's literally two lines, so I'm not too bothered today.

Write out files

• For any input file foo/bar/yo.mdwn under the source directory, write foo/bar/yo/index.html in the output directory, creating the output directory and subdirectories as needed. But index.mdwn in a directory should result in index.html in the corresponding output directory.

• Hmm, my plan was to hack up something quickly and then tidying that up. But this turns out be ever so slightly more complicated than I thought. This is my third time trying to implement riki and I've run into this kind of surprise compoication before. But I'll push through. I should take notes of what the complexities are. Right now it's keeping track of page content (blob vs HTML), and filename. I want to be consistent, and avoid possibilities for coding mistakes, when I can.

• OK, I have something that works with my silly little test site.

• Did a little refactor to simplify code.

• Figuring out the output file name is a little tricky, but not too bad. Prime target for unit tests, too.

Trying this on my sites

• Some of my very simples sites work.
• Others have problems.
  • failing to handle some Markdown combinations
  • missing directives: inline, map
• I've noted those in issues.

End

• I've merged the changes.