--- title: riki static site generator subtitle: Subset of ikiwiki rewritten in Rust bindings: - subplot/riki.yaml - lib/files.yaml - lib/runcmd.yaml impls: rust: - subplot/riki.rs ... [ikiwiki]: http://ikiwiki.info/ [Subplot]: https://subplot.tech/ # Introduction `riki` is a small subset of [ikiwiki][] rewritten in Rust, for speed. This document describes the requirements and acceptance criteria for the software, and how to verify that riki meets them in an automated way. This is done using the [Subplot][] software. # Verification scenarios The approach used for verifying acceptance criteria is to run `riki` against known inputs, and check that the output is as expected. Specifically this is done by comparing the Pandoc abstract syntax trees of the input and output. Pandoc is a well-known, well-respected tool that we rely on as an "oracle". ## Markdown features ### Empty Markdown file _Requirement: Given an empty input Markdown file, the output must be an empty HTML file._ ~~~scenario given an installed riki given file site/empty.mdwn from empty when I run riki build --plain-body site output then AST of site/empty.mdwn matches that of output/empty.html ~~~ ~~~{#empty .file} ~~~ ### Plain text _Requirement: Given a Markdown file with plain text, the output must be an HTML file with the same text, without extra elements._ ~~~scenario given an installed riki given file site/page.mdwn from para when I run riki build --plain-body site output then AST of site/page.mdwn matches that of output/page.html ~~~ ~~~{#para .file} Hello, world. There are two paragraphs. ~~~ ### Quoted block _Requirement: Given a Markdown file with an quoted block of text, the output must have a blockquote element. ~~~scenario given an installed riki given file site/page.mdwn from blockquote when I run riki build --plain-body site output then AST of site/page.mdwn matches that of output/page.html ~~~ ~~~{#blockquote .file} > This is a quoted block. ~~~ ### Indented code block _Requirement: Given a Markdown file with an indented code block, the output must have a pre element. ~~~scenario given an installed riki given file site/page.mdwn from indented-code when I run riki build --plain-body site output then AST of site/page.mdwn matches that of output/page.html ~~~ ~~~{#indented-code .file} This is indented by four spaces. ~~~ ### Fenced code block _Requirement: Given a Markdown file with a fenced code block, the output must have a pre element. ~~~scenario given an installed riki given file site/page.mdwn from fenced-code when I run riki build --plain-body site output then AST of site/page.mdwn matches that of output/page.html ~~~ ~~~{#fenced-code .file} ``` This is a fenced code block. ``` ~~~ ### Image link _Requirement: Given a Markdown file linking to an image, the output must have an img element. ~~~scenario given an installed riki given file site/page.mdwn from image-link when I run riki build --plain-body site output then AST of site/page.mdwn matches that of output/page.html ~~~ ~~~{#image-link .file} ![my kitten](cat.jpg) ~~~ ### Emphasised text _Requirement: Inline markup for emphasis must result in an em element in HTML output._ ~~~scenario given an installed riki given file site/page.mdwn from emph when I run riki build --plain-body site output then AST of site/page.mdwn matches that of output/page.html ~~~ ~~~{#emph .file} There is *emphasized*, and so is _this_. ~~~ ### Strongly emphasised text _Requirement: Inline markup for strong emphasis must result in a strong element in HTML output._ ~~~scenario given an installed riki given file site/page.mdwn from strong when I run riki build --plain-body site output then AST of site/page.mdwn matches that of output/page.html ~~~ ~~~{#strong .file} There is **emphasized**, and so is __this__. ~~~ ### Strike through in text _Requirement: Inline markup for strike through must result in a del element in HTML output._ ~~~scenario given an installed riki given file site/page.mdwn from strike when I run riki build --plain-body site output then AST of site/page.mdwn matches that of output/page.html ~~~ ~~~{#strike .file} There is ~~struck through~~. ~~~ ### Headings _Requirement: Given a Markdown file with headings of various levels, the output must be an HTML file with corresponding `h1`, `h2`, etc, elements, without extra elements. Up to six levels of headings must be supported._ ~~~scenario given an installed riki given file site/page.mdwn from headings when I run riki build --plain-body site output then AST of site/page.mdwn matches that of output/page.html ~~~ ~~~{#headings .file} # Heading one ## Heading two ### Heading three #### Heading four ##### Heading five ###### Heading six ~~~ ### Inline code _Requirement: Inline code markup with backticks must result in a code element in HTML output._ ~~~scenario given an installed riki given file site/page.mdwn from backticks when I run riki build --plain-body site output then AST of site/page.mdwn matches that of output/page.html ~~~ ~~~{#backticks .file} There is `code` lurking here. ~~~ ### Table _Requirement: Markup of a table result in a table element in HTML output._ **Note: This is disabled. Pandoc doesn't seem to handle the HTML table OK.*** ~~~ given an installed riki given file site/page.mdwn from table when I run riki build --plain-body site output then AST of site/page.mdwn matches that of output/page.html ~~~ ### Horizontal rule _Requirement: Markup of a horizontal rule must result in hr element in HTML output._ ~~~scenario given an installed riki given file site/page.mdwn from rule when I run riki build --plain-body site output then AST of site/page.mdwn matches that of output/page.html ~~~ ~~~{#rule .file} foo --------------------------------------------------------------------------------------- bar ~~~ ### Unordered list _Requirement: Markup of an unordered list must result in a ul element in HTML output._ ~~~scenario given an installed riki given file site/page.mdwn from ul when I run riki build --plain-body site output then AST of site/page.mdwn matches that of output/page.html ~~~ ~~~{#ul .file} * first * second ~~~ ### Ordered list _Requirement: Markup of an ordered list must result in an ol element in HTML output._ **Note: This is disabled. Pandoc doesn't seem to parse the HTML list the same as the Markdown.*** ~~~ given an installed riki given file site/page.mdwn from ol when I run riki build --plain-body site output then AST of site/page.mdwn matches that of output/page.html ~~~ ### Task list _Requirement: Markup of a task list must result in a ul element in HTML output._ ~~~scenario given an installed riki given file site/page.mdwn from tasklist when I run riki build --plain-body site output then AST of site/page.mdwn matches that of output/page.html ~~~ ~~~{#tasklist .file} * [ ] not done * [x] done ~~~ ## Definition list _Requirement: Markup indicating use of a definition list should be flagged as an error._ Justification: Neither the CommonMark specification, nor GitHub Flavored Markdown, supports definition lists, even though some Markdown variants do. The Markdown parser Riki uses doesn't support it. ~~~scenario given an installed riki given file site/page.mdwn from dl-1 when I try to run riki build --plain-body site output then command fails then stderr contains "definition list" given file site/page.mdwn from dl-2 when I try to run riki build --plain-body site output then command fails then stderr contains "definition list" given file site/page.mdwn from dl-3 when I run riki build --plain-body site output then file output/page.html contains ": bar" ~~~ ~~~{#dl-1 .file} foo : bar ~~~ ~~~{#dl-2 .file} foo : bar ~~~ ~~~{#dl-3 .file} foo : bar ~~~ ## Input files other than Markdown _Requirement: Input files that aren't Markdown files must be copied into the destination directory as-is._ ~~~scenario given an installed riki given file site/image.jpg from image when I run riki build --plain-body site output then files site/image.jpg and output/image.jpg match ~~~ ~~~{#image .file} # Dummy Pretend this is an image. ~~~ ## Input files in sub=directories _Requirement: If an source page or file is in a sub-directory, it should be put in the corresponding sub-directory in the target directory._ ~~~scenario given an installed riki given file site/foo/page.mdwn from image given file site/bar/image.jpg from para when I run riki build --plain-body site output then AST of site/foo/page.mdwn matches that of output/foo/page.html then files site/bar//image.jpg and output/bar/image.jpg match ~~~ ## Wiki links to other pages on the site _Requirement: Pages can link to other pages on the site, the same way ikiwiki does, including subpages._ ~~~scenario given an installed riki given file site/dir/foo.mdwn from foo given file site/absolute.mdwn from empty given file site/dir/sibling.mdwn from empty given file site/dir/foo/child.mdwn from empty given file site/dir/foo/child/grandchild.mdwn from empty when I run riki build --plain-body site output then file output/dir/foo.html contains "href="../absolute"" then file output/dir/foo.html contains "href="sibling"" then file output/dir/foo.html contains "href="foo/child"" then file output/dir/foo.html contains "href="foo/child/grandchild"" ~~~ Note the uppercase link to the `child` page in the test page below. ~~~{#foo .file .markdown} [[/absolute]] [[sibling]] [[child]] [[child/grandchild]] [[CHILD]] ~~~ ## Wiki links to pages that don't exist _Requirement: Linking to a page that doesn't exist is an error._ ~~~scenario given an installed riki given file site/dir/foo.mdwn from badlink when I try to run riki build --plain-body site output then command fails ~~~ ~~~{#badlink .file .markdown} [[missing]] ~~~ ## Directives ### `meta title` _Requirement: the `meta title` directive sets page title._ ~~~scenario given an installed riki given file site/index.mdwn from meta when I run riki build site output then file output/index.html contains "Yo" ~~~ ~~~{#meta .file .markdown} [[!meta title=Yo]]] ~~~ ### `img` _Requirement: the `img` directive embeds an image in the generated HTML page._ ~~~scenario given an installed riki given file site/index.mdwn from img given file site/img.jpg from jpeg when I run riki build site output then file output/index.html contains "