Write new documentation conforming to Diátaxis

4 files changed, 516 insertions, 241 deletions

diff --git a/GEMTEXT-COMPATIBILITY-EXPLANATION.md b/GEMTEXT-COMPATIBILITY-EXPLANATION.md
new file mode 100644
index 0000000..ca033df
--- /dev/null
+++ b/GEMTEXT-COMPATIBILITY-EXPLANATION.md
@@ -0,0 +1,83 @@
+# Gemtext Compatibility Explanation Document
+
+This explanation document details the rationale behind the design decisions for the gemtext output format. Its structure mirrors that of the [gemtext compatibility reference guide](GEMTEXT-COMPATIBILITY-REFERENCE-GUIDE.md).
+
+The explanation document format is as follows:
+
+````markdown
+## <Feature Name>
+
+<Rationale>
+````
+
+## Nesting
+
+Gemtext does not support nesting elements, so it is impossible for the gemtext output format to fully support nesting.
+
+The gemtext renderer may be able to flatten nested elements to allow other output formats to use nested elements without harming the gemtext output format, but adding even partial support for it would probably make the regex unmaintainable and lose too much semantic meaning anyway.
+
+## Escape Characters
+
+Gemtext does not support escape characters, so it is impossible for the gemtext output format to fully support escape characters.
+
+The gemtext renderer may be able to remove backslashes to allow other output formats to use escape characters without harming the gemtext output format, but adding even partial support for it would probably make the regex unmaintainable and invoke so many corner cases that much of the documentation would need to be devoted just to escape characters.
+
+## Paragraphs
+
+Markdown paragraphs are the same as gemtext text lines.
+
+## Blockquotes
+
+Markdown blockquotes are the same as gemtext quote lines.
+
+## Headings
+
+Markdown headings delimited with number signs are the same as gemtext headings, except that gemtext does not support heading levels 4-6. Markdown heading levels 4-6 are flattened to heading level 3 in the gemtext output format. Flattening Markdown heading levels 4-6 results in a significant loss of semantic meaning, so using those levels is strongly discouraged. Flattening Markdown headings is supported because it does not lose as much semantic meaning as flattening element nesting would and, unlike element nesting, implementing it does not overcomplicate the regex.
+
+Alternate Markdown syntax for delimiting headings (equal signs and dashes) is supported since implementing it does not overcomplicate the regex.
+
+## Emphasis (Italics and/or Bolding)
+
+Gemtext does not support italicized and/or bolded text, so it is impossible for the gemtext output format to fully support italicized and/or bolded text.
+
+In order to allow other output formats to use italic and/or bold syntax without harming the gemtext output format, asterisks delimiting italicized and/or bolded text are removed from the gemtext output. Loss of significant semantic meaning can be avoided by using italics and/or bolding in such a way that the text remains comprehensible even with the italics and/or bolding removed.
+
+## Unordered Lists
+
+Markdown unordered list items delimited with asterisks are the same as gemtext unordered list items.
+
+Alternate Markdown syntax for delimiting unordered list items (dashes and plus signs) is supported since implementing it does not overcomplicate the regex.
+
+## Ordered Lists
+
+Gemtext does not support ordered lists, so it is impossible for the gemtext output format to fully support ordered lists.
+
+In order to allow other output formats to use ordered list syntax without harming the gemtext output format and in order to make ordered lists useful in the gemtext output format, ordered list items are converted to unordered list items in the gemtext output. This is supported since implementing it does not overcomplicate the regex. Loss of significant semantic meaning can be avoided by using ordered lists in such a way that the list remains comprehensible even with the ordering removed.
+
+## Preformatted Text
+
+Markdown preformatted text delimited with 3 backticks is the same as gemtext preformatted text.
+
+Gemtext does not support preformatted text delimited with more than 3 backticks. This is not supported because it is not possible in the regex. This is not considered a deficiency since preformatted text with more than 3 backticks is only used for nesting or escaping, features that have already been documented as unsupported.
+
+Alternate Markdown syntax for delimiting preformatted text (4+ spaces or a tab) is unsupported because the regex for supporting it has not been implemented.
+
+## Links
+
+Gemtext does not support inline links, so it is impossible for the gemtext output format to fully support inline links.
+
+In order to allow other output formats to use inline link syntax without harming the gemtext output format and in order to make inline links useful in the gemtext output format, all links are optionally converted to reference-style links in the gemtext output. The conversion is optional because reference-style links may not be appropriate on all pages.
+
+Only basic link syntax is supported: brackets containing link text followed by parenthesis containing a URL optionally followed by quotes containing a link title. Alternate link syntax is unsupported because it has not been implemented.
+
+## Inline Images
+
+Gemtext does not support inline images, so it is impossible for the gemtext output format to fully support inline images.
+
+In order to allow other output formats to use inline image syntax without harming the gemtext output format and in order to make inline images useful in the gemtext output format, inline images are treated the same as regular links.
+
+## Whitespace
+
+Whitespace has no special meaning in gemtext. Gemini clients simply display whitespace verbatim. This can lead to discrepancies between the gemtext output format and other output formats if the guidelines in the [gemtext compatibility reference guide](GEMTEXT-COMPATIBILITY-REFERENCE-GUIDE.md) are not followed.
+
+There are plans to implement regex which "autocorrects" the whitespace between elements so that discrepancies cannot appear in the gemtext output and so that the user does not need to manually insert the correct amount of whitespace between elements.
diff --git a/GEMTEXT-COMPATIBILITY-REFERENCE-GUIDE.md b/GEMTEXT-COMPATIBILITY-REFERENCE-GUIDE.md
new file mode 100644
index 0000000..dc68a5b
--- /dev/null
+++ b/GEMTEXT-COMPATIBILITY-REFERENCE-GUIDE.md
@@ -0,0 +1,429 @@
+# Gemtext Compatibility Reference Guide
+
+This reference guide documents the compatibility of Markdown features with gemtext as an output format of this Hugo theme. It should be assumed that any Markdown features not documented below are unsupported.
+
+The reference guide format is as follows:
+
+```markdown
+## <Feature Name>
+
+<Markdown input> => <gemtext output>
+
+Support level: <full, partial, or unsupported>
+
+[Other relevant information]
+
+[Examples]
+```
+
+## Nesting
+
+```plaintext
+nested element => unchanged
+```
+
+Support level: unsupported
+
+Nesting support is not factored into other features' support levels.
+
+## Escape Characters
+
+```plaintext
+literal backslash + character => unchanged
+```
+
+Support level: unsupported
+
+Escape character support is not factored into other features' support levels.
+
+## Paragraphs
+
+```plaintext
+paragraph => text line
+```
+
+Support level: full
+
+E.g:
+
+Markdown input:
+
+```markdown
+I will become a text line in the gemtext output.
+```
+
+Gemtext output:
+
+```gemtext
+I will become a text line in the gemtext output.
+```
+
+## Blockquotes
+
+```plaintext
+blockquote => quote line
+```
+
+Support level: full
+
+E.g:
+
+Markdown input:
+
+```markdown
+> I will become quote lines
+> in the gemtext output.
+```
+
+Gemtext output:
+
+```gemtext
+> I will become quote lines
+> in the gemtext output.
+```
+
+## Headings
+
+```plaintext
+heading => (flattened) heading
+```
+
+Support level: partial
+
+Number signs, equal signs, and dashes can delimit headings. Markdown heading levels greater than level 3 are flattened to level 3 in the gemtext output. The use of heading levels greater than level 3 is strongly discouraged.
+
+E.g:
+
+Markdown input:
+
+```markdown
+===
+I will become a level 1 heading in the gemtext output
+
+
+---------
+I will become a level 2 heading in the gemtext output
+
+
+### I will become a level 3 heading in the gemtext output
+
+
+#### I will become a level 3 heading in the gemtext output
+
+
+##### I will become a level 3 heading in the gemtext output
+
+
+###### I will become a level 3 heading in the gemtext output
+```
+
+Gemtext output:
+
+```gemtext
+# I will become a level 1 heading in the gemtext output
+
+
+## I will become a level 2 heading in the gemtext output
+
+
+### I will become a level 3 heading in the gemtext output
+
+
+### I will become a level 3 heading in the gemtext output
+
+
+### I will become a level 3 heading in the gemtext output
+
+
+### I will become a level 3 heading in the gemtext output
+```
+
+## Emphasis (Italic)
+
+```plaintext
+emphasis (italic) => text with italic delimiters removed
+```
+
+Support level: partial
+
+Asterisks delimiting italicized text are removed from the gemtext output.
+
+E.g:
+
+Markdown input:
+
+```markdown
+I will become *italicized* in the HTML output.
+```
+
+Gemtext output:
+
+```gemtext
+I will become italicized in the HTML output.
+```
+
+## Emphasis (Bold)
+
+```plaintext
+emphasis (bold) => text with bold delimiters removed
+```
+
+Support level: partial
+
+Asterisks delimiting bolded text are removed from the gemtext output.
+
+E.g:
+
+Markdown input:
+
+```markdown
+I will become **bolded** in the HTML output.
+```
+
+Gemtext output:
+
+```gemtext
+I will become bolded in the HTML output.
+```
+
+## Emphasis (Bold and Italic)
+
+```plaintext
+emphasis (bold and italic) => text with bold and italic delimiters removed
+```
+
+Support level: partial
+
+Asterisks delimiting bolded and italicized text are removed from the gemtext output.
+
+E.g:
+
+Markdown input:
+
+```markdown
+I will become ***bolded and italicized*** in the HTML output.
+```
+
+gemtext output:
+
+```gemtext
+I will become bolded and italicized in the HTML output.
+```
+
+## Unordered Lists
+
+```plaintext
+unordered list item => unordered list item
+```
+
+Support level: full
+
+Dashes \(\-\), asterisks \(\*\), and plus signs \(\+\) can delimit unordered list items.
+
+E.g:
+
+Markdown input:
+
+```markdown
+* I will become unordered list #1 item #1 in the gemtext output
+* I will become unordered list #1 item #2 in the gemtext output
+
+- I will become unordered list #2 item #1 in the gemtext output
+- I will become unordered list #2 item #2 in the gemtext output
+
++ I will become unordered list #3 item #1 in the gemtext output
++ I will become unordered list #3 item #2 in the gemtext output
+```
+
+Gemtext output:
+
+```markdown
+* I will become unordered list #1 item #1 in the gemtext output
+* I will become unordered list #1 item #2 in the gemtext output
+
+* I will become unordered list #2 item #1 in the gemtext output
+* I will become unordered list #2 item #2 in the gemtext output
+
+* I will become unordered list #3 item #1 in the gemtext output
+* I will become unordered list #3 item #2 in the gemtext output
+```
+
+## Ordered Lists
+
+```plaintext
+ordered list item => unordered list line
+```
+
+Support level: partial
+
+Numbers can delimit unordered list lines.
+
+E.g:
+
+Markdown input:
+
+```markdown
+1. I will become an unordered list line in the gemtext output
+2. I will also become an unordered list line in the gemtext output
+```
+
+Gemtext output:
+
+```gemtext
+* I will become an unordered list line in the gemtext output
+* I will also become an unordered list line in the gemtext output
+```
+
+## Preformatted Text
+
+```plaintext
+preformatted text => preformatting toggle lines + preformatted text lines
+```
+
+Support level: partial
+
+Only 3 consecutive backticks can delimit preformatted text. Text following the leading "```" on the same line is permitted.
+
+E.g:
+
+Markdown input:
+
+````markdown
+```markdown
+[this link](https://example.com) will not be rendered in the HTML nor in the gemtext output.
+```
+````
+
+Gemtext output:
+
+````gemtext
+```markdown
+[this link](https://example.com) will not be rendered in the HTML nor in the gemtext output.
+```
+````
+
+## Links
+
+```plaintext
+link => superscripted reference numbers + link lines
+```
+
+Support level: partial
+
+Hypertext references must be URL-encoded. Angle bracketed URLs, Markdown reference-style links, and linking to heading IDs are unsupported.
+
+If the "makerefs" variable in the frontmatter is set to true (the default), text enclosed in brackets \(e.g. \[Arch Linux\]\) immediately followed by a URL in parenthesis \(e.g. \(https://archlinux.org\)\) and an optional link title \("Arch Linux"\) becomes a reference-style link with a corresponding link line appended to the bottom of the page in the gemtext output. If there is a link title in the Markdown, it becomes the link name in the gemtext.
+
+E.g:
+
+Markdown input:
+
+```markdown
+[Debian](https://www.debian.org) is a good OS, but I prefer [arch](https://archlinux.org "Arch Linux").
+```
+ 
+Gemtext output:
+
+```gemtext
+Debian¹ is a good OS, but I prefer arch².
+
+
+## References
+
+=> https://www.debian.org 🔗 [1]: Debian
+=> https://archlinux.org 🔗 [2]: Arch Linux
+```
+
+If the "makerefs" variable in the frontmatter is set to false, reference-style links are not created and only links that occupy the entire line become link lines in the gemtext output.
+
+E.g:
+
+Markdown input:
+
+```markdown
+---
+<mandatory frontmatter>
+makerefs: false
+---
+[Puppy Linux](https://puppylinux-woof-ce.github.io "a lightweight linux distro")
+```
+
+Gemtext output:
+
+```gemtext
+=> https://puppylinux-woof-ce.github.io Puppy Linux
+```
+
+## Inline Images
+
+```plaintext
+inline image => link line
+```
+
+Support level: partial
+
+Links with a preceding exclamation mark are treated the same as normal links in the gemtext output.
+
+E.g:
+
+Markdown input:
+
+```markdown
+---
+<mandatory frontmatter>
+makerefs: false
+---
+Check out my dog:
+
+![Spot](pics/dogs/spot.jpeg "A black, brown, and white hound running in the yard with his tongue out")
+```
+
+Gemtext output:
+
+```gemtext
+Check out my dog:
+
+=> pics/dogs/spot.jpeg Spot
+```
+
+## Whitespace
+
+```plaintext
+whitespace => literal whitespace
+```
+
+Support level: partial
+
+Whitespace in the Markdown input is copied verbatim into the gemtext output. For maximum compatibility, it is advised to use 2 literal newlines after each element except before headings. Headings require 3 preceding literal newlines except at the start of the document.
+
+E.g:
+
+Markdown input:
+
+```markdown
+I will become a text line
+
+
+## I will become a level 2 heading
+
+* I will become unordered list item #1
+* I will become unordered list item #2
+
+> I will become
+> quote lines
+```
+
+Gemtext output:
+
+```gemtext
+I will become a text line
+
+
+## I will become a level 2 heading
+
+* I will become unordered list item #1
+* I will become unordered list item #2
+
+> I will become
+> quote lines
+```
diff --git a/GEMTEXT-COMPATIBILITY.md b/GEMTEXT-COMPATIBILITY.md
deleted file mode 100644
index e5a163c..0000000
--- a/GEMTEXT-COMPATIBILITY.md
+++ /dev/null
@@ -1,239 +0,0 @@
-# Gemtext Compatibility
-
-Gemtext output format support for Hugo is a hack. Since Hugo's theme API does not expose the Markdown parser, the Markdown is rendered into gemtext using regex. The lack of a proper Markdown parser coupled with the limitations of the [Gemini protocol](https://gemini.circumlunar.space/docs/specification.gmi)'s document format gemtext means only a limited subset of Markdown can be converted to gemtext. That subset is documented below. Any Markdown features not explicitly mentioned below should be assumed incompatible.
-
-## Paragraphs
-
-Markdown paragraphs are supported.
-
-Explanation:
-
-Markdown paragraphs map directly onto gemtext text lines. They are left unmodified.
-
-## Blockquotes
-
-Blockquotes are partially supported.
-
-Explanation:
-
-Markdown blockquotes map onto gemtext quote lines. Gemtext only supports flat (non-nested) quote lines that do not contain other elements like lists or headings. For compatibility, use only flat blockquotes containing no other elements.
-
-E.g:
-
-```markdown
-> I am a multi-line
-> quote for demo purposes.
-> I do not contain any
-> other elements.
-```
-
-## Headings
-
-Markdown headings are partially supported.
-
-Explanation:
-
-Markdown supports 6 headings while gemtext only supports 3. Markdown headings 1-3 \(\#, \#\#, \#\#\#\) map to their respective gemtext heading. Markdown headings 4-6 \(\#\#\#\#, \#\#\#\#\#, \#\#\#\#\#\#\) map to the level 3 \(\#\#\#\) gemtext heading. This flattening is also reflected in the HTML through the CSS styling.
-
-Alternate syntax for Markdown headings including == and -- is not supported. Only number signs \(\#\) may be used.
-
-The goldmark Markdown renderer requires whitespace between the number signs and the heading name whereas the gemtext specification does not. For compatibility, do not use Markdown headings 4-6 and always put a space after the number signs.
-
-## Whitespace
-
-Newlines are partially supported. Line breaks are unsupported.
-
-Explanation:
-
-The gemtext renderer and HTML renderer handle whitespace differently. While whitespace has special meaning in Markdown, the gemtext renderer simply copies it unmodified into the output. It is possible to achieve consecutive newlines in the HTML, but the gemtext won't render it correctly. For compatibility, use two literal newlines after each new element except before headings. Headings must be preceded by three literal newlines.
-
-E.g:
-
-````markdown
-I am a paragraph.
-
-* unordered list item 1
-* unordered list item 2
-
-1. ordered list item 1
-2. ordered list item 2
-
-
-## I am a Heading
-
-```
-I am preformatted text.
-```
-
-> I am
-> a quote
-````
-
-## Emphasis
-
-Bold and italics are partially supported.
-
-Explanation:
-
-Since gemtext does not support bold nor italics, bold and italic text in Markdown map onto gemtext text lines with the asterisks removed. The gemtext renderer only understands asterisks as representing bold or italics, not underscores. For compatibility, use asterisks and write text that doesn't strictly depend on the display of the bold or italics.
-
-E.g:
-
-Markdown input:
-
-```markdown
-*I am italic text!*
-**I am bold text!**
-***I am bold and italic text!***
-
-_I am italic text!_
-__I am bold text!__
-___I am bold and italic text!___
-```
-
-Gemtext output:
-
-```gemtext
-I am italic text!
-I am bold text!
-I am bold and italic text!
-
-_I am italic text!_
-__I am bold text!__
-___I am bold and italic text!___
-```
-
-## Lists
-
-Unordered lists are partially supported. Ordered lists are unsupported.
-
-Explanation:
-
-Since gemtext does not support ordered lists, ordered lists in Markdown map onto text lines in Gemini.
-
-Unordered list items in Markdown map onto unordered list items in gemtext. Gemtext does not support adding elements in lists nor nested lists. Dashes \(\-\), asterisks \(\*\), and plus signs \(\+\) can all be used to represent line items. For compatibility, use only flat lists containing no other elements.
-
-E.g:
-
-```
-* this is
-* a list
-
-- this is
-- a list
-
-+ this is
-+ a list
-```
-
-## Preformatted Text
-
-Preformatted text is partially supported.
-
-Explanation:
-
-Preformatted text in Markdown maps to preformatting toggle lines and preformatted text lines in gemtext. Gemtext only supports using 3 backticks to represent preformatting toggle lines. For best compatibility, always use exactly 3 backticks.
-
-E.g:
-
-````
-```plaintext
-I love Gemini!
-```
-````
-
-## Links
-
-Links are partially supported.
-
-Explanation:
-
-Links in Markdown map to link lines in gemtext. The gemtext renderer does not recognize angle bracketed URLs nor reference-style links. It only recognizes links that have link text enclosed in brackets \(e.g. \[Arch Linux\]\), immediately followed by the URL in parenthesis \(e.g. \(archlinux.org\)\).
-
-```markdown
-[Arch Linux](https://archlinux.org)
-```
-
-Gemtext does not support inline links. To circumvent this limitation, the default behavior is to create link references and append them to the bottom of the page.
-
-E.g:
-
-Markdown input:
-
-```markdown
-Do you like the [Arch Linux](https://archlinux.org) distro?
-
-What about the [Gentoo](https://www.gentoo.org/) distro?
-```
-
-Gemtext output:
-
-```gemtext
-Do you like the Arch Linux¹ distro?
-
-What about the Gentoo² distro?
-
-
-=> https://archlinux.org 🔗 1: Arch Linux 
-=> https://www.gentoo.org 🔗 2: Gentoo
-```
-
-To disable the link references at the bottom, set "makerefs" to false in the frontmatter. This changes the behavior of the gemtext renderer so that it only renders non-inline Markdown links.
-
-E.g:
-
-Markdown input with "makerefs" set to false:
-
-```markdown
-[Arch Linux](https://archlinux.org)
-
-any text before [Arch Linux](https://archlinux.org) or after
-```
-
-Gemtext output:
-
-```gemtext
-=> https://archlinux.org 🔗 Arch Linux
-
-any text before [Arch Linux](https://archlinux.org) or after
-```
-
-Inline images in Markdown can be added by putting an exclamation mark immediately before the link brackets. Gemtext does not support inline images, so they are rendered as normal links. They only show up inline in the HTML.
-
-E.g:
-
-Markdown input:
-
-```markdown
-![Cute cat photo](cat.png)
-```
-
-Gemtext output:
-
-```gemtext
-Cute cat photo¹
-
-
-=> cat.png 🔗 1: Cute cat photo
-```
-
-If a Markdown link has a title and the "makerefs" variable is set to true (the default), the link reference at the bottom of the page uses the link title instead of the link text.
-
-E.g:
-
-Markdown input:
-
-```markdown
-Do you like the [Arch Linux](https://archlinux.org "Arch") distro?
-```
-
-Gemtext output:
-
-```gemtext
-Do you like the Arch Linux¹ distro?
-
-
-=> https://archlinux.org 🔗 1: Arch
-```
-
-For compatibility, only use links with brackets and parenthesis. Always URL encode links. Do not use inline links with the "makerefs" page variable disabled. Do not omit link text nor hypertext references.
diff --git a/README.md b/README.md
index 66f8ae1..e0f09b2 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,10 @@ A live demo of the theme can be found at the following domain: [https://nicholas
 * English
 * Spanish
 
+## Documentation
+
+The [gemtext compatibility reference guide](GEMTEXT-COMPATIBILITY-REFERENCE-GUIDE.md) documents the compatibility of Markdown features with gemtext as an output format in of this Hugo theme. The [gemtext compatibility rationale document](GEMTEXT-COMPATIBILITY-RATIONALE.md) explains the rationale behind the design decisions for the gemtext output format.
+
 ## Get The Theme
 
 Run from the root of your Hugo site:
@@ -38,8 +42,6 @@ $ git submodule add https://git.nicholasjohnson.ch/hugo-theme-journal themes/jou
 
 To render the blog for Gemini and the Web, use separate configuration files. For guidance, look at [my journal repo](https://git.nicholasjohnson.ch/journal).
 
-The [Gemtext compatibility document](GEMTEXT-COMPATIBILITY.md) explains which Markdown can be safely converted to Gemini.
-
 ## Versioning
 
 This Hugo theme uses [Semantic Versioning 2.0.0](https://semver.org/).