| Not enough table | to be considered table |
+| Not enough table | to be considered table |
+These are ~not strikethroughs.
+This is not ~~~~~one~~~~~ huge strikethrough.
+ http://google.com/å
+
+scyther@pokemon.com
+
+scy.the_rbe-edr+ill@pokemon.com
+
+scyther@pokemon.com.
+
+scyther@pokemon.com/
+
+scyther@pokemon.com/beedrill@pokemon.com
+
+mailto:scyther@pokemon.com
+
+This is a mailto:scyther@pokemon.com
+
+mailto:scyther@pokemon.com.
+
+mmmmailto:scyther@pokemon.com
+
+mailto:scyther@pokemon.com/
+
+mailto:scyther@pokemon.com/message
+
+mailto:scyther@pokemon.com/mailto:beedrill@pokemon.com
+
+xmpp:scyther@pokemon.com
+
+xmpp:scyther@pokemon.com.
+
+xmpp:scyther@pokemon.com/message
+
+xmpp:scyther@pokemon.com/message.
+
+Email me at:scyther@pokemon.com
+
+www.github.com www.github.com/á
+
+www.google.com/a_b
+
+Underscores not allowed in host name www.xxx.yyy._zzz
+
+Underscores not allowed in host name www.xxx._yyy.zzz
+
+Underscores allowed in domain name www._xxx.yyy.zzz
+
+**Autolink and http://inlines**
+
+
+
+a.w@b.c
+
+Full stop outside parens shouldn't be included http://google.com/ok.
+
+(Full stop inside parens shouldn't be included http://google.com/ok.)
+
+"http://google.com"
+
+'http://google.com'
+
+http://🍄.ga/ http://x🍄.ga/
+.
+: http://google.com https://google.com
+http://google.com/å http://google.com/å
+scyther@pokemon.com
+scy.the_rbe-edr+ill@pokemon.com
+scyther@pokemon.com.
+scyther@pokemon.com/
+scyther@pokemon.com/beedrill@pokemon.com
+mailto:scyther@pokemon.com
+This is a mailto:scyther@pokemon.com
+mailto:scyther@pokemon.com.
+mmmmailto:scyther@pokemon.com
+mailto:scyther@pokemon.com/
+mailto:scyther@pokemon.com/message
+mailto:scyther@pokemon.com/mailto:beedrill@pokemon.com
+xmpp:scyther@pokemon.com
+xmpp:scyther@pokemon.com.
+xmpp:scyther@pokemon.com/message
+xmpp:scyther@pokemon.com/message.
+Email me at:scyther@pokemon.com
+www.github.com www.github.com/á
+www.google.com/a_b
+Underscores not allowed in host name www.xxx.yyy._zzz
+Underscores not allowed in host name www.xxx._yyy.zzz
+Underscores allowed in domain name www._xxx.yyy.zzz
+Autolink and http://inlines
+
+a.w@b.c
+Full stop outside parens shouldn't be included http://google.com/ok.
+(Full stop inside parens shouldn't be included http://google.com/ok.)
+"http://google.com"
+'http://google.com'
+http://🍄.ga/ http://x🍄.ga/
+````````````````````````````````
+
+```````````````````````````````` example
+This shouldn't crash everything: (_A_@_.A
+.
+
+````````````````````````````````
+
+```````````````````````````````` example
+These should not link:
+
+* @a.b.c@. x
+* n@. b
+.
+These should not link:
+
+````````````````````````````````
+
+## HTML tag filter
+
+
+```````````````````````````````` example
+This is <![CDATA[ not okay, but **this** <strong>is</strong>.
+
+<p>This is <xmp> not okay, but **this** <strong>is</strong>.</p>
+
+Nope, I won't have <textarea>.
+
+<p>No <textarea> here either.</p>
+
+<p>This <random /> <thing> is okay</thing> though.</p>
+
+Yep, <totally>okay</totally>.
+
+<!-- HTML comments are okay, though. -->
+<!- But we're strict. ->
+<! No nonsense. >
+<!-- Leave multiline comments the heck alone, though, okay?
+Even with {"x":"y"} or 1 > 2 or whatever. Even **markdown**.
+-->
+<!--- Support everything CommonMark's parser does. -->
+<!---->
+<!--thistoo-->
+.
+<p>This is <xmp> not okay, but <strong>this</strong> <strong>is</strong>.</p>
+<p>This is <xmp> not okay, but **this** <strong>is</strong>.</p>
+<p>Nope, I won't have <textarea>.</p>
+<p>No <textarea> here either.</p>
+<p>This <random /> <thing> is okay</thing> though.</p>
+<p>Yep, <totally>okay</totally>.</p>
+<!-- HTML comments are okay, though. -->
+<p><!- But we're strict. ->
+<! No nonsense. ></p>
+<!-- Leave multiline comments the heck alone, though, okay?
+Even with {"x":"y"} or 1 > 2 or whatever. Even **markdown**.
+-->
+<!--- Support everything CommonMark's parser does. -->
+<!---->
+<!--thistoo-->
+````````````````````````````````
+
+## Footnotes
+
+```````````````````````````````` example
+This is some text![^1]. Other text.[^footnote].
+
+Here's a thing[^other-note].
+
+And another thing[^codeblock-note].
+
+This doesn't have a referent[^nope].
+
+
+[^other-note]: no code block here (spaces are stripped away)
+
+[^codeblock-note]:
+ this is now a code block (8 spaces indentation)
+
+[^1]: Some *bolded* footnote definition.
+
+Hi!
+
+[^footnote]:
+ > Blockquotes can be in a footnote.
+
+ as well as code blocks
+
+ or, naturally, simple paragraphs.
+
+[^unused]: This is unused.
+.
+<p>This is some text!<sup class="footnote-ref"><a href="#fn-1" id="fnref-1" data-footnote-ref>1</a></sup>. Other text.<sup class="footnote-ref"><a href="#fn-footnote" id="fnref-footnote" data-footnote-ref>2</a></sup>.</p>
+<p>Here's a thing<sup class="footnote-ref"><a href="#fn-other-note" id="fnref-other-note" data-footnote-ref>3</a></sup>.</p>
+<p>And another thing<sup class="footnote-ref"><a href="#fn-codeblock-note" id="fnref-codeblock-note" data-footnote-ref>4</a></sup>.</p>
+<p>This doesn't have a referent[^nope].</p>
+<p>Hi!</p>
+<section class="footnotes" data-footnotes>
+<ol>
+<li id="fn-1">
+<p>Some <em>bolded</em> footnote definition. <a href="#fnref-1" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="1" aria-label="Back to reference 1">↩</a></p>
+</li>
+<li id="fn-footnote">
+<blockquote>
+<p>Blockquotes can be in a footnote.</p>
+</blockquote>
+<pre><code>as well as code blocks
+</code></pre>
+<p>or, naturally, simple paragraphs. <a href="#fnref-footnote" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="2" aria-label="Back to reference 2">↩</a></p>
+</li>
+<li id="fn-other-note">
+<p>no code block here (spaces are stripped away) <a href="#fnref-other-note" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="3" aria-label="Back to reference 3">↩</a></p>
+</li>
+<li id="fn-codeblock-note">
+<pre><code>this is now a code block (8 spaces indentation)
+</code></pre>
+<a href="#fnref-codeblock-note" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="4" aria-label="Back to reference 4">↩</a>
+</li>
+</ol>
+</section>
+````````````````````````````````
+
+## When a footnote is used multiple times, we insert multiple backrefs.
+
+```````````````````````````````` example
+This is some text. It has a footnote[^a-footnote].
+
+This footnote is referenced[^a-footnote] multiple times, in lots of different places.[^a-footnote]
+
+[^a-footnote]: This footnote definition should have three backrefs.
+.
+<p>This is some text. It has a footnote<sup class="footnote-ref"><a href="#fn-a-footnote" id="fnref-a-footnote" data-footnote-ref>1</a></sup>.</p>
+<p>This footnote is referenced<sup class="footnote-ref"><a href="#fn-a-footnote" id="fnref-a-footnote-2" data-footnote-ref>1</a></sup> multiple times, in lots of different places.<sup class="footnote-ref"><a href="#fn-a-footnote" id="fnref-a-footnote-3" data-footnote-ref>1</a></sup></p>
+<section class="footnotes" data-footnotes>
+<ol>
+<li id="fn-a-footnote">
+<p>This footnote definition should have three backrefs. <a href="#fnref-a-footnote" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="1" aria-label="Back to reference 1">↩</a> <a href="#fnref-a-footnote-2" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="1-2" aria-label="Back to reference 1-2">↩<sup class="footnote-ref">2</sup></a> <a href="#fnref-a-footnote-3" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="1-3" aria-label="Back to reference 1-3">↩<sup class="footnote-ref">3</sup></a></p>
+</li>
+</ol>
+</section>
+````````````````````````````````
+
+## Footnote reference labels are href escaped
+
+```````````````````````````````` example
+Hello[^"><script>alert(1)</script>]
+
+[^"><script>alert(1)</script>]: pwned
+.
+<p>Hello<sup class="footnote-ref"><a href="#fn-%22%3E%3Cscript%3Ealert(1)%3C/script%3E" id="fnref-%22%3E%3Cscript%3Ealert(1)%3C/script%3E" data-footnote-ref>1</a></sup></p>
+<section class="footnotes" data-footnotes>
+<ol>
+<li id="fn-%22%3E%3Cscript%3Ealert(1)%3C/script%3E">
+<p>pwned <a href="#fnref-%22%3E%3Cscript%3Ealert(1)%3C/script%3E" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="1" aria-label="Back to reference 1">↩</a></p>
+</li>
+</ol>
+</section>
+````````````````````````````````
+
+## Interop
+
+Autolink and strikethrough.
+
+```````````````````````````````` example
+~~www.google.com~~
+
+~~http://google.com~~
+.
+<p><del><a href="http://www.google.com">www.google.com</a></del></p>
+<p><del><a href="http://google.com">http://google.com</a></del></p>
+````````````````````````````````
+
+Autolink and tables.
+
+```````````````````````````````` example
+| a | b |
+| --- | --- |
+| https://github.com www.github.com | http://pokemon.com |
+.
+<table>
+<thead>
+<tr>
+<th>a</th>
+<th>b</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><a href="https://github.com">https://github.com</a> <a href="http://www.github.com">www.github.com</a></td>
+<td><a href="http://pokemon.com">http://pokemon.com</a></td>
+</tr>
+</tbody>
+</table>
+````````````````````````````````
+
+## Task lists
+
+```````````````````````````````` example
+- [ ] foo
+- [x] bar
+.
+<ul>
+<li><input type="checkbox" disabled="" /> foo</li>
+<li><input type="checkbox" checked="" disabled="" /> bar</li>
+</ul>
+````````````````````````````````
+
+Show that a task list and a regular list get processed the same in
+the way that sublists are created. If something works in a list
+item, then it should work the same way with a task. The only
+difference should be the tasklist marker. So, if we use something
+other than a space or x, it won't be recognized as a task item, and
+so will be treated as a regular item.
+
+```````````````````````````````` example
+- [x] foo
+ - [ ] bar
+ - [x] baz
+- [ ] bim
+
+Show a regular (non task) list to show that it has the same structure
+- [@] foo
+ - [@] bar
+ - [@] baz
+- [@] bim
+.
+<ul>
+<li><input type="checkbox" checked="" disabled="" /> foo
+<ul>
+<li><input type="checkbox" disabled="" /> bar</li>
+<li><input type="checkbox" checked="" disabled="" /> baz</li>
+</ul>
+</li>
+<li><input type="checkbox" disabled="" /> bim</li>
+</ul>
+<p>Show a regular (non task) list to show that it has the same structure</p>
+<ul>
+<li>[@] foo
+<ul>
+<li>[@] bar</li>
+<li>[@] baz</li>
+</ul>
+</li>
+<li>[@] bim</li>
+</ul>
+````````````````````````````````
+Use a larger indent -- a task list and a regular list should produce
+the same structure.
+
+```````````````````````````````` example
+- [x] foo
+ - [ ] bar
+ - [x] baz
+- [ ] bim
+
+Show a regular (non task) list to show that it has the same structure
+- [@] foo
+ - [@] bar
+ - [@] baz
+- [@] bim
+.
+<ul>
+<li><input type="checkbox" checked="" disabled="" /> foo
+<ul>
+<li><input type="checkbox" disabled="" /> bar</li>
+<li><input type="checkbox" checked="" disabled="" /> baz</li>
+</ul>
+</li>
+<li><input type="checkbox" disabled="" /> bim</li>
+</ul>
+<p>Show a regular (non task) list to show that it has the same structure</p>
+<ul>
+<li>[@] foo
+<ul>
+<li>[@] bar</li>
+<li>[@] baz</li>
+</ul>
+</li>
+<li>[@] bim</li>
+</ul>
+````````````````````````````````
diff --git a/documents/markdown/cmark-gfm/inline-autolink.md b/documents/markdown/cmark-gfm/inline-autolink.md
new file mode 100644
index 0000000..0f71482
--- /dev/null
+++ b/documents/markdown/cmark-gfm/inline-autolink.md
@@ -0,0 +1,14 @@
+closed (valid) autolinks:
+
+ <ftp://1.2.3.4:21/path/foo>
+ <http://foo.bar.baz?q=hello&id=22&boolean>
+ <http://veeeeeeeeeeeeeeeeeeery.loooooooooooooooooooooooooooooooong.autolink/>
+ <teeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeest@gmail.com>
+
+these are not autolinks:
+
+ <ftp://1.2.3.4:21/path/foo
+ <http://foo.bar.baz?q=hello&id=22&boolean
+ <http://veeeeeeeeeeeeeeeeeeery.loooooooooooooooooooooooooooooooong.autolink
+ <teeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeest@gmail.com
+ < http://foo.bar.baz?q=hello&id=22&boolean >
diff --git a/documents/markdown/cmark-gfm/inline-em-flat.md b/documents/markdown/cmark-gfm/inline-em-flat.md
new file mode 100644
index 0000000..b7668a5
--- /dev/null
+++ b/documents/markdown/cmark-gfm/inline-em-flat.md
@@ -0,0 +1,5 @@
+*this* *is* *your* *basic* *boring* *emphasis*
+
+_this_ _is_ _your_ _basic_ _boring_ _emphasis_
+
+**this** **is** **your** **basic** **boring** **emphasis**
diff --git a/documents/markdown/cmark-gfm/inline-em-nested.md b/documents/markdown/cmark-gfm/inline-em-nested.md
new file mode 100644
index 0000000..6bb0a0d
--- /dev/null
+++ b/documents/markdown/cmark-gfm/inline-em-nested.md
@@ -0,0 +1,5 @@
+*this *is *a *bunch* of* nested* emphases*
+
+__this __is __a __bunch__ of__ nested__ emphases__
+
+***this ***is ***a ***bunch*** of*** nested*** emphases***
diff --git a/documents/markdown/cmark-gfm/inline-em-worst.md b/documents/markdown/cmark-gfm/inline-em-worst.md
new file mode 100644
index 0000000..b6d21da
--- /dev/null
+++ b/documents/markdown/cmark-gfm/inline-em-worst.md
@@ -0,0 +1,5 @@
+*this *is *a *worst *case *for *em *backtracking
+
+__this __is __a __worst __case __for __em __backtracking
+
+***this ***is ***a ***worst ***case ***for ***em ***backtracking
diff --git a/documents/markdown/cmark-gfm/inline-entity.md b/documents/markdown/cmark-gfm/inline-entity.md
new file mode 100644
index 0000000..da095ed
--- /dev/null
+++ b/documents/markdown/cmark-gfm/inline-entity.md
@@ -0,0 +1,11 @@
+entities:
+
+ & © Æ Ď ¾ ℋ ⅆ ∲
+
+# Ӓ Ϡ �
+
+non-entities:
+
+&18900987654321234567890; &1234567890098765432123456789009876543212345678987654;
+
+&qwertyuioppoiuytrewqwer; &oiuytrewqwertyuioiuytrewqwertyuioytrewqwertyuiiuytri;
diff --git a/documents/markdown/cmark-gfm/inline-escape.md b/documents/markdown/cmark-gfm/inline-escape.md
new file mode 100644
index 0000000..4e1bb39
--- /dev/null
+++ b/documents/markdown/cmark-gfm/inline-escape.md
@@ -0,0 +1,15 @@
+
+\t\e\s\t\i\n\g \e\s\c\a\p\e \s\e\q\u\e\n\c\e\s
+
+\!\\\"\#\$\%\&\'\(\)\*\+\,\.\/\:\;\<\=\>\?
+
+\@ \[ \] \^ \_ \` \{ \| \} \~ \- \'
+
+\
+\\
+\\\
+\\\\
+\\\\\
+
+\<this\> \<is\> \<not\> \<html\>
+
diff --git a/documents/markdown/cmark-gfm/inline-html.md b/documents/markdown/cmark-gfm/inline-html.md
new file mode 100644
index 0000000..f6e6341
--- /dev/null
+++ b/documents/markdown/cmark-gfm/inline-html.md
@@ -0,0 +1,44 @@
+Taking commonmark tests from the spec for benchmarking here:
+
+<a><bab><c2c>
+
+<a/><b2/>
+
+<a /><b2
+data="foo" >
+
+<a foo="bar" bam = 'baz <em>"</em>'
+_boolean zoop:33=zoop:33 />
+
+<33> <__>
+
+<a h*#ref="hi">
+
+<a href="hi'> <a href=hi'>
+
+< a><
+foo><bar/ >
+
+<a href='bar'title=title>
+
+</a>
+</foo >
+
+</a href="foo">
+
+foo <!-- this is a
+comment - with hyphen -->
+
+foo <!-- not a comment -- two hyphens -->
+
+foo <?php echo $a; ?>
+
+foo <!ELEMENT br EMPTY>
+
+foo <![CDATA[>&<]]]]><![CDATA[>
+
+<a href="ö">
+
+<a href="\*">
+
+<a href="\"">
diff --git a/documents/markdown/cmark-gfm/inline-links-flat.md b/documents/markdown/cmark-gfm/inline-links-flat.md
new file mode 100644
index 0000000..5117db8
--- /dev/null
+++ b/documents/markdown/cmark-gfm/inline-links-flat.md
@@ -0,0 +1,23 @@
+Valid links:
+
+ [this is a link]()
+ [this is a link](<http://something.example.com/foo/bar>)
+ [this is a link](http://something.example.com/foo/bar 'test')
+ ![this is an image]()
+ 
+ 
+
+ [escape test](<\>\>\>\>\>\>\>\>\>\>\>\>\>\>> '\'\'\'\'\'\'\'\'\'\'\'\'\'\'')
+ [escape test \]\]\]\]\]\]\]\]\]\]\]\]\]\]\]\]](\)\)\)\)\)\)\)\)\)\)\)\)\)\))
+
+Invalid links:
+
+ [this is not a link
+
+ [this is not a link](
+
+ [this is not a link](http://something.example.com/foo/bar 'test'
+
+ [this is not a link](((((((((((((((((((((((((((((((((((((((((((((((
+
+ [this is not a link]((((((((((()))))))))) (((((((((()))))))))))
diff --git a/documents/markdown/cmark-gfm/inline-links-nested.md b/documents/markdown/cmark-gfm/inline-links-nested.md
new file mode 100644
index 0000000..4e7dc85
--- /dev/null
+++ b/documents/markdown/cmark-gfm/inline-links-nested.md
@@ -0,0 +1,13 @@
+Valid links:
+
+[[[[[[[[](test)](test)](test)](test)](test)](test)](test)]
+
+[ [[[[[[[[[[[[[[[[[[ [](test) ]]]]]]]]]]]]]]]]]] ](test)
+
+Invalid links:
+
+[[[[[[[[[
+
+[ [ [ [ [ [ [ [ [ [ [ [ [ [ [ [ [ [ [ [ [ [ [ [ [ [ [ [ [ [ [ [ [ [ [ [ [ [
+
+ lobortis, sapien arcu mattis erat, vel aliquet sem urna et risus. Ut feugiat sapien vitae mi elementum laoreet. Suspendisse potenti. Aliquam erat nisl, aliquam pretium libero aliquet, sagittis eleifend nunc. In hac habitasse platea dictumst. Integer turpis augue, tincidunt dignissim mauris id, rhoncus dapibus purus. Maecenas et enim odio. Nullam massa metus, varius quis vehicula sed, pharetra mollis erat. In quis viverra velit. Vivamus placerat, est nec hendrerit varius, enim dui hendrerit magna, ut pulvinar nibh lorem vel lacus. Mauris a orci iaculis, hendrerit eros sed, gravida leo. In dictum mauris vel augue varius, ac ullamcorper nisl ornare. In eu posuere velit, ac fermentum arcu. Interdum et malesuada fames ac ante ipsum primis in faucibus. Nullam sed malesuada leo, at interdum elit.
+
+Nullam ut tincidunt nunc. [Pellentesque][1] metus lacus, commodo eget justo ut, rutrum varius nunc. Sed non rhoncus risus. Morbi sodales gravida pulvinar. Duis malesuada, odio volutpat elementum vulputate, massa magna scelerisque ante, et accumsan tellus nunc in sem. Donec mattis arcu et velit aliquet, non sagittis justo vestibulum. Suspendisse volutpat felis lectus, nec consequat ipsum mattis id. Donec dapibus vehicula facilisis. In tincidunt mi nisi, nec faucibus tortor euismod nec. Suspendisse ante ligula, aliquet vitae libero eu, vulputate dapibus libero. Sed bibendum, sapien at posuere interdum, libero est sollicitudin magna, ac gravida tellus purus eu ipsum. Proin ut quam arcu.
+
+Suspendisse potenti. Donec ante velit, ornare at augue quis, tristique laoreet sem. Etiam in ipsum elit. Nullam cursus dolor sit amet nulla feugiat tristique. Phasellus ac tellus tincidunt, imperdiet purus eget, ullamcorper ipsum. Cras eu tincidunt sem. Nullam sed dapibus magna. Lorem ipsum dolor sit amet, consectetur adipiscing elit. In id venenatis tortor. In consectetur sollicitudin pharetra. Etiam convallis nisi nunc, et aliquam turpis viverra sit amet. Maecenas faucibus sodales tortor. Suspendisse lobortis mi eu leo viverra volutpat. Pellentesque velit ante, vehicula sodales congue ut, elementum a urna. Cras tempor, ipsum eget luctus rhoncus, arcu ligula fermentum urna, vulputate pharetra enim enim non libero.
+
+Proin diam quam, elementum in eleifend id, elementum et metus. Cras in justo consequat justo semper ultrices. Sed dignissim lectus a ante mollis, nec vulputate ante molestie. Proin in porta nunc. Etiam pulvinar turpis sed velit porttitor, vel adipiscing velit fringilla. Cras ac tellus vitae purus pharetra tincidunt. Sed cursus aliquet aliquet. Cras eleifend commodo malesuada. In turpis turpis, ullamcorper ut tincidunt a, ullamcorper a nunc. Etiam luctus tellus ac dapibus gravida. Ut nec lacus laoreet neque ullamcorper volutpat.
+
+Nunc et leo erat. Aenean mattis ultrices lorem, eget adipiscing dolor ultricies eu. In hac habitasse platea dictumst. Vivamus cursus feugiat sapien quis aliquam. Mauris quam libero, porta vel volutpat ut, blandit a purus. Vivamus vestibulum dui vel tortor molestie, sit amet feugiat sem commodo. Nulla facilisi. Sed molestie arcu eget tellus vestibulum tristique.
+
+[1]: https://github.com/markdown-it
diff --git a/documents/markdown/cmark-gfm/rawtabs.md b/documents/markdown/cmark-gfm/rawtabs.md
new file mode 100644
index 0000000..dc989ea
--- /dev/null
+++ b/documents/markdown/cmark-gfm/rawtabs.md
@@ -0,0 +1,18 @@
+
+this is a test for tab expansion, be careful not to replace them with spaces
+
+1 4444
+22 333
+333 22
+4444 1
+
+
+ tab-indented line
+ space-indented line
+ tab-indented line
+
+
+a lot of spaces in between here
+
+a lot of tabs in between here
+
diff --git a/documents/markdown/cmark-gfm/regression.md b/documents/markdown/cmark-gfm/regression.md
new file mode 100644
index 0000000..cbf3d00
--- /dev/null
+++ b/documents/markdown/cmark-gfm/regression.md
@@ -0,0 +1,375 @@
+### Regression tests
+
+Issue #113: EOL character weirdness on Windows
+(Important: first line ends with CR + CR + LF)
+
+```````````````````````````````` example
+line1
+line2
+.
+<p>line1</p>
+<p>line2</p>
+````````````````````````````````
+
+Issue #114: cmark skipping first character in line
+(Important: the blank lines around "Repeatedly" contain a tab.)
+
+```````````````````````````````` example
+By taking it apart
+
+- alternative solutions
+→
+Repeatedly solving
+→
+- how techniques
+.
+<p>By taking it apart</p>
+<ul>
+<li>alternative solutions</li>
+</ul>
+<p>Repeatedly solving</p>
+<ul>
+<li>how techniques</li>
+</ul>
+````````````````````````````````
+
+Issue jgm/CommonMark#430: h2..h6 not recognized as block tags.
+
+```````````````````````````````` example
+<h1>lorem</h1>
+
+<h2>lorem</h2>
+
+<h3>lorem</h3>
+
+<h4>lorem</h4>
+
+<h5>lorem</h5>
+
+<h6>lorem</h6>
+.
+<h1>lorem</h1>
+<h2>lorem</h2>
+<h3>lorem</h3>
+<h4>lorem</h4>
+<h5>lorem</h5>
+<h6>lorem</h6>
+````````````````````````````````
+
+Issue jgm/commonmark.js#109 - tabs after setext header line
+
+
+```````````````````````````````` example
+hi
+--→
+.
+<h2>hi</h2>
+````````````````````````````````
+
+Issue #177 - incorrect emphasis parsing
+
+```````````````````````````````` example
+a***b* c*
+.
+<p>a*<em><em>b</em> c</em></p>
+````````````````````````````````
+
+Issue #193 - unescaped left angle brackets in link destination
+
+```````````````````````````````` example
+[a]
+
+[a]: <te<st>
+.
+<p>[a]</p>
+<p>[a]: <te<st></p>
+````````````````````````````````
+
+Issue #192 - escaped spaces in link destination
+
+
+```````````````````````````````` example
+[a](te\ st)
+.
+<p>[a](te\ st)</p>
+````````````````````````````````
+
+Issue github/github#76615: multiple delimiter combinations gets sketchy
+
+
+```````````````````````````````` example strikethrough
+~~**_`this`_**~~
+~~***`this`***~~
+~~___`this`___~~
+
+**_`this`_**
+***`this`***
+___`this`___
+
+~~**_this_**~~
+~~***this***~~
+~~___this___~~
+
+**_this_**
+***this***
+___this___
+.
+<p><del><strong><em><code>this</code></em></strong></del><br />
+<del><em><strong><code>this</code></strong></em></del><br />
+<del><em><strong><code>this</code></strong></em></del></p>
+<p><strong><em><code>this</code></em></strong><br />
+<em><strong><code>this</code></strong></em><br />
+<em><strong><code>this</code></strong></em></p>
+<p><del><strong><em>this</em></strong></del><br />
+<del><em><strong>this</strong></em></del><br />
+<del><em><strong>this</strong></em></del></p>
+<p><strong><em>this</em></strong><br />
+<em><strong>this</strong></em><br />
+<em><strong>this</strong></em></p>
+````````````````````````````````
+
+Issue #527 - meta tags in inline contexts
+
+```````````````````````````````` example
+City:
+<span itemprop="contentLocation" itemscope itemtype="https://schema.org/City">
+ <meta itemprop="name" content="Springfield">
+</span>
+.
+<p>City:
+<span itemprop="contentLocation" itemscope itemtype="https://schema.org/City">
+<meta itemprop="name" content="Springfield">
+</span></p>
+````````````````````````````````
+
+cmark-gfm strikethrough rules
+
+```````````````````````````````` example strikethrough
+~Hi~ Hello, world!
+.
+<p><del>Hi</del> Hello, world!</p>
+````````````````````````````````
+
+```````````````````````````````` example strikethrough
+This ~text~ ~~is~~ ~~~curious~~~.
+.
+<p>This <del>text</del> <del>is</del> ~~~curious~~~.</p>
+````````````````````````````````
+
+`~` should not be escaped in href — https://github.com/github/markup/issues/311
+
+```````````````````````````````` example
+[x](http://members.aon.at/~nkehrer/ibm_5110/emu5110.html)
+.
+<p><a href="http://members.aon.at/~nkehrer/ibm_5110/emu5110.html">x</a></p>
+````````````````````````````````
+
+Footnotes in tables
+
+```````````````````````````````` example table footnotes
+A footnote in a paragraph[^1]
+
+| Column1 | Column2 |
+| --------- | ------- |
+| foot [^1] | note |
+
+[^1]: a footnote
+.
+<p>A footnote in a paragraph<sup class="footnote-ref"><a href="#fn-1" id="fnref-1" data-footnote-ref>1</a></sup></p>
+<table>
+<thead>
+<tr>
+<th>Column1</th>
+<th>Column2</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>foot <sup class="footnote-ref"><a href="#fn-1" id="fnref-1-2" data-footnote-ref>1</a></sup></td>
+<td>note</td>
+</tr>
+</tbody>
+</table>
+<section class="footnotes" data-footnotes>
+<ol>
+<li id="fn-1">
+<p>a footnote <a href="#fnref-1" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="1" aria-label="Back to reference 1">↩</a> <a href="#fnref-1-2" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="1-2" aria-label="Back to reference 1-2">↩<sup class="footnote-ref">2</sup></a></p>
+</li>
+</ol>
+</section>
+````````````````````````````````
+
+Issue #527 - meta tags in inline contexts
+
+```````````````````````````````` example
+City:
+<span itemprop="contentLocation" itemscope itemtype="https://schema.org/City">
+ <meta itemprop="name" content="Springfield">
+</span>
+.
+<p>City:
+<span itemprop="contentLocation" itemscope itemtype="https://schema.org/City">
+<meta itemprop="name" content="Springfield">
+</span></p>
+````````````````````````````````
+
+Issue #530 - link parsing corner cases
+
+```````````````````````````````` example
+[a](\ b)
+
+[a](<<b)
+
+[a](<b
+)
+.
+<p>[a](\ b)</p>
+<p>[a](<<b)</p>
+<p>[a](<b
+)</p>
+````````````````````````````````
+
+Issue commonmark#526 - unescaped ( in link title
+
+```````````````````````````````` example
+[link](url ((title))
+.
+<p>[link](url ((title))</p>
+````````````````````````````````
+
+Issue commonamrk#517 - script, pre, style close tag without
+opener.
+
+```````````````````````````````` example
+</script>
+
+</pre>
+
+</style>
+.
+</script>
+</pre>
+</style>
+````````````````````````````````
+
+Issue #289.
+
+```````````````````````````````` example
+[a](<b) c>
+.
+<p>[a](<b) c></p>
+````````````````````````````````
+
+Pull request #128 - Buffer overread in tables extension
+
+```````````````````````````````` example table
+|
+-|
+.
+<p>|
+-|</p>
+````````````````````````````````
+
+Footnotes may be nested inside other footnotes.
+
+```````````````````````````````` example footnotes
+This is some text. It has a citation.[^citation]
+
+[^another-citation]: My second citation.
+
+[^citation]: This is a long winded parapgraph that also has another citation.[^another-citation]
+.
+<p>This is some text. It has a citation.<sup class="footnote-ref"><a href="#fn-citation" id="fnref-citation" data-footnote-ref>1</a></sup></p>
+<section class="footnotes" data-footnotes>
+<ol>
+<li id="fn-citation">
+<p>This is a long winded parapgraph that also has another citation.<sup class="footnote-ref"><a href="#fn-another-citation" id="fnref-another-citation" data-footnote-ref>2</a></sup> <a href="#fnref-citation" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="1" aria-label="Back to reference 1">↩</a></p>
+</li>
+<li id="fn-another-citation">
+<p>My second citation. <a href="#fnref-another-citation" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="2" aria-label="Back to reference 2">↩</a></p>
+</li>
+</ol>
+</section>
+````````````````````````````````
+
+Footnotes are similar to, but should not be confused with, link references
+
+```````````````````````````````` example footnotes
+This is some text. It has two footnotes references, side-by-side without any spaces,[^footnote1][^footnote2] which are definitely not link references.
+
+[^footnote1]: Hello.
+
+[^footnote2]: Goodbye.
+.
+<p>This is some text. It has two footnotes references, side-by-side without any spaces,<sup class="footnote-ref"><a href="#fn-footnote1" id="fnref-footnote1" data-footnote-ref>1</a></sup><sup class="footnote-ref"><a href="#fn-footnote2" id="fnref-footnote2" data-footnote-ref>2</a></sup> which are definitely not link references.</p>
+<section class="footnotes" data-footnotes>
+<ol>
+<li id="fn-footnote1">
+<p>Hello. <a href="#fnref-footnote1" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="1" aria-label="Back to reference 1">↩</a></p>
+</li>
+<li id="fn-footnote2">
+<p>Goodbye. <a href="#fnref-footnote2" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="2" aria-label="Back to reference 2">↩</a></p>
+</li>
+</ol>
+</section>
+````````````````````````````````
+
+Footnotes may begin with or have a 'w' or a '_' in their reference label.
+
+```````````````````````````````` example footnotes autolink
+This is some text. Sometimes the autolinker splits up text into multiple nodes, hoping it will find a hyperlink, so this text has a footnote whose reference label begins with a `w`.[^widely-cited]
+
+It has another footnote that contains many different characters (the autolinker was also breaking on `_`).[^sphinx-of-black-quartz_judge-my-vow-0123456789]
+
+[^sphinx-of-black-quartz_judge-my-vow-0123456789]: so does this.
+
+[^widely-cited]: this renders properly.
+.
+<p>This is some text. Sometimes the autolinker splits up text into multiple nodes, hoping it will find a hyperlink, so this text has a footnote whose reference label begins with a <code>w</code>.<sup class="footnote-ref"><a href="#fn-widely-cited" id="fnref-widely-cited" data-footnote-ref>1</a></sup></p>
+<p>It has another footnote that contains many different characters (the autolinker was also breaking on <code>_</code>).<sup class="footnote-ref"><a href="#fn-sphinx-of-black-quartz_judge-my-vow-0123456789" id="fnref-sphinx-of-black-quartz_judge-my-vow-0123456789" data-footnote-ref>2</a></sup></p>
+<section class="footnotes" data-footnotes>
+<ol>
+<li id="fn-widely-cited">
+<p>this renders properly. <a href="#fnref-widely-cited" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="1" aria-label="Back to reference 1">↩</a></p>
+</li>
+<li id="fn-sphinx-of-black-quartz_judge-my-vow-0123456789">
+<p>so does this. <a href="#fnref-sphinx-of-black-quartz_judge-my-vow-0123456789" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="2" aria-label="Back to reference 2">↩</a></p>
+</li>
+</ol>
+</section>
+````````````````````````````````
+
+Footnotes interacting with strikethrough should not lead to a use-after-free
+
+```````````````````````````````` example footnotes autolink strikethrough table
+|Tot.....[^_a_]|
+.
+<p>|Tot.....[^_a_]|</p>
+````````````````````````````````
+
+Footnotes interacting with strikethrough should not lead to a use-after-free pt2
+
+```````````````````````````````` example footnotes autolink strikethrough table
+[^~~is~~1]
+.
+<p>[^~~is~~1]</p>
+````````````````````````````````
+
+Adjacent unused footnotes definitions should not lead to a use after free
+
+```````````````````````````````` example footnotes autolink strikethrough table
+Hello world
+
+
+[^a]:[^b]:
+.
+<p>Hello world</p>
+````````````````````````````````
+
+Issue #424 - emphasis before links
+
+```````````````````````````````` example
+*text* [link](#section)
+.
+<p><em>text</em> <a href="#section">link</a></p>
+````````````````````````````````
diff --git a/documents/markdown/cmark-gfm/smart_punct.md b/documents/markdown/cmark-gfm/smart_punct.md
new file mode 100644
index 0000000..fd55e62
--- /dev/null
+++ b/documents/markdown/cmark-gfm/smart_punct.md
@@ -0,0 +1,177 @@
+## Smart punctuation
+
+Open quotes are matched with closed quotes.
+The same method is used for matching openers and closers
+as is used in emphasis parsing:
+
+```````````````````````````````` example
+"Hello," said the spider.
+"'Shelob' is my name."
+.
+<p>“Hello,” said the spider.
+“‘Shelob’ is my name.”</p>
+````````````````````````````````
+
+```````````````````````````````` example
+'A', 'B', and 'C' are letters.
+.
+<p>‘A’, ‘B’, and ‘C’ are letters.</p>
+````````````````````````````````
+
+```````````````````````````````` example
+'Oak,' 'elm,' and 'beech' are names of trees.
+So is 'pine.'
+.
+<p>‘Oak,’ ‘elm,’ and ‘beech’ are names of trees.
+So is ‘pine.’</p>
+````````````````````````````````
+
+```````````````````````````````` example
+'He said, "I want to go."'
+.
+<p>‘He said, “I want to go.”’</p>
+````````````````````````````````
+
+A single quote that isn't an open quote matched
+with a close quote will be treated as an
+apostrophe:
+
+```````````````````````````````` example
+Were you alive in the 70's?
+.
+<p>Were you alive in the 70’s?</p>
+````````````````````````````````
+
+```````````````````````````````` example
+Here is some quoted '`code`' and a "[quoted link](url)".
+.
+<p>Here is some quoted ‘<code>code</code>’ and a “<a href="url">quoted link</a>”.</p>
+````````````````````````````````
+
+Here the first `'` is treated as an apostrophe, not
+an open quote, because the final single quote is matched
+by the single quote before `jolly`:
+
+```````````````````````````````` example
+'tis the season to be 'jolly'
+.
+<p>’tis the season to be ‘jolly’</p>
+````````````````````````````````
+
+Multiple apostrophes should not be marked as open/closing quotes.
+
+```````````````````````````````` example
+'We'll use Jane's boat and John's truck,' Jenna said.
+.
+<p>‘We’ll use Jane’s boat and John’s truck,’ Jenna said.</p>
+````````````````````````````````
+
+An unmatched double quote will be interpreted as a
+left double quote, to facilitate this style:
+
+```````````````````````````````` example
+"A paragraph with no closing quote.
+
+"Second paragraph by same speaker, in fiction."
+.
+<p>“A paragraph with no closing quote.</p>
+<p>“Second paragraph by same speaker, in fiction.”</p>
+````````````````````````````````
+
+A quote following a `]` or `)` character cannot
+be an open quote:
+
+```````````````````````````````` example
+[a]'s b'
+.
+<p>[a]’s b’</p>
+````````````````````````````````
+
+Quotes that are escaped come out as literal straight
+quotes:
+
+```````````````````````````````` example
+\"This is not smart.\"
+This isn\'t either.
+5\'8\"
+.
+<p>"This is not smart."
+This isn't either.
+5'8"</p>
+````````````````````````````````
+
+Two hyphens form an en-dash, three an em-dash.
+
+```````````````````````````````` example
+Some dashes: em---em
+en--en
+em --- em
+en -- en
+2--3
+.
+<p>Some dashes: em—em
+en–en
+em — em
+en – en
+2–3</p>
+````````````````````````````````
+
+A sequence of more than three hyphens is
+parsed as a sequence of em and/or en dashes,
+with no hyphens. If possible, a homogeneous
+sequence of dashes is used (so, 10 hyphens
+= 5 en dashes, and 9 hyphens = 3 em dashes).
+When a heterogeneous sequence must be used,
+the em dashes come first, followed by the en
+dashes, and as few en dashes as possible are
+used (so, 7 hyphens = 2 em dashes an 1 en
+dash).
+
+```````````````````````````````` example
+one-
+two--
+three---
+four----
+five-----
+six------
+seven-------
+eight--------
+nine---------
+thirteen-------------.
+.
+<p>one-
+two–
+three—
+four––
+five—–
+six——
+seven—––
+eight––––
+nine———
+thirteen———––.</p>
+````````````````````````````````
+
+Hyphens can be escaped:
+
+```````````````````````````````` example
+Escaped hyphens: \-- \-\-\-.
+.
+<p>Escaped hyphens: -- ---.</p>
+````````````````````````````````
+
+Three periods form an ellipsis:
+
+```````````````````````````````` example
+Ellipses...and...and....
+.
+<p>Ellipses…and…and….</p>
+````````````````````````````````
+
+Periods can be escaped if ellipsis-formation
+is not wanted:
+
+```````````````````````````````` example
+No ellipses\.\.\.
+.
+<p>No ellipses...</p>
+````````````````````````````````
diff --git a/documents/markdown/cmark-gfm/spec.md b/documents/markdown/cmark-gfm/spec.md
new file mode 100644
index 0000000..d42f336
--- /dev/null
+++ b/documents/markdown/cmark-gfm/spec.md
@@ -0,0 +1,10212 @@
+---
+title: GitHub Flavored Markdown Spec
+version: 0.29
+date: '2019-04-06'
+license: '[CC-BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/)'
+...
+
+# Introduction
+
+## What is GitHub Flavored Markdown?
+
+GitHub Flavored Markdown, often shortened as GFM, is the dialect of Markdown
+that is currently supported for user content on GitHub.com and GitHub
+Enterprise.
+
+This formal specification, based on the CommonMark Spec, defines the syntax and
+semantics of this dialect.
+
+GFM is a strict superset of CommonMark. All the features which are supported in
+GitHub user content and that are not specified on the original CommonMark Spec
+are hence known as **extensions**, and highlighted as such.
+
+While GFM supports a wide range of inputs, it's worth noting that GitHub.com
+and GitHub Enterprise perform additional post-processing and sanitization after
+GFM is converted to HTML to ensure security and consistency of the website.
+
+## What is Markdown?
+
+Markdown is a plain text format for writing structured documents,
+based on conventions for indicating formatting in email
+and usenet posts. It was developed by John Gruber (with
+help from Aaron Swartz) and released in 2004 in the form of a
+[syntax description](http://daringfireball.net/projects/markdown/syntax)
+and a Perl script (`Markdown.pl`) for converting Markdown to
+HTML. In the next decade, dozens of implementations were
+developed in many languages. Some extended the original
+Markdown syntax with conventions for footnotes, tables, and
+other document elements. Some allowed Markdown documents to be
+rendered in formats other than HTML. Websites like Reddit,
+StackOverflow, and GitHub had millions of people using Markdown.
+And Markdown started to be used beyond the web, to author books,
+articles, slide shows, letters, and lecture notes.
+
+What distinguishes Markdown from many other lightweight markup
+syntaxes, which are often easier to write, is its readability.
+As Gruber writes:
+
+> The overriding design goal for Markdown's formatting syntax is
+> to make it as readable as possible. The idea is that a
+> Markdown-formatted document should be publishable as-is, as
+> plain text, without looking like it's been marked up with tags
+> or formatting instructions.
+> (<http://daringfireball.net/projects/markdown/>)
+
+The point can be illustrated by comparing a sample of
+[AsciiDoc](http://www.methods.co.nz/asciidoc/) with
+an equivalent sample of Markdown. Here is a sample of
+AsciiDoc from the AsciiDoc manual:
+
+```
+1. List item one.
++
+List item one continued with a second paragraph followed by an
+Indented block.
++
+.................
+$ ls *.sh
+$ mv *.sh ~/tmp
+.................
++
+List item continued with a third paragraph.
+
+2. List item two continued with an open block.
++
+--
+This paragraph is part of the preceding list item.
+
+a. This list is nested and does not require explicit item
+continuation.
++
+This paragraph is part of the preceding list item.
+
+b. List item b.
+
+This paragraph belongs to item two of the outer list.
+--
+```
+
+And here is the equivalent in Markdown:
+```
+1. List item one.
+
+ List item one continued with a second paragraph followed by an
+ Indented block.
+
+ $ ls *.sh
+ $ mv *.sh ~/tmp
+
+ List item continued with a third paragraph.
+
+2. List item two continued with an open block.
+
+ This paragraph is part of the preceding list item.
+
+ 1. This list is nested and does not require explicit item continuation.
+
+ This paragraph is part of the preceding list item.
+
+ 2. List item b.
+
+ This paragraph belongs to item two of the outer list.
+```
+
+The AsciiDoc version is, arguably, easier to write. You don't need
+to worry about indentation. But the Markdown version is much easier
+to read. The nesting of list items is apparent to the eye in the
+source, not just in the processed document.
+
+## Why is a spec needed?
+
+John Gruber's [canonical description of Markdown's
+syntax](http://daringfireball.net/projects/markdown/syntax)
+does not specify the syntax unambiguously. Here are some examples of
+questions it does not answer:
+
+1. How much indentation is needed for a sublist? The spec says that
+ continuation paragraphs need to be indented four spaces, but is
+ not fully explicit about sublists. It is natural to think that
+ they, too, must be indented four spaces, but `Markdown.pl` does
+ not require that. This is hardly a "corner case," and divergences
+ between implementations on this issue often lead to surprises for
+ users in real documents. (See [this comment by John
+ Gruber](https://web.archive.org/web/20170611172104/http://article.gmane.org/gmane.text.markdown.general/1997).)
+
+2. Is a blank line needed before a block quote or heading?
+ Most implementations do not require the blank line. However,
+ this can lead to unexpected results in hard-wrapped text, and
+ also to ambiguities in parsing (note that some implementations
+ put the heading inside the blockquote, while others do not).
+ (John Gruber has also spoken [in favor of requiring the blank
+ lines](https://web.archive.org/web/20170611172104/http://article.gmane.org/gmane.text.markdown.general/2146).)
+
+3. Is a blank line needed before an indented code block?
+ (`Markdown.pl` requires it, but this is not mentioned in the
+ documentation, and some implementations do not require it.)
+
+ ``` markdown
+ paragraph
+ code?
+ ```
+
+4. What is the exact rule for determining when list items get
+ wrapped in `<p>` tags? Can a list be partially "loose" and partially
+ "tight"? What should we do with a list like this?
+
+ ``` markdown
+ 1. one
+
+ 2. two
+ 3. three
+ ```
+
+ Or this?
+
+ ``` markdown
+ 1. one
+ - a
+
+ - b
+ 2. two
+ ```
+
+ (There are some relevant comments by John Gruber
+ [here](https://web.archive.org/web/20170611172104/http://article.gmane.org/gmane.text.markdown.general/2554).)
+
+5. Can list markers be indented? Can ordered list markers be right-aligned?
+
+ ``` markdown
+ 8. item 1
+ 9. item 2
+ 10. item 2a
+ ```
+
+6. Is this one list with a thematic break in its second item,
+ or two lists separated by a thematic break?
+
+ ``` markdown
+ * a
+ * * * * *
+ * b
+ ```
+
+7. When list markers change from numbers to bullets, do we have
+ two lists or one? (The Markdown syntax description suggests two,
+ but the perl scripts and many other implementations produce one.)
+
+ ``` markdown
+ 1. fee
+ 2. fie
+ - foe
+ - fum
+ ```
+
+8. What are the precedence rules for the markers of inline structure?
+ For example, is the following a valid link, or does the code span
+ take precedence ?
+
+ ``` markdown
+ [a backtick (`)](/url) and [another backtick (`)](/url).
+ ```
+
+9. What are the precedence rules for markers of emphasis and strong
+ emphasis? For example, how should the following be parsed?
+
+ ``` markdown
+ *foo *bar* baz*
+ ```
+
+10. What are the precedence rules between block-level and inline-level
+ structure? For example, how should the following be parsed?
+
+ ``` markdown
+ - `a long code span can contain a hyphen like this
+ - and it can screw things up`
+ ```
+
+11. Can list items include section headings? (`Markdown.pl` does not
+ allow this, but does allow blockquotes to include headings.)
+
+ ``` markdown
+ - # Heading
+ ```
+
+12. Can list items be empty?
+
+ ``` markdown
+ * a
+ *
+ * b
+ ```
+
+13. Can link references be defined inside block quotes or list items?
+
+ ``` markdown
+ > Blockquote [foo].
+ >
+ > [foo]: /url
+ ```
+
+14. If there are multiple definitions for the same reference, which takes
+ precedence?
+
+ ``` markdown
+ [foo]: /url1
+ [foo]: /url2
+
+ [foo][]
+ ```
+
+In the absence of a spec, early implementers consulted `Markdown.pl`
+to resolve these ambiguities. But `Markdown.pl` was quite buggy, and
+gave manifestly bad results in many cases, so it was not a
+satisfactory replacement for a spec.
+
+Because there is no unambiguous spec, implementations have diverged
+considerably. As a result, users are often surprised to find that
+a document that renders one way on one system (say, a GitHub wiki)
+renders differently on another (say, converting to docbook using
+pandoc). To make matters worse, because nothing in Markdown counts
+as a "syntax error," the divergence often isn't discovered right away.
+
+## About this document
+
+This document attempts to specify Markdown syntax unambiguously.
+It contains many examples with side-by-side Markdown and
+HTML. These are intended to double as conformance tests. An
+accompanying script `spec_tests.py` can be used to run the tests
+against any Markdown program:
+
+ python test/spec_tests.py --spec spec.txt --program PROGRAM
+
+Since this document describes how Markdown is to be parsed into
+an abstract syntax tree, it would have made sense to use an abstract
+representation of the syntax tree instead of HTML. But HTML is capable
+of representing the structural distinctions we need to make, and the
+choice of HTML for the tests makes it possible to run the tests against
+an implementation without writing an abstract syntax tree renderer.
+
+This document is generated from a text file, `spec.txt`, written
+in Markdown with a small extension for the side-by-side tests.
+The script `tools/makespec.py` can be used to convert `spec.txt` into
+HTML or CommonMark (which can then be converted into other formats).
+
+In the examples, the `→` character is used to represent tabs.
+
+# Preliminaries
+
+## Characters and lines
+
+Any sequence of [characters] is a valid CommonMark
+document.
+
+A [character](@) is a Unicode code point. Although some
+code points (for example, combining accents) do not correspond to
+characters in an intuitive sense, all code points count as characters
+for purposes of this spec.
+
+This spec does not specify an encoding; it thinks of lines as composed
+of [characters] rather than bytes. A conforming parser may be limited
+to a certain encoding.
+
+A [line](@) is a sequence of zero or more [characters]
+other than newline (`U+000A`) or carriage return (`U+000D`),
+followed by a [line ending] or by the end of file.
+
+A [line ending](@) is a newline (`U+000A`), a carriage return
+(`U+000D`) not followed by a newline, or a carriage return and a
+following newline.
+
+A line containing no characters, or a line containing only spaces
+(`U+0020`) or tabs (`U+0009`), is called a [blank line](@).
+
+The following definitions of character classes will be used in this spec:
+
+A [whitespace character](@) is a space
+(`U+0020`), tab (`U+0009`), newline (`U+000A`), line tabulation (`U+000B`),
+form feed (`U+000C`), or carriage return (`U+000D`).
+
+[Whitespace](@) is a sequence of one or more [whitespace
+characters].
+
+A [Unicode whitespace character](@) is
+any code point in the Unicode `Zs` general category, or a tab (`U+0009`),
+carriage return (`U+000D`), newline (`U+000A`), or form feed
+(`U+000C`).
+
+[Unicode whitespace](@) is a sequence of one
+or more [Unicode whitespace characters].
+
+A [space](@) is `U+0020`.
+
+A [non-whitespace character](@) is any character
+that is not a [whitespace character].
+
+An [ASCII punctuation character](@)
+is `!`, `"`, `#`, `$`, `%`, `&`, `'`, `(`, `)`,
+`*`, `+`, `,`, `-`, `.`, `/` (U+0021–2F),
+`:`, `;`, `<`, `=`, `>`, `?`, `@` (U+003A–0040),
+`[`, `\`, `]`, `^`, `_`, `` ` `` (U+005B–0060),
+`{`, `|`, `}`, or `~` (U+007B–007E).
+
+A [punctuation character](@) is an [ASCII
+punctuation character] or anything in
+the general Unicode categories `Pc`, `Pd`, `Pe`, `Pf`, `Pi`, `Po`, or `Ps`.
+
+## Tabs
+
+Tabs in lines are not expanded to [spaces]. However,
+in contexts where whitespace helps to define block structure,
+tabs behave as if they were replaced by spaces with a tab stop
+of 4 characters.
+
+Thus, for example, a tab can be used instead of four spaces
+in an indented code block. (Note, however, that internal
+tabs are passed through as literal tabs, not expanded to
+spaces.)
+
+```````````````````````````````` example
+→foo→baz→→bim
+.
+<pre><code>foo→baz→→bim
+</code></pre>
+````````````````````````````````
+
+```````````````````````````````` example
+ →foo→baz→→bim
+.
+<pre><code>foo→baz→→bim
+</code></pre>
+````````````````````````````````
+
+```````````````````````````````` example
+ a→a
+ ὐ→a
+.
+<pre><code>a→a
+ὐ→a
+</code></pre>
+````````````````````````````````
+
+In the following example, a continuation paragraph of a list
+item is indented with a tab; this has exactly the same effect
+as indentation with four spaces would:
+
+```````````````````````````````` example
+ - foo
+
+→bar
+.
+<ul>
+<li>
+<p>foo</p>
+<p>bar</p>
+</li>
+</ul>
+````````````````````````````````
+
+```````````````````````````````` example
+- foo
+
+→→bar
+.
+<ul>
+<li>
+<p>foo</p>
+<pre><code> bar
+</code></pre>
+</li>
+</ul>
+````````````````````````````````
+
+Normally the `>` that begins a block quote may be followed
+optionally by a space, which is not considered part of the
+content. In the following case `>` is followed by a tab,
+which is treated as if it were expanded into three spaces.
+Since one of these spaces is considered part of the
+delimiter, `foo` is considered to be indented six spaces
+inside the block quote context, so we get an indented
+code block starting with two spaces.
+
+```````````````````````````````` example
+>→→foo
+.
+<blockquote>
+<pre><code> foo
+</code></pre>
+</blockquote>
+````````````````````````````````
+
+```````````````````````````````` example
+-→→foo
+.
+<ul>
+<li>
+<pre><code> foo
+</code></pre>
+</li>
+</ul>
+````````````````````````````````
+
+
+```````````````````````````````` example
+ foo
+→bar
+.
+<pre><code>foo
+bar
+</code></pre>
+````````````````````````````````
+
+```````````````````````````````` example
+ - foo
+ - bar
+→ - baz
+.
+<ul>
+<li>foo
+<ul>
+<li>bar
+<ul>
+<li>baz</li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+````````````````````````````````
+
+```````````````````````````````` example
+#→Foo
+.
+<h1>Foo</h1>
+````````````````````````````````
+
+```````````````````````````````` example
+*→*→*→
+.
+<hr />
+````````````````````````````````
+
+
+## Insecure characters
+
+For security reasons, the Unicode character `U+0000` must be replaced
+with the REPLACEMENT CHARACTER (`U+FFFD`).
+
+# Blocks and inlines
+
+We can think of a document as a sequence of
+[blocks](@)---structural elements like paragraphs, block
+quotations, lists, headings, rules, and code blocks. Some blocks (like
+block quotes and list items) contain other blocks; others (like
+headings and paragraphs) contain [inline](@) content---text,
+links, emphasized text, images, code spans, and so on.
+
+## Precedence
+
+Indicators of block structure always take precedence over indicators
+of inline structure. So, for example, the following is a list with
+two items, not a list with one item containing a code span:
+
+```````````````````````````````` example
+- `one
+- two`
+.
+<ul>
+<li>`one</li>
+<li>two`</li>
+</ul>
+````````````````````````````````
+
+
+This means that parsing can proceed in two steps: first, the block
+structure of the document can be discerned; second, text lines inside
+paragraphs, headings, and other block constructs can be parsed for inline
+structure. The second step requires information about link reference
+definitions that will be available only at the end of the first
+step. Note that the first step requires processing lines in sequence,
+but the second can be parallelized, since the inline parsing of
+one block element does not affect the inline parsing of any other.
+
+## Container blocks and leaf blocks
+
+We can divide blocks into two types:
+[container blocks](@),
+which can contain other blocks, and [leaf blocks](@),
+which cannot.
+
+# Leaf blocks
+
+This section describes the different kinds of leaf block that make up a
+Markdown document.
+
+## Thematic breaks
+
+A line consisting of 0-3 spaces of indentation, followed by a sequence
+of three or more matching `-`, `_`, or `*` characters, each followed
+optionally by any number of spaces or tabs, forms a
+[thematic break](@).
+
+```````````````````````````````` example
+***
+---
+___
+.
+<hr />
+<hr />
+<hr />
+````````````````````````````````
+
+
+Wrong characters:
+
+```````````````````````````````` example
++++
+.
+<p>+++</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+===
+.
+<p>===</p>
+````````````````````````````````
+
+
+Not enough characters:
+
+```````````````````````````````` example
+--
+**
+__
+.
+<p>--
+**
+__</p>
+````````````````````````````````
+
+
+One to three spaces indent are allowed:
+
+```````````````````````````````` example
+ ***
+ ***
+ ***
+.
+<hr />
+<hr />
+<hr />
+````````````````````````````````
+
+
+Four spaces is too many:
+
+```````````````````````````````` example
+ ***
+.
+<pre><code>***
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+Foo
+ ***
+.
+<p>Foo
+***</p>
+````````````````````````````````
+
+
+More than three characters may be used:
+
+```````````````````````````````` example
+_____________________________________
+.
+<hr />
+````````````````````````````````
+
+
+Spaces are allowed between the characters:
+
+```````````````````````````````` example
+ - - -
+.
+<hr />
+````````````````````````````````
+
+
+```````````````````````````````` example
+ ** * ** * ** * **
+.
+<hr />
+````````````````````````````````
+
+
+```````````````````````````````` example
+- - - -
+.
+<hr />
+````````````````````````````````
+
+
+Spaces are allowed at the end:
+
+```````````````````````````````` example
+- - - -
+.
+<hr />
+````````````````````````````````
+
+
+However, no other characters may occur in the line:
+
+```````````````````````````````` example
+_ _ _ _ a
+
+a------
+
+---a---
+.
+<p>_ _ _ _ a</p>
+<p>a------</p>
+<p>---a---</p>
+````````````````````````````````
+
+
+It is required that all of the [non-whitespace characters] be the same.
+So, this is not a thematic break:
+
+```````````````````````````````` example
+ *-*
+.
+<p><em>-</em></p>
+````````````````````````````````
+
+
+Thematic breaks do not need blank lines before or after:
+
+```````````````````````````````` example
+- foo
+***
+- bar
+.
+<ul>
+<li>foo</li>
+</ul>
+<hr />
+<ul>
+<li>bar</li>
+</ul>
+````````````````````````````````
+
+
+Thematic breaks can interrupt a paragraph:
+
+```````````````````````````````` example
+Foo
+***
+bar
+.
+<p>Foo</p>
+<hr />
+<p>bar</p>
+````````````````````````````````
+
+
+If a line of dashes that meets the above conditions for being a
+thematic break could also be interpreted as the underline of a [setext
+heading], the interpretation as a
+[setext heading] takes precedence. Thus, for example,
+this is a setext heading, not a paragraph followed by a thematic break:
+
+```````````````````````````````` example
+Foo
+---
+bar
+.
+<h2>Foo</h2>
+<p>bar</p>
+````````````````````````````````
+
+
+When both a thematic break and a list item are possible
+interpretations of a line, the thematic break takes precedence:
+
+```````````````````````````````` example
+* Foo
+* * *
+* Bar
+.
+<ul>
+<li>Foo</li>
+</ul>
+<hr />
+<ul>
+<li>Bar</li>
+</ul>
+````````````````````````````````
+
+
+If you want a thematic break in a list item, use a different bullet:
+
+```````````````````````````````` example
+- Foo
+- * * *
+.
+<ul>
+<li>Foo</li>
+<li>
+<hr />
+</li>
+</ul>
+````````````````````````````````
+
+
+## ATX headings
+
+An [ATX heading](@)
+consists of a string of characters, parsed as inline content, between an
+opening sequence of 1--6 unescaped `#` characters and an optional
+closing sequence of any number of unescaped `#` characters.
+The opening sequence of `#` characters must be followed by a
+[space] or by the end of line. The optional closing sequence of `#`s must be
+preceded by a [space] and may be followed by spaces only. The opening
+`#` character may be indented 0-3 spaces. The raw contents of the
+heading are stripped of leading and trailing spaces before being parsed
+as inline content. The heading level is equal to the number of `#`
+characters in the opening sequence.
+
+Simple headings:
+
+```````````````````````````````` example
+# foo
+## foo
+### foo
+#### foo
+##### foo
+###### foo
+.
+<h1>foo</h1>
+<h2>foo</h2>
+<h3>foo</h3>
+<h4>foo</h4>
+<h5>foo</h5>
+<h6>foo</h6>
+````````````````````````````````
+
+
+More than six `#` characters is not a heading:
+
+```````````````````````````````` example
+####### foo
+.
+<p>####### foo</p>
+````````````````````````````````
+
+
+At least one space is required between the `#` characters and the
+heading's contents, unless the heading is empty. Note that many
+implementations currently do not require the space. However, the
+space was required by the
+[original ATX implementation](http://www.aaronsw.com/2002/atx/atx.py),
+and it helps prevent things like the following from being parsed as
+headings:
+
+```````````````````````````````` example
+#5 bolt
+
+#hashtag
+.
+<p>#5 bolt</p>
+<p>#hashtag</p>
+````````````````````````````````
+
+
+This is not a heading, because the first `#` is escaped:
+
+```````````````````````````````` example
+\## foo
+.
+<p>## foo</p>
+````````````````````````````````
+
+
+Contents are parsed as inlines:
+
+```````````````````````````````` example
+# foo *bar* \*baz\*
+.
+<h1>foo <em>bar</em> *baz*</h1>
+````````````````````````````````
+
+
+Leading and trailing [whitespace] is ignored in parsing inline content:
+
+```````````````````````````````` example
+# foo
+.
+<h1>foo</h1>
+````````````````````````````````
+
+
+One to three spaces indentation are allowed:
+
+```````````````````````````````` example
+ ### foo
+ ## foo
+ # foo
+.
+<h3>foo</h3>
+<h2>foo</h2>
+<h1>foo</h1>
+````````````````````````````````
+
+
+Four spaces are too much:
+
+```````````````````````````````` example
+ # foo
+.
+<pre><code># foo
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo
+ # bar
+.
+<p>foo
+# bar</p>
+````````````````````````````````
+
+
+A closing sequence of `#` characters is optional:
+
+```````````````````````````````` example
+## foo ##
+ ### bar ###
+.
+<h2>foo</h2>
+<h3>bar</h3>
+````````````````````````````````
+
+
+It need not be the same length as the opening sequence:
+
+```````````````````````````````` example
+# foo ##################################
+##### foo ##
+.
+<h1>foo</h1>
+<h5>foo</h5>
+````````````````````````````````
+
+
+Spaces are allowed after the closing sequence:
+
+```````````````````````````````` example
+### foo ###
+.
+<h3>foo</h3>
+````````````````````````````````
+
+
+A sequence of `#` characters with anything but [spaces] following it
+is not a closing sequence, but counts as part of the contents of the
+heading:
+
+```````````````````````````````` example
+### foo ### b
+.
+<h3>foo ### b</h3>
+````````````````````````````````
+
+
+The closing sequence must be preceded by a space:
+
+```````````````````````````````` example
+# foo#
+.
+<h1>foo#</h1>
+````````````````````````````````
+
+
+Backslash-escaped `#` characters do not count as part
+of the closing sequence:
+
+```````````````````````````````` example
+### foo \###
+## foo #\##
+# foo \#
+.
+<h3>foo ###</h3>
+<h2>foo ###</h2>
+<h1>foo #</h1>
+````````````````````````````````
+
+
+ATX headings need not be separated from surrounding content by blank
+lines, and they can interrupt paragraphs:
+
+```````````````````````````````` example
+****
+## foo
+****
+.
+<hr />
+<h2>foo</h2>
+<hr />
+````````````````````````````````
+
+
+```````````````````````````````` example
+Foo bar
+# baz
+Bar foo
+.
+<p>Foo bar</p>
+<h1>baz</h1>
+<p>Bar foo</p>
+````````````````````````````````
+
+
+ATX headings can be empty:
+
+```````````````````````````````` example
+##
+#
+### ###
+.
+<h2></h2>
+<h1></h1>
+<h3></h3>
+````````````````````````````````
+
+
+## Setext headings
+
+A [setext heading](@) consists of one or more
+lines of text, each containing at least one [non-whitespace
+character], with no more than 3 spaces indentation, followed by
+a [setext heading underline]. The lines of text must be such
+that, were they not followed by the setext heading underline,
+they would be interpreted as a paragraph: they cannot be
+interpretable as a [code fence], [ATX heading][ATX headings],
+[block quote][block quotes], [thematic break][thematic breaks],
+[list item][list items], or [HTML block][HTML blocks].
+
+A [setext heading underline](@) is a sequence of
+`=` characters or a sequence of `-` characters, with no more than 3
+spaces of indentation and any number of trailing spaces or tabs.
+
+The heading is a level 1 heading if `=` characters are used in
+the [setext heading underline], and a level 2 heading if `-`
+characters are used. The contents of the heading are the result
+of parsing the preceding lines of text as CommonMark inline
+content.
+
+In general, a setext heading need not be preceded or followed by a
+blank line. However, it cannot interrupt a paragraph, so when a
+setext heading comes after a paragraph, a blank line is needed between
+them.
+
+Simple examples:
+
+```````````````````````````````` example
+Foo *bar*
+=========
+
+Foo *bar*
+---------
+.
+<h1>Foo <em>bar</em></h1>
+<h2>Foo <em>bar</em></h2>
+````````````````````````````````
+
+
+The content of the header may span more than one line:
+
+```````````````````````````````` example
+Foo *bar
+baz*
+====
+.
+<h1>Foo <em>bar
+baz</em></h1>
+````````````````````````````````
+
+The contents are the result of parsing the headings's raw
+content as inlines. The heading's raw content is formed by
+concatenating the lines and removing initial and final
+[whitespace].
+
+```````````````````````````````` example
+ Foo *bar
+baz*→
+====
+.
+<h1>Foo <em>bar
+baz</em></h1>
+````````````````````````````````
+
+
+The underlining can be any length:
+
+```````````````````````````````` example
+Foo
+-------------------------
+
+Foo
+=
+.
+<h2>Foo</h2>
+<h1>Foo</h1>
+````````````````````````````````
+
+
+The heading content can be indented up to three spaces, and need
+not line up with the underlining:
+
+```````````````````````````````` example
+ Foo
+---
+
+ Foo
+-----
+
+ Foo
+ ===
+.
+<h2>Foo</h2>
+<h2>Foo</h2>
+<h1>Foo</h1>
+````````````````````````````````
+
+
+Four spaces indent is too much:
+
+```````````````````````````````` example
+ Foo
+ ---
+
+ Foo
+---
+.
+<pre><code>Foo
+---
+
+Foo
+</code></pre>
+<hr />
+````````````````````````````````
+
+
+The setext heading underline can be indented up to three spaces, and
+may have trailing spaces:
+
+```````````````````````````````` example
+Foo
+ ----
+.
+<h2>Foo</h2>
+````````````````````````````````
+
+
+Four spaces is too much:
+
+```````````````````````````````` example
+Foo
+ ---
+.
+<p>Foo
+---</p>
+````````````````````````````````
+
+
+The setext heading underline cannot contain internal spaces:
+
+```````````````````````````````` example
+Foo
+= =
+
+Foo
+--- -
+.
+<p>Foo
+= =</p>
+<p>Foo</p>
+<hr />
+````````````````````````````````
+
+
+Trailing spaces in the content line do not cause a line break:
+
+```````````````````````````````` example
+Foo
+-----
+.
+<h2>Foo</h2>
+````````````````````````````````
+
+
+Nor does a backslash at the end:
+
+```````````````````````````````` example
+Foo\
+----
+.
+<h2>Foo\</h2>
+````````````````````````````````
+
+
+Since indicators of block structure take precedence over
+indicators of inline structure, the following are setext headings:
+
+```````````````````````````````` example
+`Foo
+----
+`
+
+<a title="a lot
+---
+of dashes"/>
+.
+<h2>`Foo</h2>
+<p>`</p>
+<h2><a title="a lot</h2>
+<p>of dashes"/></p>
+````````````````````````````````
+
+
+The setext heading underline cannot be a [lazy continuation
+line] in a list item or block quote:
+
+```````````````````````````````` example
+> Foo
+---
+.
+<blockquote>
+<p>Foo</p>
+</blockquote>
+<hr />
+````````````````````````````````
+
+
+```````````````````````````````` example
+> foo
+bar
+===
+.
+<blockquote>
+<p>foo
+bar
+===</p>
+</blockquote>
+````````````````````````````````
+
+
+```````````````````````````````` example
+- Foo
+---
+.
+<ul>
+<li>Foo</li>
+</ul>
+<hr />
+````````````````````````````````
+
+
+A blank line is needed between a paragraph and a following
+setext heading, since otherwise the paragraph becomes part
+of the heading's content:
+
+```````````````````````````````` example
+Foo
+Bar
+---
+.
+<h2>Foo
+Bar</h2>
+````````````````````````````````
+
+
+But in general a blank line is not required before or after
+setext headings:
+
+```````````````````````````````` example
+---
+Foo
+---
+Bar
+---
+Baz
+.
+<hr />
+<h2>Foo</h2>
+<h2>Bar</h2>
+<p>Baz</p>
+````````````````````````````````
+
+
+Setext headings cannot be empty:
+
+```````````````````````````````` example
+
+====
+.
+<p>====</p>
+````````````````````````````````
+
+
+Setext heading text lines must not be interpretable as block
+constructs other than paragraphs. So, the line of dashes
+in these examples gets interpreted as a thematic break:
+
+```````````````````````````````` example
+---
+---
+.
+<hr />
+<hr />
+````````````````````````````````
+
+
+```````````````````````````````` example
+- foo
+-----
+.
+<ul>
+<li>foo</li>
+</ul>
+<hr />
+````````````````````````````````
+
+
+```````````````````````````````` example
+ foo
+---
+.
+<pre><code>foo
+</code></pre>
+<hr />
+````````````````````````````````
+
+
+```````````````````````````````` example
+> foo
+-----
+.
+<blockquote>
+<p>foo</p>
+</blockquote>
+<hr />
+````````````````````````````````
+
+
+If you want a heading with `> foo` as its literal text, you can
+use backslash escapes:
+
+```````````````````````````````` example
+\> foo
+------
+.
+<h2>> foo</h2>
+````````````````````````````````
+
+
+**Compatibility note:** Most existing Markdown implementations
+do not allow the text of setext headings to span multiple lines.
+But there is no consensus about how to interpret
+
+``` markdown
+Foo
+bar
+---
+baz
+```
+
+One can find four different interpretations:
+
+1. paragraph "Foo", heading "bar", paragraph "baz"
+2. paragraph "Foo bar", thematic break, paragraph "baz"
+3. paragraph "Foo bar --- baz"
+4. heading "Foo bar", paragraph "baz"
+
+We find interpretation 4 most natural, and interpretation 4
+increases the expressive power of CommonMark, by allowing
+multiline headings. Authors who want interpretation 1 can
+put a blank line after the first paragraph:
+
+```````````````````````````````` example
+Foo
+
+bar
+---
+baz
+.
+<p>Foo</p>
+<h2>bar</h2>
+<p>baz</p>
+````````````````````````````````
+
+
+Authors who want interpretation 2 can put blank lines around
+the thematic break,
+
+```````````````````````````````` example
+Foo
+bar
+
+---
+
+baz
+.
+<p>Foo
+bar</p>
+<hr />
+<p>baz</p>
+````````````````````````````````
+
+
+or use a thematic break that cannot count as a [setext heading
+underline], such as
+
+```````````````````````````````` example
+Foo
+bar
+* * *
+baz
+.
+<p>Foo
+bar</p>
+<hr />
+<p>baz</p>
+````````````````````````````````
+
+
+Authors who want interpretation 3 can use backslash escapes:
+
+```````````````````````````````` example
+Foo
+bar
+\---
+baz
+.
+<p>Foo
+bar
+---
+baz</p>
+````````````````````````````````
+
+
+## Indented code blocks
+
+An [indented code block](@) is composed of one or more
+[indented chunks] separated by blank lines.
+An [indented chunk](@) is a sequence of non-blank lines,
+each indented four or more spaces. The contents of the code block are
+the literal contents of the lines, including trailing
+[line endings], minus four spaces of indentation.
+An indented code block has no [info string].
+
+An indented code block cannot interrupt a paragraph, so there must be
+a blank line between a paragraph and a following indented code block.
+(A blank line is not needed, however, between a code block and a following
+paragraph.)
+
+```````````````````````````````` example
+ a simple
+ indented code block
+.
+<pre><code>a simple
+ indented code block
+</code></pre>
+````````````````````````````````
+
+
+If there is any ambiguity between an interpretation of indentation
+as a code block and as indicating that material belongs to a [list
+item][list items], the list item interpretation takes precedence:
+
+```````````````````````````````` example
+ - foo
+
+ bar
+.
+<ul>
+<li>
+<p>foo</p>
+<p>bar</p>
+</li>
+</ul>
+````````````````````````````````
+
+
+```````````````````````````````` example
+1. foo
+
+ - bar
+.
+<ol>
+<li>
+<p>foo</p>
+<ul>
+<li>bar</li>
+</ul>
+</li>
+</ol>
+````````````````````````````````
+
+
+
+The contents of a code block are literal text, and do not get parsed
+as Markdown:
+
+```````````````````````````````` example
+ <a/>
+ *hi*
+
+ - one
+.
+<pre><code><a/>
+*hi*
+
+- one
+</code></pre>
+````````````````````````````````
+
+
+Here we have three chunks separated by blank lines:
+
+```````````````````````````````` example
+ chunk1
+
+ chunk2
+
+
+
+ chunk3
+.
+<pre><code>chunk1
+
+chunk2
+
+
+
+chunk3
+</code></pre>
+````````````````````````````````
+
+
+Any initial spaces beyond four will be included in the content, even
+in interior blank lines:
+
+```````````````````````````````` example
+ chunk1
+
+ chunk2
+.
+<pre><code>chunk1
+
+ chunk2
+</code></pre>
+````````````````````````````````
+
+
+An indented code block cannot interrupt a paragraph. (This
+allows hanging indents and the like.)
+
+```````````````````````````````` example
+Foo
+ bar
+
+.
+<p>Foo
+bar</p>
+````````````````````````````````
+
+
+However, any non-blank line with fewer than four leading spaces ends
+the code block immediately. So a paragraph may occur immediately
+after indented code:
+
+```````````````````````````````` example
+ foo
+bar
+.
+<pre><code>foo
+</code></pre>
+<p>bar</p>
+````````````````````````````````
+
+
+And indented code can occur immediately before and after other kinds of
+blocks:
+
+```````````````````````````````` example
+# Heading
+ foo
+Heading
+------
+ foo
+----
+.
+<h1>Heading</h1>
+<pre><code>foo
+</code></pre>
+<h2>Heading</h2>
+<pre><code>foo
+</code></pre>
+<hr />
+````````````````````````````````
+
+
+The first line can be indented more than four spaces:
+
+```````````````````````````````` example
+ foo
+ bar
+.
+<pre><code> foo
+bar
+</code></pre>
+````````````````````````````````
+
+
+Blank lines preceding or following an indented code block
+are not included in it:
+
+```````````````````````````````` example
+
+
+ foo
+
+
+.
+<pre><code>foo
+</code></pre>
+````````````````````````````````
+
+
+Trailing spaces are included in the code block's content:
+
+```````````````````````````````` example
+ foo
+.
+<pre><code>foo
+</code></pre>
+````````````````````````````````
+
+
+
+## Fenced code blocks
+
+A [code fence](@) is a sequence
+of at least three consecutive backtick characters (`` ` ``) or
+tildes (`~`). (Tildes and backticks cannot be mixed.)
+A [fenced code block](@)
+begins with a code fence, indented no more than three spaces.
+
+The line with the opening code fence may optionally contain some text
+following the code fence; this is trimmed of leading and trailing
+whitespace and called the [info string](@). If the [info string] comes
+after a backtick fence, it may not contain any backtick
+characters. (The reason for this restriction is that otherwise
+some inline code would be incorrectly interpreted as the
+beginning of a fenced code block.)
+
+The content of the code block consists of all subsequent lines, until
+a closing [code fence] of the same type as the code block
+began with (backticks or tildes), and with at least as many backticks
+or tildes as the opening code fence. If the leading code fence is
+indented N spaces, then up to N spaces of indentation are removed from
+each line of the content (if present). (If a content line is not
+indented, it is preserved unchanged. If it is indented less than N
+spaces, all of the indentation is removed.)
+
+The closing code fence may be indented up to three spaces, and may be
+followed only by spaces, which are ignored. If the end of the
+containing block (or document) is reached and no closing code fence
+has been found, the code block contains all of the lines after the
+opening code fence until the end of the containing block (or
+document). (An alternative spec would require backtracking in the
+event that a closing code fence is not found. But this makes parsing
+much less efficient, and there seems to be no real downside to the
+behavior described here.)
+
+A fenced code block may interrupt a paragraph, and does not require
+a blank line either before or after.
+
+The content of a code fence is treated as literal text, not parsed
+as inlines. The first word of the [info string] is typically used to
+specify the language of the code sample, and rendered in the `class`
+attribute of the `code` tag. However, this spec does not mandate any
+particular treatment of the [info string].
+
+Here is a simple example with backticks:
+
+```````````````````````````````` example
+```
+<
+ >
+```
+.
+<pre><code><
+ >
+</code></pre>
+````````````````````````````````
+
+
+With tildes:
+
+```````````````````````````````` example
+~~~
+<
+ >
+~~~
+.
+<pre><code><
+ >
+</code></pre>
+````````````````````````````````
+
+Fewer than three backticks is not enough:
+
+```````````````````````````````` example
+``
+foo
+``
+.
+<p><code>foo</code></p>
+````````````````````````````````
+
+The closing code fence must use the same character as the opening
+fence:
+
+```````````````````````````````` example
+```
+aaa
+~~~
+```
+.
+<pre><code>aaa
+~~~
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+~~~
+aaa
+```
+~~~
+.
+<pre><code>aaa
+```
+</code></pre>
+````````````````````````````````
+
+
+The closing code fence must be at least as long as the opening fence:
+
+```````````````````````````````` example
+````
+aaa
+```
+``````
+.
+<pre><code>aaa
+```
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+~~~~
+aaa
+~~~
+~~~~
+.
+<pre><code>aaa
+~~~
+</code></pre>
+````````````````````````````````
+
+
+Unclosed code blocks are closed by the end of the document
+(or the enclosing [block quote][block quotes] or [list item][list items]):
+
+```````````````````````````````` example
+```
+.
+<pre><code></code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+`````
+
+```
+aaa
+.
+<pre><code>
+```
+aaa
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+> ```
+> aaa
+
+bbb
+.
+<blockquote>
+<pre><code>aaa
+</code></pre>
+</blockquote>
+<p>bbb</p>
+````````````````````````````````
+
+
+A code block can have all empty lines as its content:
+
+```````````````````````````````` example
+```
+
+
+```
+.
+<pre><code>
+
+</code></pre>
+````````````````````````````````
+
+
+A code block can be empty:
+
+```````````````````````````````` example
+```
+```
+.
+<pre><code></code></pre>
+````````````````````````````````
+
+
+Fences can be indented. If the opening fence is indented,
+content lines will have equivalent opening indentation removed,
+if present:
+
+```````````````````````````````` example
+ ```
+ aaa
+aaa
+```
+.
+<pre><code>aaa
+aaa
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+ ```
+aaa
+ aaa
+aaa
+ ```
+.
+<pre><code>aaa
+aaa
+aaa
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+ ```
+ aaa
+ aaa
+ aaa
+ ```
+.
+<pre><code>aaa
+ aaa
+aaa
+</code></pre>
+````````````````````````````````
+
+
+Four spaces indentation produces an indented code block:
+
+```````````````````````````````` example
+ ```
+ aaa
+ ```
+.
+<pre><code>```
+aaa
+```
+</code></pre>
+````````````````````````````````
+
+
+Closing fences may be indented by 0-3 spaces, and their indentation
+need not match that of the opening fence:
+
+```````````````````````````````` example
+```
+aaa
+ ```
+.
+<pre><code>aaa
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+ ```
+aaa
+ ```
+.
+<pre><code>aaa
+</code></pre>
+````````````````````````````````
+
+
+This is not a closing fence, because it is indented 4 spaces:
+
+```````````````````````````````` example
+```
+aaa
+ ```
+.
+<pre><code>aaa
+ ```
+</code></pre>
+````````````````````````````````
+
+
+
+Code fences (opening and closing) cannot contain internal spaces:
+
+```````````````````````````````` example
+``` ```
+aaa
+.
+<p><code> </code>
+aaa</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+~~~~~~
+aaa
+~~~ ~~
+.
+<pre><code>aaa
+~~~ ~~
+</code></pre>
+````````````````````````````````
+
+
+Fenced code blocks can interrupt paragraphs, and can be followed
+directly by paragraphs, without a blank line between:
+
+```````````````````````````````` example
+foo
+```
+bar
+```
+baz
+.
+<p>foo</p>
+<pre><code>bar
+</code></pre>
+<p>baz</p>
+````````````````````````````````
+
+
+Other blocks can also occur before and after fenced code blocks
+without an intervening blank line:
+
+```````````````````````````````` example
+foo
+---
+~~~
+bar
+~~~
+# baz
+.
+<h2>foo</h2>
+<pre><code>bar
+</code></pre>
+<h1>baz</h1>
+````````````````````````````````
+
+
+An [info string] can be provided after the opening code fence.
+Although this spec doesn't mandate any particular treatment of
+the info string, the first word is typically used to specify
+the language of the code block. In HTML output, the language is
+normally indicated by adding a class to the `code` element consisting
+of `language-` followed by the language name.
+
+```````````````````````````````` example
+```ruby
+def foo(x)
+ return 3
+end
+```
+.
+<pre><code class="language-ruby">def foo(x)
+ return 3
+end
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+~~~~ ruby startline=3 $%@#$
+def foo(x)
+ return 3
+end
+~~~~~~~
+.
+<pre><code class="language-ruby">def foo(x)
+ return 3
+end
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+````;
+````
+.
+<pre><code class="language-;"></code></pre>
+````````````````````````````````
+
+
+[Info strings] for backtick code blocks cannot contain backticks:
+
+```````````````````````````````` example
+``` aa ```
+foo
+.
+<p><code>aa</code>
+foo</p>
+````````````````````````````````
+
+
+[Info strings] for tilde code blocks can contain backticks and tildes:
+
+```````````````````````````````` example
+~~~ aa ``` ~~~
+foo
+~~~
+.
+<pre><code class="language-aa">foo
+</code></pre>
+````````````````````````````````
+
+
+Closing code fences cannot have [info strings]:
+
+```````````````````````````````` example
+```
+``` aaa
+```
+.
+<pre><code>``` aaa
+</code></pre>
+````````````````````````````````
+
+
+
+## HTML blocks
+
+An [HTML block](@) is a group of lines that is treated
+as raw HTML (and will not be escaped in HTML output).
+
+There are seven kinds of [HTML block], which can be defined by their
+start and end conditions. The block begins with a line that meets a
+[start condition](@) (after up to three spaces optional indentation).
+It ends with the first subsequent line that meets a matching [end
+condition](@), or the last line of the document, or the last line of
+the [container block](#container-blocks) containing the current HTML
+block, if no line is encountered that meets the [end condition]. If
+the first line meets both the [start condition] and the [end
+condition], the block will contain just that line.
+
+1. **Start condition:** line begins with the string `<script`,
+`<pre`, or `<style` (case-insensitive), followed by whitespace,
+the string `>`, or the end of the line.\
+**End condition:** line contains an end tag
+`</script>`, `</pre>`, or `</style>` (case-insensitive; it
+need not match the start tag).
+
+2. **Start condition:** line begins with the string `<!--`.\
+**End condition:** line contains the string `-->`.
+
+3. **Start condition:** line begins with the string `<?`.\
+**End condition:** line contains the string `?>`.
+
+4. **Start condition:** line begins with the string `<!`
+followed by an uppercase ASCII letter.\
+**End condition:** line contains the character `>`.
+
+5. **Start condition:** line begins with the string
+`<![CDATA[`.\
+**End condition:** line contains the string `]]]]><![CDATA[>`.
+
+6. **Start condition:** line begins with the string `<` or `</`
+followed by one of the strings (case-insensitive) `address`,
+`article`, `aside`, `base`, `basefont`, `blockquote`, `body`,
+`caption`, `center`, `col`, `colgroup`, `dd`, `details`, `dialog`,
+`dir`, `div`, `dl`, `dt`, `fieldset`, `figcaption`, `figure`,
+`footer`, `form`, `frame`, `frameset`,
+`h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `head`, `header`, `hr`,
+`html`, `iframe`, `legend`, `li`, `link`, `main`, `menu`, `menuitem`,
+`nav`, `noframes`, `ol`, `optgroup`, `option`, `p`, `param`,
+`section`, `summary`, `table`, `tbody`, `td`,
+`tfoot`, `th`, `thead`, `title`, `tr`, `track`, `ul`, followed
+by [whitespace], the end of the line, the string `>`, or
+the string `/>`.\
+**End condition:** line is followed by a [blank line].
+
+7. **Start condition:** line begins with a complete [open tag]
+(with any [tag name] other than `script`,
+`style`, or `pre`) or a complete [closing tag],
+followed only by [whitespace] or the end of the line.\
+**End condition:** line is followed by a [blank line].
+
+HTML blocks continue until they are closed by their appropriate
+[end condition], or the last line of the document or other [container
+block](#container-blocks). This means any HTML **within an HTML
+block** that might otherwise be recognised as a start condition will
+be ignored by the parser and passed through as-is, without changing
+the parser's state.
+
+For instance, `<pre>` within a HTML block started by `<table>` will not affect
+the parser state; as the HTML block was started in by start condition 6, it
+will end at any blank line. This can be surprising:
+
+```````````````````````````````` example
+<table><tr><td>
+<pre>
+**Hello**,
+
+_world_.
+</pre>
+</td></tr></table>
+.
+<table><tr><td>
+<pre>
+**Hello**,
+<p><em>world</em>.
+</pre></p>
+</td></tr></table>
+````````````````````````````````
+
+In this case, the HTML block is terminated by the newline — the `**Hello**`
+text remains verbatim — and regular parsing resumes, with a paragraph,
+emphasised `world` and inline and block HTML following.
+
+All types of [HTML blocks] except type 7 may interrupt
+a paragraph. Blocks of type 7 may not interrupt a paragraph.
+(This restriction is intended to prevent unwanted interpretation
+of long tags inside a wrapped paragraph as starting HTML blocks.)
+
+Some simple examples follow. Here are some basic HTML blocks
+of type 6:
+
+```````````````````````````````` example
+<table>
+ <tr>
+ <td>
+ hi
+ </td>
+ </tr>
+</table>
+
+okay.
+.
+<table>
+ <tr>
+ <td>
+ hi
+ </td>
+ </tr>
+</table>
+<p>okay.</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+ <div>
+ *hello*
+ <foo><a>
+.
+ <div>
+ *hello*
+ <foo><a>
+````````````````````````````````
+
+
+A block can also start with a closing tag:
+
+```````````````````````````````` example
+</div>
+*foo*
+.
+</div>
+*foo*
+````````````````````````````````
+
+
+Here we have two HTML blocks with a Markdown paragraph between them:
+
+```````````````````````````````` example
+<DIV CLASS="foo">
+
+*Markdown*
+
+</DIV>
+.
+<DIV CLASS="foo">
+<p><em>Markdown</em></p>
+</DIV>
+````````````````````````````````
+
+
+The tag on the first line can be partial, as long
+as it is split where there would be whitespace:
+
+```````````````````````````````` example
+<div id="foo"
+ class="bar">
+</div>
+.
+<div id="foo"
+ class="bar">
+</div>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<div id="foo" class="bar
+ baz">
+</div>
+.
+<div id="foo" class="bar
+ baz">
+</div>
+````````````````````````````````
+
+
+An open tag need not be closed:
+```````````````````````````````` example
+<div>
+*foo*
+
+*bar*
+.
+<div>
+*foo*
+<p><em>bar</em></p>
+````````````````````````````````
+
+
+
+A partial tag need not even be completed (garbage
+in, garbage out):
+
+```````````````````````````````` example
+<div id="foo"
+*hi*
+.
+<div id="foo"
+*hi*
+````````````````````````````````
+
+
+```````````````````````````````` example
+<div class
+foo
+.
+<div class
+foo
+````````````````````````````````
+
+
+The initial tag doesn't even need to be a valid
+tag, as long as it starts like one:
+
+```````````````````````````````` example
+<div *???-&&&-<---
+*foo*
+.
+<div *???-&&&-<---
+*foo*
+````````````````````````````````
+
+
+In type 6 blocks, the initial tag need not be on a line by
+itself:
+
+```````````````````````````````` example
+<div><a href="bar">*foo*</a></div>
+.
+<div><a href="bar">*foo*</a></div>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<table><tr><td>
+foo
+</td></tr></table>
+.
+<table><tr><td>
+foo
+</td></tr></table>
+````````````````````````````````
+
+
+Everything until the next blank line or end of document
+gets included in the HTML block. So, in the following
+example, what looks like a Markdown code block
+is actually part of the HTML block, which continues until a blank
+line or the end of the document is reached:
+
+```````````````````````````````` example
+<div></div>
+``` c
+int x = 33;
+```
+.
+<div></div>
+``` c
+int x = 33;
+```
+````````````````````````````````
+
+
+To start an [HTML block] with a tag that is *not* in the
+list of block-level tags in (6), you must put the tag by
+itself on the first line (and it must be complete):
+
+```````````````````````````````` example
+<a href="foo">
+*bar*
+</a>
+.
+<a href="foo">
+*bar*
+</a>
+````````````````````````````````
+
+
+In type 7 blocks, the [tag name] can be anything:
+
+```````````````````````````````` example
+<Warning>
+*bar*
+</Warning>
+.
+<Warning>
+*bar*
+</Warning>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<i class="foo">
+*bar*
+</i>
+.
+<i class="foo">
+*bar*
+</i>
+````````````````````````````````
+
+
+```````````````````````````````` example
+</ins>
+*bar*
+.
+</ins>
+*bar*
+````````````````````````````````
+
+
+These rules are designed to allow us to work with tags that
+can function as either block-level or inline-level tags.
+The `<del>` tag is a nice example. We can surround content with
+`<del>` tags in three different ways. In this case, we get a raw
+HTML block, because the `<del>` tag is on a line by itself:
+
+```````````````````````````````` example
+<del>
+*foo*
+</del>
+.
+<del>
+*foo*
+</del>
+````````````````````````````````
+
+
+In this case, we get a raw HTML block that just includes
+the `<del>` tag (because it ends with the following blank
+line). So the contents get interpreted as CommonMark:
+
+```````````````````````````````` example
+<del>
+
+*foo*
+
+</del>
+.
+<del>
+<p><em>foo</em></p>
+</del>
+````````````````````````````````
+
+
+Finally, in this case, the `<del>` tags are interpreted
+as [raw HTML] *inside* the CommonMark paragraph. (Because
+the tag is not on a line by itself, we get inline HTML
+rather than an [HTML block].)
+
+```````````````````````````````` example
+<del>*foo*</del>
+.
+<p><del><em>foo</em></del></p>
+````````````````````````````````
+
+
+HTML tags designed to contain literal content
+(`script`, `style`, `pre`), comments, processing instructions,
+and declarations are treated somewhat differently.
+Instead of ending at the first blank line, these blocks
+end at the first line containing a corresponding end tag.
+As a result, these blocks can contain blank lines:
+
+A pre tag (type 1):
+
+```````````````````````````````` example
+<pre language="haskell"><code>
+import Text.HTML.TagSoup
+
+main :: IO ()
+main = print $ parseTags tags
+</code></pre>
+okay
+.
+<pre language="haskell"><code>
+import Text.HTML.TagSoup
+
+main :: IO ()
+main = print $ parseTags tags
+</code></pre>
+<p>okay</p>
+````````````````````````````````
+
+
+A script tag (type 1):
+
+```````````````````````````````` example
+<script type="text/javascript">
+// JavaScript example
+
+document.getElementById("demo").innerHTML = "Hello JavaScript!";
+</script>
+okay
+.
+<script type="text/javascript">
+// JavaScript example
+
+document.getElementById("demo").innerHTML = "Hello JavaScript!";
+</script>
+<p>okay</p>
+````````````````````````````````
+
+
+A style tag (type 1):
+
+```````````````````````````````` example
+<style
+ type="text/css">
+h1 {color:red;}
+
+p {color:blue;}
+</style>
+okay
+.
+<style
+ type="text/css">
+h1 {color:red;}
+
+p {color:blue;}
+</style>
+<p>okay</p>
+````````````````````````````````
+
+
+If there is no matching end tag, the block will end at the
+end of the document (or the enclosing [block quote][block quotes]
+or [list item][list items]):
+
+```````````````````````````````` example
+<style
+ type="text/css">
+
+foo
+.
+<style
+ type="text/css">
+
+foo
+````````````````````````````````
+
+
+```````````````````````````````` example
+> <div>
+> foo
+
+bar
+.
+<blockquote>
+<div>
+foo
+</blockquote>
+<p>bar</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+- <div>
+- foo
+.
+<ul>
+<li>
+<div>
+</li>
+<li>foo</li>
+</ul>
+````````````````````````````````
+
+
+The end tag can occur on the same line as the start tag:
+
+```````````````````````````````` example
+<style>p{color:red;}</style>
+*foo*
+.
+<style>p{color:red;}</style>
+<p><em>foo</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<!-- foo -->*bar*
+*baz*
+.
+<!-- foo -->*bar*
+<p><em>baz</em></p>
+````````````````````````````````
+
+
+Note that anything on the last line after the
+end tag will be included in the [HTML block]:
+
+```````````````````````````````` example
+<script>
+foo
+</script>1. *bar*
+.
+<script>
+foo
+</script>1. *bar*
+````````````````````````````````
+
+
+A comment (type 2):
+
+```````````````````````````````` example
+<!-- Foo
+
+bar
+ baz -->
+okay
+.
+<!-- Foo
+
+bar
+ baz -->
+<p>okay</p>
+````````````````````````````````
+
+
+
+A processing instruction (type 3):
+
+```````````````````````````````` example
+<?php
+
+ echo '>';
+
+?>
+okay
+.
+<?php
+
+ echo '>';
+
+?>
+<p>okay</p>
+````````````````````````````````
+
+
+A declaration (type 4):
+
+```````````````````````````````` example
+<!DOCTYPE html>
+.
+<!DOCTYPE html>
+````````````````````````````````
+
+
+CDATA (type 5):
+
+```````````````````````````````` example
+<![CDATA[
+function matchwo(a,b)
+{
+ if (a < b && a < 0) then {
+ return 1;
+
+ } else {
+
+ return 0;
+ }
+}
+]]]]><![CDATA[>
+okay
+.
+<![CDATA[
+function matchwo(a,b)
+{
+ if (a < b && a < 0) then {
+ return 1;
+
+ } else {
+
+ return 0;
+ }
+}
+]]]]><![CDATA[>
+<p>okay</p>
+````````````````````````````````
+
+
+The opening tag can be indented 1-3 spaces, but not 4:
+
+```````````````````````````````` example
+ <!-- foo -->
+
+ <!-- foo -->
+.
+ <!-- foo -->
+<pre><code><!-- foo -->
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+ <div>
+
+ <div>
+.
+ <div>
+<pre><code><div>
+</code></pre>
+````````````````````````````````
+
+
+An HTML block of types 1--6 can interrupt a paragraph, and need not be
+preceded by a blank line.
+
+```````````````````````````````` example
+Foo
+<div>
+bar
+</div>
+.
+<p>Foo</p>
+<div>
+bar
+</div>
+````````````````````````````````
+
+
+However, a following blank line is needed, except at the end of
+a document, and except for blocks of types 1--5, [above][HTML
+block]:
+
+```````````````````````````````` example
+<div>
+bar
+</div>
+*foo*
+.
+<div>
+bar
+</div>
+*foo*
+````````````````````````````````
+
+
+HTML blocks of type 7 cannot interrupt a paragraph:
+
+```````````````````````````````` example
+Foo
+<a href="bar">
+baz
+.
+<p>Foo
+<a href="bar">
+baz</p>
+````````````````````````````````
+
+
+This rule differs from John Gruber's original Markdown syntax
+specification, which says:
+
+> The only restrictions are that block-level HTML elements —
+> e.g. `<div>`, `<table>`, `<pre>`, `<p>`, etc. — must be separated from
+> surrounding content by blank lines, and the start and end tags of the
+> block should not be indented with tabs or spaces.
+
+In some ways Gruber's rule is more restrictive than the one given
+here:
+
+- It requires that an HTML block be preceded by a blank line.
+- It does not allow the start tag to be indented.
+- It requires a matching end tag, which it also does not allow to
+ be indented.
+
+Most Markdown implementations (including some of Gruber's own) do not
+respect all of these restrictions.
+
+There is one respect, however, in which Gruber's rule is more liberal
+than the one given here, since it allows blank lines to occur inside
+an HTML block. There are two reasons for disallowing them here.
+First, it removes the need to parse balanced tags, which is
+expensive and can require backtracking from the end of the document
+if no matching end tag is found. Second, it provides a very simple
+and flexible way of including Markdown content inside HTML tags:
+simply separate the Markdown from the HTML using blank lines:
+
+Compare:
+
+```````````````````````````````` example
+<div>
+
+*Emphasized* text.
+
+</div>
+.
+<div>
+<p><em>Emphasized</em> text.</p>
+</div>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<div>
+*Emphasized* text.
+</div>
+.
+<div>
+*Emphasized* text.
+</div>
+````````````````````````````````
+
+
+Some Markdown implementations have adopted a convention of
+interpreting content inside tags as text if the open tag has
+the attribute `markdown=1`. The rule given above seems a simpler and
+more elegant way of achieving the same expressive power, which is also
+much simpler to parse.
+
+The main potential drawback is that one can no longer paste HTML
+blocks into Markdown documents with 100% reliability. However,
+*in most cases* this will work fine, because the blank lines in
+HTML are usually followed by HTML block tags. For example:
+
+```````````````````````````````` example
+<table>
+
+<tr>
+
+<td>
+Hi
+</td>
+
+</tr>
+
+</table>
+.
+<table>
+<tr>
+<td>
+Hi
+</td>
+</tr>
+</table>
+````````````````````````````````
+
+
+There are problems, however, if the inner tags are indented
+*and* separated by spaces, as then they will be interpreted as
+an indented code block:
+
+```````````````````````````````` example
+<table>
+
+ <tr>
+
+ <td>
+ Hi
+ </td>
+
+ </tr>
+
+</table>
+.
+<table>
+ <tr>
+<pre><code><td>
+ Hi
+</td>
+</code></pre>
+ </tr>
+</table>
+````````````````````````````````
+
+
+Fortunately, blank lines are usually not necessary and can be
+deleted. The exception is inside `<pre>` tags, but as described
+[above][HTML blocks], raw HTML blocks starting with `<pre>`
+*can* contain blank lines.
+
+## Link reference definitions
+
+A [link reference definition](@)
+consists of a [link label], indented up to three spaces, followed
+by a colon (`:`), optional [whitespace] (including up to one
+[line ending]), a [link destination],
+optional [whitespace] (including up to one
+[line ending]), and an optional [link
+title], which if it is present must be separated
+from the [link destination] by [whitespace].
+No further [non-whitespace characters] may occur on the line.
+
+A [link reference definition]
+does not correspond to a structural element of a document. Instead, it
+defines a label which can be used in [reference links]
+and reference-style [images] elsewhere in the document. [Link
+reference definitions] can come either before or after the links that use
+them.
+
+```````````````````````````````` example
+[foo]: /url "title"
+
+[foo]
+.
+<p><a href="/url" title="title">foo</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+ [foo]:
+ /url
+ 'the title'
+
+[foo]
+.
+<p><a href="/url" title="the title">foo</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[Foo*bar\]]:my_(url) 'title (with parens)'
+
+[Foo*bar\]]
+.
+<p><a href="my_(url)" title="title (with parens)">Foo*bar]</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[Foo bar]:
+<my url>
+'title'
+
+[Foo bar]
+.
+<p><a href="my%20url" title="title">Foo bar</a></p>
+````````````````````````````````
+
+
+The title may extend over multiple lines:
+
+```````````````````````````````` example
+[foo]: /url '
+title
+line1
+line2
+'
+
+[foo]
+.
+<p><a href="/url" title="
+title
+line1
+line2
+">foo</a></p>
+````````````````````````````````
+
+
+However, it may not contain a [blank line]:
+
+```````````````````````````````` example
+[foo]: /url 'title
+
+with blank line'
+
+[foo]
+.
+<p>[foo]: /url 'title</p>
+<p>with blank line'</p>
+<p>[foo]</p>
+````````````````````````````````
+
+
+The title may be omitted:
+
+```````````````````````````````` example
+[foo]:
+/url
+
+[foo]
+.
+<p><a href="/url">foo</a></p>
+````````````````````````````````
+
+
+The link destination may not be omitted:
+
+```````````````````````````````` example
+[foo]:
+
+[foo]
+.
+<p>[foo]:</p>
+<p>[foo]</p>
+````````````````````````````````
+
+ However, an empty link destination may be specified using
+ angle brackets:
+
+```````````````````````````````` example
+[foo]: <>
+
+[foo]
+.
+<p><a href="">foo</a></p>
+````````````````````````````````
+
+The title must be separated from the link destination by
+whitespace:
+
+```````````````````````````````` example
+[foo]: <bar>(baz)
+
+[foo]
+.
+<p>[foo]: <bar>(baz)</p>
+<p>[foo]</p>
+````````````````````````````````
+
+
+Both title and destination can contain backslash escapes
+and literal backslashes:
+
+```````````````````````````````` example
+[foo]: /url\bar\*baz "foo\"bar\baz"
+
+[foo]
+.
+<p><a href="/url%5Cbar*baz" title="foo"bar\baz">foo</a></p>
+````````````````````````````````
+
+
+A link can come before its corresponding definition:
+
+```````````````````````````````` example
+[foo]
+
+[foo]: url
+.
+<p><a href="url">foo</a></p>
+````````````````````````````````
+
+
+If there are several matching definitions, the first one takes
+precedence:
+
+```````````````````````````````` example
+[foo]
+
+[foo]: first
+[foo]: second
+.
+<p><a href="first">foo</a></p>
+````````````````````````````````
+
+
+As noted in the section on [Links], matching of labels is
+case-insensitive (see [matches]).
+
+```````````````````````````````` example
+[FOO]: /url
+
+[Foo]
+.
+<p><a href="/url">Foo</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[ΑΓΩ]: /φου
+
+[αγω]
+.
+<p><a href="/%CF%86%CE%BF%CF%85">αγω</a></p>
+````````````````````````````````
+
+
+Here is a link reference definition with no corresponding link.
+It contributes nothing to the document.
+
+```````````````````````````````` example
+[foo]: /url
+.
+````````````````````````````````
+
+
+Here is another one:
+
+```````````````````````````````` example
+[
+foo
+]: /url
+bar
+.
+<p>bar</p>
+````````````````````````````````
+
+
+This is not a link reference definition, because there are
+[non-whitespace characters] after the title:
+
+```````````````````````````````` example
+[foo]: /url "title" ok
+.
+<p>[foo]: /url "title" ok</p>
+````````````````````````````````
+
+
+This is a link reference definition, but it has no title:
+
+```````````````````````````````` example
+[foo]: /url
+"title" ok
+.
+<p>"title" ok</p>
+````````````````````````````````
+
+
+This is not a link reference definition, because it is indented
+four spaces:
+
+```````````````````````````````` example
+ [foo]: /url "title"
+
+[foo]
+.
+<pre><code>[foo]: /url "title"
+</code></pre>
+<p>[foo]</p>
+````````````````````````````````
+
+
+This is not a link reference definition, because it occurs inside
+a code block:
+
+```````````````````````````````` example
+```
+[foo]: /url
+```
+
+[foo]
+.
+<pre><code>[foo]: /url
+</code></pre>
+<p>[foo]</p>
+````````````````````````````````
+
+
+A [link reference definition] cannot interrupt a paragraph.
+
+```````````````````````````````` example
+Foo
+[bar]: /baz
+
+[bar]
+.
+<p>Foo
+[bar]: /baz</p>
+<p>[bar]</p>
+````````````````````````````````
+
+
+However, it can directly follow other block elements, such as headings
+and thematic breaks, and it need not be followed by a blank line.
+
+```````````````````````````````` example
+# [Foo]
+[foo]: /url
+> bar
+.
+<h1><a href="/url">Foo</a></h1>
+<blockquote>
+<p>bar</p>
+</blockquote>
+````````````````````````````````
+
+```````````````````````````````` example
+[foo]: /url
+bar
+===
+[foo]
+.
+<h1>bar</h1>
+<p><a href="/url">foo</a></p>
+````````````````````````````````
+
+```````````````````````````````` example
+[foo]: /url
+===
+[foo]
+.
+<p>===
+<a href="/url">foo</a></p>
+````````````````````````````````
+
+
+Several [link reference definitions]
+can occur one after another, without intervening blank lines.
+
+```````````````````````````````` example
+[foo]: /foo-url "foo"
+[bar]: /bar-url
+ "bar"
+[baz]: /baz-url
+
+[foo],
+[bar],
+[baz]
+.
+<p><a href="/foo-url" title="foo">foo</a>,
+<a href="/bar-url" title="bar">bar</a>,
+<a href="/baz-url">baz</a></p>
+````````````````````````````````
+
+
+[Link reference definitions] can occur
+inside block containers, like lists and block quotations. They
+affect the entire document, not just the container in which they
+are defined:
+
+```````````````````````````````` example
+[foo]
+
+> [foo]: /url
+.
+<p><a href="/url">foo</a></p>
+<blockquote>
+</blockquote>
+````````````````````````````````
+
+
+Whether something is a [link reference definition] is
+independent of whether the link reference it defines is
+used in the document. Thus, for example, the following
+document contains just a link reference definition, and
+no visible content:
+
+```````````````````````````````` example
+[foo]: /url
+.
+````````````````````````````````
+
+
+## Paragraphs
+
+A sequence of non-blank lines that cannot be interpreted as other
+kinds of blocks forms a [paragraph](@).
+The contents of the paragraph are the result of parsing the
+paragraph's raw content as inlines. The paragraph's raw content
+is formed by concatenating the lines and removing initial and final
+[whitespace].
+
+A simple example with two paragraphs:
+
+```````````````````````````````` example
+aaa
+
+bbb
+.
+<p>aaa</p>
+<p>bbb</p>
+````````````````````````````````
+
+
+Paragraphs can contain multiple lines, but no blank lines:
+
+```````````````````````````````` example
+aaa
+bbb
+
+ccc
+ddd
+.
+<p>aaa
+bbb</p>
+<p>ccc
+ddd</p>
+````````````````````````````````
+
+
+Multiple blank lines between paragraph have no effect:
+
+```````````````````````````````` example
+aaa
+
+
+bbb
+.
+<p>aaa</p>
+<p>bbb</p>
+````````````````````````````````
+
+
+Leading spaces are skipped:
+
+```````````````````````````````` example
+ aaa
+ bbb
+.
+<p>aaa
+bbb</p>
+````````````````````````````````
+
+
+Lines after the first may be indented any amount, since indented
+code blocks cannot interrupt paragraphs.
+
+```````````````````````````````` example
+aaa
+ bbb
+ ccc
+.
+<p>aaa
+bbb
+ccc</p>
+````````````````````````````````
+
+
+However, the first line may be indented at most three spaces,
+or an indented code block will be triggered:
+
+```````````````````````````````` example
+ aaa
+bbb
+.
+<p>aaa
+bbb</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+ aaa
+bbb
+.
+<pre><code>aaa
+</code></pre>
+<p>bbb</p>
+````````````````````````````````
+
+
+Final spaces are stripped before inline parsing, so a paragraph
+that ends with two or more spaces will not end with a [hard line
+break]:
+
+```````````````````````````````` example
+aaa
+bbb
+.
+<p>aaa<br />
+bbb</p>
+````````````````````````````````
+
+
+## Blank lines
+
+[Blank lines] between block-level elements are ignored,
+except for the role they play in determining whether a [list]
+is [tight] or [loose].
+
+Blank lines at the beginning and end of the document are also ignored.
+
+```````````````````````````````` example
+
+
+aaa
+
+
+# aaa
+
+
+.
+<p>aaa</p>
+<h1>aaa</h1>
+````````````````````````````````
+
+<div class="extension">
+
+## Tables (extension)
+
+GFM enables the `table` extension, where an additional leaf block type is
+available.
+
+A [table](@) is an arrangement of data with rows and columns, consisting of a
+single header row, a [delimiter row] separating the header from the data, and
+zero or more data rows.
+
+Each row consists of cells containing arbitrary text, in which [inlines] are
+parsed, separated by pipes (`|`). A leading and trailing pipe is also
+recommended for clarity of reading, and if there's otherwise parsing ambiguity.
+Spaces between pipes and cell content are trimmed. Block-level elements cannot
+be inserted in a table.
+
+The [delimiter row](@) consists of cells whose only content are hyphens (`-`),
+and optionally, a leading or trailing colon (`:`), or both, to indicate left,
+right, or center alignment respectively.
+
+```````````````````````````````` example table
+| foo | bar |
+| --- | --- |
+| baz | bim |
+.
+<table>
+<thead>
+<tr>
+<th>foo</th>
+<th>bar</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>baz</td>
+<td>bim</td>
+</tr>
+</tbody>
+</table>
+````````````````````````````````
+
+Cells in one column don't need to match length, though it's easier to read if
+they are. Likewise, use of leading and trailing pipes may be inconsistent:
+
+```````````````````````````````` example table
+| abc | defghi |
+:-: | -----------:
+bar | baz
+.
+<table>
+<thead>
+<tr>
+<th align="center">abc</th>
+<th align="right">defghi</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td align="center">bar</td>
+<td align="right">baz</td>
+</tr>
+</tbody>
+</table>
+````````````````````````````````
+
+Include a pipe in a cell's content by escaping it, including inside other
+inline spans:
+
+```````````````````````````````` example table
+| f\|oo |
+| ------ |
+| b `\|` az |
+| b **\|** im |
+.
+<table>
+<thead>
+<tr>
+<th>f|oo</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>b <code>|</code> az</td>
+</tr>
+<tr>
+<td>b <strong>|</strong> im</td>
+</tr>
+</tbody>
+</table>
+````````````````````````````````
+
+The table is broken at the first empty line, or beginning of another
+block-level structure:
+
+```````````````````````````````` example table
+| abc | def |
+| --- | --- |
+| bar | baz |
+> bar
+.
+<table>
+<thead>
+<tr>
+<th>abc</th>
+<th>def</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>bar</td>
+<td>baz</td>
+</tr>
+</tbody>
+</table>
+<blockquote>
+<p>bar</p>
+</blockquote>
+````````````````````````````````
+
+```````````````````````````````` example table
+| abc | def |
+| --- | --- |
+| bar | baz |
+bar
+
+bar
+.
+<table>
+<thead>
+<tr>
+<th>abc</th>
+<th>def</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>bar</td>
+<td>baz</td>
+</tr>
+<tr>
+<td>bar</td>
+<td></td>
+</tr>
+</tbody>
+</table>
+<p>bar</p>
+````````````````````````````````
+
+The header row must match the [delimiter row] in the number of cells. If not,
+a table will not be recognized:
+
+```````````````````````````````` example table
+| abc | def |
+| --- |
+| bar |
+.
+<p>| abc | def |
+| --- |
+| bar |</p>
+````````````````````````````````
+
+The remainder of the table's rows may vary in the number of cells. If there
+are a number of cells fewer than the number of cells in the header row, empty
+cells are inserted. If there are greater, the excess is ignored:
+
+```````````````````````````````` example table
+| abc | def |
+| --- | --- |
+| bar |
+| bar | baz | boo |
+.
+<table>
+<thead>
+<tr>
+<th>abc</th>
+<th>def</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>bar</td>
+<td></td>
+</tr>
+<tr>
+<td>bar</td>
+<td>baz</td>
+</tr>
+</tbody>
+</table>
+````````````````````````````````
+
+If there are no rows in the body, no `<tbody>` is generated in HTML output:
+
+```````````````````````````````` example table
+| abc | def |
+| --- | --- |
+.
+<table>
+<thead>
+<tr>
+<th>abc</th>
+<th>def</th>
+</tr>
+</thead>
+</table>
+````````````````````````````````
+
+</div>
+
+# Container blocks
+
+A [container block](#container-blocks) is a block that has other
+blocks as its contents. There are two basic kinds of container blocks:
+[block quotes] and [list items].
+[Lists] are meta-containers for [list items].
+
+We define the syntax for container blocks recursively. The general
+form of the definition is:
+
+> If X is a sequence of blocks, then the result of
+> transforming X in such-and-such a way is a container of type Y
+> with these blocks as its content.
+
+So, we explain what counts as a block quote or list item by explaining
+how these can be *generated* from their contents. This should suffice
+to define the syntax, although it does not give a recipe for *parsing*
+these constructions. (A recipe is provided below in the section entitled
+[A parsing strategy](#appendix-a-parsing-strategy).)
+
+## Block quotes
+
+A [block quote marker](@)
+consists of 0-3 spaces of initial indent, plus (a) the character `>` together
+with a following space, or (b) a single character `>` not followed by a space.
+
+The following rules define [block quotes]:
+
+1. **Basic case.** If a string of lines *Ls* constitute a sequence
+ of blocks *Bs*, then the result of prepending a [block quote
+ marker] to the beginning of each line in *Ls*
+ is a [block quote](#block-quotes) containing *Bs*.
+
+2. **Laziness.** If a string of lines *Ls* constitute a [block
+ quote](#block-quotes) with contents *Bs*, then the result of deleting
+ the initial [block quote marker] from one or
+ more lines in which the next [non-whitespace character] after the [block
+ quote marker] is [paragraph continuation
+ text] is a block quote with *Bs* as its content.
+ [Paragraph continuation text](@) is text
+ that will be parsed as part of the content of a paragraph, but does
+ not occur at the beginning of the paragraph.
+
+3. **Consecutiveness.** A document cannot contain two [block
+ quotes] in a row unless there is a [blank line] between them.
+
+Nothing else counts as a [block quote](#block-quotes).
+
+Here is a simple example:
+
+```````````````````````````````` example
+> # Foo
+> bar
+> baz
+.
+<blockquote>
+<h1>Foo</h1>
+<p>bar
+baz</p>
+</blockquote>
+````````````````````````````````
+
+
+The spaces after the `>` characters can be omitted:
+
+```````````````````````````````` example
+># Foo
+>bar
+> baz
+.
+<blockquote>
+<h1>Foo</h1>
+<p>bar
+baz</p>
+</blockquote>
+````````````````````````````````
+
+
+The `>` characters can be indented 1-3 spaces:
+
+```````````````````````````````` example
+ > # Foo
+ > bar
+ > baz
+.
+<blockquote>
+<h1>Foo</h1>
+<p>bar
+baz</p>
+</blockquote>
+````````````````````````````````
+
+
+Four spaces gives us a code block:
+
+```````````````````````````````` example
+ > # Foo
+ > bar
+ > baz
+.
+<pre><code>> # Foo
+> bar
+> baz
+</code></pre>
+````````````````````````````````
+
+
+The Laziness clause allows us to omit the `>` before
+[paragraph continuation text]:
+
+```````````````````````````````` example
+> # Foo
+> bar
+baz
+.
+<blockquote>
+<h1>Foo</h1>
+<p>bar
+baz</p>
+</blockquote>
+````````````````````````````````
+
+
+A block quote can contain some lazy and some non-lazy
+continuation lines:
+
+```````````````````````````````` example
+> bar
+baz
+> foo
+.
+<blockquote>
+<p>bar
+baz
+foo</p>
+</blockquote>
+````````````````````````````````
+
+
+Laziness only applies to lines that would have been continuations of
+paragraphs had they been prepended with [block quote markers].
+For example, the `> ` cannot be omitted in the second line of
+
+``` markdown
+> foo
+> ---
+```
+
+without changing the meaning:
+
+```````````````````````````````` example
+> foo
+---
+.
+<blockquote>
+<p>foo</p>
+</blockquote>
+<hr />
+````````````````````````````````
+
+
+Similarly, if we omit the `> ` in the second line of
+
+``` markdown
+> - foo
+> - bar
+```
+
+then the block quote ends after the first line:
+
+```````````````````````````````` example
+> - foo
+- bar
+.
+<blockquote>
+<ul>
+<li>foo</li>
+</ul>
+</blockquote>
+<ul>
+<li>bar</li>
+</ul>
+````````````````````````````````
+
+
+For the same reason, we can't omit the `> ` in front of
+subsequent lines of an indented or fenced code block:
+
+```````````````````````````````` example
+> foo
+ bar
+.
+<blockquote>
+<pre><code>foo
+</code></pre>
+</blockquote>
+<pre><code>bar
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+> ```
+foo
+```
+.
+<blockquote>
+<pre><code></code></pre>
+</blockquote>
+<p>foo</p>
+<pre><code></code></pre>
+````````````````````````````````
+
+
+Note that in the following case, we have a [lazy
+continuation line]:
+
+```````````````````````````````` example
+> foo
+ - bar
+.
+<blockquote>
+<p>foo
+- bar</p>
+</blockquote>
+````````````````````````````````
+
+
+To see why, note that in
+
+```markdown
+> foo
+> - bar
+```
+
+the `- bar` is indented too far to start a list, and can't
+be an indented code block because indented code blocks cannot
+interrupt paragraphs, so it is [paragraph continuation text].
+
+A block quote can be empty:
+
+```````````````````````````````` example
+>
+.
+<blockquote>
+</blockquote>
+````````````````````````````````
+
+
+```````````````````````````````` example
+>
+>
+>
+.
+<blockquote>
+</blockquote>
+````````````````````````````````
+
+
+A block quote can have initial or final blank lines:
+
+```````````````````````````````` example
+>
+> foo
+>
+.
+<blockquote>
+<p>foo</p>
+</blockquote>
+````````````````````````````````
+
+
+A blank line always separates block quotes:
+
+```````````````````````````````` example
+> foo
+
+> bar
+.
+<blockquote>
+<p>foo</p>
+</blockquote>
+<blockquote>
+<p>bar</p>
+</blockquote>
+````````````````````````````````
+
+
+(Most current Markdown implementations, including John Gruber's
+original `Markdown.pl`, will parse this example as a single block quote
+with two paragraphs. But it seems better to allow the author to decide
+whether two block quotes or one are wanted.)
+
+Consecutiveness means that if we put these block quotes together,
+we get a single block quote:
+
+```````````````````````````````` example
+> foo
+> bar
+.
+<blockquote>
+<p>foo
+bar</p>
+</blockquote>
+````````````````````````````````
+
+
+To get a block quote with two paragraphs, use:
+
+```````````````````````````````` example
+> foo
+>
+> bar
+.
+<blockquote>
+<p>foo</p>
+<p>bar</p>
+</blockquote>
+````````````````````````````````
+
+
+Block quotes can interrupt paragraphs:
+
+```````````````````````````````` example
+foo
+> bar
+.
+<p>foo</p>
+<blockquote>
+<p>bar</p>
+</blockquote>
+````````````````````````````````
+
+
+In general, blank lines are not needed before or after block
+quotes:
+
+```````````````````````````````` example
+> aaa
+***
+> bbb
+.
+<blockquote>
+<p>aaa</p>
+</blockquote>
+<hr />
+<blockquote>
+<p>bbb</p>
+</blockquote>
+````````````````````````````````
+
+
+However, because of laziness, a blank line is needed between
+a block quote and a following paragraph:
+
+```````````````````````````````` example
+> bar
+baz
+.
+<blockquote>
+<p>bar
+baz</p>
+</blockquote>
+````````````````````````````````
+
+
+```````````````````````````````` example
+> bar
+
+baz
+.
+<blockquote>
+<p>bar</p>
+</blockquote>
+<p>baz</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+> bar
+>
+baz
+.
+<blockquote>
+<p>bar</p>
+</blockquote>
+<p>baz</p>
+````````````````````````````````
+
+
+It is a consequence of the Laziness rule that any number
+of initial `>`s may be omitted on a continuation line of a
+nested block quote:
+
+```````````````````````````````` example
+> > > foo
+bar
+.
+<blockquote>
+<blockquote>
+<blockquote>
+<p>foo
+bar</p>
+</blockquote>
+</blockquote>
+</blockquote>
+````````````````````````````````
+
+
+```````````````````````````````` example
+>>> foo
+> bar
+>>baz
+.
+<blockquote>
+<blockquote>
+<blockquote>
+<p>foo
+bar
+baz</p>
+</blockquote>
+</blockquote>
+</blockquote>
+````````````````````````````````
+
+
+When including an indented code block in a block quote,
+remember that the [block quote marker] includes
+both the `>` and a following space. So *five spaces* are needed after
+the `>`:
+
+```````````````````````````````` example
+> code
+
+> not code
+.
+<blockquote>
+<pre><code>code
+</code></pre>
+</blockquote>
+<blockquote>
+<p>not code</p>
+</blockquote>
+````````````````````````````````
+
+
+
+## List items
+
+A [list marker](@) is a
+[bullet list marker] or an [ordered list marker].
+
+A [bullet list marker](@)
+is a `-`, `+`, or `*` character.
+
+An [ordered list marker](@)
+is a sequence of 1--9 arabic digits (`0-9`), followed by either a
+`.` character or a `)` character. (The reason for the length
+limit is that with 10 digits we start seeing integer overflows
+in some browsers.)
+
+The following rules define [list items]:
+
+1. **Basic case.** If a sequence of lines *Ls* constitute a sequence of
+ blocks *Bs* starting with a [non-whitespace character], and *M* is a
+ list marker of width *W* followed by 1 ≤ *N* ≤ 4 spaces, then the result
+ of prepending *M* and the following spaces to the first line of
+ *Ls*, and indenting subsequent lines of *Ls* by *W + N* spaces, is a
+ list item with *Bs* as its contents. The type of the list item
+ (bullet or ordered) is determined by the type of its list marker.
+ If the list item is ordered, then it is also assigned a start
+ number, based on the ordered list marker.
+
+ Exceptions:
+
+ 1. When the first list item in a [list] interrupts
+ a paragraph---that is, when it starts on a line that would
+ otherwise count as [paragraph continuation text]---then (a)
+ the lines *Ls* must not begin with a blank line, and (b) if
+ the list item is ordered, the start number must be 1.
+ 2. If any line is a [thematic break][thematic breaks] then
+ that line is not a list item.
+
+For example, let *Ls* be the lines
+
+```````````````````````````````` example
+A paragraph
+with two lines.
+
+ indented code
+
+> A block quote.
+.
+<p>A paragraph
+with two lines.</p>
+<pre><code>indented code
+</code></pre>
+<blockquote>
+<p>A block quote.</p>
+</blockquote>
+````````````````````````````````
+
+
+And let *M* be the marker `1.`, and *N* = 2. Then rule #1 says
+that the following is an ordered list item with start number 1,
+and the same contents as *Ls*:
+
+```````````````````````````````` example
+1. A paragraph
+ with two lines.
+
+ indented code
+
+ > A block quote.
+.
+<ol>
+<li>
+<p>A paragraph
+with two lines.</p>
+<pre><code>indented code
+</code></pre>
+<blockquote>
+<p>A block quote.</p>
+</blockquote>
+</li>
+</ol>
+````````````````````````````````
+
+
+The most important thing to notice is that the position of
+the text after the list marker determines how much indentation
+is needed in subsequent blocks in the list item. If the list
+marker takes up two spaces, and there are three spaces between
+the list marker and the next [non-whitespace character], then blocks
+must be indented five spaces in order to fall under the list
+item.
+
+Here are some examples showing how far content must be indented to be
+put under the list item:
+
+```````````````````````````````` example
+- one
+
+ two
+.
+<ul>
+<li>one</li>
+</ul>
+<p>two</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+- one
+
+ two
+.
+<ul>
+<li>
+<p>one</p>
+<p>two</p>
+</li>
+</ul>
+````````````````````````````````
+
+
+```````````````````````````````` example
+ - one
+
+ two
+.
+<ul>
+<li>one</li>
+</ul>
+<pre><code> two
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+ - one
+
+ two
+.
+<ul>
+<li>
+<p>one</p>
+<p>two</p>
+</li>
+</ul>
+````````````````````````````````
+
+
+It is tempting to think of this in terms of columns: the continuation
+blocks must be indented at least to the column of the first
+[non-whitespace character] after the list marker. However, that is not quite right.
+The spaces after the list marker determine how much relative indentation
+is needed. Which column this indentation reaches will depend on
+how the list item is embedded in other constructions, as shown by
+this example:
+
+```````````````````````````````` example
+ > > 1. one
+>>
+>> two
+.
+<blockquote>
+<blockquote>
+<ol>
+<li>
+<p>one</p>
+<p>two</p>
+</li>
+</ol>
+</blockquote>
+</blockquote>
+````````````````````````````````
+
+
+Here `two` occurs in the same column as the list marker `1.`,
+but is actually contained in the list item, because there is
+sufficient indentation after the last containing blockquote marker.
+
+The converse is also possible. In the following example, the word `two`
+occurs far to the right of the initial text of the list item, `one`, but
+it is not considered part of the list item, because it is not indented
+far enough past the blockquote marker:
+
+```````````````````````````````` example
+>>- one
+>>
+ > > two
+.
+<blockquote>
+<blockquote>
+<ul>
+<li>one</li>
+</ul>
+<p>two</p>
+</blockquote>
+</blockquote>
+````````````````````````````````
+
+
+Note that at least one space is needed between the list marker and
+any following content, so these are not list items:
+
+```````````````````````````````` example
+-one
+
+2.two
+.
+<p>-one</p>
+<p>2.two</p>
+````````````````````````````````
+
+
+A list item may contain blocks that are separated by more than
+one blank line.
+
+```````````````````````````````` example
+- foo
+
+
+ bar
+.
+<ul>
+<li>
+<p>foo</p>
+<p>bar</p>
+</li>
+</ul>
+````````````````````````````````
+
+
+A list item may contain any kind of block:
+
+```````````````````````````````` example
+1. foo
+
+ ```
+ bar
+ ```
+
+ baz
+
+ > bam
+.
+<ol>
+<li>
+<p>foo</p>
+<pre><code>bar
+</code></pre>
+<p>baz</p>
+<blockquote>
+<p>bam</p>
+</blockquote>
+</li>
+</ol>
+````````````````````````````````
+
+
+A list item that contains an indented code block will preserve
+empty lines within the code block verbatim.
+
+```````````````````````````````` example
+- Foo
+
+ bar
+
+
+ baz
+.
+<ul>
+<li>
+<p>Foo</p>
+<pre><code>bar
+
+
+baz
+</code></pre>
+</li>
+</ul>
+````````````````````````````````
+
+Note that ordered list start numbers must be nine digits or less:
+
+```````````````````````````````` example
+123456789. ok
+.
+<ol start="123456789">
+<li>ok</li>
+</ol>
+````````````````````````````````
+
+
+```````````````````````````````` example
+1234567890. not ok
+.
+<p>1234567890. not ok</p>
+````````````````````````````````
+
+
+A start number may begin with 0s:
+
+```````````````````````````````` example
+0. ok
+.
+<ol start="0">
+<li>ok</li>
+</ol>
+````````````````````````````````
+
+
+```````````````````````````````` example
+003. ok
+.
+<ol start="3">
+<li>ok</li>
+</ol>
+````````````````````````````````
+
+
+A start number may not be negative:
+
+```````````````````````````````` example
+-1. not ok
+.
+<p>-1. not ok</p>
+````````````````````````````````
+
+
+
+2. **Item starting with indented code.** If a sequence of lines *Ls*
+ constitute a sequence of blocks *Bs* starting with an indented code
+ block, and *M* is a list marker of width *W* followed by
+ one space, then the result of prepending *M* and the following
+ space to the first line of *Ls*, and indenting subsequent lines of
+ *Ls* by *W + 1* spaces, is a list item with *Bs* as its contents.
+ If a line is empty, then it need not be indented. The type of the
+ list item (bullet or ordered) is determined by the type of its list
+ marker. If the list item is ordered, then it is also assigned a
+ start number, based on the ordered list marker.
+
+An indented code block will have to be indented four spaces beyond
+the edge of the region where text will be included in the list item.
+In the following case that is 6 spaces:
+
+```````````````````````````````` example
+- foo
+
+ bar
+.
+<ul>
+<li>
+<p>foo</p>
+<pre><code>bar
+</code></pre>
+</li>
+</ul>
+````````````````````````````````
+
+
+And in this case it is 11 spaces:
+
+```````````````````````````````` example
+ 10. foo
+
+ bar
+.
+<ol start="10">
+<li>
+<p>foo</p>
+<pre><code>bar
+</code></pre>
+</li>
+</ol>
+````````````````````````````````
+
+
+If the *first* block in the list item is an indented code block,
+then by rule #2, the contents must be indented *one* space after the
+list marker:
+
+```````````````````````````````` example
+ indented code
+
+paragraph
+
+ more code
+.
+<pre><code>indented code
+</code></pre>
+<p>paragraph</p>
+<pre><code>more code
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+1. indented code
+
+ paragraph
+
+ more code
+.
+<ol>
+<li>
+<pre><code>indented code
+</code></pre>
+<p>paragraph</p>
+<pre><code>more code
+</code></pre>
+</li>
+</ol>
+````````````````````````````````
+
+
+Note that an additional space indent is interpreted as space
+inside the code block:
+
+```````````````````````````````` example
+1. indented code
+
+ paragraph
+
+ more code
+.
+<ol>
+<li>
+<pre><code> indented code
+</code></pre>
+<p>paragraph</p>
+<pre><code>more code
+</code></pre>
+</li>
+</ol>
+````````````````````````````````
+
+
+Note that rules #1 and #2 only apply to two cases: (a) cases
+in which the lines to be included in a list item begin with a
+[non-whitespace character], and (b) cases in which
+they begin with an indented code
+block. In a case like the following, where the first block begins with
+a three-space indent, the rules do not allow us to form a list item by
+indenting the whole thing and prepending a list marker:
+
+```````````````````````````````` example
+ foo
+
+bar
+.
+<p>foo</p>
+<p>bar</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+- foo
+
+ bar
+.
+<ul>
+<li>foo</li>
+</ul>
+<p>bar</p>
+````````````````````````````````
+
+
+This is not a significant restriction, because when a block begins
+with 1-3 spaces indent, the indentation can always be removed without
+a change in interpretation, allowing rule #1 to be applied. So, in
+the above case:
+
+```````````````````````````````` example
+- foo
+
+ bar
+.
+<ul>
+<li>
+<p>foo</p>
+<p>bar</p>
+</li>
+</ul>
+````````````````````````````````
+
+
+3. **Item starting with a blank line.** If a sequence of lines *Ls*
+ starting with a single [blank line] constitute a (possibly empty)
+ sequence of blocks *Bs*, not separated from each other by more than
+ one blank line, and *M* is a list marker of width *W*,
+ then the result of prepending *M* to the first line of *Ls*, and
+ indenting subsequent lines of *Ls* by *W + 1* spaces, is a list
+ item with *Bs* as its contents.
+ If a line is empty, then it need not be indented. The type of the
+ list item (bullet or ordered) is determined by the type of its list
+ marker. If the list item is ordered, then it is also assigned a
+ start number, based on the ordered list marker.
+
+Here are some list items that start with a blank line but are not empty:
+
+```````````````````````````````` example
+-
+ foo
+-
+ ```
+ bar
+ ```
+-
+ baz
+.
+<ul>
+<li>foo</li>
+<li>
+<pre><code>bar
+</code></pre>
+</li>
+<li>
+<pre><code>baz
+</code></pre>
+</li>
+</ul>
+````````````````````````````````
+
+When the list item starts with a blank line, the number of spaces
+following the list marker doesn't change the required indentation:
+
+```````````````````````````````` example
+-
+ foo
+.
+<ul>
+<li>foo</li>
+</ul>
+````````````````````````````````
+
+
+A list item can begin with at most one blank line.
+In the following example, `foo` is not part of the list
+item:
+
+```````````````````````````````` example
+-
+
+ foo
+.
+<ul>
+<li></li>
+</ul>
+<p>foo</p>
+````````````````````````````````
+
+
+Here is an empty bullet list item:
+
+```````````````````````````````` example
+- foo
+-
+- bar
+.
+<ul>
+<li>foo</li>
+<li></li>
+<li>bar</li>
+</ul>
+````````````````````````````````
+
+
+It does not matter whether there are spaces following the [list marker]:
+
+```````````````````````````````` example
+- foo
+-
+- bar
+.
+<ul>
+<li>foo</li>
+<li></li>
+<li>bar</li>
+</ul>
+````````````````````````````````
+
+
+Here is an empty ordered list item:
+
+```````````````````````````````` example
+1. foo
+2.
+3. bar
+.
+<ol>
+<li>foo</li>
+<li></li>
+<li>bar</li>
+</ol>
+````````````````````````````````
+
+
+A list may start or end with an empty list item:
+
+```````````````````````````````` example
+*
+.
+<ul>
+<li></li>
+</ul>
+````````````````````````````````
+
+However, an empty list item cannot interrupt a paragraph:
+
+```````````````````````````````` example
+foo
+*
+
+foo
+1.
+.
+<p>foo
+*</p>
+<p>foo
+1.</p>
+````````````````````````````````
+
+
+4. **Indentation.** If a sequence of lines *Ls* constitutes a list item
+ according to rule #1, #2, or #3, then the result of indenting each line
+ of *Ls* by 1-3 spaces (the same for each line) also constitutes a
+ list item with the same contents and attributes. If a line is
+ empty, then it need not be indented.
+
+Indented one space:
+
+```````````````````````````````` example
+ 1. A paragraph
+ with two lines.
+
+ indented code
+
+ > A block quote.
+.
+<ol>
+<li>
+<p>A paragraph
+with two lines.</p>
+<pre><code>indented code
+</code></pre>
+<blockquote>
+<p>A block quote.</p>
+</blockquote>
+</li>
+</ol>
+````````````````````````````````
+
+
+Indented two spaces:
+
+```````````````````````````````` example
+ 1. A paragraph
+ with two lines.
+
+ indented code
+
+ > A block quote.
+.
+<ol>
+<li>
+<p>A paragraph
+with two lines.</p>
+<pre><code>indented code
+</code></pre>
+<blockquote>
+<p>A block quote.</p>
+</blockquote>
+</li>
+</ol>
+````````````````````````````````
+
+
+Indented three spaces:
+
+```````````````````````````````` example
+ 1. A paragraph
+ with two lines.
+
+ indented code
+
+ > A block quote.
+.
+<ol>
+<li>
+<p>A paragraph
+with two lines.</p>
+<pre><code>indented code
+</code></pre>
+<blockquote>
+<p>A block quote.</p>
+</blockquote>
+</li>
+</ol>
+````````````````````````````````
+
+
+Four spaces indent gives a code block:
+
+```````````````````````````````` example
+ 1. A paragraph
+ with two lines.
+
+ indented code
+
+ > A block quote.
+.
+<pre><code>1. A paragraph
+ with two lines.
+
+ indented code
+
+ > A block quote.
+</code></pre>
+````````````````````````````````
+
+
+
+5. **Laziness.** If a string of lines *Ls* constitute a [list
+ item](#list-items) with contents *Bs*, then the result of deleting
+ some or all of the indentation from one or more lines in which the
+ next [non-whitespace character] after the indentation is
+ [paragraph continuation text] is a
+ list item with the same contents and attributes. The unindented
+ lines are called
+ [lazy continuation line](@)s.
+
+Here is an example with [lazy continuation lines]:
+
+```````````````````````````````` example
+ 1. A paragraph
+with two lines.
+
+ indented code
+
+ > A block quote.
+.
+<ol>
+<li>
+<p>A paragraph
+with two lines.</p>
+<pre><code>indented code
+</code></pre>
+<blockquote>
+<p>A block quote.</p>
+</blockquote>
+</li>
+</ol>
+````````````````````````````````
+
+
+Indentation can be partially deleted:
+
+```````````````````````````````` example
+ 1. A paragraph
+ with two lines.
+.
+<ol>
+<li>A paragraph
+with two lines.</li>
+</ol>
+````````````````````````````````
+
+
+These examples show how laziness can work in nested structures:
+
+```````````````````````````````` example
+> 1. > Blockquote
+continued here.
+.
+<blockquote>
+<ol>
+<li>
+<blockquote>
+<p>Blockquote
+continued here.</p>
+</blockquote>
+</li>
+</ol>
+</blockquote>
+````````````````````````````````
+
+
+```````````````````````````````` example
+> 1. > Blockquote
+> continued here.
+.
+<blockquote>
+<ol>
+<li>
+<blockquote>
+<p>Blockquote
+continued here.</p>
+</blockquote>
+</li>
+</ol>
+</blockquote>
+````````````````````````````````
+
+
+
+6. **That's all.** Nothing that is not counted as a list item by rules
+ #1--5 counts as a [list item](#list-items).
+
+The rules for sublists follow from the general rules
+[above][List items]. A sublist must be indented the same number
+of spaces a paragraph would need to be in order to be included
+in the list item.
+
+So, in this case we need two spaces indent:
+
+```````````````````````````````` example
+- foo
+ - bar
+ - baz
+ - boo
+.
+<ul>
+<li>foo
+<ul>
+<li>bar
+<ul>
+<li>baz
+<ul>
+<li>boo</li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+````````````````````````````````
+
+
+One is not enough:
+
+```````````````````````````````` example
+- foo
+ - bar
+ - baz
+ - boo
+.
+<ul>
+<li>foo</li>
+<li>bar</li>
+<li>baz</li>
+<li>boo</li>
+</ul>
+````````````````````````````````
+
+
+Here we need four, because the list marker is wider:
+
+```````````````````````````````` example
+10) foo
+ - bar
+.
+<ol start="10">
+<li>foo
+<ul>
+<li>bar</li>
+</ul>
+</li>
+</ol>
+````````````````````````````````
+
+
+Three is not enough:
+
+```````````````````````````````` example
+10) foo
+ - bar
+.
+<ol start="10">
+<li>foo</li>
+</ol>
+<ul>
+<li>bar</li>
+</ul>
+````````````````````````````````
+
+
+A list may be the first block in a list item:
+
+```````````````````````````````` example
+- - foo
+.
+<ul>
+<li>
+<ul>
+<li>foo</li>
+</ul>
+</li>
+</ul>
+````````````````````````````````
+
+
+```````````````````````````````` example
+1. - 2. foo
+.
+<ol>
+<li>
+<ul>
+<li>
+<ol start="2">
+<li>foo</li>
+</ol>
+</li>
+</ul>
+</li>
+</ol>
+````````````````````````````````
+
+
+A list item can contain a heading:
+
+```````````````````````````````` example
+- # Foo
+- Bar
+ ---
+ baz
+.
+<ul>
+<li>
+<h1>Foo</h1>
+</li>
+<li>
+<h2>Bar</h2>
+baz</li>
+</ul>
+````````````````````````````````
+
+
+### Motivation
+
+John Gruber's Markdown spec says the following about list items:
+
+1. "List markers typically start at the left margin, but may be indented
+ by up to three spaces. List markers must be followed by one or more
+ spaces or a tab."
+
+2. "To make lists look nice, you can wrap items with hanging indents....
+ But if you don't want to, you don't have to."
+
+3. "List items may consist of multiple paragraphs. Each subsequent
+ paragraph in a list item must be indented by either 4 spaces or one
+ tab."
+
+4. "It looks nice if you indent every line of the subsequent paragraphs,
+ but here again, Markdown will allow you to be lazy."
+
+5. "To put a blockquote within a list item, the blockquote's `>`
+ delimiters need to be indented."
+
+6. "To put a code block within a list item, the code block needs to be
+ indented twice — 8 spaces or two tabs."
+
+These rules specify that a paragraph under a list item must be indented
+four spaces (presumably, from the left margin, rather than the start of
+the list marker, but this is not said), and that code under a list item
+must be indented eight spaces instead of the usual four. They also say
+that a block quote must be indented, but not by how much; however, the
+example given has four spaces indentation. Although nothing is said
+about other kinds of block-level content, it is certainly reasonable to
+infer that *all* block elements under a list item, including other
+lists, must be indented four spaces. This principle has been called the
+*four-space rule*.
+
+The four-space rule is clear and principled, and if the reference
+implementation `Markdown.pl` had followed it, it probably would have
+become the standard. However, `Markdown.pl` allowed paragraphs and
+sublists to start with only two spaces indentation, at least on the
+outer level. Worse, its behavior was inconsistent: a sublist of an
+outer-level list needed two spaces indentation, but a sublist of this
+sublist needed three spaces. It is not surprising, then, that different
+implementations of Markdown have developed very different rules for
+determining what comes under a list item. (Pandoc and python-Markdown,
+for example, stuck with Gruber's syntax description and the four-space
+rule, while discount, redcarpet, marked, PHP Markdown, and others
+followed `Markdown.pl`'s behavior more closely.)
+
+Unfortunately, given the divergences between implementations, there
+is no way to give a spec for list items that will be guaranteed not
+to break any existing documents. However, the spec given here should
+correctly handle lists formatted with either the four-space rule or
+the more forgiving `Markdown.pl` behavior, provided they are laid out
+in a way that is natural for a human to read.
+
+The strategy here is to let the width and indentation of the list marker
+determine the indentation necessary for blocks to fall under the list
+item, rather than having a fixed and arbitrary number. The writer can
+think of the body of the list item as a unit which gets indented to the
+right enough to fit the list marker (and any indentation on the list
+marker). (The laziness rule, #5, then allows continuation lines to be
+unindented if needed.)
+
+This rule is superior, we claim, to any rule requiring a fixed level of
+indentation from the margin. The four-space rule is clear but
+unnatural. It is quite unintuitive that
+
+``` markdown
+- foo
+
+ bar
+
+ - baz
+```
+
+should be parsed as two lists with an intervening paragraph,
+
+``` html
+<ul>
+<li>foo</li>
+</ul>
+<p>bar</p>
+<ul>
+<li>baz</li>
+</ul>
+```
+
+as the four-space rule demands, rather than a single list,
+
+``` html
+<ul>
+<li>
+<p>foo</p>
+<p>bar</p>
+<ul>
+<li>baz</li>
+</ul>
+</li>
+</ul>
+```
+
+The choice of four spaces is arbitrary. It can be learned, but it is
+not likely to be guessed, and it trips up beginners regularly.
+
+Would it help to adopt a two-space rule? The problem is that such
+a rule, together with the rule allowing 1--3 spaces indentation of the
+initial list marker, allows text that is indented *less than* the
+original list marker to be included in the list item. For example,
+`Markdown.pl` parses
+
+``` markdown
+ - one
+
+ two
+```
+
+as a single list item, with `two` a continuation paragraph:
+
+``` html
+<ul>
+<li>
+<p>one</p>
+<p>two</p>
+</li>
+</ul>
+```
+
+and similarly
+
+``` markdown
+> - one
+>
+> two
+```
+
+as
+
+``` html
+<blockquote>
+<ul>
+<li>
+<p>one</p>
+<p>two</p>
+</li>
+</ul>
+</blockquote>
+```
+
+This is extremely unintuitive.
+
+Rather than requiring a fixed indent from the margin, we could require
+a fixed indent (say, two spaces, or even one space) from the list marker (which
+may itself be indented). This proposal would remove the last anomaly
+discussed. Unlike the spec presented above, it would count the following
+as a list item with a subparagraph, even though the paragraph `bar`
+is not indented as far as the first paragraph `foo`:
+
+``` markdown
+ 10. foo
+
+ bar
+```
+
+Arguably this text does read like a list item with `bar` as a subparagraph,
+which may count in favor of the proposal. However, on this proposal indented
+code would have to be indented six spaces after the list marker. And this
+would break a lot of existing Markdown, which has the pattern:
+
+``` markdown
+1. foo
+
+ indented code
+```
+
+where the code is indented eight spaces. The spec above, by contrast, will
+parse this text as expected, since the code block's indentation is measured
+from the beginning of `foo`.
+
+The one case that needs special treatment is a list item that *starts*
+with indented code. How much indentation is required in that case, since
+we don't have a "first paragraph" to measure from? Rule #2 simply stipulates
+that in such cases, we require one space indentation from the list marker
+(and then the normal four spaces for the indented code). This will match the
+four-space rule in cases where the list marker plus its initial indentation
+takes four spaces (a common case), but diverge in other cases.
+
+<div class="extension">
+
+## Task list items (extension)
+
+GFM enables the `tasklist` extension, where an additional processing step is
+performed on [list items].
+
+A [task list item](@) is a [list item][list items] where the first block in it
+is a paragraph which begins with a [task list item marker] and at least one
+whitespace character before any other content.
+
+A [task list item marker](@) consists of an optional number of spaces, a left
+bracket (`[`), either a whitespace character or the letter `x` in either
+lowercase or uppercase, and then a right bracket (`]`).
+
+When rendered, the [task list item marker] is replaced with a semantic checkbox element;
+in an HTML output, this would be an `<input type="checkbox">` element.
+
+If the character between the brackets is a whitespace character, the checkbox
+is unchecked. Otherwise, the checkbox is checked.
+
+This spec does not define how the checkbox elements are interacted with: in practice,
+implementors are free to render the checkboxes as disabled or inmutable elements,
+or they may dynamically handle dynamic interactions (i.e. checking, unchecking) in
+the final rendered document.
+
+```````````````````````````````` example disabled
+- [ ] foo
+- [x] bar
+.
+<ul>
+<li><input disabled="" type="checkbox"> foo</li>
+<li><input checked="" disabled="" type="checkbox"> bar</li>
+</ul>
+````````````````````````````````
+
+Task lists can be arbitrarily nested:
+
+```````````````````````````````` example disabled
+- [x] foo
+ - [ ] bar
+ - [x] baz
+- [ ] bim
+.
+<ul>
+<li><input checked="" disabled="" type="checkbox"> foo
+<ul>
+<li><input disabled="" type="checkbox"> bar</li>
+<li><input checked="" disabled="" type="checkbox"> baz</li>
+</ul>
+</li>
+<li><input disabled="" type="checkbox"> bim</li>
+</ul>
+````````````````````````````````
+
+</div>
+
+## Lists
+
+A [list](@) is a sequence of one or more
+list items [of the same type]. The list items
+may be separated by any number of blank lines.
+
+Two list items are [of the same type](@)
+if they begin with a [list marker] of the same type.
+Two list markers are of the
+same type if (a) they are bullet list markers using the same character
+(`-`, `+`, or `*`) or (b) they are ordered list numbers with the same
+delimiter (either `.` or `)`).
+
+A list is an [ordered list](@)
+if its constituent list items begin with
+[ordered list markers], and a
+[bullet list](@) if its constituent list
+items begin with [bullet list markers].
+
+The [start number](@)
+of an [ordered list] is determined by the list number of
+its initial list item. The numbers of subsequent list items are
+disregarded.
+
+A list is [loose](@) if any of its constituent
+list items are separated by blank lines, or if any of its constituent
+list items directly contain two block-level elements with a blank line
+between them. Otherwise a list is [tight](@).
+(The difference in HTML output is that paragraphs in a loose list are
+wrapped in `<p>` tags, while paragraphs in a tight list are not.)
+
+Changing the bullet or ordered list delimiter starts a new list:
+
+```````````````````````````````` example
+- foo
+- bar
++ baz
+.
+<ul>
+<li>foo</li>
+<li>bar</li>
+</ul>
+<ul>
+<li>baz</li>
+</ul>
+````````````````````````````````
+
+
+```````````````````````````````` example
+1. foo
+2. bar
+3) baz
+.
+<ol>
+<li>foo</li>
+<li>bar</li>
+</ol>
+<ol start="3">
+<li>baz</li>
+</ol>
+````````````````````````````````
+
+
+In CommonMark, a list can interrupt a paragraph. That is,
+no blank line is needed to separate a paragraph from a following
+list:
+
+```````````````````````````````` example
+Foo
+- bar
+- baz
+.
+<p>Foo</p>
+<ul>
+<li>bar</li>
+<li>baz</li>
+</ul>
+````````````````````````````````
+
+`Markdown.pl` does not allow this, through fear of triggering a list
+via a numeral in a hard-wrapped line:
+
+``` markdown
+The number of windows in my house is
+14. The number of doors is 6.
+```
+
+Oddly, though, `Markdown.pl` *does* allow a blockquote to
+interrupt a paragraph, even though the same considerations might
+apply.
+
+In CommonMark, we do allow lists to interrupt paragraphs, for
+two reasons. First, it is natural and not uncommon for people
+to start lists without blank lines:
+
+``` markdown
+I need to buy
+- new shoes
+- a coat
+- a plane ticket
+```
+
+Second, we are attracted to a
+
+> [principle of uniformity](@):
+> if a chunk of text has a certain
+> meaning, it will continue to have the same meaning when put into a
+> container block (such as a list item or blockquote).
+
+(Indeed, the spec for [list items] and [block quotes] presupposes
+this principle.) This principle implies that if
+
+``` markdown
+ * I need to buy
+ - new shoes
+ - a coat
+ - a plane ticket
+```
+
+is a list item containing a paragraph followed by a nested sublist,
+as all Markdown implementations agree it is (though the paragraph
+may be rendered without `<p>` tags, since the list is "tight"),
+then
+
+``` markdown
+I need to buy
+- new shoes
+- a coat
+- a plane ticket
+```
+
+by itself should be a paragraph followed by a nested sublist.
+
+Since it is well established Markdown practice to allow lists to
+interrupt paragraphs inside list items, the [principle of
+uniformity] requires us to allow this outside list items as
+well. ([reStructuredText](http://docutils.sourceforge.net/rst.html)
+takes a different approach, requiring blank lines before lists
+even inside other list items.)
+
+In order to solve the problem of unwanted lists in paragraphs with
+hard-wrapped numerals, we allow only lists starting with `1` to
+interrupt paragraphs. Thus,
+
+```````````````````````````````` example
+The number of windows in my house is
+14. The number of doors is 6.
+.
+<p>The number of windows in my house is
+14. The number of doors is 6.</p>
+````````````````````````````````
+
+We may still get an unintended result in cases like
+
+```````````````````````````````` example
+The number of windows in my house is
+1. The number of doors is 6.
+.
+<p>The number of windows in my house is</p>
+<ol>
+<li>The number of doors is 6.</li>
+</ol>
+````````````````````````````````
+
+but this rule should prevent most spurious list captures.
+
+There can be any number of blank lines between items:
+
+```````````````````````````````` example
+- foo
+
+- bar
+
+
+- baz
+.
+<ul>
+<li>
+<p>foo</p>
+</li>
+<li>
+<p>bar</p>
+</li>
+<li>
+<p>baz</p>
+</li>
+</ul>
+````````````````````````````````
+
+```````````````````````````````` example
+- foo
+ - bar
+ - baz
+
+
+ bim
+.
+<ul>
+<li>foo
+<ul>
+<li>bar
+<ul>
+<li>
+<p>baz</p>
+<p>bim</p>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+````````````````````````````````
+
+
+To separate consecutive lists of the same type, or to separate a
+list from an indented code block that would otherwise be parsed
+as a subparagraph of the final list item, you can insert a blank HTML
+comment:
+
+```````````````````````````````` example
+- foo
+- bar
+
+<!-- -->
+
+- baz
+- bim
+.
+<ul>
+<li>foo</li>
+<li>bar</li>
+</ul>
+<!-- -->
+<ul>
+<li>baz</li>
+<li>bim</li>
+</ul>
+````````````````````````````````
+
+
+```````````````````````````````` example
+- foo
+
+ notcode
+
+- foo
+
+<!-- -->
+
+ code
+.
+<ul>
+<li>
+<p>foo</p>
+<p>notcode</p>
+</li>
+<li>
+<p>foo</p>
+</li>
+</ul>
+<!-- -->
+<pre><code>code
+</code></pre>
+````````````````````````````````
+
+
+List items need not be indented to the same level. The following
+list items will be treated as items at the same list level,
+since none is indented enough to belong to the previous list
+item:
+
+```````````````````````````````` example
+- a
+ - b
+ - c
+ - d
+ - e
+ - f
+- g
+.
+<ul>
+<li>a</li>
+<li>b</li>
+<li>c</li>
+<li>d</li>
+<li>e</li>
+<li>f</li>
+<li>g</li>
+</ul>
+````````````````````````````````
+
+
+```````````````````````````````` example
+1. a
+
+ 2. b
+
+ 3. c
+.
+<ol>
+<li>
+<p>a</p>
+</li>
+<li>
+<p>b</p>
+</li>
+<li>
+<p>c</p>
+</li>
+</ol>
+````````````````````````````````
+
+Note, however, that list items may not be indented more than
+three spaces. Here `- e` is treated as a paragraph continuation
+line, because it is indented more than three spaces:
+
+```````````````````````````````` example
+- a
+ - b
+ - c
+ - d
+ - e
+.
+<ul>
+<li>a</li>
+<li>b</li>
+<li>c</li>
+<li>d
+- e</li>
+</ul>
+````````````````````````````````
+
+And here, `3. c` is treated as in indented code block,
+because it is indented four spaces and preceded by a
+blank line.
+
+```````````````````````````````` example
+1. a
+
+ 2. b
+
+ 3. c
+.
+<ol>
+<li>
+<p>a</p>
+</li>
+<li>
+<p>b</p>
+</li>
+</ol>
+<pre><code>3. c
+</code></pre>
+````````````````````````````````
+
+
+This is a loose list, because there is a blank line between
+two of the list items:
+
+```````````````````````````````` example
+- a
+- b
+
+- c
+.
+<ul>
+<li>
+<p>a</p>
+</li>
+<li>
+<p>b</p>
+</li>
+<li>
+<p>c</p>
+</li>
+</ul>
+````````````````````````````````
+
+
+So is this, with a empty second item:
+
+```````````````````````````````` example
+* a
+*
+
+* c
+.
+<ul>
+<li>
+<p>a</p>
+</li>
+<li></li>
+<li>
+<p>c</p>
+</li>
+</ul>
+````````````````````````````````
+
+
+These are loose lists, even though there is no space between the items,
+because one of the items directly contains two block-level elements
+with a blank line between them:
+
+```````````````````````````````` example
+- a
+- b
+
+ c
+- d
+.
+<ul>
+<li>
+<p>a</p>
+</li>
+<li>
+<p>b</p>
+<p>c</p>
+</li>
+<li>
+<p>d</p>
+</li>
+</ul>
+````````````````````````````````
+
+
+```````````````````````````````` example
+- a
+- b
+
+ [ref]: /url
+- d
+.
+<ul>
+<li>
+<p>a</p>
+</li>
+<li>
+<p>b</p>
+</li>
+<li>
+<p>d</p>
+</li>
+</ul>
+````````````````````````````````
+
+
+This is a tight list, because the blank lines are in a code block:
+
+```````````````````````````````` example
+- a
+- ```
+ b
+
+
+ ```
+- c
+.
+<ul>
+<li>a</li>
+<li>
+<pre><code>b
+
+
+</code></pre>
+</li>
+<li>c</li>
+</ul>
+````````````````````````````````
+
+
+This is a tight list, because the blank line is between two
+paragraphs of a sublist. So the sublist is loose while
+the outer list is tight:
+
+```````````````````````````````` example
+- a
+ - b
+
+ c
+- d
+.
+<ul>
+<li>a
+<ul>
+<li>
+<p>b</p>
+<p>c</p>
+</li>
+</ul>
+</li>
+<li>d</li>
+</ul>
+````````````````````````````````
+
+
+This is a tight list, because the blank line is inside the
+block quote:
+
+```````````````````````````````` example
+* a
+ > b
+ >
+* c
+.
+<ul>
+<li>a
+<blockquote>
+<p>b</p>
+</blockquote>
+</li>
+<li>c</li>
+</ul>
+````````````````````````````````
+
+
+This list is tight, because the consecutive block elements
+are not separated by blank lines:
+
+```````````````````````````````` example
+- a
+ > b
+ ```
+ c
+ ```
+- d
+.
+<ul>
+<li>a
+<blockquote>
+<p>b</p>
+</blockquote>
+<pre><code>c
+</code></pre>
+</li>
+<li>d</li>
+</ul>
+````````````````````````````````
+
+
+A single-paragraph list is tight:
+
+```````````````````````````````` example
+- a
+.
+<ul>
+<li>a</li>
+</ul>
+````````````````````````````````
+
+
+```````````````````````````````` example
+- a
+ - b
+.
+<ul>
+<li>a
+<ul>
+<li>b</li>
+</ul>
+</li>
+</ul>
+````````````````````````````````
+
+
+This list is loose, because of the blank line between the
+two block elements in the list item:
+
+```````````````````````````````` example
+1. ```
+ foo
+ ```
+
+ bar
+.
+<ol>
+<li>
+<pre><code>foo
+</code></pre>
+<p>bar</p>
+</li>
+</ol>
+````````````````````````````````
+
+
+Here the outer list is loose, the inner list tight:
+
+```````````````````````````````` example
+* foo
+ * bar
+
+ baz
+.
+<ul>
+<li>
+<p>foo</p>
+<ul>
+<li>bar</li>
+</ul>
+<p>baz</p>
+</li>
+</ul>
+````````````````````````````````
+
+
+```````````````````````````````` example
+- a
+ - b
+ - c
+
+- d
+ - e
+ - f
+.
+<ul>
+<li>
+<p>a</p>
+<ul>
+<li>b</li>
+<li>c</li>
+</ul>
+</li>
+<li>
+<p>d</p>
+<ul>
+<li>e</li>
+<li>f</li>
+</ul>
+</li>
+</ul>
+````````````````````````````````
+
+
+# Inlines
+
+Inlines are parsed sequentially from the beginning of the character
+stream to the end (left to right, in left-to-right languages).
+Thus, for example, in
+
+```````````````````````````````` example
+`hi`lo`
+.
+<p><code>hi</code>lo`</p>
+````````````````````````````````
+
+`hi` is parsed as code, leaving the backtick at the end as a literal
+backtick.
+
+
+## Backslash escapes
+
+Any ASCII punctuation character may be backslash-escaped:
+
+```````````````````````````````` example
+\!\"\#\$\%\&\'\(\)\*\+\,\-\.\/\:\;\<\=\>\?\@\[\\\]\^\_\`\{\|\}\~
+.
+<p>!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~</p>
+````````````````````````````````
+
+
+Backslashes before other characters are treated as literal
+backslashes:
+
+```````````````````````````````` example
+\→\A\a\ \3\φ\«
+.
+<p>\→\A\a\ \3\φ\«</p>
+````````````````````````````````
+
+
+Escaped characters are treated as regular characters and do
+not have their usual Markdown meanings:
+
+```````````````````````````````` example
+\*not emphasized*
+\<br/> not a tag
+\[not a link](/foo)
+\`not code`
+1\. not a list
+\* not a list
+\# not a heading
+\[foo]: /url "not a reference"
+\ö not a character entity
+.
+<p>*not emphasized*
+<br/> not a tag
+[not a link](/foo)
+`not code`
+1. not a list
+* not a list
+# not a heading
+[foo]: /url "not a reference"
+&ouml; not a character entity</p>
+````````````````````````````````
+
+
+If a backslash is itself escaped, the following character is not:
+
+```````````````````````````````` example
+\\*emphasis*
+.
+<p>\<em>emphasis</em></p>
+````````````````````````````````
+
+
+A backslash at the end of the line is a [hard line break]:
+
+```````````````````````````````` example
+foo\
+bar
+.
+<p>foo<br />
+bar</p>
+````````````````````````````````
+
+
+Backslash escapes do not work in code blocks, code spans, autolinks, or
+raw HTML:
+
+```````````````````````````````` example
+`` \[\` ``
+.
+<p><code>\[\`</code></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+ \[\]
+.
+<pre><code>\[\]
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+~~~
+\[\]
+~~~
+.
+<pre><code>\[\]
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<http://example.com?find=\*>
+.
+<p><a href="http://example.com?find=%5C*">http://example.com?find=\*</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<a href="/bar\/)">
+.
+<a href="/bar\/)">
+````````````````````````````````
+
+
+But they work in all other contexts, including URLs and link titles,
+link references, and [info strings] in [fenced code blocks]:
+
+```````````````````````````````` example
+[foo](/bar\* "ti\*tle")
+.
+<p><a href="/bar*" title="ti*tle">foo</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo]
+
+[foo]: /bar\* "ti\*tle"
+.
+<p><a href="/bar*" title="ti*tle">foo</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+``` foo\+bar
+foo
+```
+.
+<pre><code class="language-foo+bar">foo
+</code></pre>
+````````````````````````````````
+
+
+
+## Entity and numeric character references
+
+Valid HTML entity references and numeric character references
+can be used in place of the corresponding Unicode character,
+with the following exceptions:
+
+- Entity and character references are not recognized in code
+ blocks and code spans.
+
+- Entity and character references cannot stand in place of
+ special characters that define structural elements in
+ CommonMark. For example, although `*` can be used
+ in place of a literal `*` character, `*` cannot replace
+ `*` in emphasis delimiters, bullet list markers, or thematic
+ breaks.
+
+Conforming CommonMark parsers need not store information about
+whether a particular character was represented in the source
+using a Unicode character or an entity reference.
+
+[Entity references](@) consist of `&` + any of the valid
+HTML5 entity names + `;`. The
+document <https://html.spec.whatwg.org/multipage/entities.json>
+is used as an authoritative source for the valid entity
+references and their corresponding code points.
+
+```````````````````````````````` example
+ & © Æ Ď
+¾ ℋ ⅆ
+∲ ≧̸
+.
+<p> & © Æ Ď
+¾ ℋ ⅆ
+∲ ≧̸</p>
+````````````````````````````````
+
+
+[Decimal numeric character
+references](@)
+consist of `&#` + a string of 1--7 arabic digits + `;`. A
+numeric character reference is parsed as the corresponding
+Unicode character. Invalid Unicode code points will be replaced by
+the REPLACEMENT CHARACTER (`U+FFFD`). For security reasons,
+the code point `U+0000` will also be replaced by `U+FFFD`.
+
+```````````````````````````````` example
+# Ӓ Ϡ �
+.
+<p># Ӓ Ϡ �</p>
+````````````````````````````````
+
+
+[Hexadecimal numeric character
+references](@) consist of `&#` +
+either `X` or `x` + a string of 1-6 hexadecimal digits + `;`.
+They too are parsed as the corresponding Unicode character (this
+time specified with a hexadecimal numeral instead of decimal).
+
+```````````````````````````````` example
+" ആ ಫ
+.
+<p>" ആ ಫ</p>
+````````````````````````````````
+
+
+Here are some nonentities:
+
+```````````````````````````````` example
+  &x; &#; &#x;
+�
+&#abcdef0;
+&ThisIsNotDefined; &hi?;
+.
+<p>&nbsp &x; &#; &#x;
+&#987654321;
+&#abcdef0;
+&ThisIsNotDefined; &hi?;</p>
+````````````````````````````````
+
+
+Although HTML5 does accept some entity references
+without a trailing semicolon (such as `©`), these are not
+recognized here, because it makes the grammar too ambiguous:
+
+```````````````````````````````` example
+©
+.
+<p>&copy</p>
+````````````````````````````````
+
+
+Strings that are not on the list of HTML5 named entities are not
+recognized as entity references either:
+
+```````````````````````````````` example
+&MadeUpEntity;
+.
+<p>&MadeUpEntity;</p>
+````````````````````````````````
+
+
+Entity and numeric character references are recognized in any
+context besides code spans or code blocks, including
+URLs, [link titles], and [fenced code block][] [info strings]:
+
+```````````````````````````````` example
+<a href="öö.html">
+.
+<a href="öö.html">
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo](/föö "föö")
+.
+<p><a href="/f%C3%B6%C3%B6" title="föö">foo</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo]
+
+[foo]: /föö "föö"
+.
+<p><a href="/f%C3%B6%C3%B6" title="föö">foo</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+``` föö
+foo
+```
+.
+<pre><code class="language-föö">foo
+</code></pre>
+````````````````````````````````
+
+
+Entity and numeric character references are treated as literal
+text in code spans and code blocks:
+
+```````````````````````````````` example
+`föö`
+.
+<p><code>f&ouml;&ouml;</code></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+ föfö
+.
+<pre><code>f&ouml;f&ouml;
+</code></pre>
+````````````````````````````````
+
+
+Entity and numeric character references cannot be used
+in place of symbols indicating structure in CommonMark
+documents.
+
+```````````````````````````````` example
+*foo*
+*foo*
+.
+<p>*foo*
+<em>foo</em></p>
+````````````````````````````````
+
+```````````````````````````````` example
+* foo
+
+* foo
+.
+<p>* foo</p>
+<ul>
+<li>foo</li>
+</ul>
+````````````````````````````````
+
+```````````````````````````````` example
+foo bar
+.
+<p>foo
+
+bar</p>
+````````````````````````````````
+
+```````````````````````````````` example
+	foo
+.
+<p>→foo</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[a](url "tit")
+.
+<p>[a](url "tit")</p>
+````````````````````````````````
+
+
+## Code spans
+
+A [backtick string](@)
+is a string of one or more backtick characters (`` ` ``) that is neither
+preceded nor followed by a backtick.
+
+A [code span](@) begins with a backtick string and ends with
+a backtick string of equal length. The contents of the code span are
+the characters between the two backtick strings, normalized in the
+following ways:
+
+- First, [line endings] are converted to [spaces].
+- If the resulting string both begins *and* ends with a [space]
+ character, but does not consist entirely of [space]
+ characters, a single [space] character is removed from the
+ front and back. This allows you to include code that begins
+ or ends with backtick characters, which must be separated by
+ whitespace from the opening or closing backtick strings.
+
+This is a simple code span:
+
+```````````````````````````````` example
+`foo`
+.
+<p><code>foo</code></p>
+````````````````````````````````
+
+
+Here two backticks are used, because the code contains a backtick.
+This example also illustrates stripping of a single leading and
+trailing space:
+
+```````````````````````````````` example
+`` foo ` bar ``
+.
+<p><code>foo ` bar</code></p>
+````````````````````````````````
+
+
+This example shows the motivation for stripping leading and trailing
+spaces:
+
+```````````````````````````````` example
+` `` `
+.
+<p><code>``</code></p>
+````````````````````````````````
+
+Note that only *one* space is stripped:
+
+```````````````````````````````` example
+` `` `
+.
+<p><code> `` </code></p>
+````````````````````````````````
+
+The stripping only happens if the space is on both
+sides of the string:
+
+```````````````````````````````` example
+` a`
+.
+<p><code> a</code></p>
+````````````````````````````````
+
+Only [spaces], and not [unicode whitespace] in general, are
+stripped in this way:
+
+```````````````````````````````` example
+` b `
+.
+<p><code> b </code></p>
+````````````````````````````````
+
+No stripping occurs if the code span contains only spaces:
+
+```````````````````````````````` example
+` `
+` `
+.
+<p><code> </code>
+<code> </code></p>
+````````````````````````````````
+
+
+[Line endings] are treated like spaces:
+
+```````````````````````````````` example
+``
+foo
+bar
+baz
+``
+.
+<p><code>foo bar baz</code></p>
+````````````````````````````````
+
+```````````````````````````````` example
+``
+foo
+``
+.
+<p><code>foo </code></p>
+````````````````````````````````
+
+
+Interior spaces are not collapsed:
+
+```````````````````````````````` example
+`foo bar
+baz`
+.
+<p><code>foo bar baz</code></p>
+````````````````````````````````
+
+Note that browsers will typically collapse consecutive spaces
+when rendering `<code>` elements, so it is recommended that
+the following CSS be used:
+
+ code{white-space: pre-wrap;}
+
+
+Note that backslash escapes do not work in code spans. All backslashes
+are treated literally:
+
+```````````````````````````````` example
+`foo\`bar`
+.
+<p><code>foo\</code>bar`</p>
+````````````````````````````````
+
+
+Backslash escapes are never needed, because one can always choose a
+string of *n* backtick characters as delimiters, where the code does
+not contain any strings of exactly *n* backtick characters.
+
+```````````````````````````````` example
+``foo`bar``
+.
+<p><code>foo`bar</code></p>
+````````````````````````````````
+
+```````````````````````````````` example
+` foo `` bar `
+.
+<p><code>foo `` bar</code></p>
+````````````````````````````````
+
+
+Code span backticks have higher precedence than any other inline
+constructs except HTML tags and autolinks. Thus, for example, this is
+not parsed as emphasized text, since the second `*` is part of a code
+span:
+
+```````````````````````````````` example
+*foo`*`
+.
+<p>*foo<code>*</code></p>
+````````````````````````````````
+
+
+And this is not parsed as a link:
+
+```````````````````````````````` example
+[not a `link](/foo`)
+.
+<p>[not a <code>link](/foo</code>)</p>
+````````````````````````````````
+
+
+Code spans, HTML tags, and autolinks have the same precedence.
+Thus, this is code:
+
+```````````````````````````````` example
+`<a href="`">`
+.
+<p><code><a href="</code>">`</p>
+````````````````````````````````
+
+
+But this is an HTML tag:
+
+```````````````````````````````` example
+<a href="`">`
+.
+<p><a href="`">`</p>
+````````````````````````````````
+
+
+And this is code:
+
+```````````````````````````````` example
+`<http://foo.bar.`baz>`
+.
+<p><code><http://foo.bar.</code>baz>`</p>
+````````````````````````````````
+
+
+But this is an autolink:
+
+```````````````````````````````` example
+<http://foo.bar.`baz>`
+.
+<p><a href="http://foo.bar.%60baz">http://foo.bar.`baz</a>`</p>
+````````````````````````````````
+
+
+When a backtick string is not closed by a matching backtick string,
+we just have literal backticks:
+
+```````````````````````````````` example
+```foo``
+.
+<p>```foo``</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+`foo
+.
+<p>`foo</p>
+````````````````````````````````
+
+The following case also illustrates the need for opening and
+closing backtick strings to be equal in length:
+
+```````````````````````````````` example
+`foo``bar``
+.
+<p>`foo<code>bar</code></p>
+````````````````````````````````
+
+
+## Emphasis and strong emphasis
+
+John Gruber's original [Markdown syntax
+description](http://daringfireball.net/projects/markdown/syntax#em) says:
+
+> Markdown treats asterisks (`*`) and underscores (`_`) as indicators of
+> emphasis. Text wrapped with one `*` or `_` will be wrapped with an HTML
+> `<em>` tag; double `*`'s or `_`'s will be wrapped with an HTML `<strong>`
+> tag.
+
+This is enough for most users, but these rules leave much undecided,
+especially when it comes to nested emphasis. The original
+`Markdown.pl` test suite makes it clear that triple `***` and
+`___` delimiters can be used for strong emphasis, and most
+implementations have also allowed the following patterns:
+
+``` markdown
+***strong emph***
+***strong** in emph*
+***emph* in strong**
+**in strong *emph***
+*in emph **strong***
+```
+
+The following patterns are less widely supported, but the intent
+is clear and they are useful (especially in contexts like bibliography
+entries):
+
+``` markdown
+*emph *with emph* in it*
+**strong **with strong** in it**
+```
+
+Many implementations have also restricted intraword emphasis to
+the `*` forms, to avoid unwanted emphasis in words containing
+internal underscores. (It is best practice to put these in code
+spans, but users often do not.)
+
+``` markdown
+internal emphasis: foo*bar*baz
+no emphasis: foo_bar_baz
+```
+
+The rules given below capture all of these patterns, while allowing
+for efficient parsing strategies that do not backtrack.
+
+First, some definitions. A [delimiter run](@) is either
+a sequence of one or more `*` characters that is not preceded or
+followed by a non-backslash-escaped `*` character, or a sequence
+of one or more `_` characters that is not preceded or followed by
+a non-backslash-escaped `_` character.
+
+A [left-flanking delimiter run](@) is
+a [delimiter run] that is (1) not followed by [Unicode whitespace],
+and either (2a) not followed by a [punctuation character], or
+(2b) followed by a [punctuation character] and
+preceded by [Unicode whitespace] or a [punctuation character].
+For purposes of this definition, the beginning and the end of
+the line count as Unicode whitespace.
+
+A [right-flanking delimiter run](@) is
+a [delimiter run] that is (1) not preceded by [Unicode whitespace],
+and either (2a) not preceded by a [punctuation character], or
+(2b) preceded by a [punctuation character] and
+followed by [Unicode whitespace] or a [punctuation character].
+For purposes of this definition, the beginning and the end of
+the line count as Unicode whitespace.
+
+Here are some examples of delimiter runs.
+
+ - left-flanking but not right-flanking:
+
+ ```
+ ***abc
+ _abc
+ **"abc"
+ _"abc"
+ ```
+
+ - right-flanking but not left-flanking:
+
+ ```
+ abc***
+ abc_
+ "abc"**
+ "abc"_
+ ```
+
+ - Both left and right-flanking:
+
+ ```
+ abc***def
+ "abc"_"def"
+ ```
+
+ - Neither left nor right-flanking:
+
+ ```
+ abc *** def
+ a _ b
+ ```
+
+(The idea of distinguishing left-flanking and right-flanking
+delimiter runs based on the character before and the character
+after comes from Roopesh Chander's
+[vfmd](http://www.vfmd.org/vfmd-spec/specification/#procedure-for-identifying-emphasis-tags).
+vfmd uses the terminology "emphasis indicator string" instead of "delimiter
+run," and its rules for distinguishing left- and right-flanking runs
+are a bit more complex than the ones given here.)
+
+The following rules define emphasis and strong emphasis:
+
+1. A single `*` character [can open emphasis](@)
+ iff (if and only if) it is part of a [left-flanking delimiter run].
+
+2. A single `_` character [can open emphasis] iff
+ it is part of a [left-flanking delimiter run]
+ and either (a) not part of a [right-flanking delimiter run]
+ or (b) part of a [right-flanking delimiter run]
+ preceded by punctuation.
+
+3. A single `*` character [can close emphasis](@)
+ iff it is part of a [right-flanking delimiter run].
+
+4. A single `_` character [can close emphasis] iff
+ it is part of a [right-flanking delimiter run]
+ and either (a) not part of a [left-flanking delimiter run]
+ or (b) part of a [left-flanking delimiter run]
+ followed by punctuation.
+
+5. A double `**` [can open strong emphasis](@)
+ iff it is part of a [left-flanking delimiter run].
+
+6. A double `__` [can open strong emphasis] iff
+ it is part of a [left-flanking delimiter run]
+ and either (a) not part of a [right-flanking delimiter run]
+ or (b) part of a [right-flanking delimiter run]
+ preceded by punctuation.
+
+7. A double `**` [can close strong emphasis](@)
+ iff it is part of a [right-flanking delimiter run].
+
+8. A double `__` [can close strong emphasis] iff
+ it is part of a [right-flanking delimiter run]
+ and either (a) not part of a [left-flanking delimiter run]
+ or (b) part of a [left-flanking delimiter run]
+ followed by punctuation.
+
+9. Emphasis begins with a delimiter that [can open emphasis] and ends
+ with a delimiter that [can close emphasis], and that uses the same
+ character (`_` or `*`) as the opening delimiter. The
+ opening and closing delimiters must belong to separate
+ [delimiter runs]. If one of the delimiters can both
+ open and close emphasis, then the sum of the lengths of the
+ delimiter runs containing the opening and closing delimiters
+ must not be a multiple of 3 unless both lengths are
+ multiples of 3.
+
+10. Strong emphasis begins with a delimiter that
+ [can open strong emphasis] and ends with a delimiter that
+ [can close strong emphasis], and that uses the same character
+ (`_` or `*`) as the opening delimiter. The
+ opening and closing delimiters must belong to separate
+ [delimiter runs]. If one of the delimiters can both open
+ and close strong emphasis, then the sum of the lengths of
+ the delimiter runs containing the opening and closing
+ delimiters must not be a multiple of 3 unless both lengths
+ are multiples of 3.
+
+11. A literal `*` character cannot occur at the beginning or end of
+ `*`-delimited emphasis or `**`-delimited strong emphasis, unless it
+ is backslash-escaped.
+
+12. A literal `_` character cannot occur at the beginning or end of
+ `_`-delimited emphasis or `__`-delimited strong emphasis, unless it
+ is backslash-escaped.
+
+Where rules 1--12 above are compatible with multiple parsings,
+the following principles resolve ambiguity:
+
+13. The number of nestings should be minimized. Thus, for example,
+ an interpretation `<strong>...</strong>` is always preferred to
+ `<em><em>...</em></em>`.
+
+14. An interpretation `<em><strong>...</strong></em>` is always
+ preferred to `<strong><em>...</em></strong>`.
+
+15. When two potential emphasis or strong emphasis spans overlap,
+ so that the second begins before the first ends and ends after
+ the first ends, the first takes precedence. Thus, for example,
+ `*foo _bar* baz_` is parsed as `<em>foo _bar</em> baz_` rather
+ than `*foo <em>bar* baz</em>`.
+
+16. When there are two potential emphasis or strong emphasis spans
+ with the same closing delimiter, the shorter one (the one that
+ opens later) takes precedence. Thus, for example,
+ `**foo **bar baz**` is parsed as `**foo <strong>bar baz</strong>`
+ rather than `<strong>foo **bar baz</strong>`.
+
+17. Inline code spans, links, images, and HTML tags group more tightly
+ than emphasis. So, when there is a choice between an interpretation
+ that contains one of these elements and one that does not, the
+ former always wins. Thus, for example, `*[foo*](bar)` is
+ parsed as `*<a href="bar">foo*</a>` rather than as
+ `<em>[foo</em>](bar)`.
+
+These rules can be illustrated through a series of examples.
+
+Rule 1:
+
+```````````````````````````````` example
+*foo bar*
+.
+<p><em>foo bar</em></p>
+````````````````````````````````
+
+
+This is not emphasis, because the opening `*` is followed by
+whitespace, and hence not part of a [left-flanking delimiter run]:
+
+```````````````````````````````` example
+a * foo bar*
+.
+<p>a * foo bar*</p>
+````````````````````````````````
+
+
+This is not emphasis, because the opening `*` is preceded
+by an alphanumeric and followed by punctuation, and hence
+not part of a [left-flanking delimiter run]:
+
+```````````````````````````````` example
+a*"foo"*
+.
+<p>a*"foo"*</p>
+````````````````````````````````
+
+
+Unicode nonbreaking spaces count as whitespace, too:
+
+```````````````````````````````` example
+* a *
+.
+<p>* a *</p>
+````````````````````````````````
+
+
+Intraword emphasis with `*` is permitted:
+
+```````````````````````````````` example
+foo*bar*
+.
+<p>foo<em>bar</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+5*6*78
+.
+<p>5<em>6</em>78</p>
+````````````````````````````````
+
+
+Rule 2:
+
+```````````````````````````````` example
+_foo bar_
+.
+<p><em>foo bar</em></p>
+````````````````````````````````
+
+
+This is not emphasis, because the opening `_` is followed by
+whitespace:
+
+```````````````````````````````` example
+_ foo bar_
+.
+<p>_ foo bar_</p>
+````````````````````````````````
+
+
+This is not emphasis, because the opening `_` is preceded
+by an alphanumeric and followed by punctuation:
+
+```````````````````````````````` example
+a_"foo"_
+.
+<p>a_"foo"_</p>
+````````````````````````````````
+
+
+Emphasis with `_` is not allowed inside words:
+
+```````````````````````````````` example
+foo_bar_
+.
+<p>foo_bar_</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+5_6_78
+.
+<p>5_6_78</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+пристаням_стремятся_
+.
+<p>пристаням_стремятся_</p>
+````````````````````````````````
+
+
+Here `_` does not generate emphasis, because the first delimiter run
+is right-flanking and the second left-flanking:
+
+```````````````````````````````` example
+aa_"bb"_cc
+.
+<p>aa_"bb"_cc</p>
+````````````````````````````````
+
+
+This is emphasis, even though the opening delimiter is
+both left- and right-flanking, because it is preceded by
+punctuation:
+
+```````````````````````````````` example
+foo-_(bar)_
+.
+<p>foo-<em>(bar)</em></p>
+````````````````````````````````
+
+
+Rule 3:
+
+This is not emphasis, because the closing delimiter does
+not match the opening delimiter:
+
+```````````````````````````````` example
+_foo*
+.
+<p>_foo*</p>
+````````````````````````````````
+
+
+This is not emphasis, because the closing `*` is preceded by
+whitespace:
+
+```````````````````````````````` example
+*foo bar *
+.
+<p>*foo bar *</p>
+````````````````````````````````
+
+
+A newline also counts as whitespace:
+
+```````````````````````````````` example
+*foo bar
+*
+.
+<p>*foo bar
+*</p>
+````````````````````````````````
+
+
+This is not emphasis, because the second `*` is
+preceded by punctuation and followed by an alphanumeric
+(hence it is not part of a [right-flanking delimiter run]:
+
+```````````````````````````````` example
+*(*foo)
+.
+<p>*(*foo)</p>
+````````````````````````````````
+
+
+The point of this restriction is more easily appreciated
+with this example:
+
+```````````````````````````````` example
+*(*foo*)*
+.
+<p><em>(<em>foo</em>)</em></p>
+````````````````````````````````
+
+
+Intraword emphasis with `*` is allowed:
+
+```````````````````````````````` example
+*foo*bar
+.
+<p><em>foo</em>bar</p>
+````````````````````````````````
+
+
+
+Rule 4:
+
+This is not emphasis, because the closing `_` is preceded by
+whitespace:
+
+```````````````````````````````` example
+_foo bar _
+.
+<p>_foo bar _</p>
+````````````````````````````````
+
+
+This is not emphasis, because the second `_` is
+preceded by punctuation and followed by an alphanumeric:
+
+```````````````````````````````` example
+_(_foo)
+.
+<p>_(_foo)</p>
+````````````````````````````````
+
+
+This is emphasis within emphasis:
+
+```````````````````````````````` example
+_(_foo_)_
+.
+<p><em>(<em>foo</em>)</em></p>
+````````````````````````````````
+
+
+Intraword emphasis is disallowed for `_`:
+
+```````````````````````````````` example
+_foo_bar
+.
+<p>_foo_bar</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+_пристаням_стремятся
+.
+<p>_пристаням_стремятся</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+_foo_bar_baz_
+.
+<p><em>foo_bar_baz</em></p>
+````````````````````````````````
+
+
+This is emphasis, even though the closing delimiter is
+both left- and right-flanking, because it is followed by
+punctuation:
+
+```````````````````````````````` example
+_(bar)_.
+.
+<p><em>(bar)</em>.</p>
+````````````````````````````````
+
+
+Rule 5:
+
+```````````````````````````````` example
+**foo bar**
+.
+<p><strong>foo bar</strong></p>
+````````````````````````````````
+
+
+This is not strong emphasis, because the opening delimiter is
+followed by whitespace:
+
+```````````````````````````````` example
+** foo bar**
+.
+<p>** foo bar**</p>
+````````````````````````````````
+
+
+This is not strong emphasis, because the opening `**` is preceded
+by an alphanumeric and followed by punctuation, and hence
+not part of a [left-flanking delimiter run]:
+
+```````````````````````````````` example
+a**"foo"**
+.
+<p>a**"foo"**</p>
+````````````````````````````````
+
+
+Intraword strong emphasis with `**` is permitted:
+
+```````````````````````````````` example
+foo**bar**
+.
+<p>foo<strong>bar</strong></p>
+````````````````````````````````
+
+
+Rule 6:
+
+```````````````````````````````` example
+__foo bar__
+.
+<p><strong>foo bar</strong></p>
+````````````````````````````````
+
+
+This is not strong emphasis, because the opening delimiter is
+followed by whitespace:
+
+```````````````````````````````` example
+__ foo bar__
+.
+<p>__ foo bar__</p>
+````````````````````````````````
+
+
+A newline counts as whitespace:
+```````````````````````````````` example
+__
+foo bar__
+.
+<p>__
+foo bar__</p>
+````````````````````````````````
+
+
+This is not strong emphasis, because the opening `__` is preceded
+by an alphanumeric and followed by punctuation:
+
+```````````````````````````````` example
+a__"foo"__
+.
+<p>a__"foo"__</p>
+````````````````````````````````
+
+
+Intraword strong emphasis is forbidden with `__`:
+
+```````````````````````````````` example
+foo__bar__
+.
+<p>foo__bar__</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+5__6__78
+.
+<p>5__6__78</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+пристаням__стремятся__
+.
+<p>пристаням__стремятся__</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+__foo, __bar__, baz__
+.
+<p><strong>foo, bar, baz</strong></p>
+````````````````````````````````
+
+
+This is strong emphasis, even though the opening delimiter is
+both left- and right-flanking, because it is preceded by
+punctuation:
+
+```````````````````````````````` example
+foo-__(bar)__
+.
+<p>foo-<strong>(bar)</strong></p>
+````````````````````````````````
+
+
+
+Rule 7:
+
+This is not strong emphasis, because the closing delimiter is preceded
+by whitespace:
+
+```````````````````````````````` example
+**foo bar **
+.
+<p>**foo bar **</p>
+````````````````````````````````
+
+
+(Nor can it be interpreted as an emphasized `*foo bar *`, because of
+Rule 11.)
+
+This is not strong emphasis, because the second `**` is
+preceded by punctuation and followed by an alphanumeric:
+
+```````````````````````````````` example
+**(**foo)
+.
+<p>**(**foo)</p>
+````````````````````````````````
+
+
+The point of this restriction is more easily appreciated
+with these examples:
+
+```````````````````````````````` example
+*(**foo**)*
+.
+<p><em>(<strong>foo</strong>)</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+**Gomphocarpus (*Gomphocarpus physocarpus*, syn.
+*Asclepias physocarpa*)**
+.
+<p><strong>Gomphocarpus (<em>Gomphocarpus physocarpus</em>, syn.
+<em>Asclepias physocarpa</em>)</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+**foo "*bar*" foo**
+.
+<p><strong>foo "<em>bar</em>" foo</strong></p>
+````````````````````````````````
+
+
+Intraword emphasis:
+
+```````````````````````````````` example
+**foo**bar
+.
+<p><strong>foo</strong>bar</p>
+````````````````````````````````
+
+
+Rule 8:
+
+This is not strong emphasis, because the closing delimiter is
+preceded by whitespace:
+
+```````````````````````````````` example
+__foo bar __
+.
+<p>__foo bar __</p>
+````````````````````````````````
+
+
+This is not strong emphasis, because the second `__` is
+preceded by punctuation and followed by an alphanumeric:
+
+```````````````````````````````` example
+__(__foo)
+.
+<p>__(__foo)</p>
+````````````````````````````````
+
+
+The point of this restriction is more easily appreciated
+with this example:
+
+```````````````````````````````` example
+_(__foo__)_
+.
+<p><em>(<strong>foo</strong>)</em></p>
+````````````````````````````````
+
+
+Intraword strong emphasis is forbidden with `__`:
+
+```````````````````````````````` example
+__foo__bar
+.
+<p>__foo__bar</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+__пристаням__стремятся
+.
+<p>__пристаням__стремятся</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+__foo__bar__baz__
+.
+<p><strong>foo__bar__baz</strong></p>
+````````````````````````````````
+
+
+This is strong emphasis, even though the closing delimiter is
+both left- and right-flanking, because it is followed by
+punctuation:
+
+```````````````````````````````` example
+__(bar)__.
+.
+<p><strong>(bar)</strong>.</p>
+````````````````````````````````
+
+
+Rule 9:
+
+Any nonempty sequence of inline elements can be the contents of an
+emphasized span.
+
+```````````````````````````````` example
+*foo [bar](/url)*
+.
+<p><em>foo <a href="/url">bar</a></em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*foo
+bar*
+.
+<p><em>foo
+bar</em></p>
+````````````````````````````````
+
+
+In particular, emphasis and strong emphasis can be nested
+inside emphasis:
+
+```````````````````````````````` example
+_foo __bar__ baz_
+.
+<p><em>foo <strong>bar</strong> baz</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+_foo _bar_ baz_
+.
+<p><em>foo <em>bar</em> baz</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+__foo_ bar_
+.
+<p><em><em>foo</em> bar</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*foo *bar**
+.
+<p><em>foo <em>bar</em></em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*foo **bar** baz*
+.
+<p><em>foo <strong>bar</strong> baz</em></p>
+````````````````````````````````
+
+```````````````````````````````` example
+*foo**bar**baz*
+.
+<p><em>foo<strong>bar</strong>baz</em></p>
+````````````````````````````````
+
+Note that in the preceding case, the interpretation
+
+``` markdown
+<p><em>foo</em><em>bar<em></em>baz</em></p>
+```
+
+
+is precluded by the condition that a delimiter that
+can both open and close (like the `*` after `foo`)
+cannot form emphasis if the sum of the lengths of
+the delimiter runs containing the opening and
+closing delimiters is a multiple of 3 unless
+both lengths are multiples of 3.
+
+
+For the same reason, we don't get two consecutive
+emphasis sections in this example:
+
+```````````````````````````````` example
+*foo**bar*
+.
+<p><em>foo**bar</em></p>
+````````````````````````````````
+
+
+The same condition ensures that the following
+cases are all strong emphasis nested inside
+emphasis, even when the interior spaces are
+omitted:
+
+
+```````````````````````````````` example
+***foo** bar*
+.
+<p><em><strong>foo</strong> bar</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*foo **bar***
+.
+<p><em>foo <strong>bar</strong></em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*foo**bar***
+.
+<p><em>foo<strong>bar</strong></em></p>
+````````````````````````````````
+
+
+When the lengths of the interior closing and opening
+delimiter runs are *both* multiples of 3, though,
+they can match to create emphasis:
+
+```````````````````````````````` example
+foo***bar***baz
+.
+<p>foo<em><strong>bar</strong></em>baz</p>
+````````````````````````````````
+
+```````````````````````````````` example
+foo******bar*********baz
+.
+<p>foo<strong>bar</strong>***baz</p>
+````````````````````````````````
+
+
+Indefinite levels of nesting are possible:
+
+```````````````````````````````` example
+*foo **bar *baz* bim** bop*
+.
+<p><em>foo <strong>bar <em>baz</em> bim</strong> bop</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*foo [*bar*](/url)*
+.
+<p><em>foo <a href="/url"><em>bar</em></a></em></p>
+````````````````````````````````
+
+
+There can be no empty emphasis or strong emphasis:
+
+```````````````````````````````` example
+** is not an empty emphasis
+.
+<p>** is not an empty emphasis</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+**** is not an empty strong emphasis
+.
+<p>**** is not an empty strong emphasis</p>
+````````````````````````````````
+
+
+
+Rule 10:
+
+Any nonempty sequence of inline elements can be the contents of an
+strongly emphasized span.
+
+```````````````````````````````` example
+**foo [bar](/url)**
+.
+<p><strong>foo <a href="/url">bar</a></strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+**foo
+bar**
+.
+<p><strong>foo
+bar</strong></p>
+````````````````````````````````
+
+
+In particular, emphasis and strong emphasis can be nested
+inside strong emphasis:
+
+```````````````````````````````` example
+__foo _bar_ baz__
+.
+<p><strong>foo <em>bar</em> baz</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+__foo __bar__ baz__
+.
+<p><strong>foo bar baz</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+____foo__ bar__
+.
+<p><strong>foo bar</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+**foo **bar****
+.
+<p><strong>foo bar</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+**foo *bar* baz**
+.
+<p><strong>foo <em>bar</em> baz</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+**foo*bar*baz**
+.
+<p><strong>foo<em>bar</em>baz</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+***foo* bar**
+.
+<p><strong><em>foo</em> bar</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+**foo *bar***
+.
+<p><strong>foo <em>bar</em></strong></p>
+````````````````````````````````
+
+
+Indefinite levels of nesting are possible:
+
+```````````````````````````````` example
+**foo *bar **baz**
+bim* bop**
+.
+<p><strong>foo <em>bar <strong>baz</strong>
+bim</em> bop</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+**foo [*bar*](/url)**
+.
+<p><strong>foo <a href="/url"><em>bar</em></a></strong></p>
+````````````````````````````````
+
+
+There can be no empty emphasis or strong emphasis:
+
+```````````````````````````````` example
+__ is not an empty emphasis
+.
+<p>__ is not an empty emphasis</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+____ is not an empty strong emphasis
+.
+<p>____ is not an empty strong emphasis</p>
+````````````````````````````````
+
+
+
+Rule 11:
+
+```````````````````````````````` example
+foo ***
+.
+<p>foo ***</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo *\**
+.
+<p>foo <em>*</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo *_*
+.
+<p>foo <em>_</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo *****
+.
+<p>foo *****</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo **\***
+.
+<p>foo <strong>*</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo **_**
+.
+<p>foo <strong>_</strong></p>
+````````````````````````````````
+
+
+Note that when delimiters do not match evenly, Rule 11 determines
+that the excess literal `*` characters will appear outside of the
+emphasis, rather than inside it:
+
+```````````````````````````````` example
+**foo*
+.
+<p>*<em>foo</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*foo**
+.
+<p><em>foo</em>*</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+***foo**
+.
+<p>*<strong>foo</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+****foo*
+.
+<p>***<em>foo</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+**foo***
+.
+<p><strong>foo</strong>*</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*foo****
+.
+<p><em>foo</em>***</p>
+````````````````````````````````
+
+
+
+Rule 12:
+
+```````````````````````````````` example
+foo ___
+.
+<p>foo ___</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo _\__
+.
+<p>foo <em>_</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo _*_
+.
+<p>foo <em>*</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo _____
+.
+<p>foo _____</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo __\___
+.
+<p>foo <strong>_</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo __*__
+.
+<p>foo <strong>*</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+__foo_
+.
+<p>_<em>foo</em></p>
+````````````````````````````````
+
+
+Note that when delimiters do not match evenly, Rule 12 determines
+that the excess literal `_` characters will appear outside of the
+emphasis, rather than inside it:
+
+```````````````````````````````` example
+_foo__
+.
+<p><em>foo</em>_</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+___foo__
+.
+<p>_<strong>foo</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+____foo_
+.
+<p>___<em>foo</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+__foo___
+.
+<p><strong>foo</strong>_</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+_foo____
+.
+<p><em>foo</em>___</p>
+````````````````````````````````
+
+
+Rule 13 implies that if you want emphasis nested directly inside
+emphasis, you must use different delimiters:
+
+```````````````````````````````` example
+**foo**
+.
+<p><strong>foo</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*_foo_*
+.
+<p><em><em>foo</em></em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+__foo__
+.
+<p><strong>foo</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+_*foo*_
+.
+<p><em><em>foo</em></em></p>
+````````````````````````````````
+
+
+However, strong emphasis within strong emphasis is possible without
+switching delimiters:
+
+```````````````````````````````` example
+****foo****
+.
+<p><strong>foo</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+____foo____
+.
+<p><strong>foo</strong></p>
+````````````````````````````````
+
+
+
+Rule 13 can be applied to arbitrarily long sequences of
+delimiters:
+
+```````````````````````````````` example
+******foo******
+.
+<p><strong>foo</strong></p>
+````````````````````````````````
+
+
+Rule 14:
+
+```````````````````````````````` example
+***foo***
+.
+<p><em><strong>foo</strong></em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+_____foo_____
+.
+<p><em><strong>foo</strong></em></p>
+````````````````````````````````
+
+
+Rule 15:
+
+```````````````````````````````` example
+*foo _bar* baz_
+.
+<p><em>foo _bar</em> baz_</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*foo __bar *baz bim__ bam*
+.
+<p><em>foo <strong>bar *baz bim</strong> bam</em></p>
+````````````````````````````````
+
+
+Rule 16:
+
+```````````````````````````````` example
+**foo **bar baz**
+.
+<p>**foo <strong>bar baz</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*foo *bar baz*
+.
+<p>*foo <em>bar baz</em></p>
+````````````````````````````````
+
+
+Rule 17:
+
+```````````````````````````````` example
+*[bar*](/url)
+.
+<p>*<a href="/url">bar*</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+_foo [bar_](/url)
+.
+<p>_foo <a href="/url">bar_</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*<img src="foo" title="*"/>
+.
+<p>*<img src="foo" title="*"/></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+**<a href="**">
+.
+<p>**<a href="**"></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+__<a href="__">
+.
+<p>__<a href="__"></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*a `*`*
+.
+<p><em>a <code>*</code></em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+_a `_`_
+.
+<p><em>a <code>_</code></em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+**a<http://foo.bar/?q=**>
+.
+<p>**a<a href="http://foo.bar/?q=**">http://foo.bar/?q=**</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+__a<http://foo.bar/?q=__>
+.
+<p>__a<a href="http://foo.bar/?q=__">http://foo.bar/?q=__</a></p>
+````````````````````````````````
+
+
+<div class="extension">
+
+## Strikethrough (extension)
+
+GFM enables the `strikethrough` extension, where an additional emphasis type is
+available.
+
+Strikethrough text is any text wrapped in two tildes (`~`).
+
+```````````````````````````````` example strikethrough
+~~Hi~~ Hello, world!
+.
+<p><del>Hi</del> Hello, world!</p>
+````````````````````````````````
+
+As with regular emphasis delimiters, a new paragraph will cause strikethrough
+parsing to cease:
+
+```````````````````````````````` example strikethrough
+This ~~has a
+
+new paragraph~~.
+.
+<p>This ~~has a</p>
+<p>new paragraph~~.</p>
+````````````````````````````````
+
+</div>
+
+## Links
+
+A link contains [link text] (the visible text), a [link destination]
+(the URI that is the link destination), and optionally a [link title].
+There are two basic kinds of links in Markdown. In [inline links] the
+destination and title are given immediately after the link text. In
+[reference links] the destination and title are defined elsewhere in
+the document.
+
+A [link text](@) consists of a sequence of zero or more
+inline elements enclosed by square brackets (`[` and `]`). The
+following rules apply:
+
+- Links may not contain other links, at any level of nesting. If
+ multiple otherwise valid link definitions appear nested inside each
+ other, the inner-most definition is used.
+
+- Brackets are allowed in the [link text] only if (a) they
+ are backslash-escaped or (b) they appear as a matched pair of brackets,
+ with an open bracket `[`, a sequence of zero or more inlines, and
+ a close bracket `]`.
+
+- Backtick [code spans], [autolinks], and raw [HTML tags] bind more tightly
+ than the brackets in link text. Thus, for example,
+ `` [foo`]` `` could not be a link text, since the second `]`
+ is part of a code span.
+
+- The brackets in link text bind more tightly than markers for
+ [emphasis and strong emphasis]. Thus, for example, `*[foo*](url)` is a link.
+
+A [link destination](@) consists of either
+
+- a sequence of zero or more characters between an opening `<` and a
+ closing `>` that contains no line breaks or unescaped
+ `<` or `>` characters, or
+
+- a nonempty sequence of characters that does not start with
+ `<`, does not include ASCII space or control characters, and
+ includes parentheses only if (a) they are backslash-escaped or
+ (b) they are part of a balanced pair of unescaped parentheses.
+ (Implementations may impose limits on parentheses nesting to
+ avoid performance issues, but at least three levels of nesting
+ should be supported.)
+
+A [link title](@) consists of either
+
+- a sequence of zero or more characters between straight double-quote
+ characters (`"`), including a `"` character only if it is
+ backslash-escaped, or
+
+- a sequence of zero or more characters between straight single-quote
+ characters (`'`), including a `'` character only if it is
+ backslash-escaped, or
+
+- a sequence of zero or more characters between matching parentheses
+ (`(...)`), including a `(` or `)` character only if it is
+ backslash-escaped.
+
+Although [link titles] may span multiple lines, they may not contain
+a [blank line].
+
+An [inline link](@) consists of a [link text] followed immediately
+by a left parenthesis `(`, optional [whitespace], an optional
+[link destination], an optional [link title] separated from the link
+destination by [whitespace], optional [whitespace], and a right
+parenthesis `)`. The link's text consists of the inlines contained
+in the [link text] (excluding the enclosing square brackets).
+The link's URI consists of the link destination, excluding enclosing
+`<...>` if present, with backslash-escapes in effect as described
+above. The link's title consists of the link title, excluding its
+enclosing delimiters, with backslash-escapes in effect as described
+above.
+
+Here is a simple inline link:
+
+```````````````````````````````` example
+[link](/uri "title")
+.
+<p><a href="/uri" title="title">link</a></p>
+````````````````````````````````
+
+
+The title may be omitted:
+
+```````````````````````````````` example
+[link](/uri)
+.
+<p><a href="/uri">link</a></p>
+````````````````````````````````
+
+
+Both the title and the destination may be omitted:
+
+```````````````````````````````` example
+[link]()
+.
+<p><a href="">link</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[link](<>)
+.
+<p><a href="">link</a></p>
+````````````````````````````````
+
+The destination can only contain spaces if it is
+enclosed in pointy brackets:
+
+```````````````````````````````` example
+[link](/my uri)
+.
+<p>[link](/my uri)</p>
+````````````````````````````````
+
+```````````````````````````````` example
+[link](</my uri>)
+.
+<p><a href="/my%20uri">link</a></p>
+````````````````````````````````
+
+The destination cannot contain line breaks,
+even if enclosed in pointy brackets:
+
+```````````````````````````````` example
+[link](foo
+bar)
+.
+<p>[link](foo
+bar)</p>
+````````````````````````````````
+
+```````````````````````````````` example
+[link](<foo
+bar>)
+.
+<p>[link](<foo
+bar>)</p>
+````````````````````````````````
+
+The destination can contain `)` if it is enclosed
+in pointy brackets:
+
+```````````````````````````````` example
+[a](<b)c>)
+.
+<p><a href="b)c">a</a></p>
+````````````````````````````````
+
+Pointy brackets that enclose links must be unescaped:
+
+```````````````````````````````` example
+[link](<foo\>)
+.
+<p>[link](<foo>)</p>
+````````````````````````````````
+
+These are not links, because the opening pointy bracket
+is not matched properly:
+
+```````````````````````````````` example
+[a](<b)c
+[a](<b)c>
+[a](<b>c)
+.
+<p>[a](<b)c
+[a](<b)c>
+[a](<b>c)</p>
+````````````````````````````````
+
+Parentheses inside the link destination may be escaped:
+
+```````````````````````````````` example
+[link](\(foo\))
+.
+<p><a href="(foo)">link</a></p>
+````````````````````````````````
+
+Any number of parentheses are allowed without escaping, as long as they are
+balanced:
+
+```````````````````````````````` example
+[link](foo(and(bar)))
+.
+<p><a href="foo(and(bar))">link</a></p>
+````````````````````````````````
+
+However, if you have unbalanced parentheses, you need to escape or use the
+`<...>` form:
+
+```````````````````````````````` example
+[link](foo\(and\(bar\))
+.
+<p><a href="foo(and(bar)">link</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[link](<foo(and(bar)>)
+.
+<p><a href="foo(and(bar)">link</a></p>
+````````````````````````````````
+
+
+Parentheses and other symbols can also be escaped, as usual
+in Markdown:
+
+```````````````````````````````` example
+[link](foo\)\:)
+.
+<p><a href="foo):">link</a></p>
+````````````````````````````````
+
+
+A link can contain fragment identifiers and queries:
+
+```````````````````````````````` example
+[link](#fragment)
+
+[link](http://example.com#fragment)
+
+[link](http://example.com?foo=3#frag)
+.
+<p><a href="#fragment">link</a></p>
+<p><a href="http://example.com#fragment">link</a></p>
+<p><a href="http://example.com?foo=3#frag">link</a></p>
+````````````````````````````````
+
+
+Note that a backslash before a non-escapable character is
+just a backslash:
+
+```````````````````````````````` example
+[link](foo\bar)
+.
+<p><a href="foo%5Cbar">link</a></p>
+````````````````````````````````
+
+
+URL-escaping should be left alone inside the destination, as all
+URL-escaped characters are also valid URL characters. Entity and
+numerical character references in the destination will be parsed
+into the corresponding Unicode code points, as usual. These may
+be optionally URL-escaped when written as HTML, but this spec
+does not enforce any particular policy for rendering URLs in
+HTML or other formats. Renderers may make different decisions
+about how to escape or normalize URLs in the output.
+
+```````````````````````````````` example
+[link](foo%20bä)
+.
+<p><a href="foo%20b%C3%A4">link</a></p>
+````````````````````````````````
+
+
+Note that, because titles can often be parsed as destinations,
+if you try to omit the destination and keep the title, you'll
+get unexpected results:
+
+```````````````````````````````` example
+[link]("title")
+.
+<p><a href="%22title%22">link</a></p>
+````````````````````````````````
+
+
+Titles may be in single quotes, double quotes, or parentheses:
+
+```````````````````````````````` example
+[link](/url "title")
+[link](/url 'title')
+[link](/url (title))
+.
+<p><a href="/url" title="title">link</a>
+<a href="/url" title="title">link</a>
+<a href="/url" title="title">link</a></p>
+````````````````````````````````
+
+
+Backslash escapes and entity and numeric character references
+may be used in titles:
+
+```````````````````````````````` example
+[link](/url "title \""")
+.
+<p><a href="/url" title="title """>link</a></p>
+````````````````````````````````
+
+
+Titles must be separated from the link using a [whitespace].
+Other [Unicode whitespace] like non-breaking space doesn't work.
+
+```````````````````````````````` example
+[link](/url "title")
+.
+<p><a href="/url%C2%A0%22title%22">link</a></p>
+````````````````````````````````
+
+
+Nested balanced quotes are not allowed without escaping:
+
+```````````````````````````````` example
+[link](/url "title "and" title")
+.
+<p>[link](/url "title "and" title")</p>
+````````````````````````````````
+
+
+But it is easy to work around this by using a different quote type:
+
+```````````````````````````````` example
+[link](/url 'title "and" title')
+.
+<p><a href="/url" title="title "and" title">link</a></p>
+````````````````````````````````
+
+
+(Note: `Markdown.pl` did allow double quotes inside a double-quoted
+title, and its test suite included a test demonstrating this.
+But it is hard to see a good rationale for the extra complexity this
+brings, since there are already many ways---backslash escaping,
+entity and numeric character references, or using a different
+quote type for the enclosing title---to write titles containing
+double quotes. `Markdown.pl`'s handling of titles has a number
+of other strange features. For example, it allows single-quoted
+titles in inline links, but not reference links. And, in
+reference links but not inline links, it allows a title to begin
+with `"` and end with `)`. `Markdown.pl` 1.0.1 even allows
+titles with no closing quotation mark, though 1.0.2b8 does not.
+It seems preferable to adopt a simple, rational rule that works
+the same way in inline links and link reference definitions.)
+
+[Whitespace] is allowed around the destination and title:
+
+```````````````````````````````` example
+[link]( /uri
+ "title" )
+.
+<p><a href="/uri" title="title">link</a></p>
+````````````````````````````````
+
+
+But it is not allowed between the link text and the
+following parenthesis:
+
+```````````````````````````````` example
+[link] (/uri)
+.
+<p>[link] (/uri)</p>
+````````````````````````````````
+
+
+The link text may contain balanced brackets, but not unbalanced ones,
+unless they are escaped:
+
+```````````````````````````````` example
+[link [foo [bar]]](/uri)
+.
+<p><a href="/uri">link [foo [bar]]</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[link] bar](/uri)
+.
+<p>[link] bar](/uri)</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[link [bar](/uri)
+.
+<p>[link <a href="/uri">bar</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[link \[bar](/uri)
+.
+<p><a href="/uri">link [bar</a></p>
+````````````````````````````````
+
+
+The link text may contain inline content:
+
+```````````````````````````````` example
+[link *foo **bar** `#`*](/uri)
+.
+<p><a href="/uri">link <em>foo <strong>bar</strong> <code>#</code></em></a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[](/uri)
+.
+<p><a href="/uri"><img src="moon.jpg" alt="moon" /></a></p>
+````````````````````````````````
+
+
+However, links may not contain other links, at any level of nesting.
+
+```````````````````````````````` example
+[foo [bar](/uri)](/uri)
+.
+<p>[foo <a href="/uri">bar</a>](/uri)</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo *[bar [baz](/uri)](/uri)*](/uri)
+.
+<p>[foo <em>[bar <a href="/uri">baz</a>](/uri)</em>](/uri)</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+](uri2)](uri3)
+.
+<p><img src="uri3" alt="[foo](uri2)" /></p>
+````````````````````````````````
+
+
+These cases illustrate the precedence of link text grouping over
+emphasis grouping:
+
+```````````````````````````````` example
+*[foo*](/uri)
+.
+<p>*<a href="/uri">foo*</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo *bar](baz*)
+.
+<p><a href="baz*">foo *bar</a></p>
+````````````````````````````````
+
+
+Note that brackets that *aren't* part of links do not take
+precedence:
+
+```````````````````````````````` example
+*foo [bar* baz]
+.
+<p><em>foo [bar</em> baz]</p>
+````````````````````````````````
+
+
+These cases illustrate the precedence of HTML tags, code spans,
+and autolinks over link grouping:
+
+```````````````````````````````` example
+[foo <bar attr="](baz)">
+.
+<p>[foo <bar attr="](baz)"></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo`](/uri)`
+.
+<p>[foo<code>](/uri)</code></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo<http://example.com/?search=](uri)>
+.
+<p>[foo<a href="http://example.com/?search=%5D(uri)">http://example.com/?search=](uri)</a></p>
+````````````````````````````````
+
+
+There are three kinds of [reference link](@)s:
+[full](#full-reference-link), [collapsed](#collapsed-reference-link),
+and [shortcut](#shortcut-reference-link).
+
+A [full reference link](@)
+consists of a [link text] immediately followed by a [link label]
+that [matches] a [link reference definition] elsewhere in the document.
+
+A [link label](@) begins with a left bracket (`[`) and ends
+with the first right bracket (`]`) that is not backslash-escaped.
+Between these brackets there must be at least one [non-whitespace character].
+Unescaped square bracket characters are not allowed inside the
+opening and closing square brackets of [link labels]. A link
+label can have at most 999 characters inside the square
+brackets.
+
+One label [matches](@)
+another just in case their normalized forms are equal. To normalize a
+label, strip off the opening and closing brackets,
+perform the *Unicode case fold*, strip leading and trailing
+[whitespace] and collapse consecutive internal
+[whitespace] to a single space. If there are multiple
+matching reference link definitions, the one that comes first in the
+document is used. (It is desirable in such cases to emit a warning.)
+
+The contents of the first link label are parsed as inlines, which are
+used as the link's text. The link's URI and title are provided by the
+matching [link reference definition].
+
+Here is a simple example:
+
+```````````````````````````````` example
+[foo][bar]
+
+[bar]: /url "title"
+.
+<p><a href="/url" title="title">foo</a></p>
+````````````````````````````````
+
+
+The rules for the [link text] are the same as with
+[inline links]. Thus:
+
+The link text may contain balanced brackets, but not unbalanced ones,
+unless they are escaped:
+
+```````````````````````````````` example
+[link [foo [bar]]][ref]
+
+[ref]: /uri
+.
+<p><a href="/uri">link [foo [bar]]</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[link \[bar][ref]
+
+[ref]: /uri
+.
+<p><a href="/uri">link [bar</a></p>
+````````````````````````````````
+
+
+The link text may contain inline content:
+
+```````````````````````````````` example
+[link *foo **bar** `#`*][ref]
+
+[ref]: /uri
+.
+<p><a href="/uri">link <em>foo <strong>bar</strong> <code>#</code></em></a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[][ref]
+
+[ref]: /uri
+.
+<p><a href="/uri"><img src="moon.jpg" alt="moon" /></a></p>
+````````````````````````````````
+
+
+However, links may not contain other links, at any level of nesting.
+
+```````````````````````````````` example
+[foo [bar](/uri)][ref]
+
+[ref]: /uri
+.
+<p>[foo <a href="/uri">bar</a>]<a href="/uri">ref</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo *bar [baz][ref]*][ref]
+
+[ref]: /uri
+.
+<p>[foo <em>bar <a href="/uri">baz</a></em>]<a href="/uri">ref</a></p>
+````````````````````````````````
+
+
+(In the examples above, we have two [shortcut reference links]
+instead of one [full reference link].)
+
+The following cases illustrate the precedence of link text grouping over
+emphasis grouping:
+
+```````````````````````````````` example
+*[foo*][ref]
+
+[ref]: /uri
+.
+<p>*<a href="/uri">foo*</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo *bar][ref]
+
+[ref]: /uri
+.
+<p><a href="/uri">foo *bar</a></p>
+````````````````````````````````
+
+
+These cases illustrate the precedence of HTML tags, code spans,
+and autolinks over link grouping:
+
+```````````````````````````````` example
+[foo <bar attr="][ref]">
+
+[ref]: /uri
+.
+<p>[foo <bar attr="][ref]"></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo`][ref]`
+
+[ref]: /uri
+.
+<p>[foo<code>][ref]</code></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo<http://example.com/?search=][ref]>
+
+[ref]: /uri
+.
+<p>[foo<a href="http://example.com/?search=%5D%5Bref%5D">http://example.com/?search=][ref]</a></p>
+````````````````````````````````
+
+
+Matching is case-insensitive:
+
+```````````````````````````````` example
+[foo][BaR]
+
+[bar]: /url "title"
+.
+<p><a href="/url" title="title">foo</a></p>
+````````````````````````````````
+
+
+Unicode case fold is used:
+
+```````````````````````````````` example
+[Толпой][Толпой] is a Russian word.
+
+[ТОЛПОЙ]: /url
+.
+<p><a href="/url">Толпой</a> is a Russian word.</p>
+````````````````````````````````
+
+
+Consecutive internal [whitespace] is treated as one space for
+purposes of determining matching:
+
+```````````````````````````````` example
+[Foo
+ bar]: /url
+
+[Baz][Foo bar]
+.
+<p><a href="/url">Baz</a></p>
+````````````````````````````````
+
+
+No [whitespace] is allowed between the [link text] and the
+[link label]:
+
+```````````````````````````````` example
+[foo] [bar]
+
+[bar]: /url "title"
+.
+<p>[foo] <a href="/url" title="title">bar</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo]
+[bar]
+
+[bar]: /url "title"
+.
+<p>[foo]
+<a href="/url" title="title">bar</a></p>
+````````````````````````````````
+
+
+This is a departure from John Gruber's original Markdown syntax
+description, which explicitly allows whitespace between the link
+text and the link label. It brings reference links in line with
+[inline links], which (according to both original Markdown and
+this spec) cannot have whitespace after the link text. More
+importantly, it prevents inadvertent capture of consecutive
+[shortcut reference links]. If whitespace is allowed between the
+link text and the link label, then in the following we will have
+a single reference link, not two shortcut reference links, as
+intended:
+
+``` markdown
+[foo]
+[bar]
+
+[foo]: /url1
+[bar]: /url2
+```
+
+(Note that [shortcut reference links] were introduced by Gruber
+himself in a beta version of `Markdown.pl`, but never included
+in the official syntax description. Without shortcut reference
+links, it is harmless to allow space between the link text and
+link label; but once shortcut references are introduced, it is
+too dangerous to allow this, as it frequently leads to
+unintended results.)
+
+When there are multiple matching [link reference definitions],
+the first is used:
+
+```````````````````````````````` example
+[foo]: /url1
+
+[foo]: /url2
+
+[bar][foo]
+.
+<p><a href="/url1">bar</a></p>
+````````````````````````````````
+
+
+Note that matching is performed on normalized strings, not parsed
+inline content. So the following does not match, even though the
+labels define equivalent inline content:
+
+```````````````````````````````` example
+[bar][foo\!]
+
+[foo!]: /url
+.
+<p>[bar][foo!]</p>
+````````````````````````````````
+
+
+[Link labels] cannot contain brackets, unless they are
+backslash-escaped:
+
+```````````````````````````````` example
+[foo][ref[]
+
+[ref[]: /uri
+.
+<p>[foo][ref[]</p>
+<p>[ref[]: /uri</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo][ref[bar]]
+
+[ref[bar]]: /uri
+.
+<p>[foo][ref[bar]]</p>
+<p>[ref[bar]]: /uri</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[[[foo]]]
+
+[[[foo]]]: /url
+.
+<p>[[[foo]]]</p>
+<p>[[[foo]]]: /url</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo][ref\[]
+
+[ref\[]: /uri
+.
+<p><a href="/uri">foo</a></p>
+````````````````````````````````
+
+
+Note that in this example `]` is not backslash-escaped:
+
+```````````````````````````````` example
+[bar\\]: /uri
+
+[bar\\]
+.
+<p><a href="/uri">bar\</a></p>
+````````````````````````````````
+
+
+A [link label] must contain at least one [non-whitespace character]:
+
+```````````````````````````````` example
+[]
+
+[]: /uri
+.
+<p>[]</p>
+<p>[]: /uri</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[
+ ]
+
+[
+ ]: /uri
+.
+<p>[
+]</p>
+<p>[
+]: /uri</p>
+````````````````````````````````
+
+
+A [collapsed reference link](@)
+consists of a [link label] that [matches] a
+[link reference definition] elsewhere in the
+document, followed by the string `[]`.
+The contents of the first link label are parsed as inlines,
+which are used as the link's text. The link's URI and title are
+provided by the matching reference link definition. Thus,
+`[foo][]` is equivalent to `[foo][foo]`.
+
+```````````````````````````````` example
+[foo][]
+
+[foo]: /url "title"
+.
+<p><a href="/url" title="title">foo</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[*foo* bar][]
+
+[*foo* bar]: /url "title"
+.
+<p><a href="/url" title="title"><em>foo</em> bar</a></p>
+````````````````````````````````
+
+
+The link labels are case-insensitive:
+
+```````````````````````````````` example
+[Foo][]
+
+[foo]: /url "title"
+.
+<p><a href="/url" title="title">Foo</a></p>
+````````````````````````````````
+
+
+
+As with full reference links, [whitespace] is not
+allowed between the two sets of brackets:
+
+```````````````````````````````` example
+[foo]
+[]
+
+[foo]: /url "title"
+.
+<p><a href="/url" title="title">foo</a>
+[]</p>
+````````````````````````````````
+
+
+A [shortcut reference link](@)
+consists of a [link label] that [matches] a
+[link reference definition] elsewhere in the
+document and is not followed by `[]` or a link label.
+The contents of the first link label are parsed as inlines,
+which are used as the link's text. The link's URI and title
+are provided by the matching link reference definition.
+Thus, `[foo]` is equivalent to `[foo][]`.
+
+```````````````````````````````` example
+[foo]
+
+[foo]: /url "title"
+.
+<p><a href="/url" title="title">foo</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[*foo* bar]
+
+[*foo* bar]: /url "title"
+.
+<p><a href="/url" title="title"><em>foo</em> bar</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[[*foo* bar]]
+
+[*foo* bar]: /url "title"
+.
+<p>[<a href="/url" title="title"><em>foo</em> bar</a>]</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[[bar [foo]
+
+[foo]: /url
+.
+<p>[[bar <a href="/url">foo</a></p>
+````````````````````````````````
+
+
+The link labels are case-insensitive:
+
+```````````````````````````````` example
+[Foo]
+
+[foo]: /url "title"
+.
+<p><a href="/url" title="title">Foo</a></p>
+````````````````````````````````
+
+
+A space after the link text should be preserved:
+
+```````````````````````````````` example
+[foo] bar
+
+[foo]: /url
+.
+<p><a href="/url">foo</a> bar</p>
+````````````````````````````````
+
+
+If you just want bracketed text, you can backslash-escape the
+opening bracket to avoid links:
+
+```````````````````````````````` example
+\[foo]
+
+[foo]: /url "title"
+.
+<p>[foo]</p>
+````````````````````````````````
+
+
+Note that this is a link, because a link label ends with the first
+following closing bracket:
+
+```````````````````````````````` example
+[foo*]: /url
+
+*[foo*]
+.
+<p>*<a href="/url">foo*</a></p>
+````````````````````````````````
+
+
+Full and compact references take precedence over shortcut
+references:
+
+```````````````````````````````` example
+[foo][bar]
+
+[foo]: /url1
+[bar]: /url2
+.
+<p><a href="/url2">foo</a></p>
+````````````````````````````````
+
+```````````````````````````````` example
+[foo][]
+
+[foo]: /url1
+.
+<p><a href="/url1">foo</a></p>
+````````````````````````````````
+
+Inline links also take precedence:
+
+```````````````````````````````` example
+[foo]()
+
+[foo]: /url1
+.
+<p><a href="">foo</a></p>
+````````````````````````````````
+
+```````````````````````````````` example
+[foo](not a link)
+
+[foo]: /url1
+.
+<p><a href="/url1">foo</a>(not a link)</p>
+````````````````````````````````
+
+In the following case `[bar][baz]` is parsed as a reference,
+`[foo]` as normal text:
+
+```````````````````````````````` example
+[foo][bar][baz]
+
+[baz]: /url
+.
+<p>[foo]<a href="/url">bar</a></p>
+````````````````````````````````
+
+
+Here, though, `[foo][bar]` is parsed as a reference, since
+`[bar]` is defined:
+
+```````````````````````````````` example
+[foo][bar][baz]
+
+[baz]: /url1
+[bar]: /url2
+.
+<p><a href="/url2">foo</a><a href="/url1">baz</a></p>
+````````````````````````````````
+
+
+Here `[foo]` is not parsed as a shortcut reference, because it
+is followed by a link label (even though `[bar]` is not defined):
+
+```````````````````````````````` example
+[foo][bar][baz]
+
+[baz]: /url1
+[foo]: /url2
+.
+<p>[foo]<a href="/url1">bar</a></p>
+````````````````````````````````
+
+
+
+## Images
+
+Syntax for images is like the syntax for links, with one
+difference. Instead of [link text], we have an
+[image description](@). The rules for this are the
+same as for [link text], except that (a) an
+image description starts with `
+.
+<p><img src="/url" alt="foo" title="title" /></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+![foo *bar*]
+
+[foo *bar*]: train.jpg "train & tracks"
+.
+<p><img src="train.jpg" alt="foo bar" title="train & tracks" /></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+](/url2)
+.
+<p><img src="/url2" alt="foo bar" /></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+](/url2)
+.
+<p><img src="/url2" alt="foo bar" /></p>
+````````````````````````````````
+
+
+Though this spec is concerned with parsing, not rendering, it is
+recommended that in rendering to HTML, only the plain string content
+of the [image description] be used. Note that in
+the above example, the alt attribute's value is `foo bar`, not `foo
+[bar](/url)` or `foo <a href="/url">bar</a>`. Only the plain string
+content is rendered, without formatting.
+
+```````````````````````````````` example
+![foo *bar*][]
+
+[foo *bar*]: train.jpg "train & tracks"
+.
+<p><img src="train.jpg" alt="foo bar" title="train & tracks" /></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+![foo *bar*][foobar]
+
+[FOOBAR]: train.jpg "train & tracks"
+.
+<p><img src="train.jpg" alt="foo bar" title="train & tracks" /></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+
+.
+<p><img src="train.jpg" alt="foo" /></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+My 
+.
+<p>My <img src="/path/to/train.jpg" alt="foo bar" title="title" /></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+
+.
+<p><img src="url" alt="foo" /></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+
+.
+<p><img src="/url" alt="" /></p>
+````````````````````````````````
+
+
+Reference-style:
+
+```````````````````````````````` example
+![foo][bar]
+
+[bar]: /url
+.
+<p><img src="/url" alt="foo" /></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+![foo][bar]
+
+[BAR]: /url
+.
+<p><img src="/url" alt="foo" /></p>
+````````````````````````````````
+
+
+Collapsed:
+
+```````````````````````````````` example
+![foo][]
+
+[foo]: /url "title"
+.
+<p><img src="/url" alt="foo" title="title" /></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+![*foo* bar][]
+
+[*foo* bar]: /url "title"
+.
+<p><img src="/url" alt="foo bar" title="title" /></p>
+````````````````````````````````
+
+
+The labels are case-insensitive:
+
+```````````````````````````````` example
+![Foo][]
+
+[foo]: /url "title"
+.
+<p><img src="/url" alt="Foo" title="title" /></p>
+````````````````````````````````
+
+
+As with reference links, [whitespace] is not allowed
+between the two sets of brackets:
+
+```````````````````````````````` example
+![foo]
+[]
+
+[foo]: /url "title"
+.
+<p><img src="/url" alt="foo" title="title" />
+[]</p>
+````````````````````````````````
+
+
+Shortcut:
+
+```````````````````````````````` example
+![foo]
+
+[foo]: /url "title"
+.
+<p><img src="/url" alt="foo" title="title" /></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+![*foo* bar]
+
+[*foo* bar]: /url "title"
+.
+<p><img src="/url" alt="foo bar" title="title" /></p>
+````````````````````````````````
+
+
+Note that link labels cannot contain unescaped brackets:
+
+```````````````````````````````` example
+![[foo]]
+
+[[foo]]: /url "title"
+.
+<p>![[foo]]</p>
+<p>[[foo]]: /url "title"</p>
+````````````````````````````````
+
+
+The link labels are case-insensitive:
+
+```````````````````````````````` example
+![Foo]
+
+[foo]: /url "title"
+.
+<p><img src="/url" alt="Foo" title="title" /></p>
+````````````````````````````````
+
+
+If you just want a literal `!` followed by bracketed text, you can
+backslash-escape the opening `[`:
+
+```````````````````````````````` example
+!\[foo]
+
+[foo]: /url "title"
+.
+<p>![foo]</p>
+````````````````````````````````
+
+
+If you want a link after a literal `!`, backslash-escape the
+`!`:
+
+```````````````````````````````` example
+\![foo]
+
+[foo]: /url "title"
+.
+<p>!<a href="/url" title="title">foo</a></p>
+````````````````````````````````
+
+
+## Autolinks
+
+[Autolink](@)s are absolute URIs and email addresses inside
+`<` and `>`. They are parsed as links, with the URL or email address
+as the link label.
+
+A [URI autolink](@) consists of `<`, followed by an
+[absolute URI] followed by `>`. It is parsed as
+a link to the URI, with the URI as the link's label.
+
+An [absolute URI](@),
+for these purposes, consists of a [scheme] followed by a colon (`:`)
+followed by zero or more characters other than ASCII
+[whitespace] and control characters, `<`, and `>`. If
+the URI includes these characters, they must be percent-encoded
+(e.g. `%20` for a space).
+
+For purposes of this spec, a [scheme](@) is any sequence
+of 2--32 characters beginning with an ASCII letter and followed
+by any combination of ASCII letters, digits, or the symbols plus
+("+"), period ("."), or hyphen ("-").
+
+Here are some valid autolinks:
+
+```````````````````````````````` example
+<http://foo.bar.baz>
+.
+<p><a href="http://foo.bar.baz">http://foo.bar.baz</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<http://foo.bar.baz/test?q=hello&id=22&boolean>
+.
+<p><a href="http://foo.bar.baz/test?q=hello&id=22&boolean">http://foo.bar.baz/test?q=hello&id=22&boolean</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<irc://foo.bar:2233/baz>
+.
+<p><a href="irc://foo.bar:2233/baz">irc://foo.bar:2233/baz</a></p>
+````````````````````````````````
+
+
+Uppercase is also fine:
+
+```````````````````````````````` example
+<MAILTO:FOO@BAR.BAZ>
+.
+<p><a href="MAILTO:FOO@BAR.BAZ">MAILTO:FOO@BAR.BAZ</a></p>
+````````````````````````````````
+
+
+Note that many strings that count as [absolute URIs] for
+purposes of this spec are not valid URIs, because their
+schemes are not registered or because of other problems
+with their syntax:
+
+```````````````````````````````` example
+<a+b+c:d>
+.
+<p><a href="a+b+c:d">a+b+c:d</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<made-up-scheme://foo,bar>
+.
+<p><a href="made-up-scheme://foo,bar">made-up-scheme://foo,bar</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<http://../>
+.
+<p><a href="http://../">http://../</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<localhost:5001/foo>
+.
+<p><a href="localhost:5001/foo">localhost:5001/foo</a></p>
+````````````````````````````````
+
+
+Spaces are not allowed in autolinks:
+
+```````````````````````````````` example
+<http://foo.bar/baz bim>
+.
+<p><http://foo.bar/baz bim></p>
+````````````````````````````````
+
+
+Backslash-escapes do not work inside autolinks:
+
+```````````````````````````````` example
+<http://example.com/\[\>
+.
+<p><a href="http://example.com/%5C%5B%5C">http://example.com/\[\</a></p>
+````````````````````````````````
+
+
+An [email autolink](@)
+consists of `<`, followed by an [email address],
+followed by `>`. The link's label is the email address,
+and the URL is `mailto:` followed by the email address.
+
+An [email address](@),
+for these purposes, is anything that matches
+the [non-normative regex from the HTML5
+spec](https://html.spec.whatwg.org/multipage/forms.html#e-mail-state-(type=email)):
+
+ /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?
+ (?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/
+
+Examples of email autolinks:
+
+```````````````````````````````` example
+<foo@bar.example.com>
+.
+<p><a href="mailto:foo@bar.example.com">foo@bar.example.com</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<foo+special@Bar.baz-bar0.com>
+.
+<p><a href="mailto:foo+special@Bar.baz-bar0.com">foo+special@Bar.baz-bar0.com</a></p>
+````````````````````````````````
+
+
+Backslash-escapes do not work inside email autolinks:
+
+```````````````````````````````` example
+<foo\+@bar.example.com>
+.
+<p><foo+@bar.example.com></p>
+````````````````````````````````
+
+
+These are not autolinks:
+
+```````````````````````````````` example
+<>
+.
+<p><></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+< http://foo.bar >
+.
+<p>< http://foo.bar ></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<m:abc>
+.
+<p><m:abc></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<foo.bar.baz>
+.
+<p><foo.bar.baz></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+http://example.com
+.
+<p>http://example.com</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo@bar.example.com
+.
+<p>foo@bar.example.com</p>
+````````````````````````````````
+
+<div class="extension">
+
+## Autolinks (extension)
+
+GFM enables the `autolink` extension, where autolinks will be recognised in a
+greater number of conditions.
+
+[Autolink]s can also be constructed without requiring the use of `<` and to `>`
+to delimit them, although they will be recognized under a smaller set of
+circumstances. All such recognized autolinks can only come at the beginning of
+a line, after whitespace, or any of the delimiting characters `*`, `_`, `~`,
+and `(`.
+
+An [extended www autolink](@) will be recognized
+when the text `www.` is found followed by a [valid domain].
+A [valid domain](@) consists of segments
+of alphanumeric characters, underscores (`_`) and hyphens (`-`)
+separated by periods (`.`).
+There must be at least one period,
+and no underscores may be present in the last two segments of the domain.
+
+The scheme `http` will be inserted automatically:
+
+```````````````````````````````` example autolink
+www.commonmark.org
+.
+<p><a href="http://www.commonmark.org">www.commonmark.org</a></p>
+````````````````````````````````
+
+After a [valid domain], zero or more non-space non-`<` characters may follow:
+
+```````````````````````````````` example autolink
+Visit www.commonmark.org/help for more information.
+.
+<p>Visit <a href="http://www.commonmark.org/help">www.commonmark.org/help</a> for more information.</p>
+````````````````````````````````
+
+We then apply [extended autolink path validation](@) as follows:
+
+Trailing punctuation (specifically, `?`, `!`, `.`, `,`, `:`, `*`, `_`, and `~`)
+will not be considered part of the autolink, though they may be included in the
+interior of the link:
+
+```````````````````````````````` example autolink
+Visit www.commonmark.org.
+
+Visit www.commonmark.org/a.b.
+.
+<p>Visit <a href="http://www.commonmark.org">www.commonmark.org</a>.</p>
+<p>Visit <a href="http://www.commonmark.org/a.b">www.commonmark.org/a.b</a>.</p>
+````````````````````````````````
+
+When an autolink ends in `)`, we scan the entire autolink for the total number
+of parentheses. If there is a greater number of closing parentheses than
+opening ones, we don't consider the unmatched trailing parentheses part of the
+autolink, in order to facilitate including an autolink inside a parenthesis:
+
+```````````````````````````````` example autolink
+www.google.com/search?q=Markup+(business)
+
+www.google.com/search?q=Markup+(business)))
+
+(www.google.com/search?q=Markup+(business))
+
+(www.google.com/search?q=Markup+(business)
+.
+<p><a href="http://www.google.com/search?q=Markup+(business)">www.google.com/search?q=Markup+(business)</a></p>
+<p><a href="http://www.google.com/search?q=Markup+(business)">www.google.com/search?q=Markup+(business)</a>))</p>
+<p>(<a href="http://www.google.com/search?q=Markup+(business)">www.google.com/search?q=Markup+(business)</a>)</p>
+<p>(<a href="http://www.google.com/search?q=Markup+(business)">www.google.com/search?q=Markup+(business)</a></p>
+````````````````````````````````
+
+This check is only done when the link ends in a closing parentheses `)`, so if
+the only parentheses are in the interior of the autolink, no special rules are
+applied:
+
+```````````````````````````````` example autolink
+www.google.com/search?q=(business))+ok
+.
+<p><a href="http://www.google.com/search?q=(business))+ok">www.google.com/search?q=(business))+ok</a></p>
+````````````````````````````````
+
+If an autolink ends in a semicolon (`;`), we check to see if it appears to
+resemble an [entity reference][entity references]; if the preceding text is `&`
+followed by one or more alphanumeric characters. If so, it is excluded from
+the autolink:
+
+```````````````````````````````` example autolink
+www.google.com/search?q=commonmark&hl=en
+
+www.google.com/search?q=commonmark&hl;
+.
+<p><a href="http://www.google.com/search?q=commonmark&hl=en">www.google.com/search?q=commonmark&hl=en</a></p>
+<p><a href="http://www.google.com/search?q=commonmark">www.google.com/search?q=commonmark</a>&hl;</p>
+````````````````````````````````
+
+`<` immediately ends an autolink.
+
+```````````````````````````````` example autolink
+www.commonmark.org/he<lp
+.
+<p><a href="http://www.commonmark.org/he">www.commonmark.org/he</a><lp</p>
+````````````````````````````````
+
+An [extended url autolink](@) will be recognised when one of the schemes
+`http://`, `https://`, or `ftp://`, followed by a [valid domain], then zero or
+more non-space non-`<` characters according to
+[extended autolink path validation]:
+
+```````````````````````````````` example autolink
+http://commonmark.org
+
+(Visit https://encrypted.google.com/search?q=Markup+(business))
+
+Anonymous FTP is available at ftp://foo.bar.baz.
+.
+<p><a href="http://commonmark.org">http://commonmark.org</a></p>
+<p>(Visit <a href="https://encrypted.google.com/search?q=Markup+(business)">https://encrypted.google.com/search?q=Markup+(business)</a>)</p>
+<p>Anonymous FTP is available at <a href="ftp://foo.bar.baz">ftp://foo.bar.baz</a>.</p>
+````````````````````````````````
+
+
+An [extended email autolink](@) will be recognised when an email address is
+recognised within any text node. Email addresses are recognised according to
+the following rules:
+
+* One ore more characters which are alphanumeric, or `.`, `-`, `_`, or `+`.
+* An `@` symbol.
+* One or more characters which are alphanumeric, or `-` or `_`,
+ separated by periods (`.`).
+ There must be at least one period.
+ The last character must not be one of `-` or `_`.
+
+The scheme `mailto:` will automatically be added to the generated link:
+
+```````````````````````````````` example autolink
+foo@bar.baz
+.
+<p><a href="mailto:foo@bar.baz">foo@bar.baz</a></p>
+````````````````````````````````
+
+`+` can occur before the `@`, but not after.
+
+```````````````````````````````` example autolink
+hello@mail+xyz.example isn't valid, but hello+xyz@mail.example is.
+.
+<p>hello@mail+xyz.example isn't valid, but <a href="mailto:hello+xyz@mail.example">hello+xyz@mail.example</a> is.</p>
+````````````````````````````````
+
+`.`, `-`, and `_` can occur on both sides of the `@`, but only `.` may occur at
+the end of the email address, in which case it will not be considered part of
+the address:
+
+```````````````````````````````` example autolink
+a.b-c_d@a.b
+
+a.b-c_d@a.b.
+
+a.b-c_d@a.b-
+
+a.b-c_d@a.b_
+.
+<p><a href="mailto:a.b-c_d@a.b">a.b-c_d@a.b</a></p>
+<p><a href="mailto:a.b-c_d@a.b">a.b-c_d@a.b</a>.</p>
+<p>a.b-c_d@a.b-</p>
+<p>a.b-c_d@a.b_</p>
+````````````````````````````````
+
+</div>
+
+## Raw HTML
+
+Text between `<` and `>` that looks like an HTML tag is parsed as a
+raw HTML tag and will be rendered in HTML without escaping.
+Tag and attribute names are not limited to current HTML tags,
+so custom tags (and even, say, DocBook tags) may be used.
+
+Here is the grammar for tags:
+
+A [tag name](@) consists of an ASCII letter
+followed by zero or more ASCII letters, digits, or
+hyphens (`-`).
+
+An [attribute](@) consists of [whitespace],
+an [attribute name], and an optional
+[attribute value specification].
+
+An [attribute name](@)
+consists of an ASCII letter, `_`, or `:`, followed by zero or more ASCII
+letters, digits, `_`, `.`, `:`, or `-`. (Note: This is the XML
+specification restricted to ASCII. HTML5 is laxer.)
+
+An [attribute value specification](@)
+consists of optional [whitespace],
+a `=` character, optional [whitespace], and an [attribute
+value].
+
+An [attribute value](@)
+consists of an [unquoted attribute value],
+a [single-quoted attribute value], or a [double-quoted attribute value].
+
+An [unquoted attribute value](@)
+is a nonempty string of characters not
+including [whitespace], `"`, `'`, `=`, `<`, `>`, or `` ` ``.
+
+A [single-quoted attribute value](@)
+consists of `'`, zero or more
+characters not including `'`, and a final `'`.
+
+A [double-quoted attribute value](@)
+consists of `"`, zero or more
+characters not including `"`, and a final `"`.
+
+An [open tag](@) consists of a `<` character, a [tag name],
+zero or more [attributes], optional [whitespace], an optional `/`
+character, and a `>` character.
+
+A [closing tag](@) consists of the string `</`, a
+[tag name], optional [whitespace], and the character `>`.
+
+An [HTML comment](@) consists of `<!-->`, `<!--->`, or `<!--`, a string of
+characters not including the string `-->`, and `-->` (see the
+[HTML spec](https://html.spec.whatwg.org/multipage/parsing.html#markup-declaration-open-state)).
+
+A [processing instruction](@)
+consists of the string `<?`, a string
+of characters not including the string `?>`, and the string
+`?>`.
+
+A [declaration](@) consists of the
+string `<!`, a name consisting of one or more uppercase ASCII letters,
+[whitespace], a string of characters not including the
+character `>`, and the character `>`.
+
+A [CDATA section](@) consists of
+the string `<![CDATA[`, a string of characters not including the string
+`]]]]><![CDATA[>`, and the string `]]]]>< consists of an [open tag], a [closing tag],
+an [HTML comment], a [processing instruction], a [declaration],
+or a [CDATA section].
+
+Here are some simple open tags:
+
+```````````````````````````````` example
+<a><bab><c2c>
+.
+<p><a><bab><c2c></p>
+````````````````````````````````
+
+
+Empty elements:
+
+```````````````````````````````` example
+<a/><b2/>
+.
+<p><a/><b2/></p>
+````````````````````````````````
+
+
+[Whitespace] is allowed:
+
+```````````````````````````````` example
+<a /><b2
+data="foo" >
+.
+<p><a /><b2
+data="foo" ></p>
+````````````````````````````````
+
+
+With attributes:
+
+```````````````````````````````` example
+<a foo="bar" bam = 'baz <em>"</em>'
+_boolean zoop:33=zoop:33 />
+.
+<p><a foo="bar" bam = 'baz <em>"</em>'
+_boolean zoop:33=zoop:33 /></p>
+````````````````````````````````
+
+
+Custom tag names can be used:
+
+```````````````````````````````` example
+Foo <responsive-image src="foo.jpg" />
+.
+<p>Foo <responsive-image src="foo.jpg" /></p>
+````````````````````````````````
+
+
+Illegal tag names, not parsed as HTML:
+
+```````````````````````````````` example
+<33> <__>
+.
+<p><33> <__></p>
+````````````````````````````````
+
+
+Illegal attribute names:
+
+```````````````````````````````` example
+<a h*#ref="hi">
+.
+<p><a h*#ref="hi"></p>
+````````````````````````````````
+
+
+Illegal attribute values:
+
+```````````````````````````````` example
+<a href="hi'> <a href=hi'>
+.
+<p><a href="hi'> <a href=hi'></p>
+````````````````````````````````
+
+
+Illegal [whitespace]:
+
+```````````````````````````````` example
+< a><
+foo><bar/ >
+<foo bar=baz
+bim!bop />
+.
+<p>< a><
+foo><bar/ >
+<foo bar=baz
+bim!bop /></p>
+````````````````````````````````
+
+
+Missing [whitespace]:
+
+```````````````````````````````` example
+<a href='bar'title=title>
+.
+<p><a href='bar'title=title></p>
+````````````````````````````````
+
+
+Closing tags:
+
+```````````````````````````````` example
+</a></foo >
+.
+<p></a></foo ></p>
+````````````````````````````````
+
+
+Illegal attributes in closing tag:
+
+```````````````````````````````` example
+</a href="foo">
+.
+<p></a href="foo"></p>
+````````````````````````````````
+
+
+Comments:
+
+```````````````````````````````` example
+foo <!-- this is a --
+comment - with hyphens -->
+.
+<p>foo <!-- this is a --
+comment - with hyphens --></p>
+````````````````````````````````
+
+```````````````````````````````` example
+foo <!--> foo -->
+
+foo <!---> foo -->
+.
+<p>foo <!--> foo --></p>
+<p>foo <!---> foo --></p>
+````````````````````````````````
+
+
+Processing instructions:
+
+```````````````````````````````` example
+foo <?php echo $a; ?>
+.
+<p>foo <?php echo $a; ?></p>
+````````````````````````````````
+
+
+Declarations:
+
+```````````````````````````````` example
+foo <!ELEMENT br EMPTY>
+.
+<p>foo <!ELEMENT br EMPTY></p>
+````````````````````````````````
+
+
+CDATA sections:
+
+```````````````````````````````` example
+foo <![CDATA[>&<]]]]><![CDATA[>
+.
+<p>foo <![CDATA[>&<]]]]>< (rendered
+in HTML as a `<br />` tag):
+
+```````````````````````````````` example
+foo
+baz
+.
+<p>foo<br />
+baz</p>
+````````````````````````````````
+
+
+For a more visible alternative, a backslash before the
+[line ending] may be used instead of two spaces:
+
+```````````````````````````````` example
+foo\
+baz
+.
+<p>foo<br />
+baz</p>
+````````````````````````````````
+
+
+More than two spaces can be used:
+
+```````````````````````````````` example
+foo
+baz
+.
+<p>foo<br />
+baz</p>
+````````````````````````````````
+
+
+Leading spaces at the beginning of the next line are ignored:
+
+```````````````````````````````` example
+foo
+ bar
+.
+<p>foo<br />
+bar</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo\
+ bar
+.
+<p>foo<br />
+bar</p>
+````````````````````````````````
+
+
+Line breaks can occur inside emphasis, links, and other constructs
+that allow inline content:
+
+```````````````````````````````` example
+*foo
+bar*
+.
+<p><em>foo<br />
+bar</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*foo\
+bar*
+.
+<p><em>foo<br />
+bar</em></p>
+````````````````````````````````
+
+
+Line breaks do not occur inside code spans
+
+```````````````````````````````` example
+`code
+span`
+.
+<p><code>code span</code></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+`code\
+span`
+.
+<p><code>code\ span</code></p>
+````````````````````````````````
+
+
+or HTML tags:
+
+```````````````````````````````` example
+<a href="foo
+bar">
+.
+<p><a href="foo
+bar"></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<a href="foo\
+bar">
+.
+<p><a href="foo\
+bar"></p>
+````````````````````````````````
+
+
+Hard line breaks are for separating inline content within a block.
+Neither syntax for hard line breaks works at the end of a paragraph or
+other block element:
+
+```````````````````````````````` example
+foo\
+.
+<p>foo\</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo
+.
+<p>foo</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+### foo\
+.
+<h3>foo\</h3>
+````````````````````````````````
+
+
+```````````````````````````````` example
+### foo
+.
+<h3>foo</h3>
+````````````````````````````````
+
+
+## Soft line breaks
+
+A regular line break (not in a code span or HTML tag) that is not
+preceded by two or more spaces or a backslash is parsed as a
+[softbreak](@). (A softbreak may be rendered in HTML either as a
+[line ending] or as a space. The result will be the same in
+browsers. In the examples here, a [line ending] will be used.)
+
+```````````````````````````````` example
+foo
+baz
+.
+<p>foo
+baz</p>
+````````````````````````````````
+
+
+Spaces at the end of the line and beginning of the next line are
+removed:
+
+```````````````````````````````` example
+foo
+ baz
+.
+<p>foo
+baz</p>
+````````````````````````````````
+
+
+A conforming parser may render a soft line break in HTML either as a
+line break or as a space.
+
+A renderer may also provide an option to render soft line breaks
+as hard line breaks.
+
+## Textual content
+
+Any characters not given an interpretation by the above rules will
+be parsed as plain textual content.
+
+```````````````````````````````` example
+hello $.;'there
+.
+<p>hello $.;'there</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+Foo χρῆν
+.
+<p>Foo χρῆν</p>
+````````````````````````````````
+
+
+Internal spaces are preserved verbatim:
+
+```````````````````````````````` example
+Multiple spaces
+.
+<p>Multiple spaces</p>
+````````````````````````````````
+
+
+<!-- END TESTS -->
+
+# Appendix: A parsing strategy
+
+In this appendix we describe some features of the parsing strategy
+used in the CommonMark reference implementations.
+
+## Overview
+
+Parsing has two phases:
+
+1. In the first phase, lines of input are consumed and the block
+structure of the document---its division into paragraphs, block quotes,
+list items, and so on---is constructed. Text is assigned to these
+blocks but not parsed. Link reference definitions are parsed and a
+map of links is constructed.
+
+2. In the second phase, the raw text contents of paragraphs and headings
+are parsed into sequences of Markdown inline elements (strings,
+code spans, links, emphasis, and so on), using the map of link
+references constructed in phase 1.
+
+At each point in processing, the document is represented as a tree of
+**blocks**. The root of the tree is a `document` block. The `document`
+may have any number of other blocks as **children**. These children
+may, in turn, have other blocks as children. The last child of a block
+is normally considered **open**, meaning that subsequent lines of input
+can alter its contents. (Blocks that are not open are **closed**.)
+Here, for example, is a possible document tree, with the open blocks
+marked by arrows:
+
+``` tree
+-> document
+ -> block_quote
+ paragraph
+ "Lorem ipsum dolor\nsit amet."
+ -> list (type=bullet tight=true bullet_char=-)
+ list_item
+ paragraph
+ "Qui *quodsi iracundia*"
+ -> list_item
+ -> paragraph
+ "aliquando id"
+```
+
+## Phase 1: block structure
+
+Each line that is processed has an effect on this tree. The line is
+analyzed and, depending on its contents, the document may be altered
+in one or more of the following ways:
+
+1. One or more open blocks may be closed.
+2. One or more new blocks may be created as children of the
+ last open block.
+3. Text may be added to the last (deepest) open block remaining
+ on the tree.
+
+Once a line has been incorporated into the tree in this way,
+it can be discarded, so input can be read in a stream.
+
+For each line, we follow this procedure:
+
+1. First we iterate through the open blocks, starting with the
+root document, and descending through last children down to the last
+open block. Each block imposes a condition that the line must satisfy
+if the block is to remain open. For example, a block quote requires a
+`>` character. A paragraph requires a non-blank line.
+In this phase we may match all or just some of the open
+blocks. But we cannot close unmatched blocks yet, because we may have a
+[lazy continuation line].
+
+2. Next, after consuming the continuation markers for existing
+blocks, we look for new block starts (e.g. `>` for a block quote).
+If we encounter a new block start, we close any blocks unmatched
+in step 1 before creating the new block as a child of the last
+matched block.
+
+3. Finally, we look at the remainder of the line (after block
+markers like `>`, list markers, and indentation have been consumed).
+This is text that can be incorporated into the last open
+block (a paragraph, code block, heading, or raw HTML).
+
+Setext headings are formed when we see a line of a paragraph
+that is a [setext heading underline].
+
+Reference link definitions are detected when a paragraph is closed;
+the accumulated text lines are parsed to see if they begin with
+one or more reference link definitions. Any remainder becomes a
+normal paragraph.
+
+We can see how this works by considering how the tree above is
+generated by four lines of Markdown:
+
+``` markdown
+> Lorem ipsum dolor
+sit amet.
+> - Qui *quodsi iracundia*
+> - aliquando id
+```
+
+At the outset, our document model is just
+
+``` tree
+-> document
+```
+
+The first line of our text,
+
+``` markdown
+> Lorem ipsum dolor
+```
+
+causes a `block_quote` block to be created as a child of our
+open `document` block, and a `paragraph` block as a child of
+the `block_quote`. Then the text is added to the last open
+block, the `paragraph`:
+
+``` tree
+-> document
+ -> block_quote
+ -> paragraph
+ "Lorem ipsum dolor"
+```
+
+The next line,
+
+``` markdown
+sit amet.
+```
+
+is a "lazy continuation" of the open `paragraph`, so it gets added
+to the paragraph's text:
+
+``` tree
+-> document
+ -> block_quote
+ -> paragraph
+ "Lorem ipsum dolor\nsit amet."
+```
+
+The third line,
+
+``` markdown
+> - Qui *quodsi iracundia*
+```
+
+causes the `paragraph` block to be closed, and a new `list` block
+opened as a child of the `block_quote`. A `list_item` is also
+added as a child of the `list`, and a `paragraph` as a child of
+the `list_item`. The text is then added to the new `paragraph`:
+
+``` tree
+-> document
+ -> block_quote
+ paragraph
+ "Lorem ipsum dolor\nsit amet."
+ -> list (type=bullet tight=true bullet_char=-)
+ -> list_item
+ -> paragraph
+ "Qui *quodsi iracundia*"
+```
+
+The fourth line,
+
+``` markdown
+> - aliquando id
+```
+
+causes the `list_item` (and its child the `paragraph`) to be closed,
+and a new `list_item` opened up as child of the `list`. A `paragraph`
+is added as a child of the new `list_item`, to contain the text.
+We thus obtain the final tree:
+
+``` tree
+-> document
+ -> block_quote
+ paragraph
+ "Lorem ipsum dolor\nsit amet."
+ -> list (type=bullet tight=true bullet_char=-)
+ list_item
+ paragraph
+ "Qui *quodsi iracundia*"
+ -> list_item
+ -> paragraph
+ "aliquando id"
+```
+
+## Phase 2: inline structure
+
+Once all of the input has been parsed, all open blocks are closed.
+
+We then "walk the tree," visiting every node, and parse raw
+string contents of paragraphs and headings as inlines. At this
+point we have seen all the link reference definitions, so we can
+resolve reference links as we go.
+
+``` tree
+document
+ block_quote
+ paragraph
+ str "Lorem ipsum dolor"
+ softbreak
+ str "sit amet."
+ list (type=bullet tight=true bullet_char=-)
+ list_item
+ paragraph
+ str "Qui "
+ emph
+ str "quodsi iracundia"
+ list_item
+ paragraph
+ str "aliquando id"
+```
+
+Notice how the [line ending] in the first paragraph has
+been parsed as a `softbreak`, and the asterisks in the first list item
+have become an `emph`.
+
+### An algorithm for parsing nested emphasis and links
+
+By far the trickiest part of inline parsing is handling emphasis,
+strong emphasis, links, and images. This is done using the following
+algorithm.
+
+When we're parsing inlines and we hit either
+
+- a run of `*` or `_` characters, or
+- a `[` or `.
+
+The [delimiter stack] is a doubly linked list. Each
+element contains a pointer to a text node, plus information about
+
+- the type of delimiter (`[`, `![`, `*`, `_`)
+- the number of delimiters,
+- whether the delimiter is "active" (all are active to start), and
+- whether the delimiter is a potential opener, a potential closer,
+ or both (which depends on what sort of characters precede
+ and follow the delimiters).
+
+When we hit a `]` character, we call the *look for link or image*
+procedure (see below).
+
+When we hit the end of the input, we call the *process emphasis*
+procedure (see below), with `stack_bottom` = NULL.
+
+#### *look for link or image*
+
+Starting at the top of the delimiter stack, we look backwards
+through the stack for an opening `[` or `![` delimiter.
+
+- If we don't find one, we return a literal text node `]`.
+
+- If we do find one, but it's not *active*, we remove the inactive
+ delimiter from the stack, and return a literal text node `]`.
+
+- If we find one and it's active, then we parse ahead to see if
+ we have an inline link/image, reference link/image, compact reference
+ link/image, or shortcut reference link/image.
+
+ + If we don't, then we remove the opening delimiter from the
+ delimiter stack and return a literal text node `]`.
+
+ + If we do, then
+
+ * We return a link or image node whose children are the inlines
+ after the text node pointed to by the opening delimiter.
+
+ * We run *process emphasis* on these inlines, with the `[` opener
+ as `stack_bottom`.
+
+ * We remove the opening delimiter.
+
+ * If we have a link (and not an image), we also set all
+ `[` delimiters before the opening delimiter to *inactive*. (This
+ will prevent us from getting links within links.)
+
+#### *process emphasis*
+
+Parameter `stack_bottom` sets a lower bound to how far we
+descend in the [delimiter stack]. If it is NULL, we can
+go all the way to the bottom. Otherwise, we stop before
+visiting `stack_bottom`.
+
+Let `current_position` point to the element on the [delimiter stack]
+just above `stack_bottom` (or the first element if `stack_bottom`
+is NULL).
+
+We keep track of the `openers_bottom` for each delimiter
+type (`*`, `_`) and each length of the closing delimiter run
+(modulo 3). Initialize this to `stack_bottom`.
+
+Then we repeat the following until we run out of potential
+closers:
+
+- Move `current_position` forward in the delimiter stack (if needed)
+ until we find the first potential closer with delimiter `*` or `_`.
+ (This will be the potential closer closest
+ to the beginning of the input -- the first one in parse order.)
+
+- Now, look back in the stack (staying above `stack_bottom` and
+ the `openers_bottom` for this delimiter type) for the
+ first matching potential opener ("matching" means same delimiter).
+
+- If one is found:
+
+ + Figure out whether we have emphasis or strong emphasis:
+ if both closer and opener spans have length >= 2, we have
+ strong, otherwise regular.
+
+ + Insert an emph or strong emph node accordingly, after
+ the text node corresponding to the opener.
+
+ + Remove any delimiters between the opener and closer from
+ the delimiter stack.
+
+ + Remove 1 (for regular emph) or 2 (for strong emph) delimiters
+ from the opening and closing text nodes. If they become empty
+ as a result, remove them and remove the corresponding element
+ of the delimiter stack. If the closing node is removed, reset
+ `current_position` to the next element in the stack.
+
+- If none is found:
+
+ + Set `openers_bottom` to the element before `current_position`.
+ (We know that there are no openers for this kind of closer up to and
+ including this point, so this puts a lower bound on future searches.)
+
+ + If the closer at `current_position` is not a potential opener,
+ remove it from the delimiter stack (since we know it can't
+ be a closer either).
+
+ + Advance `current_position` to the next element in the stack.
+
+After we're done, we remove all delimiters above `stack_bottom` from the
+delimiter stack.
diff --git a/documents/markdown/cmark-gfm/test.md b/documents/markdown/cmark-gfm/test.md
new file mode 100644
index 0000000..4156a2a
--- /dev/null
+++ b/documents/markdown/cmark-gfm/test.md
@@ -0,0 +1,49 @@
+# H1
+
+H2
+--
+
+t ☺
+*b* **em** `c`
+≥\&\
+\_e\_
+
+4) I1
+
+5) I2
+ > [l](/u "t")
+ >
+ > - [f]
+ > - 
+ >
+ >> <ftp://hh>
+ >> <u@hh>
+
+~~~ l☺
+cb
+~~~
+
+ c1
+ c2
+
+***
+
+<div>
+<b>x</b>
+</div>
+
+| a | b |
+| --- | --- |
+| c | `d|` \| e |
+
+google ~~yahoo~~
+
+google.com http://google.com google@google.com
+
+and <xmp> but
+
+<surewhynot>
+sure
+</surewhynot>
+
+[f]: /u "t"
diff --git a/documents/markdown/cmark-gfm/why-cmark-and-not-x.md b/documents/markdown/cmark-gfm/why-cmark-and-not-x.md
new file mode 100644
index 0000000..3fdb4e5
--- /dev/null
+++ b/documents/markdown/cmark-gfm/why-cmark-and-not-x.md
@@ -0,0 +1,104 @@
+Why use `cmark` and not X?
+==========================
+
+`hoedown`
+---------
+
+`hoedown` (which derives from `sundown`) is slightly faster
+than `cmark` in our benchmarks (0.21s vs. 0.29s). But both
+are much faster than any other available implementations.
+
+`hoedown` boasts of including "protection against all possible
+DOS attacks," but there are some chinks in the armor:
+
+ % time python -c 'print(("[" * 50000) + "a" + ("]" * 50000))' | cmark
+ ...
+ user 0m0.073s
+ % time python -c 'print(("[" * 50000) + "a" + ("]" * 50000))' | hoedown
+ ...
+ 0m17.84s
+
+`hoedown` has many parsing bugs. Here is a selection (as of
+v3.0.3):
+
+ % hoedown
+ - one
+ - two
+ 1. three
+ ^D
+ <ul>
+ <li>one
+
+ <ul>
+ <li>two</li>
+ <li>three</li>
+ </ul></li>
+ </ul>
+
+
+ % hoedown
+ ## hi\###
+ ^D
+ <h2>hi\</h2>
+
+
+ % hoedown
+ [ΑΓΩ]: /φου
+
+ [αγω]
+ ^D
+ <p>[αγω]</p>
+
+
+ % hoedown
+ ```
+ [foo]: /url
+ ```
+
+ [foo]
+ ^D
+ <p>```</p>
+
+ <p>```</p>
+
+ <p><a href="/url">foo</a></p>
+
+
+ % hoedown
+ [foo](url "ti\*tle")
+ ^D
+ <p><a href="url" title="ti\*tle">foo</a></p>
+
+
+ % ./hoedown
+ - one
+ - two
+ - three
+ - four
+ ^D
+ <ul>
+ <li>one
+
+ <ul>
+ <li>two</li>
+ <li>three</li>
+ <li>four</li>
+ </ul></li>
+ </ul>
+
+
+`discount`
+----------
+
+`cmark` is about six times faster.
+
+`kramdown`
+----------
+
+`cmark` is about a hundred times faster.
+
+`kramdown` also gets tied in knots by pathological input like
+
+ python -c 'print(("[" * 50000) + "a" + ("]" * 50000))'
+
+
diff --git a/documents/markdown/hugo-docs/LICENSE.md b/documents/markdown/hugo-docs/LICENSE.md
new file mode 100644
index 0000000..b09cd78
--- /dev/null
+++ b/documents/markdown/hugo-docs/LICENSE.md
@@ -0,0 +1,201 @@
+Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright [yyyy] [name of copyright owner]
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/documents/markdown/hugo-docs/en__common__index.md b/documents/markdown/hugo-docs/en__common__index.md
new file mode 100644
index 0000000..612165e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common__index.md
@@ -0,0 +1,13 @@
+---
+cascade:
+ build:
+ list: never
+ publishResources: false
+ render: never
+---
+
+<!--
+Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+
+Include the rendered content using the "include" shortcode.
+-->
diff --git a/documents/markdown/hugo-docs/en__common_content-format-table.md b/documents/markdown/hugo-docs/en__common_content-format-table.md
new file mode 100644
index 0000000..c0a66a1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_content-format-table.md
@@ -0,0 +1,13 @@
+---
+_comment: Do not remove front matter.
+---
+
+Content format|Media type|Identifier|File extensions
+:--|:--|:--|:--
+Markdown|`text/markdown`|`markdown`|`markdown`,`md`, `mdown`
+HTML|`text/html`|`html`|`htm`, `html`
+Emacs Org Mode|`text/org`|`org`|`org`
+AsciiDoc|`text/asciidoc`|`asciidoc`|`ad`, `adoc`, `asciidoc`
+Pandoc|`text/pandoc`|`pandoc`|`pandoc`, `pdc`
+reStructuredText|`text/rst`|`rst`|`rst`
+<!-- do not remove this comment -->
diff --git a/documents/markdown/hugo-docs/en__common_filter-sort-group.md b/documents/markdown/hugo-docs/en__common_filter-sort-group.md
new file mode 100644
index 0000000..ac73766
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_filter-sort-group.md
@@ -0,0 +1,8 @@
+---
+_comment: Do not remove front matter.
+---
+
+> [!note]
+> The [page collections quick reference guide] describes methods and functions to filter, sort, and group page collections.
+
+[page collections quick reference guide]: /quick-reference/page-collections/
diff --git a/documents/markdown/hugo-docs/en__common_functions_fmt_format-string.md b/documents/markdown/hugo-docs/en__common_functions_fmt_format-string.md
new file mode 100644
index 0000000..09a9ee8
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_functions_fmt_format-string.md
@@ -0,0 +1,7 @@
+---
+_comment: Do not remove front matter.
+---
+
+The documentation for Go's [fmt] package describes the structure and content of the format string.
+
+[fmt]: https://pkg.go.dev/fmt
diff --git a/documents/markdown/hugo-docs/en__common_functions_go-html-template-package.md b/documents/markdown/hugo-docs/en__common_functions_go-html-template-package.md
new file mode 100644
index 0000000..ed3a6af
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_functions_go-html-template-package.md
@@ -0,0 +1,14 @@
+---
+_comment: Do not remove front matter.
+---
+
+Hugo uses Go's [`text/template`][] and [`html/template`][] packages.
+
+The `text/template` package implements data-driven templates for generating textual output, while the `html/template` package implements data-driven templates for generating HTML output safe against code injection.
+
+By default, Hugo uses the `html/template` package when rendering HTML files.
+
+To generate HTML output that is safe against code injection, the `html/template` package escapes strings in certain contexts.
+
+[`text/template`]: https://pkg.go.dev/text/template
+[`html/template`]: https://pkg.go.dev/html/template
diff --git a/documents/markdown/hugo-docs/en__common_functions_go-template_text-template.md b/documents/markdown/hugo-docs/en__common_functions_go-template_text-template.md
new file mode 100644
index 0000000..c321557
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_functions_go-template_text-template.md
@@ -0,0 +1,7 @@
+---
+_comment: Do not remove front matter.
+---
+
+See Go's [`text/template`][] documentation for more information.
+
+[`text/template`]: https://pkg.go.dev/text/template
diff --git a/documents/markdown/hugo-docs/en__common_functions_hugo_sites-collection.md b/documents/markdown/hugo-docs/en__common_functions_hugo_sites-collection.md
new file mode 100644
index 0000000..9f4b81b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_functions_hugo_sites-collection.md
@@ -0,0 +1,9 @@
+---
+_comment: Do not remove front matter.
+---
+
+The returned collection follows a hierarchical sort where each subsequent dimension acts as a tie-breaker for the one above it.
+
+1. [Language](g) is sorted by [weight](g) in ascending order, falling back to lexicographical order if weights are tied or undefined.
+1. [Version](g) is then sorted by weight in ascending order, with Hugo defaulting to a descending semantic sort for any ties.
+1. [Role](g) is finally sorted by weight in ascending order, using lexicographical order as the final fallback.
diff --git a/documents/markdown/hugo-docs/en__common_functions_images_apply-image-filter.md b/documents/markdown/hugo-docs/en__common_functions_images_apply-image-filter.md
new file mode 100644
index 0000000..08e0823
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_functions_images_apply-image-filter.md
@@ -0,0 +1,27 @@
+---
+_comment: Do not remove front matter.
+---
+
+Apply the filter using the [`images.Filter`] function:
+
+[`images.Filter`]: /functions/images/filter/
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with . | images.Filter $filter }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+You can also apply the filter using the [`Filter`] method on a `Resource` object:
+
+[`Filter`]: /methods/resource/filter/
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Filter $filter }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en__common_functions_js_options.md b/documents/markdown/hugo-docs/en__common_functions_js_options.md
new file mode 100644
index 0000000..837855d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_functions_js_options.md
@@ -0,0 +1,107 @@
+---
+_comment: Do not remove front matter.
+---
+
+params
+: (`map` or `slice`) Params that can be imported as JSON in your JS files, e.g.
+
+ ```go-html-template
+ {{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }}
+ ```
+
+ And then in your JS file:
+
+ ```js
+ import * as params from '@params';
+ ```
+
+ Note that this is meant for small data sets, e.g., configuration settings. For larger data sets, please put/mount the files into `assets` and import them directly.
+
+minify
+: (`bool`) Whether to minify the generated CSS code. Default is `false`.
+
+loaders
+: {{< new-in 0.140.0 />}}
+: (`map`) Configuring a loader for a given file type lets you load that file type with an `import` statement or a `require` call. For example, configuring the `.png` file extension to use the data URL loader means importing a `.png` file gives you a data URL containing the contents of that image. Loaders available are `none`, `base64`, `binary`, `copy`, `css`, `dataurl`, `default`, `empty`, `file`, `global-css`, `js`, `json`, `jsx`, `local-css`, `text`, `ts`, `tsx`. See <https://esbuild.github.io/api/#loader>.
+
+inject
+: (`slice`) This option allows you to automatically replace a global variable with an import from another file. The path names must be relative to `assets`. See <https://esbuild.github.io/api/#inject>.
+
+shims
+: (`map`) This option allows swapping out a component with another. A common use case is to load dependencies like React from a CDN (with _shims_) when in production, but running with the full bundled `node_modules` dependency during development:
+
+ ```go-html-template
+ {{ $shims := dict "react" "js/shims/react.js" "react-dom" "js/shims/react-dom.js" }}
+ {{ $js = $js | js.Build dict "shims" $shims }}
+ ```
+
+ The _shim_ files may look like these:
+
+ ```js
+ // js/shims/react.js
+ module.exports = window.React;
+ ```
+
+ ```js
+ // js/shims/react-dom.js
+ module.exports = window.ReactDOM;
+ ```
+
+ With the above, these imports should work in both scenarios:
+
+ ```js
+ import * as React from 'react';
+ import * as ReactDOM from 'react-dom/client';
+ ```
+
+target
+: (`string`) The language target. One of: `es5`, `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020`, `es2021`, `es2022`, `es2023`, `es2024`, or `esnext`. Default is `esnext`.
+
+platform
+: {{< new-in 0.140.0 />}}
+: (`string`) One of `browser`, `node`, `neutral`. Default is `browser`. See <https://esbuild.github.io/api/#platform>.
+
+externals
+: (`slice`) External dependencies. Use this to trim dependencies you know will never be executed. See <https://esbuild.github.io/api/#external>.
+
+defines
+: (`map`) This option allows you to define a set of string replacements to be performed when building. It must be a map where each key will be replaced by its value.
+
+ ```go-html-template
+ {{ $defines := dict "process.env.NODE_ENV" `"development"` }}
+ ```
+
+drop
+: {{< new-in 0.144.0 />}}
+: (`string`) Edit your source code before building to drop certain constructs: One of `debugger` or `console`.
+: See <https://esbuild.github.io/api/#drop>
+
+sourceMap
+: (`string`) The type of source map to generate. One of `external`, `inline`, `linked`, or `none`. Default is `none`. Linked and external source maps will be written to the target with the output file name + ".map". When `linked` a `sourceMappingURL` will also be written to the output file.
+
+sourcesContent
+: {{< new-in 0.140.0 />}}
+: (`bool`) Whether to include the content of the source files in the source map. Default is `true`.
+
+JSX
+: (`string`) How to handle/transform JSX syntax. One of: `transform`, `preserve`, `automatic`. Default is `transform`. Notably, the `automatic` transform was introduced in React 17+ and will cause the necessary JSX helper functions to be imported automatically. See <https://esbuild.github.io/api/#jsx>.
+
+JSXImportSource
+: (`string`) Which library to use to automatically import its JSX helper functions from. This only works if `JSX` is set to `automatic`. The specified library needs to be installed through npm and expose certain exports. See <https://esbuild.github.io/api/#jsx-import-source>.
+
+ The combination of `JSX` and `JSXImportSource` is helpful if you want to use a non-React JSX library like Preact, e.g.:
+
+ ```go-html-template
+ {{ $js := resources.Get "js/main.jsx" | js.Build (dict "JSX" "automatic" "JSXImportSource" "preact") }}
+ ```
+
+ With the above, you can use Preact components and JSX without having to manually import `h` and `Fragment` every time:
+
+ ```jsx
+ import { render } from 'preact';
+
+ const App = () => <>Hello world!</>;
+
+ const container = document.getElementById('app');
+ if (container) render(<App />, container);
+ ```
diff --git a/documents/markdown/hugo-docs/en__common_functions_locales.md b/documents/markdown/hugo-docs/en__common_functions_locales.md
new file mode 100644
index 0000000..1cfd7a1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_functions_locales.md
@@ -0,0 +1,8 @@
+---
+_comment: Do not remove front matter.
+---
+
+> [!note]
+> Localization of dates, currencies, numbers, and percentages is performed by the [gohugoio/locales] package. The language tag of the current site must match one of the listed locales.
+
+[gohugoio/locales]: https://github.com/gohugoio/locales
diff --git a/documents/markdown/hugo-docs/en__common_functions_reflect_image-reflection-functions.md b/documents/markdown/hugo-docs/en__common_functions_reflect_image-reflection-functions.md
new file mode 100644
index 0000000..2b49b19
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_functions_reflect_image-reflection-functions.md
@@ -0,0 +1,49 @@
+---
+_comment: Do not remove front matter.
+---
+
+## Image operations
+
+Use these functions to determine which operations Hugo supports for a given resource. While Hugo classifies a variety of file types as image resources, its ability to process them or extract metadata varies by format.
+
+- [`reflect.IsImageResource`][]: {{% get-page-desc "/functions/reflect/isimageresource" %}}
+- [`reflect.IsImageResourceProcessable`][]: {{% get-page-desc "/functions/reflect/isimageresourceprocessable" %}}
+- [`reflect.IsImageResourceWithMeta`][]: {{% get-page-desc "/functions/reflect/isimageresourcewithmeta" %}}
+
+The table below shows the values these functions return for various file formats. Use it to determine which checks are required before calling specific methods in your templates.
+
+|Format|IsImageResource|IsImageResourceProcessable|IsImageResourceWithMeta|
+|:-----|:--------------|:-------------------------|:----------------------|
+|AVIF |true |**false** |true |
+|BMP |true |true |true |
+|GIF |true |true |true |
+|HEIC |true |**false** |true |
+|HEIF |true |**false** |true |
+|ICO |true |**false** |**false** |
+|JPEG |true |true |true |
+|PNG |true |true |true |
+|SVG |true |**false** |**false** |
+|TIFF |true |true |true |
+|WebP |true |true |true |
+
+This contrived example demonstrates how to iterate through resources and use these functions to apply the appropriate handling for each image format.
+
+```go-html-template
+{{ range resources.Match "**" }}
+ {{ if reflect.IsImageResource . }}
+ {{ if reflect.IsImageResourceProcessable . }}
+ {{ with .Process "resize 300x webp" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+ {{ else if reflect.IsImageResourceWithMeta . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ else }}
+ <img src="{{ .RelPermalink }}" alt="">
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+[`reflect.IsImageResource`]: /functions/reflect/isimageresource/
+[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
+[`reflect.IsImageResourceWithMeta`]: /functions/reflect/isimageresourcewithmeta/
diff --git a/documents/markdown/hugo-docs/en__common_functions_regular-expressions.md b/documents/markdown/hugo-docs/en__common_functions_regular-expressions.md
new file mode 100644
index 0000000..58f81a2
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_functions_regular-expressions.md
@@ -0,0 +1,12 @@
+---
+_comment: Do not remove front matter.
+---
+
+When specifying the regular expression, use a raw [string literal] (backticks) instead of an interpreted string literal (double quotes) to simplify the syntax. With an interpreted string literal you must escape backslashes.
+
+Go's regular expression package implements the [RE2 syntax]. The RE2 syntax is a subset of that accepted by [PCRE], roughly speaking, and with various [caveats]. Note that the RE2 `\C` escape sequence is not supported.
+
+[caveats]: https://swtch.com/~rsc/regexp/regexp3.html#caveats
+[PCRE]: https://www.pcre.org/
+[RE2 syntax]: https://github.com/google/re2/wiki/Syntax/
+[string literal]: https://go.dev/ref/spec#String_literals
diff --git a/documents/markdown/hugo-docs/en__common_functions_truthy-falsy.md b/documents/markdown/hugo-docs/en__common_functions_truthy-falsy.md
new file mode 100644
index 0000000..e15e58d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_functions_truthy-falsy.md
@@ -0,0 +1,7 @@
+---
+_comment: Do not remove front matter.
+---
+
+The falsy values are `false`, `0`, any `nil` pointer or interface value, any array, slice, map, or string of length zero, and zero `time.Time` values.
+
+Everything else is truthy.
diff --git a/documents/markdown/hugo-docs/en__common_functions_urls_anchorize-vs-urlize.md b/documents/markdown/hugo-docs/en__common_functions_urls_anchorize-vs-urlize.md
new file mode 100644
index 0000000..e00c181
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_functions_urls_anchorize-vs-urlize.md
@@ -0,0 +1,35 @@
+---
+_comment: Do not remove front matter.
+---
+
+The [`anchorize`] and [`urlize`] functions are similar:
+
+[`anchorize`]: /functions/urls/anchorize/
+[`urlize`]: /functions/urls/urlize/
+
+- Use the `anchorize` function to generate an HTML `id` attribute value
+- Use the `urlize` function to sanitize a string for usage in a URL
+
+For example:
+
+```go-html-template
+{{ $s := "A B C" }}
+{{ $s | anchorize }} → a-b-c
+{{ $s | urlize }} → a-b-c
+
+{{ $s := "a b c" }}
+{{ $s | anchorize }} → a-b---c
+{{ $s | urlize }} → a-b-c
+
+{{ $s := "< a, b, & c >" }}
+{{ $s | anchorize }} → -a-b--c-
+{{ $s | urlize }} → a-b-c
+
+{{ $s := "main.go" }}
+{{ $s | anchorize }} → maingo
+{{ $s | urlize }} → main.go
+
+{{ $s := "Hugö" }}
+{{ $s | anchorize }} → hugö
+{{ $s | urlize }} → hug%C3%B6
+```
diff --git a/documents/markdown/hugo-docs/en__common_glob-patterns.md b/documents/markdown/hugo-docs/en__common_glob-patterns.md
new file mode 100644
index 0000000..d3092de
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_glob-patterns.md
@@ -0,0 +1,23 @@
+---
+_comment: Do not remove front matter.
+---
+
+Path|Pattern|Match
+:--|:--|:--
+`images/foo/a.jpg`|`images/foo/*.jpg`|`true`
+`images/foo/a.jpg`|`images/foo/*.*`|`true`
+`images/foo/a.jpg`|`images/foo/*`|`true`
+`images/foo/a.jpg`|`images/*/*.jpg`|`true`
+`images/foo/a.jpg`|`images/*/*.*`|`true`
+`images/foo/a.jpg`|`images/*/*`|`true`
+`images/foo/a.jpg`|`*/*/*.jpg`|`true`
+`images/foo/a.jpg`|`*/*/*.*`|`true`
+`images/foo/a.jpg`|`*/*/*`|`true`
+`images/foo/a.jpg`|`**/*.jpg`|`true`
+`images/foo/a.jpg`|`**/*.*`|`true`
+`images/foo/a.jpg`|`**/*`|`true`
+`images/foo/a.jpg`|`**`|`true`
+`images/foo/a.jpg`|`*/*.jpg`|`false`
+`images/foo/a.jpg`|`*.jpg`|`false`
+`images/foo/a.jpg`|`*.*`|`false`
+`images/foo/a.jpg`|`*`|`false`
diff --git a/documents/markdown/hugo-docs/en__common_gomodules-info.md b/documents/markdown/hugo-docs/en__common_gomodules-info.md
new file mode 100644
index 0000000..1eefff5
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_gomodules-info.md
@@ -0,0 +1,14 @@
+---
+_comment: Do not remove front matter.
+---
+
+> [!note] Hugo Modules are Go Modules
+> You need [Go] version 1.18 or later and [Git] to use Hugo Modules. For older sites hosted on Netlify, please ensure the `GO_VERSION` environment variable is set to `1.18` or higher.
+>
+> Go Modules resources:
+>
+> - [go.dev/wiki/Modules](https://go.dev/wiki/Modules)
+> - [blog.golang.org/using-go-modules](https://go.dev/blog/using-go-modules)
+
+[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+[Go]: https://go.dev/doc/install
diff --git a/documents/markdown/hugo-docs/en__common_installation_01-editions.md b/documents/markdown/hugo-docs/en__common_installation_01-editions.md
new file mode 100644
index 0000000..f8f73b3
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_installation_01-editions.md
@@ -0,0 +1,23 @@
+---
+_comment: Do not remove front matter.
+---
+
+## Editions
+
+Hugo is available in several editions. Use the standard edition unless you need additional features.
+
+Feature|standard|deploy (1)|extended|extended/deploy
+:--|:-:|:-:|:-:|:-:
+Core features|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+Direct cloud deployment (2)|:x:|:heavy_check_mark:|:x:|:heavy_check_mark:
+LibSass support (3)|:x:|:x:|:heavy_check_mark:|:heavy_check_mark:
+
+(1) {{< new-in v0.159.2 />}}
+
+(2) Deploy your site directly to a Google Cloud Storage bucket, an AWS S3 bucket, or an Azure Storage container. See [details].
+
+(3) [Transpile Sass to CSS] via embedded LibSass. Note that embedded LibSass was deprecated in v0.153.0 and will be removed in a future release. Use the [Dart Sass] transpiler instead, which is compatible with any edition.
+
+[dart sass]: /functions/css/sass/#dart-sass
+[transpile sass to css]: /functions/css/sass/
+[details]: /host-and-deploy/deploy-with-hugo-deploy/
diff --git a/documents/markdown/hugo-docs/en__common_installation_02-prerequisites.md b/documents/markdown/hugo-docs/en__common_installation_02-prerequisites.md
new file mode 100644
index 0000000..293645d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_installation_02-prerequisites.md
@@ -0,0 +1,43 @@
+---
+_comment: Do not remove front matter.
+---
+
+## Prerequisites
+
+Although not required in all cases, [Git], [Go], and [Dart Sass] are commonly used when working with Hugo.
+
+Git is required to:
+
+- Build Hugo from source
+- Use the [Hugo Modules] feature
+- Install a theme as a Git submodule
+- Access [commit information] from a local Git repository
+- Host your site on [CI/CD](g) platforms such as [Cloudflare][], [GitHub Pages][], [GitLab Pages][], [Netlify][], [Render][], or [Vercel][]
+
+Go is required to:
+
+- Build Hugo from source
+- Use the Hugo Modules feature
+
+Dart Sass is required to transpile Sass to CSS when using the latest features of the Sass language.
+
+Please refer to the relevant documentation for installation instructions:
+
+- [Git][git install]
+- [Go][go install]
+- [Dart Sass][dart sass install]
+
+[Cloudflare]: /host-and-deploy/host-on-cloudflare/
+[commit information]: /methods/page/GitInfo
+[dart sass install]: /functions/css/sass/#dart-sass
+[dart sass]: https://sass-lang.com/dart-sass
+[git install]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+[git]: https://git-scm.com/
+[GitHub Pages]: /host-and-deploy/host-on-github-pages/
+[GitLab Pages]: /host-and-deploy/host-on-gitlab-pages/
+[go install]: https://go.dev/doc/install
+[go]: https://go.dev/
+[hugo modules]: /hugo-modules/
+[Netlify]: /host-and-deploy/host-on-netlify/
+[Render]: /host-and-deploy/host-on-render/
+[Vercel]: /host-and-deploy/host-on-vercel/
diff --git a/documents/markdown/hugo-docs/en__common_installation_03-prebuilt-binaries.md b/documents/markdown/hugo-docs/en__common_installation_03-prebuilt-binaries.md
new file mode 100644
index 0000000..aa8268f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_installation_03-prebuilt-binaries.md
@@ -0,0 +1,19 @@
+---
+_comment: Do not remove front matter.
+---
+
+## Prebuilt binaries
+
+Prebuilt binaries are available for a variety of operating systems and architectures. Visit the [latest release] page, and scroll down to the Assets section.
+
+1. Download the archive for the desired edition, operating system, and architecture
+1. Extract the archive
+1. Move the executable to the desired directory
+1. Add this directory to the PATH environment variable
+1. Verify that you have _execute_ permission on the file
+
+Please consult your operating system documentation if you need help setting file permissions or modifying your PATH environment variable.
+
+If you do not see a prebuilt binary for the desired edition, operating system, and architecture, install Hugo using one of the methods described below.
+
+[latest release]: https://github.com/gohugoio/hugo/releases/latest
diff --git a/documents/markdown/hugo-docs/en__common_installation_04-build-from-source.md b/documents/markdown/hugo-docs/en__common_installation_04-build-from-source.md
new file mode 100644
index 0000000..93f1d3a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_installation_04-build-from-source.md
@@ -0,0 +1,49 @@
+---
+_comment: Do not remove front matter.
+---
+
+## Build from source
+
+To build Hugo from source you must install:
+
+1. [Git]
+1. [Go] version 1.25.0 or later
+
+### Standard edition
+
+To build and install the standard edition:
+
+```sh
+CGO_ENABLED=0 go install github.com/gohugoio/hugo@latest
+```
+
+### Deploy edition
+
+{{< new-in v0.159.2 />}}
+
+To build and install the deploy edition:
+
+```sh
+CGO_ENABLED=0 go install -tags withdeploy github.com/gohugoio/hugo@latest
+```
+
+### Extended edition
+
+To build and install the extended edition, first install a C compiler such as [GCC] or [Clang] and then run the following command:
+
+```sh
+CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@latest
+```
+
+### Extended/deploy edition
+
+To build and install the extended/deploy edition, first install a C compiler such as [GCC] or [Clang] and then run the following command:
+
+```sh
+CGO_ENABLED=1 go install -tags extended,withdeploy github.com/gohugoio/hugo@latest
+```
+
+[Clang]: https://clang.llvm.org/
+[GCC]: https://gcc.gnu.org/
+[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+[Go]: https://go.dev/doc/install
diff --git a/documents/markdown/hugo-docs/en__common_installation_homebrew.md b/documents/markdown/hugo-docs/en__common_installation_homebrew.md
new file mode 100644
index 0000000..bc7902c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_installation_homebrew.md
@@ -0,0 +1,13 @@
+---
+_comment: Do not remove front matter.
+---
+
+### Homebrew
+
+[Homebrew] is a free and open-source package manager for macOS and Linux. To install the extended/deploy edition of Hugo:
+
+```sh
+brew install hugo
+```
+
+[Homebrew]: https://brew.sh/
diff --git a/documents/markdown/hugo-docs/en__common_menu-entries_pre-and-post.md b/documents/markdown/hugo-docs/en__common_menu-entries_pre-and-post.md
new file mode 100644
index 0000000..9f101b4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_menu-entries_pre-and-post.md
@@ -0,0 +1,39 @@
+---
+_comment: Do not remove front matter.
+---
+
+In this project configuration we enable rendering of [emoji shortcodes], and add emoji shortcodes before (pre) and after (post) each menu entry:
+
+{{< code-toggle file=hugo >}}
+enableEmoji = true
+
+[[menus.main]]
+name = 'About'
+pageRef = '/about'
+post = ':point_left:'
+pre = ':point_right:'
+weight = 10
+
+[[menus.main]]
+name = 'Contact'
+pageRef = '/contact'
+post = ':arrow_left:'
+pre = ':arrow_right:'
+weight = 20
+{{< /code-toggle >}}
+
+To render the menu:
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main }}
+ <li>
+ {{ .Pre | markdownify }}
+ <a href="{{ .URL }}">{{ .Name }}</a>
+ {{ .Post | markdownify }}
+ </li>
+ {{ end }}
+</ul>
+```
+
+[emoji shortcodes]: /quick-reference/emojis/
diff --git a/documents/markdown/hugo-docs/en__common_menu-entry-properties.md b/documents/markdown/hugo-docs/en__common_menu-entry-properties.md
new file mode 100644
index 0000000..daeadd7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_menu-entry-properties.md
@@ -0,0 +1,31 @@
+---
+_comment: Do not remove front matter.
+---
+
+<!--
+This description list intentionally excludes the `pageRef` and `url` properties. Add those properties manually after using the include shortcode to include this list.
+-->
+
+identifier
+: (`string`) Required when two or more menu entries have the same `name`, or when localizing the `name` using translation tables. Must start with a letter, followed by letters, digits, or underscores.
+
+name
+: (`string`) The text to display when rendering the menu entry.
+
+params
+: (`map`) User-defined properties for the menu entry.
+
+parent
+: (`string`) The `identifier` of the parent menu entry. If `identifier` is not defined, use `name`. Required for child entries in a nested menu.
+
+post
+: (`string`) The HTML to append when rendering the menu entry.
+
+pre
+: (`string`) The HTML to prepend when rendering the menu entry.
+
+title
+: (`string`) The HTML `title` attribute of the rendered menu entry.
+
+weight
+: (`int`) A non-zero integer indicating the entry's position relative the root of the menu, or to its parent for a child entry. Lighter entries float to the top, while heavier entries sink to the bottom.
diff --git a/documents/markdown/hugo-docs/en__common_methods_output-formats_to-use-this-method.md b/documents/markdown/hugo-docs/en__common_methods_output-formats_to-use-this-method.md
new file mode 100644
index 0000000..027e89b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_methods_output-formats_to-use-this-method.md
@@ -0,0 +1,9 @@
+---
+_comment: Do not remove front matter.
+---
+
+To use this method you must first select a specific [output format](g) from a page's [`OutputFormats`][] collection using the [`Get`][] or [`Canonical`][] methods.
+
+[`Canonical`]: /methods/page/outputformats/#canonical
+[`Get`]: /methods/page/outputformats/#get
+[`OutputFormats`]: /methods/page/outputformats/
diff --git a/documents/markdown/hugo-docs/en__common_methods_page_next-and-prev.md b/documents/markdown/hugo-docs/en__common_methods_page_next-and-prev.md
new file mode 100644
index 0000000..75f120c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_methods_page_next-and-prev.md
@@ -0,0 +1,60 @@
+---
+_comment: Do not remove front matter.
+---
+
+Hugo determines the _next_ and _previous_ page by sorting the site's collection of regular pages according to this sorting hierarchy:
+
+Field|Precedence|Sort direction
+:--|:--|:--
+[`weight`]|1|descending
+[`date`]|2|descending
+[`linkTitle`]|3|descending
+[`path`]|4|descending
+
+[`date`]: /methods/page/date/
+[`weight`]: /methods/page/weight/
+[`linkTitle`]: /methods/page/linktitle/
+[`path`]: /methods/page/path/
+
+The sorted page collection used to determine the _next_ and _previous_ page is independent of other page collections, which may lead to unexpected behavior.
+
+For example, with this content structure:
+
+```text
+content/
+├── pages/
+│ ├── _index.md
+│ ├── page-1.md <-- front matter: weight = 10
+│ ├── page-2.md <-- front matter: weight = 20
+│ └── page-3.md <-- front matter: weight = 30
+└── _index.md
+```
+
+And these templates:
+
+```go-html-template {file="layouts/section.html"}
+{{ range .Pages.ByWeight }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+```go-html-template {file="layouts/page.html"}
+{{ with .Prev }}
+ <a href="{{ .RelPermalink }}">Previous</a>
+{{ end }}
+
+{{ with .Next }}
+ <a href="{{ .RelPermalink }}">Next</a>
+{{ end }}
+```
+
+When you visit page-2:
+
+- The `Prev` method points to page-3
+- The `Next` method points to page-1
+
+To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [project configuration], or use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility.
+
+[project configuration]: /configuration/page/
+[`Next`]: /methods/pages/prev
+[`Prev`]: /methods/pages/prev
diff --git a/documents/markdown/hugo-docs/en__common_methods_page_nextinsection-and-previnsection.md b/documents/markdown/hugo-docs/en__common_methods_page_nextinsection-and-previnsection.md
new file mode 100644
index 0000000..4ca8a4a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_methods_page_nextinsection-and-previnsection.md
@@ -0,0 +1,78 @@
+---
+_comment: Do not remove front matter.
+---
+
+Hugo determines the _next_ and _previous_ page by sorting the current section's regular pages according to this sorting hierarchy:
+
+Field|Precedence|Sort direction
+:--|:--|:--
+[`weight`]|1|descending
+[`date`]|2|descending
+[`linkTitle`]|3|descending
+[`path`]|4|descending
+
+[`date`]: /methods/page/date/
+[`weight`]: /methods/page/weight/
+[`linkTitle`]: /methods/page/linktitle/
+[`path`]: /methods/page/path/
+
+The sorted page collection used to determine the _next_ and _previous_ page is independent of other page collections, which may lead to unexpected behavior.
+
+For example, with this content structure:
+
+```text
+content/
+├── pages/
+│ ├── _index.md
+│ ├── page-1.md <-- front matter: weight = 10
+│ ├── page-2.md <-- front matter: weight = 20
+│ └── page-3.md <-- front matter: weight = 30
+└── _index.md
+```
+
+And these templates:
+
+```go-html-template {file="layouts/section.html"}
+{{ range .Pages.ByWeight }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+```go-html-template {file="layouts/page.html"}
+{{ with .PrevInSection }}
+ <a href="{{ .RelPermalink }}">Previous</a>
+{{ end }}
+
+{{ with .NextInSection }}
+ <a href="{{ .RelPermalink }}">Next</a>
+{{ end }}
+```
+
+When you visit page-2:
+
+- The `PrevInSection` method points to page-3
+- The `NextInSection` method points to page-1
+
+To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [project configuration], or use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility.
+
+[project configuration]: /configuration/page/
+[`Next`]: /methods/pages/prev
+[`Prev`]: /methods/pages/prev
+
+## Example
+
+Code defensively by checking for page existence:
+
+```go-html-template
+{{ with .PrevInSection }}
+ <a href="{{ .RelPermalink }}">Previous</a>
+{{ end }}
+
+{{ with .NextInSection }}
+ <a href="{{ .RelPermalink }}">Next</a>
+{{ end }}
+```
+
+## Alternative
+
+Use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility.
diff --git a/documents/markdown/hugo-docs/en__common_methods_pages_group-sort-order.md b/documents/markdown/hugo-docs/en__common_methods_pages_group-sort-order.md
new file mode 100644
index 0000000..e2997a1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_methods_pages_group-sort-order.md
@@ -0,0 +1,5 @@
+---
+_comment: Do not remove front matter.
+---
+
+For the optional sort order, specify either `asc` for ascending order, or `desc` for descending order.
diff --git a/documents/markdown/hugo-docs/en__common_methods_pages_next-and-prev.md b/documents/markdown/hugo-docs/en__common_methods_pages_next-and-prev.md
new file mode 100644
index 0000000..5a92a7c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_methods_pages_next-and-prev.md
@@ -0,0 +1,72 @@
+---
+_comment: Do not remove front matter.
+---
+
+Hugo determines the _next_ and _previous_ page by sorting the page collection according to this sorting hierarchy:
+
+Field|Precedence|Sort direction
+:--|:--|:--
+[`weight`]|1|descending
+[`date`]|2|descending
+[`linkTitle`]|3|descending
+[`path`]|4|descending
+
+[`date`]: /methods/page/date/
+[`weight`]: /methods/page/weight/
+[`linkTitle`]: /methods/page/linktitle/
+[`path`]: /methods/page/path/
+
+The sorted page collection used to determine the _next_ and _previous_ page is independent of other page collections, which may lead to unexpected behavior.
+
+For example, with this content structure:
+
+```text
+content/
+├── pages/
+│ ├── _index.md
+│ ├── page-1.md <-- front matter: weight = 10
+│ ├── page-2.md <-- front matter: weight = 20
+│ └── page-3.md <-- front matter: weight = 30
+└── _index.md
+```
+
+And these templates:
+
+```go-html-template {file="layouts/section.html"}
+{{ range .Pages.ByWeight }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+```go-html-template {file="layouts/page.html"}
+{{ $pages := .CurrentSection.Pages.ByWeight }}
+
+{{ with $pages.Prev . }}
+ <a href="{{ .RelPermalink }}">Previous</a>
+{{ end }}
+
+{{ with $pages.Next . }}
+ <a href="{{ .RelPermalink }}">Next</a>
+{{ end }}
+```
+
+When you visit page-2:
+
+- The `Prev` method points to page-3
+- The `Next` method points to page-1
+
+To reverse the meaning of _next_ and _previous_ you can chain the [`Reverse`] method to the page collection definition:
+
+```go-html-template {file="layouts/page.html"}
+{{ $pages := .CurrentSection.Pages.ByWeight.Reverse }}
+
+{{ with $pages.Prev . }}
+ <a href="{{ .RelPermalink }}">Previous</a>
+{{ end }}
+
+{{ with $pages.Next . }}
+ <a href="{{ .RelPermalink }}">Next</a>
+{{ end }}
+```
+
+[`Reverse`]: /methods/pages/reverse/
diff --git a/documents/markdown/hugo-docs/en__common_methods_resource_global-page-remote-resources.md b/documents/markdown/hugo-docs/en__common_methods_resource_global-page-remote-resources.md
new file mode 100644
index 0000000..49146ae
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_methods_resource_global-page-remote-resources.md
@@ -0,0 +1,6 @@
+---
+_comment: Do not remove front matter.
+---
+
+> [!note]
+> Use this method with [global resources](g), [page resources](g), or [remote resources](g).
diff --git a/documents/markdown/hugo-docs/en__common_methods_resource_processing-spec.md b/documents/markdown/hugo-docs/en__common_methods_resource_processing-spec.md
new file mode 100644
index 0000000..140a4eb
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_methods_resource_processing-spec.md
@@ -0,0 +1,73 @@
+---
+_comment: Do not remove front matter.
+---
+
+## Processing specification
+
+The processing specification is a space-delimited, case-insensitive list containing one or more of the following options in any sequence:
+
+action
+: Specify one of `crop`, `fill`, `fit`, or `resize`. This is applicable to the [`Process`][] method and the [`images.Process`][] filter. If you specify an action, you must also provide dimensions.
+
+anchor
+: The focal point used when cropping or filling an image. Valid options include `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. The `Smart` option utilizes the [`muesli/smartcrop`][] package to identify the most interesting area of the image. This defaults to the [`anchor`][] parameter in your project configuration.
+
+background color
+: The background color used when converting transparent images to formats that do not support transparency, such as PNG to JPEG. This color also fills the empty space created when rotating an image by a non-orthogonal angle if the space is not transparent and a background color is not specified in the processing specification. The value must be an RGB [hexadecimal color][]. This defaults to the [`bgColor`][] parameter in your project configuration.
+
+compression
+: {{< new-in 0.153.5 />}}
+: The encoding strategy used for the image. Options are `lossy` or `lossless`. Note that `lossless` is only supported by the WebP format. This defaults to the [`compression`][] parameter in your project configuration.
+
+dimensions
+: The dimensions of the resulting image, in pixels. The format is `WIDTHxHEIGHT` where `WIDTH` and `HEIGHT` are whole numbers. When resizing an image, you may specify only the width (such as `600x`) or only the height (such as `x400`) for proportional scaling. Specifying both width and height when resizing an image may result in non-proportional scaling. When cropping, fitting, or filling, you must provide both width and height such as `600x400`.
+
+format
+: The format of the resulting image. Valid options include `bmp`, `gif`, `jpeg`, `png`, `tiff`, or `webp`. This defaults to the format of the source image.
+
+hint
+: The encoding preset used when processing WebP images, equivalent to the `-preset` flag for the [`cwebp`][] CLI. Valid options include `drawing`, `icon`, `photo`, `picture`, or `text`. This defaults to the [`hint`][] parameter in your project configuration.
+
+ Value|Example
+ :--|:--
+ `drawing`|Hand or line drawing with high-contrast details
+ `icon`|Small colorful image
+ `photo`|Outdoor photograph with natural lighting
+ `picture`|Indoor photograph such as a portrait
+ `text`|Image that is primarily text
+
+quality
+: The visual fidelity of the image, applicable to JPEG and WebP formats when using `lossy` compression. The format is `qQUALITY` where `QUALITY` is a whole number between `1` and `100`, inclusive. Lower numbers prioritize smaller file size, while higher numbers prioritize visual clarity. This defaults to the [`quality`][] parameter in your project configuration.
+
+resampling filter
+: The algorithm used to calculate new pixels when resizing, fitting, or filling an image. Common options include `box`, `lanczos`, `catmullRom`, `mitchellNetravali`, `linear`, or `nearestNeighbor`. This defaults to the [`resampleFilter`][] parameter in your project configuration.
+
+ Filter|Description
+ :--|:--
+ `box`|Simple and fast averaging filter appropriate for downscaling
+ `lanczos`|High-quality resampling filter for photographic images yielding sharp results
+ `catmullRom`|Sharp cubic filter that is faster than the Lanczos filter while providing similar results
+ `mitchellNetravali`|Cubic filter that produces smoother results with less ringing artifacts than CatmullRom
+ `linear`|Bilinear resampling filter, produces smooth output, faster than cubic filters
+ `nearestNeighbor`|Fastest resampling filter, no antialiasing
+
+ Refer to the [source documentation][] for a complete list of available resampling filters. If you wish to improve image quality at the expense of performance, you may wish to experiment with the alternative filters.
+
+rotation
+: The number of whole degrees to rotate an image counter-clockwise. The format is `rDEGREES` where `DEGREES` is a whole number. Hugo performs rotation before any other transformations, so your [target dimensions](#dimensions) and any [anchor](#anchor) should refer to the image orientation after rotation. Use `r90`, `r180`, or `r270` for orthogonal rotations, or arbitrary angles such as `r45`. To rotate clockwise, use a negative number such as `r-45`. To automatically rotate an image based on its Exif orientation tag, use the [`images.AutoOrient`][] filter instead of manual rotation.
+
+ Rotating by non-orthogonal values increases the image extents to fit the rotated corners. For formats supporting alpha channels such as PNG or WebP, this resulting empty space is transparent by default. If the target format does not support transparency such as JPEG, or if you explicitly specify a [background color](#background-color) in the processing specification, the space is filled. If a color is required but not specified in the processing string, it defaults to the [`bgColor`][] parameter in your project configuration.
+
+[`anchor`]: /configuration/imaging/#anchor
+[`bgcolor`]: /configuration/imaging/#bgcolor
+[`compression`]: /configuration/imaging/#compression
+[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
+[`muesli/smartcrop`]: https://github.com/muesli/smartcrop
+[`hint`]: /configuration/imaging/#hint
+[`images.AutoOrient`]: /functions/images/autoorient/
+[`images.Process`]: /functions/images/process/
+[`Process`]: /methods/resource/process
+[`quality`]: /configuration/imaging/#quality
+[`resampleFilter`]: /configuration/imaging/#resamplefilter
+[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
+[source documentation]: https://github.com/disintegration/imaging#image-resizing
diff --git a/documents/markdown/hugo-docs/en__common_methods_taxonomy_get-a-taxonomy-object.md b/documents/markdown/hugo-docs/en__common_methods_taxonomy_get-a-taxonomy-object.md
new file mode 100644
index 0000000..7538614
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_methods_taxonomy_get-a-taxonomy-object.md
@@ -0,0 +1,67 @@
+---
+_comment: Do not remove front matter.
+---
+
+Before we can use a `Taxonomy` method, we need to capture a `Taxonomy` object.
+
+## Capture a Taxonomy object
+
+Consider this project configuration:
+
+{{< code-toggle file=hugo >}}
+[taxonomies]
+genre = 'genres'
+author = 'authors'
+{{< /code-toggle >}}
+
+And this content structure:
+
+```text
+content/
+├── books/
+│ ├── and-then-there-were-none.md --> genres: suspense
+│ ├── death-on-the-nile.md --> genres: suspense
+│ └── jamaica-inn.md --> genres: suspense, romance
+│ └── pride-and-prejudice.md --> genres: romance
+└── _index.md
+```
+
+To capture the "genres" `Taxonomy` object from within any template, use the [`Taxonomies`] method on a `Site` object.
+
+```go-html-template
+{{ $taxonomyObject := .Site.Taxonomies.genres }}
+```
+
+To capture the "genres" `Taxonomy` object when rendering its page with a _taxonomy_ template, use the [`Terms`] method on the page's [`Data`] object:
+
+```go-html-template {file="layouts/taxonomy.html"}
+{{ $taxonomyObject := .Data.Terms }}
+```
+
+To inspect the data structure:
+
+```go-html-template
+<pre>{{ debug.Dump $taxonomyObject }}</pre>
+```
+
+Although the [`Alphabetical`] and [`ByCount`] methods provide a better data structure for ranging through the taxonomy, you can render the weighted pages by term directly from the `Taxonomy` object:
+
+```go-html-template
+{{ range $term, $weightedPages := $taxonomyObject }}
+ <h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a></h2>
+ <ul>
+ {{ range $weightedPages }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+In the example above, the first anchor element is a link to the term page.
+
+[`Alphabetical`]: /methods/taxonomy/alphabetical/
+[`ByCount`]: /methods/taxonomy/bycount/
+
+[`data`]: /methods/page/data/
+[`terms`]: /methods/page/data/#in-a-taxonomy-template
+[`taxonomies`]: /methods/site/taxonomies/
diff --git a/documents/markdown/hugo-docs/en__common_methods_taxonomy_ordered-taxonomy-element-methods.md b/documents/markdown/hugo-docs/en__common_methods_taxonomy_ordered-taxonomy-element-methods.md
new file mode 100644
index 0000000..ec5f8e4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_methods_taxonomy_ordered-taxonomy-element-methods.md
@@ -0,0 +1,24 @@
+---
+_comment: Do not remove front matter.
+---
+
+An ordered taxonomy is a slice, where each element is an object that contains the term and a slice of its weighted pages.
+
+Each element of the slice provides these methods:
+
+Count
+: (`int`) Returns the number of pages to which the term is assigned.
+
+Page
+: (`page.Page`) Returns the term's `Page` object, useful for linking to the term page.
+
+Pages
+: (`page.Pages`) Returns a `Pages` object containing the `Page` objects to which the term is assigned, sorted by [taxonomic weight](g). To sort or group, use any of the [methods] available to the `Pages` object. For example, sort by the last modification date.
+
+Term
+: (`string`) Returns the term name.
+
+WeightedPages
+: (`page.WeightedPages`) Returns a slice of weighted pages to which the term is assigned, sorted by taxonomic weight. The `Pages` method above is more flexible, allowing you to sort and group.
+
+[methods]: /methods/pages/
diff --git a/documents/markdown/hugo-docs/en__common_parsable-date-time-strings.md b/documents/markdown/hugo-docs/en__common_parsable-date-time-strings.md
new file mode 100644
index 0000000..9284276
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_parsable-date-time-strings.md
@@ -0,0 +1,14 @@
+---
+_comment: Do not remove front matter.
+---
+
+Format|Time zone
+:--|:--
+`2023-10-15T13:18:50-07:00`|`America/Los_Angeles`
+`2023-10-15T13:18:50-0700`|`America/Los_Angeles`
+`2023-10-15T13:18:50Z`|`Etc/UTC`
+`2023-10-15T13:18:50`|Default is `Etc/UTC`
+`2023-10-15`|Default is `Etc/UTC`
+`15 Oct 2023`|Default is `Etc/UTC`
+
+The last three examples are not fully qualified, and default to the `Etc/UTC` time zone.
diff --git a/documents/markdown/hugo-docs/en__common_permalink-tokens.md b/documents/markdown/hugo-docs/en__common_permalink-tokens.md
new file mode 100644
index 0000000..fa8308a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_permalink-tokens.md
@@ -0,0 +1,71 @@
+---
+_comment: Do not remove front matter.
+---
+
+`:year`
+: The 4-digit year as defined in the front matter `date` field.
+
+`:month`
+: The 2-digit month as defined in the front matter `date` field.
+
+`:monthname`
+: The name of the month as defined in the front matter `date` field.
+
+`:day`
+: The 2-digit day as defined in the front matter `date` field.
+
+`:weekday`
+: The 1-digit day of the week as defined in the front matter `date` field (Sunday = `0`).
+
+`:weekdayname`
+: The name of the day of the week as defined in the front matter `date` field.
+
+`:yearday`
+: The 1- to 3-digit day of the year as defined in the front matter `date` field.
+
+`:section`
+: The content's section.
+
+`:sectionslug`
+: {{< new-in 0.149.0 />}}
+: The content's section using slugified section name. The slugified section name is the `slug` as defined in front matter, else the `title` as defined in front matter, else the automatic title.
+
+`:sections`
+: The content's sections hierarchy. You can use a selection of the sections using _slice syntax_: `:sections[1:]` includes all but the first, `:sections[:last]` includes all but the last, `:sections[last]` includes only the last, `:sections[1:2]` includes section 2 and 3. Note that this slice access will not throw any out-of-bounds errors, so you don't have to be exact.
+
+`:sectionslugs`
+: {{< new-in 0.149.0 />}}
+: The content's sections hierarchy using slugified section names. The slugified section name is the `slug` as defined in front matter, else the `title` as defined in front matter, else the automatic title. You can use a selection of the sections using _slice syntax_: `:sectionslugs[1:]` includes all but the first, `:sectionslugs[:last]` includes all but the last, `:sectionslugs[last]` includes only the last, `:sectionslugs[1:2]` includes section 2 and 3. Note that this slice access will not throw any out-of-bounds errors, so you don't have to be exact.
+
+`:title`
+: The `title` as defined in front matter, else the automatic title. Hugo generates titles automatically for section, taxonomy, and term pages that are not backed by a file.
+
+`:slug`
+: The `slug` as defined in front matter, else the `title` as defined in front matter, else the automatic title. Hugo generates titles automatically for section, taxonomy, and term pages that are not backed by a file.
+
+`:filename`
+: {{< deprecated-in v0.144.0 />}}
+: Use `:contentbasename` instead.
+
+`:slugorfilename`
+: {{< deprecated-in v0.144.0 />}}
+: Use `:slugorcontentbasename` instead.
+
+`:contentbasename`
+: {{< new-in 0.144.0 />}}
+: The [content base name].
+
+[content base name]: /methods/page/file/#contentbasename
+
+`:slugorcontentbasename`
+: {{< new-in 0.144.0 />}}
+: The `slug` as defined in front matter, else the [content base name].
+
+For time-related values, you can also use the layout string components defined in Go's [time package]. For example:
+
+[time package]: https://pkg.go.dev/time#pkg-constants
+
+{{< code-toggle file=hugo >}}
+permalinks:
+ posts: /:06/:1/:2/:title/
+{{< /code-toggle >}}
diff --git a/documents/markdown/hugo-docs/en__common_ref-and-relref-error-handling.md b/documents/markdown/hugo-docs/en__common_ref-and-relref-error-handling.md
new file mode 100644
index 0000000..9ec185d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_ref-and-relref-error-handling.md
@@ -0,0 +1,10 @@
+---
+_comment: Do not remove front matter.
+---
+
+By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your project configuration, and specify a URL to return when the path cannot be resolved.
+
+{{< code-toggle file=hugo >}}
+refLinksErrorLevel = 'warning'
+refLinksNotFoundURL = '/some/other/url'
+{{< /code-toggle >}}
diff --git a/documents/markdown/hugo-docs/en__common_ref-and-relref-options.md b/documents/markdown/hugo-docs/en__common_ref-and-relref-options.md
new file mode 100644
index 0000000..ed0dd14
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_ref-and-relref-options.md
@@ -0,0 +1,12 @@
+---
+_comment: Do not remove front matter.
+---
+
+path
+: (`string`) The path to the target page. Paths without a leading slash (`/`) are resolved first relative to the current page, and then relative to the rest of the site.
+
+lang
+: (`string`) The language of the target page. Default is the current language. Optional.
+
+outputFormat
+: (`string`) The output format of the target page. Default is the current output format. Optional.
diff --git a/documents/markdown/hugo-docs/en__common_render-hooks_pageinner.md b/documents/markdown/hugo-docs/en__common_render-hooks_pageinner.md
new file mode 100644
index 0000000..4cde593
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_render-hooks_pageinner.md
@@ -0,0 +1,45 @@
+---
+_comment: Do not remove front matter.
+---
+
+## PageInner details
+
+The primary use case for `PageInner` is to resolve links and [page resources](g) relative to an included `Page`. For example, create an "include" shortcode to compose a page from multiple content files, while preserving a global context for footnotes and the table of contents:
+
+```go-html-template {file="layouts/_shortcodes/include.html" copy=true}
+{{ with .Get 0 }}
+ {{ with $.Page.GetPage . }}
+ {{- .RenderShortcodes }}
+ {{ else }}
+ {{ errorf "The %q shortcode was unable to find %q. See %s" $.Name . $.Position }}
+ {{ end }}
+{{ else }}
+ {{ errorf "The %q shortcode requires a positional parameter indicating the logical path of the file to include. See %s" .Name .Position }}
+{{ end }}
+```
+
+Then call the shortcode in your Markdown:
+
+```text {file="content/posts/post-1.md"}
+{{%/* include "/posts/post-2" */%}}
+```
+
+Any render hook triggered while rendering `/posts/post-2` will get:
+
+- `/posts/post-1` when calling `Page`
+- `/posts/post-2` when calling `PageInner`
+
+`PageInner` falls back to the value of `Page` if not relevant, and always returns a value.
+
+> [!note]
+> The `PageInner` method is only relevant for shortcodes that invoke the [`RenderShortcodes`] method, and you must call the shortcode using [Markdown notation].
+
+As a practical example, Hugo's embedded link and image render hooks use the `PageInner` method to resolve markdown link and image destinations. See the source code for each:
+
+- [Embedded link render hook]
+- [Embedded image render hook]
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes/
+[Markdown notation]: /content-management/shortcodes/#notation
+[Embedded link render hook]: <{{% eturl render-link %}}>
+[Embedded image render hook]: <{{% eturl render-image %}}>
diff --git a/documents/markdown/hugo-docs/en__common_scratch-pad-scope.md b/documents/markdown/hugo-docs/en__common_scratch-pad-scope.md
new file mode 100644
index 0000000..789b943
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_scratch-pad-scope.md
@@ -0,0 +1,21 @@
+---
+_comment: Do not remove front matter.
+---
+
+## Scope
+
+The method or function used to create a scratch pad determines its scope. For example, use the `Store` method on a `Page` object to create a scratch pad scoped to the page.
+
+Scope|Method or function
+:--|:--
+page|[`PAGE.Store`]
+site|[`SITE.Store`]
+global|[`hugo.Store`]
+local|[`collections.NewScratch`]
+shortcode|[`SHORTCODE.Store`]
+
+[`page.store`]: /methods/page/store
+[`site.store`]: /methods/site/store
+[`hugo.store`]: /functions/hugo/store
+[`collections.newscratch`]: functions/collections/newscratch
+[`shortcode.store`]: /methods/shortcode/store
diff --git a/documents/markdown/hugo-docs/en__common_store-methods.md b/documents/markdown/hugo-docs/en__common_store-methods.md
new file mode 100644
index 0000000..1dd7761
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_store-methods.md
@@ -0,0 +1,86 @@
+---
+# Do not remove front matter.
+---
+
+## Methods
+
+### Set
+
+Sets the value of the given key.
+
+```go-html-template
+{{ .Store.Set "greeting" "Hello" }}
+```
+
+### Get
+
+Gets the value of the given key.
+
+```go-html-template
+{{ .Store.Set "greeting" "Hello" }}
+{{ .Store.Get "greeting" }} → Hello
+```
+
+### Add
+
+Adds the given value to the existing value(s) of the given key.
+
+For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list.
+
+```go-html-template
+{{ .Store.Set "greeting" "Hello" }}
+{{ .Store.Add "greeting" "Welcome" }}
+{{ .Store.Get "greeting" }} → HelloWelcome
+```
+
+```go-html-template
+{{ .Store.Set "total" 3 }}
+{{ .Store.Add "total" 7 }}
+{{ .Store.Get "total" }} → 10
+```
+
+```go-html-template
+{{ .Store.Set "greetings" (slice "Hello") }}
+{{ .Store.Add "greetings" (slice "Welcome" "Cheers") }}
+{{ .Store.Get "greetings" }} → [Hello Welcome Cheers]
+```
+
+### SetInMap
+
+Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`.
+
+```go-html-template
+{{ .Store.SetInMap "greetings" "english" "Hello" }}
+{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
+{{ .Store.Get "greetings" }} → map[english:Hello french:Bonjour]
+ ```
+
+### DeleteInMap
+
+Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
+
+```go-html-template
+{{ .Store.SetInMap "greetings" "english" "Hello" }}
+{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
+{{ .Store.DeleteInMap "greetings" "english" }}
+{{ .Store.Get "greetings" }} → map[french:Bonjour]
+```
+
+### GetSortedMapValues
+
+Returns an array of values from `key` sorted by `mapKey`.
+
+```go-html-template
+{{ .Store.SetInMap "greetings" "english" "Hello" }}
+{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
+{{ .Store.GetSortedMapValues "greetings" }} → [Hello Bonjour]
+```
+
+### Delete
+
+Removes the given key.
+
+```go-html-template
+{{ .Store.Set "greeting" "Hello" }}
+{{ .Store.Delete "greeting" }}
+```
diff --git a/documents/markdown/hugo-docs/en__common_syntax-highlighting-options.md b/documents/markdown/hugo-docs/en__common_syntax-highlighting-options.md
new file mode 100644
index 0000000..11348f6
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_syntax-highlighting-options.md
@@ -0,0 +1,57 @@
+---
+_comment: Do not remove front matter.
+---
+
+anchorLineNos
+: (`bool`) Whether to render each line number as an HTML anchor element, setting the `id` attribute of the surrounding `span` element to the line number. Irrelevant if `lineNos` is `false`. Default is `false`.
+
+codeFences
+: (`bool`) Whether to highlight fenced code blocks. Default is `true`.
+
+guessSyntax
+: (`bool`) Whether to automatically detect the language if the `LANG` argument is blank or set to a language for which there is no corresponding [lexer](g). Falls back to a plain text lexer if unable to automatically detect the language. Default is `false`.
+
+ > [!note]
+ > The Chroma syntax highlighter includes lexers for approximately 250 languages, but only 5 of these have implemented automatic language detection.
+
+hl_Lines
+: (`string`) A space-delimited list of lines to emphasize within the highlighted code. To emphasize lines 2, 3, 4, and 7, set this value to `2-4 7`. This option is independent of the `lineNoStart` option.
+
+hl_inline
+: (`bool`) Whether to render the highlighted code without a wrapping container. Default is `false`.
+
+lineAnchors
+: (`string`) When rendering a line number as an HTML anchor element, prepend this value to the `id` attribute of the surrounding `span` element. This provides unique `id` attributes when a page contains two or more code blocks. Irrelevant if `lineNos` or `anchorLineNos` is `false`.
+
+lineNoStart
+: (`int`) The number to display at the beginning of the first line. Irrelevant if `lineNos` is `false`. Default is `1`.
+
+lineNos
+: (`any`) Controls line number display. Default is `false`.
+
+ - `true`: Enable line numbers, controlled by `lineNumbersInTable`.
+ - `false`: Disable line numbers.
+ - `inline`: Enable inline line numbers (sets `lineNumbersInTable` to `false`).
+ - `table`: Enable table-based line numbers (sets `lineNumbersInTable` to `true`).
+
+lineNumbersInTable
+: (`bool`) Whether to render the highlighted code in an HTML table with two cells. The left table cell contains the line numbers, while the right table cell contains the code. Irrelevant if `lineNos` is `false`. Default is `true`.
+
+noClasses
+: (`bool`) Whether to use inline CSS styles instead of an external CSS file. Default is `true`. To use an external CSS file, set this value to `false` and generate the CSS file from the command line:
+
+ ```text
+ hugo gen chromastyles --style=monokai > syntax.css
+ ```
+
+style
+: (`string`) The CSS styles to apply to the highlighted code. Case-sensitive. Default is `monokai`. See [syntax highlighting styles].
+
+tabWidth
+: (`int`) Substitute this number of spaces for each tab character in your highlighted code. Irrelevant if `noClasses` is `false`. Default is `4`.
+
+wrapperClass
+: {{< new-in 0.140.2 />}}
+: (`string`) The class or classes to use for the outermost element of the highlighted code. Default is `highlight`.
+
+[syntax highlighting styles]: /quick-reference/syntax-highlighting-styles/
diff --git a/documents/markdown/hugo-docs/en__common_time-layout-string.md b/documents/markdown/hugo-docs/en__common_time-layout-string.md
new file mode 100644
index 0000000..3664eae
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__common_time-layout-string.md
@@ -0,0 +1,46 @@
+---
+_comment: Do not remove front matter.
+---
+
+Format a `time.Time` value based on [Go's reference time]:
+
+[Go's reference time]: https://pkg.go.dev/time#pkg-constants
+
+```text
+Mon Jan 2 15:04:05 MST 2006
+```
+
+Create a layout string using these components:
+
+Description|Valid components
+:--|:--
+Year|`"2006" "06"`
+Month|`"Jan" "January" "01" "1"`
+Day of the week|`"Mon" "Monday"`
+Day of the month|`"2" "_2" "02"`
+Day of the year|`"__2" "002"`
+Hour|`"15" "3" "03"`
+Minute|`"4" "04"`
+Second|`"5" "05"`
+AM/PM mark|`"PM"`
+Time zone offsets|`"-0700" "-07:00" "-07" "-070000" "-07:00:00"`
+
+Replace the sign in the layout string with a Z to print Z instead of an offset for the UTC zone.
+
+Description|Valid components
+:--|:--
+Time zone offsets|`"Z0700" "Z07:00" "Z07" "Z070000" "Z07:00:00"`
+
+```go-html-template
+{{ $t := "2023-01-27T23:44:58-08:00" }}
+{{ $t = time.AsTime $t }}
+{{ $t = $t.Format "Jan 02, 2006 3:04 PM Z07:00" }}
+
+{{ $t }} → Jan 27, 2023 11:44 PM -08:00
+```
+
+Strings such as `PST` and `CET` are not time zones. They are time zone _abbreviations_.
+
+Strings such as `-07:00` and `+01:00` are not time zones. They are time zone _offsets_.
+
+A time zone is a geographic area with the same local time. For example, the time zone abbreviated by `PST` and `PDT` (depending on Daylight Savings Time) is `America/Los_Angeles`.
diff --git a/documents/markdown/hugo-docs/en__index.md b/documents/markdown/hugo-docs/en__index.md
new file mode 100644
index 0000000..358f6a4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en__index.md
@@ -0,0 +1,4 @@
+---
+title: The world's fastest framework for building websites
+description: Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again.
+---
diff --git a/documents/markdown/hugo-docs/en_about__index.md b/documents/markdown/hugo-docs/en_about__index.md
new file mode 100644
index 0000000..e558009
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_about__index.md
@@ -0,0 +1,9 @@
+---
+title: About Hugo
+linkTitle: About
+description: Learn about Hugo and its features, privacy protections, and security model.
+categories: []
+keywords: []
+weight: 10
+aliases: [/about-hugo/,/docs/]
+---
diff --git a/documents/markdown/hugo-docs/en_about_features.md b/documents/markdown/hugo-docs/en_about_features.md
new file mode 100644
index 0000000..2c75edd
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_about_features.md
@@ -0,0 +1,144 @@
+---
+title: Features
+description: Hugo's rich and powerful feature set provides the framework and tools to create static sites that build in seconds, often less.
+categories: []
+keywords: []
+weight: 20
+---
+
+## Framework
+
+[Multiplatform]
+: Install Hugo's single executable on Linux, macOS, Windows, and more.
+
+[Multilingual]
+: Localize your project for each language and region, including translations, images, dates, currencies, numbers, percentages, and collation sequence. Hugo's multilingual framework supports single-host and multihost configurations.
+
+[Output formats]
+: Render each page of your project to one or more output formats, with granular control by page kind, section, and path. While HTML is the default output format, you can add JSON, RSS, CSV, and more. For example, create a REST API to access content.
+
+[Templates]
+: Create templates using variables, functions, and methods to transform your content, resources, and data into a published page. While HTML templates are the most common, you can create templates for any output format.
+
+[Themes]
+: Reduce development time and cost by using one of the hundreds of themes contributed by the Hugo community. Themes are available for corporate sites, documentation projects, image portfolios, landing pages, personal and professional blogs, resumes, CVs, and more.
+
+[Modules]
+: Reduce development time and cost by creating or importing packaged combinations of archetypes, assets, content, data, templates, translation tables, static files, or configuration settings. A module may serve as the basis for a new project, or to augment an existing project.
+
+[Privacy]
+: Configure your project to help comply with regional privacy regulations.
+
+[Security]
+: Hugo's security model is based on the premise that template and configuration authors are trusted, but content authors are not. This model enables generation of HTML output safe against code injection. Other protections prevent "shelling out" to arbitrary applications, limit access to specific environment variables, prevent connections to arbitrary remote data sources, and more.
+
+## Content authoring
+
+[Content formats]
+: Create your content using Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, or reStructuredText. Markdown is the default content format, conforming to the [CommonMark] and [GitHub Flavored Markdown] specifications.
+
+[Markdown attributes]
+: Apply HTML attributes such as `class` and `id` to Markdown images and block elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables.
+
+[Markdown extensions]
+: Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more.
+
+[Markdown render hooks]
+: Override the conversion of Markdown to HTML when rendering blockquotes, fenced code blocks, headings, images, links, and tables. For example, render every standalone image as an HTML `figure` element.
+
+[Diagrams]
+: Use fenced code blocks and Markdown render hooks to include diagrams in your content.
+
+[Mathematics]
+: Include mathematical equations and expressions in Markdown using LaTeX markup.
+
+[Syntax highlighting]
+: Syntactically highlight code examples using Hugo's embedded syntax highlighter, enabled by default for fenced code blocks in Markdown. The syntax highlighter supports hundreds of code languages and dozens of styles.
+
+[Shortcodes]
+: Use Hugo's embedded shortcodes, or create your own, to insert complex content. For example, use shortcodes to include `audio` and `video` elements, render tables from local or remote data sources, insert snippets from other pages, and more.
+
+## Content management
+
+[Multidimensional content model]
+: Generate pages across any combination of language, version, and role from a single source. This allows a single piece of content to be published to multiple [sites](g) within your project, removing the need to duplicate files for different audiences or versions.
+
+[Content adapters]
+: Create content adapters to dynamically add content when building your project. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML.
+
+[Taxonomies]
+: Classify content to establish simple or complex logical relationships between pages. For example, create an authors taxonomy, and assign one or more authors to each page. Among other uses, the taxonomy system provides an inverted, weighted index to render a list of related pages, ordered by relevance.
+
+[Data]
+: Augment your content using local or remote data sources including CSV, JSON, TOML, YAML, and XML. For example, create a shortcode to render an HTML table from a remote CSV file.
+
+[Menus]
+: Provide rapid access to content via Hugo's menu system, configured automatically, globally, or on a page-by-page basis. The menu system is a key component of Hugo's multilingual architecture.
+
+[URL management]
+: Serve any page from any path via global configuration or on a page-by-page basis.
+
+## Asset pipelines
+
+[CSS Processing]
+: Bundle, transform, minify, create source maps, perform SRI hashing, and integrate with PostCSS.
+
+[Image processing]
+: Convert, resize, crop, rotate, adjust colors, apply filters, overlay text and images, and extract metadata.
+
+[JavaScript bundling]
+: Transpile TypeScript and JSX to JavaScript, bundle, tree shake, minify, create source maps, and perform SRI hashing.
+
+[Sass processing]
+: Transpile Sass to CSS, bundle, tree shake, minify, create source maps, perform SRI hashing, and integrate with PostCSS.
+
+[Tailwind CSS processing]
+: Compile Tailwind CSS utility classes into standard CSS, bundle, tree shake, optimize, minify, perform SRI hashing, and integrate with PostCSS.
+
+## Performance
+
+[Caching]
+: Reduce build time and cost by rendering a _partial_ template once then cache the result, either globally or within a given context. For example, cache the result of an asset pipeline to prevent reprocessing on every rendered page.
+
+[Segmentation]
+: Reduce build time and cost by partitioning your sites into segments. For example, render the home page and the "news section" every hour, and render the entire project once a week.
+
+[Minification]
+: Minify HTML, CSS, and JavaScript to reduce file size, bandwidth consumption, and loading times.
+
+[Multilingual]: /content-management/multilingual/
+[Multiplatform]: /installation/
+[Output formats]: /configuration/output-formats/
+[Templates]: /templates/introduction/
+[Themes]: https://themes.gohugo.io/
+[Modules]: /hugo-modules/
+[Privacy]: /configuration/privacy/
+[Security]: /about/security/
+
+[Content formats]: /content-management/formats/
+[CommonMark]: https://spec.commonmark.org/current/
+[GitHub Flavored Markdown]: https://github.github.com/gfm/
+[Markdown attributes]: /content-management/markdown-attributes/
+[Markdown extensions]: /configuration/markup/#extensions
+[Markdown render hooks]: /render-hooks/introduction/
+[Diagrams]: /content-management/diagrams/
+[Mathematics]: /content-management/mathematics/
+[Syntax highlighting]: /content-management/syntax-highlighting/
+[Shortcodes]: /content-management/shortcodes/
+
+[Multidimensional content model]: /quick-reference/glossary/#sites-matrix
+[Content adapters]: /content-management/content-adapters/
+[Taxonomies]: /content-management/taxonomies/
+[Data]: /content-management/data-sources/
+[Menus]: /content-management/menus/
+[URL management]: /content-management/urls/
+
+[CSS processing]: /functions/css/build/
+[Image processing]: /content-management/image-processing/
+[JavaScript bundling]: /functions/js/build/
+[Sass processing]: /functions/css/sass/
+[Tailwind CSS processing]: /functions/css/tailwindcss/
+
+[Caching]: /functions/partials/includecached/
+[Segmentation]: /configuration/segments/
+[Minification]: /configuration/minify/
diff --git a/documents/markdown/hugo-docs/en_about_introduction.md b/documents/markdown/hugo-docs/en_about_introduction.md
new file mode 100644
index 0000000..3d56b95
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_about_introduction.md
@@ -0,0 +1,34 @@
+---
+title: Introduction
+description: Hugo is a static site generator written in Go, optimized for speed and designed for flexibility.
+categories: []
+keywords: []
+weight: 10
+aliases: [/about/what-is-hugo/,/about/benefits/]
+---
+
+Hugo is a [static site generator] written in [Go], optimized for speed and designed for flexibility. With its advanced templating system and fast asset pipelines, Hugo renders a complete site in seconds, often less.
+
+Due to its flexible framework, multilingual support, and powerful taxonomy system, Hugo is widely used to create:
+
+- Corporate, government, nonprofit, education, news, event, and project sites
+- Documentation sites
+- Image portfolios
+- Landing pages
+- Business, professional, and personal blogs
+- Resumes and CVs
+
+Use Hugo's embedded web server during development to instantly see changes to content, structure, behavior, and presentation. Then deploy the site to your host, or push changes to your Git provider for automated builds and deployment.
+
+And with [Hugo Modules], you can share content, assets, data, translations, themes, templates, and configuration with other projects via public or private Git repositories.
+
+Learn more about Hugo's [features], [privacy protections], and [security model].
+
+[Go]: https://go.dev
+[Hugo Modules]: /hugo-modules/
+[static site generator]: https://en.wikipedia.org/wiki/Static_site_generator
+[features]: /about/features/
+[security model]: /about/security/
+[privacy protections]: /configuration/privacy
+
+{{< youtube 0RKpf3rK57I >}}
diff --git a/documents/markdown/hugo-docs/en_about_license.md b/documents/markdown/hugo-docs/en_about_license.md
new file mode 100644
index 0000000..06a3a69
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_about_license.md
@@ -0,0 +1,75 @@
+---
+title: License
+description: Hugo is released under the Apache 2.0 license.
+categories: []
+keywords: []
+weight: 40
+---
+
+## Apache License
+
+_Version 2.0, January 2004_
+_<http://www.apache.org/licenses/>_
+
+### Terms and Conditions for use, reproduction, and distribution
+
+#### 1. Definitions
+
+“License” shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+“Licensor” shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+“Legal Entity” shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, “control” means **(i)** the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or **(ii)** ownership of fifty percent (50%) or more of the outstanding shares, or **(iii)** beneficial ownership of such entity.
+
+“You” (or “Your”) shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+“Source” form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+“Object” form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+“Work” shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+“Derivative Works” shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+“Contribution” shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, “submitted” means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as “Not a Contribution.”
+
+“Contributor” shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+#### 2. Grant of Copyright License
+
+Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+#### 3. Grant of Patent License
+
+Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+#### 4. Redistribution
+
+You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+* **(a)** You must give any other recipients of the Work or Derivative Works a copy of this License; and
+* **(b)** You must cause any modified files to carry prominent notices stating that You changed the files; and
+* **(c)** You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+* **(d)** If the Work includes a “NOTICE” text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+#### 5. Submission of Contributions
+
+Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+#### 6. Trademarks
+
+This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+#### 7. Disclaimer of Warranty
+
+Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+#### 8. Limitation of Liability
+
+In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+#### 9. Accepting Warranty or Additional Liability
+
+While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
diff --git a/documents/markdown/hugo-docs/en_about_security.md b/documents/markdown/hugo-docs/en_about_security.md
new file mode 100644
index 0000000..509ca6a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_about_security.md
@@ -0,0 +1,58 @@
+---
+title: Security model
+linkTitle: Security
+description: A summary of Hugo's security model.
+categories: []
+keywords: []
+weight: 30
+aliases: [/about/security-model/]
+---
+
+## Runtime security
+
+Hugo generates static websites, meaning the final output runs directly in the browser and interacts with any integrated APIs. However, during development and site building, the `hugo` executable itself is the runtime environment.
+
+Securing a runtime is a complex task. Hugo addresses this through a robust sandboxing approach and a strict security policy with default protections. Key features include:
+
+- Virtual file system: Hugo employs a virtual file system, limiting file access. Only the main project, not external components, can access files or directories outside the project root.
+- Read-Only access: User-defined components have read-only access to the file system, preventing unintended modifications.
+- Controlled external binaries: While Hugo utilizes external binaries for features like Asciidoctor support, these are strictly predefined with specific flags and are disabled by default. The [security policy] details these limitations.
+- No arbitrary commands: To mitigate risks, Hugo intentionally avoids implementing general functions that would allow users to execute arbitrary operating system commands.
+
+This combination of sandboxing and strict defaults effectively minimizes potential security vulnerabilities during the Hugo build process.
+
+[security policy]: /configuration/security/
+
+## Dependency security
+
+Hugo utilizes [Go Modules] to manage its dependencies, compiling as a static binary. Go Modules create a `go.sum` file, a critical security feature. This file acts as a database, storing the expected cryptographic checksums of all dependencies, including those required indirectly (transitive dependencies).
+
+[Hugo Modules], which extend Go Modules' functionality, also produce a `go.sum` file. To ensure dependency integrity, commit this `go.sum` file to your version control. If Hugo detects a checksum mismatch during the build process, it will fail, indicating a possible attempt to [tamper with your project's dependencies].
+
+[Go Modules]: https://go.dev/wiki/Modules#modules
+[Hugo Modules]: /hugo-modules/
+[tamper with your project's dependencies]: https://julienrenaux.fr/2019/12/20/github-actions-security-risk/
+
+## Web application security
+
+Hugo's security philosophy is rooted in established security standards, primarily aligning with the threats defined by [OWASP]. For HTML output, Hugo operates under a clear trust model. This model assumes that template and configuration authors, the developers, are trustworthy. However, the data supplied to these templates is inherently considered untrusted. This distinction is crucial for understanding how Hugo handles potential security risks.
+
+[OWASP]: https://en.wikipedia.org/wiki/OWASP
+
+To prevent unintended escaping of data that developers know is safe, Hugo provides [`safe`] functions, such as [`safeHTML`]. These functions allow developers to explicitly mark data as trusted, bypassing the default escaping mechanisms. This is essential for scenarios where data is generated or sourced from reliable sources. However, an exception exists: enabling [inline shortcodes]. By activating this feature, you are implicitly trusting the logic within the shortcodes and the data contained within your content files.
+
+[`safeHTML`]: /functions/safe/html/
+[inline shortcodes]: /content-management/shortcodes/#inline
+
+It's vital to remember that Hugo is a static site generator. This architectural choice significantly reduces the attack surface by eliminating the complexities and vulnerabilities associated with dynamic user input. Unlike dynamic websites, Hugo generates static HTML files, minimizing the risk of real-time attacks. Regarding content, Hugo's default Markdown renderer is [configured to sanitize] potentially unsafe content. This default behavior ensures that potentially malicious code or scripts are removed or escaped. However, this setting can be reconfigured if you have a high degree of confidence in the safety of your content sources.
+
+[configured to sanitize]: /configuration/markup/#rendererunsafe
+
+In essence, Hugo prioritizes secure output by establishing a clear trust boundary between developers and data. By default, it errs on the side of caution, sanitizing potentially unsafe content and escaping data. Developers have the flexibility to adjust these defaults through [`safe`] functions and [configuration options], but they must do so with a clear understanding of the security implications. Hugo's static site generation model further strengthens its security posture by minimizing dynamic vulnerabilities.
+
+[`safe`]: /functions/safe
+[configuration options]: /configuration/security
+
+## Configuration
+
+See [configure security](/configuration/security/).
diff --git a/documents/markdown/hugo-docs/en_commands__index.md b/documents/markdown/hugo-docs/en_commands__index.md
new file mode 100644
index 0000000..b97b6e2
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands__index.md
@@ -0,0 +1,8 @@
+---
+title: Command line interface
+linkTitle: CLI
+description: Use the command line interface (CLI) to manage your project.
+categories: []
+keywords: []
+weight: 10
+---
diff --git a/documents/markdown/hugo-docs/en_commands_hugo.md b/documents/markdown/hugo-docs/en_commands_hugo.md
new file mode 100644
index 0000000..ad06eca
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo.md
@@ -0,0 +1,83 @@
+---
+title: "hugo"
+slug: hugo
+url: /commands/hugo/
+---
+## hugo
+
+Build your project
+
+### Synopsis
+
+hugo is the main command, used to build your Hugo project.
+
+Hugo is a Fast and Flexible Static Site Generator
+built with love by spf13 and friends in Go.
+
+Complete documentation is available at https://gohugo.io/.
+
+```
+hugo [flags]
+```
+
+### Options
+
+```
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ -D, --buildDrafts include content marked as draft
+ -E, --buildExpired include expired content
+ -F, --buildFuture include content with publishdate in the future
+ --cacheDir string filesystem path to cache directory
+ --cleanDestinationDir remove files from destination not found in static directories
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -c, --contentDir string filesystem path to content directory
+ -d, --destination string filesystem path to write files to
+ --disableKinds strings disable different kind of pages (home, RSS etc.)
+ --enableGitInfo add Git revision, date, author, and CODEOWNERS info to the pages
+ -e, --environment string build environment
+ --forceSyncStatic copy all files when static is changed.
+ --gc enable to run some cleanup tasks (remove unused cache files) after the build
+ -h, --help help for hugo
+ --ignoreCache ignores the cache directory
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ -l, --layoutDir string filesystem path to layout directory
+ --logLevel string log level (debug|info|warn|error)
+ --minify minify any supported output format (HTML, XML etc.)
+ --noBuildLock don't create .hugo_build.lock file
+ --noChmod don't sync permission mode of files
+ --noTimes don't sync modification time of files
+ --panicOnWarning panic on first WARNING log
+ --poll string set this to a poll interval, e.g --poll 700ms, to use a poll based approach to watch for file system changes
+ --printI18nWarnings print missing translations
+ --printMemoryUsage print memory usage to screen at intervals
+ --printPathWarnings print warnings on duplicate target paths etc.
+ --printUnusedTemplates print warnings on unused templates.
+ --quiet build in quiet mode
+ --renderSegments strings named segments to render (configured in the segments config)
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --templateMetrics display metrics about template executions
+ --templateMetricsHints calculate some improvement hints when combined with --templateMetrics
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+ --themesDir string filesystem path to themes directory
+ --trace file write trace to file (not useful in general)
+ -w, --watch watch filesystem for changes and recreate as needed
+```
+
+### SEE ALSO
+
+* [hugo build](/commands/hugo_build/) - Build your project
+* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell
+* [hugo config](/commands/hugo_config/) - Display project configuration
+* [hugo convert](/commands/hugo_convert/) - Convert front matter to another format
+* [hugo deploy](/commands/hugo_deploy/) - Deploy your project to a cloud provider
+* [hugo env](/commands/hugo_env/) - Display version and environment info
+* [hugo gen](/commands/hugo_gen/) - Generate documentation and syntax highlighting styles
+* [hugo import](/commands/hugo_import/) - Import a project from another system
+* [hugo list](/commands/hugo_list/) - List content
+* [hugo mod](/commands/hugo_mod/) - Manage modules
+* [hugo new](/commands/hugo_new/) - Create new content
+* [hugo server](/commands/hugo_server/) - Start the embedded web server
+* [hugo version](/commands/hugo_version/) - Display version
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_build.md b/documents/markdown/hugo-docs/en_commands_hugo_build.md
new file mode 100644
index 0000000..173cb09
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_build.md
@@ -0,0 +1,71 @@
+---
+title: "hugo build"
+slug: hugo_build
+url: /commands/hugo_build/
+---
+## hugo build
+
+Build your project
+
+### Synopsis
+
+build is the main command, used to build your Hugo project.
+
+Hugo is a Fast and Flexible Static Site Generator
+built with love by spf13 and friends in Go.
+
+Complete documentation is available at https://gohugo.io/.
+
+```
+hugo build [flags]
+```
+
+### Options
+
+```
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ -D, --buildDrafts include content marked as draft
+ -E, --buildExpired include expired content
+ -F, --buildFuture include content with publishdate in the future
+ --cacheDir string filesystem path to cache directory
+ --cleanDestinationDir remove files from destination not found in static directories
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -c, --contentDir string filesystem path to content directory
+ -d, --destination string filesystem path to write files to
+ --disableKinds strings disable different kind of pages (home, RSS etc.)
+ --enableGitInfo add Git revision, date, author, and CODEOWNERS info to the pages
+ -e, --environment string build environment
+ --forceSyncStatic copy all files when static is changed.
+ --gc enable to run some cleanup tasks (remove unused cache files) after the build
+ -h, --help help for build
+ --ignoreCache ignores the cache directory
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ -l, --layoutDir string filesystem path to layout directory
+ --logLevel string log level (debug|info|warn|error)
+ --minify minify any supported output format (HTML, XML etc.)
+ --noBuildLock don't create .hugo_build.lock file
+ --noChmod don't sync permission mode of files
+ --noTimes don't sync modification time of files
+ --panicOnWarning panic on first WARNING log
+ --poll string set this to a poll interval, e.g --poll 700ms, to use a poll based approach to watch for file system changes
+ --printI18nWarnings print missing translations
+ --printMemoryUsage print memory usage to screen at intervals
+ --printPathWarnings print warnings on duplicate target paths etc.
+ --printUnusedTemplates print warnings on unused templates.
+ --quiet build in quiet mode
+ --renderSegments strings named segments to render (configured in the segments config)
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --templateMetrics display metrics about template executions
+ --templateMetricsHints calculate some improvement hints when combined with --templateMetrics
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+ --themesDir string filesystem path to themes directory
+ --trace file write trace to file (not useful in general)
+ -w, --watch watch filesystem for changes and recreate as needed
+```
+
+### SEE ALSO
+
+* [hugo](/commands/hugo/) - Build your project
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_completion.md b/documents/markdown/hugo-docs/en_commands_hugo_completion.md
new file mode 100644
index 0000000..34b4114
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_completion.md
@@ -0,0 +1,45 @@
+---
+title: "hugo completion"
+slug: hugo_completion
+url: /commands/hugo_completion/
+---
+## hugo completion
+
+Generate the autocompletion script for the specified shell
+
+### Synopsis
+
+Generate the autocompletion script for hugo for the specified shell.
+See each sub-command's help for details on how to use the generated script.
+
+
+### Options
+
+```
+ -h, --help help for completion
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo](/commands/hugo/) - Build your project
+* [hugo completion bash](/commands/hugo_completion_bash/) - Generate the autocompletion script for bash
+* [hugo completion fish](/commands/hugo_completion_fish/) - Generate the autocompletion script for fish
+* [hugo completion powershell](/commands/hugo_completion_powershell/) - Generate the autocompletion script for powershell
+* [hugo completion zsh](/commands/hugo_completion_zsh/) - Generate the autocompletion script for zsh
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_completion_bash.md b/documents/markdown/hugo-docs/en_commands_hugo_completion_bash.md
new file mode 100644
index 0000000..9f18169
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_completion_bash.md
@@ -0,0 +1,64 @@
+---
+title: "hugo completion bash"
+slug: hugo_completion_bash
+url: /commands/hugo_completion_bash/
+---
+## hugo completion bash
+
+Generate the autocompletion script for bash
+
+### Synopsis
+
+Generate the autocompletion script for the bash shell.
+
+This script depends on the 'bash-completion' package.
+If it is not installed already, you can install it via your OS's package manager.
+
+To load completions in your current shell session:
+
+ source <(hugo completion bash)
+
+To load completions for every new session, execute once:
+
+#### Linux:
+
+ hugo completion bash > /etc/bash_completion.d/hugo
+
+#### macOS:
+
+ hugo completion bash > $(brew --prefix)/etc/bash_completion.d/hugo
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+hugo completion bash
+```
+
+### Options
+
+```
+ -h, --help help for bash
+ --no-descriptions disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_completion_fish.md b/documents/markdown/hugo-docs/en_commands_hugo_completion_fish.md
new file mode 100644
index 0000000..3015d23
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_completion_fish.md
@@ -0,0 +1,55 @@
+---
+title: "hugo completion fish"
+slug: hugo_completion_fish
+url: /commands/hugo_completion_fish/
+---
+## hugo completion fish
+
+Generate the autocompletion script for fish
+
+### Synopsis
+
+Generate the autocompletion script for the fish shell.
+
+To load completions in your current shell session:
+
+ hugo completion fish | source
+
+To load completions for every new session, execute once:
+
+ hugo completion fish > ~/.config/fish/completions/hugo.fish
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+hugo completion fish [flags]
+```
+
+### Options
+
+```
+ -h, --help help for fish
+ --no-descriptions disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_completion_powershell.md b/documents/markdown/hugo-docs/en_commands_hugo_completion_powershell.md
new file mode 100644
index 0000000..780f7fc
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_completion_powershell.md
@@ -0,0 +1,52 @@
+---
+title: "hugo completion powershell"
+slug: hugo_completion_powershell
+url: /commands/hugo_completion_powershell/
+---
+## hugo completion powershell
+
+Generate the autocompletion script for powershell
+
+### Synopsis
+
+Generate the autocompletion script for powershell.
+
+To load completions in your current shell session:
+
+ hugo completion powershell | Out-String | Invoke-Expression
+
+To load completions for every new session, add the output of the above command
+to your powershell profile.
+
+
+```
+hugo completion powershell [flags]
+```
+
+### Options
+
+```
+ -h, --help help for powershell
+ --no-descriptions disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_completion_zsh.md b/documents/markdown/hugo-docs/en_commands_hugo_completion_zsh.md
new file mode 100644
index 0000000..e5743e9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_completion_zsh.md
@@ -0,0 +1,66 @@
+---
+title: "hugo completion zsh"
+slug: hugo_completion_zsh
+url: /commands/hugo_completion_zsh/
+---
+## hugo completion zsh
+
+Generate the autocompletion script for zsh
+
+### Synopsis
+
+Generate the autocompletion script for the zsh shell.
+
+If shell completion is not already enabled in your environment you will need
+to enable it. You can execute the following once:
+
+ echo "autoload -U compinit; compinit" >> ~/.zshrc
+
+To load completions in your current shell session:
+
+ source <(hugo completion zsh)
+
+To load completions for every new session, execute once:
+
+#### Linux:
+
+ hugo completion zsh > "${fpath[1]}/_hugo"
+
+#### macOS:
+
+ hugo completion zsh > $(brew --prefix)/share/zsh/site-functions/_hugo
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+hugo completion zsh [flags]
+```
+
+### Options
+
+```
+ -h, --help help for zsh
+ --no-descriptions disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_config.md b/documents/markdown/hugo-docs/en_commands_hugo_config.md
new file mode 100644
index 0000000..3de89f1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_config.md
@@ -0,0 +1,52 @@
+---
+title: "hugo config"
+slug: hugo_config
+url: /commands/hugo_config/
+---
+## hugo config
+
+Display project configuration
+
+### Synopsis
+
+Display project configuration, both default and custom settings.
+
+```
+hugo config [command] [flags]
+```
+
+### Options
+
+```
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ -c, --contentDir string filesystem path to content directory
+ --format string preferred file format (toml, yaml or json) (default "toml")
+ -h, --help help for config
+ --lang string the language to display config for. Defaults to the first language defined.
+ --printZero include config options with zero values (e.g. false, 0, "") in the output
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo](/commands/hugo/) - Build your project
+* [hugo config mounts](/commands/hugo_config_mounts/) - Print the configured file mounts
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_config_mounts.md b/documents/markdown/hugo-docs/en_commands_hugo_config_mounts.md
new file mode 100644
index 0000000..eb540ac
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_config_mounts.md
@@ -0,0 +1,44 @@
+---
+title: "hugo config mounts"
+slug: hugo_config_mounts
+url: /commands/hugo_config_mounts/
+---
+## hugo config mounts
+
+Print the configured file mounts
+
+```
+hugo config mounts [flags] [args]
+```
+
+### Options
+
+```
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ -c, --contentDir string filesystem path to content directory
+ -h, --help help for mounts
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo config](/commands/hugo_config/) - Display project configuration
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_convert.md b/documents/markdown/hugo-docs/en_commands_hugo_convert.md
new file mode 100644
index 0000000..f293fa4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_convert.md
@@ -0,0 +1,46 @@
+---
+title: "hugo convert"
+slug: hugo_convert
+url: /commands/hugo_convert/
+---
+## hugo convert
+
+Convert front matter to another format
+
+### Synopsis
+
+Convert front matter to another format.
+
+See convert's subcommands toJSON, toTOML and toYAML for more information.
+
+### Options
+
+```
+ -h, --help help for convert
+ -o, --output string filesystem path to write files to
+ --unsafe enable less safe operations, please backup first
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo](/commands/hugo/) - Build your project
+* [hugo convert toJSON](/commands/hugo_convert_tojson/) - Convert front matter to JSON
+* [hugo convert toTOML](/commands/hugo_convert_totoml/) - Convert front matter to TOML
+* [hugo convert toYAML](/commands/hugo_convert_toyaml/) - Convert front matter to YAML
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_convert_toJSON.md b/documents/markdown/hugo-docs/en_commands_hugo_convert_toJSON.md
new file mode 100644
index 0000000..59a6376
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_convert_toJSON.md
@@ -0,0 +1,46 @@
+---
+title: "hugo convert toJSON"
+slug: hugo_convert_toJSON
+url: /commands/hugo_convert_tojson/
+---
+## hugo convert toJSON
+
+Convert front matter to JSON
+
+### Synopsis
+
+toJSON converts all front matter in the content directory
+to use JSON for the front matter.
+
+```
+hugo convert toJSON [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for toJSON
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ -o, --output string filesystem path to write files to
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+ --unsafe enable less safe operations, please backup first
+```
+
+### SEE ALSO
+
+* [hugo convert](/commands/hugo_convert/) - Convert front matter to another format
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_convert_toTOML.md b/documents/markdown/hugo-docs/en_commands_hugo_convert_toTOML.md
new file mode 100644
index 0000000..de48f71
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_convert_toTOML.md
@@ -0,0 +1,46 @@
+---
+title: "hugo convert toTOML"
+slug: hugo_convert_toTOML
+url: /commands/hugo_convert_totoml/
+---
+## hugo convert toTOML
+
+Convert front matter to TOML
+
+### Synopsis
+
+toTOML converts all front matter in the content directory
+to use TOML for the front matter.
+
+```
+hugo convert toTOML [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for toTOML
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ -o, --output string filesystem path to write files to
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+ --unsafe enable less safe operations, please backup first
+```
+
+### SEE ALSO
+
+* [hugo convert](/commands/hugo_convert/) - Convert front matter to another format
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_convert_toYAML.md b/documents/markdown/hugo-docs/en_commands_hugo_convert_toYAML.md
new file mode 100644
index 0000000..ae14e8e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_convert_toYAML.md
@@ -0,0 +1,46 @@
+---
+title: "hugo convert toYAML"
+slug: hugo_convert_toYAML
+url: /commands/hugo_convert_toyaml/
+---
+## hugo convert toYAML
+
+Convert front matter to YAML
+
+### Synopsis
+
+toYAML converts all front matter in the content directory
+to use YAML for the front matter.
+
+```
+hugo convert toYAML [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for toYAML
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ -o, --output string filesystem path to write files to
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+ --unsafe enable less safe operations, please backup first
+```
+
+### SEE ALSO
+
+* [hugo convert](/commands/hugo_convert/) - Convert front matter to another format
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_deploy.md b/documents/markdown/hugo-docs/en_commands_hugo_deploy.md
new file mode 100644
index 0000000..b8c08a3
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_deploy.md
@@ -0,0 +1,54 @@
+---
+title: "hugo deploy"
+slug: hugo_deploy
+url: /commands/hugo_deploy/
+---
+## hugo deploy
+
+Deploy your project to a cloud provider
+
+### Synopsis
+
+Deploy your project to a cloud provider
+
+See https://gohugo.io/hosting-and-deployment/hugo-deploy/ for detailed
+documentation.
+
+
+```
+hugo deploy [flags] [args]
+```
+
+### Options
+
+```
+ --confirm ask for confirmation before making changes to the target
+ --dryRun dry run
+ --force force upload of all files
+ -h, --help help for deploy
+ --invalidateCDN invalidate the CDN cache listed in the deployment target (default true)
+ --maxDeletes int maximum # of files to delete, or -1 to disable (default 256)
+ --target string target deployment from deployments section in config file; defaults to the first one
+ --workers int number of workers to transfer files. defaults to 10 (default 10)
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo](/commands/hugo/) - Build your project
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_env.md b/documents/markdown/hugo-docs/en_commands_hugo_env.md
new file mode 100644
index 0000000..007eb2a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_env.md
@@ -0,0 +1,43 @@
+---
+title: "hugo env"
+slug: hugo_env
+url: /commands/hugo_env/
+---
+## hugo env
+
+Display version and environment info
+
+### Synopsis
+
+Display version and environment info. This is useful in Hugo bug reports
+
+```
+hugo env [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for env
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo](/commands/hugo/) - Build your project
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_gen.md b/documents/markdown/hugo-docs/en_commands_hugo_gen.md
new file mode 100644
index 0000000..605a8fa
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_gen.md
@@ -0,0 +1,42 @@
+---
+title: "hugo gen"
+slug: hugo_gen
+url: /commands/hugo_gen/
+---
+## hugo gen
+
+Generate documentation and syntax highlighting styles
+
+### Synopsis
+
+Generate documentation for your project using Hugo's documentation engine, including syntax highlighting for various programming languages.
+
+### Options
+
+```
+ -h, --help help for gen
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo](/commands/hugo/) - Build your project
+* [hugo gen chromastyles](/commands/hugo_gen_chromastyles/) - Generate CSS stylesheet for the Chroma code highlighter
+* [hugo gen doc](/commands/hugo_gen_doc/) - Generate Markdown documentation for the Hugo CLI
+* [hugo gen man](/commands/hugo_gen_man/) - Generate man pages for the Hugo CLI
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_gen_chromastyles.md b/documents/markdown/hugo-docs/en_commands_hugo_gen_chromastyles.md
new file mode 100644
index 0000000..522d357
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_gen_chromastyles.md
@@ -0,0 +1,51 @@
+---
+title: "hugo gen chromastyles"
+slug: hugo_gen_chromastyles
+url: /commands/hugo_gen_chromastyles/
+---
+## hugo gen chromastyles
+
+Generate CSS stylesheet for the Chroma code highlighter
+
+### Synopsis
+
+Generate CSS stylesheet for the Chroma code highlighter for a given style. This stylesheet is needed if markup.highlight.noClasses is disabled in config.
+
+See https://gohugo.io/quick-reference/syntax-highlighting-styles/ for a preview of the available styles.
+
+```
+hugo gen chromastyles [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for chromastyles
+ --highlightStyle string foreground and background colors for highlighted lines, e.g. --highlightStyle "#fff000 bg:#000fff"
+ --lineNumbersInlineStyle string foreground and background colors for inline line numbers, e.g. --lineNumbersInlineStyle "#fff000 bg:#000fff"
+ --lineNumbersTableStyle string foreground and background colors for table line numbers, e.g. --lineNumbersTableStyle "#fff000 bg:#000fff"
+ --omitClassComments omit CSS class comment prefixes in the generated CSS
+ --omitEmpty omit empty CSS rules (deprecated, no longer needed)
+ --style string highlighter style (default "friendly")
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo gen](/commands/hugo_gen/) - Generate documentation and syntax highlighting styles
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_gen_doc.md b/documents/markdown/hugo-docs/en_commands_hugo_gen_doc.md
new file mode 100644
index 0000000..28f0617
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_gen_doc.md
@@ -0,0 +1,49 @@
+---
+title: "hugo gen doc"
+slug: hugo_gen_doc
+url: /commands/hugo_gen_doc/
+---
+## hugo gen doc
+
+Generate Markdown documentation for the Hugo CLI
+
+### Synopsis
+
+Generate Markdown documentation for the Hugo CLI.
+ This command is, mostly, used to create up-to-date documentation
+ of Hugo's command-line interface for https://gohugo.io/.
+
+ It creates one Markdown file per command with front matter suitable
+ for rendering in Hugo.
+
+```
+hugo gen doc [flags] [args]
+```
+
+### Options
+
+```
+ --dir string the directory to write the doc. (default "/tmp/hugodoc/")
+ -h, --help help for doc
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo gen](/commands/hugo_gen/) - Generate documentation and syntax highlighting styles
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_gen_man.md b/documents/markdown/hugo-docs/en_commands_hugo_gen_man.md
new file mode 100644
index 0000000..7ebc9ff
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_gen_man.md
@@ -0,0 +1,46 @@
+---
+title: "hugo gen man"
+slug: hugo_gen_man
+url: /commands/hugo_gen_man/
+---
+## hugo gen man
+
+Generate man pages for the Hugo CLI
+
+### Synopsis
+
+This command automatically generates up-to-date man pages of Hugo's
+ command-line interface. By default, it creates the man page files
+ in the "man" directory under the current directory.
+
+```
+hugo gen man [flags] [args]
+```
+
+### Options
+
+```
+ --dir string the directory to write the man pages. (default "man/")
+ -h, --help help for man
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo gen](/commands/hugo_gen/) - Generate documentation and syntax highlighting styles
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_import.md b/documents/markdown/hugo-docs/en_commands_hugo_import.md
new file mode 100644
index 0000000..5e38a68
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_import.md
@@ -0,0 +1,42 @@
+---
+title: "hugo import"
+slug: hugo_import
+url: /commands/hugo_import/
+---
+## hugo import
+
+Import a project from another system
+
+### Synopsis
+
+Import a project from another system.
+
+Import requires a subcommand, e.g. `hugo import jekyll jekyll_root_path target_path`.
+
+### Options
+
+```
+ -h, --help help for import
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo](/commands/hugo/) - Build your project
+* [hugo import jekyll](/commands/hugo_import_jekyll/) - hugo import from Jekyll
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_import_jekyll.md b/documents/markdown/hugo-docs/en_commands_hugo_import_jekyll.md
new file mode 100644
index 0000000..d1f16b9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_import_jekyll.md
@@ -0,0 +1,46 @@
+---
+title: "hugo import jekyll"
+slug: hugo_import_jekyll
+url: /commands/hugo_import_jekyll/
+---
+## hugo import jekyll
+
+hugo import from Jekyll
+
+### Synopsis
+
+hugo import from Jekyll.
+
+Import from Jekyll requires two paths, e.g. `hugo import jekyll jekyll_root_path target_path`.
+
+```
+hugo import jekyll [flags] [args]
+```
+
+### Options
+
+```
+ --force allow import into non-empty target directory
+ -h, --help help for jekyll
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo import](/commands/hugo_import/) - Import a project from another system
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_list.md b/documents/markdown/hugo-docs/en_commands_hugo_list.md
new file mode 100644
index 0000000..90b8e6d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_list.md
@@ -0,0 +1,46 @@
+---
+title: "hugo list"
+slug: hugo_list
+url: /commands/hugo_list/
+---
+## hugo list
+
+List content
+
+### Synopsis
+
+List content.
+
+List requires a subcommand, e.g. hugo list drafts
+
+### Options
+
+```
+ -h, --help help for list
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo](/commands/hugo/) - Build your project
+* [hugo list all](/commands/hugo_list_all/) - List all content
+* [hugo list drafts](/commands/hugo_list_drafts/) - List draft content
+* [hugo list expired](/commands/hugo_list_expired/) - List expired content
+* [hugo list future](/commands/hugo_list_future/) - List future content
+* [hugo list published](/commands/hugo_list_published/) - List published content
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_list_all.md b/documents/markdown/hugo-docs/en_commands_hugo_list_all.md
new file mode 100644
index 0000000..6b324ab
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_list_all.md
@@ -0,0 +1,43 @@
+---
+title: "hugo list all"
+slug: hugo_list_all
+url: /commands/hugo_list_all/
+---
+## hugo list all
+
+List all content
+
+### Synopsis
+
+List all content including draft, future, and expired.
+
+```
+hugo list all [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for all
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo list](/commands/hugo_list/) - List content
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_list_drafts.md b/documents/markdown/hugo-docs/en_commands_hugo_list_drafts.md
new file mode 100644
index 0000000..c6a8907
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_list_drafts.md
@@ -0,0 +1,43 @@
+---
+title: "hugo list drafts"
+slug: hugo_list_drafts
+url: /commands/hugo_list_drafts/
+---
+## hugo list drafts
+
+List draft content
+
+### Synopsis
+
+List draft content.
+
+```
+hugo list drafts [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for drafts
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo list](/commands/hugo_list/) - List content
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_list_expired.md b/documents/markdown/hugo-docs/en_commands_hugo_list_expired.md
new file mode 100644
index 0000000..b0618ca
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_list_expired.md
@@ -0,0 +1,43 @@
+---
+title: "hugo list expired"
+slug: hugo_list_expired
+url: /commands/hugo_list_expired/
+---
+## hugo list expired
+
+List expired content
+
+### Synopsis
+
+List content with a past expiration date.
+
+```
+hugo list expired [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for expired
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo list](/commands/hugo_list/) - List content
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_list_future.md b/documents/markdown/hugo-docs/en_commands_hugo_list_future.md
new file mode 100644
index 0000000..4f2fdca
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_list_future.md
@@ -0,0 +1,43 @@
+---
+title: "hugo list future"
+slug: hugo_list_future
+url: /commands/hugo_list_future/
+---
+## hugo list future
+
+List future content
+
+### Synopsis
+
+List content with a future publication date.
+
+```
+hugo list future [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for future
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo list](/commands/hugo_list/) - List content
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_list_published.md b/documents/markdown/hugo-docs/en_commands_hugo_list_published.md
new file mode 100644
index 0000000..a497687
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_list_published.md
@@ -0,0 +1,43 @@
+---
+title: "hugo list published"
+slug: hugo_list_published
+url: /commands/hugo_list_published/
+---
+## hugo list published
+
+List published content
+
+### Synopsis
+
+List content that is not draft, future, or expired.
+
+```
+hugo list published [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for published
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo list](/commands/hugo_list/) - List content
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_mod.md b/documents/markdown/hugo-docs/en_commands_hugo_mod.md
new file mode 100644
index 0000000..5cc9eef
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_mod.md
@@ -0,0 +1,58 @@
+---
+title: "hugo mod"
+slug: hugo_mod
+url: /commands/hugo_mod/
+---
+## hugo mod
+
+Manage modules
+
+### Synopsis
+
+Various helpers to help manage the modules in your project's dependency graph.
+Most operations here requires a Go version installed on your system (>= Go 1.12) and the relevant VCS client (typically Git).
+This is not needed if you only operate on modules inside /themes or if you have vendored them via "hugo mod vendor".
+
+
+Note that Hugo will always start out by resolving the components defined in the project
+configuration, provided by a _vendor directory (if no --ignoreVendorPaths flag provided),
+Go Modules, or a folder inside the themes directory, in that order.
+
+See https://gohugo.io/hugo-modules/ for more information.
+
+
+
+### Options
+
+```
+ -h, --help help for mod
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo](/commands/hugo/) - Build your project
+* [hugo mod clean](/commands/hugo_mod_clean/) - Delete the Hugo Module cache for the current project
+* [hugo mod get](/commands/hugo_mod_get/) - Resolves dependencies in your current Hugo project
+* [hugo mod graph](/commands/hugo_mod_graph/) - Print a module dependency graph
+* [hugo mod init](/commands/hugo_mod_init/) - Initialize this project as a Hugo Module
+* [hugo mod npm](/commands/hugo_mod_npm/) - Various npm helpers
+* [hugo mod tidy](/commands/hugo_mod_tidy/) - Remove unused entries in go.mod and go.sum
+* [hugo mod vendor](/commands/hugo_mod_vendor/) - Vendor all module dependencies into the _vendor directory
+* [hugo mod verify](/commands/hugo_mod_verify/) - Verify dependencies
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_mod_clean.md b/documents/markdown/hugo-docs/en_commands_hugo_mod_clean.md
new file mode 100644
index 0000000..9abb1cb
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_mod_clean.md
@@ -0,0 +1,50 @@
+---
+title: "hugo mod clean"
+slug: hugo_mod_clean
+url: /commands/hugo_mod_clean/
+---
+## hugo mod clean
+
+Delete the Hugo Module cache for the current project
+
+### Synopsis
+
+Delete the Hugo Module cache for the current project.
+
+```
+hugo mod clean [flags] [args]
+```
+
+### Options
+
+```
+ --all clean entire module cache
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ -c, --contentDir string filesystem path to content directory
+ -h, --help help for clean
+ --pattern string pattern matching module paths to clean (all if not set), e.g. "**hugo*"
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo mod](/commands/hugo_mod/) - Manage modules
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_mod_get.md b/documents/markdown/hugo-docs/en_commands_hugo_mod_get.md
new file mode 100644
index 0000000..a7eebd7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_mod_get.md
@@ -0,0 +1,74 @@
+---
+title: "hugo mod get"
+slug: hugo_mod_get
+url: /commands/hugo_mod_get/
+---
+## hugo mod get
+
+Resolves dependencies in your current Hugo project
+
+### Synopsis
+
+
+Resolves dependencies in your current Hugo project.
+
+Some examples:
+
+Install the latest version possible for a given module:
+
+ hugo mod get github.com/gohugoio/testshortcodes
+
+Install a specific version:
+
+ hugo mod get github.com/gohugoio/testshortcodes@v0.3.0
+
+Install the latest versions of all direct module dependencies:
+
+ hugo mod get
+ hugo mod get ./... (recursive)
+
+Install the latest versions of all module dependencies (direct and indirect):
+
+ hugo mod get -u
+ hugo mod get -u ./... (recursive)
+
+Run "go help get" for more information. All flags available for "go get" is also relevant here.
+
+Note that Hugo will always start out by resolving the components defined in the project
+configuration, provided by a _vendor directory (if no --ignoreVendorPaths flag provided),
+Go Modules, or a folder inside the themes directory, in that order.
+
+See https://gohugo.io/hugo-modules/ for more information.
+
+
+
+```
+hugo mod get [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for get
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo mod](/commands/hugo_mod/) - Manage modules
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_mod_graph.md b/documents/markdown/hugo-docs/en_commands_hugo_mod_graph.md
new file mode 100644
index 0000000..2e84091
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_mod_graph.md
@@ -0,0 +1,51 @@
+---
+title: "hugo mod graph"
+slug: hugo_mod_graph
+url: /commands/hugo_mod_graph/
+---
+## hugo mod graph
+
+Print a module dependency graph
+
+### Synopsis
+
+Print a module dependency graph with information about module status (disabled, vendored).
+Note that for vendored modules, that is the version listed and not the one from go.mod.
+
+
+```
+hugo mod graph [flags] [args]
+```
+
+### Options
+
+```
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ --clean delete module cache for dependencies that fail verification
+ -c, --contentDir string filesystem path to content directory
+ -h, --help help for graph
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo mod](/commands/hugo_mod/) - Manage modules
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_mod_init.md b/documents/markdown/hugo-docs/en_commands_hugo_mod_init.md
new file mode 100644
index 0000000..05d785c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_mod_init.md
@@ -0,0 +1,55 @@
+---
+title: "hugo mod init"
+slug: hugo_mod_init
+url: /commands/hugo_mod_init/
+---
+## hugo mod init
+
+Initialize this project as a Hugo Module
+
+### Synopsis
+
+Initialize this project as a Hugo Module.
+ It will try to guess the module path, but you may help by passing it as an argument, e.g:
+
+ hugo mod init github.com/gohugoio/testshortcodes
+
+ Note that Hugo Modules supports multi-module projects, so you can initialize a Hugo Module
+ inside a subfolder on GitHub, as one example.
+
+
+```
+hugo mod init [flags] [args]
+```
+
+### Options
+
+```
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ -c, --contentDir string filesystem path to content directory
+ -h, --help help for init
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo mod](/commands/hugo_mod/) - Manage modules
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_mod_npm.md b/documents/markdown/hugo-docs/en_commands_hugo_mod_npm.md
new file mode 100644
index 0000000..eafda17
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_mod_npm.md
@@ -0,0 +1,44 @@
+---
+title: "hugo mod npm"
+slug: hugo_mod_npm
+url: /commands/hugo_mod_npm/
+---
+## hugo mod npm
+
+Various npm helpers
+
+### Synopsis
+
+Various npm (Node package manager) helpers.
+
+```
+hugo mod npm [command] [flags]
+```
+
+### Options
+
+```
+ -h, --help help for npm
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo mod](/commands/hugo_mod/) - Manage modules
+* [hugo mod npm pack](/commands/hugo_mod_npm_pack/) - Experimental: Prepares and writes a composite package.json file for your project
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_mod_npm_pack.md b/documents/markdown/hugo-docs/en_commands_hugo_mod_npm_pack.md
new file mode 100644
index 0000000..8637d74
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_mod_npm_pack.md
@@ -0,0 +1,58 @@
+---
+title: "hugo mod npm pack"
+slug: hugo_mod_npm_pack
+url: /commands/hugo_mod_npm_pack/
+---
+## hugo mod npm pack
+
+Experimental: Prepares and writes a composite package.json file for your project
+
+### Synopsis
+
+Prepares and writes a composite package.json file for your project.
+
+On first run it creates a "package.hugo.json" in the project root if not already there. This file will be used as a template file
+with the base dependency set.
+
+This set will be merged with all "package.hugo.json" files found in the dependency tree, picking the version closest to the project.
+
+This command is marked as 'Experimental'. We think it's a great idea, so it's not likely to be
+removed from Hugo, but we need to test this out in "real life" to get a feel of it,
+so this may/will change in future versions of Hugo.
+
+
+```
+hugo mod npm pack [flags] [args]
+```
+
+### Options
+
+```
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ -c, --contentDir string filesystem path to content directory
+ -h, --help help for pack
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo mod npm](/commands/hugo_mod_npm/) - Various npm helpers
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_mod_tidy.md b/documents/markdown/hugo-docs/en_commands_hugo_mod_tidy.md
new file mode 100644
index 0000000..1114772
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_mod_tidy.md
@@ -0,0 +1,44 @@
+---
+title: "hugo mod tidy"
+slug: hugo_mod_tidy
+url: /commands/hugo_mod_tidy/
+---
+## hugo mod tidy
+
+Remove unused entries in go.mod and go.sum
+
+```
+hugo mod tidy [flags] [args]
+```
+
+### Options
+
+```
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ -c, --contentDir string filesystem path to content directory
+ -h, --help help for tidy
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo mod](/commands/hugo_mod/) - Manage modules
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_mod_vendor.md b/documents/markdown/hugo-docs/en_commands_hugo_mod_vendor.md
new file mode 100644
index 0000000..4e828fe
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_mod_vendor.md
@@ -0,0 +1,50 @@
+---
+title: "hugo mod vendor"
+slug: hugo_mod_vendor
+url: /commands/hugo_mod_vendor/
+---
+## hugo mod vendor
+
+Vendor all module dependencies into the _vendor directory
+
+### Synopsis
+
+Vendor all module dependencies into the _vendor directory.
+ If a module is vendored, that is where Hugo will look for it's dependencies.
+
+
+```
+hugo mod vendor [flags] [args]
+```
+
+### Options
+
+```
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ -c, --contentDir string filesystem path to content directory
+ -h, --help help for vendor
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo mod](/commands/hugo_mod/) - Manage modules
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_mod_verify.md b/documents/markdown/hugo-docs/en_commands_hugo_mod_verify.md
new file mode 100644
index 0000000..6c15a88
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_mod_verify.md
@@ -0,0 +1,49 @@
+---
+title: "hugo mod verify"
+slug: hugo_mod_verify
+url: /commands/hugo_mod_verify/
+---
+## hugo mod verify
+
+Verify dependencies
+
+### Synopsis
+
+Verify checks that the dependencies of the current module, which are stored in a local downloaded source cache, have not been modified since being downloaded.
+
+```
+hugo mod verify [flags] [args]
+```
+
+### Options
+
+```
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ --clean delete module cache for dependencies that fail verification
+ -c, --contentDir string filesystem path to content directory
+ -h, --help help for verify
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo mod](/commands/hugo_mod/) - Manage modules
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_new.md b/documents/markdown/hugo-docs/en_commands_hugo_new.md
new file mode 100644
index 0000000..a6587e4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_new.md
@@ -0,0 +1,49 @@
+---
+title: "hugo new"
+slug: hugo_new
+url: /commands/hugo_new/
+---
+## hugo new
+
+Create new content
+
+### Synopsis
+
+Create a new content file and automatically set the date and title.
+It will guess which kind of file to create based on the path provided.
+
+You can also specify the kind with `-k KIND`.
+
+If archetypes are provided in your theme or project, they will be used.
+
+Ensure you run this within the root directory of your project.
+
+### Options
+
+```
+ -h, --help help for new
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo](/commands/hugo/) - Build your project
+* [hugo new content](/commands/hugo_new_content/) - Create new content
+* [hugo new project](/commands/hugo_new_project/) - Create a new project
+* [hugo new theme](/commands/hugo_new_theme/) - Create a new theme
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_new_content.md b/documents/markdown/hugo-docs/en_commands_hugo_new_content.md
new file mode 100644
index 0000000..0a5b543
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_new_content.md
@@ -0,0 +1,58 @@
+---
+title: "hugo new content"
+slug: hugo_new_content
+url: /commands/hugo_new_content/
+---
+## hugo new content
+
+Create new content
+
+### Synopsis
+
+Create a new content file and automatically set the date and title.
+It will guess which kind of file to create based on the path provided.
+
+You can also specify the kind with `-k KIND`.
+
+If archetypes are provided in your theme or project, they will be used.
+
+Ensure you run this within the root directory of your project.
+
+```
+hugo new content [path] [flags]
+```
+
+### Options
+
+```
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --cacheDir string filesystem path to cache directory
+ -c, --contentDir string filesystem path to content directory
+ --editor string edit new content with this editor, if provided
+ -f, --force overwrite file if it already exists
+ -h, --help help for content
+ -k, --kind string content type to create
+ --renderSegments strings named segments to render (configured in the segments config)
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo new](/commands/hugo_new/) - Create new content
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_new_project.md b/documents/markdown/hugo-docs/en_commands_hugo_new_project.md
new file mode 100644
index 0000000..652eefe
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_new_project.md
@@ -0,0 +1,45 @@
+---
+title: "hugo new project"
+slug: hugo_new_project
+url: /commands/hugo_new_project/
+---
+## hugo new project
+
+Create a new project
+
+### Synopsis
+
+Create a new project at the specified path.
+
+```
+hugo new project [path] [flags]
+```
+
+### Options
+
+```
+ -f, --force init inside non-empty directory
+ --format string preferred file format (toml, yaml or json) (default "toml")
+ -h, --help help for project
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo new](/commands/hugo_new/) - Create new content
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_new_theme.md b/documents/markdown/hugo-docs/en_commands_hugo_new_theme.md
new file mode 100644
index 0000000..7a7e040
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_new_theme.md
@@ -0,0 +1,45 @@
+---
+title: "hugo new theme"
+slug: hugo_new_theme
+url: /commands/hugo_new_theme/
+---
+## hugo new theme
+
+Create a new theme
+
+### Synopsis
+
+Create a new theme with the specified name in the ./themes directory.
+This generates a functional theme including template examples and sample content.
+
+```
+hugo new theme [name] [flags]
+```
+
+### Options
+
+```
+ --format string preferred file format (toml, yaml or json) (default "toml")
+ -h, --help help for theme
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo new](/commands/hugo_new/) - Create new content
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_server.md b/documents/markdown/hugo-docs/en_commands_hugo_server.md
new file mode 100644
index 0000000..4345fbd
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_server.md
@@ -0,0 +1,97 @@
+---
+title: "hugo server"
+slug: hugo_server
+url: /commands/hugo_server/
+---
+## hugo server
+
+Start the embedded web server
+
+### Synopsis
+
+Hugo provides its own webserver which builds and serves the project.
+While hugo server is high performance, it is a webserver with limited options.
+
+The `hugo server` command will by default write and serve files from disk, but
+you can render to memory by using the `--renderToMemory` flag. This can be
+faster in some cases, but it will consume more memory.
+
+By default hugo will also watch your files for any changes you make and
+automatically rebuild the project. It will then live reload any open browser pages
+and push the latest content to them. As most Hugo projects are built in a fraction
+of a second, you will be able to save and see your changes nearly instantly.
+
+```
+hugo server [command] [flags]
+```
+
+### Options
+
+```
+ --appendPort append port to baseURL (default true)
+ -b, --baseURL string hostname (and path) to the root, e.g. https://spf13.com/
+ --bind string interface to which the server will bind (default "127.0.0.1")
+ -D, --buildDrafts include content marked as draft
+ -E, --buildExpired include expired content
+ -F, --buildFuture include content with publishdate in the future
+ --cacheDir string filesystem path to cache directory
+ --cleanDestinationDir remove files from destination not found in static directories
+ -c, --contentDir string filesystem path to content directory
+ --disableBrowserError do not show build errors in the browser
+ --disableFastRender enables full re-renders on changes
+ --disableKinds strings disable different kind of pages (home, RSS etc.)
+ --disableLiveReload watch without enabling live browser reload on rebuild
+ --enableGitInfo add Git revision, date, author, and CODEOWNERS info to the pages
+ --forceSyncStatic copy all files when static is changed.
+ --gc enable to run some cleanup tasks (remove unused cache files) after the build
+ -h, --help help for server
+ --ignoreCache ignores the cache directory
+ -l, --layoutDir string filesystem path to layout directory
+ --liveReloadPort int port for live reloading (i.e. 443 in HTTPS proxy situations) (default -1)
+ --minify minify any supported output format (HTML, XML etc.)
+ -N, --navigateToChanged navigate to changed content file on live browser reload
+ --noChmod don't sync permission mode of files
+ --noHTTPCache prevent HTTP caching
+ --noTimes don't sync modification time of files
+ -O, --openBrowser open the project in a browser after server startup
+ --panicOnWarning panic on first WARNING log
+ --poll string set this to a poll interval, e.g --poll 700ms, to use a poll based approach to watch for file system changes
+ -p, --port int port on which the server will listen (default 1313)
+ --pprof enable the pprof server (port 8080)
+ --printI18nWarnings print missing translations
+ --printMemoryUsage print memory usage to screen at intervals
+ --printPathWarnings print warnings on duplicate target paths etc.
+ --printUnusedTemplates print warnings on unused templates.
+ --renderSegments strings named segments to render (configured in the segments config)
+ --renderStaticToDisk serve static files from disk and dynamic files from memory
+ --templateMetrics display metrics about template executions
+ --templateMetricsHints calculate some improvement hints when combined with --templateMetrics
+ -t, --theme strings themes to use (located in /themes/THEMENAME/)
+ --tlsAuto generate and use locally-trusted certificates.
+ --tlsCertFile string path to TLS certificate file
+ --tlsKeyFile string path to TLS key file
+ --trace file write trace to file (not useful in general)
+ -w, --watch watch filesystem for changes and recreate as needed (default true)
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo](/commands/hugo/) - Build your project
+* [hugo server trust](/commands/hugo_server_trust/) - Install the local CA in the system trust store
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_server_trust.md b/documents/markdown/hugo-docs/en_commands_hugo_server_trust.md
new file mode 100644
index 0000000..8649838
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_server_trust.md
@@ -0,0 +1,40 @@
+---
+title: "hugo server trust"
+slug: hugo_server_trust
+url: /commands/hugo_server_trust/
+---
+## hugo server trust
+
+Install the local CA in the system trust store
+
+```
+hugo server trust [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for trust
+ --uninstall Uninstall the local CA (but do not delete it).
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo server](/commands/hugo_server/) - Start the embedded web server
diff --git a/documents/markdown/hugo-docs/en_commands_hugo_version.md b/documents/markdown/hugo-docs/en_commands_hugo_version.md
new file mode 100644
index 0000000..e71abdc
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_commands_hugo_version.md
@@ -0,0 +1,43 @@
+---
+title: "hugo version"
+slug: hugo_version
+url: /commands/hugo_version/
+---
+## hugo version
+
+Display version
+
+### Synopsis
+
+Display version and environment info. This is useful in Hugo bug reports.
+
+```
+hugo version [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for version
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo](/commands/hugo/) - Build your project
diff --git a/documents/markdown/hugo-docs/en_configuration__index.md b/documents/markdown/hugo-docs/en_configuration__index.md
new file mode 100644
index 0000000..7cb08cc
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration__index.md
@@ -0,0 +1,7 @@
+---
+title: Configuration
+description: Configure your site.
+categories: []
+keywords: []
+weight: 10
+---
diff --git a/documents/markdown/hugo-docs/en_configuration_all.md b/documents/markdown/hugo-docs/en_configuration_all.md
new file mode 100644
index 0000000..5cd79a4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_all.md
@@ -0,0 +1,429 @@
+---
+title: All settings
+description: The complete list of Hugo configuration settings.
+categories: []
+keywords: []
+weight: 20
+aliases: [/getting-started/configuration/]
+---
+
+## Settings
+
+archetypeDir
+: (`string`) The designated directory for [archetypes](g). Default is `archetypes`. {{% module-mounts-note %}}
+
+assetDir
+: (`string`) The designated directory for [global resources](g). Default is `assets`. {{% module-mounts-note %}}
+
+baseURL
+: (`string`) The absolute URL of your published site including the protocol, host, path, and a trailing slash.
+
+build
+: See [configure build][].
+
+buildDrafts
+: (`bool`) Whether to include draft content when building a site. Default is `false`.
+
+buildExpired
+: (`bool`) Whether to include expired content when building a site. Default is `false`.
+
+buildFuture
+: (`bool`) Whether to include future content when building a site. Default is `false`.
+
+cacheDir
+: (`string`) The designated cache directory. See [details](#cache-directory).
+
+caches
+: See [configure file caches][].
+
+canonifyURLs
+: (`bool`) See [details](/content-management/urls/#canonical-urls) before enabling this feature. Default is `false`.
+
+capitalizeListTitles
+: (`bool`) Whether to capitalize automatic list titles. Applicable to section, taxonomy, and term pages. Use the [`titleCaseStyle`][] setting to configure capitalization rules. Default is `true`.
+
+cascade
+: See [configure cascade][].
+
+cleanDestinationDir
+: (`bool`) Whether to remove files from the [`publishDir`][] that do not exist in the [`staticDir`][] when building the site. This setting will not take effect if the `staticDir` does not exist. Note that `.gitignore` and `.gitattributes` files, along with directories named `.git`, are always preserved in the `publishDir`. Default is `false`.
+
+contentDir
+: (`string`) The designated directory for content files. Default is `content`. {{% module-mounts-note %}}
+
+copyright
+: (`string`) The copyright notice for a site, typically displayed in the footer.
+
+dataDir
+: (`string`) The designated directory for data files. Default is `data`. {{% module-mounts-note %}}
+
+defaultContentLanguage
+: (`string`) The projects's [default language](g), conforming to the syntax described in [RFC 5646][].
+
+defaultContentLanguageInSubdir
+: (`bool`) Whether to publish the default content language to a subdirectory matching the [`defaultContentLanguage`][]. Default is `false`.
+
+defaultContentRole
+: {{< new-in 0.153.0 />}}
+: (`string`) The project's [default role](g).
+
+defaultContentRoleInSubdir
+: {{< new-in 0.153.0 />}}
+: (`bool`) Whether to publish the default content [role](g) to a subdirectory matching the [`defaultContentRole`][]. Default is `false`.
+
+defaultContentVersion
+: {{< new-in 0.153.0 />}}
+: (`string`) The project's [default version](g).
+
+defaultContentVersionInSubdir
+: {{< new-in 0.153.0 />}}
+: (`bool`) Whether to publish the default content version to a subdirectory matching the [`defaultContentVersion`][]. Default is `false`.
+
+defaultOutputFormat
+: (`string`) The default output format for the site. If unspecified, the first available format in the defined order (by weight, then alphabetically) will be used.
+
+deployment
+: See [configure deployment][].
+
+disableAliases
+: (`bool`) Whether to disable the generation of HTML redirect files for each path defined in the [`aliases`][aliases_front_matter] front matter field. When `true`, Hugo will not create physical files for [client-side redirection][], but the alias data remains available via the [`Aliases`][aliases_page_method] method on a `Page` object. Default is `false`.
+
+disableDefaultLanguageRedirect
+: {{< new-in 0.140.0 />}}
+: (`bool`) Whether to disable generation of the alias redirect for the default content language. When [`defaultContentLanguageInSubdir`][] is `true`, this setting prevents the root directory from redirecting to the language subdirectory. Conversely, when `defaultContentLanguageInSubdir` is `false`, this setting prevents the language subdirectory from redirecting to the root directory. This is superseded by the more general [`disableDefaultSiteRedirect`][] setting. Default is `false`.
+
+disableDefaultSiteRedirect
+: {{< new-in 0.154.5 />}}
+: (bool) Whether to disable generation of the alias redirect to the [default site](g). When [`defaultContentLanguageInSubdir`][], [`defaultContentRoleInSubdir`][], or [`defaultContentVersionInSubdir`][] is `true`, this prevents the root directory from redirecting to the default site's subdirectory. Conversely, when these are `false`, it prevents the subdirectories from redirecting back to the root. Default is `false`.
+
+disableHugoGeneratorInject
+: (`bool`) Whether to disable injection of a `<meta name="generator">` tag into the home page. Default is `false`.
+
+disableKinds
+: (`[]string`) A slice of page [kinds](g) to disable during the build process, any of `404`, `home`, `page`, `robotstxt`, `rss`, `section`, `sitemap`, `taxonomy`, or `term`.
+
+disableLanguages
+: (`[]string`) A slice of language keys representing the languages to disable during the build process. Although this is functional, consider using the [`disabled`][] key under each language instead.
+
+disableLiveReload
+: (`bool`) Whether to disable automatic live reloading of the browser window. Default is `false`.
+
+disablePathToLower
+: (`bool`) Whether to disable transformation of page URLs to lower case. Default is `false`.
+
+enableEmoji
+: (`bool`) Whether to allow emoji in Markdown. Default is `false`.
+
+enableGitInfo
+: (`bool`) Whether to retrieve commit metadata from the Git history of your local project and any [modules](g). This enables the [`GitInfo`][] method on a `Page` object. With the default front matter configuration, the [`Lastmod`][] method on a `Page` object returns the Git author date of the last commit for that file. Default is `false`.
+
+enableMissingTranslationPlaceholders
+: (`bool`) Whether to show a placeholder instead of the default value or an empty string if a translation is missing. Default is `false`.
+
+enableRobotsTXT
+: (`bool`) Whether to enable generation of a `robots.txt` file. Default is `false`.
+
+environment
+: (`string`) The build environment. Default is `production` when running `hugo build` and `development` when running `hugo server`.
+
+frontmatter
+: See [configure front matter][].
+
+hasCJKLanguage
+: (`bool`) Whether to automatically detect [CJK](g) languages in content. Affects the values returned by the [`WordCount`][] and [`FuzzyWordCount`][] methods. Default is `false`.
+
+HTTPCache
+: See [configure HTTP cache][].
+
+i18nDir
+: (`string`) The designated directory for translation tables. Default is `i18n`. {{% module-mounts-note %}}
+
+ignoreCache
+: (`bool`) Whether to ignore the cache directory. Default is `false`.
+
+ignoreFiles
+: (`[]string`) A slice of [regular expressions](g) used to exclude specific files from a build. These expressions are matched against the absolute file path and apply to files within the `content`, `data`, and `i18n` directories. For more advanced file exclusion options, see the section on [module mounts][].
+
+ignoreLogs
+: (`[]string`) A slice of message identifiers corresponding to warnings and errors you wish to suppress. See [`erroridf`][] and [`warnidf`][].
+
+ignoreVendorPaths
+: (`string`) A [glob pattern](g) matching the module paths to exclude from the `_vendor` directory.
+
+imaging
+: See [configure imaging][].
+
+locale
+: (`string`) The site's language tag, conforming to the syntax described in [RFC 5646][]. This value does not affect translations or localization. Hugo uses this value to populate:
+
+ - The `language` element in the [embedded RSS template][]
+ - The `lang` attribute of the `html` element in the [embedded alias template][]
+ - The `og:locale` `meta` element in the [embedded Open Graph template][]
+
+ When present in the root of the configuration, this value is ignored if one or more language keys exists. Please specify this value independently for each language key.
+
+languages
+: See [configure languages][].
+
+layoutDir
+: (`string`) The designated directory for templates. Default is `layouts`. {{% module-mounts-note %}}
+
+mainSections
+: (`string` or `[]string`) The main sections of a site. If set, the [`MainSections`][] method on the `Site` object returns the given sections, otherwise it returns the section with the most pages.
+
+markup
+: See [configure markup][].
+
+mediaTypes
+: See [configure media types][].
+
+menus
+: See [configure menus][].
+
+minify
+: See [configure minify][].
+
+module
+: See [configure modules][].
+
+newContentEditor
+: (`string`) The editor to use when creating new content.
+
+noBuildLock
+: (`bool`) Whether to disable creation of the `.hugo_build.lock` file. Default is `false`.
+
+noChmod
+: (`bool`) Whether to disable synchronization of file permission modes. Default is `false`.
+
+noTimes
+: (`bool`) Whether to disable synchronization of file modification times. Default is `false`.
+
+outputFormats
+: See [configure output formats][].
+
+outputs
+: See [configure outputs][].
+
+page
+: See [configure page][].
+
+pagination
+: See [configure pagination][].
+
+panicOnWarning
+: (`bool`) Whether to panic on the first WARNING. Default is `false`.
+
+params
+: See [configure params][].
+
+permalinks
+: See [configure permalinks][].
+
+pluralizeListTitles
+: (`bool`) Whether to pluralize automatic list titles. Applicable to section pages. Default is `true`.
+
+printI18nWarnings
+: (`bool`) Whether to log WARNINGs for each missing translation. Default is `false`.
+
+printPathWarnings
+: (`bool`) Whether to log WARNINGs when Hugo publishes two or more files to the same path. Default is `false`.
+
+printUnusedTemplates
+: (`bool`) Whether to log WARNINGs for each unused template. Default is `false`.
+
+privacy
+: See [configure privacy][].
+
+publishDir
+: (`string`) The designated directory for publishing the site. Default is `public`.
+
+refLinksErrorLevel
+: (`string`) The logging error level to use when the `ref` and `relref` functions, methods, and shortcodes are unable to resolve a reference to a page. Either `ERROR` or `WARNING`. Any `ERROR` will fail the build. Default is `ERROR`.
+
+refLinksNotFoundURL
+: (`string`) The URL to return when the `ref` and `relref` functions, methods, and shortcodes are unable to resolve a reference to a page.
+
+related
+: See [configure related content][].
+
+relativeURLs
+: (`bool`) See [details](/content-management/urls/#relative-urls) before enabling this feature. Default is `false`.
+
+removePathAccents
+: (`bool`) Whether to remove [non-spacing marks][] from [composite characters][] in content paths. Default is `false`.
+
+renderSegments
+: (`[]string`) A slice of [segments](g) to render. If omitted, all segments are rendered. This option is typically set via a command-line flag, such as `hugo build --renderSegments segment1,segment2`. The provided segment names must correspond to those defined in the [`segments`][] configuration.
+
+resourceDir
+: (`string`) The designated directory for caching output from [asset pipelines](g). Default is `resources`.
+
+roles
+: See [configure roles][].
+
+security
+: See [configure security][].
+
+sectionPagesMenu
+: (`string`) When set, each top-level section will be added to the menu identified by the provided value. See [details](/content-management/menus/#define-automatically).
+
+segments
+: See [configure segments][].
+
+server
+: See [configure server][].
+
+services
+: See [configure services][].
+
+sitemap
+: See [configure sitemap][].
+
+staticDir
+: (`string`) The designated directory for static files. Default is `static`. {{% module-mounts-note %}}
+
+summaryLength
+: (`int`) Applicable to [automatic summaries][], the minimum number of words returned by the [`Summary`][] method on a `Page` object. The `Summary` method will return content truncated at the paragraph boundary closest to the specified `summaryLength`, but at least this minimum number of words. Default is `70`.
+
+taxonomies
+: See [configure taxonomies][].
+
+templateMetrics
+: (`bool`) Whether to print template execution metrics to the console. Default is `false`. See [details](/troubleshooting/performance/#template-metrics).
+
+templateMetricsHints
+: (`bool`) Whether to print template execution improvement hints to the console. Applicable when `templateMetrics` is `true`. Default is `false`. See [details](/troubleshooting/performance/#template-metrics).
+
+theme
+: (`string` or `[]string`) The [theme](g) to use. Multiple themes can be listed, with precedence given from left to right. See [details](/hugo-modules/theme-components/).
+
+themesDir
+: (`string`) The designated directory for themes. Default is `themes`.
+
+timeout
+: (`string`) The timeout for generating page content, either as a [duration][] or in seconds. This timeout is used to prevent infinite recursion during content generation. You may need to increase this value if your pages take a long time to generate, for example, due to extensive image processing or reliance on remote content. Default is `60s`.
+
+timeZone
+: (`string`) The time zone used to parse dates without time zone offsets, including front matter date fields and values passed to the [`time.AsTime`][] and [`time.Format`][] template functions. The list of valid values may be system dependent, but should include `UTC`, `Local`, and any location in the [IANA Time Zone Database][]. For example, `America/Los_Angeles` and `Europe/Oslo` are valid time zones.
+
+title
+: (`string`) The site title.
+
+titleCaseStyle
+: (`string`) The capitalization rules to follow when Hugo automatically generates a section title, or when using the [`strings.Title`][] function. One of `ap`, `chicago`, `go`, `firstupper`, or `none`. Default is `ap`. See [details](#title-case-style).
+
+uglyurls
+: See [configure ugly URLs][].
+
+versions
+: See [configure versions][].
+
+## Cache directory
+
+Hugo's file cache directory is configurable via the [`cacheDir`][] configuration option or the `HUGO_CACHEDIR` environment variable. If neither is set, Hugo will use, in order of preference:
+
+1. If running on Netlify: `/opt/build/cache/hugo_cache/`. This means that if you run your builds on Netlify, all caches configured with `:cacheDir` will be saved and restored on the next build. For other [CI/CD](g) platforms, please read their documentation. For a CircleCI example, see [this configuration][].
+1. In a `hugo_cache` directory below the OS user cache directory as defined by Go's [os.UserCacheDir][] function. On Unix systems, per the [XDG base directory specification][], this is `$XDG_CACHE_HOME` if non-empty, else `$HOME/.cache`. On MacOS, this is `$HOME/Library/Caches`. On Windows, this is`%LocalAppData%`. On Plan 9, this is `$home/lib/cache`.
+1. In a `hugo_cache_$USER` directory below the OS temp dir.
+
+To determine the current `cacheDir`:
+
+```sh
+hugo config | grep cachedir
+```
+
+## Title case style
+
+Hugo's [`titleCaseStyle`][] setting governs capitalization for automatically generated section titles and the [`strings.Title`][] function. By default, it follows the capitalization rules published in the Associated Press Stylebook. Change this setting to use other capitalization rules.
+
+ap
+: Use the capitalization rules published in the [Associated Press Stylebook][]. This is the default.
+
+chicago
+: Use the capitalization rules published in the [Chicago Manual of Style][].
+
+go
+: Capitalize the first letter of every word.
+
+firstupper
+: Capitalize the first letter of the first word.
+
+none
+: Disable transformation of automatic section titles, and disable the transformation performed by the `strings.Title` function. This is useful if you would prefer to manually capitalize section titles as needed, and to bypass opinionated theme usage of the `strings.Title` function.
+
+## Localized settings
+
+Some configuration settings, such as menus and custom parameters, can be defined separately for each language. See [configure languages][].
+
+[Associated Press Stylebook]: https://www.apstylebook.com/
+[Chicago Manual of Style]: https://www.chicagomanualofstyle.org/home.html
+[IANA Time Zone Database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
+[XDG base directory specification]: https://specifications.freedesktop.org/basedir-spec/latest/
+[`FuzzyWordCount`]: /methods/page/fuzzywordcount/
+[`GitInfo`]: /methods/page/gitinfo/
+[`Lastmod`]: /methods/page/lastmod/
+[`MainSections`]: /methods/site/mainsections/
+[`Summary`]: /methods/page/summary/
+[`WordCount`]: /methods/page/wordcount/
+[`cacheDir`]: #cachedir
+[`defaultContentLanguageInSubdir`]: #defaultcontentlanguageinsubdir
+[`defaultContentLanguage`]: #defaultcontentlanguage
+[`defaultContentRoleInSubdir`]: #defaultcontentroleinsubdir
+[`defaultContentRole`]: #defaultcontentrole
+[`defaultContentVersionInSubdir`]: #defaultcontentversioninsubdir
+[`defaultContentVersion`]: #defaultcontentversion
+[`disableDefaultSiteRedirect`]: #disabledefaultsiteredirect
+[`disabled`]: /configuration/languages/#disabled
+[`erroridf`]: /functions/fmt/erroridf/
+[`publishDir`]: #publishdir
+[`segments`]: /configuration/segments/
+[`staticDir`]: #staticdir
+[`strings.Title`]: /functions/strings/title/
+[`time.AsTime`]: /functions/time/astime/
+[`time.Format`]: /functions/time/format/
+[`titleCaseStyle`]: #titlecasestyle
+[`warnidf`]: /functions/fmt/warnidf/
+[aliases_front_matter]: /content-management/front-matter/#aliases
+[aliases_page_method]: /methods/page/aliases/
+[automatic summaries]: /content-management/summaries/#automatic-summary
+[client-side redirection]: /content-management/urls/#client-side-redirection
+[composite characters]: https://en.wikipedia.org/wiki/Precomposed_character
+[configure HTTP cache]: /configuration/http-cache/
+[configure build]: /configuration/build/
+[configure cascade]: /configuration/cascade/
+[configure deployment]: /configuration/deployment/
+[configure file caches]: /configuration/caches/
+[configure front matter]: /configuration/front-matter/
+[configure imaging]: /configuration/imaging/
+[configure languages]: /configuration/languages/
+[configure markup]: /configuration/markup/
+[configure media types]: /configuration/media-types/
+[configure menus]: /configuration/menus/
+[configure minify]: /configuration/minify/
+[configure modules]: /configuration/module/
+[configure output formats]: /configuration/output-formats/
+[configure outputs]: /configuration/outputs/
+[configure page]: /configuration/page/
+[configure pagination]: /configuration/pagination/
+[configure params]: /configuration/params/
+[configure permalinks]: /configuration/permalinks/
+[configure privacy]: /configuration/privacy/
+[configure related content]: /configuration/related-content
+[configure roles]: /configuration/roles/
+[configure security]: /configuration/security/
+[configure segments]: /configuration/segments/
+[configure server]: /configuration/server/
+[configure services]: /configuration/services/
+[configure sitemap]: /configuration/sitemap/
+[configure taxonomies]: /configuration/taxonomies/
+[configure ugly URLs]: /configuration/ugly-urls/
+[configure versions]: /configuration/versions/
+[duration]: https://pkg.go.dev/time#Duration
+[embedded Open Graph template]: <{{% eturl opengraph %}}>
+[embedded RSS template]: <{{% eturl rss %}}>
+[embedded alias template]: <{{% eturl alias %}}>
+[module mounts]: /configuration/module/#mounts
+[non-spacing marks]: https://www.compart.com/en/unicode/category/Mn
+[os.UserCacheDir]: https://pkg.go.dev/os#UserCacheDir
+[this configuration]: https://github.com/bep/hugo-sass-test/blob/6c3960a8f4b90e8938228688bc49bdcdd6b2d99e/.circleci/config.yml
diff --git a/documents/markdown/hugo-docs/en_configuration_build.md b/documents/markdown/hugo-docs/en_configuration_build.md
new file mode 100644
index 0000000..71d3020
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_build.md
@@ -0,0 +1,83 @@
+---
+title: Configure build
+linkTitle: Build
+description: Configure global build options.
+categories: []
+keywords: []
+aliases: [/getting-started/configuration-build/]
+---
+
+The `build` configuration section contains global build-related configuration options.
+
+{{< code-toggle config=build />}}
+
+buildStats
+: See the [build stats](#build-stats) section below.
+
+cachebusters
+: See the [cache busters](#cache-busters) section below.
+
+noJSConfigInAssets
+: (`bool`) Whether to disable writing a `jsconfig.json` in your `assets` directory with mapping of imports from running [js.Build](/hugo-pipes/js). This file is intended to help with intellisense/navigation inside code editors such as [VS Code](https://code.visualstudio.com/). Note that if you do not use `js.Build`, no file will be written.
+
+useResourceCacheWhen
+: (`string`) When to use the resource file cache, one of `never`, `fallback`, or `always`. Applicable when transpiling Sass to CSS. Default is `fallback`.
+
+## Cache busters
+
+The `build.cachebusters` configuration option was added to support development using Tailwind 3.x's JIT compiler where a `build` configuration may look like this:
+
+<!-- markdownlint-disable MD049 -->
+{{< code-toggle file=hugo >}}
+[build]
+ [build.buildStats]
+ enable = true
+ [[build.cachebusters]]
+ source = 'assets/watching/hugo_stats\.json'
+ target = 'styles\.css'
+ [[build.cachebusters]]
+ source = '(postcss|tailwind)\.config\.js'
+ target = 'css'
+ [[build.cachebusters]]
+ source = 'assets/.*\.(js|ts|jsx|tsx)'
+ target = 'js'
+ [[build.cachebusters]]
+ source = 'assets/.*\.(.*)$'
+ target = '$1'
+{{< /code-toggle >}}
+<!-- markdownlint-enable MD049 -->
+
+When `buildStats` is enabled, Hugo writes a `hugo_stats.json` file on each build with HTML classes etc. that's used in the rendered output. Changes to this file will trigger a rebuild of the `styles.css` file. You also need to add `hugo_stats.json` to Hugo's server watcher. See [Hugo Starter Tailwind Basic](https://github.com/bep/hugo-starter-tailwind-basic) for a running example.
+
+source
+: (`string`) A [regular expression](g) matching file(s) relative to one of the virtual component directories in Hugo, typically `assets/...`.
+
+target
+: (`string`) A [regular expression](g) matching the keys in the resource cache that should be expired when `source` changes. You can use the matching regexp groups from `source` in the expression, e.g. `$1`.
+
+## Build stats
+
+{{< code-toggle config=build.buildStats />}}
+
+enable
+: (`bool`) Whether to create a `hugo_stats.json` file in the root of your project. This file contains arrays of the `class` attributes, `id` attributes, and tags of every HTML element within your published site. Use this file as data source when [removing unused CSS] from your site. This process is also known as pruning, purging, or tree shaking. Default is `false`.
+
+[removing unused CSS]: /functions/resources/postprocess/
+
+disableIDs
+: (`bool`) Whether to exclude `id` attributes. Default is `false`.
+
+disableTags
+: (`bool`) Whether to exclude element tags. Default is `false`.
+
+disableClasses
+: (`bool`) Whether to exclude `class` attributes. Default is `false`.
+
+> [!note]
+> Given that CSS purging is typically limited to production builds, place the `buildStats` object below [`config/production`].
+>
+> Built for speed, there may be "false positive" detections (e.g., HTML elements that are not HTML elements) while parsing the published site. These "false positives" are infrequent and inconsequential.
+
+Due to the nature of partial server builds, new HTML entities are added while the server is running, but old values will not be removed until you restart the server or run `hugo build`.
+
+[`config/production`]: /configuration/introduction/#configuration-directory
diff --git a/documents/markdown/hugo-docs/en_configuration_caches.md b/documents/markdown/hugo-docs/en_configuration_caches.md
new file mode 100644
index 0000000..14ae43b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_caches.md
@@ -0,0 +1,61 @@
+---
+title: Configure file caches
+linkTitle: Caches
+description: Configure file caches.
+categories: []
+keywords: []
+---
+
+This is the default configuration:
+
+{{< code-toggle config=caches />}}
+
+## Purpose
+
+Hugo uses file caches to store data on disk, avoiding repeated operations within the same build and persisting data from one build to the next.
+
+assets
+: Caches processed CSS and Sass resources.
+
+getresource
+: Caches files fetched from remote URLs via the [`resources.GetRemote`][] function.
+
+images
+: Caches processed images.
+
+misc
+: Caches miscellaneous data.
+
+modulegitinfo
+: Caches Git information for modules.
+
+modulequeries
+: Caches the results of module resolution queries.
+
+modules
+: Caches downloaded modules.
+
+## Keys
+
+dir
+: (`string`) The absolute file system path where Hugo stores the cached files. You can begin the path with the `:cacheDir` or `:resourceDir` [tokens](#tokens) to anchor the cache to specific system or project locations.
+
+maxAge
+: (`string`) The duration a cached entry remains valid before being evicted, expressed as a [duration](g). A value of `0` disables the cache for that key, and a value of `-1` means the cache entry never expires. Default is `-1`.
+
+## Tokens
+
+`:cacheDir`
+: (`string`) The designated cache directory. See [details](/configuration/all/#cachedir).
+
+`:project`
+: (`string`) The base directory name of the current Hugo project. This ensures isolated file caches for each project, preventing the `hugo build --gc` command from affecting other projects on the same machine.
+
+`:resourceDir`
+: (`string`) The designated directory for caching output from [asset pipelines](g). See [details](/configuration/all/#resourcedir).
+
+## Garbage collection
+
+As you modify your site or change your configuration, cached files from previous builds may remain on disk, consuming unnecessary space. Use the `hugo build --gc` command to remove these expired or unused entries from the file cache.
+
+[`resources.GetRemote`]: /functions/resources/getremote/
diff --git a/documents/markdown/hugo-docs/en_configuration_cascade.md b/documents/markdown/hugo-docs/en_configuration_cascade.md
new file mode 100644
index 0000000..5616314
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_cascade.md
@@ -0,0 +1,74 @@
+---
+title: Configure cascade
+linkTitle: Cascade
+description: Configure cascade.
+categories: []
+keywords: []
+---
+
+You can configure your site to cascade front matter values to the home page and any of its descendants. However, this cascading will be prevented if the descendant already defines the field, or if a closer ancestor [node](g) has already cascaded a value for the same field through its front matter's `cascade` key.
+
+> [!note]
+> You can also configure cascading behavior within a page's front matter. See [details].
+
+For example, to cascade a "color" parameter to the home page and all its descendants:
+
+{{< code-toggle file=hugo >}}
+[cascade.params]
+color = 'red'
+{{< /code-toggle >}}
+
+## Target
+
+<!-- TODO
+We deprecated the `_target` front matter key in favor of `target` in v0.156.0 on 2026-02-17. Remove footnote #1 on or after 2027-05-17 (15 months after deprecation).
+-->
+
+The `target`[^1] keyword allows you to target specific pages or [environments](g). For example, to cascade a "color" parameter to pages within the "articles" section, including the "articles" section page itself:
+
+[^1]: The `_target` alias for `target` is deprecated and will be removed in a future release.
+
+{{< code-toggle file=hugo >}}
+[cascade.params]
+color = 'red'
+[cascade.target]
+path = '{/articles,/articles/**}'
+{{< /code-toggle >}}
+
+Use any combination of these keywords to target pages and/or environments:
+
+environment
+: (`string`) A [glob pattern](g) matching the build [environment](g). For example: `{staging,production}`.
+
+kind
+: (`string`) A [glob pattern](g) matching the [page kind](g). For example: `{taxonomy,term}`.
+
+lang
+: (`string`) A [glob pattern](g) matching the [page language]. For example: `{en,de}`.
+
+path
+: (`string`) A [glob pattern](g) matching the page's [logical path](g). For example: `{/books,/books/**}`.
+
+## Array
+
+Define an array of cascade parameters to apply different values to different targets. For example:
+
+{{< code-toggle file=hugo >}}
+[[cascade]]
+[cascade.params]
+color = 'red'
+[cascade.target]
+path = '/books/**'
+kind = 'page'
+lang = '{en,de}'
+[[cascade]]
+[cascade.params]
+color = 'blue'
+[cascade.target]
+path = '/films/**'
+kind = 'page'
+environment = 'production'
+{{< /code-toggle >}}
+
+[details]: /content-management/front-matter/#cascade-1
+[page language]: /methods/page/language/
diff --git a/documents/markdown/hugo-docs/en_configuration_content-types.md b/documents/markdown/hugo-docs/en_configuration_content-types.md
new file mode 100644
index 0000000..4c5b5a2
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_content-types.md
@@ -0,0 +1,63 @@
+---
+title: Configure content types
+linkTitle: Content types
+description: Configure content types.
+categories: []
+keywords: []
+---
+
+{{< new-in 0.144.0 />}}
+
+Hugo supports six [content formats](g):
+
+{{% include "/_common/content-format-table.md" %}}
+
+These can be used as either page content or [page resources](g). When used as page resources, their [resource type](g) is `page`.
+
+Consider this example of a [page bundle](g):
+
+```text
+content/
+└── example/
+ ├── index.md <-- content
+ ├── a.adoc <-- resource (resource type: page)
+ ├── b.html <-- resource (resource type: page)
+ ├── c.md <-- resource (resource type: page)
+ ├── d.org <-- resource (resource type: page)
+ ├── e.pdc <-- resource (resource type: page)
+ ├── f.rst <-- resource (resource type: page)
+ ├── g.jpg <-- resource (resource type: image)
+ └── h.png <-- resource (resource type: image)
+```
+
+The `index.md` file is the page's content, while the other files are page resources. Files `a` through `f` are of resource type `page`, while `g` and `h` are of resource type `image`.
+
+When you build a site, Hugo does not publish page resources having a resource type of `page`. For example, this is the result of building the site above:
+
+```text
+public/
+├── example/
+│ ├── g.jpg
+│ ├── h.png
+│ └── index.html
+└── index.html
+```
+
+The default behavior is appropriate in most cases. Given that page resources containing markup are typically intended for inclusion in the main content, publishing them independently is generally undesirable.
+
+The default behavior is determined by the `contentTypes` configuration:
+
+{{< code-toggle config=contentTypes />}}
+
+In this default configuration, page resources with those media types will have a resource type of `page`, and will not be automatically published. To change the resource type assignment from `page` to `text` for a given media type, remove the corresponding entry from the list.
+
+For example, to set the resource type of `text/html` files to `text`, thereby enabling automatic publication, remove the `text/html` entry:
+
+{{< code-toggle file=hugo >}}
+contentTypes:
+ text/asciidoc: {}
+ text/markdown: {}
+ text/org: {}
+ text/pandoc: {}
+ text/rst: {}
+{{< /code-toggle >}}
diff --git a/documents/markdown/hugo-docs/en_configuration_deployment.md b/documents/markdown/hugo-docs/en_configuration_deployment.md
new file mode 100644
index 0000000..f145f3f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_deployment.md
@@ -0,0 +1,159 @@
+---
+title: Configure deployment
+linkTitle: Deployment
+description: Configure deployments to Amazon S3, Azure Blob Storage, or Google Cloud Storage.
+categories: []
+keywords: []
+---
+
+> [!note]
+> This configuration is only relevant when running `hugo deploy`. See [details](/host-and-deploy/deploy-with-hugo-deploy/).
+
+## Top-level options
+
+These settings control the overall behavior of the deployment process. This is the default configuration:
+
+{{< code-toggle file=hugo config=deployment />}}
+
+confirm
+: (`bool`) Whether to prompt for confirmation before deploying. Default is `false`.
+
+dryRun
+: (`bool`) Whether to simulate the deployment without any remote changes. Default is `false`.
+
+force
+: (`bool`) Whether to re-upload all files. Default is `false`.
+
+invalidateCDN
+: (`bool`) Whether to invalidate the CDN cache listed in the deployment target. Default is `true`.
+
+maxDeletes
+: (`int`) The maximum number of files to delete, or `-1` to disable. Default is `256`.
+
+matchers
+: (`[]*Matcher`) A slice of [matchers](#matchers-1).
+
+order
+: (`[]string`) An ordered slice of [regular expressions](g) that determines upload priority (left to right). Files not matching any expression are uploaded last in an arbitrary order.
+
+target
+: (`string`) The target deployment [`name`](#name). Defaults to the first target.
+
+targets
+: (`[]*Target`) A slice of [targets](#targets-1).
+
+workers
+: (`int`) The number of concurrent workers to use when uploading files. Default is `10`.
+
+## Targets
+
+A target represents a deployment target such as "staging" or "production".
+
+cloudFrontDistributionID
+: (`string`) The CloudFront Distribution ID, applicable if you are using the Amazon Web Services CloudFront CDN. Hugo will invalidate the CDN when deploying this target.
+
+exclude
+: (`string`) A [glob pattern](g) matching files to exclude when deploying to this target. Local files failing the include/exclude filters are not uploaded, and remote files failing these filters are not deleted.
+
+googleCloudCDNOrigin
+: (`string`) The Google Cloud project and CDN origin to invalidate when deploying this target, specified as `<project>/<origin>`.
+
+include
+: (`string`) A [glob pattern](g) matching files to include when deploying to this target. Local files failing the include/exclude filters are not uploaded, and remote files failing these filters are not deleted.
+
+name
+: (`string`) An arbitrary name for this target.
+
+stripIndexHTML
+: (`bool`) Whether to map files named `<dir>/index.html` to `<dir>` on the remote (except for the root `index.html`). This is useful for key-value cloud storage (e.g., Amazon S3, Google Cloud Storage, Azure Blob Storage) to align canonical URLs with object keys. Default is `false`.
+
+url
+: (`string`) The [destination URL](#destination-urls) for deployment.
+
+## Matchers
+
+A Matcher represents a configuration to be applied to files whose paths match
+the specified pattern.
+
+cacheControl
+: (`string`) The caching attributes to use when serving the blob. See [details][cacheControl].
+
+contentEncoding
+: (`string`) The encoding used for the blob's content, if any. See [details][contentEncoding].
+
+contentType
+: (`string`) The media type of the blob being written. See [details][contentType].
+
+force
+: (`bool`) Whether matching files should be re-uploaded. Useful when other route-determined metadata (e.g., `contentType`) has changed. Default is `false`.
+
+gzip
+: (`bool`) Whether the file should be gzipped before upload. If so, the `ContentEncoding` field will automatically be set to `gzip`. Default is `false`.
+
+pattern
+: (`string`) A [regular expression](g) used to match paths. Paths are converted to use forward slashes (`/`) before matching.
+
+[cacheControl]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control
+[contentEncoding]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding
+[contentType]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
+
+## Destination URLs
+
+Service|URL example
+:--|:--
+Amazon Simple Storage Service (S3)|`s3://my-bucket?region=us-west-1`
+Azure Blob Storage|`azblob://my-container`
+Google Cloud Storage (GCS)|`gs://my-bucket`
+
+With Google Cloud Storage you can target a subdirectory:
+
+```text
+gs://my-bucket?prefix=a/subdirectory
+```
+
+You can also to deploy to storage servers compatible with Amazon S3 such as:
+
+- [Ceph]
+- [MinIO]
+- [SeaweedFS]
+
+[Ceph]: https://ceph.com/
+[Minio]: https://www.minio.io/
+[SeaweedFS]: https://github.com/chrislusf/seaweedfs
+
+For example, the `url` for a MinIO deployment target might resemble this:
+
+```text
+s3://my-bucket?endpoint=https://my.minio.instance&awssdk=v2&use_path_style=true&disable_https=false
+```
+
+## Example
+
+{{< code-toggle file=hugo >}}
+[deployment]
+ order = ['.jpg$', '.gif$']
+ [[deployment.matchers]]
+ cacheControl = 'max-age=31536000, no-transform, public'
+ gzip = true
+ pattern = '^.+\.(js|css|svg|ttf)$'
+ [[deployment.matchers]]
+ cacheControl = 'max-age=31536000, no-transform, public'
+ gzip = false
+ pattern = '^.+\.(png|jpg)$'
+ [[deployment.matchers]]
+ contentType = 'application/xml'
+ gzip = true
+ pattern = '^sitemap\.xml$'
+ [[deployment.matchers]]
+ gzip = true
+ pattern = '^.+\.(html|xml|json)$'
+ [[deployment.targets]]
+ url = 's3://my_production_bucket?region=us-west-1'
+ cloudFrontDistributionID = 'E1234567890ABCDEF0'
+ exclude = '**.{heic,psd}'
+ name = 'production'
+ [[deployment.targets]]
+ url = 's3://my_staging_bucket?region=us-west-1'
+ exclude = '**.{heic,psd}'
+ name = 'staging'
+{{< /code-toggle >}}
diff --git a/documents/markdown/hugo-docs/en_configuration_front-matter.md b/documents/markdown/hugo-docs/en_configuration_front-matter.md
new file mode 100644
index 0000000..272140b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_front-matter.md
@@ -0,0 +1,103 @@
+---
+title: Configure front matter
+linkTitle: Front matter
+description: Configure front matter.
+categories: []
+keywords: []
+---
+
+## Dates
+
+There are four methods on a `Page` object that return a date.
+
+Method|Description
+:--|:--
+[`Date`][]|Returns the date of the given page.
+[`ExpiryDate`][]|Returns the expiry date of the given page.
+[`Lastmod`][]|Returns the last modification date of the given page.
+[`PublishDate`][]|Returns the publish date of the given page.
+
+[`Date`]: /methods/page/date
+[`ExpiryDate`]: /methods/page/expirydate
+[`Lastmod`]: /methods/page/lastmod
+[`PublishDate`]: /methods/page/publishdate
+
+Hugo determines the values to return based on this configuration:
+
+{{< code-toggle config=frontmatter />}}
+
+The `ExpiryDate` method, for example, returns the `expirydate` value if it exists, otherwise it returns `unpublishdate`.
+
+You can also use custom date parameters:
+
+{{< code-toggle file=hugo >}}
+[frontmatter]
+date = ["myDate", "date"]
+{{< /code-toggle >}}
+
+In the example above, the `Date` method returns the `myDate` value if it exists, otherwise it returns `date`.
+
+To fall back to the default sequence of dates, use the `:default` token:
+
+{{< code-toggle file=hugo >}}
+[frontmatter]
+date = ["myDate", ":default"]
+{{< /code-toggle >}}
+
+In the example above, the `Date` method returns the `myDate` value if it exists, otherwise it returns the first valid date from `date`, `publishdate`, `pubdate`, `published`, `lastmod`, and `modified`.
+
+## Aliases
+
+Some of the front matter fields have aliases.
+
+Front matter field|Aliases
+:--|:--
+`expiryDate`|`unpublishdate`
+`lastmod`|`modified`
+`publishDate`|`pubdate`, `published`
+
+The default front matter configuration includes these aliases.
+
+## Tokens
+
+Hugo provides the following [tokens](g) to help you configure your front matter:
+
+`:default`
+: The default ordered sequence of date fields.
+
+`:fileModTime`
+: The file's last modification timestamp.
+
+`:filename`
+: Extracts the date from the file name, provided the file name begins with a date in one of the following formats:
+
+ - `YYYY-MM-DD`
+ - `YYYY-MM-DD-HH-MM-SS` {{< new-in 0.148.0 />}}
+
+ Within the `YYYY-MM-DD-HH-MM-SS` format, the date and time values may be separated by any character including a space (e.g., `2025-02-01T14-30-00`).
+
+ Hugo resolves the extracted date to the [`timeZone`][] defined in your project configuration, falling back to the system time zone. After extracting the date, Hugo uses the remaining part of the file name to generate the page's [`slug`][], but only if you haven't already specified a slug in the page's front matter.
+
+ For example, if you name your file `2025-02-01-article.md`, Hugo will set the date to `2025-02-01` and the slug to `article`.
+
+`:git`
+: The Git author date for the file's last revision. To enable access to the Git author date, set [`enableGitInfo`][] to `true`.
+
+## Example
+
+Consider this project configuration:
+
+{{< code-toggle file=hugo >}}
+[frontmatter]
+date = [':filename', ':default']
+publishDate = [':filename', ':default']
+lastmod = ['lastmod', ':fileModTime']
+{{< /code-toggle >}}
+
+To determine `date` and `publishDate`, Hugo tries to extract the value from the file name, falling back to the default ordered sequence of date fields.
+
+To determine `lastmod`, Hugo looks for a `lastmod` field in front matter, falling back to the file's last modification timestamp.
+
+[`enableGitInfo`]: /configuration/all/#enablegitinfo
+[`slug`]: /content-management/front-matter/#slug
+[`timeZone`]: /configuration/all/#timezone
diff --git a/documents/markdown/hugo-docs/en_configuration_http-cache.md b/documents/markdown/hugo-docs/en_configuration_http-cache.md
new file mode 100644
index 0000000..73ef02a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_http-cache.md
@@ -0,0 +1,129 @@
+---
+title: Configure the HTTP cache
+linkTitle: HTTP cache
+description: Configure the HTTP cache.
+categories: []
+keywords: []
+---
+
+> [!note]
+> This configuration is only relevant when using the [`resources.GetRemote`] function.
+
+## Layered caching
+
+Hugo employs a layered caching system.
+
+```goat {.w-40}
+ .-----------.
+| dynacache |
+ '-----+-----'
+ |
+ v
+ .----------.
+| HTTP cache |
+ '-----+----'
+ |
+ v
+ .----------.
+| file cache |
+ '-----+----'
+```
+
+Dynacache
+: An in-memory cache employing a Least Recently Used (LRU) eviction policy. Entries are removed from the cache when changes occur, when they match [cache-busting] patterns, or under low-memory conditions.
+
+HTTP Cache
+: An HTTP cache for remote resources as specified in [RFC 9111]. Optimal performance is achieved when resources include appropriate HTTP cache headers. The HTTP cache utilizes the file cache for storage and retrieval of cached resources.
+
+File cache
+: See [configure file caches].
+
+The HTTP cache involves two key aspects: determining which content to cache (the caching process itself) and defining the frequency with which to check for updates (the polling strategy).
+
+## HTTP caching
+
+The HTTP cache behavior is defined for a configured set of resources. Stale resources will be refreshed from the file cache, even if their configured Time-To-Live (TTL) has not expired. If HTTP caching is disabled for a resource, Hugo will bypass the cache and access the file directly.
+
+This is the default configuration for HTTP caching:
+
+{{< code-toggle config=HTTPCache />}}
+
+respectCacheControlNoStoreInRequest
+: {{< new-in 0.151.0 />}}
+: (`bool`) Whether to respect the `no-store` directive in the server's `Cache-Control` request header when fetching remote resources via the [`resources.GetRemote`][] function. Default is `true`.
+
+respectCacheControlNoStoreInResponse
+: {{< new-in 0.151.0 />}}
+: (`bool`) Whether to respect the `no-store` directive in the server's `Cache-Control` response header when fetching remote resources via the [`resources.GetRemote`][] function. Default is `false`.
+
+cache.for.excludes
+: (`[]string`) A slice of [glob patterns](g) to exclude from caching. In its default configuration HTTP caching excludes all files.
+
+cache.for.includes
+: (`[]string`) A slice of [glob patterns](g) to cache.
+
+polls
+: A slice of polling configurations.
+
+polls.disable
+: (`bool`) Whether to disable polling for this configuration. Default is `true`.
+
+polls.high
+: (`string`) The maximum polling interval expressed as a [duration](g). This is used when the resource is considered stable. Default is `0s`.
+
+polls.low
+: (`string`) The minimum polling interval expressed as a [duration](g). This is used after a recent change and gradually increases towards `polls.high`. Default is `0s`.
+
+polls.for.excludes
+: (`[]string`) A slice of [glob patterns](g) to exclude from polling for this configuration.
+
+polls.for.includes
+: (`[]string`) A slice of [glob patterns](g) to include in polling for this configuration.
+
+## HTTP polling
+
+Polling is used in watch mode (e.g., `hugo server`) to detect changes in remote resources. Polling can be enabled even if HTTP caching is disabled. Detected changes trigger a rebuild of pages using the affected resource. Polling can be disabled for specific resources, typically those known to be static.
+
+The default configuration disables everything:
+
+{{< code-toggle file=hugo >}}
+[[HTTPCache.polls]]
+disable = true
+high = '0s'
+low = '0s'
+[HTTPCache.polls.for]
+includes = ['**']
+excludes = []
+{{< /code-toggle >}}
+
+polls
+: A slice of polling configurations.
+
+polls.disable
+: (`bool`) Whether to disable polling for this configuration. Default is `true`.
+
+polls.high
+: (`string`) The maximum polling interval expressed as a [duration](g). This is used when the resource is considered stable. Default is `0s`.
+
+polls.low
+: (`string`) The minimum polling interval expressed as a [duration](g). This is used after a recent change and gradually increases towards `polls.high`. Default is `0s`.
+
+polls.for.excludes
+: (`[]string`) A list of [glob patterns](g) to exclude from polling for this configuration.
+
+polls.for.includes
+: (`[]string`) A list of [glob patterns](g) to include in polling for this configuration.
+
+## Behavior
+
+Polling and HTTP caching interact as follows:
+
+- With polling enabled, rebuilds are triggered only by actual changes, detected via `eTag` changes (Hugo generates an MD5 hash if the server doesn't provide one).
+- If polling is enabled but HTTP caching is disabled, the remote is checked for changes only after the file cache's TTL expires (e.g., a `maxAge` of `10h` with a `1s` polling interval is inefficient).
+- If both polling and HTTP caching are enabled, changes are checked for even before the file cache's TTL expires. Cached `eTag` and `last-modified` values are sent in `if-none-match` and `if-modified-since` headers, respectively, and a cached response is returned on HTTP [304].
+
+[`resources.GetRemote`]: /functions/resources/getremote/
+[304]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/304
+[cache-busting]: /configuration/build/#cache-busters
+[configure file caches]: /configuration/caches/
+[RFC 9111]: https://datatracker.ietf.org/doc/html/rfc9111
diff --git a/documents/markdown/hugo-docs/en_configuration_imaging.md b/documents/markdown/hugo-docs/en_configuration_imaging.md
new file mode 100644
index 0000000..c0ba731
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_imaging.md
@@ -0,0 +1,91 @@
+---
+title: Configure imaging
+linkTitle: Imaging
+description: Configure imaging.
+categories: []
+keywords: []
+---
+
+These are the default settings for processing images:
+
+{{< code-toggle config=imaging />}}
+
+## Top-level options
+
+These global settings define how Hugo handles the fundamental aspects of image manipulation, such as cropping logic, background colors, and general output quality.
+
+anchor
+: (`string`) The focal point used when cropping or filling an image. Valid case-insensitive options include `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. The `Smart` option utilizes the [`muesli/smartcrop`][] package to identify the most interesting area of the image. Default is `smart`.
+
+bgColor
+: (string) The background color used when converting transparent images to formats that do not support transparency, such as PNG to JPEG. This color also fills the empty space created when rotating an image by a non-orthogonal angle if the space is not transparent and a background color is not specified in the processing specification. The value must be an RGB [hexadecimal color][]. Default is `#ffffff`.
+
+compression
+: {{< new-in 0.153.5 />}}
+: (`string`) The encoding strategy used for the image. Options are `lossy` or `lossless`. Note that `lossless` is only supported by the WebP format. Default is `lossy`.
+
+quality
+: (`int`) The visual fidelity of the image, applicable to JPEG and WebP formats when using `lossy` compression. Expressed as a whole number from `1` to `100`, inclusive. Lower numbers prioritize smaller file size, while higher numbers prioritize visual clarity. Default is `75`.
+
+resampleFilter
+: (`string`) The algorithm used to calculate new pixels when resizing, fitting, or filling an image. Common options include `box`, `lanczos`, `catmullRom`, `mitchellNetravali`, `linear`, or `nearestNeighbor`. Default is `box`.
+
+ Filter|Description
+ :--|:--
+ `box`|Simple and fast averaging filter appropriate for downscaling
+ `lanczos`|High-quality resampling filter for photographic images yielding sharp results
+ `catmullRom`|Sharp cubic filter that is faster than the Lanczos filter while providing similar results
+ `mitchellNetravali`|Cubic filter that produces smoother results with less ringing artifacts than CatmullRom
+ `linear`|Bilinear resampling filter, produces smooth output, faster than cubic filters
+ `nearestNeighbor`|Fastest resampling filter, no antialiasing
+
+ Refer to the [source documentation][] for a complete list of available resampling filters. If you wish to improve image quality at the expense of performance, you may wish to experiment with the alternative filters.
+
+## Exif method
+
+{{< deprecated-in 0.155.0 >}}
+Use [`Meta`](/methods/resource/meta/) instead.
+{{< /deprecated-in >}}
+
+## Meta method
+
+{{< new-in 0.155.0 />}}
+
+The following parameters allow you to control how Hugo extracts and filters metadata when using the [`Meta`][] method, helping you balance data granularity with build performance.
+
+fields
+: (`[]string`) A [glob slice](g) matching the fields to include when extracting metadata. If empty, a default set excluding technical metadata is used. Set to `['**']` to include all fields.
+
+ > [!note]
+ > By default, to improve performance and decrease cache size, Hugo excludes the following fields: `ColorSpace`, `Contrast`, `Exif`, `ExposureBias`, `ExposureMode`, `ExposureProgram`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`.
+
+sources
+: (`[]string`) The metadata sources to include, one or more of `exif`, `iptc`, or `xmp`. Default is `['exif', 'iptc']`. The XMP metadata is excluded by default to improve performance.
+
+## WebP images
+
+{{< new-in 0.155.0 />}}
+
+These specialized settings provide granular control over the WebP encoding process, allowing you to optimize compression based on the specific visual characteristics of your imagery.
+
+hint
+: (`string`) The encoding preset used when processing WebP images, equivalent to the `-preset` flag for the [`cwebp`][] CLI. Valid options include `drawing`, `icon`, `photo`, `picture`, or `text`. Default is `photo`.
+
+ Value|Example
+ :--|:--
+ `drawing`|Hand or line drawing with high-contrast details
+ `icon`|Small colorful image
+ `photo`|Outdoor photograph with natural lighting
+ `picture`|Indoor photograph such as a portrait
+ `text`|Image that is primarily text
+
+method
+: (`int`) The effort level of the compression algorithm. Expressed as a whole number from `0` to `6`, inclusive, equivalent to the `-m` flag for the [`cwebp`][] CLI. Lower numbers prioritize processing speed, while higher numbers prioritize compression efficiency. Default is `2`.
+
+useSharpYuv
+: (`bool`) The conversion method used for RGB-to-YUV encoding, equivalent to the `-sharp_yuv` flag for the [`cwebp`][] CLI. Enabling this prioritizes image sharpness at the expense of processing speed. Default is `false`.
+
+[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
+[`muesli/smartcrop`]: https://github.com/muesli/smartcrop
+[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
+[source documentation]: https://github.com/disintegration/imaging#image-resizing
diff --git a/documents/markdown/hugo-docs/en_configuration_introduction.md b/documents/markdown/hugo-docs/en_configuration_introduction.md
new file mode 100644
index 0000000..7a117ba
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_introduction.md
@@ -0,0 +1,288 @@
+---
+title: Introduction
+description: Configure your site using files, directories, and environment variables.
+categories: []
+keywords: []
+weight: 10
+---
+
+## Sensible defaults
+
+Hugo offers many configuration options, but its defaults are often sufficient. A new project requires only these settings:
+
+{{< code-toggle file=hugo >}}
+baseURL = 'https://example.org/'
+locale = 'en-us'
+title = 'My New Hugo Site'
+{{< /code-toggle >}}
+
+Only define settings that deviate from the defaults. A smaller configuration file is easier to read, understand, and debug. Keep your configuration concise.
+
+> [!note]
+> The best configuration file is a short configuration file.
+
+## Configuration file
+
+Create a project configuration file in the root of your project directory, naming it `hugo.toml`, `hugo.yaml`, or `hugo.json`, with that order of precedence.
+
+```text
+my-project/
+└── hugo.toml
+```
+
+> [!note]
+> For versions v0.109.0 and earlier, the project configuration file was named `config`. While you can still use this name, it's recommended to switch to the newer naming convention, `hugo`.
+
+A simple example:
+
+{{< code-toggle file=hugo >}}
+baseURL = 'https://example.org/'
+locale = 'en-us'
+title = 'ABC Widgets, Inc.'
+[params]
+subtitle = 'The Best Widgets on Earth'
+[params.contact]
+email = 'info@example.org'
+phone = '+1 202-555-1212'
+{{< /code-toggle >}}
+
+To use a different configuration file when building your project, use the `--config` flag:
+
+```sh
+hugo build --config other.toml
+```
+
+Combine two or more configuration files, with left-to-right precedence:
+
+```sh
+hugo build --config a.toml,b.yaml,c.json
+```
+
+> [!note]
+> See the specifications for each file format: [TOML], [YAML], and [JSON].
+
+## Configuration directory
+
+Instead of a single project configuration file, split your configuration by [environment](g), root configuration key, and language. For example:
+
+```text
+my-project/
+└── config/
+ ├── _default/
+ │ ├── hugo.toml
+ │ ├── menus.en.toml
+ │ ├── menus.de.toml
+ │ └── params.toml
+ └── production/
+ └── params.toml
+```
+
+The root configuration keys are {{< root-configuration-keys >}}.
+
+> [!note]
+> You must define `cascade` tables in the root configuration file. You cannot define `cascade` tables in a dedicated file. See issue [#12899] for details.
+
+[#12899]: https://github.com/gohugoio/hugo/issues/12899
+
+### Omit the root key
+
+When splitting the configuration by root key, omit the root key in the component file. For example, these are equivalent:
+
+{{< code-toggle file=config/_default/hugo >}}
+[params]
+foo = 'bar'
+{{< /code-toggle >}}
+
+{{< code-toggle file=config/_default/params >}}
+foo = 'bar'
+{{< /code-toggle >}}
+
+### Recursive parsing
+
+Hugo parses the `config` directory recursively, allowing you to organize the files into subdirectories. For example:
+
+```text
+my-project/
+└── config/
+ └── _default/
+ ├── navigation/
+ │ ├── menus.de.toml
+ │ └── menus.en.toml
+ └── hugo.toml
+```
+
+### Example
+
+```text
+my-project/
+└── config/
+ ├── _default/
+ │ ├── hugo.toml
+ │ ├── menus.en.toml
+ │ ├── menus.de.toml
+ │ └── params.toml
+ ├── production/
+ │ ├── hugo.toml
+ │ └── params.toml
+ └── staging/
+ ├── hugo.toml
+ └── params.toml
+```
+
+Considering the structure above, when running `hugo build --environment staging`, Hugo will use every setting from `config/_default` and merge `staging`'s on top of those.
+
+Let's take an example to understand this better. Let's say you are using Google Analytics for your website. This requires you to specify a [Google tag ID] in your project configuration:
+
+{{< code-toggle file=hugo >}}
+[services.googleAnalytics]
+ID = 'G-XXXXXXXXX'
+{{< /code-toggle >}}
+
+Now consider the following scenario:
+
+1. You don't want to load the analytics code when running `hugo server`.
+1. You want to use different Google tag IDs for your production and staging environments. For example:
+ - `G-PPPPPPPPP` for production
+ - `G-SSSSSSSSS` for staging
+
+To satisfy these requirements, configure your site as follows:
+
+1. `config/_default/hugo.toml`
+ - Exclude the `services.googleAnalytics` section. This will prevent loading of the analytics code when you run `hugo server`.
+ - By default, Hugo sets its `environment` to `development` when running `hugo server`. In the absence of a `config/development` directory, Hugo uses the `config/_default` directory.
+1. `config/production/hugo.toml`
+ - Include this section only:
+
+ {{< code-toggle file=hugo >}}
+ [services.googleAnalytics]
+ ID = 'G-PPPPPPPPP'
+ {{< /code-toggle >}}
+
+ - You do not need to include other parameters in this file. Include only those parameters that are specific to your production environment. Hugo will merge these parameters with the default configuration.
+ - By default, Hugo sets its `environment` to `production` when running `hugo build`. The analytics code will use the `G-PPPPPPPPP` tag ID.
+
+1. `config/staging/hugo.toml`
+
+ - Include this section only:
+
+ {{< code-toggle file=hugo >}}
+ [services.googleAnalytics]
+ ID = 'G-SSSSSSSSS'
+ {{< /code-toggle >}}
+
+ - You do not need to include other parameters in this file. Include only those parameters that are specific to your staging environment. Hugo will merge these parameters with the default configuration.
+ - To build your staging site, run `hugo build --environment staging`. The analytics code will use the `G-SSSSSSSSS` tag ID.
+
+## Merge configuration settings
+
+Hugo merges configuration settings from themes and modules, prioritizing the project's own settings. Given this simplified project structure with two themes:
+
+```text
+project/
+├── themes/
+│ ├── theme-a/
+│ │ └── hugo.toml
+│ └── theme-b/
+│ └── hugo.toml
+└── hugo.toml
+```
+
+and this project-level configuration:
+
+{{< code-toggle file=hugo >}}
+baseURL = 'https://example.org/'
+locale = 'en-us'
+title = 'My New Hugo Site'
+theme = ['theme-a','theme-b']
+{{< /code-toggle >}}
+
+Hugo merges settings in this order:
+
+1. Project configuration (`hugo.toml` in the project root)
+1. `theme-a` configuration
+1. `theme-b` configuration
+
+The `_merge` setting within each top-level configuration key controls _which_ settings are merged and _how_ they are merged.
+
+The value for `_merge` can be one of:
+
+none
+: No merge.
+
+shallow
+: Only add values for new keys.
+
+deep
+: Add values for new keys, merge existing.
+
+Note that you don't need to be so verbose as in the default setup below; a `_merge` value higher up will be inherited if not set.
+
+{{< code-toggle file=hugo dataKey="config_helpers.mergeStrategy" skipHeader=true />}}
+
+## Environment variables
+
+You can also configure settings using operating system environment variables:
+
+```sh
+export HUGO_BASEURL=https://example.org/
+export HUGO_ENABLEGITINFO=true
+export HUGO_ENVIRONMENT=staging
+hugo
+```
+
+The above sets the [`baseURL`], [`enableGitInfo`], and [`environment`] configuration options and then builds your site.
+
+> [!note]
+> An environment variable takes precedence over the values set in the configuration file. This means that if you set a configuration value with both an environment variable and in the configuration file, the value in the environment variable will be used.
+
+Environment variables simplify configuration for [CI/CD](g) platforms by allowing you to set values directly within their respective configuration and workflow files.
+
+> [!note]
+> Environment variable names must be prefixed with `HUGO_`.
+>
+> To set custom site parameters, prefix the name with `HUGO_PARAMS_`.
+
+For snake_case variable names, the standard `HUGO_` prefix won't work. Hugo infers the delimiter from the first character following `HUGO`. This allows for variations like `HUGOxPARAMSxAPI_KEY=abcdefgh` using any [permitted delimiter].
+
+In addition to configuring standard settings, environment variables may be used to override default values for certain internal settings:
+
+DART_SASS_BINARY
+: (`string`) The absolute path to the Dart Sass executable. By default, Hugo searches for the executable in each of the paths in the `PATH` environment variable.
+
+HUGO_FILE_LOG_FORMAT
+: (`string`) A format string for the file path, line number, and column number displayed when reporting errors, or when calling the `Position` method from a shortcode or Markdown render hook. Valid tokens are `:file`, `:line`, and `:col`. Default is `:file::line::col`.
+
+HUGO_MEMORYLIMIT
+: (`int`) The maximum amount of system memory, in gigabytes, that Hugo can use while rendering your site. Default is 25% of total system memory. Note that `HUGO_MEMORYLIMIT` is a "best effort" setting. Don't expect Hugo to build a million pages with only 1 GB of memory. You can get more information about how this behaves during the build by running `hugo build --logLevel info` and look for the `dynacache` label.
+
+HUGO_NUMWORKERMULTIPLIER
+: (`int`) The number of workers used in parallel processing. Default is the number of logical CPUs.
+
+## Current configuration
+
+Display the complete project configuration with:
+
+```sh
+hugo config
+```
+
+Display a specific configuration setting with:
+
+```sh
+hugo config | grep [key]
+```
+
+Display the configured file mounts with:
+
+```sh
+hugo config mounts
+```
+
+[`baseURL`]: /configuration/all#baseurl
+[`enableGitInfo`]: /configuration/all#enablegitinfo
+[`environment`]: /configuration/all#environment
+[Google tag ID]: https://support.google.com/tagmanager/answer/12326985?hl=en
+[JSON]: https://datatracker.ietf.org/doc/html/rfc7159
+[permitted delimiter]: https://pubs.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap08.html
+[TOML]: https://toml.io/en/latest
+[YAML]: https://yaml.org/spec/
diff --git a/documents/markdown/hugo-docs/en_configuration_languages.md b/documents/markdown/hugo-docs/en_configuration_languages.md
new file mode 100644
index 0000000..b289d8a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_languages.md
@@ -0,0 +1,217 @@
+---
+title: Configure languages
+linkTitle: Languages
+description: Configure the languages in your multilingual project.
+categories: []
+keywords: []
+---
+
+## Base settings
+
+Configure the following base settings:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'en'
+defaultContentLanguageInSubdir = false
+disableDefaultLanguageRedirect = false
+disableLanguages = []
+{{< /code-toggle >}}
+
+defaultContentLanguage
+: (`string`) The projects's default content language, conforming to the syntax described in [RFC 5646][]. This value must match one of the defined [language keys][]. Default is `en`.
+
+defaultContentLanguageInSubdir
+: (`bool`) Whether to publish the default content language to a subdirectory matching the [`defaultContentLanguage`][]. Default is `false`.
+
+disableDefaultLanguageRedirect
+: {{< new-in 0.140.0 />}}
+: (`bool`) Whether to disable generation of the alias redirect for the default content language. When [`defaultContentLanguageInSubdir`][] is `true`, this setting prevents the root directory from redirecting to the language subdirectory. Conversely, when `defaultContentLanguageInSubdir` is `false`, this setting prevents the language subdirectory from redirecting to the root directory. This is superseded by the more general [`disableDefaultSiteRedirect`][] setting. Default is `false`.
+
+disableLanguages
+: (`[]string]`) A slice of language keys representing the languages to disable during the build process. Although this is functional, consider using the [`disabled`](#disabled) key under each language instead.
+
+## Language settings
+
+Configure each language under the `languages` key:
+
+{{< code-toggle config=languages />}}
+
+In the above, `en` is the [language key](#language-keys).
+
+direction
+: (`string`) The language direction, either left-to-right (`ltr`) or right-to-left (`rtl`). Use this value in your templates with the global [`dir`][] HTML attribute. Access this value from a template using the [`Language.Direction`][] method on a `Site` or `Page` object. Default is `ltr`.
+
+disabled
+: (`bool`) Whether to disable this language when building the site. Default is `false`.
+
+label
+: (`string`) The language name, typically used when rendering a language switcher. Access this value from a template using the [`Language.Label`][] method on a `Site` or `Page` object.
+
+languageCode
+: {{<deprecated-in 0.158.0 />}}
+: Use [`locale`](#locale) instead.
+
+languageDirection
+: {{<deprecated-in 0.158.0 />}}
+: Use [`direction`](#direction) instead.
+
+languageName
+: {{<deprecated-in 0.158.0 />}}
+: Use [`label`](#label) instead.
+
+locale
+: (`string`) The language tag as described in [RFC 5646][]. This is the primary value used by the [`language.Translate`][] function to select a translation table, falling back to the language key if a matching translation table does not exist.
+
+ Hugo also uses this value to populate:
+
+ - The `lang` attribute of the `html` element in the [embedded alias template][]
+ - The `language` element in the [embedded RSS template][]
+ - The `locale` property in the [embedded OpenGraph template][]
+
+ > [!note]
+ > This value does not affect localization of dates, numbers, and currencies, nor does it affect the site's URL structure. These are controlled by the [language key](#language-keys).
+
+ Access this value from a template using the [`Language.Locale`][] method on a `Site` or `Page` object.
+
+title
+: (`string`) The site title for this language. Access this value from a template using the [`Title`][] method on a `Site` object.
+
+weight
+: (`int`) The language [weight](g). When set to a non-zero value, this is the primary sort criteria for this language.
+
+## Sort order
+
+Hugo sorts languages by weight in ascending order, then lexicographically in ascending order. This affects build order and complement selection.
+
+## Localized settings
+
+Some configuration settings can be defined separately for each language. For example:
+
+{{< code-toggle file=hugo >}}
+[languages.en]
+label = 'English'
+locale = 'en-US'
+timeZone = 'America/New_York'
+title = 'Project Documentation'
+weight = 1
+[languages.en.pagination]
+path = 'page'
+[languages.en.params]
+subtitle = 'Reference, Tutorials, and Explanations'
+{{< /code-toggle >}}
+
+The following configuration keys can be defined separately for each language:
+
+{{< per-lang-config-keys >}}
+
+Any key not defined in a `languages` object will fall back to the global value in the root of your project configuration.
+
+## Language keys
+
+Language keys must conform to the syntax described in [RFC 5646][]. For example:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+[languages.de]
+weight = 1
+[languages.en-US]
+weight = 2
+[languages.pt-BR]
+weight = 3
+{{< /code-toggle >}}
+
+Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7][] are also supported. Omit the `art-x-` prefix from the language key. For example:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'en'
+[languages.en]
+weight = 1
+[languages.hugolang]
+weight = 2
+{{< /code-toggle >}}
+
+> [!note]
+> Private use subtags must not exceed 8 alphanumeric characters.
+
+## Example
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = true
+disableDefaultLanguageRedirect = false
+
+[languages.de]
+contentDir = 'content/de'
+direction = 'ltr'
+disabled = false
+label = 'Deutsch'
+locale = 'de-DE'
+title = 'Projekt Dokumentation'
+weight = 1
+
+[languages.de.params]
+subtitle = 'Referenz, Tutorials und Erklärungen'
+
+[languages.en]
+contentDir = 'content/en'
+direction = 'ltr'
+disabled = false
+label = 'English'
+locale = 'en-US'
+title = 'Project Documentation'
+weight = 2
+
+[languages.en.params]
+subtitle = 'Reference, Tutorials, and Explanations'
+{{< /code-toggle >}}
+
+> [!note]
+> In the example above, omit `contentDir` if [translating by file name][].
+
+## Multihost
+
+Hugo supports multiple languages in a multihost configuration. This means you can configure a `baseURL` per `language`.
+
+> [!note]
+> If you define a `baseURL` for one language, you must define a unique `baseURL` for all languages.
+
+For example:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'fr'
+[languages.en]
+baseURL = 'https://en.example.org/'
+label = 'English'
+title = 'In English'
+weight = 2
+[languages.fr]
+baseURL = 'https://fr.example.org'
+label = 'Français'
+title = 'En Français'
+weight = 1
+{{</ code-toggle >}}
+
+With the above, Hugo publishes two sites, each with their own root:
+
+```text
+public
+├── en
+└── fr
+```
+
+[RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7
+[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
+[`Language.Direction`]: /methods/site/language/#direction
+[`Language.Label`]: /methods/site/language/#label
+[`Language.Locale`]: /methods/site/language/#locale
+[`Title`]: /methods/site/title/
+[`defaultContentLanguageInSubdir`]: #defaultcontentlanguageinsubdir
+[`defaultContentLanguage`]: #defaultcontentlanguage
+[`dir`]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir
+[`disableDefaultSiteRedirect`]: /configuration/all/#disabledefaultsiteredirect
+[`language.Translate`]: /functions/lang/translate/
+[embedded OpenGraph template]: <{{% eturl opengraph %}}>
+[embedded RSS template]: <{{% eturl rss %}}>
+[embedded alias template]: <{{% eturl alias %}}>
+[language keys]: #language-keys
+[translating by file name]: /content-management/multilingual/#translation-by-file-name
diff --git a/documents/markdown/hugo-docs/en_configuration_markup.md b/documents/markdown/hugo-docs/en_configuration_markup.md
new file mode 100644
index 0000000..087086e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_markup.md
@@ -0,0 +1,365 @@
+---
+title: Configure markup
+linkTitle: Markup
+description: Configure markup.
+categories: []
+keywords: []
+aliases: [/getting-started/configuration-markup/]
+---
+
+## Default handler
+
+In its default configuration, Hugo uses [Goldmark] to render Markdown to HTML.
+
+{{< code-toggle file=hugo >}}
+[markup]
+defaultMarkdownHandler = 'goldmark'
+{{< /code-toggle >}}
+
+Files with ending with `.md`, `.mdown`, or `.markdown` are processed as Markdown, unless you've explicitly set a different format using the `markup` field in your front matter.
+
+To use a different renderer for Markdown files, specify one of `asciidocext`, `org`, `pandoc`, or `rst` in your project configuration.
+
+`defaultMarkdownHandler`|Renderer
+:--|:--
+`asciidocext`|[AsciiDoc]
+`goldmark`|[Goldmark]
+`org`|[Emacs Org Mode]
+`pandoc`|[Pandoc]
+`rst`|[reStructuredText]
+
+To use AsciiDoc, Pandoc, or reStructuredText you must install the relevant renderer and update your [security policy].
+
+> [!note]
+> Unless you need a unique capability provided by one of the alternative Markdown handlers, we strongly recommend that you use the default setting. Goldmark is fast, well maintained, conforms to the [CommonMark] specification, and is compatible with [GitHub Flavored Markdown] (GFM).
+
+## Goldmark
+
+This is the default configuration for the Goldmark Markdown renderer:
+
+{{< code-toggle config=markup.goldmark />}}
+
+### Extensions
+
+The extensions below, excluding Extras and Passthrough, are enabled by default.
+
+Extension|Documentation|Enabled
+:--|:--|:-:
+`cjk`|[Goldmark Extensions: CJK]|:heavy_check_mark:
+`definitionList`|[PHP Markdown Extra: Definition lists]|:heavy_check_mark:
+`extras`|[Hugo Goldmark Extensions: Extras]|
+`footnote`|[PHP Markdown Extra: Footnotes]|:heavy_check_mark:
+`linkify`|[GitHub Flavored Markdown: Autolinks]|:heavy_check_mark:
+`passthrough`|[Hugo Goldmark Extensions: Passthrough]|
+`strikethrough`|[GitHub Flavored Markdown: Strikethrough]|:heavy_check_mark:
+`table`|[GitHub Flavored Markdown: Tables]|:heavy_check_mark:
+`taskList`|[GitHub Flavored Markdown: Task list items]|:heavy_check_mark:
+`typographer`|[Goldmark Extensions: Typographer]|:heavy_check_mark:
+
+#### Extras
+
+Enable [deleted text], [inserted text], [mark text], [subscript], and [superscript] elements in Markdown.
+
+Element|Markdown|Rendered
+:--|:--|:--
+Deleted text|`~~foo~~`|`<del>foo</del>`
+Inserted text|`++bar++`|`<ins>bar</ins>`
+Mark text|`==baz==`|`<mark>baz</mark>`
+Subscript|`H~2~O`|`H<sub>2</sub>O`
+Superscript|`1^st^`|`1<sup>st</sup>`
+
+To avoid a conflict[^1], if you enable the "subscript" feature of the Extras extension, you must disable the Strikethrough extension:
+
+[^1]: See [details](https://github.com/gohugoio/hugo-goldmark-extensions/commit/4d4fcd022fe45a9b51483df001c9e5f4e632d5a9).
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.extensions]
+strikethrough = false
+
+[markup.goldmark.extensions.extras.subscript]
+enable = true
+{{< /code-toggle >}}
+
+If you still need to show deleted text after disabling the Strikethrough extension, enable the "deleted text" feature of the Extras extension:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.extensions]
+strikethrough = false
+
+[markup.goldmark.extensions.extras.delete]
+enable = true
+{{< /code-toggle >}}
+
+With this configuration, to format text as deleted, wrap it with double-tildes.
+
+#### Footnote
+
+Enabled by default, the Footnote extension enables inclusion of footnotes in Markdown.
+
+enable
+: {{< new-in 0.151.0 />}}
+: (`bool`) Whether to enable the Footnotes extension. Default is `true`.
+
+backlinkHTML
+: {{< new-in 0.151.0 />}}
+: (`string`) The HTML to be displayed at the end of a footnote that links the user back to the corresponding reference in the main text. The default is ↩︎ (a return arrow symbol).
+
+enableAutoIDPrefix
+: {{< new-in 0.151.0 />}}
+: (`bool`) Whether to prepend a unique prefix to footnote IDs, preventing clashes when multiple documents are rendered together. This prefix is unique to each logical path, which means that the prefix is not unique across content dimensions such as language. Default is `false`.
+
+#### Passthrough
+
+Enable the Passthrough extension to include mathematical equations and expressions in Markdown using LaTeX markup. See [mathematics in Markdown] for details.
+
+#### Typographer
+
+The Typographer extension replaces certain character combinations with HTML entities as specified below:
+
+Markdown|Replaced by|Description
+:--|:--|:--
+`...`|`…`|horizontal ellipsis
+`'`|`’`|apostrophe
+`--`|`–`|en dash
+`---`|`—`|em dash
+`«`|`«`|left angle quote
+`“`|`“`|left double quote
+`‘`|`‘`|left single quote
+`»`|`»`|right angle quote
+`”`|`”`|right double quote
+`’`|`’`|right single quote
+
+### Goldmark settings explained
+
+Most of the Goldmark settings above are self-explanatory, but some require explanation.
+
+duplicateResourceFiles
+: (`bool`) Whether to duplicate shared page resources for each language on multilingual single-host projects. See [multilingual page resources] for details. Default is `false`.
+
+ > [!note]
+ > With multilingual single-host projects, setting this parameter to `false` will enable Hugo's [embedded link render hook] and [embedded image render hook]. This is the default configuration for multilingual single-host projects.
+
+parser.wrapStandAloneImageWithinParagraph
+: (`bool`) Whether to wrap image elements without adjacent content within a `p` element when rendered. This is the default Markdown behavior. Set to `false` when using an [image render hook] to render standalone images as `figure` elements. Default is `true`.
+
+parser.autoDefinitionTermID
+: {{< new-in 0.144.0 />}}
+: (`bool`) Whether to automatically add `id` attributes to description list terms (i.e., `dt` elements). When `true`, the `id` attribute of each `dt` element is accessible through the [`Fragments.Identifiers`] method on a `Page` object.
+
+parser.autoHeadingID
+: (`bool`) Whether to automatically add `id` attributes to headings (i.e., `h1`, `h2`, `h3`, `h4`, `h5`, and `h6` elements).
+
+parser.autoIDType
+: (`string`) The strategy used to automatically generate `id` attributes, one of `github`, `github-ascii` or `blackfriday`. Default is `github`.
+
+ - `github`: Generate GitHub-compatible `id` attributes
+ - `github-ascii`: Drop any non-ASCII characters after accent normalization
+ - `blackfriday`: Generate `id` attributes compatible with the Blackfriday Markdown renderer
+
+ This is also the strategy used by the [anchorize] template function.
+
+parser.attribute.block
+: (`bool`) Whether to enable [Markdown attributes] for block elements. Default is `false`.
+
+parser.attribute.title
+: (`bool`) Whether to enable [Markdown attributes] for headings. Default is `true`.
+
+<!-- TODO: delete this on or after July 1, 2027. -->
+renderHooks.image.enableDefault
+: Deprecated in v0.148.0. Use `renderHooks.image.useEmbedded` instead.
+
+renderHooks.image.useEmbedded
+: {{< new-in 0.148.0 />}}
+: (`string`) When to use the [embedded image render hook]. One of `auto`, `never`, `always`, or `fallback`. Default is `auto`.
+
+ - `auto`: Use the embedded image render hook only for multilingual single-host projects where the [duplication of shared page resources] feature is disabled. If custom image render hooks are defined by your project, modules, or themes, these will be used instead.
+ - `never`: Never use the embedded image render hook. If custom image render hooks are defined by your project, modules, or themes, these will be used instead.
+ - `always`: Always use the embedded image render hook, even if custom image render hooks are provided by your project, modules, or themes.
+ - `fallback`: Use the embedded image render hook only if custom image render hooks are not provided by your project, modules, or themes. If custom image render hooks exist, these will be used instead.
+
+<!-- TODO: delete this on or after July 1, 2027. -->
+renderHooks.link.enableDefault
+: Deprecated in v0.148.0. Use `renderHooks.link.useEmbedded` instead.
+
+renderHooks.link.useEmbedded
+: (`string`) When to use the [embedded link render hook]. One of `auto`, `never`, `always`, or `fallback`. Default is `auto`.
+
+ - `auto`: Use the embedded link render hook only for multilingual single-host projects where the [duplication of shared page resources] feature is disabled. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
+ - `never`: Never use the embedded link render hook. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
+ - `always`: Always use the embedded link render hook, even if custom link render hooks are provided by your project, modules, or themes.
+ - `fallback`: Use the embedded link render hook only if custom link render hooks are not provided by your project, modules, or themes. If custom link render hooks exist, these will be used instead.
+
+renderer.hardWraps
+: (`bool`) Whether to replace newline characters within a paragraph with `br` elements. Default is `false`.
+
+renderer.unsafe
+: (`bool`) Whether to render raw HTML mixed within Markdown. This is unsafe unless the content is under your control. Default is `false`.
+
+## AsciiDoc
+
+This is the default configuration for the AsciiDoc renderer:
+
+{{< code-toggle config=markup.asciidocExt />}}
+
+### AsciiDoc settings explained
+
+attributes
+: (`map`) A map of key-value pairs, each a document attribute. See Asciidoctor's [attributes].
+
+backend
+: (`string`) The backend output file format. Default is `html5`.
+
+extensions
+: (`[]string`) An array of enabled extensions, such as `asciidoctor-html5s`, `asciidoctor-bibtex`, or `asciidoctor-diagram`.
+
+ > [!note]
+ > To mitigate security risks, entries in the extension array may not contain forward slashes (`/`), backslashes (`\`), or periods. Due to this restriction, extensions must be in Ruby's `$LOAD_PATH`.
+
+failureLevel
+: (`string`) The minimum logging level that triggers a non-zero exit code (failure). Default is `fatal`.
+
+noHeaderOrFooter
+: (`bool`) Whether to output an embeddable document, which excludes the header, the footer, and everything outside the body of the document. Default is `true`.
+
+preserveTOC
+: (`bool`) Whether to preserve the table of contents (TOC) rendered by Asciidoctor. By default, to make the TOC compatible with existing themes, Hugo removes the TOC rendered by Asciidoctor. To render the TOC, use the [`TableOfContents`] method on a `Page` object in your templates. Default is `false`.
+
+safeMode
+: (`string`) The safe mode level, one of `unsafe`, `safe`, `server`, or `secure`. Default is `unsafe`.
+
+sectionNumbers
+: (`bool`) Whether to number each section title. Default is `false`.
+
+trace
+: (`bool`) Whether to include backtrace information on errors. Default is `false`.
+
+verbose
+: (`bool`) Whether to verbosely print processing information and configuration file checks to stderr. Default is `false`.
+
+workingFolderCurrent
+: (`bool`) Whether to set the working directory to be the same as that of the AsciiDoc file being processed, allowing [includes] to work with relative paths. Set to `true` to render diagrams with the [asciidoctor-diagram] extension. Default is `false`.
+
+### Configuration example
+
+{{< code-toggle file=hugo >}}
+[markup.asciidocExt]
+extensions = ['asciidoctor-html5s','asciidoctor-diagram']
+workingFolderCurrent = true
+[markup.asciidocExt.attributes]
+my-base-url = 'https://example.com/'
+my-attribute-name = 'my value'
+{{< /code-toggle >}}
+
+### Syntax highlighting
+
+Follow the steps below to enable syntax highlighting.
+
+Step 1
+: Set the `source-highlighter` attribute in your project configuration. For example:
+
+ {{< code-toggle file=hugo >}}
+ [markup.asciidocExt.attributes]
+ source-highlighter = 'rouge'
+ {{< /code-toggle >}}
+
+Step 2
+: Generate the highlighter CSS. For example:
+
+ ```text
+ rougify style monokai.sublime > assets/css/syntax.css
+ ```
+
+Step 3
+: In your base template add a link to the CSS file:
+
+ ```go-html-template {file="layouts/baseof.html"}
+ <head>
+ ...
+ {{ with resources.Get "css/syntax.css" }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
+ ...
+ </head>
+ ```
+
+Step 4
+: Add the code to be highlighted to your markup:
+
+ ```text
+ [#hello,ruby]
+ ----
+ require 'sinatra'
+
+ get '/hi' do
+ "Hello World!"
+ end
+ ----
+ ```
+
+### Troubleshooting
+
+Run `hugo build --logLevel debug` to examine Hugo's call to the Asciidoctor executable:
+
+```txt
+INFO 2019/12/22 09:08:48 Rendering book-as-pdf.adoc with C:\Ruby26-x64\bin\asciidoctor.bat using asciidoc args [--no-header-footer -r asciidoctor-html5s -b html5s -r asciidoctor-diagram --base-dir D:\prototypes\hugo_asciidoc_ddd\docs -a outdir=D:\prototypes\hugo_asciidoc_ddd\build -] ...
+```
+
+## Highlight
+
+This is the default configuration.
+
+{{< code-toggle config=markup.highlight />}}
+
+{{% include "/_common/syntax-highlighting-options.md" %}}
+
+## Table of contents
+
+This is the default configuration for the table of contents, applicable to Goldmark and Asciidoctor:
+
+{{< code-toggle config=markup.tableOfContents />}}
+
+startLevel
+: (`int`) Heading levels less than this value will be excluded from the table of contents. For example, to exclude `h1` elements from the table of contents, set this value to `2`. Default is `2`.
+
+endLevel
+: (`int`) Heading levels greater than this value will be excluded from the table of contents. For example, to exclude `h4`, `h5`, and `h6` elements from the table of contents, set this value to `3`. Default is `3`.
+
+ordered
+: (`bool`) Whether to generates an ordered list instead of an unordered list. Default is `false`.
+
+[`Fragments.Identifiers`]: /methods/page/fragments/#identifiers
+[`TableOfContents`]: /methods/page/tableofcontents/
+[anchorize]: /functions/urls/anchorize
+[AsciiDoc]: https://asciidoc.org/
+[asciidoctor-diagram]: https://asciidoctor.org/docs/asciidoctor-diagram/
+[attributes]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions
+[CommonMark]: https://spec.commonmark.org/current/
+[deleted text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/del
+[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
+[Emacs Org Mode]: https://orgmode.org/
+[embedded image render hook]: /render-hooks/images/#embedded
+[embedded link render hook]: /render-hooks/links/#embedded
+[GitHub Flavored Markdown: Autolinks]: https://github.github.com/gfm/#autolinks-extension-
+[GitHub Flavored Markdown: Strikethrough]: https://github.github.com/gfm/#strikethrough-extension-
+[GitHub Flavored Markdown: Tables]: https://github.github.com/gfm/#tables-extension-
+[GitHub Flavored Markdown: Task list items]: https://github.github.com/gfm/#task-list-items-extension-
+[GitHub Flavored Markdown]: https://github.github.com/gfm/
+[Goldmark Extensions: CJK]: https://github.com/yuin/goldmark?tab=readme-ov-file#cjk-extension
+[Goldmark Extensions: Typographer]: https://github.com/yuin/goldmark?tab=readme-ov-file#typographer-extension
+[Goldmark]: https://github.com/yuin/goldmark/
+[Hugo Goldmark Extensions: Extras]: https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#extras-extension
+[Hugo Goldmark Extensions: Passthrough]: https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#passthrough-extension
+[image render hook]: /render-hooks/images/
+[includes]: https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#includes
+[inserted text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ins
+[mark text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark
+[Markdown attributes]: /content-management/markdown-attributes/
+[mathematics in Markdown]: content-management/mathematics/
+[multilingual page resources]: /content-management/page-resources/#multilingual
+[Pandoc]: https://pandoc.org/
+[PHP Markdown Extra: Definition lists]: https://michelf.ca/projects/php-markdown/extra/#def-list
+[PHP Markdown Extra: Footnotes]: https://michelf.ca/projects/php-markdown/extra/#footnotes
+[reStructuredText]: https://docutils.sourceforge.io/rst.html
+[security policy]: /configuration/security/
+[subscript]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sub
+[superscript]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sup
diff --git a/documents/markdown/hugo-docs/en_configuration_media-types.md b/documents/markdown/hugo-docs/en_configuration_media-types.md
new file mode 100644
index 0000000..82296fb
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_media-types.md
@@ -0,0 +1,82 @@
+---
+title: Configure media types
+linkTitle: Media types
+description: Configure media types.
+categories: []
+keywords: []
+---
+
+{{% glossary-term "media type" %}}
+
+Configured media types serve multiple purposes in Hugo, including the definition of [output formats](g). This is the default media type configuration in tabular form:
+
+{{< datatable "config" "mediaTypes" "_key" "suffixes" >}}
+
+The `suffixes` column in the table above shows the suffixes associated with each media type. For example, Hugo associates `.html` and `.htm` files with the `text/html` media type.
+
+> [!note]
+> The first suffix is the primary suffix. Use the primary suffix when naming template files. For example, when creating a template for an RSS feed, use the `xml` suffix.
+
+## Default configuration
+
+The following is the default configuration that matches the table above:
+
+{{< code-toggle file=hugo config=mediaTypes />}}
+
+delimiter
+: (`string`) The delimiter between the file name and the suffix. The delimiter, in conjunction with the suffix, forms the file extension. Default is `"."`.
+
+suffixes
+: (`[]string`) The suffixes associated with this media type. The first suffix is the primary suffix.
+
+## Modify a media type
+
+You can modify any of the default media types. For example, to switch the primary suffix for `text/html` from `html` to `htm`:
+
+{{< code-toggle file=hugo >}}
+[mediaTypes.'text/html']
+suffixes = ['htm','html']
+{{< /code-toggle >}}
+
+If you alter a default media type, you must also explicitly redefine all output formats that utilize that media type. For example, to ensure the changes above affect the `html` output format, redefine the `html` output format:
+
+{{< code-toggle file=hugo >}}
+[outputFormats.html]
+mediaType = 'text/html'
+{{< /code-toggle >}}
+
+## Create a media type
+
+You can create new media types as needed. For example, to create a media type for an Atom feed:
+
+{{< code-toggle file=hugo >}}
+[mediaTypes.'application/atom+xml']
+suffixes = ['atom']
+{{< /code-toggle >}}
+
+## Media types without suffixes
+
+Occasionally, you may need to create a media type without a suffix or delimiter. For example, [Netlify] recognizes configuration files named `_redirects` and `_headers`, which Hugo can generate using custom [output formats](g).
+
+To support these custom output formats, register a custom media type with no suffix or delimiter:
+
+{{< code-toggle file=hugo >}}
+[mediaTypes.'text/netlify']
+delimiter = ''
+{{< /code-toggle >}}
+
+The custom output format definitions would look something like this:
+
+{{< code-toggle file=hugo >}}
+[outputFormats.redir]
+baseName = '_redirects'
+isPlainText = true
+mediatype = 'text/netlify'
+[outputFormats.headers]
+baseName = '_headers'
+isPlainText = true
+mediatype = 'text/netlify'
+notAlternative = true
+{{< /code-toggle >}}
+
+[Netlify]: https://www.netlify.com/
diff --git a/documents/markdown/hugo-docs/en_configuration_menus.md b/documents/markdown/hugo-docs/en_configuration_menus.md
new file mode 100644
index 0000000..6eae4f2
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_menus.md
@@ -0,0 +1,137 @@
+---
+title: Configure menus
+linkTitle: Menus
+description: Centrally define menu entries for one or more menus.
+categories: []
+keywords: []
+---
+
+> [!note]
+> To understand Hugo's menu system, please refer to the [menus] page.
+
+There are three ways to define menu entries:
+
+1. [Automatically]
+1. In [front matter]
+1. In your project configuration
+
+This page covers the project configuration method.
+
+## Example
+
+To define entries for a "main" menu:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+name = 'Home'
+pageRef = '/'
+weight = 10
+
+[[menus.main]]
+name = 'Products'
+pageRef = '/products'
+weight = 20
+
+[[menus.main]]
+name = 'Services'
+pageRef = '/services'
+weight = 30
+{{< /code-toggle >}}
+
+This creates a menu structure that you can access with [`Menus`] method on a `Site` object:
+
+```go-html-template
+{{ range .Site.Menus.main }}
+ ...
+{{ end }}
+```
+
+See [menu templates] for a detailed example.
+
+To define entries for a "footer" menu:
+
+{{< code-toggle file=hugo >}}
+[[menus.footer]]
+name = 'Terms'
+pageRef = '/terms'
+weight = 10
+
+[[menus.footer]]
+name = 'Privacy'
+pageRef = '/privacy'
+weight = 20
+{{< /code-toggle >}}
+
+Access this menu structure in the same way:
+
+```go-html-template
+{{ range .Site.Menus.footer }}
+ ...
+{{ end }}
+```
+
+## Properties
+
+Menu entries usually include at least three properties: `name`, `weight`, and either `pageRef` or `url`. Use `pageRef` for internal page destinations and `url` for external destinations.
+
+These are the available menu entry properties:
+
+{{% include "/_common/menu-entry-properties.md" %}}
+
+pageRef
+: (`string`) The [logical path](g) of the target page. For example:
+
+ page kind|pageRef
+ :--|:--
+ home|`/`
+ page|`/books/book-1`
+ section|`/books`
+ taxonomy|`/tags`
+ term|`/tags/foo`
+
+url
+: (`string`) The destination URL. Use this for external destinations only.
+
+## Nested menu
+
+This nested menu demonstrates some of the available properties:
+
+<!-- markdownlint-disable MD033 -->
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+name = 'Products'
+pageRef = '/products'
+weight = 10
+
+[[menus.main]]
+name = 'Hardware'
+pageRef = '/products/hardware'
+parent = 'Products'
+weight = 1
+
+[[menus.main]]
+name = 'Software'
+pageRef = '/products/software'
+parent = 'Products'
+weight = 2
+
+[[menus.main]]
+name = 'Services'
+pageRef = '/services'
+weight = 20
+
+[[menus.main]]
+name = 'Hugo'
+pre = '<i class="fa fa-heart"></i>'
+url = 'https://gohugo.io/'
+weight = 30
+[menus.main.params]
+rel = 'external'
+{{< /code-toggle >}}
+<!-- markdownlint-enable MD033 -->
+
+[`Menus`]: /methods/site/menus/
+[Automatically]: /content-management/menus/#define-automatically
+[front matter]: /content-management/menus/#define-in-front-matter
+[menu templates]: /templates/menu/
+[menus]: /content-management/menus/
diff --git a/documents/markdown/hugo-docs/en_configuration_minify.md b/documents/markdown/hugo-docs/en_configuration_minify.md
new file mode 100644
index 0000000..9329879
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_minify.md
@@ -0,0 +1,18 @@
+---
+title: Configure minify
+linkTitle: Minify
+description: Configure minify.
+categories: []
+keywords: []
+---
+
+This is the default configuration:
+
+{{< code-toggle config=minify />}}
+
+See the [`tdewolff/minify`][] project page for details, but note the following:
+
+- `css.inline` is for internal use. Changing this setting has no effect.
+- `html.keepConditionalComments` has been deprecated. Use `html.keepSpecialComments` instead.
+
+[`tdewolff/minify`]: https://github.com/tdewolff/minify
diff --git a/documents/markdown/hugo-docs/en_configuration_module.md b/documents/markdown/hugo-docs/en_configuration_module.md
new file mode 100644
index 0000000..56980b0
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_module.md
@@ -0,0 +1,193 @@
+---
+title: Configure modules
+linkTitle: Modules
+description: Configure modules.
+categories: []
+keywords: []
+aliases: [/hugo-modules/configuration/]
+---
+
+{{% include "/_common/gomodules-info.md" %}}
+
+## Top-level options
+
+This is the default configuration:
+
+<!-- markdownlint-disable MD049 -->
+{{< code-toggle file=hugo >}}
+[module]
+noProxy = 'none'
+noVendor = ''
+private = '*.*'
+proxy = 'direct'
+vendorClosest = false
+workspace = 'off'
+{{< /code-toggle >}}
+<!-- markdownlint-enable MD049 -->
+
+auth
+: {{< new-in 0.144.0 />}}
+: (`string`) Configures `GOAUTH` when running the Go command for module operations. This is a semicolon-separated list of authentication commands for go-import and HTTPS module mirror interactions. This is useful for private repositories. See `go help goauth` for more information.
+
+noProxy
+: (`string`) A comma-separated list of [glob patterns](g), matching paths that should not use the [configured proxy server](#proxy).
+
+noVendor
+: (`string`) A [glob pattern](g) matching module paths to skip when vendoring.
+
+private
+: (`string`) A comma-separated list of [glob patterns](g), matching paths that should be treated as private.
+
+proxy
+: (`string`) The proxy server to use to download remote modules. Default is `direct`, which means `git clone` and similar.
+
+replacements
+: (`string`) Primarily useful for local module development, a comma-separated list of mappings from module paths to directories. Paths may be absolute or relative to the [`themesDir`][].
+
+ {{< code-toggle file=hugo >}}
+ [module]
+ replacements = 'github.com/bep/my-theme -> ../..,github.com/bep/shortcodes -> /some/path'
+ {{< /code-toggle >}}
+
+vendorClosest
+: (`bool`) Whether to pick the vendored module closest to the module using it. The default behavior is to pick the first. Note that there can still be only one dependency of a given module path, so once it is in use it cannot be redefined. Default is `false`.
+
+workspace
+: (`string`) The Go workspace file to use, either as an absolute path or a path relative to the current working directory. Enabling this activates Go workspace mode and requires Go 1.18 or later. The default is `off`.
+
+You may also use environment variables to set any of the above. For example:
+
+```sh
+export HUGO_MODULE_PROXY="https://proxy.example.org"
+export HUGO_MODULE_REPLACEMENTS="github.com/bep/my-theme -> ../.."
+export HUGO_MODULE_WORKSPACE="/my/hugo.work"
+```
+
+## Hugo version
+
+You can specify a required Hugo version for your module in the `module` section. Users will then receive a warning if their Hugo version is incompatible.
+
+This is the default configuration:
+
+{{< code-toggle config=module.hugoVersion />}}
+
+You can omit any of the settings above.
+
+extended
+: (`bool`) Whether the extended edition of Hugo is required, satisfied by installing either the extended or extended/deploy edition.
+
+ > [!note]
+ > The extended version check is disabled in v0.153.2 and later.
+ >
+ > Historically, certain features—specifically WebP encoding and LibSass—required the Hugo Extended binary. However, as of v0.153.0:
+ >
+ > - WebP encoding is now supported in all Hugo editions.
+ > - LibSass has been deprecated in favor of [Dart Sass][], which is compatible with any Hugo edition.
+ >
+ > Because these dependencies no longer require a specialized binary, the internal enforcement check for the extended version has been removed. Site and theme authors are encouraged to use Dart Sass to ensure cross-edition compatibility.
+
+max
+: (`string`) The maximum Hugo version supported, for example `0.153.0`.
+
+min
+: (`string`) The minimum Hugo version supported, for example `0.102.0`.
+
+## Imports
+
+{{< code-toggle file=hugo >}}
+[[module.imports]]
+disable = false
+ignoreConfig = false
+ignoreImports = false
+path = 'github.com/gohugoio/hugoTestModules1_linux/modh1_2_1v'
+[[module.imports]]
+path = 'my-shortcodes'
+{{< /code-toggle >}}
+
+disable
+: (`bool`) Whether to disable the module but keep version information in the `go.*` files. Default is `false`.
+
+ignoreConfig
+: (`bool`) Whether to ignore module configuration files, for example, `hugo.toml`. This will also prevent loading of any transitive module dependencies. Default is `false`.
+
+ignoreImports
+: (`bool`) Whether to ignore module imports. Default is `false`.
+
+noMounts
+: (`bool`) Whether to disable directory mounting for this import. Default is `false`.
+
+noVendor
+: (`bool`) Whether to disable vendoring for this import. This setting is restricted to the main project. Default is `false`.
+
+usePackageJSON
+: {{< new-in 0.159.0 />}}
+: (`string`) Whether to use the import's npm dependencies in [hugo mod npm pack](commands/hugo_mod_npm_pack/). One of `auto` (default), `always` or `never`. When set to `auto`, Hugo will enable this if either there is a Hugo config file (e.g. `hugo.toml`) or a `package.hugo.json` file in the module root.
+
+path
+: (`string`) The module path, either a valid Go module path (e.g., `github.com/gohugoio/myShortcodes`) or the directory name if stored in the [`themesDir`][].
+
+version
+: {{< new-in 0.150.0 />}}
+: If set to a [version query](https://go.dev/ref/mod#version-queries), this import becomes a direct dependency, in contrast to dependencies managed by Go Modules. See [this issue](https://github.com/gohugoio/hugo/pull/13966) for more information.
+
+## Mounts
+
+{{% glossary-term mount %}}
+
+> [!important]
+> If you define one or more mounts to map a file system path to a component path, do not use these legacy configuration settings: [`archetypeDir`][], [`assetDir`][], [`contentDir`][], [`dataDir`][], [`i18nDir`][], [`layoutDir`][], or [`staticDir`][].
+
+### Default mounts
+
+Within a project, if you define a mount to map a file system path to a component path, the corresponding default mount for that component will be removed. This action essentially overwrites the standard, automatic mapping for that specific component with your custom one.
+
+Within a module, if you define a mount to map a file system path to a component path, all of the default mounts will be removed. Defining a mount at the module level is a more sweeping change, causing all default mappings within that module to be discarded.
+
+In either case, if you still need one of the default mounts, you must explicitly add it along with the new mount. Because custom mounts override defaults, any necessary default mappings must be re-added manually after you introduce your custom configuration.
+
+These are the default mounts:
+
+{{< code-toggle config=module.mounts />}}
+
+source
+: (`string`) The source directory of the mount. For the main project, this can be either project-relative or absolute. For other modules it must be project-relative.
+
+target
+: (`string`) Where the mount will reside within Hugo's [unified file system](g). It must begin with one of Hugo's [component](g) directories: archetypes, assets, content, data, i18n, layouts, or static. For example, content/blog.
+
+disableWatch
+: (`bool`) Whether to disable watching in watch mode for this mount. Default is `false`.
+
+files
+: {{< new-in 0.153.0 />}}
+: (`[]string`) A [glob slice](g) defining the files to include or exclude.
+
+sites
+: {{< new-in 0.153.0 />}}
+: (`map`) A map to define [sites matrix](g) and [sites complements](g) for the mount. Relevant for `content` and `layouts` mounts, and `static` mounts when in multihost mode. For `static` and `layouts`, only the `matrix` keyword is supported.
+
+### Example
+
+{{< code-toggle file=hugo >}}
+[module]
+[[module.mounts]]
+source = 'content'
+target = 'content'
+files = ['! docs/*']
+[[module.mounts]]
+source = 'node_modules'
+target = 'assets'
+[[module.mounts]]
+source = 'assets'
+target = 'assets'
+{{< /code-toggle >}}
+
+[`archetypeDir`]: /configuration/all/#archetypedir
+[`assetDir`]: /configuration/all/#assetdir
+[`contentDir`]: /configuration/all/#contentdir
+[`dataDir`]: /configuration/all/#datadir
+[`i18nDir`]: /configuration/all/#i18ndir
+[`layoutDir`]: /configuration/all/#layoutdir
+[`staticDir`]: /configuration/all/#staticdir
+[`themesDir`]: /configuration/all/#themesdir
+[Dart Sass]: /functions/css/sass/#dart-sass
diff --git a/documents/markdown/hugo-docs/en_configuration_output-formats.md b/documents/markdown/hugo-docs/en_configuration_output-formats.md
new file mode 100644
index 0000000..2ddb273
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_output-formats.md
@@ -0,0 +1,207 @@
+---
+title: Configure output formats
+linkTitle: Output formats
+description: Configure output formats.
+categories: []
+keywords: []
+---
+
+{{% glossary-term "output format" %}}
+
+You can output a page in as many formats as you want. Define an infinite number of output formats, provided they each resolve to a unique file system path.
+
+This is the default output format configuration in tabular form:
+
+{{< datatable
+ "config"
+ "outputFormats"
+ "_key"
+ "mediaType"
+ "weight"
+ "baseName"
+ "isHTML"
+ "isPlainText"
+ "noUgly"
+ "notAlternative"
+ "path"
+ "permalinkable"
+ "protocol"
+ "rel"
+ "root"
+ "ugly"
+>}}
+
+## Default configuration
+
+The following is the default configuration that matches the table above:
+
+{{< code-toggle config=outputFormats />}}
+
+baseName
+: (`string`) The base name of the published file. Default is `index`.
+
+isHTML
+: (`bool`) Whether to classify the output format as HTML. This value determines when the LiveReload script is injected and, in conjunction with [`permalinkable`](#permalinkable), whether [alias redirects][] are generated. Default is `false`.
+
+isPlainText
+: (`bool`) Whether to parse templates for this output format with Go's [`text/template`][] package instead of the [`html/template`][] package. Default is `false`.
+
+mediaType
+: (`string`) The [media type](g) of the published file. This must match one of the [configured media types][].
+
+notAlternative
+: (`bool`) Whether to exclude this output format from the values returned by the [`AlternativeOutputFormats`][] method on a `Page` object. Default is `false`.
+
+noUgly
+: (`bool`) Whether to disable ugly URLs for this output format when [`uglyURLs`][] are enabled in your project configuration. Default is `false`.
+
+path
+: (`string`) The first segment of the publication path for this output format. This path segment is relative to the root of your [`publishDir`][]. If omitted, Hugo will use the file's original content path for publishing.
+
+permalinkable
+: (`bool`) Whether to return the rendering output format rather than the main output format when invoking the [`Permalink`][] and [`RelPermalink`][] methods on a `Page` object. Along with [`isHTML`](#ishtml), this must be `true` to create [alias redirects][]. Enabled by default for the `html` and `amp` output formats. Default is `false`.
+
+protocol
+: (`string`) The protocol (scheme) of the URL for this output format. For example, `https://` or `webcal://`. Default is the scheme of the [`baseURL`][] parameter in your project configuration, typically `https://`.
+
+rel
+: (`string`) The relationship of the output format to the current page. Hugo uses this property to determine the [canonical output format](g) of the current page. For the predefined `html` output format, the default value is `canonical`; for all other predefined output formats, the default value is `alternate`.
+
+root
+: (`bool`) Whether to publish files to the root of the publish directory. Default is `false`.
+
+ugly
+: (`bool`) Whether to enable uglyURLs for this output format when `uglyURLs` is `false` in your project configuration. Default is `false`.
+
+weight
+: (`int`) When set to a non-zero value, Hugo uses the `weight` as the first criteria when sorting output formats, falling back to the name of the output format. Lighter items float to the top, while heavier items sink to the bottom. Hugo renders output formats sequentially based on the sort order. Default is `0`, except for the `html` output format, which has a default weight of `10`.
+
+## Modify an output format
+
+You can modify any of the default output formats. For example, to prioritize `json` rendering over `html` rendering, when both are generated, adjust the [`weight`](#weight):
+
+{{< code-toggle file=hugo >}}
+[outputFormats.json]
+weight = 1
+[outputFormats.html]
+weight = 2
+{{< /code-toggle >}}
+
+The example above shows that when you modify a default content format, you only need to define the properties that differ from their default values.
+
+## Create an output format
+
+You can create new output formats as needed. For example, you may wish to create an output format to support Atom feeds.
+
+Step 1
+: Output formats require a specified media type. Because Atom feeds use `application/atom+xml`, which is not one of the [default media types][], you must create it first.
+
+ {{< code-toggle file=hugo >}}
+ [mediaTypes.'application/atom+xml']
+ suffixes = ['atom']
+ {{< /code-toggle >}}
+
+ See [configure media types][] for more information.
+
+Step 2
+: Create a new output format:
+
+ {{< code-toggle file=hugo >}}
+ [outputFormats.atom]
+ mediaType = 'application/atom+xml'
+ noUgly = true
+ {{< /code-toggle >}}
+
+ Note that we use the default settings for all other output format properties.
+
+Step 3
+: Specify the page [kinds](g) for which to render this output format:
+
+ {{< code-toggle file=hugo >}}
+ [outputs]
+ home = ['html', 'rss', 'atom']
+ section = ['html', 'rss', 'atom']
+ taxonomy = ['html', 'rss', 'atom']
+ term = ['html', 'rss', 'atom']
+ {{< /code-toggle >}}
+
+ See [configure outputs][] for more information.
+
+Step 4
+: Create a template to render the output format. Since Atom feeds are lists, you need to create a list template. Consult the [template lookup order][] to find the correct template path:
+
+ ```text
+ layouts/list.atom.atom
+ ```
+
+ We leave writing the template code as an exercise for you. Aim for a result similar to the [embedded RSS template][].
+
+## List output formats
+
+To access output formats, each `Page` object provides two methods: [`OutputFormats`][] (for all formats, including the current one) and [`AlternativeOutputFormats`][]. Use `AlternativeOutputFormats` to create a link `rel` list within a `head` element, as shown below:
+
+```go-html-template
+{{ range .AlternativeOutputFormats }}
+ <link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink | safeURL }}">
+{{ end }}
+```
+
+## Link to output formats
+
+By default, a `Page` object's [`Permalink`][] and [`RelPermalink`][] methods return the URL of the [primary output format](g), typically `html`. This behavior remains consistent regardless of the template used.
+
+For example, in `page.json.json`, you'll see:
+
+```go-html-template
+{{ .RelPermalink }} → /that-page/
+{{ with .OutputFormats.Get "json" }}
+ {{ .RelPermalink }} → /that-page/index.json
+{{ end }}
+```
+
+To make these methods return the URL of the _current_ template's output format, you must set the [`permalinkable`][] setting to `true` for that format.
+
+With `permalinkable` set to true for `json` in the same `page.json.json` template:
+
+```go-html-template
+{{ .RelPermalink }} → /that-page/index.json
+{{ with .OutputFormats.Get "html" }}
+ {{ .RelPermalink }} → /that-page/
+{{ end }}
+```
+
+## Template lookup order
+
+Each output format requires a template conforming to the [template lookup order][].
+
+For the highest specificity in the template lookup order, include the page kind, output format, and suffix in the file name:
+
+```text
+[page kind].[output format].[suffix]
+```
+
+For example, for section pages:
+
+Output format|Template path
+:--|:--
+`html`|`layouts/section.html.html`
+`json`|`layouts/section.json.json`
+`rss`|`layouts/section.rss.xml`
+
+[`AlternativeOutputFormats`]: /methods/page/alternativeoutputformats/
+[`baseURL`]: /configuration/all/#baseurl
+[`OutputFormats`]: /methods/page/outputformats/
+[`Permalink`]: /methods/page/permalink/
+[`permalinkable`]: #permalinkable
+[`publishDir`]: /configuration/all/#publishdir
+[`RelPermalink`]: /methods/page/relpermalink/
+[`uglyURLs`]: /configuration/ugly-urls/
+[alias redirects]: /content-management/urls/#aliases
+[configure media types]: /configuration/media-types/
+[configure outputs]: /configuration/outputs/
+[configured media types]: /configuration/media-types/
+[default media types]: /configuration/media-types/
+[embedded RSS template]: <{{% eturl rss %}}>
+[`html/template`]: https://pkg.go.dev/html/template
+[template lookup order]: /templates/lookup-order/
+[`text/template`]: https://pkg.go.dev/text/template
diff --git a/documents/markdown/hugo-docs/en_configuration_outputs.md b/documents/markdown/hugo-docs/en_configuration_outputs.md
new file mode 100644
index 0000000..ba23f9e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_outputs.md
@@ -0,0 +1,49 @@
+---
+title: Configure outputs
+linkTitle: Outputs
+description: Configure which output formats to render for each page kind.
+categories: []
+keywords: []
+---
+
+{{% glossary-term "output format" %}}
+
+Learn more about creating and configuring output formats in the [configure output formats] section.
+
+## Outputs per page kind
+
+The following default configuration determines the output formats generated for each page kind:
+
+{{< code-toggle config=outputs />}}
+
+To render the built-in `json` output format for the `home` page kind, assuming you've already created the necessary template, add the following to your configuration:
+
+{{< code-toggle file=hugo >}}
+[outputs]
+home = ['html','rss','json']
+{{< /code-toggle >}}
+
+Notice in this example that we only specified the `home` page kind. You don't need to include entries for other page kinds unless you intend to modify their default output formats.
+
+> [!note]
+> The order of the output formats in the arrays above is important. The first element will be the _primary output format_ for that page kind, and in most cases that should be `html` as shown in the default configuration.
+>
+> The primary output format for a given page kind determines the value returned by the [`Permalink`] and [`RelPermalink`] methods on a `Page` object.
+>
+> See the [link to output formats] section for details.
+
+## Outputs per page
+
+Add output formats to a page's rendering using the `outputs` field in its front matter. For example, to include `json` in the output formats rendered for a specific page:
+
+{{< code-toggle file=content/example.md fm=true >}}
+title = 'Example'
+outputs = ['json']
+{{< /code-toggle >}}
+
+In its default configuration, Hugo will render both the `html` and `json` output formats for this page. The `outputs` field appends to, rather than replaces, the project's configured outputs.
+
+[`Permalink`]: /methods/page/permalink/
+[`RelPermalink`]: /methods/page/relpermalink/
+[configure output formats]: /configuration/output-formats/
+[link to output formats]: configuration/output-formats/#link-to-output-formats
diff --git a/documents/markdown/hugo-docs/en_configuration_page.md b/documents/markdown/hugo-docs/en_configuration_page.md
new file mode 100644
index 0000000..9012c92
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_page.md
@@ -0,0 +1,34 @@
+---
+title: Configure page
+linkTitle: Page
+description: Configure page behavior.
+categories: []
+keywords: []
+---
+
+{{< new-in 0.133.0 />}}
+
+{{% glossary-term "default sort order" %}}
+
+Hugo uses the default sort order to determine the _next_ and _previous_ page relative to the current page when calling these methods on a `Page` object:
+
+- [`Next`](/methods/page/next/) and [`Prev`](/methods/page/prev/)
+- [`NextInSection`](/methods/page/nextinsection/) and [`PrevInSection`](/methods/page/previnsection/)
+
+This is based on this default project configuration:
+
+{{< code-toggle config=page />}}
+
+To reverse the meaning of _next_ and _previous_:
+
+{{< code-toggle file=hugo >}}
+[page]
+ nextPrevInSectionSortOrder = 'asc'
+ nextPrevSortOrder = 'asc'
+{{< /code-toggle >}}
+
+> [!note]
+> These settings do not apply to the [`Next`] or [`Prev`] methods on a `Pages` object.
+
+[`Next`]: /methods/pages/next
+[`Prev`]: /methods/pages/next
diff --git a/documents/markdown/hugo-docs/en_configuration_pagination.md b/documents/markdown/hugo-docs/en_configuration_pagination.md
new file mode 100644
index 0000000..b65abbf
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_pagination.md
@@ -0,0 +1,45 @@
+---
+title: Configure pagination
+linkTitle: Pagination
+description: Configure pagination.
+categories: []
+keywords: []
+---
+
+This is the default configuration:
+
+{{< code-toggle config=pagination />}}
+
+disableAliases
+: (`bool`) Whether to disable alias generation for the first pager. Default is `false`.
+
+pagerSize
+: (`int`) The number of pages per pager. Default is `10`.
+
+path
+: (`string`) The segment of each pager URL indicating that the target page is a pager. Default is `page`.
+
+With multilingual projects you can define the pagination behavior for each language:
+
+{{< code-toggle file=hugo >}}
+[languages.en]
+contentDir = 'content/en'
+direction = 'ltr'
+label = 'English'
+locale = 'en-US'
+weight = 1
+[languages.en.pagination]
+disableAliases = true
+pagerSize = 10
+path = 'page'
+[languages.de]
+contentDir = 'content/de'
+direction = 'ltr'
+label = 'Deutsch'
+locale = 'de-DE'
+weight = 2
+[languages.de.pagination]
+disableAliases = true
+pagerSize = 20
+path = 'blatt'
+{{< /code-toggle >}}
diff --git a/documents/markdown/hugo-docs/en_configuration_params.md b/documents/markdown/hugo-docs/en_configuration_params.md
new file mode 100644
index 0000000..1b0233e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_params.md
@@ -0,0 +1,100 @@
+---
+title: Configure params
+linkTitle: Params
+description: Create custom site parameters.
+categories: []
+keywords: []
+---
+
+Use the `params` key for custom parameters:
+
+{{< code-toggle file=hugo >}}
+baseURL = 'https://example.org/'
+locale = 'en-US'
+title = 'Project Documentation'
+[params]
+subtitle = 'Reference, Tutorials, and Explanations'
+[params.contact]
+email = 'info@example.org'
+phone = '+1 206-555-1212'
+{{< /code-toggle >}}
+
+Access the custom parameters from your templates using the [`Params`] method on a `Site` object:
+
+[`Params`]: /methods/site/params/
+
+```go-html-template
+{{ .Site.Params.subtitle }} → Reference, Tutorials, and Explanations
+{{ .Site.Params.contact.email }} → info@example.org
+```
+
+Key names should use camelCase or snake_case. While TOML, YAML, and JSON allow kebab-case keys, they are not valid [identifiers](g) and cannot be used when [chaining](g) identifiers.
+
+For example, you can do either of these:
+
+```go-html-template
+{{ .Site.params.camelCase.foo }}
+{{ .Site.params.snake_case.foo }}
+```
+
+But you cannot do this:
+
+```go-html-template
+{{ .Site.params.kebab-case.foo }}
+```
+
+## Multilingual projects
+
+For multilingual projects, create a `params` key under each language:
+
+{{< code-toggle file=hugo >}}
+baseURL = 'https://example.org/'
+defaultContentLanguage = 'en'
+
+[languages.de]
+direction = 'ltr'
+label = 'Deutsch'
+locale = 'de-DE'
+title = 'Projekt Dokumentation'
+weight = 1
+
+[languages.de.params]
+subtitle = 'Referenz, Tutorials und Erklärungen'
+
+[languages.de.params.contact]
+email = 'info@de.example.org'
+phone = '+49 30 1234567'
+
+[languages.en]
+direction = 'ltr'
+label = 'English'
+locale = 'en-US'
+title = 'Project Documentation'
+weight = 2
+
+[languages.en.params]
+subtitle = 'Reference, Tutorials, and Explanations'
+
+[languages.en.params.contact]
+email = 'info@example.org'
+phone = '+1 206-555-1212'
+{{< /code-toggle >}}
+
+## Namespacing
+
+To prevent naming conflicts, module and theme developers should namespace any custom parameters specific to their module or theme.
+
+{{< code-toggle file=hugo >}}
+[params.modules.myModule.colors]
+background = '#efefef'
+font = '#222222'
+{{< /code-toggle >}}
+
+To access the module/theme settings:
+
+```go-html-template
+{{ $cfg := .Site.Params.module.mymodule }}
+
+{{ $cfg.colors.background }} → #efefef
+{{ $cfg.colors.font }} → #222222
+```
diff --git a/documents/markdown/hugo-docs/en_configuration_permalinks.md b/documents/markdown/hugo-docs/en_configuration_permalinks.md
new file mode 100644
index 0000000..49ad35b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_permalinks.md
@@ -0,0 +1,162 @@
+---
+title: Configure permalinks
+linkTitle: Permalinks
+description: Configure permalinks.
+categories: []
+keywords: []
+---
+
+This is the default configuration:
+
+{{< code-toggle config=permalinks />}}
+
+Define a URL pattern for each top-level section. Each URL pattern can target a given language and/or page kind.
+
+> [!note]
+> The [`url`] front matter field overrides any matching permalink pattern.
+
+## Monolingual example
+
+With this content structure:
+
+```text
+content/
+├── posts/
+│ ├── bash-in-slow-motion.md
+│ └── tls-in-a-nutshell.md
+├── tutorials/
+│ ├── git-for-beginners.md
+│ └── javascript-bundling-with-hugo.md
+└── _index.md
+```
+
+Render tutorials under "training", and render the posts under "articles" with a date-base hierarchy:
+
+{{< code-toggle file=hugo >}}
+[permalinks.page]
+posts = '/articles/:year/:month/:slug/'
+tutorials = '/training/:slug/'
+[permalinks.section]
+posts = '/articles/'
+tutorials = '/training/'
+{{< /code-toggle >}}
+
+The structure of the published site will be:
+
+```text
+public/
+├── articles/
+│ ├── 2023/
+│ │ ├── 04/
+│ │ │ └── bash-in-slow-motion/
+│ │ │ └── index.html
+│ │ └── 06/
+│ │ └── tls-in-a-nutshell/
+│ │ └── index.html
+│ └── index.html
+├── training/
+│ ├── git-for-beginners/
+│ │ └── index.html
+│ ├── javascript-bundling-with-hugo/
+│ │ └── index.html
+│ └── index.html
+└── index.html
+```
+
+To create a date-based hierarchy for regular pages in the content root:
+
+{{< code-toggle file=hugo >}}
+[permalinks.page]
+'/' = '/:year/:month/:slug/'
+{{< /code-toggle >}}
+
+Use the same approach with taxonomy terms. For example, to omit the taxonomy segment of the URL:
+
+{{< code-toggle file=hugo >}}
+[permalinks.term]
+'tags' = '/:slug/'
+{{< /code-toggle >}}
+
+## Multilingual example
+
+Use the `permalinks` configuration as a component of your localization strategy.
+
+With this content structure:
+
+```text
+content/
+├── en/
+│ ├── books/
+│ │ ├── les-miserables.md
+│ │ └── the-hunchback-of-notre-dame.md
+│ └── _index.md
+└── es/
+ ├── books/
+ │ ├── les-miserables.md
+ │ └── the-hunchback-of-notre-dame.md
+ └── _index.md
+```
+
+And this project configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'en'
+defaultContentLanguageInSubdir = true
+
+[languages.en]
+contentDir = 'content/en'
+direction = 'ltr'
+label = 'English'
+locale = 'en-US'
+weight = 1
+
+[languages.en.permalinks.page]
+books = '/books/:slug/'
+
+[languages.en.permalinks.section]
+books = '/books/'
+
+[languages.es]
+contentDir = 'content/es'
+direction = 'ltr'
+label = 'Español'
+locale = 'es-ES'
+weight = 2
+
+[languages.es.permalinks.page]
+books = '/libros/:slug/'
+
+[languages.es.permalinks.section]
+books = '/libros/'
+{{< /code-toggle >}}
+
+The structure of the published site will be:
+
+```text
+public/
+├── en/
+│ ├── books/
+│ │ ├── les-miserables/
+│ │ │ └── index.html
+│ │ ├── the-hunchback-of-notre-dame/
+│ │ │ └── index.html
+│ │ └── index.html
+│ └── index.html
+├── es/
+│ ├── libros/
+│ │ ├── les-miserables/
+│ │ │ └── index.html
+│ │ ├── the-hunchback-of-notre-dame/
+│ │ │ └── index.html
+│ │ └── index.html
+│ └── index.html
+└── index.html
+```
+
+## Tokens
+
+Use these tokens when defining a URL pattern.
+
+{{% include "/_common/permalink-tokens.md" %}}
+
+[`url`]: /content-management/front-matter/#url
diff --git a/documents/markdown/hugo-docs/en_configuration_privacy.md b/documents/markdown/hugo-docs/en_configuration_privacy.md
new file mode 100644
index 0000000..121765b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_privacy.md
@@ -0,0 +1,43 @@
+---
+title: Configure privacy
+linkTitle: Privacy
+description: Configure your site to help comply with regional privacy regulations.
+categories: []
+keywords: []
+aliases: [/about/privacy/]
+---
+
+## Responsibility
+
+Site authors are responsible for ensuring compliance with regional privacy regulations, including but not limited to:
+
+- GDPR (General Data Protection Regulation): Applies to individuals within the European Union and the European Economic Area.
+- CCPA (California Consumer Privacy Act): Applies to California residents.
+- CPRA (California Privacy Rights Act): Expands upon the CCPA with stronger consumer privacy protections.
+- Virginia Consumer Data Protection Act (CDPA): Applies to businesses that collect, process, or sell the personal data of Virginia residents.
+
+Hugo's privacy settings can assist in compliance efforts.
+
+## Embedded templates
+
+Hugo provides [embedded templates](g) to simplify project and content creation. Some of these templates interact with external services. For example, the `youtube` shortcode connects with YouTube's servers to embed videos.
+
+Some of these templates include settings to enhance privacy.
+
+## Configuration
+
+> [!note]
+> These settings affect the behavior of some of Hugo's embedded templates. These settings may or may not affect the behavior of templates provided by third parties in their modules or themes.
+
+These are the default privacy settings for Hugo's embedded templates:
+
+{{< code-toggle config=privacy />}}
+
+See each template's documentation for a description of its privacy settings:
+
+- [Disqus partial](/templates/embedded/#privacy-disqus)
+- [Google Analytics partial](/templates/embedded/#privacy-google-analytics)
+- [Instagram shortcode](/shortcodes/instagram/#privacy)
+- [Vimeo shortcode](/shortcodes/vimeo/#privacy)
+- [X shortcode](/shortcodes/x/#privacy)
+- [YouTube shortcode](/shortcodes/youtube/#privacy)
diff --git a/documents/markdown/hugo-docs/en_configuration_related-content.md b/documents/markdown/hugo-docs/en_configuration_related-content.md
new file mode 100644
index 0000000..de8b33b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_related-content.md
@@ -0,0 +1,111 @@
+---
+title: Configure related content
+linkTitle: Related content
+description: Configure related content.
+categories: []
+keywords: []
+---
+
+> [!note]
+> To understand Hugo's related content identification, please refer to the [related content] page.
+
+Hugo provides a sensible default configuration for identifying related content, but you can customize it in your project configuration, either globally or per language.
+
+## Default configuration
+
+This is the default configuration:
+
+{{< code-toggle config=related />}}
+
+> [!note]
+> Adding a `related` section to your project configuration requires you to provide a full configuration. You cannot override individual default values without specifying all related settings.
+
+## Top-level options
+
+threshold
+: (`int`) A value between 0-100, inclusive. A lower value will return more, but maybe not so relevant, matches.
+
+includeNewer
+: (`bool`) Whether to include pages newer than the current page in the related content listing. This will mean that the output for older posts may change as new related content gets added. Default is `false`.
+
+toLower
+: (`bool`) Whether to transform keywords in both the indexes and the queries to lower case. This may give more accurate results at a slight performance penalty. Default is `false`.
+
+## Per-index options
+
+name
+: (`string`) The index name. This value maps directly to a page parameter. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects.
+
+type
+: (`string`) One of `basic` or `fragments`. Default is `basic`.
+
+applyFilter
+: (`string`) Apply a `type` specific filter to the result of a search. This is currently only used for the `fragments` type.
+
+weight
+: (`int`) An integer weight that indicates how important this parameter is relative to the other parameters. It can be `0`, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best. Default is `0`.
+
+cardinalityThreshold
+: (`int`) If between `1` and `100`, this is a percentage. All keywords that are used in more than this percentage of documents are removed. For example, setting this to `60` will remove all keywords that are used in more than 60% of the documents in the index. If `0`, no keyword is removed from the index. Default is `0`.
+
+pattern
+: (`string`) This is currently only relevant for dates. When listing related content, we may want to list content that is also close in time. Setting "2006" (default value for date indexes) as the pattern for a date index will add weight to pages published in the same year. For busier blogs, "200601" (year and month) may be a better default.
+
+toLower
+: (`bool`) Whether to transform keywords in both the indexes and the queries to lower case. This may give more accurate results at a slight performance penalty. Default is `false`.
+
+## Example
+
+Imagine we're building a book review site. Our main content will be book reviews, and we'll use genres and authors as taxonomies. When someone views a book review, we want to show a short list of related reviews based on shared authors and genres.
+
+Create the content:
+
+```text
+content/
+└── book-reviews/
+ ├── book-review-1.md
+ ├── book-review-2.md
+ ├── book-review-3.md
+ ├── book-review-4.md
+ └── book-review-5.md
+```
+
+Configure the taxonomies:
+
+{{< code-toggle file=hugo >}}
+[taxonomies]
+author = 'authors'
+genre = 'genres'
+{{< /code-toggle >}}
+
+Configure the related content identification:
+
+{{< code-toggle file=hugo >}}
+[related]
+includeNewer = true
+threshold = 80
+toLower = true
+[[related.indices]]
+name = 'authors'
+weight = 2
+[[related.indices]]
+name = 'genres'
+weight = 1
+{{< /code-toggle >}}
+
+We've configured the `authors` index with a weight of `2` and the `genres` index with a weight of `1`. This means Hugo prioritizes shared `authors` as twice as significant as shared `genres`.
+
+Then render a list of 5 related reviews with a _partial_ template like this:
+
+```go-html-template {file="layouts/_partials/related.html" copy=true}
+{{ with site.RegularPages.Related . | first 5 }}
+ <p>Related content:</p>
+ <ul>
+ {{ range . }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+[related content]: /content-management/related-content/
diff --git a/documents/markdown/hugo-docs/en_configuration_roles.md b/documents/markdown/hugo-docs/en_configuration_roles.md
new file mode 100644
index 0000000..e5db3dc
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_roles.md
@@ -0,0 +1,35 @@
+---
+title: Configure roles
+linkTitle: Roles
+description: Configure roles.
+categories: []
+keywords: []
+---
+
+{{< new-in 0.153.0 />}}
+
+This is the default configuration:
+
+{{< code-toggle config=roles />}}
+
+## Settings
+
+Use the following setting to define how Hugo orders roles.
+
+weight
+: (`int`) The role [weight](g).
+
+## Sort order
+
+Hugo sorts roles by weight in ascending order, then lexicographically in ascending order. This affects build order and complement selection.
+
+## Example
+
+The following configuration demonstrates how to define multiple roles with specific weights.
+
+{{< code-toggle >}}
+[roles.guest]
+weight = 20
+[roles.member]
+weight = 10
+{{< /code-toggle >}}
diff --git a/documents/markdown/hugo-docs/en_configuration_security.md b/documents/markdown/hugo-docs/en_configuration_security.md
new file mode 100644
index 0000000..54342ad
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_security.md
@@ -0,0 +1,50 @@
+---
+title: Configure security
+linkTitle: Security
+description: Configure security.
+categories: []
+keywords: []
+---
+
+Hugo's built-in security policy, which restricts access to `os/exec`, remote communication, and similar operations, is configured via allowlists. By default, access is restricted. If a build attempts to use a feature not included in the allowlist, it will fail, providing a detailed message.
+
+This is the default security configuration:
+
+{{< code-toggle config=security />}}
+
+enableInlineShortcodes
+: (`bool`) Whether to enable [inline shortcodes]. Default is `false`.
+
+exec.allow
+: (`[]string`) A slice of [regular expressions](g) matching the names of external executables that Hugo is allowed to run.
+
+exec.osEnv
+: (`[]string`) A slice of [regular expressions](g) matching the names of operating system environment variables that Hugo is allowed to access.
+
+funcs.getenv
+: (`[]string`) A slice of [regular expressions](g) matching the names of operating system environment variables that Hugo is allowed to access with the [`os.Getenv`] function.
+
+http.methods
+: (`[]string`) A slice of [regular expressions](g) matching the HTTP methods that the [`resources.GetRemote`] function is allowed to use.
+
+http.mediaTypes
+: (`[]string`) Applicable to the `resources.GetRemote` function, a slice of [regular expressions](g) matching the `Content-Type` in HTTP responses that Hugo trusts, bypassing file content analysis for media type detection.
+
+http.urls
+: (`[]string`) A slice of [regular expressions](g) matching the URLs that the `resources.GetRemote` function is allowed to access.
+
+> [!note]
+> Setting an allowlist to the string `none` will completely disable the associated feature.
+
+You can also override your project configuration with environment variables. For example, to block `resources.GetRemote` from accessing any URL:
+
+```txt
+export HUGO_SECURITY_HTTP_URLS=none
+```
+
+Learn more about [using environment variables] to configure your site.
+
+[`os.Getenv`]: /functions/os/getenv
+[`resources.GetRemote`]: /functions/resources/getremote
+[inline shortcodes]: /content-management/shortcodes/#inline
+[using environment variables]: /configuration/introduction/#environment-variables
diff --git a/documents/markdown/hugo-docs/en_configuration_segments.md b/documents/markdown/hugo-docs/en_configuration_segments.md
new file mode 100644
index 0000000..d556201
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_segments.md
@@ -0,0 +1,75 @@
+---
+title: Configure segments
+linkTitle: Segments
+description: Configure your site for segmented rendering.
+categories: []
+keywords: []
+---
+
+> [!note]
+> The `segments` configuration applies only to segmented rendering. While it controls when content is rendered, it doesn't restrict access to Hugo's complete object graph (sites and pages), which remains fully available.
+
+Segmented rendering offers several advantages:
+
+- Faster builds: Process large sites more efficiently.
+- Rapid development: Render only a subset of your site for quicker iteration.
+- Scheduled rebuilds: Rebuild specific sections at different frequencies (e.g., home page and news hourly, full site weekly).
+- Targeted output: Generate specific output formats (like JSON for search indexes).
+
+## Segment definition
+
+Each segment is defined by include and exclude filters:
+
+- Filters: Each segment has zero or more exclude filters and zero or more include filters.
+- Matchers: Each filter contains one or more field [glob pattern](g) matchers.
+- Logic: Matchers within a filter use AND logic. Filters within a section (include or exclude) use OR logic.
+
+## Filter fields
+
+Available fields for filtering:
+
+kind
+: (`string`) A [glob pattern](g) matching the [page kind](g). For example: `{taxonomy,term}`.
+
+sites
+: {{< new-in 0.153.0 />}}
+: (`map`) A map to define [sites matrix](g).
+
+output
+: (`string`) A [glob pattern](g) matching the [output format](g) of the page. For example: `{html,json}`.
+
+path
+: (`string`) A [glob pattern](g) matching the page's [logical path](g). For example: `{/books,/books/**}`.
+
+## Example
+
+Place broad filters, such as those for language or output format, in the excludes section. For example:
+
+{{< code-toggle file=hugo >}}
+[segments.segment1]
+ [[segments.segment1.excludes]]
+ lang = 'n*'
+ [[segments.segment1.excludes]]
+ lang = 'en'
+ output = 'rss'
+ [[segments.segment1.includes]]
+ kind = '{home,term,taxonomy}'
+ [[segments.segment1.includes]]
+ path = '{/docs,/docs/**}'
+{{< /code-toggle >}}
+
+## Rendering segments
+
+Render specific segments using the [`renderSegments`] configuration or the `--renderSegments` flag:
+
+```sh
+hugo build --renderSegments segment1
+```
+
+You can configure multiple segments and use a comma-separated list with `--renderSegments` to render them all.
+
+```sh
+hugo build --renderSegments segment1,segment2
+```
+
+[`renderSegments`]: /configuration/all/#rendersegments
diff --git a/documents/markdown/hugo-docs/en_configuration_server.md b/documents/markdown/hugo-docs/en_configuration_server.md
new file mode 100644
index 0000000..2e1e29a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_server.md
@@ -0,0 +1,128 @@
+---
+title: Configure server
+linkTitle: Server
+description: Configure the development server.
+categories: []
+keywords: []
+---
+
+These settings are exclusive to Hugo's development server, so a dedicated [configuration directory] for development, where the server is configured accordingly, is the recommended approach.
+
+[configuration directory]: /configuration/introduction/#configuration-directory
+
+```text
+project/
+└── config/
+ ├── _default/
+ │ └── hugo.toml
+ └── development/
+ └── server.toml
+```
+
+## Default settings
+
+The development server defaults to redirecting to `/404.html` for any requests to URLs that don't exist. See the [404 errors](#404-errors) section below for details.
+
+{{< code-toggle config=server />}}
+
+force
+: (`bool`) Whether to force a redirect even if there is existing content in the path.
+
+from
+: (`string`) A [glob pattern](g) matching the requested URL. Either `from` or `fromRE` must be set. If both `from` and `fromRe` are specified, the URL must match both patterns.
+
+fromHeaders
+: {{< new-in 0.144.0 />}}
+: (`map[string][string]`) Headers to match for the redirect. This maps the HTTP header name to a [glob pattern](g) with values to match. If the map is empty, the redirect will always be triggered.
+
+fromRe
+: {{< new-in 0.144.0 />}}
+: (`string`) A [regular expression](g) used to match the requested URL. Either `from` or `fromRE` must be set. If both `from` and `fromRe` are specified, the URL must match both patterns. Capture groups from the regular expression are accessible in the `to` field as `$1`, `$2`, and so on.
+
+status
+: (`string`) The HTTP status code to use for the redirect. A status code of 200 will trigger a URL rewrite.
+
+to
+: (`string`) The URL to forward the request to.
+
+## Headers
+
+Include headers in every server response to facilitate testing, particularly for features like [Content Security Policies].
+
+[Content Security Policies]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
+
+{{< code-toggle file=config/development/server >}}
+[[headers]]
+for = '/**'
+
+[headers.values]
+X-Frame-Options = 'DENY'
+X-XSS-Protection = '1; mode=block'
+X-Content-Type-Options = 'nosniff'
+Referrer-Policy = 'strict-origin-when-cross-origin'
+Content-Security-Policy = 'script-src localhost:1313'
+{{< /code-toggle >}}
+
+## Redirects
+
+You can define simple redirect rules.
+
+{{< code-toggle file=config/development/server >}}
+[[redirects]]
+from = '/myspa/**'
+to = '/myspa/'
+status = 200
+force = false
+{{< /code-toggle >}}
+
+The `200` status code in this example triggers a URL rewrite, which is typically the desired behavior for [single-page applications].
+
+[single-page applications]: https://en.wikipedia.org/wiki/Single-page_application
+
+## 404 errors
+
+The development server defaults to redirecting to /404.html for any requests to URLs that don't exist.
+
+{{< code-toggle config=server />}}
+
+If you've already defined other redirects, you must explicitly add the 404 redirect.
+
+{{< code-toggle file=config/development/server >}}
+[[redirects]]
+force = false
+from = '/**'
+to = '/404.html'
+status = 404
+{{< /code-toggle >}}
+
+For multilingual projects, ensure the default language 404 redirect is defined last:
+
+{{< code-toggle file=config/development/server >}}
+defaultContentLanguage = 'en'
+defaultContentLanguageInSubdir = false
+[[redirects]]
+from = '/fr/**'
+to = '/fr/404.html'
+status = 404
+
+[[redirects]] # Default language must be last.
+from = '/**'
+to = '/404.html'
+status = 404
+{{< /code-toggle >}}
+
+When the default language is served from a subdirectory:
+
+{{< code-toggle file=config/development/server >}}
+defaultContentLanguage = 'en'
+defaultContentLanguageInSubdir = true
+[[redirects]]
+from = '/fr/**'
+to = '/fr/404.html'
+status = 404
+
+[[redirects]] # Default language must be last.
+from = '/**'
+to = '/en/404.html'
+status = 404
+{{< /code-toggle >}}
diff --git a/documents/markdown/hugo-docs/en_configuration_services.md b/documents/markdown/hugo-docs/en_configuration_services.md
new file mode 100644
index 0000000..a25e63a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_services.md
@@ -0,0 +1,43 @@
+---
+title: Configure services
+linkTitle: Services
+description: Configure embedded templates.
+categories: []
+keywords: []
+---
+
+Hugo provides [embedded templates](g) to simplify site and content creation. Some of these templates are configurable. For example, the embedded Google Analytics template requires a Google tag ID.
+
+This is the default configuration:
+
+{{< code-toggle config=services />}}
+
+disqus.shortname
+: (`string`) The `shortname` used with the Disqus commenting system. See [details](/templates/embedded/#disqus). To access this value from a template:
+
+ ```go-html-template
+ {{ .Site.Config.Services.Disqus.Shortname }}
+ ```
+
+googleAnalytics.id
+: (`string`) The Google tag ID for Google Analytics 4 properties. See [details](/templates/embedded/#google-analytics). To access this value from a template:
+
+ ```go-html-template
+ {{ .Site.Config.Services.GoogleAnalytics.ID }}
+ ```
+
+rss.limit
+: (`int`) The maximum number of items to include in an RSS feed. Set to `-1` for no limit. Default is `-1`. See [details](/templates/rss/). To access this value from a template:
+
+ ```go-html-template
+ {{ .Site.Config.Services.RSS.Limit }}
+ ```
+
+x.disableInlineCSS
+: (`bool`) Whether to disable the inline CSS rendered by the embedded `x` shortode. See [details](/shortcodes/x/#privacy). Default is `false`. To access this value from a template:
+
+ ```go-html-template
+ {{ .Site.Config.Services.X.DisableInlineCSS }}
+
+[v0.141.0]: https://github.com/gohugoio/hugo/releases/tag/v0.141.0
+[v0.123.0]: https://github.com/gohugoio/hugo/releases/tag/v0.123.0
diff --git a/documents/markdown/hugo-docs/en_configuration_sitemap.md b/documents/markdown/hugo-docs/en_configuration_sitemap.md
new file mode 100644
index 0000000..8000325
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_sitemap.md
@@ -0,0 +1,23 @@
+---
+title: Configure sitemap
+linkTitle: Sitemap
+description: Configure the sitemap.
+categories: []
+keywords: []
+---
+
+These are the default sitemap configuration values. They apply to all pages unless overridden in front matter.
+
+{{< code-toggle config=sitemap />}}
+
+changefreq
+: (`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. With the default value of `""` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#changefreqdef).
+
+disable
+: (`bool`) Whether to disable page inclusion. Default is `false`. Set to `true` in front matter to exclude the page.
+
+filename
+: (`string`) The name of the generated file. Default is `sitemap.xml`.
+
+priority
+: (`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. With the default value of `-1` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#prioritydef).
diff --git a/documents/markdown/hugo-docs/en_configuration_taxonomies.md b/documents/markdown/hugo-docs/en_configuration_taxonomies.md
new file mode 100644
index 0000000..5da0f7f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_taxonomies.md
@@ -0,0 +1,69 @@
+---
+title: Configure taxonomies
+linkTitle: Taxonomies
+description: Configure taxonomies.
+categories: []
+keywords: []
+---
+
+The default configuration defines two [taxonomies](g), `categories` and `tags`.
+
+{{< code-toggle config=taxonomies />}}
+
+When creating a taxonomy:
+
+- Use the singular form for the key (e.g., `category`).
+- Use the plural form for the value (e.g., `categories`).
+
+Then use the value as the key in front matter:
+
+<!-- markdownlint-disable MD007 MD032 -->
+{{< code-toggle file=content/example.md fm=true >}}
+title: Example
+categories:
+ - vegetarian
+ - gluten-free
+tags:
+ - appetizer
+ - main course
+{{< /code-toggle >}}
+<!-- markdownlint-enable MD007 MD032 -->
+If you do not expect to assign more than one [term](g) from a given taxonomy to a content page, you may use the singular form for both key and value:
+
+{{< code-toggle file=hugo >}}
+taxonomies:
+ author: author
+{{< /code-toggle >}}
+
+Then in front matter:
+
+<!-- markdownlint-disable MD007 MD032 -->
+{{< code-toggle file=content/example.md fm=true >}}
+title: Example
+author:
+ - Robert Smith
+{{< /code-toggle >}}
+<!-- markdownlint-enable MD007 MD032 -->
+
+The example above illustrates that even with a single term, the value is still provided as an array.
+
+You must explicitly define the default taxonomies to maintain them when adding a new one:
+
+{{< code-toggle file=hugo >}}
+taxonomies:
+ author: author
+ category: categories
+ tag: tags
+{{< /code-toggle >}}
+
+To disable the taxonomy system, use the [`disableKinds`] setting in the root of your project configuration to disable the `taxonomy` and `term` page [kinds](g).
+
+{{< code-toggle file=hugo >}}
+disableKinds = ['taxonomy','term']
+{{< /code-toggle >}}
+
+[`disableKinds`]: /configuration/all/#disablekinds
+
+See the [taxonomies] section for more information.
+
+[taxonomies]: /content-management/taxonomies/
diff --git a/documents/markdown/hugo-docs/en_configuration_ugly-urls.md b/documents/markdown/hugo-docs/en_configuration_ugly-urls.md
new file mode 100644
index 0000000..17b110a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_ugly-urls.md
@@ -0,0 +1,37 @@
+---
+title: Configure ugly URLs
+linkTitle: Ugly URLs
+description: Configure ugly URLs.
+categories: []
+keywords: []
+---
+
+{{% glossary-term "ugly url" %}} For example:
+
+```text
+https://example.org/section/article.html
+```
+
+In its default configuration, Hugo generates [pretty URLs](g). For example:
+
+```text
+https://example.org/section/article/
+```
+
+This is the default configuration:
+
+{{< code-toggle config=uglyURLs />}}
+
+To generate ugly URLs for the entire site:
+
+{{< code-toggle file=hugo >}}
+uglyURLs = true
+{{< /code-toggle >}}
+
+To generate ugly URLs for specific sections of your site:
+
+{{< code-toggle file=hugo >}}
+[uglyURLs]
+books = true
+films = false
+{{< /code-toggle >}}
diff --git a/documents/markdown/hugo-docs/en_configuration_versions.md b/documents/markdown/hugo-docs/en_configuration_versions.md
new file mode 100644
index 0000000..7c0e91e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_configuration_versions.md
@@ -0,0 +1,37 @@
+---
+title: Configure versions
+linkTitle: Versions
+description: Configure versions.
+categories: []
+keywords: []
+---
+
+{{< new-in 0.153.0 />}}
+
+This is the default configuration:
+
+{{< code-toggle config=versions />}}
+
+## Settings
+
+Use the following setting to define how Hugo orders versions.
+
+weight
+: (`int`) The language [weight](g).
+
+## Sort order
+
+Hugo sorts versions by weight in ascending order, then by their [semantic version][] in descending order. This affects build order and complement selection.
+
+## Example
+
+The following configuration demonstrates how to define multiple versions with specific weights.
+
+{{< code-toggle >}}
+[versions."v1.0.0"]
+weight = 20
+[versions."v2.0.0"]
+weight = 10
+{{< /code-toggle >}}
+
+[semantic version]: https://semver.org/
diff --git a/documents/markdown/hugo-docs/en_content-management__index.md b/documents/markdown/hugo-docs/en_content-management__index.md
new file mode 100644
index 0000000..4e20607
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_content-management__index.md
@@ -0,0 +1,8 @@
+---
+title: Content management
+description: Hugo makes managing large static sites easy with support for archetypes, content types, menus, cross references, summaries, and more.
+categories: []
+keywords: []
+weight: 10
+aliases: [/content/,/content/organization]
+---
diff --git a/documents/markdown/hugo-docs/en_content-management_archetypes.md b/documents/markdown/hugo-docs/en_content-management_archetypes.md
new file mode 100644
index 0000000..5f7d1ec
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_content-management_archetypes.md
@@ -0,0 +1,186 @@
+---
+title: Archetypes
+description: An archetype is a template for new content.
+categories: []
+keywords: []
+aliases: [/content/archetypes/]
+---
+
+## Overview
+
+A content file consists of [front matter](g) and markup. The markup is typically Markdown, but Hugo also supports other [content formats](g). Front matter can be TOML, YAML, or JSON.
+
+The `hugo new content` command creates a new file in the `content` directory, using an archetype as a template. This is the default archetype:
+
+{{< code-toggle file=archetypes/default.md fm=true >}}
+title = '{{ replace .File.ContentBaseName `-` ` ` | title }}'
+date = '{{ .Date }}'
+draft = true
+{{< /code-toggle >}}
+
+When you create new content, Hugo evaluates the [template actions](g) within the archetype. For example:
+
+```sh
+hugo new content posts/my-first-post.md
+```
+
+With the default archetype shown above, Hugo creates this content file:
+
+{{< code-toggle file=content/posts/my-first-post.md fm=true >}}
+title = 'My First Post'
+date = '2023-08-24T11:49:46-07:00'
+draft = true
+{{< /code-toggle >}}
+
+You can create an archetype for one or more [content types](g). For example, use one archetype for posts, and use the default archetype for everything else:
+
+```text
+archetypes/
+├── default.md
+└── posts.md
+```
+
+## Lookup order
+
+Hugo looks for archetypes in the `archetypes` directory in the root of your project, falling back to the `archetypes` directory in themes or installed modules. An archetype for a specific content type takes precedence over the default archetype.
+
+For example, if you have enabled a theme named `my-theme` and you run this command:
+
+```sh
+hugo new content posts/my-first-post.md
+```
+
+The archetype lookup order is:
+
+1. `archetypes/posts.md`
+1. `themes/my-theme/archetypes/posts.md`
+1. `archetypes/default.md`
+1. `themes/my-theme/archetypes/default.md`
+
+If none of these exists, Hugo uses a built-in default archetype.
+
+## Functions and context
+
+You can use any template [function](g) within an archetype. As shown above, the default archetype uses the [`replace`](/functions/strings/replace) function to replace hyphens with spaces when populating the title in front matter.
+
+Archetypes receive the following [context](g):
+
+Date
+: (`string`) The current date and time, formatted in compliance with RFC3339.
+
+File
+: (`hugolib.fileInfo`) Returns file information for the current page. See [details](/methods/page/file).
+
+Type
+: (`string`) The [content type](g) inferred from the top-level directory name, or as specified by the `--kind` flag passed to the `hugo new content` command.
+
+Site
+: (`page.Site`) The current site object. See [details](/methods/site/).
+
+## Date format
+
+To insert date and time with a different format, use the [`time.Now`] function:
+
+[`time.Now`]: /functions/time/now/
+
+{{< code-toggle file=archetypes/default.md fm=true >}}
+title = '{{ replace .File.ContentBaseName `-` ` ` | title }}'
+date = '{{ time.Now.Format "2006-01-02" }}'
+draft = true
+{{< /code-toggle >}}
+
+## Include content
+
+Although typically used as a front matter template, you can also use an archetype to populate content.
+
+For example, in a documentation site you might have a section (content type) for functions. Every page within this section should follow the same format: a brief description, the function signature, examples, and notes. We can pre-populate the page to remind content authors of the standard format.
+
+````text {file="archetypes/functions.md"}
+---
+date: '{{ .Date }}'
+draft: true
+title: '{{ replace .File.ContentBaseName `-` ` ` | title }}'
+---
+
+A brief description of what the function does, using simple present tense in the third person singular form. For example:
+
+`someFunction` returns the string `s` repeated `n` times.
+
+## Signature
+
+```text
+func someFunction(s string, n int) string
+```
+
+## Examples
+
+One or more practical examples, each within a fenced code block.
+
+## Notes
+
+Additional information to clarify as needed.
+````
+
+Although you can include [template actions](g) within the content body, remember that Hugo evaluates these once---at the time of content creation. In most cases, place template actions in a [template](g) where Hugo evaluates the actions every time you [build](g) the site.
+
+## Leaf bundles
+
+You can also create archetypes for [leaf bundles](g).
+
+For example, in a photography site you might have a section (content type) for galleries. Each gallery is leaf bundle with content and images.
+
+Create an archetype for galleries:
+
+```text
+archetypes/
+├── galleries/
+│ ├── images/
+│ │ └── .gitkeep
+│ └── index.md <-- same format as default.md
+└── default.md
+```
+
+Subdirectories within an archetype must contain at least one file. Without a file, Hugo will not create the subdirectory when you create new content. The name and size of the file are irrelevant. The example above includes a `.gitkeep` file, an empty file commonly used to preserve otherwise empty directories in a Git repository.
+
+To create a new gallery:
+
+```sh
+hugo new galleries/bryce-canyon
+```
+
+This produces:
+
+```text
+content/
+├── galleries/
+│ └── bryce-canyon/
+│ ├── images/
+│ │ └── .gitkeep
+│ └── index.md
+└── _index.md
+```
+
+## Specify archetype
+
+Use the `--kind` command line flag to specify an archetype when creating content.
+
+For example, let's say your site has two sections: articles and tutorials. Create an archetype for each content type:
+
+```text
+archetypes/
+├── articles.md
+├── default.md
+└── tutorials.md
+```
+
+To create an article using the articles archetype:
+
+```sh
+hugo new content articles/something.md
+```
+
+To create an article using the tutorials archetype:
+
+```sh
+hugo new content --kind tutorials articles/something.md
+```
diff --git a/documents/markdown/hugo-docs/en_content-management_build-options.md b/documents/markdown/hugo-docs/en_content-management_build-options.md
new file mode 100644
index 0000000..0e4d402
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_content-management_build-options.md
@@ -0,0 +1,303 @@
+---
+title: Build options
+description: Build options help define how Hugo must treat a given page when building the site.
+categories: []
+keywords: []
+aliases: [/content/build-options/]
+---
+
+<!-- TODO
+We deprecated the `_build` front matter key in favor of `build` in v0.145.0 on 2025-02-26. Remove footnote #1 on or after 2026-05-26 (15 months after deprecation).
+-->
+
+Build options are stored in a reserved front matter object named `build`[^1] with these defaults:
+
+[^1]: The `_build` alias for `build` is deprecated and will be removed in a future release.
+
+{{< code-toggle file=content/example/index.md fm=true >}}
+[build]
+list = 'always'
+publishResources = true
+render = 'always'
+{{< /code-toggle >}}
+
+list
+: When to include the page within page collections. Specify one of:
+
+ - `always`: Include the page in _all_ page collections. For example, `site.RegularPages`, `.Pages`, etc. This is the default value.
+ - `local`: Include the page in _local_ page collections. For example, `.RegularPages`, `.Pages`, etc. Use this option to create fully navigable but headless content sections.
+ - `never`: Do not include the page in _any_ page collection.
+
+publishResources
+: Applicable to [page bundles], determines whether to publish the associated [page resources]. Specify one of:
+
+ - `true`: Always publish resources. This is the default value.
+ - `false`: Only publish a resource when invoking its [`Permalink`], [`RelPermalink`], or [`Publish`] method within a template.
+
+render
+: When to render the page. Specify one of:
+
+ - `always`: Always render the page to disk. This is the default value.
+ - `link`: Do not render the page to disk, but assign `Permalink` and `RelPermalink` values.
+ - `never`: Never render the page to disk, and exclude it from all page collections.
+
+> [!note]
+> Any page, regardless of its build options, will always be available by using the [`.Page.GetPage`] or [`.Site.GetPage`] method.
+
+## Example -- headless page
+
+Create a unpublished page whose content and resources can be included in other pages.
+
+```text
+content/
+├── headless/
+│ ├── a.jpg
+│ ├── b.jpg
+│ └── index.md <-- leaf bundle
+└── _index.md <-- home page
+```
+
+Set the build options in front matter:
+
+{{< code-toggle file=content/headless/index.md fm=true >}}
+title = 'Headless page'
+[build]
+ list = 'never'
+ publishResources = false
+ render = 'never'
+{{< /code-toggle >}}
+
+To include the content and images on the home page:
+
+```go-html-template {file="layouts/home.html"}
+{{ with .Site.GetPage "/headless" }}
+ {{ .Content }}
+ {{ range .Resources.ByType "image" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+The published site will have this structure:
+
+```text
+public/
+├── headless/
+│ ├── a.jpg
+│ └── b.jpg
+└── index.html
+```
+
+In the example above, note that:
+
+1. Hugo did not publish an HTML file for the page.
+1. Despite setting `publishResources` to `false` in front matter, Hugo published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior.
+
+## Example -- headless section
+
+Create a unpublished section whose content and resources can be included in other pages.
+
+```text
+content/
+├── headless/
+│ ├── note-1/
+│ │ ├── a.jpg
+│ │ ├── b.jpg
+│ │ └── index.md <-- leaf bundle
+│ ├── note-2/
+│ │ ├── c.jpg
+│ │ ├── d.jpg
+│ │ └── index.md <-- leaf bundle
+│ └── _index.md <-- branch bundle
+└── _index.md <-- home page
+```
+
+Set the build options in front matter, using the `cascade` keyword to "cascade" the values down to descendant pages.
+
+{{< code-toggle file=content/headless/_index.md fm=true >}}
+title = 'Headless section'
+[[cascade]]
+[cascade.build]
+ list = 'local'
+ publishResources = false
+ render = 'never'
+{{< /code-toggle >}}
+
+In the front matter above, note that we have set `list` to `local` to include the descendant pages in local page collections.
+
+To include the content and images on the home page:
+
+```go-html-template {file="layouts/home.html"}
+{{ with .Site.GetPage "/headless" }}
+ {{ range .Pages }}
+ {{ .Content }}
+ {{ range .Resources.ByType "image" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+The published site will have this structure:
+
+```text
+public/
+├── headless/
+│ ├── note-1/
+│ │ ├── a.jpg
+│ │ └── b.jpg
+│ └── note-2/
+│ ├── c.jpg
+│ └── d.jpg
+└── index.html
+```
+
+In the example above, note that:
+
+1. Hugo did not publish an HTML file for the page.
+1. Despite setting `publishResources` to `false` in front matter, Hugo correctly published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior.
+
+## Example -- list without publishing
+
+Publish a section page without publishing the descendant pages. For example, to create a glossary:
+
+```text
+content/
+├── glossary/
+│ ├── _index.md
+│ ├── bar.md
+│ ├── baz.md
+│ └── foo.md
+└── _index.md
+```
+
+Set the build options in front matter, using the `cascade` keyword to "cascade" the values down to descendant pages.
+
+{{< code-toggle file=content/glossary/_index.md fm=true >}}
+title = 'Glossary'
+[build]
+render = 'always'
+[[cascade]]
+[cascade.build]
+ list = 'local'
+ publishResources = false
+ render = 'never'
+{{< /code-toggle >}}
+
+To render the glossary:
+
+```go-html-template {file="layouts/glossary/section.html"}
+<dl>
+ {{ range .Pages }}
+ <dt>{{ .Title }}</dt>
+ <dd>{{ .Content }}</dd>
+ {{ end }}
+</dl>
+```
+
+The published site will have this structure:
+
+```text
+public/
+├── glossary/
+│ └── index.html
+└── index.html
+```
+
+## Example -- publish without listing
+
+Publish a section's descendant pages without publishing the section page itself.
+
+```text
+content/
+├── books/
+│ ├── _index.md
+│ ├── book-1.md
+│ └── book-2.md
+└── _index.md
+```
+
+Set the build options in front matter:
+
+{{< code-toggle file=content/books/_index.md fm=true >}}
+title = 'Books'
+[build]
+render = 'never'
+list = 'never'
+{{< /code-toggle >}}
+
+The published site will have this structure:
+
+```text
+public/
+├── books/
+│ ├── book-1/
+│ │ └── index.html
+│ └── book-2/
+│ └── index.html
+└── index.html
+```
+
+## Example -- conditionally hide section
+
+Consider this example. A documentation site has a team of contributors with access to 20 custom shortcodes. Each shortcode takes several arguments, and requires documentation for the contributors to reference when using them.
+
+Instead of external documentation for the shortcodes, include an "internal" section that is hidden when building the production site.
+
+```text
+content/
+├── internal/
+│ ├── shortcodes/
+│ │ ├── _index.md
+│ │ ├── shortcode-1.md
+│ │ └── shortcode-2.md
+│ └── _index.md
+├── reference/
+│ ├── _index.md
+│ ├── reference-1.md
+│ └── reference-2.md
+├── tutorials/
+│ ├── _index.md
+│ ├── tutorial-1.md
+│ └── tutorial-2.md
+└── _index.md
+```
+
+Set the build options in front matter, using the `cascade` keyword to "cascade" the values down to descendant pages, and use the `target` keyword to target the production environment.
+
+{{< code-toggle file=content/internal/_index.md >}}
+title = 'Internal'
+[[cascade]]
+[cascade.build]
+render = 'never'
+list = 'never'
+[cascade.target]
+environment = 'production'
+{{< /code-toggle >}}
+
+The production site will have this structure:
+
+```text
+public/
+├── reference/
+│ ├── reference-1/
+│ │ └── index.html
+│ ├── reference-2/
+│ │ └── index.html
+│ └── index.html
+├── tutorials/
+│ ├── tutorial-1/
+│ │ └── index.html
+│ ├── tutorial-2/
+│ │ └── index.html
+│ └── index.html
+└── index.html
+```
+
+[`.Page.GetPage`]: /methods/page/getpage/
+[`.Site.GetPage`]: /methods/site/getpage/
+[`Permalink`]: /methods/resource/permalink/
+[`Publish`]: /methods/resource/publish/
+[`RelPermalink`]: /methods/resource/relpermalink/
+[page bundles]: /content-management/page-bundles/
+[page resources]: /content-management/page-resources/
diff --git a/documents/markdown/hugo-docs/en_content-management_comments.md b/documents/markdown/hugo-docs/en_content-management_comments.md
new file mode 100644
index 0000000..ce7f438
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_content-management_comments.md
@@ -0,0 +1,69 @@
+---
+title: Comments
+description: Hugo ships with an internal Disqus template, but this isn't the only commenting system that will work with your new Hugo website.
+categories: []
+keywords: []
+aliases: [/extras/comments/]
+---
+
+Hugo ships with support for [Disqus](https://disqus.com/), a third-party service that provides comment and community capabilities to websites via JavaScript.
+
+Your theme may already support Disqus, but if not, it is easy to add to your templates via [Hugo's built-in Disqus partial][disquspartial].
+
+## Add Disqus
+
+Hugo comes with all the code you need to load Disqus into your templates. Before adding Disqus to your site, you'll need to [set up an account][disqussetup].
+
+### Configure Disqus
+
+Disqus comments require you set a single value in your [project configuration][configuration]:
+
+{{< code-toggle file=hugo >}}
+[services.disqus]
+shortname = 'your-disqus-shortname'
+{{</ code-toggle >}}
+
+For many websites, this is enough configuration. However, you also have the option to set the following in the [front matter] of a single content file:
+
+- `disqus_identifier`
+- `disqus_title`
+- `disqus_url`
+
+### Render Hugo's built-in Disqus partial template
+
+Disqus has its own [internal template](/templates/embedded/#disqus) available, to render it add the following code where you want comments to appear:
+
+```go-html-template
+{{ partial "disqus.html" . }}
+```
+
+## Alternatives
+
+Commercial commenting systems:
+
+- [Commentix](https://www.commentix.com/)
+- [Emote](https://emote.com/)
+- [Graph Comment](https://graphcomment.com/)
+- [Hyvor Talk](https://talk.hyvor.com/)
+- [IntenseDebate](https://intensedebate.com/)
+- [ReplyBox](https://getreplybox.com/)
+
+Open-source commenting systems:
+
+- [Cactus Comments](https://cactus.chat/docs/integrations/hugo/)
+- [Comentario](https://gitlab.com/comentario/comentario/)
+- [Comma](https://github.com/Dieterbe/comma/)
+- [Commento](https://commento.io/)
+- [Discourse](https://meta.discourse.org/t/embed-discourse-comments-on-another-website-via-javascript/31963)
+- [Giscus](https://giscus.app/)
+- [Isso](https://isso-comments.de/)
+- [Remark42](https://remark42.com/)
+- [Staticman](https://staticman.net/)
+- [Talkyard](https://blog-comments.talkyard.io/)
+- [Utterances](https://utteranc.es/)
+- [Zoomment](https://zoomment.com/)
+
+[configuration]: /configuration/
+[disquspartial]: /templates/embedded/#disqus
+[disqussetup]: https://disqus.com/profile/signup/
+[front matter]: /content-management/front-matter/
diff --git a/documents/markdown/hugo-docs/en_content-management_content-adapters.md b/documents/markdown/hugo-docs/en_content-management_content-adapters.md
new file mode 100644
index 0000000..6bf3490
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_content-management_content-adapters.md
@@ -0,0 +1,354 @@
+---
+title: Content adapters
+description: Create content adapters to dynamically add content when building your project.
+categories: []
+keywords: []
+---
+
+## Overview
+
+A content adapter is a template that dynamically creates pages when building a site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML.
+
+Unlike templates that reside in the `layouts` directory, content adapters reside in the `content` directory, no more than one per directory per language. When a content adapter creates a page, the page's [logical path](g) will be relative to the content adapter.
+
+```text
+content/
+├── articles/
+│ ├── _index.md
+│ ├── article-1.md
+│ └── article-2.md
+├── books/
+│ ├── _content.gotmpl <-- content adapter
+│ └── _index.md
+└── films/
+ ├── _content.gotmpl <-- content adapter
+ └── _index.md
+```
+
+Each content adapter is named `_content.gotmpl` and uses the same [syntax] as templates in the `layouts` directory. You can use any of the [template functions] within a content adapter, as well as the methods described below.
+
+## Methods
+
+Use these methods within a content adapter.
+
+### AddPage
+
+Adds a page to the site.
+
+```go-html-template {file="content/books/_content.gotmpl"}
+{{ $content := dict
+ "mediaType" "text/markdown"
+ "value" "The _Hunchback of Notre Dame_ was written by Victor Hugo."
+}}
+{{ $page := dict
+ "content" $content
+ "kind" "page"
+ "path" "the-hunchback-of-notre-dame"
+ "title" "The Hunchback of Notre Dame"
+}}
+{{ .AddPage $page }}
+```
+
+### AddResource
+
+Adds a page resource to the site.
+
+```go-html-template {file="content/books/_content.gotmpl"}
+{{ with resources.Get "images/a.jpg" }}
+ {{ $content := dict
+ "mediaType" .MediaType.Type
+ "value" .
+ }}
+ {{ $resource := dict
+ "content" $content
+ "path" "the-hunchback-of-notre-dame/cover.jpg"
+ }}
+ {{ $.AddResource $resource }}
+{{ end }}
+```
+
+Then retrieve the new page resource with something like:
+
+```go-html-template {file="layouts/page.html"}
+{{ with .Resources.Get "cover.jpg" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+### Site
+
+Returns the `Site` to which the pages will be added.
+
+```go-html-template {file="content/books/_content.gotmpl"}
+{{ .Site.Title }}
+```
+
+> [!note]
+> Note that the `Site` returned isn't fully built when invoked from the content adapters; if you try to call methods that depends on pages, e.g. `.Site.Pages`, you will get an error saying "this method cannot be called before the site is fully initialized".
+
+### Store
+
+Returns a persistent "scratch pad" to store and manipulate data. The main use case for this is to transfer values between executions when [EnableAllLanguages](#enablealllanguages) is set. See [examples](/methods/page/store/).
+
+```go-html-template {file="content/books/_content.gotmpl"}
+{{ .Store.Set "key" "value" }}
+{{ .Store.Get "key" }}
+```
+
+### EnableAllLanguages
+
+By default, Hugo executes the content adapter only once for the first matching site in the [sites matrix](g). Use this method to expand execution to all languages while maintaining the current role and version.
+
+For more fine-grained control, define a `sites.matrix` in front matter or in a content mount.
+
+```go-html-template {file="content/books/_content.gotmpl"}
+{{ .EnableAllLanguages }}
+{{ $content := dict
+ "mediaType" "text/markdown"
+ "value" "The _Hunchback of Notre Dame_ was written by Victor Hugo."
+}}
+{{ $page := dict
+ "content" $content
+ "kind" "page"
+ "path" "the-hunchback-of-notre-dame"
+ "title" "The Hunchback of Notre Dame"
+}}
+{{ .AddPage $page }}
+```
+
+### EnableAllDimensions
+
+By default, Hugo executes the content adapter only once for the first matching site in the [sites matrix](g). Use this method to expand execution to every possible combination of language, version, and role.
+
+For more fine-grained control, define a `sites.matrix` in front matter or in a content mount.
+
+{{< new-in v0.153.0 />}}
+
+## Page map
+
+Set any [front matter field] in the map passed to the [`AddPage`](#addpage) method, excluding `markup`. Instead of setting the `markup` field, specify the `content.mediaType` as described below.
+
+This table describes the fields most commonly passed to the `AddPage` method.
+
+Key|Description|Required
+:--|:--|:-:
+`content.mediaType`|The content [media type]. Default is `text/markdown`. See [content formats] for examples.|
+`content.value`|The content value as a string.|
+`dates.date`|The page creation date as a `time.Time` value.|
+`dates.expiryDate`|The page expiry date as a `time.Time` value.|
+`dates.lastmod`|The page last modification date as a `time.Time` value.|
+`dates.publishDate`|The page publication date as a `time.Time` value.|
+`params`|A map of page parameters.|
+`path`|The page's [logical path](g) relative to the content adapter. Do not include a leading slash or file extension.|:heavy_check_mark:
+`title`|The page title.|
+
+> [!note]
+> While `path` is the only required field, we recommend setting `title` as well.
+>
+> When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C` produces a logical path of `/section/a-b-c`.
+
+## Resource map
+
+Construct the map passed to the [`AddResource`](#addresource) method using the fields below.
+
+Key|Description|Required
+:--|:--|:-:
+`content.mediaType`|The content [media type].|:heavy_check_mark:
+`content.value`|The content value as a string or resource.|:heavy_check_mark:
+`name`|The resource name.|
+`params`|A map of resource parameters.|
+`path`|The resources's [logical path](g) relative to the content adapter. Do not include a leading slash.|:heavy_check_mark:
+`title`|The resource title.|
+
+> [!note]
+> When `content.value` is a string, Hugo generates a new resource with a publication path relative to the page. However, if `content.value` is already a resource, Hugo directly uses its value and publishes it relative to the site root. This latter method is more efficient.
+>
+> When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C/cover.jpg` produces a logical path of `/section/a-b-c/cover.jpg`.
+
+## Example
+
+Create pages from remote data, where each page represents a book review.
+
+Step 1
+: Create the content structure.
+
+ ```text
+ content/
+ └── books/
+ ├── _content.gotmpl <-- content adapter
+ └── _index.md
+ ```
+
+Step 2
+: Inspect the remote data to determine how to map key-value pairs to front matter fields.\
+ <https://gohugo.io/shared/examples/data/books.json>
+
+Step 3
+: Create the content adapter.
+
+ ```go-html-template {file="content/books/_content.gotmpl" copy=true}
+ {{/* Get remote data. */}}
+ {{ $data := dict }}
+ {{ $url := "https://gohugo.io/shared/examples/data/books.json" }}
+ {{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ errorf "Unable to get remote resource %s: %s" $url . }}
+ {{ else with .Value }}
+ {{ $data = . | transform.Unmarshal }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %s" $url }}
+ {{ end }}
+ {{ end }}
+
+ {{/* Add pages and page resources. */}}
+ {{ range $data }}
+
+ {{/* Add page. */}}
+ {{ $content := dict "mediaType" "text/markdown" "value" .summary }}
+ {{ $dates := dict "date" (time.AsTime .date) }}
+ {{ $params := dict "author" .author "isbn" .isbn "rating" .rating "tags" .tags }}
+ {{ $page := dict
+ "content" $content
+ "dates" $dates
+ "kind" "page"
+ "params" $params
+ "path" .title
+ "title" .title
+ }}
+ {{ $.AddPage $page }}
+
+ {{/* Add page resource. */}}
+ {{ $item := . }}
+ {{ with $url := $item.cover }}
+ {{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ errorf "Unable to get remote resource %s: %s" $url . }}
+ {{ else with .Value }}
+ {{ $content := dict "mediaType" .MediaType.Type "value" .Content }}
+ {{ $params := dict "alt" $item.title }}
+ {{ $resource := dict
+ "content" $content
+ "params" $params
+ "path" (printf "%s/cover.%s" $item.title .MediaType.SubType)
+ }}
+ {{ $.AddResource $resource }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %s" $url }}
+ {{ end }}
+ {{ end }}
+ {{ end }}
+
+ {{ end }}
+ ```
+
+Step 4
+: Create a _page_ template to render each book review.
+
+ ```go-html-template {file="layouts/books/page.html" copy=true}
+ {{ define "main" }}
+ <h1>{{ .Title }}</h1>
+
+ {{ with .Resources.GetMatch "cover.*" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="{{ .Params.alt }}">
+ {{ end }}
+
+ <p>Author: {{ .Params.author }}</p>
+
+ <p>
+ ISBN: {{ .Params.isbn }}<br>
+ Rating: {{ .Params.rating }}<br>
+ Review date: {{ .Date | time.Format ":date_long" }}
+ </p>
+
+ {{ with .GetTerms "tags" }}
+ <p>Tags:</p>
+ <ul>
+ {{ range . }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+ {{ end }}
+
+ {{ .Content }}
+ {{ end }}
+ ```
+
+## Multilingual projects
+
+With multilingual projects you can:
+
+1. Create one content adapter for all languages using the [`EnableAllLanguages`](#enablealllanguages) method as described above.
+1. Create content adapters unique to each language. See the examples below.
+
+### Translations by file name
+
+With this project configuration:
+
+{{< code-toggle file=hugo >}}
+[languages.en]
+weight = 1
+
+[languages.de]
+weight = 2
+{{< /code-toggle >}}
+
+Include a language designator in the content adapter's file name.
+
+```text
+content/
+└── books/
+ ├── _content.de.gotmpl
+ ├── _content.en.gotmpl
+ ├── _index.de.md
+ └── _index.en.md
+```
+
+### Translations by content directory
+
+With this project configuration:
+
+{{< code-toggle file=hugo >}}
+[languages.en]
+contentDir = 'content/en'
+weight = 1
+
+[languages.de]
+contentDir = 'content/de'
+weight = 2
+{{< /code-toggle >}}
+
+Create a single content adapter in each directory:
+
+```text
+content/
+├── de/
+│ └── books/
+│ ├── _content.gotmpl
+│ └── _index.md
+└── en/
+ └── books/
+ ├── _content.gotmpl
+ └── _index.md
+```
+
+## Page collisions
+
+Two or more pages collide when they have the same publication path. Due to concurrency, the content of the published page is indeterminate. Consider this example:
+
+```text
+content/
+└── books/
+ ├── _content.gotmpl <-- content adapter
+ ├── _index.md
+ └── the-hunchback-of-notre-dame.md
+```
+
+If the content adapter also creates `books/the-hunchback-of-notre-dame`, the content of the published page is indeterminate. You can not define the processing order.
+
+To detect page collisions, use the `--printPathWarnings` flag when building your project.
+
+[content formats]: /content-management/formats/#classification
+[front matter field]: /content-management/front-matter/#fields
+[media type]: https://en.wikipedia.org/wiki/Media_type
+[syntax]: /templates/introduction/
+[template functions]: /functions/
diff --git a/documents/markdown/hugo-docs/en_content-management_data-sources.md b/documents/markdown/hugo-docs/en_content-management_data-sources.md
new file mode 100644
index 0000000..0395266
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_content-management_data-sources.md
@@ -0,0 +1,111 @@
+---
+title: Data sources
+description: Use local and remote data sources to augment or create content.
+categories: []
+keywords: []
+aliases: [/extras/datafiles/,/extras/datadrivencontent/,/doc/datafiles/,/templates/data-templates/]
+---
+
+Hugo can access and [unmarshal](g) local and remote data sources including CSV, JSON, TOML, YAML, and XML. Use this data to augment existing content or to create new content.
+
+A data source might be a file in the `data` directory, a [global resource](g), a [page resource](g), or a [remote resource](g).
+
+## Data directory
+
+The `data` directory in the root of your project may contain one or more data files, in either a flat or nested tree. Hugo merges the data files to create a single data structure, accessible with the `Data` method on a `Site` object.
+
+Hugo also merges data directories from themes and modules into this single data structure, where the `data` directory in the root of your project takes precedence.
+
+> [!note]
+> Hugo reads the combined data structure into memory and keeps it there for the entire build. For data that is infrequently accessed, use global or page resources instead.
+
+Theme and module authors may wish to namespace their data files to prevent collisions. For example:
+
+```text
+project/
+└── data/
+ └── mytheme/
+ └── foo.json
+```
+
+> [!note]
+> Do not place CSV files in the `data` directory. Access CSV files as page, global, or remote resources.
+
+See the documentation for the [`Data`] method on a `Site` object for details and examples.
+
+## Global resources
+
+Use the `resources.Get` and `transform.Unmarshal` functions to access data files that exist as global resources.
+
+See the [`transform.Unmarshal`](/functions/transform/unmarshal/#global-resource) documentation for details and examples.
+
+## Page resources
+
+Use the `Resources.Get` method on a `Page` object combined with the `transform.Unmarshal` function to access data files that exist as page resources.
+
+See the [`transform.Unmarshal`](/functions/transform/unmarshal/#page-resource) documentation for details and examples.
+
+## Remote resources
+
+Use the `resources.GetRemote` and `transform.Unmarshal` functions to access remote data.
+
+See the [`transform.Unmarshal`](/functions/transform/unmarshal/#remote-resource) documentation for details and examples.
+
+## Augment existing content
+
+Use data sources to augment existing content. For example, create a shortcode to render an HTML table from a global CSV resource.
+
+```csv {file="assets/pets.csv"}
+"name","type","breed","age"
+"Spot","dog","Collie","3"
+"Felix","cat","Malicious","7"
+```
+
+```text {file="content/example.md"}
+{{</* csv-to-table "pets.csv" */>}}
+```
+
+```go-html-template {file="layouts/_shortcodes/csv-to-table.html"}
+{{ with $file := .Get 0 }}
+ {{ with resources.Get $file }}
+ {{ with . | transform.Unmarshal }}
+ <table>
+ <thead>
+ <tr>
+ {{ range index . 0 }}
+ <th>{{ . }}</th>
+ {{ end }}
+ </tr>
+ </thead>
+ <tbody>
+ {{ range after 1 . }}
+ <tr>
+ {{ range . }}
+ <td>{{ . }}</td>
+ {{ end }}
+ </tr>
+ {{ end }}
+ </tbody>
+ </table>
+ {{ end }}
+ {{ else }}
+ {{ errorf "The %q shortcode was unable to find %s. See %s" $.Name $file $.Position }}
+ {{ end }}
+{{ else }}
+ {{ errorf "The %q shortcode requires one positional argument, the path to the CSV file relative to the assets directory. See %s" .Name .Position }}
+{{ end }}
+```
+
+Hugo renders this to:
+
+name|type|breed|age
+:--|:--|:--|:--
+Spot|dog|Collie|3
+Felix|cat|Malicious|7
+
+## Create new content
+
+Use [content adapters] to create new content.
+
+[`Data`]: /methods/site/data/
+[content adapters]: /content-management/content-adapters/
diff --git a/documents/markdown/hugo-docs/en_content-management_diagrams.md b/documents/markdown/hugo-docs/en_content-management_diagrams.md
new file mode 100644
index 0000000..763fce2
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_content-management_diagrams.md
@@ -0,0 +1,260 @@
+---
+title: Diagrams
+description: Use fenced code blocks and Markdown render hooks to include diagrams in your content.
+categories: []
+keywords: []
+---
+
+## GoAT diagrams (ASCII)
+
+Hugo natively supports [GoAT] diagrams with an [embedded code block render hook]. This means that this code block:
+
+````txt
+```goat
+ . . . .--- 1 .-- 1 / 1
+ / \ | | .---+ .-+ +
+ / \ .---+---. .--+--. | '--- 2 | '-- 2 / \ 2
+ + + | | | | ---+ ---+ +
+ / \ / \ .-+-. .-+-. .+. .+. | .--- 3 | .-- 3 \ / 3
+ / \ / \ | | | | | | | | '---+ '-+ +
+ 1 2 3 4 1 2 3 4 1 2 3 4 '--- 4 '-- 4 \ 4
+
+```
+````
+
+Will be rendered as:
+
+```goat
+
+ . . . .--- 1 .-- 1 / 1
+ / \ | | .---+ .-+ +
+ / \ .---+---. .--+--. | '--- 2 | '-- 2 / \ 2
+ + + | | | | ---+ ---+ +
+ / \ / \ .-+-. .-+-. .+. .+. | .--- 3 | .-- 3 \ / 3
+ / \ / \ | | | | | | | | '---+ '-+ +
+ 1 2 3 4 1 2 3 4 1 2 3 4 '--- 4 '-- 4 \ 4
+```
+
+## Mermaid diagrams
+
+Hugo does not provide a built-in template for Mermaid diagrams. Create your own using a [code block render hook]:
+
+```go-html-template {file="layouts/_markup/render-codeblock-mermaid.html" copy=true}
+<pre class="mermaid">
+ {{ .Inner | htmlEscape | safeHTML }}
+</pre>
+{{ .Page.Store.Set "hasMermaid" true }}
+```
+
+Then include this snippet at the _bottom_ of your base template, before the closing `body` tag:
+
+```go-html-template {file="layouts/baseof.html" copy=true}
+{{ if .Store.Get "hasMermaid" }}
+ <script type="module">
+ import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
+ mermaid.initialize({ startOnLoad: true });
+ </script>
+{{ end }}
+```
+
+With that you can use the `mermaid` language in Markdown code blocks:
+
+````text {copy=true}
+```mermaid
+sequenceDiagram
+ participant Alice
+ participant Bob
+ Alice->>John: Hello John, how are you?
+ loop Healthcheck
+ John->>John: Fight against hypochondria
+ end
+ Note right of John: Rational thoughts <br/>prevail!
+ John-->>Alice: Great!
+ John->>Bob: How about you?
+ Bob-->>John: Jolly good!
+```
+````
+
+## Goat ASCII diagram examples
+
+### Graphics
+
+```goat
+ .
+ 0 3 P * Eye / ^ /
+ *-------* +y \ +) \ / Reflection
+ 1 /| 2 /| ^ \ \ \ v
+ *-------* | | v0 \ v3 --------*--------
+ | |4 | |7 | *----\-----*
+ | *-----|-* +-----> +x / v X \ .-.<-------- o
+ |/ |/ / / o \ | / | Refraction / \
+ *-------* v / \ +-' / \
+ 5 6 +z v1 *------------------* v2 | o-----o
+ v
+
+```
+
+### Complex
+
+```goat
++-------------------+ ^ .---.
+| A Box |__.--.__ __.--> | .-. | |
+| | '--' v | * |<--- | |
++-------------------+ '-' | |
+ Round *---(-. |
+ .-----------------. .-------. .----------. .-------. | | |
+ | Mixed Rounded | | | / Diagonals \ | | | | | |
+ | & Square Corners | '--. .--' / \ |---+---| '-)-' .--------.
+ '--+------------+-' .--. | '-------+--------' | | | | / Search /
+ | | | | '---. | '-------' | '-+------'
+ |<---------->| | | | v Interior | ^
+ ' <---' '----' .-----------. ---. .--- v |
+ .------------------. Diag line | .-------. +---. \ / . |
+ | if (a > b) +---. .--->| | | | | Curved line \ / / \ |
+ | obj->fcn() | \ / | '-------' |<--' + / \ |
+ '------------------' '--' '--+--------' .--. .--. | .-. +Done?+-'
+ .---+-----. | ^ |\ | | /| .--+ | | \ /
+ | | | Join \|/ | | Curved | \| |/ | | \ | \ /
+ | | +----> o --o-- '-' Vertical '--' '--' '-- '--' + .---.
+ <--+---+-----' | /|\ | | 3 |
+ v not:line 'quotes' .-' '---'
+ .-. .---+--------. / A || B *bold* | ^
+ | | | Not a dot | <---+---<-- A dash--is not a line v |
+ '-' '---------+--' / Nor/is this. ---
+
+```
+
+### Process
+
+```goat
+ .
+ .---------. / \
+ | START | / \ .-+-------+-. ___________
+ '----+----' .-------. A / \ B | |COMPLEX| | / \ .-.
+ | | END |<-----+CHOICE +----->| | | +--->+ PREPARATION +--->| X |
+ v '-------' \ / | |PROCESS| | \___________/ '-'
+ .---------. \ / '-+---+---+-'
+ / INPUT / \ /
+ '-----+---' '
+ | ^
+ v |
+ .-----------. .-----+-----. .-.
+ | PROCESS +---------------->| PROCESS |<------+ X |
+ '-----------' '-----------' '-'
+```
+
+### File tree
+
+Created from <https://arthursonzogni.com/Diagon/#Tree>
+
+```goat {width=300 color="orange"}
+───Linux─┬─Android
+ ├─Debian─┬─Ubuntu─┬─Lubuntu
+ │ │ ├─Kubuntu
+ │ │ ├─Xubuntu
+ │ │ └─Xubuntu
+ │ └─Mint
+ ├─Centos
+ └─Fedora
+```
+
+### Sequence diagram
+
+<https://arthursonzogni.com/Diagon/#Sequence>
+
+```goat {class="w-40"}
+┌─────┐ ┌───┐
+│Alice│ │Bob│
+└──┬──┘ └─┬─┘
+ │ │
+ │ Hello Bob! │
+ │───────────>│
+ │ │
+ │Hello Alice!│
+ │<───────────│
+┌──┴──┐ ┌─┴─┐
+│Alice│ │Bob│
+└─────┘ └───┘
+
+```
+
+### Flowchart
+
+<https://arthursonzogni.com/Diagon/#Flowchart>
+
+```goat
+ _________________
+ ╱ ╲ ┌─────┐
+ ╱ DO YOU UNDERSTAND ╲____________________________________________________│GOOD!│
+ ╲ FLOW CHARTS? ╱yes └──┬──┘
+ ╲_________________╱ │
+ │no │
+ _________▽_________ ______________________ │
+ ╱ ╲ ╱ ╲ ┌────┐ │
+╱ OKAY, YOU SEE THE ╲________________╱ ... AND YOU CAN SEE ╲___│GOOD│ │
+╲ LINE LABELED 'YES'? ╱yes ╲ THE ONES LABELED 'NO'? ╱yes└──┬─┘ │
+ ╲___________________╱ ╲______________________╱ │ │
+ │no │no │ │
+ ________▽_________ _________▽__________ │ │
+ ╱ ╲ ┌───────────┐ ╱ ╲ │ │
+ ╱ BUT YOU SEE THE ╲___│WAIT, WHAT?│ ╱ BUT YOU JUST ╲___ │ │
+ ╲ ONES LABELED 'NO'? ╱yes└───────────┘ ╲ FOLLOWED THEM TWICE? ╱yes│ │ │
+ ╲__________________╱ ╲____________________╱ │ │ │
+ │no │no │ │ │
+ ┌───▽───┐ │ │ │ │
+ │LISTEN.│ └───────┬───────┘ │ │
+ └───┬───┘ ┌──────▽─────┐ │ │
+ ┌─────▽────┐ │(THAT WASN'T│ │ │
+ │I HATE YOU│ │A QUESTION) │ │ │
+ └──────────┘ └──────┬─────┘ │ │
+ ┌────▽───┐ │ │
+ │SCREW IT│ │ │
+ └────┬───┘ │ │
+ └─────┬─────┘ │
+ │ │
+ └─────┬─────┘
+ ┌───────▽──────┐
+ │LET'S GO DRING│
+ └───────┬──────┘
+ ┌─────────▽─────────┐
+ │HEY, I SHOULD TRY │
+ │INSTALLING FREEBSD!│
+ └───────────────────┘
+
+```
+
+### Table
+
+<https://arthursonzogni.com/Diagon/#Table>
+
+```goat {class="w-80 dark-blue"}
+┌────────────────────────────────────────────────┐
+│ │
+├────────────────────────────────────────────────┤
+│SYNTAX = { PRODUCTION } . │
+├────────────────────────────────────────────────┤
+│PRODUCTION = IDENTIFIER "=" EXPRESSION "." . │
+├────────────────────────────────────────────────┤
+│EXPRESSION = TERM { "|" TERM } . │
+├────────────────────────────────────────────────┤
+│TERM = FACTOR { FACTOR } . │
+├────────────────────────────────────────────────┤
+│FACTOR = IDENTIFIER │
+├────────────────────────────────────────────────┤
+│ | LITERAL │
+├────────────────────────────────────────────────┤
+│ | "[" EXPRESSION "]" │
+├────────────────────────────────────────────────┤
+│ | "(" EXPRESSION ")" │
+├────────────────────────────────────────────────┤
+│ | "{" EXPRESSION "}" . │
+├────────────────────────────────────────────────┤
+│IDENTIFIER = letter { letter } . │
+├────────────────────────────────────────────────┤
+│LITERAL = """" character { character } """" .│
+└────────────────────────────────────────────────┘
+```
+
+[code block render hook]: /render-hooks/code-blocks/
+[embedded code block render hook]: <{{% eturl render-codeblock-goat %}}>
+[GoAT]: https://github.com/bep/goat
diff --git a/documents/markdown/hugo-docs/en_content-management_formats.md b/documents/markdown/hugo-docs/en_content-management_formats.md
new file mode 100644
index 0000000..0f9fe7f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_content-management_formats.md
@@ -0,0 +1,133 @@
+---
+title: Content formats
+description: Create your content using Markdown, HTML, Emacs Org Mode, AsciiDoc, Pandoc, or reStructuredText.
+categories: []
+keywords: []
+aliases: [/content/markdown-extras/,/content/supported-formats/,/doc/supported-formats/]
+---
+
+## Introduction
+
+You may mix content formats throughout your site. For example:
+
+```text
+content/
+└── posts/
+ ├── post-1.md
+ ├── post-2.adoc
+ ├── post-3.org
+ ├── post-4.pandoc
+ ├── post-5.rst
+ └── post-6.html
+```
+
+Regardless of content format, all content must have [front matter], preferably including both `title` and `date`.
+
+Hugo selects the content renderer based on the `markup` identifier in front matter, falling back to the file extension. See the [classification] table below for a list of markup identifiers and recognized file extensions.
+
+[classification]: #classification
+[front matter]: /content-management/front-matter/
+
+## Formats
+
+### Markdown
+
+Create your content in [Markdown] preceded by front matter.
+
+Markdown is Hugo's default content format. Hugo natively renders Markdown to HTML using [Goldmark]. Goldmark is fast and conforms to the [CommonMark] and [GitHub Flavored Markdown] specifications. You can configure Goldmark in your [project configuration][configure goldmark].
+
+Hugo provides custom Markdown features including:
+
+[Attributes]
+: Apply HTML attributes such as `class` and `id` to Markdown images and block elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables.
+
+[Extensions]
+: Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more.
+
+[Mathematics]
+: Include mathematical equations and expressions in Markdown using LaTeX markup.
+
+[Render hooks]
+: Override the conversion of Markdown to HTML when rendering fenced code blocks, headings, images, and links. For example, render every standalone image as an HTML `figure` element.
+
+[Attributes]: /content-management/markdown-attributes/
+[CommonMark]: https://spec.commonmark.org/current/
+[Extensions]: /configuration/markup/#extensions
+[GitHub Flavored Markdown]: https://github.github.com/gfm/
+[Goldmark]: https://github.com/yuin/goldmark
+[Markdown]: https://daringfireball.net/projects/markdown/
+[Mathematics]: /content-management/mathematics/
+[Render hooks]: /render-hooks/introduction/
+[configure goldmark]: /configuration/markup/#goldmark
+
+### HTML
+
+Create your content in [HTML] preceded by front matter. The content is typically what you would place within an HTML document's `body` or `main` element.
+
+[HTML]: https://developer.mozilla.org/en-US/docs/Learn_web_development/Getting_started/Your_first_website/Creating_the_content
+
+### Emacs Org Mode
+
+Create your content in the [Emacs Org Mode] format preceded by front matter. You can use Org Mode keywords for front matter. See [details].
+
+[details]: /content-management/front-matter/#emacs-org-mode
+[Emacs Org Mode]: https://orgmode.org/
+
+### AsciiDoc
+
+Create your content in the [AsciiDoc] format preceded by front matter. Hugo renders AsciiDoc content to HTML using the Asciidoctor executable. You must install Asciidoctor and its dependencies (Ruby) to render the AsciiDoc content format.
+
+You can configure the AsciiDoc renderer in your [project configuration][configure asciidoc].
+
+In its default configuration, Hugo passes these CLI flags when calling the Asciidoctor executable:
+
+```text
+--no-header-footer
+```
+
+The CLI flags passed to the Asciidoctor executable depend on configuration. You may inspect the flags when building your project:
+
+```text
+hugo build --logLevel info
+```
+
+[AsciiDoc]: https://asciidoc.org/
+[configure asciidoc]: /configuration/markup/#asciidoc
+
+### Pandoc
+
+Create your content in the [Pandoc] format[^1] preceded by front matter. Hugo renders Pandoc content to HTML using the Pandoc executable. You must install Pandoc to render the Pandoc content format.
+
+[^1]: This is a derivation of the Markdown format as described by the CommonMark specification.
+
+Hugo passes these CLI flags when calling the Pandoc executable:
+
+```text
+--mathjax
+```
+
+[Pandoc]: https://pandoc.org/MANUAL.html#pandocs-markdown
+
+### reStructuredText
+
+Create your content in the [reStructuredText] format preceded by front matter. Hugo renders reStructuredText content to HTML using [Docutils], specifically rst2html. You must install Docutils and its dependencies (Python) to render the reStructuredText content format.
+
+Hugo passes these CLI flags when calling the rst2html executable:
+
+```text
+--leave-comments --initial-header-level=2
+```
+
+[Docutils]: https://docutils.sourceforge.io/
+[reStructuredText]: https://docutils.sourceforge.io/rst.html
+
+## Classification
+
+{{% include "/_common/content-format-table.md" %}}
+
+When converting content to HTML, Hugo uses:
+
+- Native renderers for Markdown, HTML, and Emacs Org mode
+- External renderers for AsciiDoc, Pandoc, and reStructuredText
+
+Native renderers are faster than external renderers.
diff --git a/documents/markdown/hugo-docs/en_content-management_front-matter.md b/documents/markdown/hugo-docs/en_content-management_front-matter.md
new file mode 100644
index 0000000..bcb40b0
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_content-management_front-matter.md
@@ -0,0 +1,379 @@
+---
+title: Front matter
+description: Use front matter to add metadata to your content.
+categories: []
+keywords: []
+aliases: [/content/front-matter/]
+---
+
+## Overview
+
+The front matter at the top of each content file is metadata that:
+
+- Describes the content
+- Augments the content
+- Establishes relationships with other content
+- Controls the published structure of your site
+- Determines template selection
+
+Provide front matter using a serialization format, one of [JSON], [TOML], or [YAML]. Hugo determines the front matter format by examining the delimiters that separate the front matter from the page content.
+
+See examples of front matter delimiters by toggling between the serialization formats below.
+
+{{< code-toggle file=content/example.md fm=true >}}
+title = 'Example'
+date = 2024-02-02T04:14:54-08:00
+draft = false
+weight = 10
+[params]
+author = 'John Smith'
+{{< /code-toggle >}}
+
+Front matter fields may be [boolean](g), [integer](g), [float](g), [string](g), [arrays](g), or [maps](g). Note that the TOML format also supports unquoted date/time values.
+
+## Fields
+
+The most common front matter fields are `date`, `draft`, `title`, and `weight`, but you can specify metadata using any of fields below.
+
+> [!note]
+> The field names below are reserved. For example, you cannot create a custom field named `type`. Create custom fields under the `params` key. See the [parameters] section for details.
+
+[parameters]: #parameters
+
+aliases
+: (`[]string`) An array of one or more [page-relative](g) or [site-relative](g) paths that should redirect to the current page. Hugo resolves these to [server-relative](g) URLs during the build process. Access these values from a template using the [`Aliases`] method on a `Page` object. See the [aliases] section for details.
+
+build
+: (`map`) A map of [build options].
+
+cascade
+: (`map`) A map (or a slice of maps) of front matter keys whose values are passed down to the page's descendants unless overwritten by self or a closer ancestor's cascade. See the [cascade] section for details.
+
+date
+: (`string`) The date associated with the page, typically the creation date. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`Date`] method on a `Page` object.
+
+description
+: (`string`) Conceptually different than the page `summary`, the description is typically rendered within a `meta` element within the `head` element of the published HTML file. Access this value from a template using the [`Description`] method on a `Page` object.
+
+draft
+: (`bool`) Whether to disable rendering unless you pass the `--buildDrafts` flag to the `hugo` command. Access this value from a template using the [`Draft`] method on a `Page` object.
+
+expiryDate
+: (`string`) The page expiration date. On or after the expiration date, the page will not be rendered unless you pass the `--buildExpired` flag to the `hugo` command. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`ExpiryDate`] method on a `Page` object.
+
+headless
+: (`bool`) Applicable to [leaf bundles], whether to set the `render` and `list` [build options] to `never`, creating a headless bundle of [page resources].
+
+isCJKLanguage
+: (`bool`) Whether the content language is in the [CJK](g) family. This value determines how Hugo calculates word count, and affects the values returned by the [`WordCount`], [`FuzzyWordCount`], [`ReadingTime`], and [`Summary`] methods on a `Page` object.
+
+keywords
+: (`[]string`) An array of keywords, typically rendered within a `meta` element within the `head` element of the published HTML file, or used as a [taxonomy](g) to classify content. Access these values from a template using the [`Keywords`] method on a `Page` object.
+
+lastmod
+: (`string`) The date that the page was last modified. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`Lastmod`] method on a `Page` object.
+
+layout
+: (`string`) Provide a template name to [target a specific template], overriding the default [template lookup order]. Set the value to the base file name of the template, excluding its extension. Access this value from a template using the [`Layout`] method on a `Page` object.
+
+linkTitle
+: (`string`) Typically a shorter version of the `title`. Access this value from a template using the [`LinkTitle`] method on a `Page` object.
+
+markup
+: (`string`) An identifier corresponding to one of the supported [content formats]. If not provided, Hugo determines the content renderer based on the file extension.
+
+menus
+: (`string`, `[]string`, or `map`) If set, Hugo adds the page to the given menu or menus. See the [menus] page for details.
+
+modified
+: Alias to [lastmod](#lastmod).
+
+outputs
+: (`[]string`) The [output formats] to render. See [configure outputs] for more information.
+
+params
+: (`map`) A map of custom [page parameters].
+
+pubdate
+: Alias to [publishDate](#publishdate).
+
+publishDate
+: (`string`) The page publication date. Before the publication date, the page will not be rendered unless you pass the `--buildFuture` flag to the `hugo` command. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`PublishDate`] method on a `Page` object.
+
+published
+: Alias to [publishDate](#publishdate).
+
+resources
+: (`map array`) An array of maps to provide metadata for [page resources].
+
+sitemap
+: (`map`) A map of sitemap options. See the [sitemap templates] page for details. Access these values from a template using the [`Sitemap`] method on a `Page` object.
+
+sites
+: {{< new-in 0.153.0 />}}
+: (`map`) A map to define [sites matrix](g) and [sites complements](g) for the page.
+
+ <!-- markdownlint-disable MD049 -->
+
+ {{< code-toggle file=content/_index.md fm=true >}}
+ title = 'Home'
+ [sites.matrix]
+ languages = ["en","fr"]
+ versions = ["v1.2.*","v2.*.*"]
+ roles = ["**"]
+ [sites.complements]
+ versions = ["v3.*.*"]
+ {{< /code-toggle >}}
+
+ <!-- markdownlint-enable MD049 -->
+
+slug
+: (`string`) Overrides the last segment of the URL path. Not applicable to `home`, `section`, `taxonomy`, or `term` pages. See the [URL management] page for details. Access this value from a template using the [`Slug`] method on a `Page` object.
+
+summary
+: (`string`) Conceptually different than the page `description`, the summary either summarizes the content or serves as a teaser to encourage readers to visit the page. Access this value from a template using the [`Summary`] method on a `Page` object.
+
+title
+: (`string`) The page title. Access this value from a template using the [`Title`] method on a `Page` object.
+
+translationKey
+: (`string`) An arbitrary value used to relate two or more translations of the same page, useful when the translated pages do not share a common path. Access this value from a template using the [`TranslationKey`] method on a `Page` object.
+
+type
+: (`string`) The [content type](g), overriding the value derived from the top-level section in which the page resides. Access this value from a template using the [`Type`] method on a `Page` object.
+
+unpublishdate
+: Alias to [expirydate](#expirydate).
+
+url
+: (`string`) Overrides the entire URL path. Applicable to regular pages and section pages. See the [URL management] page for details.
+
+weight
+: (`int`) The page [weight](g), used to order the page within a [page collection](g). Access this value from a template using the [`Weight`] method on a `Page` object.
+
+## Parameters
+
+Specify custom page parameters under the `params` key in front matter:
+
+{{< code-toggle file=content/example.md fm=true >}}
+title = 'Example'
+date = 2024-02-02T04:14:54-08:00
+draft = false
+weight = 10
+[params]
+author = 'John Smith'
+{{< /code-toggle >}}
+
+Access these values from a template using the [`Params`] or [`Param`] method on a `Page` object.
+
+Hugo provides [embedded templates] to optionally insert meta data within the `head` element of your rendered pages. These embedded templates expect the following front matter parameters:
+
+Parameter|Data type|Used by these embedded templates
+:--|:--|:--
+`audio`|`[]string`|[`opengraph.html`]
+`images`|`[]string`|[`opengraph.html`], [`schema.html`], [`twitter_cards.html`]
+`videos`|`[]string`|[`opengraph.html`]
+
+The embedded templates will skip a parameter if not provided in front matter, but will throw an error if the data type is unexpected.
+
+## Taxonomies
+
+Classify content by adding taxonomy terms to front matter. For example, with this project configuration:
+
+{{< code-toggle file=hugo >}}
+[taxonomies]
+tag = 'tags'
+genre = 'genres'
+{{< /code-toggle >}}
+
+Add taxonomy terms as shown below:
+
+{{< code-toggle file=content/example.md fm=true >}}
+title = 'Example'
+date = 2024-02-02T04:14:54-08:00
+draft = false
+weight = 10
+tags = ['red','blue']
+genres = ['mystery','romance']
+[params]
+author = 'John Smith'
+{{< /code-toggle >}}
+
+You can add taxonomy terms to the front matter of any these [page kinds](g):
+
+- `home`
+- `page`
+- `section`
+- `taxonomy`
+- `term`
+
+Access taxonomy terms from a template using the [`Params`] or [`GetTerms`] method on a `Page` object. For example:
+
+```go-html-template {file="layouts/page.html"}
+{{ with .GetTerms "tags" }}
+ <p>Tags</p>
+ <ul>
+ {{ range . }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+[`GetTerms`]: /methods/page/getterms/
+
+## Cascade
+
+A [node](g) can cascade front matter values to its descendants. However, this cascading will be prevented if the descendant already defines the field, or if a closer ancestor node has already cascaded a value for that same field.
+
+For example, to cascade a "color" parameter from the home page to all its descendants:
+
+{{< code-toggle file=content/_index.md fm=true >}}
+title = 'Home'
+[cascade.params]
+color = 'red'
+{{< /code-toggle >}}
+
+{{< new-in 0.153.0 />}}
+From Hugo 0.153.0, you can also set the [sites](#sites) front matter as cascade front matter values, which means that you can e.g. apply one or more languages to the `target` pages.
+
+### Target
+
+<!-- TODO
+We deprecated the `_target` front matter key in favor of `target` in v0.156.0 on 2026-02-17. Remove footnote #1 on or after 2027-05-17 (15 months after deprecation).
+-->
+
+The `target`[^1] keyword allows you to target specific pages or [environments](g). For example, to cascade a "color" parameter from the home page only to pages within the "articles" section, including the "articles" section page itself:
+
+[^1]: The `_target` alias for `target` is deprecated and will be removed in a future release.
+
+{{< code-toggle file=content/_index.md fm=true >}}
+title = 'Home'
+[cascade.params]
+color = 'red'
+[cascade.target]
+path = '{/articles,/articles/**}'
+[cascade.target.sites.matrix]
+languages = ['en','fr']
+{{< /code-toggle >}}
+
+Use any combination of these keywords to target pages and/or environments:
+
+environment
+: (`string`) A [glob pattern](g) matching the build [environment](g). For example: `{staging,production}`.
+
+kind
+: (`string`) A [glob pattern](g) matching the [page kind](g). For example: `{taxonomy,term}`.
+
+path
+: (`string`) A [glob pattern](g) matching the page's [logical path](g). For example: `{/books,/books/**}`.
+
+sites
+: {{< new-in 0.153.0 />}}
+: (`map`) A map to define [sites matrix](g) for the target, as in: Which sites should receive the cascaded values.
+
+### Array
+
+Define an array of cascade parameters to apply different values to different targets. For example:
+
+{{< code-toggle file=content/_index.md fm=true >}}
+title = 'Home'
+[[cascade]]
+[cascade.params]
+color = 'red'
+[cascade.target]
+path = '{/books/**}'
+kind = 'page'
+[[cascade]]
+[cascade.params]
+color = 'blue'
+[cascade.target]
+path = '{/films/**}'
+kind = 'page'
+{{< /code-toggle >}}
+
+> [!note]
+> For multilingual projects, defining cascade values in your project configuration is often more efficient. This avoids repeating the same cascade values on the home, section, taxonomy, or term page for each language. See [details](/configuration/cascade/).
+>
+> If you choose to define cascade values in front matter for a multilingual project, you must create a corresponding home, section, taxonomy, or term page for every language.
+
+## Emacs Org Mode
+
+If your [content format] is [Emacs Org Mode], you may provide front matter using Org Mode keywords. For example:
+
+```text {file="content/example.org"}
+#+TITLE: Example
+#+DATE: 2024-02-02T04:14:54-08:00
+#+DRAFT: false
+#+AUTHOR: John Smith
+#+GENRES: mystery
+#+GENRES: romance
+#+TAGS: red
+#+TAGS: blue
+#+WEIGHT: 10
+```
+
+Note that you can also specify array elements on a single line:
+
+```text {file="content/example.org"}
+#+TAGS[]: red blue
+```
+
+[content format]: /content-management/formats/
+[emacs org mode]: https://orgmode.org/
+
+## Dates
+
+When populating a date field, whether a [custom page parameter](#parameters) or one of the four predefined fields ([`date`](#date), [`expiryDate`](#expirydate), [`lastmod`](#lastmod), [`publishDate`](#publishdate)), use one of these parsable formats:
+
+{{% include "/_common/parsable-date-time-strings.md" %}}
+
+To override the default time zone, set the [`timeZone`](/configuration/all/#timezone) in your project configuration. The order of precedence for determining the time zone is:
+
+1. The time zone offset in the date/time string
+1. The time zone specified in your project configuration
+1. The `Etc/UTC` time zone
+
+[`aliases`]: /methods/page/aliases/
+[`date`]: /methods/page/date/
+[`description`]: /methods/page/description/
+[`draft`]: /methods/page/draft/
+[`expirydate`]: /methods/page/expirydate/
+[`fuzzywordcount`]: /methods/page/wordcount/
+[`keywords`]: /methods/page/keywords/
+[`lastmod`]: /methods/page/date/
+[`layout`]: /methods/page/layout/
+[`linktitle`]: /methods/page/linktitle/
+[`opengraph.html`]: <{{% eturl opengraph %}}>
+[`Param`]: /methods/page/param/
+[`Params`]: /methods/page/params/
+[`publishdate`]: /methods/page/publishdate/
+[`readingtime`]: /methods/page/readingtime/
+[`schema.html`]: <{{% eturl schema %}}>
+[`sitemap`]: /methods/page/sitemap/
+[`slug`]: /methods/page/slug/
+[`Summary`]: /methods/page/summary/
+[`title`]: /methods/page/title/
+[`translationkey`]: /methods/page/translationkey/
+[`twitter_cards.html`]: <{{% eturl twitter_cards %}}>
+[`type`]: /methods/page/type/
+[`weight`]: /methods/page/weight/
+[`wordcount`]: /methods/page/wordcount/
+[aliases]: /content-management/urls/#aliases
+[build options]: /content-management/build-options/
+[cascade]: #cascade-1
+[configure outputs]: /configuration/outputs/#outputs-per-page
+[content formats]: /content-management/formats/#classification
+[embedded templates]: /templates/embedded/
+[json]: https://www.json.org/
+[leaf bundles]: /content-management/page-bundles/#leaf-bundles
+[menus]: /content-management/menus/#define-in-front-matter
+[output formats]: /configuration/output-formats/
+[page parameters]: #parameters
+[page resources]: /content-management/page-resources/#metadata
+[sitemap templates]: /templates/sitemap/
+[target a specific template]: /templates/lookup-order/#target-a-template
+[template lookup order]: /templates/lookup-order/
+[toml]: https://toml.io/
+[URL management]: /content-management/urls/#slug
+[yaml]: https://yaml.org/
diff --git a/documents/markdown/hugo-docs/en_content-management_image-processing_index.md b/documents/markdown/hugo-docs/en_content-management_image-processing_index.md
new file mode 100644
index 0000000..173f3b3
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_content-management_image-processing_index.md
@@ -0,0 +1,169 @@
+---
+title: Image processing
+description: Transform images to change their size, shape, and appearance.
+categories: []
+keywords: []
+---
+
+Hugo provides methods to transform and analyze images during the build process. While Hugo can manage any image format as a resource, only [processable images](g) can be transformed using the methods below. The results are cached to ensure subsequent builds remain fast.
+
+> [!note]
+> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
+
+## Resources
+
+To process an image you must capture the file as a page resource, a global resource, or a remote resource.
+
+### Page
+
+{{% glossary-term "page resource" %}}
+
+```text
+content/
+└── posts/
+ └── post-1/ <-- page bundle
+ ├── index.md
+ └── sunset.jpg <-- page resource
+```
+
+To capture an image as a page resource:
+
+```go-html-template
+{{ $image := .Resources.Get "sunset.jpg" }}
+```
+
+### Global
+
+{{% glossary-term "global resource" %}}
+
+```text
+assets/
+└── images/
+ └── sunset.jpg <-- global resource
+```
+
+To capture an image as a global resource:
+
+```go-html-template
+{{ $image := resources.Get "images/sunset.jpg" }}
+```
+
+### Remote
+
+{{% glossary-term "remote resource" %}}
+
+To capture an image as a remote resource:
+
+```go-html-template
+{{ $image := resources.GetRemote "https://gohugo.io/img/hugo-logo.png" }}
+```
+
+## Rendering
+
+Once you have captured an image as a resource, render it in your templates using the [`Permalink`][], [`RelPermalink`][], [`Width`][], and [`Height`][] methods.
+
+Example 1: Throw an error if the resource is not found.
+
+```go-html-template
+{{ $image := .Resources.GetMatch "sunset.jpg" }}
+<img src="{{ $image.RelPermalink }}" width="{{ $image.Width }}" height="{{ $image.Height }}">
+```
+
+Example 2: Skip image rendering if the resource is not found.
+
+```go-html-template
+{{ $image := .Resources.GetMatch "sunset.jpg" }}
+{{ with $image }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+{{ end }}
+```
+
+Example 3: A more concise way to skip image rendering if the resource is not found.
+
+```go-html-template
+{{ with .Resources.GetMatch "sunset.jpg" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+{{ end }}
+```
+
+Example 4: Skip rendering if there's problem accessing a remote resource.
+
+```go-html-template
+{{ $url := "https://gohugo.io/img/hugo-logo.png" }}
+{{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else with .Value }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+ {{ end }}
+{{ end }}
+```
+
+{{% include "/_common/functions/reflect/image-reflection-functions.md" %}}
+
+## Processing
+
+To transform an image, apply a processing method to the image resource. Hugo generates the processed image on demand, caches the result, and returns a new resource object.
+
+```go-html-template
+{{ with .Resources.Get "sunset.jpg" }}
+ {{ with .Resize "400x" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+ {{ end }}
+{{ end }}
+```
+
+> [!note]
+> Metadata is not preserved during image transformation. Use the [`Meta`][] method with the original image resource to extract metadata from supported formats.
+
+Select a method from the table below for syntax and usage examples, depending on your specific transformation or metadata requirements:
+
+{{% render-table-of-pages-in-section
+ path=/methods/resource
+ filter=methods_resource_image_processing
+ filterType=include
+ headingColumn1=Method
+ headingColumn2=Description
+%}}{class="!mt-0"}
+
+## Performance
+
+### Caching
+
+Hugo processes images on demand and returns a new resource object. To ensure subsequent builds remain fast, Hugo caches the results in the directory specified in the [file cache][] section of your project configuration.
+
+If you host your site with Netlify, include the following in your project configuration to persist the image cache between builds:
+
+```toml
+[caches]
+ [caches.images]
+ dir = ':cacheDir/images'
+```
+
+### Garbage collection
+
+If you change image processing methods, or rename/remove images, the cache will eventually contain unused files. To remove them and reclaim disk space, run Hugo's garbage collection:
+
+```text
+hugo build --gc
+```
+
+### Resource usage
+
+The time and memory required to process an image increase with the image's dimensions. For example, a `4032x2268` image requires significantly more memory and processing time than a `1920x1080` image.
+
+If your source images are much larger than the maximum size you intend to publish, consider scaling them down before the build to optimize performance.
+
+## Configuration
+
+See [configure imaging](/configuration/imaging).
+
+[`Height`]: /methods/resource/height/
+[`Meta`]: /methods/resource/meta/
+[`Permalink`]: /methods/resource/permalink/
+[`RelPermalink`]: /methods/resource/relpermalink/
+[`Width`]: /methods/resource/width/
+[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
+[file cache]: /configuration/caches/
diff --git a/documents/markdown/hugo-docs/en_content-management_markdown-attributes.md b/documents/markdown/hugo-docs/en_content-management_markdown-attributes.md
new file mode 100644
index 0000000..42e7bcf
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_content-management_markdown-attributes.md
@@ -0,0 +1,117 @@
+---
+title: Markdown attributes
+description: Use Markdown attributes to add HTML attributes when rendering Markdown to HTML.
+categories: []
+keywords: []
+---
+
+## Overview
+
+Hugo supports Markdown attributes on images and block elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables.
+
+For example:
+
+```text
+This is a paragraph.
+{class="foo bar" id="baz"}
+```
+
+With `class` and `id` attributes you can also use short-form notation:
+
+```text
+This is a paragraph.
+{.foo .bar #baz}
+```
+
+Hugo renders both of the examples above to:
+
+```html
+<p class="foo bar" id="baz">This is a paragraph.</p>
+```
+
+With `class` and `id` attributes, whether you use long-form or short-form notation, the resulting values are available in [render hook templates][] via the `Attributes` method. For example:
+
+```go-html-template
+{{ .Attributes.class }} → foo bar
+{{ .Attributes.id }} → baz
+```
+
+## Block elements
+
+Update your project configuration to enable Markdown attributes for block-level elements.
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.parser.attribute]
+title = true # default is true
+block = true # default is false
+{{< /code-toggle >}}
+
+## Standalone images
+
+By default, when the [Goldmark] Markdown renderer encounters a standalone image element (no other elements or text on the same line), it wraps the image element within a paragraph element per the [CommonMark specification].
+
+[CommonMark specification]: https://spec.commonmark.org/current/
+[Goldmark]: https://github.com/yuin/goldmark
+
+If you were to place an attribute list beneath an image element, Hugo would apply the attributes to the surrounding paragraph, not the image.
+
+To apply attributes to a standalone image element, you must disable the default wrapping behavior:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.parser]
+wrapStandAloneImageWithinParagraph = false # default is true
+{{< /code-toggle >}}
+
+## Usage
+
+You may add [global HTML attributes], or HTML attributes specific to the current element type. Consistent with its content security model, Hugo removes HTML event attributes such as `onclick` and `onmouseover`.
+
+[global HTML attributes]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes
+
+The attribute list consists of one or more key-value pairs, separated by spaces or commas, wrapped by braces. You must quote string values that contain spaces. Unlike HTML, boolean attributes must have both key and value.
+
+For example:
+
+```text
+> This is a blockquote.
+{class="foo bar" hidden=hidden}
+```
+
+Hugo renders this to:
+
+```html
+<blockquote class="foo bar" hidden="hidden">
+ <p>This is a blockquote.</p>
+</blockquote>
+```
+
+In most cases, place the attribute list beneath the markup element. For headings and fenced code blocks, place the attribute list on the right.
+
+Element|Position of attribute list
+:--|:--
+blockquote|bottom
+fenced code block|right
+heading|right
+horizontal rule|bottom
+image|bottom
+list|bottom
+paragraph|bottom
+table|bottom
+
+For example:
+
+````text
+## Section 1 {class=foo}
+
+```sh {class=foo linenos=inline}
+declare a=1
+echo "${a}"
+```
+
+This is a paragraph.
+{class=foo}
+````
+
+As shown above, the attribute list for fenced code blocks is not limited to HTML attributes. You can also configure syntax highlighting by passing one or more of [these options](/functions/transform/highlight/#options).
+
+[render hook templates]: /render-hooks/introduction/
diff --git a/documents/markdown/hugo-docs/en_content-management_mathematics.md b/documents/markdown/hugo-docs/en_content-management_mathematics.md
new file mode 100644
index 0000000..6b86cac
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_content-management_mathematics.md
@@ -0,0 +1,237 @@
+---
+title: Mathematics in Markdown
+linkTitle: Mathematics
+description: Include mathematical equations and expressions in Markdown using LaTeX markup.
+categories: []
+keywords: []
+---
+
+## Overview
+
+Mathematical equations and expressions written in [LaTeX][] are common in academic and scientific publications. Your browser typically renders this mathematical markup using an open-source JavaScript display engine such as [MathJax][] or [KaTeX][].
+
+For example, this LaTeX markup:
+
+```text
+\[
+\begin{aligned}
+KL(\hat{y} || y) &= \sum_{c=1}^{M}\hat{y}_c \log{\frac{\hat{y}_c}{y_c}} \\
+JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y+\hat{y}}{2}))
+\end{aligned}
+\]
+```
+
+Is rendered to:
+
+\[
+\begin{aligned}
+KL(\hat{y} || y) &= \sum_{c=1}^{M}\hat{y}_c \log{\frac{\hat{y}_c}{y_c}} \\
+JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y+\hat{y}}{2}))
+\end{aligned}
+\]
+
+Equations and expressions can be displayed inline with other text, or as standalone blocks. Block presentation is also known as "display" mode.
+
+Whether an equation or expression appears inline, or as a block, depends on the delimiters that surround the mathematical markup. Delimiters are defined in pairs, where each pair consists of an opening and closing delimiter. The opening and closing delimiters may be the same, or different.
+
+> [!note]
+> You can configure Hugo to render mathematical markup on the client side using the MathJax or KaTeX display engine, or you can render the markup with the [`transform.ToMath`][] function while building your project.
+>
+> The first approach is described below.
+
+## Setup
+
+Follow these instructions to include mathematical equations and expressions in your Markdown using LaTeX markup.
+
+Step 1
+: Enable and configure the Goldmark [passthrough extension][] in your project configuration. The passthrough extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves.
+
+ {{< code-toggle file=hugo copy=true >}}
+ [markup.goldmark.extensions.passthrough]
+ enable = true
+
+ [markup.goldmark.extensions.passthrough.delimiters]
+ block = [['\[', '\]'], ['$$', '$$']]
+ inline = [['\(', '\)']]
+
+ [params]
+ math = true
+ {{< /code-toggle >}}
+
+ The configuration above enables mathematical rendering on every page unless you set the `math` parameter to `false` in front matter. To enable mathematical rendering as needed, set the `math` parameter to `false` in your project configuration, and set the `math` parameter to `true` in front matter. Use this parameter in your base template as shown in [Step 3][].
+
+ > [!note]
+ > The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration and JavaScript, you must double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting.
+ >
+ > See the [inline delimiters][] section for details.
+
+ To disable passthrough of inline snippets, omit the `inline` key from the configuration:
+
+ {{< code-toggle file=hugo >}}
+ [markup.goldmark.extensions.passthrough.delimiters]
+ block = [['\[', '\]'], ['$$', '$$']]
+ {{< /code-toggle >}}
+
+ You can define your own opening and closing delimiters, provided they match the delimiters that you set in [Step 2][].
+
+ {{< code-toggle file=hugo >}}
+ [markup.goldmark.extensions.passthrough.delimiters]
+ block = [['@@', '@@']]
+ inline = [['@', '@']]
+ {{< /code-toggle >}}
+
+Step 2
+: Create a _partial_ template to load MathJax or KaTeX. The example below loads MathJax, or you can use KaTeX as described in the [engines][] section.
+
+ ```go-html-template {file="layouts/_partials/math.html" copy=true}
+ <script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@4/tex-mml-chtml.js"></script>
+
+ <script>
+ MathJax = {
+ tex: {
+ displayMath: [['\\[', '\\]'], ['$$', '$$']], // block
+ inlineMath: [['\\(', '\\)']] // inline
+ },
+ loader:{
+ load: ['ui/safe']
+ },
+ };
+ </script>
+ ```
+
+ The delimiters above must match the delimiters in your project configuration.
+
+Step 3
+: Conditionally call the _partial_ template from the base template.
+
+ ```go-html-template {file="layouts/baseof.html"}
+ <head>
+ ...
+ {{ if .Param "math" }}
+ {{ partialCached "math.html" . }}
+ {{ end }}
+ ...
+ </head>
+ ```
+
+ The example above loads the _partial_ template if you have set the `math` parameter in front matter to `true`. If you have not set the `math` parameter in front matter, the conditional statement falls back to the `math` parameter in your project configuration.
+
+Step 4
+: If you set the `math` parameter to `false` in your project configuration, you must set the `math` parameter to `true` in front matter. For example:
+
+ {{< code-toggle file=content/math-examples.md fm=true >}}
+ title = 'Math examples'
+ date = 2024-01-24T18:09:49-08:00
+ [params]
+ math = true
+ {{< /code-toggle >}}
+
+Step 5
+: Include mathematical equations and expressions in Markdown using LaTeX markup.
+
+ ```text {file="content/math-examples.md" copy=true}
+ This is an inline \(a^*=x-b^*\) equation.
+
+ These are block equations:
+
+ \[a^*=x-b^*\]
+
+ \[ a^*=x-b^* \]
+
+ \[
+ a^*=x-b^*
+ \]
+
+ These are also block equations:
+
+ $$a^*=x-b^*$$
+
+ $$ a^*=x-b^* $$
+
+ $$
+ a^*=x-b^*
+ $$
+ ```
+
+## Inline delimiters
+
+The configuration, JavaScript, and examples above use the `\(...\)` delimiter pair for inline equations. The `$...$` delimiter pair is a common alternative, but using it may result in unintended formatting if you use the `$` symbol outside of math contexts.
+
+If you add the `$...$` delimiter pair to your configuration and JavaScript, you must double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting. For example:
+
+```text
+I will give you \\$2 if you can solve $y = x^2$.
+```
+
+> [!note]
+> If you use the `$...$` delimiter pair for inline equations, and occasionally use the `$` symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by [this KaTeX limitation][].
+
+## Engines
+
+MathJax and KaTeX are open-source JavaScript display engines.
+
+> [!note]
+> If you use the `$...$` delimiter pair for inline equations, and occasionally use the `$` symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by [this KaTeX limitation][].
+>
+>See the [inline delimiters][] section for details.
+
+To use KaTeX instead of MathJax, replace the _partial_ template from [Step 2][] with this:
+
+```go-html-template {file="layouts/_partials/math.html" copy=true}
+<link
+ rel="stylesheet"
+ href="https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.css"
+ integrity="sha384-WcoG4HRXMzYzfCgiyfrySxx90XSl2rxY5mnVY5TwtWE6KLrArNKn0T/mOgNL0Mmi"
+ crossorigin="anonymous"
+>
+<script
+ defer
+ src="https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.js"
+ integrity="sha384-J+9dG2KMoiR9hqcFao0IBLwxt6zpcyN68IgwzsCSkbreXUjmNVRhPFTssqdSGjwQ"
+ crossorigin="anonymous">
+</script>
+<script
+ defer
+ src="https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/contrib/auto-render.min.js"
+ integrity="sha384-hCXGrW6PitJEwbkoStFjeJxv+fSOOQKOPbJxSfM6G5sWZjAyWhXiTIIAmQqnlLlh"
+ crossorigin="anonymous"
+ onload="renderMathInElement(document.body);">
+</script>
+<script>
+ document.addEventListener("DOMContentLoaded", function() {
+ renderMathInElement(document.body, {
+ delimiters: [
+ {left: '\\[', right: '\\]', display: true}, // block
+ {left: '$$', right: '$$', display: true}, // block
+ {left: '\\(', right: '\\)', display: false}, // inline
+ ],
+ throwOnError : false
+ });
+ });
+</script>
+```
+
+The delimiters above must match the delimiters in your project configuration.
+
+## Chemistry
+
+Both MathJax and KaTeX provide support for chemical equations. For example:
+
+```text
+$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$
+```
+
+$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$
+
+As shown in [Step 2][] above, MathJax supports chemical equations without additional configuration. To add chemistry support to KaTeX, enable the mhchem extension as described in the KaTeX [documentation](https://katex.org/docs/libs).
+
+[`transform.ToMath`]: /functions/transform/tomath/
+[engines]: #engines
+[inline delimiters]: #inline-delimiters
+[KaTeX]: https://katex.org/
+[LaTeX]: https://www.latex-project.org/
+[MathJax]: https://www.mathjax.org/
+[passthrough extension]: /configuration/markup/#passthrough
+[Step 2]: #step-2
+[Step 3]: #step-3
+[this KaTeX limitation]: https://github.com/KaTeX/KaTeX/issues/437
diff --git a/documents/markdown/hugo-docs/en_content-management_menus.md b/documents/markdown/hugo-docs/en_content-management_menus.md
new file mode 100644
index 0000000..766cad7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_content-management_menus.md
@@ -0,0 +1,99 @@
+---
+title: Menus
+description: Create menus by defining entries, localizing each entry, and rendering the resulting data structure.
+categories: []
+keywords: []
+aliases: [/extras/menus/]
+---
+
+## Overview
+
+To create a menu for your site:
+
+1. Define the menu entries
+1. [Localize](multilingual/#menus) each entry
+1. Render the menu with a [template]
+
+Create multiple menus, either flat or nested. For example, create a main menu for the header, and a separate menu for the footer.
+
+There are three ways to define menu entries:
+
+1. Automatically
+1. In front matter
+1. In your project configuration
+
+> [!note]
+> Although you can use these methods in combination when defining a menu, the menu will be easier to conceptualize and maintain if you use one method throughout the site.
+
+## Define automatically
+
+To automatically define a menu entry for each top-level [section](g) of your site, enable the section pages menu in your project configuration.
+
+{{< code-toggle file=hugo >}}
+sectionPagesMenu = 'main'
+{{< /code-toggle >}}
+
+This creates a menu structure that you can access with `site.Menus.main` in your templates. See [menu templates] for details.
+
+## Define in front matter
+
+To add a page to the "main" menu:
+
+{{< code-toggle file=content/about.md fm=true >}}
+title = 'About'
+menus = 'main'
+{{< /code-toggle >}}
+
+Access the entry with `site.Menus.main` in your templates. See [menu templates] for details.
+
+To add a page to the "main" and "footer" menus:
+
+{{< code-toggle file=content/contact.md fm=true >}}
+title = 'Contact'
+menus = ['main','footer']
+{{< /code-toggle >}}
+
+Access the entry with `site.Menus.main` and `site.Menus.footer` in your templates. See [menu templates] for details.
+
+> [!note]
+> The configuration key in the examples above is `menus`. The `menu` (singular) configuration key is an alias for `menus`.
+
+### Properties
+
+Use these properties when defining menu entries in front matter:
+
+{{% include "/_common/menu-entry-properties.md" %}}
+
+### Example
+
+This front matter menu entry demonstrates some of the available properties:
+
+<!-- markdownlint-disable MD033 -->
+{{< code-toggle file=content/products/software.md fm=true >}}
+title = 'Software'
+[menus.main]
+parent = 'Products'
+weight = 20
+pre = '<i class="fa-solid fa-code"></i>'
+[menus.main.params]
+class = 'center'
+{{< /code-toggle >}}
+<!-- markdownlint-enable MD033 -->
+
+Access the entry with `site.Menus.main` in your templates. See [menu templates] for details.
+
+## Define in project configuration
+
+See [configure menus](/configuration/menus/).
+
+## Localize
+
+Hugo provides two methods to localize your menu entries. See [multilingual].
+
+## Render
+
+See [menu templates].
+
+[menu templates]: /templates/menu/
+[multilingual]: /content-management/multilingual/#menus
+[template]: /templates/menu/
diff --git a/documents/markdown/hugo-docs/en_content-management_multilingual.md b/documents/markdown/hugo-docs/en_content-management_multilingual.md
new file mode 100644
index 0000000..d3904db
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_content-management_multilingual.md
@@ -0,0 +1,395 @@
+---
+title: Multilingual mode
+linkTitle: Multilingual
+description: Localize your project for each language and region, including translations, images, dates, currencies, numbers, percentages, and collation sequence. Hugo's multilingual framework supports single-host and multihost configurations.
+categories: []
+keywords: []
+aliases: [/content/multilingual/,/tutorials/create-a-multilingual-site/]
+---
+
+## Configuration
+
+See [configure languages](/configuration/languages/).
+
+## Translate your content
+
+There are two ways to manage your content translations. Both ensure each page is assigned a language and is linked to its counterpart translations.
+
+### Translation by file name
+
+Considering the following example:
+
+1. `/content/about.en.md`
+1. `/content/about.fr.md`
+
+The first file is assigned the English language and is linked to the second.
+The second file is assigned the French language and is linked to the first.
+
+Their language is assigned according to the language code added as a suffix to the file name.
+
+By having the same path and base file name, the content pieces are linked together as translated pages.
+
+> [!note]
+> If a file has no language code, it will be assigned the default language.
+
+### Translation by content directory
+
+This system uses different content directories for each of the languages. Each language's `content` directory is set using the `contentDir` parameter.
+
+{{< code-toggle file=hugo >}}
+[languages.en]
+contentDir = 'content/english'
+label = "English"
+weight = 10
+
+[languages.fr]
+contentDir = 'content/french'
+label = "Français"
+weight = 20
+{{< /code-toggle >}}
+
+The value of `contentDir` can be any valid path -- even absolute path references. The only restriction is that the content directories cannot overlap.
+
+Considering the following example in conjunction with the configuration above:
+
+1. `/content/english/about.md`
+1. `/content/french/about.md`
+
+The first file is assigned the English language and is linked to the second.
+The second file is assigned the French language and is linked to the first.
+
+Their language is assigned according to the `content` directory they are placed in.
+
+By having the same path and basename (relative to their language `content` directory), the content pieces are linked together as translated pages.
+
+### Bypassing default linking
+
+Any pages sharing the same `translationKey` set in front matter will be linked as translated pages regardless of basename or location.
+
+Considering the following example:
+
+1. `/content/about-us.en.md`
+1. `/content/om.nn.md`
+1. `/content/presentation/a-propos.fr.md`
+
+{{< code-toggle file=hugo >}}
+translationKey: "about"
+{{< /code-toggle >}}
+
+By setting the `translationKey` front matter parameter to `about` in all three pages, they will be linked as translated pages.
+
+### Localizing permalinks
+
+Because paths and file names are used to handle linking, all translated pages will share the same URL (apart from the language subdirectory).
+
+To localize URLs:
+
+- For a regular page, set either [`slug`] or [`url`] in front matter
+- For a section page, set [`url`] in front matter
+
+For example, a French translation can have its own localized slug.
+
+{{< code-toggle file=content/about.fr.md fm=true >}}
+title: A Propos
+slug: "a-propos"
+{{< /code-toggle >}}
+
+At render, Hugo will build both `/about/` and `/fr/a-propos/` without affecting the translation link.
+
+### Page bundles
+
+To avoid the burden of having to duplicate files, each Page Bundle inherits the resources of its linked translated pages' bundles except for the content files (Markdown files, HTML files etc.).
+
+Therefore, from within a template, the page will have access to the files from all linked pages' bundles.
+
+If, across the linked bundles, two or more files share the same basename, only one will be included and chosen as follows:
+
+- File from current language bundle, if present.
+- First file found across bundles by order of language `Weight`.
+
+> [!note]
+> Page Bundle resources follow the same language assignment logic as content files, both by file name (`image.jpg`, `image.fr.jpg`) and by directory (`english/about/header.jpg`, `french/about/header.jpg`).
+
+## Translation of strings
+
+See the [`lang.Translate`] template function.
+
+## Localization
+
+The following localization examples assume your project's primary language is English, with translations to French and German.
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'en'
+
+[languages]
+[languages.en]
+contentDir = 'content/en'
+label = 'English'
+weight = 1
+[languages.fr]
+contentDir = 'content/fr'
+label = 'Français'
+weight = 2
+[languages.de]
+contentDir = 'content/de'
+label = 'Deutsch'
+weight = 3
+
+{{< /code-toggle >}}
+
+### Dates
+
+With this front matter:
+
+{{< code-toggle file=hugo >}}
+date = 2021-11-03T12:34:56+01:00
+{{< /code-toggle >}}
+
+And this template code:
+
+```go-html-template
+{{ .Date | time.Format ":date_full" }}
+```
+
+The rendered page displays:
+
+Language|Value
+:--|:--
+English|Wednesday, November 3, 2021
+Français|mercredi 3 novembre 2021
+Deutsch|Mittwoch, 3. November 2021
+
+See [`time.Format`] for details.
+
+### Currency
+
+With this template code:
+
+```go-html-template
+{{ 512.5032 | lang.FormatCurrency 2 "USD" }}
+```
+
+The rendered page displays:
+
+Language|Value
+:--|:--
+English|$512.50
+Français|512,50 $US
+Deutsch|512,50 $
+
+See [lang.FormatCurrency] and [lang.FormatAccounting] for details.
+
+### Numbers
+
+With this template code:
+
+```go-html-template
+{{ 512.5032 | lang.FormatNumber 2 }}
+```
+
+The rendered page displays:
+
+Language|Value
+:--|:--
+English|512.50
+Français|512,50
+Deutsch|512,50
+
+See [lang.FormatNumber] and [lang.FormatNumberCustom] for details.
+
+### Percentages
+
+With this template code:
+
+```go-html-template
+{{ 512.5032 | lang.FormatPercent 2 }}
+```
+
+The rendered page displays:
+
+Language|Value
+:--|:--
+English|512.50%
+Français|512,50 %
+Deutsch|512,50 %
+
+See [lang.FormatPercent] for details.
+
+## Menus
+
+Localization of menu entries depends on how you define them:
+
+- When you define menu entries [automatically] using the section pages menu, you must use translation tables to localize each entry.
+- When you define menu entries in [front matter], they are already localized based on the front matter itself. If the front matter values are insufficient, use translation tables to localize each entry.
+- When you define menu entries in your [project configuration], you must create language-specific menu entries under each language key. If the names of the menu entries are insufficient, use translation tables to localize each entry.
+
+### Create language-specific menu entries
+
+#### Method 1 -- Use a single configuration file
+
+For a simple menu with a small number of entries, use a single configuration file. For example:
+
+{{< code-toggle file=hugo >}}
+[languages.de]
+label = 'Deutsch'
+locale = 'de-DE'
+weight = 1
+
+[[languages.de.menus.main]]
+name = 'Produkte'
+pageRef = '/products'
+weight = 10
+
+[[languages.de.menus.main]]
+name = 'Leistungen'
+pageRef = '/services'
+weight = 20
+
+[languages.en]
+label = 'English'
+locale = 'en-US'
+weight = 2
+
+[[languages.en.menus.main]]
+name = 'Products'
+pageRef = '/products'
+weight = 10
+
+[[languages.en.menus.main]]
+name = 'Services'
+pageRef = '/services'
+weight = 20
+{{< /code-toggle >}}
+
+#### Method 2 -- Use a configuration directory
+
+With a more complex menu structure, create a [configuration directory] and split the menu entries into multiple files, one file per language. For example:
+
+```text
+config/
+└── _default/
+ ├── menus.de.toml
+ ├── menus.en.toml
+ └── hugo.toml
+```
+
+{{< code-toggle file=config/_default/menus.de >}}
+[[main]]
+name = 'Produkte'
+pageRef = '/products'
+weight = 10
+[[main]]
+name = 'Leistungen'
+pageRef = '/services'
+weight = 20
+{{< /code-toggle >}}
+
+{{< code-toggle file=config/_default/menus.en >}}
+[[main]]
+name = 'Products'
+pageRef = '/products'
+weight = 10
+[[main]]
+name = 'Services'
+pageRef = '/services'
+weight = 20
+{{< /code-toggle >}}
+
+### Use translation tables
+
+When rendering the text that appears in menu each entry, the [example menu template] does this:
+
+```go-html-template
+{{ or (T .Identifier) .Name | safeHTML }}
+```
+
+It queries the translation table for the current language using the menu entry's `identifier` and returns the translated string. If the translation table does not exist, or if the `identifier` key is not present in the translation table, it falls back to `name`.
+
+The `identifier` depends on how you define menu entries:
+
+- If you define the menu entry [automatically] using the section pages menu, the `identifier` is the page's `.Section`.
+- If you define the menu entry in your [project configuration] or in [front matter], set the `identifier` property to the desired value.
+
+For example, if you define menu entries in project configuration:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+ identifier = 'products'
+ name = 'Products'
+ pageRef = '/products'
+ weight = 10
+[[menus.main]]
+ identifier = 'services'
+ name = 'Services'
+ pageRef = '/services'
+ weight = 20
+{{< / code-toggle >}}
+
+Create corresponding entries in the translation tables:
+
+{{< code-toggle file=i18n/de >}}
+products = 'Produkte'
+services = 'Leistungen'
+{{< / code-toggle >}}
+
+## Missing translations
+
+If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown.
+
+While translating a Hugo website, it can be handy to have a visual indicator of missing translations. The [`enableMissingTranslationPlaceholders` configuration option][config] will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation.
+
+> [!note]
+> Hugo will generate your website with these missing translation placeholders. It might not be suitable for production environments.
+
+For merging of content from other languages (i.e. missing content translations), see [lang.Merge].
+
+To track down missing translation strings, run Hugo with the `--printI18nWarnings` flag:
+
+```sh
+hugo build --printI18nWarnings | grep i18n
+i18n|MISSING_TRANSLATION|en|wordCount
+```
+
+## Multilingual themes support
+
+To support Multilingual mode in your themes, some considerations must be taken for the URLs in the templates. If there is more than one language, URLs must meet the following criteria:
+
+- Come from the built-in `.Permalink` or `.RelPermalink`
+- Be constructed with the [`relLangURL`] or [`absLangURL`] template function, or be prefixed with `{{ .LanguagePrefix }}`
+
+If there is more than one language defined, the `LanguagePrefix` method will return `/en` (or whatever the current language is). If not enabled, it will be an empty string (and is therefore harmless for single-language Hugo websites).
+
+## Generate multilingual content with `hugo new content`
+
+If you organize content with translations in the same directory:
+
+```sh
+hugo new content post/test.en.md
+hugo new content post/test.de.md
+```
+
+If you organize content with translations in different directories:
+
+```sh
+hugo new content content/en/post/test.md
+hugo new content content/de/post/test.md
+```
+
+[`absLangURL`]: /functions/urls/abslangurl/
+[`lang.Translate`]: /functions/lang/translate
+[`relLangURL`]: /functions/urls/rellangurl/
+[`slug`]: /content-management/urls/#slug
+[`time.Format`]: /functions/time/format/
+[`url`]: /content-management/urls/#url
+[automatically]: /content-management/menus/#define-automatically
+[config]: /configuration/
+[configuration directory]: /configuration/introduction/#configuration-directory
+[example menu template]: /templates/menu/#example
+[front matter]: /content-management/menus/#define-in-front-matter
+[lang.FormatAccounting]: /functions/lang/formataccounting/
+[lang.FormatCurrency]: /functions/lang/formatcurrency/
+[lang.FormatNumberCustom]: /functions/lang/formatnumbercustom/
+[lang.FormatNumber]: /functions/lang/formatnumber/
+[lang.FormatPercent]: /functions/lang/formatpercent/
+[lang.Merge]: /functions/lang/merge/
+[project configuration]: /content-management/menus/#define-in-project-configuration
diff --git a/documents/markdown/hugo-docs/en_content-management_organization_index.md b/documents/markdown/hugo-docs/en_content-management_organization_index.md
new file mode 100644
index 0000000..5762e0d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_content-management_organization_index.md
@@ -0,0 +1,151 @@
+---
+title: Content organization
+linkTitle: Organization
+description: Hugo assumes that the same structure that works to organize your source content is used to organize the rendered site.
+categories: []
+keywords: []
+aliases: [/content/sections/]
+---
+
+## Page bundles
+
+Hugo supports page-relative images and other resources packaged into `Page Bundles`.
+
+These terms are connected, and you also need to read about [Page Resources](/content-management/page-resources) and [Image Processing](/content-management/image-processing) to get the full picture.
+
+```text
+content/
+├── blog/
+│ ├── hugo-is-cool/
+│ │ ├── images/
+│ │ │ ├── funnier-cat.jpg
+│ │ │ └── funny-cat.jpg
+│ │ ├── cats-info.md
+│ │ └── index.md
+│ ├── posts/
+│ │ ├── post1.md
+│ │ └── post2.md
+│ ├── 1-landscape.jpg
+│ ├── 2-sunset.jpg
+│ ├── _index.md
+│ ├── content-1.md
+│ └── content-2.md
+├── 1-logo.png
+└── _index.md
+```
+
+The file tree above shows three bundles. Note that the home page bundle cannot contain other content pages, although other files (images etc.) are allowed.
+
+## Organization of content source
+
+In Hugo, your content should be organized in a manner that reflects the rendered website.
+
+While Hugo supports content nested at any level, the top levels (i.e. `content/<DIRECTORIES>`) are special in Hugo and are considered the content type used to determine layouts etc. To read more about sections, including how to nest them, see [sections].
+
+Without any additional configuration, the following will automatically work:
+
+```txt
+.
+└── content
+ └── about
+ | └── index.md // <- https://example.org/about/
+ ├── posts
+ | ├── firstpost.md // <- https://example.org/posts/firstpost/
+ | ├── happy
+ | | └── ness.md // <- https://example.org/posts/happy/ness/
+ | └── secondpost.md // <- https://example.org/posts/secondpost/
+ └── quote
+ ├── first.md // <- https://example.org/quote/first/
+ └── second.md // <- https://example.org/quote/second/
+```
+
+## Path breakdown in Hugo
+
+The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseURL = "https://example.org/"` in your [project configuration][config].
+
+### Index pages: `_index.md`
+
+`_index.md` has a special role in Hugo. It allows you to add front matter and content to `home`, `section`, `taxonomy`, and `term` pages.
+
+> [!note]
+> Access the content and metadata within an `_index.md` file by invoking the `GetPage` method on a `Site` or `Page` object.
+
+You can create one `_index.md` for your home page and one in each of your content sections, taxonomies, and terms. The following shows typical placement of an `_index.md` that would contain content and front matter for a `posts` section list page on a Hugo website:
+
+```txt
+. url
+. ⊢--^-⊣
+. path slug
+. ⊢--^-⊣⊢---^---⊣
+. file path
+. ⊢------^------⊣
+content/posts/_index.md
+```
+
+At build, this will output to the following destination with the associated values:
+
+```txt
+
+ url ("/posts/")
+ ⊢-^-⊣
+ baseurl section ("posts")
+⊢--------^---------⊣⊢-^-⊣
+ permalink
+⊢----------^-------------⊣
+https://example.org/posts/index.html
+```
+
+The [sections] can be nested as deeply as you want. The important thing to understand is that to make the section tree fully navigational, at least the lower-most section must include a content file. (i.e. `_index.md`).
+
+### Single pages in sections
+
+Single content files in each of your sections will be rendered by a [page template]. Here is an example of a single `post` within `posts`:
+
+```txt
+ path ("posts/my-first-hugo-post.md")
+. ⊢-----------^------------⊣
+. section slug
+. ⊢-^-⊣⊢--------^----------⊣
+content/posts/my-first-hugo-post.md
+```
+
+When Hugo builds your site, the content will be output to the following destination:
+
+```txt
+
+ url ("/posts/my-first-hugo-post/")
+ ⊢------------^----------⊣
+ baseurl section slug
+⊢--------^--------⊣⊢-^--⊣⊢-------^---------⊣
+ permalink
+⊢--------------------^---------------------⊣
+https://example.org/posts/my-first-hugo-post/index.html
+```
+
+## Paths explained
+
+The following concepts provide more insight into the relationship between your project's organization and the default Hugo behavior when building output for the website.
+
+### `section`
+
+A default content type is determined by the section in which a content item is stored. `section` is determined by the location within the project's `content` directory. `section` cannot be specified or overridden in front matter.
+
+### `slug`
+
+The `slug` is the last segment of the URL path, defined by the file name and optionally overridden by a `slug` value in front matter. See [URL Management](/content-management/urls/#slug) for details.
+
+### `path`
+
+A content's `path` is determined by the section's path to the file. The file `path`:
+
+- Is based on the path to the content's location AND
+- Does not include the slug
+
+### `url`
+
+The `url` is the entire URL path, defined by the file path and optionally overridden by a `url` value in front matter. See [URL Management](/content-management/urls/#slug) for details.
+
+[config]: /configuration/
+[pretty]: /content-management/urls/#appearance
+[sections]: /content-management/sections/
+[page template]: /templates/types/#page
diff --git a/documents/markdown/hugo-docs/en_content-management_page-bundles.md b/documents/markdown/hugo-docs/en_content-management_page-bundles.md
new file mode 100644
index 0000000..a5bf9a3
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_content-management_page-bundles.md
@@ -0,0 +1,145 @@
+---
+title: Page bundles
+description: Use page bundles to logically associate one or more resources with content.
+categories: []
+keywords: []
+---
+
+## Introduction
+
+A page bundle is a directory that encapsulates both content and associated resources.
+
+By way of example, this site has an "about" page and a "privacy" page:
+
+```text
+content/
+├── about/
+│ ├── index.md
+│ └── welcome.jpg
+└── privacy.md
+```
+
+The "about" page is a page bundle. It logically associates a resource with content by bundling them together. Resources within a page bundle are [page resources], accessible with the [`Resources`] method on the `Page` object.
+
+Page bundles are either _leaf bundles_ or _branch bundles_.
+
+leaf bundle
+: A _leaf bundle_ is a directory that contains an `index.md` file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants.
+
+branch bundle
+: A _branch bundle_ is a directory that contains an `_index.md` file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top-level directories with or without `_index.md` files are also branch bundles. This includes the home page.
+
+> [!note]
+> In the definitions above and the examples below, the extension of the index file depends on the [content format](g). For example, use `index.md` for Markdown content, `index.html` for HTML content, `index.adoc` for AsciiDoc content, etc.
+
+## Comparison
+
+Page bundle characteristics vary by bundle type.
+
+| | Leaf bundle | Branch bundle |
+|---------------------|---------------------------------------------------------|---------------------------------------------------------|
+| Index file | `index.md` | `_index.md` |
+| Example | `content/about/index.md` | `content/posts/_index.md` |
+| [Page kinds](g) | `page` | `home`, `section`, `taxonomy`, or `term` |
+| Template types | [single] | [home], [section], [taxonomy], or [term] |
+| Descendant pages | None | Zero or more |
+| Resource location | Adjacent to the index file or in a nested subdirectory | Same as a leaf bundles, but excludes descendant bundles |
+| [Resource types](g) | `page`, `image`, `video`, etc. | all but `page` |
+
+Files with [resource type](g) `page` include content written in Markdown, HTML, AsciiDoc, Pandoc, reStructuredText, and Emacs Org Mode. In a leaf bundle, excluding the index file, these files are only accessible as page resources. In a branch bundle, these files are only accessible as content pages.
+
+## Leaf bundles
+
+A _leaf bundle_ is a directory that contains an `index.md` file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants.
+
+```text
+content/
+├── about
+│ └── index.md
+├── posts
+│ ├── my-post
+│ │ ├── content-1.md
+│ │ ├── content-2.md
+│ │ ├── image-1.jpg
+│ │ ├── image-2.png
+│ │ └── index.md
+│ └── my-other-post
+│ └── index.md
+└── another-section
+ ├── foo.md
+ └── not-a-leaf-bundle
+ ├── bar.md
+ └── another-leaf-bundle
+ └── index.md
+```
+
+There are four leaf bundles in the example above:
+
+about
+: This leaf bundle does not contain any page resources.
+
+my-post
+: This leaf bundle contains an index file, two resources of [resource type](g) `page`, and two resources of resource type `image`.
+
+ - content-1, content-2
+
+ These are resources of resource type `page`, accessible via the [`Resources`] method on the `Page` object. Hugo will not render these as individual pages.
+
+ - image-1, image-2
+
+ These are resources of resource type `image`, accessible via the `Resources` method on the `Page` object
+
+my-other-post
+: This leaf bundle does not contain any page resources.
+
+another-leaf-bundle
+: This leaf bundle does not contain any page resources.
+
+> [!note]
+> Create leaf bundles at any depth within the `content` directory, but a leaf bundle may not contain another bundle. Leaf bundles do not have descendants.
+
+## Branch bundles
+
+A _branch bundle_ is a directory that contains an `_index.md` file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top-level directories with or without `_index.md` files are also branch bundles. This includes the home page.
+
+```text
+content/
+├── branch-bundle-1/
+│ ├── _index.md
+│ ├── content-1.md
+│ ├── content-2.md
+│ ├── image-1.jpg
+│ └── image-2.png
+├── branch-bundle-2/
+│ ├── a-leaf-bundle/
+│ │ └── index.md
+│ └── _index.md
+└── _index.md
+```
+
+There are three branch bundles in the example above:
+
+home page
+: This branch bundle contains an index file, two descendant branch bundles, and no resources.
+
+branch-bundle-1
+: This branch bundle contains an index file, two resources of [resource type](g) `page`, and two resources of resource type `image`.
+
+branch-bundle-2
+: This branch bundle contains an index file and a leaf bundle.
+
+> [!note]
+> Create branch bundles at any depth within the `content` directory. Branch bundles may have descendants.
+
+## Headless bundles
+
+Use [build options] in front matter to create an unpublished leaf or branch bundle whose content and resources you can include in other pages.
+
+[`Resources`]: /methods/page/resources/
+[build options]: /content-management/build-options/
+[home]: /templates/types/#home
+[page resources]: /content-management/page-resources/
+[section]: /templates/types/#section
+[single]: /templates/types/#single
+[taxonomy]: /templates/types/#taxonomy
+[term]: /templates/types/#term
diff --git a/documents/markdown/hugo-docs/en_content-management_page-resources.md b/documents/markdown/hugo-docs/en_content-management_page-resources.md
new file mode 100644
index 0000000..db92734
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_content-management_page-resources.md
@@ -0,0 +1,297 @@
+---
+title: Page resources
+description: Use page resources to logically associate assets with a page.
+categories: []
+keywords: []
+---
+
+Page resources are only accessible from [page bundles](/content-management/page-bundles), those directories with `index.md` or
+`_index.md` files at their root. Page resources are only available to the
+page with which they are bundled.
+
+In this example, `first-post` is a page bundle with access to 10 page resources including audio, data, documents, images, and video. Although `second-post` is also a page bundle, it has no page resources and is unable to directly access the page resources associated with `first-post`.
+
+```text
+content
+└── post
+ ├── first-post
+ │ ├── images
+ │ │ ├── a.jpg
+ │ │ ├── b.jpg
+ │ │ └── c.jpg
+ │ ├── index.md (root of page bundle)
+ │ ├── latest.html
+ │ ├── manual.json
+ │ ├── notice.md
+ │ ├── office.mp3
+ │ ├── pocket.mp4
+ │ ├── rating.pdf
+ │ └── safety.txt
+ └── second-post
+ └── index.md (root of page bundle)
+```
+
+## Examples
+
+Use any of these methods on a `Page` object to capture page resources:
+
+- [`Resources.ByType`]
+- [`Resources.Get`]
+- [`Resources.GetMatch`]
+- [`Resources.Match`]
+
+ Once you have captured a resource, use any of the applicable [`Resource`] methods to return a value or perform an action.
+
+The following examples assume this content structure:
+
+```text
+content/
+└── example/
+ ├── data/
+ │ └── books.json <-- page resource
+ ├── images/
+ │ ├── a.jpg <-- page resource
+ │ └── b.jpg <-- page resource
+ ├── snippets/
+ │ └── text.md <-- page resource
+ └── index.md
+```
+
+Render a single image, and throw an error if the file does not exist:
+
+```go-html-template
+{{ $path := "images/a.jpg" }}
+{{ with .Resources.Get $path }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ else }}
+ {{ errorf "Unable to get page resource %q" $path }}
+{{ end }}
+```
+
+Render all images, resized to 300 px wide:
+
+```go-html-template
+{{ range .Resources.ByType "image" }}
+ {{ with .Resize "300x" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+Render the markdown snippet:
+
+```go-html-template
+{{ with .Resources.Get "snippets/text.md" }}
+ {{ .Content }}
+{{ end }}
+```
+
+List the titles in the data file, and throw an error if the file does not exist.
+
+```go-html-template
+{{ $path := "data/books.json" }}
+{{ with .Resources.Get $path }}
+ {{ with . | transform.Unmarshal }}
+ <p>Books:</p>
+ <ul>
+ {{ range . }}
+ <li>{{ .title }}</li>
+ {{ end }}
+ </ul>
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get page resource %q" $path }}
+{{ end }}
+```
+
+## Metadata
+
+The page resources' metadata is managed from the corresponding page's front matter with an array/table parameter named `resources`. You can batch assign values using [wildcards](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm).
+
+> [!note]
+> Resources of type `page` get `Title` etc. from their own front matter.
+
+name
+: (`string`) Sets the value returned in `Name`.
+
+> [!note]
+> The methods `Match`, `Get` and `GetMatch` use `Name` to match the resources.
+
+title
+: (`string`) Sets the value returned in `Title`
+
+params
+: (`map`) A map of custom key-value pairs.
+
+### Resources metadata example
+
+<!-- markdownlint-disable MD007 MD032 -->
+{{< code-toggle file=content/example.md fm=true >}}
+title: Application
+date: 2018-01-25
+resources:
+ - src: images/sunset.jpg
+ name: header
+ - src: documents/photo_specs.pdf
+ title: Photo Specifications
+ params:
+ icon: photo
+ - src: documents/guide.pdf
+ title: Instruction Guide
+ - src: documents/checklist.pdf
+ title: Document Checklist
+ - src: documents/payment.docx
+ title: Proof of Payment
+ - src: "**.pdf"
+ name: pdf-file-:counter
+ params:
+ icon: pdf
+ - src: "**.docx"
+ params:
+ icon: word
+{{</ code-toggle >}}
+<!-- markdownlint-enable MD007 MD032 -->
+
+From the example above:
+
+- `sunset.jpg` will receive a new `Name` and can now be found with `.GetMatch "header"`.
+- `documents/photo_specs.pdf` will get the `photo` icon.
+- `documents/checklist.pdf`, `documents/guide.pdf` and `documents/payment.docx` will get `Title` as set by `title`.
+- Every `PDF` in the bundle except `documents/photo_specs.pdf` will get the `pdf` icon.
+- All `PDF` files will get a new `Name`. The `name` parameter contains a special placeholder [`:counter`](#the-counter-placeholder-in-name-and-title), so the `Name` will be `pdf-file-1`, `pdf-file-2`, `pdf-file-3`.
+- Every docx in the bundle will receive the `word` icon.
+
+> [!note]
+> The order matters; only the first set values of the `title`, `name` and `params` keys will be used. Consecutive parameters will be set only for the ones not already set. In the above example, `.Params.icon` is first set to `"photo"` in `src = "documents/photo_specs.pdf"`. So that would not get overridden to `"pdf"` by the later set `src = "**.pdf"` rule.
+
+### The `:counter` placeholder in `name` and `title`
+
+The `:counter` is a special placeholder recognized in `name` and `title` parameters `resources`.
+
+The counter starts at 1 the first time they are used in either `name` or `title`.
+
+For example, if a bundle has the resources `photo_specs.pdf`, `other_specs.pdf`, `guide.pdf` and `checklist.pdf`, and the front matter has specified the `resources` as:
+
+{{< code-toggle file=content/inspections/engine/index.md fm=true >}}
+title = 'Engine inspections'
+[[resources]]
+ src = '*specs.pdf'
+ title = 'Specification #:counter'
+[[resources]]
+ src = '**.pdf'
+ name = 'pdf-file-:counter'
+{{</ code-toggle >}}
+
+the `Name` and `Title` will be assigned to the resource files as follows:
+
+| Resource file | `Name` | `Title` |
+|-------------------|-------------------|-----------------------|
+| checklist.pdf | `"pdf-file-1.pdf` | `"checklist.pdf"` |
+| guide.pdf | `"pdf-file-2.pdf` | `"guide.pdf"` |
+| other\_specs.pdf | `"pdf-file-3.pdf` | `"Specification #1"` |
+| photo\_specs.pdf | `"pdf-file-4.pdf` | `"Specification #2"` |
+
+## Multilingual
+
+By default, with a multilingual single-host project, Hugo does not duplicate shared page during the build.
+
+> [!note]
+> This behavior is limited to Markdown content. Shared page resources for other [content formats] are copied into each language bundle.
+
+Consider this project configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = true
+
+[languages.de]
+label = 'Deutsch'
+locale = 'de-DE'
+weight = 1
+
+[languages.en]
+label = 'English'
+locale = 'en-US'
+weight = 2
+{{< /code-toggle >}}
+
+And this content:
+
+```text
+content/
+└── my-bundle/
+ ├── a.jpg <-- shared page resource
+ ├── b.jpg <-- shared page resource
+ ├── c.de.jpg
+ ├── c.en.jpg
+ ├── index.de.md
+ └── index.en.md
+```
+
+With v0.122.0 and earlier, Hugo duplicated the shared page resources, creating copies for each language:
+
+```text
+public/
+├── de/
+│ ├── my-bundle/
+│ │ ├── a.jpg <-- shared page resource
+│ │ ├── b.jpg <-- shared page resource
+│ │ ├── c.de.jpg
+│ │ └── index.html
+│ └── index.html
+├── en/
+│ ├── my-bundle/
+│ │ ├── a.jpg <-- shared page resource (duplicate)
+│ │ ├── b.jpg <-- shared page resource (duplicate)
+│ │ ├── c.en.jpg
+│ │ └── index.html
+│ └── index.html
+└── index.html
+
+```
+
+With v0.123.0 and later, Hugo places the shared resources in the page bundle for the default content language:
+
+```text
+public/
+├── de/
+│ ├── my-bundle/
+│ │ ├── a.jpg <-- shared page resource
+│ │ ├── b.jpg <-- shared page resource
+│ │ ├── c.de.jpg
+│ │ └── index.html
+│ └── index.html
+├── en/
+│ ├── my-bundle/
+│ │ ├── c.en.jpg
+│ │ └── index.html
+│ └── index.html
+└── index.html
+```
+
+This approach reduces build times, storage requirements, bandwidth consumption, and deployment times, ultimately reducing cost.
+
+> [!important]
+> To resolve Markdown link and image destinations to the correct location, you must use link and image render hooks that capture the page resource with the [`Resources.Get`] method, and then invoke its [`RelPermalink`] method.
+>
+> In its default configuration, Hugo automatically uses the [embedded link render hook] and the [embedded image render hook] for multilingual single-host projects, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such projects. If custom link or image render hooks are defined by your project, modules, or themes, these will be used instead.
+>
+> You can also configure Hugo to `always` use the embedded link or image render hook, use it only as a `fallback`, or `never` use it. See [details](/configuration/markup/#renderhookslinkuseembedded).
+
+Although duplicating shared page resources is inefficient, you can enable this feature in your project configuration if desired:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark]
+duplicateResourceFiles = true
+{{< /code-toggle >}}
+
+[`RelPermalink`]: /methods/resource/relpermalink/
+[`Resource`]: /methods/resource
+[`Resources.ByType`]: /methods/page/resources#bytype
+[`Resources.Get`]: /methods/page/resources/#get
+[`Resources.GetMatch`]: /methods/page/resources#getmatch
+[`Resources.Match`]: /methods/page/resources#match
+[content formats]: /content-management/formats/
+[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
+[embedded image render hook]: /render-hooks/images/#embedded
+[embedded link render hook]: /render-hooks/links/#embedded
diff --git a/documents/markdown/hugo-docs/en_content-management_related-content.md b/documents/markdown/hugo-docs/en_content-management_related-content.md
new file mode 100644
index 0000000..48009ec
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_content-management_related-content.md
@@ -0,0 +1,102 @@
+---
+title: Related content
+description: List related content in "See Also" sections.
+categories: []
+keywords: []
+aliases: [/content/related/,/related/,/content-management/related/]
+---
+
+Hugo uses a set of factors to identify a page's related content based on front matter parameters. This can be tuned to the desired set of indices and parameters or left to Hugo's default [related content configuration](/configuration/related-content/).
+
+## List related content
+
+To list up to 5 related pages (which share the same _date_ or _keyword_ parameters) is as simple as including something similar to this partial in your template:
+
+```go-html-template {file="layouts/_partials/related.html" copy=true}
+{{ with site.RegularPages.Related . | first 5 }}
+ <p>Related content:</p>
+ <ul>
+ {{ range . }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+The `Related` method takes one argument which may be a `Page` or an options map. The options map has these options:
+
+indices
+: (`slice`) The indices to search within.
+
+document
+: (`page`) The page for which to find related content. Required when specifying an options map.
+
+namedSlices
+: (`slice`) The keywords to search for, expressed as a slice of `KeyValues` using the [`keyVals`] function.
+
+fragments
+: (`slice`) A list of special keywords that is used for indices configured as type "fragments". This will match the [fragment](g) identifiers of the documents.
+
+A fictional example using all of the above options:
+
+```go-html-template
+{{ $page := . }}
+{{ $opts := dict
+ "indices" (slice "tags" "keywords")
+ "document" $page
+ "namedSlices" (slice (keyVals "tags" "hugo" "rocks") (keyVals "date" $page.Date))
+ "fragments" (slice "heading-1" "heading-2")
+}}
+```
+
+> [!note]
+> We improved and simplified this feature in Hugo 0.111.0. Before this we had 3 different methods: `Related`, `RelatedTo` and `RelatedIndices`. Now we have only one method: `Related`. The old methods are still available but deprecated. Also see [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation of more advanced usage of this feature.
+
+## Index content headings
+
+Hugo can index the headings in your content and use this to find related content. You can enable this by adding a index of type `fragments` to your `related` configuration:
+
+{{< code-toggle file=hugo >}}
+[related]
+threshold = 20
+includeNewer = true
+toLower = false
+[[related.indices]]
+name = 'fragmentrefs'
+type = 'fragments'
+applyFilter = true
+weight = 80
+{{< /code-toggle >}}
+
+- The `name` maps to a optional front matter slice attribute that can be used to link from the page level down to the fragment/heading level.
+- If `applyFilter` is enabled, the `.HeadingsFiltered` on each page in the result will reflect the filtered headings. This is useful if you want to show the headings in the related content listing:
+
+```go-html-template
+{{ $related := .Site.RegularPages.Related . | first 5 }}
+{{ with $related }}
+ <h2>See Also</h2>
+ <ul>
+ {{ range $i, $p := . }}
+ <li>
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+ {{ with .HeadingsFiltered }}
+ <ul>
+ {{ range . }}
+ {{ $link := printf "%s#%s" $p.RelPermalink .ID | safeURL }}
+ <li>
+ <a href="{{ $link }}">{{ .Title }}</a>
+ </li>
+ {{ end }}
+ </ul>
+ {{ end }}
+ </li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+## Configuration
+
+See [configure related content](/configuration/related-content/).
+
+[`keyVals`]: /functions/collections/keyvals/
diff --git a/documents/markdown/hugo-docs/en_content-management_sections.md b/documents/markdown/hugo-docs/en_content-management_sections.md
new file mode 100644
index 0000000..3dfad5b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_content-management_sections.md
@@ -0,0 +1,139 @@
+---
+title: Sections
+description: Organize content into sections.
+
+categories: []
+keywords: []
+aliases: [/content/sections/]
+---
+
+## Overview
+
+{{% glossary-term "section" %}}
+
+```text
+content/
+├── articles/ <-- section (top-level directory)
+│ ├── 2022/
+│ │ ├── article-1/
+│ │ │ ├── cover.jpg
+│ │ │ └── index.md
+│ │ └── article-2.md
+│ └── 2023/
+│ ├── article-3.md
+│ └── article-4.md
+├── products/ <-- section (top-level directory)
+│ ├── product-1/ <-- section (has _index.md file)
+│ │ ├── benefits/ <-- section (has _index.md file)
+│ │ │ ├── _index.md
+│ │ │ ├── benefit-1.md
+│ │ │ └── benefit-2.md
+│ │ ├── features/ <-- section (has _index.md file)
+│ │ │ ├── _index.md
+│ │ │ ├── feature-1.md
+│ │ │ └── feature-2.md
+│ │ └── _index.md
+│ └── product-2/ <-- section (has _index.md file)
+│ ├── benefits/ <-- section (has _index.md file)
+│ │ ├── _index.md
+│ │ ├── benefit-1.md
+│ │ └── benefit-2.md
+│ ├── features/ <-- section (has _index.md file)
+│ │ ├── _index.md
+│ │ ├── feature-1.md
+│ │ └── feature-2.md
+│ └── _index.md
+├── _index.md
+└── about.md
+```
+
+The example above has two top-level sections: articles and products. None of the directories under articles are sections, while all of the directories under products are sections. A section within a section is a known as a nested section or subsection.
+
+## Explanation
+
+Sections and non-sections behave differently.
+
+ |Sections|Non-sections
+:--|:-:|:-:
+Directory names become URL segments|:heavy_check_mark:|:heavy_check_mark:
+Have logical ancestors and descendants|:heavy_check_mark:|:x:
+Have list pages|:heavy_check_mark:|:x:
+
+With the file structure from the [example above](#overview):
+
+1. The list page for the articles section includes all articles, regardless of directory structure; none of the subdirectories are sections.
+1. The articles/2022 and articles/2023 directories do not have list pages; they are not sections.
+1. The list page for the products section, by default, includes product-1 and product-2, but not their descendant pages. To include descendant pages, use the `RegularPagesRecursive` method instead of the `Pages` method in the _section_ template.
+1. All directories in the products section have list pages; each directory is a section.
+
+## Template selection
+
+Hugo has a defined [lookup order] to determine which template to use when rendering a page. The [lookup rules] consider the top-level section name; subsection names are not considered when selecting a template.
+
+With the file structure from the [example above](#overview):
+
+Content directory|Section template
+:--|:--
+`content/products`|`layouts/products/section.html`
+`content/products/product-1`|`layouts/products/section.html`
+`content/products/product-1/benefits`|`layouts/products/section.html`
+
+Content directory|Page template
+:--|:--
+`content/products`|`layouts/products/page.html`
+`content/products/product-1`|`layouts/products/page.html`
+`content/products/product-1/benefits`|`layouts/products/page.html`
+
+If you need to use a different template for a subsection, specify `type` and/or `layout` in front matter.
+
+## Ancestors and descendants
+
+A section has one or more ancestors (including the home page), and zero or more descendants. With the file structure from the [example above](#overview):
+
+```text
+content/products/product-1/benefits/benefit-1.md
+```
+
+The content file (benefit-1.md) has four ancestors: benefits, product-1, products, and the home page. This logical relationship allows us to use the `.Parent` and `.Ancestors` methods to traverse the site structure.
+
+For example, use the `.Ancestors` method to render breadcrumb navigation.
+
+```go-html-template {file="layouts/_partials/breadcrumb.html"}
+<nav aria-label="breadcrumb" class="breadcrumb">
+ <ol>
+ {{ range .Ancestors.Reverse }}
+ <li>
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+ </li>
+ {{ end }}
+ <li class="active">
+ <a aria-current="page" href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+ </li>
+ </ol>
+</nav>
+```
+
+With this CSS:
+
+```css
+.breadcrumb ol {
+ padding-left: 0;
+}
+
+.breadcrumb li {
+ display: inline;
+}
+
+.breadcrumb li:not(:last-child)::after {
+ content: "»";
+}
+```
+
+Hugo renders this, where each breadcrumb is a link to the corresponding page:
+
+```text
+Home » Products » Product 1 » Benefits » Benefit 1
+```
+
+[lookup order]: /templates/lookup-order/
+[lookup rules]: /templates/lookup-order/#lookup-rules
diff --git a/documents/markdown/hugo-docs/en_content-management_shortcodes.md b/documents/markdown/hugo-docs/en_content-management_shortcodes.md
new file mode 100644
index 0000000..7a1f1b8
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_content-management_shortcodes.md
@@ -0,0 +1,231 @@
+---
+title: Shortcodes
+description: Use embedded, custom, or inline shortcodes to insert elements such as videos, images, and social media embeds into your content.
+categories: []
+keywords: []
+aliases: [/extras/shortcodes/]
+---
+
+## Introduction
+
+{{% glossary-term shortcode %}}
+
+There are three types of shortcodes: embedded, custom, and inline.
+
+## Embedded
+
+Hugo's embedded shortcodes are pre-defined templates within the application. Refer to each shortcode's documentation for specific usage instructions and available arguments.
+
+{{% render-list-of-pages-in-section path=/shortcodes %}}
+
+## Custom
+
+Create custom shortcodes to simplify and standardize content creation. For example, the following _shortcode_ template generates an audio player using a [global resource](g):
+
+```go-html-template {file="layouts/_shortcodes/audio.html"}
+{{ with resources.Get (.Get "src") }}
+ <audio controls preload="auto" src="{{ .RelPermalink }}"></audio>
+{{ end }}
+```
+
+Then call the shortcode from within markup:
+
+```text {file="content/example.md"}
+{{</* audio src=/audio/test.mp3 */>}}
+```
+
+Learn more about creating shortcodes in the [shortcode templates][] section.
+
+## Inline
+
+An inline shortcode is a _shortcode_ template defined within content.
+
+Hugo's security model is based on the premise that template and configuration authors are trusted, but content authors are not. This model enables generation of HTML output safe against code injection.
+
+To conform with this security model, creating _shortcode_ templates within content is disabled by default. If you trust your content authors, you can enable this functionality in your project configuration:
+
+{{< code-toggle file=hugo >}}
+[security]
+enableInlineShortcodes = true
+{{< /code-toggle >}}
+
+For more information see [configure security](/configuration/security).
+
+The following example demonstrates an inline shortcode, `date.inline`, that accepts a single positional argument: a date/time [layout string][].
+
+```text {file="content/example.md"}
+Today is
+{{</* date.inline ":date_medium" */>}}
+ {{- now | time.Format (.Get 0) -}}
+{{</* /date.inline */>}}.
+
+Today is {{</* date.inline ":date_full" /*/>}}.
+```
+
+In the example above, the inline shortcode is executed twice: once upon definition and again when subsequently called. Hugo renders this to:
+
+```html
+<p>Today is Jan 30, 2025.</p>
+<p>Today is Thursday, January 30, 2025</p>
+```
+
+Inline shortcodes process their inner content within the same context as regular _shortcode_ templates, allowing you to use any available [shortcode method][].
+
+> [!note]
+> You cannot [nest](#nesting) inline shortcodes.
+
+Learn more about creating shortcodes in the [shortcode templates][] section.
+
+## Calling
+
+Shortcode calls involve three syntactical elements: tags, arguments, and notation.
+
+### Tags
+
+Some shortcodes expect content between opening and closing tags. For example, the embedded [`details`][] shortcode requires an opening and closing tag:
+
+```text
+{{</* details summary="See the details" */>}}
+This is a **bold** word.
+{{</* /details */>}}
+```
+
+Some shortcodes do not accept content. For example, the embedded [`instagram`][] shortcode requires a single _positional_ argument:
+
+```text
+{{</* instagram CxOWiQNP2MO */>}}
+```
+
+Some shortcodes optionally accept content. For example, you can call the embedded [`qr`][] shortcode with content:
+
+```text
+{{</* qr */>}}
+https://gohugo.io
+{{</* /qr */>}}
+```
+
+Or use the self-closing syntax with a trailing slash to pass the text as an argument:
+
+```text
+{{</* qr text=https://gohugo.io /*/>}}
+```
+
+Refer to each shortcode's documentation for specific usage instructions and available arguments.
+
+### Arguments
+
+Shortcode arguments can be either _named_ or _positional_.
+
+Named arguments are passed as case-sensitive key-value pairs, as seen in this example with the embedded [`figure`][] shortcode. The `src` argument, for instance, is required.
+
+```text
+{{</* figure src=/images/kitten.jpg */>}}
+```
+
+Positional arguments, on the other hand, are determined by their position. The embedded `instagram` shortcode, for example, expects the first argument to be the Instagram post ID.
+
+```text
+{{</* instagram CxOWiQNP2MO */>}}
+```
+
+Shortcode arguments are space-delimited, and arguments with internal spaces must be quoted.
+
+```text
+{{</* figure src=/images/kitten.jpg alt="A white kitten" */>}}
+```
+
+Shortcodes accept [scalar](g) arguments, one of [string](g), [integer](g), [floating point](g), or [boolean](g).
+
+```text
+{{</* my-shortcode name="John Smith" age=24 married=false */>}}
+```
+
+You can optionally use multiple lines when providing several arguments to a shortcode for better readability:
+
+```text
+{{</* figure
+ src=/images/kitten.jpg
+ alt="A white kitten"
+ caption="This is a white kitten"
+ loading=lazy
+*/>}}
+```
+
+Use a [raw string literal](g) if you need to pass a multiline string:
+
+```text
+{{</* myshortcode `This is some <b>HTML</b>,
+and a new line with a "quoted string".` */>}}
+```
+
+Shortcodes can accept named arguments, positional arguments, or both, but you must use either named or positional arguments exclusively within a single shortcode call; mixing them is not allowed.
+
+Refer to each shortcode's documentation for specific usage instructions and available arguments.
+
+### Notation
+
+Shortcodes can be called using two different notations, distinguished by their tag delimiters.
+
+Notation|Example
+:--|:--
+Markdown|`{{%/* foo */%}} ## Section 1 {{%/* /foo */%}}`
+Standard|`{{</* foo */>}} ## Section 2 {{</* /foo */>}}`
+
+#### Markdown notation
+
+Hugo processes the shortcode before the page content is rendered by the Markdown renderer. This means, for instance, that Markdown headings inside a Markdown-notation shortcode will be included when invoking the [`TableOfContents`][] method on the `Page` object.
+
+#### Standard notation
+
+With standard notation, Hugo processes the shortcode separately, merging the output into the page content after Markdown rendering. This means, for instance, that Markdown headings inside a standard-notation shortcode will be excluded when invoking the `TableOfContents` method on the `Page` object.
+
+By way of example, with this _shortcode_ template:
+
+```go-html-template {file="layouts/_shortcodes/foo.html"}
+{{ .Inner }}
+```
+
+And this markdown:
+
+```text {file="content/example.md"}
+{{%/* foo */%}} ## Section 1 {{%/* /foo */%}}
+
+{{</* foo */>}} ## Section 2 {{</* /foo */>}}
+```
+
+Hugo renders this HTML:
+
+```html
+<h2 id="heading">Section 1</h2>
+
+## Section 2
+```
+
+In the above, "Section 1" will be included when invoking the `TableOfContents` method, while "Section 2" will not.
+
+> [!note]
+> The shortcode author determines which notation to use. Consult each shortcode's documentation for specific usage instructions and available arguments.
+
+## Nesting
+
+Shortcodes (excluding [inline](#inline) shortcodes) can be nested, creating parent-child relationships. For example, a gallery shortcode might contain several image shortcodes:
+
+```text {file="content/example.md"}
+{{</* gallery class="content-gallery" */>}}
+ {{</* image src="/images/a.jpg" */>}}
+ {{</* image src="/images/b.jpg" */>}}
+ {{</* image src="/images/c.jpg" */>}}
+{{</* /gallery */>}}
+```
+
+The [shortcode templates][nesting] section provides a detailed explanation and examples.
+
+[`details`]: /shortcodes/details
+[`figure`]: /shortcodes/figure
+[`instagram`]: /shortcodes/instagram
+[`qr`]: /shortcodes/qr
+[`TableOfContents`]: /methods/page/tableofcontents/
+[layout string]: /functions/time/format/#layout-string
+[nesting]: /templates/shortcode/#nesting
+[shortcode method]: /templates/shortcode/#methods
+[shortcode templates]: /templates/shortcode/
diff --git a/documents/markdown/hugo-docs/en_content-management_summaries.md b/documents/markdown/hugo-docs/en_content-management_summaries.md
new file mode 100644
index 0000000..cd9eaa8
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_content-management_summaries.md
@@ -0,0 +1,157 @@
+---
+title: Content summaries
+linkTitle: Summaries
+description: Create and render content summaries.
+categories: []
+keywords: []
+aliases: [/content/summaries/,/content-management/content-summaries/]
+---
+
+<!-- Do not remove the manual summary divider below. -->
+<!-- If you do, you will break its first literal usage on this page. -->
+
+<!--more-->
+
+You can define a summary manually, in front matter, or automatically. A manual summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary.
+
+Review the [comparison table](#comparison) below to understand the characteristics of each summary type.
+
+## Manual summary
+
+Use a `<!--more-->` divider to indicate the end of the summary. Hugo will not render the summary divider itself.
+
+```text {file="content/example.md"}
++++
+title: 'Example'
+date: 2024-05-26T09:10:33-07:00
++++
+
+This is the first paragraph.
+
+<!--more-->
+
+This is the second paragraph.
+```
+
+> [!NOTE]
+> Place the summary divider on its own line. Do not place it inline with other content.
+
+Correct placement:
+
+```text {file="content/example.md"}
+---
+title: 'Example'
+---
+
+This is an example of **strong text** in a sentence. This is another sentence.
+
+<!--more-->
+
+This is another paragraph.
+```
+
+Incorrect placement:
+
+```text {file="content/example.md"}
+---
+title: 'Example'
+---
+
+This is an example of **strong text** <!--more--> in a sentence. This is another sentence.
+
+This is another paragraph.
+```
+
+When using the Emacs Org Mode [content format], use a `# more` divider to indicate the end of the summary.
+
+[content format]: /content-management/formats/
+
+## Front matter summary
+
+Use front matter to define a summary independent of content.
+
+```text {file="content/example.md"}
++++
+title: 'Example'
+date: 2024-05-26T09:10:33-07:00
+summary: 'This summary is independent of the content.'
++++
+
+This is the first paragraph.
+
+This is the second paragraph.
+```
+
+## Automatic summary
+
+If you do not define the summary manually or in front matter, Hugo automatically defines the summary based on the [`summaryLength`] in your project configuration.
+
+[`summaryLength`]: /configuration/all/#summarylength
+
+```text {file="content/example.md"}
++++
+title: 'Example'
+date: 2024-05-26T09:10:33-07:00
++++
+
+This is the first paragraph.
+
+This is the second paragraph.
+
+This is the third paragraph.
+```
+
+For example, with a `summaryLength` of 7, the automatic summary will be:
+
+```html
+<p>This is the first paragraph.</p>
+<p>This is the second paragraph.</p>
+```
+
+> [!warning]
+> Automatic `.Summary` may cut block tags (e.g., `blockquote`) in the middle when `summaryLength` is reached, causing the browser to recover the end tag (the end tag will be inserted before the parent's end tag), resulting in unexpected rendering behavior. To avoid this, wrap `.Summary` in a `<div>`; alternatively, wrap it together with the heading tag using `<section>`. You can avoid this entirely by using a manual summary. See issue [#14044] for details.
+
+## Comparison
+
+Each summary type has different characteristics:
+
+Type|Precedence|Renders markdown|Renders shortcodes|Wraps single lines with `<p>`
+:--|:-:|:-:|:-:|:-:
+Manual|1|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+Front matter|2|:heavy_check_mark:|:x:|:x:
+Automatic|3|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+
+## Rendering
+
+Render the summary in a template by calling the [`Summary`] method on a `Page` object.
+
+[`Summary`]: /methods/page/summary
+
+```go-html-template
+{{ range site.RegularPages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ <div class="summary">
+ {{ .Summary }}
+ {{ if .Truncated }}
+ <a href="{{ .RelPermalink }}">More ...</a>
+ {{ end }}
+ </div>
+{{ end }}
+```
+
+## Alternative
+
+Instead of calling the `Summary` method on a `Page` object, use the [`strings.Truncate`] function for granular control of the summary length. For example:
+
+[`strings.Truncate`]: /functions/strings/truncate/
+
+```go-html-template
+{{ range site.RegularPages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ <div class="summary">
+ {{ .Content | strings.Truncate 42 }}
+ </div>
+{{ end }}
+```
+
+[#14044]: https://github.com/gohugoio/hugo/issues/14044
diff --git a/documents/markdown/hugo-docs/en_content-management_syntax-highlighting.md b/documents/markdown/hugo-docs/en_content-management_syntax-highlighting.md
new file mode 100644
index 0000000..57735b0
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_content-management_syntax-highlighting.md
@@ -0,0 +1,102 @@
+---
+title: Syntax highlighting
+description: Add syntax highlighting to code examples.
+categories: []
+keywords: [highlight]
+aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/]
+---
+
+Hugo provides several methods to add syntax highlighting to code examples:
+
+- Use the [`transform.Highlight`] function within your templates
+- Use the [`highlight`] shortcode with any [content format](g)
+- Use fenced code blocks with the Markdown content format
+
+[`transform.Highlight`]: /functions/transform/highlight/
+[`highlight`]: /shortcodes/highlight/
+
+## Fenced code blocks
+
+In its default configuration, Hugo highlights code examples within fenced code blocks, following this form:
+
+````text {file="content/example.md"}
+```LANG [OPTIONS]
+CODE
+```
+````
+
+CODE
+: The code to highlight.
+
+LANG
+: The language of the code to highlight. Choose from one of the [supported languages]. This value is case-insensitive.
+
+OPTIONS
+: One or more space-separated or comma-separated key-value pairs wrapped in braces. Set default values for each option in your [project configuration]. The key names are case-insensitive.
+
+[supported languages]: #languages
+[project configuration]: /configuration/markup/#highlight
+
+For example, with this Markdown:
+
+````text {file="content/example.md"}
+```go {linenos=inline hl_lines=[3,"6-8"] style=emacs}
+package main
+
+import "fmt"
+
+func main() {
+ for i := 0; i < 3; i++ {
+ fmt.Println("Value of i:", i)
+ }
+}
+```
+````
+
+Hugo renders this:
+
+```go {linenos=inline, hl_lines=[3, "6-8"], style=emacs}
+package main
+
+import "fmt"
+
+func main() {
+ for i := 0; i < 3; i++ {
+ fmt.Println("Value of i:", i)
+ }
+}
+```
+
+## Options
+
+{{% include "_common/syntax-highlighting-options.md" %}}
+
+## Escaping
+
+When documenting shortcode usage, escape the tag delimiters:
+
+````text {file="content/example.md"}
+```text {linenos=inline}
+{{</*/* shortcode-1 */*/>}}
+
+{{%/*/* shortcode-2 */*/%}}
+```
+````
+
+Hugo renders this to:
+
+```text {linenos=inline}
+{{</* shortcode-1 */>}}
+
+{{%/* shortcode-2 */%}}
+```
+
+## Languages
+
+These are the supported languages. Use one of the identifiers, not the language name, when specifying a language for:
+
+- The [`transform.Highlight`] function
+- The [`highlight`] shortcode
+- Fenced code blocks
+
+{{< chroma-lexers >}}
diff --git a/documents/markdown/hugo-docs/en_content-management_taxonomies.md b/documents/markdown/hugo-docs/en_content-management_taxonomies.md
new file mode 100644
index 0000000..c8fcf78
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_content-management_taxonomies.md
@@ -0,0 +1,177 @@
+---
+title: Taxonomies
+description: Hugo includes support for user-defined taxonomies.
+categories: []
+keywords: []
+aliases: [/taxonomies/overview/,/taxonomies/usage/,/indexes/overview/,/doc/indexes/,/extras/indexes]
+---
+
+## What is a taxonomy?
+
+Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications of logical relationships between content.
+
+### Definitions
+
+Taxonomy
+: A categorization that can be used to classify content
+
+Term
+: A key within the taxonomy
+
+Value
+: A piece of content assigned to a term
+
+## Example taxonomy: movie website
+
+Let's assume you are making a website about movies. You may want to include the following taxonomies:
+
+- Actors
+- Directors
+- Studios
+- Genre
+- Year
+- Awards
+
+Then, in each of the movies, you would specify terms for each of these taxonomies (i.e., in the front matter of each of your movie content files). From these terms, Hugo would automatically create pages for each Actor, Director, Studio, Genre, Year, and Award, with each listing all of the Movies that matched that specific Actor, Director, Studio, Genre, Year, and Award.
+
+### Movie taxonomy organization
+
+To continue with the example of a movie site, the following demonstrates content relationships from the perspective of the taxonomy:
+
+```txt
+Actor <- Taxonomy
+ Bruce Willis <- Term
+ The Sixth Sense <- Value
+ Unbreakable <- Value
+ Moonrise Kingdom <- Value
+ Samuel L. Jackson <- Term
+ Unbreakable <- Value
+ The Avengers <- Value
+ xXx <- Value
+```
+
+From the perspective of the content, the relationships would appear differently, although the data and labels used are the same:
+
+```txt
+Unbreakable <- Value
+ Actors <- Taxonomy
+ Bruce Willis <- Term
+ Samuel L. Jackson <- Term
+ Director <- Taxonomy
+ M. Night Shyamalan <- Term
+ ...
+Moonrise Kingdom <- Value
+ Actors <- Taxonomy
+ Bruce Willis <- Term
+ Bill Murray <- Term
+ Director <- Taxonomy
+ Wes Anderson <- Term
+ ...
+```
+
+### Default destinations
+
+When taxonomies are used Hugo will automatically create both a page listing all the taxonomy's terms and individual pages with lists of content associated with each term. For example, a `categories` taxonomy declared in your configuration and used in your content front matter will create the following pages:
+
+- A single page at `example.com/categories/` that lists all the terms within the taxonomy
+- Individual taxonomy list pages (e.g., `/categories/development/`) for each of the terms that shows a listing of all pages marked as part of that taxonomy within any content file's front matter
+
+## Configuration
+
+See [configure taxonomies](/configuration/taxonomies/).
+
+## Assign terms to content
+
+To assign one or more terms to a page, create a front matter field using the plural name of the taxonomy, then add terms to the corresponding array. For example:
+
+{{< code-toggle file=content/example.md fm=true >}}
+title = 'Example'
+tags = ['Tag A','Tag B']
+categories = ['Category A','Category B']
+{{< /code-toggle >}}
+
+## Taxonomic weight
+
+{{% glossary-term "taxonomic weight" %}}
+
+Assign a taxonomic weight using a front matter key named `[taxonomy_name]_weight`.
+
+{{< code-toggle file="content/courses/organic-chemistry.md" fm=true >}}
+title = 'Organic Chemistry'
+weight = 10
+tags_weight = 1000
+tags = ['chemistry','science']
+{{</ code-toggle >}}
+
+With the front matter above, the "Organic Chemistry" page will float towards the top of the list on section and home pages, and it will sink towards the bottom of the list on the "chemistry" and "science" term pages.
+
+## Metadata
+
+Display metadata about each term by creating a corresponding branch bundle in the `content` directory.
+
+For example, create an "authors" taxonomy:
+
+{{< code-toggle file=hugo >}}
+[taxonomies]
+author = 'authors'
+{{< /code-toggle >}}
+
+Then create content with one [branch bundle](g) for each term:
+
+```text
+content/
+└── authors/
+ ├── jsmith/
+ │ ├── _index.md
+ │ └── portrait.jpg
+ └── rjones/
+ ├── _index.md
+ └── portrait.jpg
+```
+
+Then add front matter to each term page:
+
+{{< code-toggle file=content/authors/jsmith/_index.md fm=true >}}
+title = 'John Smith'
+affiliation = 'University of Chicago'
+{{< /code-toggle >}}
+
+Then create a _taxonomy_ template specific to the "authors" taxonomy:
+
+```go-html-template {file="layouts/authors/taxonomy.html"}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+ {{ range .Data.Terms.Alphabetical }}
+ <h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a></h2>
+ <p>Affiliation: {{ .Page.Params.Affiliation }}</p>
+ {{ with .Page.Resources.Get "portrait.jpg" }}
+ {{ with .Fill "100x100" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="portrait">
+ {{ end }}
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+In the example above we list each author including their affiliation and portrait.
+
+Or create a _term_ template specific to the "authors" taxonomy:
+
+```go-html-template {file="layouts/authors/term.html"}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ <p>Affiliation: {{ .Params.affiliation }}</p>
+ {{ with .Resources.Get "portrait.jpg" }}
+ {{ with .Fill "100x100" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="portrait">
+ {{ end }}
+ {{ end }}
+ {{ .Content }}
+ {{ range .Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ end }}
+{{ end }}
+```
+
+In the example above we display the author including their affiliation and portrait, then a list of associated content.
diff --git a/documents/markdown/hugo-docs/en_content-management_urls.md b/documents/markdown/hugo-docs/en_content-management_urls.md
new file mode 100644
index 0000000..e82ac0c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_content-management_urls.md
@@ -0,0 +1,260 @@
+---
+title: URL management
+description: Control the structure and appearance of URLs through front matter entries and settings in your project configuration.
+categories: []
+keywords: []
+aliases: [/extras/permalinks/,/extras/aliases/,/extras/urls/,/doc/redirects/,/doc/alias/,/doc/aliases/]
+---
+
+## Overview
+
+By default, when Hugo renders a page, the resulting URL matches the file path within the `content` directory. For example:
+
+```text
+content/posts/post-1.md → https://example.org/posts/post-1/
+```
+
+You can change the structure and appearance of URLs with front matter values and project configuration options.
+
+## Front matter
+
+### `slug`
+
+Set the `slug` in front matter to override the last segment of the path. This front matter field is not applicable to `home`, `section`, `taxonomy`, or `term` pages.
+
+{{< code-toggle file=content/posts/post-1.md fm=true >}}
+title = 'My First Post'
+slug = 'my-first-post'
+{{< /code-toggle >}}
+
+The resulting URL will be:
+
+```text
+https://example.org/posts/my-first-post/
+```
+
+### `url`
+
+Set the `url` in front matter to override the entire path. Use this with either regular pages or section pages.
+
+> [!note]
+> Hugo does not sanitize the `url` front matter field, allowing you to generate:
+>
+> - File paths that contain characters reserved by the operating system. For example, file paths on Windows may not contain any of these [reserved characters][]. Hugo throws an error if a file path includes a character reserved by the current operating system.
+> - URLs that contain disallowed characters. For example, the less than sign (`<`) is not allowed in a URL.
+
+If you set both `slug` and `url` in front matter, the `url` value takes precedence.
+
+#### Include a colon
+
+{{< new-in 0.136.0 />}}
+
+If you need to include a colon in the `url` front matter field, escape it with backslash characters. Use one backslash if you wrap the string within single quotes, or use two backslashes if you wrap the string within double quotes. With YAML front matter, use a single backslash if you omit quotation marks.
+
+For example, with this front matter:
+
+{{< code-toggle file=content/example.md fm=true >}}
+title: Example
+url: "my\\:example"
+{{< /code-toggle >}}
+
+The resulting URL will be:
+
+```text
+https://example.org/my:example/
+```
+
+As described above, this will fail on Windows because the colon (`:`) is a reserved character.
+
+#### File extensions
+
+With this front matter:
+
+{{< code-toggle file=content/posts/post-1.md fm=true >}}
+title = 'My First Article'
+url = 'articles/my-first-article'
+{{< /code-toggle >}}
+
+The resulting URL will be:
+
+```text
+https://example.org/articles/my-first-article/
+```
+
+If you include a file extension:
+
+{{< code-toggle file=content/posts/post-1.md fm=true >}}
+title = 'My First Article'
+url = 'articles/my-first-article.html'
+{{< /code-toggle >}}
+
+The resulting URL will be:
+
+```text
+https://example.org/articles/my-first-article.html
+```
+
+#### Leading slashes
+
+With monolingual projects, `url` values with or without a leading slash are relative to the [`baseURL`][]. With multilingual projects, `url` values with a leading slash are relative to the `baseURL`, and `url` values without a leading slash are relative to the `baseURL` plus the language prefix.
+
+Site type|Front matter `url`|Resulting URL
+:--|:--|:--
+monolingual|`/about`|`https://example.org/about/`
+monolingual|`about`|`https://example.org/about/`
+multilingual|`/about`|`https://example.org/about/`
+multilingual|`about`|`https://example.org/de/about/`
+
+#### Permalinks tokens in front matter
+
+{{< new-in 0.131.0 />}}
+
+You can also use tokens when setting the `url` value. This is typically used in `cascade` sections:
+
+{{< code-toggle file=content/foo/bar/_index.md fm=true >}}
+title ='Bar'
+[[cascade]]
+ url = '/:sections[last]/:slug'
+{{< /code-toggle >}}
+
+Use any of these tokens:
+
+{{% include "/_common/permalink-tokens.md" %}}
+
+## Project configuration
+
+### Permalinks
+
+See [configure permalinks](/configuration/permalinks).
+
+### Appearance
+
+See [configure ugly URLs](/configuration/ugly-urls/).
+
+### Post-processing
+
+Hugo provides two mutually exclusive configuration options to alter URLs _after_ it renders a page.
+
+#### Canonical URLs
+
+> [!caution]
+> This is a legacy configuration option, superseded by template functions and Markdown render hooks, and will likely be [removed in a future release][].
+{class="!mt-6"}
+
+If enabled, Hugo performs a search and replace _after_ it renders the page. It searches for site-relative URLs (those with a leading slash) associated with `action`, `href`, `src`, `srcset`, and `url` attributes. It then prepends the `baseURL` to create absolute URLs.
+
+```html
+<a href="/about"> → <a href="https://example.org/about/">
+<img src="/a.gif"> → <img src="https://example.org/a.gif">
+```
+
+This is an imperfect, brute force approach that can affect content as well as HTML attributes. As noted above, this is a legacy configuration option that will likely be removed in a future release.
+
+To enable:
+
+{{< code-toggle file=hugo >}}
+canonifyURLs = true
+{{< /code-toggle >}}
+
+#### Relative URLs
+
+> [!caution]
+> Do not enable this option unless you are creating a serverless site, navigable via the file system.
+{class="!mt-6"}
+
+If enabled, Hugo performs a search and replace _after_ it renders the page. It searches for site-relative URLs (those with a leading slash) associated with `action`, `href`, `src`, `srcset`, and `url` attributes. It then transforms the URL to be relative to the current page.
+
+For example, when rendering `content/posts/post-1`:
+
+```html
+<a href="/about"> → <a href="../../about">
+<img src="/a.gif"> → <img src="../../a.gif">
+```
+
+This is an imperfect, brute force approach that can affect content as well as HTML attributes. As noted above, do not enable this option unless you are creating a serverless site.
+
+To enable:
+
+{{< code-toggle file=hugo >}}
+relativeURLs = true
+{{< /code-toggle >}}
+
+## Aliases
+
+Aliases allow you to redirect old URLs to new URLs. This is essential for preventing broken links and ensuring that existing bookmarks or external links continue to function when you rename or move content.
+
+### Defining aliases
+
+To add redirects to a page, list the previous paths in the [`aliases`][aliases_field] field in your front matter. Hugo resolves these to [server-relative](g) paths during the build process, accounting for the [`baseURL`][] and [content dimension](g) prefixes such as language, version, or role.
+
+{{< code-toggle file=content/examples/example-1.en.md fm=true >}}
+title = 'Example 1'
+date = 2025-02-02
+aliases = ['/old-url', 'old-name', '../old/path']
+{{< /code-toggle >}}
+
+As shown in the example above, you can use [site-relative](g) paths or [page-relative](g) paths. Page-relative paths can also include directory traversal. Using the file `content/examples/example-1.en.md` as a reference point, here is how Hugo interprets those different path types:
+
+Path type|Alias|Server-relative path
+:--|:--|:--
+site-relative|`/old-url`|`/en/old-url/`
+page-relative|`old-name`|`/en/examples/old-name/`
+page-relative|`../old/path`|`/en/old/path/`
+
+### Redirection methods
+
+There are two ways to implement aliases depending on your hosting environment and preferences: client-side redirection and server-side redirection.
+
+> [!note]
+> Alias data is only generated for [output formats](g) where both [`isHTML`][] and [`permalinkable`][] are `true`. This affects both the creation of client-side redirect files and the results returned by the [`Aliases`][aliases_method] method used in server-side redirection.
+
+#### Client-side redirection
+
+By default, Hugo uses client-side redirection, generating a small HTML file for every alias. This file contains a `meta http-equiv="refresh"` tag that instructs the browser to navigate to the new URL. This approach is portable across all hosting providers.
+
+When using this method, Hugo creates a physical directory and an `index.html` file at each alias location. For example, if a page at `content/posts/new.md` has a page-relative alias of `old-path`, a file is generated at `public/posts/old-path/index.html`.
+
+Unless you provide a custom layout, Hugo uses its [embedded alias template][] to generate the redirect files:
+
+```go-html-template
+<!DOCTYPE html>
+<html lang="{{ site.Language.Locale }}">
+ <head>
+ <title>{{ .Permalink }}</title>
+ {{ with .OutputFormats.Canonical }}<link rel="{{ .Rel }}" href="{{ .Permalink }}">{{ end }}
+ <meta charset="utf-8">
+ <meta http-equiv="refresh" content="0; url={{ .Permalink }}">
+ </head>
+</html>
+```
+
+To override this, create a file named `alias.html` in your `layouts` directory. This custom template has access to the following context:
+
+`Permalink`
+: (`string`) The absolute URL of the destination page.
+
+`Page`
+: (`page.Page`) The full `Page` object of the destination.
+
+#### Server-side redirection
+
+Alternatively, you can implement server-side redirection by using the [`Aliases`][aliases_method] method on a `Page` object to generate a single configuration file that the web server processes. This method is more efficient because the redirect happens at the HTTP header level before any page content is processed, whereas a meta refresh requires the browser to download and parse the HTML body before acting. Additionally, server-side redirection improves build and deployment times because Hugo doesn't need to write a physical directory and HTML file for every alias.
+
+To implement this, you typically create a single template to generate the necessary rules for your specific host or server. Common examples include:
+
+- A `_redirects` file for hosting services such as Cloudflare, GitLab Pages, and Netlify.
+- An `.htaccess` file for web servers such as Apache and LiteSpeed.
+
+See the [`Aliases`][aliases_method] method page for a complete example of how to iterate through pages to generate these rules.
+
+If you implement server-side redirects, you should disable the generation of individual HTML files by setting [`disableAliases`][] to `true` in your project configuration. This setting only prevents the generation of the physical HTML files; the `Aliases` method on a `Page` object remains available for use in your configuration templates.
+
+[`baseURL`]: /configuration/all/#baseurl
+[`disableAliases`]: /configuration/all/#disablealiases
+[`isHTML`]: /configuration/output-formats/#ishtml
+[`permalinkable`]: /configuration/output-formats/#permalinkable
+[aliases_field]: /content-management/front-matter/#aliases
+[aliases_method]: /methods/page/aliases/
+[embedded alias template]: <{{% eturl alias %}}>
+[removed in a future release]: https://github.com/gohugoio/hugo/issues/4733
+[reserved characters]: https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions
diff --git a/documents/markdown/hugo-docs/en_contribute__index.md b/documents/markdown/hugo-docs/en_contribute__index.md
new file mode 100644
index 0000000..d0ae954
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_contribute__index.md
@@ -0,0 +1,9 @@
+---
+title: Contribute to the Hugo project
+linkTitle: Contribute
+description: Contribute to development, documentation, and themes.
+categories: []
+keywords: []
+weight: 10
+aliases: [/tutorials/how-to-contribute-to-hugo/,/community/contributing/]
+---
diff --git a/documents/markdown/hugo-docs/en_contribute_development.md b/documents/markdown/hugo-docs/en_contribute_development.md
new file mode 100644
index 0000000..2860f58
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_contribute_development.md
@@ -0,0 +1,148 @@
+---
+title: Development
+description: Contribute to the development of Hugo.
+categories: []
+keywords: []
+---
+
+## Introduction
+
+You can contribute to the Hugo project by:
+
+- Answering questions on the [forum]
+- Improving the [documentation]
+- Monitoring the [issue queue]
+- Creating or improving [themes]
+- Squashing [bugs]
+
+Please submit documentation issues and pull requests to the [documentation repository].
+
+If you have an idea for an enhancement or new feature, create a new topic on the [forum] in the "Feature" category. This will help you to:
+
+- Determine if the capability already exists
+- Measure interest
+- Refine the concept
+
+If there is sufficient interest, [create a proposal]. Do not submit a pull request until the project lead accepts the proposal.
+
+For a complete guide to contributing to Hugo, see the [Contribution Guide].
+
+## Prerequisites
+
+To build Hugo from source you must install:
+
+1. Install [Git]
+1. Install [Go] version 1.25.0 or later
+
+## GitHub workflow
+
+> [!note]
+> This section assumes that you have a working knowledge of Go, Git and GitHub, and are comfortable working on the command line.
+
+Use this workflow to create and submit pull requests.
+
+Step 1
+: Fork the [project repository].
+
+Step 2
+: Clone your fork.
+
+Step 3
+: Create a new branch with a descriptive name that includes the corresponding issue number.
+
+ For a new feature:
+
+ ```sh
+ git checkout -b feat/implement-some-feature-99999
+ ```
+
+ For a bug fix:
+
+ ```sh
+ git checkout -b fix/fix-some-bug-99999
+ ```
+
+Step 4
+: Make changes.
+
+Step 5
+: Build and install.
+
+ To build and install the standard edition:
+
+ ```sh
+ CGO_ENABLED=0 go install
+ ```
+
+ {{< new-in v0.159.2 />}} To build and install the deploy edition:
+
+ ```sh
+ CGO_ENABLED=0 go install -tags withdeploy
+ ```
+
+ To build and install the extended edition, first install a C compiler such as [GCC] or [Clang] and then run the following command:
+
+ ```sh
+ CGO_ENABLED=1 go install -tags extended
+ ```
+
+ To build and install the extended/deploy edition, first install a C compiler such as [GCC] or [Clang] and then run the following command:
+
+ ```sh
+ CGO_ENABLED=1 go install -tags extended,withdeploy
+ ```
+
+Step 6
+: Test your changes:
+
+ ```text
+ go test ./...
+ ```
+
+Step 7
+: Commit your changes with a descriptive commit message:
+
+ - Provide a summary on the first line, typically 50 characters or less, followed by a blank line.
+ - Begin the summary with the name of the package, followed by a colon, a space, and a brief description of the change beginning with a capital letter
+ - Use imperative present tense
+ - See the [commit message guidelines] for requirements
+ - Optionally, provide a detailed description where each line is 72 characters or less, followed by a blank line.
+ - Add one or more "Fixes" or "Closes" keywords, each on its own line, referencing the [issues] addressed by this change.
+
+ For example:
+
+ ```sh
+ git commit -m "tpl/strings: Create wrap function
+
+ The strings.Wrap function wraps a string into one or more lines,
+ splitting the string after the given number of characters, but not
+ splitting in the middle of a word.
+
+ Fixes #99998
+ Closes #99999"
+ ```
+
+Step 8
+: Push the new branch to your fork of the documentation repository.
+
+Step 9
+: Visit the [project repository] and create a pull request (PR).
+
+Step 10
+: A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR.
+
+[Clang]: https://clang.llvm.org/
+[Contribution Guide]: https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md
+[GCC]: https://gcc.gnu.org/
+[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+[Go]: https://go.dev/doc/install
+[bugs]: https://github.com/gohugoio/hugo/issues?q=is%3Aopen+is%3Aissue+label%3ABug
+[commit message guidelines]: https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md#git-commit-message-guidelines
+[create a proposal]: https://github.com/gohugoio/hugo/issues/new?labels=Proposal%2C+NeedsTriage&template=feature_request.md
+[documentation repository]: https://github.com/gohugoio/hugoDocs
+[documentation]: /documentation
+[forum]: https://discourse.gohugo.io
+[issue queue]: https://github.com/gohugoio/hugo/issues
+[issues]: https://github.com/gohugoio/hugo/issues
+[project repository]: https://github.com/gohugoio/hugo/
+[themes]: https://themes.gohugo.io/
diff --git a/documents/markdown/hugo-docs/en_contribute_documentation.md b/documents/markdown/hugo-docs/en_contribute_documentation.md
new file mode 100644
index 0000000..9d464f4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_contribute_documentation.md
@@ -0,0 +1,548 @@
+---
+title: Documentation
+description: Help us to improve the documentation by identifying issues and suggesting changes.
+categories: []
+keywords: []
+aliases: [/contribute/docs/]
+---
+
+## Introduction
+
+We welcome corrections and improvements to the documentation. The documentation lives in a separate repository from the main project. To contribute:
+
+- For corrections and improvements to existing documentation, submit issues and pull requests to the [documentation repository].
+- For documentation of new features, include the documentation changes in your pull request to the [project repository].
+
+## Guidelines
+
+### Style
+
+Follow Google's [developer documentation style guide].
+
+### Markdown
+
+Adhere to these Markdown conventions:
+
+- Use [ATX] headings (levels 2-4), not [setext] headings.
+- Use [collapsed link references][] instead of full or shortcut references. For example:
+
+ ```text
+ This is a [link][].
+
+ [link]: https://example.org
+ ```
+
+- Use [fenced code blocks] instead of [indented code blocks].
+- Use hyphens, not asterisks, for unordered [list items].
+- Use [callouts](#callouts) instead of bold text for emphasis.
+- Do not mix [raw HTML] within Markdown.
+- Do not use bold text in place of a heading or description term (`dt`).
+- Remove consecutive blank lines.
+- Remove trailing spaces.
+
+### Glossary
+
+[Glossary] terms are defined on individual pages, providing a central repository for definitions, though these pages are not directly linked from the site.
+
+Definitions must be complete sentences, with the first sentence defining the term. Italicize the first occurrence of the term and any referenced glossary terms for consistency.
+
+Link to glossary terms using this syntax: `[term](g)`
+
+Term lookups are case-insensitive, ignore formatting, and support singular and plural forms. For example, all of these variations will link to the same glossary term:
+
+```text
+[global resource](g)
+[Global Resource](g)
+[Global Resources](g)
+[`Global Resources`](g)
+```
+
+Use the [glossary-term shortcode](#glossary-term) to insert a term definition:
+
+```text
+{{%/* glossary-term "global resource" */%}}
+```
+
+### Terminology
+
+Link to the [glossary] as needed and use terms consistently. Pay particular attention to:
+
+- "front matter" (two words, except when referring to the configuration key)
+- "home page" (two words)
+- "website" (one word)
+- "standalone" (one word, no hyphen)
+- "map" (instead of "dictionary")
+- "flag" (instead of "option" for command-line flags)
+- "client side" (noun), "client-side" (adjective)
+- "server side" (noun), "server-side" (adjective)
+- "Markdown" (capitalized)
+- "open-source" (hyphenated adjective)
+- "Node.js" (first mention per page), "Node" (subsequent mentions), "node" (for the executable), "npm" (always lowercase)
+
+### Template types
+
+When you refer to a template type, italicize it:
+
+```text
+When creating a _taxonomy_ template, do this...
+```
+
+However, if the template type is also a link, do not italicize it to avoid distracting formatting:
+
+```text
+When creating a [taxonomy] template, do this...
+```
+
+Do not italicize the template type in a title, heading, or front matter description.
+
+### Titles and headings
+
+- Use sentence-style capitalization.
+- Avoid formatted strings.
+- Keep them concise.
+
+### Page descriptions
+
+When writing the page `description` use imperative present tense when possible. For example:
+
+{{< code-toggle file=content/en/functions/data/_index.md" fm=true >}}
+title: Data functions
+linkTitle: data
+description: Use these functions to read local or remote data files.
+{{< /code-toggle >}}
+
+### Writing style
+
+Use active voice and present tense wherever possible.
+
+No → With Hugo you can build a static site.\
+Yes → Build a static site with Hugo.
+
+No → This will cause Hugo to generate HTML files in the `public` directory.\
+Yes → Hugo generates HTML files in the `public` directory.
+
+Use second person instead of third person.
+
+No → Users should exercise caution when deleting files.\
+Better → You must be cautious when deleting files.\
+Best → Be cautious when deleting files.
+
+Minimize adverbs.
+
+No → Hugo is extremely fast.\
+Yes → Hugo is fast.
+
+> [!note]
+> "It's an adverb, Sam. It's a lazy tool of a weak mind." (Outbreak, 1995).
+
+### Function and method descriptions
+
+Start descriptions in the functions and methods sections with "Returns", or for boolean values, "Reports whether".
+
+### File paths and names
+
+Enclose directory names, file names, and file paths in backticks, except when used in:
+
+- Page titles
+- Section headings (h1-h6)
+- Definition list terms
+- The `description` field in front matter
+
+### Miscellaneous
+
+Other best practices:
+
+- Introduce lists with a sentence or phrase, not directly under a heading.
+- Avoid bold text; use [callouts](#callouts) for emphasis.
+- Do not put description terms (`dt`) in backticks unless syntactically necessary.
+- Do not use Hugo's `ref` or `relref` shortcodes.
+- Prioritize current best practices over multiple options or historical information.
+- Use short, focused code examples.
+- Use [basic english] where possible for a global audience.
+
+## Front matter fields
+
+This site uses the front matter fields listed in the table below.
+
+Of the four required fields, only `title` and `description` require data.
+
+```text
+title: The title
+description: The description
+categories: []
+keywords: []
+```
+
+This example demonstrates the minimum required front matter fields.
+
+If quotation marks are required, prefer single quotes to double quotes when possible.
+
+Field|Description|Required
+:--|:--|:--
+`title`|The page title|:heavy_check_mark:
+`linkTitle`|A short version of the page title|
+`description`|A complete sentence describing the page|:heavy_check_mark:
+`categories`|An array of terms in the categories taxonomy|:heavy_check_mark: [^1]
+`keywords`|An array of keywords used to identify related content|:heavy_check_mark: [^1]
+`publishDate`|Applicable to news items: the publication date|
+`params.alt_title`|An alternate title: used in the "see also" panel if provided|
+`params.functions_and_methods.aliases`|Applicable to function and method pages: an array of alias names|
+`params.functions_and_methods.returnType`|Applicable to function and method pages: the data type returned|
+`params.functions_and_methods.signatures`|Applicable to function and method pages: an array of signatures|
+`params.hide_in_this_section`|Whether to hide the "in this section" panel|
+`params.minversion`|Applicable to the quick start page: the minimum Hugo version required|
+`params.permalink`|Reserved for use by the news content adapter|
+`params.reference (used in glossary term)`|Applicable to glossary entries: a URL for additional information|
+`params.searchable`|Whether to add the content of this page to the search index. The default value is cascaded down from the project configuration; `true` if the page kind is `page`, and `false` if the page kind is one of `home`, `section`, `taxonomy`, or `term`. Add this field to override the default value.|
+`params.show_publish_date`|Whether to show the `publishDate` when rendering the page|
+`weight`|The page weight|
+`aliases`|Previous URLs used to access this page|
+`expirydate`|The expiration date|
+
+[^1]: The field is required, but its data is not.
+
+## Related content
+
+When available, the "See also" sidebar displays related pages using Hugo's [related content] feature, based on front matter keywords. We ensure consistent keyword usage by validating them against `data/keywords.yaml` during the build process. If a keyword is not found, you'll be alerted and must either modify the keyword or update the data file. This validation process helps to refine the related content for better results.
+
+If the title in the "See also" sidebar is ambiguous or the same as another page, you can define an alternate title in the front matter:
+
+{{< code-toggle file=hugo >}}
+title = 'Long descriptive title'
+linkTitle = 'Short title'
+[params]
+alt_title = 'Whatever you want'
+{{< /code-toggle >}}
+
+Use of the alternate title is limited to the "See also" sidebar.
+
+> [!note]
+> Think carefully before setting the `alt_title`. Use it only when absolutely necessary.
+
+## Code examples
+
+With examples of template code:
+
+- Indent with two spaces.
+- Insert a space after an opening action delimiter.
+- Insert a space before a closing action delimiter.
+- Do not add white space removal syntax to action delimiters unless required. For example, inline elements like `img` and `a` require whitespace removal on both sides.
+
+```go-html-template
+{{ if eq $foo $bar }}
+ {{ fmt.Printf "%s is %s" $foo $bar }}
+{{ end }}
+```
+
+### Fenced code blocks
+
+Always specify the language.
+
+When providing a Mardown example, set the code language to "text" to prevent
+erroneous lexing/highlighting of shortcode calls.
+
+````text
+```go-html-template
+{{ if eq $foo "bar" }}
+ {{ print "foo is bar" }}
+{{ end }}
+```
+````
+
+To include a file name header and copy-to-clipboard button:
+
+````text
+```go-html-template {file="layouts/_partials/foo.html" copy=true}
+{{ if eq $foo "bar" }}
+ {{ print "foo is bar" }}
+{{ end }}
+```
+````
+
+To wrap the code block within an initially-opened `details` element using a non-default summary:
+
+````text
+```go-html-template {details=true open=true summary="layouts/_partials/foo.html" copy=true}
+{{ if eq $foo "bar" }}
+ {{ print "foo is bar" }}
+{{ end }}
+```
+````
+
+Whitespace trimming is enabled by default. To override this behavior and preserve leading and trailing spaces:
+
+````text
+```go-html-template {trim=false}
+
+{{ if eq $foo "bar" }}
+ {{ print "foo is bar" }}
+{{ end }}
+
+```
+````
+
+### Shortcode calls
+
+Use this syntax :
+
+````text
+```text
+{{</*/* foo */*/>}}
+{{%/*/* foo */*/%}}
+```
+````
+
+### Project configuration
+
+Use the [code-toggle shortcode](#code-toggle) to include project configuration examples:
+
+```text
+{{</* code-toggle file=hugo */>}}
+baseURL = 'https://example.org/'
+locale = 'en-US'
+title = 'My Site'
+{{</* /code-toggle */>}}
+```
+
+### Front matter
+
+Use the [code-toggle shortcode](#code-toggle) to include front matter examples:
+
+```text
+{{</* code-toggle file=content/posts/my-first-post.md fm=true */>}}
+title = 'My first post'
+date = 2023-11-09T12:56:07-08:00
+draft = false
+{{</* /code-toggle */>}}
+```
+
+## Callouts
+
+To visually emphasize important information, use callouts (admonitions). Callout types are case-insensitive. Effective March 8, 2025, we utilize only three of the five available types.
+
+- note (272 instances)
+- warning (2 instances)
+- caution (1 instance)
+
+Limiting the number of callout types helps us to use them consistently.
+
+```text
+> [!note]
+> Useful information that users should know, even when skimming content.
+```
+
+> [!note]
+> Useful information that users should know, even when skimming content.
+
+```text
+> [!warning]
+> Urgent info that needs immediate user attention to avoid problems.
+```
+
+> [!warning]
+> Urgent info that needs immediate user attention to avoid problems.
+
+```text
+> [!caution]
+> Advises about risks or negative outcomes of certain actions.
+```
+
+> [!caution]
+> Advises about risks or negative outcomes of certain actions.
+
+```text
+> [!tip]
+> Helpful advice for doing things better or more easily.
+```
+
+> [!tip]
+> Helpful advice for doing things better or more easily.
+
+```text
+> [!important]
+> Key information users need to know to achieve their goal.
+```
+
+> [!important]
+> Key information users need to know to achieve their goal.
+
+## Shortcodes
+
+These shortcodes are commonly used throughout the documentation. Other shortcodes are available for specialized use.
+
+### code-toggle
+
+Use the `code-toggle` shortcode to display examples of project configuration, front matter, or data files. This shortcode takes these arguments:
+
+config
+: (`string`) The section of `hugo.Data.docs.config` to render.
+
+copy
+: (`bool`) Whether to display a copy-to-clipboard button. Default is `false`.
+
+datakey:
+: (`string`) The section of `hugo.Data.docs` to render.
+
+file
+: (`string`) The file name to display above the rendered code. Omit the file extension for project configuration examples.
+
+fm
+: (`bool`) Whether to render the code as front matter. Default is `false`.
+
+skipHeader
+: (`bool`) Whether to omit top-level key(s) when rendering a section of `hugo.Data.docs.config`.
+
+```text
+{{</* code-toggle file=hugo copy=true */>}}
+baseURL = 'https://example.org/'
+locale = 'en-US'
+title = 'My Site'
+{{</* /code-toggle */>}}
+```
+
+### deprecated-in
+
+Use the `deprecated-in` shortcode to indicate that a feature is deprecated:
+
+```text
+{{</* deprecated-in 0.144.0 /*/>}}
+```
+
+You can also include details:
+
+```text
+{{</* deprecated-in 0.144.0 */>}}
+Use [`hugo.IsServer`](/functions/hugo/isserver/) instead.
+{{</* /deprecated-in */>}}
+```
+
+### eturl
+
+Use the embedded template URL (`eturl`) shortcode to insert an absolute URL to the source code for an embedded template. The shortcode takes a single argument, the base file name of the template (omit the file extension).
+
+```text
+This is a link to the [embedded alias template].
+
+[embedded alias template]: <{{%/* eturl alias */%}}>
+```
+
+### glossary-term
+
+Use the `glossary-term` shortcode to insert the definition of the given glossary term.
+
+```text
+{{%/* glossary-term scalar */%}}
+```
+
+### include
+
+Use the `include` shortcode to include content from another page.
+
+```text
+{{%/* include "_common/glob-patterns.md" */%}}
+```
+
+### new-in
+
+Use the `new-in` shortcode to indicate a new feature:
+
+```text
+{{</* new-in 0.144.0 /*/>}}
+```
+
+You can also include details:
+
+```text
+{{</* new-in 0.144.0 */>}}
+This is a new feature.
+{{</* /new-in */>}}
+```
+
+## New features
+
+Use the [new-in](#new-in) shortcode to indicate a new feature.
+
+The new-in shortcode will trigger a build warning if the specified version is older than a predefined threshold, based on differences in major and minor versions. This serves as a reminder to remove this shortcode call. See [details](https://github.com/gohugoio/hugoDocs/blob/master/layouts/_partials/layouts/blocks/feature-state.html).
+
+## Deprecated features
+
+Use the [deprecated-in](#deprecated-in) shortcode to indicate that a feature is deprecated.
+
+The deprecated-in shortcode will trigger a build warning if the specified version is older than a predefined threshold, based on differences in major and minor versions. This serves as a reminder to remove this shortcode call and the associated content. See [details](https://github.com/gohugoio/hugoDocs/blob/master/layouts/_partials/layouts/blocks/feature-state.html).
+
+When deprecating a feature that has its own page, also set the `expiryDate` in front matter to two years from the date of deprecation. Include a brief comment to explain the setting:
+
+```yaml
+expiryDate: 2028-03-03 # deprecated 2026-03-03 in v0.157.0
+```
+
+## GitHub workflow
+
+> [!note]
+> This section assumes that you have a working knowledge of Git and GitHub, and are comfortable working on the command line.
+
+Use this workflow to create and submit pull requests.
+
+Step 1
+: Fork the [documentation repository].
+
+Step 2
+: Clone your fork.
+
+Step 3
+: Create a new branch with a descriptive name that includes the corresponding issue number, if any:
+
+ ```sh
+ git checkout -b restructure-foo-page-99999
+ ```
+
+Step 4
+: Make changes.
+
+Step 5
+: Build the site locally to preview your changes.
+
+Step 6
+: Commit your changes with a descriptive commit message:
+
+ - Provide a summary on the first line, typically 50 characters or less, followed by a blank line.
+ - Begin the summary with one of `content`, `theme`, `config`, `all`, or `misc`, followed by a colon, a space, and a brief description of the change beginning with a capital letter
+ - Use imperative present tense
+ - Optionally, provide a detailed description where each line is 72 characters or less, followed by a blank line.
+ - Optionally, add one or more "Fixes" or "Closes" keywords, each on its own line, referencing the [issues] addressed by this change.
+
+ For example:
+
+ ```text
+ git commit -m "content: Restructure the taxonomy page
+
+ This restructures the taxonomy page by splitting topics into logical
+ sections, each with one or more examples.
+
+ Fixes #9999
+ Closes #9998"
+ ```
+
+Step 7
+: Push the new branch to your fork of the documentation repository.
+
+Step 8
+: Visit the [documentation repository] and create a pull request (PR).
+
+Step 9
+: A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR.
+
+[ATX]: https://spec.commonmark.org/current/#atx-headings
+[basic english]: https://simple.wikipedia.org/wiki/Basic_English
+[collapsed link references]: https://discourse.gohugo.io/t/55714
+[developer documentation style guide]: https://developers.google.com/style
+[documentation repository]: https://github.com/gohugoio/hugoDocs/
+[fenced code blocks]: https://spec.commonmark.org/current/#fenced-code-blocks
+[glossary]: /quick-reference/glossary/
+[indented code blocks]: https://spec.commonmark.org/current/#indented-code-blocks
+[issues]: https://github.com/gohugoio/hugoDocs/issues
+[list items]: https://spec.commonmark.org/current/#list-items
+[project repository]: https://github.com/gohugoio/hugo
+[raw HTML]: https://spec.commonmark.org/current/#raw-html
+[related content]: /content-management/related-content/
+[setext]: https://spec.commonmark.org/current/#setext-heading
diff --git a/documents/markdown/hugo-docs/en_contribute_themes.md b/documents/markdown/hugo-docs/en_contribute_themes.md
new file mode 100644
index 0000000..8a3457b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_contribute_themes.md
@@ -0,0 +1,25 @@
+---
+title: Themes
+description: If you've built a Hugo theme and want to contribute back to the Hugo Community, please share it with us.
+categories: []
+keywords: []
+aliases: [/contribute/theme/]
+---
+
+Visit [themes.gohugo.io] to browse a collection of themes created by the Hugo community.
+
+To submit your theme:
+
+1. Read the [submission guidelines]
+1. Open a pull request in the [themes repository]
+
+Other useful theme directories:
+
+- [jamstack.club]
+- [jamstackthemes.dev]
+
+[jamstack.club]: https://jamstack.club/#ssg=hugo
+[jamstackthemes.dev]: https://jamstackthemes.dev/ssg/hugo
+[submission guidelines]: https://github.com/gohugoio/hugoThemesSiteBuilder/tree/main#readme
+[themes repository]: https://github.com/gohugoio/hugoThemesSiteBuilder
+[themes.gohugo.io]: https://themes.gohugo.io/
diff --git a/documents/markdown/hugo-docs/en_documentation.md b/documents/markdown/hugo-docs/en_documentation.md
new file mode 100644
index 0000000..9bd3421
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_documentation.md
@@ -0,0 +1,22 @@
+---
+title: Hugo Documentation
+linkTitle: Docs
+description: Hugo is the world's fastest static website engine. It's written in Go (aka Golang) and developed by bep, spf13 and friends.
+layout: list
+params:
+ searchable: false
+---
+
+<!--
+If we want content on this page at some point, considering taking it from:
+
+- https://gohugo.io/about/introduction/
+- https://gohugo.io/about/features/
+
+Try to use the same language (e.g., tagline) everywhere:
+
+- Home: https://gohugo.io/
+- Docs: https://gohugo.io/documentation/
+- Project repo: https://github.com/gohugoio/hugo?tab=readme-ov-file#readme
+- Docs repo: https://github.com/gohugoio/hugoDocs?tab=readme-ov-file#readme
+-->
diff --git a/documents/markdown/hugo-docs/en_functions__index.md b/documents/markdown/hugo-docs/en_functions__index.md
new file mode 100644
index 0000000..d308121
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions__index.md
@@ -0,0 +1,8 @@
+---
+title: Functions
+description: Use these functions within your templates and archetypes.
+categories: []
+keywords: []
+weight: 10
+aliases: [/layout/functions/,/templates/functions]
+---
diff --git a/documents/markdown/hugo-docs/en_functions_cast_ToFloat.md b/documents/markdown/hugo-docs/en_functions_cast_ToFloat.md
new file mode 100644
index 0000000..5720429
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_cast_ToFloat.md
@@ -0,0 +1,46 @@
+---
+title: cast.ToFloat
+description: Converts a value to a decimal floating-point number (base 10).
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [float]
+ returnType: float64
+ signatures: [cast.ToFloat INPUT]
+aliases: [/functions/float]
+---
+
+With a decimal (base 10) input:
+
+```go-html-template
+{{ float 11 }} → 11 (float64)
+{{ float "11" }} → 11 (float64)
+
+{{ float 11.1 }} → 11.1 (float64)
+{{ float "11.1" }} → 11.1 (float64)
+
+{{ float 11.9 }} → 11.9 (float64)
+{{ float "11.9" }} → 11.9 (float64)
+```
+
+With a binary (base 2) input:
+
+```go-html-template
+{{ float 0b11 }} → 3 (float64)
+```
+
+With an octal (base 8) input (use either notation):
+
+```go-html-template
+{{ float 011 }} → 9 (float64)
+{{ float "011" }} → 11 (float64)
+
+{{ float 0o11 }} → 9 (float64)
+```
+
+With a hexadecimal (base 16) input:
+
+```go-html-template
+{{ float 0x11 }} → 17 (float64)
+```
diff --git a/documents/markdown/hugo-docs/en_functions_cast_ToInt.md b/documents/markdown/hugo-docs/en_functions_cast_ToInt.md
new file mode 100644
index 0000000..4ede692
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_cast_ToInt.md
@@ -0,0 +1,50 @@
+---
+title: cast.ToInt
+description: Converts a value to a decimal integer (base 10).
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [int]
+ returnType: int
+ signatures: [cast.ToInt INPUT]
+aliases: [/functions/int]
+---
+
+With a decimal (base 10) input:
+
+```go-html-template
+{{ int 11 }} → 11 (int)
+{{ int "11" }} → 11 (int)
+
+{{ int 11.1 }} → 11 (int)
+{{ int 11.9 }} → 11 (int)
+```
+
+With a binary (base 2) input:
+
+```go-html-template
+{{ int 0b11 }} → 3 (int)
+{{ int "0b11" }} → 3 (int)
+```
+
+With an octal (base 8) input (use either notation):
+
+```go-html-template
+{{ int 011 }} → 9 (int)
+{{ int "011" }} → 9 (int)
+
+{{ int 0o11 }} → 9 (int)
+{{ int "0o11" }} → 9 (int)
+```
+
+With a hexadecimal (base 16) input:
+
+```go-html-template
+{{ int 0x11 }} → 17 (int)
+{{ int "0x11" }} → 17 (int)
+```
+
+> [!note]
+> Values with a leading zero are octal (base 8). When casting a string representation of a decimal (base 10) number, remove leading zeros:
+
+`{{ strings.TrimLeft "0" "0011" | int }} → 11`
diff --git a/documents/markdown/hugo-docs/en_functions_cast_ToString.md b/documents/markdown/hugo-docs/en_functions_cast_ToString.md
new file mode 100644
index 0000000..1bba001
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_cast_ToString.md
@@ -0,0 +1,49 @@
+---
+title: cast.ToString
+description: Converts a value to a string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [string]
+ returnType: string
+ signatures: [cast.ToString INPUT]
+aliases: [/functions/string]
+---
+
+With a decimal (base 10) input:
+
+```go-html-template
+{{ string 11 }} → 11 (string)
+{{ string "11" }} → 11 (string)
+
+{{ string 11.1 }} → 11.1 (string)
+{{ string "11.1" }} → 11.1 (string)
+
+{{ string 11.9 }} → 11.9 (string)
+{{ string "11.9" }} → 11.9 (string)
+```
+
+With a binary (base 2) input:
+
+```go-html-template
+{{ string 0b11 }} → 3 (string)
+{{ string "0b11" }} → 0b11 (string)
+```
+
+With an octal (base 8) input (use either notation):
+
+```go-html-template
+{{ string 011 }} → 9 (string)
+{{ string "011" }} → 011 (string)
+
+{{ string 0o11 }} → 9 (string)
+{{ string "0o11" }} → 0o11 (string)
+```
+
+With a hexadecimal (base 16) input:
+
+```go-html-template
+{{ string 0x11 }} → 17 (string)
+{{ string "0x11" }} → 0x11 (string)
+```
diff --git a/documents/markdown/hugo-docs/en_functions_cast__index.md b/documents/markdown/hugo-docs/en_functions_cast__index.md
new file mode 100644
index 0000000..1584ab1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_cast__index.md
@@ -0,0 +1,7 @@
+---
+title: Cast functions
+linkTitle: cast
+description: Use these functions to cast a value from one data type to another.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_collections_After.md b/documents/markdown/hugo-docs/en_functions_collections_After.md
new file mode 100644
index 0000000..28acfd6
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_After.md
@@ -0,0 +1,67 @@
+---
+title: collections.After
+description: Returns a slice containing the elements after the first N elements of the given slice.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [after]
+ returnType: '[]any'
+ signatures: [collections.After N SLICE]
+aliases: [/functions/after]
+---
+
+The following shows `after` being used in conjunction with the [`slice`]function:
+
+```go-html-template
+{{ $data := slice "one" "two" "three" "four" }}
+<ul>
+ {{ range after 2 $data }}
+ <li>{{ . }}</li>
+ {{ end }}
+</ul>
+```
+
+The template above is rendered to:
+
+```html
+<ul>
+ <li>three</li>
+ <li>four</li>
+</ul>
+```
+
+## Example of `after` with `first`: 2nd–4th most recent articles
+
+You can use `after` in combination with the [`first`] function and Hugo's [powerful sorting methods](/quick-reference/page-collections/#sort). Let's assume you have a `section` page at `example.com/articles`. You have 10 articles, but you want your template to show only two rows:
+
+1. The top row is titled "Featured" and shows only the most recently published article (i.e. by `publishdate` in the content files' front matter).
+1. The second row is titled "Recent Articles" and shows only the 2nd- to 4th-most recently published articles.
+
+```go-html-template {file="layouts/section/articles.html"}
+{{ define "main" }}
+ <section class="row featured-article">
+ <h2>Featured Article</h2>
+ {{ range first 1 .Pages.ByPublishDate.Reverse }}
+ <header>
+ <h3><a href="{{ .RelPermalink }}">{{ .Title }}</a></h3>
+ </header>
+ <p>{{ .Description }}</p>
+ {{ end }}
+ </section>
+ <div class="row recent-articles">
+ <h2>Recent Articles</h2>
+ {{ range first 3 (after 1 .Pages.ByPublishDate.Reverse) }}
+ <section class="recent-article">
+ <header>
+ <h3><a href="{{ .RelPermalink }}">{{ .Title }}</a></h3>
+ </header>
+ <p>{{ .Description }}</p>
+ </section>
+ {{ end }}
+ </div>
+{{ end }}
+```
+
+[`first`]: /functions/collections/first/
+[`slice`]: /functions/collections/slice/
diff --git a/documents/markdown/hugo-docs/en_functions_collections_Append.md b/documents/markdown/hugo-docs/en_functions_collections_Append.md
new file mode 100644
index 0000000..d392a3f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_Append.md
@@ -0,0 +1,100 @@
+---
+title: collections.Append
+description: Returns a slice by adding one or more elements, or an entire second slice, to the end of the given slice.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [append]
+ returnType: '[]any'
+ signatures:
+ - collections.Append ELEMENT [ELEMENT...] SLICE
+ - collections.Append SLICE1 SLICE2
+aliases: [/functions/append]
+---
+
+This function appends all elements, excluding the last, to the last element. This allows [pipe](g) constructs as shown below.
+
+Append a single element to a slice:
+
+```go-html-template
+{{ $s := slice "a" "b" }}
+{{ $s }} → [a b]
+
+{{ $s = $s | append "c" }}
+{{ $s }} → [a b c]
+```
+
+Append two elements to a slice:
+
+```go-html-template
+{{ $s := slice "a" "b" }}
+{{ $s }} → [a b]
+
+{{ $s = $s | append "c" "d" }}
+{{ $s }} → [a b c d]
+```
+
+Append two elements, as a slice, to a slice. This produces the same result as the previous example:
+
+```go-html-template
+{{ $s := slice "a" "b" }}
+{{ $s }} → [a b]
+
+{{ $s = $s | append (slice "c" "d") }}
+{{ $s }} → [a b c d]
+```
+
+Start with an empty slice:
+
+```go-html-template
+{{ $s := slice }}
+{{ $s }} → []
+
+{{ $s = $s | append "a" }}
+{{ $s }} → [a]
+
+{{ $s = $s | append "b" "c" }}
+{{ $s }} → [a b c]
+
+{{ $s = $s | append (slice "d" "e") }}
+{{ $s }} → [a b c d e]
+```
+
+If you start with a slice of a slice:
+
+```go-html-template
+{{ $s := slice (slice "a" "b") }}
+{{ $s }} → [[a b]]
+
+{{ $s = $s | append (slice "c" "d") }}
+{{ $s }} → [[a b] [c d]]
+```
+
+To create a slice of slices, starting with an empty slice:
+
+```go-html-template
+{{ $s := slice }}
+{{ $s }} → []
+
+{{ $s = $s | append (slice (slice "a" "b")) }}
+{{ $s }} → [[a b]]
+
+{{ $s = $s | append (slice "c" "d") }}
+{{ $s }} → [[a b] [c d]]
+```
+
+Although the elements in the examples above are strings, you can use the `append` function with any data type, including Pages. For example, on the home page of a corporate site, to display links to the two most recent press releases followed by links to the four most recent articles:
+
+```go-html-template
+{{ $p := where site.RegularPages "Type" "press-releases" | first 2 }}
+{{ $p = $p | append (where site.RegularPages "Type" "articles" | first 4) }}
+
+{{ with $p }}
+ <ul>
+ {{ range . }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_functions_collections_Apply.md b/documents/markdown/hugo-docs/en_functions_collections_Apply.md
new file mode 100644
index 0000000..1d4f9bf
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_Apply.md
@@ -0,0 +1,26 @@
+---
+title: collections.Apply
+description: Returns a slice by transforming each element of the given slice using a specific function and parameters.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [apply]
+ returnType: '[]any'
+ signatures: [collections.Apply SLICE FUNCTION PARAM...]
+aliases: [/functions/apply]
+---
+
+The `apply` function takes three or more arguments, depending on the function being applied to the slice elements.
+
+The first argument is the slice itself, the second argument is the function name, and the remaining arguments are passed to the function, with the string `"."` representing the slice element.
+
+```go-html-template
+{{ $s := slice "hello" "world" }}
+
+{{ $s = apply $s "strings.FirstUpper" "." }}
+{{ $s }} → [Hello World]
+
+{{ $s = apply $s "strings.Replace" "." "l" "_" }}
+{{ $s }} → [He__o Wor_d]
+```
diff --git a/documents/markdown/hugo-docs/en_functions_collections_Complement.md b/documents/markdown/hugo-docs/en_functions_collections_Complement.md
new file mode 100644
index 0000000..c9fc02c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_Complement.md
@@ -0,0 +1,73 @@
+---
+title: collections.Complement
+description: Returns a slice by identifying elements in the last given slice that do not appear in any of the preceding slices.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [complement]
+ returnType: '[]any'
+ signatures: ['collections.Complement SLICE [SLICE...]']
+aliases: [/functions/complement]
+---
+
+To find the elements within `$c3` that do not exist in `$c1` or `$c2`:
+
+```go-html-template
+{{ $c1 := slice 3 }}
+{{ $c2 := slice 4 5 }}
+{{ $c3 := slice 1 2 3 4 5 }}
+
+{{ complement $c1 $c2 $c3 }} → [1 2]
+```
+
+> [!note]
+> Make your code simpler to understand by using a [chained pipeline]:
+
+```go-html-template
+{{ $c3 | complement $c1 $c2 }} → [1 2]
+```
+
+You can also use the `complement` function with page collections. Let's say your site has five content types:
+
+```text
+content/
+├── blog/
+├── books/
+├── faqs/
+├── films/
+└── songs/
+```
+
+To list everything except blog articles (`blog`) and frequently asked questions (`faqs`):
+
+```go-html-template
+{{ $blog := where site.RegularPages "Type" "blog" }}
+{{ $faqs := where site.RegularPages "Type" "faqs" }}
+{{ range site.RegularPages | complement $blog $faqs }}
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+{{ end }}
+```
+
+> [!note]
+> Although the example above demonstrates the `complement` function, you could use the [`where`] function as well:
+
+```go-html-template
+{{ range where site.RegularPages "Type" "not in" (slice "blog" "faqs") }}
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+{{ end }}
+```
+
+In this example we use the `complement` function to remove [stop words] from a sentence:
+
+```go-html-template
+{{ $text := "The quick brown fox jumps over the lazy dog" }}
+{{ $stopWords := slice "a" "an" "in" "over" "the" "under" }}
+{{ $filtered := split $text " " | complement $stopWords }}
+
+{{ delimit $filtered " " }} → The quick brown fox jumps lazy dog
+```
+
+[`where`]: /functions/collections/where/
+[chained pipeline]: https://pkg.go.dev/text/template#hdr-Pipelines
+[stop words]: https://en.wikipedia.org/wiki/Stop_word
diff --git a/documents/markdown/hugo-docs/en_functions_collections_D.md b/documents/markdown/hugo-docs/en_functions_collections_D.md
new file mode 100644
index 0000000..3538632
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_D.md
@@ -0,0 +1,82 @@
+---
+title: collections.D
+description: Returns a sorted slice of unique random integers based on a given seed, count, and maximum value.
+categories: []
+keywords: [random]
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: '[]int'
+ signatures: [collections.D SEED N HIGH]
+---
+
+{{< new-in 0.149.0 />}}
+
+The `collections.D` function returns a sorted slice of unique random integers in the half-open [interval](g) `[0, HIGH)` using the provided [`SEED`](g) value. The number of elements in the resulting slice is `N` or `HIGH`, whichever is less.
+
+- `N` and `H` must be integers in the closed interval `[0, 1000000]`
+- `SEED` must be an integer in the closed interval `[0, 2^64 - 1]`
+
+## Return values
+
+Condition|Return value
+:--|:--|:--
+`N <= HIGH`|A sorted random sample of size `N` using J. S. Vitter's [Method D][] for sequential random sampling
+`N > HIGH`|The full, sorted range `[0, HIGH)` of size `HIGH`
+`N == 0`|An empty slice
+`N < 0`|Error
+`N > 10^6`|Error
+`HIGH == 0`|An empty slice
+`HIGH < 0`|Error
+`HIGH > 10^6`|Error
+`SEED < 0`|Error
+{.no-wrap-first-col}
+
+## Examples
+
+```go-html-template
+{{ collections.D 6 7 42 }} → [4, 9, 10, 20, 22, 24, 41]
+```
+
+The example above generates the _same_ random numbers each time it is called. To generate a _different_ set of 7 random numbers in the same range, change the seed value.
+
+```go-html-template
+{{ collections.D 2 7 42 }} → [3, 11, 19, 25, 32, 33, 38]
+```
+
+When `N` is greater than `HIGH`, this function returns the full, sorted range [0, `HIGH`) of size `HIGH`:
+
+```go-html-template
+{{ collections.D 6 42 7 }} → [0 1 2 3 4 5 6]
+```
+
+A common use case is the selection of random pages from a page collection. For example, to render a list of 5 random pages using the [day of the year][] as the seed value:
+
+```go-html-template
+<ul>
+ {{ $p := site.RegularPages }}
+ {{ range collections.D time.Now.YearDay 5 ($p | len) }}
+ {{ with (index $p .) }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ {{ end }}
+</ul>
+```
+
+The construct above is significantly faster than using the [`collections.Shuffle`][] function.
+
+## Seed value
+
+Choosing an appropriate seed value depends on your objective.
+
+Objective|Seed example
+:--|:--
+Consistent result|`42`
+Different result on each call|`int time.Now.UnixNano`
+Same result per day|`time.Now.YearDay`
+Same result per page|`hash.FNV32a .Path`
+Different result per page per day|`hash.FNV32a (print .Path time.Now.YearDay)`
+
+[`collections.Shuffle`]: /functions/collections/shuffle/
+[day of the year]: /methods/time/yearday/
+[Method D]: https://getkerf.wordpress.com/2016/03/30/the-best-algorithm-no-one-knows-about/
diff --git a/documents/markdown/hugo-docs/en_functions_collections_Delimit.md b/documents/markdown/hugo-docs/en_functions_collections_Delimit.md
new file mode 100644
index 0000000..b8cba7f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_Delimit.md
@@ -0,0 +1,31 @@
+---
+title: collections.Delimit
+description: Returns a string by joining the values of the given slice or map with a delimiter.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [delimit]
+ returnType: string
+ signatures: ['collections.Delimit SLICE|MAP DELIMITER [LAST]']
+aliases: [/functions/delimit]
+---
+
+Delimit a slice:
+
+```go-html-template
+{{ $s := slice "b" "a" "c" }}
+{{ delimit $s ", " }} → b, a, c
+{{ delimit $s ", " " and "}} → b, a and c
+```
+
+Delimit a map:
+
+> [!note]
+> The `delimit` function sorts maps by key, returning the values.
+
+```go-html-template
+{{ $m := dict "b" 2 "a" 1 "c" 3 }}
+{{ delimit $m ", " }} → 1, 2, 3
+{{ delimit $m ", " " and "}} → 1, 2 and 3
+```
diff --git a/documents/markdown/hugo-docs/en_functions_collections_Dictionary.md b/documents/markdown/hugo-docs/en_functions_collections_Dictionary.md
new file mode 100644
index 0000000..621adb8
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_Dictionary.md
@@ -0,0 +1,51 @@
+---
+title: collections.Dictionary
+description: Returns a map created from the given key-value pairs.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [dict]
+ returnType: map[string]any
+ signatures: ['collections.Dictionary [VALUE...]']
+aliases: [/functions/dict]
+---
+
+Specify the key-value pairs as individual arguments:
+
+```go-html-template
+{{ $m := dict "a" 1 "b" 2 }}
+```
+
+The above produces this data structure:
+
+```json
+{
+ "a": 1,
+ "b": 2
+}
+```
+
+To create an empty map:
+
+```go-html-template
+{{ $m := dict }}
+```
+
+Note that the `key` can be either a `string` or a `[]string`. The latter is useful to create a deeply nested structure, e.g.:
+
+```go-html-template
+{{ $m := dict (slice "a" "b" "c") "value" }}
+```
+
+The above produces this data structure:
+
+```json
+{
+ "a": {
+ "b": {
+ "c": "value"
+ }
+ }
+}
+```
diff --git a/documents/markdown/hugo-docs/en_functions_collections_First.md b/documents/markdown/hugo-docs/en_functions_collections_First.md
new file mode 100644
index 0000000..2df5ec0
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_First.md
@@ -0,0 +1,56 @@
+---
+title: collections.First
+description: Returns the first N elements of the given slice or string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [first]
+ returnType: 'any'
+ signatures: [collections.First N SLICE|STRING]
+aliases: [/functions/first]
+---
+
+```go-html-template
+{{ slice "a" "b" "c" | first 1 }} → [a]
+{{ slice "a" "b" "c" | first 2 }} → [a b]
+```
+
+Given that a string is in effect a read-only slice of bytes, this function can be used to return the specified number of bytes from the beginning of the string:
+
+```go-html-template
+{{ "abc" | first 1 }} → a
+{{ "abc" | first 2 }} → ab
+```
+
+Note that a _character_ may consist of multiple _bytes_:
+
+```go-html-template
+{{ "Schön" | first 3 }} → Sch
+{{ "Schön" | first 4 }} → Sch\xc3
+{{ "Schön" | first 5 }} → Schö
+```
+
+To use the `collections.First` function with a page collection:
+
+```go-html-template
+{{ range first 5 .Pages }}
+ {{ .Render "summary" }}
+{{ end }}
+```
+
+Set `N` to zero to return an empty slice:
+
+```go-html-template
+{{ $emptyPageCollection := first 0 .Pages }}
+```
+
+Use `first` and [`where`][] together:
+
+```go-html-template
+{{ range where .Pages "Section" "articles" | first 5 }}
+ {{ .Render "summary" }}
+{{ end }}
+```
+
+[`where`]: /functions/collections/where/
diff --git a/documents/markdown/hugo-docs/en_functions_collections_Group.md b/documents/markdown/hugo-docs/en_functions_collections_Group.md
new file mode 100644
index 0000000..3542e3f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_Group.md
@@ -0,0 +1,31 @@
+---
+title: collections.Group
+description: Returns a map by grouping the given page collection (slice) by a specific key.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [group]
+ returnType: page.PageGroup
+ signatures: [collections.Group KEY PAGES]
+aliases: [/functions/group]
+---
+
+```go-html-template
+{{ $new := .Site.RegularPages | first 10 | group "New" }}
+{{ $old := .Site.RegularPages | last 10 | group "Old" }}
+{{ $groups := slice $new $old }}
+{{ range $groups }}
+ <h3>{{ .Key }}{{/* Prints "New", "Old" */}}</h3>
+ <ul>
+ {{ range .Pages }}
+ <li>
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+ <div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
+ </li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+The page group you get from `group` is of the same type you get from the built-in [group methods](/quick-reference/page-collections/#group) in Hugo. The example above can be [paginated](/templates/pagination/).
diff --git a/documents/markdown/hugo-docs/en_functions_collections_In.md b/documents/markdown/hugo-docs/en_functions_collections_In.md
new file mode 100644
index 0000000..3ae72f1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_In.md
@@ -0,0 +1,22 @@
+---
+title: collections.In
+description: Reports whether a value exists within the given slice or string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [in]
+ returnType: bool
+ signatures: [collections.In SLICE|STRING VALUE]
+aliases: [/functions/in]
+---
+
+```go-html-template
+{{ $s := slice "a" "b" "c" }}
+{{ in $s "b" }} → true
+```
+
+```go-html-template
+{{ $s := "abc" }}
+{{ in $s "b" }} → true
+```
diff --git a/documents/markdown/hugo-docs/en_functions_collections_IndexFunction.md b/documents/markdown/hugo-docs/en_functions_collections_IndexFunction.md
new file mode 100644
index 0000000..f7155c5
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_IndexFunction.md
@@ -0,0 +1,50 @@
+---
+title: collections.Index
+description: Returns an element or value from the given slice or map at the specified key(s).
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [index]
+ returnType: any
+ signatures: [collections.Index SLICE|MAP KEY...]
+aliases: [/functions/index,/functions/index-function]
+---
+
+Each indexed item must be a map or a slice:
+
+```go-html-template
+{{ $s := slice "a" "b" "c" }}
+{{ index $s 0 }} → a
+{{ index $s 1 }} → b
+
+{{ $m := dict "a" 100 "b" 200 }}
+{{ index $m "b" }} → 200
+```
+
+Use two or more keys to access a nested value:
+
+```go-html-template
+{{ $m := dict "a" 100 "b" 200 "c" (slice 10 20 30) }}
+{{ index $m "c" 1 }} → 20
+
+{{ $m := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }}
+{{ index $m "c" "e" }} → 20
+```
+
+You may also use a slice of keys to access a nested value:
+
+```go-html-template
+{{ $m := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }}
+{{ $s := slice "c" "e" }}
+{{ index $m $s }} → 20
+```
+
+Use the `collections.Index` function to access a nested value when the key is variable. For example, these are equivalent:
+
+```go-html-template
+{{ .Site.Params.foo }}
+
+{{ $k := "foo" }}
+{{ index .Site.Params $k }}
+```
diff --git a/documents/markdown/hugo-docs/en_functions_collections_Intersect.md b/documents/markdown/hugo-docs/en_functions_collections_Intersect.md
new file mode 100644
index 0000000..3f7d9de
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_Intersect.md
@@ -0,0 +1,24 @@
+---
+title: collections.Intersect
+description: Returns a slice containing the common elements found in two given slices, in the same order as the first slice.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [intersect]
+ returnType: '[]any'
+ signatures: [collections.Intersect SLICE1 SLICE2]
+aliases: [/functions/intersect]
+---
+
+A useful example is to use it as `AND` filters when combined with where:
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Type" "not in" (slice "page" "about") }}
+{{ $pages := $pages | union (where .Site.RegularPages "Params.pinned" true) }}
+{{ $pages := $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }}
+```
+
+The above fetches regular pages not of `page` or `about` type unless they are pinned. And finally, we exclude all pages with no `images` set in Page parameters.
+
+See [union](/functions/collections/union) for `OR`.
diff --git a/documents/markdown/hugo-docs/en_functions_collections_IsSet.md b/documents/markdown/hugo-docs/en_functions_collections_IsSet.md
new file mode 100644
index 0000000..9a37f35
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_IsSet.md
@@ -0,0 +1,42 @@
+---
+title: collections.IsSet
+description: Reports whether a specific key or index exists in the given map or slice.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [isset]
+ returnType: bool
+ signatures: [collections.IsSet MAP|SLICE KEY|INDEX]
+aliases: [/functions/isset]
+---
+
+For example, consider this project configuration:
+
+{{< code-toggle file=hugo >}}
+[params]
+showHeroImage = false
+{{< /code-toggle >}}
+
+If the value of `showHeroImage` is `true`, we can detect that it exists using either `if` or `with`:
+
+```go-html-template
+{{ if site.Params.showHeroImage }}
+ {{ site.Params.showHeroImage }} → true
+{{ end }}
+
+{{ with site.Params.showHeroImage }}
+ {{ . }} → true
+{{ end }}
+```
+
+But if the value of `showHeroImage` is `false`, we can't use either `if` or `with` to detect its existence. In this case, you must use the `isset` function:
+
+```go-html-template
+{{ if isset site.Params "showheroimage" }}
+ <p>The showHeroImage parameter is set to {{ site.Params.showHeroImage }}.<p>
+{{ end }}
+```
+
+> [!note]
+> When using the `isset` function you must reference the key using lower case. See the previous example.
diff --git a/documents/markdown/hugo-docs/en_functions_collections_KeyVals.md b/documents/markdown/hugo-docs/en_functions_collections_KeyVals.md
new file mode 100644
index 0000000..12d0a00
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_KeyVals.md
@@ -0,0 +1,42 @@
+---
+title: collections.KeyVals
+description: Returns a KeyVals struct by pairing a given key and values.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [keyVals]
+ returnType: types.KeyValues
+ signatures: [collections.KeyVals KEY VALUE...]
+aliases: [/functions/keyvals]
+---
+
+The primary application for this function is the definition of the `namedSlices` value in the options map passed to the [`Related`] method on the `Pages` object.
+
+[`Related`]: /methods/pages/related/
+
+See [related content](/content-management/related-content/).
+
+```go-html-template
+{{ $kv := keyVals "foo" "a" "b" "c" }}
+```
+
+The resulting data structure is:
+
+```json
+{
+ "Key": "foo",
+ "Values": [
+ "a",
+ "b",
+ "c"
+ ]
+}
+```
+
+To extract the key and values:
+
+```go-html-template
+{{ $kv.Key }} → foo
+{{ $kv.Values }} → [a b c]
+```
diff --git a/documents/markdown/hugo-docs/en_functions_collections_Last.md b/documents/markdown/hugo-docs/en_functions_collections_Last.md
new file mode 100644
index 0000000..9c0dc6f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_Last.md
@@ -0,0 +1,56 @@
+---
+title: collections.Last
+description: Returns the last N elements of the given slice or string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [last]
+ returnType: 'any'
+ signatures: [collections.Last N SLICE|STRING]
+aliases: [/functions/last]
+---
+
+```go-html-template
+{{ slice "a" "b" "c" | last 1 }} → [c]
+{{ slice "a" "b" "c" | last 2 }} → [b c]
+```
+
+Given that a string is in effect a read-only slice of bytes, this function can be used to return the specified number of bytes from the end of the string:
+
+```go-html-template
+{{ "abc" | last 1 }} → c
+{{ "abc" | last 2 }} → bc
+```
+
+Note that a _character_ may consist of multiple _bytes_:
+
+```go-html-template
+{{ "Schön" | last 1 }} → n
+{{ "Schön" | last 2 }} → \xb6n
+{{ "Schön" | last 3 }} → ön
+```
+
+To use the `collections.Last` function with a page collection:
+
+```go-html-template
+{{ range last 5 .Pages }}
+ {{ .Render "summary" }}
+{{ end }}
+```
+
+Set `N` to zero to return an empty slice:
+
+```go-html-template
+{{ $emptyPageCollection := last 0 .Pages }}
+```
+
+Use `last` and [`where`][] together:
+
+[`where`]: /functions/collections/where/
+
+```go-html-template
+{{ range where .Pages "Section" "articles" | last 5 }}
+ {{ .Render "summary" }}
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_functions_collections_Merge.md b/documents/markdown/hugo-docs/en_functions_collections_Merge.md
new file mode 100644
index 0000000..d86b58c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_Merge.md
@@ -0,0 +1,67 @@
+---
+title: collections.Merge
+description: Returns a map by combining two or more given maps.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [merge]
+ returnType: map[string]any
+ signatures: [collections.Merge MAP MAP...]
+aliases: [/functions/merge]
+---
+
+Returns the result of merging two or more maps from left to right. If a key already exists, `merge` updates its value. If a key is absent, `merge` inserts the value under the new key.
+
+Key handling is case-insensitive.
+
+The following examples use these map definitions:
+
+```go-html-template
+{{ $m1 := dict "x" "foo" }}
+{{ $m2 := dict "x" "bar" "y" "wibble" }}
+{{ $m3 := dict "x" "baz" "y" "wobble" "z" (dict "a" "huey") }}
+```
+
+Example 1
+
+```go-html-template
+{{ $merged := merge $m1 $m2 $m3 }}
+
+{{ $merged.x }} → baz
+{{ $merged.y }} → wobble
+{{ $merged.z.a }} → huey
+```
+
+Example 2
+
+```go-html-template
+{{ $merged := merge $m3 $m2 $m1 }}
+
+{{ $merged.x }} → foo
+{{ $merged.y }} → wibble
+{{ $merged.z.a }} → huey
+```
+
+Example 3
+
+```go-html-template
+{{ $merged := merge $m2 $m3 $m1 }}
+
+{{ $merged.x }} → foo
+{{ $merged.y }} → wobble
+{{ $merged.z.a }} → huey
+```
+
+Example 4
+
+```go-html-template
+{{ $merged := merge $m1 $m3 $m2 }}
+
+{{ $merged.x }} → bar
+{{ $merged.y }} → wibble
+{{ $merged.z.a }} → huey
+```
+
+> [!note]
+> Regardless of depth, merging only applies to maps. For slices, use [append](/functions/collections/append).
diff --git a/documents/markdown/hugo-docs/en_functions_collections_NewScratch.md b/documents/markdown/hugo-docs/en_functions_collections_NewScratch.md
new file mode 100644
index 0000000..82f9a3c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_NewScratch.md
@@ -0,0 +1,119 @@
+---
+title: collections.NewScratch
+description: Returns a locally scoped "scratch pad" to store and manipulate data.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [newScratch]
+ returnType: maps.Scratch
+ signatures: [collections.NewScratch]
+---
+
+Use the `collections.NewScratch` function to create a locally scoped [scratch pad](g) to store and manipulate data. To create a scratch pad with a different [scope](g), refer to the [scope](#scope) section below.
+
+## Methods
+
+### Set
+
+Sets the value of the given key.
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.Set "greeting" "Hello" }}
+```
+
+### Get
+
+Gets the value of the given key.
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.Set "greeting" "Hello" }}
+{{ $s.Get "greeting" }} → Hello
+```
+
+### Add
+
+Adds the given value to existing value(s) of the given key.
+
+For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list.
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.Set "greeting" "Hello" }}
+{{ $s.Add "greeting" "Welcome" }}
+{{ $s.Get "greeting" }} → HelloWelcome
+```
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.Set "total" 3 }}
+{{ $s.Add "total" 7 }}
+{{ $s.Get "total" }} → 10
+```
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.Set "greetings" (slice "Hello") }}
+{{ $s.Add "greetings" (slice "Welcome" "Cheers") }}
+{{ $s.Get "greetings" }} → [Hello Welcome Cheers]
+```
+
+### SetInMap
+
+Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`.
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.SetInMap "greetings" "english" "Hello" }}
+{{ $s.SetInMap "greetings" "french" "Bonjour" }}
+{{ $s.Get "greetings" }} → map[english:Hello french:Bonjour]
+```
+
+### DeleteInMap
+
+Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.SetInMap "greetings" "english" "Hello" }}
+{{ $s.SetInMap "greetings" "french" "Bonjour" }}
+{{ $s.DeleteInMap "greetings" "english" }}
+{{ $s.Get "greetings" }} → map[french:Bonjour]
+```
+
+### GetSortedMapValues
+
+Returns an array of values from `key` sorted by `mapKey`.
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.SetInMap "greetings" "english" "Hello" }}
+{{ $s.SetInMap "greetings" "french" "Bonjour" }}
+{{ $s.GetSortedMapValues "greetings" }} → [Hello Bonjour]
+```
+
+### Delete
+
+Removes the given key.
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.Set "greeting" "Hello" }}
+{{ $s.Delete "greeting" }}
+```
+
+### Values
+
+Returns the raw backing map. Do not use with `Store` methods on a `Page` object due to concurrency issues.
+
+```go-html-template
+{{ $s := newScratch }}
+{{ $s.SetInMap "greetings" "english" "Hello" }}
+{{ $s.SetInMap "greetings" "french" "Bonjour" }}
+
+{{ $map := $s.Values }}
+```
+
+{{% include "_common/scratch-pad-scope.md" %}}
diff --git a/documents/markdown/hugo-docs/en_functions_collections_Querify.md b/documents/markdown/hugo-docs/en_functions_collections_Querify.md
new file mode 100644
index 0000000..53a30f0
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_Querify.md
@@ -0,0 +1,48 @@
+---
+title: collections.Querify
+description: Returns a URL query string from the given map, slice, or sequence of key-value pairs.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [querify]
+ returnType: string
+ signatures: [collections.Querify MAP|SLICE|KEY VALUE...]
+aliases: [/functions/querify]
+---
+
+Specify the key-value pairs as a map, a slice, or a sequence of scalar values. For example, the following are equivalent:
+
+```go-html-template
+{{ collections.Querify (dict "a" 1 "b" 2) }}
+{{ collections.Querify (slice "a" 1 "b" 2) }}
+{{ collections.Querify "a" 1 "b" 2 }}
+```
+
+To append a query string to a URL:
+
+```go-html-template
+{{ $qs := collections.Querify (dict "a" 1 "b" 2) }}
+{{ $href := printf "https://example.org?%s" $qs }}
+
+<a href="{{ $href }}">Link</a>
+```
+
+Hugo renders this to:
+
+```html
+<a href="https://example.org?a=1&b=2">Link</a>
+```
+
+You can also pass in a map from your project configuration or front matter. For example:
+
+{{< code-toggle file=content/example.md fm=true >}}
+title = 'Example'
+[params.query]
+a = 1
+b = 2
+{{< /code-toggle >}}
+
+```go-html-template
+{{ collections.Querify .Params.query }}
+```
diff --git a/documents/markdown/hugo-docs/en_functions_collections_Reverse.md b/documents/markdown/hugo-docs/en_functions_collections_Reverse.md
new file mode 100644
index 0000000..e443583
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_Reverse.md
@@ -0,0 +1,16 @@
+---
+title: collections.Reverse
+description: Returns a slice by reversing the order of elements in the given slice.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: '[]any'
+ signatures: [collections.Reverse SLICE]
+aliases: [/functions/collections.reverse]
+---
+
+```go-html-template
+{{ slice 2 1 3 | collections.Reverse }} → [3 1 2]
+```
diff --git a/documents/markdown/hugo-docs/en_functions_collections_Seq.md b/documents/markdown/hugo-docs/en_functions_collections_Seq.md
new file mode 100644
index 0000000..93cd5cc
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_Seq.md
@@ -0,0 +1,35 @@
+---
+title: collections.Seq
+description: Returns a slice of integers starting from 1 or a given value, incrementing by 1 or a given value, and ending at a given value.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [seq]
+ returnType: '[]int'
+ signatures:
+ - collections.Seq LAST
+ - collections.Seq FIRST LAST
+ - collections.Seq FIRST INCREMENT LAST
+aliases: [/functions/seq]
+---
+
+```go-html-template
+{{ seq 2 }} → [1 2]
+{{ seq 0 2 }} → [0 1 2]
+{{ seq -2 2 }} → [-2 -1 0 1 2]
+{{ seq -2 2 2 }} → [-2 0 2]
+```
+
+A contrived example of iterating over a sequence of integers:
+
+```go-html-template
+{{ $product := 1 }}
+{{ range seq 4 }}
+ {{ $product = mul $product . }}
+{{ end }}
+{{ $product }} → 24
+```
+
+> [!note]
+> The slice created by this function is limited to 1 million elements.
diff --git a/documents/markdown/hugo-docs/en_functions_collections_Shuffle.md b/documents/markdown/hugo-docs/en_functions_collections_Shuffle.md
new file mode 100644
index 0000000..cdaea0a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_Shuffle.md
@@ -0,0 +1,35 @@
+---
+title: collections.Shuffle
+description: Returns a slice by randomizing the element order of the given slice.
+categories: []
+keywords: [random]
+params:
+ functions_and_methods:
+ aliases: [shuffle]
+ returnType: '[]any'
+ signatures: [collections.Shuffle SLICE]
+aliases: [/functions/shuffle]
+---
+
+```go-html-template
+{{ collections.Shuffle (slice "a" "b" "c") }} → [b a c]
+```
+
+The result will vary from one build to the next.
+
+To render an unordered list of 5 random pages from a page collection:
+
+```go-html-template
+<ul>
+ {{ $p := site.RegularPages }}
+ {{ range $p | collections.Shuffle | first 5 }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+{{< new-in 0.149.0 />}}
+
+Using the [`collections.D`][] function for the same task is significantly faster.
+
+[`collections.D`]: /functions/collections/D/
diff --git a/documents/markdown/hugo-docs/en_functions_collections_Slice.md b/documents/markdown/hugo-docs/en_functions_collections_Slice.md
new file mode 100644
index 0000000..bcf9b9c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_Slice.md
@@ -0,0 +1,23 @@
+---
+title: collections.Slice
+description: Returns a slice created from the given values.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [slice]
+ returnType: '[]any'
+ signatures: ['collections.Slice [VALUE...]']
+aliases: [/functions/slice]
+---
+
+```go-html-template
+{{ $s := slice "a" "b" "c" }}
+{{ $s }} → [a b c]
+```
+
+To create an empty slice:
+
+```go-html-template
+{{ $s := slice }}
+```
diff --git a/documents/markdown/hugo-docs/en_functions_collections_Sort.md b/documents/markdown/hugo-docs/en_functions_collections_Sort.md
new file mode 100644
index 0000000..c7bea6c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_Sort.md
@@ -0,0 +1,150 @@
+---
+title: collections.Sort
+description: Returns a sorted map or slice by reordering the given collection by a key and order.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [sort]
+ returnType: any
+ signatures: ['collections.Sort MAP|SLICE [KEY] [ORDER]']
+aliases: [/functions/sort]
+---
+
+The `KEY` is optional when sorting slices in ascending order, otherwise it is required. When sorting slices, use the literal `value` in place of the `KEY`. See examples below.
+
+The `ORDER` may be either `asc` (ascending) or `desc` (descending). The default sort order is ascending.
+
+## Sort a slice
+
+The examples below assume this project configuration:
+
+{{< code-toggle file=hugo >}}
+[params]
+grades = ['b','a','c']
+{{< /code-toggle >}}
+
+### Ascending order {#slice-ascending-order}
+
+Sort slice elements in ascending order using either of these constructs:
+
+```go-html-template
+{{ sort site.Params.grades }} → [a b c]
+{{ sort site.Params.grades "value" "asc" }} → [a b c]
+```
+
+In the examples above, `value` is the `KEY` representing the value of the slice element.
+
+### Descending order {#slice-descending-order}
+
+Sort slice elements in descending order:
+
+```go-html-template
+{{ sort site.Params.grades "value" "desc" }} → [c b a]
+```
+
+In the example above, `value` is the `KEY` representing the value of the slice element.
+
+## Sort a map
+
+The examples below assume this project configuration:
+
+{{< code-toggle file=hugo >}}
+[params.authors.a]
+firstName = 'Marius'
+lastName = 'Pontmercy'
+[params.authors.b]
+firstName = 'Victor'
+lastName = 'Hugo'
+[params.authors.c]
+firstName = 'Jean'
+lastName = 'Valjean'
+{{< /code-toggle >}}
+
+> [!note]
+> When sorting maps, the `KEY` argument must be lowercase.
+
+### Ascending order {#map-ascending-order}
+
+Sort map objects in ascending order using either of these constructs:
+
+```go-html-template
+{{ range sort site.Params.authors "firstname" }}
+ {{ .firstName }}
+{{ end }}
+
+{{ range sort site.Params.authors "firstname" "asc" }}
+ {{ .firstName }}
+{{ end }}
+```
+
+These produce:
+
+```text
+Jean Marius Victor
+```
+
+### Descending order {#map-descending-order}
+
+Sort map objects in descending order:
+
+```go-html-template
+{{ range sort site.Params.authors "firstname" "desc" }}
+ {{ .firstName }}
+{{ end }}
+```
+
+This produces:
+
+```text
+Victor Marius Jean
+```
+
+### First level key removal
+
+Hugo removes the first level keys when sorting a map.
+
+Original map:
+
+```json
+{
+ "felix": {
+ "breed": "malicious",
+ "type": "cat"
+ },
+ "spot": {
+ "breed": "boxer",
+ "type": "dog"
+ }
+}
+```
+
+After sorting:
+
+```json
+[
+ {
+ "breed": "malicious",
+ "type": "cat"
+ },
+ {
+ "breed": "boxer",
+ "type": "dog"
+ }
+]
+```
+
+## Sort a page collection
+
+> [!note]
+> Although you can use the `sort` function to sort a page collection, Hugo provides [sorting and grouping methods] as well.
+
+In this contrived example, sort the site's regular pages by `.Type` in descending order:
+
+```go-html-template
+{{ range sort site.RegularPages "Type" "desc" }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+[sorting and grouping methods]: /methods/pages/
diff --git a/documents/markdown/hugo-docs/en_functions_collections_SymDiff.md b/documents/markdown/hugo-docs/en_functions_collections_SymDiff.md
new file mode 100644
index 0000000..a895da0
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_SymDiff.md
@@ -0,0 +1,20 @@
+---
+title: collections.SymDiff
+description: Returns a slice containing the symmetric difference of two given slices.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [symdiff]
+ returnType: '[]any'
+ signatures: [SLICE1 | collections.SymDiff SLICE2]
+aliases: [/functions/symdiff]
+---
+
+Example:
+
+```go-html-template
+{{ slice 1 2 3 | symdiff (slice 3 4) }} → [1 2 4]
+```
+
+Also see <https://en.wikipedia.org/wiki/Symmetric_difference>.
diff --git a/documents/markdown/hugo-docs/en_functions_collections_Union.md b/documents/markdown/hugo-docs/en_functions_collections_Union.md
new file mode 100644
index 0000000..53e94ac
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_Union.md
@@ -0,0 +1,35 @@
+---
+title: collections.Union
+description: Returns a slice containing the unique elements from two given slices.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [union]
+ returnType: '[]any'
+ signatures: [collections.Union SLICE1 SLICE2]
+aliases: [/functions/union]
+---
+
+
+
+```go-html-template
+{{ union (slice 1 2 3) (slice 3 4 5) }} → [1 2 3 4 5]
+{{ union (slice 1 2 3) nil }} → [1 2 3]
+{{ union nil (slice 1 2 3) }} → [1 2 3]
+{{ union nil nil }} → []
+```
+
+## OR filter in where query
+
+This is also very useful to use as `OR` filters when combined with where:
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Type" "not in" (slice "page" "about") }}
+{{ $pages = $pages | union (where .Site.RegularPages "Params.pinned" true) }}
+{{ $pages = $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }}
+```
+
+The above fetches regular pages not of `page` or `about` type unless they are pinned. And finally, we exclude all pages with no `images` set in Page parameters.
+
+See [intersect](/functions/collections/intersect) for `AND`.
diff --git a/documents/markdown/hugo-docs/en_functions_collections_Uniq.md b/documents/markdown/hugo-docs/en_functions_collections_Uniq.md
new file mode 100644
index 0000000..664c851
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_Uniq.md
@@ -0,0 +1,16 @@
+---
+title: collections.Uniq
+description: Returns a slice by removing duplicate elements from the given slice.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [uniq]
+ returnType: '[]any'
+ signatures: [collections.Uniq SLICE]
+aliases: [/functions/uniq]
+---
+
+```go-html-template
+{{ slice 1 3 2 1 | uniq }} → [1 3 2]
+```
diff --git a/documents/markdown/hugo-docs/en_functions_collections_Where.md b/documents/markdown/hugo-docs/en_functions_collections_Where.md
new file mode 100644
index 0000000..40dd78f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections_Where.md
@@ -0,0 +1,419 @@
+---
+title: collections.Where
+description: Returns a slice by filtering the given slice based on a key, operator, and value.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [where]
+ returnType: '[]any'
+ signatures: ['collections.Where SLICE KEY [OPERATOR] VALUE']
+aliases: [/functions/where]
+---
+
+The `where` function returns the given slice, removing elements that do not satisfy the comparison condition. The comparison condition is composed of the `KEY`, `OPERATOR`, and `VALUE` arguments:
+
+```text
+collections.Where SLICE KEY [OPERATOR] VALUE
+ --------------------
+ comparison condition
+```
+
+Hugo will test for equality if you do not provide an `OPERATOR` argument. For example:
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Section" "books" }}
+{{ $books := where hugo.Data.books "genres" "suspense" }}
+```
+
+## Arguments
+
+The where function takes three or four arguments. The `OPERATOR` argument is optional.
+
+SLICE
+: (`[]any`) A [page collection](g) or a [slice](g) of [maps](g).
+
+KEY
+: (`string`) The key of the page or map value to compare with `VALUE`. With page collections, commonly used comparison keys are `Section`, `Type`, and `Params`. To compare with a member of the page `Params` map, [chain](g) the subkey as shown below:
+
+ ```go-html-template
+ {{ $result := where .Site.RegularPages "Params.foo" "bar" }}
+ ```
+
+OPERATOR
+: (`string`) The logical comparison [operator](#operators).
+
+VALUE
+: (`any`) The value with which to compare. The values to compare must have comparable data types. For example:
+
+Comparison|Result
+:--|:--
+`"123" "eq" "123"`|`true`
+`"123" "eq" 123`|`false`
+`false "eq" "false"`|`false`
+`false "eq" false`|`true`
+
+When one or both of the values to compare is a slice, use the `in`, `not in`, or `intersect` operators as described below.
+
+## Operators
+
+Use any of the following logical operators:
+
+`=`, `==`, `eq`
+: (`bool`) Reports whether the given field value is equal to `VALUE`.
+
+`!=`, `<>`, `ne`
+: (`bool`) Reports whether the given field value is not equal to `VALUE`.
+
+`>=`, `ge`
+: (`bool`) Reports whether the given field value is greater than or equal to `VALUE`.
+
+`>`, `gt`
+: `true` Reports whether the given field value is greater than `VALUE`.
+
+`<=`, `le`
+: (`bool`) Reports whether the given field value is less than or equal to `VALUE`.
+
+`<`, `lt`
+: (`bool`) Reports whether the given field value is less than `VALUE`.
+
+`in`
+: (`bool`) Reports whether the given field value is a member of `VALUE`. Compare string to slice, or string to string. See [details](/functions/collections/in).
+
+`not in`
+: (`bool`) Reports whether the given field value is not a member of `VALUE`. Compare string to slice, or string to string. See [details](/functions/collections/in).
+
+`intersect`
+: (`bool`) Reports whether the given field value (a slice) contains one or more elements in common with `VALUE`. See [details](/functions/collections/intersect).
+
+`like`
+: (`bool`) Reports whether the given field value matches the [regular expression](g) specified in `VALUE`. Use the `like` operator to compare `string` values. The `like` operator returns `false` when comparing other data types to the regular expression.
+
+> [!note]
+> The examples below perform comparisons within a page collection, but the same comparisons are applicable to a slice of maps.
+
+## String comparison
+
+Compare the value of the given field to a [`string`](g):
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Section" "eq" "books" }}
+{{ $pages := where .Site.RegularPages "Section" "ne" "books" }}
+```
+
+## Numeric comparison
+
+Compare the value of the given field to an [`int`](g) or [`float`](g):
+
+```go-html-template
+{{ $books := where site.RegularPages "Section" "eq" "books" }}
+
+{{ $pages := where $books "Params.price" "eq" 42 }}
+{{ $pages := where $books "Params.price" "ne" 42.67 }}
+{{ $pages := where $books "Params.price" "ge" 42 }}
+{{ $pages := where $books "Params.price" "gt" 42.67 }}
+{{ $pages := where $books "Params.price" "le" 42 }}
+{{ $pages := where $books "Params.price" "lt" 42.67 }}
+```
+
+## Boolean comparison
+
+Compare the value of the given field to a [`bool`](g):
+
+```go-html-template
+{{ $books := where site.RegularPages "Section" "eq" "books" }}
+
+{{ $pages := where $books "Params.fiction" "eq" true }}
+{{ $pages := where $books "Params.fiction" "eq" false }}
+{{ $pages := where $books "Params.fiction" "ne" true }}
+{{ $pages := where $books "Params.fiction" "ne" false }}
+```
+
+## Member comparison
+
+Compare a [`scalar`](g) to a [`slice`](g).
+
+For example, to return a slice of pages where the `color` page parameter is either "red" or "yellow":
+
+```go-html-template
+{{ $fruit := where site.RegularPages "Section" "eq" "fruit" }}
+
+{{ $colors := slice "red" "yellow" }}
+{{ $pages := where $fruit "Params.color" "in" $colors }}
+```
+
+To return a slice of pages where the "color" page parameter is neither "red" nor "yellow":
+
+```go-html-template
+{{ $fruit := where site.RegularPages "Section" "eq" "fruit" }}
+
+{{ $colors := slice "red" "yellow" }}
+{{ $pages := where $fruit "Params.color" "not in" $colors }}
+```
+
+## Intersection comparison
+
+Compare a `slice` to a `slice`, returning elements with common values. This is frequently used when comparing taxonomy terms.
+
+For example, to return a slice of pages where any of the terms in the "genres" taxonomy are "suspense" or "romance":
+
+```go-html-template
+{{ $books := where site.RegularPages "Section" "eq" "books" }}
+
+{{ $genres := slice "suspense" "romance" }}
+{{ $pages := where $books "Params.genres" "intersect" $genres }}
+```
+
+## Regular expression comparison
+
+To return a slice of pages where the "author" page parameter begins with either "victor" or "Victor":
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Params.author" "like" `(?i)^victor` }}
+```
+
+{{% include "/_common/functions/regular-expressions.md" %}}
+
+> [!note]
+> Use the `like` operator to compare string values. Comparing other data types will result in an empty slice.
+
+## Date comparison
+
+### Predefined dates
+
+There are four predefined front matter dates: [`date`], [`publishDate`], [`lastmod`], and [`expiryDate`]. Regardless of the front matter data format (TOML, YAML, or JSON) these are [`time.Time`] values, allowing precise comparisons.
+
+For example, to return a slice of pages that were created before the current year:
+
+```go-html-template
+{{ $startOfYear := time.AsTime (printf "%d-01-01" now.Year) }}
+{{ $pages := where .Site.RegularPages "Date" "lt" $startOfYear }}
+```
+
+### Custom dates
+
+With custom front matter dates, the comparison depends on the front matter data format (TOML, YAML, or JSON).
+
+> [!note]
+> Using TOML for pages with custom front matter dates enables precise date comparisons.
+
+With TOML, date values are first-class citizens. TOML has a date data type while JSON and YAML do not. If you quote a TOML date, it is a string. If you do not quote a TOML date value, it is [`time.Time`] value, enabling precise comparisons.
+
+In the TOML example below, note that the event date is not quoted.
+
+```text {file="content/events/2024-user-conference.md"}
++++
+title = '2024 User Conference"
+eventDate = 2024-04-01
++++
+```
+
+To return a slice of future events:
+
+```go-html-template
+{{ $events := where .Site.RegularPages "Type" "events" }}
+{{ $futureEvents := where $events "Params.eventDate" "gt" now }}
+```
+
+When working with YAML or JSON, or quoted TOML values, custom dates are strings; you cannot compare them with `time.Time` values. String comparisons may be possible if the custom date layout is consistent from one page to the next. To be safe, filter the pages by ranging over the slice:
+
+```go-html-template
+{{ $events := where .Site.RegularPages "Type" "events" }}
+{{ $futureEvents := slice }}
+{{ range $events }}
+ {{ if gt (time.AsTime .Params.eventDate) now }}
+ {{ $futureEvents = $futureEvents | append . }}
+ {{ end }}
+{{ end }}
+```
+
+## Nil comparison
+
+To return a slice of pages where the "color" parameter is present in front matter, compare to `nil`:
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Params.color" "ne" nil }}
+```
+
+To return a slice of pages where the "color" parameter is not present in front matter, compare to `nil`:
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Params.color" "eq" nil }}
+```
+
+In both examples above, note that `nil` is not quoted.
+
+## Nested comparison
+
+These are equivalent:
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Type" "tutorials" }}
+{{ $pages = where $pages "Params.level" "eq" "beginner" }}
+```
+
+```go-html-template
+{{ $pages := where (where .Site.RegularPages "Type" "tutorials") "Params.level" "eq" "beginner" }}
+```
+
+## Portable section comparison
+
+Useful for theme authors, avoid hardcoding section names by using the `where` function with the [`MainSections`] method on a `Site` object.
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Section" "in" .Site.MainSections }}
+```
+
+With this construct, a theme author can instruct users to specify their main sections in their project configuration:
+
+{{< code-toggle file=hugo >}}
+mainSections = ['blog','galleries']
+{{< /code-toggle >}}
+
+If `mainSections` is not defined in your project configuration, the `MainSections` method returns a slice with one element---the top-level section with the most pages.
+
+## Boolean/undefined comparison
+
+Consider this project structure:
+
+```text
+content/
+├── posts/
+│ ├── _index.md
+│ ├── post-1.md <-- front matter: exclude = false
+│ ├── post-2.md <-- front matter: exclude = true
+│ └── post-3.md <-- front matter: exclude not defined
+└── _index.md
+```
+
+The first two pages have an "exclude" field in front matter, but the last page does not. When testing for _equality_, the third page is _excluded_ from the result. When testing for _inequality_, the third page is _included_ in the result.
+
+### Equality test
+
+This template:
+
+```go-html-template
+<ul>
+ {{ range where .Site.RegularPages "Params.exclude" "eq" false }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li><a href="/posts/post-1/">Post 1</a></li>
+</ul>
+```
+
+This template:
+
+```go-html-template
+<ul>
+ {{ range where .Site.RegularPages "Params.exclude" "eq" true }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li><a href="/posts/post-2/">Post 2</a></li>
+</ul>
+```
+
+### Inequality test
+
+This template:
+
+```go-html-template
+<ul>
+ {{ range where .Site.RegularPages "Params.exclude" "ne" false }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li><a href="/posts/post-2/">Post 2</a></li>
+ <li><a href="/posts/post-3/">Post 3</a></li>
+</ul>
+```
+
+This template:
+
+```go-html-template
+<ul>
+ {{ range where .Site.RegularPages "Params.exclude" "ne" true }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li><a href="/posts/post-1/">Post 1</a></li>
+ <li><a href="/posts/post-3/">Post 3</a></li>
+</ul>
+```
+
+To exclude a page with an undefined field from a boolean _inequality_ test:
+
+1. Create a slice using a boolean comparison
+1. Create a slice using a nil comparison
+1. Subtract the second slice from the first slice using the [`collections.Complement`] function.
+
+This template:
+
+```go-html-template
+{{ $p1 := where .Site.RegularPages "Params.exclude" "ne" true }}
+{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }}
+<ul>
+ {{ range $p1 | complement $p2 }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li><a href="/posts/post-1/">Post 1</a></li>
+</ul>
+```
+
+This template:
+
+```go-html-template
+{{ $p1 := where .Site.RegularPages "Params.exclude" "ne" false }}
+{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }}
+<ul>
+ {{ range $p1 | complement $p2 }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li><a href="/posts/post-1/">Post 2</a></li>
+</ul>
+```
+
+[`collections.Complement`]: /functions/collections/complement/
+[`date`]: /methods/page/date/
+[`lastmod`]: /methods/page/lastmod/
+[`MainSections`]: /methods/site/mainsections/
+[`time.Time`]: https://pkg.go.dev/time#Time
diff --git a/documents/markdown/hugo-docs/en_functions_collections__index.md b/documents/markdown/hugo-docs/en_functions_collections__index.md
new file mode 100644
index 0000000..0f07db5
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_collections__index.md
@@ -0,0 +1,7 @@
+---
+title: Collections functions
+linkTitle: collections
+description: Use these functions to manipulate and query maps, slices, and strings.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_compare_Conditional.md b/documents/markdown/hugo-docs/en_functions_compare_Conditional.md
new file mode 100644
index 0000000..c004bf4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_compare_Conditional.md
@@ -0,0 +1,31 @@
+---
+title: compare.Conditional
+description: Returns one of two arguments depending on the value of the control argument.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [cond]
+ returnType: any
+ signatures: [compare.Conditional CONTROL ARG1 ARG2]
+aliases: [/functions/cond]
+---
+
+If CONTROL is truthy the function returns ARG1, otherwise it returns ARG2.
+
+```go-html-template
+{{ $qty := 42 }}
+{{ cond (le $qty 3) "few" "many" }} → many
+```
+
+Unlike [ternary operators] in other languages, the `compare.Conditional` function does not perform [short-circuit evaluation]. It evaluates both ARG1 and ARG2 regardless of the CONTROL value.
+
+[short-circuit evaluation]: https://en.wikipedia.org/wiki/Short-circuit_evaluation
+[ternary operators]: https://en.wikipedia.org/wiki/Ternary_conditional_operator
+
+Due to the absence of short-circuit evaluation, these examples throw an error:
+
+```go-html-template
+{{ cond true "true" (div 1 0) }}
+{{ cond false (div 1 0) "false" }}
+```
diff --git a/documents/markdown/hugo-docs/en_functions_compare_Default.md b/documents/markdown/hugo-docs/en_functions_compare_Default.md
new file mode 100644
index 0000000..5925f77
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_compare_Default.md
@@ -0,0 +1,47 @@
+---
+title: compare.Default
+description: Returns the second argument if set, else the first argument.
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [default]
+ returnType: any
+ signatures: [compare.Default DEFAULT INPUT]
+aliases: [/functions/default]
+---
+
+The `default` function returns the second argument if set, else the first argument.
+
+> [!note]
+> When the second argument is the boolean `false` value, the `default` function returns `false`. All _other_ falsy values are considered unset.
+>
+> The falsy values are `false`, `0`, any `nil` pointer or interface value, any array, slice, map, or string of length zero, and zero `time.Time` values.
+>
+> Everything else is truthy.
+>
+> To set a default value based on truthiness, use the [`or`] operator instead.
+
+The `default` function returns the second argument if set:
+
+```go-html-template
+{{ default 42 1 }} → 1
+{{ default 42 "foo" }} → foo
+{{ default 42 (dict "k" "v") }} → map[k:v]
+{{ default 42 (slice "a" "b") }} → [a b]
+{{ default 42 true }} → true
+
+<!-- As noted above, the boolean "false" is considered set -->
+{{ default 42 false }} → false
+```
+
+The `default` function returns the first argument if the second argument is not set:
+
+```go-html-template
+{{ default 42 0 }} → 42
+{{ default 42 "" }} → 42
+{{ default 42 dict }} → 42
+{{ default 42 slice }} → 42
+{{ default 42 nil }} → 42
+```
+
+[`or`]: /functions/go-template/or/
diff --git a/documents/markdown/hugo-docs/en_functions_compare_Eq.md b/documents/markdown/hugo-docs/en_functions_compare_Eq.md
new file mode 100644
index 0000000..583e2e4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_compare_Eq.md
@@ -0,0 +1,24 @@
+---
+title: compare.Eq
+description: Returns the boolean truth of arg1 == arg2 || arg1 == arg3.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [eq]
+ returnType: bool
+ signatures: ['compare.Eq ARG1 ARG2 [ARG...]']
+aliases: [/functions/eq]
+---
+
+```go-html-template
+{{ eq 1 1 }} → true
+{{ eq 1 2 }} → false
+
+{{ eq 1 1 1 }} → true
+{{ eq 1 1 2 }} → true
+{{ eq 1 2 1 }} → true
+{{ eq 1 2 2 }} → false
+```
+
+You can also use the `compare.Eq` function to compare strings, boolean values, dates, slices, maps, and pages.
diff --git a/documents/markdown/hugo-docs/en_functions_compare_Ge.md b/documents/markdown/hugo-docs/en_functions_compare_Ge.md
new file mode 100644
index 0000000..fd793f0
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_compare_Ge.md
@@ -0,0 +1,35 @@
+---
+title: compare.Ge
+description: Returns the boolean truth of arg1 >= arg2 && arg1 >= arg3.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [ge]
+ returnType: bool
+ signatures: ['compare.Ge ARG1 ARG2 [ARG...]']
+aliases: [/functions/ge]
+---
+
+```go-html-template
+{{ ge 1 1 }} → true
+{{ ge 1 2 }} → false
+{{ ge 2 1 }} → true
+
+{{ ge 1 1 1 }} → true
+{{ ge 1 1 2 }} → false
+{{ ge 1 2 1 }} → false
+{{ ge 1 2 2 }} → false
+
+{{ ge 2 1 1 }} → true
+{{ ge 2 1 2 }} → true
+{{ ge 2 2 1 }} → true
+```
+
+Use the `compare.Ge` function to compare other data types as well:
+
+```go-html-template
+{{ ge "ab" "a" }} → true
+{{ ge time.Now (time.AsTime "1964-12-30") }} → true
+{{ ge true false }} → true
+```
diff --git a/documents/markdown/hugo-docs/en_functions_compare_Gt.md b/documents/markdown/hugo-docs/en_functions_compare_Gt.md
new file mode 100644
index 0000000..f48312c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_compare_Gt.md
@@ -0,0 +1,35 @@
+---
+title: compare.Gt
+description: Returns the boolean truth of arg1 > arg2 && arg1 > arg3.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [gt]
+ returnType: bool
+ signatures: ['compare.Gt ARG1 ARG2 [ARG...]']
+aliases: [/functions/gt]
+---
+
+```go-html-template
+{{ gt 1 1 }} → false
+{{ gt 1 2 }} → false
+{{ gt 2 1 }} → true
+
+{{ gt 1 1 1 }} → false
+{{ gt 1 1 2 }} → false
+{{ gt 1 2 1 }} → false
+{{ gt 1 2 2 }} → false
+
+{{ gt 2 1 1 }} → true
+{{ gt 2 1 2 }} → false
+{{ gt 2 2 1 }} → false
+```
+
+Use the `compare.Gt` function to compare other data types as well:
+
+```go-html-template
+{{ gt "ab" "a" }} → true
+{{ gt time.Now (time.AsTime "1964-12-30") }} → true
+{{ gt true false }} → true
+```
diff --git a/documents/markdown/hugo-docs/en_functions_compare_Le.md b/documents/markdown/hugo-docs/en_functions_compare_Le.md
new file mode 100644
index 0000000..b490d68
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_compare_Le.md
@@ -0,0 +1,35 @@
+---
+title: compare.Le
+description: Returns the boolean truth of arg1 <= arg2 && arg1 <= arg3.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [le]
+ returnType: bool
+ signatures: ['compare.Le ARG1 ARG2 [ARG...]']
+aliases: [/functions/le]
+---
+
+```go-html-template
+{{ le 1 1 }} → true
+{{ le 1 2 }} → true
+{{ le 2 1 }} → false
+
+{{ le 1 1 1 }} → true
+{{ le 1 1 2 }} → true
+{{ le 1 2 1 }} → true
+{{ le 1 2 2 }} → true
+
+{{ le 2 1 1 }} → false
+{{ le 2 1 2 }} → false
+{{ le 2 2 1 }} → false
+```
+
+Use the `compare.Le` function to compare other data types as well:
+
+```go-html-template
+{{ le "ab" "a" }} → false
+{{ le time.Now (time.AsTime "1964-12-30") }} → false
+{{ le true false }} → false
+```
diff --git a/documents/markdown/hugo-docs/en_functions_compare_Lt.md b/documents/markdown/hugo-docs/en_functions_compare_Lt.md
new file mode 100644
index 0000000..a5578cc
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_compare_Lt.md
@@ -0,0 +1,35 @@
+---
+title: compare.Lt
+description: Returns the boolean truth of arg1 < arg2 && arg1 < arg3.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [lt]
+ returnType: bool
+ signatures: ['compare.Lt ARG1 ARG2 [ARG...]']
+aliases: [/functions/lt]
+---
+
+```go-html-template
+{{ lt 1 1 }} → false
+{{ lt 1 2 }} → true
+{{ lt 2 1 }} → false
+
+{{ lt 1 1 1 }} → false
+{{ lt 1 1 2 }} → false
+{{ lt 1 2 1 }} → false
+{{ lt 1 2 2 }} → true
+
+{{ lt 2 1 1 }} → false
+{{ lt 2 1 2 }} → false
+{{ lt 2 2 1 }} → false
+```
+
+Use the `compare.Lt` function to compare other data types as well:
+
+```go-html-template
+{{ lt "ab" "a" }} → false
+{{ lt time.Now (time.AsTime "1964-12-30") }} → false
+{{ lt true false }} → false
+```
diff --git a/documents/markdown/hugo-docs/en_functions_compare_Ne.md b/documents/markdown/hugo-docs/en_functions_compare_Ne.md
new file mode 100644
index 0000000..8839983
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_compare_Ne.md
@@ -0,0 +1,24 @@
+---
+title: compare.Ne
+description: Returns the boolean truth of arg1 != arg2 && arg1 != arg3.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [ne]
+ returnType: bool
+ signatures: ['compare.Ne ARG1 ARG2 [ARG...]']
+aliases: [/functions/ne]
+---
+
+```go-html-template
+{{ ne 1 1 }} → false
+{{ ne 1 2 }} → true
+
+{{ ne 1 1 1 }} → false
+{{ ne 1 1 2 }} → false
+{{ ne 1 2 1 }} → false
+{{ ne 1 2 2 }} → true
+```
+
+You can also use the `compare.Ne` function to compare strings, boolean values, dates, slices, maps, and pages.
diff --git a/documents/markdown/hugo-docs/en_functions_compare__index.md b/documents/markdown/hugo-docs/en_functions_compare__index.md
new file mode 100644
index 0000000..59673a2
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_compare__index.md
@@ -0,0 +1,7 @@
+---
+title: Compare functions
+linkTitle: compare
+description: Use these functions to compare two or more values.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_crypto_HMAC.md b/documents/markdown/hugo-docs/en_functions_crypto_HMAC.md
new file mode 100644
index 0000000..5929826
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_crypto_HMAC.md
@@ -0,0 +1,27 @@
+---
+title: crypto.HMAC
+description: Returns a cryptographic hash that uses a key to sign a message.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [hmac]
+ returnType: string
+ signatures: ['crypto.HMAC HASH_TYPE KEY MESSAGE [ENCODING]']
+aliases: [/functions/hmac]
+---
+
+Set the `HASH_TYPE` argument to `md5`, `sha1`, `sha256`, or `sha512`.
+
+Set the optional `ENCODING` argument to either `hex` (default) or `binary`.
+
+```go-html-template
+{{ hmac "sha256" "Secret key" "Secret message" }}
+5cceb491f45f8b154e20f3b0a30ed3a6ff3027d373f85c78ffe8983180b03c84
+
+{{ hmac "sha256" "Secret key" "Secret message" "hex" }}
+5cceb491f45f8b154e20f3b0a30ed3a6ff3027d373f85c78ffe8983180b03c84
+
+{{ hmac "sha256" "Secret key" "Secret message" "binary" | base64Encode }}
+XM60kfRfixVOIPOwow7Tpv8wJ9Nz+Fx4/+iYMYCwPIQ=
+```
diff --git a/documents/markdown/hugo-docs/en_functions_crypto_MD5.md b/documents/markdown/hugo-docs/en_functions_crypto_MD5.md
new file mode 100644
index 0000000..89bb8cc
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_crypto_MD5.md
@@ -0,0 +1,22 @@
+---
+title: crypto.MD5
+description: Hashes the given input and returns its MD5 checksum encoded to a hexadecimal string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [md5]
+ returnType: string
+ signatures: [crypto.MD5 INPUT]
+aliases: [/functions/md5]
+---
+
+```go-html-template
+{{ md5 "Hello world" }} → 3e25960a79dbc69b674cd4ec67a72c62
+```
+
+This can be useful if you want to use [Gravatar](https://en.gravatar.com/) for generating a unique avatar:
+
+```html
+<img src="https://www.gravatar.com/avatar/{{ md5 "your@email.com" }}?s=100&d=identicon">
+```
diff --git a/documents/markdown/hugo-docs/en_functions_crypto_SHA1.md b/documents/markdown/hugo-docs/en_functions_crypto_SHA1.md
new file mode 100644
index 0000000..c80dac0
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_crypto_SHA1.md
@@ -0,0 +1,16 @@
+---
+title: crypto.SHA1
+description: Hashes the given input and returns its SHA1 checksum encoded to a hexadecimal string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [sha1]
+ returnType: string
+ signatures: [crypto.SHA1 INPUT]
+aliases: [/functions/sha,/functions/sha1]
+---
+
+```go-html-template
+{{ sha1 "Hello world" }} → 7b502c3a1f48c8609ae212cdfb639dee39673f5e
+```
diff --git a/documents/markdown/hugo-docs/en_functions_crypto_SHA256.md b/documents/markdown/hugo-docs/en_functions_crypto_SHA256.md
new file mode 100644
index 0000000..d0a66c0
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_crypto_SHA256.md
@@ -0,0 +1,16 @@
+---
+title: crypto.SHA256
+description: Hashes the given input and returns its SHA256 checksum encoded to a hexadecimal string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [sha256]
+ returnType: string
+ signatures: [crypto.SHA256 INPUT]
+aliases: [/functions/sha256]
+---
+
+```go-html-template
+{{ sha256 "Hello world" }} → 64ec88ca00b268e5ba1a35678a1b5316d212f4f366b2477232534a8aeca37f3c
+```
diff --git a/documents/markdown/hugo-docs/en_functions_crypto__index.md b/documents/markdown/hugo-docs/en_functions_crypto__index.md
new file mode 100644
index 0000000..5771630
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_crypto__index.md
@@ -0,0 +1,7 @@
+---
+title: Crypto functions
+linkTitle: crypto
+description: Use these functions to create cryptographic hashes.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_css_Build.md b/documents/markdown/hugo-docs/en_functions_css_Build.md
new file mode 100644
index 0000000..5224a4e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_css_Build.md
@@ -0,0 +1,259 @@
+---
+title: css.Build
+description: Bundle, transform, and minify CSS resources.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: resource.Resource
+ signatures: ['css.Build [OPTIONS] RESOURCE']
+---
+
+{{< new-in 0.158.0 />}}
+
+> [!note]
+> The `css.Build` function is backed by the [`evanw/esbuild`][] package, providing a mature, high-performance foundation for bundling, transformation, and minification.
+
+Use the `css.Build` function to:
+
+- Recursively replace `@import` statements in CSS files with the content of the imported files
+- Transform syntax for browser compatibility
+- Apply vendor prefixes for browser compatibility
+- Minify the bundled CSS code
+- Create a source map
+
+If an `@import` statement includes a media query, a feature query, or a cascade layer assignment, the function wraps the imported content in the corresponding `@media`, `@supports`, or `@layer` rule.
+
+## Usage
+
+In this example, Hugo bundles the local files referenced by `@import` statements to create and publish a single resource with inline content.
+
+```text
+assets/
+└── css/
+ ├── components/
+ │ ├── a.css
+ │ └── b.css
+ └── main.css
+```
+
+```css {file="assets/css/main.css" copy=true}
+@import url('https://cdn.jsdelivr.net/npm/the-new-css-reset/css/reset.min.css');
+
+@import './components/a.css';
+@import './components/b.css';
+
+.c {color: blue; }
+```
+
+```css {file="assets/css/components/a.css" copy=true}
+.a { color: red; }
+```
+
+```css {file="assets/css/components/b.css" copy=true}
+.b { color: green; }
+```
+
+```go-html-template {file="layouts/_partials/css.html" copy=true}
+{{ with resources.Get "css/main.css" | css.Build }}
+ {{ if hugo.IsDevelopment }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ else }}
+ {{ with . | fingerprint }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+```go-html-template {file="layouts/baseof.html" copy=true}
+{{ partialCached "css.html" . }}
+```
+
+The generated CSS code:
+
+```css {file="public/css/main.css"}
+@import "https://cdn.jsdelivr.net/npm/the-new-css-reset/css/reset.min.css";
+
+.a {
+ color: red;
+}
+
+.b {
+ color: green;
+}
+
+.c {
+ color: blue;
+}
+```
+
+To minify the generated CSS code, use the [`minify`](#minify) option as described below.
+
+## Options
+
+The `css.Build` function takes an optional map of options to fine-tune bundling, minification, and browser compatibility.
+
+externals
+: (`[]string`) A slice of path patterns to exclude from bundling. The `@import` statements for these patterns remain as-is in the generated CSS code. See [details][esb_external].
+
+ ```go-html-template
+ {{ $opts := dict "externals" (slice "./exclude-these/*" "./exclude-these-too/*") }}
+ {{ $r := resources.Get "css/main.css" | css.Build $opts }}
+ ```
+
+loaders
+: (`map`) A map of file extensions to loader types. This determines how files with a given extension are processed during bundling. By default, Hugo uses the `css` loader for `.css` files and the `file` loader for all others. Common loaders include:
+
+ - `css`: Processes the file as a CSS file
+ - `dataurl`: Embeds the file as a base64-encoded data URL
+ - `empty`: Excludes the file from the bundle
+ - `file`: Copies the file to the output directory and rewrites the URL
+ - `text`: Loads the file content as a string
+
+ See [details][esb_loader].
+
+ ```go-html-template
+ {{ $opts := dict "loaders" (dict ".png" "dataurl" ".svg" "dataurl") }}
+ {{ $r := resources.Get "css/main.css" | css.Build $opts }}
+ ```
+
+mainFields
+: (`[]string`) A prioritized slice of field names in a `package.json` file that determine the CSS entry point of a Node package. The default is `["style", "main"]`. See [details][esb_mainfields].
+
+ When an `@import` statement references a Node package, Hugo consults the metadata in the `package.json` file to find the stylesheet. Use this option to support packages that define a CSS entry point using non-standard fields.
+
+ ```go-html-template
+ {{ $opts := dict "mainFields" (slice "css" "style" "main") }}
+ {{ $r := resources.Get "css/main.css" | css.Build $opts }}
+ ```
+
+minify
+: (`bool`) Whether to minify the generated CSS code. Default is `false`. See [details][esb_minify].
+
+ ```go-html-template
+ {{ $opts := dict "minify" true }}
+ {{ $r := resources.Get "css/main.css" | css.Build $opts }}
+ ```
+
+sourceMap
+: (`string`) The type of source map to generate. One of `external`, `inline`, `linked`, or `none`. Default is `none`. See [details][esb_sourcemap].
+
+ ```go-html-template
+ {{ $opts := dict "sourceMap" "linked" }}
+ {{ $r := resources.Get "css/main.css" | css.Build $opts }}
+ ```
+
+sourcesContent
+: (`bool`) Whether to include the content of the source files in the source map. Default is `true`. See [details][esb_sourcesContent].
+
+ ```go-html-template
+ {{ $opts := dict "sourceMap" "linked" "sourcesContent" false }}
+ {{ $r := resources.Get "css/main.css" | css.Build $opts }}
+ ```
+
+target
+: (`[]string`) The target environment for the generated CSS code. This determines which syntax transformations to perform and which vendor prefixes to apply. If unset, no transformations or prefixing are performed. Each element consists of a target name and a version number. Supported targets include `chrome`, `edge`, `firefox`, `ie`, `ios`, `opera`, and `safari`. See [details][esb_target].
+
+ ```go-html-template
+ {{ $target := slice "chrome115" "edge115" "firefox116" "ios16.4" "opera101" "safari16.4" }}
+ {{ $opts := dict "target" $target }}
+ {{ $r := resources.Get "css/main.css" | css.Build $opts }}
+ ```
+
+ In the example above, the target environment is roughly equivalent to the [browserlist][] "baseline widely available" profile as of March 2026.
+
+targetPath
+: (`string`) The path to the generated CSS file, relative to the project's [`publishDir`][]. If unset, this defaults to the asset's original path with a `.css` extension.
+
+ ```go-html-template
+ {{ $opts := dict "targetPath" "css/styles.css" }}
+ {{ $r := resources.Get "css/main.css" | css.Build $opts }}
+ ```
+
+## Example
+
+The example below uses several of the [options](#options) described above to bundle, transform, and minify CSS code.
+
+```go-html-template {file="layouts/_partials/css.html" copy=true}
+{{ with resources.Get "css/main.css" }}
+ {{ $opts := dict
+ "loaders" (dict ".png" "dataurl" ".svg" "dataurl")
+ "minify" (cond hugo.IsDevelopment false true)
+ "sourceMap" (cond hugo.IsDevelopment "linked" "none")
+ "target" (slice "chrome115" "edge115" "firefox116" "ios16.4" "opera101" "safari16.4")
+ }}
+ {{ with . | css.Build $opts }}
+ {{ if hugo.IsDevelopment }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ else }}
+ {{ with . | fingerprint }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+Using the options above, Hugo does the following:
+
+- Embeds PNG and SVG images as data URLs in the generated CSS code
+- Minifies the output in production but not in development
+- Generates an external source map in development but not in production
+- Transforms syntax for compatibility with the targeted browser versions
+- Adds vendor prefixes for compatibility with the targeted browser versions
+- Publishes the generated CSS code to `css/styles.css`
+- In production, adds an SRI hash and inserts a file hash into the filename
+
+## Common patterns
+
+The examples below cover the most frequent use cases for referencing resources within your project or within Node packages. These patterns apply to both `@import` statements and the `url()` functional notation used for images and fonts.
+
+All resources referenced by a path, including images, fonts, and stylesheets, must reside in the `assets` directory of the [unified file system](g), or within a Node package.
+
+### Files in the assets directory
+
+To include a stylesheet from the `assets` directory, you can use a bare path, a relative path, or a root-relative path. When you use a bare path, Hugo searches relative to the current stylesheet, then relative to the `assets` directory.
+
+```css {file="/assets/css/main.css"}
+/* A bare path */
+@import "variables.css";
+
+/* A relative path */
+@import "./theme.css";
+@import "../layout.css";
+
+/* A root-relative path */
+@import "/css/grid.css";
+
+/* A url() reference using the same resolution logic */
+.logo { background: url("/images/logo.svg"); }
+```
+
+### Node packages
+
+When referencing a Node package by name, Hugo consults the `package.json` file within that package to find the entry point.
+
+```css {file="/assets/css/main.css"}
+@import "bootstrap";
+```
+
+### Files within a package
+
+To reference a specific file within a Node package, provide the path starting with the package name.
+
+```css {file="/assets/css/main.css"}
+@import "bootstrap/dist/css/bootstrap-grid.css";
+```
+
+[`evanw/esbuild`]: https://github.com/evanw/esbuild
+[`publishDir`]: /configuration/all/#publishdir
+[browserlist]: https://browsersl.ist
+[esb_external]: https://esbuild.github.io/api/#external
+[esb_loader]: https://esbuild.github.io/api/#loader
+[esb_mainfields]: https://esbuild.github.io/api/#main-fields
+[esb_minify]: https://esbuild.github.io/api/#minify
+[esb_sourcemap]: https://esbuild.github.io/api/#sourcemap
+[esb_sourcesContent]: https://esbuild.github.io/api/#sources-content
+[esb_target]: https://esbuild.github.io/api/#target
diff --git a/documents/markdown/hugo-docs/en_functions_css_PostCSS.md b/documents/markdown/hugo-docs/en_functions_css_PostCSS.md
new file mode 100644
index 0000000..3e4e7ad
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_css_PostCSS.md
@@ -0,0 +1,122 @@
+---
+title: css.PostCSS
+description: Processes the given resource with PostCSS using any PostCSS plugin.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [postCSS]
+ returnType: resource.Resource
+ signatures: ['css.PostCSS [OPTIONS] RESOURCE']
+aliases: [/functions/resources/postcss/]
+---
+
+```go-html-template
+{{ with resources.Get "css/main.css" | postCSS }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+{{ end }}
+```
+
+## Setup
+
+Follow the steps below to transform CSS using any of the available [PostCSS plugins].
+
+Step 1
+: Install [Node.js].
+
+Step 2
+: Install the required Node packages in the root of your project. For example, to add vendor prefixes to your CSS rules:
+
+ ```sh
+ npm i -D postcss postcss-cli autoprefixer
+ ```
+
+Step 3
+: Create a PostCSS configuration file in the root of your project.
+
+ ```js {file="postcss.config.js"}
+ module.exports = {
+ plugins: [
+ require('autoprefixer')
+ ]
+ };
+ ```
+
+ > [!note]
+ > If you are a Windows user, and the path to your project contains a space, you must place the PostCSS configuration within the package.json file. See [this example] and issue [#7333].
+
+Step 4
+: Place your CSS file within the `assets/css` directory.
+
+Step 5
+: Process the resource with PostCSS:
+
+ ```go-html-template
+ {{ with resources.Get "css/main.css" | postCSS }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ end }}
+ ```
+
+## Options
+
+The `css.PostCSS` method takes an optional map of options.
+
+config
+: (`string`) The directory that contains the PostCSS configuration file. Default is the root of the project directory.
+
+noMap
+: (`bool`) Whether to disable inline source maps. Default is `false`.
+
+inlineImports
+: (`bool`) Whether to enable inlining of import statements. It does so recursively, but will only import a file once. URL imports (e.g. `@import url('https://fonts.googleapis.com/css?family=Open+Sans&display=swap');`) and imports with media queries will be ignored. Note that this import routine does not care about the CSS spec, so you can have @import anywhere in the file. Hugo will look for imports relative to the module mount and will respect theme overrides. Default is `false`.
+
+skipInlineImportsNotFound
+: (`bool`) Whether to allow the build process to continue despite unresolved import statements, preserving the original import declarations. If you have regular CSS imports in your CSS that you want to preserve, you can either use imports with URL or media queries (Hugo does not try to resolve those) or set this option to `true`. Default is `false`.
+
+```go-html-template
+{{ $opts := dict "config" "config-directory" "noMap" true }}
+{{ with resources.Get "css/main.css" | postCSS $opts }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+{{ end }}
+```
+
+## No configuration file
+
+To avoid using a PostCSS configuration file, you can specify a minimal configuration using the options map.
+
+use
+: (`string`) A space-delimited list of PostCSS plugins to use.
+
+parser
+: (`string`) A custom PostCSS parser.
+
+stringifier
+: (`string`) A custom PostCSS stringifier.
+
+syntax
+: (`string`) Custom postcss syntax.
+
+```go-html-template
+{{ $opts := dict "use" "autoprefixer postcss-color-alpha" }}
+{{ with resources.Get "css/main.css" | postCSS $opts }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+{{ end }}
+```
+
+## Check environment
+
+The current Hugo environment name (set by `--environment` or in configuration or OS environment) is available in the Node context, which allows constructs like this:
+
+```js
+const autoprefixer = require('autoprefixer');
+module.exports = {
+ plugins: [
+ process.env.HUGO_ENVIRONMENT !== 'development' ? autoprefixer : null
+ ]
+}
+```
+
+[#7333]: https://github.com/gohugoio/hugo/issues/7333
+[Node.js]: https://nodejs.org/en
+[PostCSS plugins]: https://postcss.org/docs/postcss-plugins
+[this example]: https://github.com/postcss/postcss-load-config#packagejson
diff --git a/documents/markdown/hugo-docs/en_functions_css_Quoted.md b/documents/markdown/hugo-docs/en_functions_css_Quoted.md
new file mode 100644
index 0000000..58784f3
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_css_Quoted.md
@@ -0,0 +1,73 @@
+---
+title: css.Quoted
+description: Returns the given string, setting its data type to indicate that it must be quoted when used in CSS.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: css.QuotedString
+ signatures: [css.Quoted STRING]
+---
+
+<!-- Added in v0.111.0 -->
+
+> [!note]
+> This function is only applicable to the [`vars`] option passed to the [`css.Sass`] function.
+
+When passing a `vars` map to the `css.Sass` function, Hugo detects common typed CSS values such as `24px` or `#FF0000` using regular expression matching. If necessary, you can bypass automatic type inference by using the `css.Quoted` function to explicitly indicate that the value must be treated as a quoted string.
+
+For example:
+
+```scss {file="assets/sass/main.scss"}
+@use "hugo:vars" as h;
+
+ol li::after {
+ content: h.$ol-li-after;
+}
+
+ul li::after {
+ content: h.$ul-li-after;
+}
+```
+
+```go-html-template {file="layouts/_partials/css.html"}
+{{ $vars := dict
+ "ol_li_after" ("6" | css.Quoted )
+ "ul_li_after" ("7" | css.Quoted )
+}}
+
+{{ with resources.Get "sass/main.scss" }}
+ {{ $opts := dict
+ "enableSourceMap" hugo.IsDevelopment
+ "outputStyle" (cond hugo.IsDevelopment "expanded" "compressed")
+ "targetPath" "css/main.css"
+ "transpiler" "dartsass"
+ "vars" $vars
+ }}
+ {{ with . | toCSS $opts }}
+ {{ if hugo.IsDevelopment }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ else }}
+ {{ with . | fingerprint }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+The Sass code is transpiled to:
+
+```css {file="public/css/main.css"}
+ol li::after {
+ content: "6";
+}
+
+ul li::after {
+ content: "7";
+}
+```
+
+[`css.Sass`]: /functions/css/sass/
+[`vars`]: /functions/css/sass/#vars
diff --git a/documents/markdown/hugo-docs/en_functions_css_Sass.md b/documents/markdown/hugo-docs/en_functions_css_Sass.md
new file mode 100644
index 0000000..c5e1077
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_css_Sass.md
@@ -0,0 +1,169 @@
+---
+title: css.Sass
+description: Transpiles Sass to CSS.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [toCSS]
+ returnType: resource.Resource
+ signatures: ['css.Sass [OPTIONS] RESOURCE']
+aliases: [/functions/resources/tocss/]
+---
+
+Transpile Sass to CSS using the LibSass transpiler included in Hugo's extended and extended/deploy editions, or [install Dart Sass](#dart-sass) to use the latest features of the Sass language.
+
+> [!warning]
+> The embedded LibSass transpiler was deprecated in [v0.153.0][] and will be removed in a future release. Use the Dart Sass transpiler instead.
+
+Sass has two forms of syntax: [SCSS][] and [indented][]. Hugo supports both.
+
+## Options
+
+enableSourceMap
+: (`bool`) Whether to generate a source map. Default is `false`.
+
+includePaths
+: (`slice`) A slice of paths, relative to the project root, that the transpiler will use when resolving `@use` and `@import` statements.
+
+outputStyle
+: (`string`) The output style of the resulting CSS. With LibSass, one of `nested` (default), `expanded`, `compact`, or `compressed`. With Dart Sass, either `expanded` (default) or `compressed`.
+
+precision
+: (`int`) The precision of floating point math. Applicable to LibSass. Default is `8`.
+
+silenceDeprecations
+: {{< new-in 0.139.0 />}}
+: (`slice`) A slice of deprecation IDs to silence. IDs are enclosed in brackets within Dart Sass warning messages (e.g., `import` in `WARN Dart Sass: DEPRECATED [import]`). Applicable to Dart Sass. Default is `false`.
+
+silenceDependencyDeprecations
+: {{< new-in 0.146.0 />}}
+: (`bool`) Whether to silence deprecation warnings from dependencies, where a dependency is considered any file transitively imported through a load path. This does not apply to `@warn` or `@debug` rules.Default is `false`.
+
+sourceMapIncludeSources
+: (`bool`) Whether to embed sources in the generated source map. Applicable to Dart Sass. Default is `false`.
+
+targetPath
+: (`string`) The publish path for the transformed resource, relative to the[`publishDir`][]. If unset, the target path defaults to the asset's original path with a `.css` extension.
+
+transpiler
+: (`string`) The transpiler to use, either `libsass` or `dartsass`. Hugo's extended and extended/deploy editions include the LibSass transpiler. To use the Dart Sass transpiler, see the [installation instructions](#dart-sass). Default is `libsass`.
+
+ > [!warning]
+ > The embedded LibSass transpiler was deprecated in [v0.153.0][] and will be removed in a future release. Use the Dart Sass transpiler instead.
+
+vars
+: (`map`) A map of key-value pairs that will be available in the `hugo:vars` namespace. Useful for [initializing Sass variables from Hugo templates](https://discourse.gohugo.io/t/42053/).
+
+ ```scss
+ // LibSass
+ @import "hugo:vars";
+
+ // Dart Sass
+ @use "hugo:vars" as v;
+ ```
+
+ When passing a `vars` map to the `css.Sass` function, Hugo detects common typed CSS values such as `24px` or `#FF0000` using regular expression matching. If necessary, you can bypass automatic type inference by using the [`css.Quoted`][] or [`css.Unquoted`][] function to explicitly indicate a value's type.
+
+## Example
+
+```go-html-template {copy=true}
+{{ with resources.Get "sass/main.scss" }}
+ {{ $opts := dict
+ "enableSourceMap" hugo.IsDevelopment
+ "outputStyle" (cond hugo.IsDevelopment "expanded" "compressed")
+ "targetPath" "css/main.css"
+ "transpiler" "dartsass"
+ "vars" site.Params.styles
+ "includePaths" (slice "node_modules/bootstrap/scss")
+ }}
+ {{ with . | toCSS $opts }}
+ {{ if hugo.IsDevelopment }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ else }}
+ {{ with . | fingerprint }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+## Dart Sass
+
+Hugo's extended and extended/deploy editions include [LibSass][] to transpile Sass to CSS. In 2020, the Sass team deprecated LibSass in favor of [Dart Sass][].
+
+Use the latest features of the Sass language by installing Dart Sass in your development and production environments.
+
+### Installation overview
+
+Dart Sass is compatible with Hugo v0.114.0 and later.
+
+If you have been using Embedded Dart Sass[^1] with Hugo v0.113.0 and earlier, uninstall Embedded Dart Sass, then install Dart Sass. If you have installed both, Hugo will use Dart Sass.
+
+If you install Hugo as a [Snap package][] there is no need to install Dart Sass. The Hugo Snap package includes Dart Sass.
+
+[^1]: In 2023, the Sass team deprecated Embedded Dart Sass in favor of Dart Sass.
+
+### Installing in a development environment
+
+When you install Dart Sass somewhere in your PATH, Hugo will find it.
+
+OS|Package manager|Site|Installation
+:--|:--|:--|:--
+Linux|Homebrew|[brew.sh]|`brew install sass/sass/sass`
+Linux|Snap|[snapcraft.io]|`sudo snap install dart-sass`
+macOS|Homebrew|[brew.sh]|`brew install sass/sass/sass`
+Windows|Chocolatey|[chocolatey.org]|`choco install sass`
+Windows|Scoop|[scoop.sh]|`scoop install sass`
+
+You may also install [prebuilt binaries][] for Linux, macOS, and Windows. You must install the prebuilt binary outside of your project directory and ensure its path is included in your system's PATH environment variable.
+
+Run `hugo env` to list the active transpilers.
+
+> [!note]
+> If you build Hugo from source and run `mage test -v`, the test will fail if you install Dart Sass as a Snap package. This is due to the Snap package's strict confinement model.
+
+### Installing in a production environment
+
+To use Dart Sass with Hugo on a [CI/CD](g) platform, you typically must modify your build workflow to install Dart Sass before the Hugo site build begins. This is because these platforms don't have Dart Sass pre-installed, and Hugo needs it to process your Sass files.
+
+There's one key exception where you can skip this step: you have committed your `resources` directory to your repository. This is only possible if:
+
+- You have not changed Hugo's default asset cache location.
+- You have not set [`useResourceCacheWhen`][] to never in your project configuration.
+
+By committing the `resources` directory, you're providing the pre-built CSS files directly to your CI/CD platform, so it doesn't need to run the Sass compilation itself.
+
+For examples of how to install Dart Sass in a production environment, see these hosting guides:
+
+- [Cloudflare][]
+- [GitHub Pages][]
+- [GitLab Pages][]
+- [Netlify][]
+- [Render][]
+- [SourceHut][]
+- [Vercel][]
+
+[`css.Quoted`]: /functions/css/quoted/
+[`css.Unquoted`]: /functions/css/unquoted/
+[`publishDir`]: /configuration/all/#publishdir
+[`useResourceCacheWhen`]: /configuration/build/#useresourcecachewhen
+[brew.sh]: https://brew.sh/
+[chocolatey.org]: https://community.chocolatey.org/packages/sass
+[Cloudflare]: /host-and-deploy/host-on-cloudflare/
+[Dart Sass]: https://sass-lang.com/dart-sass/
+[GitHub Pages]: /host-and-deploy/host-on-github-pages/
+[GitLab Pages]: /host-and-deploy/host-on-gitlab-pages/
+[indented]: https://sass-lang.com/documentation/syntax#the-indented-syntax
+[LibSass]: https://sass-lang.com/libsass
+[Netlify]: /host-and-deploy/host-on-netlify/
+[prebuilt binaries]: https://github.com/sass/dart-sass/releases/latest
+[Render]: /host-and-deploy/host-on-render/
+[scoop.sh]: https://scoop.sh/#/apps?q=sass
+[SCSS]: https://sass-lang.com/documentation/syntax#scss
+[Snap package]: https://snapcraft.io/hugo
+[snapcraft.io]: https://snapcraft.io/dart-sass
+[SourceHut]: /host-and-deploy/host-on-sourcehut-pages/
+[v0.153.0]: https://github.com/gohugoio/hugo/releases/tag/v0.153.0
+[Vercel]: /host-and-deploy/host-on-vercel/
diff --git a/documents/markdown/hugo-docs/en_functions_css_TailwindCSS.md b/documents/markdown/hugo-docs/en_functions_css_TailwindCSS.md
new file mode 100644
index 0000000..d104ed9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_css_TailwindCSS.md
@@ -0,0 +1,115 @@
+---
+title: css.TailwindCSS
+description: Processes the given resource with the Tailwind CSS CLI.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: resource.Resource
+ signatures: ['css.TailwindCSS [OPTIONS] RESOURCE']
+---
+
+Use the `css.TailwindCSS` function to process your Tailwind CSS files. This function uses the Tailwind CSS CLI to:
+
+1. Scan your templates for Tailwind CSS utility class usage.
+1. Compile those utility classes into standard CSS.
+1. Generate an optimized CSS output file.
+
+> [!note]
+> Use this function with Tailwind CSS v4.0 and later, which require a relatively [modern browser] to render correctly.
+
+[modern browser]: https://tailwindcss.com/docs/compatibility#browser-support
+
+## Setup
+
+Step 1
+: Install the Tailwind CSS CLI v4.0 or later:
+
+ ```sh {copy=true}
+ npm install --save-dev tailwindcss @tailwindcss/cli @tailwindcss/typography
+ ```
+
+ The Tailwind CSS CLI is also available as a [standalone executable]. You must install it outside of your project directory and ensure its path is included in your system's `PATH` environment variable.
+
+ [standalone executable]: https://github.com/tailwindlabs/tailwindcss/releases/latest
+
+Step 2
+: Add this to your project configuration:
+
+ {{< code-toggle file=hugo copy=true >}}
+ [build]
+ [build.buildStats]
+ enable = true
+ [[build.cachebusters]]
+ source = 'assets/notwatching/hugo_stats\.json'
+ target = 'css'
+ [[build.cachebusters]]
+ source = '(postcss|tailwind)\.config\.js'
+ target = 'css'
+ [module]
+ [[module.mounts]]
+ source = 'assets'
+ target = 'assets'
+ [[module.mounts]]
+ disableWatch = true
+ source = 'hugo_stats.json'
+ target = 'assets/notwatching/hugo_stats.json'
+ {{< /code-toggle >}}
+
+Step 3
+: Create a CSS entry file:
+
+ ```css {file="assets/css/main.css" copy=true}
+ @import "tailwindcss";
+ @plugin "@tailwindcss/typography";
+ @source "hugo_stats.json";
+ ```
+
+ Tailwind CSS respects `.gitignore` files. This means that if `hugo_stats.json` is listed in your `.gitignore` file, Tailwind CSS will ignore it. To make `hugo_stats.json` available to Tailwind CSS you must explicitly source it as shown in the example above.
+
+Step 4
+: Create a _partial_ template to process the CSS with the Tailwind CSS CLI:
+
+ ```go-html-template {file="layouts/_partials/css.html" copy=true}
+ {{ with resources.Get "css/main.css" }}
+ {{ $opts := dict "minify" (not hugo.IsDevelopment) }}
+ {{ with . | css.TailwindCSS $opts }}
+ {{ if hugo.IsDevelopment }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ else }}
+ {{ with . | fingerprint }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
+ {{ end }}
+ {{ end }}
+ {{ end }}
+ ```
+
+Step 5
+: Call the _partial_ template from your base template, deferring template execution until after all sites and output formats have been rendered:
+
+ ```go-html-template {file="layouts/baseof.html" copy=true}
+ <head>
+ ...
+ {{ with (templates.Defer (dict "key" "global")) }}
+ {{ partial "css.html" . }}
+ {{ end }}
+ ...
+ </head>
+ ```
+
+## Options
+
+minify
+: (`bool`) Whether to optimize and minify the output. Default is `false`.
+
+optimize
+: (`bool`) Whether to optimize the output without minifying. Default is `false`.
+
+disableInlineImports
+: {{< new-in 0.147.4 />}}
+: (`bool`) Whether to disable inlining of `@import` statements. Inlining is performed recursively, but currently once only per file. It is not possible to import the same file in different scopes (root, media query, etc.). Note that this import routine does not care about the CSS specification, so you can have `@import` statements anywhere in the file. Default is `false`.
+
+skipInlineImportsNotFound
+: (`bool`) Whether to allow the build process to continue despite unresolved import statements, preserving the original import declarations. It is important to note that the inline importer does not process URL-based imports or those with media queries, and these will remain unaltered even when this option is disabled. Default is `false`.
diff --git a/documents/markdown/hugo-docs/en_functions_css_Unquoted.md b/documents/markdown/hugo-docs/en_functions_css_Unquoted.md
new file mode 100644
index 0000000..9800b9d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_css_Unquoted.md
@@ -0,0 +1,73 @@
+---
+title: css.Unquoted
+description: Returns the given string, setting its data type to indicate that it must not be quoted when used in CSS.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: css.UnquotedString
+ signatures: [css.Unquoted STRING]
+---
+
+<!-- Added in v0.111.0 -->
+
+> [!note]
+> This function is only applicable to the [`vars`] option passed to the [`css.Sass`] function.
+
+When passing a `vars` map to the `css.Sass` function, Hugo detects common typed CSS values such as `24px` or `#FF0000` using regular expression matching. If necessary, you can bypass automatic type inference by using the `css.Unquoted` function to explicitly indicate that the value must not be treated as a quoted string.
+
+For example:
+
+```scss {file="assets/sass/main.scss"}
+@use "hugo:vars" as h;
+
+h1 {
+ font-size: h.$font-size-h1;
+}
+
+h2 {
+ font-size: h.$font-size-h2;
+}
+```
+
+```go-html-template {file="layouts/_partials/css.html"}
+{{ $vars := dict
+ "font_size_h1" ("72px * 0.500" | css.Unquoted)
+ "font_size_h2" ("72px * 0.375" | css.Unquoted)
+}}
+
+{{ with resources.Get "sass/main.scss" }}
+ {{ $opts := dict
+ "enableSourceMap" hugo.IsDevelopment
+ "outputStyle" (cond hugo.IsDevelopment "expanded" "compressed")
+ "targetPath" "css/main.css"
+ "transpiler" "dartsass"
+ "vars" $vars
+ }}
+ {{ with . | toCSS $opts }}
+ {{ if hugo.IsDevelopment }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ else }}
+ {{ with . | fingerprint }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+The Sass rules are transpiled to:
+
+```css {file="public/css/main.css"}
+h1 {
+ font-size: 36px;
+}
+
+h2 {
+ font-size: 27px;
+}
+```
+
+[`css.Sass`]: /functions/css/sass/
+[`vars`]: /functions/css/sass/#vars
diff --git a/documents/markdown/hugo-docs/en_functions_css__index.md b/documents/markdown/hugo-docs/en_functions_css__index.md
new file mode 100644
index 0000000..9faabbb
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_css__index.md
@@ -0,0 +1,7 @@
+---
+title: CSS functions
+linkTitle: css
+description: Use these functions to work with CSS and Sass files.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_debug_Dump.md b/documents/markdown/hugo-docs/en_functions_debug_Dump.md
new file mode 100644
index 0000000..c06a49a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_debug_Dump.md
@@ -0,0 +1,33 @@
+---
+title: debug.Dump
+description: Returns an object dump as a string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [debug.Dump VALUE]
+---
+
+```go-html-template
+<pre>{{ debug.Dump hugo.Data.books }}</pre>
+```
+
+```json
+[
+ {
+ "author": "Victor Hugo",
+ "rating": 4,
+ "title": "The Hunchback of Notre Dame"
+ },
+ {
+ "author": "Victor Hugo",
+ "rating": 5,
+ "title": "Les Misérables"
+ }
+]
+```
+
+> [!note]
+> Output from this function may change from one release to the next. Use for debugging only.
diff --git a/documents/markdown/hugo-docs/en_functions_debug_Timer.md b/documents/markdown/hugo-docs/en_functions_debug_Timer.md
new file mode 100644
index 0000000..d72b79e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_debug_Timer.md
@@ -0,0 +1,35 @@
+---
+title: debug.Timer
+description: Creates a named timer that reports elapsed time to the console.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: debug.Timer
+ signatures: [debug.Timer NAME]
+---
+
+Use the `debug.Timer` function to determine execution time for a block of code, useful for finding performance bottlenecks in templates.
+
+The timer starts when you instantiate it, and stops when you call its `Stop` method.
+
+```go-html-template
+{{ $t := debug.Timer "TestSqrt" }}
+{{ range 2000 }}
+ {{ $f := math.Sqrt . }}
+{{ end }}
+{{ $t.Stop }}
+```
+
+Use the `--logLevel info` command line flag when you build the site.
+
+```sh
+hugo build --logLevel info
+```
+
+The results are displayed in the console at the end of the build. You can have as many timers as you want and if you don't stop them, they will be stopped at the end of build.
+
+```text
+INFO timer: name TestSqrt count 1002 duration 2.496017496s average 2.491035ms median 2.282291ms
+```
diff --git a/documents/markdown/hugo-docs/en_functions_debug_VisualizeSpaces.md b/documents/markdown/hugo-docs/en_functions_debug_VisualizeSpaces.md
new file mode 100644
index 0000000..39b9158
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_debug_VisualizeSpaces.md
@@ -0,0 +1,17 @@
+---
+title: debug.VisualizeSpaces
+description: Returns the given string with spaces replaced by a visible string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [debug.VisualizeSpaces STRING]
+---
+
+<!-- Added in v0.112.0 -->
+
+```go-html-template
+{{ debug.VisualizeSpaces "foo bar" }} → foo[SPACE][SPACE]bar
+```
diff --git a/documents/markdown/hugo-docs/en_functions_debug__index.md b/documents/markdown/hugo-docs/en_functions_debug__index.md
new file mode 100644
index 0000000..49fe416
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_debug__index.md
@@ -0,0 +1,7 @@
+---
+title: Debug functions
+linkTitle: debug
+description: Use these functions to debug your templates.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_diagrams_Goat.md b/documents/markdown/hugo-docs/en_functions_diagrams_Goat.md
new file mode 100644
index 0000000..3802b46
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_diagrams_Goat.md
@@ -0,0 +1,115 @@
+---
+title: diagrams.Goat
+description: Returns an SVGDiagram object created from the given GoAT markup and options.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: diagrams.SVGDiagram
+ signatures: [diagrams.Goat MARKUP]
+---
+
+Useful in a [code block render hook], the `diagrams.Goat` function returns an SVGDiagram object created from the given [GoAT] markup.
+
+## Methods
+
+The SVGDiagram object has the following methods:
+
+Inner
+: (`template.HTML`) Returns the SVG child elements without a wrapping `svg` element, allowing you to create your own wrapper.
+
+Wrapped
+: (`template.HTML`) Returns the SVG child elements wrapped in an `svg` element.
+
+Width
+: (`int`) Returns the width of the rendered diagram, in pixels.
+
+Height
+: (`int`) Returns the height of the rendered diagram, in pixels.
+
+## GoAT Diagrams
+
+Hugo natively supports GoAT diagrams with an [embedded code block render hook].
+
+This Markdown:
+
+````text
+```goat
+.---. .-. .-. .-. .---.
+| A +--->| 1 |<--->| 2 |<--->| 3 |<---+ B |
+'---' '-' '+' '+' '---'
+```
+````
+
+Is rendered to:
+
+```html
+<div class="goat svg-container">
+ <svg xmlns="http://www.w3.org/2000/svg" font-family="Menlo,Lucida Console,monospace" viewBox="0 0 352 57">
+ ...
+ </svg>
+</div>
+```
+
+Which appears in your browser as:
+
+```goat {class="mw6-ns"}
+.---. .-. .-. .-. .---.
+| A +--->| 1 |<--->| 2 |<--->| 3 |<---+ B |
+'---' '-' '+' '+' '---'
+```
+
+To customize rendering, override Hugo's [embedded code block render hook] for GoAT diagrams.
+
+## Code block render hook
+
+By way of example, let's create a code block render hook to render GoAT diagrams as `figure` elements with an optional caption.
+
+```go-html-template {file="layouts/_markup/render-codeblock-goat.html"}
+{{ $caption := or .Attributes.caption "" }}
+{{ $class := or .Attributes.class "diagram" }}
+{{ $id := or .Attributes.id (printf "diagram-%d" (add 1 .Ordinal)) }}
+
+<figure id="{{ $id }}">
+ {{ with diagrams.Goat (trim .Inner "\n\r") }}
+ <svg class="{{ $class }}" width="{{ .Width }}" height="{{ .Height }}" xmlns="http://www.w3.org/2000/svg" version="1.1">
+ {{ .Inner }}
+ </svg>
+ {{ end }}
+ <figcaption>{{ $caption }}</figcaption>
+</figure>
+```
+
+This Markdown:
+
+````text {file="content/example.md" }
+```goat {class="foo" caption="Diagram 1: Example"}
+.---. .-. .-. .-. .---.
+| A +--->| 1 |<--->| 2 |<--->| 3 |<---+ B |
+'---' '-' '+' '+' '---'
+```
+````
+
+Is rendered to:
+
+```html
+<figure id="diagram-1">
+ <svg class="foo" width="272" height="57" xmlns="http://www.w3.org/2000/svg" version="1.1">
+ ...
+ </svg>
+ <figcaption>Diagram 1: Example</figcaption>
+</figure>
+```
+
+Use CSS to style the SVG as needed:
+
+```css
+svg.foo {
+ font-family: "Segoe UI","Noto Sans",Helvetica,Arial,sans-serif
+}
+```
+
+[code block render hook]: /render-hooks/code-blocks/
+[embedded code block render hook]: <{{% eturl render-codeblock-goat %}}>
+[GoAT]: https://github.com/bep/goat
diff --git a/documents/markdown/hugo-docs/en_functions_diagrams__index.md b/documents/markdown/hugo-docs/en_functions_diagrams__index.md
new file mode 100644
index 0000000..6aa4070
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_diagrams__index.md
@@ -0,0 +1,7 @@
+---
+title: Diagram functions
+linkTitle: diagrams
+description: Use these functions to render diagrams.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_encoding_Base64Decode.md b/documents/markdown/hugo-docs/en_functions_encoding_Base64Decode.md
new file mode 100644
index 0000000..5237e90
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_encoding_Base64Decode.md
@@ -0,0 +1,39 @@
+---
+title: encoding.Base64Decode
+description: Returns the base64 decoding of the given content.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [base64Decode]
+ returnType: string
+ signatures: [encoding.Base64Decode INPUT]
+aliases: [/functions/base64Decode]
+---
+
+```go-html-template
+{{ "SHVnbw==" | base64Decode }} → Hugo
+```
+
+Use the `base64Decode` function to decode responses from APIs. For example, the result of this call to GitHub's API contains the base64-encoded representation of the repository's README file:
+
+```text
+https://api.github.com/repos/gohugoio/hugo/readme
+```
+
+To retrieve and render the content:
+
+```go-html-template
+{{ $url := "https://api.github.com/repos/gohugoio/hugo/readme" }}
+{{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else with .Value }}
+ {{ with . | transform.Unmarshal }}
+ {{ .content | base64Decode | markdownify }}
+ {{ end }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+ {{ end }}
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_functions_encoding_Base64Encode.md b/documents/markdown/hugo-docs/en_functions_encoding_Base64Encode.md
new file mode 100644
index 0000000..e19d677
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_encoding_Base64Encode.md
@@ -0,0 +1,16 @@
+---
+title: encoding.Base64Encode
+description: Returns the base64 decoding of the given content.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [base64Encode]
+ returnType: string
+ signatures: [encoding.Base64Encode INPUT]
+aliases: [/functions/base64, /functions/base64Encode]
+---
+
+```go-html-template
+{{ "Hugo" | base64Encode }} → SHVnbw==
+```
diff --git a/documents/markdown/hugo-docs/en_functions_encoding_Jsonify.md b/documents/markdown/hugo-docs/en_functions_encoding_Jsonify.md
new file mode 100644
index 0000000..5bbbf14
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_encoding_Jsonify.md
@@ -0,0 +1,34 @@
+---
+title: encoding.Jsonify
+description: Encodes the given object to JSON.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [jsonify]
+ returnType: template.HTML
+ signatures: ['encoding.Jsonify [OPTIONS] INPUT']
+aliases: [/functions/jsonify]
+---
+
+To customize the printing of the JSON, pass an options map as the first
+argument. Supported options are "prefix" and "indent". Each JSON element in
+the output will begin on a new line beginning with _prefix_ followed by one or
+more copies of _indent_ according to the indentation nesting.
+
+```go-html-template
+{{ dict "title" .Title "content" .Plain | jsonify }}
+{{ dict "title" .Title "content" .Plain | jsonify (dict "indent" " ") }}
+{{ dict "title" .Title "content" .Plain | jsonify (dict "prefix" " " "indent" " ") }}
+```
+
+## Options
+
+indent
+: (`string`) Indentation to use. Default is "".
+
+prefix
+: (`string`) Indentation prefix. Default is "".
+
+noHTMLEscape
+: (`bool`) Whether to disable escaping of problematic HTML characters inside JSON quoted strings. The default behavior is to escape `&`, `<`, and `>` to `\u0026`, `\u003c`, and `\u003e` to avoid certain safety problems that can arise when embedding JSON in HTML. Default is `false`.
diff --git a/documents/markdown/hugo-docs/en_functions_encoding__index.md b/documents/markdown/hugo-docs/en_functions_encoding__index.md
new file mode 100644
index 0000000..f2819f0
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_encoding__index.md
@@ -0,0 +1,7 @@
+---
+title: Encoding functions
+linkTitle: encoding
+description: Use these functions to encode and decode data.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_fmt_Errorf.md b/documents/markdown/hugo-docs/en_functions_fmt_Errorf.md
new file mode 100644
index 0000000..799622f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_fmt_Errorf.md
@@ -0,0 +1,24 @@
+---
+title: fmt.Errorf
+description: Log an ERROR from a template.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [errorf]
+ returnType: string
+ signatures: ['fmt.Errorf FORMAT [INPUT]']
+aliases: [/functions/errorf]
+---
+
+{{% include "/_common/functions/fmt/format-string.md" %}}
+
+The `errorf` function evaluates the format string, then prints the result to the ERROR log and fails the build.
+
+```go-html-template
+{{ errorf "The %q shortcode requires a src argument. See %s" .Name .Position }}
+```
+
+Use the [`erroridf`] function to allow optional suppression of specific errors.
+
+[`erroridf`]: /functions/fmt/erroridf/
diff --git a/documents/markdown/hugo-docs/en_functions_fmt_Erroridf.md b/documents/markdown/hugo-docs/en_functions_fmt_Erroridf.md
new file mode 100644
index 0000000..d6af48f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_fmt_Erroridf.md
@@ -0,0 +1,38 @@
+---
+title: fmt.Erroridf
+description: Log a suppressible ERROR from a template.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [erroridf]
+ returnType: string
+ signatures: ['fmt.Erroridf ID FORMAT [INPUT]']
+aliases: [/functions/erroridf]
+---
+
+{{% include "/_common/functions/fmt/format-string.md" %}}
+
+The `erroridf` function evaluates the format string, then prints the result to the ERROR log and fails the build. Unlike the [`errorf`] function, you may suppress errors logged by the `erroridf` function by adding the message ID to the `ignoreLogs` array in your project configuration.
+
+This template code:
+
+```go-html-template
+{{ erroridf "error-42" "You should consider fixing this." }}
+```
+
+Produces this console log:
+
+```text
+ERROR You should consider fixing this.
+You can suppress this error by adding the following to your project configuration:
+ignoreLogs = ['error-42']
+```
+
+To suppress this message:
+
+{{< code-toggle file=hugo >}}
+ignoreLogs = ["error-42"]
+{{< /code-toggle >}}
+
+[`errorf`]: /functions/fmt/errorf/
diff --git a/documents/markdown/hugo-docs/en_functions_fmt_Print.md b/documents/markdown/hugo-docs/en_functions_fmt_Print.md
new file mode 100644
index 0000000..f1d169c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_fmt_Print.md
@@ -0,0 +1,18 @@
+---
+title: fmt.Print
+description: Prints the default representation of the given arguments using the standard `fmt.Print` function.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [print]
+ returnType: string
+ signatures: [fmt.Print INPUT]
+aliases: [/functions/print]
+---
+
+```go-html-template
+{{ print "foo" }} → foo
+{{ print "foo" "bar" }} → foobar
+{{ print (slice 1 2 3) }} → [1 2 3]
+```
diff --git a/documents/markdown/hugo-docs/en_functions_fmt_Printf.md b/documents/markdown/hugo-docs/en_functions_fmt_Printf.md
new file mode 100644
index 0000000..68df986
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_fmt_Printf.md
@@ -0,0 +1,37 @@
+---
+title: fmt.Printf
+description: Formats a string using the standard `fmt.Sprintf` function.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [printf]
+ returnType: string
+ signatures: ['fmt.Printf FORMAT [INPUT]']
+aliases: [/functions/printf]
+---
+
+{{% include "/_common/functions/fmt/format-string.md" %}}
+
+```go-html-template
+{{ $var := "world" }}
+{{ printf "Hello %s." $var }} → Hello world.
+```
+
+```go-html-template
+{{ $pi := 3.14159265 }}
+{{ printf "Pi is approximately %.2f." $pi }} → 3.14
+```
+
+Use the `printf` function with the `safeHTMLAttr` function:
+
+```go-html-template
+{{ $desc := "Eat at Joe's" }}
+<meta name="description" {{ printf "content=%q" $desc | safeHTMLAttr }}>
+```
+
+Hugo renders this to:
+
+```html
+<meta name="description" content="Eat at Joe's">
+```
diff --git a/documents/markdown/hugo-docs/en_functions_fmt_Println.md b/documents/markdown/hugo-docs/en_functions_fmt_Println.md
new file mode 100644
index 0000000..6bcda3b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_fmt_Println.md
@@ -0,0 +1,17 @@
+---
+title: fmt.Println
+description: Prints the default representation of the given argument using the standard `fmt.Print` function and enforces a line break.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [println]
+ returnType: string
+ signatures: [fmt.Println INPUT]
+aliases: [/functions/println]
+---
+
+```go-html-template
+{{ println "foo" }} → foo\n
+{{ println "foo" "bar" }} → foo bar\n
+```
diff --git a/documents/markdown/hugo-docs/en_functions_fmt_Warnf.md b/documents/markdown/hugo-docs/en_functions_fmt_Warnf.md
new file mode 100644
index 0000000..887a8d4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_fmt_Warnf.md
@@ -0,0 +1,34 @@
+---
+title: fmt.Warnf
+description: Log a WARNING from a template.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [warnf]
+ returnType: string
+ signatures: ['fmt.Warnf FORMAT [INPUT]']
+aliases: [/functions/warnf]
+---
+
+{{% include "/_common/functions/fmt/format-string.md" %}}
+
+The `warnf` function evaluates the format string, then prints the result to the WARNING log. Hugo prints each unique message once to avoid flooding the log with duplicate warnings.
+
+```go-html-template
+{{ warnf "The %q shortcode was unable to find %s. See %s" .Name $file .Position }}
+```
+
+Use the [`warnidf`] function to allow optional suppression of specific warnings.
+
+To prevent suppression of duplicate messages when using `warnf` for debugging, make each message unique with the [`math.Counter`] function. For example:
+
+```go-html-template
+{{ range site.RegularPages }}
+ {{ .Section | warnf "%#[2]v [%[1]d]" math.Counter }}
+{{ end }}
+```
+
+[`math.Counter`]: /functions/math/counter/
+
+[`warnidf`]: /functions/fmt/warnidf/
diff --git a/documents/markdown/hugo-docs/en_functions_fmt_Warnidf.md b/documents/markdown/hugo-docs/en_functions_fmt_Warnidf.md
new file mode 100644
index 0000000..21fee29
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_fmt_Warnidf.md
@@ -0,0 +1,38 @@
+---
+title: fmt.Warnidf
+description: Log a suppressible WARNING from a template.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [warnidf]
+ returnType: string
+ signatures: ['fmt.Warnidf ID FORMAT [INPUT]']
+aliases: [/functions/warnidf]
+---
+
+{{% include "/_common/functions/fmt/format-string.md" %}}
+
+The `warnidf` function evaluates the format string, then prints the result to the WARNING log. Unlike the [`warnf`] function, you may suppress warnings logged by the `warnidf` function by adding the message ID to the `ignoreLogs` array in your project configuration.
+
+This template code:
+
+```go-html-template
+{{ warnidf "warning-42" "You should consider fixing this." }}
+```
+
+Produces this console log:
+
+```text
+WARN You should consider fixing this.
+You can suppress this warning by adding the following to your project configuration:
+ignoreLogs = ['warning-42']
+```
+
+To suppress this message:
+
+{{< code-toggle file=hugo >}}
+ignoreLogs = ["warning-42"]
+{{< /code-toggle >}}
+
+[`warnf`]: /functions/fmt/warnf/
diff --git a/documents/markdown/hugo-docs/en_functions_fmt__index.md b/documents/markdown/hugo-docs/en_functions_fmt__index.md
new file mode 100644
index 0000000..d388df1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_fmt__index.md
@@ -0,0 +1,7 @@
+---
+title: Fmt functions
+linkTitle: fmt
+description: Use these functions to print strings within a template or to print messages to the terminal.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_global__index.md b/documents/markdown/hugo-docs/en_functions_global__index.md
new file mode 100644
index 0000000..3d93517
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_global__index.md
@@ -0,0 +1,6 @@
+---
+title: Global functions
+linkTitle: global
+description: Use these global functions to access page and site data.
+categories: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_global_page.md b/documents/markdown/hugo-docs/en_functions_global_page.md
new file mode 100644
index 0000000..a7672d9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_global_page.md
@@ -0,0 +1,100 @@
+---
+title: page
+description: Provides global access to a Page object.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType:
+ signatures: [page]
+aliases: [/functions/page]
+---
+
+At the top level of a template that receives a `Page` object in context, these are equivalent:
+
+```go-html-template
+{{ .Params.foo }}
+{{ .Page.Params.foo }}
+{{ page.Params.foo }}
+```
+
+When a `Page` object is not in context, you can use the global `page` function:
+
+```go-html-template
+{{ page.Params.foo }}
+```
+
+> [!note]
+> Do not use the global `page` function in shortcodes, partials called by shortcodes, or cached partials. See [warnings](#warnings) below.
+
+## Explanation
+
+Hugo almost always passes a `Page` as the data context into the top-level template (e.g., `baseof.html`). The one exception is the multihost sitemap template. This means that you can access the current page with the `.` in the template.
+
+But when you are deeply nested inside of a [content view](g), [partial](g), or [render hook](g), it is not always practical or possible to access the `Page` object.
+
+Use the global `page` function to access the `Page` object from anywhere in any template.
+
+## Warnings
+
+### Be aware of top-level context
+
+The global `page` function accesses the `Page` object passed into the top-level template.
+
+With this content structure:
+
+```text
+content/
+├── posts/
+│ ├── post-1.md
+│ ├── post-2.md
+│ └── post-3.md
+└── _index.md <-- title is "My Home Page"
+```
+
+And this code in the _home_ template:
+
+```go-html-template {file="layouts/home.html"}
+{{ range site.Sections }}
+ {{ range .Pages }}
+ {{ page.Title }}
+ {{ end }}
+{{ end }}
+```
+
+The rendered output will be:
+
+```text
+My Home Page
+My Home Page
+My Home Page
+```
+
+In the example above, the global `page` function accesses the `Page` object passed into the _home_ template; it does not access the `Page` object of the iterated pages.
+
+### Be aware of caching
+
+Do not use the global `page` function in:
+
+- Shortcodes
+- Partials called by shortcodes
+- Partials cached by the [`partialCached`] function
+
+Hugo caches rendered shortcodes. If you use the global `page` function within a shortcode, and the page content is rendered in two or more templates, the cached shortcode may be incorrect.
+
+Consider this _section_ template:
+
+```go-html-template {file="layouts/section.html"}
+{{ range .Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ .Summary }}
+{{ end }}
+```
+
+When you call the [`Summary`] method, Hugo renders the page content including shortcodes. In this case, within a shortcode, the global `page` function accesses the `Page` object of the section page, not the content page.
+
+If Hugo renders the section page before a content page, the cached rendered shortcode will be incorrect. You cannot control the rendering sequence due to concurrency.
+
+[`partialCached`]: /functions/partials/includecached/
+[`Summary`]: /methods/page/summary/
diff --git a/documents/markdown/hugo-docs/en_functions_global_site.md b/documents/markdown/hugo-docs/en_functions_global_site.md
new file mode 100644
index 0000000..be0c673
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_global_site.md
@@ -0,0 +1,30 @@
+---
+title: site
+description: Provides global access to the current Site object.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType:
+ signatures: [site]
+aliases: [/functions/site]
+---
+
+Use the `site` function to return the `Site` object regardless of current context.
+
+```go-html-template
+{{ site.Params.foo }}
+```
+
+When the `Site` object is in context you can use the `Site` property:
+
+```go-html-template
+<!-- current context -->
+{{ .Site.Params.foo }}
+<!-- template context -->
+{{ $.Site.Params.foo }}
+```
+
+> [!note]
+> To simplify your templates, use the global `site` function regardless of whether the `Site` object is in context.
diff --git a/documents/markdown/hugo-docs/en_functions_go-template__index.md b/documents/markdown/hugo-docs/en_functions_go-template__index.md
new file mode 100644
index 0000000..627dc28
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_go-template__index.md
@@ -0,0 +1,7 @@
+---
+title: Go template functions, operators, and statements
+linkTitle: go template
+description: These are the functions, operators, and statements provided by Go's text/template package.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_go-template_and.md b/documents/markdown/hugo-docs/en_functions_go-template_and.md
new file mode 100644
index 0000000..016a8cf
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_go-template_and.md
@@ -0,0 +1,28 @@
+---
+title: and
+description: Returns the first falsy argument. If all arguments are truthy, returns the last argument.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: any
+ signatures: [and VALUE...]
+---
+
+{{% include "/_common/functions/truthy-falsy.md" %}}
+
+The `and` function evaluates the arguments from left to right, and returns when the result is determined.
+
+```go-html-template
+{{ and 1 0 "" }} → 0 (int)
+{{ and 1 false 0 }} → false (bool)
+
+{{ and 1 2 3 }} → 3 (int)
+{{ and "a" "b" "c" }} → c (string)
+{{ and "a" 1 true }} → true (bool)
+
+{{ and false (math.Div 1 0) }} → false (bool)
+```
+
+{{% include "/_common/functions/go-template/text-template.md" %}}
diff --git a/documents/markdown/hugo-docs/en_functions_go-template_block.md b/documents/markdown/hugo-docs/en_functions_go-template_block.md
new file mode 100644
index 0000000..d603a1f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_go-template_block.md
@@ -0,0 +1,54 @@
+---
+title: block
+description: Defines a template and executes it in place.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType:
+ signatures: [block NAME CONTEXT]
+---
+
+A block is shorthand for defining a template:
+
+```go-html-template
+{{ define "name" }} T1 {{ end }}
+```
+
+and then executing it in place:
+
+```go-html-template
+{{ template "name" pipeline }}
+```
+
+The typical use is to define a set of root templates that are then customized by redefining the block templates within.
+
+```go-html-template {file="layouts/baseof.html"}
+<body>
+ <main>
+ {{ block "main" . }}
+ {{ print "default value if 'main' template is empty" }}
+ {{ end }}
+ </main>
+</body>
+```
+
+```go-html-template {file="layouts/page.html"}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+{{ end }}
+```
+
+```go-html-template {file="layouts/section.html"}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+ {{ range .Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ end }}
+{{ end }}
+```
+
+{{% include "/_common/functions/go-template/text-template.md" %}}
diff --git a/documents/markdown/hugo-docs/en_functions_go-template_break.md b/documents/markdown/hugo-docs/en_functions_go-template_break.md
new file mode 100644
index 0000000..9236ec9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_go-template_break.md
@@ -0,0 +1,31 @@
+---
+title: break
+description: Used with the range statement, stops the innermost iteration and bypasses all remaining iterations.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType:
+ signatures: [break]
+---
+
+This template code:
+
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $s }}
+ {{ if eq . "bar" }}
+ {{ break }}
+ {{ end }}
+ <p>{{ . }}</p>
+{{ end }}
+```
+
+Is rendered to:
+
+```html
+<p>foo</p>
+```
+
+{{% include "/_common/functions/go-template/text-template.md" %}}
diff --git a/documents/markdown/hugo-docs/en_functions_go-template_continue.md b/documents/markdown/hugo-docs/en_functions_go-template_continue.md
new file mode 100644
index 0000000..0b9339b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_go-template_continue.md
@@ -0,0 +1,32 @@
+---
+title: continue
+description: Used with the range statement, stops the innermost iteration and continues to the next iteration.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType:
+ signatures: [continue]
+---
+
+This template code:
+
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $s }}
+ {{ if eq . "bar" }}
+ {{ continue }}
+ {{ end }}
+ <p>{{ . }}</p>
+{{ end }}
+```
+
+Is rendered to:
+
+```html
+<p>foo</p>
+<p>baz</p>
+```
+
+{{% include "/_common/functions/go-template/text-template.md" %}}
diff --git a/documents/markdown/hugo-docs/en_functions_go-template_define.md b/documents/markdown/hugo-docs/en_functions_go-template_define.md
new file mode 100644
index 0000000..e493905
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_go-template_define.md
@@ -0,0 +1,50 @@
+---
+title: define
+description: Defines a template.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType:
+ signatures: [define NAME]
+---
+
+Use with the [`block`] statement:
+
+```go-html-template
+{{ block "main" . }}
+ {{ print "default value if 'main' template is empty" }}
+{{ end }}
+
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+{{ end }}
+```
+
+Use with the [`partial`] function:
+
+```go-html-template
+{{ partial "inline/foo.html" (dict "answer" 42) }}
+
+{{ define "_partials/inline/foo.html" }}
+ {{ printf "The answer is %v." .answer }}
+{{ end }}
+```
+
+Use with the [`template`] function:
+
+```go-html-template
+{{ template "foo" (dict "answer" 42) }}
+
+{{ define "foo" }}
+ {{ printf "The answer is %v." .answer }}
+{{ end }}
+```
+
+{{% include "/_common/functions/go-template/text-template.md" %}}
+
+[`block`]: /functions/go-template/block/
+[`template`]: /functions/go-template/block/
+[`partial`]: /functions/partials/include/
diff --git a/documents/markdown/hugo-docs/en_functions_go-template_else.md b/documents/markdown/hugo-docs/en_functions_go-template_else.md
new file mode 100644
index 0000000..db39800
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_go-template_else.md
@@ -0,0 +1,65 @@
+---
+title: else
+description: Begins an alternate block for if, with, and range statements.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType:
+ signatures: [else VALUE]
+---
+
+Use with the [`if`] statement:
+
+```go-html-template
+{{ $var := "foo" }}
+{{ if $var }}
+ {{ $var }} → foo
+{{ else }}
+ {{ print "var is falsy" }}
+{{ end }}
+```
+
+Use with the [`with`] statement:
+
+```go-html-template
+{{ $var := "foo" }}
+{{ with $var }}
+ {{ . }} → foo
+{{ else }}
+ {{ print "var is falsy" }}
+{{ end }}
+```
+
+Use with the [`range`] statement:
+
+```go-html-template
+{{ $var := slice 1 2 3 }}
+{{ range $var }}
+ {{ . }} → 1 2 3
+{{ else }}
+ {{ print "var is falsy" }}
+{{ end }}
+```
+
+Use `else if` to check multiple conditions.
+
+```go-html-template
+{{ $var := 12 }}
+{{ if eq $var 6 }}
+ {{ print "var is 6" }}
+{{ else if eq $var 7 }}
+ {{ print "var is 7" }}
+{{ else if eq $var 42 }}
+ {{ print "var is 42" }}
+{{ else }}
+ {{ print "var is something else" }}
+{{ end }}
+```
+
+{{% include "/_common/functions/go-template/text-template.md" %}}
+
+[`if`]: /functions/go-template/if/
+[`with`]: /functions/go-template/with/
+[`range`]: /functions/go-template/range/
diff --git a/documents/markdown/hugo-docs/en_functions_go-template_end.md b/documents/markdown/hugo-docs/en_functions_go-template_end.md
new file mode 100644
index 0000000..6de1207
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_go-template_end.md
@@ -0,0 +1,60 @@
+---
+title: end
+description: Terminates if, with, range, block, and define statements.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType:
+ signatures: [end]
+---
+
+Use with the [`if`] statement:
+
+```go-html-template
+{{ $var := "foo" }}
+{{ if $var }}
+ {{ $var }} → foo
+{{ end }}
+```
+
+Use with the [`with`] statement:
+
+```go-html-template
+{{ $var := "foo" }}
+{{ with $var }}
+ {{ . }} → foo
+{{ end }}
+```
+
+Use with the [`range`] statement:
+
+```go-html-template
+{{ $var := slice 1 2 3 }}
+{{ range $var }}
+ {{ . }} → 1 2 3
+{{ end }}
+```
+
+Use with the [`block`] statement:
+
+```go-html-template
+{{ block "main" . }}{{ end }}
+```
+
+Use with the [`define`] statement:
+
+```go-html-template
+{{ define "main" }}
+ {{ print "this is the main section" }}
+{{ end }}
+```
+
+{{% include "/_common/functions/go-template/text-template.md" %}}
+
+[`block`]: /functions/go-template/block/
+[`define`]: /functions/go-template/define/
+[`if`]: /functions/go-template/if/
+[`range`]: /functions/go-template/range/
+[`with`]: /functions/go-template/with/
diff --git a/documents/markdown/hugo-docs/en_functions_go-template_if.md b/documents/markdown/hugo-docs/en_functions_go-template_if.md
new file mode 100644
index 0000000..af2989c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_go-template_if.md
@@ -0,0 +1,50 @@
+---
+title: if
+description: Executes the block if the expression is truthy.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType:
+ signatures: [if EXPR]
+---
+
+{{% include "/_common/functions/truthy-falsy.md" %}}
+
+```go-html-template
+{{ $var := "foo" }}
+{{ if $var }}
+ {{ $var }} → foo
+{{ end }}
+```
+
+Use with the [`else`] statement:
+
+```go-html-template
+{{ $var := "foo" }}
+{{ if $var }}
+ {{ $var }} → foo
+{{ else }}
+ {{ print "var is falsy" }}
+{{ end }}
+```
+
+Use `else if` to check multiple conditions:
+
+```go-html-template
+{{ $var := 12 }}
+{{ if eq $var 6 }}
+ {{ print "var is 6" }}
+{{ else if eq $var 7 }}
+ {{ print "var is 7" }}
+{{ else if eq $var 42 }}
+ {{ print "var is 42" }}
+{{ else }}
+ {{ print "var is something else" }}
+{{ end }}
+```
+
+{{% include "/_common/functions/go-template/text-template.md" %}}
+
+[`else`]: /functions/go-template/else/
diff --git a/documents/markdown/hugo-docs/en_functions_go-template_len.md b/documents/markdown/hugo-docs/en_functions_go-template_len.md
new file mode 100644
index 0000000..6a13784
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_go-template_len.md
@@ -0,0 +1,47 @@
+---
+title: len
+description: Returns the length of a string, slice, map, or collection.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: int
+ signatures: [len VALUE]
+aliases: [/functions/len]
+---
+
+With a string:
+
+```go-html-template
+{{ "ab" | len }} → 2
+{{ "" | len }} → 0
+```
+
+With a slice:
+
+```go-html-template
+{{ slice "a" "b" | len }} → 2
+{{ slice | len }} → 0
+```
+
+With a map:
+
+```go-html-template
+{{ dict "a" 1 "b" 2 | len }} → 2
+{{ dict | len }} → 0
+```
+
+With a collection:
+
+```go-html-template
+{{ site.RegularPages | len }} → 42
+```
+
+You may also determine the number of pages in a collection with:
+
+```go-html-template
+{{ site.RegularPages.Len }} → 42
+```
+
+{{% include "/_common/functions/go-template/text-template.md" %}}
diff --git a/documents/markdown/hugo-docs/en_functions_go-template_not.md b/documents/markdown/hugo-docs/en_functions_go-template_not.md
new file mode 100644
index 0000000..fd8b9af
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_go-template_not.md
@@ -0,0 +1,33 @@
+---
+title: not
+description: Returns the boolean negation of its single argument.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [not VALUE]
+---
+
+Unlike the `and` and `or` operators, the `not` operator always returns a boolean value.
+
+```go-html-template
+{{ not true }} → false
+{{ not false }} → true
+
+{{ not 1 }} → false
+{{ not 0 }} → true
+
+{{ not "x" }} → false
+{{ not "" }} → true
+```
+
+Use the `not` operator, twice in succession, to cast any value to a boolean value. For example:
+
+```go-html-template
+{{ 42 | not | not }} → true
+{{ "" | not | not }} → false
+```
+
+{{% include "/_common/functions/go-template/text-template.md" %}}
diff --git a/documents/markdown/hugo-docs/en_functions_go-template_or.md b/documents/markdown/hugo-docs/en_functions_go-template_or.md
new file mode 100644
index 0000000..1b85a5d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_go-template_or.md
@@ -0,0 +1,28 @@
+---
+title: or
+description: Returns the first truthy argument. If all arguments are falsy, returns the last argument.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: any
+ signatures: [or VALUE...]
+---
+
+{{% include "/_common/functions/truthy-falsy.md" %}}
+
+The `or` function evaluates the arguments from left to right, and returns when the result is determined.
+
+```go-html-template
+{{ or 0 1 2 }} → 1 (int)
+{{ or false "a" 1 }} → a (string)
+{{ or 0 true "a" }} → true (bool)
+
+{{ or false "" 0 }} → 0 (int)
+{{ or 0 "" false }} → false (bool)
+
+{{ or true (math.Div 1 0) }} → true (bool)
+```
+
+{{% include "/_common/functions/go-template/text-template.md" %}}
diff --git a/documents/markdown/hugo-docs/en_functions_go-template_range.md b/documents/markdown/hugo-docs/en_functions_go-template_range.md
new file mode 100644
index 0000000..07d9525
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_go-template_range.md
@@ -0,0 +1,220 @@
+---
+title: range
+description: Iterates over a non-empty collection, binds context (the dot) to successive elements, and executes the block.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType:
+ signatures: [range COLLECTION]
+aliases: [/functions/range]
+---
+
+The collection may be a slice, a map, or an integer.
+
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $s }}
+ {{ . }} → foo bar baz
+{{ end }}
+```
+
+Use with the [`else`] statement:
+
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $s }}
+ <p>{{ . }}</p>
+{{ else }}
+ <p>The collection is empty</p>
+{{ end }}
+```
+
+Within a range block:
+
+- Use the [`continue`] statement to stop the innermost iteration and continue to the next iteration
+- Use the [`break`] statement to stop the innermost iteration and bypass all remaining iterations
+
+## Understanding context
+
+See the [context] section in the introduction to templating.
+
+For example, at the top of a _page_ template, the [context](g) (the dot) is a `Page` object. Within the `range` block, the context is bound to each successive element.
+
+With this contrived example:
+
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $s }}
+ {{ .Title }}
+{{ end }}
+```
+
+Hugo will throw an error:
+
+```text
+can't evaluate field Title in type int
+```
+
+The error occurs because we are trying to use the `.Title` method on a string instead of a `Page` object. Within the `range` block, if we want to render the page title, we need to get the context passed into the template.
+
+> [!note]
+> Use the `$` to get the context passed into the template.
+
+This template will render the page title three times:
+
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $s }}
+ {{ $.Title }}
+{{ end }}
+```
+
+> [!note]
+> Gaining a thorough understanding of context is critical for anyone writing template code.
+
+## Examples
+
+### Slice of scalars
+
+This template code:
+
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $s }}
+ <p>{{ . }}</p>
+{{ end }}
+```
+
+Is rendered to:
+
+```html
+<p>foo</p>
+<p>bar</p>
+<p>baz</p>
+```
+
+This template code:
+
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $v := $s }}
+ <p>{{ $v }}</p>
+{{ end }}
+```
+
+Is rendered to:
+
+```html
+<p>foo</p>
+<p>bar</p>
+<p>baz</p>
+```
+
+This template code:
+
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $k, $v := $s }}
+ <p>{{ $k }}: {{ $v }}</p>
+{{ end }}
+```
+
+Is rendered to:
+
+```html
+<p>0: foo</p>
+<p>1: bar</p>
+<p>2: baz</p>
+```
+
+### Slice of maps
+
+This template code:
+
+```go-html-template
+{{ $m := slice
+ (dict "name" "John" "age" 30)
+ (dict "name" "Will" "age" 28)
+ (dict "name" "Joey" "age" 24)
+}}
+{{ range $m }}
+ <p>{{ .name }} is {{ .age }}</p>
+{{ end }}
+```
+
+Is rendered to:
+
+```html
+<p>John is 30</p>
+<p>Will is 28</p>
+<p>Joey is 24</p>
+```
+
+### Slice of pages
+
+This template code:
+
+```go-html-template
+{{ range where site.RegularPages "Type" "articles" }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+Is rendered to:
+
+```html
+<h2><a href="/articles/article-3/">Article 3</a></h2>
+<h2><a href="/articles/article-2/">Article 2</a></h2>
+<h2><a href="/articles/article-1/">Article 1</a></h2>
+```
+
+### Maps
+
+This template code:
+
+```go-html-template
+{{ $m := dict "name" "John" "age" 30 }}
+{{ range $k, $v := $m }}
+ <p>key = {{ $k }} value = {{ $v }}</p>
+{{ end }}
+```
+
+Is rendered to:
+
+```go-html-template
+<p>key = age value = 30</p>
+<p>key = name value = John</p>
+```
+
+Unlike ranging over an array or slice, Hugo sorts by key when ranging over a map.
+
+### Integers
+
+Ranging over a positive integer `n` executes the block `n` times, with the context starting at zero and incrementing by one in each iteration.
+
+```go-html-template
+{{ $s := slice }}
+{{ range 1 }}
+ {{ $s = $s | append . }}
+{{ end }}
+{{ $s }} → [0]
+```
+
+```go-html-template
+{{ $s := slice }}
+{{ range 3 }}
+ {{ $s = $s | append . }}
+{{ end }}
+{{ $s }} → [0 1 2]
+```
+
+Ranging over a non-positive integer executes the block zero times.
+
+{{% include "/_common/functions/go-template/text-template.md" %}}
+
+[`break`]: /functions/go-template/break/
+[`continue`]: /functions/go-template/continue/
+[`else`]: /functions/go-template/else/
+[context]: /templates/introduction/#context
diff --git a/documents/markdown/hugo-docs/en_functions_go-template_return.md b/documents/markdown/hugo-docs/en_functions_go-template_return.md
new file mode 100644
index 0000000..e969085
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_go-template_return.md
@@ -0,0 +1,93 @@
+---
+title: return
+description: Used within partial templates, terminates template execution and returns the given value, if any.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: any
+ signatures: ['return [VALUE]']
+---
+
+The `return` statement is a non-standard extension to Go's [text/template package]. Used within _partial_ templates, the `return` statement terminates template execution and returns the given value, if any.
+
+The returned value may be of any data type including, but not limited to, [`bool`](g), [`float`](g), [`int`](g), [`map`](g), [`resource`](g), [`slice`](g), or [`string`](g).
+
+A `return` statement without a value returns an empty string of type `template.HTML`.
+
+> [!note]
+> Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks. See [usage](#usage) notes below.
+
+## Example
+
+By way of example, let's create a _partial_ template that _renders_ HTML, describing whether the given number is odd or even:
+
+```go-html-template {file="layouts/_partials/odd-or-even.html"}
+{{ if math.ModBool . 2 }}
+ <p>{{ . }} is even</p>
+{{ else }}
+ <p>{{ . }} is odd</p>
+{{ end }}
+```
+
+When called, the partial renders HTML:
+
+```go-html-template
+{{ partial "odd-or-even.html" 42 }} → <p>42 is even</p>
+```
+
+Instead of rendering HTML, let's create a partial that _returns_ a boolean value, reporting whether the given number is even:
+
+```go-html-template {file="layouts/_partials/is-even.html"}
+{{ return math.ModBool . 2 }}
+```
+
+With this template:
+
+```go-html-template
+{{ $number := 42 }}
+{{ if partial "is-even.html" $number }}
+ <p>{{ $number }} is even</p>
+{{ else }}
+ <p>{{ $number }} is odd</p>
+{{ end }}
+```
+
+Hugo renders:
+
+```html
+<p>42 is even</p>
+```
+
+## Usage
+
+> [!note]
+> Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks.
+
+A partial that returns a value must contain only one `return` statement, placed at the end of the template.
+
+For example:
+
+```go-html-template {file="layouts/_partials/is-even.html"}
+{{ $result := false }}
+{{ if math.ModBool . 2 }}
+ {{ $result = "even" }}
+{{ else }}
+ {{ $result = "odd" }}
+{{ end }}
+{{ return $result }}
+```
+
+> [!note]
+> The construct below is incorrect; it contains more than one `return` statement.
+
+```go-html-template {file="layouts/_partials/do-not-do-this.html"}
+{{ if math.ModBool . 2 }}
+ {{ return "even" }}
+{{ else }}
+ {{ return "odd" }}
+{{ end }}
+```
+
+[text/template package]: https://pkg.go.dev/text/template
diff --git a/documents/markdown/hugo-docs/en_functions_go-template_template.md b/documents/markdown/hugo-docs/en_functions_go-template_template.md
new file mode 100644
index 0000000..671f95e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_go-template_template.md
@@ -0,0 +1,42 @@
+---
+title: template
+description: Executes the given template, optionally passing context.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType:
+ signatures: ['template NAME [CONTEXT]']
+---
+
+Use the `template` function to execute a defined template:
+
+```go-html-template
+{{ template "foo" (dict "answer" 42) }}
+
+{{ define "foo" }}
+ {{ printf "The answer is %v." .answer }}
+{{ end }}
+```
+
+The example above can be rewritten using an inline _partial_ template:
+
+```go-html-template
+{{ partial "inline/foo.html" (dict "answer" 42) }}
+
+{{ define "_partials/inline/foo.html" }}
+ {{ printf "The answer is %v." .answer }}
+{{ end }}
+```
+
+The key distinctions between the preceding two examples are:
+
+1. Inline partials are globally scoped. That means that an inline partial defined in _one_ template may be called from _any_ template.
+1. Leveraging the [`partialCached`] function when calling an inline partial allows for performance optimization through result caching.
+1. An inline partial can [`return`] a value of any data type instead of rendering a string.
+
+{{% include "/_common/functions/go-template/text-template.md" %}}
+
+[`partialCached`]: /functions/partials/includecached/
+[`return`]: /functions/go-template/return/
diff --git a/documents/markdown/hugo-docs/en_functions_go-template_try.md b/documents/markdown/hugo-docs/en_functions_go-template_try.md
new file mode 100644
index 0000000..4ef2126
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_go-template_try.md
@@ -0,0 +1,112 @@
+---
+title: try
+description: Returns a TryValue object after evaluating the given expression.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: TryValue
+ signatures: ['try EXPRESSION']
+---
+
+{{< new-in 0.141.0 />}}
+
+The `try` statement is a non-standard extension to Go's [`text/template`][] package. It introduces a mechanism for handling errors within templates, mimicking the `try-catch` constructs found in other programming languages.
+
+## Methods
+
+The `TryValue` object encapsulates the result of evaluating the expression, and provides two methods:
+
+### Err
+
+(`string`) Returns a string representation of the error thrown by the expression, if an error occurred, or returns `nil` if the expression evaluated without errors.
+
+### Value
+
+(`any`) Returns the result of the expression if the evaluation was successful, or returns `nil` if an error occurred while evaluating the expression.
+
+## Explanation
+
+By way of example, let's divide a number by zero:
+
+```go-html-template
+{{ $x := 1 }}
+{{ $y := 0 }}
+{{ $result := div $x $y }}
+{{ printf "%v divided by %v equals %v" $x $y .Value }}
+```
+
+As expected, the example above throws an error and fails the build:
+
+```terminfo
+Error: error calling div: can't divide the value by 0
+```
+
+Instead of failing the build, we can catch the error and emit a warning:
+
+```go-html-template
+{{ $x := 1 }}
+{{ $y := 0 }}
+{{ with try (div $x $y) }}
+ {{ with .Err }}
+ {{ warnf "%s" . }}
+ {{ else }}
+ {{ printf "%v divided by %v equals %v" $x $y .Value }}
+ {{ end }}
+{{ end }}
+```
+
+The error thrown by the expression is logged to the console as a warning:
+
+```terminfo
+WARN error calling div: can't divide the value by 0
+```
+
+Now let's change the arguments to avoid dividing by zero:
+
+```go-html-template
+{{ $x := 42 }}
+{{ $y := 6 }}
+{{ with try (div $x $y) }}
+ {{ with .Err }}
+ {{ warnf "%s" . }}
+ {{ else }}
+ {{ printf "%v divided by %v equals %v" $x $y .Value }}
+ {{ end }}
+{{ end }}
+```
+
+Hugo renders the above to:
+
+```html
+42 divided by 6 equals 7
+```
+
+## Example
+
+Error handling is essential when using the [`resources.GetRemote`][] function to capture remote resources such as data or images. When calling this function, if the HTTP request fails, Hugo will fail the build.
+
+Instead of failing the build, we can catch the error and emit a warning:
+
+```go-html-template
+{{ $url := "https://broken-example.org/images/a.jpg" }}
+{{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ warnf "%s" . }}
+ {{ else with .Value }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ else }}
+ {{ warnf "Unable to get remote resource %q" $url }}
+ {{ end }}
+{{ end }}
+```
+
+In the above, note that the [context](g) within the last conditional block is the `TryValue` object returned by the `try` statement. At this point neither the `Err` nor `Value` methods returned anything, so the current context is not useful. Use the `$` to access the [template context][] if needed.
+
+> [!note]
+> Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil.
+
+[`resources.GetRemote`]: /functions/resources/getremote/
+[template context]: /templates/introduction/#template-context
+[`text/template`]: https://pkg.go.dev/text/template
diff --git a/documents/markdown/hugo-docs/en_functions_go-template_urlquery.md b/documents/markdown/hugo-docs/en_functions_go-template_urlquery.md
new file mode 100644
index 0000000..dc97f86
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_go-template_urlquery.md
@@ -0,0 +1,27 @@
+---
+title: urlquery
+description: Returns the escaped value of the textual representation of its arguments in a form suitable for embedding in a URL query.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: ['urlquery VALUE [VALUE...]']
+aliases: [/functions/urlquery]
+---
+
+This template code:
+
+```go-html-template
+{{ $u := urlquery "https://" "example.com" | safeURL }}
+<a href="https://example.org?url={{ $u }}">Link</a>
+```
+
+Is rendered to:
+
+```html
+<a href="https://example.org?url=https%3A%2F%2Fexample.com">Link</a>
+```
+
+{{% include "/_common/functions/go-template/text-template.md" %}}
diff --git a/documents/markdown/hugo-docs/en_functions_go-template_with.md b/documents/markdown/hugo-docs/en_functions_go-template_with.md
new file mode 100644
index 0000000..7354f16
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_go-template_with.md
@@ -0,0 +1,95 @@
+---
+title: with
+description: Binds context (the dot) to the expression and executes the block if expression is truthy.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType:
+ signatures: [with EXPR]
+aliases: [/functions/with]
+---
+
+{{% include "/_common/functions/truthy-falsy.md" %}}
+
+```go-html-template
+{{ $var := "foo" }}
+{{ with $var }}
+ {{ . }} → foo
+{{ end }}
+```
+
+Use with the [`else`] statement:
+
+```go-html-template
+{{ $var := "foo" }}
+{{ with $var }}
+ {{ . }} → foo
+{{ else }}
+ {{ print "var is falsy" }}
+{{ end }}
+```
+
+Use `else with` to check multiple conditions:
+
+```go-html-template
+{{ $v1 := 0 }}
+{{ $v2 := 42 }}
+{{ with $v1 }}
+ {{ . }}
+{{ else with $v2 }}
+ {{ . }} → 42
+{{ else }}
+ {{ print "v1 and v2 are falsy" }}
+{{ end }}
+```
+
+Initialize a variable, scoped to the current block:
+
+```go-html-template
+{{ with $var := 42 }}
+ {{ . }} → 42
+ {{ $var }} → 42
+{{ end }}
+{{ $var }} → undefined
+```
+
+## Understanding context
+
+See the [context] section in the introduction to templating.
+
+For example, at the top of a _page_ template, the [context](g) (the dot) is a `Page` object. Inside of the `with` block, the context is bound to the value passed to the `with` statement.
+
+With this contrived example:
+
+```go-html-template
+{{ with 42 }}
+ {{ .Title }}
+{{ end }}
+```
+
+Hugo will throw an error:
+
+ can't evaluate field Title in type int
+
+The error occurs because we are trying to use the `.Title` method on an integer instead of a `Page` object. Inside of the `with` block, if we want to render the page title, we need to get the context passed into the template.
+
+> [!note]
+> Use the `$` to get the context passed into the template.
+
+This template will render the page title as desired:
+
+```go-html-template
+{{ with 42 }}
+ {{ $.Title }}
+{{ end }}
+```
+
+> [!note]
+> Gaining a thorough understanding of context is critical for anyone writing template code.
+
+{{% include "/_common/functions/go-template/text-template.md" %}}
+
+[`else`]: /functions/go-template/else/
+[context]: /templates/introduction/#context
diff --git a/documents/markdown/hugo-docs/en_functions_hash_FNV32a.md b/documents/markdown/hugo-docs/en_functions_hash_FNV32a.md
new file mode 100644
index 0000000..fc2d673
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_hash_FNV32a.md
@@ -0,0 +1,16 @@
+---
+title: hash.FNV32a
+description: Returns the 32-bit FNV (Fowler-Noll-Vo) non-cryptographic hash of the given string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: int
+ signatures: [hash.FNV32a STRING]
+aliases: [/functions/crypto/fnv32a/,/functions/crypto.fnv32a]
+---
+
+```go-html-template
+{{ hash.FNV32a "Hello world" }} → 1498229191
+```
diff --git a/documents/markdown/hugo-docs/en_functions_hash_XxHash.md b/documents/markdown/hugo-docs/en_functions_hash_XxHash.md
new file mode 100644
index 0000000..6a92b2b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_hash_XxHash.md
@@ -0,0 +1,17 @@
+---
+title: hash.XxHash
+description: Returns the 64-bit xxHash non-cryptographic hash of the given string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [xxhash]
+ returnType: string
+ signatures: [hash.XxHash STRING]
+---
+
+```go-html-template
+{{ hash.XxHash "Hello world" }} → c500b0c912b376d8
+```
+
+[xxHash](https://xxhash.com/) is a very fast non-cryptographic hash algorithm. Hugo uses [this Go implementation](https://github.com/cespare/xxhash).
diff --git a/documents/markdown/hugo-docs/en_functions_hash__index.md b/documents/markdown/hugo-docs/en_functions_hash__index.md
new file mode 100644
index 0000000..956f7fb
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_hash__index.md
@@ -0,0 +1,7 @@
+---
+title: Hash functions
+linkTitle: hash
+description: Use these functions to create non-cryptographic hashes.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_hugo_BuildDate.md b/documents/markdown/hugo-docs/en_functions_hugo_BuildDate.md
new file mode 100644
index 0000000..a592283
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_hugo_BuildDate.md
@@ -0,0 +1,19 @@
+---
+title: hugo.BuildDate
+description: Returns the compile date of the Hugo binary.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [hugo.BuildDate]
+---
+
+The `hugo.BuildDate` function returns the compile date of the Hugo binary, formatted per [RFC 3339].
+
+[RFC 3339]: https://datatracker.ietf.org/doc/html/rfc3339
+
+```go-html-template
+{{ hugo.BuildDate }} → 2023-11-01T17:57:00Z
+```
diff --git a/documents/markdown/hugo-docs/en_functions_hugo_CommitHash.md b/documents/markdown/hugo-docs/en_functions_hugo_CommitHash.md
new file mode 100644
index 0000000..324e985
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_hugo_CommitHash.md
@@ -0,0 +1,15 @@
+---
+title: hugo.CommitHash
+description: Returns the Git commit hash of the Hugo binary.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [hugo.CommitHash]
+---
+
+```go-html-template
+{{ hugo.CommitHash }} → a4892a07b41b7b3f1f143140ee4ec0a9a5cf3970
+```
diff --git a/documents/markdown/hugo-docs/en_functions_hugo_Data.md b/documents/markdown/hugo-docs/en_functions_hugo_Data.md
new file mode 100644
index 0000000..b8f8dbd
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_hugo_Data.md
@@ -0,0 +1,105 @@
+---
+title: hugo.Data
+description: Returns a data structure composed from the files in the data directory.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: map
+ signatures: [hugo.Data]
+---
+
+{{< new-in 0.156.0 />}}
+
+Use the `hugo.Data` function to access data within the `data` directory, or within any directory [mounted] to the `data` directory. Supported data formats include JSON, TOML, YAML, and XML.
+
+> [!note]
+> Although Hugo can unmarshal CSV files with the [`transform.Unmarshal`] function, do not place CSV files in the `data` directory. You cannot access data within CSV files using this method.
+
+Consider this `data` directory:
+
+```text
+data/
+├── books/
+│ ├── fiction.yaml
+│ └── nonfiction.yaml
+├── films.json
+├── paintings.xml
+└── sculptures.toml
+```
+
+And these data files:
+
+```yaml {file="data/books/fiction.yaml"}
+- title: The Hunchback of Notre Dame
+ author: Victor Hugo
+ isbn: 978-0140443530
+- title: Les Misérables
+ author: Victor Hugo
+ isbn: 978-0451419439
+```
+
+```yaml {file="data/books/nonfiction.yaml"}
+- title: The Ancien Régime and the Revolution
+ author: Alexis de Tocqueville
+ isbn: 978-0141441641
+- title: Interpreting the French Revolution
+ author: François Furet
+ isbn: 978-0521280495
+```
+
+Access the data by [chaining](g) the [identifiers](g):
+
+```go-html-template
+{{ range $category, $books := hugo.Data.books }}
+ <p>{{ $category | title }}</p>
+ <ul>
+ {{ range $books }}
+ <li>{{ .title }} ({{ .isbn }})</li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+Hugo renders this to:
+
+```html
+<p>Fiction</p>
+<ul>
+ <li>The Hunchback of Notre Dame (978-0140443530)</li>
+ <li>Les Misérables (978-0451419439)</li>
+</ul>
+<p>Nonfiction</p>
+<ul>
+ <li>The Ancien Régime and the Revolution (978-0141441641)</li>
+ <li>Interpreting the French Revolution (978-0521280495)</li>
+</ul>
+```
+
+To limit the listing to fiction, and sort by title:
+
+```go-html-template
+<ul>
+ {{ range sort hugo.Data.books.fiction "title" }}
+ <li>{{ .title }} ({{ .author }})</li>
+ {{ end }}
+</ul>
+```
+
+To find a fiction book by ISBN:
+
+```go-html-template
+{{ range where hugo.Data.books.fiction "isbn" "978-0140443530" }}
+ <li>{{ .title }} ({{ .author }})</li>
+{{ end }}
+```
+
+In the template examples above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function. For example:
+
+```go-html-template
+{{ index hugo.Data.books "historical-fiction" }}
+```
+
+[`index`]: /functions/collections/indexfunction/
+[`transform.Unmarshal`]: /functions/transform/unmarshal/
+[mounted]: /configuration/module/#mounts
diff --git a/documents/markdown/hugo-docs/en_functions_hugo_Deps.md b/documents/markdown/hugo-docs/en_functions_hugo_Deps.md
new file mode 100644
index 0000000..9d8667e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_hugo_Deps.md
@@ -0,0 +1,66 @@
+---
+title: hugo.Deps
+description: Returns a slice of project dependencies, either Hugo Modules or local theme components.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: '[]hugo.Dependency'
+ signatures: [hugo.Deps]
+---
+
+The `hugo.Deps` function returns a slice of project dependencies, either Hugo Modules or local theme components. Each dependency contains:
+
+Owner
+: (`hugo.Dependency`) In the dependency tree, this is the first module that defines this module as a dependency (e.g., `github.com/gohugoio/hugo-mod-bootstrap-scss/v5`).
+
+Path
+: (`string`) The module path or the path below your `themes` directory (e.g., `github.com/gohugoio/hugo-mod-jslibs-dist/popperjs/v2`).
+
+Replace
+: (`hugo.Dependency`) Replaced by this dependency.
+
+Time
+: (`time.Time`) The time that the version was created (e.g., `2022-02-13 15:11:28 +0000 UTC`).
+
+Vendor
+: (`bool`) Reports whether the dependency is vendored.
+
+Version
+: (`string`) The module version (e.g., `v2.21100.20000`).
+
+An example table listing the dependencies:
+
+```go-html-template
+<h2>Dependencies</h2>
+<table class="table table-dark">
+ <thead>
+ <tr>
+ <th scope="col">#</th>
+ <th scope="col">Owner</th>
+ <th scope="col">Path</th>
+ <th scope="col">Version</th>
+ <th scope="col">Time</th>
+ <th scope="col">Vendor</th>
+ </tr>
+ </thead>
+ <tbody>
+ {{ range $index, $element := hugo.Deps }}
+ <tr>
+ <th scope="row">{{ add $index 1 }}</th>
+ <td>{{ with $element.Owner }}{{ .Path }}{{ end }}</td>
+ <td>
+ {{ $element.Path }}
+ {{ with $element.Replace }}
+ => {{ .Path }}
+ {{ end }}
+ </td>
+ <td>{{ $element.Version }}</td>
+ <td>{{ with $element.Time }}{{ . }}{{ end }}</td>
+ <td>{{ $element.Vendor }}</td>
+ </tr>
+ {{ end }}
+ </tbody>
+</table>
+```
diff --git a/documents/markdown/hugo-docs/en_functions_hugo_Environment.md b/documents/markdown/hugo-docs/en_functions_hugo_Environment.md
new file mode 100644
index 0000000..6f69dd3
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_hugo_Environment.md
@@ -0,0 +1,26 @@
+---
+title: hugo.Environment
+description: Returns the current running environment.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [hugo.Environment]
+---
+
+The `hugo.Environment` function returns the current running [environment](g) as defined through the `--environment` command line flag.
+
+```go-html-template
+{{ hugo.Environment }} → production
+```
+
+Command line examples:
+
+Command|Environment
+:--|:--
+`hugo build`|`production`
+`hugo build --environment staging`|`staging`
+`hugo server`|`development`
+`hugo server --environment staging`|`staging`
diff --git a/documents/markdown/hugo-docs/en_functions_hugo_Generator.md b/documents/markdown/hugo-docs/en_functions_hugo_Generator.md
new file mode 100644
index 0000000..b2238e4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_hugo_Generator.md
@@ -0,0 +1,15 @@
+---
+title: hugo.Generator
+description: Renders an HTML meta element identifying the software that generated the site.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: template.HTML
+ signatures: [hugo.Generator]
+---
+
+```go-html-template
+{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.158.0">
+```
diff --git a/documents/markdown/hugo-docs/en_functions_hugo_GoVersion.md b/documents/markdown/hugo-docs/en_functions_hugo_GoVersion.md
new file mode 100644
index 0000000..94e310d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_hugo_GoVersion.md
@@ -0,0 +1,15 @@
+---
+title: hugo.GoVersion
+description: Returns the Go version used to compile the Hugo binary
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [hugo.GoVersion]
+---
+
+```go-html-template
+{{ hugo.GoVersion }} → go1.21.1
+```
diff --git a/documents/markdown/hugo-docs/en_functions_hugo_IsDevelopment.md b/documents/markdown/hugo-docs/en_functions_hugo_IsDevelopment.md
new file mode 100644
index 0000000..2392c54
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_hugo_IsDevelopment.md
@@ -0,0 +1,15 @@
+---
+title: hugo.IsDevelopment
+description: Reports whether the current running environment is "development".
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [hugo.IsDevelopment]
+---
+
+```go-html-template
+{{ hugo.IsDevelopment }} → true/false
+```
diff --git a/documents/markdown/hugo-docs/en_functions_hugo_IsExtended.md b/documents/markdown/hugo-docs/en_functions_hugo_IsExtended.md
new file mode 100644
index 0000000..ab7e0f7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_hugo_IsExtended.md
@@ -0,0 +1,15 @@
+---
+title: hugo.IsExtended
+description: Reports whether the Hugo binary is either the extended or extended/deploy edition.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [hugo.IsExtended]
+---
+
+```go-html-template
+{{ hugo.IsExtended }} → true/false
+```
diff --git a/documents/markdown/hugo-docs/en_functions_hugo_IsMultihost.md b/documents/markdown/hugo-docs/en_functions_hugo_IsMultihost.md
new file mode 100644
index 0000000..d95b998
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_hugo_IsMultihost.md
@@ -0,0 +1,37 @@
+---
+title: hugo.IsMultihost
+description: Reports whether each configured language has a unique base URL.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [hugo.IsMultihost]
+---
+
+Project configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = true
+[languages]
+ [languages.de]
+ baseURL = 'https://de.example.org/'
+ label = 'Deutsch'
+ locale = 'de-DE'
+ title = 'Projekt Dokumentation'
+ weight = 1
+ [languages.en]
+ baseURL = 'https://en.example.org/'
+ label = 'English'
+ locale = 'en-US'
+ title = 'Project Documentation'
+ weight = 2
+{{< /code-toggle >}}
+
+Template:
+
+```go-html-template
+{{ hugo.IsMultihost }} → true
+```
diff --git a/documents/markdown/hugo-docs/en_functions_hugo_IsMultilingual.md b/documents/markdown/hugo-docs/en_functions_hugo_IsMultilingual.md
new file mode 100644
index 0000000..9fb9865
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_hugo_IsMultilingual.md
@@ -0,0 +1,35 @@
+---
+title: hugo.IsMultilingual
+description: Reports whether there are two or more configured languages.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [hugo.IsMultilingual]
+---
+
+Project configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = true
+[languages]
+ [languages.de]
+ label = 'Deutsch'
+ locale = 'de-DE'
+ title = 'Projekt Dokumentation'
+ weight = 1
+ [languages.en]
+ label = 'English'
+ locale = 'en-US'
+ title = 'Project Documentation'
+ weight = 2
+{{< /code-toggle >}}
+
+Template:
+
+```go-html-template
+{{ hugo.IsMultilingual }} → true
+```
diff --git a/documents/markdown/hugo-docs/en_functions_hugo_IsProduction.md b/documents/markdown/hugo-docs/en_functions_hugo_IsProduction.md
new file mode 100644
index 0000000..e5433c2
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_hugo_IsProduction.md
@@ -0,0 +1,15 @@
+---
+title: hugo.IsProduction
+description: Reports whether the current running environment is "production".
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [hugo.IsProduction]
+---
+
+```go-html-template
+{{ hugo.IsProduction }} → true/false
+```
diff --git a/documents/markdown/hugo-docs/en_functions_hugo_IsServer.md b/documents/markdown/hugo-docs/en_functions_hugo_IsServer.md
new file mode 100644
index 0000000..771d4eb
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_hugo_IsServer.md
@@ -0,0 +1,15 @@
+---
+title: hugo.IsServer
+description: Reports whether the built-in development server is running.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [hugo.IsServer]
+---
+
+```go-html-template
+{{ hugo.IsServer }} → true/false
+```
diff --git a/documents/markdown/hugo-docs/en_functions_hugo_Sites.md b/documents/markdown/hugo-docs/en_functions_hugo_Sites.md
new file mode 100644
index 0000000..a559826
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_hugo_Sites.md
@@ -0,0 +1,82 @@
+---
+title: hugo.Sites
+description: Returns a collection of all sites for all dimensions.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: page.Sites
+ signatures: [hugo.Sites]
+---
+
+{{< new-in 0.156.0 />}}
+
+{{% include "/_common/functions/hugo/sites-collection.md" %}}
+
+With this project configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = true
+defaultContentVersionInSubdir = true
+
+[languages.de]
+contentDir = 'content/de'
+direction = 'ltr'
+label = 'Deutsch'
+locale = 'de-DE'
+title = 'Projekt Dokumentation'
+weight = 1
+
+[languages.en]
+contentDir = 'content/en'
+direction = 'ltr'
+label = 'English'
+locale = 'en-US'
+title = 'Project Documentation'
+weight = 2
+
+[versions.'v1.0.0']
+[versions.'v2.0.0']
+[versions.'v3.0.0']
+{{< /code-toggle >}}
+
+This template:
+
+```go-html-template
+<ul>
+ {{ range hugo.Sites }}
+ <li><a href="{{ .Home.RelPermalink }}">{{ .Title }} {{ .Version.Name }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Produces a list of links to each home page:
+
+```html
+<ul>
+ <li><a href="/v3.0.0/de/">Projekt Dokumentation v3.0.0</a></li>
+ <li><a href="/v2.0.0/de/">Projekt Dokumentation v2.0.0</a></li>
+ <li><a href="/v1.0.0/de/">Projekt Dokumentation v1.0.0</a></li>
+ <li><a href="/v3.0.0/en/">Project Documentation v3.0.0</a></li>
+ <li><a href="/v2.0.0/en/">Project Documentation v2.0.0</a></li>
+ <li><a href="/v1.0.0/en/">Project Documentation v1.0.0</a></li>
+</ul>
+```
+
+To render a link to the home page of the [default site](g):
+
+```go-html-template
+{{ with hugo.Sites.Default }}
+ <a href="{{ .Home.RelPermalink }}">{{ .Title }}</a>
+{{ end }}
+```
+
+This is equivalent to:
+
+```go-html-template
+{{ with index hugo.Sites 0 }}
+ <a href="{{ .Home.RelPermalink }}">{{ .Title }}</a>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_functions_hugo_Store.md b/documents/markdown/hugo-docs/en_functions_hugo_Store.md
new file mode 100644
index 0000000..c0d5c59
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_hugo_Store.md
@@ -0,0 +1,117 @@
+---
+title: hugo.Store
+description: Returns a globally scoped "scratch pad" to store and manipulate data.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: maps.Scratch
+ signatures: [hugo.Store]
+---
+
+{{< new-in 0.139.0 />}}
+
+Use the `hugo.Store` function to create a globally scoped [scratch pad](g) to store and manipulate data. To create a scratch pad with a different [scope](g), refer to the [scope](#scope) section below.
+
+## Methods
+
+### Set
+
+Sets the value of the given key.
+
+```go-html-template
+{{ hugo.Store.Set "greeting" "Hello" }}
+```
+
+### Get
+
+Gets the value of the given key.
+
+```go-html-template
+{{ hugo.Store.Set "greeting" "Hello" }}
+{{ hugo.Store.Get "greeting" }} → Hello
+```
+
+### Add
+
+Adds the given value to the existing value(s) of the given key.
+
+For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list.
+
+```go-html-template
+{{ hugo.Store.Set "greeting" "Hello" }}
+{{ hugo.Store.Add "greeting" "Welcome" }}
+{{ hugo.Store.Get "greeting" }} → HelloWelcome
+```
+
+```go-html-template
+{{ hugo.Store.Set "total" 3 }}
+{{ hugo.Store.Add "total" 7 }}
+{{ hugo.Store.Get "total" }} → 10
+```
+
+```go-html-template
+{{ hugo.Store.Set "greetings" (slice "Hello") }}
+{{ hugo.Store.Add "greetings" (slice "Welcome" "Cheers") }}
+{{ hugo.Store.Get "greetings" }} → [Hello Welcome Cheers]
+```
+
+### SetInMap
+
+Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`.
+
+```go-html-template
+{{ hugo.Store.SetInMap "greetings" "english" "Hello" }}
+{{ hugo.Store.SetInMap "greetings" "french" "Bonjour" }}
+{{ hugo.Store.Get "greetings" }} → map[english:Hello french:Bonjour]
+```
+
+### DeleteInMap
+
+Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
+
+```go-html-template
+{{ hugo.Store.SetInMap "greetings" "english" "Hello" }}
+{{ hugo.Store.SetInMap "greetings" "french" "Bonjour" }}
+{{ hugo.Store.DeleteInMap "greetings" "english" }}
+{{ hugo.Store.Get "greetings" }} → map[french:Bonjour]
+ ```
+
+### GetSortedMapValues
+
+Returns an array of values from `key` sorted by `mapKey`.
+
+```go-html-template
+{{ hugo.Store.SetInMap "greetings" "english" "Hello" }}
+{{ hugo.Store.SetInMap "greetings" "french" "Bonjour" }}
+{{ hugo.Store.GetSortedMapValues "greetings" }} → [Hello Bonjour]
+```
+
+### Delete
+
+Removes the given key.
+
+```go-html-template
+{{ hugo.Store.Set "greeting" "Hello" }}
+{{ hugo.Store.Delete "greeting" }}
+```
+
+{{% include "_common/scratch-pad-scope.md" %}}
+
+## Determinate values
+
+The `Store` method is often used to set scratch pad values within a _shortcode_ template, a _partial_ template called by a _shortcode_ template, or by a _render hook_ template. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.
+
+If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop](g) variable:
+
+```go-html-template
+{{ $noop := .Content }}
+{{ hugo.Store.Get "mykey" }}
+```
+
+You can also trigger content rendering with the `ContentWithoutSummary`, `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount` methods. For example:
+
+```go-html-template
+{{ $noop := .WordCount }}
+{{ hugo.Store.Get "mykey" }}
+```
diff --git a/documents/markdown/hugo-docs/en_functions_hugo_Version.md b/documents/markdown/hugo-docs/en_functions_hugo_Version.md
new file mode 100644
index 0000000..8778e17
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_hugo_Version.md
@@ -0,0 +1,15 @@
+---
+title: hugo.Version
+description: Returns the current version of the Hugo binary.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: hugo.VersionString
+ signatures: [hugo.Version]
+---
+
+```go-html-template
+{{ hugo.Version }} → 0.158.0
+```
diff --git a/documents/markdown/hugo-docs/en_functions_hugo_WorkingDir.md b/documents/markdown/hugo-docs/en_functions_hugo_WorkingDir.md
new file mode 100644
index 0000000..e501025
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_hugo_WorkingDir.md
@@ -0,0 +1,15 @@
+---
+title: hugo.WorkingDir
+description: Returns the project working directory.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [hugo.WorkingDir]
+---
+
+```go-html-template
+{{ hugo.WorkingDir }} → /home/user/projects/my-hugo-site
+```
diff --git a/documents/markdown/hugo-docs/en_functions_hugo__index.md b/documents/markdown/hugo-docs/en_functions_hugo__index.md
new file mode 100644
index 0000000..b1c9216
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_hugo__index.md
@@ -0,0 +1,7 @@
+---
+title: Hugo functions
+linkTitle: hugo
+description: Use these functions to access information about the Hugo application and the current environment.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_images_AutoOrient.md b/documents/markdown/hugo-docs/en_functions_images_AutoOrient.md
new file mode 100644
index 0000000..d81dfbb
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_AutoOrient.md
@@ -0,0 +1,46 @@
+---
+title: images.AutoOrient
+description: Returns an image filter that rotates and flips an image as needed per its Exif orientation tag.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: [images.AutoOrient]
+---
+
+## Usage
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.AutoOrient }}
+```
+
+{{% include "/_common/functions/images/apply-image-filter.md" %}}
+
+> [!note]
+> When using with other filters, specify `images.AutoOrient` first.
+
+```go-html-template
+{{ $filters := slice
+ images.AutoOrient
+ (images.Process "resize 200x")
+}}
+{{ with resources.Get "images/original.jpg" }}
+ {{ with images.Filter $filters . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+## Example
+
+{{< img
+ src="images/examples/landscape-exif-orientation-5.jpg"
+ alt="Zion National Park"
+ filter="AutoOrient"
+ filterArgs=""
+ example=true
+>}}
diff --git a/documents/markdown/hugo-docs/en_functions_images_Brightness.md b/documents/markdown/hugo-docs/en_functions_images_Brightness.md
new file mode 100644
index 0000000..0ddfcba
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_Brightness.md
@@ -0,0 +1,33 @@
+---
+title: images.Brightness
+description: Returns an image filter that changes the brightness of an image.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: [images.Brightness PERCENTAGE]
+---
+
+The percentage must be in the range [-100, 100] where 0 has no effect. A value of `-100` produces a solid black image, and a value of `100` produces a solid white image.
+
+## Usage
+
+Create the image filter:
+
+```go-html-template
+{{ $filter := images.Brightness 12 }}
+```
+
+{{% include "/_common/functions/images/apply-image-filter.md" %}}
+
+## Example
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Brightness"
+ filterArgs="12"
+ example=true
+>}}
diff --git a/documents/markdown/hugo-docs/en_functions_images_ColorBalance.md b/documents/markdown/hugo-docs/en_functions_images_ColorBalance.md
new file mode 100644
index 0000000..be4a2bc
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_ColorBalance.md
@@ -0,0 +1,33 @@
+---
+title: images.ColorBalance
+description: Returns an image filter that changes the color balance of an image.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: [images.ColorBalance PCTRED PCTGREEN PCTBLUE]
+---
+
+The percentage for each channel (red, green, blue) must be in the range [-100, 500].
+
+## Usage
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.ColorBalance -10 10 50 }}
+```
+
+{{% include "/_common/functions/images/apply-image-filter.md" %}}
+
+## Example
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="ColorBalance"
+ filterArgs="-10,10,50"
+ example=true
+>}}
diff --git a/documents/markdown/hugo-docs/en_functions_images_Colorize.md b/documents/markdown/hugo-docs/en_functions_images_Colorize.md
new file mode 100644
index 0000000..6b8cd59
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_Colorize.md
@@ -0,0 +1,37 @@
+---
+title: images.Colorize
+description: Returns an image filter that produces a colorized version of an image.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: [images.Colorize HUE SATURATION PERCENTAGE]
+---
+
+The hue is the angle on the color wheel, typically in the range [0, 360].
+
+The saturation must be in the range [0, 100].
+
+The percentage specifies the strength of the effect, and must be in the range [0, 100].
+
+## Usage
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.Colorize 180 50 20 }}
+```
+
+{{% include "/_common/functions/images/apply-image-filter.md" %}}
+
+## Example
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Colorize"
+ filterArgs="180,50,20"
+ example=true
+>}}
diff --git a/documents/markdown/hugo-docs/en_functions_images_Config.md b/documents/markdown/hugo-docs/en_functions_images_Config.md
new file mode 100644
index 0000000..6900769
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_Config.md
@@ -0,0 +1,28 @@
+---
+title: images.Config
+description: Returns an image.Config structure from the image at the specified path, relative to the working directory.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: image.Config
+ signatures: [images.Config PATH]
+aliases: [/functions/imageconfig]
+---
+
+> [!note]
+> This is a legacy function, superseded by the [`Width`][] and [`Height`][] methods for [global resources](g), [page resources](g), and [remote resources](g). See the [image processing][] section for details.
+
+```go-html-template
+{{ $ic := images.Config "/static/images/a.jpg" }}
+
+{{ $ic.Width }} → 600 (int)
+{{ $ic.Height }} → 400 (int)
+```
+
+Supported image formats include AVIF, BMP, GIF, HEIC, HEIF, JPEG, PNG, TIFF, and WebP.
+
+[`Height`]: /methods/resource/height/
+[`Width`]: /methods/resource/width/
+[image processing]: /content-management/image-processing/
diff --git a/documents/markdown/hugo-docs/en_functions_images_Contrast.md b/documents/markdown/hugo-docs/en_functions_images_Contrast.md
new file mode 100644
index 0000000..f5d6074
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_Contrast.md
@@ -0,0 +1,33 @@
+---
+title: images.Contrast
+description: Returns an image filter that changes the contrast of an image.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: [images.Contrast PERCENTAGE]
+---
+
+The percentage must be in the range [-100, 100] where 0 has no effect. A value of `-100` produces a solid grey image, and a value of `100` produces an over-contrasted image.
+
+## Usage
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.Contrast -20 }}
+```
+
+{{% include "/_common/functions/images/apply-image-filter.md" %}}
+
+## Example
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Contrast"
+ filterArgs="-20"
+ example=true
+>}}
diff --git a/documents/markdown/hugo-docs/en_functions_images_Dither.md b/documents/markdown/hugo-docs/en_functions_images_Dither.md
new file mode 100644
index 0000000..0110a18
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_Dither.md
@@ -0,0 +1,154 @@
+---
+title: images.Dither
+description: Returns an image filter that dithers an image.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: ['images.Dither [OPTIONS]']
+---
+
+## Options
+
+colors
+: (`[]string`) A slice of two or more colors that make up the dithering palette, each expressed as an RGB or RGBA [hexadecimal] value, with or without a leading hash mark. The default values are opaque black (`000000ff`) and opaque white (`ffffffff`).
+
+[hexadecimal]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
+
+method
+: (`string`) The dithering method. See the [dithering methods](#dithering-methods) section below for a list of the available methods. Default is `FloydSteinberg`.
+
+serpentine
+: (`bool`) Applicable to error diffusion dithering methods, whether to apply the error diffusion matrix in a serpentine manner, meaning that it goes right-to-left every other line. This greatly reduces line-type artifacts. Default is `true`.
+
+strength
+: (`float`) The strength at which to apply the dithering matrix, typically a value in the range [0, 1]. A value of `1.0` applies the dithering matrix at 100% strength (no modification of the dither matrix). The `strength` is inversely proportional to contrast; reducing the strength increases the contrast. Setting `strength` to a value such as `0.8` can be useful to reduce noise in the dithered image. Default is `1.0`.
+
+## Usage
+
+Create the options map:
+
+```go-html-template
+{{ $opts := dict
+ "colors" (slice "222222" "808080" "dddddd")
+ "method" "ClusteredDot4x4"
+ "strength" 0.85
+}}
+```
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.Dither $opts }}
+```
+
+Or create the filter using the default settings:
+
+```go-html-template
+{{ $filter := images.Dither }}
+```
+
+{{% include "/_common/functions/images/apply-image-filter.md" %}}
+
+## Dithering methods
+
+See the [Go documentation] for descriptions of each of the dithering methods below.
+
+[Go documentation]: https://pkg.go.dev/github.com/makeworld-the-better-one/dither/v2#pkg-variables
+
+Error diffusion dithering methods:
+
+- Atkinson
+- Burkes
+- FalseFloydSteinberg
+- FloydSteinberg
+- JarvisJudiceNinke
+- Sierra
+- Sierra2
+- Sierra2_4A
+- Sierra3
+- SierraLite
+- Simple2D
+- StevenPigeon
+- Stucki
+- TwoRowSierra
+
+Ordered dithering methods:
+
+- ClusteredDot4x4
+- ClusteredDot6x6
+- ClusteredDot6x6_2
+- ClusteredDot6x6_3
+- ClusteredDot8x8
+- ClusteredDotDiagonal16x16
+- ClusteredDotDiagonal6x6
+- ClusteredDotDiagonal8x8
+- ClusteredDotDiagonal8x8_2
+- ClusteredDotDiagonal8x8_3
+- ClusteredDotHorizontalLine
+- ClusteredDotSpiral5x5
+- ClusteredDotVerticalLine
+- Horizontal3x5
+- Vertical5x3
+
+## Example
+
+This example uses the default dithering options.
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Dither"
+ filterArgs=""
+ example=true
+>}}
+
+## Recommendations
+
+Regardless of dithering method, do both of the following to obtain the best results:
+
+1. Scale the image _before_ dithering
+1. Output the image to a lossless format such as GIF or PNG
+
+The example below does both of these, and it sets the dithering palette to the three most dominant colors in the image.
+
+```go-html-template
+{{ with resources.Get "original.jpg" }}
+ {{ $opts := dict
+ "method" "ClusteredDotSpiral5x5"
+ "colors" (first 3 .Colors)
+ }}
+ {{ $filters := slice
+ (images.Process "resize 800x")
+ (images.Dither $opts)
+ (images.Process "png")
+ }}
+ {{ with . | images.Filter $filters }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+For best results, if the dithering palette is grayscale, convert the image to grayscale before dithering.
+
+```go-html-template
+{{ $opts := dict "colors" (slice "222" "808080" "ddd") }}
+{{ $filters := slice
+ (images.Process "resize 800x")
+ (images.Grayscale)
+ (images.Dither $opts)
+ (images.Process "png")
+}}
+{{ with images.Filter $filters . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+The example above:
+
+1. Resizes the image to be 800 px wide
+1. Converts the image to grayscale
+1. Dithers the image using the default (`FloydSteinberg`) dithering method with a grayscale palette
+1. Converts the image to the PNG format
diff --git a/documents/markdown/hugo-docs/en_functions_images_Filter.md b/documents/markdown/hugo-docs/en_functions_images_Filter.md
new file mode 100644
index 0000000..a320883
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_Filter.md
@@ -0,0 +1,75 @@
+---
+title: images.Filter
+description: Applies one or more image filters to the given image resource.
+categories: []
+keywords: [filter]
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.ImageResource
+ signatures: [images.Filter FILTER... RESOURCE]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
+The `images.Filter` function returns a new resource from a [processable image](g) after applying one or more [image filters](#image-filters).
+
+> [!note]
+> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
+
+## Usage
+
+Use the `images.Filter` function to apply effects such as blurring, sharpening, or grayscale conversion. You can pass a single filter or a slice of filters. When providing a slice, Hugo applies the filters from left to right.
+
+To apply a single filter:
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with images.Filter images.Grayscale . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+To apply two or more filters, executing from left to right:
+
+```go-html-template
+{{ $filters := slice
+ images.Grayscale
+ (images.GaussianBlur 8)
+}}
+{{ with resources.Get "images/original.jpg" }}
+ {{ with images.Filter $filters . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+You can also apply image filters using the [`Filter`][] method on a `Resource` object.
+
+## Example
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with images.Filter images.Grayscale . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Grayscale"
+ filterArgs=""
+ example=true
+>}}
+
+## Image filters
+
+Use any of these filters with the `images.Filter` function, or with the `Filter` method on a `Resource` object.
+
+{{% render-list-of-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude %}}
+
+[`Filter`]: /methods/resource/filter/
+[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
diff --git a/documents/markdown/hugo-docs/en_functions_images_Gamma.md b/documents/markdown/hugo-docs/en_functions_images_Gamma.md
new file mode 100644
index 0000000..d8cb076
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_Gamma.md
@@ -0,0 +1,33 @@
+---
+title: images.Gamma
+description: Returns an image filter that performs gamma correction on an image.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: [images.Gamma GAMMA]
+---
+
+The gamma value must be positive. A value greater than 1 lightens the image, while a value less than 1 darkens the image. The filter has no effect when the gamma value is 1.
+
+## Usage
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.Gamma 1.667 }}
+```
+
+{{% include "/_common/functions/images/apply-image-filter.md" %}}
+
+## Example
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Gamma"
+ filterArgs="1.667"
+ example=true
+>}}
diff --git a/documents/markdown/hugo-docs/en_functions_images_GaussianBlur.md b/documents/markdown/hugo-docs/en_functions_images_GaussianBlur.md
new file mode 100644
index 0000000..c5eb136
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_GaussianBlur.md
@@ -0,0 +1,33 @@
+---
+title: images.GaussianBlur
+description: Returns an image filter that applies a gaussian blur to an image.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: [images.GaussianBlur SIGMA]
+---
+
+The sigma value must be positive, and indicates how much the image will be blurred. The blur-affected radius is approximately 3 times the sigma value.
+
+## Usage
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.GaussianBlur 5 }}
+```
+
+{{% include "/_common/functions/images/apply-image-filter.md" %}}
+
+## Example
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="GaussianBlur"
+ filterArgs="5"
+ example=true
+>}}
diff --git a/documents/markdown/hugo-docs/en_functions_images_Grayscale.md b/documents/markdown/hugo-docs/en_functions_images_Grayscale.md
new file mode 100644
index 0000000..d3651b8
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_Grayscale.md
@@ -0,0 +1,31 @@
+---
+title: images.Grayscale
+description: Returns an image filter that produces a grayscale version of an image.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: [images.Grayscale]
+---
+
+## Usage
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.Grayscale }}
+```
+
+{{% include "/_common/functions/images/apply-image-filter.md" %}}
+
+## Example
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Grayscale"
+ filterArgs=""
+ example=true
+>}}
diff --git a/documents/markdown/hugo-docs/en_functions_images_Hue.md b/documents/markdown/hugo-docs/en_functions_images_Hue.md
new file mode 100644
index 0000000..f334eeb
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_Hue.md
@@ -0,0 +1,33 @@
+---
+title: images.Hue
+description: Returns an image filter that rotates the hue of an image.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: [images.Hue SHIFT]
+---
+
+The hue angle shift is typically in the range [-180, 180] where 0 has no effect.
+
+## Usage
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.Hue -15 }}
+```
+
+{{% include "/_common/functions/images/apply-image-filter.md" %}}
+
+## Example
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Hue"
+ filterArgs="-15"
+ example=true
+>}}
diff --git a/documents/markdown/hugo-docs/en_functions_images_Invert.md b/documents/markdown/hugo-docs/en_functions_images_Invert.md
new file mode 100644
index 0000000..0f9f9a9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_Invert.md
@@ -0,0 +1,31 @@
+---
+title: images.Invert
+description: Returns an image filter that negates the colors of an image.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: [images.Invert]
+---
+
+## Usage
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.Invert }}
+```
+
+{{% include "/_common/functions/images/apply-image-filter.md" %}}
+
+## Example
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Invert"
+ filterArgs=""
+ example=true
+>}}
diff --git a/documents/markdown/hugo-docs/en_functions_images_Mask.md b/documents/markdown/hugo-docs/en_functions_images_Mask.md
new file mode 100644
index 0000000..ecc489d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_Mask.md
@@ -0,0 +1,75 @@
+---
+title: images.Mask
+description: Returns an image filter that applies a mask to the source image.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: [images.Mask RESOURCE]
+---
+
+{{< new-in 0.141.0 />}}
+
+The `images.Mask` filter applies a mask to an image. Black pixels in the mask make the corresponding areas of the base image transparent, while white pixels keep them opaque. Color images are converted to grayscale for masking purposes. The mask is automatically resized to match the dimensions of the base image.
+
+> [!note]
+> Of the formats supported by Hugo's imaging pipeline, only PNG and WebP have an alpha channel to support transparency. If your source image has a different format and you require transparent masked areas, convert it to either PNG or WebP as shown in the example below.
+
+When applying a mask to a non-transparent image format such as JPEG, the masked areas will be filled with the color specified by the `bgColor` parameter in your [project configuration]. You can override that color with a `Process` image filter:
+
+```go-html-template
+{{ $filter := images.Process "#00ff00" }}
+```
+
+## Usage
+
+Create a slice of filters, one for WebP conversion and the other for mask application:
+
+```go-html-template
+{{ $filter1 := images.Process "webp" }}
+{{ $filter2 := images.Mask (resources.Get "images/mask.png") }}
+{{ $filters := slice $filter1 $filter2 }}
+```
+
+Apply the filters using the [`images.Filter`] function:
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with . | images.Filter $filters }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+You can also apply the filter using the [`Filter`] method on a 'Resource' object:
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Filter $filters }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+## Example
+
+Mask
+
+{{< img
+ src="images/examples/mask.png"
+ example=false
+>}}
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="mask"
+ filterArgs="images/examples/mask.png"
+ example=true
+>}}
+
+[`Filter`]: /methods/resource/filter/
+[`images.Filter`]: /functions/images/filter/
+[project configuration]: /configuration/imaging/
diff --git a/documents/markdown/hugo-docs/en_functions_images_Opacity.md b/documents/markdown/hugo-docs/en_functions_images_Opacity.md
new file mode 100644
index 0000000..2105aea
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_Opacity.md
@@ -0,0 +1,47 @@
+---
+title: images.Opacity
+description: Returns an image filter that changes the opacity of an image.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: [images.Opacity OPACITY]
+---
+
+The opacity value must be in the range [0, 1]. A value of `0` produces a transparent image, and a value of `1` produces an opaque image (no transparency).
+
+## Usage
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.Opacity 0.65 }}
+```
+
+{{% include "/_common/functions/images/apply-image-filter.md" %}}
+
+The `images.Opacity` filter is most useful for target formats such as PNG and WebP that support transparency. If the source image does not support transparency, combine this filter with the `images.Process` filter:
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ $filters := slice
+ (images.Opacity 0.65)
+ (images.Process "png")
+ }}
+ {{ with . | images.Filter $filters }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+## Example
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Opacity"
+ filterArgs="0.65"
+ example=true
+>}}
diff --git a/documents/markdown/hugo-docs/en_functions_images_Overlay.md b/documents/markdown/hugo-docs/en_functions_images_Overlay.md
new file mode 100644
index 0000000..8e5eec3
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_Overlay.md
@@ -0,0 +1,45 @@
+---
+title: images.Overlay
+description: Returns an image filter that overlays the source image at the given coordinates, relative to the upper left corner.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: [images.Overlay RESOURCE X Y]
+---
+
+## Usage
+
+Capture the overlay image as a resource:
+
+```go-html-template
+{{ $overlay := "" }}
+{{ $path := "images/logo.png" }}
+{{ with resources.Get $path }}
+ {{ $overlay = . }}
+{{ else }}
+ {{ errorf "Unable to get resource %q" $path }}
+{{ end }}
+```
+
+The overlay image can be a [global resource](g), a [page resource](g), or a [remote resource](g).
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.Overlay $overlay 20 20 }}
+```
+
+{{% include "/_common/functions/images/apply-image-filter.md" %}}
+
+## Example
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Overlay"
+ filterArgs="images/logos/logo-64x64.png,20,20"
+ example=true
+>}}
diff --git a/documents/markdown/hugo-docs/en_functions_images_Padding.md b/documents/markdown/hugo-docs/en_functions_images_Padding.md
new file mode 100644
index 0000000..8e6d05c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_Padding.md
@@ -0,0 +1,70 @@
+---
+title: images.Padding
+description: Returns an image filter that resizes the image canvas without resizing the image.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: ['images.Padding V1 [V2] [V3] [V4] [COLOR]']
+---
+
+The last argument is the canvas color, expressed as an RGB or RGBA [hexadecimal color]. The default value is `ffffffff` (opaque white). The preceding arguments are the padding values, in pixels, using the CSS [shorthand property] syntax. Negative padding values will crop the image.
+
+[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
+[shorthand property]: https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box
+
+## Usage
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.Padding 20 40 "#976941" }}
+```
+
+{{% include "/_common/functions/images/apply-image-filter.md" %}}
+
+Combine with the [`Colors`] method to create a border with one of the image's most dominant colors:
+
+[`Colors`]: /methods/resource/colors/
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ $filter := images.Padding 20 40 (index .Colors 2) }}
+ {{ with . | images.Filter $filter }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+## Example
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Padding"
+ filterArgs="20,40,20,40,#976941"
+ example=true
+>}}
+
+## Other recipes
+
+This example resizes an image to 300px wide, converts it to the WebP format, adds 20px vertical padding and 50px horizontal padding, then sets the canvas color to dark green with 33% opacity.
+
+Conversion to WebP is required to support transparency. PNG and WebP images have an alpha channel; JPEG and GIF do not.
+
+```go-html-template
+{{ $img := resources.Get "images/a.jpg" }}
+{{ $filters := slice
+ (images.Process "resize 300x webp")
+ (images.Padding 20 50 "#0705")
+}}
+{{ $img = $img.Filter $filters }}
+```
+
+To add a 2px gray border to an image:
+
+```go-html-template
+{{ $img = $img.Filter (images.Padding 2 "#777") }}
+```
diff --git a/documents/markdown/hugo-docs/en_functions_images_Pixelate.md b/documents/markdown/hugo-docs/en_functions_images_Pixelate.md
new file mode 100644
index 0000000..954950c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_Pixelate.md
@@ -0,0 +1,31 @@
+---
+title: images.Pixelate
+description: Returns an image filter that applies a pixelation effect to an image.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: [images.Pixelate SIZE]
+---
+
+## Usage
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.Pixelate 4 }}
+```
+
+{{% include "/_common/functions/images/apply-image-filter.md" %}}
+
+## Example
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Pixelate"
+ filterArgs="4"
+ example=true
+>}}
diff --git a/documents/markdown/hugo-docs/en_functions_images_Process.md b/documents/markdown/hugo-docs/en_functions_images_Process.md
new file mode 100644
index 0000000..2064b24
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_Process.md
@@ -0,0 +1,50 @@
+---
+title: images.Process
+description: Returns an image filter that processes an image according to the given processing specification.
+categories: []
+keywords: [process]
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: [images.Process SPECIFICATION]
+---
+
+Returns an image filter that processes an image according to the given [processing specification][]. This versatile filter supports the full range of image transformations, including resizing, cropping, rotation, and format conversion, all within a single specification string. Use this as an argument to the [`Filter`][] method or the [`images.Filter`][] function.
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ $filter := images.Process "crop 200x200 TopRight webp q50" }}
+ {{ with .Filter $filter }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+In the example above, `"crop 200x200 TopRight webp q50"` is the processing specification.
+
+{{% include "/_common/methods/resource/processing-spec.md" %}}
+
+## Usage
+
+Create a filter:
+
+```go-html-template
+{{ $filter := images.Process "crop 200x200 TopRight webp q50" }}
+```
+
+{{% include "/_common/functions/images/apply-image-filter.md" %}}
+
+## Example
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Process"
+ filterArgs="crop 200x200 TopRight webp q50"
+ example=true
+>}}
+
+[`Filter`]: /methods/resource/filter/
+[`images.Filter`]: /functions/images/filter
+[processing specification]: #processing-specification
diff --git a/documents/markdown/hugo-docs/en_functions_images_QR.md b/documents/markdown/hugo-docs/en_functions_images_QR.md
new file mode 100644
index 0000000..bf13e16
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_QR.md
@@ -0,0 +1,138 @@
+---
+title: images.QR
+description: Encodes the given text into a QR code using the specified options, returning an image resource.
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.ImageResource
+ signatures: ['images.QR TEXT [OPTIONS]']
+---
+
+{{< new-in 0.141.0 />}}
+
+The `images.QR` function encodes the given text into a [QR code] using the specified options, returning an image resource. The size of the generated image depends on three factors:
+
+- Data length: Longer text necessitates a larger image to accommodate the increased information density.
+- Error correction level: Higher error correction levels enhance the QR code's resistance to damage, but this typically results in a slightly larger image size to maintain readability.
+- Pixels per module: The number of image pixels assigned to each individual module (the smallest unit of the QR code) directly impacts the overall image size. A higher pixel count per module leads to a larger, higher-resolution image.
+
+Although the default option values are sufficient for most applications, you should test the rendered QR code both on-screen and in print.
+
+## Options
+
+level
+: (`string`) The error correction level to use when encoding the text, one of `low`, `medium`, `quartile`, or `high`. Default is `medium`.
+
+ Error correction level|Redundancy
+ :--|:--|:--
+ low|20%
+ medium|38%
+ quartile|55%
+ high|65%
+
+scale
+: (`int`) The number of image pixels per QR code module. Must be greater than or equal to `2`. Default is `4`.
+
+targetDir
+: (`string`) The subdirectory within the [`publishDir`] where Hugo will place the generated image. Use Unix-style slashes (`/`) to separarate path segments. If empty or not provided, the image is placed directly in the `publishDir` root. Hugo automatically creates the necessary subdirectories if they don't exist.
+
+## Examples
+
+To create a QR code using the default values for `level` and `scale`:
+
+```go-html-template
+{{ $text := "https://gohugo.io" }}
+{{ with images.QR $text }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+{{< qr text="https://gohugo.io" class="qrcode" targetDir="images/qr" />}}
+
+Specify `level`, `scale`, and `targetDir` as needed to achieve the desired result:
+
+```go-html-template
+{{ $text := "https://gohugo.io" }}
+{{ $opts := dict
+ "level" "high"
+ "scale" 3
+ "targetDir" "images/qr"
+}}
+{{ with images.QR $text $opts }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+{{< qr text="https://gohugo.io" level="high" scale=3 targetDir="codes" class="qrcode" targetDir="images/qr" />}}
+
+To include a QR code that points to the `Permalink` of the current page:
+
+```go-html-template {file="layouts/page.html"}
+{{ with images.QR .Permalink }}
+ <img
+ src="{{ .RelPermalink }}"
+ width="{{ .Width }}"
+ height="{{ .Height }}"
+ alt="QR code linking to {{ $.Permalink }}"
+ class="qr-code"
+ loading="lazy"
+ >
+{{ end }}
+```
+
+Then hide the QR code with CSS unless printing the page:
+
+```css
+/* Hide QR code by default */
+.qr-code {
+ display: none;
+}
+
+/* Show QR code when printing */
+@media print {
+ .qr-code {
+ display: block;
+ }
+}
+```
+
+## Scale
+
+As you decrease the size of a QR code, the maximum distance at which it can be reliably scanned by a device also decreases.
+
+In the example above, we set the `scale` to `2`, resulting in a QR code where each module consists of 2x2 pixels. While this might be sufficient for on-screen display, it's likely to be problematic when printed at 600 dpi.
+
+\[ \frac{2\:px}{module} \times \frac{1\:inch}{600\:px} \times \frac{25.4\:mm}{1\:inch} = \frac{0.085\:mm}{module} \]
+
+This module size is half of the commonly recommended minimum of 0.170 mm.\
+If the QR code will be printed, use the default `scale` value of `4` pixels per module.
+
+Avoid using Hugo's image processing methods to resize QR codes. Resizing can introduce blurring due to anti-aliasing when a QR code module occupies a fractional number of pixels.
+
+> [!note]
+> Always test the rendered QR code both on-screen and in print.
+
+## Shortcode
+
+Call the `qr` shortcode to insert a QR code into your content.
+
+Use the self-closing syntax to pass the text as an argument:
+
+```text
+{{</* qr text="https://gohugo.io" /*/>}}
+```
+
+Or insert the text between the opening and closing tags:
+
+```text
+{{</* qr */>}}
+https://gohugo.io
+{{</* /qr */>}}
+```
+
+The `qr` shortcode accepts several arguments including `level` and `scale`. See the [related documentation] for details.
+
+[`publishDir`]: /configuration/all/#publishdir
+[QR code]: https://en.wikipedia.org/wiki/QR_code
+[related documentation]: /shortcodes/qr/
diff --git a/documents/markdown/hugo-docs/en_functions_images_Saturation.md b/documents/markdown/hugo-docs/en_functions_images_Saturation.md
new file mode 100644
index 0000000..d1dd48b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_Saturation.md
@@ -0,0 +1,33 @@
+---
+title: images.Saturation
+description: Returns an image filter that changes the saturation of an image.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: [images.Saturation PERCENTAGE]
+---
+
+The percentage must be in the range [-100, 500] where 0 has no effect.
+
+## Usage
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.Saturation 65 }}
+```
+
+{{% include "/_common/functions/images/apply-image-filter.md" %}}
+
+## Example
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Saturation"
+ filterArgs="65"
+ example=true
+>}}
diff --git a/documents/markdown/hugo-docs/en_functions_images_Sepia.md b/documents/markdown/hugo-docs/en_functions_images_Sepia.md
new file mode 100644
index 0000000..ae43045
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_Sepia.md
@@ -0,0 +1,33 @@
+---
+title: images.Sepia
+description: Returns an image filter that produces a sepia-toned version of an image.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: [images.Sepia PERCENTAGE]
+---
+
+The percentage must be in the range [0, 100] where 0 has no effect.
+
+## Usage
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.Sepia 75 }}
+```
+
+{{% include "/_common/functions/images/apply-image-filter.md" %}}
+
+## Example
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Sepia"
+ filterArgs="75"
+ example=true
+>}}
diff --git a/documents/markdown/hugo-docs/en_functions_images_Sigmoid.md b/documents/markdown/hugo-docs/en_functions_images_Sigmoid.md
new file mode 100644
index 0000000..9bfcaf9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_Sigmoid.md
@@ -0,0 +1,37 @@
+---
+title: images.Sigmoid
+description: Returns an image filter that changes the contrast of an image using a sigmoidal function.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: [images.Sigmoid MIDPOINT FACTOR]
+---
+
+This is a non-linear contrast change useful for photo adjustments; it preserves highlight and shadow detail.
+
+The midpoint is the midpoint of contrast. It must be in the range [0, 1], typically 0.5.
+
+The factor indicates how much to increase or decrease the contrast, typically in the range [-10, 10] where 0 has no effect. A positive value increases contrast, while a negative value decrease contrast.
+
+## Usage
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.Sigmoid 0.6 -4 }}
+```
+
+{{% include "/_common/functions/images/apply-image-filter.md" %}}
+
+## Example
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Sigmoid"
+ filterArgs="0.6,-4"
+ example=true
+>}}
diff --git a/documents/markdown/hugo-docs/en_functions_images_Text.md b/documents/markdown/hugo-docs/en_functions_images_Text.md
new file mode 100644
index 0000000..c6a0e5b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_Text.md
@@ -0,0 +1,123 @@
+---
+title: images.Text
+description: Returns an image filter that adds text to an image.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: ['images.Text TEXT [OPTIONS]']
+---
+
+## Options
+
+Although none of the options are required, at a minimum you will want to set the `size` to be some reasonable percentage of the image height.
+
+alignx
+: {{< new-in 0.141.0 />}}
+: (`string`) The horizontal alignment of the text relative to the horizontal offset, one of `left`, `center`, or `right`. Default is `left`.
+
+aligny
+: {{< new-in 0.147.0 />}}
+: (`string`) The vertical alignment of the text relative to the vertical offset, one of `top`, `center`, or `bottom`. Default is `top`.
+
+color
+: (`string`) The font color, either a 3-digit or 6-digit hexadecimal color code. Default is `#ffffff` (white).
+
+font
+: (`resource.Resource`) The font can be a [global resource](g), a [page resource](g), or a [remote resource](g). Default is [Go Regular], a proportional sans-serif TrueType font.
+
+linespacing
+: (`int`) The number of pixels between each line. For a line height of 1.4, set the `linespacing` to 0.4 multiplied by the `size`. Default is `2`.
+
+size
+: (`int`) The font size in pixels. Default is `20`.
+
+x
+: (`int`) The horizontal offset, in pixels, relative to the left of the image. Default is `10`.
+
+y
+: (`int`) The vertical offset, in pixels, relative to the top of the image. Default is `10`.
+
+[Go Regular]: https://go.dev/blog/go-fonts#sans-serif
+
+## Usage
+
+Set the text and paths:
+
+```go-html-template
+{{ $text := "Zion National Park" }}
+{{ $fontPath := "https://github.com/google/fonts/raw/main/ofl/lato/Lato-Regular.ttf" }}
+{{ $imagePath := "images/original.jpg" }}
+```
+
+Capture the font as a resource:
+
+```go-html-template
+{{ $font := "" }}
+{{ with try (resources.GetRemote $fontPath) }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else with .Value }}
+ {{ $font = . }}
+ {{ else }}
+ {{ errorf "Unable to get resource %s" $fontPath }}
+ {{ end }}
+{{ end }}
+```
+
+Create the filter, centering the text horizontally and vertically:
+
+```go-html-template
+{{ $r := "" }}
+{{ $filter := "" }}
+{{ with $r = resources.Get $imagePath }}
+ {{ $opts := dict
+ "alignx" "center"
+ "aligny" "center"
+ "color" "#fbfaf5"
+ "font" $font
+ "linespacing" 8
+ "size" 60
+ "x" (mul .Width 0.5 | int)
+ "y" (mul .Height 0.5 | int)
+ }}
+ {{ $filter = images.Text $text $opts }}
+{{ else }}
+ {{ errorf "Unable to get resource %s" $imagePath }}
+{{ end }}
+```
+
+Apply the filter using the [`images.Filter`] function:
+
+```go-html-template
+{{ with $r }}
+ {{ with . | images.Filter $filter }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+You can also apply the filter using the [`Filter`] method on a `Resource` object:
+
+```go-html-template
+{{ with $r }}
+ {{ with .Filter $filter }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+[`images.Filter`]: /functions/images/filter/
+[`Filter`]: /methods/resource/filter/
+
+## Example
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Text"
+ filterArgs="Zion National Park,25,190,40,1.2,#fbfaf5"
+ example=true
+>}}
diff --git a/documents/markdown/hugo-docs/en_functions_images_UnsharpMask.md b/documents/markdown/hugo-docs/en_functions_images_UnsharpMask.md
new file mode 100644
index 0000000..9c06eb5
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images_UnsharpMask.md
@@ -0,0 +1,37 @@
+---
+title: images.UnsharpMask
+description: Returns an image filter that sharpens an image.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: [images.UnsharpMask SIGMA AMOUNT THRESHOLD]
+---
+
+The sigma argument is used in a gaussian function and affects the radius of effect. Sigma must be positive. The sharpen radius is approximately 3 times the sigma value.
+
+The amount argument controls how much darker and how much lighter the edge borders become. Typically between 0.5 and 1.5.
+
+The threshold argument controls the minimum brightness change that will be sharpened. Typically between 0 and 0.05.
+
+## Usage
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.UnsharpMask 10 0.4 0.03 }}
+```
+
+{{% include "/_common/functions/images/apply-image-filter.md" %}}
+
+## Example
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="UnsharpMask"
+ filterArgs="10,0.4,0.03"
+ example=true
+>}}
diff --git a/documents/markdown/hugo-docs/en_functions_images__index.md b/documents/markdown/hugo-docs/en_functions_images__index.md
new file mode 100644
index 0000000..f92e16e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_images__index.md
@@ -0,0 +1,7 @@
+---
+title: Image functions
+linkTitle: images
+description: Use these functions to create an image filter, apply an image filter to an image, and to retrieve image information.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_inflect_Humanize.md b/documents/markdown/hugo-docs/en_functions_inflect_Humanize.md
new file mode 100644
index 0000000..d3d7852
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_inflect_Humanize.md
@@ -0,0 +1,24 @@
+---
+title: inflect.Humanize
+description: Returns the humanized version of the input with the first letter capitalized.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [humanize]
+ returnType: string
+ signatures: [inflect.Humanize INPUT]
+aliases: [/functions/humanize]
+---
+
+```go-html-template
+{{ humanize "my-first-post" }} → My first post
+{{ humanize "myCamelPost" }} → My camel post
+```
+
+If the input is an integer or a string representation of an integer, humanize returns the number with the proper ordinal appended.
+
+```go-html-template
+{{ humanize "52" }} → 52nd
+{{ humanize 103 }} → 103rd
+```
diff --git a/documents/markdown/hugo-docs/en_functions_inflect_Pluralize.md b/documents/markdown/hugo-docs/en_functions_inflect_Pluralize.md
new file mode 100644
index 0000000..f168770
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_inflect_Pluralize.md
@@ -0,0 +1,16 @@
+---
+title: inflect.Pluralize
+description: Pluralizes the given word according to a set of common English pluralization rules.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [pluralize]
+ returnType: string
+ signatures: [inflect.Pluralize INPUT]
+aliases: [/functions/pluralize]
+---
+
+```go-html-template
+{{ "cat" | pluralize }} → cats
+```
diff --git a/documents/markdown/hugo-docs/en_functions_inflect_Singularize.md b/documents/markdown/hugo-docs/en_functions_inflect_Singularize.md
new file mode 100644
index 0000000..41e05b7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_inflect_Singularize.md
@@ -0,0 +1,16 @@
+---
+title: inflect.Singularize
+description: Singularizes the given word according to a set of common English singularization rules.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [singularize]
+ returnType: string
+ signatures: [inflect.Singularize INPUT]
+aliases: [/functions/singularize]
+---
+
+```go-html-template
+{{ "cats" | singularize }} → cat
+```
diff --git a/documents/markdown/hugo-docs/en_functions_inflect__index.md b/documents/markdown/hugo-docs/en_functions_inflect__index.md
new file mode 100644
index 0000000..2afe4fe
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_inflect__index.md
@@ -0,0 +1,7 @@
+---
+title: Inflect functions
+linkTitle: inflect
+description: These functions provide word inflection features such as singularization and pluralization of English nouns.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_js_Babel.md b/documents/markdown/hugo-docs/en_functions_js_Babel.md
new file mode 100644
index 0000000..c4493f9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_js_Babel.md
@@ -0,0 +1,97 @@
+---
+title: js.Babel
+description: Compile the given JavaScript resource with Babel.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [babel]
+ returnType: resource.Resource
+ signatures: ['js.Babel [OPTIONS] RESOURCE']
+aliases: [/functions/resources/babel/]
+---
+
+```go-html-template
+{{ with resources.Get "js/main.js" }}
+ {{ $opts := dict
+ "minified" hugo.IsProduction
+ "noComments" hugo.IsProduction
+ "sourceMap" (cond hugo.IsProduction "none" "external")
+ }}
+ {{ with . | js.Babel $opts }}
+ {{ if hugo.IsProduction }}
+ {{ with . | fingerprint }}
+ <script src="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"></script>
+ {{ end }}
+ {{ else }}
+ <script src="{{ .RelPermalink }}"></script>
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+## Setup
+
+Step 1
+: Install [Node.js](https://nodejs.org/en/download)
+
+Step 2
+: Install the required Node packages in the root of your project.
+
+ ```sh
+ npm install --save-dev @babel/core @babel/cli
+ ```
+
+Step 3
+: Add the babel executable to Hugo's `security.exec.allow` list in your project configuration:
+
+ {{< code-toggle file=hugo >}}
+ [security.exec]
+ allow = ['^(dart-)?sass(-embedded)?$', '^go$', '^npx$', '^postcss$', '^babel$']
+ {{< /code-toggle >}}
+
+## Configuration
+
+We add the main project's `node_modules` to `NODE_PATH` when running Babel and similar tools. There are some known [issues](https://github.com/babel/babel/issues/5618) with Babel in this area, so if you have a `babel.config.js` living in a Hugo Module (and not in the project itself), we recommend using `require` to load the presets/plugins, e.g.:
+
+```js
+module.exports = {
+ presets: [
+ [
+ require("@babel/preset-env"),
+ {
+ useBuiltIns: "entry",
+ corejs: 3,
+ },
+ ],
+ ],
+};
+```
+
+## Options
+
+compact
+: (`bool`) Whether to remove optional newlines and whitespace. Enabled when `minified` is `true`. Default is `false`
+
+config
+: (`string`) Path to the Babel configuration file. Hugo will, by default, look for a `babel.config.js` file in the root of your project. See [details](https://babeljs.io/docs/en/configuration).
+
+minified
+: (`bool`) Whether to minify the compiled code. Enables the `compact` option. Default is `false`.
+
+noBabelrc
+: (`string`) Whether to ignore `.babelrc` and `.babelignore` files. Default is `false`.
+
+noComments
+: (`bool`) Whether to remove comments. Default is `false`.
+
+sourceMap
+: (`string`) Whether to generate source maps, one of `external`, `inline`, or `none`. Default is `none`.
+
+verbose
+: (`bool`) Whether to enable verbose logging. Default is `false`
+
+<!--
+In the above, technically "none" is not one of the enumerated sourceMap
+values but it has the same effect and is easier to document than an empty string.
+-->
diff --git a/documents/markdown/hugo-docs/en_functions_js_Batch.md b/documents/markdown/hugo-docs/en_functions_js_Batch.md
new file mode 100644
index 0000000..b4b85cd
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_js_Batch.md
@@ -0,0 +1,312 @@
+---
+title: js.Batch
+description: Build JavaScript bundle groups with global code splitting and flexible hooks/runners setup.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: js.Batcher
+ signatures: ['js.Batch [ID]']
+---
+
+> [!note]
+> The `js.Batch` function is backed by the [`evanw/esbuild`][] package, providing a mature, high-performance foundation for bundling, transformation, and minification.
+
+> [!note]
+> For a runnable example of this feature, see [this test and demo repo](https://github.com/bep/hugojsbatchdemo/).
+
+The Batch `ID` is used to create the base directory for this batch. Forward slashes are allowed. `js.Batch` returns an object with an API with this structure:
+
+- [Group]
+ - [Script]
+ - [SetOptions]
+ - [Instance]
+ - [SetOptions]
+ - [Runner]
+ - [SetOptions]
+ - [Config]
+ - [SetOptions]
+
+## Group
+
+The `Group` method take an `ID` (`string`) as argument. No slashes. It returns an object with these methods:
+
+### Script
+
+The `Script` method takes an `ID` (`string`) as argument. No slashes. It returns an [OptionsSetter] that can be used to set [script options] for this script.
+
+```go-html-template
+{{ with js.Batch "js/mybatch" }}
+ {{ with .Group "mygroup" }}
+ {{ with .Script "myscript" }}
+ {{ .SetOptions (dict "resource" (resources.Get "myscript.js")) }}
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+`SetOptions` takes a [script options] map. Note that if you want the script to be handled by a [runner], you need to set the `export` option to match what you want to pass on to the runner (default is `*`).
+
+### Instance
+
+The `Instance` method takes two `string` arguments `SCRIPT_ID` and `INSTANCE_ID`. No slashes. It returns an [OptionsSetter] that can be used to set [params options] for this instance.
+
+```go-html-template
+{{ with js.Batch "js/mybatch" }}
+ {{ with .Group "mygroup" }}
+ {{ with .Instance "myscript" "myinstance" }}
+ {{ .SetOptions (dict "params" (dict "param1" "value1")) }}
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+`SetOptions` takes a [params options] map. The instance options will be passed to any [runner] script in the same group, as JSON.
+
+### Runner
+
+The `Runner` method takes an `ID` (`string`) as argument. No slashes. It returns an [OptionsSetter] that can be used to set [script options] for this runner.
+
+```go-html-template
+{{ with js.Batch "js/mybatch" }}
+ {{ with .Group "mygroup" }}
+ {{ with .Runner "myrunner" }}
+ {{ .SetOptions (dict "resource" (resources.Get "myrunner.js")) }}
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+`SetOptions` takes a [script options] map.
+
+The runner will receive a data structure with all instances for that group with a live binding of the [JavaScript import] of the defined `export`.
+
+The runner script's export must be a function that takes one argument, the group data structure. An example of a group data structure as JSON is:
+
+```json
+{
+ "id": "leaflet",
+ "scripts": [
+ {
+ "id": "mapjsx",
+ "binding": JAVASCRIPT_BINDING,
+ "instances": [
+ {
+ "id": "0",
+ "params": {
+ "c": "h-64",
+ "lat": 48.8533173846729,
+ "lon": 2.3497416090232535,
+ "r": "map.jsx",
+ "title": "Cathédrale Notre-Dame de Paris",
+ "zoom": 23
+ }
+ },
+ {
+ "id": "1",
+ "params": {
+ "c": "h-64",
+ "lat": 59.96300872062237,
+ "lon": 10.663529183196863,
+ "r": "map.jsx",
+ "title": "Holmenkollen",
+ "zoom": 3
+ }
+ }
+ ]
+ }
+ ]
+}
+```
+
+Below is an example of a runner script that uses React to render elements. Note that the export (`default`) must match the `export` option in the [script options] (`default` is the default value for runner scripts) (runnable versions of examples on this page can be found at [js.Batch Demo Repo]):
+
+```js
+import * as ReactDOM from 'react-dom/client';
+import * as React from 'react';
+
+export default function Run(group) {
+ console.log('Running react-create-elements.js', group);
+ const scripts = group.scripts;
+ for (const script of scripts) {
+ for (const instance of script.instances) {
+ /* This is a convention in this project. */
+ let elId = `${script.id}-${instance.id}`;
+ let el = document.getElementById(elId);
+ if (!el) {
+ console.warn(`Element with id ${elId} not found`);
+ continue;
+ }
+ const root = ReactDOM.createRoot(el);
+ const reactEl = React.createElement(script.binding, instance.params);
+ root.render(reactEl);
+ }
+ }
+}
+```
+
+### Config
+
+Returns an [OptionsSetter] that can be used to set [build options] for the batch.
+
+These are mostly the same as for `js.Build`, but note that:
+
+- `targetPath` is set automatically (there may be multiple outputs).
+- `format` must be `esm`, currently the only format supporting [code splitting].
+- `params` will be available in the `@params/config` namespace in the scripts. This way you can import both the [script] or [runner] params and the [config] params with:
+
+```js
+import * as params from "@params";
+import * as config from "@params/config";
+```
+
+Setting the `Config` for a batch can be done from any template (including _shortcode_ templates), but will only be set once (the first will win):
+
+```go-html-template
+{{ with js.Batch "js/mybatch" }}
+ {{ with .Config }}
+ {{ .SetOptions (dict
+ "target" "es2023"
+ "format" "esm"
+ "jsx" "automatic"
+ "loaders" (dict ".png" "dataurl")
+ "minify" true
+ "params" (dict "param1" "value1")
+ )
+ }}
+ {{ end }}
+{{ end }}
+```
+
+## Options
+
+### Build options
+
+format
+: (`string`) Currently only `esm` is supported in ESBuild's [code splitting].
+
+{{% include "/_common/functions/js/options.md" %}}
+
+### Script options
+
+resource
+: The resource to build. This can be a file resource or a virtual resource.
+
+export
+: The export to bind the runner to. Set it to `*` to export the [entire namespace](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#namespace_import). Default is `default` for [runner] scripts and `*` for other [scripts](#script).
+
+importContext
+: An additional context for resolving imports. Hugo will always check this one first before falling back to `assets` and `node_modules`. A common use of this is to resolve imports inside a page bundle. See [import context](#import-context).
+
+params
+: A map of parameters that will be passed to the script as JSON. These gets bound to the `@params` namespace:
+
+ ```js
+ import * as params from '@params';
+ ```
+
+### Params options
+
+params
+: A map of parameters that will be passed to the script as JSON.
+
+### Import context
+
+Hugo will, by default, first try to resolve any import in [assets](/hugo-pipes/introduction/#asset-directory) and, if not found, let [ESBuild] resolve it (e.g. from `node_modules`). The `importContext` option can be used to set the first context for resolving imports. A common use of this is to resolve imports inside a [page bundle](/content-management/page-bundles/).
+
+```go-html-template
+{{ $common := resources.Match "/js/headlessui/*.*" }}
+{{ $importContext := (slice $.Page ($common.Mount "/js/headlessui" ".")) }}
+```
+
+You can pass any object that implements [Resource.Get](/methods/page/resources/#get). Pass a slice to set multiple contexts.
+
+The example above uses [`Resources.Mount`] to resolve a directory inside `assets` relative to the page bundle.
+
+### OptionsSetter
+
+An `OptionsSetter` is a special object that is returned once only. This means that you should wrap it with [with]:
+
+```go-html-template
+{{ with .Script "myscript" }}
+ {{ .SetOptions (dict "resource" (resources.Get "myscript.js"))}}
+{{ end }}
+```
+
+## Build
+
+The `Build` method returns an object with the following structure:
+
+- Groups (map)
+ - [`Resources`]
+
+Each [`Resource`] will be of media type `application/javascript` or `text/css`.
+
+In a template you would typically handle one group with a given `ID` (e.g. scripts for the current section). Because of the concurrent build, this needs to be done in a [`templates.Defer`] block:
+
+> [!note]
+> The [`templates.Defer`] acts as a synchronisation point to handle scripts added concurrently by different templates. If you have a setup with where the batch is created in one go (in one template), you don't need it.
+>
+> See [this discussion](https://discourse.gohugo.io/t/js-batch-with-simple-global-script/53002/5?u=bep) for more.
+
+```go-html-template
+{{ $group := .group }}
+{{ with (templates.Defer (dict "key" $group "data" $group )) }}
+ {{ with (js.Batch "js/mybatch") }}
+ {{ with .Build }}
+ {{ with index .Groups $ }}
+ {{ range . }}
+ {{ $s := . }}
+ {{ if eq $s.MediaType.SubType "css" }}
+ <link href="{{ $s.RelPermalink }}" rel="stylesheet" />
+ {{ else }}
+ <script src="{{ $s.RelPermalink }}" type="module"></script>
+ {{ end }}
+ {{ end }}
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+## Known Issues
+
+In the official documentation for ESBuild's [code splitting], there's a warning note in the header. The two issues are:
+
+- `esm` is currently the only implemented output format. This means that it will not work for very old browsers. See [caniuse](https://caniuse.com/?search=ESM).
+- There's a known import ordering issue.
+
+We have not seen the ordering issue as a problem during our [extensive testing](https://github.com/bep/hugojsbatchdemo) of this new feature with different libraries. There are two main cases:
+
+1. Undefined execution order of imports, see [this comment](https://github.com/evanw/esbuild/issues/399#issuecomment-1458680887)
+1. Only one execution order of imports, see [this comment](https://github.com/evanw/esbuild/issues/399#issuecomment-735355932)
+
+Many would say that both of the above are [code smells](https://en.wikipedia.org/wiki/Code_smell). The first one has a simple workaround in Hugo. Define the import order in its own script and make sure it gets passed early to ESBuild, e.g. by putting it in a script group with a name that comes early in the alphabet.
+
+```js
+import './lib2.js';
+import './lib1.js';
+
+console.log('entrypoints-workaround.js');
+```
+
+[ESBuild]: https://github.com/evanw/esbuild
+[JavaScript import]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import
+[OptionsSetter]: #optionssetter
+[SetOptions]: #optionssetter
+[`Resource`]: /methods/resource/
+[`Resources.Mount`]: /methods/page/resources/#mount
+[`Resources`]: /methods/page/resources/
+[`evanw/esbuild`]: https://github.com/evanw/esbuild
+[`templates.Defer`]: /functions/templates/defer/
+[build options]: #build-options
+[code splitting]: https://esbuild.github.io/api/#splitting
+[config]: #config
+[group]: #group
+[instance]: #instance
+[js.Batch Demo Repo]: https://github.com/bep/hugojsbatchdemo/
+[params options]: #params-options
+[runner]: #runner
+[script options]: #script-options
+[script]: #script
+[with]: /functions/go-template/with/
diff --git a/documents/markdown/hugo-docs/en_functions_js_Build.md b/documents/markdown/hugo-docs/en_functions_js_Build.md
new file mode 100644
index 0000000..60960a1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_js_Build.md
@@ -0,0 +1,124 @@
+---
+title: js.Build
+description: Bundle, transpile, tree shake, and minify JavaScript resources.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: resource.Resource
+ signatures: ['js.Build [OPTIONS] RESOURCE']
+---
+
+> [!note]
+> The `js.Build` function is backed by the [`evanw/esbuild`][] package, providing a mature, high-performance foundation for bundling, transformation, and minification.
+
+Use the `js.Build` function to:
+
+- Bundle
+- Transpile (TypeScript and JSX)
+- Tree shake
+- Minify
+- Create source maps
+
+```go-html-template
+{{ with resources.Get "js/main.js" }}
+ {{$opts := dict
+ "minify" (cond hugo.IsDevelopment false true)
+ "sourceMap" (cond hugo.IsDevelopment "linked" "none")
+ }}
+ {{ with . | js.Build $opts }}
+ {{ if hugo.IsDevelopment }}
+ <script src="{{ .RelPermalink }}"></script>
+ {{ else }}
+ {{ with . | fingerprint }}
+ <script src="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"></script>
+ {{ end }}
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+## Options
+
+targetPath
+: (`string`) If not set, the source path will be used as the base target path. Note that the target path's extension may change if the target MIME type is different, e.g. when the source is TypeScript.
+
+format
+: (`string`) The output format. One of: `iife`, `cjs`, `esm`. Default is `iife`, a self-executing function, suitable for inclusion as a `<script>` tag.
+
+{{% include "/_common/functions/js/options.md" %}}
+
+## Import JS code from the assets directory
+
+`js.Build` has full support for Hugo's [unified file system](g). You can see some simple examples in this [test project](https://github.com/gohugoio/hugoTestProjectJSModImports), but in short this means that you can do this:
+
+```js
+import { hello } from 'my/module';
+```
+
+And it will resolve to the top-most `index.{js,ts,tsx,jsx}` inside `assets/my/module` in the layered file system.
+
+```js
+import { hello3 } from 'my/module/hello3';
+```
+
+Will resolve to `hello3.{js,ts,tsx,jsx}` inside `assets/my/module`.
+
+Any imports starting with `.` are resolved relative to the current file:
+
+```js
+import { hello4 } from './lib';
+```
+
+For other files (e.g. `JSON`, `CSS`) you need to use the relative path including any extension, e.g:
+
+```js
+import * as data from 'my/module/data.json';
+```
+
+Any imports in a file outside `assets` or that does not resolve to a component inside `assets` will be resolved by [esbuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo build`.
+
+Also note the new `params` option that can be passed from template to your JS files, e.g.:
+
+```go-html-template
+{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }}
+```
+
+And then in your JS file:
+
+```js
+import * as params from '@params';
+```
+
+Hugo will, by default, generate a `assets/jsconfig.json` file that maps the imports. This is useful for navigation/intellisense help inside code editors, but if you don't need/want it, you can [turn it off](/configuration/build/).
+
+## Node.js dependencies
+
+Use the `js.Build` function to include Node dependencies.
+
+Any imports in a file outside `assets` or that does not resolve to a component inside `assets` will be resolved by [esbuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo build`.
+
+The start directory for resolving npm packages (aka. packages that live inside a `node_modules` directory) is always the main project directory.
+
+> [!note]
+> If you're developing a theme/component that is supposed to be imported and depends on dependencies inside `package.json`, we recommend reading about [hugo mod npm pack](/commands/hugo_mod_npm_pack/), a tool to consolidate all the npm dependencies in a project.
+
+## Examples
+
+```go-html-template
+{{ $built := resources.Get "js/index.js" | js.Build "main.js" }}
+```
+
+Or with options:
+
+```go-html-template
+{{ $externals := slice "react" "react-dom" }}
+{{ $defines := dict "process.env.NODE_ENV" `"development"` }}
+
+{{ $opts := dict "targetPath" "main.js" "externals" $externals "defines" $defines }}
+{{ $built := resources.Get "scripts/main.js" | js.Build $opts }}
+<script src="{{ $built.RelPermalink }}" defer></script>
+```
+
+[`evanw/esbuild`]: https://github.com/evanw/esbuild
diff --git a/documents/markdown/hugo-docs/en_functions_js__index.md b/documents/markdown/hugo-docs/en_functions_js__index.md
new file mode 100644
index 0000000..d3557a2
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_js__index.md
@@ -0,0 +1,7 @@
+---
+title: JavaScript functions
+linkTitle: js
+description: Use these functions to work with JavaScript and TypeScript files.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_lang_FormatAccounting.md b/documents/markdown/hugo-docs/en_functions_lang_FormatAccounting.md
new file mode 100644
index 0000000..d2a1d76
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_lang_FormatAccounting.md
@@ -0,0 +1,17 @@
+---
+title: lang.FormatAccounting
+description: Returns a currency representation of a number for the given currency and precision for the current language and region in accounting notation.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [lang.FormatAccounting PRECISION CURRENCY NUMBER]
+---
+
+```go-html-template
+{{ 512.5032 | lang.FormatAccounting 2 "NOK" }} → NOK512.50
+```
+
+{{% include "/_common/functions/locales.md" %}}
diff --git a/documents/markdown/hugo-docs/en_functions_lang_FormatCurrency.md b/documents/markdown/hugo-docs/en_functions_lang_FormatCurrency.md
new file mode 100644
index 0000000..327413c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_lang_FormatCurrency.md
@@ -0,0 +1,17 @@
+---
+title: lang.FormatCurrency
+description: Returns a currency representation of a number for the given currency and precision for the current language and region.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [lang.FormatCurrency PRECISION CURRENCY NUMBER]
+---
+
+```go-html-template
+{{ 512.5032 | lang.FormatCurrency 2 "USD" }} → $512.50
+```
+
+{{% include "/_common/functions/locales.md" %}}
diff --git a/documents/markdown/hugo-docs/en_functions_lang_FormatNumber.md b/documents/markdown/hugo-docs/en_functions_lang_FormatNumber.md
new file mode 100644
index 0000000..5bf3799
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_lang_FormatNumber.md
@@ -0,0 +1,17 @@
+---
+title: lang.FormatNumber
+description: Returns a numeric representation of a number with the given precision for the current language and region.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [lang.FormatNumber PRECISION NUMBER]
+---
+
+```go-html-template
+{{ 512.5032 | lang.FormatNumber 2 }} → 512.50
+```
+
+{{% include "/_common/functions/locales.md" %}}
diff --git a/documents/markdown/hugo-docs/en_functions_lang_FormatNumberCustom.md b/documents/markdown/hugo-docs/en_functions_lang_FormatNumberCustom.md
new file mode 100644
index 0000000..0a70cd9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_lang_FormatNumberCustom.md
@@ -0,0 +1,30 @@
+---
+title: lang.FormatNumberCustom
+description: Returns a numeric representation of a number with the given precision using negative, decimal, and grouping options.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: ['lang.FormatNumberCustom PRECISION NUMBER [OPTIONS...]']
+aliases: ['/functions/numfmt/']
+---
+
+This function formats a number with the given precision. The first options parameter is a space-delimited string of characters to represent negativity, the decimal point, and grouping. The default value is `- . ,`. The second options parameter defines an alternative delimiting character.
+
+Note that numbers are rounded up at 5 or greater. So, with precision set to 0, 1.5 becomes 2, and 1.4 becomes 1.
+
+For a simpler function that adapts to the current language, see [`lang.FormatNumber`].
+
+```go-html-template
+{{ lang.FormatNumberCustom 2 12345.6789 }} → 12,345.68
+{{ lang.FormatNumberCustom 2 12345.6789 "- , ." }} → 12.345,68
+{{ lang.FormatNumberCustom 6 -12345.6789 "- ." }} → -12345.678900
+{{ lang.FormatNumberCustom 0 -12345.6789 "- . ," }} → -12,346
+{{ lang.FormatNumberCustom 0 -12345.6789 "-|.| " "|" }} → -12 346
+```
+
+{{% include "/_common/functions/locales.md" %}}
+
+[`lang.FormatNumber`]: /functions/lang/formatnumber/
diff --git a/documents/markdown/hugo-docs/en_functions_lang_FormatPercent.md b/documents/markdown/hugo-docs/en_functions_lang_FormatPercent.md
new file mode 100644
index 0000000..aef1fb6
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_lang_FormatPercent.md
@@ -0,0 +1,17 @@
+---
+title: lang.FormatPercent
+description: Returns a percentage representation of a number with the given precision for the current language and region.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [lang.FormatPercent PRECISION NUMBER]
+---
+
+```go-html-template
+{{ 512.5032 | lang.FormatPercent 2 }} → 512.50%
+```
+
+{{% include "/_common/functions/locales.md" %}}
diff --git a/documents/markdown/hugo-docs/en_functions_lang_Merge.md b/documents/markdown/hugo-docs/en_functions_lang_Merge.md
new file mode 100644
index 0000000..f2ce160
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_lang_Merge.md
@@ -0,0 +1,29 @@
+---
+title: lang.Merge
+description: Merge missing translations from other languages.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: any
+ signatures: [lang.Merge FROM TO]
+aliases: [/functions/lang.merge]
+---
+
+As an example:
+
+```sh
+{{ $pages := .Site.RegularPages | lang.Merge $frSite.RegularPages | lang.Merge $enSite.RegularPages }}
+```
+
+Will "fill in the gaps" in the current site with, from left to right, content from the French site, and lastly the English.
+
+A more practical example is to fill in the missing translations from the other languages:
+
+```sh
+{{ $pages := .Site.RegularPages }}
+{{ range .Site.Home.Translations }}
+ {{ $pages = $pages | lang.Merge .Site.RegularPages }}
+{{ end }}
+ ```
diff --git a/documents/markdown/hugo-docs/en_functions_lang_Translate.md b/documents/markdown/hugo-docs/en_functions_lang_Translate.md
new file mode 100644
index 0000000..442090f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_lang_Translate.md
@@ -0,0 +1,247 @@
+---
+title: lang.Translate
+description: Translates a string using the translation tables in the i18n directory.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [T, i18n]
+ returnType: string
+ signatures: ['lang.Translate KEY [CONTEXT]']
+aliases: [/functions/i18n]
+---
+
+The `lang.Translate` function returns the value associated with given key as defined in the translation table for the current language.
+
+If the key is not found in the translation table for the current language, the `lang.Translate` function falls back to the translation table for the [`defaultContentLanguage`][].
+
+If the key is not found in the translation table for the `defaultContentLanguage`, the `lang.Translate` function returns an empty string.
+
+> [!note]
+> To list missing and fallback translations, set [`printI18nWarnings`][] to `true` in your project configuration, or use the `--printI18nWarnings` flag when building your project.
+>
+> To render placeholders for missing and fallback translations, set [`enableMissingTranslationPlaceholders`][] to `true` in your project configuration.
+
+## Translation tables
+
+Create translation tables in the `i18n` directory, naming each file according to [RFC 5646][]. Translation tables may be JSON, TOML, or YAML. For example:
+
+```text
+i18n/en.toml
+i18n/pt-BR.toml
+```
+
+The base name must match the [`locale`][] or [language key][] as defined in your project configuration. Hugo selects the translation table based on the `locale`, falling back to the language key if a matching translation table does not exist.
+
+Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7][] are also supported. You may omit the `art-x-` prefix for brevity. For example:
+
+```text
+i18n/art-x-hugolang.toml
+i18n/hugolang.toml
+```
+
+> [!note]
+> Private use subtags must not exceed 8 alphanumeric characters.
+
+## Simple translations
+
+Let's say your multilingual project supports two languages, English and Polish. Create a translation table for each language in the `i18n` directory.
+
+```text
+i18n/
+├── en.toml
+└── pl.toml
+```
+
+The English translation table:
+
+{{< code-toggle file=i18n/en >}}
+privacy = 'privacy'
+security = 'security'
+{{< /code-toggle >}}
+
+The Polish translation table:
+
+{{< code-toggle file=i18n/pl >}}
+privacy = 'prywatność'
+security = 'bezpieczeństwo'
+{{< /code-toggle >}}
+
+> [!note]
+> The examples below use the `T` alias for brevity.
+
+When viewing the English language site:
+
+```go-html-template
+{{ T "privacy" }} → privacy
+{{ T "security" }} → security
+````
+
+When viewing the Polish language site:
+
+```go-html-template
+{{ T "privacy" }} → prywatność
+{{ T "security" }} → bezpieczeństwo
+```
+
+## Translations with pluralization
+
+Let's say your multilingual project supports two languages, English and Polish. Create a translation table for each language in the `i18n` directory.
+
+```text
+i18n/
+├── en.toml
+└── pl.toml
+```
+
+The Unicode [CLDR Plural Rules chart][CLDR] describes the pluralization categories for each language.
+
+The English translation table:
+
+{{< code-toggle file=i18n/en >}}
+[day]
+one = 'day'
+other = 'days'
+
+[day_with_count]
+one = '{{ . }} day'
+other = '{{ . }} days'
+{{< /code-toggle >}}
+
+The Polish translation table:
+
+{{< code-toggle file=i18n/pl >}}
+[day]
+one = 'miesiąc'
+few = 'miesiące'
+many = 'miesięcy'
+other = 'miesiąca'
+
+[day_with_count]
+one = '{{ . }} miesiąc'
+few = '{{ . }} miesiące'
+many = '{{ . }} miesięcy'
+other = '{{ . }} miesiąca'
+{{< /code-toggle >}}
+
+> [!note]
+> The examples below use the `T` alias for brevity.
+
+When viewing the English language site:
+
+```go-html-template
+{{ T "day" 0 }} → days
+{{ T "day" 1 }} → day
+{{ T "day" 2 }} → days
+{{ T "day" 5 }} → days
+
+{{ T "day_with_count" 0 }} → 0 days
+{{ T "day_with_count" 1 }} → 1 day
+{{ T "day_with_count" 2 }} → 2 days
+{{ T "day_with_count" 5 }} → 5 days
+````
+
+When viewing the Polish language site:
+
+```go-html-template
+{{ T "day" 0 }} → miesięcy
+{{ T "day" 1 }} → miesiąc
+{{ T "day" 2 }} → miesiące
+{{ T "day" 5 }} → miesięcy
+
+{{ T "day_with_count" 0 }} → 0 miesięcy
+{{ T "day_with_count" 1 }} → 1 miesiąc
+{{ T "day_with_count" 2 }} → 2 miesiące
+{{ T "day_with_count" 5 }} → 5 miesięcy
+```
+
+In the pluralization examples above, we passed an integer in context (the second argument). You can also pass a map in context, providing a `count` key to control pluralization.
+
+Translation table:
+
+{{< code-toggle file=i18n/en >}}
+[age]
+one = '{{ .name }} is {{ .count }} year old.'
+other = '{{ .name }} is {{ .count }} years old.'
+{{< /code-toggle >}}
+
+Template code:
+
+```go-html-template
+{{ T "age" (dict "name" "Will" "count" 1) }} → Will is 1 year old.
+{{ T "age" (dict "name" "John" "count" 3) }} → John is 3 years old.
+```
+
+> [!note]
+> Translation tables may contain both simple translations and translations with pluralization.
+
+## Reserved keys
+
+Hugo uses the [go-i18n][] package to look up values in translation tables. This package reserves the following keys for internal use:
+
+id
+: (`string`) Uniquely identifies the message.
+
+description
+: (`string`) Describes the message to give additional context to translators that may be relevant for translation.
+
+hash
+: (`string`) Uniquely identifies the content of the message that this message was translated from.
+
+leftdelim
+: (`string`) The left Go template delimiter.
+
+rightdelim
+: (`string`) The right Go template delimiter.
+
+zero
+: (`string`) The content of the message for the [CLDR][] plural form "zero".
+
+one
+: (`string`) The content of the message for the [CLDR][] plural form "one".
+
+two
+: (`string`) The content of the message for the [CLDR][] plural form "two".
+
+few
+: (`string`) The content of the message for the [CLDR][] plural form "few".
+
+many
+: (`string`) The content of the message for the [CLDR][] plural form "many".
+
+other
+: (`string`) The content of the message for the [CLDR][] plural form "other".
+
+If you need to provide a translation for one of the reserved keys, you can prepend the word with an underscore. For example:
+
+{{< code-toggle file=i18n/es >}}
+_description = 'descripción'
+_few = 'pocos'
+_many = 'muchos'
+_one = 'uno'
+_other = 'otro'
+_two = 'dos'
+_zero = 'cero'
+{{< /code-toggle >}}
+
+Then in your templates:
+
+```go-html-template
+{{ T "_description" }} → descripción
+{{ T "_few" }} → pocos
+{{ T "_many" }} → muchos
+{{ T "_one" }} → uno
+{{ T "_two" }} → dos
+{{ T "_zero" }} → cero
+{{ T "_other" }} → otro
+```
+
+[`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage
+[`enableMissingTranslationPlaceholders`]: /configuration/all/#enablemissingtranslationplaceholders
+[`locale`]: /configuration/languages/#locale
+[`printI18nWarnings`]: /configuration/all/#printi18nwarnings
+[CLDR]: https://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html
+[go-i18n]: https://github.com/nicksnyder/go-i18n
+[language key]: /configuration/languages/#language-keys
+[RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7
+[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
diff --git a/documents/markdown/hugo-docs/en_functions_lang__index.md b/documents/markdown/hugo-docs/en_functions_lang__index.md
new file mode 100644
index 0000000..de75cad
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_lang__index.md
@@ -0,0 +1,7 @@
+---
+title: Lang functions
+linkTitle: lang
+description: Use these functions to adapt your site to meet language and regional requirements.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_math_Abs.md b/documents/markdown/hugo-docs/en_functions_math_Abs.md
new file mode 100644
index 0000000..60d8d6d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Abs.md
@@ -0,0 +1,15 @@
+---
+title: math.Abs
+description: Returns the absolute value of the given number.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: float64
+ signatures: [math.Abs VALUE]
+---
+
+```go-html-template
+{{ math.Abs -2.1 }} → 2.1
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_Acos.md b/documents/markdown/hugo-docs/en_functions_math_Acos.md
new file mode 100644
index 0000000..32537e2
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Acos.md
@@ -0,0 +1,17 @@
+---
+title: math.Acos
+description: Returns the arccosine, in radians, of the given number.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: float64
+ signatures: [math.Acos VALUE]
+---
+
+{{< new-in 0.130.0 />}}
+
+```go-html-template
+{{ math.Acos 1 }} → 0
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_Add.md b/documents/markdown/hugo-docs/en_functions_math_Add.md
new file mode 100644
index 0000000..cd137c6
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Add.md
@@ -0,0 +1,23 @@
+---
+title: math.Add
+description: Adds two or more numbers.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [add]
+ returnType: any
+ signatures: [math.Add VALUE VALUE...]
+---
+
+If one of the numbers is a [`float`](g), the result is a `float`.
+
+```go-html-template
+{{ add 12 3 2 }} → 17
+```
+
+You can also use the `add` function to concatenate strings.
+
+```go-html-template
+{{ add "hu" "go" }} → hugo
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_Asin.md b/documents/markdown/hugo-docs/en_functions_math_Asin.md
new file mode 100644
index 0000000..76114a7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Asin.md
@@ -0,0 +1,17 @@
+---
+title: math.Asin
+description: Returns the arcsine, in radians, of the given number.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: float64
+ signatures: [math.Asin VALUE]
+---
+
+{{< new-in 0.130.0 />}}
+
+```go-html-template
+{{ math.Asin 1 }} → 1.5707963267948966
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_Atan.md b/documents/markdown/hugo-docs/en_functions_math_Atan.md
new file mode 100644
index 0000000..5c8268b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Atan.md
@@ -0,0 +1,17 @@
+---
+title: math.Atan
+description: Returns the arctangent, in radians, of the given number.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: float64
+ signatures: [math.Atan VALUE]
+---
+
+{{< new-in 0.130.0 />}}
+
+```go-html-template
+{{ math.Atan 1 }} → 0.7853981633974483
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_Atan2.md b/documents/markdown/hugo-docs/en_functions_math_Atan2.md
new file mode 100644
index 0000000..942fffd
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Atan2.md
@@ -0,0 +1,17 @@
+---
+title: math.Atan2
+description: Returns the arctangent, in radians, of the given number pair, determining the correct quadrant from their signs.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: float64
+ signatures: [math.Atan2 VALUE VALUE]
+---
+
+{{< new-in 0.130.0 />}}
+
+```go-html-template
+{{ math.Atan2 1 2 }} → 0.4636476090008061
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_Ceil.md b/documents/markdown/hugo-docs/en_functions_math_Ceil.md
new file mode 100644
index 0000000..22a9d02
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Ceil.md
@@ -0,0 +1,15 @@
+---
+title: math.Ceil
+description: Returns the least integer value greater than or equal to the given number.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: float64
+ signatures: [math.Ceil VALUE]
+---
+
+```go-html-template
+{{ math.Ceil 2.1 }} → 3
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_Cos.md b/documents/markdown/hugo-docs/en_functions_math_Cos.md
new file mode 100644
index 0000000..249a064
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Cos.md
@@ -0,0 +1,17 @@
+---
+title: math.Cos
+description: Returns the cosine of the given radian number.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: float64
+ signatures: [math.Cos VALUE]
+---
+
+{{< new-in 0.130.0 />}}
+
+```go-html-template
+{{ math.Cos 1 }} → 0.5403023058681398
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_Counter.md b/documents/markdown/hugo-docs/en_functions_math_Counter.md
new file mode 100644
index 0000000..9eb6cb7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Counter.md
@@ -0,0 +1,33 @@
+---
+title: math.Counter
+description: Increments and returns a global counter.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: uint64
+ signatures: [math.Counter]
+---
+
+The counter is global for both monolingual and multilingual projects, and its initial value for each build is 1.
+
+```go-html-template {file="layouts/page.html"}
+{{ warnf "page.html called %d times" math.Counter }}
+```
+
+```text
+WARN page.html called 1 times
+WARN page.html called 2 times
+WARN page.html called 3 times
+```
+
+Use this function to:
+
+- Create unique warnings as shown above; the [`warnf`] function suppresses duplicate messages
+- Create unique target paths for the `resources.FromString` function where the target path is also the cache key
+
+> [!note]
+> Due to concurrency, the value returned in a given template for a given page will vary from one build to the next. You cannot use this function to assign a static id to each page.
+
+[`warnf`]: /functions/fmt/warnf/
diff --git a/documents/markdown/hugo-docs/en_functions_math_Div.md b/documents/markdown/hugo-docs/en_functions_math_Div.md
new file mode 100644
index 0000000..0e338a9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Div.md
@@ -0,0 +1,17 @@
+---
+title: math.Div
+description: Divides the first number by one or more numbers.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [div]
+ returnType: any
+ signatures: [math.Div VALUE VALUE...]
+---
+
+If one of the numbers is a [`float`](g), the result is a `float`.
+
+```go-html-template
+{{ div 12 3 2 }} → 2
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_Floor.md b/documents/markdown/hugo-docs/en_functions_math_Floor.md
new file mode 100644
index 0000000..dbfd862
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Floor.md
@@ -0,0 +1,15 @@
+---
+title: math.Floor
+description: Returns the greatest integer value less than or equal to the given number.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: float64
+ signatures: [math.Floor VALUE]
+---
+
+```go-html-template
+{{ math.Floor 1.9 }} → 1
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_Log.md b/documents/markdown/hugo-docs/en_functions_math_Log.md
new file mode 100644
index 0000000..123ffac
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Log.md
@@ -0,0 +1,15 @@
+---
+title: math.Log
+description: Returns the natural logarithm of the given number.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: float64
+ signatures: [math.Log VALUE]
+---
+
+```go-html-template
+{{ math.Log 42 }} → 3.737
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_Max.md b/documents/markdown/hugo-docs/en_functions_math_Max.md
new file mode 100644
index 0000000..d3a7676
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Max.md
@@ -0,0 +1,15 @@
+---
+title: math.Max
+description: Returns the greater of all numbers. Accepts scalars, slices, or both.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: float64
+ signatures: [math.Max VALUE...]
+---
+
+```go-html-template
+{{ math.Max 1 (slice 2 3) 4 }} → 4
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_MaxInt64.md b/documents/markdown/hugo-docs/en_functions_math_MaxInt64.md
new file mode 100644
index 0000000..ee4f68f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_MaxInt64.md
@@ -0,0 +1,27 @@
+---
+title: math.MaxInt64
+description: Returns the maximum value for a signed 64-bit integer.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: int64
+ signatures: [math.MaxInt64]
+---
+
+{{< new-in 0.147.3 />}}
+
+```go-html-template
+{{ math.MaxInt64 }} → 9223372036854775807
+```
+
+This function is helpful for simulating a loop that continues indefinitely until a break condition is met. For example:
+
+```go-html-template
+{{ range math.MaxInt64 }}
+ {{ if eq . 42 }}
+ {{ break }}
+ {{ end }}
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_Min.md b/documents/markdown/hugo-docs/en_functions_math_Min.md
new file mode 100644
index 0000000..4f7d7b8
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Min.md
@@ -0,0 +1,15 @@
+---
+title: math.Min
+description: Returns the smaller of all numbers. Accepts scalars, slices, or both.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: float64
+ signatures: [math.Min VALUE...]
+---
+
+```go-html-template
+{{ math.Min 1 (slice 2 3) 4 }} → 1
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_Mod.md b/documents/markdown/hugo-docs/en_functions_math_Mod.md
new file mode 100644
index 0000000..6035a36
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Mod.md
@@ -0,0 +1,15 @@
+---
+title: math.Mod
+description: Returns the modulus of two integers.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [mod]
+ returnType: int64
+ signatures: [math.Mod VALUE1 VALUE2]
+---
+
+```go-html-template
+{{ mod 15 3 }} → 0
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_ModBool.md b/documents/markdown/hugo-docs/en_functions_math_ModBool.md
new file mode 100644
index 0000000..fc7813d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_ModBool.md
@@ -0,0 +1,15 @@
+---
+title: math.ModBool
+description: Reports whether the modulus of two integers equals 0.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [modBool]
+ returnType: bool
+ signatures: [math.ModBool VALUE1 VALUE2]
+---
+
+```go-html-template
+{{ modBool 15 3 }} → true
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_Mul.md b/documents/markdown/hugo-docs/en_functions_math_Mul.md
new file mode 100644
index 0000000..69f2dbe
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Mul.md
@@ -0,0 +1,17 @@
+---
+title: math.Mul
+description: Multiplies two or more numbers.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [mul]
+ returnType: any
+ signatures: [math.Mul VALUE VALUE...]
+---
+
+If one of the numbers is a [`float`](g), the result is a `float`.
+
+```go-html-template
+{{ mul 12 3 2 }} → 72
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_Pi.md b/documents/markdown/hugo-docs/en_functions_math_Pi.md
new file mode 100644
index 0000000..0bc74bf
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Pi.md
@@ -0,0 +1,17 @@
+---
+title: math.Pi
+description: Returns the mathematical constant pi.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: float64
+ signatures: [math.Pi]
+---
+
+{{< new-in 0.130.0 />}}
+
+```go-html-template
+{{ math.Pi }} → 3.141592653589793
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_Pow.md b/documents/markdown/hugo-docs/en_functions_math_Pow.md
new file mode 100644
index 0000000..a438430
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Pow.md
@@ -0,0 +1,15 @@
+---
+title: math.Pow
+description: Returns the first number raised to the power of the second number.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [pow]
+ returnType: float64
+ signatures: [math.Pow VALUE1 VALUE2]
+---
+
+```go-html-template
+{{ math.Pow 2 3 }} → 8
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_Product.md b/documents/markdown/hugo-docs/en_functions_math_Product.md
new file mode 100644
index 0000000..ffb1afe
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Product.md
@@ -0,0 +1,15 @@
+---
+title: math.Product
+description: Returns the product of all numbers. Accepts scalars, slices, or both.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: float64
+ signatures: [math.Product VALUE...]
+---
+
+```go-html-template
+{{ math.Product 1 (slice 2 3) 4 }} → 24
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_Rand.md b/documents/markdown/hugo-docs/en_functions_math_Rand.md
new file mode 100644
index 0000000..72338ac
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Rand.md
@@ -0,0 +1,41 @@
+---
+title: math.Rand
+description: Returns a pseudo-random number in the half-open interval [0.0, 1.0).
+categories: []
+keywords: [random]
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: float64
+ signatures: [math.Rand]
+---
+
+The `math.Rand` function returns a pseudo-random number in the half-open [interval](g) [0.0, 1.0).
+
+```go-html-template
+{{ math.Rand }} → 0.6312770459590062
+```
+
+To generate a random integer in the closed interval [0, 5]:
+
+```go-html-template
+{{ math.Rand | mul 6 | math.Floor }}
+```
+
+To generate a random integer in the closed interval [1, 6]:
+
+```go-html-template
+{{ math.Rand | mul 6 | math.Ceil }}
+```
+
+To generate a random float, with one digit after the decimal point, in the closed interval [0, 4.9]:
+
+```go-html-template
+{{ div (math.Rand | mul 50 | math.Floor) 10 }}
+```
+
+To generate a random float, with one digit after the decimal point, in the closed interval [0.1, 5.0]:
+
+```go-html-template
+{{ div (math.Rand | mul 50 | math.Ceil) 10 }}
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_Round.md b/documents/markdown/hugo-docs/en_functions_math_Round.md
new file mode 100644
index 0000000..6bc015c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Round.md
@@ -0,0 +1,15 @@
+---
+title: math.Round
+description: Returns the nearest integer, rounding half away from zero.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: float64
+ signatures: [math.Round VALUE]
+---
+
+```go-html-template
+{{ math.Round 1.5 }} → 2
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_Sin.md b/documents/markdown/hugo-docs/en_functions_math_Sin.md
new file mode 100644
index 0000000..b5ab86b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Sin.md
@@ -0,0 +1,17 @@
+---
+title: math.Sin
+description: Returns the sine of the given radian number.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: float64
+ signatures: [math.Sin VALUE]
+---
+
+{{< new-in 0.130.0 />}}
+
+```go-html-template
+{{ math.Sin 1 }} → 0.8414709848078965
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_Sqrt.md b/documents/markdown/hugo-docs/en_functions_math_Sqrt.md
new file mode 100644
index 0000000..b2f49fd
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Sqrt.md
@@ -0,0 +1,15 @@
+---
+title: math.Sqrt
+description: Returns the square root of the given number.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: float64
+ signatures: [math.Sqrt VALUE]
+---
+
+```go-html-template
+{{ math.Sqrt 81 }} → 9
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_Sub.md b/documents/markdown/hugo-docs/en_functions_math_Sub.md
new file mode 100644
index 0000000..49459cd
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Sub.md
@@ -0,0 +1,17 @@
+---
+title: math.Sub
+description: Subtracts one or more numbers from the first number.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [sub]
+ returnType: any
+ signatures: [math.Sub VALUE VALUE...]
+---
+
+If one of the numbers is a [`float`](g), the result is a `float`.
+
+```go-html-template
+{{ sub 12 3 2 }} → 7
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_Sum.md b/documents/markdown/hugo-docs/en_functions_math_Sum.md
new file mode 100644
index 0000000..e14bc92
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Sum.md
@@ -0,0 +1,14 @@
+---
+title: math.Sum
+description: Returns the sum of all numbers. Accepts scalars, slices, or both.
+categories: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: float64
+ signatures: [math.Sum VALUE...]
+---
+
+```go-html-template
+{{ math.Sum 1 (slice 2 3) 4 }} → 10
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_Tan.md b/documents/markdown/hugo-docs/en_functions_math_Tan.md
new file mode 100644
index 0000000..c4f861c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_Tan.md
@@ -0,0 +1,17 @@
+---
+title: math.Tan
+description: Returns the tangent of the given radian number.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: float64
+ signatures: [math.Tan VALUE]
+---
+
+{{< new-in 0.130.0 />}}
+
+```go-html-template
+{{ math.Tan 1 }} → 1.557407724654902
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_ToDegrees.md b/documents/markdown/hugo-docs/en_functions_math_ToDegrees.md
new file mode 100644
index 0000000..f01cd47
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_ToDegrees.md
@@ -0,0 +1,17 @@
+---
+title: math.ToDegrees
+description: ToDegrees converts radians into degrees.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: float64
+ signatures: [math.ToDegrees VALUE]
+---
+
+{{< new-in 0.130.0 />}}
+
+```go-html-template
+{{ math.ToDegrees 1.5707963267948966 }} → 90
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math_ToRadians.md b/documents/markdown/hugo-docs/en_functions_math_ToRadians.md
new file mode 100644
index 0000000..b5acbb6
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math_ToRadians.md
@@ -0,0 +1,17 @@
+---
+title: math.ToRadians
+description: ToRadians converts degrees into radians.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: float64
+ signatures: [math.ToRadians VALUE]
+---
+
+{{< new-in 0.130.0 />}}
+
+```go-html-template
+{{ math.ToRadians 90 }} → 1.5707963267948966
+```
diff --git a/documents/markdown/hugo-docs/en_functions_math__index.md b/documents/markdown/hugo-docs/en_functions_math__index.md
new file mode 100644
index 0000000..c58a5a7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_math__index.md
@@ -0,0 +1,6 @@
+---
+title: Math functions
+linkTitle: math
+description: Use these functions to perform mathematical operations.
+categories: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_openapi3_Unmarshal.md b/documents/markdown/hugo-docs/en_functions_openapi3_Unmarshal.md
new file mode 100644
index 0000000..f64ee11
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_openapi3_Unmarshal.md
@@ -0,0 +1,116 @@
+---
+title: openapi3.Unmarshal
+description: Unmarshals the given resource into an OpenAPI 3 Description.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: openapi3.OpenAPIDocument
+ signatures: ['openapi3.Unmarshal RESOURCE [OPTIONS]']
+---
+
+The resource passed to the `openapi3.Unmarshal` function must be an [OpenAPI Document][], typically in JSON or YAML format. This resource can be a [global resource](g) or a [remote resource](g).
+
+This function automatically resolves and includes all external references, both local and remote, and returns a complete [OpenAPI Description][] that fully describes the surface of an API and its semantics.
+
+## Options
+
+{{< new-in 0.153.0 />}}
+
+getremote
+: (`map`) This is a map of the options for the [`resources.GetRemote`][] function, useful when an OpenAPI Document includes remote external references.
+
+## Examples
+
+### Remote resource
+
+To work with a remote resource:
+
+```go-html-template {copy=true}
+{{ $api := "" }}
+{{ $url := "https://petstore.swagger.io/v2/swagger.json" }}
+{{ $opts := dict
+ "headers" (dict "Authorization" "Bearer abcd")
+}}
+{{ with try (resources.GetRemote $url $opts) }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else with .Value }}
+ {{ $api = openapi3.Unmarshal . (dict "getremote" $opts) }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+ {{ end }}
+{{ end }}
+```
+
+In the example above, the same HTTP Authorization header is used for both the initial remote request made by the `resources.GetRemote` function and for subsequent requests by the `openapi.Unmarshal` function as it retrieve remote external references.
+
+### Global resource
+
+To work with a global resource:
+
+```go-html-template {copy=true}
+{{ $api := "" }}
+{{ $opts := dict
+ "method" "post"
+ "key" now.UnixNano
+}}
+{{ with resources.Get "api/petstore.json" }}
+ {{ $api = openapi3.Unmarshal . (dict "getremote" $opts) }}
+{{ end }}
+```
+
+For global resources, local external reference paths starting with `/` are resolved relative to the `assets` directory. All other local paths are resolved relative to the entry point. In the example above, local paths are resolved relative to `assets/api/petstore.json`.
+
+## Inspection
+
+> [!note]
+> The unmarshaled data structure is created with [`kin-openapi`](https://github.com/getkin/kin-openapi). Many fields are structs or pointers (not maps), and therefore require accessors or other methods for indexing and iteration.
+> For example, prior to [`kin-openapi` v0.122.0](https://github.com/getkin/kin-openapi#v01220) / [Hugo v0.121.0](https://github.com/gohugoio/hugo/releases/tag/v0.121.0), `Paths` was a map (so `.Paths` was iterable) and it is now a pointer (and requires the `.Paths.Map` accessor, as in the example above).
+> See the [`kin-openapi` godoc for OpenAPI 3](https://pkg.go.dev/github.com/getkin/kin-openapi/openapi3) for full type definitions.
+
+To inspect the unmarshaled data structure:
+
+```go-html-template {copy=true}
+<pre>{{ debug.Dump $api }}</pre>
+```
+
+To list the GET and POST operations for each of the API paths:
+
+```go-html-template {copy=true}
+{{ range $path, $details := $api.Paths.Map }}
+ <p>{{ $path }}</p>
+ <dl>
+ {{ with $details.Get }}
+ <dt>GET</dt>
+ <dd>{{ .Summary }}</dd>
+ {{ end }}
+ {{ with $details.Post }}
+ <dt>POST</dt>
+ <dd>{{ .Summary }}</dd>
+ {{ end }}
+ </dl>
+{{ end }}
+```
+
+Hugo renders this to:
+
+```html
+<p>/pets</p>
+<dl>
+ <dt>GET</dt>
+ <dd>List all pets</dd>
+ <dt>POST</dt>
+ <dd>Create a pet</dd>
+</dl>
+<p>/pets/{petId}</p>
+<dl>
+ <dt>GET</dt>
+ <dd>Info for a specific pet</dd>
+</dl>
+```
+
+[`resources.GetRemote`]: /functions/resources/getremote/#options
+[OpenAPI Document]: https://swagger.io/specification/#openapi-document
+[OpenAPI Description]: https://swagger.io/specification/#openapi-description
diff --git a/documents/markdown/hugo-docs/en_functions_openapi3__index.md b/documents/markdown/hugo-docs/en_functions_openapi3__index.md
new file mode 100644
index 0000000..852daf7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_openapi3__index.md
@@ -0,0 +1,7 @@
+---
+title: OpenAPI functions
+linkTitle: openapi3
+description: Use these functions to work with OpenAPI 3 definitions.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_os_FileExists.md b/documents/markdown/hugo-docs/en_functions_os_FileExists.md
new file mode 100644
index 0000000..b8a01a3
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_os_FileExists.md
@@ -0,0 +1,37 @@
+---
+title: os.FileExists
+description: Reports whether the file or directory exists.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [fileExists]
+ returnType: bool
+ signatures: [os.FileExists PATH]
+aliases: [/functions/fileexists]
+---
+
+The `os.FileExists` function attempts to resolve the path relative to the root of your project directory. If a matching file or directory is not found, it will attempt to resolve the path relative to the [`contentDir`](/configuration/all/#contentdir). A leading path separator (`/`) is optional.
+
+With this directory structure:
+
+```text
+content/
+├── about.md
+├── contact.md
+└── news/
+ ├── article-1.md
+ └── article-2.md
+```
+
+The function returns these values:
+
+```go-html-template
+{{ fileExists "content" }} → true
+{{ fileExists "content/news" }} → true
+{{ fileExists "content/news/article-1" }} → false
+{{ fileExists "content/news/article-1.md" }} → true
+{{ fileExists "news" }} → true
+{{ fileExists "news/article-1" }} → false
+{{ fileExists "news/article-1.md" }} → true
+```
diff --git a/documents/markdown/hugo-docs/en_functions_os_Getenv.md b/documents/markdown/hugo-docs/en_functions_os_Getenv.md
new file mode 100644
index 0000000..d9e6e08
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_os_Getenv.md
@@ -0,0 +1,54 @@
+---
+title: os.Getenv
+description: Returns the value of an environment variable, or an empty string if the environment variable is not set.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [getenv]
+ returnType: string
+ signatures: [os.Getenv VARIABLE]
+aliases: [/functions/getenv]
+---
+
+## Security
+
+By default, when using the `os.Getenv` function Hugo allows access to:
+
+- The `CI` environment variable
+- Any environment variable beginning with `HUGO_`
+
+To access other environment variables, adjust your project configuration. For example, to allow access to the `HOME` and `USER` environment variables:
+
+{{< code-toggle file=hugo >}}
+[security.funcs]
+getenv = ['^HUGO_', '^CI$', '^USER$', '^HOME$']
+{{< /code-toggle >}}
+
+For more information see [configure security](/configuration/security).
+
+## Examples
+
+```go-html-template
+{{ getenv "HOME" }} → /home/victor
+{{ getenv "USER" }} → victor
+```
+
+You can pass values when building your project:
+
+```sh
+MY_VAR1=foo MY_VAR2=bar hugo
+
+OR
+
+export MY_VAR1=foo
+export MY_VAR2=bar
+hugo
+```
+
+And then retrieve the values within a template:
+
+```go-html-template
+{{ getenv "MY_VAR1" }} → foo
+{{ getenv "MY_VAR2" }} → bar
+```
diff --git a/documents/markdown/hugo-docs/en_functions_os_ReadDir.md b/documents/markdown/hugo-docs/en_functions_os_ReadDir.md
new file mode 100644
index 0000000..65c398a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_os_ReadDir.md
@@ -0,0 +1,45 @@
+---
+title: os.ReadDir
+description: Returns an array of FileInfo structures sorted by file name, one element for each directory entry.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [readDir]
+ returnType: os.FileInfo
+ signatures: [os.ReadDir PATH]
+aliases: [/functions/readdir]
+---
+
+The `os.ReadDir` function resolves the path relative to the root of your project directory. A leading path separator (`/`) is optional.
+
+With this directory structure:
+
+```text
+content/
+├── about.md
+├── contact.md
+└── news/
+ ├── article-1.md
+ └── article-2.md
+```
+
+This template code:
+
+```go-html-template
+{{ range readDir "content" }}
+ {{ .Name }} → {{ .IsDir }}
+{{ end }}
+```
+
+Produces:
+
+```html
+about.md → false
+contact.md → false
+news → true
+```
+
+Note that `os.ReadDir` is not recursive.
+
+Details of the `FileInfo` structure are available in the [Go documentation](https://pkg.go.dev/io/fs#FileInfo).
diff --git a/documents/markdown/hugo-docs/en_functions_os_ReadFile.md b/documents/markdown/hugo-docs/en_functions_os_ReadFile.md
new file mode 100644
index 0000000..7f25327
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_os_ReadFile.md
@@ -0,0 +1,34 @@
+---
+title: os.ReadFile
+description: Returns the contents of a file.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [readFile]
+ returnType: string
+ signatures: [os.ReadFile PATH]
+aliases: [/functions/readfile]
+---
+
+The `os.ReadFile` function attempts to resolve the path relative to the root of your project directory. If a matching file is not found, it will attempt to resolve the path relative to the [`contentDir`](/configuration/all/#contentdir). A leading path separator (`/`) is optional.
+
+With a file named README.md in the root of your project directory:
+
+```text
+This is **bold** text.
+```
+
+This template code:
+
+```go-html-template
+{{ readFile "README.md" }}
+```
+
+Produces:
+
+```html
+This is **bold** text.
+```
+
+Note that `os.ReadFile` returns raw (uninterpreted) content.
diff --git a/documents/markdown/hugo-docs/en_functions_os_Stat.md b/documents/markdown/hugo-docs/en_functions_os_Stat.md
new file mode 100644
index 0000000..63cb3f2
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_os_Stat.md
@@ -0,0 +1,27 @@
+---
+title: os.Stat
+description: Returns a FileInfo structure describing a file or directory.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: os.FileInfo
+ signatures: [os.Stat PATH]
+aliases: [/functions/os.stat]
+---
+
+The `os.Stat` function attempts to resolve the path relative to the root of your project directory. If a matching file or directory is not found, it will attempt to resolve the path relative to the [`contentDir`](/configuration/all/#contentdir). A leading path separator (`/`) is optional.
+
+```go-html-template
+{{ $f := os.Stat "README.md" }}
+{{ $f.IsDir }} → false (bool)
+{{ $f.ModTime }} → 2021-11-25 10:06:49.315429236 -0800 PST (time.Time)
+{{ $f.Name }} → README.md (string)
+{{ $f.Size }} → 241 (int64)
+
+{{ $d := os.Stat "content" }}
+{{ $d.IsDir }} → true (bool)
+```
+
+Details of the `FileInfo` structure are available in the [Go documentation](https://pkg.go.dev/io/fs#FileInfo).
diff --git a/documents/markdown/hugo-docs/en_functions_os__index.md b/documents/markdown/hugo-docs/en_functions_os__index.md
new file mode 100644
index 0000000..b125f70
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_os__index.md
@@ -0,0 +1,7 @@
+---
+title: OS functions
+linkTitle: os
+description: Use these functions to interact with the operating system.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_partials_Include.md b/documents/markdown/hugo-docs/en_functions_partials_Include.md
new file mode 100644
index 0000000..dfb8873
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_partials_Include.md
@@ -0,0 +1,80 @@
+---
+title: partials.Include
+description: Executes the given template, optionally passing context. If the partial template contains a return statement, returns the given value, else returns the rendered output.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [partial]
+ returnType: any
+ signatures: ['partials.Include NAME [CONTEXT]']
+aliases: [/functions/partial]
+---
+
+Without a [`return`] statement, the `partial` function returns a string of type `template.HTML`. With a `return` statement, the `partial` function can return any data type.
+
+In this example we have three _partial_ templates:
+
+```text
+layouts/
+└── _partials/
+ ├── average.html
+ ├── breadcrumbs.html
+ └── footer.html
+```
+
+The "average" partial returns the average of one or more numbers. We pass the numbers in context:
+
+```go-html-template
+{{ $numbers := slice 1 6 7 42 }}
+{{ $average := partial "average.html" $numbers }}
+```
+
+The "breadcrumbs" partial renders [breadcrumb navigation], and needs to receive the current page in context:
+
+```go-html-template
+{{ partial "breadcrumbs.html" . }}
+```
+
+The "footer" partial renders the site footer. In this contrived example, the footer does not need access to the current page, so we can omit context:
+
+```go-html-template
+{{ partial "footer.html" }}
+```
+
+You can pass anything in context: a page, a page collection, a scalar value, a slice, or a map. In this example we pass the current page and three scalar values:
+
+```go-html-template
+{{ $ctx := dict
+ "page" .
+ "name" "John Doe"
+ "major" "Finance"
+ "gpa" 4.0
+}}
+{{ partial "render-student-info.html" $ctx }}
+```
+
+Then, within the _partial_ template:
+
+```go-html-template
+<p>{{ .name }} is majoring in {{ .major }}.</p>
+<p>Their grade point average is {{ .gpa }}.</p>
+<p>See <a href="{{ .page.RelPermalink }}">details.</a></p>
+```
+
+To return a value from a _partial_ template, it must contain only one `return` statement, placed at the end of the template:
+
+```go-html-template
+{{ $result := "" }}
+{{ if math.ModBool . 2 }}
+ {{ $result = "even" }}
+{{ else }}
+ {{ $result = "odd" }}
+{{ end }}
+{{ return $result }}
+```
+
+See [details][`return`].
+
+[`return`]: /functions/go-template/return/
+[breadcrumb navigation]: /content-management/sections/#ancestors-and-descendants
diff --git a/documents/markdown/hugo-docs/en_functions_partials_IncludeCached.md b/documents/markdown/hugo-docs/en_functions_partials_IncludeCached.md
new file mode 100644
index 0000000..a8a7157
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_partials_IncludeCached.md
@@ -0,0 +1,57 @@
+---
+title: partials.IncludeCached
+description: Executes the given template and caches the result, optionally passing one or more variant keys. If the partial template contains a return statement, returns the given value, else returns the rendered output.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [partialCached]
+ returnType: any
+ signatures: ['partials.IncludeCached LAYOUT CONTEXT [VARIANT...]']
+aliases: [/functions/partialcached]
+---
+
+Without a [`return`] statement, the `partialCached` function returns a string of type `template.HTML`. With a `return` statement, the `partialCached` function can return any data type.
+
+The `partialCached` function can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation.
+
+> [!note]
+> Each site (or language) has its own `partialCached` cache, so each site will execute a partial once.
+>
+> Hugo renders pages in parallel, and will render the partial more than once with concurrent calls to the `partialCached` function. After Hugo caches the rendered partial, new pages entering the build pipeline will use the cached result.
+
+Here is the simplest usage:
+
+```go-html-template
+{{ partialCached "footer.html" . }}
+```
+
+Pass additional arguments to `partialCached` to create variants of the cached partial. For example, if you have a complex partial that should be identical when rendered for pages within the same section, use a variant based on section so that the partial is only rendered once per section:
+
+```go-html-template {file="layouts/baseof.html"}
+{{ partialCached "footer.html" . .Section }}
+```
+
+Pass additional arguments, of any data type, as needed to create unique variants:
+
+```go-html-template
+{{ partialCached "footer.html" . .Params.country .Params.province }}
+```
+
+The variant arguments are not available to the underlying _partial_ template; they are only used to create unique cache keys.
+
+To return a value from a _partial_ template, it must contain only one `return` statement, placed at the end of the template:
+
+```go-html-template
+{{ $result := "" }}
+{{ if math.ModBool . 2 }}
+ {{ $result = "even" }}
+{{ else }}
+ {{ $result = "odd" }}
+{{ end }}
+{{ return $result }}
+```
+
+See [details][`return`].
+
+[`return`]: /functions/go-template/return/
diff --git a/documents/markdown/hugo-docs/en_functions_partials__index.md b/documents/markdown/hugo-docs/en_functions_partials__index.md
new file mode 100644
index 0000000..09b4673
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_partials__index.md
@@ -0,0 +1,7 @@
+---
+title: Partial functions
+linkTitle: partials
+description: Use these functions to call partial templates.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_path_Base.md b/documents/markdown/hugo-docs/en_functions_path_Base.md
new file mode 100644
index 0000000..39d52bf
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_path_Base.md
@@ -0,0 +1,20 @@
+---
+title: path.Base
+description: Replaces path separators with slashes (`/`) and returns the last element of the given path.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [path.Base PATH]
+aliases: [/functions/path.base]
+---
+
+```go-html-template
+{{ path.Base "a/news.html" }} → news.html
+{{ path.Base "news.html" }} → news.html
+{{ path.Base "a/b/c" }} → c
+{{ path.Base "/x/y/z/" }} → z
+{{ path.Base "" }} → .
+```
diff --git a/documents/markdown/hugo-docs/en_functions_path_BaseName.md b/documents/markdown/hugo-docs/en_functions_path_BaseName.md
new file mode 100644
index 0000000..468898a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_path_BaseName.md
@@ -0,0 +1,20 @@
+---
+title: path.BaseName
+description: Replaces path separators with slashes (`/`) and returns the last element of the given path, removing the extension if present.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [path.BaseName PATH]
+aliases: [/functions/path.basename]
+---
+
+```go-html-template
+{{ path.BaseName "a/news.html" }} → news
+{{ path.BaseName "news.html" }} → news
+{{ path.BaseName "a/b/c" }} → c
+{{ path.BaseName "/x/y/z/" }} → z
+{{ path.BaseName "" }} → .
+```
diff --git a/documents/markdown/hugo-docs/en_functions_path_Clean.md b/documents/markdown/hugo-docs/en_functions_path_Clean.md
new file mode 100644
index 0000000..b9f2de0
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_path_Clean.md
@@ -0,0 +1,27 @@
+---
+title: path.Clean
+description: Replaces path separators with slashes (`/`) and returns the shortest path name equivalent to the given path.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [path.Clean PATH]
+aliases: [/functions/path.clean]
+---
+
+See Go's [`path.Clean`] documentation for details.
+
+[`path.Clean`]: https://pkg.go.dev/path#Clean
+
+```go-html-template
+{{ path.Clean "foo/bar" }} → foo/bar
+{{ path.Clean "/foo/bar" }} → /foo/bar
+{{ path.Clean "/foo/bar/" }} → /foo/bar
+{{ path.Clean "/foo//bar/" }} → /foo/bar
+{{ path.Clean "/foo/./bar/" }} → /foo/bar
+{{ path.Clean "/foo/../bar/" }} → /bar
+{{ path.Clean "/../foo/../bar/" }} → /bar
+{{ path.Clean "" }} → .
+```
diff --git a/documents/markdown/hugo-docs/en_functions_path_Dir.md b/documents/markdown/hugo-docs/en_functions_path_Dir.md
new file mode 100644
index 0000000..04d5500
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_path_Dir.md
@@ -0,0 +1,21 @@
+---
+title: path.Dir
+description: Replaces path separators with slashes (/) and returns all but the last element of the given path.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [path.Dir PATH]
+aliases: [/functions/path.dir]
+---
+
+```go-html-template
+{{ path.Dir "a/news.html" }} → a
+{{ path.Dir "news.html" }} → .
+{{ path.Dir "a/b/c" }} → a/b
+{{ path.Dir "/a/b/c" }} → /a/b
+{{ path.Dir "/a/b/c/" }} → /a/b/c
+{{ path.Dir "" }} → .
+```
diff --git a/documents/markdown/hugo-docs/en_functions_path_Ext.md b/documents/markdown/hugo-docs/en_functions_path_Ext.md
new file mode 100644
index 0000000..3646d02
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_path_Ext.md
@@ -0,0 +1,18 @@
+---
+title: path.Ext
+description: Replaces path separators with slashes (`/`) and returns the file name extension of the given path.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [path.Ext PATH]
+aliases: [/functions/path.ext]
+---
+
+The extension is the suffix beginning at the final dot in the final slash-separated element of path; it is empty if there is no dot.
+
+```go-html-template
+{{ path.Ext "a/b/c/news.html" }} → .html
+```
diff --git a/documents/markdown/hugo-docs/en_functions_path_Join.md b/documents/markdown/hugo-docs/en_functions_path_Join.md
new file mode 100644
index 0000000..bda4673
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_path_Join.md
@@ -0,0 +1,28 @@
+---
+title: path.Join
+description: Replaces path separators with slashes (`/`), joins the given path elements into a single path, and returns the shortest path name equivalent to the result.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [path.Join ELEMENT...]
+aliases: [/functions/path.join]
+---
+
+See Go's [`path.Join`] and [`path.Clean`] documentation for details.
+
+[`path.Clean`]: https://pkg.go.dev/path#Clean
+[`path.Join`]: https://pkg.go.dev/path#Join
+
+```go-html-template
+{{ path.Join "partial" "news.html" }} → partial/news.html
+{{ path.Join "partial/" "news.html" }} → partial/news.html
+{{ path.Join "foo/bar" "baz" }} → foo/bar/baz
+{{ path.Join "foo" "bar" "baz" }} → foo/bar/baz
+{{ path.Join "foo" "" "baz" }} → foo/baz
+{{ path.Join "foo" "." "baz" }} → foo/baz
+{{ path.Join "foo" ".." "baz" }} → baz
+{{ path.Join "/.." "foo" ".." "baz" }} → baz
+```
diff --git a/documents/markdown/hugo-docs/en_functions_path_Split.md b/documents/markdown/hugo-docs/en_functions_path_Split.md
new file mode 100644
index 0000000..d4f8d08
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_path_Split.md
@@ -0,0 +1,28 @@
+---
+title: path.Split
+description: Replaces path separators with slashes (`/`) and splits the resulting path immediately following the final slash, separating it into a directory and file name component.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: paths.DirFile
+ signatures: [path.Split PATH]
+aliases: [/functions/path.split]
+---
+
+If there is no slash in the given path, `path.Split` returns an empty directory, and file set to path. The returned values have the property that path = dir+file.
+
+```go-html-template
+{{ $dirFile := path.Split "a/news.html" }}
+{{ $dirFile.Dir }} → a/
+{{ $dirFile.File }} → news.html
+
+{{ $dirFile := path.Split "news.html" }}
+{{ $dirFile.Dir }} → "" (empty string)
+{{ $dirFile.File }} → news.html
+
+{{ $dirFile := path.Split "a/b/c" }}
+{{ $dirFile.Dir }} → a/b/
+{{ $dirFile.File }} → c
+```
diff --git a/documents/markdown/hugo-docs/en_functions_path__index.md b/documents/markdown/hugo-docs/en_functions_path__index.md
new file mode 100644
index 0000000..49b2927
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_path__index.md
@@ -0,0 +1,7 @@
+---
+title: Path functions
+linkTitle: path
+description: Use these functions to work with file paths.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_reflect_IsImageResource.md b/documents/markdown/hugo-docs/en_functions_reflect_IsImageResource.md
new file mode 100644
index 0000000..f1a6dec
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_reflect_IsImageResource.md
@@ -0,0 +1,29 @@
+---
+title: reflect.IsImageResource
+description: Reports whether the given value is a Resource object representing an image as defined by its media type.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [reflect.IsImageResource INPUT]
+---
+
+{{< new-in 0.154.0 />}}
+
+## Usage
+
+This example iterates through all project resources and uses `reflect.IsImageResource` to decide whether to render an image tag or provide a download link for non-image files.
+
+```go-html-template
+{{ range resources.Match "**" }}
+ {{ if reflect.IsImageResource . }}
+ <img src="{{ .RelPermalink }}" alt="Image">
+ {{ else }}
+ <a href="{{ .RelPermalink }}">Download</a>
+ {{ end }}
+{{ end }}
+```
+
+{{% include "/_common/functions/reflect/image-reflection-functions.md" %}}
diff --git a/documents/markdown/hugo-docs/en_functions_reflect_IsImageResourceProcessable.md b/documents/markdown/hugo-docs/en_functions_reflect_IsImageResourceProcessable.md
new file mode 100644
index 0000000..d0d3d23
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_reflect_IsImageResourceProcessable.md
@@ -0,0 +1,31 @@
+---
+title: reflect.IsImageResourceProcessable
+description: Reports whether the given value is a Resource object representing an image from which Hugo can extract dimensions and perform processing such as converting, resizing, cropping, or filtering.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [reflect.IsImageResourceProcessable INPUT]
+---
+
+{{< new-in 0.157.0 />}}
+
+{{% glossary-term "processable image" %}}
+
+## Usage
+
+This example iterates through all project resources and uses `reflect.IsImageResourceProcessable` to ensure the image pipeline can perform transformations like resizing before processing begins.
+
+```go-html-template
+{{ range resources.Match "**" }}
+ {{ if reflect.IsImageResourceProcessable . }}
+ {{ with .Process "resize 300x webp" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="Processed Image">
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+{{% include "/_common/functions/reflect/image-reflection-functions.md" %}}
diff --git a/documents/markdown/hugo-docs/en_functions_reflect_IsImageResourceWithMeta.md b/documents/markdown/hugo-docs/en_functions_reflect_IsImageResourceWithMeta.md
new file mode 100644
index 0000000..642ce2d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_reflect_IsImageResourceWithMeta.md
@@ -0,0 +1,30 @@
+---
+title: reflect.IsImageResourceWithMeta
+description: Reports whether the given value is a Resource object representing an image from which Hugo can extract dimensions and, if present, Exif, IPTC, and XMP data.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [reflect.IsImageResourceWithMeta INPUT]
+---
+
+{{< new-in 0.157.0 />}}
+
+## Usage
+
+This example iterates through all project resources and uses `reflect.IsImageResourceWithMeta` to safely display image dimensions and metadata only for supported formats.
+
+```go-html-template
+{{ range resources.Match "**" }}
+ {{ if reflect.IsImageResourceWithMeta . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="Image with Meta">
+ {{ with .Meta }}
+ <p>Taken on: {{ .Date }}</p>
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+{{% include "/_common/functions/reflect/image-reflection-functions.md" %}}
diff --git a/documents/markdown/hugo-docs/en_functions_reflect_IsMap.md b/documents/markdown/hugo-docs/en_functions_reflect_IsMap.md
new file mode 100644
index 0000000..55b9811
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_reflect_IsMap.md
@@ -0,0 +1,17 @@
+---
+title: reflect.IsMap
+description: Reports whether the given value is a map.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [reflect.IsMap INPUT]
+aliases: [/functions/reflect.ismap]
+---
+
+```go-html-template
+{{ reflect.IsMap (dict "key" "value") }} → true
+{{ reflect.IsMap "yo" }} → false
+```
diff --git a/documents/markdown/hugo-docs/en_functions_reflect_IsPage.md b/documents/markdown/hugo-docs/en_functions_reflect_IsPage.md
new file mode 100644
index 0000000..eaf545c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_reflect_IsPage.md
@@ -0,0 +1,23 @@
+---
+title: reflect.IsPage
+description: Reports whether the given value is a Page object.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [reflect.IsPage INPUT]
+---
+
+{{< new-in 0.154.0 />}}
+
+```go-html-template {file="layouts/page.html"}
+{{ with site.GetPage "/examples" }}
+ {{ reflect.IsPage . }} → true
+{{ end }}
+
+{{ with .Site }}
+ {{ reflect.IsPage . }} → false
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_functions_reflect_IsResource.md b/documents/markdown/hugo-docs/en_functions_reflect_IsResource.md
new file mode 100644
index 0000000..ae86b4e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_reflect_IsResource.md
@@ -0,0 +1,65 @@
+---
+title: reflect.IsResource
+description: Reports whether the given value is a Resource object.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [reflect.IsResource INPUT]
+---
+
+{{< new-in 0.154.0 />}}
+
+With this project structure:
+
+```text
+project/
+├── assets/
+│ ├── a.json
+│ ├── b.avif
+│ └── c.jpg
+└── content/
+ └── example/
+ ├── index.md
+ ├── d.json
+ ├── e.avif
+ └── f.jpg
+```
+
+These are the values returned by the `reflect.IsResource` function:
+
+```go-html-template {file="layouts/page.html"}
+{{ with resources.Get "a.json" }}
+ {{ reflect.IsResource . }} → true
+{{ end }}
+
+{{ with resources.Get "b.avif" }}
+ {{ reflect.IsResource . }} → true
+{{ end }}
+
+{{ with resources.Get "c.jpg" }}
+ {{ reflect.IsResource . }} → true
+{{ end }}
+```
+
+```go-html-template {file="layouts/page.html"}
+{{ with .Resources.Get "d.json" }}
+ {{ reflect.IsResource . }} → true
+{{ end }}
+
+{{ with .Resources.Get "e.avif" }}
+ {{ reflect.IsResource . }} → true
+{{ end }}
+
+{{ with .Resources.Get "f.jpg" }}
+ {{ reflect.IsResource . }} → true
+{{ end }}
+```
+
+```go-html-template {file="layouts/page.html"}
+{{ with site.GetPage "/example" }}
+ {{ reflect.IsResource . }} → true
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_functions_reflect_IsSite.md b/documents/markdown/hugo-docs/en_functions_reflect_IsSite.md
new file mode 100644
index 0000000..9170dd4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_reflect_IsSite.md
@@ -0,0 +1,23 @@
+---
+title: reflect.IsSite
+description: Reports whether the given value is a Site object.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [reflect.IsSite INPUT]
+---
+
+{{< new-in 0.154.0 />}}
+
+```go-html-template {file="layouts/page.html"}
+{{ with .Site }}
+ {{ reflect.IsSite . }} → true
+{{ end }}
+
+{{ with site.GetPage "/examples" }}
+ {{ reflect.IsSite . }} → false
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_functions_reflect_IsSlice.md b/documents/markdown/hugo-docs/en_functions_reflect_IsSlice.md
new file mode 100644
index 0000000..3a5c122
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_reflect_IsSlice.md
@@ -0,0 +1,17 @@
+---
+title: reflect.IsSlice
+description: Reports whether the given value is a slice.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [reflect.IsSlice INPUT]
+aliases: [/functions/reflect.isslice]
+---
+
+```go-html-template
+{{ reflect.IsSlice (slice 1 2 3) }} → true
+{{ reflect.IsSlice "yo" }} → false
+```
diff --git a/documents/markdown/hugo-docs/en_functions_reflect__index.md b/documents/markdown/hugo-docs/en_functions_reflect__index.md
new file mode 100644
index 0000000..58f00c3
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_reflect__index.md
@@ -0,0 +1,7 @@
+---
+title: Reflect functions
+linkTitle: reflect
+description: Use these functions to determine a value's data type.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_resources_ByType.md b/documents/markdown/hugo-docs/en_functions_resources_ByType.md
new file mode 100644
index 0000000..99e2b97
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_resources_ByType.md
@@ -0,0 +1,27 @@
+---
+title: resources.ByType
+description: Returns a collection of global resources of the given media type, or nil if none found.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: resource.Resources
+ signatures: [resources.ByType MEDIATYPE]
+---
+
+The [media type] is typically one of `image`, `text`, `audio`, `video`, or `application`.
+
+```go-html-template
+{{ range resources.ByType "image" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+> [!note]
+> This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
+>
+> For page resources, use the [`Resources.ByType`] method on a `Page` object.
+
+[`Resources.ByType`]: /methods/page/resources/
+[media type]: https://en.wikipedia.org/wiki/Media_type
diff --git a/documents/markdown/hugo-docs/en_functions_resources_Concat.md b/documents/markdown/hugo-docs/en_functions_resources_Concat.md
new file mode 100644
index 0000000..fe7226e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_resources_Concat.md
@@ -0,0 +1,26 @@
+---
+title: resources.Concat
+description: Returns a concatenated slice of resources.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: resource.Resource
+ signatures: ['resources.Concat TARGETPATH [RESOURCE...]']
+---
+
+The `resources.Concat` function returns a concatenated slice of resources, caching the result using the target path as its cache key. Each resource must have the same [media type].
+
+Hugo publishes the resource to the target path when you call its [`Publish`], [`Permalink`], or [`RelPermalink`] method.
+
+[media type]: https://en.wikipedia.org/wiki/Media_type
+[`publish`]: /methods/resource/publish/
+[`permalink`]: /methods/resource/permalink/
+[`relpermalink`]: /methods/resource/relpermalink/
+
+```go-html-template
+{{ $plugins := resources.Get "js/plugins.js" }}
+{{ $global := resources.Get "js/global.js" }}
+{{ $js := slice $plugins $global | resources.Concat "js/bundle.js" }}
+```
diff --git a/documents/markdown/hugo-docs/en_functions_resources_Copy.md b/documents/markdown/hugo-docs/en_functions_resources_Copy.md
new file mode 100644
index 0000000..220a3db
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_resources_Copy.md
@@ -0,0 +1,27 @@
+---
+title: resources.Copy
+description: Copies the given resource to the target path.
+categories: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: resource.Resource
+ signatures: [resources.Copy TARGETPATH RESOURCE]
+---
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ with resources.Copy "img/new-image-name.jpg" . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+The relative URL of the new published resource will be:
+
+```text
+/img/new-image-name.jpg
+```
+
+> [!note]
+> Use the `resources.Copy` function with global, page, and remote resources.
diff --git a/documents/markdown/hugo-docs/en_functions_resources_ExecuteAsTemplate.md b/documents/markdown/hugo-docs/en_functions_resources_ExecuteAsTemplate.md
new file mode 100644
index 0000000..2ffb9df
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_resources_ExecuteAsTemplate.md
@@ -0,0 +1,61 @@
+---
+title: resources.ExecuteAsTemplate
+description: Returns a resource created from a Go template, parsed and executed with the given context.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: resource.Resource
+ signatures: [resources.ExecuteAsTemplate TARGETPATH CONTEXT RESOURCE]
+---
+
+The `resources.ExecuteAsTemplate` function returns a resource created from a Go template, parsed and executed with the given context, caching the result using the target path as its cache key.
+
+Hugo publishes the resource to the target path when you call its [`Publish`], [`Permalink`], or [`RelPermalink`] methods.
+
+Let's say you have a CSS file that you wish to populate with values from your project configuration:
+
+```go-html-template {file="assets/css/template.css"}
+body {
+ background-color: {{ site.Params.style.bg_color }};
+ color: {{ site.Params.style.text_color }};
+}
+```
+
+And your project configuration contains:
+
+{{< code-toggle file=hugo >}}
+[params.style]
+bg_color = '#fefefe'
+text_color = '#222'
+{{< /code-toggle >}}
+
+Place this in your baseof.html template:
+
+```go-html-template
+{{ with resources.Get "css/template.css" }}
+ {{ with resources.ExecuteAsTemplate "css/main.css" $ . }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ end }}
+{{ end }}
+```
+
+The example above:
+
+1. Captures the template as a resource
+1. Executes the resource as a template, passing the current page in context
+1. Publishes the resource to css/main.css
+
+The result is:
+
+```css {file="public/css/main.css"}
+body {
+ background-color: #fefefe;
+ color: #222;
+}
+```
+
+[`publish`]: /methods/resource/publish/
+[`permalink`]: /methods/resource/permalink/
+[`relpermalink`]: /methods/resource/relpermalink/
diff --git a/documents/markdown/hugo-docs/en_functions_resources_Fingerprint.md b/documents/markdown/hugo-docs/en_functions_resources_Fingerprint.md
new file mode 100644
index 0000000..6757a0b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_resources_Fingerprint.md
@@ -0,0 +1,36 @@
+---
+title: resources.Fingerprint
+description: Cryptographically hashes the content of the given resource.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [fingerprint]
+ returnType: resource.Resource
+ signatures: ['resources.Fingerprint [ALGORITHM] RESOURCE']
+---
+
+```go-html-template
+{{ with resources.Get "js/main.js" }}
+ {{ with . | fingerprint "sha256" }}
+ <script src="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"></script>
+ {{ end }}
+{{ end }}
+```
+
+Hugo renders this to something like:
+
+```html
+<script src="/js/main.62e...df1.js" integrity="sha256-Yuh...rfE=" crossorigin="anonymous"></script>
+```
+
+Although most commonly used with CSS and JavaScript resources, you can use the `resources.Fingerprint` function with any resource type.
+
+The hash algorithm may be one of `md5`, `sha256` (default), `sha384`, or `sha512`.
+
+After cryptographically hashing the resource content:
+
+1. The values returned by the `.Permalink` and `.RelPermalink` methods include the hash sum
+1. The resource's `.Data.Integrity` method returns a [Subresource Integrity] (SRI) value consisting of the name of the hash algorithm, one hyphen, and the base64-encoded hash sum
+
+[Subresource Integrity]: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
diff --git a/documents/markdown/hugo-docs/en_functions_resources_FromString.md b/documents/markdown/hugo-docs/en_functions_resources_FromString.md
new file mode 100644
index 0000000..0ca7419
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_resources_FromString.md
@@ -0,0 +1,76 @@
+---
+title: resources.FromString
+description: Returns a resource created from a string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: resource.Resource
+ signatures: [resources.FromString TARGETPATH STRING]
+---
+
+The `resources.FromString` function returns a resource created from a string, caching the result using the target path as its cache key.
+
+Hugo publishes the resource to the target path when you call its [`Publish`], [`Permalink`], or [`RelPermalink`] methods.
+
+[`publish`]: /methods/resource/publish/
+[`permalink`]: /methods/resource/permalink/
+[`relpermalink`]: /methods/resource/relpermalink/
+
+Let's say you need to publish a file named "site.json" in the root of your `public` directory, containing the build date, the Hugo version used to build the site, and the date that the content was last modified. For example:
+
+```json
+{
+ "build_date": "2026-03-16T13:56:25-07:00",
+ "hugo_version": "0.158.0",
+ "last_modified": "2026-02-16T12:04:52-07:00"
+}
+```
+
+Place this in your baseof.html template:
+
+```go-html-template
+{{ if .IsHome }}
+ {{ $rfc3339 := "2006-01-02T15:04:05Z07:00" }}
+ {{ $m := dict
+ "hugo_version" hugo.Version
+ "build_date" (now.Format $rfc3339)
+ "last_modified" (site.Lastmod.Format $rfc3339)
+ }}
+ {{ $json := jsonify $m }}
+ {{ $r := resources.FromString "site.json" $json }}
+ {{ $r.Publish }}
+{{ end }}
+```
+
+The example above:
+
+1. Creates a map with the relevant key-value pairs using the [`dict`] function
+1. Encodes the map as a JSON string using the [`jsonify`] function
+1. Creates a resource from the JSON string using the `resources.FromString` function
+1. Publishes the file to the root of the `public` directory using the resource's `.Publish` method
+
+Combine `resources.FromString` with [`resources.ExecuteAsTemplate`] if your string contains template actions. Rewriting the example above:
+
+```go-html-template
+{{ if .IsHome }}
+ {{ $string := `
+ {{ $rfc3339 := "2006-01-02T15:04:05Z07:00" }}
+ {{ $m := dict
+ "hugo_version" hugo.Version
+ "build_date" (now.Format $rfc3339)
+ "last_modified" (site.Lastmod.Format $rfc3339)
+ }}
+ {{ $json := jsonify $m }}
+ `
+ }}
+ {{ $r := resources.FromString "" $string }}
+ {{ $r = $r | resources.ExecuteAsTemplate "site.json" . }}
+ {{ $r.Publish }}
+{{ end }}
+```
+
+[`dict`]: /functions/collections/dictionary/
+[`jsonify`]: /functions/encoding/jsonify/
+[`resources.ExecuteAsTemplate`]: /functions/resources/executeastemplate/
diff --git a/documents/markdown/hugo-docs/en_functions_resources_Get.md b/documents/markdown/hugo-docs/en_functions_resources_Get.md
new file mode 100644
index 0000000..db91f0a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_resources_Get.md
@@ -0,0 +1,24 @@
+---
+title: resources.Get
+description: Returns a global resource from the given path, or nil if none found.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: resource.Resource
+ signatures: [resources.Get PATH]
+---
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+> [!note]
+> This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
+>
+> For page resources, use the [`Resources.Get`] method on a `Page` object.
+
+[`Resources.Get`]: /methods/page/resources/
diff --git a/documents/markdown/hugo-docs/en_functions_resources_GetMatch.md b/documents/markdown/hugo-docs/en_functions_resources_GetMatch.md
new file mode 100644
index 0000000..bf6a954
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_resources_GetMatch.md
@@ -0,0 +1,28 @@
+---
+title: resources.GetMatch
+description: Returns the first global resource from paths matching the given glob pattern, or nil if none found.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: resource.Resource
+ signatures: [resources.GetMatch PATTERN]
+---
+
+```go-html-template
+{{ with resources.GetMatch "images/*.jpg" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+> [!note]
+> This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
+>
+> For page resources, use the [`Resources.GetMatch`] method on a `Page` object.
+
+Hugo determines a match using a case-insensitive [glob pattern](g).
+
+{{% include "/_common/glob-patterns.md" %}}
+
+[`Resources.GetMatch`]: /methods/page/resources/
diff --git a/documents/markdown/hugo-docs/en_functions_resources_GetRemote.md b/documents/markdown/hugo-docs/en_functions_resources_GetRemote.md
new file mode 100644
index 0000000..caa9cc1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_resources_GetRemote.md
@@ -0,0 +1,240 @@
+---
+title: resources.GetRemote
+description: Returns a remote resource from the given URL, or nil if none found.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: resource.Resource
+ signatures: ['resources.GetRemote URL [OPTIONS]']
+---
+
+{{< new-in 0.141.0 >}}
+The `Err` method on the returned resource was removed in v0.141.0.
+
+Use the [`try`](/functions/go-template/try) statement instead, as shown in the [error handling](#error-handling) example below.
+{{< /new-in >}}
+
+```go-html-template
+{{ $url := "https://example.org/images/a.jpg" }}
+{{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else with .Value }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+ {{ end }}
+{{ end }}
+```
+
+## Options
+
+The `resources.GetRemote` function takes an optional map of options.
+
+body
+: (`string`) The data you want to transmit to the server.
+
+headers
+: (`map[string][]string`) The collection of key-value pairs that provide additional information about the request.
+
+key
+: (`string`) The cache key. Hugo derives the default value from the URL and options map. See [caching](#caching).
+
+method
+: (`string`) The action to perform on the requested resource, typically one of `GET`, `POST`, or `HEAD`.
+
+responseHeaders
+: {{< new-in 0.143.0 />}}
+: (`[]string`) The headers to extract from the server's response, accessible through the resource's [`Data.Headers`][] method. Header name matching is case-insensitive.
+
+timeout
+: {{< new-in 0.157.0 />}}
+: (`string`) The duration after which the request is cancelled if it does not complete, expressed as a [duration](g). If not specified, the request will timeout after 2 minutes.
+
+## Options examples
+
+> [!note]
+> For brevity, the examples below do not include [error handling][].
+
+To include a header:
+
+```go-html-template
+{{ $url := "https://example.org/api" }}
+{{ $opts := dict
+ "headers" (dict "Authorization" "Bearer abcd")
+}}
+{{ $resource := resources.GetRemote $url $opts }}
+```
+
+To specify more than one value for the same header key, use a slice:
+
+```go-html-template
+{{ $url := "https://example.org/api" }}
+{{ $opts := dict
+ "headers" (dict "X-List" (slice "a" "b" "c"))
+}}
+{{ $resource := resources.GetRemote $url $opts }}
+```
+
+To post data:
+
+```go-html-template
+{{ $url := "https://example.org/api" }}
+{{ $opts := dict
+ "method" "post"
+ "body" `{"complete": true}`
+ "headers" (dict "Content-Type" "application/json")
+}}
+{{ $resource := resources.GetRemote $url $opts }}
+```
+
+To override the default cache key:
+
+```go-html-template
+{{ $url := "https://example.org/images/a.jpg" }}
+{{ $opts := dict
+ "key" (print $url (now.Format "2006-01-02"))
+}}
+{{ $resource := resources.GetRemote $url $opts }}
+```
+
+To extract specific headers from the server's response:
+
+```go-html-template
+{{ $url := "https://example.org/images/a.jpg" }}
+{{ $opts := dict
+ "method" "HEAD"
+ "responseHeaders" (slice "X-Frame-Options" "Server")
+}}
+{{ $resource := resources.GetRemote $url $opts }}
+```
+
+Use the `timeout` option to prevent slow external requests from stalling the build when fetching multiple remote feeds:
+
+```go-html-template
+{{ $url := "https://example.org/feed.rss" }}
+{{ $opts := dict "timeout" "10s" }}
+{{ with try (resources.GetRemote $url $opts) }}
+ {{ with .Err }}
+ {{ warnf "Failed to fetch feed: %s" . }}
+ {{ else with .Value }}
+ {{ $data = . | transform.Unmarshal }}
+ {{ end }}
+{{ end }}
+```
+
+## Remote data
+
+When retrieving remote data, use the [`transform.Unmarshal`][] function to [unmarshal](g) the response.
+
+```go-html-template
+{{ $data := dict }}
+{{ $url := "https://example.org/books.json" }}
+{{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else with .Value }}
+ {{ $data = . | transform.Unmarshal }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+ {{ end }}
+{{ end }}
+```
+
+> [!note]
+> When retrieving remote data, a misconfigured server may send a response header with an incorrect [Content-Type][]. For example, the server may set the Content-Type header to `application/octet-stream` instead of `application/json`.
+>
+> In these cases, pass the resource `Content` through the `transform.Unmarshal` function instead of passing the resource itself. For example, in the above, do this instead:
+>
+> `{{ $data = .Content | transform.Unmarshal }}`
+
+## Error handling
+
+Use the [`try`][] statement to capture HTTP request errors. If you do not handle the error yourself, Hugo will fail the build.
+
+> [!note]
+> Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil.
+
+```go-html-template
+{{ $url := "https://broken-example.org/images/a.jpg" }}
+{{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else with .Value }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+ {{ end }}
+{{ end }}
+```
+
+To log an error as a warning instead of an error:
+
+```go-html-template
+{{ $url := "https://broken-example.org/images/a.jpg" }}
+{{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ warnf "%s" . }}
+ {{ else with .Value }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ else }}
+ {{ warnf "Unable to get remote resource %q" $url }}
+ {{ end }}
+{{ end }}
+```
+
+## HTTP response
+
+The [`Data`][] method on a resource returned by the `resources.GetRemote` function returns information from the HTTP response.
+
+## Caching
+
+Resources returned from `resources.GetRemote` are cached to disk. See [configure file caches][] for details.
+
+By default, Hugo derives the cache key from the arguments passed to the function. Override the cache key by setting a `key` in the options map. Use this approach to have more control over how often Hugo fetches a remote resource.
+
+```go-html-template
+{{ $url := "https://example.org/images/a.jpg" }}
+{{ $cacheKey := print $url (now.Format "2006-01-02") }}
+{{ $opts := dict "key" $cacheKey }}
+{{ $resource := resources.GetRemote $url $opts }}
+```
+
+## Security
+
+To protect against malicious intent, the `resources.GetRemote` function inspects the server response including:
+
+- The [Content-Type][] in the response header
+- The file extension, if any
+- The content itself
+
+If Hugo is unable to resolve the media type to an entry in its [allowlist][], the function throws an error:
+
+```text
+ERROR error calling resources.GetRemote: failed to resolve media type...
+```
+
+For example, you will see the error above if you attempt to download an executable.
+
+Although the allowlist contains entries for common media types, you may encounter situations where Hugo is unable to resolve the media type of a file that you know to be safe. In these situations, edit your project configuration to add the media type to the allowlist. For example:
+
+{{< code-toggle file=hugo >}}
+[security.http]
+mediaTypes = ['^image/avif$','^application/vnd\.api\+json$']
+{{< /code-toggle >}}
+
+Note that the entry above is:
+
+- An _addition_ to the allowlist; it does not _replace_ the allowlist
+- An array of [regular expressions](g)
+
+[`Data.Headers`]: /methods/resource/data/#headers
+[`Data`]: /methods/resource/data/
+[`transform.Unmarshal`]: /functions/transform/unmarshal/
+[`try`]: /functions/go-template/try
+[allowlist]: https://en.wikipedia.org/wiki/Whitelist
+[configure file caches]: /configuration/caches/
+[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
+[error handling]: #error-handling
diff --git a/documents/markdown/hugo-docs/en_functions_resources_Match.md b/documents/markdown/hugo-docs/en_functions_resources_Match.md
new file mode 100644
index 0000000..6c7d836
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_resources_Match.md
@@ -0,0 +1,29 @@
+---
+title: resources.Match
+description: Returns a collection of global resources from paths matching the given glob pattern, or nil if none found.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: resource.Resources
+ signatures: [resources.Match PATTERN]
+---
+
+```go-html-template
+{{ range resources.Match "images/*.jpg" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+> [!note]
+> This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
+>
+> For page resources, use the [`Resources.Match`] method on a `Page` object.
+
+Hugo determines a match using a case-insensitive [glob pattern].
+
+{{% include "/_common/glob-patterns.md" %}}
+
+[`Resources.Match`]: /methods/page/resources/
+[glob pattern]: https://github.com/gobwas/glob#example
diff --git a/documents/markdown/hugo-docs/en_functions_resources_Minify.md b/documents/markdown/hugo-docs/en_functions_resources_Minify.md
new file mode 100644
index 0000000..183e667
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_resources_Minify.md
@@ -0,0 +1,18 @@
+---
+title: resources.Minify
+description: Minifies the given resource.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [minify]
+ returnType: resource.Resource
+ signatures: [resources.Minify RESOURCE]
+---
+
+```go-html-template
+{{ $css := resources.Get "css/main.css" }}
+{{ $style := $css | minify }}
+```
+
+Any CSS, JS, JSON, HTML, SVG, or XML resource can be minified using resources.Minify which takes for argument the resource object.
diff --git a/documents/markdown/hugo-docs/en_functions_resources_PostProcess.md b/documents/markdown/hugo-docs/en_functions_resources_PostProcess.md
new file mode 100644
index 0000000..f20bed7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_resources_PostProcess.md
@@ -0,0 +1,148 @@
+---
+title: resources.PostProcess
+description: Processes the given resource after the build.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: postpub.PostPublishedResource
+ signatures: [resources.PostProcess RESOURCE]
+---
+
+The `resources.PostProcess` function delays resource transformation steps until the build is complete, primarily for tasks like removing unused CSS rules.
+
+## Example
+
+In this example, after the build is complete, Hugo will:
+
+1. Purge unused CSS using the [PurgeCSS] plugin for [PostCSS]
+1. Add vendor prefixes to CSS rules using the [Autoprefixer] plugin for PostCSS
+1. [Minify] the CSS
+1. [Fingerprint] the CSS
+
+Step 1
+: Install [Node.js].
+
+Step 2
+: Install the required Node packages in the root of your project:
+
+ ```sh {copy=true}
+ npm i -D postcss postcss-cli autoprefixer @fullhuman/postcss-purgecss
+ ```
+
+Step 3
+: Enable creation of the `hugo_stats.json` file when building the site. If you are only using this for the production build, consider placing it below [`config/production`].
+
+ {{< code-toggle file=hugo copy=true >}}
+ [build.buildStats]
+ enable = true
+ {{< /code-toggle >}}
+
+ See the [configure build] documentation for details and options.
+
+Step 4
+: Create a PostCSS configuration file in the root of your project.
+
+ ```js {file="postcss.config.js" copy=true}
+ const autoprefixer = require('autoprefixer');
+ const purgeCSSPlugin = require('@fullhuman/postcss-purgecss').default;
+
+ const purgecss = purgeCSSPlugin({
+ content: ['./hugo_stats.json'],
+ defaultExtractor: content => {
+ const els = JSON.parse(content).htmlElements;
+ return [
+ ...(els.tags || []),
+ ...(els.classes || []),
+ ...(els.ids || []),
+ ];
+ },
+ // https://purgecss.com/safelisting.html
+ safelist: []
+ });
+
+ module.exports = {
+ plugins: [
+ process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null,
+ autoprefixer,
+ ]
+ };
+ ```
+
+ > [!note]
+ > If you are a Windows user, and the path to your project contains a space, you must place the PostCSS configuration within the package.json file. See [this example] and issue [#7333].
+
+Step 5
+: Place your CSS file within the `assets/css` directory.
+
+Step 6
+: If the current environment is not `development`, process the resource with PostCSS:
+
+ ```go-html-template {copy=true}
+ {{ with resources.Get "css/main.css" }}
+ {{ if hugo.IsDevelopment }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ else }}
+ {{ with . | postCSS | minify | fingerprint | resources.PostProcess }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
+ {{ end }}
+ {{ end }}
+ ```
+
+## Environment variables
+
+Hugo passes the environment variables below to PostCSS, allowing you to do something like:
+
+```js
+process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null,
+```
+
+PWD
+: The absolute path to the project working directory.
+
+HUGO_ENVIRONMENT
+: The current Hugo environment, set with the `--environment` command line flag.
+Default is `production` for `hugo build` and `development` for `hugo server`.
+
+HUGO_PUBLISHDIR
+: The absolute path to the publish directory, typically `public`. This value points to a directory on disk, even when rendering to memory with the `--renderToMemory` command line flag.
+
+HUGO_FILE_X
+: Hugo automatically mounts the following files from your project's root directory under `assets/_jsconfig`:
+
+- `babel.config.js`
+- `postcss.config.js`
+- `tailwind.config.js`
+
+For each file, Hugo creates a corresponding environment variable named `HUGO_FILE_:filename:`, where `:filename:` is the uppercase version of the filename with periods replaced by underscores. This allows you to access these files within your JavaScript, for example:
+
+```js
+let tailwindConfig = process.env.HUGO_FILE_TAILWIND_CONFIG_JS || './tailwind.config.js';
+```
+
+## Limitations
+
+Do not use `resources.PostProcess` when running Hugo's built-in development server. The examples above specifically prevent this by verifying that the current environment is not `development`.
+
+The `resources.PostProcess` function only works within templates that produce HTML files.
+
+You cannot manipulate the values returned from the resource's methods. For example, the `strings.ToUpper` function in this example will not work as expected:
+
+```go-html-template
+{{ $css := resources.Get "css/main.css" }}
+{{ $css = $css | css.PostCSS | minify | fingerprint | resources.PostProcess }}
+{{ $css.RelPermalink | strings.ToUpper }}
+```
+
+[#7333]: https://github.com/gohugoio/hugo/issues/7333
+[`config/production`]: /configuration/introduction/#configuration-directory
+[Autoprefixer]: https://github.com/postcss/autoprefixer
+[configure build]: /configuration/build/
+[Fingerprint]: /functions/resources/fingerprint/
+[Minify]: /functions/resources/minify/
+[Node.js]: https://nodejs.org/en
+[PostCSS]: https://postcss.org/
+[PurgeCSS]: https://github.com/FullHuman/purgecss
+[this example]: https://github.com/postcss/postcss-load-config#packagejson
diff --git a/documents/markdown/hugo-docs/en_functions_resources__index.md b/documents/markdown/hugo-docs/en_functions_resources__index.md
new file mode 100644
index 0000000..030cafd
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_resources__index.md
@@ -0,0 +1,7 @@
+---
+title: Resource functions
+linkTitle: resources
+description: Use these functions to work with resources.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_safe_CSS.md b/documents/markdown/hugo-docs/en_functions_safe_CSS.md
new file mode 100644
index 0000000..12ebbf8
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_safe_CSS.md
@@ -0,0 +1,62 @@
+---
+title: safe.CSS
+description: Declares the given string as a safe CSS string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [safeCSS]
+ returnType: template.CSS
+ signatures: [safe.CSS INPUT]
+aliases: [/functions/safecss]
+---
+
+## Introduction
+
+{{% include "/_common/functions/go-html-template-package.md" %}}
+
+## Usage
+
+Use the `safe.CSS` function to encapsulate known safe content that matches any of:
+
+1. The CSS3 stylesheet production, such as `p { color: purple }`.
+1. The CSS3 rule production, such as `a[href=~"https:"].foo#bar`.
+1. CSS3 declaration productions, such as `color: red; margin: 2px`.
+1. The CSS3 value production, such as `rgba(0, 0, 255, 127)`.
+
+Use of this type presents a security risk: the encapsulated content should come from a trusted source, as it will be included verbatim in the template output.
+
+See the [Go documentation] for details.
+
+## Example
+
+Without a safe declaration:
+
+```go-html-template
+{{ $style := "color: red;" }}
+<p style="{{ $style }}">foo</p>
+```
+
+Hugo renders the above to:
+
+```html
+<p style="ZgotmplZ">foo</p>
+```
+
+> [!note]
+> `ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context at runtime.
+
+To declare the string as safe:
+
+```go-html-template
+{{ $style := "color: red;" }}
+<p style="{{ $style | safeCSS }}">foo</p>
+```
+
+Hugo renders the above to:
+
+```html
+<p style="color: red;">foo</p>
+```
+
+[Go documentation]: https://pkg.go.dev/html/template#CSS
diff --git a/documents/markdown/hugo-docs/en_functions_safe_HTML.md b/documents/markdown/hugo-docs/en_functions_safe_HTML.md
new file mode 100644
index 0000000..25ffb33
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_safe_HTML.md
@@ -0,0 +1,54 @@
+---
+title: safe.HTML
+description: Declares the given string as a safeHTML string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [safeHTML]
+ returnType: template.HTML
+ signatures: [safe.HTML INPUT]
+aliases: [/functions/safehtml]
+---
+
+## Introduction
+
+{{% include "/_common/functions/go-html-template-package.md" %}}
+
+## Usage
+
+Use the `safe.HTML` function to encapsulate a known safe HTML document fragment. It should not be used for HTML from a third-party, or HTML with unclosed tags or comments.
+
+Use of this type presents a security risk: the encapsulated content should come from a trusted source, as it will be included verbatim in the template output.
+
+See the [Go documentation] for details.
+
+[Go documentation]: https://pkg.go.dev/html/template#HTML
+
+## Example
+
+Without a safe declaration:
+
+```go-html-template
+{{ $html := "<em>emphasized</em>" }}
+{{ $html }}
+```
+
+Hugo renders the above to:
+
+```html
+<em>emphasized</em>
+```
+
+To declare the string as safe:
+
+```go-html-template
+{{ $html := "<em>emphasized</em>" }}
+{{ $html | safeHTML }}
+```
+
+Hugo renders the above to:
+
+```html
+<em>emphasized</em>
+```
diff --git a/documents/markdown/hugo-docs/en_functions_safe_HTMLAttr.md b/documents/markdown/hugo-docs/en_functions_safe_HTMLAttr.md
new file mode 100644
index 0000000..7cfefdf
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_safe_HTMLAttr.md
@@ -0,0 +1,60 @@
+---
+title: safe.HTMLAttr
+description: Declares the given key-value pair as a safe HTML attribute.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [safeHTMLAttr]
+ returnType: template.HTMLAttr
+ signatures: [safe.HTMLAttr INPUT]
+aliases: [/functions/safehtmlattr]
+---
+
+## Introduction
+
+{{% include "/_common/functions/go-html-template-package.md" %}}
+
+## Usage
+
+Use the `safe.HTMLAttr` function to encapsulate an HTML attribute from a trusted source.
+
+Use of this type presents a security risk: the encapsulated content should come from a trusted source, as it will be included verbatim in the template output.
+
+See the [Go documentation] for details.
+
+[Go documentation]: https://pkg.go.dev/html/template#HTMLAttr
+
+## Example
+
+Without a safe declaration:
+
+```go-html-template
+{{ with .Date }}
+ {{ $humanDate := time.Format "2 Jan 2006" . }}
+ {{ $machineDate := time.Format "2006-01-02T15:04:05-07:00" . }}
+ <time datetime="{{ $machineDate }}">{{ $humanDate }}</time>
+{{ end }}
+```
+
+Hugo renders the above to:
+
+```html
+<time datetime="2024-05-26T07:19:55+02:00">26 May 2024</time>
+```
+
+To declare the key-value pair as safe:
+
+```go-html-template
+{{ with .Date }}
+ {{ $humanDate := time.Format "2 Jan 2006" . }}
+ {{ $machineDate := time.Format "2006-01-02T15:04:05-07:00" . }}
+ <time {{ printf "datetime=%q" $machineDate | safeHTMLAttr }}>{{ $humanDate }}</time>
+{{ end }}
+```
+
+Hugo renders the above to:
+
+```html
+<time datetime="2024-05-26T07:19:55+02:00">26 May 2024</time>
+```
diff --git a/documents/markdown/hugo-docs/en_functions_safe_JS.md b/documents/markdown/hugo-docs/en_functions_safe_JS.md
new file mode 100644
index 0000000..0c4d900
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_safe_JS.md
@@ -0,0 +1,60 @@
+---
+title: safe.JS
+description: Declares the given string as a safe JavaScript expression.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [safeJS]
+ returnType: template.JS
+ signatures: [safe.JS INPUT]
+aliases: [/functions/safejs]
+---
+
+## Introduction
+
+{{% include "/_common/functions/go-html-template-package.md" %}}
+
+## Usage
+
+Use the `safe.JS` function to encapsulate a known safe EcmaScript5 Expression.
+
+Template authors are responsible for ensuring that typed expressions do not break the intended precedence and that there is no statement/expression ambiguity as when passing an expression like `{ foo: bar() }\n['foo']()`, which is both a valid Expression and a valid Program with a very different meaning.
+
+Use of this type presents a security risk: the encapsulated content should come from a trusted source, as it will be included verbatim in the template output.
+
+Using the `safe.JS` function to include valid but untrusted JSON is not safe. A safe alternative is to parse the JSON with the [`transform.Unmarshal`] function and then pass the resultant object into the template, where it will be converted to sanitized JSON when presented in a JavaScript context.
+
+[`transform.Unmarshal`]: /functions/transform/unmarshal/
+
+See the [Go documentation] for details.
+
+[Go documentation]: https://pkg.go.dev/html/template#JS
+
+## Example
+
+Without a safe declaration:
+
+```go-html-template
+{{ $js := "x + y" }}
+<script>const a = {{ $js }}</script>
+```
+
+Hugo renders the above to:
+
+```html
+<script>const a = "x + y"</script>
+```
+
+To declare the string as safe:
+
+```go-html-template
+{{ $js := "x + y" }}
+<script>const a = {{ $js | safeJS }}</script>
+```
+
+Hugo renders the above to:
+
+```html
+<script>const a = x + y</script>
+```
diff --git a/documents/markdown/hugo-docs/en_functions_safe_JSStr.md b/documents/markdown/hugo-docs/en_functions_safe_JSStr.md
new file mode 100644
index 0000000..81946a1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_safe_JSStr.md
@@ -0,0 +1,62 @@
+---
+title: safe.JSStr
+description: Declares the given string as a safe JavaScript string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [safeJSStr]
+ returnType: template.JSStr
+ signatures: [safe.JSStr INPUT]
+aliases: [/functions/safejsstr]
+---
+
+## Introduction
+
+{{% include "/_common/functions/go-html-template-package.md" %}}
+
+## Usage
+
+Use the `safe.JSStr` function to encapsulate a sequence of characters meant to be embedded between quotes in a JavaScript expression.
+
+Use of this type presents a security risk: the encapsulated content should come from a trusted source, as it will be included verbatim in the template output.
+
+See the [Go documentation] for details.
+
+[Go documentation]: https://pkg.go.dev/html/template#JSStr
+
+## Example
+
+Without a safe declaration:
+
+```go-html-template
+{{ $title := "Lilo & Stitch" }}
+<script>
+ const a = "Title: " + {{ $title }};
+</script>
+```
+
+Hugo renders the above to:
+
+```html
+<script>
+ const a = "Title: " + "Lilo \u0026 Stitch";
+</script>
+```
+
+To declare the string as safe:
+
+```go-html-template
+{{ $title := "Lilo & Stitch" }}
+<script>
+ const a = "Title: " + {{ $title | safeJSStr }};
+</script>
+```
+
+Hugo renders the above to:
+
+```html
+<script>
+ const a = "Title: " + "Lilo & Stitch";
+</script>
+```
diff --git a/documents/markdown/hugo-docs/en_functions_safe_URL.md b/documents/markdown/hugo-docs/en_functions_safe_URL.md
new file mode 100644
index 0000000..44bed80
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_safe_URL.md
@@ -0,0 +1,61 @@
+---
+title: safe.URL
+description: Declares the given string as a safe URL or URL substring.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [safeURL]
+ returnType: template.URL
+ signatures: [safe.URL INPUT]
+aliases: [/functions/safeurl]
+---
+
+## Introduction
+
+{{% include "/_common/functions/go-html-template-package.md" %}}
+
+## Usage
+
+Use the `safe.URL` function to encapsulate a known safe URL or URL substring. Schemes other than the following are considered unsafe:
+
+- `http:`
+- `https:`
+- `mailto:`
+
+Use of this type presents a security risk: the encapsulated content should come from a trusted source, as it will be included verbatim in the template output.
+
+See the [Go documentation] for details.
+
+## Example
+
+Without a safe declaration:
+
+```go-html-template
+{{ $href := "irc://irc.freenode.net/#golang" }}
+<a href="{{ $href }}">IRC</a>
+```
+
+Hugo renders the above to:
+
+```html
+<a href="#ZgotmplZ">IRC</a>
+```
+
+> [!note]
+> `ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context at runtime.
+
+To declare the string as safe:
+
+```go-html-template
+{{ $href := "irc://irc.freenode.net/#golang" }}
+<a href="{{ $href | safeURL }}">IRC</a>
+```
+
+Hugo renders the above to:
+
+```html
+<a href="irc://irc.freenode.net/#golang">IRC</a>
+```
+
+[Go documentation]: https://pkg.go.dev/html/template#URL
diff --git a/documents/markdown/hugo-docs/en_functions_safe__index.md b/documents/markdown/hugo-docs/en_functions_safe__index.md
new file mode 100644
index 0000000..8d5697b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_safe__index.md
@@ -0,0 +1,7 @@
+---
+title: Safe functions
+linkTitle: safe
+description: Use these functions to declare a value as safe in the context of Go's html/template package.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_strings_Chomp.md b/documents/markdown/hugo-docs/en_functions_strings_Chomp.md
new file mode 100644
index 0000000..1ff2b7f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_Chomp.md
@@ -0,0 +1,22 @@
+---
+title: strings.Chomp
+description: Returns the given string, removing all trailing newline characters and carriage returns.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [chomp]
+ returnType: any
+ signatures: [strings.Chomp STRING]
+aliases: [/functions/chomp]
+---
+
+If the argument is of type `template.HTML`, returns `template.HTML`, else returns a `string`.
+
+```go-html-template
+{{ chomp "foo\n" }} → foo
+{{ chomp "foo\n\n" }} → foo
+
+{{ chomp "foo\r\n" }} → foo
+{{ chomp "foo\r\n\r\n" }} → foo
+```
diff --git a/documents/markdown/hugo-docs/en_functions_strings_Contains.md b/documents/markdown/hugo-docs/en_functions_strings_Contains.md
new file mode 100644
index 0000000..e0e3b08
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_Contains.md
@@ -0,0 +1,22 @@
+---
+title: strings.Contains
+description: Reports whether the given string contains the given substring.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [strings.Contains STRING SUBSTRING]
+aliases: [/functions/strings.contains]
+---
+
+```go-html-template
+{{ strings.Contains "Hugo" "go" }} → true
+```
+
+The check is case sensitive:
+
+```go-html-template
+{{ strings.Contains "Hugo" "Go" }} → false
+```
diff --git a/documents/markdown/hugo-docs/en_functions_strings_ContainsAny.md b/documents/markdown/hugo-docs/en_functions_strings_ContainsAny.md
new file mode 100644
index 0000000..521ff34
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_ContainsAny.md
@@ -0,0 +1,22 @@
+---
+title: strings.ContainsAny
+description: Reports whether the given string contains any character within the given set.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [strings.ContainsAny STRING SET]
+aliases: [/functions/strings.containsany]
+---
+
+```go-html-template
+{{ strings.ContainsAny "Hugo" "gm" }} → true
+```
+
+The check is case sensitive:
+
+```go-html-template
+{{ strings.ContainsAny "Hugo" "Gm" }} → false
+```
diff --git a/documents/markdown/hugo-docs/en_functions_strings_ContainsNonSpace.md b/documents/markdown/hugo-docs/en_functions_strings_ContainsNonSpace.md
new file mode 100644
index 0000000..7b8dcb7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_ContainsNonSpace.md
@@ -0,0 +1,22 @@
+---
+title: strings.ContainsNonSpace
+description: Reports whether the given string contains any non-space characters as defined by Unicode.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [strings.ContainsNonSpace STRING]
+aliases: [/functions/strings.containsnonspace]
+---
+
+Whitespace characters include `\t`, `\n`, `\v`, `\f`, `\r`, and characters in the [Unicode Space Separator] category.
+
+[Unicode Space Separator]: https://www.compart.com/en/unicode/category/Zs
+
+```go-html-template
+{{ strings.ContainsNonSpace "\n" }} → false
+{{ strings.ContainsNonSpace " " }} → false
+{{ strings.ContainsNonSpace "\n abc" }} → true
+```
diff --git a/documents/markdown/hugo-docs/en_functions_strings_Count.md b/documents/markdown/hugo-docs/en_functions_strings_Count.md
new file mode 100644
index 0000000..76378b2
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_Count.md
@@ -0,0 +1,21 @@
+---
+title: strings.Count
+description: Returns the number of non-overlapping instances of the given substring within the given string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: int
+ signatures: [strings.Count SUBSTR STRING]
+aliases: [/functions/strings.count]
+---
+
+If `SUBSTR` is an empty string, this function returns 1 plus the number of Unicode code points in `STRING`.
+
+```go-html-template
+{{ "aaabaab" | strings.Count "a" }} → 5
+{{ "aaabaab" | strings.Count "aa" }} → 2
+{{ "aaabaab" | strings.Count "aaa" }} → 1
+{{ "aaabaab" | strings.Count "" }} → 8
+```
diff --git a/documents/markdown/hugo-docs/en_functions_strings_CountRunes.md b/documents/markdown/hugo-docs/en_functions_strings_CountRunes.md
new file mode 100644
index 0000000..3ac7baa
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_CountRunes.md
@@ -0,0 +1,20 @@
+---
+title: strings.CountRunes
+description: Returns the number of runes in the given string excluding whitespace.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [countrunes]
+ returnType: int
+ signatures: [strings.CountRunes STRING]
+aliases: [/functions/countrunes]
+---
+
+In contrast with the [`strings.RuneCount`] function, which counts every rune in a string, `strings.CountRunes` excludes whitespace.
+
+```go-html-template
+{{ "Hello, 世界" | strings.CountRunes }} → 8
+```
+
+[`strings.RuneCount`]: /functions/strings/runecount/
diff --git a/documents/markdown/hugo-docs/en_functions_strings_CountWords.md b/documents/markdown/hugo-docs/en_functions_strings_CountWords.md
new file mode 100644
index 0000000..14939a7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_CountWords.md
@@ -0,0 +1,16 @@
+---
+title: strings.CountWords
+description: Returns the number of words in the given string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [countwords]
+ returnType: int
+ signatures: [strings.CountWords STRING]
+aliases: [/functions/countwords]
+---
+
+```go-html-template
+{{ "Hugo is a static site generator." | countwords }} → 6
+```
diff --git a/documents/markdown/hugo-docs/en_functions_strings_Diff_index.md b/documents/markdown/hugo-docs/en_functions_strings_Diff_index.md
new file mode 100644
index 0000000..31d348e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_Diff_index.md
@@ -0,0 +1,31 @@
+---
+title: strings.Diff
+description: Returns an anchored diff of the two texts OLD and NEW in the unified diff format. If OLD and NEW are identical, returns an empty string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [strings.Diff OLDNAME OLD NEWNAME NEW]
+---
+
+Use `strings.Diff` to compare two strings and render a highlighted diff:
+
+```go-html-template
+{{ $want := `
+<p>The product of 6 and 7 is 42.</p>
+<p>The product of 7 and 6 is 42.</p>
+`}}
+
+{{ $got := `
+<p>The product of 6 and 7 is 42.</p>
+<p>The product of 7 and 6 is 13.</p>
+`}}
+
+{{ $diff := strings.Diff "want" $want "got" $got }}
+{{ transform.Highlight $diff "diff" }}
+```
+
+Rendered:
+
+
diff --git a/documents/markdown/hugo-docs/en_functions_strings_FindRESubmatch.md b/documents/markdown/hugo-docs/en_functions_strings_FindRESubmatch.md
new file mode 100644
index 0000000..d039607
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_FindRESubmatch.md
@@ -0,0 +1,86 @@
+---
+title: strings.FindRESubmatch
+description: Returns a slice of all successive matches of the regular expression. Each element is a slice of strings holding the text of the leftmost match of the regular expression and the matches, if any, of its subexpressions.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [findRESubmatch]
+ returnType: '[][]string'
+ signatures: ['strings.FindRESubmatch PATTERN INPUT [LIMIT]']
+aliases: [/functions/findresubmatch]
+---
+
+By default, `findRESubmatch` finds all matches. You can limit the number of matches with an optional LIMIT argument. A return value of nil indicates no match.
+
+{{% include "/_common/functions/regular-expressions.md" %}}
+
+## Demonstrative examples
+
+```go-html-template
+{{ findRESubmatch `a(x*)b` "-ab-" }} → [["ab" ""]]
+{{ findRESubmatch `a(x*)b` "-axxb-" }} → [["axxb" "xx"]]
+{{ findRESubmatch `a(x*)b` "-ab-axb-" }} → [["ab" ""] ["axb" "x"]]
+{{ findRESubmatch `a(x*)b` "-axxb-ab-" }} → [["axxb" "xx"] ["ab" ""]]
+{{ findRESubmatch `a(x*)b` "-axxb-ab-" 1 }} → [["axxb" "xx"]]
+```
+
+## Practical example
+
+This Markdown:
+
+```text
+- [Example](https://example.org)
+- [Hugo](https://gohugo.io)
+```
+
+Produces this HTML:
+
+```html
+<ul>
+ <li><a href="https://example.org">Example</a></li>
+ <li><a href="https://gohugo.io">Hugo</a></li>
+</ul>
+```
+
+To match the anchor elements, capturing the link destination and text:
+
+```go-html-template
+{{ $regex := `<a\s*href="(.+?)">(.+?)</a>` }}
+{{ $matches := findRESubmatch $regex .Content }}
+```
+
+Viewed as JSON, the data structure of `$matches` in the code above is:
+
+```json
+[
+ [
+ "<a href=\"https://example.org\"></a>Example</a>",
+ "https://example.org",
+ "Example"
+ ],
+ [
+ "<a href=\"https://gohugo.io\">Hugo</a>",
+ "https://gohugo.io",
+ "Hugo"
+ ]
+]
+```
+
+To render the `href` attributes:
+
+```go-html-template
+{{ range $matches }}
+ {{ index . 1 }}
+{{ end }}
+```
+
+Result:
+
+```text
+https://example.org
+https://gohugo.io
+```
+
+> [!note]
+> You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin.
diff --git a/documents/markdown/hugo-docs/en_functions_strings_FindRe.md b/documents/markdown/hugo-docs/en_functions_strings_FindRe.md
new file mode 100644
index 0000000..45129ec
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_FindRe.md
@@ -0,0 +1,32 @@
+---
+title: strings.FindRE
+description: Returns a slice of strings that match the regular expression.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [findRE]
+ returnType: '[]string'
+ signatures: ['strings.FindRE PATTERN INPUT [LIMIT]']
+aliases: [/functions/findre]
+---
+By default, `findRE` finds all matches. You can limit the number of matches with an optional LIMIT argument.
+
+{{% include "/_common/functions/regular-expressions.md" %}}
+
+This example returns a slice of all second level headings (`h2` elements) within the rendered `.Content`:
+
+```go-html-template
+{{ findRE `(?s)<h2.*?>.*?</h2>` .Content }}
+```
+
+The `s` flag causes `.` to match `\n` as well, allowing us to find an `h2` element that contains newlines.
+
+To limit the number of matches to one:
+
+```go-html-template
+{{ findRE `(?s)<h2.*?>.*?</h2>` .Content 1 }}
+```
+
+> [!note]
+> You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin.
diff --git a/documents/markdown/hugo-docs/en_functions_strings_FirstUpper.md b/documents/markdown/hugo-docs/en_functions_strings_FirstUpper.md
new file mode 100644
index 0000000..41bf1f7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_FirstUpper.md
@@ -0,0 +1,16 @@
+---
+title: strings.FirstUpper
+description: Returns the given string, capitalizing the first character.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [strings.FirstUpper STRING]
+aliases: [/functions/strings.firstupper]
+---
+
+```go-html-template
+{{ strings.FirstUpper "foo" }} → Foo
+```
diff --git a/documents/markdown/hugo-docs/en_functions_strings_HasPrefix.md b/documents/markdown/hugo-docs/en_functions_strings_HasPrefix.md
new file mode 100644
index 0000000..2babe85
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_HasPrefix.md
@@ -0,0 +1,16 @@
+---
+title: strings.HasPrefix
+description: Reports whether the given string begins with the given prefix.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [hasPrefix]
+ returnType: bool
+ signatures: [strings.HasPrefix STRING PREFIX]
+aliases: [/functions/hasprefix,/functions/strings.hasprefix]
+---
+
+```go-html-template
+{{ hasPrefix "Hugo" "Hu" }} → true
+```
diff --git a/documents/markdown/hugo-docs/en_functions_strings_HasSuffix.md b/documents/markdown/hugo-docs/en_functions_strings_HasSuffix.md
new file mode 100644
index 0000000..c6b5f4d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_HasSuffix.md
@@ -0,0 +1,16 @@
+---
+title: strings.HasSuffix
+description: Reports whether the given string ends with the given suffix.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [hasSuffix]
+ returnType: bool
+ signatures: [strings.HasSuffix STRING SUFFIX]
+aliases: [/functions/hassuffix,/functions/strings/hassuffix]
+---
+
+```go-html-template
+{{ hasSuffix "Hugo" "go" }} → true
+```
diff --git a/documents/markdown/hugo-docs/en_functions_strings_Repeat.md b/documents/markdown/hugo-docs/en_functions_strings_Repeat.md
new file mode 100644
index 0000000..d45216a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_Repeat.md
@@ -0,0 +1,16 @@
+---
+title: strings.Repeat
+description: Returns a new string consisting of zero or more copies of another string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [strings.Repeat COUNT STRING]
+aliases: [/functions/strings.repeat]
+---
+
+```go-html-template
+{{ strings.Repeat 3 "yo" }} → yoyoyo
+```
diff --git a/documents/markdown/hugo-docs/en_functions_strings_Replace.md b/documents/markdown/hugo-docs/en_functions_strings_Replace.md
new file mode 100644
index 0000000..b449ea8
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_Replace.md
@@ -0,0 +1,23 @@
+---
+title: strings.Replace
+description: Returns a copy of INPUT, replacing all occurrences of OLD with NEW.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [replace]
+ returnType: string
+ signatures: ['strings.Replace INPUT OLD NEW [LIMIT]']
+aliases: [/functions/replace]
+---
+
+```go-html-template
+{{ $s := "Batman and Robin" }}
+{{ replace $s "Robin" "Catwoman" }} → Batman and Catwoman
+```
+
+Limit the number of replacements using the `LIMIT` argument:
+
+```go-html-template
+{{ replace "aabbaabb" "a" "z" 2 }} → zzbbaabb
+```
diff --git a/documents/markdown/hugo-docs/en_functions_strings_ReplacePairs.md b/documents/markdown/hugo-docs/en_functions_strings_ReplacePairs.md
new file mode 100644
index 0000000..5e2face
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_ReplacePairs.md
@@ -0,0 +1,111 @@
+---
+title: strings.ReplacePairs
+description: Returns a copy of a string with multiple replacements performed in a single pass, using a slice of old and new string pairs.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: ['strings.ReplacePairs OLD NEW [OLD NEW ...] INPUT']
+---
+
+{{< new-in 0.158.0 />}}
+
+Use the `strings.ReplacePairs` function to perform multiple replacements on a string in a single operation. This approach is faster than sequentially calling the [`strings.Replace`][] function.
+
+Replacing strings sequentially requires multiple function calls and variable re-assignments.
+
+```go-html-template
+{{ $s := "aabbcc" }}
+{{ $s = strings.Replace $s "a" "x" }}
+{{ $s = strings.Replace $s "b" "y" }}
+{{ $s = strings.Replace $s "c" "z" }}
+{{ $s }} → xxyyzz
+```
+
+Using `strings.ReplacePairs` produces the same result with fewer function calls in less time.
+
+```go-html-template
+{{ "aabbcc" | strings.ReplacePairs "a" "x" "b" "y" "c" "z" }} → xxyyzz
+```
+
+Pairs may also be passed as a single slice:
+
+```go-html-template
+{{ $pairs := slice
+ "a" "x"
+ "b" "y"
+ "c" "z"
+}}
+{{ "aabbcc" | strings.ReplacePairs $pairs }} → xxyyzz
+```
+
+## Examples
+
+Observe that replacements are not applied recursively because the function scans the string only once.
+
+```go-html-template
+{{ $pairs := slice
+ "a" "b"
+ "b" "c"
+}}
+{{ "a" | strings.ReplacePairs $pairs }} → b
+```
+
+Apply the first match when multiple old strings could match at the same position.
+
+```go-html-template
+{{ $pairs := slice
+ "app" "pear"
+ "apple" "orange"
+}}
+{{ "apple" | strings.ReplacePairs $pairs }} → pearle
+```
+
+Delete specific strings by providing an empty string as the second value in a pair.
+
+```go-html-template
+{{ $pairs := slice "b" "" }}
+{{ "abc" | strings.ReplacePairs $pairs }} → ac
+```
+
+## Edge cases
+
+The table below outlines how the function handles various input scenarios.
+
+Scenario|Result
+:--|:--
+Fewer than two arguments|Error
+Odd number of slice elements|Error
+Empty slice|Returns the input string
+Empty input string|Returns an empty string
+Empty old string|Returns the input string [interleaved](g) with the new string
+
+## Performance
+
+While `strings.Replace` and `strings.ReplacePairs` can produce the same results, they handle data differently. Choosing the right one can noticeably reduce the time Hugo takes to build your project.
+
+### Single pass vs. multiple passes
+
+When using `strings.Replace`, Hugo must scan the text from start to finish to find a match. If you chain three replacements together, Hugo performs three separate passes over the entire string.
+
+The `strings.ReplacePairs` function is more efficient because it performs a single pass. Hugo looks through the text once and applies all replacements simultaneously.
+
+### Caching
+
+Unlike `strings.Replace`, which performs a direct substitution, `strings.ReplacePairs` requires an initialization step to prepare the single-pass replacement logic. To make this efficient, Hugo manages this logic using a cache:
+
+- During the initial call, Hugo initializes and stores the logic for that specific set of pairs.
+- During subsequent calls, Hugo retrieves the stored logic, skipping the initialization step and reducing the duration of the call.
+
+### Choosing the right function
+
+The efficiency of `strings.ReplacePairs` increases as the text gets longer or the number of pairs grows. Consider these scenarios when deciding which function to use:
+
+- For a single replacement on a short string like a title, `strings.Replace` is efficient.
+- For multiple replacements or long strings like a long-form article, `strings.ReplacePairs` is much faster.
+
+For a document with about 8000 characters, which is roughly the length of a long-form article, `strings.ReplacePairs` outperforms five sequential `strings.Replace` calls during the initial call. Once cached, it is the faster choice for almost any situation with two or more pairs.
+
+[`strings.Replace`]: /functions/strings/replace/
diff --git a/documents/markdown/hugo-docs/en_functions_strings_ReplaceRE.md b/documents/markdown/hugo-docs/en_functions_strings_ReplaceRE.md
new file mode 100644
index 0000000..dba4bd1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_ReplaceRE.md
@@ -0,0 +1,38 @@
+---
+title: strings.ReplaceRE
+description: Returns a copy of INPUT, replacing all occurrences of a regular expression with a replacement pattern.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [replaceRE]
+ returnType: string
+ signatures: ['strings.ReplaceRE PATTERN REPLACEMENT INPUT [LIMIT]']
+aliases: [/functions/replacere]
+---
+
+{{% include "/_common/functions/regular-expressions.md" %}}
+
+```go-html-template
+{{ $s := "a-b--c---d" }}
+{{ replaceRE `(-{2,})` "-" $s }} → a-b-c-d
+```
+
+Limit the number of replacements using the LIMIT argument:
+
+```go-html-template
+{{ $s := "a-b--c---d" }}
+{{ replaceRE `(-{2,})` "-" $s 1 }} → a-b-c---d
+```
+
+Use `$1`, `$2`, etc. within the replacement string to insert the content of each capturing group within the regular expression:
+
+```go-html-template
+{{ $s := "http://gohugo.io/docs" }}
+{{ replaceRE "^https?://([^/]+).*" "$1" $s }} → gohugo.io
+```
+
+> [!note]
+> You can write and test your regular expression using [regex101.com]. Be sure to select the Go flavor before you begin.
+
+[regex101.com]: https://regex101.com/
diff --git a/documents/markdown/hugo-docs/en_functions_strings_RuneCount.md b/documents/markdown/hugo-docs/en_functions_strings_RuneCount.md
new file mode 100644
index 0000000..bdc1bfd
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_RuneCount.md
@@ -0,0 +1,20 @@
+---
+title: strings.RuneCount
+description: Returns the number of runes in the given string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: int
+ signatures: [strings.RuneCount STRING]
+aliases: [/functions/strings.runecount]
+---
+
+In contrast with the [`strings.CountRunes`] function, which excludes whitespace, `strings.RuneCount` counts every rune in a string.
+
+```go-html-template
+{{ "Hello, 世界" | strings.RuneCount }} → 9
+```
+
+[`strings.CountRunes`]: /functions/strings/countrunes/
diff --git a/documents/markdown/hugo-docs/en_functions_strings_SliceString.md b/documents/markdown/hugo-docs/en_functions_strings_SliceString.md
new file mode 100644
index 0000000..69e4f6f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_SliceString.md
@@ -0,0 +1,24 @@
+---
+title: strings.SliceString
+description: Returns a substring of the given string, beginning with the start position and ending before the end position.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [slicestr]
+ returnType: string
+ signatures: ['strings.SliceString STRING [START] [END]']
+aliases: [/functions/slicestr]
+---
+
+The START and END positions are zero-based, where `0` represents the first character of the string. If START is not specified, the substring will begin at position `0`. If END is not specified, the substring will end after the last character.
+
+```go-html-template
+{{ slicestr "BatMan" }} → BatMan
+{{ slicestr "BatMan" 3 }} → Man
+{{ slicestr "BatMan" 0 3 }} → Bat
+```
+
+The START and END arguments represent the endpoints of a half-open [interval](g), a concept that may be difficult to grasp when first encountered. You may find that the [`strings.Substr`] function is easier to understand.
+
+[`strings.Substr`]: /functions/strings/substr/
diff --git a/documents/markdown/hugo-docs/en_functions_strings_Split.md b/documents/markdown/hugo-docs/en_functions_strings_Split.md
new file mode 100644
index 0000000..bcab1b4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_Split.md
@@ -0,0 +1,24 @@
+---
+title: strings.Split
+description: Returns a slice of strings by splitting the given string by a delimiter.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [split]
+ returnType: '[]string'
+ signatures: [strings.Split STRING DELIM]
+aliases: [/functions/split]
+---
+
+Examples:
+
+```go-html-template
+{{ split "tag1,tag2,tag3" "," }} → ["tag1", "tag2", "tag3"]
+{{ split "abc" "" }} → ["a", "b", "c"]
+```
+
+> [!note]
+> The `strings.Split` function essentially does the opposite of the [`collections.Delimit`] function. While `split` creates a slice from a string, `delimit` creates a string from a slice.
+
+[`collections.Delimit`]: /functions/collections/delimit/
diff --git a/documents/markdown/hugo-docs/en_functions_strings_Substr.md b/documents/markdown/hugo-docs/en_functions_strings_Substr.md
new file mode 100644
index 0000000..a4c779f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_Substr.md
@@ -0,0 +1,36 @@
+---
+title: strings.Substr
+description: Returns a substring of the given string, beginning with the start position and ending after the given length.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [substr]
+ returnType: string
+ signatures: ['strings.Substr STRING [START] [LENGTH]']
+aliases: [/functions/substr]
+---
+
+The start position is zero-based, where `0` represents the first character of the string. If START is not specified, the substring will begin at position `0`. Specify a negative START position to extract characters from the end of the string.
+
+If LENGTH is not specified, the substring will include all characters from the START position to the end of the string. If negative, that number of characters will be omitted from the end of string.
+
+```go-html-template
+{{ substr "abcdef" 0 }} → abcdef
+{{ substr "abcdef" 1 }} → bcdef
+
+{{ substr "abcdef" 0 1 }} → a
+{{ substr "abcdef" 1 1 }} → b
+
+{{ substr "abcdef" 0 -1 }} → abcde
+{{ substr "abcdef" 1 -1 }} → bcde
+
+{{ substr "abcdef" -1 }} → f
+{{ substr "abcdef" -2 }} → ef
+
+{{ substr "abcdef" -1 1 }} → f
+{{ substr "abcdef" -2 1 }} → e
+
+{{ substr "abcdef" -3 -1 }} → de
+{{ substr "abcdef" -3 -2 }} → d
+```
diff --git a/documents/markdown/hugo-docs/en_functions_strings_Title.md b/documents/markdown/hugo-docs/en_functions_strings_Title.md
new file mode 100644
index 0000000..0ff79cd
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_Title.md
@@ -0,0 +1,29 @@
+---
+title: strings.Title
+description: Returns the given string, converting it to title case.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [title]
+ returnType: string
+ signatures: [strings.Title STRING]
+aliases: [/functions/title]
+---
+
+```go-html-template
+{{ title "table of contents (TOC)" }} → Table of Contents (TOC)
+```
+
+By default, Hugo follows the capitalization rules published in the [Associated Press Stylebook]. Change your [project configuration] if you would prefer to:
+
+- Follow the capitalization rules published in the [Chicago Manual of Style]
+- Capitalize the first letter of every word
+- Capitalize the first letter of the first word
+- Disable the effects of the `title` function
+
+The last option is useful if your theme uses the `title` function, and you would prefer to manually capitalize strings as needed.
+
+[Associated Press Stylebook]: https://www.apstylebook.com/
+[Chicago Manual of Style]: https://www.chicagomanualofstyle.org/home.html
+[project configuration]: /configuration/all/#title-case-style
diff --git a/documents/markdown/hugo-docs/en_functions_strings_ToLower.md b/documents/markdown/hugo-docs/en_functions_strings_ToLower.md
new file mode 100644
index 0000000..18ed6d4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_ToLower.md
@@ -0,0 +1,16 @@
+---
+title: strings.ToLower
+description: Returns the given string, converting all characters to lowercase.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [lower]
+ returnType: string
+ signatures: [strings.ToLower STRING]
+aliases: [/functions/lower]
+---
+
+```go-html-template
+{{ lower "BatMan" }} → batman
+```
diff --git a/documents/markdown/hugo-docs/en_functions_strings_ToUpper.md b/documents/markdown/hugo-docs/en_functions_strings_ToUpper.md
new file mode 100644
index 0000000..a3e8ff9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_ToUpper.md
@@ -0,0 +1,16 @@
+---
+title: strings.ToUpper
+description: Returns the given string, converting all characters to uppercase.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [upper]
+ returnType: string
+ signatures: [strings.ToUpper STRING]
+aliases: [/functions/upper]
+---
+
+```go-html-template
+{{ upper "BatMan" }} → BATMAN
+```
diff --git a/documents/markdown/hugo-docs/en_functions_strings_Trim.md b/documents/markdown/hugo-docs/en_functions_strings_Trim.md
new file mode 100644
index 0000000..edbdcc2
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_Trim.md
@@ -0,0 +1,16 @@
+---
+title: strings.Trim
+description: Returns the given string, removing leading and trailing characters specified in the cutset.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [trim]
+ returnType: string
+ signatures: [strings.Trim STRING CUTSET]
+aliases: [/functions/trim]
+---
+
+```go-html-template
+{{ trim "++foo--" "+-" }} → foo
+```
diff --git a/documents/markdown/hugo-docs/en_functions_strings_TrimLeft.md b/documents/markdown/hugo-docs/en_functions_strings_TrimLeft.md
new file mode 100644
index 0000000..c5d6ba6
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_TrimLeft.md
@@ -0,0 +1,23 @@
+---
+title: strings.TrimLeft
+description: Returns the given string, removing leading characters specified in the cutset.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [strings.TrimLeft CUTSET STRING]
+aliases: [/functions/strings.trimleft]
+---
+
+```go-html-template
+{{ strings.TrimLeft "a" "abba" }} → bba
+```
+
+The `strings.TrimLeft` function converts the arguments to strings if possible:
+
+```go-html-template
+{{ strings.TrimLeft 21 12345 }} → 345 (string)
+{{ strings.TrimLeft "rt" true }} → ue
+```
diff --git a/documents/markdown/hugo-docs/en_functions_strings_TrimPrefix.md b/documents/markdown/hugo-docs/en_functions_strings_TrimPrefix.md
new file mode 100644
index 0000000..b897d87
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_TrimPrefix.md
@@ -0,0 +1,18 @@
+---
+title: strings.TrimPrefix
+description: Returns the given string, removing the prefix from the beginning of the string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [strings.TrimPrefix PREFIX STRING]
+aliases: [/functions/strings.trimprefix]
+---
+
+```go-html-template
+{{ strings.TrimPrefix "a" "aabbaa" }} → abbaa
+{{ strings.TrimPrefix "aa" "aabbaa" }} → bbaa
+{{ strings.TrimPrefix "aaa" "aabbaa" }} → aabbaa
+```
diff --git a/documents/markdown/hugo-docs/en_functions_strings_TrimRight.md b/documents/markdown/hugo-docs/en_functions_strings_TrimRight.md
new file mode 100644
index 0000000..05c2ed3
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_TrimRight.md
@@ -0,0 +1,23 @@
+---
+title: strings.TrimRight
+description: Returns the given string, removing trailing characters specified in the cutset.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [strings.TrimRight CUTSET STRING]
+aliases: [/functions/strings.trimright]
+---
+
+```go-html-template
+{{ strings.TrimRight "a" "abba" }} → abb
+```
+
+The `strings.TrimRight` function converts the arguments to strings if possible:
+
+```go-html-template
+{{ strings.TrimRight 54 12345 }} → 123 (string)
+{{ strings.TrimRight "eu" true }} → tr
+```
diff --git a/documents/markdown/hugo-docs/en_functions_strings_TrimSpace.md b/documents/markdown/hugo-docs/en_functions_strings_TrimSpace.md
new file mode 100644
index 0000000..77da321
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_TrimSpace.md
@@ -0,0 +1,20 @@
+---
+title: strings.TrimSpace
+description: Returns the given string, removing leading and trailing whitespace as defined by Unicode.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [strings.TrimSpace STRING]
+---
+
+{{< new-in 0.136.3 />}}
+
+Whitespace characters include `\t`, `\n`, `\v`, `\f`, `\r`, and characters in the [Unicode Space Separator] category.
+
+[Unicode Space Separator]: https://www.compart.com/en/unicode/category/Zs
+
+```go-html-template
+{{ strings.TrimSpace "\n\r\t foo \n\r\t" }} → foo
+```
diff --git a/documents/markdown/hugo-docs/en_functions_strings_TrimSuffix.md b/documents/markdown/hugo-docs/en_functions_strings_TrimSuffix.md
new file mode 100644
index 0000000..8028421
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_TrimSuffix.md
@@ -0,0 +1,18 @@
+---
+title: strings.TrimSuffix
+description: Returns the given string, removing the suffix from the end of the string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [strings.TrimSuffix SUFFIX STRING]
+aliases: [/functions/strings.trimsuffix]
+---
+
+```go-html-template
+{{ strings.TrimSuffix "a" "aabbaa" }} → aabba
+{{ strings.TrimSuffix "aa" "aabbaa" }} → aabb
+{{ strings.TrimSuffix "aaa" "aabbaa" }} → aabbaa
+```
diff --git a/documents/markdown/hugo-docs/en_functions_strings_Truncate.md b/documents/markdown/hugo-docs/en_functions_strings_Truncate.md
new file mode 100644
index 0000000..c419822
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings_Truncate.md
@@ -0,0 +1,23 @@
+---
+title: strings.Truncate
+description: Returns the given string, truncating it to a maximum length without cutting words or leaving unclosed HTML tags.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [truncate]
+ returnType: template.HTML
+ signatures: ['strings.Truncate SIZE [ELLIPSIS] INPUT']
+aliases: [/functions/truncate]
+---
+
+Since Go templates are HTML-aware, `truncate` will intelligently handle normal strings vs HTML strings:
+
+```go-html-template
+{{ "<em>Keep my HTML</em>" | safeHTML | truncate 10 }} → <em>Keep my …</em>
+```
+
+> [!note]
+> If you have a raw string that contains HTML tags you want to remain treated as HTML, you will need to convert the string to HTML using the [`safeHTML`]function before sending the value to `truncate`. Otherwise, the HTML tags will be escaped when passed through the `truncate` function.
+
+[`safeHTML`]: /functions/safe/html/
diff --git a/documents/markdown/hugo-docs/en_functions_strings__index.md b/documents/markdown/hugo-docs/en_functions_strings__index.md
new file mode 100644
index 0000000..28f26f1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_strings__index.md
@@ -0,0 +1,7 @@
+---
+title: String functions
+linkTitle: strings
+description: Use these functions to work with strings.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_templates_Current.md b/documents/markdown/hugo-docs/en_functions_templates_Current.md
new file mode 100644
index 0000000..47adf38
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_templates_Current.md
@@ -0,0 +1,155 @@
+---
+title: templates.Current
+description: Returns information about the currently executing template.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: tpl.CurrentTemplateInfo
+ signatures: [templates.Current]
+---
+
+> [!note]
+> This function is experimental and subject to change.
+
+{{< new-in 0.146.0 />}}
+
+The `templates.Current` function provides introspection capabilities, allowing you to access details about the currently executing templates. This is useful for debugging complex template hierarchies and understanding the flow of execution during rendering.
+
+## Methods
+
+Ancestors
+: (`tpl.CurrentTemplateInfos`) Returns a slice containing information about each template in the current execution chain, starting from the parent of the current template and going up towards the initial template called. It excludes any base template applied via `define` and `block`. You can chain the `Reverse` method to this result to get the slice in chronological execution order.
+
+Base
+: (`tpl.CurrentTemplateInfoCommonOps`) Returns an object representing the base template that was applied to the current template, if any. This may be `nil`.
+
+Filename
+: (`string`) Returns the absolute path of the current template. This will be empty for embedded templates.
+
+Name
+: (`string`) Returns the name of the current template. This is usually the path relative to the layouts directory.
+
+Parent
+: (`tpl.CurrentTemplateInfo`) Returns an object representing the parent of the current template, if any. This may be `nil`.
+
+## Examples
+
+The examples below help visualize template execution and require a `debug` parameter set to `true` in your project configuration:
+
+{{< code-toggle file=hugo >}}
+[params]
+debug = true
+{{< /code-toggle >}}
+
+### Boundaries
+
+To visually mark where a template begins and ends execution:
+
+```go-html-template {file="layouts/page.html"}
+{{ define "main" }}
+ {{ if site.Params.debug }}
+ <div class="debug">[entering {{ templates.Current.Filename }}]</div>
+ {{ end }}
+
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+
+ {{ if site.Params.debug }}
+ <div class="debug">[leaving {{ templates.Current.Filename }}]</div>
+ {{ end }}
+{{ end }}
+```
+
+### Call stack
+
+To display the chain of templates that led to the current one, create a _partial_ template that iterates through its ancestors:
+
+```go-html-template {file="layouts/_partials/template-call-stack.html" copy=true}
+{{ with templates.Current }}
+ <div class="debug">
+ {{ range .Ancestors }}
+ {{ .Filename }}<br>
+ {{ with .Base }}
+ {{ .Filename }}<br>
+ {{ end }}
+ {{ end }}
+ </div>
+{{ end }}
+```
+
+Then call the partial from any template:
+
+```go-html-template {file="layouts/_partials/footer/copyright.html" copy=true}
+{{ if site.Params.debug }}
+ {{ partial "template-call-stack.html" . }}
+{{ end }}
+```
+
+The rendered template stack would look something like this:
+
+```text
+/home/user/project/layouts/_partials/footer/copyright.html
+/home/user/project/themes/foo/layouts/_partials/footer.html
+/home/user/project/layouts/page.html
+/home/user/project/themes/foo/layouts/baseof.html
+```
+
+To reverse the order of the entries, chain the `Reverse` method to the `Ancestors` method:
+
+```go-html-template {file="layouts/_partials/template-call-stack.html" copy=true}
+{{ with templates.Current }}
+ <div class="debug">
+ {{ range .Ancestors.Reverse }}
+ {{ with .Base }}
+ {{ .Filename }}<br>
+ {{ end }}
+ {{ .Filename }}<br>
+ {{ end }}
+ </div>
+{{ end }}
+```
+
+### VS Code
+
+To render links that, when clicked, will open the template in Microsoft Visual Studio Code, create a _partial_ template with anchor elements that use the `vscode` URI scheme:
+
+```go-html-template {file="layouts/_partials/template-open-in-vs-code.html" copy=true}
+{{ with templates.Current.Parent }}
+ <div class="debug">
+ <a href="vscode://file/{{ .Filename }}">{{ .Name }}</a>
+ {{ with .Base }}
+ <a href="vscode://file/{{ .Filename }}">{{ .Name }}</a>
+ {{ end }}
+ </div>
+{{ end }}
+```
+
+Then call the partial from any template:
+
+```go-html-template {file="layouts/page.html" copy=true}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+
+ {{ if site.Params.debug }}
+ {{ partial "template-open-in-vs-code.html" . }}
+ {{ end }}
+{{ end }}
+```
+
+Use the same approach to render the entire call stack as links:
+
+```go-html-template {file="layouts/_partials/template-call-stack.html" copy=true}
+{{ with templates.Current }}
+ <div class="debug">
+ {{ range .Ancestors }}
+ <a href="vscode://file/{{ .Filename }}">{{ .Filename }}</a><br>
+ {{ with .Base }}
+ <a href="vscode://file/{{ .Filename }}">{{ .Filename }}</a><br>
+ {{ end }}
+ {{ end }}
+ </div>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_functions_templates_Defer.md b/documents/markdown/hugo-docs/en_functions_templates_Defer.md
new file mode 100644
index 0000000..272c36b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_templates_Defer.md
@@ -0,0 +1,95 @@
+---
+title: templates.Defer
+description: Defer execution of a template until after all sites and output formats have been rendered.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [templates.Defer OPTIONS]
+aliases: [/functions/templates.defer]
+---
+
+> [!note]
+> This feature should only be used in the main template, typically `layouts/baseof.html`. Using it in _shortcode_, _partial_, or _render hook_ templates may lead to unpredictable results. For further details, please refer to [this issue].
+
+[this issue]: https://github.com/gohugoio/hugo/issues/13492#issuecomment-2734700391
+
+In some rare use cases, you may need to defer the execution of a template until after all sites and output formats have been rendered. One such example could be [TailwindCSS](/functions/css/tailwindcss/) using the output of [hugo_stats.json](/configuration/build/) to determine which classes and other HTML identifiers are being used in the final output:
+
+```go-html-template {file="layouts/baseof.html" copy=true}
+<head>
+ ...
+ {{ with (templates.Defer (dict "key" "global")) }}
+ {{ partial "css.html" . }}
+ {{ end }}
+ ...
+</head>
+```
+
+```go-html-template {file="layouts/_partials/css.html" copy=true}
+{{ with resources.Get "css/main.css" }}
+ {{ $opts := dict "minify" (not hugo.IsDevelopment) }}
+ {{ with . | css.TailwindCSS $opts }}
+ {{ if hugo.IsDevelopment }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ else }}
+ {{ with . | fingerprint }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+> [!note]
+> This function only works in combination with the `with` keyword.
+>
+> Variables defined on the outside are not visible on the inside and vice versa. To pass in data, use the `data` [option](#options).
+
+For the above to work well when running the server (or `hugo -w`), you want to have a configuration similar to this:
+
+{{< code-toggle file=hugo >}}
+[build]
+ [build.buildStats]
+ enable = true
+ [[build.cachebusters]]
+ source = 'assets/notwatching/hugo_stats\.json'
+ target = 'css'
+ [[build.cachebusters]]
+ source = '(postcss|tailwind)\.config\.js'
+ target = 'css'
+[module]
+ [[module.mounts]]
+ source = 'assets'
+ target = 'assets'
+ [[module.mounts]]
+ disableWatch = true
+ source = 'hugo_stats.json'
+ target = 'assets/notwatching/hugo_stats.json'
+{{< /code-toggle >}}
+
+## Options
+
+The `templates.Defer` function takes a single argument, a map with the following optional keys:
+
+key (`string`)
+: The key to use for the deferred template. This will, combined with a hash of the template content, be used as a cache key. If this is not set, Hugo will execute the deferred template on every render. This is not what you want for shared resources like CSS and JavaScript.
+
+data (`map`)
+: Optional map to pass as data to the deferred template. This will be available in the deferred template as `.` or `$`.
+
+```go-html-template
+Language Outside: {{ site.Language.Name }}
+Page Outside: {{ .RelPermalink }}
+I18n Outside: {{ i18n "hello" }}
+{{ $data := (dict "page" . )}}
+{{ with (templates.Defer (dict "data" $data )) }}
+ Language Inside: {{ site.Language.Name }}
+ Page Inside: {{ .page.RelPermalink }}
+ I18n Inside: {{ i18n "hello" }}
+{{ end }}
+```
+
+The [output format](/configuration/output-formats/), [site](/methods/page/site/), and [language](/methods/site/language) will be the same, even if the execution is deferred. In the example above, this means that the `site.Language.Name` and `.RelPermalink` will be the same on the inside and the outside of the deferred template.
diff --git a/documents/markdown/hugo-docs/en_functions_templates_Exists.md b/documents/markdown/hugo-docs/en_functions_templates_Exists.md
new file mode 100644
index 0000000..a8d627f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_templates_Exists.md
@@ -0,0 +1,27 @@
+---
+title: templates.Exists
+description: Reports whether a template file exists under the given path relative to the layouts directory.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [templates.Exists PATH]
+aliases: [/functions/templates.exists]
+---
+
+A template file is any file within the `layouts` directory of either the project or any of its theme components.
+
+Use the `templates.Exists` function with dynamic template paths:
+
+```go-html-template
+{{ $partialPath := printf "headers/%s.html" .Type }}
+{{ if templates.Exists ( printf "_partials/%s" $partialPath ) }}
+ {{ partial $partialPath . }}
+{{ else }}
+ {{ partial "headers/default.html" . }}
+{{ end }}
+```
+
+In the example above, if a "headers" partial does not exist for the given content type, Hugo falls back to a default template.
diff --git a/documents/markdown/hugo-docs/en_functions_templates_Inner.md b/documents/markdown/hugo-docs/en_functions_templates_Inner.md
new file mode 100644
index 0000000..15fab2d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_templates_Inner.md
@@ -0,0 +1,71 @@
+---
+title: templates.Inner
+description: Executes the content block enclosed by a partial call.
+categories: []
+keywords: [decorator]
+params:
+ functions_and_methods:
+ aliases: [inner]
+ returnType: any
+ signatures: ['templates.Inner [CONTEXT]']
+---
+
+{{< new-in 0.154.0 />}}
+
+The `templates.Inner` function defines the injection point for code nested within a block style partial call. This is the core mechanism used to create a [partial decorator][].
+
+## Overview
+
+The `templates.Inner` function acts as a placeholder within a partial template. When a partial is called as a decorator, it captures a block of code from the calling template rather than rendering it immediately. The `templates.Inner` function tells Hugo exactly where to inject that captured content.
+
+This signals a reversal of execution where the callee becomes the caller. The partial manages the outer structure while the calling template remains in control of the inner content.
+
+## Usage
+
+To use this function, the calling template must use the block style syntax with a [`with`][] statement. This allows decorators to be deeply nested.
+
+```go-html-template {file="layouts/home.html"}
+{{ with partial "components/card.html" . }}
+ <p>This content is passed to the partial.</p>
+{{ end }}
+```
+
+Inside the partial, call `templates.Inner` to render the captured block.
+
+```go-html-template {file="layouts/_partials/components/card.html"}
+<div class="card-frame">
+ {{ templates.Inner . }}
+</div>
+```
+
+## Arguments
+
+The function accepts one optional argument: the [context](g). This argument determines the value of the dot (`.`) inside the captured block when it is rendered.
+
+- If you provide an argument, such as `{{ templates.Inner .SomeData }}`, the dot inside the captured block is rebound to that specific data.
+- If you do not provide an argument, the captured block uses the context of the caller where the partial was first invoked.
+
+## Context and scope
+
+When using decorators, the `with` statement creates a new [scope](g). Variables defined outside the with block in the calling template are not automatically available inside the captured block.
+
+By passing a context to `templates.Inner`, you ensure that the injected content has access to the correct data even when nested inside multiple layers of wrappers. This is critical when the decorator is used inside a loop or a specific data overlay.
+
+## Repeated execution
+
+A decorator can execute the captured content zero or more times. This is useful when the wrapper needs to repeat the same decoration for a collection of items, such as a list or a grid.
+
+```go-html-template {file="layouts/_partials/list-decorator.html"}
+<ul class="styled-list">
+ {{ range .items }}
+ <li>
+ {{ templates.Inner . }}
+ </li>
+ {{ end }}
+</ul>
+```
+
+In this example, the code provided by the caller is rendered once for every item in the .items collection, with the dot . updated to the current item in each iteration.
+
+[`with`]: /functions/go-template/with/
+[partial decorator]: /templates/partial-decorators/
diff --git a/documents/markdown/hugo-docs/en_functions_templates__index.md b/documents/markdown/hugo-docs/en_functions_templates__index.md
new file mode 100644
index 0000000..a385604
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_templates__index.md
@@ -0,0 +1,7 @@
+---
+title: Template functions
+linkTitle: templates
+description: Use these functions to query the template system.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_time_AsTime.md b/documents/markdown/hugo-docs/en_functions_time_AsTime.md
new file mode 100644
index 0000000..884d6c6
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_time_AsTime.md
@@ -0,0 +1,48 @@
+---
+title: time.AsTime
+description: Returns the given string representation of a date/time value as a time.Time value.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [time]
+ returnType: time.Time
+ signatures: ['time.AsTime INPUT [TIMEZONE]']
+aliases: [/functions/time]
+---
+
+## Overview
+
+Hugo provides [functions] and [methods] to format, localize, parse, compare, and manipulate date/time values. Before you can do any of these with string representations of date/time values, you must first convert them to [`time.Time`] values using the `time.AsTime` function.
+
+```go-html-template
+{{ $t := "2023-10-15T13:18:50-07:00" }}
+{{ time.AsTime $t }} → 2023-10-15 13:18:50 -0700 PDT (time.Time)
+```
+
+## Parsable strings
+
+As shown above, the first argument must be a parsable string representation of a date/time value. For example:
+
+{{% include "/_common/parsable-date-time-strings.md" %}}
+
+To override the default time zone, set the [`timeZone`] in your project configuration or provide a second argument to the `time.AsTime` function. For example:
+
+```go-html-template
+{{ time.AsTime "15 Oct 2023" "America/Los_Angeles" }}
+```
+
+The list of valid time zones may be system dependent, but should include `UTC`, `Local`, or any location in the [IANA Time Zone database].
+
+The order of precedence for determining the time zone is:
+
+1. The time zone offset in the date/time string
+1. The time zone provided as the second argument to the `time.AsTime` function
+1. The time zone specified in your project configuration
+1. The `Etc/UTC` time zone
+
+[IANA Time Zone database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+[`time.Time`]: https://pkg.go.dev/time#Time
+[`timeZone`]: /configuration/all/#timezone
+[functions]: /functions/time/
+[methods]: /methods/time/
diff --git a/documents/markdown/hugo-docs/en_functions_time_Duration.md b/documents/markdown/hugo-docs/en_functions_time_Duration.md
new file mode 100644
index 0000000..bd6adfb
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_time_Duration.md
@@ -0,0 +1,41 @@
+---
+title: time.Duration
+description: Returns a time.Duration value using the given time unit and number.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [duration]
+ returnType: time.Duration
+ signatures: [time.Duration TIME_UNIT NUMBER]
+aliases: [/functions/duration]
+---
+
+The `time.Duration` function returns a [`time.Duration`] value that you can use with any of the `Duration` [methods].
+
+This template:
+
+```go-html-template
+{{ $duration := time.Duration "hour" 24 }}
+{{ printf "There are %.0f seconds in one day." $duration.Seconds }}
+```
+
+Is rendered to:
+
+```text
+There are 86400 seconds in one day.
+```
+
+The time unit must be one of the following:
+
+Duration|Valid time units
+:--|:--
+hours|`hour`, `h`
+minutes|`minute`, `m`
+seconds|`second`, `s`
+milliseconds|`millisecond`, `ms`
+microseconds|`microsecond`, `us`, `µs`
+nanoseconds|`nanosecond`, `ns`
+
+[`time.Duration`]: https://pkg.go.dev/time#Duration
+[methods]: /methods/duration/
diff --git a/documents/markdown/hugo-docs/en_functions_time_Format.md b/documents/markdown/hugo-docs/en_functions_time_Format.md
new file mode 100644
index 0000000..112a6e7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_time_Format.md
@@ -0,0 +1,80 @@
+---
+title: time.Format
+description: Returns the given date/time as a formatted and localized string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [dateFormat]
+ returnType: string
+ signatures: [time.Format LAYOUT INPUT]
+aliases: [/functions/dateformat]
+---
+
+Use the `time.Format` function with `time.Time` values:
+
+```go-html-template
+{{ $t := time.AsTime "2023-10-15T13:18:50-07:00" }}
+{{ time.Format "2 Jan 2006" $t }} → 15 Oct 2023
+```
+
+Or use `time.Format` with a parsable string representation of a date/time value:
+
+```go-html-template
+{{ $t := "15 Oct 2023" }}
+{{ time.Format "January 2, 2006" $t }} → October 15, 2023
+```
+
+Examples of parsable string representations:
+
+{{% include "/_common/parsable-date-time-strings.md" %}}
+
+To override the default time zone, set the [`timeZone`] in your project configuration. The order of precedence for determining the time zone is:
+
+1. The time zone offset in the date/time string
+1. The time zone specified in your project configuration
+1. The `Etc/UTC` time zone
+
+[`timeZone`]: /configuration/all/#timezone
+
+## Layout string
+
+{{% include "/_common/time-layout-string.md" %}}
+
+## Localization
+
+Use the `time.Format` function to localize `time.Time` values for the current language and region.
+
+{{% include "/_common/functions/locales.md" %}}
+
+Use the layout string as described above, or one of the tokens below. For example:
+
+```go-html-template
+{{ .Date | time.Format ":date_medium" }} → Jan 27, 2023
+```
+
+Localized to en-US:
+
+Token|Result
+:--|:--
+`:date_full`|`Friday, January 27, 2023`
+`:date_long`|`January 27, 2023`
+`:date_medium`|`Jan 27, 2023`
+`:date_short`|`1/27/23`
+`:time_full`|`11:44:58 pm Pacific Standard Time`
+`:time_long`|`11:44:58 pm PST`
+`:time_medium`|`11:44:58 pm`
+`:time_short`|`11:44 pm`
+
+Localized to de-DE:
+
+Token|Result
+:--|:--
+`:date_full`|`Freitag, 27. Januar 2023`
+`:date_long`|`27. Januar 2023`
+`:date_medium`|`27.01.2023`
+`:date_short`|`27.01.23`
+`:time_full`|`23:44:58 Nordamerikanische Westküsten-Normalzeit`
+`:time_long`|`23:44:58 PST`
+`:time_medium`|`23:44:58`
+`:time_short`|`23:44`
diff --git a/documents/markdown/hugo-docs/en_functions_time_In.md b/documents/markdown/hugo-docs/en_functions_time_In.md
new file mode 100644
index 0000000..821eb99
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_time_In.md
@@ -0,0 +1,30 @@
+---
+title: time.In
+description: Returns the given date/time as represented in the specified IANA time zone.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: time.Time
+ signatures: [time.In TIMEZONE INPUT]
+---
+
+{{< new-in 0.146.0 />}}
+
+The `time.In` function returns the given date/time as represented in the specified [IANA](g) time zone.
+
+- If the time zone is an empty string or `UTC`, the time is returned in [UTC](g).
+- If the time zone is `Local`, the time is returned in the system's local time zone.
+- Otherwise, the time zone must be a valid IANA [time zone name].
+
+[time zone name]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List
+
+```go-html-template
+{{ $layout := "2006-01-02T15:04:05-07:00" }}
+{{ $t := time.AsTime "2025-03-31T14:45:00-00:00" }}
+
+{{ $t | time.In "America/Denver" | time.Format $layout }} → 2025-03-31T08:45:00-06:00
+{{ $t | time.In "Australia/Adelaide" | time.Format $layout }} → 2025-04-01T01:15:00+10:30
+{{ $t | time.In "Europe/Oslo" | time.Format $layout }} → 2025-03-31T16:45:00+02:00
+```
diff --git a/documents/markdown/hugo-docs/en_functions_time_Now.md b/documents/markdown/hugo-docs/en_functions_time_Now.md
new file mode 100644
index 0000000..9b6fa46
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_time_Now.md
@@ -0,0 +1,42 @@
+---
+title: time.Now
+description: Returns the current local time.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [now]
+ returnType: time.Time
+ signatures: [time.Now]
+aliases: [/functions/now]
+---
+
+For example, when building a site on October 15, 2023 in the America/Los_Angeles time zone:
+
+```go-html-template
+{{ time.Now }}
+```
+
+This produces a `time.Time` value, with a string representation such as:
+
+```text
+2023-10-15 12:59:28.337140706 -0700 PDT m=+0.041752605
+```
+
+To format and [localize](g) the value, pass it through the [`time.Format`] function:
+
+```go-html-template
+{{ time.Now | time.Format "Jan 2006" }} → Oct 2023
+```
+
+The `time.Now` function returns a `time.Time` value, so you can chain any of the [time methods] to the resulting value. For example:
+
+```go-html-template
+{{ time.Now.Year }} → 2023 (int)
+{{ time.Now.Weekday.String }} → Sunday
+{{ time.Now.Month.String }} → October
+{{ time.Now.Unix }} → 1697400955 (int64)
+```
+
+[`time.Format`]: /functions/time/format/
+[time methods]: /methods/time/
diff --git a/documents/markdown/hugo-docs/en_functions_time_ParseDuration.md b/documents/markdown/hugo-docs/en_functions_time_ParseDuration.md
new file mode 100644
index 0000000..418632f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_time_ParseDuration.md
@@ -0,0 +1,32 @@
+---
+title: time.ParseDuration
+description: Returns a time.Duration value by parsing the given duration string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: time.Duration
+ signatures: [time.ParseDuration DURATION]
+aliases: [/functions/time.parseduration]
+---
+
+The `time.ParseDuration` function returns a [`time.Duration`] value that you can use with any of the `Duration` [methods].
+
+A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as `300ms`, `-1.5h` or `2h45m`. Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`.
+
+This template:
+
+```go-html-template
+{{ $duration := time.ParseDuration "24h" }}
+{{ printf "There are %.0f seconds in one day." $duration.Seconds }}
+```
+
+Is rendered to:
+
+```text
+There are 86400 seconds in one day.
+```
+
+[`time.Duration`]: https://pkg.go.dev/time#Duration
+[methods]: /methods/duration/
diff --git a/documents/markdown/hugo-docs/en_functions_time__index.md b/documents/markdown/hugo-docs/en_functions_time__index.md
new file mode 100644
index 0000000..9c2ff21
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_time__index.md
@@ -0,0 +1,7 @@
+---
+title: Time functions
+linkTitle: time
+description: Use these functions to work with time values.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_transform_CanHighlight.md b/documents/markdown/hugo-docs/en_functions_transform_CanHighlight.md
new file mode 100644
index 0000000..5e3b04a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_transform_CanHighlight.md
@@ -0,0 +1,16 @@
+---
+title: transform.CanHighlight
+description: Reports whether the given code language is supported by the Chroma highlighter.
+categories: []
+keywords: [highlight]
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [transform.CanHighlight LANGUAGE]
+---
+
+```go-html-template
+{{ transform.CanHighlight "go" }} → true
+{{ transform.CanHighlight "klingon" }} → false
+```
diff --git a/documents/markdown/hugo-docs/en_functions_transform_Emojify.md b/documents/markdown/hugo-docs/en_functions_transform_Emojify.md
new file mode 100644
index 0000000..6a4501f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_transform_Emojify.md
@@ -0,0 +1,27 @@
+---
+title: transform.Emojify
+description: Runs a string through the Emoji emoticons processor.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [emojify]
+ returnType: template.HTML
+ signatures: [transform.Emojify INPUT]
+aliases: [/functions/emojify]
+---
+
+`emojify` runs a passed string through the Emoji emoticons processor.
+
+See the list of [emoji shortcodes] for available emoticons.
+
+The `emojify` function can be called in your templates but not directly in your content files by default. For emojis in content files, set [`enableEmoji`] to `true` in your project configuration. Then you can write emoji shorthand directly into your content files;
+
+```text
+I :heart: Hugo!
+```
+
+I :heart: Hugo!
+
+[`enableEmoji`]: /configuration/all/#enableemoji
+[emoji shortcodes]: /quick-reference/emojis/
diff --git a/documents/markdown/hugo-docs/en_functions_transform_HTMLEscape.md b/documents/markdown/hugo-docs/en_functions_transform_HTMLEscape.md
new file mode 100644
index 0000000..069fd92
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_transform_HTMLEscape.md
@@ -0,0 +1,29 @@
+---
+title: transform.HTMLEscape
+description: Returns the given string, escaping special characters by replacing them with HTML entities.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [htmlEscape]
+ returnType: string
+ signatures: [transform.HTMLEscape INPUT]
+aliases: [/functions/htmlescape]
+---
+
+The `transform.HTMLEscape` function escapes five special characters by replacing them with [HTML entities]:
+
+- `&` → `&`
+- `<` → `<`
+- `>` → `>`
+- `'` → `'`
+- `"` → `"`
+
+For example:
+
+```go-html-template
+{{ htmlEscape "Lilo & Stitch" }} → Lilo & Stitch
+{{ htmlEscape "7 > 6" }} → 7 > 6
+```
+
+[html entities]: https://developer.mozilla.org/en-US/docs/Glossary/Entity
diff --git a/documents/markdown/hugo-docs/en_functions_transform_HTMLUnescape.md b/documents/markdown/hugo-docs/en_functions_transform_HTMLUnescape.md
new file mode 100644
index 0000000..ab9be94
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_transform_HTMLUnescape.md
@@ -0,0 +1,29 @@
+---
+title: transform.HTMLUnescape
+description: Returns the given string, replacing each HTML entity with its corresponding character.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [htmlUnescape]
+ returnType: string
+ signatures: [transform.HTMLUnescape INPUT]
+aliases: [/functions/htmlunescape]
+---
+
+The `transform.HTMLUnescape` function replaces [HTML entities][] with their corresponding characters.
+
+```go-html-template
+{{ htmlUnescape "Lilo & Stitch" }} → Lilo & Stitch
+{{ htmlUnescape "7 > 6" }} → 7 > 6
+```
+
+In most contexts Go's [`html/template`][] package will escape special characters. To bypass this behavior, pass the unescaped string through the [`safeHTML`][] function.
+
+```go-html-template
+{{ htmlUnescape "Lilo & Stitch" | safeHTML }}
+```
+
+[`safehtml`]: /functions/safe/html/
+[html entities]: https://developer.mozilla.org/en-us/docs/glossary/entity
+[`html/template`]: https://pkg.go.dev/html/template
diff --git a/documents/markdown/hugo-docs/en_functions_transform_HTMLtoMarkdown.md b/documents/markdown/hugo-docs/en_functions_transform_HTMLtoMarkdown.md
new file mode 100644
index 0000000..1c05c7d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_transform_HTMLtoMarkdown.md
@@ -0,0 +1,37 @@
+---
+title: transform.HTMLToMarkdown
+description: Converts HTML to Markdown.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [transform.HTMLToMarkdown INPUT]
+---
+
+{{< new-in "0.151.0" />}}
+
+> [!note]
+> This function is experimental and its API may change in the future.
+
+The `transform.HTMLToMarkdown` function converts HTML to Markdown by utilizing the [`html-to-markdown`][] Go package.
+
+## Usage
+
+```go-html-template
+{{ .Content | transform.HTMLToMarkdown | safeHTML }}
+```
+
+## Plugins
+
+The conversion process is enabled by the following `html-to-markdown` plugins:
+
+Plugin|Description
+:--|:--
+Base|Implements basic shared functionality
+CommonMark|Implements Markdown according to the [Commonmark Spec][]
+Table|Implements tables according to the [GitHub Flavored Markdown Spec][]
+
+[`html-to-markdown`]: https://github.com/JohannesKaufmann/html-to-markdown?tab=readme-ov-file#readme
+[Commonmark Spec]: https://spec.commonmark.org/current/
+[GitHub Flavored Markdown Spec]: https://github.github.com/gfm/
diff --git a/documents/markdown/hugo-docs/en_functions_transform_Highlight.md b/documents/markdown/hugo-docs/en_functions_transform_Highlight.md
new file mode 100644
index 0000000..1e4e235
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_transform_Highlight.md
@@ -0,0 +1,53 @@
+---
+title: transform.Highlight
+description: Renders code with a syntax highlighter.
+categories: []
+keywords: [highlight]
+params:
+ functions_and_methods:
+ aliases: [highlight]
+ returnType: template.HTML
+ signatures: ['transform.Highlight CODE LANG [OPTIONS]']
+aliases: [/functions/highlight]
+---
+
+The `highlight` function uses the [Chroma] syntax highlighter, supporting over 200 languages with more than 40 [highlighting styles].
+
+[chroma]: https://github.com/alecthomas/chroma
+[highlighting styles]: /quick-reference/syntax-highlighting-styles/
+
+## Arguments
+
+The `transform.Highlight` shortcode takes three arguments.
+
+CODE
+: (`string`) The code to highlight.
+
+LANG
+: (`string`) The language of the code to highlight. Choose from one of the [supported languages]. This value is case-insensitive.
+
+OPTIONS
+: (`map or string`) A map or comma-separated key-value pairs wrapped in quotation marks. Set default values for each option in your [project configuration]. The key names are case-insensitive.
+
+[project configuration]: /configuration/markup#highlight
+[supported languages]: /content-management/syntax-highlighting#languages
+
+## Examples
+
+```go-html-template
+{{ $input := `fmt.Println("Hello World!")` }}
+{{ transform.Highlight $input "go" }}
+
+{{ $input := `console.log('Hello World!');` }}
+{{ $lang := "js" }}
+{{ transform.Highlight $input $lang "lineNos=table, style=api" }}
+
+{{ $input := `echo "Hello World!"` }}
+{{ $lang := "bash" }}
+{{ $opts := dict "lineNos" "table" "style" "dracula" }}
+{{ transform.Highlight $input $lang $opts }}
+```
+
+## Options
+
+{{% include "_common/syntax-highlighting-options.md" %}}
diff --git a/documents/markdown/hugo-docs/en_functions_transform_HighlightCodeBlock.md b/documents/markdown/hugo-docs/en_functions_transform_HighlightCodeBlock.md
new file mode 100644
index 0000000..2fc0b6f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_transform_HighlightCodeBlock.md
@@ -0,0 +1,36 @@
+---
+title: transform.HighlightCodeBlock
+description: Highlights code received in context within a code block render hook.
+categories: []
+keywords: [highlight]
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: highlight.HighlightResult
+ signatures: ['transform.HighlightCodeBlock CONTEXT [OPTIONS]']
+---
+
+This function is only useful within a code block render hook.
+
+Given the context passed into a code block render hook, `transform.HighlightCodeBlock` returns a `HighlightResult` object with two methods.
+
+.Wrapped
+: (`template.HTML`) Returns highlighted code wrapped in `<div>`, `<pre>`, and `<code>` elements. This is identical to the value returned by the transform.Highlight function.
+
+.Inner
+: (`template.HTML`) Returns highlighted code without any wrapping elements, allowing you to create your own wrapper.
+
+```go-html-template
+{{ $result := transform.HighlightCodeBlock . }}
+{{ $result.Wrapped }}
+```
+
+To override the default [highlighting options]:
+
+```go-html-template
+{{ $opts := merge .Options (dict "linenos" true) }}
+{{ $result := transform.HighlightCodeBlock . $opts }}
+{{ $result.Wrapped }}
+```
+
+[highlighting options]: /functions/transform/highlight/#options
diff --git a/documents/markdown/hugo-docs/en_functions_transform_Markdownify.md b/documents/markdown/hugo-docs/en_functions_transform_Markdownify.md
new file mode 100644
index 0000000..c22de1e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_transform_Markdownify.md
@@ -0,0 +1,27 @@
+---
+title: transform.Markdownify
+description: Renders Markdown to HTML.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [markdownify]
+ returnType: template.HTML
+ signatures: [transform.Markdownify INPUT]
+aliases: [/functions/markdownify]
+---
+
+```go-html-template
+<h2>{{ .Title | markdownify }}</h2>
+```
+
+If the resulting HTML is a single paragraph, Hugo removes the wrapping `p` tags to produce inline HTML as required per the example above.
+
+To keep the wrapping `p` tags for a single paragraph, use the [`RenderString`] method on the `Page` object, setting the `display` option to `block`.
+
+> [!note]
+> Although the `markdownify` function honors [Markdown render hooks] when rendering Markdown to HTML, use the `RenderString` method instead of `markdownify` if a render hook accesses `.Page` context. See issue [#9692] for details.
+
+[#9692]: https://github.com/gohugoio/hugo/issues/9692
+[`RenderString`]: /methods/page/renderstring/
+[Markdown render hooks]: /render-hooks/
diff --git a/documents/markdown/hugo-docs/en_functions_transform_Plainify.md b/documents/markdown/hugo-docs/en_functions_transform_Plainify.md
new file mode 100644
index 0000000..780cf46
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_transform_Plainify.md
@@ -0,0 +1,16 @@
+---
+title: transform.Plainify
+description: Returns a string with all HTML tags removed.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [plainify]
+ returnType: template.HTML
+ signatures: [transform.Plainify INPUT]
+aliases: [/functions/plainify]
+---
+
+```go-html-template
+{{ "<b>BatMan</b>" | plainify }} → BatMan
+```
diff --git a/documents/markdown/hugo-docs/en_functions_transform_PortableText.md b/documents/markdown/hugo-docs/en_functions_transform_PortableText.md
new file mode 100644
index 0000000..d100f5e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_transform_PortableText.md
@@ -0,0 +1,215 @@
+---
+title: transform.PortableText
+description: Converts Portable Text to Markdown.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [transform.PortableText MAP]
+---
+
+{{< new-in "0.145.0" />}}
+
+[Portable Text](https://www.portabletext.org/) is a JSON structure that represent rich text content in the [Sanity](https://www.sanity.io/) CMS. In Hugo, this function is typically used in a [Content Adapter](https://gohugo.io/content-management/content-adapters/) that creates pages from Sanity data.
+
+## Types supported
+
+- `block` and `span`
+- `image`. Note that the image handling is currently very simple; we link to the `asset.url` using `asset.altText` as the image alt text and `asset.title` as the title. For more fine grained control you may want to process the images in a [image render hook](/render-hooks/images/).
+- `code` (see the [code-input](https://www.sanity.io/plugins/code-input) plugin). Code will be rendered as [fenced code blocks](/contribute/documentation/#fenced-code-blocks) with any file name provided passed on as a markdown attribute.
+
+> [!note]
+> Since the Portable Text gets converted to Markdown before it gets passed to Hugo, rendering of links, headings, images and code blocks can be controlled with [Render Hooks](https://gohugo.io/render-hooks/).
+
+## Example
+
+### Content Adapter
+
+```go-html-template {file="content/_content.gotmpl" copy=true}
+{{ $projectID := "mysanityprojectid" }}
+{{ $useCached := true }}
+{{ $api := "api" }}
+{{ if $useCached }}
+ {{/* See https://www.sanity.io/docs/api-cdn */}}
+ {{ $api = "apicdn" }}
+{{ end }}
+{{ $url := printf "https://%s.%s.sanity.io/v2021-06-07/data/query/production" $projectID $api }}
+
+{{/* prettier-ignore-start */ -}}
+{{ $q := `*[_type == 'post']{
+ title, publishedAt, summary, slug, body[]{
+ ...,
+ _type == "image" => {
+ ...,
+ asset->{
+ _id,
+ path,
+ url,
+ altText,
+ title,
+ description,
+ metadata {
+ dimensions {
+ aspectRatio,
+ width,
+ height
+ }
+ }
+ }
+ }
+ },
+ }`
+}}
+{{/* prettier-ignore-end */ -}}
+{{ $body := dict "query" $q | jsonify }}
+{{ $opts := dict "method" "post" "body" $body }}
+{{ $r := resources.GetRemote $url $opts }}
+{{ $m := $r | transform.Unmarshal }}
+{{ $result := $m.result }}
+{{ range $result }}
+ {{ if not .slug }}
+ {{ continue }}
+ {{ end }}
+ {{ $markdown := transform.PortableText .body }}
+ {{ $content := dict
+ "mediaType" "text/markdown"
+ "value" $markdown
+ }}
+ {{ $params := dict
+ "portabletext" (.body | jsonify (dict "indent" " "))
+ }}
+ {{ $page := dict
+ "content" $content
+ "kind" "page"
+ "path" .slug.current
+ "title" .title
+ "date" (.publishedAt | time )
+ "summary" .summary
+ "params" $params
+ }}
+ {{ $.AddPage $page }}
+{{ end }}
+```
+
+### Sanity setup
+
+Below outlines a suitable Sanity studio setup for the above example.
+
+```ts {file="sanity.config.ts" copy=true}
+import {defineConfig} from 'sanity'
+import {structureTool} from 'sanity/structure'
+import {visionTool} from '@sanity/vision'
+import {schemaTypes} from './schemaTypes'
+import {media} from 'sanity-plugin-media'
+import {codeInput} from '@sanity/code-input'
+
+export default defineConfig({
+ name: 'default',
+ title: 'my-sanity-project',
+
+ projectId: 'mysanityprojectid',
+ dataset: 'production',
+
+ plugins: [structureTool(), visionTool(), media(),codeInput()],
+
+ schema: {
+ types: schemaTypes,
+ },
+})
+```
+
+Type/schema definition:
+
+```ts {file="schemaTypes/postType.ts" copy=true}
+import {defineField, defineType} from 'sanity'
+
+export const postType = defineType({
+ name: 'post',
+ title: 'Post',
+ type: 'document',
+ fields: [
+ defineField({
+ name: 'title',
+ type: 'string',
+ validation: (rule) => rule.required(),
+ }),
+ defineField({
+ name: 'summary',
+ type: 'string',
+ validation: (rule) => rule.required(),
+ }),
+ defineField({
+ name: 'slug',
+ type: 'slug',
+ options: {source: 'title'},
+ validation: (rule) => rule.required(),
+ }),
+ defineField({
+ name: 'publishedAt',
+ type: 'datetime',
+ initialValue: () => new Date().toISOString(),
+ validation: (rule) => rule.required(),
+ }),
+ defineField({
+ name: 'body',
+ type: 'array',
+ of: [
+ {
+ type: 'block',
+ },
+ {
+ type: 'image'
+ },
+ {
+ type: 'code',
+ options: {
+ language: 'css',
+ languageAlternatives: [
+ {title: 'HTML', value: 'html'},
+ {title: 'CSS', value: 'css'},
+ ],
+ withFilename: true,
+ },
+ },
+ ],
+ }),
+ ],
+})
+```
+
+Note that the above requires some additional plugins to be installed:
+
+```sh
+npm i sanity-plugin-media @sanity/code-input
+```
+
+```ts {file="schemaTypes/index.ts" copy=true}
+import {postType} from './postType'
+
+export const schemaTypes = [postType]
+```
+
+## Server setup
+
+Unfortunately, Sanity's API does not support [RFC 7234](https://tools.ietf.org/html/rfc7234) and their output changes even if the data has not. A recommended setup is therefore to use their cached `apicdn` endpoint (see above) and then set up a reasonable polling and file cache strategy in your Hugo configuration, e.g:
+
+<!-- markdownlint-disable MD049 -->
+{{< code-toggle file=hugo >}}
+[HTTPCache]
+ [[HTTPCache.polls]]
+ disable = false
+ low = '30s'
+ high = '3m'
+ [HTTPCache.polls.for]
+ includes = ['https://*.*.sanity.io/**']
+
+[caches.getresource]
+ dir = ':cacheDir/:project'
+ maxAge = "5m"
+{{< /code-toggle >}}
+<!-- markdownlint-enable MD049 -->
+
+The polling above will be used when running the server/watch mode and rebuild when you push new content in Sanity.
+
+See [Caching in resources.GetRemote](/functions/resources/getremote/#caching) for more fine grained control.
diff --git a/documents/markdown/hugo-docs/en_functions_transform_Remarshal.md b/documents/markdown/hugo-docs/en_functions_transform_Remarshal.md
new file mode 100644
index 0000000..d40c217
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_transform_Remarshal.md
@@ -0,0 +1,89 @@
+---
+title: transform.Remarshal
+description: Marshals a string of serialized data, or a map, into a string of serialized data in the specified format.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [transform.Remarshal FORMAT INPUT]
+aliases: [/functions/transform.remarshal]
+---
+
+The format must be one of `json`, `toml`, `yaml`, or `xml`. If the input is a string of serialized data, it must be valid JSON, TOML, YAML, or XML.
+
+> [!note]
+> This function is primarily a helper for Hugo's documentation, used to convert configuration and front matter examples to JSON, TOML, and YAML.
+>
+> This is not a general purpose converter, and may change without notice if required for Hugo's documentation site.
+
+Example 1
+: Convert a string of TOML to JSON.
+
+```go-html-template
+{{ $s := `
+ baseURL = 'https://example.org/'
+ locale = 'en-US'
+ title = 'ABC Widgets'
+`}}
+<pre>{{ transform.Remarshal "json" $s }}</pre>
+```
+
+Resulting HTML:
+
+```html
+<pre>{
+ "baseURL": "https://example.org/",
+ "locale": "en-US",
+ "title": "ABC Widgets"
+}
+</pre>
+```
+
+Rendered in browser:
+
+```text
+{
+ "baseURL": "https://example.org/",
+ "locale": "en-US",
+ "title": "ABC Widgets"
+}
+```
+
+Example 2
+: Convert a map to YAML.
+
+```go-html-template
+{{ $m := dict
+ "a" "Hugo rocks!"
+ "b" (dict "question" "What is 6x7?" "answer" 42)
+ "c" (slice "foo" "bar")
+}}
+<pre>{{ transform.Remarshal "yaml" $m }}</pre>
+```
+
+Resulting HTML:
+
+```html
+<pre>a: Hugo rocks!
+b:
+ answer: 42
+ question: What is 6x7?
+c:
+- foo
+- bar
+</pre>
+```
+
+Rendered in browser:
+
+```text
+a: Hugo rocks!
+b:
+ answer: 42
+ question: What is 6x7?
+c:
+- foo
+- bar
+```
diff --git a/documents/markdown/hugo-docs/en_functions_transform_ToMath.md b/documents/markdown/hugo-docs/en_functions_transform_ToMath.md
new file mode 100644
index 0000000..27b2f0d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_transform_ToMath.md
@@ -0,0 +1,196 @@
+---
+title: transform.ToMath
+description: Renders mathematical equations and expressions written in the LaTeX markup language.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: template.HTML
+ signatures: ['transform.ToMath INPUT [OPTIONS]']
+aliases: [/functions/tomath]
+---
+
+{{< new-in 0.132.0 />}}
+
+Hugo uses an embedded instance of the [KaTeX] display engine to render mathematical markup to HTML. You do not need to install the KaTeX display engine.
+
+```go-html-template
+{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" }}
+```
+
+> [!note]
+> By default, Hugo renders mathematical markup to [MathML], and does not require any CSS to display the result.
+>
+> To optimize rendering quality and accessibility, use the `htmlAndMathml` output option as described below. This approach requires an external stylesheet.
+
+```go-html-template
+{{ $opts := dict "output" "htmlAndMathml" }}
+{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" $opts }}
+```
+
+## Options
+
+Pass a map of options as the second argument to the `transform.ToMath` function. The options below are a subset of the KaTeX [rendering options].
+
+displayMode
+: (`bool`) Whether to render in display mode instead of inline mode. Default is `false`.
+
+errorColor
+: (`string`) The color of the error messages expressed as an RGB [hexadecimal color]. Default is `#cc0000`.
+
+fleqn
+: (`bool`) Whether to render flush left with a 2em left margin. Default is `false`.
+
+macros
+: (`map`) A map of macros to be used in the math expression. Default is `{}`.
+
+ ```go-html-template
+ {{ $macros := dict
+ "\\addBar" "\\bar{#1}"
+ "\\bold" "\\mathbf{#1}"
+ }}
+ {{ $opts := dict "macros" $macros }}
+ {{ transform.ToMath "\\addBar{y} + \\bold{H}" $opts }}
+ ```
+
+minRuleThickness
+: (`float`) The minimum thickness of the fraction lines in `em`. Default is `0.04`.
+
+output
+: (`string`) Determines the markup language of the output, one of `html`, `mathml`, or `htmlAndMathml`. Default is `mathml`.
+
+ With `html` and `htmlAndMathml` you must include the KaTeX style sheet within the `head` element of your base template.
+
+ ```html
+ <link
+ rel="stylesheet"
+ href="https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.css"
+ integrity="sha384-WcoG4HRXMzYzfCgiyfrySxx90XSl2rxY5mnVY5TwtWE6KLrArNKn0T/mOgNL0Mmi"
+ crossorigin="anonymous"
+ >
+ ```
+
+strict
+: {{< new-in 0.147.6 />}}
+: (`string`) Controls how KaTeX handles LaTeX features that offer convenience but aren't officially supported, one of `error`, `ignore`, or `warn`. Default is `error`.
+
+ - `error`: Throws an error when convenient, unsupported LaTeX features are encountered.
+ - `ignore`: Allows convenient, unsupported LaTeX features without any feedback.
+ - `warn`: {{< new-in 0.147.7 />}} Emits a warning when convenient, unsupported LaTeX features are encountered.
+
+ The `newLineInDisplayMode` error code, which flags the use of `\\` or `\newline` in display mode outside an array or tabular environment, is intentionally designed not to throw an error, despite this behavior being questionable.
+
+throwOnError
+: (`bool`) Whether to throw a `ParseError` when KaTeX encounters an unsupported command or invalid LaTeX. Default is `true`.
+
+## Error handling
+
+There are three ways to handle errors:
+
+1. Let KaTeX throw an error and fail the build. This is the default behavior.
+1. Set the `throwOnError` option to `false` to make KaTeX render the expression as an error instead of throwing an error. See [options](#options).
+1. Handle the error in your template.
+
+The example below demonstrates error handing within a template.
+
+## Example
+
+Instead of client-side JavaScript rendering of mathematical markup using MathJax or KaTeX, create a passthrough render hook which calls the `transform.ToMath` function.
+
+Step 1
+: Enable and configure the Goldmark [passthrough extension][] in your project configuration. The passthrough extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves.
+
+[passthrough extension]: /configuration/markup/#passthrough
+
+ {{< code-toggle file=hugo copy=true >}}
+ [markup.goldmark.extensions.passthrough]
+ enable = true
+ [markup.goldmark.extensions.passthrough.delimiters]
+ block = [['\[', '\]'], ['$$', '$$']]
+ inline = [['\(', '\)']]
+ {{< /code-toggle >}}
+
+ > [!note]
+ > The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration, you must double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting.
+
+Step 2
+: Create a [passthrough render hook][] to capture and render the LaTeX markup.4
+
+[passthrough render hook]: /render-hooks/passthrough/
+
+ ```go-html-template {file="layouts/_markup/render-passthrough.html" copy=true}
+ {{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }}
+ {{- with try (transform.ToMath .Inner $opts) }}
+ {{- with .Err }}
+ {{- errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }}
+ {{- else }}
+ {{- .Value }}
+ {{- $.Page.Store.Set "hasMath" true }}
+ {{- end }}
+ {{- end -}}
+ ```
+
+Step 3
+: In your base template, conditionally include the KaTeX CSS within the head element.
+
+ ```go-html-template {file="layouts/baseof.html" copy=true}
+ <head>
+ {{ $noop := .WordCount }}
+ {{ if .Page.Store.Get "hasMath" }}
+ <link
+ rel="stylesheet"
+ href="https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.css"
+ integrity="sha384-WcoG4HRXMzYzfCgiyfrySxx90XSl2rxY5mnVY5TwtWE6KLrArNKn0T/mOgNL0Mmi"
+ crossorigin="anonymous"
+ >
+ {{ end }}
+ </head>
+ ```
+
+ In the above, note the use of a [noop](g) statement to force content rendering before we check the value of `hasMath` with the `Store.Get` method.
+
+ > [!note]
+ > This conditional approach only identifies math on the current page. Mathematical expressions will not display correctly when one page's content is embedded within another. For example, if a [list page](g) calls the [`Content`][] or [`Summary`][] methods while ranging through its page collection, the list page will not load the KaTeX CSS.
+ >
+ > If this affects your site, use this conditional logic instead:
+ >
+ > ```go-html-template {file="layouts/baseof.html" copy=true}
+ > {{ $noop := .WordCount }}
+ > {{ if or (.Page.Store.Get "hasMath") .IsNode }}
+ > <link rel="stylesheet" href="...">
+ > {{ end }}
+ > ```
+
+Step 4
+: Add some mathematical markup to your content, then test.
+
+ ```text {file="content/example.md"}
+ This is an inline \(a^*=x-b^*\) equation.
+
+ These are block equations:
+
+ \[a^*=x-b^*\]
+
+ $$a^*=x-b^*$$
+ ```
+
+## Chemistry
+
+{{< new-in 0.144.0 />}}
+
+You can also use the `transform.ToMath` function to render chemical equations, leveraging the `\ce` and `\pu` functions from the [mhchem] package.
+
+```text
+$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$
+```
+
+$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$
+
+[`Content`]: /methods/page/content/
+[`Summary`]: /methods/page/summary/
+[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
+[KaTeX]: https://katex.org/
+[MathML]: https://developer.mozilla.org/en-US/docs/Web/MathML
+[mhchem]: https://mhchem.github.io/MathJax-mhchem/
+[rendering options]: https://katex.org/docs/options.html
diff --git a/documents/markdown/hugo-docs/en_functions_transform_Unmarshal.md b/documents/markdown/hugo-docs/en_functions_transform_Unmarshal.md
new file mode 100644
index 0000000..c92f6a0
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_transform_Unmarshal.md
@@ -0,0 +1,371 @@
+---
+title: transform.Unmarshal
+description: Parses serialized data and returns a map or an array. Supports CSV, JSON, TOML, YAML, and XML.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [unmarshal]
+ returnType: any
+ signatures: ['transform.Unmarshal [OPTIONS] INPUT']
+aliases: [/functions/transform.unmarshal]
+---
+
+The input can be a string or a [resource](g).
+
+## Options
+
+delimiter
+: (`string`) Applicable to CSV files. The delimiter used. Default is `,`.
+
+comment
+: (`string`) Applicable to CSV files. The comment character used in the CSV. If set, lines beginning with the comment character without preceding whitespace are ignored.
+
+format
+: {{< new-in 0.149.0 />}}
+: (`string`) The serialization format of the input, one of `csv`, `json`, `org`, `toml`, `xml`, or `yaml`. If empty or unspecified, Hugo infers the format from the input. For resources, this option is only needed if the file lacks an extension or to override the inferred format. For strings, it's only required when the format is ambiguous.
+
+lazyQuotes
+: (`bool`) Applicable to CSV files. Whether to allow a quote in an unquoted field, or to allow a non-doubled quote in a quoted field. Default is `false`.
+
+targetType
+: {{< new-in 0.146.7 />}}
+: (`string`) Applicable to CSV files. The target data type, either `slice` or `map`. Default is `slice`.
+
+## Unmarshal a string
+
+```go-html-template
+{{ $string := `
+title: Les Misérables
+author: Victor Hugo
+`}}
+
+{{ $book := transform.Unmarshal $string }}
+{{ $book.title }} → Les Misérables
+{{ $book.author }} → Victor Hugo
+```
+
+## Unmarshal a resource
+
+Use the `transform.Unmarshal` function with global, page, and remote resources.
+
+### Global resource
+
+A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
+
+```text
+assets/
+└── data/
+ └── books.json
+```
+
+```go-html-template
+{{ $data := dict }}
+{{ $path := "data/books.json" }}
+{{ with resources.Get $path }}
+ {{ with . | transform.Unmarshal }}
+ {{ $data = . }}
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get global resource %q" $path }}
+{{ end }}
+
+{{ range where $data "author" "Victor Hugo" }}
+ {{ .title }} → Les Misérables
+{{ end }}
+```
+
+### Page resource
+
+A page resource is a file within a [page bundle].
+
+```text
+content/
+├── post/
+│ └── book-reviews/
+│ ├── books.json
+│ └── index.md
+└── _index.md
+```
+
+```go-html-template
+{{ $data := dict }}
+{{ $path := "books.json" }}
+{{ with .Resources.Get $path }}
+ {{ with . | transform.Unmarshal }}
+ {{ $data = . }}
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get page resource %q" $path }}
+{{ end }}
+
+{{ range where $data "author" "Victor Hugo" }}
+ {{ .title }} → Les Misérables
+{{ end }}
+```
+
+### Remote resource
+
+A remote resource is a file on a remote server, accessible via HTTP or HTTPS.
+
+```go-html-template
+{{ $data := dict }}
+{{ $url := "https://example.org/books.json" }}
+{{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else with .Value }}
+ {{ $data = . | transform.Unmarshal }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+ {{ end }}
+{{ end }}
+
+{{ range where $data "author" "Victor Hugo" }}
+ {{ .title }} → Les Misérables
+{{ end }}
+```
+
+> [!note]
+> When retrieving remote data, a misconfigured server may send a response header with an incorrect [Content-Type]. For example, the server may set the Content-Type header to `application/octet-stream` instead of `application/json`.
+>
+> In these cases, pass the resource `Content` through the `transform.Unmarshal` function instead of passing the resource itself. For example, in the above, do this instead:
+>
+> `{{ $data = .Content | transform.Unmarshal }}`
+
+## Working with CSV
+
+The examples below use this CSV file:
+
+```csv
+"name","type","breed","age"
+"Spot","dog","Collie",3
+"Rover","dog","Boxer",5
+"Felix","cat","Calico",7
+```
+
+To render an HTML table from a CSV file:
+
+```go-html-template
+{{ $data := slice }}
+{{ $file := "pets.csv" }}
+{{ with or (.Resources.Get $file) (resources.Get $file) }}
+ {{ $opts := dict "targetType" "slice" }}
+ {{ $data = transform.Unmarshal $opts . }}
+{{ end }}
+
+{{ with $data }}
+ <table>
+ <thead>
+ <tr>
+ {{ range index . 0 }}
+ <th>{{ . }}</th>
+ {{ end }}
+ </tr>
+ </thead>
+ <tbody>
+ {{ range . | after 1 }}
+ <tr>
+ {{ range . }}
+ <td>{{ . }}</td>
+ {{ end }}
+ </tr>
+ {{ end }}
+ </tbody>
+ </table>
+{{ end }}
+```
+
+To extract a subset of the data, or to sort the data, unmarshal to a map instead of a slice:
+
+```go-html-template
+{{ $data := dict }}
+{{ $file := "pets.csv" }}
+{{ with or (.Resources.Get $file) (resources.Get $file) }}
+ {{ $opts := dict "targetType" "map" }}
+ {{ $data = transform.Unmarshal $opts . }}
+{{ end }}
+
+{{ with sort (where $data "type" "dog") "name" "asc" }}
+ <table>
+ <thead>
+ <tr>
+ <th>name</th>
+ <th>type</th>
+ <th>breed</th>
+ <th>age</th>
+ </tr>
+ </thead>
+ <tbody>
+ {{ range . }}
+ <tr>
+ <td>{{ .name }}</td>
+ <td>{{ .type }}</td>
+ <td>{{ .breed }}</td>
+ <td>{{ .age }}</td>
+ </tr>
+ {{ end }}
+ </tbody>
+ </table>
+{{ end }}
+```
+
+## Working with XML
+
+When unmarshaling an XML file, do not include the root node when accessing data. For example, after unmarshaling the RSS feed below, access the feed title with `$data.channel.title`.
+
+```xml
+<?xml version="1.0" encoding="utf-8" standalone="yes"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+ <channel>
+ <title>Books on Example Site</title>
+ <link>https://example.org/books/</link>
+ <description>Recent content in Books on Example Site</description>
+ <language>en-US</language>
+ <atom:link href="https://example.org/books/index.xml" rel="self" type="application/rss+xml" />
+ <item>
+ <title>The Hunchback of Notre Dame</title>
+ <description>Written by Victor Hugo</description>
+ <link>https://example.org/books/the-hunchback-of-notre-dame/</link>
+ <pubDate>Mon, 09 Oct 2023 09:27:12 -0700</pubDate>
+ <guid>https://example.org/books/the-hunchback-of-notre-dame/</guid>
+ </item>
+ <item>
+ <title>Les Misérables</title>
+ <description>Written by Victor Hugo</description>
+ <link>https://example.org/books/les-miserables/</link>
+ <pubDate>Mon, 09 Oct 2023 09:27:11 -0700</pubDate>
+ <guid>https://example.org/books/les-miserables/</guid>
+ </item>
+ </channel>
+</rss>
+```
+
+Get the remote data:
+
+```go-html-template
+{{ $data := dict }}
+{{ $url := "https://example.org/books/index.xml" }}
+{{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else with .Value }}
+ {{ $data = . | transform.Unmarshal }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+ {{ end }}
+{{ end }}
+```
+
+Inspect the data structure:
+
+```go-html-template
+<pre>{{ debug.Dump $data }}</pre>
+```
+
+List the book titles:
+
+```go-html-template
+{{ with $data.channel.item }}
+ <ul>
+ {{ range . }}
+ <li>{{ .title }}</li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+Hugo renders this to:
+
+```html
+<ul>
+ <li>The Hunchback of Notre Dame</li>
+ <li>Les Misérables</li>
+</ul>
+```
+
+### XML attributes and namespaces
+
+Let's add a `lang` attribute to the `title` nodes of our RSS feed, and a namespaced node for the ISBN number:
+
+```xml
+<?xml version="1.0" encoding="utf-8" standalone="yes"?>
+<rss version="2.0"
+ xmlns:atom="http://www.w3.org/2005/Atom"
+ xmlns:isbn="http://schemas.isbn.org/ns/1999/basic.dtd"
+>
+ <channel>
+ <title>Books on Example Site</title>
+ <link>https://example.org/books/</link>
+ <description>Recent content in Books on Example Site</description>
+ <language>en-US</language>
+ <atom:link href="https://example.org/books/index.xml" rel="self" type="application/rss+xml" />
+ <item>
+ <title lang="en">The Hunchback of Notre Dame</title>
+ <description>Written by Victor Hugo</description>
+ <isbn:number>9780140443530</isbn:number>
+ <link>https://example.org/books/the-hunchback-of-notre-dame/</link>
+ <pubDate>Mon, 09 Oct 2023 09:27:12 -0700</pubDate>
+ <guid>https://example.org/books/the-hunchback-of-notre-dame/</guid>
+ </item>
+ <item>
+ <title lang="fr">Les Misérables</title>
+ <description>Written by Victor Hugo</description>
+ <isbn:number>9780451419439</isbn:number>
+ <link>https://example.org/books/les-miserables/</link>
+ <pubDate>Mon, 09 Oct 2023 09:27:11 -0700</pubDate>
+ <guid>https://example.org/books/les-miserables/</guid>
+ </item>
+ </channel>
+</rss>
+```
+
+After retrieving the remote data, inspect the data structure:
+
+```go-html-template
+<pre>{{ debug.Dump $data }}</pre>
+```
+
+Each item node looks like this:
+
+```json
+{
+ "description": "Written by Victor Hugo",
+ "guid": "https://example.org/books/the-hunchback-of-notre-dame/",
+ "link": "https://example.org/books/the-hunchback-of-notre-dame/",
+ "number": "9780140443530",
+ "pubDate": "Mon, 09 Oct 2023 09:27:12 -0700",
+ "title": {
+ "#text": "The Hunchback of Notre Dame",
+ "-lang": "en"
+ }
+}
+```
+
+The title keys do not begin with an underscore or a letter---they are not valid [identifiers](g). Use the [`index`] function to access the values:
+
+```go-html-template
+{{ with $data.channel.item }}
+ <ul>
+ {{ range . }}
+ {{ $title := index .title "#text" }}
+ {{ $lang := index .title "-lang" }}
+ {{ $ISBN := .number }}
+ <li>{{ $title }} ({{ $lang }}) {{ $ISBN }}</li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+Hugo renders this to:
+
+```html
+<ul>
+ <li>The Hunchback of Notre Dame (en) 9780140443530</li>
+ <li>Les Misérables (fr) 9780451419439</li>
+</ul>
+```
+
+[`index`]: /functions/collections/indexfunction/
+[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
+[page bundle]: /content-management/page-bundles/
diff --git a/documents/markdown/hugo-docs/en_functions_transform_XMLEscape.md b/documents/markdown/hugo-docs/en_functions_transform_XMLEscape.md
new file mode 100644
index 0000000..d9a9cdf
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_transform_XMLEscape.md
@@ -0,0 +1,38 @@
+---
+title: transform.XMLEscape
+description: Returns the given string, removing disallowed characters then escaping the result to its XML equivalent.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [transform.XMLEscape INPUT]
+---
+
+The `transform.XMLEscape` function removes [disallowed characters][] as defined in the XML specification, then escapes the result by replacing the following characters with [HTML entities]:
+
+- `"` → `"`
+- `'` → `'`
+- `&` → `&`
+- `<` → `<`
+- `>` → `>`
+- `\t` → `	`
+- `\n` → `
`
+- `\r` → `
`
+
+For example:
+
+```go-html-template
+{{ transform.XMLEscape "<p>abc</p>" }} → <p>abc</p>
+```
+
+When using `transform.XMLEscape` in a template rendered by Go's [`html/template`][] package, declare the string to be safe HTML to avoid double escaping. For example, in an RSS template:
+
+```xml {file="layouts/rss.xml"}
+<description>{{ .Summary | transform.XMLEscape | safeHTML }}</description>
+```
+
+[disallowed characters]: https://www.w3.org/TR/xml/#charsets
+[html entities]: https://developer.mozilla.org/en-us/docs/glossary/entity
+[`html/template`]: https://pkg.go.dev/html/template
diff --git a/documents/markdown/hugo-docs/en_functions_transform__index.md b/documents/markdown/hugo-docs/en_functions_transform__index.md
new file mode 100644
index 0000000..19c271b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_transform__index.md
@@ -0,0 +1,7 @@
+---
+title: Transform functions
+linkTitle: transform
+description: Use these functions to transform values from one format to another.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_functions_urls_AbsLangURL.md b/documents/markdown/hugo-docs/en_functions_urls_AbsLangURL.md
new file mode 100644
index 0000000..b2cf021
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_urls_AbsLangURL.md
@@ -0,0 +1,72 @@
+---
+title: urls.AbsLangURL
+description: Returns an absolute URL with a language prefix, if any.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [absLangURL]
+ returnType: string
+ signatures: [urls.AbsLangURL INPUT]
+aliases: [/functions/abslangurl]
+---
+
+Use this function with both monolingual and multilingual configurations. The URL returned by this function depends on:
+
+- Whether the input begins with a slash (`/`)
+- The `baseURL` in your project configuration
+- The language prefix, if any
+
+This is the project configuration for the examples that follow:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'en'
+defaultContentLanguageInSubdir = true
+[languages.en]
+weight = 1
+[languages.es]
+weight = 2
+{{< /code-toggle >}}
+
+## Input does not begin with a slash
+
+If the input does not begin with a slash, the path in the resulting URL will be relative to the `baseURL` in your project configuration.
+
+When rendering the `en` site with `baseURL = https://example.org/`
+
+```go-html-template
+{{ absLangURL "" }} → https://example.org/en/
+{{ absLangURL "articles" }} → https://example.org/en/articles
+{{ absLangURL "style.css" }} → https://example.org/en/style.css
+```
+
+When rendering the `en` site with `baseURL = https://example.org/docs/`
+
+```go-html-template
+{{ absLangURL "" }} → https://example.org/docs/en/
+{{ absLangURL "articles" }} → https://example.org/docs/en/articles
+{{ absLangURL "style.css" }} → https://example.org/docs/en/style.css
+```
+
+## Input begins with a slash
+
+If the input begins with a slash, the path in the resulting URL will be relative to the protocol+host of the `baseURL` in your project configuration.
+
+When rendering the `en` site with `baseURL = https://example.org/`
+
+```go-html-template
+{{ absLangURL "/" }} → https://example.org/en/
+{{ absLangURL "/articles" }} → https://example.org/en/articles
+{{ absLangURL "/style.css" }} → https://example.org/en/style.css
+```
+
+When rendering the `en` site with `baseURL = https://example.org/docs/`
+
+```go-html-template
+{{ absLangURL "/" }} → https://example.org/en/
+{{ absLangURL "/articles" }} → https://example.org/en/articles
+{{ absLangURL "/style.css" }} → https://example.org/en/style.css
+```
+
+> [!note]
+> As illustrated by the previous example, using a leading slash is rarely desirable and can lead to unexpected outcomes. In nearly all cases, omit the leading slash.
diff --git a/documents/markdown/hugo-docs/en_functions_urls_AbsURL.md b/documents/markdown/hugo-docs/en_functions_urls_AbsURL.md
new file mode 100644
index 0000000..e298624
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_urls_AbsURL.md
@@ -0,0 +1,62 @@
+---
+title: urls.AbsURL
+description: Returns an absolute URL.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [absURL]
+ returnType: string
+ signatures: [urls.AbsURL INPUT]
+aliases: [/functions/absurl]
+---
+
+With multilingual configurations, use the [`urls.AbsLangURL`] function instead. The URL returned by this function depends on:
+
+- Whether the input begins with a slash (`/`)
+- The `baseURL` in your project configuration
+
+## Input does not begin with a slash
+
+If the input does not begin with a slash, the path in the resulting URL will be relative to the `baseURL` in your project configuration.
+
+With `baseURL = https://example.org/`
+
+```go-html-template
+{{ absURL "" }} → https://example.org/
+{{ absURL "articles" }} → https://example.org/articles
+{{ absURL "style.css" }} → https://example.org/style.css
+```
+
+With `baseURL = https://example.org/docs/`
+
+```go-html-template
+{{ absURL "" }} → https://example.org/docs/
+{{ absURL "articles" }} → https://example.org/docs/articles
+{{ absURL "style.css" }} → https://example.org/docs/style.css
+```
+
+## Input begins with a slash
+
+If the input begins with a slash, the path in the resulting URL will be relative to the protocol+host of the `baseURL` in your project configuration.
+
+With `baseURL = https://example.org/`
+
+```go-html-template
+{{ absURL "/" }} → https://example.org/
+{{ absURL "/articles" }} → https://example.org/articles
+{{ absURL "/style.css" }} → https://example.org/style.css
+```
+
+With `baseURL = https://example.org/docs/`
+
+```go-html-template
+{{ absURL "/" }} → https://example.org/
+{{ absURL "/articles" }} → https://example.org/articles
+{{ absURL "/style.css" }} → https://example.org/style.css
+```
+
+> [!note]
+> As illustrated by the previous example, using a leading slash is rarely desirable and can lead to unexpected outcomes. In nearly all cases, omit the leading slash.
+
+[`urls.AbsLangURL`]: /functions/urls/abslangurl/
diff --git a/documents/markdown/hugo-docs/en_functions_urls_Anchorize.md b/documents/markdown/hugo-docs/en_functions_urls_Anchorize.md
new file mode 100644
index 0000000..d529ec4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_urls_Anchorize.md
@@ -0,0 +1,36 @@
+---
+title: urls.Anchorize
+description: Returns the given string, sanitized for usage in an HTML id attribute.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [anchorize]
+ returnType: string
+ signatures: [urls.Anchorize INPUT]
+aliases: [/functions/anchorize]
+---
+
+{{% include "/_common/functions/urls/anchorize-vs-urlize.md" %}}
+
+## Sanitizing logic
+
+With the default Markdown renderer, Goldmark, the sanitizing logic is controlled by your project configuration:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.parser]
+autoHeadingIDType = 'github'
+{{< /code-toggle >}}
+
+This controls the behavior of the `anchorize` function and the generation of heading IDs when rendering Markdown to HTML.
+
+Set `autoHeadingIDType` to one of:
+
+github
+: Compatible with GitHub. This is the default.
+
+github-ascii
+: Similar to the `github` setting, but removes non-ASCII characters.
+
+blackfriday
+: Provided for backwards compatibility with Hugo v0.59.1 and earlier. This option will be removed in a future release.
diff --git a/documents/markdown/hugo-docs/en_functions_urls_JoinPath.md b/documents/markdown/hugo-docs/en_functions_urls_JoinPath.md
new file mode 100644
index 0000000..b9da7e4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_urls_JoinPath.md
@@ -0,0 +1,27 @@
+---
+title: urls.JoinPath
+description: Joins the provided elements into a URL string and cleans the result of any ./ or ../ elements. If the argument list is empty, JoinPath returns an empty string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [urls.JoinPath ELEMENT...]
+aliases: [/functions/urls.joinpath]
+---
+
+```go-html-template
+{{ urls.JoinPath }} → "" (empty string)
+{{ urls.JoinPath "" }} → /
+{{ urls.JoinPath "a" }} → a
+{{ urls.JoinPath "a" "b" }} → a/b
+{{ urls.JoinPath "/a" "b" }} → /a/b
+{{ urls.JoinPath "https://example.org" "b" }} → https://example.org/b
+
+{{ urls.JoinPath (slice "a" "b") }} → a/b
+```
+
+Unlike the [`path.Join`] function, `urls.JoinPath` retains consecutive leading slashes.
+
+[`path.Join`]: /functions/path/join/
diff --git a/documents/markdown/hugo-docs/en_functions_urls_Parse.md b/documents/markdown/hugo-docs/en_functions_urls_Parse.md
new file mode 100644
index 0000000..7def5fb
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_urls_Parse.md
@@ -0,0 +1,35 @@
+---
+title: urls.Parse
+description: Parses a URL into a URL structure.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: url.URL
+ signatures: [urls.Parse URL]
+aliases: [/functions/urls.parse]
+---
+
+The `urls.Parse` function parses a URL into a [URL structure](https://godoc.org/net/url#URL). The URL may be relative (a path, without a host) or absolute (starting with a [scheme]). Hugo throws an error when parsing an invalid URL.
+
+[scheme]: https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml#uri-schemes-1
+
+```go-html-template
+{{ $url := "https://example.org:123/foo?a=6&b=7#bar" }}
+{{ $u := urls.Parse $url }}
+
+{{ $u.String }} → https://example.org:123/foo?a=6&b=7#bar
+{{ $u.IsAbs }} → true
+{{ $u.Scheme }} → https
+{{ $u.Host }} → example.org:123
+{{ $u.Hostname }} → example.org
+{{ $u.RequestURI }} → /foo?a=6&b=7
+{{ $u.Path }} → /foo
+{{ $u.RawQuery }} → a=6&b=7
+{{ $u.Query }} → map[a:[6] b:[7]]
+{{ $u.Query.a }} → [6]
+{{ $u.Query.Get "a" }} → 6
+{{ $u.Query.Has "b" }} → true
+{{ $u.Fragment }} → bar
+```
diff --git a/documents/markdown/hugo-docs/en_functions_urls_PathEscape.md b/documents/markdown/hugo-docs/en_functions_urls_PathEscape.md
new file mode 100644
index 0000000..7b19af0
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_urls_PathEscape.md
@@ -0,0 +1,22 @@
+---
+title: urls.PathEscape
+description: Returns the given string, applying percent-encoding to special characters and reserved delimiters so it can be safely used as a segment within a URL path.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [urls.PathEscape INPUT]
+---
+
+{{< new-in v0.153.0 />}}
+
+The `urls.PathEscape` function does the inverse transformation of [`urls.PathUnescape`][].
+
+```go-html-template
+{{ urls.PathEscape "my café" }} → my%20caf%C3%A9
+```
+
+Use this function to escape a string so that it can be safely used as an individual segment within a URL path.
+
+[`urls.PathUnescape`]: /functions/urls/PathUnescape/
diff --git a/documents/markdown/hugo-docs/en_functions_urls_PathUnescape.md b/documents/markdown/hugo-docs/en_functions_urls_PathUnescape.md
new file mode 100644
index 0000000..ab2057d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_urls_PathUnescape.md
@@ -0,0 +1,22 @@
+---
+title: urls.PathUnescape
+description: Returns the given string, replacing all percent-encoded sequences with the corresponding unescaped characters.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [urls.PathUnescape INPUT]
+---
+
+{{< new-in v0.153.0 />}}
+
+The `urls.PathUnescape` function does the inverse transformation of [`urls.PathEscape`][].
+
+```go-html-template
+{{ urls.PathUnescape "A%2Fb%2Fc%3Fd=%C3%A9&f=g+h" }} → A/b/c?d=é&f=g+h
+```
+
+Use this function to decode an individual segment within a URL path.
+
+[`urls.PathEscape`]: /functions/urls/PathEscape/
diff --git a/documents/markdown/hugo-docs/en_functions_urls_Ref.md b/documents/markdown/hugo-docs/en_functions_urls_Ref.md
new file mode 100644
index 0000000..92abed9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_urls_Ref.md
@@ -0,0 +1,46 @@
+---
+title: urls.Ref
+description: Returns the absolute URL of the page with the given path, language, and output format.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [ref]
+ returnType: string
+ signatures:
+ - urls.Ref PAGE PATH
+ - urls.Ref PAGE OPTIONS
+aliases: [/functions/ref]
+---
+
+## Usage
+
+The `ref` function takes two arguments:
+
+1. The context for resolving relative paths (typically the current page).
+1. Either the target page's path or an options map (see below).
+
+## Options
+
+{{% include "_common/ref-and-relref-options.md" %}}
+
+## Examples
+
+The following examples show the rendered output for a page on the English version of the site:
+
+```go-html-template
+{{ ref . "/books/book-1" }} → https://example.org/en/books/book-1/
+
+{{ $opts := dict "path" "/books/book-1" }}
+{{ ref . $opts }} → https://example.org/en/books/book-1/
+
+{{ $opts := dict "path" "/books/book-1" "lang" "de" }}
+{{ ref . $opts }} → https://example.org/de/books/book-1/
+
+{{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }}
+{{ ref . $opts }} → https://example.org/de/books/book-1/index.json
+```
+
+## Error handling
+
+{{% include "_common/ref-and-relref-error-handling.md" %}}
diff --git a/documents/markdown/hugo-docs/en_functions_urls_RelLangURL.md b/documents/markdown/hugo-docs/en_functions_urls_RelLangURL.md
new file mode 100644
index 0000000..ea31316
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_urls_RelLangURL.md
@@ -0,0 +1,82 @@
+---
+title: urls.RelLangURL
+description: Returns a relative URL with a language prefix, if any.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [relLangURL]
+ returnType: string
+ signatures: [urls.RelLangURL INPUT]
+aliases: [/functions/rellangurl]
+---
+
+Use this function with both monolingual and multilingual configurations. The URL returned by this function depends on:
+
+- Whether the input begins with a slash (`/`)
+- The `baseURL` in your project configuration
+- The language prefix, if any
+
+This is the project configuration for the examples that follow:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'en'
+defaultContentLanguageInSubdir = true
+[languages.en]
+weight = 1
+[languages.es]
+weight = 2
+{{< /code-toggle >}}
+
+## Input does not begin with a slash
+
+If the input does not begin with a slash, the resulting URL will be relative to the `baseURL` in your project configuration.
+
+When rendering the `en` site with `baseURL = https://example.org/`
+
+```go-html-template
+{{ relLangURL "" }} → /en/
+{{ relLangURL "articles" }} → /en/articles
+{{ relLangURL "style.css" }} → /en/style.css
+{{ relLangURL "https://example.org" }} → https://example.org
+{{ relLangURL "https://example.org/" }} → /en
+{{ relLangURL "https://www.example.org" }} → https://www.example.org
+{{ relLangURL "https://www.example.org/" }} → https://www.example.org/
+```
+
+When rendering the `en` site with `baseURL = https://example.org/docs/`
+
+```go-html-template
+{{ relLangURL "" }} → /docs/en/
+{{ relLangURL "articles" }} → /docs/en/articles
+{{ relLangURL "style.css" }} → /docs/en/style.css
+{{ relLangURL "https://example.org" }} → https://example.org
+{{ relLangURL "https://example.org/" }} → https://example.org/
+{{ relLangURL "https://example.org/docs" }} → https://example.org/docs
+{{ relLangURL "https://example.org/docs/" }} → /docs/en
+{{ relLangURL "https://www.example.org" }} → https://www.example.org
+{{ relLangURL "https://www.example.org/" }} → https://www.example.org/
+```
+
+## Input begins with a slash
+
+If the input begins with a slash, the resulting URL will be relative to the protocol+host of the `baseURL` in your project configuration.
+
+When rendering the `en` site with `baseURL = https://example.org/`
+
+```go-html-template
+{{ relLangURL "/" }} → /en/
+{{ relLangURL "/articles" }} → /en/articles
+{{ relLangURL "/style.css" }} → /en/style.css
+```
+
+When rendering the `en` site with `baseURL = https://example.org/docs/`
+
+```go-html-template
+{{ relLangURL "/" }} → /en/
+{{ relLangURL "/articles" }} → /en/articles
+{{ relLangURL "/style.css" }} → /en/style.css
+```
+
+> [!note]
+> As illustrated by the previous example, using a leading slash is rarely desirable and can lead to unexpected outcomes. In nearly all cases, omit the leading slash.
diff --git a/documents/markdown/hugo-docs/en_functions_urls_RelRef.md b/documents/markdown/hugo-docs/en_functions_urls_RelRef.md
new file mode 100644
index 0000000..aa7acf5
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_urls_RelRef.md
@@ -0,0 +1,46 @@
+---
+title: urls.RelRef
+description: Returns the relative URL of the page with the given path, language, and output format.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [relref]
+ returnType: string
+ signatures:
+ - urls.RelRef PAGE PATH
+ - urls.RelRef PAGE OPTIONS
+aliases: [/functions/relref]
+---
+
+## Usage
+
+The `relref` function takes two arguments:
+
+1. The context for resolving relative paths (typically the current page).
+1. Either the target page's path or an options map (see below).
+
+## Options
+
+{{% include "_common/ref-and-relref-options.md" %}}
+
+## Examples
+
+The following examples show the rendered output for a page on the English version of the site:
+
+```go-html-template
+{{ relref . "/books/book-1" }} → /en/books/book-1/
+
+{{ $opts := dict "path" "/books/book-1" }}
+{{ relref . $opts }} → /en/books/book-1/
+
+{{ $opts := dict "path" "/books/book-1" "lang" "de" }}
+{{ relref . $opts }} → /de/books/book-1/
+
+{{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }}
+{{ relref . $opts }} → /de/books/book-1/index.json
+```
+
+## Error handling
+
+{{% include "_common/ref-and-relref-error-handling.md" %}}
diff --git a/documents/markdown/hugo-docs/en_functions_urls_RelURL.md b/documents/markdown/hugo-docs/en_functions_urls_RelURL.md
new file mode 100644
index 0000000..97328eb
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_urls_RelURL.md
@@ -0,0 +1,72 @@
+---
+title: urls.RelURL
+description: Returns a relative URL.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [relURL]
+ returnType: string
+ signatures: [urls.RelURL INPUT]
+aliases: [/functions/relurl]
+---
+
+With multilingual configurations, use the [`urls.RelLangURL`] function instead. The URL returned by this function depends on:
+
+- Whether the input begins with a slash (`/`)
+- The `baseURL` in your project configuration
+
+## Input does not begin with a slash
+
+If the input does not begin with a slash, the resulting URL will be relative to the `baseURL` in your project configuration.
+
+With `baseURL = https://example.org/`
+
+```go-html-template
+{{ relURL "" }} → /
+{{ relURL "articles" }} → /articles
+{{ relURL "style.css" }} → /style.css
+{{ relURL "https://example.org" }} → https://example.org
+{{ relURL "https://example.org/" }} → /
+{{ relURL "https://www.example.org" }} → https://www.example.org
+{{ relURL "https://www.example.org/" }} → https://www.example.org/
+```
+
+With `baseURL = https://example.org/docs/`
+
+```go-html-template
+{{ relURL "" }} → /docs/
+{{ relURL "articles" }} → /docs/articles
+{{ relURL "style.css" }} → /docs/style.css
+{{ relURL "https://example.org" }} → https://example.org
+{{ relURL "https://example.org/" }} → https://example.org/
+{{ relURL "https://example.org/docs" }} → https://example.org/docs
+{{ relURL "https://example.org/docs/" }} → /docs
+{{ relURL "https://www.example.org" }} → https://www.example.org
+{{ relURL "https://www.example.org/" }} → https://www.example.org/
+```
+
+## Input begins with a slash
+
+If the input begins with a slash, the resulting URL will be relative to the protocol+host of the `baseURL` in your project configuration.
+
+With `baseURL = https://example.org/`
+
+```go-html-template
+{{ relURL "/" }} → /
+{{ relURL "/articles" }} → /articles
+{{ relURL "/style.css" }} → /style.css
+```
+
+With `baseURL = https://example.org/docs/`
+
+```go-html-template
+{{ relURL "/" }} → /
+{{ relURL "/articles" }} → /articles
+{{ relURL "/style.css" }} → /style.css
+```
+
+> [!note]
+> As illustrated by the previous example, using a leading slash is rarely desirable and can lead to unexpected outcomes. In nearly all cases, omit the leading slash.
+
+[`urls.RelLangURL`]: /functions/urls/rellangurl/
diff --git a/documents/markdown/hugo-docs/en_functions_urls_URLize.md b/documents/markdown/hugo-docs/en_functions_urls_URLize.md
new file mode 100644
index 0000000..28bc1dc
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_urls_URLize.md
@@ -0,0 +1,61 @@
+---
+title: urls.URLize
+description: Returns the given string, sanitized for usage in a URL.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [urlize]
+ returnType: string
+ signatures: [urls.URLize INPUT]
+aliases: [/functions/urlize]
+---
+
+{{% include "/_common/functions/urls/anchorize-vs-urlize.md" %}}
+
+## Example
+
+Use the `urlize` function to create a link to a [term page](g).
+
+Consider this project configuration:
+
+{{< code-toggle file=hugo >}}
+[taxonomies]
+author = 'authors'
+{{< /code-toggle >}}
+
+And this front matter:
+
+{{< code-toggle file=content/books/les-miserables.md fm=true >}}
+title = 'Les Misérables'
+authors = ['Victor Hugo']
+{{< /code-toggle >}}
+
+The published site will have this structure:
+
+```text
+public/
+├── authors/
+│ ├── victor-hugo/
+│ │ └── index.html
+│ └── index.html
+├── books/
+│ ├── les-miserables/
+│ │ └── index.html
+│ └── index.html
+└── index.html
+```
+
+To create a link to the term page:
+
+```go-html-template
+{{ $taxonomy := "authors" }}
+{{ $term := "Victor Hugo" }}
+{{ with index .Site.Taxonomies $taxonomy (urlize $term) }}
+ <a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a>
+{{ end }}
+```
+
+To generate a list of term pages associated with a given content page, use the [`GetTerms`] method on a `Page` object.
+
+[`GetTerms`]: /methods/page/getterms/
diff --git a/documents/markdown/hugo-docs/en_functions_urls__index.md b/documents/markdown/hugo-docs/en_functions_urls__index.md
new file mode 100644
index 0000000..3a1962d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_functions_urls__index.md
@@ -0,0 +1,7 @@
+---
+title: URL functions
+linkTitle: urls
+description: Use these functions to work with URLs.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_getting-started__index.md b/documents/markdown/hugo-docs/en_getting-started__index.md
new file mode 100644
index 0000000..2e2f571
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_getting-started__index.md
@@ -0,0 +1,8 @@
+---
+title: Getting started
+description: How to get started with Hugo.
+categories: []
+keywords: []
+weight: 10
+aliases: [/overview/introduction/]
+---
diff --git a/documents/markdown/hugo-docs/en_getting-started_directory-structure.md b/documents/markdown/hugo-docs/en_getting-started_directory-structure.md
new file mode 100644
index 0000000..81dbe95
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_getting-started_directory-structure.md
@@ -0,0 +1,203 @@
+---
+title: Directory structure
+description: An overview of Hugo's directory structure.
+categories: []
+keywords: []
+weight: 30
+aliases: [/overview/source-directory/]
+---
+
+Each Hugo project is a directory, with subdirectories that contribute to content, structure, behavior, and presentation.
+
+## Project skeleton
+
+Hugo generates a project skeleton when you create a new project. For example, this command:
+
+```sh
+hugo new project my-project
+```
+
+Creates this directory structure:
+
+```txt
+my-project/
+├── archetypes/
+│ └── default.md
+├── assets/
+├── content/
+├── data/
+├── i18n/
+├── layouts/
+├── static/
+├── themes/
+└── hugo.toml <-- project configuration
+```
+
+Depending on requirements, you may wish to organize your project configuration into subdirectories:
+
+```txt
+my-project/
+├── archetypes/
+│ └── default.md
+├── assets/
+├── config/ <-- project configuration
+│ └── _default/
+│ └── hugo.toml
+├── content/
+├── data/
+├── i18n/
+├── layouts/
+├── static/
+└── themes/
+```
+
+When you build your project, Hugo creates a `public` directory, and typically a `resources` directory as well:
+
+```txt
+my-project/
+├── archetypes/
+│ └── default.md
+├── assets/
+├── config/
+│ └── _default/
+│ └── hugo.toml
+├── content/
+├── data/
+├── i18n/
+├── layouts/
+├── public/ <-- created when you build your project
+├── resources/ <-- created when you build your project
+├── static/
+└── themes/
+```
+
+## Directories
+
+Each of the subdirectories contributes to content, structure, behavior, or presentation.
+
+archetypes
+: The `archetypes` directory contains templates for new content. See [details](/content-management/archetypes/).
+
+assets
+: The `assets` directory contains global resources typically passed through an asset pipeline. This includes resources such as images, CSS, Sass, JavaScript, and TypeScript. See [details](/hugo-pipes/introduction/).
+
+config
+: The `config` directory contains your project configuration, possibly split into multiple subdirectories and files. For projects with minimal configuration or projects that do not need to behave differently in different environments, a single configuration file named `hugo.toml` in the root of the project is sufficient. See [details](/configuration/introduction/#configuration-directory).
+
+content
+: The `content` directory contains the markup files (typically Markdown) and page resources that comprise the content of your project. See [details](/content-management/organization/).
+
+data
+: The `data` directory contains data files (JSON, TOML, YAML, or XML) that augment content, configuration, localization, and navigation. See [details](/content-management/data-sources/).
+
+i18n
+: The `i18n` directory contains translation tables for multilingual projects. See [details](/content-management/multilingual/).
+
+layouts
+: The `layouts` directory contains templates to transform content, data, and resources into a complete website. See [details](/templates/).
+
+public
+: The `public` directory contains the published website, generated when you run the `hugo build` or `hugo server` commands. Hugo recreates this directory and its content as needed. See [details](/getting-started/usage/#build-your-project).
+
+resources
+: The `resources` directory contains cached output from Hugo's asset pipelines, generated when you run the `hugo build` or `hugo server` commands. By default this cache directory includes CSS and images. Hugo recreates this directory and its content as needed.
+
+static
+: The `static` directory contains files that will be copied to the `public` directory when you build your project. For example: `favicon.ico`, `robots.txt`, and files that verify website ownership. Before the introduction of [page bundles](g) and [asset pipelines](/hugo-pipes/introduction/), the `static` directory was also used for images, CSS, and JavaScript.
+
+themes
+: The `themes` directory contains one or more [themes](g), each in its own subdirectory.
+
+## Unified file system
+
+Hugo creates a [unified file system](g), allowing you to mount two or more directories to the same location. For example, let's say your home directory contains a Hugo project in one directory, and shared content in another:
+
+```text
+home/
+└── user/
+ ├── my-project/
+ │ ├── content/
+ │ │ ├── books/
+ │ │ │ ├── _index.md
+ │ │ │ ├── book-1.md
+ │ │ │ └── book-2.md
+ │ │ └── _index.md
+ │ ├── themes/
+ │ │ └── my-theme/
+ │ └── hugo.toml
+ └── shared-content/
+ └── films/
+ ├── _index.md
+ ├── film-1.md
+ └── film-2.md
+```
+
+You can include the shared content using mounts. In your project configuration:
+
+{{< code-toggle file=hugo >}}
+[[module.mounts]]
+source = 'content'
+target = 'content'
+
+[[module.mounts]]
+source = '/home/user/shared-content'
+target = 'content'
+{{< /code-toggle >}}
+
+> [!note]
+> Defining a custom mount replaces the default mounting for that [component](g). To overlay an external directory on top of the project default, you must explicitly mount both.
+>
+> Hugo does not follow symbolic links. If you need the functionality provided by symbolic links, use Hugo's unified file system instead.
+
+After mounting, the unified file system has this structure:
+
+```text
+home/
+└── user/
+ └── my-project/
+ ├── content/
+ │ ├── books/
+ │ │ ├── _index.md
+ │ │ ├── book-1.md
+ │ │ └── book-2.md
+ │ ├── films/
+ │ │ ├── _index.md
+ │ │ ├── film-1.md
+ │ │ └── film-2.md
+ │ └── _index.md
+ ├── themes/
+ │ └── my-theme/
+ └── hugo.toml
+```
+
+When two or more files share the same path, the version in the highest layer takes precedence. In the example above, if the `shared-content` directory contains `books/book-1.md`, it is ignored because the project's `content` directory is the first (highest) mount.
+
+You can mount directories to `archetypes`, `assets`, `content`, `data`, `i18n`, `layouts`, and `static`. See [details](/configuration/module/#mounts).
+
+You can also mount directories from Git repositories using Hugo Modules. See [details](/hugo-modules/).
+
+## Theme skeleton
+
+Hugo generates a functional theme skeleton when you create a new theme. For example, this command:
+
+```text
+hugo new theme my-theme
+```
+
+Creates this directory structure (subdirectories not shown):
+
+```text
+my-theme/
+├── archetypes/
+├── assets/
+├── content/
+├── data/
+├── i18n/
+├── layouts/
+├── static/
+└── hugo.toml
+```
+
+Using the unified file system described above, Hugo mounts each of these directories to the corresponding location in the project. When two files have the same path, the file in the project directory takes precedence. This allows you, for example, to override a theme's template by placing a copy in the same location within the project directory.
+
+If you are simultaneously using components from two or more themes or modules, and there's a path collision, the first mount takes precedence.
diff --git a/documents/markdown/hugo-docs/en_getting-started_external-learning-resources_index.md b/documents/markdown/hugo-docs/en_getting-started_external-learning-resources_index.md
new file mode 100644
index 0000000..d3101be
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_getting-started_external-learning-resources_index.md
@@ -0,0 +1,86 @@
+---
+title: External learning resources
+linkTitle: External resources
+description: Use these third-party resources to learn Hugo.
+categories: []
+keywords: []
+weight: 40
+---
+
+> [!note]
+> Many of the resources on this page, including older books and videos, may contain out-of-date information. The Hugo software has undergone significant changes since these resources were created. These changes include the introduction of a new template system, the deprecation of various functions and settings, and the addition of new features like Markdown render hooks, content adapters, and support for mathematical markup. While some concepts may still be relevant, it's recommended to consult the official Hugo documentation for the most current and accurate information.
+
+## Books
+
+### Hugo in Action
+
+Hugo in Action is a step-by-step guide to using Hugo to create static websites. Working with a complete example website and source code samples, you'll learn how to build and host a low-maintenance, high-performance site that will wow your users and stay stable without relying on a third-party server.
+
+[{{< img src="hugo-in-action.png" alt="Book cover: Hugo in Action" filter="process" filterArgs="resize x350 webp">}}](https://www.manning.com/books/hugo-in-action/)
+
+Author: Atishay Jain\
+Publisher: [Manning Publications](https://www.manning.com/books/hugo-in-action/)\
+Publication date: March 2022\
+Length: 488 pages\
+ISBN: 9781617297007
+
+### Build Websites with Hugo
+
+In this book, you'll use Hugo to build a personal portfolio site that you can use to showcase your skills and thoughts to the world. You'll build the basic skeleton, develop a custom theme, and use content templates to generate new pages quickly. You'll use internal and external data sources to embed content into your site and render some of your content in JSON and RSS. You'll add a blog section with posts and integrate Disqus with your site, and then make your site searchable.
+
+[{{< img src="build-websites-with-hugo.png" alt="Book cover: Build Websites with Hugo" filter="process" filterArgs="resize x350 webp">}}](https://pragprog.com/titles/bhhugo/build-websites-with-hugo/)
+
+Author: Brian P. Hogan\
+Publisher: [Pragmatic Bookshelf](https://pragprog.com/titles/bhhugo/build-websites-with-hugo/)\
+Publication date: May 2020\
+Length: 154 pages\
+ISBN: 9781680507263
+
+## Videos
+
+### Hugo Beginner Tutorial Series
+
+Welcome to this introduction to Hugo tutorial. This series aims to take you from a lion cub with basic web design knowledge to creating your first Hugo website. In this series, you'll learn how to set up a Hugo site, the basics of using Hugo layouts, partials, and templating, set up a blog, and finally, use data files. By the end of this series, you'll have the foundational knowledge to build your own Hugo sites.
+
+1. [Getting set up in Hugo](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/)
+1. [Layouts in Hugo](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/layouts-in-hugo/)
+1. [Hugo Partials](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/hugo-partials/)
+1. [Hugo templating basics](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/hugo-templating-basics/)
+1. [Blogging in Hugo](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/blogging-in-hugo/)
+1. [Using Data in Hugo](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/using-data-in-hugo/)
+
+Creator: Mike Neumegen\
+Affiliation: [CloudCannon](https://cloudcannon.com/)\
+Creation date: April 2022
+
+### Hugo Static Site Generator
+
+This course covers the basics of using the Hugo static site generator. Work your way through the articles, and we'll teach you everything you need to know to create a professional and scalable website or blog!
+
+1. [Introduction](https://www.giraffeacademy.com/static-site-generators/hugo/)
+1. [Windows Installation](https://www.giraffeacademy.com/static-site-generators/hugo/installing-hugo-on-windows/)
+1. [Mac Installation](https://www.giraffeacademy.com/static-site-generators/hugo/installing-hugo-on-mac/)
+1. [Creating A New Site](https://www.giraffeacademy.com/static-site-generators/hugo/hugo-directory-structure/)
+1. [Installing & Using Themes](https://www.giraffeacademy.com/static-site-generators/hugo/installing-using-themes/)
+1. [Content Organization](https://www.giraffeacademy.com/static-site-generators/hugo/content-organization/)
+1. [Front Matter](https://www.giraffeacademy.com/static-site-generators/hugo/front-matter/)
+1. [Archetypes](https://www.giraffeacademy.com/static-site-generators/hugo/archetypes/)
+1. [Shortcodes](https://www.giraffeacademy.com/static-site-generators/hugo/shortcodes/)
+1. [Taxonomies](https://www.giraffeacademy.com/static-site-generators/hugo/taxonomies/)
+1. [Template Basics](https://www.giraffeacademy.com/static-site-generators/hugo/introduction-to-templates/)
+1. [List Page Templates](https://www.giraffeacademy.com/static-site-generators/hugo/list-page-templates/)
+1. [Single Page Templates](https://www.giraffeacademy.com/static-site-generators/hugo/single-page-templates/)
+1. [Home Page Templates](https://www.giraffeacademy.com/static-site-generators/hugo/home-page-templates/)
+1. [Section Templates](https://www.giraffeacademy.com/static-site-generators/hugo/section-templates/)
+1. [Block Templates](https://www.giraffeacademy.com/static-site-generators/hugo/block-templates/)
+1. [Variables](https://www.giraffeacademy.com/static-site-generators/hugo/variables/)
+1. [Functions](https://www.giraffeacademy.com/static-site-generators/hugo/functions/)
+1. [Conditionals](https://www.giraffeacademy.com/static-site-generators/hugo/conditionals/)
+1. [Data Templates](https://www.giraffeacademy.com/static-site-generators/hugo/data-templates/)
+1. [Partial Templates](https://www.giraffeacademy.com/static-site-generators/hugo/partial-templates/)
+1. [Shortcode Templates](https://www.giraffeacademy.com/static-site-generators/hugo/shortcode-templates/)
+1. [Building & Hosting](https://www.giraffeacademy.com/static-site-generators/hugo/building-&-hosting/)
+
+Creator: Mike Dane\
+Affiliation: [Giraffe Academy](https://www.giraffeacademy.com/)\
+Creation date: September 2017
diff --git a/documents/markdown/hugo-docs/en_getting-started_quick-start.md b/documents/markdown/hugo-docs/en_getting-started_quick-start.md
new file mode 100644
index 0000000..f882291
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_getting-started_quick-start.md
@@ -0,0 +1,216 @@
+---
+title: Quick start
+description: Create your first Hugo project.
+categories: []
+keywords: []
+params:
+ minVersion: v0.156.0
+weight: 10
+aliases: [/quickstart/,/overview/quickstart/]
+---
+
+In this tutorial you will:
+
+1. Create a project
+1. Add content
+1. Configure the project
+1. Publish the project
+
+## Prerequisites
+
+Before you begin this tutorial you must:
+
+1. [Install Hugo] (extended or extended/deploy edition, {{% param "minVersion" %}} or later)
+1. [Install Git]
+
+You must also be comfortable working from the command line.
+
+## Create a project
+
+### Commands
+
+> [!note]
+> **If you are a Windows user:**
+>
+> - Do not use the Command Prompt
+> - Do not use Windows PowerShell
+> - Run these commands from [PowerShell][] or a Linux terminal such as WSL or Git > Bash
+>
+> PowerShell and Windows PowerShell [are different applications][].
+
+Verify that you have installed Hugo {{% param "minVersion" %}} or later.
+
+```text
+hugo version
+```
+
+Run these commands to create a Hugo project with the [Ananke][] theme. The next section provides an explanation of each command.
+
+```text
+hugo new project quickstart
+cd quickstart
+git init
+git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
+echo "theme = 'ananke'" >> hugo.toml
+hugo server
+```
+
+View your project at the URL displayed in your terminal. Press `Ctrl + C` to stop Hugo's development server.
+
+### Explanation of commands
+
+Create the [project skeleton][] for your project in the `quickstart` directory.
+
+```text
+hugo new project quickstart
+```
+
+Change the current directory to the root of your project.
+
+```text
+cd quickstart
+```
+
+Initialize an empty Git repository in the current directory.
+
+```text
+git init
+```
+
+Clone the [Ananke][] theme into the `themes` directory, adding it to your project as a [Git submodule][].
+
+```text
+git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
+```
+
+Append a line to your project configuration file, indicating the current theme.
+
+```text
+echo "theme = 'ananke'" >> hugo.toml
+```
+
+Start Hugo's development server.
+
+```text
+hugo server
+```
+
+Press `Ctrl + C` to stop Hugo's development server.
+
+## Add content
+
+Add a new page to your project.
+
+```text
+hugo new content content/posts/my-first-post.md
+```
+
+Hugo created the file in the `content/posts` directory. Open the file with your editor.
+
+```text
++++
+title = 'My First Post'
+date = 2024-01-14T07:07:07+01:00
+draft = true
++++
+```
+
+Notice the `draft` value in the [front matter][] is `true`. By default, Hugo does not publish draft content when you build the project. Learn more about [draft, future, and expired content][].
+
+Add some [Markdown][] to the body of the post, but do not change the `draft` value.
+
+```text
++++
+title = 'My First Post'
+date = 2024-01-14T07:07:07+01:00
+draft = true
++++
+## Introduction
+
+This is **bold** text, and this is *emphasized* text.
+
+Visit the [Hugo](https://gohugo.io) website!
+```
+
+Save the file, then start Hugo's development server. You can run either of the following commands to include draft content.
+
+```text
+hugo server --buildDrafts
+hugo server -D
+```
+
+View your project at the URL displayed in your terminal. Keep the development server running as you continue to add and change content.
+
+When satisfied with your new content, set the front matter `draft` parameter to `false`.
+
+> [!note]
+> Hugo's rendering engine conforms to the CommonMark [specification][] for Markdown. The CommonMark organization provides a useful [live testing tool][] powered by the reference implementation.
+
+## Configure the project
+
+With your editor, open your [project configuration][] file (`hugo.toml`) in the root of your project.
+
+```text
+baseURL = 'https://example.org/'
+locale = 'en-us'
+title = 'My New Hugo Project'
+theme = 'ananke'
+```
+
+Make the following changes:
+
+1. Set the `baseURL` for your project. This value must begin with the protocol and end with a slash, as shown above.
+1. Set the `locale` to your locale.
+1. Set the `title` for your project.
+
+Start Hugo's development server to see your changes, remembering to include draft content.
+
+```text
+hugo server -D
+```
+
+> [!note]
+> Most theme authors provide configuration guidelines and options. Make sure to visit your theme's repository or documentation site for details.
+>
+> [The New Dynamic][], authors of the Ananke theme, provide [documentation][] for configuration and usage. They also provide a [demonstration site][].
+
+## Publish the project
+
+In this step you will _publish_ your project, but you will not _deploy_ it.
+
+When you publish your project, Hugo renders all build artifacts to the `public` directory in the root of your project. This includes the HTML files for every site, along with assets such as images, CSS, and JavaScript. The command is simple.
+
+```text
+hugo
+```
+
+To learn how to _deploy_ your project, see the [host and deploy][] section.
+
+## Ask for help
+
+Hugo's [forum][] is an active community of users and developers who answer questions, share knowledge, and provide examples. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question.
+
+## Other resources
+
+For other resources to help you learn Hugo, including books and video tutorials, see the [external learning resources][] page.
+
+[Ananke]: https://github.com/theNewDynamic/gohugo-theme-ananke
+[are different applications]: https://learn.microsoft.com/en-us/powershell/scripting/whats-new/differences-from-windows-powershell?view=powershell-7.3
+[demonstration site]: https://gohugo-ananke-theme-demo.netlify.app/
+[documentation]: https://github.com/theNewDynamic/gohugo-theme-ananke#readme
+[draft, future, and expired content]: /getting-started/usage/#draft-future-and-expired-content
+[external learning resources]: /getting-started/external-learning-resources/
+[forum]: https://discourse.gohugo.io/
+[front matter]: /content-management/front-matter/
+[Git submodule]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
+[host and deploy]: /host-and-deploy/
+[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+[Install Hugo]: /installation/
+[live testing tool]: https://spec.commonmark.org/dingus/
+[Markdown]: https://daringfireball.net/projects/markdown
+[PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows
+[project configuration]: /configuration/
+[project skeleton]: /getting-started/directory-structure/#project-skeleton
+[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132
+[specification]: https://spec.commonmark.org/
+[The New Dynamic]: https://www.thenewdynamic.com/
diff --git a/documents/markdown/hugo-docs/en_getting-started_usage.md b/documents/markdown/hugo-docs/en_getting-started_usage.md
new file mode 100644
index 0000000..ad4301d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_getting-started_usage.md
@@ -0,0 +1,156 @@
+---
+title: Basic usage
+description: Use the command-line interface (CLI) to perform basic tasks.
+categories: []
+keywords: []
+weight: 20
+aliases: [/overview/usage/,/extras/livereload/,/doc/usage/,/usage/]
+---
+
+## Test your installation
+
+After [installing] Hugo, test your installation by running:
+
+```sh
+hugo version
+```
+
+You should see something like:
+
+```text
+hugo v0.158.0-f41be7959a44108641f1e081adf5c4be7fc1bb63 linux/amd64 BuildDate=2026-03-16T17:42:04Z VendorInfo=gohugoio
+```
+
+## Display available commands
+
+To see a list of the available commands and flags:
+
+```sh
+hugo help
+```
+
+To get help with a subcommand, use the `--help` flag. For example:
+
+```sh
+hugo server --help
+```
+
+## Build your project
+
+To build your project, `cd` into your project directory and run:
+
+```sh
+hugo build
+```
+
+The [`hugo build`] command builds your project, publishing the files to the `public` directory. To publish your project to a different directory, use the [`--destination`] flag or set [`publishDir`] in your project configuration.
+
+> [!note]
+> Hugo does not clear the `public` directory before building your project. Existing files are overwritten, but not deleted. This behavior is intentional to prevent the inadvertent removal of files that you may have added to the `public` directory after the build.
+>
+> Depending on your needs, you may wish to manually clear the contents of the `public` directory before every build.
+
+## Draft, future, and expired content
+
+Hugo allows you to set `draft`, `date`, `publishDate`, and `expiryDate` in the [front matter] of your content. By default, Hugo will not publish content when:
+
+- The `draft` value is `true`
+- The `date` is in the future
+- The `publishDate` is in the future
+- The `expiryDate` is in the past
+
+> [!note]
+> Hugo publishes descendants of draft, future, and expired [node](g) pages. To prevent publication of these descendants, use the [`cascade`] front matter field to cascade [build options] to the descendant pages.
+
+You can override the default behavior when running `hugo build` or `hugo server` with command line flags:
+
+```sh
+hugo build --buildDrafts # or -D
+hugo build --buildExpired # or -E
+hugo build --buildFuture # or -F
+```
+
+Although you can also set these values in your project configuration, it can lead to unwanted results unless all content authors are aware of, and understand, the settings.
+
+> [!note]
+> As noted above, Hugo does not clear the `public` directory before building your project. Depending on the _current_ evaluation of the four conditions above, after the build your `public` directory may contain extraneous files from a previous build.
+>
+> A common practice is to manually clear the contents of the `public` directory before each build to remove draft, expired, and future content.
+
+## Develop and test your site
+
+To view your site while developing layouts or creating content, `cd` into your project directory and run:
+
+```sh
+hugo server
+```
+
+The [`hugo server`] command builds your site and serves your pages using a minimal HTTP server. When you run `hugo server` it will display the URL of your local site:
+
+```text
+Web Server is available at http://localhost:1313/
+```
+
+While the server is running, it watches your project directory for changes to assets, configuration, content, data, layouts, translations, and static files. When it detects a change, the server rebuilds your site and refreshes your browser using [LiveReload].
+
+Most Hugo builds are so fast that you may not notice the change unless you are looking directly at your browser.
+
+### LiveReload
+
+While the server is running, Hugo injects JavaScript into the generated HTML pages. The LiveReload script creates a connection from the browser to the server via web sockets. You do not need to install any software or browser plugins, nor is any configuration required.
+
+### Automatic redirection
+
+When editing content, if you want your browser to automatically redirect to the page you last modified, run:
+
+```sh
+hugo server --navigateToChanged
+```
+
+## Deploy your site
+
+> [!note]
+> As noted above, Hugo does not clear the `public` directory before building your project. Manually clear the contents of the `public` directory before each build to remove draft, expired, and future content.
+
+When you are ready to deploy your site, run:
+
+```sh
+hugo
+```
+
+This builds your site, publishing the files to the `public` directory. The directory structure will look something like this:
+
+```text
+public/
+├── categories/
+│ ├── index.html
+│ └── index.xml <-- RSS feed for this section
+├── posts/
+│ ├── my-first-post/
+│ │ └── index.html
+│ ├── index.html
+│ └── index.xml <-- RSS feed for this section
+├── tags/
+│ ├── index.html
+│ └── index.xml <-- RSS feed for this section
+├── index.html
+├── index.xml <-- RSS feed for the site
+└── sitemap.xml
+```
+
+In a simple hosting environment, where you typically `ftp`, `rsync`, or `scp` your files to the root of a virtual host, the contents of the `public` directory are all that you need.
+
+Most of our users deploy their sites to a [CI/CD](g) platform, where a push[^1] to their remote Git repository triggers a build and deployment. Learn more in the [host and deploy] section.
+
+[^1]: The Git repository contains the entire project directory, typically excluding the `public` directory because the site is built _after_ the push.
+
+[`--destination`]: /commands/hugo/#options
+[`cascade`]: /content-management/front-matter/#cascade
+[`hugo server`]: /commands/hugo_server/
+[`hugo build`]: /commands/hugo/
+[`publishDir`]: /configuration/all/#publishdir
+[build options]: /content-management/build-options/
+[front matter]: /content-management/front-matter/
+[host and deploy]: /host-and-deploy/
+[installing]: /installation/
+[LiveReload]: https://github.com/livereload/livereload-js
diff --git a/documents/markdown/hugo-docs/en_host-and-deploy__index.md b/documents/markdown/hugo-docs/en_host-and-deploy__index.md
new file mode 100644
index 0000000..627f12c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_host-and-deploy__index.md
@@ -0,0 +1,8 @@
+---
+title: Host and deploy
+description: Services and tools to host and deploy your site.
+categories: []
+keywords: []
+weight: 10
+aliases: [/hosting-and-deployment/]
+---
diff --git a/documents/markdown/hugo-docs/en_host-and-deploy_deploy-with-hugo-deploy.md b/documents/markdown/hugo-docs/en_host-and-deploy_deploy-with-hugo-deploy.md
new file mode 100644
index 0000000..b894fef
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_host-and-deploy_deploy-with-hugo-deploy.md
@@ -0,0 +1,97 @@
+---
+title: Deploy with hugo
+description: Deploy your site with the hugo CLI.
+categories: []
+keywords: []
+aliases: [/hosting-and-deployment/hugo-deploy/]
+---
+
+Use the `hugo deploy` command to deploy your site Amazon S3, Azure Blob Storage, or Google Cloud Storage.
+
+> [!note]
+> This feature requires the deploy or extended/deploy edition. See the [installation] section for details.
+
+## Assumptions
+
+1. You have completed the [Quick Start] or have a Hugo website you are ready to deploy and share with the world.
+1. You have an account with the service provider ([AWS], [Azure], or [Google Cloud]) that you want to deploy to.
+1. You have authenticated.
+ - AWS: [Install the CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) and run [`aws configure`](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html).
+ - Azure: [Install the CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) and run [`az login`](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli).
+ - Google Cloud: [Install the CLI](https://cloud.google.com/sdk) and run [`gcloud auth login`](https://cloud.google.com/sdk/gcloud/reference/auth/login).
+
+ Each service supports various authentication methods, including environment variables. See [details](https://gocloud.dev/howto/blob/#services).
+
+1. You have created a bucket to deploy to. If you want your site to be
+ public, be sure to configure the bucket to be publicly readable as a static website.
+ - AWS: [create a bucket](https://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html) and [host a static website](https://docs.aws.amazon.com/AmazonS3/latest/userguide/WebsiteHosting.html)
+ - Azure: [create a storage container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal) and [host a static website](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website)
+
+ - Google Cloud: [create a bucket](https://cloud.google.com/storage/docs/creating-buckets) and [host a static website](https://cloud.google.com/storage/docs/hosting-static-website)
+
+## Configuration
+
+Create a deployment target in your [project configuration]. The only required parameters are [`name`] and [`url`]:
+
+{{< code-toggle file=hugo >}}
+[deployment]
+ [[deployment.targets]]
+ name = 'production'
+ url = 's3://my_bucket?region=us-west-1'
+{{< /code-toggle >}}
+
+## Deploy
+
+To deploy to a target:
+
+```sh
+hugo deploy [--target=<target name>]
+```
+
+This command syncs the contents of your local `public` directory (the default publish directory) with the destination bucket. If no target is specified, Hugo deploys to the first configured target.
+
+For more command-line options, see `hugo help deploy` or the [CLI documentation].
+
+### File list creation
+
+`hugo deploy` creates local and remote file lists by traversing the local publish directory and the remote bucket. Inclusion and exclusion are determined by the deployment target's [configuration]:
+
+- `include`: All files are skipped by default except those that match the pattern.
+- `exclude`: Files matching the pattern are skipped.
+
+> [!note]
+> During local file list creation, Hugo skips `.DS_Store` files and hidden directories (those starting with a period, like `.git`), except for the [`.well-known`] directory, which is traversed if present.
+
+### File list comparison
+
+Hugo compares the local and remote file lists to identify necessary changes. It first compares file names. If both exist, it compares sizes and MD5 checksums. Any difference triggers a re-upload, and remote files not present locally are deleted.
+
+> [!note]
+> Excluded remote files (due to `include`/`exclude` configuration) won't be deleted.
+
+The `--force` flag forces all files to be re-uploaded, even if Hugo detects no local/remote differences.
+
+The `--confirm` or `--dryRun` flags cause Hugo to display the detected differences and then pause or stop.
+
+### Synchronization
+
+Hugo applies the changes to the remote bucket: uploading missing or changed files and deleting remote files not present locally. Uploaded file headers are configured remotely based on the matchers configuration.
+
+> [!note]
+> To prevent accidental data loss, Hugo will not delete more than 256 remote files by default. Use the `--maxDeletes` flag to override this limit.
+
+## Advanced configuration
+
+See [configure deployment](/configuration/deployment/).
+
+[`.well-known`]: https://en.wikipedia.org/wiki/Well-known_URI
+[`name`]: /configuration/deployment/#name
+[`url`]: /configuration/deployment/#url
+[AWS]: https://aws.amazon.com
+[Azure]: https://azure.microsoft.com
+[CLI documentation]: /commands/hugo_deploy/
+[configuration]: /configuration/deployment/#targets-1
+[Google Cloud]: https://cloud.google.com/
+[installation]: /installation/
+[Quick Start]: /getting-started/quick-start/
+[project configuration]: /configuration/deployment/
diff --git a/documents/markdown/hugo-docs/en_host-and-deploy_deploy-with-rclone.md b/documents/markdown/hugo-docs/en_host-and-deploy_deploy-with-rclone.md
new file mode 100644
index 0000000..b5e898d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_host-and-deploy_deploy-with-rclone.md
@@ -0,0 +1,43 @@
+---
+title: Deploy with rclone
+description: Deploy your site with the rclone CLI.
+categories: []
+keywords: []
+aliases: [/hosting-and-deployment/deployment-with-rclone/]
+---
+
+## Assumptions
+
+- A web host running a web server. This could be a shared hosting environment or a VPS.
+- Access to your web host with any of the [protocols supported by rclone](https://rclone.org/#providers), such as SFTP.
+- A functional static website built with Hugo
+- Deploying from an [Rclone](https://rclone.org) compatible operating system
+- You have [installed Rclone](https://rclone.org/install/).
+
+**NB**: You can remove `--interactive` in the commands below once you are comfortable with rclone, if you wish. Also, `--gc` and `--minify` are optional in the commands below.
+
+## Getting started
+
+The spoiler is that you can even deploy your entire website from any compatible OS with no configuration. Using SFTP for example:
+
+```txt
+hugo build --gc --minify
+rclone sync --interactive --sftp-host sftp.example.com --sftp-user www-data --sftp-ask-password public/ :sftp:www/
+```
+
+## Configure Rclone for even easier usage
+
+The easiest way is simply to run `rclone config`.
+
+The [Rclone docs](https://rclone.org/docs/) provide [an example of configuring Rclone to use SFTP](https://rclone.org/sftp/).
+
+For the next commands, we will assume you configured a remote you named `hugo-www`.
+
+The above 'spoiler' commands could become:
+
+```txt
+hugo build --gc --minify
+rclone sync --interactive public/ hugo-www:www/
+```
+
+After you issue the above commands (and respond to any prompts), check your website and you will see that it is deployed.
diff --git a/documents/markdown/hugo-docs/en_host-and-deploy_deploy-with-rsync.md b/documents/markdown/hugo-docs/en_host-and-deploy_deploy-with-rsync.md
new file mode 100644
index 0000000..1c0967b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_host-and-deploy_deploy-with-rsync.md
@@ -0,0 +1,135 @@
+---
+title: Deploy with rsync
+description: Deploy your site with the rsync CLI.
+categories: []
+keywords: []
+aliases: [/hosting-and-deployment/deployment-with-rsync/]
+---
+
+## Assumptions
+
+- A web host running a web server. This could be a shared hosting environment or a VPS.
+- Access to your web host with SSH
+- A functional static website built with Hugo
+
+The spoiler is that you can deploy your entire website with a command that looks like the following:
+
+```txt
+hugo && rsync -avz --delete public/ www-data@ftp.topologix.fr:~/www/
+```
+
+As you will see, we'll put this command in a shell script file, which makes building and deployment as easy as executing `./deploy`.
+
+## Copy Your SSH Key to your host
+
+To make logging in to your server more secure and less interactive, you can upload your SSH key. If you have already installed your SSH key to your server, you can move on to the next section.
+
+First, install the ssh client. On Debian distributions, use the following command:
+
+```sh {file="install-openssh.sh"}
+sudo apt-get install openssh-client
+```
+
+Then generate your ssh key. First, create the `.ssh` directory in your home directory if it doesn't exist:
+
+```txt
+~$ cd && mkdir .ssh & cd .ssh
+```
+
+Next, execute this command to generate a new keypair called `rsa_id`:
+
+```txt
+~/.ssh/$ ssh-keygen -t rsa -q -C "For SSH" -f rsa_id
+```
+
+You'll be prompted for a passphrase, which is an extra layer of protection. Enter the passphrase you'd like to use, and then enter it again when prompted, or leave it blank if you don't want to have a passphrase. Not using a passphrase will let you transfer files non-interactively, as you won't be prompted for a password when you log in, but it is slightly less secure.
+
+To make logging in easier, add a definition for your web host to the file `~/.ssh/config` with the following command, replacing `HOST` with the IP address or hostname of your web host, and `USER` with the username you use to log in to your web host when transferring files:
+
+```txt
+~/.ssh/$ cat >> config <<EOF
+Host HOST
+ Hostname HOST
+ Port 22
+ User USER
+ IdentityFile ~/.ssh/rsa_id
+EOF
+```
+
+Then copy your ssh public key to the remote server with the `ssh-copy-id` command:
+
+```txt
+~/.ssh/$ ssh-copy-id -i rsa_id.pub USER@HOST.com
+```
+
+Now you can easily connect to the remote server:
+
+```txt
+~$ ssh user@host
+Enter passphrase for key '/home/mylogin/.ssh/rsa_id':
+```
+
+Now that you can log in with your SSH key, let's create a script to automate deployment of your Hugo site.
+
+## Shell script
+
+Create a new script called `deploy` at the root of your Hugo tree:
+
+```txt
+~/websites/topologix.fr$ editor deploy
+```
+
+Add the following content. Replace the `USER`, `HOST`, and `DIR` values with your own values:
+
+```sh
+#!/bin/sh
+USER=my-user
+HOST=my-server.com
+DIR=my/directory/to/topologix.fr/ # the directory where your website files should go
+
+hugo build && rsync -avz --delete public/ ${USER}@${HOST}:~/${DIR} # this will delete everything on the server that's not in the local public directory
+
+exit 0
+```
+
+Note that `DIR` is the relative path from the remote user's home. If you have to specify a full path (for instance `/var/www/mysite/`) you must change `~/${DIR}` to `${DIR}` inside the command-line. For most cases you should not have to.
+
+Save and close, and make the `deploy` file executable:
+
+```txt
+~/websites/topologix.fr$ chmod +x deploy
+```
+
+Now you only have to enter the following command to deploy and update your website:
+
+```txt
+~/websites/topologix.fr$ ./deploy
+```
+
+Your site builds and deploys:
+
+```txt
+Started building sites ...
+Built site for language en:
+0 draft content
+0 future content
+0 expired content
+5 pages created
+0 non-page files copied
+0 paginator pages created
+0 tags created
+0 categories created
+total in 56 ms
+sending incremental file list
+404.html
+index.html
+index.xml
+sitemap.xml
+posts/
+posts/index.html
+
+sent 9,550 bytes received 1,708 bytes 7,505.33 bytes/sec
+total size is 966,557 speedup is 85.86
+```
+
+You can incorporate other processing tasks into this deployment script as well.
diff --git a/documents/markdown/hugo-docs/en_host-and-deploy_host-on-aws-amplify_index.md b/documents/markdown/hugo-docs/en_host-and-deploy_host-on-aws-amplify_index.md
new file mode 100644
index 0000000..f7f8869
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_host-and-deploy_host-on-aws-amplify_index.md
@@ -0,0 +1,157 @@
+---
+title: Host on AWS Amplify
+description: Host your site on AWS Amplify.
+categories: []
+keywords: []
+aliases: [/hosting-and-deployment/hosting-on-aws-amplify/]
+---
+
+Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using GitLab for version control.
+
+## Prerequisites
+
+Please complete the following tasks before continuing:
+
+1. [Create](https://aws.amazon.com/resources/create-account/) an AWS account
+1. [Log in](https://console.aws.amazon.com/) to your AWS account
+1. [Create](https://github.com/signup) a GitHub account
+1. [Log in](https://github.com/login) to your GitHub account
+1. [Create](https://github.com/new) a GitHub repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
+1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
+1. Commit the changes to your local Git repository and push to your GitHub repository.
+
+## Procedure
+
+This procedure will enable continuous deployment from a GitHub repository. The procedure is essentially the same if you are using GitLab or Bitbucket.
+
+Step 1
+: Create a file named `amplify.yml` in the root of your project.
+
+ ```sh
+ touch amplify.yml
+ ```
+
+Step 2
+: Copy and paste the YAML below into the file you created. Change the application versions and time zone as needed.
+
+ ```yaml {file="amplify.yml" copy=true}
+ version: 1
+ env:
+ variables:
+ # Application versions
+ DART_SASS_VERSION: 1.98.0
+ GO_VERSION: 1.26.1
+ HUGO_VERSION: 0.158.0
+ # Time zone
+ TZ: Europe/Oslo
+ # Cache
+ HUGO_CACHEDIR: ${PWD}/.hugo
+ NPM_CONFIG_CACHE: ${PWD}/.npm
+ frontend:
+ phases:
+ preBuild:
+ commands:
+ # Create directory for user-specific executable files
+ - echo "Creating directory for user-specific executable files..."
+ - mkdir -p "${HOME}/.local"
+
+ # Install Dart Sass
+ - echo "Installing Dart Sass ${DART_SASS_VERSION}..."
+ - curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ - tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ - rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ - export PATH="${HOME}/.local/dart-sass:${PATH}"
+
+ # Install Go
+ - echo "Installing Go ${GO_VERSION}..."
+ - curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz"
+ - tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz"
+ - rm "go${GO_VERSION}.linux-amd64.tar.gz"
+ - export PATH="${HOME}/.local/go/bin:${PATH}"
+
+ # Install Hugo
+ - echo "Installing Hugo ${HUGO_VERSION}..."
+ - curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ - mkdir "${HOME}/.local/hugo"
+ - tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ - rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ - export PATH="${HOME}/.local/hugo:${PATH}"
+
+ # Verify installations
+ - echo "Verifying installations..."
+ - "echo Dart Sass: $(sass --version)"
+ - "echo Go: $(go version)"
+ - "echo Hugo: $(hugo version)"
+ - "echo Node.js: $(node --version)"
+
+ # Install Node.js dependencies
+ - echo "Installing Node.js dependencies..."
+ - "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci --prefer-offline || true"
+
+ # Configure Git
+ - echo "Configuring Git..."
+ - git config core.quotepath false
+ build:
+ commands:
+ - echo "Building site..."
+ - hugo build --gc --minify
+ artifacts:
+ baseDirectory: public
+ files:
+ - '**/*'
+ cache:
+ paths:
+ - ${HUGO_CACHEDIR}/**/*
+ - ${NPM_CONFIG_CACHE}/**/*
+ ```
+
+Step 3
+: Commit and push the change to your GitHub repository.
+
+ ```sh
+ git add -A
+ git commit -m "Create amplify.yml"
+ git push
+ ```
+
+Step 4
+: Log in to your AWS account, navigate to the [Amplify Console], then press the **Deploy an app** button.
+
+Step 5
+: Choose a source code provider, then press the **Next** button.
+
+ 
+
+Step 6
+: Authorize AWS Amplify to access your GitHub account.
+
+ 
+
+Step 7
+: Select your personal account or relevant organization.
+
+ 
+
+Step 8
+: Authorize access to one or more repositories.
+
+ 
+
+Step 9
+: Select a repository and branch, then press the **Next** button.
+
+ 
+
+Step 10
+: On the "App settings" page, scroll to the bottom then press the **Next** button. Amplify reads the `amplify.yml` file you created in Steps 1-3 instead of using the values on this page.
+
+Step 11
+: On the "Review" page, scroll to the bottom then press the **Save and deploy** button.
+
+Step 12
+: When your site has finished deploying, press the **Visit deployed URL** button to view your published site.
+
+ 
+
+[Amplify Console]: https://console.aws.amazon.com/amplify/apps
diff --git a/documents/markdown/hugo-docs/en_host-and-deploy_host-on-azure-static-web-apps.md b/documents/markdown/hugo-docs/en_host-and-deploy_host-on-azure-static-web-apps.md
new file mode 100644
index 0000000..68fe145
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_host-and-deploy_host-on-azure-static-web-apps.md
@@ -0,0 +1,11 @@
+---
+title: Host on Azure Static Web Apps
+description: Host your site on Azure Static Web Apps.
+categories: []
+keywords: []
+aliases: [/hosting-and-deployment/hosting-on-azure-static-web-apps/]
+---
+
+You can create and deploy a Hugo web application to Azure Static Web Apps. The final result is a new Azure Static Web App with associated GitHub Actions that give you control over how the app is built and published. You'll learn how to create a Hugo app, set up an Azure Static Web App and deploy the Hugo app to Azure.
+
+Here's the tutorial on how to [Publish a Hugo site to Azure Static Web Apps](https://docs.microsoft.com/en-us/azure/static-web-apps/publish-hugo).
diff --git a/documents/markdown/hugo-docs/en_host-and-deploy_host-on-cloudflare_index.md b/documents/markdown/hugo-docs/en_host-and-deploy_host-on-cloudflare_index.md
new file mode 100644
index 0000000..b66f511
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_host-and-deploy_host-on-cloudflare_index.md
@@ -0,0 +1,184 @@
+---
+title: Host on Cloudflare
+description: Host your site on Cloudflare.
+categories: []
+keywords: []
+---
+
+Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using GitLab for version control.
+
+## Prerequisites
+
+Please complete the following tasks before continuing:
+
+1. [Create](https://dash.cloudflare.com/sign-up) a Cloudflare account
+1. [Log in](https://dash.cloudflare.com/login) to your Cloudflare account
+1. [Create](https://github.com/signup) a GitHub account
+1. [Log in](https://github.com/login) to your GitHub account
+1. [Create](https://github.com/new) a GitHub repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
+1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
+
+## Procedure
+
+Step 1
+: Create a `wrangler.toml` file in the root of your project.
+
+ ```toml {file="wrangler.toml" copy=true}
+ name = 'hosting-cloudflare-worker'
+ compatibility_date = '2025-07-31'
+
+ [build]
+ command = 'chmod a+x build.sh && ./build.sh'
+
+ [assets]
+ directory = './public'
+ not_found_handling = '404-page'
+ ```
+
+Step 2
+: Create a `build.sh` file in the root of your project.
+
+ ```sh {file="build.sh" copy=true}
+ #!/usr/bin/env bash
+
+ #------------------------------------------------------------------------------
+ # @file
+ # Builds a Hugo site hosted on a Cloudflare Worker.
+ #
+ # The Cloudflare Worker automatically installs Node.js dependencies.
+ #------------------------------------------------------------------------------
+
+ # Exit on error, undefined variables, or pipe failures
+ set -euo pipefail
+
+ build_temp_dir=""
+
+ # Perform cleanup
+ cleanup() {
+ if [[ -n "${build_temp_dir:-}" && -d "${build_temp_dir}" ]]; then
+ rm -rf "${build_temp_dir}"
+ fi
+ }
+
+ # Register the cleanup trap
+ trap cleanup EXIT SIGINT SIGTERM
+
+ main() {
+ # Define tool versions
+ DART_SASS_VERSION=1.98.0
+ GO_VERSION=1.26.1
+ HUGO_VERSION=0.158.0
+ NODE_VERSION=24.14.0
+
+ # Set the build timezone
+ export TZ=Europe/Oslo
+
+ # Create and move into a temporary directory for downloads
+ build_temp_dir=$(mktemp -d)
+ pushd "${build_temp_dir}" > /dev/null
+
+ # Create the local tools directory
+ mkdir -p "${HOME}/.local"
+
+ # Install Dart Sass
+ echo "Installing Dart Sass ${DART_SASS_VERSION}..."
+ curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ export PATH="${HOME}/.local/dart-sass:${PATH}"
+
+ # Install Go
+ echo "Installing Go ${GO_VERSION}..."
+ curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz"
+ tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/go/bin:${PATH}"
+
+ # Install Hugo
+ echo "Installing Hugo ${HUGO_VERSION}..."
+ curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
+ mkdir -p "${HOME}/.local/hugo"
+ tar -C "${HOME}/.local/hugo" -xf "hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/hugo:${PATH}"
+
+ # Install Node.js
+ echo "Installing Node.js ${NODE_VERSION}..."
+ curl -sLJO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz"
+ tar -C "${HOME}/.local" -xf "node-v${NODE_VERSION}-linux-x64.tar.xz"
+ export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}"
+
+ # Return to the project root
+ popd > /dev/null
+
+ # Verify installations
+ echo "Verifying installations..."
+ echo Dart Sass: "$(sass --version)"
+ echo Go: "$(go version)"
+ echo Hugo: "$(hugo version)"
+ echo Node.js: "$(node --version)"
+
+ # Configure Git
+ echo "Configuring Git..."
+ git config core.quotepath false
+ if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
+ git fetch --unshallow
+ fi
+
+ # Build the site
+ echo "Building the site..."
+ hugo build --gc --minify
+ }
+
+ main "$@"
+ ```
+
+Step 3
+: Commit the changes to your local Git repository and push to your GitHub repository.
+
+Step 4
+: In the upper right corner of the Cloudflare [dashboard](https://dash.cloudflare.com/), press the **Add** button and select "Workers" from the drop down menu.
+
+ 
+
+Step 5
+: On the "Workers" tab, press the **Get started** button to the right of the "Import a repository" item.
+
+ 
+
+Step 6
+: Connect to GitHub.
+
+ 
+
+Step 7
+: Select the GitHub account where you want to install the Cloudflare Workers and Pages application.
+
+ 
+
+Step 8
+: Authorize the Cloudflare Workers and Pages application to access all repositories or only select repositories, then press the **Install & Authorize** button.
+
+ 
+
+ Your browser will be redirected to the Cloudflare dashboard.
+
+Step 9
+: On the "Workers" tab, press the **Get started** button to the right of the "Import a repository" item.
+
+ 
+
+Step 10
+: Select the repository to import.
+
+ 
+
+Step 11
+: On the "Set up your application" screen, provide a project name, leave the build command blank, then press the **Create and deploy** button.
+
+ 
+
+Step 12
+: Wait for the site to build and deploy, then visit your site.
+
+ 
+
+In the future, whenever you push a change from your local Git repository, Cloudflare will rebuild and deploy your site.
diff --git a/documents/markdown/hugo-docs/en_host-and-deploy_host-on-firebase.md b/documents/markdown/hugo-docs/en_host-and-deploy_host-on-firebase.md
new file mode 100644
index 0000000..9a28f1f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_host-and-deploy_host-on-firebase.md
@@ -0,0 +1,106 @@
+---
+title: Host on Firebase
+description: Host your site on Firebase.
+categories: []
+keywords: []
+aliases: [/hosting-and-deployment/hosting-on-firebase/]
+---
+
+## Assumptions
+
+1. You have an account with [Firebase][signup]. (If you don't, you can sign up for free using your Google account.)
+1. You have completed the [Quick Start] or have a completed Hugo website ready for deployment.
+
+## Initial setup
+
+Go to the [Firebase console][console] and create a new project (unless you already have a project). You will need to globally install `firebase-tools` (node.js):
+
+```sh
+npm install -g firebase-tools
+```
+
+Log in to Firebase (setup on your local machine) using `firebase login`, which opens a browser where you can select your account. Use `firebase logout` in case you are already logged in but to the wrong account.
+
+```sh
+firebase login
+```
+
+In the root of your Hugo project, initialize the Firebase project with the `firebase init` command:
+
+```sh
+firebase init
+```
+
+From here:
+
+1. Choose Hosting in the feature question
+1. Choose the project you just set up
+1. Accept the default for your database rules file
+1. Accept the default for the publish directory, which is `public`
+1. Choose "No" in the question if you are deploying a single-page app
+
+## Using Firebase & GitHub CI/CD
+
+In new versions of Firebase, some other questions apply:
+
+1. Set up automatic builds and deploys with GitHub?
+
+ Here you will be redirected to login in your GitHub account to get permissions. Confirm.
+
+1. For which GitHub repository would you like to set up a GitHub workflow? (format: user/repository)
+
+ Include the repository you will use in the format above (Account/Repo)
+ Firebase script with retrieve credentials, create a service account you can later manage in your GitHub settings.
+
+1. Set up the workflow to run a build script before every deploy?
+
+ Here is your opportunity to include some commands before you run the deploy.
+
+1. Set up automatic deployment to your site's live channel when a PR is merged?
+
+ You can let in the default option (main)
+
+After that Firebase has been set in your project with [CI/CD](g). After that run:
+
+```sh
+hugo build && firebase deploy
+```
+
+With this you will have the app initialized manually. After that you can manage and fix your GitHub workflow from <https://github.com/your-account/your-repo/actions>.
+
+Don't forget to update your static pages before push!
+
+## Manual deploy
+
+To deploy your Hugo site, execute the `firebase deploy` command, and your site will be up in no time:
+
+```sh
+hugo && firebase deploy
+```
+
+## CI setup (other tools)
+
+You can generate a deploy token using
+
+```sh
+firebase login:ci
+```
+
+You can also set up your CI and add the token to a private variable like `$FIREBASE_DEPLOY_TOKEN`.
+
+> [!note]
+> This is a private secret and it should not appear in a public repository. Make sure you understand your chosen CI and that it's not visible to others.
+
+You can then add a step in your build to do the deployment using the token:
+
+```sh
+firebase deploy --token $FIREBASE_DEPLOY_TOKEN
+```
+
+## Reference links
+
+- [Firebase CLI Reference](https://firebase.google.com/docs/cli/#administrative_commands)
+
+[console]: https://console.firebase.google.com/
+[Quick Start]: /getting-started/quick-start/
+[signup]: https://console.firebase.google.com/
diff --git a/documents/markdown/hugo-docs/en_host-and-deploy_host-on-github-pages_index.md b/documents/markdown/hugo-docs/en_host-and-deploy_host-on-github-pages_index.md
new file mode 100644
index 0000000..03b1786
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_host-and-deploy_host-on-github-pages_index.md
@@ -0,0 +1,196 @@
+---
+title: Host on GitHub Pages
+description: Host your site on GitHub Pages.
+categories: []
+keywords: []
+aliases: [/hosting-and-deployment/hosting-on-github/]
+---
+
+## Types of sites
+
+There are three types of GitHub Pages sites: project, user, and organization. Project sites are connected to a specific project hosted on GitHub. User and organization sites are connected to a specific account on GitHub.com.
+
+> [!note]
+> See the [GitHub Pages documentation] to understand the requirements for repository ownership and naming.
+
+## Prerequisites
+
+Please complete the following tasks before continuing:
+
+1. [Create](https://github.com/signup) a GitHub account
+1. [Log in](https://github.com/login) to your GitHub account
+1. [Create](https://github.com/new) a GitHub repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
+1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
+1. Commit the changes to your local Git repository and push to your GitHub repository
+
+## Procedure
+
+Step 1
+: Visit your GitHub repository. From the main menu choose **Settings** > **Pages**. In the center of your screen you will see this:
+
+ 
+
+ Change the **Source** to `GitHub Actions`. The change is immediate; you do not have to press a Save button.
+
+ 
+
+Step 2
+: In your project configuration, change the location of the image cache to the [`cacheDir`] as shown below:
+
+ {{< code-toggle file=hugo copy=true >}}
+ [caches.images]
+ dir = ':cacheDir/images'
+ {{< /code-toggle >}}
+
+ See [configure file caches] for more information.
+
+Step 3
+: Create a file named `hugo.yaml` in a directory named `.github/workflows`.
+
+ ```text
+ mkdir -p .github/workflows
+ touch .github/workflows/hugo.yaml
+ ```
+
+Step 4
+: Copy and paste the YAML below into the file you created.
+
+ ```yaml {file=".github/workflows/hugo.yaml" copy=true}
+ name: Build and deploy
+ on:
+ push:
+ branches:
+ - main
+ workflow_dispatch:
+ permissions:
+ contents: read
+ pages: write
+ id-token: write
+ concurrency:
+ group: pages
+ cancel-in-progress: false
+ defaults:
+ run:
+ shell: bash
+ jobs:
+ build:
+ runs-on: ubuntu-latest
+ env:
+ DART_SASS_VERSION: 1.98.0
+ GO_VERSION: 1.26.1
+ HUGO_VERSION: 0.158.0
+ NODE_VERSION: 24.14.0
+ TZ: Europe/Oslo
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v6
+ with:
+ submodules: recursive
+ fetch-depth: 0
+ - name: Setup Go
+ uses: actions/setup-go@v6
+ with:
+ go-version: ${{ env.GO_VERSION }}
+ cache: false
+ - name: Setup Node.js
+ uses: actions/setup-node@v6
+ with:
+ node-version: ${{ env.NODE_VERSION }}
+ - name: Setup Pages
+ id: pages
+ uses: actions/configure-pages@v5
+ - name: Create directory for user-specific executable files
+ run: |
+ mkdir -p "${HOME}/.local"
+ - name: Install Dart Sass
+ run: |
+ curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ echo "${HOME}/.local/dart-sass" >> "${GITHUB_PATH}"
+ - name: Install Hugo
+ run: |
+ curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ mkdir "${HOME}/.local/hugo"
+ tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ echo "${HOME}/.local/hugo" >> "${GITHUB_PATH}"
+ - name: Verify installations
+ run: |
+ echo "Dart Sass: $(sass --version)"
+ echo "Go: $(go version)"
+ echo "Hugo: $(hugo version)"
+ echo "Node.js: $(node --version)"
+ - name: Install Node.js dependencies
+ run: |
+ [[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true
+ - name: Configure Git
+ run: |
+ git config core.quotepath false
+ - name: Cache restore
+ id: cache-restore
+ uses: actions/cache/restore@v5
+ with:
+ path: ${{ runner.temp }}/hugo_cache
+ key: hugo-${{ github.run_id }}
+ restore-keys:
+ hugo-
+ - name: Build the site
+ run: |
+ hugo build \
+ --gc \
+ --minify \
+ --baseURL "${{ steps.pages.outputs.base_url }}/" \
+ --cacheDir "${{ runner.temp }}/hugo_cache"
+ - name: Cache save
+ id: cache-save
+ uses: actions/cache/save@v5
+ with:
+ path: ${{ runner.temp }}/hugo_cache
+ key: ${{ steps.cache-restore.outputs.cache-primary-key }}
+ - name: Upload artifact
+ uses: actions/upload-pages-artifact@v3
+ with:
+ path: ./public
+ deploy:
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ runs-on: ubuntu-latest
+ needs: build
+ steps:
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v4
+ ```
+
+Step 5
+: Commit the changes to your local Git repository and push to your GitHub repository.
+
+Step 6
+: From GitHub's main menu, choose **Actions**. You will see something like this:
+
+ 
+
+Step 7
+: When GitHub has finished building and deploying your site, the color of the status indicator will change to green.
+
+ 
+
+Step 8
+: Click on the commit message as shown above. Under the deploy step, you will see a link to your live site.
+
+ 
+
+In the future, whenever you push a change from your local Git repository, GitHub Pages will rebuild and deploy your site.
+
+## Other resources
+
+- [Learn more about GitHub Actions](https://docs.github.com/en/actions)
+- [Caching dependencies to speed up workflows](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows)
+- [Manage a custom domain for your GitHub Pages site](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages)
+
+[`cacheDir`]: /configuration/all/#cachedir
+[configure file caches]: /configuration/caches/
+[GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites
diff --git a/documents/markdown/hugo-docs/en_host-and-deploy_host-on-gitlab-pages.md b/documents/markdown/hugo-docs/en_host-and-deploy_host-on-gitlab-pages.md
new file mode 100644
index 0000000..6792b4f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_host-and-deploy_host-on-gitlab-pages.md
@@ -0,0 +1,137 @@
+---
+title: Host on GitLab Pages
+description: Host your site on GitLab Pages.
+categories: []
+keywords: []
+aliases: [/hosting-and-deployment/hosting-on-gitlab/]
+---
+
+## Assumptions
+
+- Working familiarity with Git for version control
+- Completion of the Hugo [Quick Start]
+- A [GitLab account](https://gitlab.com/users/sign_in)
+- A Hugo website on your local machine that you are ready to publish
+
+## BaseURL
+
+The `baseURL` in your [project configuration](/configuration/) must reflect the full URL of your GitLab pages repository if you are using the default GitLab Pages URL (e.g., `https://<YourUsername>.gitlab.io/<your-hugo-site>/`) and not a custom domain.
+
+## Configure GitLab CI/CD
+
+Define your [CI/CD](g) jobs by creating a `.gitlab-ci.yml` file in the root of your project.
+
+```yaml {file=".gitlab-ci.yml" copy=true}
+variables:
+ # Application versions
+ DART_SASS_VERSION: 1.98.0
+ HUGO_VERSION: 0.158.0
+ NODE_VERSION: 24.14.0
+ # Git
+ GIT_DEPTH: 0
+ GIT_STRATEGY: clone
+ GIT_SUBMODULE_STRATEGY: recursive
+ # Time zone
+ TZ: Europe/Oslo
+
+image:
+ name: golang:1.26.1-bookworm
+
+pages:
+ stage: deploy
+ script:
+ - |
+ # Create directory for user-specific executable files
+ echo "Creating directory for user-specific executable files..."
+ mkdir -p "${HOME}/.local"
+
+ # Install utilities
+ echo "Installing utilities..."
+ apt-get update
+ apt-get install -y brotli xz-utils zstd
+
+ # Install Dart Sass
+ echo "Installing Dart Sass ${DART_SASS_VERSION}..."
+ curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ export PATH="${HOME}/.local/dart-sass:${PATH}"
+
+ # Install Hugo
+ echo "Installing Hugo ${HUGO_VERSION}..."
+ curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
+ mkdir -p "${HOME}/.local/hugo"
+ tar -C "${HOME}/.local/hugo" -xf "hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
+ rm "hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/hugo:${PATH}"
+
+ # Install Node.js
+ echo "Installing Node.js ${NODE_VERSION}..."
+ curl -sLJO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz"
+ tar -C "${HOME}/.local" -xf "node-v${NODE_VERSION}-linux-x64.tar.xz"
+ rm "node-v${NODE_VERSION}-linux-x64.tar.xz"
+ export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}"
+
+ # Verify installations
+ echo "Verifying installations..."
+ echo "Dart Sass: $(sass --version)"
+ echo "Go: $(go version)"
+ echo "Hugo: $(hugo version)"
+ echo "Node.js: $(node --version)"
+ echo "brotli: $(brotli --version)"
+ echo "xz: $(xz --version)"
+ echo "zstd: $(zstd --version)"
+
+ # Install Node.js dependencies
+ echo "Installing Node.js dependencies..."
+ [[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci --prefer-offline || true
+
+ # Configure Git
+ echo "Configuring Git..."
+ git config core.quotepath false
+
+ # Build site
+ echo "Building site..."
+ hugo --gc --minify --baseURL "${CI_PAGES_URL}"
+
+ # Compress published files
+ echo "Compressing published files..."
+ find public/ -type f -regextype posix-extended -regex '.+\.(css|html|js|json|mjs|svg|txt|xml)$' -print0 > files.txt
+ time xargs --null --max-procs=0 --max-args=1 brotli --quality=10 --force --keep < files.txt
+ time xargs --null --max-procs=0 --max-args=1 gzip -9 --force --keep < files.txt
+ artifacts:
+ paths:
+ - public
+ rules:
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+```
+
+## Push your Hugo website to GitLab
+
+Next, create a new repository on GitLab. It is not necessary to make the repository public. In addition, you might want to add `/public` to your .gitignore file, as there is no need to push compiled assets to GitLab or keep your output website in version control.
+
+```sh
+# initialize new git repository
+git init
+
+# add /public directory to our .gitignore file
+echo "/public" >> .gitignore
+
+# commit and push code to master branch
+git add .
+git commit -m "Initial commit"
+git remote add origin https://gitlab.com/YourUsername/your-hugo-site.git
+git push -u origin master
+```
+
+## Wait for your page to build
+
+That's it! You can now follow the CI agent building your page at `https://gitlab.com/<YourUsername>/<your-hugo-site>/pipelines`.
+
+After the build has passed, your new website is available at `https://<YourUsername>.gitlab.io/<your-hugo-site>/`.
+
+## Next steps
+
+GitLab supports using custom CNAME's and TLS certificates. For more details on GitLab Pages, see the [GitLab Pages setup documentation](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/).
+
+[Quick Start]: /getting-started/quick-start/
diff --git a/documents/markdown/hugo-docs/en_host-and-deploy_host-on-netlify_index.md b/documents/markdown/hugo-docs/en_host-and-deploy_host-on-netlify_index.md
new file mode 100644
index 0000000..34ff067
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_host-and-deploy_host-on-netlify_index.md
@@ -0,0 +1,121 @@
+---
+title: Host on Netlify
+description: Host your site on Netlify.
+categories: []
+keywords: []
+aliases: [/hosting-and-deployment/hosting-on-netlify/]
+---
+
+Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using Azure DevOps, Bitbucket, or GitLab for version control.
+
+## Prerequisites
+
+Please complete the following tasks before continuing:
+
+1. [Create](https://app.netlify.com/signup) a Netlify account
+1. [Log in](https://app.netlify.com/login) to your Netlify account
+1. [Create](https://github.com/signup) a GitHub account
+1. [Log in](https://github.com/login) to your GitHub account
+1. [Create](https://github.com/new) a GitHub repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
+1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
+1. Commit the changes to your local Git repository and push to your GitHub repository.
+
+## Procedure
+
+<!-- Using "text" as the code block language because "toml" looks terrible. -->
+
+Step 1
+: Create a `netlify.toml` file in the root of your project.
+
+ ```text {file="netlify.toml" copy=true}
+ [build.environment]
+ DART_SASS_VERSION = "1.98.0"
+ GO_VERSION = "1.26.1"
+ HUGO_VERSION = "0.158.0"
+ NODE_VERSION = "24.14.0"
+ TZ = "Europe/Oslo"
+
+ [build]
+ publish = "public"
+ command = """\
+ git config core.quotepath false && \
+ hugo build --gc --minify --baseURL "${URL}"
+ """
+ ```
+
+ If your site requires Dart Sass to transpile Sass to CSS, set the `DART_SASS_VERSION` and include the Dart Sass installation in the build step.
+
+ ```text {file="netlify.toml" copy=true}
+ [build.environment]
+ DART_SASS_VERSION = "1.98.0"
+ GO_VERSION = "1.26.1"
+ HUGO_VERSION = "0.158.0"
+ NODE_VERSION = "24.14.0"
+ TZ = "Europe/Oslo"
+
+ [build]
+ publish = "public"
+ command = """\
+ curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" && \
+ tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" && \
+ rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" && \
+ export PATH="${HOME}/.local/dart-sass:${PATH}" && \
+ git config core.quotepath false && \
+ hugo build --gc --minify --baseURL "${URL}"
+ """
+ ```
+
+Step 2
+: Commit the changes to your local Git repository and push to your GitHub repository.
+
+Step 3
+: In the upper right corner of the Netlify dashboard, press the **Add new project** button and select “Import an existing project".
+
+ 
+
+Step 4
+: Connect to GitHub.
+
+ 
+
+Step 5
+: Press the "Authorize Netlify" button to allow the Netlify application to access your GitHub account.
+
+ 
+
+Step 6
+: Press the **Configure Netlify on GitHub** button.
+
+ 
+
+Step 7
+: Select the GitHub account where you want to install the Netlify application.
+
+ 
+
+Step 8
+: Authorize the Netlify application to access all repositories or only select repositories, then press the Install button.
+
+ 
+
+Your browser will be redirected to the Netlify dashboard.
+
+Step 9
+: Click on the name of the repository you wish to import.
+
+ 
+
+Step 10
+: On the "Review configuration" page, enter a project name, leave the settings at their default values, then press the **Deploy** button.
+
+ 
+
+ 
+
+Step 11
+: When the deployment completes, click on the link to your published site.
+
+ 
+
+In the future, whenever you push a change from your local Git repository, Netlify will rebuild and deploy your site.
diff --git a/documents/markdown/hugo-docs/en_host-and-deploy_host-on-render_index.md b/documents/markdown/hugo-docs/en_host-and-deploy_host-on-render_index.md
new file mode 100644
index 0000000..7ccbcc9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_host-and-deploy_host-on-render_index.md
@@ -0,0 +1,185 @@
+---
+title: Host on Render
+description: Host your site on Render.
+categories: []
+keywords: []
+aliases: [/hosting-and-deployment/hosting-on-render/]
+---
+
+Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using Bitbucket or GitLab for version control.
+
+## Prerequisites
+
+Please complete the following tasks before continuing:
+
+1. [Create](https://dashboard.render.com/register) a Render account
+1. [Log in](https://dashboard.render.com/login) to your Render account
+1. [Create](https://github.com/signup) a GitHub account
+1. [Log in](https://github.com/login) to your GitHub account
+1. [Create](https://github.com/new) a GitHub repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
+1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
+
+## Procedure
+
+Step 1
+: Create a [Render Blueprint][] in the root of your project.
+
+ ``` {file="render.yaml" copy=true}
+ services:
+ - type: web
+ name: hosting-render
+ repo: https://github.com/jmooring/hosting-render
+ runtime: static
+ buildCommand: chmod a+x build.sh && ./build.sh
+ staticPublishPath: public
+ envVars:
+ - key: DART_SASS_VERSION
+ value: 1.98.0
+ - key: GO_VERSION
+ value: 1.26.1
+ - key: HUGO_VERSION
+ value: 0.158.0
+ - key: NODE_VERSION
+ value: 24.14.0
+ - key: TZ
+ value: Europe/Oslo
+ ```
+
+Step 2
+: Create a `build.sh` file in the root of your project.
+
+ ```sh {file="build.sh" copy=true}
+ #!/usr/bin/env bash
+
+ #------------------------------------------------------------------------------
+ # @file
+ # Builds a Hugo site hosted on a Render.
+ #
+ # Render automatically installs Node.js dependencies.
+ #------------------------------------------------------------------------------
+
+ # Exit on error, undefined variables, or pipe failures
+ set -euo pipefail
+
+ build_temp_dir=""
+
+ # Perform cleanup
+ cleanup() {
+ if [[ -n "${build_temp_dir:-}" && -d "${build_temp_dir}" ]]; then
+ rm -rf "${build_temp_dir}"
+ fi
+ }
+
+ # Register the cleanup trap
+ trap cleanup EXIT SIGINT SIGTERM
+
+ main() {
+ # Create and move into a temporary directory for downloads
+ build_temp_dir=$(mktemp -d)
+ pushd "${build_temp_dir}" > /dev/null
+
+ # Create the local tools directory
+ mkdir -p "${HOME}/.local"
+
+ # Install Dart Sass
+ echo "Installing Dart Sass ${DART_SASS_VERSION}..."
+ curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ export PATH="${HOME}/.local/dart-sass:${PATH}"
+
+ # Install Go
+ echo "Installing Go ${GO_VERSION}..."
+ curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz"
+ tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/go/bin:${PATH}"
+
+ # Install Hugo
+ echo "Installing Hugo ${HUGO_VERSION}..."
+ curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
+ mkdir -p "${HOME}/.local/hugo"
+ tar -C "${HOME}/.local/hugo" -xf "hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/hugo:${PATH}"
+
+ # Return to the project root
+ popd > /dev/null
+
+ # Verify installations
+ echo "Verifying installations..."
+ echo Dart Sass: "$(sass --version)"
+ echo Go: "$(go version)"
+ echo Hugo: "$(hugo version)"
+ echo Node.js: "$(node --version)"
+
+ # Configure Git
+ echo "Configuring Git..."
+ git config core.quotepath false
+ if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
+ git fetch --unshallow
+ fi
+
+ # Build the site
+ echo "Building the site..."
+ hugo build --gc --minify --baseURL "${RENDER_EXTERNAL_URL}"
+ }
+
+ main "$@"
+ ```
+
+Step 3
+: Commit the changes to your local Git repository and push to your GitHub repository.
+
+Step 4
+: On the Render [dashboard][], press the **Add new** button and select "Blueprint" from the drop-down menu.
+
+ 
+
+Step 5
+: Press the **GitHub** button to connect to your GitHub account.
+
+ 
+
+Step 6
+: Press the **Authorize Render** button to allow the Render application to access your GitHub account.
+
+ 
+
+Step 7
+: Select the GitHub account where you want to install the Render application.
+
+ 
+
+Step 8
+: Authorize the Render application to access all repositories or only select repositories, then press the **Install** button.
+
+
+
+Step 9
+: On the "Create a new Blueprint Instance in My Workspacee" page, press the **Connect** button to the right of the name of your GitHub repository.
+
+ 
+
+Step 10
+: Enter a unique name for your Blueprint, then press the **Deploy Blueprint** button at the bottom of the page.
+
+ 
+
+Step 11
+: Wait for the site to build and deploy, then click on the "Resources" link on the left side of the page.
+
+ 
+
+Step 12
+: Click on the link to the static site resource.
+
+ 
+
+Step 13
+: Click on the link to your published site.
+
+ 
+
+In the future, whenever you push a change from your local Git repository, Render will rebuild and deploy your site.
+
+[Render Blueprint]: https://render.com/docs/blueprint-spec
+[dashboard]: https://dashboard.render.com/
diff --git a/documents/markdown/hugo-docs/en_host-and-deploy_host-on-sourcehut-pages.md b/documents/markdown/hugo-docs/en_host-and-deploy_host-on-sourcehut-pages.md
new file mode 100644
index 0000000..9054596
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_host-and-deploy_host-on-sourcehut-pages.md
@@ -0,0 +1,125 @@
+---
+title: Host on SourceHut Pages
+description: Host your site on SourceHut Pages.
+categories: []
+keywords: []
+aliases: [/hosting-and-deployment/hosting-on-sourcehut/]
+---
+
+## Assumptions
+
+- Working familiarity with [Git][] or [Mercurial][] for version control
+- Completion of the Hugo [Quick Start][]
+- A [SourceHut account][]
+- A Hugo website on your local machine that you are ready to publish
+
+[Git]: https://git-scm.com/
+[Mercurial]: https://www.mercurial-scm.org/
+[SourceHut account]: https://meta.sr.ht/login
+[Quick Start]: /getting-started/quick-start/
+
+Any and all mentions of `<YourUsername>` refer to your actual SourceHut username and must be substituted accordingly.
+
+## BaseURL
+
+The [`baseURL`][] in your project configuration must reflect the full URL provided by SourceHut Pages if you are using the default address (e.g. `https://<YourUsername>.srht.site/`). If you want to use another domain, check the [custom domain section][] of the official documentation.
+
+[`baseURL`]: /configuration/all/#baseurl
+[custom domain section]: https://srht.site/custom-domains
+
+## Manual deployment
+
+This method does not require a paid account. To proceed you will need to create a [SourceHut personal access token][] and install and configure the [hut][] CLI tool:
+
+[SourceHut personal access token]: https://meta.sr.ht/oauth2/personal-token
+[hut]: https://sr.ht/~xenrox/hut/
+
+```sh
+hugo build
+tar -C public -cvz . > site.tar.gz
+hut init
+hut pages publish -d <YourUsername>.srht.site site.tar.gz
+```
+
+A TLS certificate will be automatically obtained for you, and your new website will be available at `https://<YourUsername>.srht.site/` (or the provided custom domain).
+
+## Automated deployment
+
+This method requires a paid account and relies on the SourceHut build system.
+
+First, define your [build manifest][] by creating a `.build.yml` file in the root of your project. The following is a bare-bones template:
+
+[build manifest]: https://man.sr.ht/builds.sr.ht/#build-manifests
+
+```yaml {file=".build.yml" copy=true}
+image: alpine/edge
+packages:
+ - hugo
+ - hut
+oauth: pages.sr.ht/PAGES:RW
+environment:
+ site: <YourUsername>.srht.site
+tasks:
+- package: |
+ cd $site
+ hugo build
+ tar -C public -cvz . > ../site.tar.gz
+- upload: |
+ hut pages publish -d $site site.tar.gz
+```
+
+If your site requires [Dart Sass][] to transpile Sass to CSS, set the DART_SASS_VERSION to the [latest version number][] and include the Dart Sass installation lines before running the Hugo build step. Note that for Alpine, the `linux-x64-musl` version is used.
+
+[Dart Sass]: https://gohugo.io/functions/css/sass/#dart-sass
+[latest version number]: https://github.com/sass/dart-sass/releases
+
+```yaml {file=".build.yml" copy=true}
+image: alpine/edge
+packages:
+ - hugo
+ - hut
+ - curl # For Dart Sass installation
+oauth: pages.sr.ht/PAGES:RW
+environment:
+ site: <YourUsername>.srht.site
+tasks:
+- package: |
+ DART_SASS_VERSION=1.98.0
+ mkdir -p $HOME/.local
+ curl -L https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64-musl.tar.gz -o dart-sass.tar.gz
+ tar -xzf dart-sass.tar.gz -C $HOME/.local
+ rm dart-sass.tar.gz
+ chmod -R +x $HOME/.local/dart-sass/src
+ export PATH="$HOME/.local/dart-sass:$PATH"
+ sass --version # Verify installation
+ cd $site
+ hugo build
+ tar -C public -cvz . > ../site.tar.gz
+- upload: |
+ hut pages publish -d $site site.tar.gz
+```
+
+Now what's left is creating a repository titled `<YourUsername>.srht.site` (or your custom domain, if applicable) and pushing your local project. Here's an example using Git:
+
+```sh
+# initialize new git repository
+git init
+
+# add /public directory to our .gitignore file
+echo "/public" >> .gitignore
+
+# commit and push code to main branch
+git add .
+git commit -m "Initial commit"
+git remote add origin https://git.sr.ht/~<YourUsername>/<YourUsername>.srht.site
+git push -u origin main
+```
+
+You can now follow the build progress of your page at `https://builds.sr.ht/`.
+
+After the build has passed, a TLS certificate will be automatically obtained for you and your new website will be available at `https://<YourUsername>.srht.site/` (or the provided custom domain).
+
+## Other resources
+
+- [SourceHut Pages](https://srht.site/)
+- [SourceHut Builds user manual](https://man.sr.ht/builds.sr.ht/)
diff --git a/documents/markdown/hugo-docs/en_host-and-deploy_host-on-vercel_index.md b/documents/markdown/hugo-docs/en_host-and-deploy_host-on-vercel_index.md
new file mode 100644
index 0000000..9682588
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_host-and-deploy_host-on-vercel_index.md
@@ -0,0 +1,185 @@
+---
+title: Host on Vercel
+description: Host your site on Vercel.
+categories: []
+keywords: []
+---
+
+Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using Bitbucket or GitLab for version control.
+
+## Prerequisites
+
+Please complete the following tasks before continuing:
+
+1. [Create](https://vercel.com/signup) a Vercel account
+1. [Log in](https://vercel.com/login) to your Vercel account
+1. [Create](https://github.com/signup) a GitHub account
+1. [Log in](https://github.com/login) to your GitHub account
+1. [Create](https://github.com/new) a GitHub repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
+1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
+
+## Procedure
+
+Step 1
+: Create a `vercel.json` file in the root of your project.
+
+ ```json {file="vercel.json" copy=true}
+ {
+ "$schema": "https://openapi.vercel.sh/vercel.json",
+ "buildCommand": "chmod a+x build.sh && ./build.sh",
+ "outputDirectory": "public"
+ }
+ ```
+
+Step 2
+: Create a `build.sh` file in the root of your project.
+
+ ```sh {file="build.sh" copy=true}
+ #!/usr/bin/env bash
+
+ #------------------------------------------------------------------------------
+ # @file
+ # Builds a Hugo site hosted on Vercel.
+ #
+ # The Vercel build image automatically installs Node.js dependencies.
+ #------------------------------------------------------------------------------
+
+ # Exit on error, undefined variables, or pipe failures
+ set -euo pipefail
+
+ build_temp_dir=""
+
+ # Perform cleanup
+ cleanup() {
+ if [[ -n "${build_temp_dir:-}" && -d "${build_temp_dir}" ]]; then
+ rm -rf "${build_temp_dir}"
+ fi
+ }
+
+ # Register the cleanup trap
+ trap cleanup EXIT SIGINT SIGTERM
+
+ main() {
+ # Define tool versions
+ DART_SASS_VERSION=1.98.0
+ GO_VERSION=1.26.1
+ HUGO_VERSION=0.158.0
+ NODE_VERSION=24.14.0
+
+ # Set the build timezone
+ export TZ=Europe/Oslo
+
+ # Create and move into a temporary directory for downloads
+ build_temp_dir=$(mktemp -d)
+ pushd "${build_temp_dir}" > /dev/null
+
+ # Create the local tools directory
+ mkdir -p "${HOME}/.local"
+
+ # Install Dart Sass
+ echo "Installing Dart Sass ${DART_SASS_VERSION}..."
+ curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ export PATH="${HOME}/.local/dart-sass:${PATH}"
+
+ # Install Go
+ echo "Installing Go ${GO_VERSION}..."
+ curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz"
+ tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/go/bin:${PATH}"
+
+ # Install Hugo
+ echo "Installing Hugo ${HUGO_VERSION}..."
+ curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
+ mkdir -p "${HOME}/.local/hugo"
+ tar -C "${HOME}/.local/hugo" -xf "hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/hugo:${PATH}"
+
+ # Install Node.js
+ echo "Installing Node.js ${NODE_VERSION}..."
+ curl -sLJO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz"
+ tar -C "${HOME}/.local" -xf "node-v${NODE_VERSION}-linux-x64.tar.xz"
+ export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}"
+
+ # Return to the project root
+ popd > /dev/null
+
+ # Verify installations
+ echo "Verifying installations..."
+ echo Dart Sass: "$(sass --version)"
+ echo Go: "$(go version)"
+ echo Hugo: "$(hugo version)"
+ echo Node.js: "$(node --version)"
+
+ # Configure Git
+ echo "Configuring Git..."
+ git config core.quotepath false
+ if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
+ git fetch --unshallow
+ fi
+
+ # Build the site
+ echo "Building the site..."
+ hugo build --gc --minify --baseURL "https://${VERCEL_PROJECT_PRODUCTION_URL}"
+ }
+
+ main "$@"
+ ```
+
+Step 3
+: Commit the changes to your local Git repository and push to your GitHub repository.
+
+Step 4
+: In the upper right corner of the Vercel dashboard, press the **Add New** button and select "Project" from the drop down menu.
+
+ 
+
+Step 5
+: Press the "Continue with GitHub" button.
+
+ 
+
+Step 6
+: Press the **Authorize Vercel** button to allow the Vercel application to access your GitHub account.
+
+ 
+
+Step 7
+: Press the **Install** button to install the Vercel application.
+
+ 
+
+Step 8
+: Select the GitHub account where you want to install the Vercel application.
+
+ 
+
+Step 9
+: Authorize the Vercel application to access all repositories or only select repositories, then press the **Install** button.
+
+ 
+
+ Your browser will be redirected to the Cloudflare dashboard.
+
+Step 10
+: Press the **Import** button to the right of the name of your GitHub repository.
+
+ 
+
+Step 11
+: On the "New Project" page, leave the settings at their default values and press the **Deploy** button.
+
+ 
+
+Step 12
+: When the deployment completes, press the **Continue to Dashboard" button at the bottom of the page.
+
+ 
+
+Step 13
+: On the "Production Deployment" page, click on the link to your published site.
+
+ 
+
+In the future, whenever you push a change from your local Git repository, Vercel will rebuild and deploy your site.
diff --git a/documents/markdown/hugo-docs/en_hugo-modules__index.md b/documents/markdown/hugo-docs/en_hugo-modules__index.md
new file mode 100644
index 0000000..7a538ea
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_hugo-modules__index.md
@@ -0,0 +1,8 @@
+---
+title: Hugo Modules
+description: Use Hugo Modules to manage the content, presentation, and behavior of your site.
+categories: []
+keywords: []
+weight: 10
+aliases: [/themes/overview/,/themes/]
+---
diff --git a/documents/markdown/hugo-docs/en_hugo-modules_introduction.md b/documents/markdown/hugo-docs/en_hugo-modules_introduction.md
new file mode 100644
index 0000000..ba1dd6a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_hugo-modules_introduction.md
@@ -0,0 +1,19 @@
+---
+title: Introduction
+description: A brief introduction to Hugo Modules.
+categories: []
+keywords: []
+weight: 10
+---
+
+Hugo uses modules as its fundamental organizational units. A module can be a full Hugo project or a smaller, reusable piece providing one or more of Hugo's seven component types: static files, content, layouts, data, assets, internationalization (i18n) resources, and archetypes.
+
+Modules are combinable in any arrangement, and external directories (including those from non-Hugo projects) can be mounted, effectively creating a single, unified file system.
+
+Some example projects:
+
+<https://github.com/bep/docuapi>
+: A theme that has been ported to Hugo Modules while testing this feature. It is a good example of a non-Hugo-project mounted into Hugo's directory structure.
+
+<https://github.com/bep/my-modular-site>
+: A simple site used for testing.
diff --git a/documents/markdown/hugo-docs/en_hugo-modules_nodejs-dependencies.md b/documents/markdown/hugo-docs/en_hugo-modules_nodejs-dependencies.md
new file mode 100644
index 0000000..6adb183
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_hugo-modules_nodejs-dependencies.md
@@ -0,0 +1,52 @@
+---
+title: Node.js dependencies
+description: How to manage Node dependencies in Hugo Modules.
+date: 2026-03-22
+categories: []
+keywords: []
+weight: 40
+---
+
+Hugo Modules that need Node packages (e.g. for Tailwind CSS) can declare those dependencies in a standard `package.json` at the module root. Hugo consolidates dependencies from all modules into an [npm workspace], so you only need a single `npm install` at the project level.
+
+[npm workspace]: https://docs.npmjs.com/cli/using-npm/workspaces
+
+## Declaring dependencies
+
+Each Hugo Module declares its Node dependencies in a `package.json` file in its root directory, using the standard `dependencies` and `devDependencies` fields.
+
+> [!note]
+> We improved this setup greatly in Hugo [v0.159.0](https://github.com/gohugoio/hugo/releases/tag/v0.159.0), but we kept the old `package.hugo.json` in the search path. Mostly to preserve as much backward compatibility as possible, but it may also be useful in some situations to reserve a separate set of Node dependencies for Hugo.
+
+## Consolidating with `hugo mod npm pack`
+
+Run [`hugo mod npm pack`] to collect Node dependencies from all modules and write them to `packages/hugoautogen/package.json`. Hugo also adds a `workspaces` entry to your project's root `package.json` pointing to this auto-generated package.
+
+The resulting project structure:
+
+```text
+project/
+├── package.json # your project's package.json (updated with workspaces entry)
+├── packages/
+│ └── hugoautogen/
+│ ├── package.json # auto-generated, contains consolidated module deps
+│ └── hugo_packagemeta.json # metadata and checksums for staleness detection
+└── ...
+```
+
+> [!note]
+In Hugo < v0.159.0 Hugo wrote the dependencies into your project's package.json, so if you have used `hugo mod npm pack` on your project using older Hugo versions, now is the time to do a spring cleaning of your project `package.json` file: Only direct Node dependencies needs to live in this file, all incoming dependencies from imported Hugo Modules gets written to `packages/hugoautogen/package.json`.
+
+When merging, the **topmost version, starting from the project, take precedence**. If a module declares `tailwindcss@4.1` but your project already has `tailwindcss@4.0`, the project version wins and the module dependency is excluded from the generated workspace package.
+
+## Staleness detection
+
+When Hugo detects that the npm dependency configuration has changed in one or more of the modules in use, you will get a warning in the console:
+
+```text
+WARN npm dependencies are out of sync, please run "hugo mod npm pack" (you may also want to run "npm install" after that)
+```
+
+This ensures you don't forget to re-run `hugo mod npm pack` after updating module versions.
+
+[`hugo mod npm pack`]: /commands/hugo_mod_npm_pack
diff --git a/documents/markdown/hugo-docs/en_hugo-modules_theme-components.md b/documents/markdown/hugo-docs/en_hugo-modules_theme-components.md
new file mode 100644
index 0000000..03891ed
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_hugo-modules_theme-components.md
@@ -0,0 +1,35 @@
+---
+title: Theme components
+description: Hugo provides advanced theming support with theme components.
+categories: []
+keywords: []
+weight: 30
+aliases: [/themes/customize/,/themes/customizing/]
+---
+
+A project can configure a theme as a composite of as many theme components as you need:
+
+{{< code-toggle file=hugo >}}
+theme = ["my-shortcodes", "base-theme", "hyde"]
+{{< /code-toggle >}}
+
+You can even nest this, and have the theme component itself include theme components in its own `hugo.toml` (theme inheritance).
+
+The theme definition example above in `hugo.toml` creates a theme with 3 theme components with precedence from left to right.
+
+For any given file, data entry, etc., Hugo will look first in the project and then in `my-shortcodes`, `base-theme`, and lastly `hyde`.
+
+Hugo uses two different algorithms to merge the file systems, depending on the file type:
+
+- For `i18n` and `data` files, Hugo merges deeply using the translation ID and data key inside the files.
+- For `static`, `layouts` (templates), and `archetypes` files, these are merged on file level. So the left-most file will be chosen.
+
+The name used in the `theme` definition above must match a directory in `/your-site/themes`, e.g. `/your-site/themes/my-shortcodes`.
+
+Also note that a component that is part of a theme can have its own configuration file, e.g. `hugo.toml`. There are currently some restrictions to what a theme component can configure:
+
+- `params` (global and per language)
+- `menu` (global and per language)
+- `outputformats` and `mediatypes`
+
+The same rules apply here: The left-most parameter/menu etc. with the same ID will win. There are some hidden and experimental namespace support in the above, which we will work to improve in the future, but theme authors are encouraged to create their own namespaces to avoid naming conflicts.
diff --git a/documents/markdown/hugo-docs/en_hugo-modules_use-modules.md b/documents/markdown/hugo-docs/en_hugo-modules_use-modules.md
new file mode 100644
index 0000000..e432afb
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_hugo-modules_use-modules.md
@@ -0,0 +1,200 @@
+---
+title: Use Hugo Modules
+description: Use modules to manage the content, layout, presentation, and behavior of your site.
+categories: []
+keywords: []
+weight: 20
+aliases: [/themes/usage/,/themes/installing/,/installing-and-using-themes/]
+---
+
+> [!note]
+> To work with modules you must install [Git][] and [Go][] 1.18 or later.
+
+## Introduction
+
+{{% glossary-term module %}}
+
+- Modules can be imported in any combination or sequence.
+- Module imports are recursive; importing Module A can trigger the import of Module B, and so on.
+- Modules can provide configuration files and directories, subject to the constraints described in the [merge configuration settings][] section of the documentation.
+- External directories, including those from non-Hugo projects, can be mounted to create a [unified file system](g).
+
+## Import
+
+To import a module, first initialize the project itself as a module. For example:
+
+```sh
+hugo mod init github.com/user/project
+```
+
+This will generate a [`go.mod`][] file in the project root.
+
+> [!note]
+> The module name is a unique identifier rather than a hosting requirement. Using a name like `github.com/user/project` is a common convention but it does not mean you must use Git or host your code on GitHub. You can use any name you like if you do not plan to have others import your project as a module. For example, you could use a simple name such as `my-project` when you run the initialization command.
+
+Then define one or more imports in your project configuration. This contrived example imports three modules, each containing custom shortcodes:
+
+{{< code-toggle file=hugo >}}
+[module]
+ [[module.imports]]
+ path = 'shortcodes-a'
+ [[module.imports]]
+ path = '/home/user/shortcodes-b'
+ [[module.imports]]
+ path = 'github.com/user/shortcodes-c'
+{{< /code-toggle >}}
+
+Import precedence is top-down. For example, if `shortcodes-a`, `shortcodes-b`, and `shortcodes-c` each define an `image` shortcode, the `image` shortcode from `shortcodes-a` will take effect.
+
+> [!note]
+> If multiple modules contain data files or [translation tables](g) with identical paths, the data is deeply merged, following top-down precedence.
+
+When you build your project, Hugo will:
+
+1. Download the modules
+1. Cache them for future use
+1. Generate a [`go.sum`][] file in the project root
+
+See [configuring module imports][] for details and options.
+
+## Update
+
+When you import a module, Hugo creates `go.mod` and `go.sum` files in your project root, storing version and checksum data. Clearing the module cache and rebuilding will re-download the originally imported module version, as specified in the `go.mod` file, ensuring consistent builds. Modules can be updated to other versions as needed.
+
+To update a module to the latest version:
+
+```sh
+hugo mod get -u github.com/user/shortcodes-c
+```
+
+To update a module to a specific version:
+
+```sh
+hugo mod get -u github.com/user/shortcodes-c@v0.42.0
+```
+
+To update all modules to the latest version:
+
+```sh
+hugo mod get -u
+```
+
+To recursively update all modules to the latest version:
+
+```sh
+hugo mod get -u ./...
+```
+
+## Tidy
+
+To remove unused entries from the `go.mod` and `go.sum` files:
+
+```sh
+hugo mod tidy
+```
+
+## Cache
+
+Hugo caches modules to avoid repeated downloads during site builds. By default, these are stored in the `modules` directory within the [`cacheDir`][].
+
+To clean the module cache for the current project:
+
+```sh
+hugo mod clean
+```
+
+To clean the module cache for all projects:
+
+```sh
+hugo mod clean --all
+```
+
+For details on cache location and eviction, see [configuring file caches][].
+
+## Vendor
+
+{{% glossary-term vendor %}}
+
+Vendoring a module provides the benefits described above and allows for local inspection of its [components](g).
+
+```sh
+hugo mod vendor
+```
+
+This command creates a `_vendor` directory containing copies of all imported modules, used in subsequent builds. Note that:
+
+- The `hugo mod vendor` command can be run from any module tree level.
+- Modules within the `themes` directory are not vendored.
+- The `--ignoreVendorPaths` flag allows you to exclude vendored modules matching a [glob pattern](g) from specific commands.
+
+> [!important]
+> Instead of modifying files directly within the `_vendor` directory, override them by creating a corresponding file with the same relative path in your project's root.
+
+To remove the vendored modules, delete the `_vendor` directory.
+
+## Replace
+
+For local module development, use a `replace` directive in `go.mod` pointing to your local directory:
+
+```text
+replace github.com/user/module => /home/user/projects/module
+```
+
+With `hugo serve`r running, this change will trigger a configuration reload and add the local directory to the watch list. Alternatively, configure replacements by setting the [`replacements`][] parameter in your project configuration.
+
+## Workspace
+
+{{% glossary-term "workspace" %}}
+
+Workspaces simplify local development of sites with modules. Create a `.work` file to define a workspace, and activate it via the [`workspace`][] configuration parameter or the `HUGO_MODULE_WORKSPACE` environment variable.
+
+A `.work` file example:
+
+```text
+go 1.25
+
+use .
+use ../my-hugo-module
+```
+
+Use the `use` directive to list module paths, including the main project (`.`). Start the Hugo server with the workspace enabled:
+
+```sh
+HUGO_MODULE_WORKSPACE=hugo.work hugo server --ignoreVendorPaths "**"
+```
+
+The `--ignoreVendorPaths` flag, used to ignore vendored dependencies (if applicable), enables live reloading of local edits within the workspace.
+
+## Graph
+
+To generate a [dependency graph](g), including vendoring, module replacement, and disabled module information, execute `hugo mod graph` within the target module directory. For example:
+
+```sh
+$ hugo mod graph
+
+github.com/bep/my-modular-site github.com/bep/hugotestmods/mymounts@v1.2.0
+github.com/bep/my-modular-site github.com/bep/hugotestmods/mypartials@v1.0.7
+github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myassets@v1.0.4
+github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myv2@v1.0.0
+DISABLED github.com/bep/my-modular-site github.com/spf13/hyde@v0.0.0-20190427180251-e36f5799b396
+github.com/bep/my-modular-site github.com/bep/hugo-fresh@v1.0.1
+github.com/bep/my-modular-site in-themesdir
+```
+
+## Mounts
+
+Imported modules automatically mount their component directories to Hugo's [unified file system](g). You can also manually mount any directory, including those from non-Hugo projects, to component directories.
+
+See [configuring module mounts][] for details.
+
+[`cacheDir`]: /configuration/all/#cachedir
+[`go.mod`]: https://go.dev/ref/mod#go-mod-file
+[`go.sum`]: https://go.dev/ref/mod#go-sum-files
+[`replacements`]: /configuration/module/#replacements
+[`workspace`]: /configuration/module/#workspace
+[configuring file caches]: /configuration/caches/
+[configuring module imports]: /configuration/module/#imports
+[configuring module mounts]: /configuration/module/#mounts
+[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+[Go]: https://go.dev/doc/install
+[merge configuration settings]: /configuration/introduction/#merge-configuration-settings
diff --git a/documents/markdown/hugo-docs/en_hugo-pipes__index.md b/documents/markdown/hugo-docs/en_hugo-pipes__index.md
new file mode 100755
index 0000000..5102815
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_hugo-pipes__index.md
@@ -0,0 +1,7 @@
+---
+title: Hugo Pipes
+description: Use asset pipelines to transform and optimize images, stylesheets, and JavaScript.
+categories: []
+keywords: []
+weight: 10
+---
diff --git a/documents/markdown/hugo-docs/en_hugo-pipes_bundling.md b/documents/markdown/hugo-docs/en_hugo-pipes_bundling.md
new file mode 100755
index 0000000..335cc5c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_hugo-pipes_bundling.md
@@ -0,0 +1,9 @@
+---
+title: Concat
+linkTitle: Concatenating assets
+description: Bundle any number of assets into one resource.
+categories: []
+keywords: []
+---
+
+See the [`resources.Concat`](/functions/resources/concat/) function.
diff --git a/documents/markdown/hugo-docs/en_hugo-pipes_fingerprint.md b/documents/markdown/hugo-docs/en_hugo-pipes_fingerprint.md
new file mode 100755
index 0000000..d38dfc1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_hugo-pipes_fingerprint.md
@@ -0,0 +1,9 @@
+---
+title: Fingerprint
+linkTitle: Fingerprinting and SRI hashing
+description: Cryptographically hash the content of the given resource.
+categories: []
+keywords: []
+---
+
+See the [`resources.Fingerprint`](/functions/resources/fingerprint/) function.
diff --git a/documents/markdown/hugo-docs/en_hugo-pipes_introduction.md b/documents/markdown/hugo-docs/en_hugo-pipes_introduction.md
new file mode 100755
index 0000000..fa9493f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_hugo-pipes_introduction.md
@@ -0,0 +1,74 @@
+---
+title: Hugo Pipes
+linkTitle: Introduction
+description: Hugo Pipes is Hugo's asset processing set of functions.
+categories: []
+keywords: []
+weight: 10
+aliases: [/assets/]
+---
+
+## Find resources in assets
+
+This is about global and remote resources.
+
+global resource
+: A file within the `assets` directory, or within any directory [mounted] to the `assets` directory.
+
+remote resource
+: A file on a remote server, accessible via HTTP or HTTPS.
+
+For `.Page` scoped resources, see the [page resources] section.
+
+[mounted]: /configuration/module/#mounts
+[page resources]: /content-management/page-resources/
+
+## Get a resource
+
+In order to process an asset with Hugo Pipes, it must be retrieved as a resource.
+
+For global resources, use:
+
+- [`resources.ByType`](/functions/resources/bytype/)
+- [`resources.Get`](/functions/resources/get/)
+- [`resources.GetMatch`](/functions/resources/getmatch/)
+- [`resources.Match`](/functions/resources/match/)
+
+For remote resources, use:
+
+- [`resources.GetRemote`](/functions/resources/getremote/)
+
+See the [GoDoc Page](https://pkg.go.dev/github.com/gohugoio/hugo/tpl/resources) for the `resources` package for an up to date overview of all template functions in this namespace.
+
+## Copy a resource
+
+See the [`resources.Copy`](/functions/resources/copy/) function.
+
+## Asset directory
+
+Asset files must be stored in the asset directory. This is `assets` by default, but can be configured via the configuration file's `assetDir` key.
+
+## Asset publishing
+
+Hugo publishes assets to the `publishDir` (typically `public`) when you invoke `.Permalink`, `.RelPermalink`, or `.Publish`. You can use `.Content` to inline the asset.
+
+## Go Pipes
+
+For improved readability, the Hugo Pipes examples of this documentation will be written using [Go Pipes](/templates/introduction/#pipes):
+
+```go-html-template
+{{ $style := resources.Get "sass/main.scss" | css.Sass | resources.Minify | resources.Fingerprint }}
+<link rel="stylesheet" href="{{ $style.Permalink }}">
+```
+
+## Caching
+
+Hugo Pipes invocations are cached based on the entire _pipe chain_.
+
+An example of a pipe chain is:
+
+```go-html-template
+{{ $mainJs := resources.Get "js/main.js" | js.Build "main.js" | minify | fingerprint }}
+```
+
+The pipe chain is only invoked the first time it is encountered in a site build, and results are otherwise loaded from cache. As such, Hugo Pipes can be used in templates which are executed thousands or millions of times without negatively impacting the build performance.
diff --git a/documents/markdown/hugo-docs/en_hugo-pipes_js.md b/documents/markdown/hugo-docs/en_hugo-pipes_js.md
new file mode 100644
index 0000000..18572d5
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_hugo-pipes_js.md
@@ -0,0 +1,9 @@
+---
+title: JavaScript
+linkTitle: JavaScript building
+description: Bundle, transpile, tree shake, code split, and minify JavaScript resources.
+categories: []
+keywords: []
+---
+
+See [JS functions](/functions/js/).
diff --git a/documents/markdown/hugo-docs/en_hugo-pipes_minification.md b/documents/markdown/hugo-docs/en_hugo-pipes_minification.md
new file mode 100755
index 0000000..4ba1ea6
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_hugo-pipes_minification.md
@@ -0,0 +1,9 @@
+---
+title: Minify
+linkTitle: Asset minification
+description: Minify a given resource.
+categories: []
+keywords: []
+---
+
+See the [`resources.Minify`](/functions/resources/minify/) function.
diff --git a/documents/markdown/hugo-docs/en_hugo-pipes_postcss.md b/documents/markdown/hugo-docs/en_hugo-pipes_postcss.md
new file mode 100755
index 0000000..1b47e8a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_hugo-pipes_postcss.md
@@ -0,0 +1,8 @@
+---
+title: PostCSS
+description: Process the given resource with PostCSS using any PostCSS plugin.
+categories: []
+keywords: []
+---
+
+See the [`css.PostCSS`](/functions/css/postcss/) function.
diff --git a/documents/markdown/hugo-docs/en_hugo-pipes_postprocess.md b/documents/markdown/hugo-docs/en_hugo-pipes_postprocess.md
new file mode 100755
index 0000000..72540fd
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_hugo-pipes_postprocess.md
@@ -0,0 +1,8 @@
+---
+title: PostProcess
+description: Process the given resource after the build.
+categories: []
+keywords: []
+---
+
+See the [`resources.PostProcess`](/functions/resources/postprocess/) function.
diff --git a/documents/markdown/hugo-docs/en_hugo-pipes_resource-from-string.md b/documents/markdown/hugo-docs/en_hugo-pipes_resource-from-string.md
new file mode 100755
index 0000000..ed5eaff
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_hugo-pipes_resource-from-string.md
@@ -0,0 +1,9 @@
+---
+title: FromString
+linkTitle: Resource from string
+description: Create a resource from a string.
+categories: []
+keywords: []
+---
+
+See the [`resources.FromString`](/functions/resources/fromstring/) function.
diff --git a/documents/markdown/hugo-docs/en_hugo-pipes_resource-from-template.md b/documents/markdown/hugo-docs/en_hugo-pipes_resource-from-template.md
new file mode 100755
index 0000000..bc50f63
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_hugo-pipes_resource-from-template.md
@@ -0,0 +1,9 @@
+---
+title: ExecuteAsTemplate
+linkTitle: Resource from template
+description: Create a resource from a Go template, parsed and executed with the given context.
+categories: []
+keywords: []
+---
+
+See the [`resources.ExecuteAsTemplate`](/functions/resources/executeastemplate/) function.
diff --git a/documents/markdown/hugo-docs/en_hugo-pipes_transpile-sass-to-css.md b/documents/markdown/hugo-docs/en_hugo-pipes_transpile-sass-to-css.md
new file mode 100644
index 0000000..7569142
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_hugo-pipes_transpile-sass-to-css.md
@@ -0,0 +1,10 @@
+---
+title: ToCSS
+linkTitle: Transpile Sass to CSS
+description: Transpile Sass to CSS.
+categories: []
+keywords: []
+aliases: [/hugo-pipes/transform-to-css/]
+---
+
+See the [`css.Sass`](/functions/css/sass) function.
diff --git a/documents/markdown/hugo-docs/en_installation__index.md b/documents/markdown/hugo-docs/en_installation__index.md
new file mode 100644
index 0000000..fdcb8f9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_installation__index.md
@@ -0,0 +1,8 @@
+---
+title: Installation
+description: Install Hugo on macOS, Linux, Windows, BSD, and on any machine that can run the Go compiler tool chain.
+categories: []
+keywords: []
+weight: 10
+aliases: [/getting-started/installing/]
+---
diff --git a/documents/markdown/hugo-docs/en_installation_bsd.md b/documents/markdown/hugo-docs/en_installation_bsd.md
new file mode 100644
index 0000000..7b8e8c8
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_installation_bsd.md
@@ -0,0 +1,71 @@
+---
+title: BSD
+description: Install Hugo on BSD derivatives.
+categories: []
+keywords: []
+weight: 40
+---
+
+{{% include "/_common/installation/01-editions.md" %}}
+
+{{% include "/_common/installation/02-prerequisites.md" %}}
+
+{{% include "/_common/installation/03-prebuilt-binaries.md" %}}
+
+## Repository packages
+
+Most BSD derivatives maintain a repository for commonly installed applications. Please note that these repositories may not contain the [latest release].
+
+[latest release]: https://github.com/gohugoio/hugo/releases/latest
+
+### DragonFly BSD
+
+[DragonFly BSD] includes Hugo in its package repository. To install the extended edition of Hugo:
+
+```sh
+sudo pkg install gohugo
+```
+
+[DragonFly BSD]: https://www.dragonflybsd.org/
+
+### FreeBSD
+
+[FreeBSD] includes Hugo in its package repository. To install the extended edition of Hugo:
+
+```sh
+sudo pkg install gohugo
+```
+
+[FreeBSD]: https://www.freebsd.org/
+
+### NetBSD
+
+[NetBSD] includes Hugo in its package repository. To install the extended edition of Hugo:
+
+```sh
+sudo pkgin install go-hugo
+```
+
+[NetBSD]: https://www.netbsd.org/
+
+### OpenBSD
+
+[OpenBSD] includes Hugo in its package repository. This will prompt you to select which edition of Hugo to install:
+
+```sh
+doas pkg_add hugo
+```
+
+[OpenBSD]: https://www.openbsd.org/
+
+{{% include "/_common/installation/04-build-from-source.md" %}}
+
+## Comparison
+
+ |Prebuilt binaries|Repository packages|Build from source
+:--|:--:|:--:|:--:
+Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+Easy to upgrade?|:heavy_check_mark:|varies|:heavy_check_mark:
+Easy to downgrade?|:heavy_check_mark:|varies|:heavy_check_mark:
+Automatic updates?|:x:|varies|:x:
+Latest version available?|:heavy_check_mark:|varies|:heavy_check_mark:
diff --git a/documents/markdown/hugo-docs/en_installation_linux.md b/documents/markdown/hugo-docs/en_installation_linux.md
new file mode 100644
index 0000000..6e8c9cd
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_installation_linux.md
@@ -0,0 +1,216 @@
+---
+title: Linux
+description: Install Hugo on Linux.
+categories: []
+keywords: []
+weight: 20
+---
+
+{{% include "/_common/installation/01-editions.md" %}}
+
+{{% include "/_common/installation/02-prerequisites.md" %}}
+
+{{% include "/_common/installation/03-prebuilt-binaries.md" %}}
+
+## Package managers
+
+### Snap
+
+[Snap] is a free and open-source package manager for Linux. Available for [most distributions], snap packages are simple to install and are automatically updated.
+
+The Hugo snap package is [strictly confined]. Strictly confined snaps run in complete isolation, up to a minimal access level that's deemed always safe. The sites you create and build must be located within your home directory, or on removable media.
+
+To install the extended edition of Hugo:
+
+```sh
+sudo snap install hugo
+```
+
+To control automatic updates:
+
+```sh
+# disable automatic updates
+sudo snap refresh --hold hugo
+
+# enable automatic updates
+sudo snap refresh --unhold hugo
+```
+
+To control access to removable media:
+
+```sh
+# allow access
+sudo snap connect hugo:removable-media
+
+# revoke access
+sudo snap disconnect hugo:removable-media
+```
+
+To control access to SSH keys:
+
+```sh
+# allow access
+sudo snap connect hugo:ssh-keys
+
+# revoke access
+sudo snap disconnect hugo:ssh-keys
+```
+
+[strictly confined]: https://snapcraft.io/docs/snap-confinement
+[most distributions]: https://snapcraft.io/docs/installing-snapd
+[Snap]: https://snapcraft.io/
+
+{{% include "/_common/installation/homebrew.md" %}}
+
+## Repository packages
+
+Most Linux distributions maintain a repository for commonly installed applications.
+
+> [!note]
+> The Hugo version available in package repositories varies based on Linux distribution and release, and in some cases will not be the [latest version].
+>
+> Use one of the other installation methods if your package repository does not provide the desired version.
+
+### Alpine Linux
+
+To install the extended edition of Hugo on [Alpine Linux]:
+
+```sh
+doas apk add --no-cache --repository=https://dl-cdn.alpinelinux.org/alpine/edge/community hugo
+```
+
+### Arch Linux
+
+Derivatives of the [Arch Linux] distribution of Linux include [EndeavourOS], [Garuda Linux], [Manjaro], and others. To install the extended edition of Hugo:
+
+```sh
+sudo pacman -S hugo
+```
+
+### Debian
+
+Derivatives of the [Debian] distribution of Linux include [elementary OS], [KDE neon], [Linux Lite], [Linux Mint], [MX Linux], [Pop!_OS], [Ubuntu], [Zorin OS], and others. To install the extended edition of Hugo:
+
+```sh
+sudo apt install hugo
+```
+
+You can also download Debian packages from the [latest release][] page.
+
+### Exherbo
+
+To install the extended edition of Hugo on [Exherbo]:
+
+1. Add this line to /etc/paludis/options.conf:
+
+ ```text
+ www-apps/hugo extended
+ ```
+
+1. Install using the Paludis package manager:
+
+ ```sh
+ cave resolve -x repository/heirecka
+ cave resolve -x hugo
+ ```
+
+### Fedora
+
+Derivatives of the [Fedora] distribution of Linux include [CentOS], [Red Hat Enterprise Linux], and others. To install the extended edition of Hugo:
+
+```sh
+sudo dnf install hugo
+```
+
+### Gentoo
+
+Derivatives of the [Gentoo] distribution of Linux include [Calculate Linux], [Funtoo], and others. To install the extended edition of Hugo:
+
+1. Specify the `extended` [USE] flag in /etc/portage/package.use/hugo:
+
+ ```text
+ www-apps/hugo extended
+ ```
+
+1. Build using the Portage package manager:
+
+ ```sh
+ sudo emerge www-apps/hugo
+ ```
+
+### NixOS
+
+The NixOS distribution of Linux includes Hugo in its package repository. To install the extended edition of Hugo:
+
+```sh
+nix-env -iA nixos.hugo
+```
+
+### openSUSE
+
+Derivatives of the [openSUSE] distribution of Linux include [GeckoLinux], [Linux Karmada], and others. To install the extended edition of Hugo:
+
+```sh
+sudo zypper install hugo
+```
+
+### Solus
+
+The [Solus] distribution of Linux includes Hugo in its package repository. To install the extended edition of Hugo:
+
+```sh
+sudo eopkg install hugo
+```
+
+### Void Linux
+
+To install the extended edition of Hugo on [Void Linux]:
+
+```sh
+sudo xbps-install -S hugo
+```
+
+{{% include "/_common/installation/04-build-from-source.md" %}}
+
+## Comparison
+
+ |Prebuilt binaries|Package managers|Repository packages|Build from source
+:--|:--:|:--:|:--:|:--:
+Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark:
+Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^1]|varies|:heavy_check_mark:
+Automatic updates?|:x:|varies [^2]|:x:|:x:
+Latest version available?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_check_mark:
+
+[^1]: Easy if a previous version is still installed.
+[^2]: Snap packages are automatically updated. Homebrew requires advanced configuration.
+
+[Alpine Linux]: https://alpinelinux.org/
+[Arch Linux]: https://archlinux.org/
+[Calculate Linux]: https://www.calculate-linux.org/
+[CentOS]: https://www.centos.org/
+[Debian]: https://www.debian.org/
+[elementary OS]: https://elementary.io/
+[EndeavourOS]: https://endeavouros.com/
+[Exherbo]: https://www.exherbolinux.org/
+[Fedora]: https://getfedora.org/
+[Funtoo]: https://www.funtoo.org/
+[Garuda Linux]: https://garudalinux.org/
+[GeckoLinux]: https://geckolinux.github.io/
+[Gentoo]: https://www.gentoo.org/
+[KDE neon]: https://neon.kde.org/
+[latest release]: https://github.com/gohugoio/hugo/releases/latest
+[latest version]: https://github.com/gohugoio/hugo/releases/latest
+[Linux Karmada]: https://linuxkamarada.com/
+[Linux Lite]: https://www.linuxliteos.com/
+[Linux Mint]: https://linuxmint.com/
+[Manjaro]: https://manjaro.org/
+[MX Linux]: https://mxlinux.org/
+[openSUSE]: https://www.opensuse.org/
+[Pop!_OS]: https://pop.system76.com/
+[Red Hat Enterprise Linux]: https://www.redhat.com/
+[Solus]: https://getsol.us/
+[Ubuntu]: https://ubuntu.com/
+[USE]: https://packages.gentoo.org/packages/www-apps/hugo
+[Void Linux]: https://voidlinux.org/
+[Zorin OS]: https://zorin.com/os/
diff --git a/documents/markdown/hugo-docs/en_installation_macos.md b/documents/markdown/hugo-docs/en_installation_macos.md
new file mode 100644
index 0000000..1984d1a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_installation_macos.md
@@ -0,0 +1,42 @@
+---
+title: macOS
+description: Install Hugo on macOS.
+categories: []
+keywords: []
+weight: 10
+---
+
+{{% include "/_common/installation/01-editions.md" %}}
+
+{{% include "/_common/installation/02-prerequisites.md" %}}
+
+{{% include "/_common/installation/03-prebuilt-binaries.md" %}}
+
+## Package managers
+
+{{% include "/_common/installation/homebrew.md" %}}
+
+### MacPorts
+
+[MacPorts] is a free and open-source package manager for macOS. To install the extended edition of Hugo:
+
+```sh
+sudo port install hugo
+```
+
+[MacPorts]: https://www.macports.org/
+
+{{% include "/_common/installation/04-build-from-source.md" %}}
+
+## Comparison
+
+ |Prebuilt binaries|Package managers|Build from source
+:--|:--:|:--:|:--:
+Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^1]|:heavy_check_mark:
+Automatic updates?|:x:|:x: [^2]|:x:
+Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+
+[^1]: Easy if a previous version is still installed.
+[^2]: Possible but requires advanced configuration.
diff --git a/documents/markdown/hugo-docs/en_installation_windows.md b/documents/markdown/hugo-docs/en_installation_windows.md
new file mode 100644
index 0000000..8563ab7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_installation_windows.md
@@ -0,0 +1,70 @@
+---
+title: Windows
+description: Install Hugo on Windows.
+categories: []
+keywords: []
+weight: 30
+---
+
+> [!note]
+> Hugo v0.121.1 and later require at least Windows 10 or Windows Server 2016.
+
+{{% include "/_common/installation/01-editions.md" %}}
+
+{{% include "/_common/installation/02-prerequisites.md" %}}
+
+{{% include "/_common/installation/03-prebuilt-binaries.md" %}}
+
+## Package managers
+
+### Chocolatey
+
+[Chocolatey] is a free and open-source package manager for Windows. To install the extended edition of Hugo:
+
+```sh
+choco install hugo-extended
+```
+
+### Scoop
+
+[Scoop] is a free and open-source package manager for Windows. To install the extended edition of Hugo:
+
+```sh
+scoop install hugo-extended
+```
+
+### Winget
+
+[Winget] is Microsoft's official free and open-source package manager for Windows. To install the extended edition of Hugo:
+
+```sh
+winget install Hugo.Hugo.Extended
+```
+
+To uninstall the extended edition of Hugo:
+
+```sh
+winget uninstall --name "Hugo (Extended)"
+```
+
+{{% include "/_common/installation/04-build-from-source.md" %}}
+
+> [!note]
+> See these [detailed instructions](https://discourse.gohugo.io/t/41370) to install GCC on Windows.
+
+## Comparison
+
+ |Prebuilt binaries|Package managers|Build from source
+:--|:--:|:--:|:--:
+Easy to install?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+Easy to upgrade?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+Easy to downgrade?|:heavy_check_mark:|:heavy_check_mark: [^2]|:heavy_check_mark:
+Automatic updates?|:x:|:x: [^1]|:x:
+Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
+
+[^1]: Possible but requires advanced configuration.
+[^2]: Easy if a previous version is still installed.
+
+[Chocolatey]: https://chocolatey.org/
+[Scoop]: https://scoop.sh/
+[Winget]: https://learn.microsoft.com/en-us/windows/package-manager/
diff --git a/documents/markdown/hugo-docs/en_methods__index.md b/documents/markdown/hugo-docs/en_methods__index.md
new file mode 100644
index 0000000..39f2b61
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods__index.md
@@ -0,0 +1,8 @@
+---
+title: Methods
+description: Use these methods within your templates.
+categories: []
+keywords: []
+weight: 10
+aliases: ['/variables/']
+---
diff --git a/documents/markdown/hugo-docs/en_methods_duration_Abs.md b/documents/markdown/hugo-docs/en_methods_duration_Abs.md
new file mode 100644
index 0000000..2e85797
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_duration_Abs.md
@@ -0,0 +1,15 @@
+---
+title: Abs
+description: Returns the absolute value of the given time.Duration value.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: time.Duration
+ signatures: [DURATION.Abs]
+---
+
+```go-html-template
+{{ $d = time.ParseDuration "-3h" }}
+{{ $d.Abs }} → 3h0m0s
+```
diff --git a/documents/markdown/hugo-docs/en_methods_duration_Hours.md b/documents/markdown/hugo-docs/en_methods_duration_Hours.md
new file mode 100644
index 0000000..2365551
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_duration_Hours.md
@@ -0,0 +1,15 @@
+---
+title: Hours
+description: Returns the time.Duration value as a floating point number of hours.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: float64
+ signatures: [DURATION.Hours]
+---
+
+```go-html-template
+{{ $d = time.ParseDuration "3.5h2.5m1.5s" }}
+{{ $d.Hours }} → 3.5420833333333333
+```
diff --git a/documents/markdown/hugo-docs/en_methods_duration_Microseconds.md b/documents/markdown/hugo-docs/en_methods_duration_Microseconds.md
new file mode 100644
index 0000000..c090316
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_duration_Microseconds.md
@@ -0,0 +1,15 @@
+---
+title: Microseconds
+description: Returns the time.Duration value as an integer microsecond count.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int64
+ signatures: [DURATION.Microseconds]
+---
+
+```go-html-template
+{{ $d = time.ParseDuration "3.5h2.5m1.5s" }}
+{{ $d.Microseconds }} → 12751500000
+```
diff --git a/documents/markdown/hugo-docs/en_methods_duration_Milliseconds.md b/documents/markdown/hugo-docs/en_methods_duration_Milliseconds.md
new file mode 100644
index 0000000..288f369
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_duration_Milliseconds.md
@@ -0,0 +1,15 @@
+---
+title: Milliseconds
+description: Returns the time.Duration value as an integer millisecond count.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int64
+ signatures: [DURATION.Milliseconds]
+---
+
+```go-html-template
+{{ $d = time.ParseDuration "3.5h2.5m1.5s" }}
+{{ $d.Milliseconds }} → 12751500
+```
diff --git a/documents/markdown/hugo-docs/en_methods_duration_Minutes.md b/documents/markdown/hugo-docs/en_methods_duration_Minutes.md
new file mode 100644
index 0000000..aec904f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_duration_Minutes.md
@@ -0,0 +1,15 @@
+---
+title: Minutes
+description: Returns the time.Duration value as a floating point number of minutes.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: float64
+ signatures: [DURATION.Minutes]
+---
+
+```go-html-template
+{{ $d = time.ParseDuration "3.5h2.5m1.5s" }}
+{{ $d.Minutes }} → 212.525
+```
diff --git a/documents/markdown/hugo-docs/en_methods_duration_Nanoseconds.md b/documents/markdown/hugo-docs/en_methods_duration_Nanoseconds.md
new file mode 100644
index 0000000..fd1b9e4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_duration_Nanoseconds.md
@@ -0,0 +1,15 @@
+---
+title: Nanoseconds
+description: Returns the time.Duration value as an integer nanosecond count.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int64
+ signatures: [DURATION.Nanoseconds]
+---
+
+```go-html-template
+{{ $d = time.ParseDuration "3.5h2.5m1.5s" }}
+{{ $d.Nanoseconds }} → 12751500000000
+```
diff --git a/documents/markdown/hugo-docs/en_methods_duration_Round.md b/documents/markdown/hugo-docs/en_methods_duration_Round.md
new file mode 100644
index 0000000..dfd0625
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_duration_Round.md
@@ -0,0 +1,18 @@
+---
+title: Round
+description: Returns the result of rounding DURATION1 to the nearest multiple of DURATION2.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType:
+ signatures: [DURATION1.Round DURATION2]
+---
+
+```go-html-template
+{{ $d = time.ParseDuration "3.5h2.5m1.5s" }}
+
+{{ $d.Round (time.ParseDuration "2h") }} → 4h0m0s
+{{ $d.Round (time.ParseDuration "3m") }} → 3h33m0s
+{{ $d.Round (time.ParseDuration "4s") }} → 3h32m32s
+```
diff --git a/documents/markdown/hugo-docs/en_methods_duration_Seconds.md b/documents/markdown/hugo-docs/en_methods_duration_Seconds.md
new file mode 100644
index 0000000..8b6d060
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_duration_Seconds.md
@@ -0,0 +1,15 @@
+---
+title: Seconds
+description: Returns the time.Duration value as a floating point number of seconds.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: float64
+ signatures: [DURATION.Seconds]
+---
+
+```go-html-template
+{{ $d = time.ParseDuration "3.5h2.5m1.5s" }}
+{{ $d.Seconds }} → 12751.5
+```
diff --git a/documents/markdown/hugo-docs/en_methods_duration_Truncate.md b/documents/markdown/hugo-docs/en_methods_duration_Truncate.md
new file mode 100644
index 0000000..5a785a7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_duration_Truncate.md
@@ -0,0 +1,18 @@
+---
+title: Truncate
+description: Returns the result of rounding DURATION1 toward zero to a multiple of DURATION2.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: time.Duration
+ signatures: [DURATION1.Truncate DURATION2]
+---
+
+```go-html-template
+{{ $d = time.ParseDuration "3.5h2.5m1.5s" }}
+
+{{ $d.Truncate (time.ParseDuration "2h") }} → 2h0m0s
+{{ $d.Truncate (time.ParseDuration "3m") }} → 3h30m0s
+{{ $d.Truncate (time.ParseDuration "4s") }} → 3h32m28s
+```
diff --git a/documents/markdown/hugo-docs/en_methods_duration__index.md b/documents/markdown/hugo-docs/en_methods_duration__index.md
new file mode 100644
index 0000000..4c690ec
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_duration__index.md
@@ -0,0 +1,7 @@
+---
+title: Duration methods
+linkTitle: Duration
+description: Use these methods with a time.Duration value.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_methods_menu-entry_Children.md b/documents/markdown/hugo-docs/en_methods_menu-entry_Children.md
new file mode 100644
index 0000000..16cec71
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_menu-entry_Children.md
@@ -0,0 +1,66 @@
+---
+title: Children
+description: Returns a collection of child menu entries, if any, under the given menu entry.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: navigation.Menu
+ signatures: [MENUENTRY.Children]
+---
+
+Use the `Children` method when rendering a nested menu.
+
+With this project configuration:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+name = 'Products'
+pageRef = '/product'
+weight = 10
+
+[[menus.main]]
+name = 'Product 1'
+pageRef = '/products/product-1'
+parent = 'Products'
+weight = 1
+
+[[menus.main]]
+name = 'Product 2'
+pageRef = '/products/product-2'
+parent = 'Products'
+weight = 2
+{{< /code-toggle >}}
+
+And this template:
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main }}
+ <li>
+ <a href="{{ .URL }}">{{ .Name }}</a>
+ {{ if .HasChildren }}
+ <ul>
+ {{ range .Children }}
+ <li><a href="{{ .URL }}">{{ .Name }}</a></li>
+ {{ end }}
+ </ul>
+ {{ end }}
+ </li>
+ {{ end }}
+</ul>
+```
+
+Hugo renders this HTML:
+
+```html
+<ul>
+ <li>
+ <a href="/products/">Products</a>
+ <ul>
+ <li><a href="/products/product-1/">Product 1</a></li>
+ <li><a href="/products/product-2/">Product 2</a></li>
+ </ul>
+ </li>
+</ul>
+```
diff --git a/documents/markdown/hugo-docs/en_methods_menu-entry_HasChildren.md b/documents/markdown/hugo-docs/en_methods_menu-entry_HasChildren.md
new file mode 100644
index 0000000..59ef2e1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_menu-entry_HasChildren.md
@@ -0,0 +1,66 @@
+---
+title: HasChildren
+description: Reports whether the given menu entry has child menu entries.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [MENUENTRY.HasChildren]
+---
+
+Use the `HasChildren` method when rendering a nested menu.
+
+With this project configuration:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+name = 'Products'
+pageRef = '/product'
+weight = 10
+
+[[menus.main]]
+name = 'Product 1'
+pageRef = '/products/product-1'
+parent = 'Products'
+weight = 1
+
+[[menus.main]]
+name = 'Product 2'
+pageRef = '/products/product-2'
+parent = 'Products'
+weight = 2
+{{< /code-toggle >}}
+
+And this template:
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main }}
+ <li>
+ <a href="{{ .URL }}">{{ .Name }}</a>
+ {{ if .HasChildren }}
+ <ul>
+ {{ range .Children }}
+ <li><a href="{{ .URL }}">{{ .Name }}</a></li>
+ {{ end }}
+ </ul>
+ {{ end }}
+ </li>
+ {{ end }}
+</ul>
+```
+
+Hugo renders this HTML:
+
+```html
+<ul>
+ <li>
+ <a href="/products/">Products</a>
+ <ul>
+ <li><a href="/products/product-1/">Product 1</a></li>
+ <li><a href="/products/product-2/">Product 2</a></li>
+ </ul>
+ </li>
+</ul>
+```
diff --git a/documents/markdown/hugo-docs/en_methods_menu-entry_Identifier.md b/documents/markdown/hugo-docs/en_methods_menu-entry_Identifier.md
new file mode 100644
index 0000000..7310ff3
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_menu-entry_Identifier.md
@@ -0,0 +1,41 @@
+---
+title: Identifier
+description: Returns the `identifier` property of the given menu entry.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [MENUENTRY.Identifier]
+---
+
+The `Identifier` method returns the `identifier` property of the menu entry. If you define the menu entry [automatically], it returns the page's section.
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+identifier = 'about'
+name = 'About'
+pageRef = '/about'
+weight = 10
+
+[[menus.main]]
+identifier = 'contact'
+name = 'Contact'
+pageRef = '/contact'
+weight = 20
+{{< /code-toggle >}}
+
+This example uses the `Identifier` method when querying the translation table on a multilingual project, falling back the `name` property if a matching key in the translation table does not exist:
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main }}
+ <li><a href="{{ .URL }}">{{ or (T .Identifier) .Name }}</a></li>
+ {{ end }}
+</ul>
+```
+
+> [!note]
+> In the menu definition above, note that the `identifier` property is only required when two or more menu entries have the same name, or when localizing the name using translation tables.
+
+[automatically]: /content-management/menus/#define-automatically
diff --git a/documents/markdown/hugo-docs/en_methods_menu-entry_KeyName.md b/documents/markdown/hugo-docs/en_methods_menu-entry_KeyName.md
new file mode 100644
index 0000000..abf6396
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_menu-entry_KeyName.md
@@ -0,0 +1,39 @@
+---
+title: KeyName
+description: Returns the `identifier` property of the given menu entry, falling back to its `name` property.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [MENUENTRY.KeyName]
+---
+
+In this menu definition, the second entry does not contain an `identifier`, so the `Identifier` method returns its `name` property instead:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+identifier = 'about'
+name = 'About'
+pageRef = '/about'
+weight = 10
+
+[[menus.main]]
+name = 'Contact'
+pageRef = '/contact'
+weight = 20
+{{< /code-toggle >}}
+
+This example uses the `KeyName` method when querying the translation table on a multilingual project, falling back the `name` property if a matching key in the translation table does not exist:
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main }}
+ <li><a href="{{ .URL }}">{{ or (T (.KeyName | lower)) .Name }}</a></li>
+ {{ end }}
+</ul>
+```
+
+In the example above, we need to pass the value returned by `.KeyName` through the [`lower`] function because the keys in the translation table are lowercase.
+
+[`lower`]: /functions/strings/tolower/
diff --git a/documents/markdown/hugo-docs/en_methods_menu-entry_Menu.md b/documents/markdown/hugo-docs/en_methods_menu-entry_Menu.md
new file mode 100644
index 0000000..074911e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_menu-entry_Menu.md
@@ -0,0 +1,22 @@
+---
+title: Menu
+description: Returns the identifier of the menu that contains the given menu entry.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [MENUENTRY.Menu]
+---
+
+```go-html-template
+{{ range .Site.Menus.main }}
+ {{ .Menu }} → main
+{{ end }}
+```
+
+Use this method with the [`IsMenuCurrent`] and [`HasMenuCurrent`] methods on a `Page` object to set "active" and "ancestor" classes on a rendered entry. See [this example].
+
+[`HasMenuCurrent`]: /methods/page/hasmenucurrent/
+[`IsMenuCurrent`]: /methods/page/ismenucurrent/
+[this example]: /templates/menu/#example
diff --git a/documents/markdown/hugo-docs/en_methods_menu-entry_Name.md b/documents/markdown/hugo-docs/en_methods_menu-entry_Name.md
new file mode 100644
index 0000000..a00601b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_menu-entry_Name.md
@@ -0,0 +1,28 @@
+---
+title: Name
+description: Returns the `name` property of the given menu entry.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [MENUENTRY.Name]
+---
+
+If you define the menu entry [automatically], the `Name` method returns the page's [`LinkTitle`], falling back to its [`Title`].
+
+If you define the menu entry in [front matter] or in your [project configuration], the `Name` method returns the `name` property of the given menu entry. If the `name` is not defined, and the menu entry resolves to a page, the `Name` returns the page [`LinkTitle`], falling back to its [`Title`].
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main }}
+ <li><a href="{{ .URL }}">{{ .Name }}</a></li>
+ {{ end }}
+</ul>
+```
+
+[`LinkTitle`]: /methods/page/linktitle/
+[`Title`]: /methods/page/title/
+[automatically]: /content-management/menus/#define-automatically
+[front matter]: /content-management/menus/#define-in-front-matter
+[project configuration]: /content-management/menus/#define-in-project-configuration
diff --git a/documents/markdown/hugo-docs/en_methods_menu-entry_Page.md b/documents/markdown/hugo-docs/en_methods_menu-entry_Page.md
new file mode 100644
index 0000000..489ee7a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_menu-entry_Page.md
@@ -0,0 +1,53 @@
+---
+title: Page
+description: Returns the Page object associated with the given menu entry.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Page
+ signatures: [MENUENTRY.Page]
+---
+
+Regardless of how you [define menu entries], an entry associated with a page has access to its [methods].
+
+In this menu definition, the first two entries are associated with a page, the last entry is not:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+pageRef = '/about'
+weight = 10
+
+[[menus.main]]
+pageRef = '/contact'
+weight = 20
+
+[[menus.main]]
+name = 'Hugo'
+url = 'https://gohugo.io'
+weight = 30
+{{< /code-toggle >}}
+
+In this example, if the menu entry is associated with a page, we use page's [`RelPermalink`] and [`LinkTitle`] when rendering the anchor element.
+
+If the entry is not associated with a page, we use its `url` and `name` properties.
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main }}
+ {{ with .Page }}
+ <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
+ {{ else }}
+ <li><a href="{{ .URL }}">{{ .Name }}</a></li>
+ {{ end }}
+ {{ end }}
+</ul>
+```
+
+See the [menu templates] section for more information.
+
+[`LinkTitle`]: /methods/page/linktitle/
+[`RelPermalink`]: /methods/page/relpermalink/
+[define menu entries]: /content-management/menus/
+[menu templates]: /templates/menu/#page-references
+[methods]: /methods/page/
diff --git a/documents/markdown/hugo-docs/en_methods_menu-entry_PageRef.md b/documents/markdown/hugo-docs/en_methods_menu-entry_PageRef.md
new file mode 100644
index 0000000..8d4e536
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_menu-entry_PageRef.md
@@ -0,0 +1,109 @@
+---
+title: PageRef
+description: Returns the `pageRef` property of the given menu entry.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [MENUENTRY.PageRef]
+---
+
+> [!note]
+> The use case for this method is rare.
+> In almost also scenarios you should use the [`URL`] method instead.
+
+## Explanation
+
+If you specify a `pageRef` property when [defining a menu entry] in your project configuration, Hugo looks for a matching page when rendering the entry.
+
+If a matching page is found:
+
+- The [`URL`] method returns the page's relative permalink
+- The [`Page`] method returns the corresponding `Page` object
+- The [`HasMenuCurrent`] and [`IsMenuCurrent`] methods on a `Page` object return the expected values
+
+If a matching page is not found:
+
+- The [`URL`] method returns the entry's `url` property if set, else an empty string
+- The [`Page`] method returns nil
+- The [`HasMenuCurrent`] and [`IsMenuCurrent`] methods on a `Page` object return `false`
+
+> [!note]
+> In almost also scenarios you should use the [`URL`] method instead.
+
+## Example
+
+This example is contrived.
+
+> [!note]
+> In almost also scenarios you should use the [`URL`] method instead.
+
+Consider this content structure:
+
+```text
+content/
+├── products.md
+└── _index.md
+```
+
+And this menu definition:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+name = 'Products'
+pageRef = '/products'
+weight = 10
+[[menus.main]]
+name = 'Services'
+pageRef = '/services'
+weight = 20
+{{< /code-toggle >}}
+
+With this template code:
+
+```go-html-template {file="layouts/_partials/menu.html"}
+<ul>
+ {{ range .Site.Menus.main }}
+ <li><a href="{{ .URL }}">{{ .Name }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Hugo render this HTML:
+
+```html
+<ul>
+ <li><a href="/products/">Products</a></li>
+ <li><a href="">Services</a></li>
+</ul>
+```
+
+In the above note that the `href` attribute of the second `anchor` element is blank because Hugo was unable to find the "services" page.
+
+With this template code:
+
+```go-html-template {file="layouts/_partials/menu.html"}
+<ul>
+ {{ range .Site.Menus.main }}
+ <li><a href="{{ or .URL .PageRef }}">{{ .Name }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Hugo renders this HTML:
+
+```html
+<ul>
+ <li><a href="/products/">Products</a></li>
+ <li><a href="/services">Services</a></li>
+</ul>
+```
+
+In the above note that Hugo populates the `href` attribute of the second `anchor` element with the `pageRef` property as defined in your project configuration because the template code falls back to the `PageRef` method.
+
+[`HasMenuCurrent`]: /methods/page/hasmenucurrent/
+[`IsMenuCurrent`]: /methods/page/ismenucurrent/
+[`Page`]: /methods/menu-entry/page/
+[`URL`]: /methods/menu-entry/url/
+[defining a menu entry]: /content-management/menus/#define-in-project-configuration
diff --git a/documents/markdown/hugo-docs/en_methods_menu-entry_Params.md b/documents/markdown/hugo-docs/en_methods_menu-entry_Params.md
new file mode 100644
index 0000000..1131781
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_menu-entry_Params.md
@@ -0,0 +1,61 @@
+---
+title: Params
+description: Returns the `params` property of the given menu entry.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: maps.Params
+ signatures: [MENUENTRY.Params]
+---
+
+When you define menu entries in your [project configuration] or in [front matter], you can include a `params` key to attach additional information to the entry. For example:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+name = 'About'
+pageRef = '/about'
+weight = 10
+
+[[menus.main]]
+name = 'Contact'
+pageRef = '/contact'
+weight = 20
+
+[[menus.main]]
+name = 'Hugo'
+url = 'https://gohugo.io'
+weight = 30
+[menus.main.params]
+ rel = 'external'
+{{< /code-toggle >}}
+
+With this template:
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main }}
+ <li>
+ <a href="{{ .URL }}" {{ with .Params.rel }}rel="{{ . }}"{{ end }}>
+ {{ .Name }}
+ </a>
+ </li>
+ {{ end }}
+</ul>
+```
+
+Hugo renders:
+
+```html
+<ul>
+ <li><a href="/about/">About</a></li>
+ <li><a href="/contact/">Contact</a></li>
+ <li><a href="https://gohugo.io" rel="external">Hugo</a></li>
+</ul>
+```
+
+See the [menu templates] section for more information.
+
+[menu templates]: /templates/menu/#menu-entry-parameters
+[front matter]: /content-management/menus/#define-in-front-matter
+[project configuration]: /content-management/menus/
diff --git a/documents/markdown/hugo-docs/en_methods_menu-entry_Parent.md b/documents/markdown/hugo-docs/en_methods_menu-entry_Parent.md
new file mode 100644
index 0000000..7c61752
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_menu-entry_Parent.md
@@ -0,0 +1,50 @@
+---
+title: Parent
+description: Returns the `parent` property of the given menu entry.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [MENUENTRY.Parent]
+---
+
+With this menu definition:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+name = 'Products'
+pageRef = '/product'
+weight = 10
+
+[[menus.main]]
+name = 'Product 1'
+pageRef = '/products/product-1'
+parent = 'Products'
+weight = 1
+
+[[menus.main]]
+name = 'Product 2'
+pageRef = '/products/product-2'
+parent = 'Products'
+weight = 2
+{{< /code-toggle >}}
+
+This template renders the nested menu, listing the `parent` property next each of the child entries:
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main }}
+ <li>
+ <a href="{{ .URL }}">{{ .Name }}</a>
+ {{ if .HasChildren }}
+ <ul>
+ {{ range .Children }}
+ <li><a href="{{ .URL }}">{{ .Name }}</a> ({{ .Parent }})</li>
+ {{ end }}
+ </ul>
+ {{ end }}
+ </li>
+ {{ end }}
+</ul>
+```
diff --git a/documents/markdown/hugo-docs/en_methods_menu-entry_Post.md b/documents/markdown/hugo-docs/en_methods_menu-entry_Post.md
new file mode 100644
index 0000000..2da8c38
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_menu-entry_Post.md
@@ -0,0 +1,12 @@
+---
+title: Post
+description: Returns the `post` property of the given menu entry.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: template.HTML
+ signatures: [MENUENTRY.Post]
+---
+
+{{% include "/_common/menu-entries/pre-and-post.md" %}}
diff --git a/documents/markdown/hugo-docs/en_methods_menu-entry_Pre.md b/documents/markdown/hugo-docs/en_methods_menu-entry_Pre.md
new file mode 100644
index 0000000..19af243
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_menu-entry_Pre.md
@@ -0,0 +1,12 @@
+---
+title: Pre
+description: Returns the `pre` property of the given menu entry.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: template.HTML
+ signatures: [MENUENTRY.Pre]
+---
+
+{{% include "/_common/menu-entries/pre-and-post.md" %}}
diff --git a/documents/markdown/hugo-docs/en_methods_menu-entry_Title.md b/documents/markdown/hugo-docs/en_methods_menu-entry_Title.md
new file mode 100644
index 0000000..526132d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_menu-entry_Title.md
@@ -0,0 +1,22 @@
+---
+title: Title
+description: Returns the `title` property of the given menu entry.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [MENUENTRY.Title]
+---
+
+The `Title` method returns the `title` property of the given menu entry. If the `title` is not defined, and the menu entry resolves to a page, the `Title` returns the page [`Title`].
+
+[`Title`]: /methods/page/title/
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main }}
+ <li><a href="{{ .URL }}" title="{{ .Title }}>{{ .Name }}</a></li>
+ {{ end }}
+</ul>
+```
diff --git a/documents/markdown/hugo-docs/en_methods_menu-entry_URL.md b/documents/markdown/hugo-docs/en_methods_menu-entry_URL.md
new file mode 100644
index 0000000..e29a6f0
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_menu-entry_URL.md
@@ -0,0 +1,22 @@
+---
+title: URL
+description: Returns the relative permalink of the page associated with the given menu entry, else its `url` property.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [MENUENTRY.URL]
+---
+
+For menu entries associated with a page, the `URL` method returns the page's [`RelPermalink`], otherwise it returns the entry's `url` property.
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main }}
+ <li><a href="{{ .URL }}">{{ .Name }}</a></li>
+ {{ end }}
+</ul>
+```
+
+[`RelPermalink`]: /methods/page/relpermalink/
diff --git a/documents/markdown/hugo-docs/en_methods_menu-entry_Weight.md b/documents/markdown/hugo-docs/en_methods_menu-entry_Weight.md
new file mode 100644
index 0000000..17fc3a4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_menu-entry_Weight.md
@@ -0,0 +1,31 @@
+---
+title: Weight
+description: Returns the `weight` property of the given menu entry.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [MENUENTRY.Weight]
+---
+
+If you define the menu entry [automatically], the `Weight` method returns the page's [`Weight`].
+
+If you define the menu entry in [front matter] or in your [project configuration], the `Weight` method returns the `weight` property, falling back to the page's `Weight`.
+
+In this contrived example, we limit the number of menu entries based on weight:
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main }}
+ {{ if le .Weight 42 }}
+ <li><a href="{{ .URL }}">{{ .Name }}</a></li>
+ {{ end }}
+ {{ end }}
+</ul>
+```
+
+[`Weight`]: /methods/page/weight/
+[automatically]: /content-management/menus/#define-automatically
+[front matter]: /content-management/menus/#define-in-front-matter
+[project configuration]: /content-management/menus/#define-in-project-configuration
diff --git a/documents/markdown/hugo-docs/en_methods_menu-entry__index.md b/documents/markdown/hugo-docs/en_methods_menu-entry__index.md
new file mode 100644
index 0000000..129e9bc
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_menu-entry__index.md
@@ -0,0 +1,7 @@
+---
+title: Menu entry methods
+linkTitle: Menu entry
+description: Use these methods in your menu templates.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_methods_menu_ByName.md b/documents/markdown/hugo-docs/en_methods_menu_ByName.md
new file mode 100644
index 0000000..d98a4ac
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_menu_ByName.md
@@ -0,0 +1,65 @@
+---
+title: ByName
+description: Returns the given menu with its entries sorted by name.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: navigation.Menu
+ signatures: [MENU.ByName]
+---
+
+The `Sort` method returns the given menu with its entries sorted by `name`.
+
+Consider this menu definition:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+name = 'Services'
+pageRef = '/services'
+weight = 10
+
+[[menus.main]]
+name = 'About'
+pageRef = '/about'
+weight = 20
+
+[[menus.main]]
+name = 'Contact'
+pageRef = '/contact'
+weight = 30
+{{< /code-toggle >}}
+
+To sort the entries by `name`:
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main.ByName }}
+ <li><a href="{{ .URL }}">{{ .Name }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Hugo renders this to:
+
+```html
+<ul>
+ <li><a href="/about/">About</a></li>
+ <li><a href="/contact">Contact</a></li>
+ <li><a href="/services/">Services</a></li>
+</ul>
+```
+
+You can also sort menu entries using the [`sort`] function. For example, to sort by `name` in descending order:
+
+```go-html-template
+<ul>
+ {{ range sort .Site.Menus.main "Name" "desc" }}
+ <li><a href="{{ .URL }}">{{ .Name }}</a></li>
+ {{ end }}
+</ul>
+```
+
+When using the sort function with menu entries, specify any of the following keys: `Identifier`, `Name`, `Parent`, `Post`, `Pre`, `Title`, `URL`, or `Weight`.
+
+[`sort`]: /functions/collections/sort/
diff --git a/documents/markdown/hugo-docs/en_methods_menu_ByWeight.md b/documents/markdown/hugo-docs/en_methods_menu_ByWeight.md
new file mode 100644
index 0000000..013d37e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_menu_ByWeight.md
@@ -0,0 +1,71 @@
+---
+title: ByWeight
+description: Returns the given menu with its entries sorted by weight, then by name, then by identifier.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: navigation.Menu
+ signatures: [MENU.ByWeight]
+---
+
+The `ByWeight` method returns the given menu with its entries sorted by [`weight`](g), then by `name`, then by `identifier`. This is the default sort order.
+
+Consider this menu definition:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+identifier = 'about'
+name = 'About'
+pageRef = '/about'
+weight = 20
+
+[[menus.main]]
+identifier = 'services'
+name = 'Services'
+pageRef = '/services'
+weight = 10
+
+[[menus.main]]
+identifier = 'contact'
+name = 'Contact'
+pageRef = '/contact'
+weight = 30
+{{< /code-toggle >}}
+
+To sort the entries by `weight`, then by `name`, then by `identifier`:
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main.ByWeight }}
+ <li><a href="{{ .URL }}">{{ .Name }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Hugo renders this to:
+
+```html
+<ul>
+ <li><a href="/services/">Services</a></li>
+ <li><a href="/about/">About</a></li>
+ <li><a href="/contact">Contact</a></li>
+</ul>
+```
+
+> [!note]
+> In the menu definition above, note that the `identifier` property is only required when two or more menu entries have the same name, or when localizing the name using translation tables.
+
+You can also sort menu entries using the [`sort`] function. For example, to sort by `weight` in descending order:
+
+```go-html-template
+<ul>
+ {{ range sort .Site.Menus.main "Weight" "desc" }}
+ <li><a href="{{ .URL }}">{{ .Name }}</a></li>
+ {{ end }}
+</ul>
+```
+
+When using the sort function with menu entries, specify any of the following keys: `Identifier`, `Name`, `Parent`, `Post`, `Pre`, `Title`, `URL`, or `Weight`.
+
+[`sort`]: /functions/collections/sort/
diff --git a/documents/markdown/hugo-docs/en_methods_menu_Limit.md b/documents/markdown/hugo-docs/en_methods_menu_Limit.md
new file mode 100644
index 0000000..005fef1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_menu_Limit.md
@@ -0,0 +1,50 @@
+---
+title: Limit
+description: Returns the given menu, limited to the first N entries.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: navigation.Menu
+ signatures: [MENU.Limit N]
+---
+
+The `Limit` method returns the given menu, limited to the first N entries.
+
+Consider this menu definition:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+name = 'Services'
+pageRef = '/services'
+weight = 10
+
+[[menus.main]]
+name = 'About'
+pageRef = '/about'
+weight = 20
+
+[[menus.main]]
+name = 'Contact'
+pageRef = '/contact'
+weight = 30
+{{< /code-toggle >}}
+
+To sort the entries by name, and limit to the first 2 entries:
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main.ByName.Limit 2 }}
+ <li><a href="{{ .URL }}">{{ .Name }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Hugo renders this to:
+
+```html
+<ul>
+ <li><a href="/about/">About</a></li>
+ <li><a href="/contact">Contact</a></li>
+</ul>
+```
diff --git a/documents/markdown/hugo-docs/en_methods_menu_Reverse.md b/documents/markdown/hugo-docs/en_methods_menu_Reverse.md
new file mode 100644
index 0000000..1ee31aa
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_menu_Reverse.md
@@ -0,0 +1,51 @@
+---
+title: Reverse
+description: Returns the given menu, reversing the sort order of its entries.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: navigation.Menu
+ signatures: [MENU.Reverse]
+---
+
+The `Reverse` method returns the given menu, reversing the sort order of its entries.
+
+Consider this menu definition:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+name = 'Services'
+pageRef = '/services'
+weight = 10
+
+[[menus.main]]
+name = 'About'
+pageRef = '/about'
+weight = 20
+
+[[menus.main]]
+name = 'Contact'
+pageRef = '/contact'
+weight = 30
+{{< /code-toggle >}}
+
+To sort the entries by name in descending order:
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main.ByName.Reverse }}
+ <li><a href="{{ .URL }}">{{ .Name }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Hugo renders this to:
+
+```html
+<ul>
+ <li><a href="/services/">Services</a></li>
+ <li><a href="/contact">Contact</a></li>
+ <li><a href="/about/">About</a></li>
+</ul>
+```
diff --git a/documents/markdown/hugo-docs/en_methods_menu__index.md b/documents/markdown/hugo-docs/en_methods_menu__index.md
new file mode 100644
index 0000000..41084fd
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_menu__index.md
@@ -0,0 +1,7 @@
+---
+title: Menu methods
+linkTitle: Menu
+description: Use these methods when ranging through menu entries.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_methods_output-format_MediaType.md b/documents/markdown/hugo-docs/en_methods_output-format_MediaType.md
new file mode 100644
index 0000000..9283868
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_output-format_MediaType.md
@@ -0,0 +1,36 @@
+---
+title: MediaType
+description: Returns the media type of the given output format.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: media.Type
+ signatures: [OUTPUTFORMAT.MediaType]
+---
+
+{{% include "/_common/methods/output-formats/to-use-this-method.md" %}}
+
+```go-html-template
+{{ with .Site.Home.OutputFormats.Get "rss" }}
+ {{ with .MediaType }}
+ {{ .Type }} → application/rss+xml
+ {{ .MainType }} → application
+ {{ .SubType }} → rss
+ {{ end }}
+{{ end }}
+```
+
+## Methods
+
+### MainType
+
+(`string`) Returns the main type of the output format's media type.
+
+### SubType
+
+(`string`) Returns the subtype of the current format's media type.
+
+### Type
+
+(`string`) Returns the current format's media type.
diff --git a/documents/markdown/hugo-docs/en_methods_output-format_Name.md b/documents/markdown/hugo-docs/en_methods_output-format_Name.md
new file mode 100644
index 0000000..307f940
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_output-format_Name.md
@@ -0,0 +1,18 @@
+---
+title: Name
+description: Returns the identifier of the given output format.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [OUTPUTFORMAT.Name]
+---
+
+{{% include "/_common/methods/output-formats/to-use-this-method.md" %}}
+
+```go-html-template
+{{ with .Site.Home.OutputFormats.Get "rss" }}
+ {{ .Name }} → rss
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_output-format_Permalink.md b/documents/markdown/hugo-docs/en_methods_output-format_Permalink.md
new file mode 100644
index 0000000..09b98dc
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_output-format_Permalink.md
@@ -0,0 +1,18 @@
+---
+title: Permalink
+description: Returns the permalink of the page generated by the current output format.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [OUTPUTFORMAT.Permalink]
+---
+
+{{% include "/_common/methods/output-formats/to-use-this-method.md" %}}
+
+```go-html-template
+{{ with .Site.Home.OutputFormats.Get "rss" }}
+ {{ .Permalink }} → https://example.org/index.xml
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_output-format_Rel.md b/documents/markdown/hugo-docs/en_methods_output-format_Rel.md
new file mode 100644
index 0000000..4c3db97
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_output-format_Rel.md
@@ -0,0 +1,18 @@
+---
+title: Rel
+description: Returns the rel value of the given output format, either the default or as defined in your project configuration.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [OUTPUTFORMAT.Rel]
+---
+
+{{% include "/_common/methods/output-formats/to-use-this-method.md" %}}
+
+```go-html-template
+{{ with .Site.Home.OutputFormats.Get "rss" }}
+ {{ .Rel }} → alternate
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_output-format_RelPermalink.md b/documents/markdown/hugo-docs/en_methods_output-format_RelPermalink.md
new file mode 100644
index 0000000..434100c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_output-format_RelPermalink.md
@@ -0,0 +1,18 @@
+---
+title: RelPermalink
+description: Returns the relative permalink of the page generated by the current output format.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [OUTPUTFORMAT.RelPermalink]
+---
+
+{{% include "/_common/methods/output-formats/to-use-this-method.md" %}}
+
+```go-html-template
+{{ with .Site.Home.OutputFormats.Get "rss" }}
+ {{ .RelPermalink }} → /index.xml
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_output-format__index.md b/documents/markdown/hugo-docs/en_methods_output-format__index.md
new file mode 100644
index 0000000..dd374de
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_output-format__index.md
@@ -0,0 +1,7 @@
+---
+title: Output format methods
+linkTitle: Output format
+description: Use these methods with an OutputFormat object.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_methods_page_Aliases.md b/documents/markdown/hugo-docs/en_methods_page_Aliases.md
new file mode 100644
index 0000000..f159ba8
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Aliases.md
@@ -0,0 +1,138 @@
+---
+title: Aliases
+description: Returns the aliases defined in front matter as server-relative URLs, resolved according to the current content dimension.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: '[]string'
+ signatures: [PAGE.Aliases]
+---
+
+The `Aliases` method on a `Page` object returns the values defined in the [`aliases`][] front matter field as server-relative URLs, resolved according to the current [content dimension](g).
+
+The `Aliases` method is useful for generating a `_redirects` file, which contains a source URL, a target URL, and an HTTP status code for each alias. You can use a `_redirects` file with hosting services such as Cloudflare, GitLab Pages, and Netlify.
+
+## Redirects
+
+By default, Hugo handles aliases by creating individual HTML files for each alias path. These files contain a `meta http-equiv="refresh"` tag to redirect the visitor via the browser.
+
+While functional, generating a single `_redirects` file allows your hosting provider to handle redirects at the server level. This is more efficient than client-side redirection and improves performance by eliminating the need to load a middle-man HTML page.
+
+> [!tip]
+> You can use the same general approach to generate an `.htaccess` file.
+
+## Example
+
+The following example demonstrates how to configure your site and create a template to automate the generation of a `_redirects` file.
+
+### Content structure
+
+The content structure for this multilingual example looks like this:
+
+```text
+content/
+├── examples/
+│ ├── a.de.md aliases = ['a-old']
+│ ├── a.en.md aliases = ['a-old', 'a-older']
+│ ├── b.de.md aliases = ['b-old']
+│ └── b.en.md aliases = ['b-old', 'b-older']
+└── _index.md
+```
+
+In the example above, the aliases are [page-relative](g). To specify a [site-relative](g) path, preface the entry with a slash (`/`). Both forms are resolved to [server-relative](g) paths.
+
+Page-relative paths can also include directory traversal:
+
+| Path type | File path | Alias | Server-relative path |
+| :--- | :--- | :--- | :--- |
+| page-relative | `content/examples/a.en.md` | `a-old` | `/en/examples/a-old/` |
+| page-relative | `content/examples/a.en.md` | `../a-old` | `/en/a-old/` |
+| site-relative | `content/examples/a.en.md` | `/a-old` | `/en/a-old/` |
+
+### Project configuration
+
+To implement this, you must update your project configuration to:
+
+1. Disable the generation of default HTML redirect files by setting `disableAliases` to `true`.
+1. Define a [media type][] named `text/redirects` to handle the file format.
+1. Define a custom [output format][] named `redirects` to set the filename to `_redirects` and place it at the root of the published site.
+1. Configure the home page [outputs][] to include the `redirects` format in addition to `html`.
+
+{{< code-toggle file=hugo >}}
+baseURL = 'https://example.org/'
+disableAliases = true
+
+defaultContentLanguage = 'en'
+defaultContentLanguageInSubdir = true
+
+[languages.en]
+ locale = 'en-US'
+ direction = 'ltr'
+ name = 'English'
+ weight = 1
+ title = 'My Site in English'
+
+[languages.de]
+ locale = 'de-DE'
+ direction = 'ltr'
+ name = 'Deutsch'
+ weight = 2
+ title = 'My Site in German'
+
+[mediaTypes]
+ [mediaTypes.'text/redirects']
+ delimiter = ''
+
+[outputFormats]
+ [outputFormats.redirects]
+ baseName = '_redirects'
+ isPlainText = true
+ mediaType = 'text/redirects'
+ root = true
+
+[outputs]
+ home = ['html', 'redirects']
+{{< /code-toggle >}}
+
+### Template implementation
+
+Next, create a home page template specifically for the `redirects` output format. The following template iterates through every page in every language and extracts its aliases.
+
+To ensure the resulting `_redirects` file is valid, the template uses the [`strings.FindRE`][] function to check for whitespace such as tabs or newlines within the alias string. If whitespace is detected, Hugo will throw an error and fail the build to prevent generating an invalid file.
+
+```go-html-template {file="layouts/home.redirects" copy=true}
+{{- if site.IsDefault -}}
+ {{- range hugo.Sites -}}
+ {{- range $p := .Pages -}}
+ {{- range .Aliases -}}
+ {{- if findRE `\s` . -}}
+ {{- errorf "One of the front matter aliases in %q contains whitespace" $p.String -}}
+ {{- end -}}
+ {{- printf "%s %s 301\n" . $p.RelPermalink -}}
+ {{- end -}}
+ {{- end -}}
+ {{- end -}}
+{{- end -}}
+```
+
+### Generated output
+
+Once Hugo processes the template, it produces a clean list of redirect rules. Each line follows the required format: the source URL, the destination URL, and the HTTP status code.
+
+The resulting `_redirects` file looks like this:
+
+```text
+/de/examples/a-old /de/examples/a/ 301
+/de/examples/b-old /de/examples/b/ 301
+/en/examples/b-old /en/examples/b/ 301
+/en/examples/b-older /en/examples/b/ 301
+/en/examples/a-old /en/examples/a/ 301
+/en/examples/a-older /en/examples/a/ 301
+```
+
+[`aliases`]: /content-management/front-matter/#aliases
+[`strings.FindRE`]: /functions/strings/findre/
+[media type]: /configuration/media-types/
+[output format]: /configuration/output-formats/
+[outputs]: /configuration/outputs/
diff --git a/documents/markdown/hugo-docs/en_methods_page_AllTranslations.md b/documents/markdown/hugo-docs/en_methods_page_AllTranslations.md
new file mode 100644
index 0000000..e34c8b7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_AllTranslations.md
@@ -0,0 +1,88 @@
+---
+title: AllTranslations
+description: Returns all translations of the given page, including the current language, sorted by language weight then language name.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGE.AllTranslations]
+---
+
+With this project configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'en'
+
+[languages.en]
+contentDir = 'content/en'
+label = 'English'
+locale = 'en-US'
+weight = 1
+
+[languages.de]
+contentDir = 'content/de'
+label = 'Deutsch'
+locale = 'de-DE'
+weight = 2
+
+[languages.fr]
+contentDir = 'content/fr'
+label = 'Français'
+locale = 'fr-FR'
+weight = 3
+{{< /code-toggle >}}
+
+And this content:
+
+```text
+content/
+├── de/
+│ ├── books/
+│ │ ├── book-1.md
+│ │ └── book-2.md
+│ └── _index.md
+├── en/
+│ ├── books/
+│ │ ├── book-1.md
+│ │ └── book-2.md
+│ └── _index.md
+├── fr/
+│ ├── books/
+│ │ └── book-1.md
+│ └── _index.md
+└── _index.md
+```
+
+And this template:
+
+```go-html-template
+{{ with .AllTranslations }}
+ <ul>
+ {{ range . }}
+ <li>
+ <a href="{{ .RelPermalink }}" hreflang="{{ .Language.Locale }}">{{ .LinkTitle }} ({{ or .Language.Label .Language.Name }})</a>
+ </li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+Hugo will render this list on the "Book 1" page of each site:
+
+```html
+<ul>
+ <li><a href="/books/book-1/" hreflang="en-US">Book 1 (English)</a></li>
+ <li><a href="/de/books/book-1/" hreflang="de-DE">Book 1 (Deutsch)</a></li>
+ <li><a href="/fr/books/book-1/" hreflang="fr-FR">Book 1 (Français)</a></li>
+</ul>
+```
+
+On the "Book 2" page of the English and German sites, Hugo will render this:
+
+```html
+<ul>
+ <li><a href="/books/book-1/" hreflang="en-US">Book 1 (English)</a></li>
+ <li><a href="/de/books/book-1/" hreflang="de-DE">Book 1 (Deutsch)</a></li>
+</ul>
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_AlternativeOutputFormats.md b/documents/markdown/hugo-docs/en_methods_page_AlternativeOutputFormats.md
new file mode 100644
index 0000000..72ef9f5
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_AlternativeOutputFormats.md
@@ -0,0 +1,29 @@
+---
+title: AlternativeOutputFormats
+description: Returns a slice of OutputFormat objects, excluding the current output format, each representing one of the output formats enabled for the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.OutputFormats
+ signatures: [PAGE.AlternativeOutputFormats]
+---
+
+{{% glossary-term "output format" %}}
+
+The `AlternativeOutputFormats` method on a `Page` object returns a slice of `OutputFormat` objects, excluding the current output format, each representing one of the output formats enabled for the given page. See [details](/configuration/output-formats/).
+
+For example, to generate a `link` element for each of the alternative output formats:
+
+```go-html-template
+{{ range .AlternativeOutputFormats }}
+ {{ printf "<link rel=%q type=%q href=%q>" .Rel .MediaType.Type .Permalink | safeHTML }}
+{{ end }}
+```
+
+Hugo renders this to something like:
+
+```html
+<link rel="alternate" type="application/rss+xml" href="https://example.org/index.xml">
+<link rel="alternate" type="application/json" href="https://example.org/index.json">
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_Ancestors.md b/documents/markdown/hugo-docs/en_methods_page_Ancestors.md
new file mode 100644
index 0000000..d8275cf
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Ancestors.md
@@ -0,0 +1,76 @@
+---
+title: Ancestors
+description: Returns a collection of Page objects, one for each ancestor section of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGE.Ancestors]
+---
+
+With this content structure:
+
+```text
+content/
+├── auctions/
+│ ├── 2023-11/
+│ │ ├── _index.md <-- front matter: weight = 202311
+│ │ ├── auction-1.md
+│ │ └── auction-2.md
+│ ├── 2023-12/
+│ │ ├── _index.md <-- front matter: weight = 202312
+│ │ ├── auction-3.md
+│ │ └── auction-4.md
+│ ├── _index.md <-- front matter: weight = 30
+│ ├── bidding.md
+│ └── payment.md
+├── books/
+│ ├── _index.md <-- front matter: weight = 10
+│ ├── book-1.md
+│ └── book-2.md
+├── films/
+│ ├── _index.md <-- front matter: weight = 20
+│ ├── film-1.md
+│ └── film-2.md
+└── _index.md
+```
+
+And this template:
+
+```go-html-template
+{{ range .Ancestors }}
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+{{ end }}
+```
+
+On the November 2023 auctions page, Hugo renders:
+
+```html
+<a href="/auctions/2023-11/">Auctions in November 2023</a>
+<a href="/auctions/">Auctions</a>
+<a href="/">Home</a>
+```
+
+In the example above, notice that Hugo orders the ancestors from closest to furthest. This makes breadcrumb navigation simple:
+
+```go-html-template
+<nav aria-label="breadcrumb" class="breadcrumb">
+ <ol>
+ {{ range .Ancestors.Reverse }}
+ <li>
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+ </li>
+ {{ end }}
+ <li class="active">
+ <a aria-current="page" href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+ </li>
+ </ol>
+</nav>
+```
+
+With some CSS, the code above renders something like this, where each breadcrumb links to its page:
+
+```text
+Home > Auctions > Auctions in November 2023 > Auction 1
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_BundleType.md b/documents/markdown/hugo-docs/en_methods_page_BundleType.md
new file mode 100644
index 0000000..e919511
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_BundleType.md
@@ -0,0 +1,33 @@
+---
+title: BundleType
+description: Returns the bundle type of the given page, or an empty string if the page is not a page bundle.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [PAGE.BundleType]
+---
+
+A page bundle is a directory that encapsulates both content and associated [resources](g). There are two types of page bundles: [leaf bundles](g) and [branch bundles](g). See [details](/content-management/page-bundles/).
+
+The `BundleType` method on a `Page` object returns `branch` for branch bundles, `leaf` for leaf bundles, and an empty string if the page is not a page bundle.
+
+```text
+content/
+├── films/
+│ ├── film-1/
+│ │ ├── a.jpg
+│ │ └── index.md <-- leaf bundle
+│ ├── _index.md <-- branch bundle
+│ ├── b.jpg
+│ ├── film-2.md
+│ └── film-3.md
+└── _index.md <-- branch bundle
+```
+
+To get the value within a template:
+
+```go-html-template
+{{ .BundleType }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_CodeOwners.md b/documents/markdown/hugo-docs/en_methods_page_CodeOwners.md
new file mode 100644
index 0000000..00afa75
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_CodeOwners.md
@@ -0,0 +1,65 @@
+---
+title: CodeOwners
+description: Returns of slice of code owners for the given page, derived from the CODEOWNERS file in the root of the project directory.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: '[]string'
+ signatures: [PAGE.CodeOwners]
+---
+
+GitHub and GitLab support CODEOWNERS files. This file specifies the users responsible for developing and maintaining software and documentation. This definition can apply to the entire repository, specific directories, or to individual files. To learn more:
+
+- [GitHub CODEOWNERS documentation]
+- [GitLab CODEOWNERS documentation]
+
+Use the `CodeOwners` method on a `Page` object to determine the code owners for the given page.
+
+[GitHub CODEOWNERS documentation]: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+[GitLab CODEOWNERS documentation]: https://docs.gitlab.com/ee/user/project/code_owners.html
+
+To use the `CodeOwners` method you must enable access to your local Git repository:
+
+{{< code-toggle file=hugo >}}
+enableGitInfo = true
+{{< /code-toggle >}}
+
+Consider this project structure:
+
+```text
+my-project/
+├── content/
+│ ├── books/
+│ │ └── les-miserables.md
+│ └── films/
+│ └── the-hunchback-of-notre-dame.md
+└── CODEOWNERS
+```
+
+And this CODEOWNERS file:
+
+```text
+* @jdoe
+/content/books/ @tjones
+/content/films/ @mrichards @rsmith
+```
+
+The table below shows the slice of code owners returned for each file:
+
+Path|Code owners
+:--|:--
+`books/les-miserables.md`|`[@tjones]`
+`films/the-hunchback-of-notre-dame.md`|`[@mrichards @rsmith]`
+
+Render the code owners for each content page:
+
+```go-html-template
+{{ range .CodeOwners }}
+ {{ . }}
+{{ end }}
+```
+
+Combine this method with [`resources.GetRemote`] to retrieve names and avatars from your Git provider by querying their API.
+
+[`resources.GetRemote`]: /functions/resources/getremote/
diff --git a/documents/markdown/hugo-docs/en_methods_page_Content.md b/documents/markdown/hugo-docs/en_methods_page_Content.md
new file mode 100644
index 0000000..21348eb
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Content.md
@@ -0,0 +1,16 @@
+---
+title: Content
+description: Returns the rendered content of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: template.HTML
+ signatures: [PAGE.Content]
+---
+
+The `Content` method on a `Page` object renders Markdown and shortcodes to HTML.
+
+```go-html-template
+{{ .Content }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_ContentWithoutSummary.md b/documents/markdown/hugo-docs/en_methods_page_ContentWithoutSummary.md
new file mode 100644
index 0000000..4923b11
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_ContentWithoutSummary.md
@@ -0,0 +1,22 @@
+---
+title: ContentWithoutSummary
+description: Returns the rendered content of the given page, excluding the content summary.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: template.HTML
+ signatures: [PAGE.ContentWithoutSummary]
+---
+
+{{< new-in 0.134.0 />}}
+
+Applicable when using manual or automatic [content summaries], the `ContentWithoutSummary` method on a `Page` object renders Markdown and shortcodes to HTML, excluding the content summary from the result.
+
+[content summaries]: /content-management/summaries/#manual-summary
+
+```go-html-template
+{{ .ContentWithoutSummary }}
+```
+
+The `ContentWithoutSummary` method returns the same as `Content` if you define the content summary in front matter.
diff --git a/documents/markdown/hugo-docs/en_methods_page_CurrentSection.md b/documents/markdown/hugo-docs/en_methods_page_CurrentSection.md
new file mode 100644
index 0000000..93457f1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_CurrentSection.md
@@ -0,0 +1,48 @@
+---
+title: CurrentSection
+description: Returns the Page object of the section in which the given page resides.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Page
+ signatures: [PAGE.CurrentSection]
+---
+
+{{% glossary-term section %}}
+
+> [!note]
+> The current section of a [section page](g), [taxonomy page](g), [term page](g), or the home page, is itself.
+
+Consider this content structure:
+
+```text
+content/
+├── auctions/
+│ ├── 2023-11/
+│ │ ├── _index.md <-- current section: 2023-11
+│ │ ├── auction-1.md
+│ │ └── auction-2.md <-- current section: 2023-11
+│ ├── 2023-12/
+│ │ ├── _index.md
+│ │ ├── auction-3.md
+│ │ └── auction-4.md
+│ ├── _index.md <-- current section: auctions
+│ ├── bidding.md
+│ └── payment.md <-- current section: auctions
+├── books/
+│ ├── _index.md <-- current section: books
+│ ├── book-1.md
+│ └── book-2.md <-- current section: books
+├── films/
+│ ├── _index.md <-- current section: films
+│ ├── film-1.md
+│ └── film-2.md <-- current section: films
+└── _index.md <-- current section: home
+```
+
+To create a link to the current section page:
+
+```go-html-template
+<a href="{{ .CurrentSection.RelPermalink }}">{{ .CurrentSection.LinkTitle }}</a>
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_Data.md b/documents/markdown/hugo-docs/en_methods_page_Data.md
new file mode 100644
index 0000000..3d4433a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Data.md
@@ -0,0 +1,101 @@
+---
+title: Data
+description: Returns a unique data object for each page kind.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Data
+ signatures: [PAGE.Data]
+---
+
+The `Data` method on a `Page` object returns a unique data object for each [page kind](g).
+
+> [!note]
+> The `Data` method is only useful within [taxonomy](g) and [term](g) templates.
+>
+> Themes that are not actively maintained may still use `.Data.Pages` in their templates. Although that syntax remains functional, use one of these methods instead: [`Pages`], [`RegularPages`], or [`RegularPagesRecursive`]
+
+The examples that follow are based on this project configuration:
+
+{{< code-toggle file=hugo >}}
+[taxonomies]
+genre = 'genres'
+author = 'authors'
+{{< /code-toggle >}}
+
+And this content structure:
+
+```text
+content/
+├── books/
+│ ├── and-then-there-were-none.md --> genres: suspense
+│ ├── death-on-the-nile.md --> genres: suspense
+│ └── jamaica-inn.md --> genres: suspense, romance
+│ └── pride-and-prejudice.md --> genres: romance
+└── _index.md
+```
+
+## In a taxonomy template
+
+Use these methods on the `Data` object within a _taxonomy_ template.
+
+Singular
+: (`string`) Returns the singular name of the taxonomy.
+
+```go-html-template
+{{ .Data.Singular }} → genre
+```
+
+Plural
+: (`string`) Returns the plural name of the taxonomy.
+
+```go-html-template
+{{ .Data.Plural }} → genres
+```
+
+Terms
+: (`page.Taxonomy`) Returns the `Taxonomy` object, consisting of a map of terms and the [weighted pages](g) associated with each term.
+
+```go-html-template
+{{ $taxonomyObject := .Data.Terms }}
+```
+
+> [!note]
+> Once you have captured the `Taxonomy` object, use any of the [taxonomy methods] to sort, count, or capture a subset of its weighted pages.
+
+Learn more about [taxonomy templates].
+
+## In a term template
+
+Use these methods on the `Data` object within a _term_ template.
+
+Singular
+: (`string`) Returns the singular name of the taxonomy.
+
+```go-html-template
+{{ .Data.Singular }} → genre
+```
+
+Plural
+: (`string`) Returns the plural name of the taxonomy.
+
+```go-html-template
+{{ .Data.Plural }} → genres
+```
+
+Term
+: (`string`) Returns the name of the term.
+
+```go-html-template
+{{ .Data.Term }} → suspense
+```
+
+Learn more about [term templates].
+
+[`Pages`]: /methods/page/pages/
+[`RegularPages`]: /methods/page/regularpages/
+[`RegularPagesRecursive`]: /methods/page/regularpagesrecursive/
+[taxonomy methods]: /methods/taxonomy/
+[taxonomy templates]: /templates/types/#taxonomy
+[term templates]: /templates/types/#term
diff --git a/documents/markdown/hugo-docs/en_methods_page_Date.md b/documents/markdown/hugo-docs/en_methods_page_Date.md
new file mode 100644
index 0000000..ffddcf0
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Date.md
@@ -0,0 +1,33 @@
+---
+title: Date
+description: Returns the date of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: time.Time
+ signatures: [PAGE.Date]
+---
+
+Set the date in front matter:
+
+{{< code-toggle file=content/news/article-1.md fm=true >}}
+title = 'Article 1'
+date = 2023-10-19T00:40:04-07:00
+{{< /code-toggle >}}
+
+> [!note]
+> The date field in front matter is often considered to be the creation date, You can change its meaning, and its effect on your project, in your project configuration. See [details].
+
+The date is a [time.Time] value. Format and localize the value with the [`time.Format`] function, or use it with any of the [time methods].
+
+```go-html-template
+{{ .Date | time.Format ":date_medium" }} → Oct 19, 2023
+```
+
+In the example above we explicitly set the date in front matter. With Hugo's default configuration, the `Date` method returns the front matter value. This behavior is configurable, allowing you to set fallback values if the date is not defined in front matter. See [details].
+
+[`time.Format`]: /functions/time/format/
+[details]: /configuration/front-matter/#dates
+[time methods]: /methods/time/
+[time.Time]: https://pkg.go.dev/time#Time
diff --git a/documents/markdown/hugo-docs/en_methods_page_Description.md b/documents/markdown/hugo-docs/en_methods_page_Description.md
new file mode 100644
index 0000000..7a609bb
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Description.md
@@ -0,0 +1,27 @@
+---
+title: Description
+description: Returns the description of the given page as defined in front matter.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [PAGE.Description]
+---
+
+Conceptually different from a [content summary], a page description is typically used in metadata about the page.
+
+{{< code-toggle file=content/recipes/sushi.md fm=true >}}
+title = 'How to make spicy tuna hand rolls'
+description = 'Instructions for making spicy tuna hand rolls.'
+{{< /code-toggle >}}
+
+```go-html-template {file="layouts/baseof.html"}
+<head>
+ ...
+ <meta name="description" content="{{ .Description }}">
+ ...
+</head>
+```
+
+[content summary]: /content-management/summaries/
diff --git a/documents/markdown/hugo-docs/en_methods_page_Draft.md b/documents/markdown/hugo-docs/en_methods_page_Draft.md
new file mode 100644
index 0000000..d814d85
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Draft.md
@@ -0,0 +1,21 @@
+---
+title: Draft
+description: Reports whether the given page is a draft as defined in front matter.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [PAGE.Draft]
+---
+
+By default, Hugo does not publish draft pages when you build your project. To include draft pages when you build your project, use the `--buildDrafts` command line flag.
+
+{{< code-toggle file=content/posts/post-1.md fm=true >}}
+title = 'Post 1'
+draft = true
+{{< /code-toggle >}}
+
+```go-html-template
+{{ .Draft }} → true
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_Eq.md b/documents/markdown/hugo-docs/en_methods_page_Eq.md
new file mode 100644
index 0000000..0cfe1f1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Eq.md
@@ -0,0 +1,21 @@
+---
+title: Eq
+description: Reports whether two Page objects are equal.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [PAGE1.Eq PAGE2]
+---
+
+In this contrived example we list all pages in the current section except for the current page.
+
+```go-html-template {file="layouts/page.html"}
+{{ $currentPage := . }}
+{{ range .CurrentSection.Pages }}
+ {{ if not (.Eq $currentPage) }}
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+ {{ end }}
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_ExpiryDate.md b/documents/markdown/hugo-docs/en_methods_page_ExpiryDate.md
new file mode 100644
index 0000000..67e6b30
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_ExpiryDate.md
@@ -0,0 +1,32 @@
+---
+title: ExpiryDate
+description: Returns the expiry date of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: time.Time
+ signatures: [PAGE.ExpiryDate]
+---
+
+By default, Hugo excludes expired pages when building your project. To include expired pages, use the `--buildExpired` command line flag.
+
+Set the expiry date in front matter:
+
+{{< code-toggle file=content/news/article-1.md fm=true >}}
+title = 'Article 1'
+expiryDate = 2024-10-19T00:32:13-07:00
+{{< /code-toggle >}}
+
+The expiry date is a [time.Time] value. Format and localize the value with the [`time.Format`] function, or use it with any of the [time methods].
+
+```go-html-template
+{{ .ExpiryDate | time.Format ":date_medium" }} → Oct 19, 2024
+```
+
+In the example above we explicitly set the expiry date in front matter. With Hugo's default configuration, the `ExpiryDate` method returns the front matter value. This behavior is configurable, allowing you to set fallback values if the expiry date is not defined in front matter. See [details].
+
+[`time.Format`]: /functions/time/format/
+[details]: /configuration/front-matter/#dates
+[time methods]: /methods/time/
+[time.Time]: https://pkg.go.dev/time#Time
diff --git a/documents/markdown/hugo-docs/en_methods_page_File.md b/documents/markdown/hugo-docs/en_methods_page_File.md
new file mode 100644
index 0000000..0bf2fde
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_File.md
@@ -0,0 +1,192 @@
+---
+title: File
+description: For pages backed by a file, returns file information for the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: hugolib.fileInfo
+ signatures: [PAGE.File]
+---
+
+By default, not all pages are backed by a file, including top-level [section pages](g), [taxonomy pages](g), and [term pages](g). By definition, you cannot retrieve file information when the file does not exist.
+
+To back one of the pages above with a file, create an `_index.md` file in the corresponding directory. For example:
+
+```text
+content/
+└── books/
+ ├── _index.md <-- the top-slevel section page
+ ├── book-1.md
+ └── book-2.md
+```
+
+> [!note]
+> Code defensively by verifying file existence as shown in the examples below.
+
+## Methods
+
+> [!note]
+> The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend on the operating system.
+
+### BaseFileName
+
+(`string`) The file name, excluding the extension.
+
+```go-html-template
+{{ with .File }}
+ {{ .BaseFileName }}
+{{ end }}
+```
+
+### ContentBaseName
+
+(`string`) If the page is a branch or leaf bundle, the name of the containing directory, else the `TranslationBaseName`.
+
+```go-html-template
+{{ with .File }}
+ {{ .ContentBaseName }}
+{{ end }}
+```
+
+### Dir
+
+(`string`) The file path, excluding the file name, relative to the `content` directory.
+
+```go-html-template
+{{ with .File }}
+ {{ .Dir }}
+{{ end }}
+```
+
+### Ext
+
+(`string`) The file extension.
+
+```go-html-template
+{{ with .File }}
+ {{ .Ext }}
+{{ end }}
+```
+
+### Filename
+
+(`string`) The absolute file path.
+
+```go-html-template
+{{ with .File }}
+ {{ .Filename }}
+{{ end }}
+```
+
+### IsContentAdapter
+
+(`bool`) Reports whether the file is a [content adapter].
+
+```go-html-template
+{{ with .File }}
+ {{ .IsContentAdapter }}
+{{ end }}
+```
+
+### LogicalName
+
+(`string`) The file name.
+
+```go-html-template
+{{ with .File }}
+ {{ .LogicalName }}
+{{ end }}
+```
+
+### Path
+
+(`string`) The file path, relative to the `content` directory.
+
+```go-html-template
+{{ with .File }}
+ {{ .Path }}
+{{ end }}
+```
+
+### Section
+
+(`string`) The name of the top-level section in which the file resides.
+
+```go-html-template
+{{ with .File }}
+ {{ .Section }}
+{{ end }}
+```
+
+### TranslationBaseName
+
+(`string`) The file name, excluding the extension and language identifier.
+
+```go-html-template
+{{ with .File }}
+ {{ .TranslationBaseName }}
+{{ end }}
+```
+
+### UniqueID
+
+(`string`) The MD5 hash of `.File.Path`.
+
+```go-html-template
+{{ with .File }}
+ {{ .UniqueID }}
+{{ end }}
+```
+
+## Examples
+
+Consider this content structure in a multilingual project:
+
+```text
+content/
+├── news/
+│ ├── b/
+│ │ ├── index.de.md <-- leaf bundle
+│ │ └── index.en.md <-- leaf bundle
+│ ├── a.de.md <-- regular content
+│ ├── a.en.md <-- regular content
+│ ├── _index.de.md <-- branch bundle
+│ └── _index.en.md <-- branch bundle
+├── _index.de.md
+└── _index.en.md
+```
+
+With the English language site:
+
+ |regular content|leaf bundle|branch bundle
+:--|:--|:--|:--
+BaseFileName|a.en|index.en|_index.en
+ContentBaseName|a|b|news
+Dir|news/|news/b/|news/
+Ext|md|md|md
+Filename|/home/user/...|/home/user/...|/home/user/...
+IsContentAdapter|false|false|false
+LogicalName|a.en.md|index.en.md|_index.en.md
+Path|news/a.en.md|news/b/index.en.md|news/_index.en.md
+Section|news|news|news
+TranslationBaseName|a|index|_index
+UniqueID|15be14b...|186868f...|7d9159d...
+
+## Defensive coding
+
+Some of the pages on a site may not be backed by a file. For example:
+
+- Top-level section pages
+- Taxonomy pages
+- Term pages
+
+Without a backing file, Hugo will throw an error if you attempt to access a `.File` property. To code defensively, first check for file existence:
+
+```go-html-template
+{{ with .File }}
+ {{ .ContentBaseName }}
+{{ end }}
+```
+
+[content adapter]: /content-management/content-adapters/
diff --git a/documents/markdown/hugo-docs/en_methods_page_FirstSection.md b/documents/markdown/hugo-docs/en_methods_page_FirstSection.md
new file mode 100644
index 0000000..73ddd2d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_FirstSection.md
@@ -0,0 +1,48 @@
+---
+title: FirstSection
+description: Returns the Page object of the top-level section of which the given page is a descendant.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Page
+ signatures: [PAGE.FirstSection]
+---
+
+{{% glossary-term section %}}
+
+> [!note]
+> When called on the home page, the `FirstSection` method returns the `Page` object of the home page itself.
+
+Consider this content structure:
+
+```text
+content/
+├── auctions/
+│ ├── 2023-11/
+│ │ ├── _index.md <-- first section: auctions
+│ │ ├── auction-1.md
+│ │ └── auction-2.md <-- first section: auctions
+│ ├── 2023-12/
+│ │ ├── _index.md
+│ │ ├── auction-3.md
+│ │ └── auction-4.md
+│ ├── _index.md <-- first section: auctions
+│ ├── bidding.md
+│ └── payment.md <-- first section: auctions
+├── books/
+│ ├── _index.md <-- first section: books
+│ ├── book-1.md
+│ └── book-2.md <-- first section: books
+├── films/
+│ ├── _index.md <-- first section: films
+│ ├── film-1.md
+│ └── film-2.md <-- first section: films
+└── _index.md <-- first section: home
+```
+
+To link to the top-level section of which the current page is a descendant:
+
+```go-html-template
+<a href="{{ .FirstSection.RelPermalink }}">{{ .FirstSection.LinkTitle }}</a>
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_Fragments.md b/documents/markdown/hugo-docs/en_methods_page_Fragments.md
new file mode 100644
index 0000000..9df47f3
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Fragments.md
@@ -0,0 +1,109 @@
+---
+title: Fragments
+description: Returns a data structure of the fragments in the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: tableofcontents.Fragments
+ signatures: [PAGE.Fragments]
+---
+
+In a URL, whether absolute or relative, the [fragment](g) links to an `id` attribute of an HTML element on the page.
+
+```text
+/articles/article-1#section-2
+------------------- ---------
+ path fragment
+```
+
+Hugo assigns an `id` attribute to each Markdown [ATX] and [setext] heading within the page content. You can override the `id` with a [Markdown attribute](g) as needed. This creates the relationship between an entry in the [table of contents] (TOC) and a heading on the page.
+
+Use the `Fragments` method on a `Page` object to create a table of contents with the `Fragments.ToHTML` method, or by [walking](g) the `Fragments.Map` data structure.
+
+## Methods
+
+### Headings
+
+(`slice`) A slice of maps of all headings on the page, with first-level keys for each heading. Each map contains the following keys: `ID`, `Level`, `Title` and `Headings`. To inspect the data structure:
+
+```go-html-template
+<pre>{{ debug.Dump .Fragments.Headings }}</pre>
+```
+
+### HeadingsMap
+
+(`map`) A nested map of all headings on the page. Each map contains the following keys: `ID`, `Level`, `Title` and `Headings`. To inspect the data structure:
+
+```go-html-template
+<pre>{{ debug.Dump .Fragments.HeadingsMap }}</pre>
+```
+
+### Identifiers
+
+(`slice`) A slice containing the `id` attribute of each heading on the page. If so configured, will also contain the `id` attribute of each description term (i.e., `dt` element) on the page.
+
+See [configure Markup](/configuration/markup/#parserautodefinitiontermid).
+
+To inspect the data structure:
+
+```go-html-template
+<pre>{{ debug.Dump .Fragments.Identifiers }}</pre>
+```
+
+### Identifiers.Contains ID
+
+(`bool`) Reports whether one or more headings on the page has the given `id` attribute, useful for validating fragments within a link [render hook](g).
+
+```go-html-template
+{{ .Fragments.Identifiers.Contains "section-2" }} → true
+```
+
+### Identifiers.Count ID
+
+(`int`) The number of headings on a page with the given `id` attribute, useful for detecting duplicates.
+
+```go-html-template
+{{ .Fragments.Identifiers.Count "section-2" }} → 1
+```
+
+### ToHTML
+
+(`template.HTML`) Returns a TOC as a nested list, either ordered or unordered, identical to the HTML returned by the [`TableOfContents`] method. This method take three arguments: the start level (`int`), the end level (`int`), and a boolean (`true` to return an ordered list, `false` to return an unordered list).
+
+Use this method when you want to control the start level, end level, or list type independently from the table of contents settings in your project configuration.
+
+```go-html-template
+{{ $startLevel := 2 }}
+{{ $endLevel := 3 }}
+{{ $ordered := true }}
+{{ .Fragments.ToHTML $startLevel $endLevel $ordered }}
+```
+
+Hugo renders this to:
+
+```html
+<nav id="TableOfContents">
+ <ol>
+ <li><a href="#section-1">Section 1</a>
+ <ol>
+ <li><a href="#section-11">Section 1.1</a></li>
+ <li><a href="#section-12">Section 1.2</a></li>
+ </ol>
+ </li>
+ <li><a href="#section-2">Section 2</a></li>
+ </ol>
+</nav>
+```
+
+> [!note]
+> It is safe to use the `Fragments` methods within a render hook, even for the current page.
+>
+> When using the `Fragments` methods within a shortcode, call the shortcode using [standard notation]. If you use [Markdown notation] the rendered shortcode is included in the creation of the fragments map, resulting in a circular loop.
+
+[`TableOfContents`]: /methods/page/tableofcontents/
+[ATX]: https://spec.commonmark.org/current/#atx-headings
+[Markdown notation]: /content-management/shortcodes/#notation
+[setext]: https://spec.commonmark.org/current/#setext-headings
+[standard notation]: /content-management/shortcodes/#notation
+[table of contents]: /methods/page/tableofcontents/
diff --git a/documents/markdown/hugo-docs/en_methods_page_FuzzyWordCount.md b/documents/markdown/hugo-docs/en_methods_page_FuzzyWordCount.md
new file mode 100644
index 0000000..815a074
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_FuzzyWordCount.md
@@ -0,0 +1,18 @@
+---
+title: FuzzyWordCount
+description: Returns the number of words in the content of the given page, rounded up to the nearest multiple of 100.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [PAGE.FuzzyWordCount]
+---
+
+```go-html-template
+{{ .FuzzyWordCount }} → 200
+```
+
+To get the exact word count, use the [`WordCount`] method.
+
+[`WordCount`]: /methods/page/wordcount/
diff --git a/documents/markdown/hugo-docs/en_methods_page_GetPage.md b/documents/markdown/hugo-docs/en_methods_page_GetPage.md
new file mode 100644
index 0000000..7c1e45d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_GetPage.md
@@ -0,0 +1,64 @@
+---
+title: GetPage
+description: Returns a Page object from the given path.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Page
+ signatures: [PAGE.GetPage PATH]
+aliases: [/functions/getpage]
+---
+
+The `GetPage` method is also available on a `Site` object. See [details].
+
+[details]: /methods/site/getpage/
+
+When using the `GetPage` method on the `Page` object, specify a path relative to the current directory or relative to the `content` directory.
+
+If Hugo cannot resolve the path to a page, the method returns nil. If the path is ambiguous, Hugo throws an error and fails the build.
+
+Consider this content structure:
+
+```text
+content/
+├── works/
+│ ├── paintings/
+│ │ ├── _index.md
+│ │ ├── starry-night.md
+│ │ └── the-mona-lisa.md
+│ ├── sculptures/
+│ │ ├── _index.md
+│ │ ├── david.md
+│ │ └── the-thinker.md
+│ └── _index.md
+└── _index.md
+```
+
+The examples below depict the result of rendering `works/paintings/the-mona-lisa.md`:
+
+```go-html-template {file="layouts/works/page.html"}
+{{ with .GetPage "starry-night" }}
+ {{ .Title }} → Starry Night
+{{ end }}
+
+{{ with .GetPage "./starry-night" }}
+ {{ .Title }} → Starry Night
+{{ end }}
+
+{{ with .GetPage "../paintings/starry-night" }}
+ {{ .Title }} → Starry Night
+{{ end }}
+
+{{ with .GetPage "/works/paintings/starry-night" }}
+ {{ .Title }} → Starry Night
+{{ end }}
+
+{{ with .GetPage "../sculptures/david" }}
+ {{ .Title }} → David
+{{ end }}
+
+{{ with .GetPage "/works/sculptures/david" }}
+ {{ .Title }} → David
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_GetTerms.md b/documents/markdown/hugo-docs/en_methods_page_GetTerms.md
new file mode 100644
index 0000000..53b996f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_GetTerms.md
@@ -0,0 +1,41 @@
+---
+title: GetTerms
+description: Returns a collection of term pages for terms defined on the given page in the given taxonomy, ordered according to the sequence in which they appear in front matter.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGE.GetTerms TAXONOMY]
+---
+
+Given this front matter:
+
+{{< code-toggle file=content/books/les-miserables.md fm=true >}}
+title = 'Les Misérables'
+tags = ['historical','classic','fiction']
+{{< /code-toggle >}}
+
+This template code:
+
+```go-html-template
+{{ with .GetTerms "tags" }}
+ <p>Tags</p>
+ <ul>
+ {{ range . }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+Is rendered to:
+
+```html
+<p>Tags</p>
+<ul>
+ <li><a href="/tags/historical/">historical</a></li>
+ <li><a href="/tags/classic/">classic</a></li>
+ <li><a href="/tags/fiction/">fiction</a></li>
+</ul>
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_GitInfo.md b/documents/markdown/hugo-docs/en_methods_page_GitInfo.md
new file mode 100644
index 0000000..8a60f09
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_GitInfo.md
@@ -0,0 +1,194 @@
+---
+title: GitInfo
+description: Provides access to commit metadata for a given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: '*gitmap.GitInfo'
+ signatures: [PAGE.GitInfo]
+---
+
+The `GitInfo` method on a `Page` object provides access to commit metadata from your Git history, such as the author's name, the commit hash, and the commit message.
+
+> [!note]
+> Hugo's Git integration is performant, but may increase build times for large projects.
+
+## Prerequisites
+
+Install Git, create a repository, and commit your project files.
+
+You must also allow Hugo to access your repository by adding this to your project configuration:
+
+{{< code-toggle file=hugo >}}
+enableGitInfo = true
+{{< /code-toggle >}}
+
+> [!note]
+> When you set [`enableGitInfo`][] to `true`, the last modification date for each content page will automatically be the Author Date of the last commit for that file.
+>
+> This is configurable. See [details][].
+
+## Scope
+
+Commit metadata is available for content stored in your local repository and for content provided by [modules](g).
+
+### Local content
+
+Hugo retrieves commit metadata for files tracked within your project's local repository. This includes all content files managed by Git in your main project directory.
+
+### Module content
+
+{{< new-in 0.157.0 />}}
+
+Hugo also retrieves commit metadata for content provided by modules. This allows you to display commit data for remote repositories that are mounted as content directories, such as when aggregating documentation from multiple sources.
+
+## Methods
+
+### AbbreviatedHash
+
+(`string`) Returns the seven-character shortened version of the commit hash.
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ .AbbreviatedHash }} → aab9ec0
+{{ end }}
+```
+
+### AuthorDate
+
+(`time.Time`) Returns the date the author originally created the commit.
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ .AuthorDate.Format "2006-01-02" }} → 2023-10-09
+{{ end }}
+```
+
+### AuthorEmail
+
+(`string`) Returns the author's email address, respecting [gitmailmap][].
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ .AuthorEmail }} → jsmith@example.org
+{{ end }}
+```
+
+### AuthorName
+
+(`string`) Returns the author's name, respecting [gitmailmap][].
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ .AuthorName }} → John Smith
+{{ end }}
+```
+
+### CommitDate
+
+(`time.Time`) Returns the date the commit was applied to the branch.
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ .CommitDate.Format "2006-01-02" }} → 2023-10-09
+{{ end }}
+```
+
+### Hash
+
+(`string`) Returns the full SHA-1 commit hash.
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ .Hash }} → aab9ec0b31ebac916a1468c4c9c305f2bebf78d4
+{{ end }}
+```
+
+### Subject
+
+(`string`) Returns the first line of the commit message (the summary).
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ .Subject }} → Add tutorials
+{{ end }}
+```
+
+### Body
+
+(`string`) Returns the full content of the commit message, excluding the subject line.
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ .Body }} → Two new pages added.
+{{ end }}
+```
+
+### Ancestors
+
+(`gitmap.GitInfos`) Returns a list of previous commits for this specific file, ordered from most recent to oldest.
+
+For example, to list the last 5 commits:
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ range .Ancestors | first 5 }}
+ {{ .CommitDate.Format "2006-01-02" }}: {{ .Subject }}
+ {{ end }}
+{{ end }}
+```
+
+To reverse the order:
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ range .Ancestors.Reverse | first 5 }}
+ {{ .CommitDate.Format "2006-01-02" }}: {{ .Subject }}
+ {{ end }}
+{{ end }}
+```
+
+### Parent
+
+(`*gitmap.GitInfo`) Returns the most recent ancestor commit for the file, if any.
+
+## Last modified date
+
+By default, when `enableGitInfo` is `true`, the `Lastmod` method on a `Page` object returns the Git AuthorDate of the last commit that included the file.
+
+You can change this behavior in your [project configuration][].
+
+## Hosting considerations
+
+On a [CI/CD](g) platform, the step that clones your project repository must perform a deep clone. If the clone is shallow, the Git information for a given file may be inaccurate. It might incorrectly reflect the most recent repository commit, rather than the commit that actually modified the file.
+
+While some providers perform a deep clone by default, others require you to configure the depth yourself.
+
+Hosting service|Default clone depth|Configurable
+:--|:--|:--
+AWS Amplify|Deep|N/A
+Cloudflare|Shallow|Yes [^1]
+DigitalOcean App Platform|Deep|N/A
+GitHub Pages|Shallow|Yes [^2]
+GitLab Pages|Shallow|Yes [^3]
+Netlify|Deep|N/A
+Render|Shallow|Yes [^1]
+Vercel|Shallow|Yes [^1]
+
+[^1]: To perform a deep clone when hosting on Cloudflare, Render, or Vercel, include this code in the build script after the repository has been cloned:
+
+ ```text
+ if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
+ git fetch --unshallow
+ fi
+ ```
+
+[^2]: To perform a deep clone when hosting on GitHub Pages, set `fetch-depth: 0` in the `checkout` step of the GitHub Action. See [example](/host-and-deploy/host-on-github-pages/#step-7).
+
+[^3]: To perform a deep clone when hosting on GitLab Pages, set the `GIT_DEPTH` environment variable to `0` in the workflow file. See [example](/host-and-deploy/host-on-gitlab-pages/#configure-gitlab-cicd).
+
+[`enableGitInfo`]: /configuration/all/#enablegitinfo
+[details]: /configuration/front-matter/#dates
+[gitmailmap]: https://git-scm.com/docs/gitmailmap
+[project configuration]: /configuration/front-matter/
diff --git a/documents/markdown/hugo-docs/en_methods_page_HasMenuCurrent.md b/documents/markdown/hugo-docs/en_methods_page_HasMenuCurrent.md
new file mode 100644
index 0000000..22bcc64
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_HasMenuCurrent.md
@@ -0,0 +1,33 @@
+---
+title: HasMenuCurrent
+description: Reports whether the given Page object matches the Page object associated with one of the child menu entries under the given menu entry in the given menu.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [PAGE.HasMenuCurrent MENU MENUENTRY]
+aliases: [/functions/hasmenucurrent]
+---
+
+If the `Page` object associated with the menu entry is a section, this method also returns `true` for any descendant of that section.
+
+```go-html-template
+{{ $currentPage := . }}
+{{ range site.Menus.main }}
+ {{ if $currentPage.IsMenuCurrent .Menu . }}
+ <a class="active" aria-current="page" href="{{ .URL }}">{{ .Name }}</a>
+ {{ else if $currentPage.HasMenuCurrent .Menu . }}
+ <a class="ancestor" aria-current="true" href="{{ .URL }}">{{ .Name }}</a>
+ {{ else }}
+ <a href="{{ .URL }}">{{ .Name }}</a>
+ {{ end }}
+{{ end }}
+```
+
+See [menu templates] for a complete example.
+
+> [!note]
+> When using this method you must either define the menu entry in front matter, or specify a `pageRef` property when defining the menu entry in your project configuration.
+
+[menu templates]: /templates/menu/#example
diff --git a/documents/markdown/hugo-docs/en_methods_page_HasShortcode.md b/documents/markdown/hugo-docs/en_methods_page_HasShortcode.md
new file mode 100644
index 0000000..2e585da
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_HasShortcode.md
@@ -0,0 +1,50 @@
+---
+title: HasShortcode
+description: Reports whether the given shortcode is called by the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [PAGE.HasShortcode NAME]
+---
+
+By example, let's use [Plotly] to render a chart:
+
+[Plotly]: https://plotly.com/javascript/
+
+```text {file="content/example.md"}
+{{</* plotly */>}}
+{
+ "data": [
+ {
+ "x": ["giraffes", "orangutans", "monkeys"],
+ "y": [20, 14, 23],
+ "type": "bar"
+ }
+ ],
+}
+{{</* /plotly */>}}
+```
+
+The shortcode is simple:
+
+```go-html-template {file="layouts/_shortcodes/plotly.html"}
+{{ $id := printf "plotly-%02d" .Ordinal }}
+<div id="{{ $id }}"></div>
+<script>
+ Plotly.newPlot(document.getElementById({{ $id }}), {{ .Inner | safeJS }});
+</script>
+```
+
+Now we can selectively load the required JavaScript on pages that call the "plotly" shortcode:
+
+```go-html-template {file="layouts/baseof.html"}
+<head>
+ ...
+ {{ if .HasShortcode "plotly" }}
+ <script src="https://cdn.plot.ly/plotly-2.28.0.min.js"></script>
+ {{ end }}
+ ...
+</head>
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_HeadingsFiltered.md b/documents/markdown/hugo-docs/en_methods_page_HeadingsFiltered.md
new file mode 100644
index 0000000..86c989d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_HeadingsFiltered.md
@@ -0,0 +1,16 @@
+---
+title: HeadingsFiltered
+description: Returns a slice of headings for each page related to the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: tableofcontents.Headings
+ signatures: [PAGE.HeadingsFiltered]
+---
+
+Use in conjunction with the [`Related`] method on a [`Pages`] object. See [details].
+
+[`Pages`]: /methods/pages/
+[`Related`]: /methods/pages/related/
+[details]: /content-management/related-content/#index-content-headings
diff --git a/documents/markdown/hugo-docs/en_methods_page_InSection.md b/documents/markdown/hugo-docs/en_methods_page_InSection.md
new file mode 100644
index 0000000..adca82d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_InSection.md
@@ -0,0 +1,91 @@
+---
+title: InSection
+description: Reports whether the given page is in the given section.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [PAGE.InSection SECTION]
+---
+
+{{% glossary-term section %}}
+
+The `InSection` method on a `Page` object reports whether the given page is in the given section. Note that the method returns `true` when comparing a page to a sibling.
+
+With this content structure:
+
+```text
+content/
+├── auctions/
+│ ├── 2023-11/
+│ │ ├── _index.md
+│ │ ├── auction-1.md
+│ │ └── auction-2.md
+│ ├── 2023-12/
+│ │ ├── _index.md
+│ │ ├── auction-3.md
+│ │ └── auction-4.md
+│ ├── _index.md
+│ ├── bidding.md
+│ └── payment.md
+└── _index.md
+```
+
+When rendering the "auction-1" page:
+
+```go-html-template
+{{ with .Site.GetPage "/" }}
+ {{ $.InSection . }} → false
+{{ end }}
+
+{{ with .Site.GetPage "/auctions" }}
+ {{ $.InSection . }} → false
+{{ end }}
+
+{{ with .Site.GetPage "/auctions/2023-11" }}
+ {{ $.InSection . }} → true
+{{ end }}
+
+{{ with .Site.GetPage "/auctions/2023-11/auction-2" }}
+ {{ $.InSection . }} → true
+{{ end }}
+```
+
+In the examples above we are coding defensively using the [`with`] statement, returning nothing if the page does not exist. By adding an [`else`] clause we can do some error reporting:
+
+```go-html-template
+{{ $path := "/auctions/2023-11" }}
+{{ with .Site.GetPage $path }}
+ {{ $.InSection . }} → true
+{{ else }}
+ {{ errorf "Unable to find the section with path %s" $path }}
+{{ end }}
+ ```
+
+## Understanding context
+
+Inside of the `with` block, the [context](g) (the dot) is the section `Page` object, not the `Page` object passed into the template. If we were to use this syntax:
+
+```go-html-template
+{{ with .Site.GetPage "/auctions" }}
+ {{ .InSection . }} → true
+{{ end }}
+```
+
+The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself.
+
+> [!note]
+> Use the `$` to get the context passed into the template.
+
+```go-html-template
+{{ with .Site.GetPage "/auctions" }}
+ {{ $.InSection . }} → true
+{{ end }}
+```
+
+> [!note]
+> Gaining a thorough understanding of context is critical for anyone writing template code.
+
+[`else`]: /functions/go-template/else/
+[`with`]: /functions/go-template/with/
diff --git a/documents/markdown/hugo-docs/en_methods_page_IsAncestor.md b/documents/markdown/hugo-docs/en_methods_page_IsAncestor.md
new file mode 100644
index 0000000..fe1b784
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_IsAncestor.md
@@ -0,0 +1,87 @@
+---
+title: IsAncestor
+description: Reports whether PAGE1 is an ancestor of PAGE2.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [PAGE1.IsAncestor PAGE2]
+---
+
+With this content structure:
+
+```text
+content/
+├── auctions/
+│ ├── 2023-11/
+│ │ ├── _index.md
+│ │ ├── auction-1.md
+│ │ └── auction-2.md
+│ ├── 2023-12/
+│ │ ├── _index.md
+│ │ ├── auction-3.md
+│ │ └── auction-4.md
+│ ├── _index.md
+│ ├── bidding.md
+│ └── payment.md
+└── _index.md
+```
+
+When rendering the "auctions" page:
+
+```go-html-template
+{{ with .Site.GetPage "/" }}
+ {{ $.IsAncestor . }} → false
+{{ end }}
+
+{{ with .Site.GetPage "/auctions" }}
+ {{ $.IsAncestor . }} → false
+{{ end }}
+
+{{ with .Site.GetPage "/auctions/2023-11" }}
+ {{ $.IsAncestor . }} → true
+{{ end }}
+
+{{ with .Site.GetPage "/auctions/2023-11/auction-2" }}
+ {{ $.IsAncestor . }} → true
+{{ end }}
+```
+
+In the examples above we are coding defensively using the [`with`] statement, returning nothing if the page does not exist. By adding an [`else`] clause we can do some error reporting:
+
+```go-html-template
+{{ $path := "/auctions/2023-11" }}
+{{ with .Site.GetPage $path }}
+ {{ $.IsAncestor . }} → true
+{{ else }}
+ {{ errorf "Unable to find the section with path %s" $path }}
+{{ end }}
+ ```
+
+## Understanding context
+
+Inside of the `with` block, the [context](g) (the dot) is the section `Page` object, not the `Page` object passed into the template. If we were to use this syntax:
+
+```go-html-template
+{{ with .Site.GetPage "/auctions" }}
+ {{ .IsAncestor . }} → true
+{{ end }}
+```
+
+The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself.
+
+> [!note]
+> Use the `$` to get the context passed into the template.
+
+```go-html-template
+{{ with .Site.GetPage "/auctions" }}
+ {{ $.IsAncestor . }} → true
+{{ end }}
+```
+
+> [!note]
+> Gaining a thorough understanding of context is critical for anyone writing template code.
+
+[`else`]: /functions/go-template/else/
+[`with`]: /functions/go-template/with/
diff --git a/documents/markdown/hugo-docs/en_methods_page_IsDescendant.md b/documents/markdown/hugo-docs/en_methods_page_IsDescendant.md
new file mode 100644
index 0000000..6ee8d3c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_IsDescendant.md
@@ -0,0 +1,87 @@
+---
+title: IsDescendant
+description: Reports whether PAGE1 is a descendant of PAGE2.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [PAGE1.IsDescendant PAGE2]
+---
+
+With this content structure:
+
+```text
+content/
+├── auctions/
+│ ├── 2023-11/
+│ │ ├── _index.md
+│ │ ├── auction-1.md
+│ │ └── auction-2.md
+│ ├── 2023-12/
+│ │ ├── _index.md
+│ │ ├── auction-3.md
+│ │ └── auction-4.md
+│ ├── _index.md
+│ ├── bidding.md
+│ └── payment.md
+└── _index.md
+```
+
+When rendering the "auctions" page:
+
+```go-html-template
+{{ with .Site.GetPage "/" }}
+ {{ $.IsDescendant . }} → true
+{{ end }}
+
+{{ with .Site.GetPage "/auctions" }}
+ {{ $.IsDescendant . }} → false
+{{ end }}
+
+{{ with .Site.GetPage "/auctions/2023-11" }}
+ {{ $.IsDescendant . }} → false
+{{ end }}
+
+{{ with .Site.GetPage "/auctions/2023-11/auction-2" }}
+ {{ $.IsDescendant . }} → false
+{{ end }}
+```
+
+In the examples above we are coding defensively using the [`with`] statement, returning nothing if the page does not exist. By adding an [`else`] clause we can do some error reporting:
+
+```go-html-template
+{{ $path := "/auctions/2023-11" }}
+{{ with .Site.GetPage $path }}
+ {{ $.IsDescendant . }} → true
+{{ else }}
+ {{ errorf "Unable to find the section with path %s" $path }}
+{{ end }}
+ ```
+
+## Understanding context
+
+Inside of the `with` block, the [context](g) (the dot) is the section `Page` object, not the `Page` object passed into the template. If we were to use this syntax:
+
+```go-html-template
+{{ with .Site.GetPage "/auctions" }}
+ {{ .IsDescendant . }} → true
+{{ end }}
+```
+
+The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself.
+
+> [!note]
+> Use the `$` to get the context passed into the template.
+
+```go-html-template
+{{ with .Site.GetPage "/auctions" }}
+ {{ $.IsDescendant . }} → true
+{{ end }}
+```
+
+> [!note]
+> Gaining a thorough understanding of context is critical for anyone writing template code.
+
+[`else`]: /functions/go-template/else/
+[`with`]: /functions/go-template/with/
diff --git a/documents/markdown/hugo-docs/en_methods_page_IsHome.md b/documents/markdown/hugo-docs/en_methods_page_IsHome.md
new file mode 100644
index 0000000..66d8180
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_IsHome.md
@@ -0,0 +1,26 @@
+---
+title: IsHome
+description: Reports whether the given page is the home page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [PAGE.IsHome]
+---
+
+The `IsHome` method on a `Page` object returns `true` if the [page kind](g) is `home`.
+
+```text
+content/
+├── books/
+│ ├── book-1/
+│ │ └── index.md <-- kind = page
+│ ├── book-2.md <-- kind = page
+│ └── _index.md <-- kind = section
+└── _index.md <-- kind = home
+```
+
+```go-html-template
+{{ .IsHome }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_IsMenuCurrent.md b/documents/markdown/hugo-docs/en_methods_page_IsMenuCurrent.md
new file mode 100644
index 0000000..60b6842
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_IsMenuCurrent.md
@@ -0,0 +1,31 @@
+---
+title: IsMenuCurrent
+description: Reports whether the given Page object matches the Page object associated with the given menu entry in the given menu.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [PAGE.IsMenuCurrent MENU MENUENTRY]
+aliases: [/functions/ismenucurrent]
+---
+
+```go-html-template
+{{ $currentPage := . }}
+{{ range site.Menus.main }}
+ {{ if $currentPage.IsMenuCurrent .Menu . }}
+ <a class="active" aria-current="page" href="{{ .URL }}">{{ .Name }}</a>
+ {{ else if $currentPage.HasMenuCurrent .Menu . }}
+ <a class="ancestor" aria-current="true" href="{{ .URL }}">{{ .Name }}</a>
+ {{ else }}
+ <a href="{{ .URL }}">{{ .Name }}</a>
+ {{ end }}
+{{ end }}
+```
+
+See [menu templates] for a complete example.
+
+> [!note]
+> When using this method you must either define the menu entry in front matter, or specify a `pageRef` property when defining the menu entry in your project configuration.
+
+[menu templates]: /templates/menu/#example
diff --git a/documents/markdown/hugo-docs/en_methods_page_IsNode.md b/documents/markdown/hugo-docs/en_methods_page_IsNode.md
new file mode 100644
index 0000000..24e7c03
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_IsNode.md
@@ -0,0 +1,30 @@
+---
+title: IsNode
+description: Reports whether the given page is a node.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [PAGE.IsNode]
+---
+
+The `IsNode` method on a `Page` object checks if the [page kind](g) is one of the following: `home`, `section`, `taxonomy`, or `term`. If it is, the method returns `true`, indicating the page is a [node](g). Otherwise, if the page kind is page, it returns `false`.
+
+```text
+content/
+├── books/
+│ ├── book-1/
+│ │ └── index.md <-- kind = page IsNode = false
+│ ├── book-2.md <-- kind = page IsNode = false
+│ └── _index.md <-- kind = section IsNode = true
+├── tags
+│ ├── fiction
+│ │ └── _index.md <-- kind = term IsNode = true
+│ └── _index.md <-- kind = taxonomy IsNode = true
+└── _index.md <-- kind = home IsNode = true
+```
+
+```go-html-template
+{{ .IsNode }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_IsPage.md b/documents/markdown/hugo-docs/en_methods_page_IsPage.md
new file mode 100644
index 0000000..910a3a7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_IsPage.md
@@ -0,0 +1,26 @@
+---
+title: IsPage
+description: Reports whether the given page is a regular page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [PAGE.IsPage]
+---
+
+The `IsPage` method on a `Page` object returns `true` if the [page kind](g) is `page`.
+
+```text
+content/
+├── books/
+│ ├── book-1/
+│ │ └── index.md <-- kind = page
+│ ├── book-2.md <-- kind = page
+│ └── _index.md <-- kind = section
+└── _index.md <-- kind = home
+```
+
+```go-html-template
+{{ .IsPage }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_IsSection.md b/documents/markdown/hugo-docs/en_methods_page_IsSection.md
new file mode 100644
index 0000000..7a04fbd
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_IsSection.md
@@ -0,0 +1,26 @@
+---
+title: IsSection
+description: Reports whether the given page is a section page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [PAGE.IsSection]
+---
+
+The `IsSection` method on a `Page` object returns `true` if the [page kind](g) is `section`.
+
+```text
+content/
+├── books/
+│ ├── book-1/
+│ │ └── index.md <-- kind = page
+│ ├── book-2.md <-- kind = page
+│ └── _index.md <-- kind = section
+└── _index.md <-- kind = home
+```
+
+```go-html-template
+{{ .IsSection }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_IsTranslated.md b/documents/markdown/hugo-docs/en_methods_page_IsTranslated.md
new file mode 100644
index 0000000..a9d12b9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_IsTranslated.md
@@ -0,0 +1,56 @@
+---
+title: IsTranslated
+description: Reports whether the given page has one or more translations.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [PAGE.IsTranslated]
+---
+
+With this project configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'en'
+
+[languages.en]
+contentDir = 'content/en'
+label = 'English'
+locale = 'en-US'
+weight = 1
+
+[languages.de]
+contentDir = 'content/de'
+label = 'Deutsch'
+locale = 'de-DE'
+weight = 2
+{{< /code-toggle >}}
+
+And this content:
+
+```text
+content/
+├── de/
+│ ├── books/
+│ │ └── book-1.md
+│ └── _index.md
+├── en/
+│ ├── books/
+│ │ ├── book-1.md
+│ │ └── book-2.md
+│ └── _index.md
+└── _index.md
+```
+
+When rendering `content/en/books/book-1.md`:
+
+```go-html-template
+{{ .IsTranslated }} → true
+```
+
+When rendering `content/en/books/book-2.md`:
+
+```go-html-template
+{{ .IsTranslated }} → false
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_Keywords.md b/documents/markdown/hugo-docs/en_methods_page_Keywords.md
new file mode 100644
index 0000000..7c94098
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Keywords.md
@@ -0,0 +1,46 @@
+---
+title: Keywords
+description: Returns a slice of keywords as defined in front matter.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: '[]string'
+ signatures: [PAGE.Keywords]
+---
+
+By default, Hugo evaluates the keywords when creating collections of [related content].
+
+[related content]: /content-management/related-content/
+
+{{< code-toggle file=content/recipes/sushi.md fm=true >}}
+title = 'How to make spicy tuna hand rolls'
+keywords = ['tuna','sriracha','nori','rice']
+{{< /code-toggle >}}
+
+To list the keywords within a template:
+
+```go-html-template
+{{ range .Keywords }}
+ {{ . }}
+{{ end }}
+```
+
+Or use the [delimit] function:
+
+```go-html-template
+{{ delimit .Keywords ", " ", and " }} → tuna, sriracha, nori, and rice
+```
+
+[delimit]: /functions/collections/delimit/
+
+Keywords are also a useful [taxonomy]:
+
+{{< code-toggle file=hugo >}}
+[taxonomies]
+tag = 'tags'
+keyword = 'keywords'
+category = 'categories'
+{{< /code-toggle >}}
+
+[taxonomy]: /content-management/taxonomies/
diff --git a/documents/markdown/hugo-docs/en_methods_page_Kind.md b/documents/markdown/hugo-docs/en_methods_page_Kind.md
new file mode 100644
index 0000000..a01877e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Kind.md
@@ -0,0 +1,32 @@
+---
+title: Kind
+description: Returns the kind of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [PAGE.Kind]
+---
+
+The [page kind](g) is one of `home`, `page`, `section`, `taxonomy`, or `term`.
+
+```text
+content/
+├── books/
+│ ├── book-1/
+│ │ └── index.md <-- kind = page
+│ ├── book-2.md <-- kind = page
+│ └── _index.md <-- kind = section
+├── tags/
+│ ├── fiction/
+│ │ └── _index.md <-- kind = term
+│ └── _index.md <-- kind = taxonomy
+└── _index.md <-- kind = home
+```
+
+To get the value within a template:
+
+```go-html-template
+{{ .Kind }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_Language.md b/documents/markdown/hugo-docs/en_methods_page_Language.md
new file mode 100644
index 0000000..26a40e5
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Language.md
@@ -0,0 +1,135 @@
+---
+title: Language
+description: Returns the Language object for the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: langs.Language
+ signatures: [PAGE.Language]
+---
+
+The `Language` method on a `Page` object returns the `Language` object for the given page, derived from the language definition in your project configuration.
+
+You can also use the `Language` method on a `Site` object. See [details][].
+
+## Methods
+
+The examples below assume the following language definition.
+
+{{< code-toggle file=hugo >}}
+[languages.de]
+direction = 'ltr'
+label = 'Deutsch'
+locale = 'de-DE'
+weight = 2
+{{< /code-toggle >}}
+
+### Direction
+
+{{< new-in 0.158.0 />}}
+
+(`string`) Returns the [`direction`][] from the language definition.
+
+```go-html-template
+{{ .Language.Direction }} → ltr
+```
+
+### IsDefault
+
+{{< new-in 0.153.0 />}}
+
+(`bool`) Reports whether this is the [default language][].
+
+```go-html-template
+{{ .Language.IsDefault }} → true
+```
+
+### Label
+
+{{< new-in 0.158.0 />}}
+
+(`string`) Returns the [`label`][] from the language definition.
+
+```go-html-template
+{{ .Language.Label }} → Deutsch
+```
+
+### Lang
+
+{{<deprecated-in 0.158.0 />}}
+
+Use [`Name`](#name) instead.
+
+### LanguageCode
+
+{{<deprecated-in 0.158.0 />}}
+
+Use [`Locale`](#locale) instead.
+
+### LanguageDirection
+
+{{<deprecated-in 0.158.0 />}}
+
+Use [`Direction`](#direction) instead.
+
+### LanguageName
+
+{{<deprecated-in 0.158.0 />}}
+
+Use [`Label`](#label) instead.
+
+### Locale
+
+{{< new-in 0.158.0 />}}
+
+(`string`) Returns the [`locale`][] from the language definition, falling back to [`Name`](#name).
+
+```go-html-template
+{{ .Language.Locale }} → de-DE
+```
+
+### Name
+
+{{< new-in 0.153.0 />}}
+
+(`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from the language definition.
+
+```go-html-template
+{{ .Language.Name }} → de
+```
+
+### Weight
+
+{{<deprecated-in 0.158.0 />}}
+
+[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
+[`direction`]: /configuration/languages/#direction
+[`label`]: /configuration/languages/#label
+[`locale`]: /configuration/languages/#locale
+[default language]: /quick-reference/glossary/#default-language
+[details]: /methods/site/language/
+
+## Example
+
+Use the code below to create a language selector, allowing users to navigate between the different translated versions of the current page.
+
+```go-html-template {file="layouts/_partials/language-selector.html" copy=true}
+{{ with .Rotate "language" }}
+ <nav class="language-selector">
+ <ul>
+ {{ range . }}
+ {{ if eq .Language $.Language }}
+ <li class="active">
+ <a aria-current="page" href="{{ .Permalink }}" hreflang="{{ .Language.Locale }}">{{ .Language.Label }}</a>
+ </li>
+ {{ else }}
+ <li>
+ <a href="{{ .Permalink }}" hreflang="{{ .Language.Locale }}">{{ .Language.Label }}</a>
+ </li>
+ {{ end }}
+ {{ end }}
+ </ul>
+ </nav>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_Lastmod.md b/documents/markdown/hugo-docs/en_methods_page_Lastmod.md
new file mode 100644
index 0000000..643eddc
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Lastmod.md
@@ -0,0 +1,36 @@
+---
+title: Lastmod
+description: Returns the last modification date of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: time.Time
+ signatures: [PAGE.Lastmod]
+---
+
+Set the last modification date in front matter:
+
+{{< code-toggle file=content/news/article-1.md fm=true >}}
+title = 'Article 1'
+lastmod = 2023-10-19T00:40:04-07:00
+{{< /code-toggle >}}
+
+The last modification date is a [time.Time] value. Format and localize the value with the [`time.Format`] function, or use it with any of the [time methods].
+
+```go-html-template
+{{ .Lastmod | time.Format ":date_medium" }} → Oct 19, 2023
+```
+
+In the example above we explicitly set the last modification date in front matter. With Hugo's default configuration, the `Lastmod` method returns the front matter value. This behavior is configurable, allowing you to:
+
+- Set the last modification date to the Author Date of the last Git commit for that file. See [`GitInfo`] for details.
+- Set fallback values if the last modification date is not defined in front matter.
+
+Learn more about [date configuration].
+
+[`gitinfo`]: /methods/page/gitinfo/
+[`time.format`]: /functions/time/format/
+[date configuration]: /configuration/front-matter/#dates
+[time methods]: /methods/time/
+[time.time]: https://pkg.go.dev/time#Time
diff --git a/documents/markdown/hugo-docs/en_methods_page_Layout.md b/documents/markdown/hugo-docs/en_methods_page_Layout.md
new file mode 100644
index 0000000..e038f38
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Layout.md
@@ -0,0 +1,40 @@
+---
+title: Layout
+description: Returns the layout for the given page as defined in front matter.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [PAGE.Layout]
+---
+
+Specify the `layout` field in front matter to target a particular template. See [details].
+
+[details]: /templates/lookup-order/#target-a-template
+
+{{< code-toggle file=content/contact.md fm=true >}}
+title = 'Contact'
+layout = 'contact'
+{{< /code-toggle >}}
+
+Hugo will render the page using contact.html.
+
+```text
+layouts/
+├── baseof.html
+├── contact.html
+├── home.html
+├── page.html
+├── section.html
+├── taxonomy.html
+└── term.html
+```
+
+Although rarely used within a template, you can access the value with:
+
+```go-html-template
+{{ .Layout }}
+```
+
+The `Layout` method returns an empty string if the `layout` field in front matter is not defined.
diff --git a/documents/markdown/hugo-docs/en_methods_page_Len.md b/documents/markdown/hugo-docs/en_methods_page_Len.md
new file mode 100644
index 0000000..010da88
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Len.md
@@ -0,0 +1,14 @@
+---
+title: Len
+description: Returns the length, in bytes, of the rendered content of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [PAGE.Len]
+---
+
+```go-html-template
+{{ .Len }} → 42
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_LinkTitle.md b/documents/markdown/hugo-docs/en_methods_page_LinkTitle.md
new file mode 100644
index 0000000..fcfd531
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_LinkTitle.md
@@ -0,0 +1,29 @@
+---
+title: LinkTitle
+description: Returns the link title of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [PAGE.LinkTitle]
+---
+
+The `LinkTitle` method returns the `linkTitle` field as defined in front matter, falling back to the value returned by the [`Title`] method.
+
+[`Title`]: /methods/page/title/
+
+{{< code-toggle file=content/articles/healthy-desserts.md fm=true >}}
+title = 'Seventeen delightful recipes for healthy desserts'
+linkTitle = 'Dessert recipes'
+{{< /code-toggle >}}
+
+```go-html-template
+{{ .LinkTitle }} → Dessert recipes
+```
+
+As demonstrated above, defining a link title in front matter is advantageous when the page title is long. Use it when generating anchor elements in your templates:
+
+```go-html-template
+<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_Next.md b/documents/markdown/hugo-docs/en_methods_page_Next.md
new file mode 100644
index 0000000..9966030
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Next.md
@@ -0,0 +1,12 @@
+---
+title: Next
+description: Returns the next page in a site's collection of regular pages, relative to the current page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Page
+ signatures: [PAGE.Next]
+---
+
+{{% include "/_common/methods/page/next-and-prev.md" %}}
diff --git a/documents/markdown/hugo-docs/en_methods_page_NextInSection.md b/documents/markdown/hugo-docs/en_methods_page_NextInSection.md
new file mode 100644
index 0000000..eb02c94
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_NextInSection.md
@@ -0,0 +1,12 @@
+---
+title: NextInSection
+description: Returns the next regular page in a section, relative to the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Page
+ signatures: [PAGE.NextInSection]
+---
+
+{{% include "/_common/methods/page/nextinsection-and-previnsection.md" %}}
diff --git a/documents/markdown/hugo-docs/en_methods_page_OutputFormats.md b/documents/markdown/hugo-docs/en_methods_page_OutputFormats.md
new file mode 100644
index 0000000..19377fe
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_OutputFormats.md
@@ -0,0 +1,73 @@
+---
+title: OutputFormats
+description: Returns a slice of OutputFormat objects, each representing one of the output formats enabled for the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: '[]OutputFormat'
+ signatures: [PAGE.OutputFormats]
+---
+
+{{% glossary-term "output format" %}}
+
+The `OutputFormats` method on a `Page` object returns a slice of `OutputFormat` objects, each representing one of the output formats enabled for the given page. See [details](/configuration/output-formats/).
+
+## Methods
+
+### Canonical
+
+{{< new-in "0.154.4" />}}
+
+(`page.OutputFormat`) Returns the [canonical output format](g) for the current page, if defined. Once you have captured the object, use any of its [associated methods][].
+
+```go-html-template
+{{ with .Site.Home.OutputFormats.Canonical }}
+ {{ .MediaType.Type }} → text/html
+ {{ .MediaType.MainType }} → text
+ {{ .MediaType.SubType }} → html
+ {{ .Name }} → html
+ {{ .Permalink }} → https://example.org/
+ {{ .Rel }} → canonical
+ {{ .RelPermalink }} → /
+{{ end }}
+```
+
+### Get
+
+(`page.OutputFormat`) Returns the `OutputFormat` object with the given identifier. Once you have captured the object, use any of its [associated methods][].
+
+```go-html-template
+{{ with .Site.Home.OutputFormats.Get "rss" }}
+ {{ .MediaType.Type }} → application/rss+xml
+ {{ .MediaType.MainType }} → application
+ {{ .MediaType.SubType }} → rss
+ {{ .Name }} → rss
+ {{ .Permalink }} → https://example.org/index.xml
+ {{ .Rel }} → alternate
+ {{ .RelPermalink }} → /index.xml
+{{ end }}
+```
+
+## Examples
+
+To render a `link` element pointing to the [canonical output format](g) for the current page:
+
+```go-html-template
+{{ with .OutputFormats.Canonical }}
+ {{ printf "<link rel=%q type=%q href=%q>" .Rel .MediaType.Type .Permalink | safeHTML }}
+{{ end }}
+```
+
+To render an anchor element pointing to the `rss` output format for the current page:
+
+```go-html-template
+{{ with .OutputFormats.Get "rss" }}
+ <a href="{{ .RelPermalink }}">RSS Feed</a>
+{{ end }}
+```
+
+Please see the [link to output formats] section to understand the importance of the construct above.
+
+[associated methods]: /methods/output-format/
+[link to output formats]: /configuration/output-formats/#link-to-output-formats
diff --git a/documents/markdown/hugo-docs/en_methods_page_Page.md b/documents/markdown/hugo-docs/en_methods_page_Page.md
new file mode 100644
index 0000000..b7bdf35
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Page.md
@@ -0,0 +1,35 @@
+---
+title: Page
+description: Returns the Page object of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Page
+ signatures: [PAGE.Page]
+---
+
+This is a convenience method, useful within _partial_ templates that are called from both _shortcode_ and other template types.
+
+```go-html-template {file="layouts/_shortcodes/foo.html"}
+{{ partial "my-partial.html" . }}
+```
+
+When the _shortcode_ template calls the _partial_ template, it passes the current [context](g) (the dot). The context includes identifiers such as `Page`, `Params`, `Inner`, and `Name`.
+
+```go-html-template {file="layouts/page.html"}
+{{ partial "my-partial.html" . }}
+```
+
+When the _page_ template calls the _partial_ template, it also passes the current context (the dot). But in this case, the dot _is_ the `Page` object.
+
+```go-html-template {file="layouts/_partials/my-partial.html"}
+The page title is: {{ .Page.Title }}
+```
+
+To handle both scenarios, the _partial_ template must be able to access the `Page` object with `Page.Page`.
+
+> [!note]
+> And yes, that means you can do `.Page.Page.Page.Page.Title` too.
+>
+> But don't.
diff --git a/documents/markdown/hugo-docs/en_methods_page_Pages.md b/documents/markdown/hugo-docs/en_methods_page_Pages.md
new file mode 100644
index 0000000..ba43c36
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Pages.md
@@ -0,0 +1,82 @@
+---
+title: Pages
+description: Returns a collection of regular pages within the current section, and section pages of immediate descendant sections.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGE.Pages]
+---
+
+The `Pages` method on a `Page` object is available to these [page kinds](g): `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection](g) in [context](g), in the [default sort order](g).
+
+Range through the page collection in your template:
+
+```go-html-template
+{{ range .Pages.ByTitle }}
+ <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
+{{ end }}
+```
+
+Consider this content structure:
+
+```text
+content/
+├── lessons/
+│ ├── lesson-1/
+│ │ ├── _index.md
+│ │ ├── part-1.md
+│ │ └── part-2.md
+│ ├── lesson-2/
+│ │ ├── resources/
+│ │ │ ├── task-list.md
+│ │ │ └── worksheet.md
+│ │ ├── _index.md
+│ │ ├── part-1.md
+│ │ └── part-2.md
+│ ├── _index.md
+│ ├── grading-policy.md
+│ └── lesson-plan.md
+├── _index.md
+├── contact.md
+└── legal.md
+```
+
+When rendering the home page, the `Pages` method returns:
+
+ contact.md
+ legal.md
+ lessons/_index.md
+
+When rendering the lessons page, the `Pages` method returns:
+
+ lessons/grading-policy.md
+ lessons/lesson-plan.md
+ lessons/lesson-1/_index.md
+ lessons/lesson-2/_index.md
+
+When rendering lesson-1, the `Pages` method returns:
+
+ lessons/lesson-1/part-1.md
+ lessons/lesson-1/part-2.md
+
+When rendering lesson-2, the `Pages` method returns:
+
+ lessons/lesson-2/part-1.md
+ lessons/lesson-2/part-2.md
+ lessons/lesson-2/resources/task-list.md
+ lessons/lesson-2/resources/worksheet.md
+
+In the last example, the collection includes pages in the resources subdirectory. That directory is not a [section](g)---it does not contain an `_index.md` file. Its contents are part of the lesson-2 section.
+
+> [!note]
+> When used with a `Site` object, the `Pages` method recursively returns all pages within the site. See [details].
+
+```go-html-template
+{{ range .Site.Pages.ByTitle }}
+ <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
+{{ end }}
+```
+
+[details]: /methods/site/pages/
diff --git a/documents/markdown/hugo-docs/en_methods_page_Paginate.md b/documents/markdown/hugo-docs/en_methods_page_Paginate.md
new file mode 100644
index 0000000..452bf9d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Paginate.md
@@ -0,0 +1,47 @@
+---
+title: Paginate
+description: Paginates a collection of pages.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pager
+ signatures: ['PAGE.Paginate COLLECTION [N]']
+---
+
+Pagination is the process of splitting a list page into two or more pagers, where each pager contains a subset of the page collection and navigation links to other pagers.
+
+By default, the number of elements on each pager is determined by your [project configuration]. The default is `10`. Override that value by providing a second argument, an integer, when calling the `Paginate` method.
+
+> [!note]
+> There is also a `Paginator` method on `Page` objects, but it can neither filter nor sort the page collection.
+>
+> The `Paginate` method is more flexible.
+
+You can invoke pagination in [home], [section], [taxonomy], and [term] templates.
+
+```go-html-template {file="layouts/section.html"}
+{{ $pages := where .Site.RegularPages "Section" "articles" }}
+{{ $pages = $pages.ByTitle }}
+{{ range (.Paginate $pages 7).Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
+{{ end }}
+{{ partial "pagination.html" . }}
+```
+
+In the example above, we:
+
+1. Build a page collection
+1. Sort the collection by title
+1. Paginate the collection, with 7 elements per pager
+1. Range over the paginated page collection, rendering a link to each page
+1. Call the embedded pagination template to create navigation links between pagers
+
+> [!note]
+> Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect.
+
+[home]: /templates/types/#home
+[section]: /templates/types/#section
+[project configuration]: /configuration/pagination/
+[taxonomy]: /templates/types/#taxonomy
+[term]: /templates/types/#term
diff --git a/documents/markdown/hugo-docs/en_methods_page_Paginator.md b/documents/markdown/hugo-docs/en_methods_page_Paginator.md
new file mode 100644
index 0000000..059e55e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Paginator.md
@@ -0,0 +1,40 @@
+---
+title: Paginator
+description: Paginates the collection of regular pages received in context.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pager
+ signatures: [PAGE.Paginator]
+---
+
+Pagination is the process of splitting a list page into two or more pagers, where each pager contains a subset of the page collection and navigation links to other pagers.
+
+The number of elements on each pager is determined by your [project configuration]. The default is `10`.
+
+You can invoke pagination in [home], [section], [taxonomy], and [term] templates. Each of these receives a collection of regular pages in [context](g). When you invoke the `Paginator` method, it paginates the page collection received in context.
+
+```go-html-template {file="layouts/section.html"}
+{{ range .Paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+{{ partial "pagination.html" . }}
+```
+
+In the example above, the embedded pagination template creates navigation links between pagers.
+
+> [!note]
+> Although simple to invoke, with the `Paginator` method you can neither filter nor sort the page collection. It acts upon the page collection received in context.
+>
+> The [`Paginate`] method is more flexible, and strongly recommended.
+
+> [!note]
+> Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect.
+
+[home]: /templates/types/#home
+[section]: /templates/types/#section
+[project configuration]: /configuration/pagination/
+[taxonomy]: /templates/types/#taxonomy
+[term]: /templates/types/#term
+[`Paginate`]: /methods/page/paginate/
diff --git a/documents/markdown/hugo-docs/en_methods_page_Param.md b/documents/markdown/hugo-docs/en_methods_page_Param.md
new file mode 100644
index 0000000..b07c1cd
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Param.md
@@ -0,0 +1,48 @@
+---
+title: Param
+description: Returns a page parameter with the given key, falling back to a site parameter if present.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: any
+ signatures: [PAGE.Param KEY]
+aliases: [/functions/param]
+---
+
+The `Param` method on a `Page` object looks for the given `KEY` in page parameters, and returns the corresponding value. If it cannot find the `KEY` in page parameters, it looks for the `KEY` in site parameters. If it cannot find the `KEY` in either location, the `Param` method returns `nil`.
+
+Site and theme developers commonly set parameters at the site level, allowing content authors to override those parameters at the page level.
+
+For example, to show a table of contents on every page, but allow authors to hide the table of contents as needed:
+
+Configuration:
+
+{{< code-toggle file=hugo >}}
+[params]
+display_toc = true
+{{< /code-toggle >}}
+
+Content:
+
+{{< code-toggle file=content/example.md fm=true >}}
+title = 'Example'
+date = 2023-01-01
+draft = false
+[params]
+display_toc = false
+{{< /code-toggle >}}
+
+Template:
+
+```go-html-template
+{{ if .Param "display_toc" }}
+ {{ .TableOfContents }}
+{{ end }}
+```
+
+The `Param` method returns the value associated with the given `KEY`, regardless of whether the value is truthy or falsy. If you need to ignore falsy values, use this construct instead:
+
+```go-html-template
+{{ or .Params.foo site.Params.foo }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_Params.md b/documents/markdown/hugo-docs/en_methods_page_Params.md
new file mode 100644
index 0000000..eeb2534
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Params.md
@@ -0,0 +1,42 @@
+---
+title: Params
+description: Returns a map of custom parameters as defined in the front matter of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: maps.Params
+ signatures: [PAGE.Params]
+---
+
+By way of example, consider this front matter:
+
+{{< code-toggle file=content/annual-conference.md fm=true >}}
+title = 'Annual conference'
+date = 2023-10-17T15:11:37-07:00
+[params]
+display_related = true
+key-with-hyphens = 'must use index function'
+[params.author]
+ email = 'jsmith@example.org'
+ name = 'John Smith'
+{{< /code-toggle >}}
+
+The `title` and `date` fields are standard [front matter fields], while the other fields are user-defined.
+
+Access the custom fields by [chaining](g) the [identifiers](g) when needed:
+
+```go-html-template
+{{ .Params.display_related }} → true
+{{ .Params.author.email }} → jsmith@example.org
+{{ .Params.author.name }} → John Smith
+```
+
+In the template example above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function:
+
+```go-html-template
+{{ index .Params "key-with-hyphens" }} → must use index function
+```
+
+[`index`]: /functions/collections/indexfunction/
+[front matter fields]: /content-management/front-matter/#fields
diff --git a/documents/markdown/hugo-docs/en_methods_page_Parent.md b/documents/markdown/hugo-docs/en_methods_page_Parent.md
new file mode 100644
index 0000000..0946a79
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Parent.md
@@ -0,0 +1,52 @@
+---
+title: Parent
+description: Returns the Page object of the parent section of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Page
+ signatures: [PAGE.Parent]
+---
+
+{{% glossary-term section %}}
+
+> [!note]
+> The parent section of a regular page is the [current section].
+
+Consider this content structure:
+
+```text
+content/
+├── auctions/
+│ ├── 2023-11/
+│ │ ├── _index.md <-- parent: auctions
+│ │ ├── auction-1.md
+│ │ └── auction-2.md <-- parent: 2023-11
+│ ├── 2023-12/
+│ │ ├── _index.md
+│ │ ├── auction-3.md
+│ │ └── auction-4.md
+│ ├── _index.md <-- parent: home
+│ ├── bidding.md
+│ └── payment.md <-- parent: auctions
+├── books/
+│ ├── _index.md <-- parent: home
+│ ├── book-1.md
+│ └── book-2.md <-- parent: books
+├── films/
+│ ├── _index.md <-- parent: home
+│ ├── film-1.md
+│ └── film-2.md <-- parent: films
+└── _index.md <-- parent: nil
+```
+
+In the example above, note the parent section of the home page is nil. Code defensively by verifying existence of the parent section before calling methods on its `Page` object. To create a link to the parent section page of the current page:
+
+```go-html-template
+{{ with .Parent }}
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+{{ end }}
+```
+
+[current section]: /methods/page/currentsection/
diff --git a/documents/markdown/hugo-docs/en_methods_page_Path.md b/documents/markdown/hugo-docs/en_methods_page_Path.md
new file mode 100644
index 0000000..b2ef7a0
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Path.md
@@ -0,0 +1,138 @@
+---
+title: Path
+description: Returns the logical path of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [PAGE.Path]
+---
+
+The `Path` method on a `Page` object returns the logical path of the given page, regardless of whether the page is backed by a file.
+
+{{% glossary-term "logical path" %}}
+
+```go-html-template
+{{ .Path }} → /posts/post-1
+```
+
+> [!note]
+> Beginning with the release of [v0.92.0] in January 2022, Hugo emitted a warning whenever calling the `Path` method. The warning indicated that this method would change in a future release.
+>
+> The meaning of, and value returned by, the `Path` method on a `Page` object changed with the release of [v0.123.0] in February 2024.
+
+The value returned by the `Path` method on a `Page` object is independent of content format, language, and URL modifiers such as the `slug` and `url` front matter fields.
+
+## Examples
+
+### Monolingual project
+
+Note that the logical path is independent of content format and URL modifiers.
+
+File path|Front matter slug|Logical path
+:--|:--|:--
+`content/_index.md`||`/`
+`content/posts/_index.md`||`/posts`
+`content/posts/post-1.md`|`foo`|`/posts/post-1`
+`content/posts/post-2.html`|`bar`|`/posts/post-2`
+
+### Multilingual site
+
+Note that the logical path is independent of content format, language identifiers, and URL modifiers.
+
+File path|Front matter slug|Logical path
+:--|:--|:--
+`content/_index.en.md`||`/`
+`content/_index.de.md`||`/`
+`content/posts/_index.en.md`||`/posts`
+`content/posts/_index.de.md`||`/posts`
+`content/posts/posts-1.en.md`|`foo`|`/posts/post-1`
+`content/posts/posts-1.de.md`|`foo`|`/posts/post-1`
+`content/posts/posts-2.en.html`|`bar`|`/posts/post-2`
+`content/posts/posts-2.de.html`|`bar`|`/posts/post-2`
+
+### Pages not backed by a file
+
+The `Path` method on a `Page` object returns a value regardless of whether the page is backed by a file.
+
+```text
+content/
+└── posts/
+ └── post-1.md <-- front matter: tags = ['hugo']
+```
+
+When you build the site:
+
+```text
+public/
+├── posts/
+│ ├── post-1/
+│ │ └── index.html .Page.Path = /posts/post-1
+│ └── index.html .Page.Path = /posts
+├── tags/
+│ ├── hugo/
+│ │ └── index.html .Page.Path = /tags/hugo
+│ └── index.html .Page.Path = /tags
+└── index.html .Page.Path = /
+```
+
+## Finding pages
+
+These methods, functions, and shortcodes use the logical path to find the given page:
+
+Methods|Functions|Shortcodes
+:--|:--|:--
+[`Site.GetPage`]|[`urls.Ref`]|[`ref`]
+[`Page.GetPage`]|[`urls.RelRef`]|[`relref`]
+[`Page.Ref`]| |
+[`Page.RelRef`]| |
+[`Shortcode.Ref`]| |
+[`Shortcode.RelRef`]| |
+
+> [!note]
+> Specify the logical path when using any of these methods, functions, or shortcodes. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree.
+
+## Logical tree
+
+Just as file paths form a file tree, logical paths form a logical tree.
+
+A file tree:
+
+```text
+content/
+└── s1/
+ ├── p1/
+ │ └── index.md
+ └── p2.md
+```
+
+The same content represented as a logical tree:
+
+```text
+content/
+└── s1/
+ ├── p1
+ └── p2
+```
+
+A key difference between these trees is the relative path from p1 to p2:
+
+- In the file tree, the relative path from p1 to p2 is `../p2.md`
+- In the logical tree, the relative path is `p2`
+
+> [!note]
+> Remember to use the logical path when using any of the methods, functions, or shortcodes listed in the previous section. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree.
+
+[`Page.GetPage`]: /methods/page/getpage/
+[`Page.Ref`]: /methods/page/ref/
+[`Page.RelRef`]: /methods/page/relref/
+[`ref`]: /shortcodes/ref/
+[`relref`]: /shortcodes/relref/
+[`Shortcode.Ref`]: /methods/shortcode/ref
+[`Shortcode.RelRef`]: /methods/shortcode/relref
+[`Site.GetPage`]: /methods/site/getpage/
+[`urls.Ref`]: /functions/urls/ref/
+[`urls.RelRef`]: /functions/urls/relref/
+[v0.123.0]: https://github.com/gohugoio/hugo/releases/tag/v0.123.0
+[v0.92.0]: https://github.com/gohugoio/hugo/releases/tag/v0.92.0
diff --git a/documents/markdown/hugo-docs/en_methods_page_Permalink.md b/documents/markdown/hugo-docs/en_methods_page_Permalink.md
new file mode 100644
index 0000000..ffd6ede
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Permalink.md
@@ -0,0 +1,24 @@
+---
+title: Permalink
+description: Returns the permalink of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [PAGE.Permalink]
+---
+
+Project configuration:
+
+{{< code-toggle file=hugo >}}
+title = 'Documentation'
+baseURL = 'https://example.org/docs/'
+{{< /code-toggle >}}
+
+Template:
+
+```go-html-template
+{{ $page := .Site.GetPage "/about" }}
+{{ $page.Permalink }} → https://example.org/docs/about/
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_Plain.md b/documents/markdown/hugo-docs/en_methods_page_Plain.md
new file mode 100644
index 0000000..23bc214
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Plain.md
@@ -0,0 +1,23 @@
+---
+title: Plain
+description: Returns the rendered content of the given page, removing all HTML tags.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [PAGE.Plain]
+---
+
+The `Plain` method on a `Page` object renders Markdown and [shortcodes](g) to HTML, then strips the HTML [tags][]. It does not strip HTML [entities][].
+
+To prevent Go's [`html/template`][] package from escaping HTML entities, pass the result through the [`htmlUnescape`][] function.
+
+```go-html-template
+{{ .Plain | htmlUnescape }}
+```
+
+[`html/template`]: https://pkg.go.dev/html/template
+[entities]: https://developer.mozilla.org/en-US/docs/Glossary/Entity
+[tags]: https://developer.mozilla.org/en-US/docs/Glossary/Tag
+[`htmlUnescape`]: /functions/transform/htmlunescape/
diff --git a/documents/markdown/hugo-docs/en_methods_page_PlainWords.md b/documents/markdown/hugo-docs/en_methods_page_PlainWords.md
new file mode 100644
index 0000000..5749a21
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_PlainWords.md
@@ -0,0 +1,31 @@
+---
+title: PlainWords
+description: Calls the Plain method, splits the result into a slice of words, and returns the slice.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: '[]string'
+ signatures: [PAGE.PlainWords]
+---
+
+The `PlainWords` method on a `Page` object calls the [`Plain`] method, then uses Go's [`strings.Fields`] function to split the result into words.
+
+> [!note]
+> `Fields` splits the string `s` around each instance of one or more consecutive whitespace characters, as defined by [`unicode.IsSpace`], returning a slice of substrings of `s` or an empty slice if `s` contains only whitespace.
+
+As a result, elements within the slice may contain leading or trailing punctuation.
+
+```go-html-template
+{{ .PlainWords }}
+```
+
+To determine the approximate number of unique words on a page:
+
+```go-html-template
+{{ .PlainWords | uniq }} → 42
+```
+
+[`Plain`]: /methods/page/plain/
+[`strings.Fields`]: https://pkg.go.dev/strings#Fields
+[`unicode.IsSpace`]: https://pkg.go.dev/unicode#IsSpace
diff --git a/documents/markdown/hugo-docs/en_methods_page_Prev.md b/documents/markdown/hugo-docs/en_methods_page_Prev.md
new file mode 100644
index 0000000..5a6e216
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Prev.md
@@ -0,0 +1,12 @@
+---
+title: Prev
+description: Returns the previous page in a site's collection of regular pages, relative to the current page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Page
+ signatures: [PAGE.Prev]
+---
+
+{{% include "/_common/methods/page/next-and-prev.md" %}}
diff --git a/documents/markdown/hugo-docs/en_methods_page_PrevInSection.md b/documents/markdown/hugo-docs/en_methods_page_PrevInSection.md
new file mode 100644
index 0000000..14d3ca0
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_PrevInSection.md
@@ -0,0 +1,12 @@
+---
+title: PrevInSection
+description: Returns the previous regular page in a section, relative to the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Page
+ signatures: [PAGE.PrevInSection]
+---
+
+{{% include "/_common/methods/page/nextinsection-and-previnsection.md" %}}
diff --git a/documents/markdown/hugo-docs/en_methods_page_PublishDate.md b/documents/markdown/hugo-docs/en_methods_page_PublishDate.md
new file mode 100644
index 0000000..ec3c133
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_PublishDate.md
@@ -0,0 +1,32 @@
+---
+title: PublishDate
+description: Returns the publish date of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: time.Time
+ signatures: [PAGE.PublishDate]
+---
+
+By default, Hugo excludes pages with future publish dates when building your project. To include future pages, use the `--buildFuture` command line flag.
+
+Set the publish date in front matter:
+
+{{< code-toggle file=content/news/article-1.md fm=true >}}
+title = 'Article 1'
+publishDate = 2023-10-19T00:40:04-07:00
+{{< /code-toggle >}}
+
+The publish date is a [time.Time] value. Format and localize the value with the [`time.Format`] function, or use it with any of the [time methods].
+
+```go-html-template
+{{ .PublishDate | time.Format ":date_medium" }} → Oct 19, 2023
+```
+
+In the example above we explicitly set the publish date in front matter. With Hugo's default configuration, the `PublishDate` method returns the front matter value. This behavior is configurable, allowing you to set fallback values if the publish date is not defined in front matter. See [details].
+
+[`time.Format`]: /functions/time/format/
+[details]: /configuration/front-matter/#dates
+[time methods]: /methods/time/
+[time.Time]: https://pkg.go.dev/time#Time
diff --git a/documents/markdown/hugo-docs/en_methods_page_RawContent.md b/documents/markdown/hugo-docs/en_methods_page_RawContent.md
new file mode 100644
index 0000000..41215ef
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_RawContent.md
@@ -0,0 +1,23 @@
+---
+title: RawContent
+description: Returns the raw content of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [PAGE.RawContent]
+---
+
+The `RawContent` method on a `Page` object returns the raw content. The raw content does not include front matter.
+
+```go-html-template
+{{ .RawContent }}
+```
+
+This is useful when rendering a page in a plain text [output format](g).
+
+> [!note]
+> [Shortcodes](g) within the content are not rendered. To get the raw content with shortcodes rendered, use the [`RenderShortcodes`] method on a `Page` object.
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes/
diff --git a/documents/markdown/hugo-docs/en_methods_page_ReadingTime.md b/documents/markdown/hugo-docs/en_methods_page_ReadingTime.md
new file mode 100644
index 0000000..2fd2ea4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_ReadingTime.md
@@ -0,0 +1,47 @@
+---
+title: ReadingTime
+description: Returns the estimated reading time, in minutes, for the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [PAGE.ReadingTime]
+---
+
+The estimated reading time is calculated by dividing the number of words in the content by the reading speed.
+
+By default, Hugo assumes a reading speed of 212 words per minute. For CJK languages, it assumes 500 words per minute.
+
+```go-html-template
+{{ printf "Estimated reading time: %d minutes" .ReadingTime }}
+```
+
+Reading speed varies by language. Create language-specific estimated reading times on your multilingual project using site parameters.
+
+{{< code-toggle file=hugo >}}
+[languages]
+ [languages.de]
+ contentDir = 'content/de'
+ label = 'Deutsch'
+ locale = 'de-DE'
+ weight = 2
+ [languages.de.params]
+ reading_speed = 179
+ [languages.en]
+ contentDir = 'content/en'
+ label = 'English'
+ locale = 'en-US'
+ weight = 1
+ [languages.en.params]
+ reading_speed = 228
+{{< /code-toggle >}}
+
+Then in your template:
+
+```go-html-template
+{{ $readingTime := div (float .WordCount) .Site.Params.reading_speed }}
+{{ $readingTime = math.Ceil $readingTime }}
+```
+
+We cast the `.WordCount` to a float to obtain a float when we divide by the reading speed. Then round up to the nearest integer.
diff --git a/documents/markdown/hugo-docs/en_methods_page_Ref.md b/documents/markdown/hugo-docs/en_methods_page_Ref.md
new file mode 100644
index 0000000..35f9460
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Ref.md
@@ -0,0 +1,37 @@
+---
+title: Ref
+description: Returns the absolute URL of the page with the given path, language, and output format.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [PAGE.Ref OPTIONS]
+---
+
+## Usage
+
+The `Ref` method accepts a single argument: an options map.
+
+## Options
+
+{{% include "_common/ref-and-relref-options.md" %}}
+
+## Examples
+
+The following examples show the rendered output for a page on the English version of the site:
+
+```go-html-template
+{{ $opts := dict "path" "/books/book-1" }}
+{{ .Ref $opts }} → https://example.org/en/books/book-1/
+
+{{ $opts := dict "path" "/books/book-1" "lang" "de" }}
+{{ .Ref $opts }} → https://example.org/de/books/book-1/
+
+{{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }}
+{{ .Ref $opts }} → https://example.org/de/books/book-1/index.json
+```
+
+## Error handling
+
+{{% include "_common/ref-and-relref-error-handling.md" %}}
diff --git a/documents/markdown/hugo-docs/en_methods_page_RegularPages.md b/documents/markdown/hugo-docs/en_methods_page_RegularPages.md
new file mode 100644
index 0000000..761de3a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_RegularPages.md
@@ -0,0 +1,79 @@
+---
+title: RegularPages
+description: Returns a collection of regular pages within the current section.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGE.RegularPages]
+---
+
+The `RegularPages` method on a `Page` object is available to these [page kinds](g): `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection](g) in [context](g), in the [default sort order](g).
+
+Range through the page collection in your template:
+
+```go-html-template
+{{ range .RegularPages.ByTitle }}
+ <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
+{{ end }}
+```
+
+Consider this content structure:
+
+```text
+content/
+├── lessons/
+│ ├── lesson-1/
+│ │ ├── _index.md
+│ │ ├── part-1.md
+│ │ └── part-2.md
+│ ├── lesson-2/
+│ │ ├── resources/
+│ │ │ ├── task-list.md
+│ │ │ └── worksheet.md
+│ │ ├── _index.md
+│ │ ├── part-1.md
+│ │ └── part-2.md
+│ ├── _index.md
+│ ├── grading-policy.md
+│ └── lesson-plan.md
+├── _index.md
+├── contact.md
+└── legal.md
+```
+
+When rendering the home page, the `RegularPages` method returns:
+
+ contact.md
+ legal.md
+
+When rendering the lessons page, the `RegularPages` method returns:
+
+ lessons/grading-policy.md
+ lessons/lesson-plan.md
+
+When rendering lesson-1, the `RegularPages` method returns:
+
+ lessons/lesson-1/part-1.md
+ lessons/lesson-1/part-2.md
+
+When rendering lesson-2, the `RegularPages` method returns:
+
+ lessons/lesson-2/part-1.md
+ lessons/lesson-2/part-2.md
+ lessons/lesson-2/resources/task-list.md
+ lessons/lesson-2/resources/worksheet.md
+
+In the last example, the collection includes pages in the resources subdirectory. That directory is not a [section](g)---it does not contain an `_index.md` file. Its contents are part of the lesson-2 section.
+
+> [!note]
+> When used with the `Site` object, the `RegularPages` method recursively returns all regular pages within the site. See [details].
+
+```go-html-template
+{{ range .Site.RegularPages.ByTitle }}
+ <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
+{{ end }}
+```
+
+[details]: /methods/site/regularpages/
diff --git a/documents/markdown/hugo-docs/en_methods_page_RegularPagesRecursive.md b/documents/markdown/hugo-docs/en_methods_page_RegularPagesRecursive.md
new file mode 100644
index 0000000..d85cd0b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_RegularPagesRecursive.md
@@ -0,0 +1,83 @@
+---
+title: RegularPagesRecursive
+description: Returns a collection of regular pages within the current section, and regular pages within all descendant sections.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGE.RegularPagesRecursive]
+---
+
+The `RegularPagesRecursive` method on a `Page` object is available to these [page kinds](g): `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection](g) in [context](g), in the [default sort order](g).
+
+Range through the page collection in your template:
+
+```go-html-template
+{{ range .RegularPagesRecursive.ByTitle }}
+ <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
+{{ end }}
+```
+
+Consider this content structure:
+
+```text
+content/
+├── lessons/
+│ ├── lesson-1/
+│ │ ├── _index.md
+│ │ ├── part-1.md
+│ │ └── part-2.md
+│ ├── lesson-2/
+│ │ ├── resources/
+│ │ │ ├── task-list.md
+│ │ │ └── worksheet.md
+│ │ ├── _index.md
+│ │ ├── part-1.md
+│ │ └── part-2.md
+│ ├── _index.md
+│ ├── grading-policy.md
+│ └── lesson-plan.md
+├── _index.md
+├── contact.md
+└── legal.md
+```
+
+When rendering the home page, the `RegularPagesRecursive` method returns:
+
+ contact.md
+ lessons/grading-policy.md
+ legal.md
+ lessons/lesson-plan.md
+ lessons/lesson-2/part-1.md
+ lessons/lesson-1/part-1.md
+ lessons/lesson-2/part-2.md
+ lessons/lesson-1/part-2.md
+ lessons/lesson-2/resources/task-list.md
+ lessons/lesson-2/resources/worksheet.md
+
+When rendering the lessons page, the `RegularPagesRecursive` method returns:
+
+ lessons/grading-policy.md
+ lessons/lesson-plan.md
+ lessons/lesson-2/part-1.md
+ lessons/lesson-1/part-1.md
+ lessons/lesson-2/part-2.md
+ lessons/lesson-1/part-2.md
+ lessons/lesson-2/resources/task-list.md
+ lessons/lesson-2/resources/worksheet.md
+
+When rendering lesson-1, the `RegularPagesRecursive` method returns:
+
+ lessons/lesson-1/part-1.md
+ lessons/lesson-1/part-2.md
+
+When rendering lesson-2, the `RegularPagesRecursive` method returns:
+
+ lessons/lesson-2/part-1.md
+ lessons/lesson-2/part-2.md
+ lessons/lesson-2/resources/task-list.md
+ lessons/lesson-2/resources/worksheet.md
+
+> [!note]
+> The `RegularPagesRecursive` method is not available on a `Site` object.
diff --git a/documents/markdown/hugo-docs/en_methods_page_RelPermalink.md b/documents/markdown/hugo-docs/en_methods_page_RelPermalink.md
new file mode 100644
index 0000000..ba03dc1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_RelPermalink.md
@@ -0,0 +1,24 @@
+---
+title: RelPermalink
+description: Returns the relative permalink of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [PAGE.RelPermalink]
+---
+
+Project configuration:
+
+{{< code-toggle file=hugo >}}
+title = 'Documentation'
+baseURL = 'https://example.org/docs/'
+{{< /code-toggle >}}
+
+Template:
+
+```go-html-template
+{{ $page := .Site.GetPage "/about" }}
+{{ $page.RelPermalink }} → /docs/about/
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_RelRef.md b/documents/markdown/hugo-docs/en_methods_page_RelRef.md
new file mode 100644
index 0000000..7edab57
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_RelRef.md
@@ -0,0 +1,37 @@
+---
+title: RelRef
+description: Returns the relative URL of the page with the given path, language, and output format.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [PAGE.RelRef OPTIONS]
+---
+
+## Usage
+
+The `RelRef` method accepts a single argument: an options map.
+
+## Options
+
+{{% include "_common/ref-and-relref-options.md" %}}
+
+## Examples
+
+The following examples show the rendered output for a page on the English version of the site:
+
+```go-html-template
+{{ $opts := dict "path" "/books/book-1" }}
+{{ .RelRef $opts }} → /en/books/book-1/
+
+{{ $opts := dict "path" "/books/book-1" "lang" "de" }}
+{{ .RelRef $opts }} → /de/books/book-1/
+
+{{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }}
+{{ .RelRef $opts }} → /de/books/book-1/index.json
+```
+
+## Error handling
+
+{{% include "_common/ref-and-relref-error-handling.md" %}}
diff --git a/documents/markdown/hugo-docs/en_methods_page_Render.md b/documents/markdown/hugo-docs/en_methods_page_Render.md
new file mode 100644
index 0000000..cd24419
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Render.md
@@ -0,0 +1,71 @@
+---
+title: Render
+description: Renders the given template with the given page as context.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: template.HTML
+ signatures: [PAGE.Render NAME]
+aliases: [/functions/render]
+---
+
+Typically used when ranging over a page collection, the `Render` method on a `Page` object renders the given template, passing the given page as context.
+
+```go-html-template
+{{ range site.RegularPages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ .Render "summary" }}
+{{ end }}
+```
+
+In the example above, note that the template ("summary") is identified by its file name without directory or extension.
+
+Although similar to the [`partial`] function, there are key differences.
+
+`Render` method|`partial` function
+:--|:--
+The `Page` object is automatically passed to the given template. You cannot pass additional context.|You must specify the context, allowing you to pass a combination of objects, slices, maps, and scalars.
+The path to the template is determined by the [content type](g).|You must specify the path to the template, relative to the `layouts/_partials` directory.
+
+Consider this layout structure:
+
+```text
+layouts/
+├── books/
+│ └── li.html <-- used when content type is "books"
+├── baseof.html
+├── home.html
+├── li.html <-- used for other content types
+├── page.html
+├── section.html
+├── taxonomy.html
+└── term.html
+```
+
+And this template:
+
+```go-html-template
+<ul>
+ {{ range site.RegularPages.ByDate }}
+ {{ .Render "li" }}
+ {{ end }}
+</ul>
+```
+
+When rendering content of type "books" the `Render` method calls:
+
+```text
+layouts/books/li.html
+```
+
+For all other content types the `Render` methods calls:
+
+```text
+layouts/li.html
+```
+
+See [content views] for more examples.
+
+[content views]: /templates/types/#content-view
+[`partial`]: /functions/partials/include/
diff --git a/documents/markdown/hugo-docs/en_methods_page_RenderShortcodes.md b/documents/markdown/hugo-docs/en_methods_page_RenderShortcodes.md
new file mode 100644
index 0000000..e440302
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_RenderShortcodes.md
@@ -0,0 +1,87 @@
+---
+title: RenderShortcodes
+description: Renders all shortcodes in the content of the given page, preserving the surrounding markup.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: template.HTML
+ signatures: [PAGE.RenderShortcodes]
+---
+
+Use this method in _shortcode_ templates to compose a page from multiple content files, while preserving a global context for footnotes and the table of contents.
+
+For example:
+
+```go-html-template {file="layouts/_shortcodes/include.html" copy=true}
+{{ with .Get 0 }}
+ {{ with $.Page.GetPage . }}
+ {{- .RenderShortcodes }}
+ {{ else }}
+ {{ errorf "The %q shortcode was unable to find %q. See %s" $.Name . $.Position }}
+ {{ end }}
+{{ else }}
+ {{ errorf "The %q shortcode requires a positional parameter indicating the logical path of the file to include. See %s" .Name .Position }}
+{{ end }}
+```
+
+Then call the shortcode in your Markdown:
+
+```text {file="content/about.md"}
+{{%/* include "/snippets/services" */%}}
+{{%/* include "/snippets/values" */%}}
+{{%/* include "/snippets/leadership" */%}}
+```
+
+Each of the included Markdown files can contain calls to other shortcodes.
+
+## Shortcode notation
+
+In the example above it's important to understand the difference between the two delimiters used when calling a shortcode:
+
+- `{{</* myshortcode */>}}` tells Hugo that the rendered shortcode does not need further processing. For example, the shortcode content is HTML.
+- `{{%/* myshortcode */%}}` tells Hugo that the rendered shortcode needs further processing. For example, the shortcode content is Markdown.
+
+Use the latter for the "include" shortcode described above.
+
+## Further explanation
+
+To understand what is returned by the `RenderShortcodes` method, consider this content file
+
+```text {file="content/about.md"}
++++
+title = 'About'
+date = 2023-10-07T12:28:33-07:00
++++
+
+{{</* ref "privacy" */>}}
+
+An *emphasized* word.
+```
+
+With this template code:
+
+```go-html-template
+{{ $p := site.GetPage "/about" }}
+{{ $p.RenderShortcodes }}
+```
+
+Hugo renders this:;
+
+```html
+https://example.org/privacy/
+
+An *emphasized* word.
+```
+
+Note that the shortcode within the content file was rendered, but the surrounding Markdown was preserved.
+
+## Limitations
+
+The primary use case for `.RenderShortcodes` is inclusion of Markdown content. If you try to use `.RenderShortcodes` inside `HTML` blocks when inside Markdown, you will get a warning similar to this:
+
+```text
+WARN .RenderShortcodes detected inside HTML block in "/content/mypost.md"; this may not be what you intended ...
+```
+
+The above warning can be turned off is this is what you really want.
diff --git a/documents/markdown/hugo-docs/en_methods_page_RenderString.md b/documents/markdown/hugo-docs/en_methods_page_RenderString.md
new file mode 100644
index 0000000..5f97e35
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_RenderString.md
@@ -0,0 +1,49 @@
+---
+title: RenderString
+description: Renders markup to HTML.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: template.HTML
+ signatures: ['PAGE.RenderString [OPTIONS] MARKUP']
+aliases: [/functions/renderstring]
+---
+
+```go-html-template
+{{ $s := "An *emphasized* word" }}
+{{ $s | .RenderString }} → An <em>emphasized</em> word
+```
+
+This method takes an optional map of options:
+
+display
+: (`string`) Specify either `inline` or `block`. If `inline`, removes surrounding `p` tags from short snippets. Default is `inline`.
+
+markup
+: (`string`) Specify a [markup identifier] for the provided markup. Default is the `markup` front matter value, falling back to the value derived from the page's file extension.
+
+Render with the default markup renderer:
+
+```go-html-template
+{{ $s := "An *emphasized* word" }}
+{{ $s | .RenderString }} → An <em>emphasized</em> word
+
+{{ $opts := dict "display" "block" }}
+{{ $s | .RenderString $opts }} → <p>An <em>emphasized</em> word</p>
+```
+
+Render with [Pandoc]:
+
+```go-html-template
+{{ $s := "H~2~O" }}
+
+{{ $opts := dict "markup" "pandoc" }}
+{{ $s | .RenderString $opts }} → H<sub>2</sub>O
+
+{{ $opts := dict "display" "block" "markup" "pandoc" }}
+{{ .RenderString $opts $s }} → <p>H<sub>2</sub>O</p>
+```
+
+[markup identifier]: /content-management/formats/#classification
+[pandoc]: https://pandoc.org/
diff --git a/documents/markdown/hugo-docs/en_methods_page_Resources.md b/documents/markdown/hugo-docs/en_methods_page_Resources.md
new file mode 100644
index 0000000..a99ca2f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Resources.md
@@ -0,0 +1,90 @@
+---
+title: Resources
+description: Returns a collection of page resources.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: resource.Resources
+ signatures: [PAGE.Resources]
+---
+
+The `Resources` method on a `Page` object returns a collection of page resources. A page resource is a file within a [page bundle](g).
+
+To work with global or remote resources, see the [`resources`] functions.
+
+## Methods
+
+### ByType
+
+(`resource.Resources`) Returns a collection of page resources of the given [media type], or nil if none found. The media type is typically one of `image`, `text`, `audio`, `video`, or `application`.
+
+```go-html-template
+{{ range .Resources.ByType "image" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+When working with global resources instead of page resources, use the [`resources.ByType`] function.
+
+### Get
+
+(`resource.Resource`) Returns a page resource from the given path, or nil if none found.
+
+```go-html-template
+{{ with .Resources.Get "images/a.jpg" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+When working with global resources instead of page resources, use the [`resources.Get`] function.
+
+### GetMatch
+
+(`resource.Resource`) Returns the first page resource from paths matching the given [glob pattern](g), or nil if none found.
+
+```go-html-template
+{{ with .Resources.GetMatch "images/*.jpg" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+When working with global resources instead of page resources, use the [`resources.GetMatch`] function.
+
+### Match
+
+(`resource.Resources`) Returns a collection of page resources from paths matching the given [glob pattern](g), or nil if none found.
+
+```go-html-template
+{{ range .Resources.Match "images/*.jpg" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+When working with global resources instead of page resources, use the [`resources.Match`] function.
+
+### Mount
+
+{{< new-in 0.140.0 />}}
+
+(`ResourceGetter`) Mounts the given resources from the two arguments base (`string`) to the given target path (`string`) and returns an object that implements [Get](#get). Note that leading slashes in target marks an absolute path. Relative target paths allows you to mount resources relative to another set, e.g. a [Page bundle](/content-management/page-bundles/):
+
+```go-html-template
+{{ $common := resources.Match "/js/headlessui/*.*" }}
+{{ $importContext := (slice $.Page ($common.Mount "/js/headlessui" ".")) }}
+```
+
+This method is currently only useful in [js.Batch](/functions/js/batch/#import-context).
+
+## Pattern matching
+
+With the `GetMatch` and `Match` methods, Hugo determines a match using a case-insensitive [glob pattern](g).
+
+{{% include "/_common/glob-patterns.md" %}}
+
+[`resources.ByType`]: /functions/resources/ByType/
+[`resources.GetMatch`]: /functions/resources/ByType/
+[`resources.Get`]: /functions/resources/ByType/
+[`resources.Match`]: /functions/resources/ByType/
+[`resources`]: /functions/resources/
+[media type]: https://en.wikipedia.org/wiki/Media_type
diff --git a/documents/markdown/hugo-docs/en_methods_page_Rotate.md b/documents/markdown/hugo-docs/en_methods_page_Rotate.md
new file mode 100644
index 0000000..643945d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Rotate.md
@@ -0,0 +1,55 @@
+---
+title: Rotate
+description: Returns a collection of pages that vary along the specified dimension while sharing the current page's values for the other dimensions, including the current page, sorted by the dimension's default sort order.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGE.Rotate DIMENSION]
+---
+
+{{< new-in 0.153.0 />}}
+
+The rotate method on a page object returns a collection of pages that vary along the specified [dimension](g), while holding the other dimensions constant. The result includes the current page and is sorted according to the rules of the specified dimension. For example, rotating along [language](g) returns all language variants that share the current page's [version](g) and [role](g).
+
+The `DIMENSION` argument must be one of `language`, `version`, or `role`.
+
+## Sort order
+
+Use the following rules to understand how Hugo sorts the collection returned by the `Rotate` method.
+
+| Dimension | Primary Sort | Secondary Sort |
+| :--- | :--- | :--- |
+| Language | Weight ascending | Lexicographical ascending |
+| Version | Weight ascending | Semantic version descending |
+| Role | Weight ascending | Lexicographical ascending |
+
+## Examples
+
+To render a list of the current page's language variants, including the current page, while sharing its current version and role:
+
+```go-html-template
+{{/* Returns languages sorted by weight ascending, then lexicographically ascending */}}
+{{ range .Rotate "language" }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+To render a list of the current page's version variants, including the current page, while sharing its current language and role:
+
+```go-html-template
+{{/* Returns versions sorted by weight ascending, then semantic version descending */}}
+{{ range .Rotate "version" }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+To render a list of the current page's role variants, including the current page, while sharing its current language and version:
+
+```go-html-template
+{{/* Returns roles sorted by weight ascending, then lexicographically ascending */}}
+{{ range .Rotate "role" }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_Scratch.md b/documents/markdown/hugo-docs/en_methods_page_Scratch.md
new file mode 100644
index 0000000..61c5dc1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Scratch.md
@@ -0,0 +1,21 @@
+---
+title: Scratch
+description: Returns a "scratch pad" to store and manipulate data, scoped to the current page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: maps.Scratch
+ signatures: [PAGE.Scratch]
+expiryDate: 2026-11-18 # deprecated 2024-11-18 (soft)
+---
+
+{{< deprecated-in 0.138.0 >}}
+Use the [`PAGE.Store`] method instead.
+
+This is a soft deprecation. This method will be removed in a future release, but the removal date has not been established. Although Hugo will not emit a warning if you continue to use this method, you should begin using `PAGE.Store` as soon as possible.
+
+Beginning with v0.138.0 the `PAGE.Scratch` method is aliased to `PAGE.Store`.
+
+[`PAGE.Store`]: /methods/page/store/
+{{< /deprecated-in >}}
diff --git a/documents/markdown/hugo-docs/en_methods_page_Section.md b/documents/markdown/hugo-docs/en_methods_page_Section.md
new file mode 100644
index 0000000..04c6a8a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Section.md
@@ -0,0 +1,54 @@
+---
+title: Section
+description: Returns the name of the top-level section in which the given page resides.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [PAGE.Section]
+---
+
+{{% glossary-term section %}}
+
+With this content structure:
+
+```text
+content/
+├── lessons/
+│ ├── math/
+│ │ ├── _index.md
+│ │ ├── lesson-1.md
+│ │ └── lesson-2.md
+│ └── _index.md
+└── _index.md
+```
+
+When rendering lesson-1.md:
+
+```go-html-template
+{{ .Section }} → lessons
+```
+
+In the example above "lessons" is the top-level section.
+
+The `Section` method is often used with the [`where`] function to build a page collection.
+
+```go-html-template
+{{ range where .Site.RegularPages "Section" "lessons" }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+This is similar to using the [`Type`] method with the `where` function
+
+```go-html-template
+{{ range where .Site.RegularPages "Type" "lessons" }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+However, if the `type` field in front matter has been defined on one or more pages, the page collection based on `Type` will be different than the page collection based on `Section`.
+
+[`where`]: /functions/collections/where/
+[`Type`]: /methods/page/type/
diff --git a/documents/markdown/hugo-docs/en_methods_page_Sections.md b/documents/markdown/hugo-docs/en_methods_page_Sections.md
new file mode 100644
index 0000000..12f0a8c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Sections.md
@@ -0,0 +1,62 @@
+---
+title: Sections
+description: Returns a collection of section pages, one for each immediate descendant section of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGE.Sections]
+---
+
+The `Sections` method on a `Page` object is available to these [page kinds](g): `home`, `section`, and `taxonomy`. The templates for these page kinds receive a page [collection](g) in [context](g), in the [default sort order](g).
+
+With this content structure:
+
+```text
+content/
+├── auctions/
+│ ├── 2023-11/
+│ │ ├── _index.md <-- front matter: weight = 202311
+│ │ ├── auction-1.md
+│ │ └── auction-2.md
+│ ├── 2023-12/
+│ │ ├── _index.md <-- front matter: weight = 202312
+│ │ ├── auction-3.md
+│ │ └── auction-4.md
+│ ├── _index.md <-- front matter: weight = 30
+│ ├── bidding.md
+│ └── payment.md
+├── books/
+│ ├── _index.md <-- front matter: weight = 20
+│ ├── book-1.md
+│ └── book-2.md
+├── films/
+│ ├── _index.md <-- front matter: weight = 10
+│ ├── film-1.md
+│ └── film-2.md
+└── _index.md
+```
+
+And this template:
+
+```go-html-template
+{{ range .Sections.ByWeight }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+On the home page, Hugo renders:
+
+```html
+<h2><a href="/films/">Films</a></h2>
+<h2><a href="/books/">Books</a></h2>
+<h2><a href="/auctions/">Auctions</a></h2>
+```
+
+On the auctions page, Hugo renders:
+
+```html
+<h2><a href="/auctions/2023-11/">Auctions in November 2023</a></h2>
+<h2><a href="/auctions/2023-12/">Auctions in December 2023</a></h2>
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_Site.md b/documents/markdown/hugo-docs/en_methods_page_Site.md
new file mode 100644
index 0000000..4649e5e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Site.md
@@ -0,0 +1,18 @@
+---
+title: Site
+description: Returns the Site object.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.siteWrapper
+ signatures: [PAGE.Site]
+---
+
+See [Site methods].
+
+[Site methods]: /methods/site/
+
+```go-html-template
+{{ .Site.Title }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_Sitemap.md b/documents/markdown/hugo-docs/en_methods_page_Sitemap.md
new file mode 100644
index 0000000..53f8cae
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Sitemap.md
@@ -0,0 +1,79 @@
+---
+title: Sitemap
+description: Returns the sitemap settings for the given page as defined in front matter, falling back to the sitemap settings as defined in your project configuration.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: config.SitemapConfig
+ signatures: [PAGE.Sitemap]
+---
+
+Access to the `Sitemap` method on a `Page` object is restricted to [sitemap templates].
+
+## Methods
+
+### ChangeFreq
+
+(`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. With the default value of `""` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#changefreqdef).
+
+```go-html-template
+{{ .Sitemap.ChangeFreq }}
+```
+
+### Disable
+
+(`bool`) Whether to disable page inclusion. Default is `false`. Set to `true` in front matter to exclude the page.
+
+```go-html-template
+{{ .Sitemap.Disable }}
+```
+
+### Priority
+
+(`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. With the default value of `-1` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#prioritydef).
+
+```go-html-template
+{{ .Sitemap.Priority }}
+```
+
+## Example
+
+With this project configuration:
+
+{{< code-toggle file=hugo >}}
+[sitemap]
+changeFreq = 'monthly'
+{{< /code-toggle >}}
+
+And this content:
+
+{{< code-toggle file=content/news.md fm=true >}}
+title = 'News'
+[sitemap]
+changeFreq = 'hourly'
+{{< /code-toggle >}}
+
+And this simplistic sitemap template:
+
+```xml {file="layouts/sitemap.xml"}
+{{ printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>" | safeHTML }}
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
+ xmlns:xhtml="http://www.w3.org/1999/xhtml">
+ {{ range .Pages }}
+ <url>
+ <loc>{{ .Permalink }}</loc>
+ {{ if not .Lastmod.IsZero }}
+ <lastmod>{{ .Lastmod.Format "2006-01-02T15:04:05-07:00" | safeHTML }}</lastmod>
+ {{ end }}
+ {{ with .Sitemap.ChangeFreq }}
+ <changefreq>{{ . }}</changefreq>
+ {{ end }}
+ </url>
+ {{ end }}
+</urlset>
+```
+
+The change frequency will be `hourly` for the news page, and `monthly` for other pages.
+
+[sitemap templates]: /templates/sitemap/
diff --git a/documents/markdown/hugo-docs/en_methods_page_Sites.md b/documents/markdown/hugo-docs/en_methods_page_Sites.md
new file mode 100644
index 0000000..293590b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Sites.md
@@ -0,0 +1,15 @@
+---
+title: Sites
+description: Returns a collection of all sites for all dimensions.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Sites
+ signatures: [PAGE.Sites]
+expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0
+---
+
+{{< deprecated-in 0.156.0 >}}
+Use [`hugo.Sites`](/functions/hugo/sites/) instead.
+{{< /deprecated-in >}}
diff --git a/documents/markdown/hugo-docs/en_methods_page_Slug.md b/documents/markdown/hugo-docs/en_methods_page_Slug.md
new file mode 100644
index 0000000..34000b6
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Slug.md
@@ -0,0 +1,25 @@
+---
+title: Slug
+description: Returns the URL slug of the given page as defined in front matter.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [PAGE.Slug]
+---
+
+{{< code-toggle file=content/recipes/spicy-tuna-hand-rolls.md fm=true >}}
+title = 'How to make spicy tuna hand rolls'
+slug = 'sushi'
+{{< /code-toggle >}}
+
+This page will be served from:
+
+ https://example.org/recipes/sushi
+
+To get the slug value within a template:
+
+```go-html-template
+{{ .Slug }} → sushi
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_Store.md b/documents/markdown/hugo-docs/en_methods_page_Store.md
new file mode 100644
index 0000000..c5ad6b3
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Store.md
@@ -0,0 +1,35 @@
+---
+title: Store
+description: Returns a "scratch pad" to store and manipulate data, scoped to the current page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: maps.Scratch
+ signatures: [PAGE.Store]
+aliases: [/functions/store/,/extras/scratch/,/doc/scratch/,/functions/scratch]
+---
+
+Use the `Store` method on a `Page` object to create a [scratch pad](g) to store and manipulate data, scoped to the current page. To create a scratch pad with a different [scope](g), refer to the [scope](#scope) section below.
+
+{{% include "_common/store-methods.md" %}}
+
+{{% include "_common/scratch-pad-scope.md" %}}
+
+## Determinate values
+
+The `Store` method is often used to set scratch pad values within a _shortcode_ template, a _partial_ template called by a _shortcode_ template, or by a _render hook_ template. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.
+
+If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop](g) variable:
+
+```go-html-template
+{{ $noop := .Content }}
+{{ .Store.Get "mykey" }}
+```
+
+You can also trigger content rendering with the `ContentWithoutSummary`, `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount` methods. For example:
+
+```go-html-template
+{{ $noop := .WordCount }}
+{{ .Store.Get "mykey" }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_Summary.md b/documents/markdown/hugo-docs/en_methods_page_Summary.md
new file mode 100644
index 0000000..c72a244
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Summary.md
@@ -0,0 +1,48 @@
+---
+title: Summary
+description: Returns the summary of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: template.HTML
+ signatures: [PAGE.Summary]
+---
+
+<!-- Do not remove the manual summary divider below. -->
+<!-- If you do, you will break its first literal usage on this page. -->
+
+<!--more-->
+
+You can define a [summary] manually, in front matter, or automatically. A manual summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary.
+
+To list the pages in a section with a summary beneath each link:
+
+```go-html-template
+{{ range .Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ .Summary }}
+{{ end }}
+```
+
+> [!warning]
+> Automatic `.Summary` may cut block tags (e.g., `blockquote`) in the middle, causing the browser to recover the end tag. See [automatic summary] for details and for ways to avoid this.
+
+Depending on content length and how you define the summary, the summary may be equivalent to the content itself. To determine whether the content length exceeds the summary length, use the [`Truncated`] method on a `Page` object. This is useful for conditionally rendering a “read more” link:
+
+```go-html-template
+{{ range .Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ .Summary }}
+ {{ if .Truncated }}
+ <a href="{{ .RelPermalink }}">Read more...</a>
+ {{ end }}
+{{ end }}
+```
+
+> [!note]
+> The `Truncated` method returns `false` if you define the summary in front matter.
+
+[`Truncated`]: /methods/page/truncated
+[summary]: /content-management/summaries/
+[automatic summary]: /content-management/summaries/#automatic-summary
diff --git a/documents/markdown/hugo-docs/en_methods_page_TableOfContents.md b/documents/markdown/hugo-docs/en_methods_page_TableOfContents.md
new file mode 100644
index 0000000..d5ae216
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_TableOfContents.md
@@ -0,0 +1,47 @@
+---
+title: TableOfContents
+description: Returns a table of contents for the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: template.HTML
+ signatures: [PAGE.TableOfContents]
+aliases: [/content-management/toc/]
+---
+
+The `TableOfContents` method on a `Page` object returns an ordered or unordered list of the Markdown [ATX] and [setext] headings within the page content.
+
+[atx]: https://spec.commonmark.org/current/#atx-headings
+[setext]: https://spec.commonmark.org/current/#setext-headings
+
+This template code:
+
+```go-html-template
+{{ .TableOfContents }}
+```
+
+Produces this HTML:
+
+```html
+<nav id="TableOfContents">
+ <ul>
+ <li><a href="#section-1">Section 1</a>
+ <ul>
+ <li><a href="#section-11">Section 1.1</a></li>
+ <li><a href="#section-12">Section 1.2</a></li>
+ </ul>
+ </li>
+ <li><a href="#section-2">Section 2</a></li>
+ </ul>
+</nav>
+```
+
+By default, the `TableOfContents` method returns an unordered list of level 2 and level 3 headings. You can adjust this in your project configuration:
+
+{{< code-toggle file=hugo >}}
+[markup.tableOfContents]
+endLevel = 3
+ordered = false
+startLevel = 2
+{{< /code-toggle >}}
diff --git a/documents/markdown/hugo-docs/en_methods_page_Title.md b/documents/markdown/hugo-docs/en_methods_page_Title.md
new file mode 100644
index 0000000..5135c5a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Title.md
@@ -0,0 +1,46 @@
+---
+title: Title
+description: Returns the title of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [PAGE.Title]
+---
+
+With pages backed by a file, the `Title` method returns the `title` field as defined in front matter:
+
+{{< code-toggle file=content/about.md fm=true >}}
+title = 'About us'
+{{< /code-toggle >}}
+
+```go-html-template
+{{ .Title }} → About us
+```
+
+When a page is not backed by a file, the value returned by the `Title` method depends on the page [kind](g).
+
+Page kind|Page title when the page is not backed by a file
+:--|:--
+home|site title
+section|section name (capitalized and pluralized)
+taxonomy|taxonomy name (capitalized and pluralized)
+term|term name (capitalized and pluralized)
+
+You can disable automatic capitalization and pluralization in your project configuration:
+
+{{< code-toggle file=hugo >}}
+capitalizeListTitles = false
+pluralizeListTitles = false
+{{< /code-toggle >}}
+
+You can change the capitalization style in your project configuration to one of `ap`, `chicago`, `go`, `firstupper`, or `none`. For example:
+
+{{< code-toggle file=hugo >}}
+titleCaseStyle = "firstupper"
+{{< /code-toggle >}}
+
+See [details].
+
+[details]: /configuration/all/#title-case-style
diff --git a/documents/markdown/hugo-docs/en_methods_page_TranslationKey.md b/documents/markdown/hugo-docs/en_methods_page_TranslationKey.md
new file mode 100644
index 0000000..3cbcb4a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_TranslationKey.md
@@ -0,0 +1,71 @@
+---
+title: TranslationKey
+description: Returns the translation key of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [PAGE.TranslationKey]
+---
+
+The translation key creates a relationship between all translations of a given page. The translation key is derived from the file path, or from the `translationKey` parameter if defined in front matter.
+
+With this project configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'en'
+
+[languages.en]
+contentDir = 'content/en'
+label = 'English'
+locale = 'en-US'
+weight = 1
+
+[languages.de]
+contentDir = 'content/de'
+label = 'Deutsch'
+locale = 'de-DE'
+weight = 2
+{{< /code-toggle >}}
+
+And this content:
+
+```text
+content/
+├── de/
+│ ├── books/
+│ │ ├── buch-1.md
+│ │ └── book-2.md
+│ └── _index.md
+├── en/
+│ ├── books/
+│ │ ├── book-1.md
+│ │ └── book-2.md
+│ └── _index.md
+└── _index.md
+```
+
+And this front matter:
+
+{{< code-toggle file=content/en/books/book-1.md fm=true >}}
+title = 'Book 1'
+translationKey = 'foo'
+{{< /code-toggle >}}
+
+{{< code-toggle file=content/de/books/buch-1.md fm=true >}}
+title = 'Buch 1'
+translationKey = 'foo'
+{{< /code-toggle >}}
+
+When rendering either either of the pages above:
+
+```go-html-template
+{{ .TranslationKey }} → page/foo
+```
+
+If the front matter of Book 2, in both languages, does not include a translation key:
+
+```go-html-template
+{{ .TranslationKey }} → page/books/book-2
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_Translations.md b/documents/markdown/hugo-docs/en_methods_page_Translations.md
new file mode 100644
index 0000000..da3715c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Translations.md
@@ -0,0 +1,86 @@
+---
+title: Translations
+description: Returns all translations of the given page, excluding the current language, sorted by language weight then language name.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGE.Translations]
+---
+
+With this project configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'en'
+
+[languages.en]
+contentDir = 'content/en'
+label = 'English'
+locale = 'en-US'
+weight = 1
+
+[languages.de]
+contentDir = 'content/de'
+label = 'Deutsch'
+locale = 'de-DE'
+weight = 2
+
+[languages.fr]
+contentDir = 'content/fr'
+label = 'Français'
+locale = 'fr-FR'
+weight = 3
+{{< /code-toggle >}}
+
+And this content:
+
+```text
+content/
+├── de/
+│ ├── books/
+│ │ ├── book-1.md
+│ │ └── book-2.md
+│ └── _index.md
+├── en/
+│ ├── books/
+│ │ ├── book-1.md
+│ │ └── book-2.md
+│ └── _index.md
+├── fr/
+│ ├── books/
+│ │ └── book-1.md
+│ └── _index.md
+└── _index.md
+```
+
+And this template:
+
+```go-html-template
+{{ with .Translations }}
+ <ul>
+ {{ range . }}
+ <li>
+ <a href="{{ .RelPermalink }}" hreflang="{{ .Language.Locale }}">{{ .LinkTitle }} ({{ or .Language.Label .Language.Name }})</a>
+ </li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+Hugo will render this list on the "Book 1" page of the English site:
+
+```html
+<ul>
+ <li><a href="/de/books/book-1/" hreflang="de-DE">Book 1 (Deutsch)</a></li>
+ <li><a href="/fr/books/book-1/" hreflang="fr-FR">Book 1 (Français)</a></li>
+</ul>
+```
+
+Hugo will render this list on the "Book 2" page of the English site:
+
+```html
+<ul>
+ <li><a href="/de/books/book-1/" hreflang="de-DE">Book 1 (Deutsch)</a></li>
+</ul>
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_Truncated.md b/documents/markdown/hugo-docs/en_methods_page_Truncated.md
new file mode 100644
index 0000000..8c25730
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Truncated.md
@@ -0,0 +1,29 @@
+---
+title: Truncated
+description: Reports whether the content length exceeds the summary length.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [PAGE.Truncated]
+---
+
+You can define a [summary] manually, in front matter, or automatically. A manual summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary.
+
+[summary]: /content-management/summaries/
+
+The `Truncated` method returns `true` if the content length exceeds the summary length. This is useful for conditionally rendering a "read more" link:
+
+```go-html-template
+{{ range .Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ .Summary }}
+ {{ if .Truncated }}
+ <a href="{{ .RelPermalink }}">Read more...</a>
+ {{ end }}
+{{ end }}
+```
+
+> [!note]
+> The `Truncated` method returns `false` if you define the summary in front matter.
diff --git a/documents/markdown/hugo-docs/en_methods_page_Type.md b/documents/markdown/hugo-docs/en_methods_page_Type.md
new file mode 100644
index 0000000..6f855fb
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Type.md
@@ -0,0 +1,51 @@
+---
+title: Type
+description: Returns the content type of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [PAGE.Type]
+---
+
+The `Type` method on a `Page` object returns the [content type](g) of the given page. The content type is defined by the `type` field in front matter, or inferred from the top-level directory name if the `type` field in front matter is not defined.
+
+With this content structure:
+
+```text
+content/
+├── auction/
+│ ├── _index.md
+│ ├── item-1.md
+│ └── item-2.md <-- front matter: type = books
+├── books/
+│ ├── _index.md
+│ ├── book-1.md
+│ └── book-2.md
+├── films/
+│ ├── _index.md
+│ ├── film-1.md
+│ └── film-2.md
+└── _index.md
+```
+
+To list the books, regardless of [section](g):
+
+```go-html-template
+{{ range where .Site.RegularPages.ByTitle "Type" "books" }}
+ <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
+{{ end }}
+```
+
+Hugo renders this to;
+
+```html
+<h2><a href="/books/book-1/">Book 1</a></h2>
+<h2><a href="/books/book-2/">Book 2</a></h2>
+<h2><a href="/auction/item-2/">Item 2</a></h2>
+```
+
+The `type` field in front matter is also useful for targeting a template. See [details].
+
+[details]: /templates/lookup-order/#target-a-template
diff --git a/documents/markdown/hugo-docs/en_methods_page_Weight.md b/documents/markdown/hugo-docs/en_methods_page_Weight.md
new file mode 100644
index 0000000..c14af02
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_Weight.md
@@ -0,0 +1,25 @@
+---
+title: Weight
+description: Returns the weight of the given page as defined in front matter.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [PAGE.Weight]
+---
+
+The `Weight` method on a `Page` object returns the [weight](g) of the given page as defined in front matter.
+
+{{< code-toggle file=content/recipes/sushi.md fm=true >}}
+title = 'How to make spicy tuna hand rolls'
+weight = 42
+{{< /code-toggle >}}
+
+Page weight controls the position of a page within a collection that is sorted by weight. Assign weights using non-zero integers. Lighter items float to the top, while heavier items sink to the bottom. Unweighted or zero-weighted elements are placed at the end of the collection.
+
+Although rarely used within a template, you can access the value with:
+
+```go-html-template
+{{ .Weight }} → 42
+```
diff --git a/documents/markdown/hugo-docs/en_methods_page_WordCount.md b/documents/markdown/hugo-docs/en_methods_page_WordCount.md
new file mode 100644
index 0000000..3950244
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page_WordCount.md
@@ -0,0 +1,18 @@
+---
+title: WordCount
+description: Returns the number of words in the content of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [PAGE.WordCount]
+---
+
+```go-html-template
+{{ .WordCount }} → 103
+```
+
+To round up to nearest multiple of 100, use the [`FuzzyWordCount`] method.
+
+[`FuzzyWordCount`]: /methods/page/fuzzywordcount/
diff --git a/documents/markdown/hugo-docs/en_methods_page__index.md b/documents/markdown/hugo-docs/en_methods_page__index.md
new file mode 100644
index 0000000..c7ae7ad
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_page__index.md
@@ -0,0 +1,8 @@
+---
+title: Page methods
+linkTitle: Page
+description: Use these methods with a Page object.
+categories: []
+keywords: []
+aliases: [/variables/page/]
+---
diff --git a/documents/markdown/hugo-docs/en_methods_pager_First.md b/documents/markdown/hugo-docs/en_methods_pager_First.md
new file mode 100644
index 0000000..9cd5898
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pager_First.md
@@ -0,0 +1,38 @@
+---
+title: First
+description: Returns the first pager in the pager collection.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pager
+ signatures: [PAGER.First]
+---
+
+Use the `First` method to build navigation between pagers.
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ <ul>
+ {{ with .First }}
+ <li><a href="{{ .URL }}">First</a></li>
+ {{ end }}
+ {{ with .Prev }}
+ <li><a href="{{ .URL }}">Previous</a></li>
+ {{ end }}
+ {{ with .Next }}
+ <li><a href="{{ .URL }}">Next</a></li>
+ {{ end }}
+ {{ with .Last }}
+ <li><a href="{{ .URL }}">Last</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pager_HasNext.md b/documents/markdown/hugo-docs/en_methods_pager_HasNext.md
new file mode 100644
index 0000000..cf3688e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pager_HasNext.md
@@ -0,0 +1,66 @@
+---
+title: HasNext
+description: Reports whether there is a pager after the current pager.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [PAGER.HasNext]
+---
+
+Use the `HasNext` method to build navigation between pagers.
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ <ul>
+ {{ with .First }}
+ <li><a href="{{ .URL }}">First</a></li>
+ {{ end }}
+ {{ if .HasPrev }}
+ <li><a href="{{ .Prev.URL }}">Previous</a></li>
+ {{ end }}
+ {{ if .HasNext }}
+ <li><a href="{{ .Next.URL }}">Next</a></li>
+ {{ end }}
+ {{ with .Last }}
+ <li><a href="{{ .URL }}">Last</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+You can also write the above without using the `HasNext` method:
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ <ul>
+ {{ with .First }}
+ <li><a href="{{ .URL }}">First</a></li>
+ {{ end }}
+ {{ with .Prev }}
+ <li><a href="{{ .URL }}">Previous</a></li>
+ {{ end }}
+ {{ with .Next }}
+ <li><a href="{{ .URL }}">Next</a></li>
+ {{ end }}
+ {{ with .Last }}
+ <li><a href="{{ .URL }}">Last</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pager_HasPrev.md b/documents/markdown/hugo-docs/en_methods_pager_HasPrev.md
new file mode 100644
index 0000000..4b486b7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pager_HasPrev.md
@@ -0,0 +1,66 @@
+---
+title: HasPrev
+description: Reports whether there is a pager before the current pager.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [PAGER.HasPrev]
+---
+
+Use the `HasPrev` method to build navigation between pagers.
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ <ul>
+ {{ with .First }}
+ <li><a href="{{ .URL }}">First</a></li>
+ {{ end }}
+ {{ if .HasPrev }}
+ <li><a href="{{ .Prev.URL }}">Previous</a></li>
+ {{ end }}
+ {{ if .HasNext }}
+ <li><a href="{{ .Next.URL }}">Next</a></li>
+ {{ end }}
+ {{ with .Last }}
+ <li><a href="{{ .URL }}">Last</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+You can also write the above without using the `HasPrev` method:
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ <ul>
+ {{ with .First }}
+ <li><a href="{{ .URL }}">First</a></li>
+ {{ end }}
+ {{ with .Prev }}
+ <li><a href="{{ .URL }}">Previous</a></li>
+ {{ end }}
+ {{ with .Next }}
+ <li><a href="{{ .URL }}">Next</a></li>
+ {{ end }}
+ {{ with .Last }}
+ <li><a href="{{ .URL }}">Last</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pager_Last.md b/documents/markdown/hugo-docs/en_methods_pager_Last.md
new file mode 100644
index 0000000..71dea18
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pager_Last.md
@@ -0,0 +1,38 @@
+---
+title: Last
+description: Returns the last pager in the pager collection.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pager
+ signatures: [PAGER.Last]
+---
+
+Use the `Last` method to build navigation between pagers.
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ <ul>
+ {{ with .First }}
+ <li><a href="{{ .URL }}">First</a></li>
+ {{ end }}
+ {{ with .Prev }}
+ <li><a href="{{ .URL }}">Previous</a></li>
+ {{ end }}
+ {{ with .Next }}
+ <li><a href="{{ .URL }}">Next</a></li>
+ {{ end }}
+ {{ with .Last }}
+ <li><a href="{{ .URL }}">Last</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pager_Next.md b/documents/markdown/hugo-docs/en_methods_pager_Next.md
new file mode 100644
index 0000000..d7ea9ca
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pager_Next.md
@@ -0,0 +1,38 @@
+---
+title: Next
+description: Returns the next pager in the pager collection.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pager
+ signatures: [PAGER.Next]
+---
+
+Use the `Next` method to build navigation between pagers.
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ <ul>
+ {{ with .First }}
+ <li><a href="{{ .URL }}">First</a></li>
+ {{ end }}
+ {{ with .Prev }}
+ <li><a href="{{ .URL }}">Previous</a></li>
+ {{ end }}
+ {{ with .Next }}
+ <li><a href="{{ .URL }}">Next</a></li>
+ {{ end }}
+ {{ with .Last }}
+ <li><a href="{{ .URL }}">Last</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pager_NumberOfElements.md b/documents/markdown/hugo-docs/en_methods_pager_NumberOfElements.md
new file mode 100644
index 0000000..9f88126
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pager_NumberOfElements.md
@@ -0,0 +1,23 @@
+---
+title: NumberOfElements
+description: Returns the number of pages in the current pager.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [PAGER.NumberOfElements]
+---
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ {{ .NumberOfElements }}
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pager_PageGroups.md b/documents/markdown/hugo-docs/en_methods_pager_PageGroups.md
new file mode 100644
index 0000000..df668dd
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pager_PageGroups.md
@@ -0,0 +1,28 @@
+---
+title: PageGroups
+description: Returns the page groups in the current pager.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.PagesGroup
+ signatures: [PAGER.PageGroups]
+---
+
+Use the `PageGroups` method with any of the [grouping methods].
+
+[grouping methods]: /quick-reference/page-collections/#group
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate ($pages.GroupByDate "Jan 2006") }}
+
+{{ range $paginator.PageGroups }}
+ <h2>{{ .Key }}</h2>
+ {{ range .Pages }}
+ <h3><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h3>
+ {{ end }}
+{{ end }}
+
+{{ partial "pagination.html" . }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pager_PageNumber.md b/documents/markdown/hugo-docs/en_methods_pager_PageNumber.md
new file mode 100644
index 0000000..6d0b8e3
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pager_PageNumber.md
@@ -0,0 +1,29 @@
+---
+title: PageNumber
+description: Returns the current pager's number within the pager collection.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [PAGER.PageNumber]
+---
+
+Use the `PageNumber` method to build navigation between pagers.
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ <ul>
+ {{ range .Pagers }}
+ <li><a href="{{ .URL }}">{{ .PageNumber }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pager_PagerSize.md b/documents/markdown/hugo-docs/en_methods_pager_PagerSize.md
new file mode 100644
index 0000000..1bec9e4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pager_PagerSize.md
@@ -0,0 +1,29 @@
+---
+title: PagerSize
+description: Returns the number of pages per pager.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [PAGER.PagerSize]
+aliases: [/methods/pager/pagesize/]
+---
+
+The number of pages per pager is determined by the optional second argument passed to the [`Paginate`] method, falling back to the `pagerSize` as defined in your [project configuration].
+
+[`Paginate`]: /methods/page/paginate/
+[project configuration]: /templates/pagination/#configuration
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ {{ .PagerSize }}
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pager_Pagers.md b/documents/markdown/hugo-docs/en_methods_pager_Pagers.md
new file mode 100644
index 0000000..e431069
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pager_Pagers.md
@@ -0,0 +1,29 @@
+---
+title: Pagers
+description: Returns the pagers collection.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.pagers
+ signatures: [PAGER.Pagers]
+---
+
+Use the `Pagers` method to build navigation between pagers.
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ <ul>
+ {{ range .Pagers }}
+ <li><a href="{{ .URL }}">{{ .PageNumber }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pager_Pages.md b/documents/markdown/hugo-docs/en_methods_pager_Pages.md
new file mode 100644
index 0000000..bb5ac92
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pager_Pages.md
@@ -0,0 +1,21 @@
+---
+title: Pages
+description: Returns the pages in the current pager.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGER.Pages]
+---
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ partial "pagination.html" . }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pager_Prev.md b/documents/markdown/hugo-docs/en_methods_pager_Prev.md
new file mode 100644
index 0000000..eb79f96
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pager_Prev.md
@@ -0,0 +1,38 @@
+---
+title: Prev
+description: Returns the previous pager in the pager collection.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pager
+ signatures: [PAGER.Prev]
+---
+
+Use the `Prev` method to build navigation between pagers.
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ <ul>
+ {{ with .First }}
+ <li><a href="{{ .URL }}">First</a></li>
+ {{ end }}
+ {{ with .Prev }}
+ <li><a href="{{ .URL }}">Previous</a></li>
+ {{ end }}
+ {{ with .Next }}
+ <li><a href="{{ .URL }}">Next</a></li>
+ {{ end }}
+ {{ with .Last }}
+ <li><a href="{{ .URL }}">Last</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pager_TotalNumberOfElements.md b/documents/markdown/hugo-docs/en_methods_pager_TotalNumberOfElements.md
new file mode 100644
index 0000000..ad29a01
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pager_TotalNumberOfElements.md
@@ -0,0 +1,23 @@
+---
+title: TotalNumberOfElements
+description: Returns the number of pages in the pager collection.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [PAGER.TotalNumberOfElements]
+---
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ {{ .TotalNumberOfElements }}
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pager_TotalPages.md b/documents/markdown/hugo-docs/en_methods_pager_TotalPages.md
new file mode 100644
index 0000000..63da5d7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pager_TotalPages.md
@@ -0,0 +1,39 @@
+---
+title: TotalPages
+description: Returns the number of pagers in the pager collection.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [PAGER.TotalPages]
+---
+
+Use the `TotalPages` method to build navigation between pagers.
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ <p>Pager {{ .PageNumber }} of {{ .TotalPages }}</p>
+ <ul>
+ {{ with .First }}
+ <li><a href="{{ .URL }}">First</a></li>
+ {{ end }}
+ {{ with .Prev }}
+ <li><a href="{{ .URL }}">Previous</a></li>
+ {{ end }}
+ {{ with .Next }}
+ <li><a href="{{ .URL }}">Next</a></li>
+ {{ end }}
+ {{ with .Last }}
+ <li><a href="{{ .URL }}">Last</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pager_URL.md b/documents/markdown/hugo-docs/en_methods_pager_URL.md
new file mode 100644
index 0000000..a3558ba
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pager_URL.md
@@ -0,0 +1,38 @@
+---
+title: URL
+description: Returns the URL of the current pager relative to the site root.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [PAGER.URL]
+---
+
+Use the `URL` method to build navigation between pagers.
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ <ul>
+ {{ with .First }}
+ <li><a href="{{ .URL }}">First</a></li>
+ {{ end }}
+ {{ with .Prev }}
+ <li><a href="{{ .URL }}">Previous</a></li>
+ {{ end }}
+ {{ with .Next }}
+ <li><a href="{{ .URL }}">Next</a></li>
+ {{ end }}
+ {{ with .Last }}
+ <li><a href="{{ .URL }}">Last</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pager__index.md b/documents/markdown/hugo-docs/en_methods_pager__index.md
new file mode 100644
index 0000000..200640c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pager__index.md
@@ -0,0 +1,6 @@
+---
+title: Pager methods
+linkTitle: Pager
+description: Use these methods with a Pager object when building navigation for a paginated list page.
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_methods_pages_ByDate.md b/documents/markdown/hugo-docs/en_methods_pages_ByDate.md
new file mode 100644
index 0000000..5d1e339
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pages_ByDate.md
@@ -0,0 +1,28 @@
+---
+title: ByDate
+description: Returns the given page collection sorted by date in ascending order.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGES.ByDate]
+---
+
+When sorting by date, the value is determined by your [project configuration], defaulting to the `date` field in front matter.
+
+[project configuration]: /configuration/front-matter/#dates
+
+```go-html-template
+{{ range .Pages.ByDate }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+To sort in descending order:
+
+```go-html-template
+{{ range .Pages.ByDate.Reverse }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pages_ByExpiryDate.md b/documents/markdown/hugo-docs/en_methods_pages_ByExpiryDate.md
new file mode 100644
index 0000000..4f34c6e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pages_ByExpiryDate.md
@@ -0,0 +1,28 @@
+---
+title: ByExpiryDate
+description: Returns the given page collection sorted by expiration date in ascending order.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGES.ByExpiryDate]
+---
+
+When sorting by expiration date, the value is determined by your [project configuration], defaulting to the `expiryDate` field in front matter.
+
+[project configuration]: /configuration/front-matter/#dates
+
+```go-html-template
+{{ range .Pages.ByExpiryDate }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+To sort in descending order:
+
+```go-html-template
+{{ range .Pages.ByExpiryDate.Reverse }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pages_ByLanguage.md b/documents/markdown/hugo-docs/en_methods_pages_ByLanguage.md
new file mode 100644
index 0000000..751e1d8
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pages_ByLanguage.md
@@ -0,0 +1,45 @@
+---
+title: ByLanguage
+description: Returns the given page collection sorted by language.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGES.ByLanguage]
+---
+
+When sorting by language, Hugo orders the page collection using the following priority:
+
+1. Language weight (ascending)
+1. Date (descending)
+1. LinkTitle (ascending)
+
+This method is rarely, if ever, needed. Page collections that already contain multiple languages, such as those returned by the [`Rotate`][], [`Translations`][], or [`AllTranslations`][] methods on a `Page` object, are already sorted by language weight.
+
+This contrived example aggregates pages from all sites and then sorts them by language:
+
+```go-html-template
+{{ $p := slice }}
+{{ range hugo.Sites }}
+ {{ range .Pages }}
+ {{ $p = $p | append . }}
+ {{ end }}
+{{ end }}
+
+{{ range $p.ByLanguage }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+To sort in descending order:
+
+```go-html-template
+{{ range $p.ByLanguage.Reverse }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+[`AllTranslations`]: /methods/page/alltranslations/
+[`Rotate`]: /methods/page/rotate/
+[`Translations`]: /methods/page/translations/
diff --git a/documents/markdown/hugo-docs/en_methods_pages_ByLastmod.md b/documents/markdown/hugo-docs/en_methods_pages_ByLastmod.md
new file mode 100644
index 0000000..7fc865e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pages_ByLastmod.md
@@ -0,0 +1,28 @@
+---
+title: ByLastmod
+description: Returns the given page collection sorted by last modification date in ascending order.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGES.ByLastmod]
+---
+
+When sorting by last modification date, the value is determined by your [project configuration], defaulting to the `lastmod` field in front matter.
+
+[project configuration]: /configuration/front-matter/#dates
+
+```go-html-template
+{{ range .Pages.ByLastmod }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+To sort in descending order:
+
+```go-html-template
+{{ range .Pages.ByLastmod.Reverse }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pages_ByLength.md b/documents/markdown/hugo-docs/en_methods_pages_ByLength.md
new file mode 100644
index 0000000..c47bf98
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pages_ByLength.md
@@ -0,0 +1,24 @@
+---
+title: ByLength
+description: Returns the given page collection sorted by content length in ascending order.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGES.ByLength]
+---
+
+```go-html-template
+{{ range .Pages.ByLength }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+To sort in descending order:
+
+```go-html-template
+{{ range .Pages.ByLength.Reverse }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pages_ByLinkTitle.md b/documents/markdown/hugo-docs/en_methods_pages_ByLinkTitle.md
new file mode 100644
index 0000000..4a024d2
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pages_ByLinkTitle.md
@@ -0,0 +1,24 @@
+---
+title: ByLinkTitle
+description: Returns the given page collection sorted by link title in ascending order, falling back to title if link title is not defined.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGES.ByLinkTitle]
+---
+
+```go-html-template
+{{ range .Pages.ByLinkTitle }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+To sort in descending order:
+
+```go-html-template
+{{ range .Pages.ByLinkTitle.Reverse }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pages_ByParam.md b/documents/markdown/hugo-docs/en_methods_pages_ByParam.md
new file mode 100644
index 0000000..fcc9b28
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pages_ByParam.md
@@ -0,0 +1,34 @@
+---
+title: ByParam
+description: Returns the given page collection sorted by the given parameter in ascending order.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGES.ByParam PARAM]
+---
+
+If the given parameter is not present in front matter, Hugo will use the matching parameter in your project configuration if present.
+
+```go-html-template
+{{ range .Pages.ByParam "author" }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+To sort in descending order:
+
+```go-html-template
+{{ range (.Pages.ByParam "author").Reverse }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+If the targeted parameter is nested, access the field using dot notation:
+
+```go-html-template
+{{ range .Pages.ByParam "author.last_name" }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pages_ByPublishDate.md b/documents/markdown/hugo-docs/en_methods_pages_ByPublishDate.md
new file mode 100644
index 0000000..76d2b2b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pages_ByPublishDate.md
@@ -0,0 +1,28 @@
+---
+title: ByPublishDate
+description: Returns the given page collection sorted by publish date in ascending order.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGES.ByPublishDate]
+---
+
+When sorting by publish date, the value is determined by your [project configuration], defaulting to the `publishDate` field in front matter.
+
+[project configuration]: /configuration/front-matter/#dates
+
+```go-html-template
+{{ range .Pages.ByPublishDate }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+To sort in descending order:
+
+```go-html-template
+{{ range .Pages.ByPublishDate.Reverse }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pages_ByTitle.md b/documents/markdown/hugo-docs/en_methods_pages_ByTitle.md
new file mode 100644
index 0000000..e10c417
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pages_ByTitle.md
@@ -0,0 +1,24 @@
+---
+title: ByTitle
+description: Returns the given page collection sorted by title in ascending order.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGES.ByTitle]
+---
+
+```go-html-template
+{{ range .Pages.ByTitle }}
+ <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
+{{ end }}
+```
+
+To sort in descending order:
+
+```go-html-template
+{{ range .Pages.ByTitle.Reverse }}
+ <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pages_ByWeight.md b/documents/markdown/hugo-docs/en_methods_pages_ByWeight.md
new file mode 100644
index 0000000..ba255d3
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pages_ByWeight.md
@@ -0,0 +1,26 @@
+---
+title: ByWeight
+description: Returns the given page collection sorted by weight in ascending order.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGES.ByWeight]
+---
+
+Assign a [weight](g) to a page using the `weight` field in front matter. The weight must be a non-zero integer. Lighter items float to the top, while heavier items sink to the bottom. Unweighted or zero-weighted pages are placed at the end of the collection.
+
+```go-html-template
+{{ range .Pages.ByWeight }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+To sort in descending order:
+
+```go-html-template
+{{ range .Pages.ByWeight.Reverse }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pages_GroupBy.md b/documents/markdown/hugo-docs/en_methods_pages_GroupBy.md
new file mode 100644
index 0000000..aff0800
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pages_GroupBy.md
@@ -0,0 +1,36 @@
+---
+title: GroupBy
+description: Returns the given page collection grouped by the given field in ascending order.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.PagesGroup
+ signatures: ['PAGES.GroupBy FIELD [SORT]']
+---
+
+{{% include "/_common/methods/pages/group-sort-order.md" %}}
+
+```go-html-template
+{{ range .Pages.GroupBy "Section" }}
+ <p>{{ .Key }}</p>
+ <ul>
+ {{ range .Pages }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+To sort the groups in descending order:
+
+```go-html-template
+{{ range .Pages.GroupBy "Section" "desc" }}
+ <p>{{ .Key }}</p>
+ <ul>
+ {{ range .Pages }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pages_GroupByDate.md b/documents/markdown/hugo-docs/en_methods_pages_GroupByDate.md
new file mode 100644
index 0000000..19f7918
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pages_GroupByDate.md
@@ -0,0 +1,63 @@
+---
+title: GroupByDate
+description: Returns the given page collection grouped by date in descending order.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.PagesGroup
+ signatures: ['PAGES.GroupByDate LAYOUT [SORT]']
+---
+
+When grouping by date, the value is determined by your [project configuration], defaulting to the `date` field in front matter.
+
+The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized](g) for language and region.
+
+[`time.Format`]: /functions/time/format/
+[layout string]: #layout-string
+[project configuration]: /configuration/front-matter/#dates
+
+{{% include "/_common/methods/pages/group-sort-order.md" %}}
+
+To group content by year and month:
+
+```go-html-template
+{{ range .Pages.GroupByDate "January 2006" }}
+ <p>{{ .Key }}</p>
+ <ul>
+ {{ range .Pages }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+To sort the groups in ascending order:
+
+```go-html-template
+{{ range .Pages.GroupByDate "January 2006" "asc" }}
+ <p>{{ .Key }}</p>
+ <ul>
+ {{ range .Pages }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+The pages within each group will also be sorted by date, either ascending or descending depending on the grouping option. To sort the pages within each group, use one of the sorting methods. For example, to sort the pages within each group by title:
+
+```go-html-template
+{{ range .Pages.GroupByDate "January 2006" }}
+ <p>{{ .Key }}</p>
+ <ul>
+ {{ range .Pages.ByTitle }}
+ <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+## Layout string
+
+{{% include "/_common/time-layout-string.md" %}}
diff --git a/documents/markdown/hugo-docs/en_methods_pages_GroupByExpiryDate.md b/documents/markdown/hugo-docs/en_methods_pages_GroupByExpiryDate.md
new file mode 100644
index 0000000..7fe0282
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pages_GroupByExpiryDate.md
@@ -0,0 +1,63 @@
+---
+title: GroupByExpiryDate
+description: Returns the given page collection grouped by expiration date in descending order.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.PagesGroup
+ signatures: ['PAGES.GroupByExpiryDate LAYOUT [SORT]']
+---
+
+When grouping by expiration date, the value is determined by your [project configuration], defaulting to the `expiryDate` field in front matter.
+
+The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized](g) for language and region.
+
+[`time.Format`]: /functions/time/format/
+[layout string]: #layout-string
+[project configuration]: /configuration/front-matter/#dates
+
+{{% include "/_common/methods/pages/group-sort-order.md" %}}
+
+To group content by year and month:
+
+```go-html-template
+{{ range .Pages.GroupByExpiryDate "January 2006" }}
+ <p>{{ .Key }}</p>
+ <ul>
+ {{ range .Pages }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+To sort the groups in ascending order:
+
+```go-html-template
+{{ range .Pages.GroupByExpiryDate "January 2006" "asc" }}
+ <p>{{ .Key }}</p>
+ <ul>
+ {{ range .Pages }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+The pages within each group will also be sorted by expiration date, either ascending or descending depending on your grouping option. To sort the pages within each group, use one of the sorting methods. For example, to sort the pages within each group by title:
+
+```go-html-template
+{{ range .Pages.GroupByExpiryDate "January 2006" }}
+ <p>{{ .Key }}</p>
+ <ul>
+ {{ range .Pages.ByTitle }}
+ <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+## Layout string
+
+{{% include "/_common/time-layout-string.md" %}}
diff --git a/documents/markdown/hugo-docs/en_methods_pages_GroupByLastmod.md b/documents/markdown/hugo-docs/en_methods_pages_GroupByLastmod.md
new file mode 100644
index 0000000..45da5af
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pages_GroupByLastmod.md
@@ -0,0 +1,63 @@
+---
+title: GroupByLastmod
+description: Returns the given page collection grouped by last modification date in descending order.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.PagesGroup
+ signatures: ['PAGES.GroupByLastmod LAYOUT [SORT]']
+---
+
+When grouping by last modification date, the value is determined by your [project configuration], defaulting to the `lastmod` field in front matter.
+
+The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized](g) for language and region.
+
+[`time.Format`]: /functions/time/format/
+[layout string]: #layout-string
+[project configuration]: /configuration/front-matter/#dates
+
+{{% include "/_common/methods/pages/group-sort-order.md" %}}
+
+To group content by year and month:
+
+```go-html-template
+{{ range .Pages.GroupByLastmod "January 2006" }}
+ <p>{{ .Key }}</p>
+ <ul>
+ {{ range .Pages }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+To sort the groups in ascending order:
+
+```go-html-template
+{{ range .Pages.GroupByLastmod "January 2006" "asc" }}
+ <p>{{ .Key }}</p>
+ <ul>
+ {{ range .Pages }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+The pages within each group will also be sorted by last modification date, either ascending or descending depending on your grouping option. To sort the pages within each group, use one of the sorting methods. For example, to sort the pages within each group by title:
+
+```go-html-template
+{{ range .Pages.GroupByLastmod "January 2006" }}
+ <p>{{ .Key }}</p>
+ <ul>
+ {{ range .Pages.ByTitle }}
+ <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+## Layout string
+
+{{% include "/_common/time-layout-string.md" %}}
diff --git a/documents/markdown/hugo-docs/en_methods_pages_GroupByParam.md b/documents/markdown/hugo-docs/en_methods_pages_GroupByParam.md
new file mode 100644
index 0000000..6764144
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pages_GroupByParam.md
@@ -0,0 +1,36 @@
+---
+title: GroupByParam
+description: Returns the given page collection grouped by the given parameter in ascending order.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.PagesGroup
+ signatures: ['PAGES.GroupByParam PARAM [SORT]']
+---
+
+{{% include "/_common/methods/pages/group-sort-order.md" %}}
+
+```go-html-template
+{{ range .Pages.GroupByParam "color" }}
+ <p>{{ .Key | title }}</p>
+ <ul>
+ {{ range .Pages }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+To sort the groups in descending order:
+
+```go-html-template
+{{ range .Pages.GroupByParam "color" "desc" }}
+ <p>{{ .Key | title }}</p>
+ <ul>
+ {{ range .Pages }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pages_GroupByParamDate.md b/documents/markdown/hugo-docs/en_methods_pages_GroupByParamDate.md
new file mode 100644
index 0000000..b05a096
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pages_GroupByParamDate.md
@@ -0,0 +1,60 @@
+---
+title: GroupByParamDate
+description: Returns the given page collection grouped by the given date parameter in descending order.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.PagesGroup
+ signatures: ['PAGES.GroupByParamDate PARAM LAYOUT [SORT]']
+---
+
+The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized](g) for language and region.
+
+[`time.Format`]: /functions/time/format/
+[layout string]: #layout-string
+
+{{% include "/_common/methods/pages/group-sort-order.md" %}}
+
+To group content by year and month:
+
+```go-html-template
+{{ range .Pages.GroupByParamDate "eventDate" "January 2006" }}
+ <p>{{ .Key }}</p>
+ <ul>
+ {{ range .Pages }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+To sort the groups in ascending order:
+
+```go-html-template
+{{ range .Pages.GroupByParamDate "eventDate" "January 2006" "asc" }}
+ <p>{{ .Key }}</p>
+ <ul>
+ {{ range .Pages }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+The pages within each group will also be sorted by the parameter date, either ascending or descending depending on your grouping option. To sort the pages within each group, use one of the sorting methods. For example, to sort the pages within each group by title:
+
+```go-html-template
+{{ range .Pages.GroupByParamDate "eventDate" "January 2006" }}
+ <p>{{ .Key }}</p>
+ <ul>
+ {{ range .Pages.ByTitle }}
+ <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+## Layout string
+
+{{% include "/_common/time-layout-string.md" %}}
diff --git a/documents/markdown/hugo-docs/en_methods_pages_GroupByPublishDate.md b/documents/markdown/hugo-docs/en_methods_pages_GroupByPublishDate.md
new file mode 100644
index 0000000..629a848
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pages_GroupByPublishDate.md
@@ -0,0 +1,63 @@
+---
+title: GroupByPublishDate
+description: Returns the given page collection grouped by publish date in descending order.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.PagesGroup
+ signatures: ['PAGES.GroupByPublishDate LAYOUT [SORT]']
+---
+
+When grouping by publish date, the value is determined by your [project configuration], defaulting to the `publishDate` field in front matter.
+
+The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized](g) for language and region.
+
+[`time.Format`]: /functions/time/format/
+[layout string]: #layout-string
+[project configuration]: /configuration/front-matter/#dates
+
+{{% include "/_common/methods/pages/group-sort-order.md" %}}
+
+To group content by year and month:
+
+```go-html-template
+{{ range .Pages.GroupByPublishDate "January 2006" }}
+ <p>{{ .Key }}</p>
+ <ul>
+ {{ range .Pages }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+To sort the groups in ascending order:
+
+```go-html-template
+{{ range .Pages.GroupByPublishDate "January 2006" "asc" }}
+ <p>{{ .Key }}</p>
+ <ul>
+ {{ range .Pages }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+The pages within each group will also be sorted by publish date, either ascending or descending depending on your grouping option. To sort the pages within each group, use one of the sorting methods. For example, to sort the pages within each group by title:
+
+```go-html-template
+{{ range .Pages.GroupByPublishDate "January 2006" }}
+ <p>{{ .Key }}</p>
+ <ul>
+ {{ range .Pages.ByTitle }}
+ <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+## Layout string
+
+{{% include "/_common/time-layout-string.md" %}}
diff --git a/documents/markdown/hugo-docs/en_methods_pages_Len.md b/documents/markdown/hugo-docs/en_methods_pages_Len.md
new file mode 100644
index 0000000..85b3267
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pages_Len.md
@@ -0,0 +1,14 @@
+---
+title: Len
+description: Returns the number of pages in the given page collection.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [PAGES.Len]
+---
+
+```go-html-template
+{{ .Pages.Len }} → 42
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pages_Limit.md b/documents/markdown/hugo-docs/en_methods_pages_Limit.md
new file mode 100644
index 0000000..6ee3de2
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pages_Limit.md
@@ -0,0 +1,16 @@
+---
+title: Limit
+description: Returns the first N pages from the given page collection.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGES.Limit NUMBER]
+---
+
+```go-html-template
+{{ range .Pages.Limit 3 }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pages_Next.md b/documents/markdown/hugo-docs/en_methods_pages_Next.md
new file mode 100644
index 0000000..ce091c1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pages_Next.md
@@ -0,0 +1,12 @@
+---
+title: Next
+description: Returns the next page in a page collection, relative to the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Page
+ signatures: [PAGES.Next PAGE]
+---
+
+{{% include "/_common/methods/pages/next-and-prev.md" %}}
diff --git a/documents/markdown/hugo-docs/en_methods_pages_Prev.md b/documents/markdown/hugo-docs/en_methods_pages_Prev.md
new file mode 100644
index 0000000..004b949
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pages_Prev.md
@@ -0,0 +1,12 @@
+---
+title: Prev
+description: Returns the previous page in a page collection, relative to the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGES.Prev PAGE]
+---
+
+{{% include "/_common/methods/pages/next-and-prev.md" %}}
diff --git a/documents/markdown/hugo-docs/en_methods_pages_Related.md b/documents/markdown/hugo-docs/en_methods_pages_Related.md
new file mode 100644
index 0000000..6d38595
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pages_Related.md
@@ -0,0 +1,75 @@
+---
+title: Related
+description: Returns a collection of pages related to the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures:
+ - PAGES.Related PAGE
+ - PAGES.Related OPTIONS
+---
+
+Based on front matter, Hugo uses several factors to identify content related to the given page. Use the default [related content configuration], or tune the results to the desired indices and parameters. See [details].
+
+The argument passed to the `Related` method may be a `Page` or an options map. For example, to pass the current page:
+
+```go-html-template {file="layouts/page.html"}
+{{ with .Site.RegularPages.Related . | first 5 }}
+ <p>Related pages:</p>
+ <ul>
+ {{ range . }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+To pass an options map:
+
+```go-html-template {file="layouts/page.html"}
+{{ $opts := dict
+ "document" .
+ "indices" (slice "tags" "keywords")
+}}
+{{ with .Site.RegularPages.Related $opts | first 5 }}
+ <p>Related pages:</p>
+ <ul>
+ {{ range . }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+## Options
+
+indices
+: (`slice`) The indices to search within.
+
+document
+: (`page`) The page for which to find related content. Required when specifying an options map.
+
+namedSlices
+: (`slice`) The keywords to search for, expressed as a slice of `KeyValues` using the [`keyVals`] function.
+
+[`keyVals`]: /functions/collections/keyvals/
+
+fragments
+: (`slice`) A list of special keywords that is used for indices configured as type "fragments". This will match the [fragment](g) identifiers of the documents.
+
+A contrived example using all of the above:
+
+```go-html-template
+{{ $page := . }}
+{{ $opts := dict
+ "indices" (slice "tags" "keywords")
+ "document" $page
+ "namedSlices" (slice (keyVals "tags" "hugo" "rocks") (keyVals "date" $page.Date))
+ "fragments" (slice "heading-1" "heading-2")
+}}
+```
+
+[details]: /content-management/related-content/
+[related content configuration]: /configuration/related-content/
diff --git a/documents/markdown/hugo-docs/en_methods_pages_Reverse.md b/documents/markdown/hugo-docs/en_methods_pages_Reverse.md
new file mode 100644
index 0000000..23c4b03
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pages_Reverse.md
@@ -0,0 +1,16 @@
+---
+title: Reverse
+description: Returns the given page collection in reverse order.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGES.Reverse]
+---
+
+```go-html-template
+{{ range .Pages.ByDate.Reverse }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_pages__index.md b/documents/markdown/hugo-docs/en_methods_pages__index.md
new file mode 100644
index 0000000..f2495ae
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_pages__index.md
@@ -0,0 +1,8 @@
+---
+title: Pages methods
+linkTitle: Pages
+description: Use these methods with a collection of Page objects.
+categories: []
+keywords: []
+aliases: [/variables/pages]
+---
diff --git a/documents/markdown/hugo-docs/en_methods_resource_Colors.md b/documents/markdown/hugo-docs/en_methods_resource_Colors.md
new file mode 100644
index 0000000..b249068
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_resource_Colors.md
@@ -0,0 +1,176 @@
+---
+title: Colors
+description: Applicable to images, returns a slice of the most dominant colors using a simple histogram method.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: '[]images.Color'
+ signatures: [RESOURCE.Colors]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
+The `Colors` method returns a slice of the most dominant colors in a [processable image](g), ordered from most dominant to least dominant.
+
+> [!note]
+> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
+
+## Usage
+
+This method is fast, but if you downscale your image first, you can further improve performance by extracting colors from the smaller resource.
+
+## Methods
+
+Each color in the slice is an object with the following methods:
+
+### ColorHex
+
+(`string`) Returns the [hexadecimal color][] value, prefixed with a hash sign.
+
+### Luminance
+
+(`float64`) Returns the [relative luminance][] of the color in the sRGB colorspace in the range [0, 1]. A value of `0` represents the darkest black, while a value of `1` represents the lightest white.
+
+> [!note]
+> Image filters such as [`images.Dither`][], [`images.Padding`][], and [`images.Text`][] accept either hexadecimal color values or `images.Color` objects as arguments. Hugo renders an `images.Color` object as a hexadecimal color value.
+
+## Sorting
+
+As a contrived example, create a table of an image's dominant colors with the most dominant color first, and display the relative luminance of each dominant color:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ <table>
+ <thead>
+ <tr>
+ <th>Color</th>
+ <th>Relative luminance</th>
+ </tr>
+ </thead>
+ <tbody>
+ {{ range .Colors }}
+ <tr>
+ <td>{{ .ColorHex }}</td>
+ <td>{{ .Luminance | lang.FormatNumber 4 }}</td>
+ </tr>
+ {{ end }}
+ </tbody>
+ </table>
+{{ end }}
+```
+
+Hugo renders this to:
+
+ColorHex|Relative luminance
+:--|:--
+`#bebebd`|`0.5145`
+`#514947`|`0.0697`
+`#768a9a`|`0.2436`
+`#647789`|`0.1771`
+`#90725e`|`0.1877`
+`#a48974`|`0.2704`
+
+To sort by dominance with the least dominant color first:
+
+```go-html-template
+{{ range .Colors | collections.Reverse }}
+```
+
+To sort by relative luminance with the darkest color first:
+
+```go-html-template
+{{ range sort .Colors "Luminance" }}
+```
+
+To sort by relative luminance with the lightest color first, use either of these constructs:
+
+```go-html-template
+{{ range sort .Colors "Luminance" | collections.Reverse }}
+{{ range sort .Colors "Luminance" "desc" }}
+```
+
+## Examples
+
+### Image borders
+
+To add a 5 pixel border to an image using the most dominant color:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ $mostDominant := index .Colors 0 }}
+ {{ $filter := images.Padding 5 $mostDominant }}
+ {{ with .Filter $filter }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+To add a 5 pixel border to an image using the darkest dominant color:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ $darkest := index (sort .Colors "Luminance") 0 }}
+ {{ $filter := images.Padding 5 $darkest }}
+ {{ with .Filter $filter }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+### Light text on dark background
+
+To create a text box where the foreground and background colors are derived from an image's lightest and darkest dominant colors:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ $darkest := index (sort .Colors "Luminance") 0 }}
+ {{ $lightest := index (sort .Colors "Luminance" "desc") 0 }}
+ <div style="background: {{ $darkest }};">
+ <div style="color: {{ $lightest }};">
+ <p>This is light text on a dark background.</p>
+ </div>
+ </div>
+{{ end }}
+```
+
+### WCAG contrast ratio
+
+In the previous example we placed light text on a dark background, but does this color combination conform to [WCAG][] guidelines for either the [minimum][] or the [enhanced][] contrast ratio?
+
+The WCAG defines the [contrast ratio][] as:
+
+$$contrast\ ratio = { L_1 + 0.05 \over L_2 + 0.05 }$$
+
+where \(L_1\) is the relative luminance of the lightest color and \(L_2\) is the relative luminance of the darkest color.
+
+Calculate the contrast ratio to determine WCAG conformance:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ $lightest := index (sort .Colors "Luminance" "desc") 0 }}
+ {{ $darkest := index (sort .Colors "Luminance") 0 }}
+ {{ $cr := div
+ (add $lightest.Luminance 0.05)
+ (add $darkest.Luminance 0.05)
+ }}
+ {{ if ge $cr 7.5 }}
+ {{ printf "The %.2f contrast ratio conforms to WCAG Level AAA." $cr }}
+ {{ else if ge $cr 4.5 }}
+ {{ printf "The %.2f contrast ratio conforms to WCAG Level AA." $cr }}
+ {{ else }}
+ {{ printf "The %.2f contrast ratio does not conform to WCAG guidelines." $cr }}
+ {{ end }}
+{{ end }}
+```
+
+[WCAG]: https://en.wikipedia.org/wiki/Web_Content_Accessibility_Guidelines
+[`images.Dither`]: /functions/images/dither/
+[`images.Padding`]: /functions/images/padding/
+[`images.Text`]: /functions/images/text/
+[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
+[contrast ratio]: https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio
+[enhanced]: https://www.w3.org/WAI/WCAG22/quickref/?showtechniques=145#contrast-enhanced
+[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
+[minimum]: https://www.w3.org/WAI/WCAG22/quickref/?showtechniques=145#contrast-minimum
+[relative luminance]: https://www.w3.org/TR/WCAG21/#dfn-relative-luminance
diff --git a/documents/markdown/hugo-docs/en_methods_resource_Content.md b/documents/markdown/hugo-docs/en_methods_resource_Content.md
new file mode 100644
index 0000000..ff2ad6d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_resource_Content.md
@@ -0,0 +1,60 @@
+---
+title: Content
+description: Returns the content of the given resource.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: any
+ signatures: [RESOURCE.Content]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
+The `Content` method on a `Resource` object returns `template.HTML` when the [resource type] is `page`, otherwise it returns a `string`.
+
+[resource type]: /methods/resource/resourcetype/
+
+```text {file="assets/quotations/kipling.txt"}
+He travels the fastest who travels alone.
+```
+
+To get the content:
+
+```go-html-template
+{{ with resources.Get "quotations/kipling.txt" }}
+ {{ .Content }} → He travels the fastest who travels alone.
+{{ end }}
+```
+
+To get the size in bytes:
+
+```go-html-template
+{{ with resources.Get "quotations/kipling.txt" }}
+ {{ .Content | len }} → 42
+{{ end }}
+```
+
+To create an inline image:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ <img src="data:{{ .MediaType.Type }};base64,{{ .Content | base64Encode }}">
+{{ end }}
+```
+
+To create inline CSS:
+
+```go-html-template
+{{ with resources.Get "css/style.css" }}
+ <style>{{ .Content | safeCSS }}</style>
+{{ end }}
+```
+
+To create inline JavaScript:
+
+```go-html-template
+{{ with resources.Get "js/script.js" }}
+ <script>{{ .Content | safeJS }}</script>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_resource_Crop.md b/documents/markdown/hugo-docs/en_methods_resource_Crop.md
new file mode 100644
index 0000000..e764be1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_resource_Crop.md
@@ -0,0 +1,54 @@
+---
+title: Crop
+description: Applicable to images, returns a new image resource cropped according to the given processing specification.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: images.ImageResource
+ signatures: [RESOURCE.Crop SPECIFICATION]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
+The `Crop` method returns a new resource from a [processable image](g) according to the given [processing specification][].
+
+> [!note]
+> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
+
+## Usage
+
+When cropping, you must provide both width and height (such as `200x200`) within the specification. This method does not perform any resizing; it simply extracts a region of the image based on the dimensions and the [anchor](#anchor) provided, if any.
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Crop "200x200 TopRight" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+In the example above, `"200x200 TopRight"` is the processing specification.
+
+{{% include "/_common/methods/resource/processing-spec.md" %}}
+
+## Example
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Crop "200x200 TopRight" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Process"
+ filterArgs="crop 200x200 TopRight"
+ example=true
+>}}
+
+[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
+[processing specification]: #processing-specification
diff --git a/documents/markdown/hugo-docs/en_methods_resource_Data.md b/documents/markdown/hugo-docs/en_methods_resource_Data.md
new file mode 100644
index 0000000..01b2282
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_resource_Data.md
@@ -0,0 +1,64 @@
+---
+title: Data
+description: Applicable to resources returned by the resources.GetRemote function, returns information from the HTTP response.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: map
+ signatures: [RESOURCE.Data]
+---
+
+The `Data` method on a resource returned by the [`resources.GetRemote`] function returns information from the HTTP response.
+
+## Example
+
+```go-html-template
+{{ $url := "https://example.org/images/a.jpg" }}
+{{ $opts := dict "responseHeaders" (slice "Server") }}
+{{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else with .Value }}
+ {{ with .Data }}
+ {{ .ContentLength }} → 42764
+ {{ .ContentType }} → image/jpeg
+ {{ .Headers }} → map[Server:[Netlify]]
+ {{ .Status }} → 200 OK
+ {{ .StatusCode }} → 200
+ {{ .TransferEncoding }} → []
+ {{ end }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+ {{ end }}
+{{ end }}
+```
+
+## Methods
+
+### ContentLength
+
+(`int`) The content length in bytes.
+
+### ContentType
+
+(`string`) The content type.
+
+### Headers
+
+(`map[string][]string`) A map of response headers matching those requested in the [`responseHeaders`] option passed to the `resources.GetRemote` function. The header name matching is case-insensitive. In most cases there will be one value per header key.
+
+### Status
+
+(`string`) The HTTP status text.
+
+### StatusCode
+
+(`int`) The HTTP status code.
+
+### TransferEncoding
+
+(`string`) The transfer encoding.
+
+[`resources.GetRemote`]: /functions/resources/getremote/
+[`responseHeaders`]: /functions/resources/getremote/#responseheaders
diff --git a/documents/markdown/hugo-docs/en_methods_resource_Err.md b/documents/markdown/hugo-docs/en_methods_resource_Err.md
new file mode 100644
index 0000000..aa0d076
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_resource_Err.md
@@ -0,0 +1,17 @@
+---
+title: Err
+description: Applicable to resources returned by the resources.GetRemote function, returns an error message if the HTTP request fails, else nil.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: resource.resourceError
+ signatures: [RESOURCE.Err]
+expiryDate: 2027-01-16 # deprecated 2025-01-16 in v0.141.0
+---
+
+{{< deprecated-in 0.141.0 >}}
+Use the `try` statement instead. See [example].
+
+[example]: /functions/go-template/try/#example
+{{< /deprecated-in >}}
diff --git a/documents/markdown/hugo-docs/en_methods_resource_Exif.md b/documents/markdown/hugo-docs/en_methods_resource_Exif.md
new file mode 100644
index 0000000..bc060f4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_resource_Exif.md
@@ -0,0 +1,15 @@
+---
+title: Exif
+description: Returns an object containing Exif metadata for supported image formats.
+categories: []
+keywords: ['metadata']
+params:
+ functions_and_methods:
+ returnType: meta.ExifInfo
+ signatures: [RESOURCE.Exif]
+expiryDate: 2028-01-28 # deprecated 2026-01-28 in v0.155.0
+---
+
+{{< deprecated-in 0.155.0 >}}
+Use [`Meta`](/methods/resource/meta/) instead.
+{{< /deprecated-in >}}
diff --git a/documents/markdown/hugo-docs/en_methods_resource_Fill.md b/documents/markdown/hugo-docs/en_methods_resource_Fill.md
new file mode 100644
index 0000000..c510afe
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_resource_Fill.md
@@ -0,0 +1,54 @@
+---
+title: Fill
+description: Applicable to images, returns a new image resource cropped and resized according to the given processing specification.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: images.ImageResource
+ signatures: [RESOURCE.Fill SPECIFICATION]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
+The `Fill` method returns a new resource from a [processable image](g) according to the given [processing specification][].
+
+> [!note]
+> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
+
+## Usage
+
+When filling, you must provide both width and height (such as `500x200`) within the specification. `Fill` maintains the original aspect ratio by resizing the image to cover the target area and cropping any overflowing pixels based on the [anchor](#anchor) provided.
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Fill "500x200 TopRight" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+In the example above, `"500x200 TopRight"` is the _processing specification.
+
+{{% include "/_common/methods/resource/processing-spec.md" %}}
+
+## Example
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Fill "500x200 TopRight" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Process"
+ filterArgs="fill 500x200 TopRight"
+ example=true
+>}}
+
+[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
+[processing specification]: #processing-specification
diff --git a/documents/markdown/hugo-docs/en_methods_resource_Filter.md b/documents/markdown/hugo-docs/en_methods_resource_Filter.md
new file mode 100644
index 0000000..812466a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_resource_Filter.md
@@ -0,0 +1,75 @@
+---
+title: Filter
+description: Applicable to images, applies one or more image filters to the given image resource.
+categories: []
+keywords: [filter]
+params:
+ alt_title: RESOURCE.Filter
+ functions_and_methods:
+ returnType: images.ImageResource
+ signatures: [RESOURCE.Filter FILTER...]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
+The `Filter` method returns a new resource from a [processable image](g) after applying one or more [image filters](#image-filters).
+
+> [!note]
+> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
+
+## Usage
+
+Use the `Filter` method to apply effects such as blurring, sharpening, or grayscale conversion. You can pass a single filter or a slice of filters. When providing a slice, Hugo applies the filters from left to right.
+
+To apply a single filter:
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Filter images.Grayscale }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+To apply multiple filters:
+
+```go-html-template
+{{ $filters := slice
+ images.Grayscale
+ (images.GaussianBlur 8)
+}}
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Filter $filters }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+You can also apply image filters using the [`images.Filter`][] function.
+
+## Example
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Filter images.Grayscale }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Grayscale"
+ filterArgs=""
+ example=true
+>}}
+
+## Image filters
+
+Use any of these filters with the `Filter` method.
+
+{{% render-list-of-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude %}}
+
+[`images.Filter`]: /functions/images/filter/
+[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
diff --git a/documents/markdown/hugo-docs/en_methods_resource_Fit.md b/documents/markdown/hugo-docs/en_methods_resource_Fit.md
new file mode 100644
index 0000000..2c0a7c9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_resource_Fit.md
@@ -0,0 +1,56 @@
+---
+title: Fit
+description: Applicable to images, returns a new image resource downscaled to fit according to the given processing specification.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: images.ImageResource
+ signatures: [RESOURCE.Fit SPECIFICATION]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
+The `Fit` method returns a new resource from a [processable image](g) according to the given [processing specification][].
+
+> [!note]
+> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
+
+## Usage
+
+When fitting, you must provide both width and height (such as `300x175`) within the specification. `Fit` maintains the original aspect ratio by downscaling the image until it fits within the specified dimensions. Unlike [`Fill`][] or [`Resize`][], this method will never upscale an image; if the source image is smaller than the target dimensions, the dimensions of the resulting image are the same as the original.
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Fit "300x175" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+In the example above, `"300x175"` is the processing specification.
+
+{{% include "/_common/methods/resource/processing-spec.md" %}}
+
+## Example
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Fit "300x175" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Process"
+ filterArgs="fit 300x175"
+ example=true
+>}}
+
+[`Fill`]: /methods/resource/fill/
+[`Resize`]: /methods/resource/resize/
+[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
+[processing specification]: #processing-specification
diff --git a/documents/markdown/hugo-docs/en_methods_resource_Height.md b/documents/markdown/hugo-docs/en_methods_resource_Height.md
new file mode 100644
index 0000000..726802c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_resource_Height.md
@@ -0,0 +1,26 @@
+---
+title: Height
+description: Applicable to images, returns the height of the given resource.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [RESOURCE.Height]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
+Use the [`reflect.IsImageResourceWithMeta`][] function to verify that Hugo can determine the dimensions before calling the `Height` method.
+
+```go-html-template
+{{ with resources.GetMatch "images/featured.*" }}
+ {{ if reflect.IsImageResourceWithMeta . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ else }}
+ <img src="{{ .RelPermalink }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+[`reflect.IsImageResourceWithMeta`]: /functions/reflect/isimageresourcewithmeta/
diff --git a/documents/markdown/hugo-docs/en_methods_resource_MediaType.md b/documents/markdown/hugo-docs/en_methods_resource_MediaType.md
new file mode 100644
index 0000000..7721f69
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_resource_MediaType.md
@@ -0,0 +1,66 @@
+---
+title: MediaType
+description: Returns a media type object for the given resource.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: media.Type
+ signatures: [RESOURCE.MediaType]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
+The `MediaType` method on a `Resource` object returns an object with additional methods.
+
+## Methods
+
+### Type
+
+(`string`) The resource's media type.
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ .MediaType.Type }} → image/jpeg
+{{ end }}
+```
+
+### MainType
+
+(`string`) The main type of the resource's media type.
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ .MediaType.MainType }} → image
+{{ end }}
+```
+
+### SubType
+
+(`string`) The subtype of the resource's media type. This may or may not correspond to the file suffix.
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ .MediaType.SubType }} → jpeg
+{{ end }}
+```
+
+### Suffixes
+
+(`slice`) A slice of possible file suffixes for the resource's media type.
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ .MediaType.Suffixes }} → [jpg jpeg jpe jif jfif]
+{{ end }}
+```
+
+### FirstSuffix.Suffix
+
+(`string`) The first of the possible file suffixes for the resource's media type.
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ .MediaType.FirstSuffix.Suffix }} → jpg
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_resource_Meta.md b/documents/markdown/hugo-docs/en_methods_resource_Meta.md
new file mode 100644
index 0000000..8a992ba
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_resource_Meta.md
@@ -0,0 +1,110 @@
+---
+title: Meta
+description: Applicable to images, returns an object containing Exif, IPTC, and XMP metadata for supported image formats.
+categories: []
+keywords: ['metadata']
+params:
+ functions_and_methods:
+ returnType: meta.MetaInfo
+ signatures: [RESOURCE.Meta]
+---
+
+{{< new-in 0.155.3 />}}
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
+The `Meta` method on an image `Resource` object returns an object containing [Exif][Exif_Definition], [IPTC][IPTC_Definition], and [XMP][XMP_Definition] metadata.
+
+While Hugo classifies many file types as images, only certain formats support metadata extraction. Supported formats include AVIF, BMP, GIF, HEIC, HEIF, JPEG, PNG, TIFF, and WebP.
+
+> [!note]
+> Metadata is not preserved during image transformation. Use this method with the _original_ image resource to extract metadata from supported formats.
+
+## Usage
+
+Use the [`reflect.IsImageResourceWithMeta`][] function to verify that a resource supports metadata extraction before calling the `Meta` method.
+
+```go-html-template
+{{ with resources.GetMatch "images/featured.*" }}
+ {{ if reflect.IsImageResourceWithMeta . }}
+ {{ with .Meta }}
+ {{ .Date.Format "2006-01-02" }}
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+## Methods
+
+### Date
+
+(`time.Time`) Returns the image creation date/time. Format with the [`time.Format`][] function.
+
+### Lat
+
+(`float64`) Returns the GPS latitude in degrees from Exif metadata, with a fallback to XMP metadata.
+
+### Long
+
+(`float64`) Returns the GPS longitude in degrees from Exif metadata, with a fallback to XMP metadata.
+
+### Orientation
+
+(`int`) Returns the value of the Exif `Orientation` tag, one of eight possible values.
+
+Value|Description
+:--|:--
+`1`|Horizontal (normal)
+`2`|Mirrored horizontal
+`3`|Rotated 180 degrees
+`4`|Mirrored vertical
+`5`|Mirrored horizontal and rotated 270 degrees clockwise
+`6`|Rotated 90 degrees clockwise
+`7`|Mirrored horizontal and rotated 90 degrees clockwise
+`8`|Rotated 270 degrees clockwise
+{class="!mt-0"}
+
+> [!tip]
+> Use the [`images.AutoOrient`][] image filter to rotate and flip an image as needed per its Exif orientation tag
+
+### Exif
+
+(`meta.Tags`) Returns a collection of available Exif fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your project configuration.
+
+### IPTC
+
+(`meta.Tags`) Returns a collection of available IPTC fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your project configuration.
+
+### XMP
+
+(`meta.Tags`) Returns a collection of available XMP fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your project configuration.
+
+## Examples
+
+To list the creation date, latitude, longitude, and orientation:
+
+```go-html-template
+{{ with resources.GetMatch "images/featured.*" }}
+ {{ if reflect.IsImageResourceWithMeta . }}
+ {{ with .Meta }}
+ <pre>
+ {{ printf "%-25s %v\n" "Date" .Date }}
+ {{ printf "%-25s %v\n" "Latitude" .Lat }}
+ {{ printf "%-25s %v\n" "Longitude" .Long }}
+ {{ printf "%-25s %v\n" "Orientation" .Orientation }}
+ </pre>
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+{{% include "/_common/functions/reflect/image-reflection-functions.md" %}}
+
+[`fields`]: /configuration/imaging/#fields
+[`images.AutoOrient`]: /functions/images/autoorient/
+[`reflect.IsImageResourceWithMeta`]: /functions/reflect/isimageresourcewithmeta/
+[`sources`]: /configuration/imaging/#sources
+[`time.Format`]: /functions/time/format/
+[Exif_Definition]: https://en.wikipedia.org/wiki/Exif
+[IPTC_Definition]: https://en.wikipedia.org/wiki/IPTC_Information_Interchange_Model
+[XMP_Definition]: https://en.wikipedia.org/wiki/Extensible_Metadata_Platform
diff --git a/documents/markdown/hugo-docs/en_methods_resource_Name.md b/documents/markdown/hugo-docs/en_methods_resource_Name.md
new file mode 100644
index 0000000..3331bb5
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_resource_Name.md
@@ -0,0 +1,89 @@
+---
+title: Name
+description: Returns the name of the given resource as optionally defined in front matter, falling back to its file path.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [RESOURCE.Name]
+---
+
+The value returned by the `Name` method on a `Resource` object depends on the resource type.
+
+## Global resource
+
+With a [global resource](g), the `Name` method returns the path to the resource, relative to the `assets` directory.
+
+```text
+assets/
+└── images/
+ └── Sunrise in Bryce Canyon.jpg
+```
+
+```go-html-template
+{{ with resources.Get "images/Sunrise in Bryce Canyon.jpg" }}
+ {{ .Name }} → /images/Sunrise in Bryce Canyon.jpg
+{{ end }}
+```
+
+## Page resource
+
+With a [page resource](g), if you create an element in the `resources` array in front matter, the `Name` method returns the value of the `name` parameter.
+
+```text
+content/
+├── example/
+│ ├── images/
+│ │ └── a.jpg
+│ └── index.md
+└── _index.md
+```
+
+{{< code-toggle file=content/example/index.md fm=true >}}
+title = 'Example'
+[[resources]]
+src = 'images/a.jpg'
+name = 'Sunrise in Bryce Canyon'
+{{< /code-toggle >}}
+
+```go-html-template
+{{ with .Resources.Get "images/a.jpg" }}
+ {{ .Name }} → Sunrise in Bryce Canyon
+{{ end }}
+```
+
+You can also capture the image by specifying its `name` instead of its path:
+
+```go-html-template
+{{ with .Resources.Get "Sunrise in Bryce Canyon" }}
+ {{ .Name }} → Sunrise in Bryce Canyon
+{{ end }}
+```
+
+If you do not create an element in the `resources` array in front matter, the `Name` method returns the file path, relative to the page bundle.
+
+```text
+content/
+├── example/
+│ ├── images/
+│ │ └── Sunrise in Bryce Canyon.jpg
+│ └── index.md
+└── _index.md
+```
+
+```go-html-template
+{{ with .Resources.Get "images/Sunrise in Bryce Canyon.jpg" }}
+ {{ .Name }} → images/Sunrise in Bryce Canyon.jpg
+{{ end }}
+```
+
+## Remote resource
+
+With a [remote resource](g), the `Name` method returns a hashed file name.
+
+```go-html-template
+{{ with resources.GetRemote "https://example.org/images/a.jpg" }}
+ {{ .Name }} → /a_18432433023265451104.jpg
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_resource_Params.md b/documents/markdown/hugo-docs/en_methods_resource_Params.md
new file mode 100644
index 0000000..38f2ef6
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_resource_Params.md
@@ -0,0 +1,61 @@
+---
+title: Params
+description: Returns a map of resource parameters as defined in front matter.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: map
+ signatures: [RESOURCE.Params]
+---
+
+Use the `Params` method with [page resources](g). It is not applicable to either [global resources](g) or [remote resources](g).
+
+With this content structure:
+
+```text
+content/
+├── posts/
+│ ├── cats/
+│ │ ├── images/
+│ │ │ └── a.jpg
+│ │ └── index.md
+│ └── _index.md
+└── _index.md
+```
+
+And this front matter:
+
+{{< code-toggle file=content/posts/cats.md fm=true >}}
+title = 'Cats'
+[[resources]]
+ src = 'images/a.jpg'
+ title = 'Felix the cat'
+ [resources.params]
+ alt = 'Photograph of black cat'
+ temperament = 'vicious'
+{{< /code-toggle >}}
+
+And this template:
+
+```go-html-template
+{{ with .Resources.Get "images/a.jpg" }}
+ <figure>
+ <img alt="{{ .Params.alt }}" src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+ <figcaption>{{ .Title }} is {{ .Params.temperament }}</figcaption>
+ </figure>
+{{ end }}
+```
+
+Hugo renders:
+
+```html
+<figure>
+ <img alt="Photograph of black cat" src="/posts/post-1/images/a.jpg" width="600" height="400">
+ <figcaption>Felix the cat is vicious</figcaption>
+</figure>
+```
+
+See the [page resources] section for more information.
+
+[page resources]: /content-management/page-resources/
diff --git a/documents/markdown/hugo-docs/en_methods_resource_Permalink.md b/documents/markdown/hugo-docs/en_methods_resource_Permalink.md
new file mode 100644
index 0000000..a8ec2d3
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_resource_Permalink.md
@@ -0,0 +1,20 @@
+---
+title: Permalink
+description: Publishes the given resource and returns its permalink.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [RESOURCE.Permalink]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
+The `Permalink` method on a `Resource` object writes the resource to the publish directory, typically `public`, and returns its [permalink](g).
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ .Permalink }} → https://example.org/images/a.jpg
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_resource_Process.md b/documents/markdown/hugo-docs/en_methods_resource_Process.md
new file mode 100644
index 0000000..9edb086
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_resource_Process.md
@@ -0,0 +1,70 @@
+---
+title: Process
+description: Applicable to images, returns a new image resource processed according to the given processing specification.
+categories: []
+keywords: [process]
+params:
+ alt_title: RESOURCE.Process
+ functions_and_methods:
+ returnType: images.ImageResource
+ signatures: [RESOURCE.Process SPECIFICATION]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
+The `Process` method returns a new resource from a [processable image](g) according to the given [processing specification][].
+
+> [!note]
+> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
+
+## Usage
+
+This versatile method supports the full range of image transformations including resizing, cropping, rotation, and format conversion within a single specification string. Unlike specialized methods such as [`Resize`][] or [`Crop`][], you must explicitly include the [action](#action) in the specification if you are changing the image dimensions.
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Process "crop 200x200 TopRight webp q50" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+In the example above, `"crop 200x200 TopRight webp q50"` is the processing specification.
+
+You can also use this method to apply simple transformations such as rotation and conversion:
+
+```go-html-template
+{{/* Rotate 90 degrees counter-clockwise. */}}
+{{ $image := $image.Process "r90" }}
+
+{{/* Convert to WebP. */}}
+{{ $image := $image.Process "webp" }}
+```
+
+The `Process` method is also available as a filter. This is more effective if you need to apply multiple filters to an image. See [`images.Process`][].
+
+{{% include "/_common/methods/resource/processing-spec.md" %}}
+
+## Example
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Process "crop 200x200 TopRight webp q50" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Process"
+ filterArgs="crop 200x200 TopRight webp q50"
+ example=true
+>}}
+
+[`Crop`]: /methods/resource/crop/
+[`Resize`]: /methods/resource/resize/
+[`images.Process`]: /functions/images/process/
+[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
+[processing specification]: #processing-specification
diff --git a/documents/markdown/hugo-docs/en_methods_resource_Publish.md b/documents/markdown/hugo-docs/en_methods_resource_Publish.md
new file mode 100644
index 0000000..0ecdf7e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_resource_Publish.md
@@ -0,0 +1,32 @@
+---
+title: Publish
+description: Publishes the given resource.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: nil
+ signatures: [RESOURCE.Publish]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
+The `Publish` method on a `Resource` object writes the resource to the publish directory, typically `public`.
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ .Publish }}
+{{ end }}
+```
+
+The `Permalink` and `RelPermalink` methods also publish a resource. `Publish` is a convenience method for publishing without a return value. For example, this:
+
+```go-html-template
+{{ $resource.Publish }}
+```
+
+Instead of this:
+
+```go-html-template
+{{ $noop := $resource.Permalink }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_resource_RelPermalink.md b/documents/markdown/hugo-docs/en_methods_resource_RelPermalink.md
new file mode 100644
index 0000000..d4c907b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_resource_RelPermalink.md
@@ -0,0 +1,20 @@
+---
+title: RelPermalink
+description: Publishes the given resource and returns its relative permalink.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [RESOURCE.RelPermalink]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
+The `Permalink` method on a `Resource` object writes the resource to the publish directory, typically `public`, and returns its [relative permalink](g).
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ .RelPermalink }} → /images/a.jpg
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_resource_Resize.md b/documents/markdown/hugo-docs/en_methods_resource_Resize.md
new file mode 100644
index 0000000..f1e08db
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_resource_Resize.md
@@ -0,0 +1,56 @@
+---
+title: Resize
+description: Applicable to images, returns a new image resource resized according to the given processing specification.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: images.ImageResource
+ signatures: [RESOURCE.Resize SPECIFICATION]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
+The `Resize` method returns a new resource from a [processable image](g) according to the given [processing specification][].
+
+> [!note]
+> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
+
+## Usage
+
+Resize an image according to the given processing specification. You may specify only the width (such as `300x`) or only the height (such as `x150`) for proportional scaling.
+
+If you specify both width and height (such as `300x150`), the resulting image will be scaled to those exact dimensions. If the target aspect ratio differs from the original, the image will be non-proportionally scaled (stretched or squashed).
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Resize "300x" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+In the example above, `"300x"` is the processing specification.
+
+{{% include "/_common/methods/resource/processing-spec.md" %}}
+
+## Example
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Resize "300x" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Process"
+ filterArgs="resize 300x"
+ example=true
+>}}
+
+[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
+[processing specification]: #processing-specification
diff --git a/documents/markdown/hugo-docs/en_methods_resource_ResourceType.md b/documents/markdown/hugo-docs/en_methods_resource_ResourceType.md
new file mode 100644
index 0000000..70dc591
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_resource_ResourceType.md
@@ -0,0 +1,43 @@
+---
+title: ResourceType
+description: Returns the main type of the given resource's media type.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [RESOURCE.ResourceType]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
+Common resource types include `audio`, `image`, `text`, and `video`.
+
+```go-html-template
+{{ with resources.Get "image/a.jpg" }}
+ {{ .ResourceType }} → image
+ {{ .MediaType.MainType }} → image
+{{ end }}
+```
+
+When working with content files, the resource type is `page`.
+
+```text
+content/
+├── lessons/
+│ ├── lesson-1/
+│ │ ├── _objectives.md <-- resource type = page
+│ │ ├── _topics.md <-- resource type = page
+│ │ ├── _example.jpg <-- resource type = image
+│ │ └── index.md
+│ └── _index.md
+└── _index.md
+```
+
+With the structure above, we can range through page resources of type `page` to build content:
+
+```go-html-template {file="layouts/lessons/page.html"}
+{{ range .Resources.ByType "page" }}
+ {{ .Content }}
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_resource_Title.md b/documents/markdown/hugo-docs/en_methods_resource_Title.md
new file mode 100644
index 0000000..c02d29f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_resource_Title.md
@@ -0,0 +1,81 @@
+---
+title: Title
+description: Returns the title of the given resource as optionally defined in front matter, falling back to a relative path or hashed file name depending on resource type.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [RESOURCE.Title]
+---
+
+The value returned by the `Title` method on a `Resource` object depends on the resource type.
+
+## Global resource
+
+With a [global resource](g), the `Title` method returns the path to the resource, relative to the `assets` directory.
+
+```text
+assets/
+└── images/
+ └── Sunrise in Bryce Canyon.jpg
+```
+
+```go-html-template
+{{ with resources.Get "images/Sunrise in Bryce Canyon.jpg" }}
+ {{ .Title }} → /images/Sunrise in Bryce Canyon.jpg
+{{ end }}
+```
+
+## Page resource
+
+With a [page resource](g), if you create an element in the `resources` array in front matter, the `Title` method returns the value of the `title` parameter.
+
+```text
+content/
+├── example/
+│ ├── images/
+│ │ └── a.jpg
+│ └── index.md
+└── _index.md
+```
+
+{{< code-toggle file=content/example/index.md fm=true >}}
+title = 'Example'
+[[resources]]
+src = 'images/a.jpg'
+title = 'A beautiful sunrise in Bryce Canyon'
+{{< /code-toggle >}}
+
+```go-html-template
+{{ with .Resources.Get "images/a.jpg" }}
+ {{ .Title }} → A beautiful sunrise in Bryce Canyon
+{{ end }}
+```
+
+If you do not create an element in the `resources` array in front matter, the `Title` method returns the file path, relative to the page bundle.
+
+```text
+content/
+├── example/
+│ ├── images/
+│ │ └── Sunrise in Bryce Canyon.jpg
+│ └── index.md
+└── _index.md
+```
+
+```go-html-template
+{{ with .Resources.Get "Sunrise in Bryce Canyon.jpg" }}
+ {{ .Title }} → images/Sunrise in Bryce Canyon.jpg
+{{ end }}
+```
+
+## Remote resource
+
+With a [remote resource](g), the `Title` method returns a hashed file name.
+
+```go-html-template
+{{ with resources.GetRemote "https://example.org/images/a.jpg" }}
+ {{ .Title }} → /a_18432433023265451104.jpg
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_resource_Width.md b/documents/markdown/hugo-docs/en_methods_resource_Width.md
new file mode 100644
index 0000000..74eb373
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_resource_Width.md
@@ -0,0 +1,26 @@
+---
+title: Width
+description: Applicable to images, returns the width of the given resource.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [RESOURCE.Width]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
+Use the [`reflect.IsImageResourceWithMeta`][] function to verify that Hugo can determine the dimensions before calling the `Width` method.
+
+```go-html-template
+{{ with resources.GetMatch "images/featured.*" }}
+ {{ if reflect.IsImageResourceWithMeta . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ else }}
+ <img src="{{ .RelPermalink }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+[`reflect.IsImageResourceWithMeta`]: /functions/reflect/isimageresourcewithmeta/
diff --git a/documents/markdown/hugo-docs/en_methods_resource__index.md b/documents/markdown/hugo-docs/en_methods_resource__index.md
new file mode 100644
index 0000000..c6012e7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_resource__index.md
@@ -0,0 +1,7 @@
+---
+title: Resource methods
+linkTitle: Resource
+description: Use these methods with a global, page, or remote Resource object.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_methods_shortcode_Get.md b/documents/markdown/hugo-docs/en_methods_shortcode_Get.md
new file mode 100644
index 0000000..aef9987
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_shortcode_Get.md
@@ -0,0 +1,46 @@
+---
+title: Get
+description: Returns the value of the given argument.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: any
+ signatures: [SHORTCODE.Get ARG]
+---
+
+Specify the argument by position or by name. When calling a shortcode within Markdown, use either positional or named argument, but not both.
+
+> [!note]
+> Some shortcodes support positional arguments, some support named arguments, and others support both. Refer to the shortcode's documentation for usage details.
+
+## Positional arguments
+
+This shortcode call uses positional arguments:
+
+```text {file="content/about.md"}
+{{</* myshortcode "Hello" "world" */>}}
+```
+
+To retrieve arguments by position:
+
+```go-html-template {file="layouts/_shortcodes/myshortcode.html"}
+{{ printf "%s %s." (.Get 0) (.Get 1) }} → Hello world.
+```
+
+## Named arguments
+
+This shortcode call uses named arguments:
+
+```text {file="content/about.md"}
+{{</* myshortcode greeting="Hello" firstName="world" */>}}
+```
+
+To retrieve arguments by name:
+
+```go-html-template {file="layouts/_shortcodes/myshortcode.html"}
+{{ printf "%s %s." (.Get "greeting") (.Get "firstName") }} → Hello world.
+```
+
+> [!note]
+> Argument names are case-sensitive.
diff --git a/documents/markdown/hugo-docs/en_methods_shortcode_Inner.md b/documents/markdown/hugo-docs/en_methods_shortcode_Inner.md
new file mode 100644
index 0000000..bb5a16a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_shortcode_Inner.md
@@ -0,0 +1,143 @@
+---
+title: Inner
+description: Returns the content between opening and closing shortcode tags, applicable when the shortcode call includes a closing tag.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: template.HTML
+ signatures: [SHORTCODE.Inner]
+---
+
+This content:
+
+```text {file="content/services.md"}
+{{</* card title="Product Design" */>}}
+We design the **best** widgets in the world.
+{{</* /card */>}}
+```
+
+With this shortcode:
+
+```go-html-template {file="layouts/_shortcodes/card.html"}
+<div class="card">
+ {{ with .Get "title" }}
+ <div class="card-title">{{ . }}</div>
+ {{ end }}
+ <div class="card-content">
+ {{ .Inner | strings.TrimSpace }}
+ </div>
+</div>
+```
+
+Is rendered to:
+
+```html
+<div class="card">
+ <div class="card-title">Product Design</div>
+ <div class="card-content">
+ We design the **best** widgets in the world.
+ </div>
+</div>
+```
+
+> [!note]
+> Content between opening and closing shortcode tags may include leading and/or trailing newlines, depending on placement within the Markdown. Use the [`strings.TrimSpace`] function as shown above to remove carriage returns and newlines.
+
+> [!note]
+> In the example above, the value returned by `Inner` is Markdown, but it was rendered as plain text. Use either of the following approaches to render Markdown to HTML.
+
+## Use RenderString
+
+Let's modify the example above to pass the value returned by `Inner` through the [`RenderString`] method on the `Page` object:
+
+```go-html-template {file="layouts/_shortcodes/card.html"}
+<div class="card">
+ {{ with .Get "title" }}
+ <div class="card-title">{{ . }}</div>
+ {{ end }}
+ <div class="card-content">
+ {{ .Inner | strings.TrimSpace | .Page.RenderString }}
+ </div>
+</div>
+```
+
+Hugo renders this to:
+
+```html
+<div class="card">
+ <div class="card-title">Product design</div>
+ <div class="card-content">
+ We produce the <strong>best</strong> widgets in the world.
+ </div>
+</div>
+```
+
+You can use the [`markdownify`] function instead of the `RenderString` method, but the latter is more flexible. See [details].
+
+## Alternative notation
+
+Instead of calling the shortcode with the `{{</* */>}}` notation, use the `{{%/* */%}}` notation:
+
+```text {file="content/services.md"}
+{{%/* card title="Product Design" */%}}
+We design the **best** widgets in the world.
+{{%/* /card */%}}
+```
+
+When you use the `{{%/* */%}}` notation, Hugo renders the entire shortcode as Markdown, requiring the following changes.
+
+First, configure the renderer to allow raw HTML within Markdown:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.renderer]
+unsafe = true
+{{< /code-toggle >}}
+
+This configuration is not unsafe if _you_ control the content. Read more about Hugo's [security model].
+
+Second, because we are rendering the entire shortcode as Markdown, we must adhere to the rules governing [indentation] and inclusion of [raw HTML blocks] as provided in the [CommonMark] specification.
+
+```go-html-template {file="layouts/_shortcodes/card.html"}
+<div class="card">
+ {{ with .Get "title" }}
+ <div class="card-title">{{ . }}</div>
+ {{ end }}
+ <div class="card-content">
+
+ {{ .Inner | strings.TrimSpace }}
+ </div>
+</div>
+```
+
+The difference between this and the previous example is subtle but required. Note the change in indentation, the addition of a blank line, and removal of the `RenderString` method.
+
+```diff
+--- layouts/_shortcodes/a.html
++++ layouts/_shortcodes/b.html
+@@ -1,8 +1,9 @@
+ <div class="card">
+ {{ with .Get "title" }}
+- <div class="card-title">{{ . }}</div>
++ <div class="card-title">{{ . }}</div>
+ {{ end }}
+ <div class="card-content">
+- {{ .Inner | strings.TrimSpace | .Page.RenderString }}
++
++ {{ .Inner | strings.TrimSpace }}
+ </div>
+ </div>
+```
+
+> [!note]
+> Don't process the `Inner` value with `RenderString` or `markdownify` when using [Markdown notation] to call the shortcode.
+
+[`markdownify`]: /functions/transform/markdownify/
+[`RenderString`]: /methods/page/renderstring/
+[`strings.TrimSpace`]: /functions/strings/trimspace/
+[CommonMark]: https://spec.commonmark.org/current/
+[details]: /methods/page/renderstring/
+[indentation]: https://spec.commonmark.org/current/#indented-code-blocks
+[Markdown notation]: /content-management/shortcodes/#notation
+[raw HTML blocks]: https://spec.commonmark.org/current/#html-blocks
+[security model]: /about/security/
diff --git a/documents/markdown/hugo-docs/en_methods_shortcode_InnerDeindent.md b/documents/markdown/hugo-docs/en_methods_shortcode_InnerDeindent.md
new file mode 100644
index 0000000..3d7536b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_shortcode_InnerDeindent.md
@@ -0,0 +1,98 @@
+---
+title: InnerDeindent
+description: Returns the content between opening and closing shortcode tags, with indentation removed, applicable when the shortcode call includes a closing tag.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: template.HTML
+ signatures: [SHORTCODE.InnerDeindent]
+---
+
+Similar to the [`Inner`] method, `InnerDeindent` returns the content between opening and closing shortcode tags. However, with `InnerDeindent`, indentation before the content is removed.
+
+This allows us to effectively bypass the rules governing [indentation] as provided in the [CommonMark] specification.
+
+Consider this Markdown, an unordered list with a small gallery of thumbnail images within each list item:
+
+```text {file="content/about.md"}
+- Gallery one
+
+ {{</* gallery */>}}
+ 
+ 
+ {{</* /gallery */>}}
+
+- Gallery two
+
+ {{</* gallery */>}}
+ 
+ 
+ {{</* /gallery */>}}
+```
+
+In the example above, notice that the content between the opening and closing shortcode tags is indented by four spaces. Per the CommonMark specification, this is treated as an indented code block.
+
+With this shortcode, calling `Inner` instead of `InnerDeindent`:
+
+```go-html-template {file="layouts/_shortcodes/gallery.html"}
+<div class="gallery">
+ {{ .Inner | strings.TrimSpace | .Page.RenderString }}
+</div>
+```
+
+Hugo renders the Markdown to:
+
+```html
+<ul>
+ <li>
+ <p>Gallery one</p>
+ <div class="gallery">
+ <pre><code>
+ 
+ </code></pre>
+ </div>
+ </li>
+ <li>
+ <p>Gallery two</p>
+ <div class="gallery">
+ <pre><code>
+ 
+ </code></pre>
+ </div>
+ </li>
+</ul>
+```
+
+Although technically correct per the CommonMark specification, this is not what we want. If we remove the indentation using the `InnerDeindent` method:
+
+```go-html-template {file="layouts/_shortcodes/gallery.html"}
+<div class="gallery">
+ {{ .InnerDeindent | strings.TrimSpace | .Page.RenderString }}
+</div>
+```
+
+Hugo renders the Markdown to:
+
+```html
+<ul>
+ <li>
+ <p>Gallery one</p>
+ <div class="gallery">
+ <img src="images/a.jpg" alt="kitten a">
+ <img src="images/b.jpg" alt="kitten b">
+ </div>
+ </li>
+ <li>
+ <p>Gallery two</p>
+ <div class="gallery">
+ <img src="images/c.jpg" alt="kitten c">
+ <img src="images/d.jpg" alt="kitten d">
+ </div>
+ </li>
+</ul>
+```
+
+[commonmark]: https://commonmark.org/
+[indentation]: https://spec.commonmark.org/current/#indented-code-blocks
+[`Inner`]: /methods/shortcode/inner/
diff --git a/documents/markdown/hugo-docs/en_methods_shortcode_IsNamedParams.md b/documents/markdown/hugo-docs/en_methods_shortcode_IsNamedParams.md
new file mode 100644
index 0000000..0574128
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_shortcode_IsNamedParams.md
@@ -0,0 +1,29 @@
+---
+title: IsNamedParams
+description: Reports whether the shortcode call uses named arguments.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [SHORTCODE.IsNamedParams]
+---
+
+To support both positional and named arguments when calling a shortcode, use the `IsNamedParams` method to determine how the shortcode was called.
+
+With this _shortcode_ template:
+
+```go-html-template {file="layouts/_shortcodes/myshortcode.html"}
+{{ if .IsNamedParams }}
+ {{ printf "%s %s." (.Get "greeting") (.Get "firstName") }}
+{{ else }}
+ {{ printf "%s %s." (.Get 0) (.Get 1) }}
+{{ end }}
+```
+
+Both of these calls return the same value:
+
+```text {file="content/about.md"}
+{{</* myshortcode greeting="Hello" firstName="world" */>}}
+{{</* myshortcode "Hello" "world" */>}}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_shortcode_Name.md b/documents/markdown/hugo-docs/en_methods_shortcode_Name.md
new file mode 100644
index 0000000..c42513c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_shortcode_Name.md
@@ -0,0 +1,27 @@
+---
+title: Name
+description: Returns the shortcode file name, excluding the file extension.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [SHORTCODE.Name]
+---
+
+The `Name` method is useful for error reporting. For example, if your shortcode requires a "greeting" argument:
+
+```go-html-template {file="layouts/_shortcodes/myshortcode.html"}
+{{ $greeting := "" }}
+{{ with .Get "greeting" }}
+ {{ $greeting = . }}
+{{ else }}
+ {{ errorf "The %q shortcode requires a 'greeting' argument. See %s" .Name .Position }}
+{{ end }}
+```
+
+In the absence of a "greeting" argument, Hugo will throw an error message and fail the build:
+
+```text
+ERROR The "myshortcode" shortcode requires a 'greeting' argument. See "/home/user/project/content/about.md:11:1"
+```
diff --git a/documents/markdown/hugo-docs/en_methods_shortcode_Ordinal.md b/documents/markdown/hugo-docs/en_methods_shortcode_Ordinal.md
new file mode 100644
index 0000000..b167589
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_shortcode_Ordinal.md
@@ -0,0 +1,52 @@
+---
+title: Ordinal
+description: Returns the zero-based ordinal of the shortcode in relation to its parent.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [SHORTCODE.Ordinal]
+---
+
+The `Ordinal` method returns the zero-based ordinal of the shortcode in relation to its parent. If the parent is the page itself, the ordinal represents the position of this shortcode in the page content.
+
+> [!note]
+> Hugo increments the ordinal with each shortcode call, regardless of the specific shortcode type. This means that the ordinal value is tracked sequentially across all shortcodes within a given page.
+
+This method is useful for, among other things, assigning unique element IDs when a shortcode is called two or more times from the same page. For example:
+
+```text {file="content/about.md"}
+{{</* img src="images/a.jpg" */>}}
+
+{{</* img src="images/b.jpg" */>}}
+```
+
+This shortcode performs error checking, then renders an HTML `img` element with a unique `id` attribute:
+
+```go-html-template {file="layouts/_shortcodes/img.html"}
+{{ $src := "" }}
+{{ with .Get "src" }}
+ {{ $src = . }}
+ {{ with resources.Get $src }}
+ {{ $id := printf "img-%03d" $.Ordinal }}
+ <img id="{{ $id }}" src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ else }}
+ {{ errorf "The %q shortcode was unable to find %s. See %s" $.Name $src $.Position }}
+ {{ end }}
+{{ else }}
+ {{ errorf "The %q shortcode requires a 'src' argument. See %s" .Name .Position }}
+{{ end }}
+```
+
+Hugo renders the page to:
+
+```html
+<img id="img-000" src="/images/a.jpg" width="600" height="400" alt="">
+<img id="img-001" src="/images/b.jpg" width="600" height="400" alt="">
+```
+
+> [!note]
+> In the _shortcode_ template above, the [`with`] statement is used to create conditional blocks. Remember that the `with` statement binds context (the dot) to its expression. Inside of a `with` block, preface shortcode method calls with a `$` to access the top-level context passed into the template.
+
+[`with`]: /functions/go-template/with/
diff --git a/documents/markdown/hugo-docs/en_methods_shortcode_Page.md b/documents/markdown/hugo-docs/en_methods_shortcode_Page.md
new file mode 100644
index 0000000..0fa1c9c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_shortcode_Page.md
@@ -0,0 +1,36 @@
+---
+title: Page
+description: Returns the Page object from which the shortcode was called.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: hugolib.pageForShortcode
+ signatures: [SHORTCODE.Page]
+---
+
+With this content:
+
+{{< code-toggle file=content/books/les-miserables.md fm=true >}}
+title = 'Les Misérables'
+author = 'Victor Hugo'
+publication_year = 1862
+isbn = '978-0451419439'
+{{< /code-toggle >}}
+
+Calling this shortcode:
+
+```text
+{{</* book-details */>}}
+```
+
+We can access the front matter values using the `Page` method:
+
+```go-html-template {file="layouts/_shortcodes/book-details.html"}
+<ul>
+ <li>Title: {{ .Page.Title }}</li>
+ <li>Author: {{ .Page.Params.author }}</li>
+ <li>Published: {{ .Page.Params.publication_year }}</li>
+ <li>ISBN: {{ .Page.Params.isbn }}</li>
+</ul>
+```
diff --git a/documents/markdown/hugo-docs/en_methods_shortcode_Params.md b/documents/markdown/hugo-docs/en_methods_shortcode_Params.md
new file mode 100644
index 0000000..c8252f5
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_shortcode_Params.md
@@ -0,0 +1,32 @@
+---
+title: Params
+description: Returns a collection of the shortcode arguments.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: any
+ signatures: [SHORTCODE.Params]
+---
+
+When you call a shortcode using positional arguments, the `Params` method returns a slice.
+
+```text {file="content/about.md"}
+{{</* myshortcode "Hello" "world" */>}}
+```
+
+```go-html-template {file="layouts/_shortcodes/myshortcode.html"}
+{{ index .Params 0 }} → Hello
+{{ index .Params 1 }} → world
+```
+
+When you call a shortcode using named arguments, the `Params` method returns a map.
+
+```text {file="content/about.md"}
+{{</* myshortcode greeting="Hello" name="world" */>}}
+```
+
+```go-html-template {file="layouts/_shortcodes/myshortcode.html"}
+{{ .Params.greeting }} → Hello
+{{ .Params.name }} → world
+```
diff --git a/documents/markdown/hugo-docs/en_methods_shortcode_Parent.md b/documents/markdown/hugo-docs/en_methods_shortcode_Parent.md
new file mode 100644
index 0000000..4597d10
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_shortcode_Parent.md
@@ -0,0 +1,50 @@
+---
+title: Parent
+description: Returns the parent shortcode context in nested shortcodes.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: hugolib.ShortcodeWithPage
+ signatures: [SHORTCODE.Parent]
+---
+
+This is useful for inheritance of common shortcode arguments from the root.
+
+In this contrived example, the "greeting" shortcode is the parent, and the "now" shortcode is child.
+
+```text {file="content/welcome.md"}
+{{</* greeting dateFormat="Jan 2, 2006" */>}}
+Welcome. Today is {{</* now */>}}.
+{{</* /greeting */>}}
+```
+
+```go-html-template {file="layouts/_shortcodes/greeting.html"}
+<div class="greeting">
+ {{ .Inner | strings.TrimSpace | .Page.RenderString }}
+</div>
+```
+
+```go-html-template {file="layouts/_shortcodes/now.html"}
+{{- $dateFormat := "January 2, 2006 15:04:05" }}
+
+{{- with .Params }}
+ {{- with .dateFormat }}
+ {{- $dateFormat = . }}
+ {{- end }}
+{{- else }}
+ {{- with .Parent.Params }}
+ {{- with .dateFormat }}
+ {{- $dateFormat = . }}
+ {{- end }}
+ {{- end }}
+{{- end }}
+
+{{- now | time.Format $dateFormat -}}
+```
+
+The "now" shortcode formats the current time using:
+
+1. The `dateFormat` argument passed to the "now" shortcode, if present
+1. The `dateFormat` argument passed to the "greeting" shortcode, if present
+1. The default layout string defined at the top of the shortcode
diff --git a/documents/markdown/hugo-docs/en_methods_shortcode_Position.md b/documents/markdown/hugo-docs/en_methods_shortcode_Position.md
new file mode 100644
index 0000000..4052a73
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_shortcode_Position.md
@@ -0,0 +1,30 @@
+---
+title: Position
+description: Returns the file name and position from which the shortcode was called.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: text.Position
+ signatures: [SHORTCODE.Position]
+---
+
+The `Position` method is useful for error reporting. For example, if your shortcode requires a "greeting" argument:
+
+```go-html-template {file="layouts/_shortcodes/myshortcode.html"}
+{{ $greeting := "" }}
+{{ with .Get "greeting" }}
+ {{ $greeting = . }}
+{{ else }}
+ {{ errorf "The %q shortcode requires a 'greeting' argument. See %s" .Name .Position }}
+{{ end }}
+```
+
+In the absence of a "greeting" argument, Hugo will throw an error message and fail the build:
+
+```text
+ERROR The "myshortcode" shortcode requires a 'greeting' argument. See "/home/user/project/content/about.md:11:1"
+```
+
+> [!note]
+> The position can be expensive to calculate. Limit its use to error reporting.
diff --git a/documents/markdown/hugo-docs/en_methods_shortcode_Ref.md b/documents/markdown/hugo-docs/en_methods_shortcode_Ref.md
new file mode 100644
index 0000000..3a877d5
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_shortcode_Ref.md
@@ -0,0 +1,37 @@
+---
+title: Ref
+description: Returns the absolute URL of the page with the given path, language, and output format.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [SHORTCODE.Ref OPTIONS]
+---
+
+## Usage
+
+The `Ref` method accepts a single argument: an options map.
+
+## Options
+
+{{% include "_common/ref-and-relref-options.md" %}}
+
+## Examples
+
+The following examples show the rendered output for a page on the English version of the site:
+
+```go-html-template
+{{ $opts := dict "path" "/books/book-1" }}
+{{ .Ref $opts }} → https://example.org/en/books/book-1/
+
+{{ $opts := dict "path" "/books/book-1" "lang" "de" }}
+{{ .Ref $opts }} → https://example.org/de/books/book-1/
+
+{{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }}
+{{ .Ref $opts }} → https://example.org/de/books/book-1/index.json
+```
+
+## Error handling
+
+{{% include "_common/ref-and-relref-error-handling.md" %}}
diff --git a/documents/markdown/hugo-docs/en_methods_shortcode_RelRef.md b/documents/markdown/hugo-docs/en_methods_shortcode_RelRef.md
new file mode 100644
index 0000000..273705a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_shortcode_RelRef.md
@@ -0,0 +1,37 @@
+---
+title: RelRef
+description: Returns the relative URL of the page with the given path, language, and output format.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [SHORTCODE.RelRef OPTIONS]
+---
+
+## Usage
+
+The `RelRef` method accepts a single argument: an options map.
+
+## Options
+
+{{% include "_common/ref-and-relref-options.md" %}}
+
+## Examples
+
+The following examples show the rendered output for a page on the English version of the site:
+
+```go-html-template
+{{ $opts := dict "path" "/books/book-1" }}
+{{ .RelRef $opts }} → /en/books/book-1/
+
+{{ $opts := dict "path" "/books/book-1" "lang" "de" }}
+{{ .RelRef $opts }} → /de/books/book-1/
+
+{{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }}
+{{ .RelRef $opts }} → /de/books/book-1/index.json
+```
+
+## Error handling
+
+{{% include "_common/ref-and-relref-error-handling.md" %}}
diff --git a/documents/markdown/hugo-docs/en_methods_shortcode_Scratch.md b/documents/markdown/hugo-docs/en_methods_shortcode_Scratch.md
new file mode 100644
index 0000000..6efec20
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_shortcode_Scratch.md
@@ -0,0 +1,21 @@
+---
+title: Scratch
+description: Returns a "scratch pad" to store and manipulate data, scoped to the current shortcode.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: maps.Scratch
+ signatures: [SHORTCODE.Scratch]
+expiryDate: 2026-11-18 # deprecated 2024-11-18 (soft)
+---
+
+{{< deprecated-in 0.139.0 >}}
+Use the [`SHORTCODE.Store`] method instead.
+
+This is a soft deprecation. This method will be removed in a future release, but the removal date has not been established. Although Hugo will not emit a warning if you continue to use this method, you should begin using `SHORTCODE.Store` as soon as possible.
+
+Beginning with v0.139.0 the `SHORTCODE.Scratch` method is aliased to `SHORTCODE.Store`.
+
+[`SHORTCODE.Store`]: /methods/shortcode/store/
+{{< /deprecated-in >}}
diff --git a/documents/markdown/hugo-docs/en_methods_shortcode_Site.md b/documents/markdown/hugo-docs/en_methods_shortcode_Site.md
new file mode 100644
index 0000000..4c5a9a9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_shortcode_Site.md
@@ -0,0 +1,18 @@
+---
+title: Site
+description: Returns the Site object.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.siteWrapper
+ signatures: [SHORTCODE.Site]
+---
+
+See [Site methods].
+
+[Site methods]: /methods/site/
+
+```go-html-template
+{{ .Site.Title }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_shortcode_Store.md b/documents/markdown/hugo-docs/en_methods_shortcode_Store.md
new file mode 100644
index 0000000..76cb923
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_shortcode_Store.md
@@ -0,0 +1,24 @@
+---
+title: Store
+description: Returns a "scratch pad" to store and manipulate data, scoped to the current shortcode.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: maps.Scratch
+ signatures: [SHORTCODE.Store]
+---
+
+{{< new-in 0.139.0 />}}
+
+Use the `Store` method to create a [scratch pad](g) to store and manipulate data, scoped to the current shortcode. To create a scratch pad with a different [scope](g), refer to the [scope](#scope) section below.
+
+> [!note]
+> With the introduction of the [`newScratch`] function, and the ability to [assign values to template variables] after initialization, the `Store` method within a shortcode is mostly obsolete.
+
+{{% include "_common/store-methods.md" %}}
+
+{{% include "_common/scratch-pad-scope.md" %}}
+
+[`newScratch`]: /functions/collections/newScratch/
+[assign values to template variables]: https://go.dev/doc/go1.11#texttemplatepkgtexttemplate
diff --git a/documents/markdown/hugo-docs/en_methods_shortcode__index.md b/documents/markdown/hugo-docs/en_methods_shortcode__index.md
new file mode 100644
index 0000000..0064f42
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_shortcode__index.md
@@ -0,0 +1,8 @@
+---
+title: Shortcode methods
+linkTitle: Shortcode
+description: Use these methods in your shortcode templates.
+categories: []
+keywords: []
+aliases: [/variables/shortcodes]
+---
diff --git a/documents/markdown/hugo-docs/en_methods_site_AllPages.md b/documents/markdown/hugo-docs/en_methods_site_AllPages.md
new file mode 100644
index 0000000..84e5648
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_AllPages.md
@@ -0,0 +1,15 @@
+---
+title: AllPages
+description: Returns a collection of all pages in all languages.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [SITE.AllPages]
+expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0
+---
+
+{{< deprecated-in 0.156.0 >}}
+See [details](https://discourse.gohugo.io/t/56732).
+{{< /deprecated-in >}}
diff --git a/documents/markdown/hugo-docs/en_methods_site_BaseURL.md b/documents/markdown/hugo-docs/en_methods_site_BaseURL.md
new file mode 100644
index 0000000..7b1b5e8
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_BaseURL.md
@@ -0,0 +1,32 @@
+---
+title: BaseURL
+description: Returns the base URL as defined in your project configuration.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [SITE.BaseURL]
+---
+
+Project configuration:
+
+{{< code-toggle file=hugo >}}
+baseURL = 'https://example.org/docs/'
+{{< /code-toggle >}}
+
+Template:
+
+```go-html-template
+{{ .Site.BaseURL }} → https://example.org/docs/
+```
+
+> [!note]
+> There is almost never a good reason to use this method in your templates. Its usage tends to be fragile due to misconfiguration.
+>
+> Use the [`absURL`], [`absLangURL`], [`relURL`], or [`relLangURL`] functions instead.
+
+[`absLangURL`]: /functions/urls/absLangURL/
+[`absURL`]: /functions/urls/absURL/
+[`relLangURL`]: /functions/urls/relLangURL/
+[`relURL`]: /functions/urls/relURL/
diff --git a/documents/markdown/hugo-docs/en_methods_site_BuildDrafts.md b/documents/markdown/hugo-docs/en_methods_site_BuildDrafts.md
new file mode 100644
index 0000000..0a94adf
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_BuildDrafts.md
@@ -0,0 +1,15 @@
+---
+title: BuildDrafts
+description: Reports reports whether draft publishing is enabled for the current build.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [SITE.BuildDrafts]
+expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0
+---
+
+{{< deprecated-in 0.156.0 >}}
+See [details](https://discourse.gohugo.io/t/56732).
+{{< /deprecated-in >}}
diff --git a/documents/markdown/hugo-docs/en_methods_site_Config.md b/documents/markdown/hugo-docs/en_methods_site_Config.md
new file mode 100644
index 0000000..9cc8856
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_Config.md
@@ -0,0 +1,52 @@
+---
+title: Config
+description: Returns a subset of your project configuration.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.SiteConfig
+ signatures: [SITE.Config]
+---
+
+The `Config` method on a `Site` object provides access to a subset of your project configuration, specifically the `services` and `privacy` keys.
+
+## Services
+
+See [configure services](/configuration/services).
+
+For example, to use Hugo's built-in Google Analytics template you must add a [Google tag ID]:
+
+[Google tag ID]: https://support.google.com/tagmanager/answer/12326985?hl=en
+
+{{< code-toggle file=hugo >}}
+[services.googleAnalytics]
+id = 'G-XXXXXXXXX'
+{{< /code-toggle >}}
+
+To access this value from a template:
+
+```go-html-template
+{{ .Site.Config.Services.GoogleAnalytics.ID }} → G-XXXXXXXXX
+```
+
+You must capitalize each identifier as shown above.
+
+## Privacy
+
+See [configure privacy](/configuration/privacy).
+
+For example, to disable usage of the built-in YouTube shortcode:
+
+{{< code-toggle file=hugo >}}
+[privacy.youtube]
+disable = true
+{{< /code-toggle >}}
+
+To access this value from a template:
+
+```go-html-template
+{{ .Site.Config.Privacy.YouTube.Disable }} → true
+```
+
+You must capitalize each identifier as shown above.
diff --git a/documents/markdown/hugo-docs/en_methods_site_Copyright.md b/documents/markdown/hugo-docs/en_methods_site_Copyright.md
new file mode 100644
index 0000000..e73ff66
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_Copyright.md
@@ -0,0 +1,22 @@
+---
+title: Copyright
+description: Returns the copyright notice as defined in your project configuration.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [SITE.Copyright]
+---
+
+Project configuration:
+
+{{< code-toggle file=hugo >}}
+copyright = '© 2023 ABC Widgets, Inc.'
+{{< /code-toggle >}}
+
+Template:
+
+```go-html-template
+{{ .Site.Copyright }} → © 2023 ABC Widgets, Inc.
+```
diff --git a/documents/markdown/hugo-docs/en_methods_site_Data.md b/documents/markdown/hugo-docs/en_methods_site_Data.md
new file mode 100644
index 0000000..0790c4f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_Data.md
@@ -0,0 +1,15 @@
+---
+title: Data
+description: Returns a data structure composed from the files in the data directory.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: map
+ signatures: [SITE.Data]
+expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0
+---
+
+{{< deprecated-in 0.156.0 >}}
+Use [`hugo.Data`](/functions/hugo/data/) instead.
+{{< /deprecated-in >}}
diff --git a/documents/markdown/hugo-docs/en_methods_site_Dimension.md b/documents/markdown/hugo-docs/en_methods_site_Dimension.md
new file mode 100644
index 0000000..7c20016
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_Dimension.md
@@ -0,0 +1,36 @@
+---
+title: Dimension
+description: Returns the dimension object for the given dimension for the given site.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.SiteDimension
+ signatures: [SITE.Dimension DIMENSION]
+---
+
+{{< new-in 0.153.0 />}}
+
+The `Dimension` method on a `Site` object returns the dimension object for the given [dimension](g).
+
+The `DIMENSION` argument must be one of `language`, `version`, or `role`.
+
+Example|Returns|Equivalent to
+:--|:--|:--
+`{{ .Site.Dimension "language" }}`|`langs.Language`|`{{ .Site.Language }}`
+`{{ .Site.Dimension "version" }}`|`version.Version`|`{{ .Site.Version }}`
+`{{ .Site.Dimension "role" }}`|`roles.Role`|`{{ .Site.Role }}`
+
+```go-html-template
+{{ $languageObject := .Site.Dimension "language" }}
+{{ $languageObject.IsDefault }} → true
+{{ $languageObject.Name }} → en
+
+{{ $versionObject := .Site.Dimension "version" }}
+{{ $versionObject.IsDefault }} → true
+{{ $versionObject.Name }} → v1.0.0
+
+{{ $roleObject := .Site.Dimension "role" }}
+{{ $roleObject.IsDefault }} → true
+{{ $roleObject.Name }} → guest
+```
diff --git a/documents/markdown/hugo-docs/en_methods_site_GetPage.md b/documents/markdown/hugo-docs/en_methods_site_GetPage.md
new file mode 100644
index 0000000..fab6e04
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_GetPage.md
@@ -0,0 +1,105 @@
+---
+title: GetPage
+description: Returns a Page object from the given path.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Page
+ signatures: [SITE.GetPage PATH]
+---
+
+The `GetPage` method is also available on `Page` objects, allowing you to specify a path relative to the current page. See [details].
+
+[details]: /methods/page/getpage/
+
+When using the `GetPage` method on a `Site` object, specify a path relative to the `content` directory.
+
+If Hugo cannot resolve the path to a page, the method returns nil.
+
+Consider this content structure:
+
+```text
+content/
+├── works/
+│ ├── paintings/
+│ │ ├── _index.md
+│ │ ├── starry-night.md
+│ │ └── the-mona-lisa.md
+│ ├── sculptures/
+│ │ ├── _index.md
+│ │ ├── david.md
+│ │ └── the-thinker.md
+│ └── _index.md
+└── _index.md
+```
+
+This _home_ template:
+
+```go-html-template {file="layouts/home.html"}
+{{ with .Site.GetPage "/works/paintings" }}
+ <ul>
+ {{ range .Pages }}
+ <li>{{ .Title }} by {{ .Params.artist }}</li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li>Starry Night by Vincent van Gogh</li>
+ <li>The Mona Lisa by Leonardo da Vinci</li>
+</ul>
+```
+
+To get a regular page instead of a section page:
+
+```go-html-template {file="layouts/home.html"}
+{{ with .Site.GetPage "/works/paintings/starry-night" }}
+ {{ .Title }} → Starry Night
+ {{ .Params.artist }} → Vincent van Gogh
+{{ end }}
+```
+
+## Multilingual projects
+
+With multilingual projects, the `GetPage` method on a `Site` object resolves the given path to a page in the current language.
+
+To get a page from a different language, query the `Sites` object:
+
+```go-html-template
+{{ with where hugo.Sites "Language.Name" "eq" "de" }}
+ {{ with index . 0 }}
+ {{ with .GetPage "/works/paintings/starry-night" }}
+ {{ .Title }} → Sternenklare Nacht
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+## Page bundles
+
+Consider this content structure:
+
+```text
+content/
+├── headless/
+│ ├── a.jpg
+│ ├── b.jpg
+│ ├── c.jpg
+│ └── index.md <-- front matter: headless = true
+└── _index.md
+```
+
+In the _home_ template, use the `GetPage` method on a `Site` object to render all the images in the headless [page bundle](g):
+
+```go-html-template {file="layouts/home.html"}
+{{ with .Site.GetPage "/headless" }}
+ {{ range .Resources.ByType "image" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_site_Home.md b/documents/markdown/hugo-docs/en_methods_site_Home.md
new file mode 100644
index 0000000..57b2cea
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_Home.md
@@ -0,0 +1,39 @@
+---
+title: Home
+description: Returns the home Page object for the given site.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Page
+ signatures: [SITE.Home]
+---
+
+The `Home` method on a `Site` object is a convenient way to access the home page, and is functionally equivalent to:
+
+```go-html-template
+{{ .Site.GetPage "/" }}
+```
+
+Because it returns a `Page` object, you can use any of the available [page methods][] by chaining them. For example:
+
+```go-html-template
+{{ .Site.Home.Store.Set "greeting" "Hello" }}
+```
+
+This method is commonly used to generate a link to the home page. For example:
+
+Project configuration:
+
+{{< code-toggle file=hugo >}}
+baseURL = 'https://example.org/docs/'
+{{< /code-toggle >}}
+
+Template:
+
+```go-html-template
+{{ .Site.Home.Permalink }} → https://example.org/docs/
+{{ .Site.Home.RelPermalink }} → /docs/
+```
+
+[page methods]: /methods/page/
diff --git a/documents/markdown/hugo-docs/en_methods_site_IsDefault.md b/documents/markdown/hugo-docs/en_methods_site_IsDefault.md
new file mode 100644
index 0000000..543bc4f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_IsDefault.md
@@ -0,0 +1,50 @@
+---
+title: IsDefault
+description: Reports whether the given site is the default site across all dimensions.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [SITE.IsDefault]
+---
+
+{{< new-in 0.156.0 />}}
+
+The `IsDefault` method on a `Site` object reports whether the given site is the [default site](g) across all dimensions: [language](g), [version](g), and [role](g). This is useful to ensure that a block of code executes only once per build, regardless of the number of [sites](g) generated by your [dimensions](g).
+
+For example, the following configuration defines a matrix of sites across language and version dimensions.
+
+{{< code-toggle file=hugo >}}
+[languages.de]
+contentDir = 'content/de'
+direction = 'ltr'
+label = 'Deutsch'
+locale = 'de-DE'
+title = 'Projekt Dokumentation'
+weight = 1
+
+[languages.en]
+contentDir = 'content/en'
+direction = 'ltr'
+label = 'English'
+locale = 'en-US'
+title = 'Project Documentation'
+weight = 2
+
+[versions.'v1.0.0']
+[versions.'v2.0.0']
+[versions.'v3.0.0']
+{{< /code-toggle >}}
+
+If you call an initialization partial to handle one-time build logic or global variable setup, wrap that call in an [`if`][] statement using this function. This prevents the logic from being executed for every dimensional variation.
+
+```go-html-template
+{{ if .Site.IsDefault }}
+ {{ partial "init.html" . }}
+{{ end }}
+```
+
+In this setup, the code block is only executed for the English version v3.0.0 site. English is selected because it has the lowest weight, and version v3.0.0 is selected because it is the first version when sorted semantically in descending order.
+
+[`if`]: /functions/go-template/if/
diff --git a/documents/markdown/hugo-docs/en_methods_site_Language.md b/documents/markdown/hugo-docs/en_methods_site_Language.md
new file mode 100644
index 0000000..6f2f013
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_Language.md
@@ -0,0 +1,122 @@
+---
+title: Language
+description: Returns the Language object for the given site.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: langs.Language
+ signatures: [SITE.Language]
+---
+
+The `Language` method on a `Site` object returns the `Language` object for the given site, derived from the language definition in your project configuration.
+
+You can also use the `Language` method on a `Page` object. See [details][].
+
+## Methods
+
+The examples below assume the following language definition.
+
+{{< code-toggle file=hugo >}}
+[languages.de]
+direction = 'ltr'
+label = 'Deutsch'
+locale = 'de-DE'
+weight = 2
+{{< /code-toggle >}}
+
+### Direction
+
+{{< new-in 0.158.0 />}}
+
+(`string`) Returns the [`direction`][] from the language definition.
+
+```go-html-template
+{{ .Site.Language.Direction }} → ltr
+```
+
+### IsDefault
+
+{{< new-in 0.153.0 />}}
+
+(`bool`) Reports whether this is the [default language][].
+
+```go-html-template
+{{ .Site.Language.IsDefault }} → true
+```
+
+### Label
+
+{{< new-in 0.158.0 />}}
+
+(`string`) Returns the [`label`][] from the language definition.
+
+```go-html-template
+{{ .Site.Language.Label }} → Deutsch
+```
+
+### Lang
+
+{{<deprecated-in 0.158.0 />}}
+
+Use [`Name`](#name) instead.
+
+### LanguageCode
+
+{{<deprecated-in 0.158.0 />}}
+
+Use [`Locale`](#locale) instead.
+
+### LanguageDirection
+
+{{<deprecated-in 0.158.0 />}}
+
+Use [`Direction`](#direction) instead.
+
+### LanguageName
+
+{{<deprecated-in 0.158.0 />}}
+
+Use [`Label`](#label) instead.
+
+### Locale
+
+{{< new-in 0.158.0 />}}
+
+(`string`) Returns the [`locale`][] from the language definition, falling back to [`Name`](#name).
+
+```go-html-template
+{{ .Site.Language.Locale }} → de-DE
+```
+
+### Name
+
+{{< new-in 0.153.0 />}}
+
+(`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from the language definition.
+
+```go-html-template
+{{ .Site.Language.Name }} → de
+```
+
+### Weight
+
+{{<deprecated-in 0.158.0 />}}
+
+## Example
+
+Some of the methods above are commonly used in a base template as attributes for the `html` element.
+
+```go-html-template
+<html
+ lang="{{ .Site.Language.Locale }}"
+ dir="{{ or .Site.Language.Direction `ltr` }}"
+>
+```
+
+[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
+[`direction`]: /configuration/languages/#direction
+[`label`]: /configuration/languages/#label
+[`locale`]: /configuration/languages/#locale
+[default language]: /quick-reference/glossary/#default-language
+[details]: /methods/page/language/
diff --git a/documents/markdown/hugo-docs/en_methods_site_LanguagePrefix.md b/documents/markdown/hugo-docs/en_methods_site_LanguagePrefix.md
new file mode 100644
index 0000000..59e7d3a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_LanguagePrefix.md
@@ -0,0 +1,51 @@
+---
+title: LanguagePrefix
+description: Returns the URL language prefix, if any, for the given site.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [SITE.LanguagePrefix]
+---
+
+Consider this project configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = false
+
+[languages.de]
+direction = 'ltr'
+label = 'Deutsch'
+locale = 'de-DE'
+title = 'Projekt Dokumentation'
+weight = 1
+
+[languages.en]
+direction = 'ltr'
+label = 'English'
+locale = 'en-US'
+title = 'Project Documentation'
+weight = 2
+{{< /code-toggle >}}
+
+When visiting the German language site:
+
+```go-html-template
+{{ .Site.LanguagePrefix }} → ""
+```
+
+When visiting the English language site:
+
+```go-html-template
+{{ .Site.LanguagePrefix }} → /en
+```
+
+If you change `defaultContentLanguageInSubdir` to `true`, when visiting the German language site:
+
+```go-html-template
+{{ .Site.LanguagePrefix }} → /de
+```
+
+You may use the `LanguagePrefix` method with both monolingual and multilingual projects.
diff --git a/documents/markdown/hugo-docs/en_methods_site_Languages.md b/documents/markdown/hugo-docs/en_methods_site_Languages.md
new file mode 100644
index 0000000..fa51f1e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_Languages.md
@@ -0,0 +1,15 @@
+---
+title: Languages
+description: Returns a collection of language objects for all sites, ordered by language weight.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: langs.Languages
+ signatures: [SITE.Languages]
+expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0
+---
+
+{{< deprecated-in 0.156.0 >}}
+See [details](https://discourse.gohugo.io/t/56732).
+{{< /deprecated-in >}}
diff --git a/documents/markdown/hugo-docs/en_methods_site_Lastmod.md b/documents/markdown/hugo-docs/en_methods_site_Lastmod.md
new file mode 100644
index 0000000..2dec750
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_Lastmod.md
@@ -0,0 +1,21 @@
+---
+title: Lastmod
+description: Returns the last modification date of site content.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: time.Time
+ signatures: [SITE.Lastmod]
+---
+
+The `Lastmod` method on a `Site` object returns a [`time.Time`] value. Use this with time [functions] and [methods]. For example:
+
+```go-html-template
+{{ .Site.Lastmod | time.Format ":date_long" }} → January 31, 2024
+
+```
+
+[`time.Time`]: https://pkg.go.dev/time#Time
+[functions]: /functions/time/
+[methods]: /methods/time/
diff --git a/documents/markdown/hugo-docs/en_methods_site_MainSections.md b/documents/markdown/hugo-docs/en_methods_site_MainSections.md
new file mode 100644
index 0000000..0df8de6
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_MainSections.md
@@ -0,0 +1,54 @@
+---
+title: MainSections
+description: Returns a slice of the main section names as defined in your project configuration, falling back to the top-level section with the most pages.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: '[]string'
+ signatures: [SITE.MainSections]
+---
+
+Project configuration:
+
+{{< code-toggle file=hugo >}}
+mainSections = ['books','films']
+{{< /code-toggle >}}
+
+Template:
+
+```go-html-template
+{{ .Site.MainSections }} → [books films]
+```
+
+If `mainSections` is not defined in your project configuration, this method returns a slice with one element---the top-level section with the most pages.
+
+With this content structure, the "films" section has the most pages:
+
+```text
+content/
+├── books/
+│ ├── book-1.md
+│ └── book-2.md
+├── films/
+│ ├── film-1.md
+│ ├── film-2.md
+│ └── film-3.md
+└── _index.md
+```
+
+Template:
+
+```go-html-template
+{{ .Site.MainSections }} → [films]
+```
+
+When creating a theme, instead of hardcoding section names when listing the most relevant pages on the front page, instruct users to set `mainSections` in their project configuration.
+
+Then your _home_ template can do something like this:
+
+```go-html-template {file="layouts/home.html"}
+{{ range where .Site.RegularPages "Section" "in" .Site.MainSections }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_site_Menus.md b/documents/markdown/hugo-docs/en_methods_site_Menus.md
new file mode 100644
index 0000000..0c8509e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_Menus.md
@@ -0,0 +1,89 @@
+---
+title: Menus
+description: Returns a collection of menu objects for the given site.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: navigation.Menus
+ signatures: [SITE.Menus]
+---
+
+The `Menus` method on a `Site` object returns a collection of menus, where each menu contains one or more entries, either flat or nested. Each entry points to a page within the site, or to an external resource.
+
+> [!note]
+> Menus can be defined and localized in several ways. Please see the [menus] section for a complete explanation and examples.
+
+A site can have multiple menus. For example, a main menu and a footer menu:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+name = 'Home'
+pageRef = '/'
+weight = 10
+
+[[menus.main]]
+name = 'Books'
+pageRef = '/books'
+weight = 20
+
+[[menus.main]]
+name = 'Films'
+pageRef = '/films'
+weight = 30
+
+[[menus.footer]]
+name = 'Legal'
+pageRef = '/legal'
+weight = 10
+
+[[menus.footer]]
+name = 'Privacy'
+pageRef = '/privacy'
+weight = 20
+{{< /code-toggle >}}
+
+This template renders the main menu:
+
+```go-html-template
+{{ with site.Menus.main }}
+ <nav class="menu">
+ {{ range . }}
+ {{ if $.IsMenuCurrent .Menu . }}
+ <a class="active" aria-current="page" href="{{ .URL }}">{{ .Name }}</a>
+ {{ else }}
+ <a href="{{ .URL }}">{{ .Name }}</a>
+ {{ end }}
+ {{ end }}
+ </nav>
+{{ end }}
+```
+
+When viewing the home page, the result is:
+
+```html
+<nav class="menu">
+ <a class="active" aria-current="page" href="/">Home</a>
+ <a href="/books/">Books</a>
+ <a href="/films/">Films</a>
+</nav>
+```
+
+When viewing the "books" page, the result is:
+
+```html
+<nav class="menu">
+ <a href="/">Home</a>
+ <a class="active" aria-current="page" href="/books/">Books</a>
+ <a href="/films/">Films</a>
+</nav>
+```
+
+You will typically render a menu using a _partial_ template. As the active menu entry will be different on each page, use the [`partial`] function to call the template. Do not use the [`partialCached`] function.
+
+The example above is simplistic. Please see the [menu templates] section for more information.
+
+[`partial`]: /functions/partials/include/
+[`partialCached`]: /functions/partials/includecached/
+[menu templates]: /templates/menu/
+[menus]: /content-management/menus/
diff --git a/documents/markdown/hugo-docs/en_methods_site_Pages.md b/documents/markdown/hugo-docs/en_methods_site_Pages.md
new file mode 100644
index 0000000..a6ba5e0
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_Pages.md
@@ -0,0 +1,22 @@
+---
+title: Pages
+description: Returns a collection of all pages.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [SITE.Pages]
+---
+
+This method returns all page [kinds](g) in the current language, in the [default sort order](g). That includes the home page, section pages, taxonomy pages, term pages, and regular pages.
+
+In most cases you should use the [`RegularPages`] method instead.
+
+[`RegularPages`]: /methods/site/regularpages/
+
+```go-html-template
+{{ range .Site.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_site_Param.md b/documents/markdown/hugo-docs/en_methods_site_Param.md
new file mode 100644
index 0000000..b2ec5d9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_Param.md
@@ -0,0 +1,28 @@
+---
+title: Param
+description: Returns the site parameter with the given key.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: any
+ signatures: [SITE.Param KEY]
+---
+
+The `Param` method on a `Site` object is a convenience method to return the value of a user-defined parameter in your project configuration.
+
+{{< code-toggle file=hugo >}}
+[params]
+display_toc = true
+{{< /code-toggle >}}
+
+```go-html-template
+{{ .Site.Param "display_toc" }} → true
+```
+
+The above is equivalent to either of these:
+
+```go-html-template
+{{ .Site.Params.display_toc }}
+{{ index .Site.Params "display_toc" }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_site_Params.md b/documents/markdown/hugo-docs/en_methods_site_Params.md
new file mode 100644
index 0000000..62bc8f1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_Params.md
@@ -0,0 +1,42 @@
+---
+title: Params
+description: Returns a map of custom parameters as defined in your project configuration.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: maps.Params
+ signatures: [SITE.Params]
+---
+
+With this project configuration:
+
+{{< code-toggle file=hugo >}}
+[params]
+ subtitle = 'The Best Widgets on Earth'
+ copyright-year = '2023'
+ [params.author]
+ email = 'jsmith@example.org'
+ name = 'John Smith'
+ [params.layouts]
+ rfc_1123 = 'Mon, 02 Jan 2006 15:04:05 MST'
+ rfc_3339 = '2006-01-02T15:04:05-07:00'
+{{< /code-toggle >}}
+
+Access the custom parameters by [chaining](g) the [identifiers](g):
+
+```go-html-template
+{{ .Site.Params.subtitle }} → The Best Widgets on Earth
+{{ .Site.Params.author.name }} → John Smith
+
+{{ $layout := .Site.Params.layouts.rfc_1123 }}
+{{ .Site.Lastmod.Format $layout }} → Tue, 17 Oct 2023 13:21:02 PDT
+```
+
+In the template example above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function:
+
+```go-html-template
+{{ index .Site.Params "copyright-year" }} → 2023
+```
+
+[`index`]: /functions/collections/indexfunction/
diff --git a/documents/markdown/hugo-docs/en_methods_site_RegularPages.md b/documents/markdown/hugo-docs/en_methods_site_RegularPages.md
new file mode 100644
index 0000000..69a4605
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_RegularPages.md
@@ -0,0 +1,32 @@
+---
+title: RegularPages
+description: Returns a collection of all regular pages.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [SITE.RegularPages]
+---
+
+The `RegularPages` method on a `Site` object returns a collection of all [regular pages](g), in the [default sort order](g).
+
+```go-html-template
+{{ range .Site.RegularPages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+{{% glossary-term "default sort order" %}}
+
+[default sort order](g)
+
+To change the sort order, use any of the `Pages` [sorting methods]. For example:
+
+```go-html-template
+{{ range .Site.RegularPages.ByTitle }}
+ <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
+{{ end }}
+```
+
+[sorting methods]: /methods/pages/
diff --git a/documents/markdown/hugo-docs/en_methods_site_Role.md b/documents/markdown/hugo-docs/en_methods_site_Role.md
new file mode 100644
index 0000000..b8aee5f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_Role.md
@@ -0,0 +1,34 @@
+---
+title: Role
+description: Returns the Role object for the given site.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: roles.Role
+ signatures: [SITE.Role]
+---
+
+{{< new-in 0.153.0 />}}
+
+The `Role` method on a `Site` object returns the `Role` object for the given site, derived from the role definition in your project configuration.
+
+## Methods
+
+### IsDefault
+
+(`bool`) Reports whether this is the [default role][].
+
+```go-html-template
+{{ .Site.Role.IsDefault }} → true
+```
+
+### Name
+
+(`string`) Returns the role name. This is the lowercased key from your project configuration.
+
+```go-html-template
+{{ .Site.Role.Name }} → guest
+```
+
+[default role]: /quick-reference/glossary/#default-role
diff --git a/documents/markdown/hugo-docs/en_methods_site_Sections.md b/documents/markdown/hugo-docs/en_methods_site_Sections.md
new file mode 100644
index 0000000..0ddaf06
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_Sections.md
@@ -0,0 +1,40 @@
+---
+title: Sections
+description: Returns a collection of top-level section pages.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [SITE.Sections]
+---
+
+The `Sections` method on a `Site` object returns a collection of top-level [section pages](g), in the [default sort order](g).
+
+Given this content structure:
+
+```text
+content/
+├── books/
+│ ├── book-1.md
+│ └── book-2.md
+├── films/
+│ ├── film-1.md
+│ └── film-2.md
+└── _index.md
+```
+
+This template:
+
+```go-html-template
+{{ range .Site.Sections }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+Is rendered to:
+
+```html
+<h2><a href="/books/">Books</a></h2>
+<h2><a href="/films/">Films</a></h2>
+```
diff --git a/documents/markdown/hugo-docs/en_methods_site_Sites.md b/documents/markdown/hugo-docs/en_methods_site_Sites.md
new file mode 100644
index 0000000..ef7ff8b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_Sites.md
@@ -0,0 +1,15 @@
+---
+title: Sites
+description: Returns a collection of all sites for all dimensions.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Sites
+ signatures: [SITE.Sites]
+expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0
+---
+
+{{< deprecated-in 0.156.0 >}}
+Use [`hugo.Sites`](/functions/hugo/sites/) instead.
+{{< /deprecated-in >}}
diff --git a/documents/markdown/hugo-docs/en_methods_site_Store.md b/documents/markdown/hugo-docs/en_methods_site_Store.md
new file mode 100644
index 0000000..6c6d57a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_Store.md
@@ -0,0 +1,117 @@
+---
+title: Store
+description: Returns a "scratch pad" to store and manipulate data, scoped to the current site.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: maps.Scratch
+ signatures: [site.Store]
+---
+
+{{< new-in 0.139.0 />}}
+
+Use the `Store` method on a `Site` object to create a [scratch pad](g) to store and manipulate data, scoped to the current site. To create a scratch pad with a different [scope](g), refer to the [scope](#scope) section below.
+
+## Methods
+
+### Set
+
+Sets the value of a given key.
+
+```go-html-template
+{{ site.Store.Set "greeting" "Hello" }}
+```
+
+### Get
+
+Gets the value of a given key.
+
+```go-html-template
+{{ site.Store.Set "greeting" "Hello" }}
+{{ site.Store.Get "greeting" }} → Hello
+```
+
+### Add
+
+Adds a given value to existing value(s) of the given key.
+
+For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list.
+
+```go-html-template
+{{ site.Store.Set "greeting" "Hello" }}
+{{ site.Store.Add "greeting" "Welcome" }}
+{{ site.Store.Get "greeting" }} → HelloWelcome
+```
+
+```go-html-template
+{{ site.Store.Set "total" 3 }}
+{{ site.Store.Add "total" 7 }}
+{{ site.Store.Get "total" }} → 10
+```
+
+```go-html-template
+{{ site.Store.Set "greetings" (slice "Hello") }}
+{{ site.Store.Add "greetings" (slice "Welcome" "Cheers") }}
+{{ site.Store.Get "greetings" }} → [Hello Welcome Cheers]
+ ```
+
+### SetInMap
+
+Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`.
+
+```go-html-template
+{{ site.Store.SetInMap "greetings" "english" "Hello" }}
+{{ site.Store.SetInMap "greetings" "french" "Bonjour" }}
+{{ site.Store.Get "greetings" }} → map[english:Hello french:Bonjour]
+```
+
+### DeleteInMap
+
+Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
+
+```go-html-template
+{{ site.Store.SetInMap "greetings" "english" "Hello" }}
+{{ site.Store.SetInMap "greetings" "french" "Bonjour" }}
+{{ site.Store.DeleteInMap "greetings" "english" }}
+{{ site.Store.Get "greetings" }} → map[french:Bonjour]
+```
+
+### GetSortedMapValues
+
+Returns an array of values from `key` sorted by `mapKey`.
+
+```go-html-template
+{{ site.Store.SetInMap "greetings" "english" "Hello" }}
+{{ site.Store.SetInMap "greetings" "french" "Bonjour" }}
+{{ site.Store.GetSortedMapValues "greetings" }} → [Hello Bonjour]
+```
+
+### Delete
+
+Removes the given key.
+
+```go-html-template
+{{ site.Store.Set "greeting" "Hello" }}
+{{ site.Store.Delete "greeting" }}
+```
+
+{{% include "_common/scratch-pad-scope.md" %}}
+
+## Determinate values
+
+The `Store` method is often used to set scratch pad values within a _shortcode_ template, a _partial_ template called by a _shortcode_ template, or by a _render hook_ template. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.
+
+If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop](g) variable:
+
+```go-html-template
+{{ $noop := .Content }}
+{{ site.Store.Get "mykey" }}
+```
+
+You can also trigger content rendering with the `ContentWithoutSummary`, `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount` methods. For example:
+
+```go-html-template
+{{ $noop := .WordCount }}
+{{ site.Store.Get "mykey" }}
+```
diff --git a/documents/markdown/hugo-docs/en_methods_site_Taxonomies.md b/documents/markdown/hugo-docs/en_methods_site_Taxonomies.md
new file mode 100644
index 0000000..4417c9e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_Taxonomies.md
@@ -0,0 +1,181 @@
+---
+title: Taxonomies
+description: Returns a data structure containing the site's Taxonomy objects, the terms within each Taxonomy object, and the pages to which the terms are assigned.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.TaxonomyList
+ signatures: [SITE.Taxonomies]
+---
+
+Conceptually, the `Taxonomies` method on a `Site` object returns a data structure such as:
+
+<!-- markdownlint-disable MD007 MD032 -->
+{{< code-toggle file=hugo >}}
+taxonomy a:
+ - term 1:
+ - page 1
+ - page 2
+ - term 2:
+ - page 1
+taxonomy b:
+ - term 1:
+ - page 2
+ - term 2:
+ - page 1
+ - page 2
+{{< /code-toggle >}}
+<!-- markdownlint-enable MD007 MD032 -->
+
+For example, on a book review site you might create two taxonomies; one for genres and another for authors.
+
+With this project configuration:
+
+{{< code-toggle file=hugo >}}
+[taxonomies]
+genre = 'genres'
+author = 'authors'
+{{< /code-toggle >}}
+
+And this content structure:
+
+```text
+content/
+├── books/
+│ ├── and-then-there-were-none.md --> genres: suspense
+│ ├── death-on-the-nile.md --> genres: suspense
+│ └── jamaica-inn.md --> genres: suspense, romance
+│ └── pride-and-prejudice.md --> genres: romance
+└── _index.md
+```
+
+Conceptually, the taxonomies data structure looks like:
+
+<!-- markdownlint-disable MD007 MD032 -->
+{{< code-toggle file=hugo >}}
+genres:
+ - suspense:
+ - And Then There Were None
+ - Death on the Nile
+ - Jamaica Inn
+ - romance:
+ - Jamaica Inn
+ - Pride and Prejudice
+authors:
+ - achristie:
+ - And Then There Were None
+ - Death on the Nile
+ - ddmaurier:
+ - Jamaica Inn
+ - jausten:
+ - Pride and Prejudice
+{{< /code-toggle >}}
+<!-- markdownlint-enable MD007 MD032 -->
+
+To list the "suspense" books:
+
+```go-html-template
+<ul>
+ {{ range .Site.Taxonomies.genres.suspense }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Hugo renders this to:
+
+```html
+<ul>
+ <li><a href="/books/and-then-there-were-none/">And Then There Were None</a></li>
+ <li><a href="/books/death-on-the-nile/">Death on the Nile</a></li>
+ <li><a href="/books/jamaica-inn/">Jamaica Inn</a></li>
+</ul>
+```
+
+> [!note]
+> Hugo's taxonomy system is powerful, allowing you to classify content and create relationships between pages.
+>
+> Please see the [taxonomies] section for a complete explanation and examples.
+
+## Examples
+
+### List content with the same taxonomy term
+
+If you are using a taxonomy for something like a series of posts, you can list individual pages associated with the same term. For example:
+
+```go-html-template
+<ul>
+ {{ range .Site.Taxonomies.series.golang }}
+ <li><a href="{{ .Page.RelPermalink }}">{{ .Page.Title }}</a></li>
+ {{ end }}
+</ul>
+```
+
+### List all content in a given taxonomy
+
+This would be very useful in a sidebar as “featured content”. You could even have different sections of “featured content” by assigning different terms to the content.
+
+```go-html-template
+<section id="menu">
+ <ul>
+ {{ range $term, $taxonomy := .Site.Taxonomies.featured }}
+ <li>{{ $term }}</li>
+ <ul>
+ {{ range $taxonomy.Pages }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+ {{ end }}
+ </ul>
+</section>
+```
+
+### Render a site's taxonomies
+
+The following example displays all terms in a site's tags taxonomy:
+
+```go-html-template
+<ul>
+ {{ range .Site.Taxonomies.tags }}
+ <li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li>
+ {{ end }}
+</ul>
+```
+
+This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms.
+
+```go-html-template {file="layouts/_partials/all-taxonomies.html"}
+{{ with .Site.Taxonomies }}
+ {{ $numberOfTerms := 0 }}
+ {{ range $taxonomy, $terms := . }}
+ {{ $numberOfTerms = len . | add $numberOfTerms }}
+ {{ end }}
+
+ {{ if gt $numberOfTerms 0 }}
+ <ul>
+ {{ range $taxonomy, $terms := . }}
+ {{ with $terms }}
+ <li>
+ <a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a>
+ <ul>
+ {{ range $term, $weightedPages := . }}
+ <li>
+ <a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a>
+ <ul>
+ {{ range $weightedPages }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+ </li>
+ {{ end }}
+ </ul>
+ </li>
+ {{ end }}
+ {{ end }}
+ </ul>
+ {{ end }}
+{{ end }}
+```
+
+[taxonomies]: /content-management/taxonomies/
diff --git a/documents/markdown/hugo-docs/en_methods_site_Title.md b/documents/markdown/hugo-docs/en_methods_site_Title.md
new file mode 100644
index 0000000..ad8a48c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_Title.md
@@ -0,0 +1,22 @@
+---
+title: Title
+description: Returns the title as defined in your project configuration.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [SITE.Title]
+---
+
+Project configuration:
+
+{{< code-toggle file=hugo >}}
+title = 'My Documentation Site'
+{{< /code-toggle >}}
+
+Template:
+
+```go-html-template
+{{ .Site.Title }} → My Documentation Site
+```
diff --git a/documents/markdown/hugo-docs/en_methods_site_Version.md b/documents/markdown/hugo-docs/en_methods_site_Version.md
new file mode 100644
index 0000000..d424d46
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site_Version.md
@@ -0,0 +1,34 @@
+---
+title: Version
+description: Returns the Version object for the given site.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: versions.Version
+ signatures: [SITE.Version]
+---
+
+{{< new-in 0.153.0 />}}
+
+The `Version` method on a `Site` object returns the `Version` object for the given site, derived from the version definition in your project configuration.
+
+## Methods
+
+### IsDefault
+
+(`bool`) Reports whether this is the [default version][].
+
+```go-html-template
+{{ .Site.Version.IsDefault }} → true
+```
+
+### Name
+
+(`string`) Returns the version name. This is the lowercased key from your project configuration.
+
+```go-html-template
+{{ .Site.Version.Name }} → v1.0.0
+```
+
+[default version]: /quick-reference/glossary/#default-version
diff --git a/documents/markdown/hugo-docs/en_methods_site__index.md b/documents/markdown/hugo-docs/en_methods_site__index.md
new file mode 100644
index 0000000..4f878a1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_site__index.md
@@ -0,0 +1,8 @@
+---
+title: Site methods
+linkTitle: Site
+description: Use these methods with a Site object.
+categories: []
+keywords: []
+aliases: [/variables/site/]
+---
diff --git a/documents/markdown/hugo-docs/en_methods_taxonomy_Alphabetical.md b/documents/markdown/hugo-docs/en_methods_taxonomy_Alphabetical.md
new file mode 100644
index 0000000..af4af59
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_taxonomy_Alphabetical.md
@@ -0,0 +1,69 @@
+---
+title: Alphabetical
+description: Returns an ordered taxonomy, sorted alphabetically by term.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.OrderedTaxonomy
+ signatures: [TAXONOMY.Alphabetical]
+---
+
+The `Alphabetical` method on a `Taxonomy` object returns an [ordered taxonomy](g), sorted alphabetically by [term](g).
+
+While a `Taxonomy` object is a [map](g), an ordered taxonomy is a [slice](g), where each element is an object that contains the term and a slice of its [weighted pages](g).
+
+{{% include "/_common/methods/taxonomy/get-a-taxonomy-object.md" %}}
+
+## Get the ordered taxonomy
+
+Now that we have captured the “genres” Taxonomy object, let's get the ordered taxonomy sorted alphabetically by term:
+
+```go-html-template
+{{ $taxonomyObject.Alphabetical }}
+```
+
+To reverse the sort order:
+
+```go-html-template
+{{ $taxonomyObject.Alphabetical.Reverse }}
+```
+
+To inspect the data structure:
+
+```go-html-template
+<pre>{{ debug.Dump $taxonomyObject.Alphabetical }}</pre>
+```
+
+{{% include "/_common/methods/taxonomy/ordered-taxonomy-element-methods.md" %}}
+
+## Example
+
+With this template:
+
+```go-html-template
+{{ range $taxonomyObject.Alphabetical }}
+ <h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a> ({{ .Count }})</h2>
+ <ul>
+ {{ range .Pages.ByTitle }}
+ <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+Hugo renders:
+
+```html
+<h2><a href="/genres/romance/">romance</a> (2)</h2>
+<ul>
+ <li><a href="/books/jamaica-inn/">Jamaica inn</a></li>
+ <li><a href="/books/pride-and-prejudice/">Pride and prejudice</a></li>
+</ul>
+<h2><a href="/genres/suspense/">suspense</a> (3)</h2>
+<ul>
+ <li><a href="/books/and-then-there-were-none/">And then there were none</a></li>
+ <li><a href="/books/death-on-the-nile/">Death on the nile</a></li>
+ <li><a href="/books/jamaica-inn/">Jamaica inn</a></li>
+</ul>
+```
diff --git a/documents/markdown/hugo-docs/en_methods_taxonomy_ByCount.md b/documents/markdown/hugo-docs/en_methods_taxonomy_ByCount.md
new file mode 100644
index 0000000..196b317
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_taxonomy_ByCount.md
@@ -0,0 +1,69 @@
+---
+title: ByCount
+description: Returns an ordered taxonomy, sorted by the number of pages associated with each term.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.OrderedTaxonomy
+ signatures: [TAXONOMY.ByCount]
+---
+
+The `ByCount` method on a `Taxonomy` object returns an [ordered taxonomy](g), sorted by the number of pages associated with each [term](g), then sorted alphabetically by term in the event of a tie.
+
+While a `Taxonomy` object is a [map](g), an ordered taxonomy is a [slice](g), where each element is an object that contains the term and a slice of its [weighted pages](g).
+
+{{% include "/_common/methods/taxonomy/get-a-taxonomy-object.md" %}}
+
+## Get the ordered taxonomy
+
+Now that we have captured the “genres” Taxonomy object, let's get the ordered taxonomy sorted by the number of pages associated with each term:
+
+```go-html-template
+{{ $taxonomyObject.ByCount }}
+```
+
+To reverse the sort order:
+
+```go-html-template
+{{ $taxonomyObject.ByCount.Reverse }}
+```
+
+To inspect the data structure:
+
+```go-html-template
+<pre>{{ debug.Dump $taxonomyObject.ByCount }}</pre>
+```
+
+{{% include "/_common/methods/taxonomy/ordered-taxonomy-element-methods.md" %}}
+
+## Example
+
+With this template:
+
+```go-html-template
+{{ range $taxonomyObject.ByCount }}
+ <h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a> ({{ .Count }})</h2>
+ <ul>
+ {{ range .Pages.ByTitle }}
+ <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+Hugo renders:
+
+```html
+<h2><a href="/genres/suspense/">suspense</a> (3)</h2>
+<ul>
+ <li><a href="/books/and-then-there-were-none/">And then there were none</a></li>
+ <li><a href="/books/death-on-the-nile/">Death on the nile</a></li>
+ <li><a href="/books/jamaica-inn/">Jamaica inn</a></li>
+</ul>
+<h2><a href="/genres/romance/">romance</a> (2)</h2>
+<ul>
+ <li><a href="/books/jamaica-inn/">Jamaica inn</a></li>
+ <li><a href="/books/pride-and-prejudice/">Pride and prejudice</a></li>
+</ul>
+```
diff --git a/documents/markdown/hugo-docs/en_methods_taxonomy_Count.md b/documents/markdown/hugo-docs/en_methods_taxonomy_Count.md
new file mode 100644
index 0000000..76af8ee
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_taxonomy_Count.md
@@ -0,0 +1,22 @@
+---
+title: Count
+description: Returns the number of number of weighted pages to which the given term has been assigned.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [TAXONOMY.Count TERM]
+---
+
+The `Count` method on a `Taxonomy` object returns the number of number of [weighted pages](g) to which the given [term](g) has been assigned.
+
+{{% include "/_common/methods/taxonomy/get-a-taxonomy-object.md" %}}
+
+## Count the weighted pages
+
+Now that we have captured the "genres" `Taxonomy` object, let's count the number of weighted pages to which the "suspense" term has been assigned:
+
+```go-html-template
+{{ $taxonomyObject.Count "suspense" }} → 3
+```
diff --git a/documents/markdown/hugo-docs/en_methods_taxonomy_Get.md b/documents/markdown/hugo-docs/en_methods_taxonomy_Get.md
new file mode 100644
index 0000000..03c1848
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_taxonomy_Get.md
@@ -0,0 +1,67 @@
+---
+title: Get
+description: Returns a slice of weighted pages to which the given term has been assigned.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.WeightedPages
+ signatures: [TAXONOMY.Get TERM]
+---
+
+The `Get` method on a `Taxonomy` object returns a slice of [weighted pages](g) to which the given [term](g) has been assigned.
+
+{{% include "/_common/methods/taxonomy/get-a-taxonomy-object.md" %}}
+
+## Get the weighted pages
+
+Now that we have captured the "genres" `Taxonomy` object, let's get the weighted pages to which the "suspense" term has been assigned:
+
+```go-html-template
+{{ $weightedPages := $taxonomyObject.Get "suspense" }}
+```
+
+The above is equivalent to:
+
+```go-html-template
+{{ $weightedPages := $taxonomyObject.suspense }}
+```
+
+But, if the term is not a valid [identifier](g), you cannot use the [chaining](g) syntax. For example, this will throw an error because the identifier contains a hyphen:
+
+```go-html-template
+{{ $weightedPages := $taxonomyObject.my-genre }}
+```
+
+You could also use the [`index`] function, but the syntax is more verbose:
+
+```go-html-template
+{{ $weightedPages := index $taxonomyObject "my-genre" }}
+```
+
+To inspect the data structure:
+
+```go-html-template
+<pre>{{ debug.Dump $weightedPages }}</pre>
+```
+
+## Example
+
+With this template:
+
+```go-html-template
+{{ $weightedPages := $taxonomyObject.Get "suspense" }}
+{{ range $weightedPages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+Hugo renders:
+
+```html
+<h2><a href="/books/jamaica-inn/">Jamaica inn</a></h2>
+<h2><a href="/books/death-on-the-nile/">Death on the nile</a></h2>
+<h2><a href="/books/and-then-there-were-none/">And then there were none</a></h2>
+```
+
+[`index`]: /functions/collections/indexfunction/
diff --git a/documents/markdown/hugo-docs/en_methods_taxonomy_Page.md b/documents/markdown/hugo-docs/en_methods_taxonomy_Page.md
new file mode 100644
index 0000000..628148e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_taxonomy_Page.md
@@ -0,0 +1,24 @@
+---
+title: Page
+description: Returns the taxonomy page or nil if the taxonomy has no terms.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Page
+ signatures: [TAXONOMY.Page]
+---
+
+This `TAXONOMY` method returns nil if the taxonomy has no terms, so you must code defensively:
+
+```go-html-template
+{{ with .Site.Taxonomies.tags.Page }}
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+{{ end }}
+```
+
+This is rendered to:
+
+```html
+<a href="/tags/">Tags</a>
+```
diff --git a/documents/markdown/hugo-docs/en_methods_taxonomy__index.md b/documents/markdown/hugo-docs/en_methods_taxonomy__index.md
new file mode 100644
index 0000000..9cf4c74
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_taxonomy__index.md
@@ -0,0 +1,7 @@
+---
+title: Taxonomy methods
+linkTitle: Taxonomy
+description: Use these methods with a Taxonomy object.
+keywords: []
+aliases: [/variables/taxonomy/]
+---
diff --git a/documents/markdown/hugo-docs/en_methods_time_Add.md b/documents/markdown/hugo-docs/en_methods_time_Add.md
new file mode 100644
index 0000000..e518a16
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_Add.md
@@ -0,0 +1,20 @@
+---
+title: Add
+description: Returns the given time plus the given duration.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: time.Time
+ signatures: [TIME.Add DURATION]
+---
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+
+{{ $d1 = time.ParseDuration "3h20m10s" }}
+{{ $d2 = time.ParseDuration "-3h20m10s" }}
+
+{{ $t.Add $d1 }} → 2023-01-28 03:05:08 -0800 PST
+{{ $t.Add $d2 }} → 2023-01-27 20:24:48 -0800 PST
+```
diff --git a/documents/markdown/hugo-docs/en_methods_time_AddDate.md b/documents/markdown/hugo-docs/en_methods_time_AddDate.md
new file mode 100644
index 0000000..ffc93c7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_AddDate.md
@@ -0,0 +1,37 @@
+---
+title: AddDate
+description: Returns the time corresponding to adding the given number of years, months, and days to the given time.Time value.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: time.Time
+ signatures: [TIME.AddDate YEARS MONTHS DAYS]
+aliases: [/functions/adddate]
+---
+
+```go-html-template
+{{ $d := "2022-01-01" | time.AsTime }}
+
+{{ $d.AddDate 0 0 1 | time.Format "2006-01-02" }} → 2022-01-02
+{{ $d.AddDate 0 1 1 | time.Format "2006-01-02" }} → 2022-02-02
+{{ $d.AddDate 1 1 1 | time.Format "2006-01-02" }} → 2023-02-02
+
+{{ $d.AddDate -1 -1 -1 | time.Format "2006-01-02" }} → 2020-11-30
+```
+
+> [!note]
+> When adding months or years, Hugo normalizes the final `time.Time` value if the resulting day does not exist. For example, adding one month to 31 January produces 2 March or 3 March, depending on the year.
+>
+> See [this explanation](https://github.com/golang/go/issues/31145#issuecomment-479067967) from the Go team.
+
+```go-html-template
+{{ $d := "2023-01-31" | time.AsTime }}
+{{ $d.AddDate 0 1 0 | time.Format "2006-01-02" }} → 2023-03-03
+
+{{ $d := "2024-01-31" | time.AsTime }}
+{{ $d.AddDate 0 1 0 | time.Format "2006-01-02" }} → 2024-03-02
+
+{{ $d := "2024-02-29" | time.AsTime }}
+{{ $d.AddDate 1 0 0 | time.Format "2006-01-02" }} → 2025-03-01
+```
diff --git a/documents/markdown/hugo-docs/en_methods_time_After.md b/documents/markdown/hugo-docs/en_methods_time_After.md
new file mode 100644
index 0000000..1c8d41f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_After.md
@@ -0,0 +1,17 @@
+---
+title: After
+description: Reports whether TIME1 is after TIME2.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [TIME1.After TIME2]
+---
+
+```go-html-template
+{{ $t1 := time.AsTime "2023-01-01T17:00:00-08:00" }}
+{{ $t2 := time.AsTime "2010-01-01T17:00:00-08:00" }}
+
+{{ $t1.After $t2 }} → true
+```
diff --git a/documents/markdown/hugo-docs/en_methods_time_Before.md b/documents/markdown/hugo-docs/en_methods_time_Before.md
new file mode 100644
index 0000000..f6dc3a8
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_Before.md
@@ -0,0 +1,16 @@
+---
+title: Before
+description: Reports whether TIME1 is before TIME2.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [TIME1.Before TIME2]
+---
+
+```go-html-template
+{{ $t1 := time.AsTime "2023-01-01T17:00:00-08:00" }}
+{{ $t2 := time.AsTime "2030-01-01T17:00:00-08:00" }}
+
+{{ $t1.Before $t2 }} → true
diff --git a/documents/markdown/hugo-docs/en_methods_time_Day.md b/documents/markdown/hugo-docs/en_methods_time_Day.md
new file mode 100644
index 0000000..e9e6787
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_Day.md
@@ -0,0 +1,15 @@
+---
+title: Day
+description: Returns the day of the month of the given time.Time value.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [TIME.Day]
+---
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.Day }} → 27
+```
diff --git a/documents/markdown/hugo-docs/en_methods_time_Equal.md b/documents/markdown/hugo-docs/en_methods_time_Equal.md
new file mode 100644
index 0000000..6db1042
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_Equal.md
@@ -0,0 +1,17 @@
+---
+title: Equal
+description: Reports whether TIME1 is equal to TIME2.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [TIME1.Equal TIME2]
+---
+
+```go-html-template
+{{ $t1 := time.AsTime "2023-01-01T17:00:00-08:00" }}
+{{ $t2 := time.AsTime "2023-01-01T20:00:00-05:00" }}
+
+{{ $t1.Equal $t2 }} → true
+```
diff --git a/documents/markdown/hugo-docs/en_methods_time_Format.md b/documents/markdown/hugo-docs/en_methods_time_Format.md
new file mode 100644
index 0000000..8a484b7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_Format.md
@@ -0,0 +1,88 @@
+---
+title: Format
+description: Returns a textual representation of the time.Time value formatted according to the layout string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [TIME.Format LAYOUT]
+aliases: [/methods/time/format]
+---
+
+```go-template
+{{ $t := "2023-01-27T23:44:58-08:00" }}
+{{ $t = time.AsTime $t }}
+{{ $format := "2 Jan 2006" }}
+
+{{ $t.Format $format }} → 27 Jan 2023
+```
+
+> [!note]
+> To [localize](g) the return value, use the [`time.Format`] function instead.
+
+Use the `Format` method with any `time.Time` value, including the four predefined front matter dates:
+
+```go-html-template
+{{ $format := "2 Jan 2006" }}
+
+{{ .Date.Format $format }}
+{{ .PublishDate.Format $format }}
+{{ .ExpiryDate.Format $format }}
+{{ .Lastmod.Format $format }}
+```
+
+> [!note]
+> Use the [`time.Format`] function to format string representations of dates, and to format raw TOML dates that exclude time and time zone offset.
+
+## Layout string
+
+{{% include "/_common/time-layout-string.md" %}}
+
+## Examples
+
+Given this front matter:
+
+{{< code-toggle fm=true >}}
+title = "About time"
+date = 2023-01-27T23:44:58-08:00
+{{< /code-toggle >}}
+
+The examples below were rendered in the `America/Los_Angeles` time zone:
+
+Format string|Result
+:--|:--
+`Monday, January 2, 2006`|`Friday, January 27, 2023`
+`Mon Jan 2 2006`|`Fri Jan 27 2023`
+`January 2006`|`January 2023`
+`2006-01-02`|`2023-01-27`
+`Monday`|`Friday`
+`02 Jan 06 15:04 MST`|`27 Jan 23 23:44 PST`
+`Mon, 02 Jan 2006 15:04:05 MST`|`Fri, 27 Jan 2023 23:44:58 PST`
+`Mon, 02 Jan 2006 15:04:05 -0700`|`Fri, 27 Jan 2023 23:44:58 -0800`
+
+## UTC and local time
+
+Convert and format any `time.Time` value to either Coordinated Universal Time (UTC) or local time.
+
+```go-html-template
+{{ $t := "2023-01-27T23:44:58-08:00" }}
+{{ $t = time.AsTime $t }}
+{{ $format := "2 Jan 2006 3:04:05 PM MST" }}
+
+{{ $t.UTC.Format $format }} → 28 Jan 2023 7:44:58 AM UTC
+{{ $t.Local.Format $format }} → 27 Jan 2023 11:44:58 PM PST
+```
+
+## Ordinal representation
+
+Use the [`humanize`](/functions/inflect/humanize) function to render the day of the month as an ordinal number:
+
+```go-html-template
+{{ $t := "2023-01-27T23:44:58-08:00" }}
+{{ $t = time.AsTime $t }}
+
+{{ humanize $t.Day }} of {{ $t.Format "January 2006" }} → 27th of January 2023
+```
+
+[`time.Format`]: /functions/time/format/
diff --git a/documents/markdown/hugo-docs/en_methods_time_Hour.md b/documents/markdown/hugo-docs/en_methods_time_Hour.md
new file mode 100644
index 0000000..28ecf62
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_Hour.md
@@ -0,0 +1,15 @@
+---
+title: Hour
+description: Returns the hour within the day of the given time.Time value, in the range [0, 23].
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [TIME.Hour]
+---
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.Hour }} → 23
+```
diff --git a/documents/markdown/hugo-docs/en_methods_time_IsDST.md b/documents/markdown/hugo-docs/en_methods_time_IsDST.md
new file mode 100644
index 0000000..28177b1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_IsDST.md
@@ -0,0 +1,18 @@
+---
+title: IsDST
+description: Reports whether the given time.Time value is in Daylight Savings Time.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [TIME.IsDST]
+---
+
+```go-html-template
+{{ $t1 := time.AsTime "2023-01-01T00:00:00-08:00" }}
+{{ $t2 := time.AsTime "2023-07-01T00:00:00-07:00" }}
+
+{{ $t1.IsDST }} → false
+{{ $t2.IsDST }} → true
+```
diff --git a/documents/markdown/hugo-docs/en_methods_time_IsZero.md b/documents/markdown/hugo-docs/en_methods_time_IsZero.md
new file mode 100644
index 0000000..4001727
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_IsZero.md
@@ -0,0 +1,18 @@
+---
+title: IsZero
+description: Reports whether the given time.Time value represents the zero time instant, January 1, year 1, 00:00:00 UTC.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [TIME.IsZero]
+---
+
+````go-html-template
+{{ $t1 := time.AsTime "2023-01-01T00:00:00-08:00" }}
+{{ $t2 := time.AsTime "0001-01-01T00:00:00-00:00" }}
+
+{{ $t1.IsZero }} → false
+{{ $t2.IsZero }} → true
+```
diff --git a/documents/markdown/hugo-docs/en_methods_time_Local.md b/documents/markdown/hugo-docs/en_methods_time_Local.md
new file mode 100644
index 0000000..74fe889
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_Local.md
@@ -0,0 +1,15 @@
+---
+title: Local
+description: Returns the given time.Time value with the location set to local time.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: time.Time
+ signatures: [TIME.Local]
+---
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-28T07:44:58+00:00" }}
+{{ $t.Local }} → 2023-01-27 23:44:58 -0800 PST
+```
diff --git a/documents/markdown/hugo-docs/en_methods_time_Minute.md b/documents/markdown/hugo-docs/en_methods_time_Minute.md
new file mode 100644
index 0000000..b53db6d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_Minute.md
@@ -0,0 +1,15 @@
+---
+title: Minute
+description: Returns the minute offset within the hour of the given time.Time value, in the range [0, 59].
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [TIME.Minute]
+---
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.Minute }} → 44
+```
diff --git a/documents/markdown/hugo-docs/en_methods_time_Month.md b/documents/markdown/hugo-docs/en_methods_time_Month.md
new file mode 100644
index 0000000..b0ccea9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_Month.md
@@ -0,0 +1,24 @@
+---
+title: Month
+description: Returns the month of the year of the given time.Time value.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: time.Month
+ signatures: [TIME.Month]
+---
+
+To convert the `time.Month` value to a string:
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.Month.String }} → January
+```
+
+To convert the `time.Month` value to an integer.
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.Month | int }} → 1
+```
diff --git a/documents/markdown/hugo-docs/en_methods_time_Nanosecond.md b/documents/markdown/hugo-docs/en_methods_time_Nanosecond.md
new file mode 100644
index 0000000..d895f96
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_Nanosecond.md
@@ -0,0 +1,15 @@
+---
+title: Nanosecond
+description: Returns the nanosecond offset within the second of the given time.Time value, in the range [0, 999999999].
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [TIME.Nanosecond]
+---
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.Nanosecond }} → 0
+```
diff --git a/documents/markdown/hugo-docs/en_methods_time_Round.md b/documents/markdown/hugo-docs/en_methods_time_Round.md
new file mode 100644
index 0000000..afda0e2
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_Round.md
@@ -0,0 +1,21 @@
+---
+title: Round
+description: Returns the result of rounding TIME to the nearest multiple of DURATION since January 1, 0001, 00:00:00 UTC.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: time.Time
+ signatures: [TIME.Round DURATION]
+---
+
+The rounding behavior for halfway values is to round up.
+
+The `Round` method operates on TIME as an absolute duration since the [zero time](g); it does not operate on the presentation form of the time. If DURATION is a multiple of one hour, `Round` may return a time with a non-zero minute, depending on the time zone.
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $d := time.ParseDuration "1h" }}
+
+{{ ($t.Round $d).Format "2006-01-02T15:04:05-00:00" }} → 2023-01-28T00:00:00-00:00
+```
diff --git a/documents/markdown/hugo-docs/en_methods_time_Second.md b/documents/markdown/hugo-docs/en_methods_time_Second.md
new file mode 100644
index 0000000..3af086f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_Second.md
@@ -0,0 +1,15 @@
+---
+title: Second
+description: Returns the second offset within the minute of the given time.Time value, in the range [0, 59].
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [TIME.Second]
+---
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.Second }} → 58
+```
diff --git a/documents/markdown/hugo-docs/en_methods_time_Sub.md b/documents/markdown/hugo-docs/en_methods_time_Sub.md
new file mode 100644
index 0000000..d48bf34
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_Sub.md
@@ -0,0 +1,17 @@
+---
+title: Sub
+description: Returns the duration computed by subtracting TIME2 from TIME1.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: time.Duration
+ signatures: [TIME1.Sub TIME2]
+---
+
+```go-html-template
+{{ $t1 := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t2 := time.AsTime "2023-01-26T22:34:38-08:00" }}
+
+{{ $t1.Sub $t2 }} → 25h10m20s
+```
diff --git a/documents/markdown/hugo-docs/en_methods_time_Truncate.md b/documents/markdown/hugo-docs/en_methods_time_Truncate.md
new file mode 100644
index 0000000..b90c384
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_Truncate.md
@@ -0,0 +1,19 @@
+---
+title: Truncate
+description: Returns the result of rounding TIME down to a multiple of DURATION since January 1, 0001, 00:00:00 UTC.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: time.Time
+ signatures: [TIME.Truncate DURATION]
+---
+
+The `Truncate` method operates on TIME as an absolute duration since the [zero time](g); it does not operate on the presentation form of the time. If DURATION is a multiple of one hour, `Truncate` may return a time with a non-zero minute, depending on the time zone.
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $d := time.ParseDuration "1h" }}
+
+{{ ($t.Truncate $d).Format "2006-01-02T15:04:05-00:00" }} → 2023-01-27T23:00:00-00:00
+```
diff --git a/documents/markdown/hugo-docs/en_methods_time_UTC.md b/documents/markdown/hugo-docs/en_methods_time_UTC.md
new file mode 100644
index 0000000..e131a00
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_UTC.md
@@ -0,0 +1,14 @@
+---
+title: UTC
+description: Returns the given time.Time value with the location set to UTC.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: time.Time
+ signatures: [TIME.UTC]
+---
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.UTC }} → 2023-01-28 07:44:58 +0000 UTC
diff --git a/documents/markdown/hugo-docs/en_methods_time_Unix.md b/documents/markdown/hugo-docs/en_methods_time_Unix.md
new file mode 100644
index 0000000..73deb52
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_Unix.md
@@ -0,0 +1,17 @@
+---
+title: Unix
+description: Returns the given time.Time value expressed as the number of seconds elapsed since January 1, 1970 UTC.
+categories: []
+params:
+ functions_and_methods:
+ returnType: int64
+ signatures: [TIME.Unix]
+aliases: [/functions/unix]
+---
+
+See [Unix epoch](https://en.wikipedia.org/wiki/Unix_time).
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.Unix }} → 1674891898
+```
diff --git a/documents/markdown/hugo-docs/en_methods_time_UnixMicro.md b/documents/markdown/hugo-docs/en_methods_time_UnixMicro.md
new file mode 100644
index 0000000..fadb091
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_UnixMicro.md
@@ -0,0 +1,17 @@
+---
+title: UnixMicro
+description: Returns the given time.Time value expressed as the number of microseconds elapsed since January 1, 1970 UTC.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int64
+ signatures: [TIME.UnixMicro]
+---
+
+See [Unix epoch](https://en.wikipedia.org/wiki/Unix_time).
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.UnixMicro }} → 1674891898000000
+```
diff --git a/documents/markdown/hugo-docs/en_methods_time_UnixMilli.md b/documents/markdown/hugo-docs/en_methods_time_UnixMilli.md
new file mode 100644
index 0000000..9d2261d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_UnixMilli.md
@@ -0,0 +1,17 @@
+---
+title: UnixMilli
+description: Returns the given time.Time value expressed as the number of milliseconds elapsed since January 1, 1970 UTC.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int64
+ signatures: [TIME.UnixMilli]
+---
+
+See [Unix epoch](https://en.wikipedia.org/wiki/Unix_time).
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.UnixMilli }} → 1674891898000
+```
diff --git a/documents/markdown/hugo-docs/en_methods_time_UnixNano.md b/documents/markdown/hugo-docs/en_methods_time_UnixNano.md
new file mode 100644
index 0000000..4159dde
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_UnixNano.md
@@ -0,0 +1,17 @@
+---
+title: UnixNano
+description: Returns the given time.Time value expressed as the number of nanoseconds elapsed since January 1, 1970 UTC.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int64
+ signatures: [TIME.UnixNano]
+---
+
+See [Unix epoch](https://en.wikipedia.org/wiki/Unix_time).
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.UnixNano }} → 1674891898000000000
+```
diff --git a/documents/markdown/hugo-docs/en_methods_time_Weekday.md b/documents/markdown/hugo-docs/en_methods_time_Weekday.md
new file mode 100644
index 0000000..da939ff
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_Weekday.md
@@ -0,0 +1,23 @@
+---
+title: Weekday
+description: Returns the day of the week of the given time.Time value.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: time.Weekday
+ signatures: [TIME.Weekday]
+---
+
+To convert the `time.Weekday` value to a string:
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.Weekday.String }} → Friday
+```
+
+To convert the `time.Weekday` value to an integer.
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.Weekday | int }} → 5
diff --git a/documents/markdown/hugo-docs/en_methods_time_Year.md b/documents/markdown/hugo-docs/en_methods_time_Year.md
new file mode 100644
index 0000000..3f647ea
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_Year.md
@@ -0,0 +1,15 @@
+---
+title: Year
+description: Returns the year of the given time.Time value.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [TIME.Year]
+---
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.Year }} → 2023
+```
diff --git a/documents/markdown/hugo-docs/en_methods_time_YearDay.md b/documents/markdown/hugo-docs/en_methods_time_YearDay.md
new file mode 100644
index 0000000..a93158b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time_YearDay.md
@@ -0,0 +1,15 @@
+---
+title: YearDay
+description: Returns the day of the year of the given time.Time value, in the range [1, 365] for non-leap years, and [1, 366] in leap years.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [TIME.YearDay]
+---
+
+```go-html-template
+{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
+{{ $t.YearDay }} → 27
+```
diff --git a/documents/markdown/hugo-docs/en_methods_time__index.md b/documents/markdown/hugo-docs/en_methods_time__index.md
new file mode 100644
index 0000000..067d91a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_methods_time__index.md
@@ -0,0 +1,7 @@
+---
+title: Time methods
+linkTitle: Time
+description: Use these methods with a time.Time value.
+categories: []
+keywords: []
+---
diff --git a/documents/markdown/hugo-docs/en_news__index.md b/documents/markdown/hugo-docs/en_news__index.md
new file mode 100644
index 0000000..23c082c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_news__index.md
@@ -0,0 +1,9 @@
+---
+title: News
+description: Stay up-to-date with the latest news and announcements.
+outputs:
+ - html
+ - rss
+weight: 10
+aliases: [/release-notes/]
+---
diff --git a/documents/markdown/hugo-docs/en_quick-reference__index.md b/documents/markdown/hugo-docs/en_quick-reference__index.md
new file mode 100644
index 0000000..98f978f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference__index.md
@@ -0,0 +1,8 @@
+---
+title: Quick reference guides
+linkTitle: Quick reference
+description: Use these quick reference guides for quick access to key information.
+categories: []
+keywords: []
+weight: 10
+---
diff --git a/documents/markdown/hugo-docs/en_quick-reference_emojis.md b/documents/markdown/hugo-docs/en_quick-reference_emojis.md
new file mode 100644
index 0000000..75f2697
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_emojis.md
@@ -0,0 +1,1681 @@
+---
+title: Emojis
+description: Include emoji shortcodes in your Markdown or templates.
+categories: []
+keywords: []
+params:
+ searchable: false
+---
+
+## Attribution
+
+This quick reference guide was generated using the [ikatyang/emoji-cheat-sheet] project which reads from the [GitHub Emoji API] and the [Unicode Full Emoji List].
+
+Note that GitHub [custom emoji] are not supported.
+
+[custom emoji]: #github-custom-emoji
+[github emoji api]: https://api.github.com/emojis
+[ikatyang/emoji-cheat-sheet]: https://github.com/ikatyang/emoji-cheat-sheet/
+[unicode full emoji list]: https://unicode.org/emoji/charts/full-emoji-list.html
+
+## Usage
+
+Configure Hugo to enable emoji processing in Markdown:
+
+{{< code-toggle file=hugo >}}
+enableEmoji = true
+{{< /code-toggle >}}
+
+With emoji processing enabled, this Markdown:
+
+```md
+Hello! :wave:
+```
+
+Is rendered to:
+
+```html
+Hello! 👋
+```
+
+And in your browser... Hello! :wave:
+
+To process an emoji shortcode from within a template, use the [`emojify`] function or pass the string through the [`RenderString`] method on a `Page` object:
+
+```go-html-template
+{{ "Hello! :wave:" | .RenderString }}
+```
+
+[`emojify`]: /functions/transform/emojify/
+[`RenderString`]: /methods/page/renderstring/
+
+<!--
+To generate the sections below:
+
+ git clone https://github.com/ikatyang/emoji-cheat-sheet
+ cd emoji-cheat-sheet
+ npm install
+ npm run generate
+
+Then...
+
+ 1. Copy and paste from README.md
+ 2. Search/replace (regex) "^###\s" with "## "
+ 3. Search/replace "^####\s " with "### "
+ 4. Search/replace (regex) "<br />" ""
+-->
+
+## Table of Contents
+
+- [Smileys & Emotion](#smileys--emotion)
+- [People & Body](#people--body)
+- [Animals & Nature](#animals--nature)
+- [Food & Drink](#food--drink)
+- [Travel & Places](#travel--places)
+- [Activities](#activities)
+- [Objects](#objects)
+- [Symbols](#symbols)
+- [Flags](#flags)
+- [GitHub Custom Emoji](#github-custom-emoji)
+
+## Smileys & Emotion
+
+- [Face Smiling](#face-smiling)
+- [Face Affection](#face-affection)
+- [Face Tongue](#face-tongue)
+- [Face Hand](#face-hand)
+- [Face Neutral Skeptical](#face-neutral-skeptical)
+- [Face Sleepy](#face-sleepy)
+- [Face Unwell](#face-unwell)
+- [Face Hat](#face-hat)
+- [Face Glasses](#face-glasses)
+- [Face Concerned](#face-concerned)
+- [Face Negative](#face-negative)
+- [Face Costume](#face-costume)
+- [Cat Face](#cat-face)
+- [Monkey Face](#monkey-face)
+- [Heart](#heart)
+- [Emotion](#emotion)
+
+### Face Smiling
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#smileys--emotion) | :grinning: | `:grinning:` | :smiley: | `:smiley:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :smile: | `:smile:` | :grin: | `:grin:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :laughing: | `:laughing:` `:satisfied:` | :sweat_smile: | `:sweat_smile:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :rofl: | `:rofl:` | :joy: | `:joy:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :slightly_smiling_face: | `:slightly_smiling_face:` | :upside_down_face: | `:upside_down_face:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :melting_face: | `:melting_face:` | :wink: | `:wink:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :blush: | `:blush:` | :innocent: | `:innocent:` | [top](#table-of-contents) |
+
+### Face Affection
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#smileys--emotion) | :smiling_face_with_three_hearts: | `:smiling_face_with_three_hearts:` | :heart_eyes: | `:heart_eyes:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :star_struck: | `:star_struck:` | :kissing_heart: | `:kissing_heart:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :kissing: | `:kissing:` | :relaxed: | `:relaxed:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :kissing_closed_eyes: | `:kissing_closed_eyes:` | :kissing_smiling_eyes: | `:kissing_smiling_eyes:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :smiling_face_with_tear: | `:smiling_face_with_tear:` | | | [top](#table-of-contents) |
+
+### Face Tongue
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#smileys--emotion) | :yum: | `:yum:` | :stuck_out_tongue: | `:stuck_out_tongue:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :stuck_out_tongue_winking_eye: | `:stuck_out_tongue_winking_eye:` | :zany_face: | `:zany_face:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :stuck_out_tongue_closed_eyes: | `:stuck_out_tongue_closed_eyes:` | :money_mouth_face: | `:money_mouth_face:` | [top](#table-of-contents) |
+
+### Face Hand
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#smileys--emotion) | :hugs: | `:hugs:` | :hand_over_mouth: | `:hand_over_mouth:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :face_with_open_eyes_and_hand_over_mouth: | `:face_with_open_eyes_and_hand_over_mouth:` | :face_with_peeking_eye: | `:face_with_peeking_eye:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :shushing_face: | `:shushing_face:` | :thinking: | `:thinking:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :saluting_face: | `:saluting_face:` | | | [top](#table-of-contents) |
+
+### Face Neutral Skeptical
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#smileys--emotion) | :zipper_mouth_face: | `:zipper_mouth_face:` | :raised_eyebrow: | `:raised_eyebrow:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :neutral_face: | `:neutral_face:` | :expressionless: | `:expressionless:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :no_mouth: | `:no_mouth:` | :dotted_line_face: | `:dotted_line_face:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :face_in_clouds: | `:face_in_clouds:` | :smirk: | `:smirk:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :unamused: | `:unamused:` | :roll_eyes: | `:roll_eyes:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :grimacing: | `:grimacing:` | :face_exhaling: | `:face_exhaling:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :lying_face: | `:lying_face:` | :shaking_face: | `:shaking_face:` | [top](#table-of-contents) |
+
+### Face Sleepy
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#smileys--emotion) | :relieved: | `:relieved:` | :pensive: | `:pensive:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :sleepy: | `:sleepy:` | :drooling_face: | `:drooling_face:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :sleeping: | `:sleeping:` | | | [top](#table-of-contents) |
+
+### Face Unwell
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#smileys--emotion) | :mask: | `:mask:` | :face_with_thermometer: | `:face_with_thermometer:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :face_with_head_bandage: | `:face_with_head_bandage:` | :nauseated_face: | `:nauseated_face:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :vomiting_face: | `:vomiting_face:` | :sneezing_face: | `:sneezing_face:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :hot_face: | `:hot_face:` | :cold_face: | `:cold_face:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :woozy_face: | `:woozy_face:` | :dizzy_face: | `:dizzy_face:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :face_with_spiral_eyes: | `:face_with_spiral_eyes:` | :exploding_head: | `:exploding_head:` | [top](#table-of-contents) |
+
+### Face Hat
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#smileys--emotion) | :cowboy_hat_face: | `:cowboy_hat_face:` | :partying_face: | `:partying_face:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :disguised_face: | `:disguised_face:` | | | [top](#table-of-contents) |
+
+### Face Glasses
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#smileys--emotion) | :sunglasses: | `:sunglasses:` | :nerd_face: | `:nerd_face:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :monocle_face: | `:monocle_face:` | | | [top](#table-of-contents) |
+
+### Face Concerned
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#smileys--emotion) | :confused: | `:confused:` | :face_with_diagonal_mouth: | `:face_with_diagonal_mouth:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :worried: | `:worried:` | :slightly_frowning_face: | `:slightly_frowning_face:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :frowning_face: | `:frowning_face:` | :open_mouth: | `:open_mouth:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :hushed: | `:hushed:` | :astonished: | `:astonished:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :flushed: | `:flushed:` | :pleading_face: | `:pleading_face:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :face_holding_back_tears: | `:face_holding_back_tears:` | :frowning: | `:frowning:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :anguished: | `:anguished:` | :fearful: | `:fearful:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :cold_sweat: | `:cold_sweat:` | :disappointed_relieved: | `:disappointed_relieved:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :cry: | `:cry:` | :sob: | `:sob:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :scream: | `:scream:` | :confounded: | `:confounded:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :persevere: | `:persevere:` | :disappointed: | `:disappointed:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :sweat: | `:sweat:` | :weary: | `:weary:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :tired_face: | `:tired_face:` | :yawning_face: | `:yawning_face:` | [top](#table-of-contents) |
+
+### Face Negative
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#smileys--emotion) | :triumph: | `:triumph:` | :pout: | `:pout:` `:rage:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :angry: | `:angry:` | :cursing_face: | `:cursing_face:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :smiling_imp: | `:smiling_imp:` | :imp: | `:imp:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :skull: | `:skull:` | :skull_and_crossbones: | `:skull_and_crossbones:` | [top](#table-of-contents) |
+
+### Face Costume
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#smileys--emotion) | :hankey: | `:hankey:` `:poop:` `:shit:` | :clown_face: | `:clown_face:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :japanese_ogre: | `:japanese_ogre:` | :japanese_goblin: | `:japanese_goblin:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :ghost: | `:ghost:` | :alien: | `:alien:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :space_invader: | `:space_invader:` | :robot: | `:robot:` | [top](#table-of-contents) |
+
+### Cat Face
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#smileys--emotion) | :smiley_cat: | `:smiley_cat:` | :smile_cat: | `:smile_cat:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :joy_cat: | `:joy_cat:` | :heart_eyes_cat: | `:heart_eyes_cat:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :smirk_cat: | `:smirk_cat:` | :kissing_cat: | `:kissing_cat:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :scream_cat: | `:scream_cat:` | :crying_cat_face: | `:crying_cat_face:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :pouting_cat: | `:pouting_cat:` | | | [top](#table-of-contents) |
+
+### Monkey Face
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#smileys--emotion) | :see_no_evil: | `:see_no_evil:` | :hear_no_evil: | `:hear_no_evil:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :speak_no_evil: | `:speak_no_evil:` | | | [top](#table-of-contents) |
+
+### Heart
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#smileys--emotion) | :love_letter: | `:love_letter:` | :cupid: | `:cupid:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :gift_heart: | `:gift_heart:` | :sparkling_heart: | `:sparkling_heart:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :heartpulse: | `:heartpulse:` | :heartbeat: | `:heartbeat:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :revolving_hearts: | `:revolving_hearts:` | :two_hearts: | `:two_hearts:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :heart_decoration: | `:heart_decoration:` | :heavy_heart_exclamation: | `:heavy_heart_exclamation:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :broken_heart: | `:broken_heart:` | :heart_on_fire: | `:heart_on_fire:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :mending_heart: | `:mending_heart:` | :heart: | `:heart:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :pink_heart: | `:pink_heart:` | :orange_heart: | `:orange_heart:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :yellow_heart: | `:yellow_heart:` | :green_heart: | `:green_heart:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :blue_heart: | `:blue_heart:` | :light_blue_heart: | `:light_blue_heart:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :purple_heart: | `:purple_heart:` | :brown_heart: | `:brown_heart:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :black_heart: | `:black_heart:` | :grey_heart: | `:grey_heart:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :white_heart: | `:white_heart:` | | | [top](#table-of-contents) |
+
+### Emotion
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#smileys--emotion) | :kiss: | `:kiss:` | :100: | `:100:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :anger: | `:anger:` | :boom: | `:boom:` `:collision:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :dizzy: | `:dizzy:` | :sweat_drops: | `:sweat_drops:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :dash: | `:dash:` | :hole: | `:hole:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :speech_balloon: | `:speech_balloon:` | :eye_speech_bubble: | `:eye_speech_bubble:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :left_speech_bubble: | `:left_speech_bubble:` | :right_anger_bubble: | `:right_anger_bubble:` | [top](#table-of-contents) |
+| [top](#smileys--emotion) | :thought_balloon: | `:thought_balloon:` | :zzz: | `:zzz:` | [top](#table-of-contents) |
+
+## People & Body
+
+- [Hand Fingers Open](#hand-fingers-open)
+- [Hand Fingers Partial](#hand-fingers-partial)
+- [Hand Single Finger](#hand-single-finger)
+- [Hand Fingers Closed](#hand-fingers-closed)
+- [Hands](#hands)
+- [Hand Prop](#hand-prop)
+- [Body Parts](#body-parts)
+- [Person](#person)
+- [Person Gesture](#person-gesture)
+- [Person Role](#person-role)
+- [Person Fantasy](#person-fantasy)
+- [Person Activity](#person-activity)
+- [Person Sport](#person-sport)
+- [Person Resting](#person-resting)
+- [Family](#family)
+- [Person Symbol](#person-symbol)
+
+### Hand Fingers Open
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :wave: | `:wave:` | :raised_back_of_hand: | `:raised_back_of_hand:` | [top](#table-of-contents) |
+| [top](#people--body) | :raised_hand_with_fingers_splayed: | `:raised_hand_with_fingers_splayed:` | :hand: | `:hand:` `:raised_hand:` | [top](#table-of-contents) |
+| [top](#people--body) | :vulcan_salute: | `:vulcan_salute:` | :rightwards_hand: | `:rightwards_hand:` | [top](#table-of-contents) |
+| [top](#people--body) | :leftwards_hand: | `:leftwards_hand:` | :palm_down_hand: | `:palm_down_hand:` | [top](#table-of-contents) |
+| [top](#people--body) | :palm_up_hand: | `:palm_up_hand:` | :leftwards_pushing_hand: | `:leftwards_pushing_hand:` | [top](#table-of-contents) |
+| [top](#people--body) | :rightwards_pushing_hand: | `:rightwards_pushing_hand:` | | | [top](#table-of-contents) |
+
+### Hand Fingers Partial
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :ok_hand: | `:ok_hand:` | :pinched_fingers: | `:pinched_fingers:` | [top](#table-of-contents) |
+| [top](#people--body) | :pinching_hand: | `:pinching_hand:` | :v: | `:v:` | [top](#table-of-contents) |
+| [top](#people--body) | :crossed_fingers: | `:crossed_fingers:` | :hand_with_index_finger_and_thumb_crossed: | `:hand_with_index_finger_and_thumb_crossed:` | [top](#table-of-contents) |
+| [top](#people--body) | :love_you_gesture: | `:love_you_gesture:` | :metal: | `:metal:` | [top](#table-of-contents) |
+| [top](#people--body) | :call_me_hand: | `:call_me_hand:` | | | [top](#table-of-contents) |
+
+### Hand Single Finger
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :point_left: | `:point_left:` | :point_right: | `:point_right:` | [top](#table-of-contents) |
+| [top](#people--body) | :point_up_2: | `:point_up_2:` | :fu: | `:fu:` `:middle_finger:` | [top](#table-of-contents) |
+| [top](#people--body) | :point_down: | `:point_down:` | :point_up: | `:point_up:` | [top](#table-of-contents) |
+| [top](#people--body) | :index_pointing_at_the_viewer: | `:index_pointing_at_the_viewer:` | | | [top](#table-of-contents) |
+
+### Hand Fingers Closed
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :+1: | `:+1:` `:thumbsup:` | :-1: | `:-1:` `:thumbsdown:` | [top](#table-of-contents) |
+| [top](#people--body) | :fist: | `:fist:` `:fist_raised:` | :facepunch: | `:facepunch:` `:fist_oncoming:` `:punch:` | [top](#table-of-contents) |
+| [top](#people--body) | :fist_left: | `:fist_left:` | :fist_right: | `:fist_right:` | [top](#table-of-contents) |
+
+### Hands
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :clap: | `:clap:` | :raised_hands: | `:raised_hands:` | [top](#table-of-contents) |
+| [top](#people--body) | :heart_hands: | `:heart_hands:` | :open_hands: | `:open_hands:` | [top](#table-of-contents) |
+| [top](#people--body) | :palms_up_together: | `:palms_up_together:` | :handshake: | `:handshake:` | [top](#table-of-contents) |
+| [top](#people--body) | :pray: | `:pray:` | | | [top](#table-of-contents) |
+
+### Hand Prop
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :writing_hand: | `:writing_hand:` | :nail_care: | `:nail_care:` | [top](#table-of-contents) |
+| [top](#people--body) | :selfie: | `:selfie:` | | | [top](#table-of-contents) |
+
+### Body Parts
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :muscle: | `:muscle:` | :mechanical_arm: | `:mechanical_arm:` | [top](#table-of-contents) |
+| [top](#people--body) | :mechanical_leg: | `:mechanical_leg:` | :leg: | `:leg:` | [top](#table-of-contents) |
+| [top](#people--body) | :foot: | `:foot:` | :ear: | `:ear:` | [top](#table-of-contents) |
+| [top](#people--body) | :ear_with_hearing_aid: | `:ear_with_hearing_aid:` | :nose: | `:nose:` | [top](#table-of-contents) |
+| [top](#people--body) | :brain: | `:brain:` | :anatomical_heart: | `:anatomical_heart:` | [top](#table-of-contents) |
+| [top](#people--body) | :lungs: | `:lungs:` | :tooth: | `:tooth:` | [top](#table-of-contents) |
+| [top](#people--body) | :bone: | `:bone:` | :eyes: | `:eyes:` | [top](#table-of-contents) |
+| [top](#people--body) | :eye: | `:eye:` | :tongue: | `:tongue:` | [top](#table-of-contents) |
+| [top](#people--body) | :lips: | `:lips:` | :biting_lip: | `:biting_lip:` | [top](#table-of-contents) |
+
+### Person
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :baby: | `:baby:` | :child: | `:child:` | [top](#table-of-contents) |
+| [top](#people--body) | :boy: | `:boy:` | :girl: | `:girl:` | [top](#table-of-contents) |
+| [top](#people--body) | :adult: | `:adult:` | :blond_haired_person: | `:blond_haired_person:` | [top](#table-of-contents) |
+| [top](#people--body) | :man: | `:man:` | :bearded_person: | `:bearded_person:` | [top](#table-of-contents) |
+| [top](#people--body) | :man_beard: | `:man_beard:` | :woman_beard: | `:woman_beard:` | [top](#table-of-contents) |
+| [top](#people--body) | :red_haired_man: | `:red_haired_man:` | :curly_haired_man: | `:curly_haired_man:` | [top](#table-of-contents) |
+| [top](#people--body) | :white_haired_man: | `:white_haired_man:` | :bald_man: | `:bald_man:` | [top](#table-of-contents) |
+| [top](#people--body) | :woman: | `:woman:` | :red_haired_woman: | `:red_haired_woman:` | [top](#table-of-contents) |
+| [top](#people--body) | :person_red_hair: | `:person_red_hair:` | :curly_haired_woman: | `:curly_haired_woman:` | [top](#table-of-contents) |
+| [top](#people--body) | :person_curly_hair: | `:person_curly_hair:` | :white_haired_woman: | `:white_haired_woman:` | [top](#table-of-contents) |
+| [top](#people--body) | :person_white_hair: | `:person_white_hair:` | :bald_woman: | `:bald_woman:` | [top](#table-of-contents) |
+| [top](#people--body) | :person_bald: | `:person_bald:` | :blond_haired_woman: | `:blond_haired_woman:` `:blonde_woman:` | [top](#table-of-contents) |
+| [top](#people--body) | :blond_haired_man: | `:blond_haired_man:` | :older_adult: | `:older_adult:` | [top](#table-of-contents) |
+| [top](#people--body) | :older_man: | `:older_man:` | :older_woman: | `:older_woman:` | [top](#table-of-contents) |
+
+### Person Gesture
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :frowning_person: | `:frowning_person:` | :frowning_man: | `:frowning_man:` | [top](#table-of-contents) |
+| [top](#people--body) | :frowning_woman: | `:frowning_woman:` | :pouting_face: | `:pouting_face:` | [top](#table-of-contents) |
+| [top](#people--body) | :pouting_man: | `:pouting_man:` | :pouting_woman: | `:pouting_woman:` | [top](#table-of-contents) |
+| [top](#people--body) | :no_good: | `:no_good:` | :ng_man: | `:ng_man:` `:no_good_man:` | [top](#table-of-contents) |
+| [top](#people--body) | :ng_woman: | `:ng_woman:` `:no_good_woman:` | :ok_person: | `:ok_person:` | [top](#table-of-contents) |
+| [top](#people--body) | :ok_man: | `:ok_man:` | :ok_woman: | `:ok_woman:` | [top](#table-of-contents) |
+| [top](#people--body) | :information_desk_person: | `:information_desk_person:` `:tipping_hand_person:` | :sassy_man: | `:sassy_man:` `:tipping_hand_man:` | [top](#table-of-contents) |
+| [top](#people--body) | :sassy_woman: | `:sassy_woman:` `:tipping_hand_woman:` | :raising_hand: | `:raising_hand:` | [top](#table-of-contents) |
+| [top](#people--body) | :raising_hand_man: | `:raising_hand_man:` | :raising_hand_woman: | `:raising_hand_woman:` | [top](#table-of-contents) |
+| [top](#people--body) | :deaf_person: | `:deaf_person:` | :deaf_man: | `:deaf_man:` | [top](#table-of-contents) |
+| [top](#people--body) | :deaf_woman: | `:deaf_woman:` | :bow: | `:bow:` | [top](#table-of-contents) |
+| [top](#people--body) | :bowing_man: | `:bowing_man:` | :bowing_woman: | `:bowing_woman:` | [top](#table-of-contents) |
+| [top](#people--body) | :facepalm: | `:facepalm:` | :man_facepalming: | `:man_facepalming:` | [top](#table-of-contents) |
+| [top](#people--body) | :woman_facepalming: | `:woman_facepalming:` | :shrug: | `:shrug:` | [top](#table-of-contents) |
+| [top](#people--body) | :man_shrugging: | `:man_shrugging:` | :woman_shrugging: | `:woman_shrugging:` | [top](#table-of-contents) |
+
+### Person Role
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :health_worker: | `:health_worker:` | :man_health_worker: | `:man_health_worker:` | [top](#table-of-contents) |
+| [top](#people--body) | :woman_health_worker: | `:woman_health_worker:` | :student: | `:student:` | [top](#table-of-contents) |
+| [top](#people--body) | :man_student: | `:man_student:` | :woman_student: | `:woman_student:` | [top](#table-of-contents) |
+| [top](#people--body) | :teacher: | `:teacher:` | :man_teacher: | `:man_teacher:` | [top](#table-of-contents) |
+| [top](#people--body) | :woman_teacher: | `:woman_teacher:` | :judge: | `:judge:` | [top](#table-of-contents) |
+| [top](#people--body) | :man_judge: | `:man_judge:` | :woman_judge: | `:woman_judge:` | [top](#table-of-contents) |
+| [top](#people--body) | :farmer: | `:farmer:` | :man_farmer: | `:man_farmer:` | [top](#table-of-contents) |
+| [top](#people--body) | :woman_farmer: | `:woman_farmer:` | :cook: | `:cook:` | [top](#table-of-contents) |
+| [top](#people--body) | :man_cook: | `:man_cook:` | :woman_cook: | `:woman_cook:` | [top](#table-of-contents) |
+| [top](#people--body) | :mechanic: | `:mechanic:` | :man_mechanic: | `:man_mechanic:` | [top](#table-of-contents) |
+| [top](#people--body) | :woman_mechanic: | `:woman_mechanic:` | :factory_worker: | `:factory_worker:` | [top](#table-of-contents) |
+| [top](#people--body) | :man_factory_worker: | `:man_factory_worker:` | :woman_factory_worker: | `:woman_factory_worker:` | [top](#table-of-contents) |
+| [top](#people--body) | :office_worker: | `:office_worker:` | :man_office_worker: | `:man_office_worker:` | [top](#table-of-contents) |
+| [top](#people--body) | :woman_office_worker: | `:woman_office_worker:` | :scientist: | `:scientist:` | [top](#table-of-contents) |
+| [top](#people--body) | :man_scientist: | `:man_scientist:` | :woman_scientist: | `:woman_scientist:` | [top](#table-of-contents) |
+| [top](#people--body) | :technologist: | `:technologist:` | :man_technologist: | `:man_technologist:` | [top](#table-of-contents) |
+| [top](#people--body) | :woman_technologist: | `:woman_technologist:` | :singer: | `:singer:` | [top](#table-of-contents) |
+| [top](#people--body) | :man_singer: | `:man_singer:` | :woman_singer: | `:woman_singer:` | [top](#table-of-contents) |
+| [top](#people--body) | :artist: | `:artist:` | :man_artist: | `:man_artist:` | [top](#table-of-contents) |
+| [top](#people--body) | :woman_artist: | `:woman_artist:` | :pilot: | `:pilot:` | [top](#table-of-contents) |
+| [top](#people--body) | :man_pilot: | `:man_pilot:` | :woman_pilot: | `:woman_pilot:` | [top](#table-of-contents) |
+| [top](#people--body) | :astronaut: | `:astronaut:` | :man_astronaut: | `:man_astronaut:` | [top](#table-of-contents) |
+| [top](#people--body) | :woman_astronaut: | `:woman_astronaut:` | :firefighter: | `:firefighter:` | [top](#table-of-contents) |
+| [top](#people--body) | :man_firefighter: | `:man_firefighter:` | :woman_firefighter: | `:woman_firefighter:` | [top](#table-of-contents) |
+| [top](#people--body) | :cop: | `:cop:` `:police_officer:` | :policeman: | `:policeman:` | [top](#table-of-contents) |
+| [top](#people--body) | :policewoman: | `:policewoman:` | :detective: | `:detective:` | [top](#table-of-contents) |
+| [top](#people--body) | :male_detective: | `:male_detective:` | :female_detective: | `:female_detective:` | [top](#table-of-contents) |
+| [top](#people--body) | :guard: | `:guard:` | :guardsman: | `:guardsman:` | [top](#table-of-contents) |
+| [top](#people--body) | :guardswoman: | `:guardswoman:` | :ninja: | `:ninja:` | [top](#table-of-contents) |
+| [top](#people--body) | :construction_worker: | `:construction_worker:` | :construction_worker_man: | `:construction_worker_man:` | [top](#table-of-contents) |
+| [top](#people--body) | :construction_worker_woman: | `:construction_worker_woman:` | :person_with_crown: | `:person_with_crown:` | [top](#table-of-contents) |
+| [top](#people--body) | :prince: | `:prince:` | :princess: | `:princess:` | [top](#table-of-contents) |
+| [top](#people--body) | :person_with_turban: | `:person_with_turban:` | :man_with_turban: | `:man_with_turban:` | [top](#table-of-contents) |
+| [top](#people--body) | :woman_with_turban: | `:woman_with_turban:` | :man_with_gua_pi_mao: | `:man_with_gua_pi_mao:` | [top](#table-of-contents) |
+| [top](#people--body) | :woman_with_headscarf: | `:woman_with_headscarf:` | :person_in_tuxedo: | `:person_in_tuxedo:` | [top](#table-of-contents) |
+| [top](#people--body) | :man_in_tuxedo: | `:man_in_tuxedo:` | :woman_in_tuxedo: | `:woman_in_tuxedo:` | [top](#table-of-contents) |
+| [top](#people--body) | :person_with_veil: | `:person_with_veil:` | :man_with_veil: | `:man_with_veil:` | [top](#table-of-contents) |
+| [top](#people--body) | :bride_with_veil: | `:bride_with_veil:` `:woman_with_veil:` | :pregnant_woman: | `:pregnant_woman:` | [top](#table-of-contents) |
+| [top](#people--body) | :pregnant_man: | `:pregnant_man:` | :pregnant_person: | `:pregnant_person:` | [top](#table-of-contents) |
+| [top](#people--body) | :breast_feeding: | `:breast_feeding:` | :woman_feeding_baby: | `:woman_feeding_baby:` | [top](#table-of-contents) |
+| [top](#people--body) | :man_feeding_baby: | `:man_feeding_baby:` | :person_feeding_baby: | `:person_feeding_baby:` | [top](#table-of-contents) |
+
+### Person Fantasy
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :angel: | `:angel:` | :santa: | `:santa:` | [top](#table-of-contents) |
+| [top](#people--body) | :mrs_claus: | `:mrs_claus:` | :mx_claus: | `:mx_claus:` | [top](#table-of-contents) |
+| [top](#people--body) | :superhero: | `:superhero:` | :superhero_man: | `:superhero_man:` | [top](#table-of-contents) |
+| [top](#people--body) | :superhero_woman: | `:superhero_woman:` | :supervillain: | `:supervillain:` | [top](#table-of-contents) |
+| [top](#people--body) | :supervillain_man: | `:supervillain_man:` | :supervillain_woman: | `:supervillain_woman:` | [top](#table-of-contents) |
+| [top](#people--body) | :mage: | `:mage:` | :mage_man: | `:mage_man:` | [top](#table-of-contents) |
+| [top](#people--body) | :mage_woman: | `:mage_woman:` | :fairy: | `:fairy:` | [top](#table-of-contents) |
+| [top](#people--body) | :fairy_man: | `:fairy_man:` | :fairy_woman: | `:fairy_woman:` | [top](#table-of-contents) |
+| [top](#people--body) | :vampire: | `:vampire:` | :vampire_man: | `:vampire_man:` | [top](#table-of-contents) |
+| [top](#people--body) | :vampire_woman: | `:vampire_woman:` | :merperson: | `:merperson:` | [top](#table-of-contents) |
+| [top](#people--body) | :merman: | `:merman:` | :mermaid: | `:mermaid:` | [top](#table-of-contents) |
+| [top](#people--body) | :elf: | `:elf:` | :elf_man: | `:elf_man:` | [top](#table-of-contents) |
+| [top](#people--body) | :elf_woman: | `:elf_woman:` | :genie: | `:genie:` | [top](#table-of-contents) |
+| [top](#people--body) | :genie_man: | `:genie_man:` | :genie_woman: | `:genie_woman:` | [top](#table-of-contents) |
+| [top](#people--body) | :zombie: | `:zombie:` | :zombie_man: | `:zombie_man:` | [top](#table-of-contents) |
+| [top](#people--body) | :zombie_woman: | `:zombie_woman:` | :troll: | `:troll:` | [top](#table-of-contents) |
+
+### Person Activity
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :massage: | `:massage:` | :massage_man: | `:massage_man:` | [top](#table-of-contents) |
+| [top](#people--body) | :massage_woman: | `:massage_woman:` | :haircut: | `:haircut:` | [top](#table-of-contents) |
+| [top](#people--body) | :haircut_man: | `:haircut_man:` | :haircut_woman: | `:haircut_woman:` | [top](#table-of-contents) |
+| [top](#people--body) | :walking: | `:walking:` | :walking_man: | `:walking_man:` | [top](#table-of-contents) |
+| [top](#people--body) | :walking_woman: | `:walking_woman:` | :standing_person: | `:standing_person:` | [top](#table-of-contents) |
+| [top](#people--body) | :standing_man: | `:standing_man:` | :standing_woman: | `:standing_woman:` | [top](#table-of-contents) |
+| [top](#people--body) | :kneeling_person: | `:kneeling_person:` | :kneeling_man: | `:kneeling_man:` | [top](#table-of-contents) |
+| [top](#people--body) | :kneeling_woman: | `:kneeling_woman:` | :person_with_probing_cane: | `:person_with_probing_cane:` | [top](#table-of-contents) |
+| [top](#people--body) | :man_with_probing_cane: | `:man_with_probing_cane:` | :woman_with_probing_cane: | `:woman_with_probing_cane:` | [top](#table-of-contents) |
+| [top](#people--body) | :person_in_motorized_wheelchair: | `:person_in_motorized_wheelchair:` | :man_in_motorized_wheelchair: | `:man_in_motorized_wheelchair:` | [top](#table-of-contents) |
+| [top](#people--body) | :woman_in_motorized_wheelchair: | `:woman_in_motorized_wheelchair:` | :person_in_manual_wheelchair: | `:person_in_manual_wheelchair:` | [top](#table-of-contents) |
+| [top](#people--body) | :man_in_manual_wheelchair: | `:man_in_manual_wheelchair:` | :woman_in_manual_wheelchair: | `:woman_in_manual_wheelchair:` | [top](#table-of-contents) |
+| [top](#people--body) | :runner: | `:runner:` `:running:` | :running_man: | `:running_man:` | [top](#table-of-contents) |
+| [top](#people--body) | :running_woman: | `:running_woman:` | :dancer: | `:dancer:` `:woman_dancing:` | [top](#table-of-contents) |
+| [top](#people--body) | :man_dancing: | `:man_dancing:` | :business_suit_levitating: | `:business_suit_levitating:` | [top](#table-of-contents) |
+| [top](#people--body) | :dancers: | `:dancers:` | :dancing_men: | `:dancing_men:` | [top](#table-of-contents) |
+| [top](#people--body) | :dancing_women: | `:dancing_women:` | :sauna_person: | `:sauna_person:` | [top](#table-of-contents) |
+| [top](#people--body) | :sauna_man: | `:sauna_man:` | :sauna_woman: | `:sauna_woman:` | [top](#table-of-contents) |
+| [top](#people--body) | :climbing: | `:climbing:` | :climbing_man: | `:climbing_man:` | [top](#table-of-contents) |
+| [top](#people--body) | :climbing_woman: | `:climbing_woman:` | | | [top](#table-of-contents) |
+
+### Person Sport
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :person_fencing: | `:person_fencing:` | :horse_racing: | `:horse_racing:` | [top](#table-of-contents) |
+| [top](#people--body) | :skier: | `:skier:` | :snowboarder: | `:snowboarder:` | [top](#table-of-contents) |
+| [top](#people--body) | :golfing: | `:golfing:` | :golfing_man: | `:golfing_man:` | [top](#table-of-contents) |
+| [top](#people--body) | :golfing_woman: | `:golfing_woman:` | :surfer: | `:surfer:` | [top](#table-of-contents) |
+| [top](#people--body) | :surfing_man: | `:surfing_man:` | :surfing_woman: | `:surfing_woman:` | [top](#table-of-contents) |
+| [top](#people--body) | :rowboat: | `:rowboat:` | :rowing_man: | `:rowing_man:` | [top](#table-of-contents) |
+| [top](#people--body) | :rowing_woman: | `:rowing_woman:` | :swimmer: | `:swimmer:` | [top](#table-of-contents) |
+| [top](#people--body) | :swimming_man: | `:swimming_man:` | :swimming_woman: | `:swimming_woman:` | [top](#table-of-contents) |
+| [top](#people--body) | :bouncing_ball_person: | `:bouncing_ball_person:` | :basketball_man: | `:basketball_man:` `:bouncing_ball_man:` | [top](#table-of-contents) |
+| [top](#people--body) | :basketball_woman: | `:basketball_woman:` `:bouncing_ball_woman:` | :weight_lifting: | `:weight_lifting:` | [top](#table-of-contents) |
+| [top](#people--body) | :weight_lifting_man: | `:weight_lifting_man:` | :weight_lifting_woman: | `:weight_lifting_woman:` | [top](#table-of-contents) |
+| [top](#people--body) | :bicyclist: | `:bicyclist:` | :biking_man: | `:biking_man:` | [top](#table-of-contents) |
+| [top](#people--body) | :biking_woman: | `:biking_woman:` | :mountain_bicyclist: | `:mountain_bicyclist:` | [top](#table-of-contents) |
+| [top](#people--body) | :mountain_biking_man: | `:mountain_biking_man:` | :mountain_biking_woman: | `:mountain_biking_woman:` | [top](#table-of-contents) |
+| [top](#people--body) | :cartwheeling: | `:cartwheeling:` | :man_cartwheeling: | `:man_cartwheeling:` | [top](#table-of-contents) |
+| [top](#people--body) | :woman_cartwheeling: | `:woman_cartwheeling:` | :wrestling: | `:wrestling:` | [top](#table-of-contents) |
+| [top](#people--body) | :men_wrestling: | `:men_wrestling:` | :women_wrestling: | `:women_wrestling:` | [top](#table-of-contents) |
+| [top](#people--body) | :water_polo: | `:water_polo:` | :man_playing_water_polo: | `:man_playing_water_polo:` | [top](#table-of-contents) |
+| [top](#people--body) | :woman_playing_water_polo: | `:woman_playing_water_polo:` | :handball_person: | `:handball_person:` | [top](#table-of-contents) |
+| [top](#people--body) | :man_playing_handball: | `:man_playing_handball:` | :woman_playing_handball: | `:woman_playing_handball:` | [top](#table-of-contents) |
+| [top](#people--body) | :juggling_person: | `:juggling_person:` | :man_juggling: | `:man_juggling:` | [top](#table-of-contents) |
+| [top](#people--body) | :woman_juggling: | `:woman_juggling:` | | | [top](#table-of-contents) |
+
+### Person Resting
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :lotus_position: | `:lotus_position:` | :lotus_position_man: | `:lotus_position_man:` | [top](#table-of-contents) |
+| [top](#people--body) | :lotus_position_woman: | `:lotus_position_woman:` | :bath: | `:bath:` | [top](#table-of-contents) |
+| [top](#people--body) | :sleeping_bed: | `:sleeping_bed:` | | | [top](#table-of-contents) |
+
+### Family
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :people_holding_hands: | `:people_holding_hands:` | :two_women_holding_hands: | `:two_women_holding_hands:` | [top](#table-of-contents) |
+| [top](#people--body) | :couple: | `:couple:` | :two_men_holding_hands: | `:two_men_holding_hands:` | [top](#table-of-contents) |
+| [top](#people--body) | :couplekiss: | `:couplekiss:` | :couplekiss_man_woman: | `:couplekiss_man_woman:` | [top](#table-of-contents) |
+| [top](#people--body) | :couplekiss_man_man: | `:couplekiss_man_man:` | :couplekiss_woman_woman: | `:couplekiss_woman_woman:` | [top](#table-of-contents) |
+| [top](#people--body) | :couple_with_heart: | `:couple_with_heart:` | :couple_with_heart_woman_man: | `:couple_with_heart_woman_man:` | [top](#table-of-contents) |
+| [top](#people--body) | :couple_with_heart_man_man: | `:couple_with_heart_man_man:` | :couple_with_heart_woman_woman: | `:couple_with_heart_woman_woman:` | [top](#table-of-contents) |
+| [top](#people--body) | :family_man_woman_boy: | `:family_man_woman_boy:` | :family_man_woman_girl: | `:family_man_woman_girl:` | [top](#table-of-contents) |
+| [top](#people--body) | :family_man_woman_girl_boy: | `:family_man_woman_girl_boy:` | :family_man_woman_boy_boy: | `:family_man_woman_boy_boy:` | [top](#table-of-contents) |
+| [top](#people--body) | :family_man_woman_girl_girl: | `:family_man_woman_girl_girl:` | :family_man_man_boy: | `:family_man_man_boy:` | [top](#table-of-contents) |
+| [top](#people--body) | :family_man_man_girl: | `:family_man_man_girl:` | :family_man_man_girl_boy: | `:family_man_man_girl_boy:` | [top](#table-of-contents) |
+| [top](#people--body) | :family_man_man_boy_boy: | `:family_man_man_boy_boy:` | :family_man_man_girl_girl: | `:family_man_man_girl_girl:` | [top](#table-of-contents) |
+| [top](#people--body) | :family_woman_woman_boy: | `:family_woman_woman_boy:` | :family_woman_woman_girl: | `:family_woman_woman_girl:` | [top](#table-of-contents) |
+| [top](#people--body) | :family_woman_woman_girl_boy: | `:family_woman_woman_girl_boy:` | :family_woman_woman_boy_boy: | `:family_woman_woman_boy_boy:` | [top](#table-of-contents) |
+| [top](#people--body) | :family_woman_woman_girl_girl: | `:family_woman_woman_girl_girl:` | :family_man_boy: | `:family_man_boy:` | [top](#table-of-contents) |
+| [top](#people--body) | :family_man_boy_boy: | `:family_man_boy_boy:` | :family_man_girl: | `:family_man_girl:` | [top](#table-of-contents) |
+| [top](#people--body) | :family_man_girl_boy: | `:family_man_girl_boy:` | :family_man_girl_girl: | `:family_man_girl_girl:` | [top](#table-of-contents) |
+| [top](#people--body) | :family_woman_boy: | `:family_woman_boy:` | :family_woman_boy_boy: | `:family_woman_boy_boy:` | [top](#table-of-contents) |
+| [top](#people--body) | :family_woman_girl: | `:family_woman_girl:` | :family_woman_girl_boy: | `:family_woman_girl_boy:` | [top](#table-of-contents) |
+| [top](#people--body) | :family_woman_girl_girl: | `:family_woman_girl_girl:` | | | [top](#table-of-contents) |
+
+### Person Symbol
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#people--body) | :speaking_head: | `:speaking_head:` | :bust_in_silhouette: | `:bust_in_silhouette:` | [top](#table-of-contents) |
+| [top](#people--body) | :busts_in_silhouette: | `:busts_in_silhouette:` | :people_hugging: | `:people_hugging:` | [top](#table-of-contents) |
+| [top](#people--body) | :family: | `:family:` | :footprints: | `:footprints:` | [top](#table-of-contents) |
+
+## Animals & Nature
+
+- [Animal Mammal](#animal-mammal)
+- [Animal Bird](#animal-bird)
+- [Animal Amphibian](#animal-amphibian)
+- [Animal Reptile](#animal-reptile)
+- [Animal Marine](#animal-marine)
+- [Animal Bug](#animal-bug)
+- [Plant Flower](#plant-flower)
+- [Plant Other](#plant-other)
+
+### Animal Mammal
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#animals--nature) | :monkey_face: | `:monkey_face:` | :monkey: | `:monkey:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :gorilla: | `:gorilla:` | :orangutan: | `:orangutan:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :dog: | `:dog:` | :dog2: | `:dog2:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :guide_dog: | `:guide_dog:` | :service_dog: | `:service_dog:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :poodle: | `:poodle:` | :wolf: | `:wolf:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :fox_face: | `:fox_face:` | :raccoon: | `:raccoon:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :cat: | `:cat:` | :cat2: | `:cat2:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :black_cat: | `:black_cat:` | :lion: | `:lion:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :tiger: | `:tiger:` | :tiger2: | `:tiger2:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :leopard: | `:leopard:` | :horse: | `:horse:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :moose: | `:moose:` | :donkey: | `:donkey:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :racehorse: | `:racehorse:` | :unicorn: | `:unicorn:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :zebra: | `:zebra:` | :deer: | `:deer:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :bison: | `:bison:` | :cow: | `:cow:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :ox: | `:ox:` | :water_buffalo: | `:water_buffalo:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :cow2: | `:cow2:` | :pig: | `:pig:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :pig2: | `:pig2:` | :boar: | `:boar:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :pig_nose: | `:pig_nose:` | :ram: | `:ram:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :sheep: | `:sheep:` | :goat: | `:goat:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :dromedary_camel: | `:dromedary_camel:` | :camel: | `:camel:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :llama: | `:llama:` | :giraffe: | `:giraffe:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :elephant: | `:elephant:` | :mammoth: | `:mammoth:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :rhinoceros: | `:rhinoceros:` | :hippopotamus: | `:hippopotamus:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :mouse: | `:mouse:` | :mouse2: | `:mouse2:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :rat: | `:rat:` | :hamster: | `:hamster:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :rabbit: | `:rabbit:` | :rabbit2: | `:rabbit2:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :chipmunk: | `:chipmunk:` | :beaver: | `:beaver:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :hedgehog: | `:hedgehog:` | :bat: | `:bat:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :bear: | `:bear:` | :polar_bear: | `:polar_bear:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :koala: | `:koala:` | :panda_face: | `:panda_face:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :sloth: | `:sloth:` | :otter: | `:otter:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :skunk: | `:skunk:` | :kangaroo: | `:kangaroo:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :badger: | `:badger:` | :feet: | `:feet:` `:paw_prints:` | [top](#table-of-contents) |
+
+### Animal Bird
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#animals--nature) | :turkey: | `:turkey:` | :chicken: | `:chicken:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :rooster: | `:rooster:` | :hatching_chick: | `:hatching_chick:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :baby_chick: | `:baby_chick:` | :hatched_chick: | `:hatched_chick:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :bird: | `:bird:` | :penguin: | `:penguin:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :dove: | `:dove:` | :eagle: | `:eagle:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :duck: | `:duck:` | :swan: | `:swan:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :owl: | `:owl:` | :dodo: | `:dodo:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :feather: | `:feather:` | :flamingo: | `:flamingo:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :peacock: | `:peacock:` | :parrot: | `:parrot:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :wing: | `:wing:` | :black_bird: | `:black_bird:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :goose: | `:goose:` | | | [top](#table-of-contents) |
+
+### Animal Amphibian
+
+| | ico | shortcode | |
+| - | :-: | - | - |
+| [top](#animals--nature) | :frog: | `:frog:` | [top](#table-of-contents) |
+
+### Animal Reptile
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#animals--nature) | :crocodile: | `:crocodile:` | :turtle: | `:turtle:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :lizard: | `:lizard:` | :snake: | `:snake:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :dragon_face: | `:dragon_face:` | :dragon: | `:dragon:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :sauropod: | `:sauropod:` | :t-rex: | `:t-rex:` | [top](#table-of-contents) |
+
+### Animal Marine
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#animals--nature) | :whale: | `:whale:` | :whale2: | `:whale2:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :dolphin: | `:dolphin:` `:flipper:` | :seal: | `:seal:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :fish: | `:fish:` | :tropical_fish: | `:tropical_fish:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :blowfish: | `:blowfish:` | :shark: | `:shark:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :octopus: | `:octopus:` | :shell: | `:shell:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :coral: | `:coral:` | :jellyfish: | `:jellyfish:` | [top](#table-of-contents) |
+
+### Animal Bug
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#animals--nature) | :snail: | `:snail:` | :butterfly: | `:butterfly:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :bug: | `:bug:` | :ant: | `:ant:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :bee: | `:bee:` `:honeybee:` | :beetle: | `:beetle:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :lady_beetle: | `:lady_beetle:` | :cricket: | `:cricket:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :cockroach: | `:cockroach:` | :spider: | `:spider:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :spider_web: | `:spider_web:` | :scorpion: | `:scorpion:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :mosquito: | `:mosquito:` | :fly: | `:fly:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :worm: | `:worm:` | :microbe: | `:microbe:` | [top](#table-of-contents) |
+
+### Plant Flower
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#animals--nature) | :bouquet: | `:bouquet:` | :cherry_blossom: | `:cherry_blossom:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :white_flower: | `:white_flower:` | :lotus: | `:lotus:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :rosette: | `:rosette:` | :rose: | `:rose:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :wilted_flower: | `:wilted_flower:` | :hibiscus: | `:hibiscus:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :sunflower: | `:sunflower:` | :blossom: | `:blossom:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :tulip: | `:tulip:` | :hyacinth: | `:hyacinth:` | [top](#table-of-contents) |
+
+### Plant Other
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#animals--nature) | :seedling: | `:seedling:` | :potted_plant: | `:potted_plant:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :evergreen_tree: | `:evergreen_tree:` | :deciduous_tree: | `:deciduous_tree:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :palm_tree: | `:palm_tree:` | :cactus: | `:cactus:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :ear_of_rice: | `:ear_of_rice:` | :herb: | `:herb:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :shamrock: | `:shamrock:` | :four_leaf_clover: | `:four_leaf_clover:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :maple_leaf: | `:maple_leaf:` | :fallen_leaf: | `:fallen_leaf:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :leaves: | `:leaves:` | :empty_nest: | `:empty_nest:` | [top](#table-of-contents) |
+| [top](#animals--nature) | :nest_with_eggs: | `:nest_with_eggs:` | :mushroom: | `:mushroom:` | [top](#table-of-contents) |
+
+## Food & Drink
+
+- [Food Fruit](#food-fruit)
+- [Food Vegetable](#food-vegetable)
+- [Food Prepared](#food-prepared)
+- [Food Asian](#food-asian)
+- [Food Marine](#food-marine)
+- [Food Sweet](#food-sweet)
+- [Drink](#drink)
+- [Dishware](#dishware)
+
+### Food Fruit
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#food--drink) | :grapes: | `:grapes:` | :melon: | `:melon:` | [top](#table-of-contents) |
+| [top](#food--drink) | :watermelon: | `:watermelon:` | :mandarin: | `:mandarin:` `:orange:` `:tangerine:` | [top](#table-of-contents) |
+| [top](#food--drink) | :lemon: | `:lemon:` | :banana: | `:banana:` | [top](#table-of-contents) |
+| [top](#food--drink) | :pineapple: | `:pineapple:` | :mango: | `:mango:` | [top](#table-of-contents) |
+| [top](#food--drink) | :apple: | `:apple:` | :green_apple: | `:green_apple:` | [top](#table-of-contents) |
+| [top](#food--drink) | :pear: | `:pear:` | :peach: | `:peach:` | [top](#table-of-contents) |
+| [top](#food--drink) | :cherries: | `:cherries:` | :strawberry: | `:strawberry:` | [top](#table-of-contents) |
+| [top](#food--drink) | :blueberries: | `:blueberries:` | :kiwi_fruit: | `:kiwi_fruit:` | [top](#table-of-contents) |
+| [top](#food--drink) | :tomato: | `:tomato:` | :olive: | `:olive:` | [top](#table-of-contents) |
+| [top](#food--drink) | :coconut: | `:coconut:` | | | [top](#table-of-contents) |
+
+### Food Vegetable
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#food--drink) | :avocado: | `:avocado:` | :eggplant: | `:eggplant:` | [top](#table-of-contents) |
+| [top](#food--drink) | :potato: | `:potato:` | :carrot: | `:carrot:` | [top](#table-of-contents) |
+| [top](#food--drink) | :corn: | `:corn:` | :hot_pepper: | `:hot_pepper:` | [top](#table-of-contents) |
+| [top](#food--drink) | :bell_pepper: | `:bell_pepper:` | :cucumber: | `:cucumber:` | [top](#table-of-contents) |
+| [top](#food--drink) | :leafy_green: | `:leafy_green:` | :broccoli: | `:broccoli:` | [top](#table-of-contents) |
+| [top](#food--drink) | :garlic: | `:garlic:` | :onion: | `:onion:` | [top](#table-of-contents) |
+| [top](#food--drink) | :peanuts: | `:peanuts:` | :beans: | `:beans:` | [top](#table-of-contents) |
+| [top](#food--drink) | :chestnut: | `:chestnut:` | :ginger_root: | `:ginger_root:` | [top](#table-of-contents) |
+| [top](#food--drink) | :pea_pod: | `:pea_pod:` | | | [top](#table-of-contents) |
+
+### Food Prepared
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#food--drink) | :bread: | `:bread:` | :croissant: | `:croissant:` | [top](#table-of-contents) |
+| [top](#food--drink) | :baguette_bread: | `:baguette_bread:` | :flatbread: | `:flatbread:` | [top](#table-of-contents) |
+| [top](#food--drink) | :pretzel: | `:pretzel:` | :bagel: | `:bagel:` | [top](#table-of-contents) |
+| [top](#food--drink) | :pancakes: | `:pancakes:` | :waffle: | `:waffle:` | [top](#table-of-contents) |
+| [top](#food--drink) | :cheese: | `:cheese:` | :meat_on_bone: | `:meat_on_bone:` | [top](#table-of-contents) |
+| [top](#food--drink) | :poultry_leg: | `:poultry_leg:` | :cut_of_meat: | `:cut_of_meat:` | [top](#table-of-contents) |
+| [top](#food--drink) | :bacon: | `:bacon:` | :hamburger: | `:hamburger:` | [top](#table-of-contents) |
+| [top](#food--drink) | :fries: | `:fries:` | :pizza: | `:pizza:` | [top](#table-of-contents) |
+| [top](#food--drink) | :hotdog: | `:hotdog:` | :sandwich: | `:sandwich:` | [top](#table-of-contents) |
+| [top](#food--drink) | :taco: | `:taco:` | :burrito: | `:burrito:` | [top](#table-of-contents) |
+| [top](#food--drink) | :tamale: | `:tamale:` | :stuffed_flatbread: | `:stuffed_flatbread:` | [top](#table-of-contents) |
+| [top](#food--drink) | :falafel: | `:falafel:` | :egg: | `:egg:` | [top](#table-of-contents) |
+| [top](#food--drink) | :fried_egg: | `:fried_egg:` | :shallow_pan_of_food: | `:shallow_pan_of_food:` | [top](#table-of-contents) |
+| [top](#food--drink) | :stew: | `:stew:` | :fondue: | `:fondue:` | [top](#table-of-contents) |
+| [top](#food--drink) | :bowl_with_spoon: | `:bowl_with_spoon:` | :green_salad: | `:green_salad:` | [top](#table-of-contents) |
+| [top](#food--drink) | :popcorn: | `:popcorn:` | :butter: | `:butter:` | [top](#table-of-contents) |
+| [top](#food--drink) | :salt: | `:salt:` | :canned_food: | `:canned_food:` | [top](#table-of-contents) |
+
+### Food Asian
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#food--drink) | :bento: | `:bento:` | :rice_cracker: | `:rice_cracker:` | [top](#table-of-contents) |
+| [top](#food--drink) | :rice_ball: | `:rice_ball:` | :rice: | `:rice:` | [top](#table-of-contents) |
+| [top](#food--drink) | :curry: | `:curry:` | :ramen: | `:ramen:` | [top](#table-of-contents) |
+| [top](#food--drink) | :spaghetti: | `:spaghetti:` | :sweet_potato: | `:sweet_potato:` | [top](#table-of-contents) |
+| [top](#food--drink) | :oden: | `:oden:` | :sushi: | `:sushi:` | [top](#table-of-contents) |
+| [top](#food--drink) | :fried_shrimp: | `:fried_shrimp:` | :fish_cake: | `:fish_cake:` | [top](#table-of-contents) |
+| [top](#food--drink) | :moon_cake: | `:moon_cake:` | :dango: | `:dango:` | [top](#table-of-contents) |
+| [top](#food--drink) | :dumpling: | `:dumpling:` | :fortune_cookie: | `:fortune_cookie:` | [top](#table-of-contents) |
+| [top](#food--drink) | :takeout_box: | `:takeout_box:` | | | [top](#table-of-contents) |
+
+### Food Marine
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#food--drink) | :crab: | `:crab:` | :lobster: | `:lobster:` | [top](#table-of-contents) |
+| [top](#food--drink) | :shrimp: | `:shrimp:` | :squid: | `:squid:` | [top](#table-of-contents) |
+| [top](#food--drink) | :oyster: | `:oyster:` | | | [top](#table-of-contents) |
+
+### Food Sweet
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#food--drink) | :icecream: | `:icecream:` | :shaved_ice: | `:shaved_ice:` | [top](#table-of-contents) |
+| [top](#food--drink) | :ice_cream: | `:ice_cream:` | :doughnut: | `:doughnut:` | [top](#table-of-contents) |
+| [top](#food--drink) | :cookie: | `:cookie:` | :birthday: | `:birthday:` | [top](#table-of-contents) |
+| [top](#food--drink) | :cake: | `:cake:` | :cupcake: | `:cupcake:` | [top](#table-of-contents) |
+| [top](#food--drink) | :pie: | `:pie:` | :chocolate_bar: | `:chocolate_bar:` | [top](#table-of-contents) |
+| [top](#food--drink) | :candy: | `:candy:` | :lollipop: | `:lollipop:` | [top](#table-of-contents) |
+| [top](#food--drink) | :custard: | `:custard:` | :honey_pot: | `:honey_pot:` | [top](#table-of-contents) |
+
+### Drink
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#food--drink) | :baby_bottle: | `:baby_bottle:` | :milk_glass: | `:milk_glass:` | [top](#table-of-contents) |
+| [top](#food--drink) | :coffee: | `:coffee:` | :teapot: | `:teapot:` | [top](#table-of-contents) |
+| [top](#food--drink) | :tea: | `:tea:` | :sake: | `:sake:` | [top](#table-of-contents) |
+| [top](#food--drink) | :champagne: | `:champagne:` | :wine_glass: | `:wine_glass:` | [top](#table-of-contents) |
+| [top](#food--drink) | :cocktail: | `:cocktail:` | :tropical_drink: | `:tropical_drink:` | [top](#table-of-contents) |
+| [top](#food--drink) | :beer: | `:beer:` | :beers: | `:beers:` | [top](#table-of-contents) |
+| [top](#food--drink) | :clinking_glasses: | `:clinking_glasses:` | :tumbler_glass: | `:tumbler_glass:` | [top](#table-of-contents) |
+| [top](#food--drink) | :pouring_liquid: | `:pouring_liquid:` | :cup_with_straw: | `:cup_with_straw:` | [top](#table-of-contents) |
+| [top](#food--drink) | :bubble_tea: | `:bubble_tea:` | :beverage_box: | `:beverage_box:` | [top](#table-of-contents) |
+| [top](#food--drink) | :mate: | `:mate:` | :ice_cube: | `:ice_cube:` | [top](#table-of-contents) |
+
+### Dishware
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#food--drink) | :chopsticks: | `:chopsticks:` | :plate_with_cutlery: | `:plate_with_cutlery:` | [top](#table-of-contents) |
+| [top](#food--drink) | :fork_and_knife: | `:fork_and_knife:` | :spoon: | `:spoon:` | [top](#table-of-contents) |
+| [top](#food--drink) | :hocho: | `:hocho:` `:knife:` | :jar: | `:jar:` | [top](#table-of-contents) |
+| [top](#food--drink) | :amphora: | `:amphora:` | | | [top](#table-of-contents) |
+
+## Travel & Places
+
+- [Place Map](#place-map)
+- [Place Geographic](#place-geographic)
+- [Place Building](#place-building)
+- [Place Religious](#place-religious)
+- [Place Other](#place-other)
+- [Transport Ground](#transport-ground)
+- [Transport Water](#transport-water)
+- [Transport Air](#transport-air)
+- [Hotel](#hotel)
+- [Time](#time)
+- [Sky & Weather](#sky--weather)
+
+### Place Map
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#travel--places) | :earth_africa: | `:earth_africa:` | :earth_americas: | `:earth_americas:` | [top](#table-of-contents) |
+| [top](#travel--places) | :earth_asia: | `:earth_asia:` | :globe_with_meridians: | `:globe_with_meridians:` | [top](#table-of-contents) |
+| [top](#travel--places) | :world_map: | `:world_map:` | :japan: | `:japan:` | [top](#table-of-contents) |
+| [top](#travel--places) | :compass: | `:compass:` | | | [top](#table-of-contents) |
+
+### Place Geographic
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#travel--places) | :mountain_snow: | `:mountain_snow:` | :mountain: | `:mountain:` | [top](#table-of-contents) |
+| [top](#travel--places) | :volcano: | `:volcano:` | :mount_fuji: | `:mount_fuji:` | [top](#table-of-contents) |
+| [top](#travel--places) | :camping: | `:camping:` | :beach_umbrella: | `:beach_umbrella:` | [top](#table-of-contents) |
+| [top](#travel--places) | :desert: | `:desert:` | :desert_island: | `:desert_island:` | [top](#table-of-contents) |
+| [top](#travel--places) | :national_park: | `:national_park:` | | | [top](#table-of-contents) |
+
+### Place Building
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#travel--places) | :stadium: | `:stadium:` | :classical_building: | `:classical_building:` | [top](#table-of-contents) |
+| [top](#travel--places) | :building_construction: | `:building_construction:` | :bricks: | `:bricks:` | [top](#table-of-contents) |
+| [top](#travel--places) | :rock: | `:rock:` | :wood: | `:wood:` | [top](#table-of-contents) |
+| [top](#travel--places) | :hut: | `:hut:` | :houses: | `:houses:` | [top](#table-of-contents) |
+| [top](#travel--places) | :derelict_house: | `:derelict_house:` | :house: | `:house:` | [top](#table-of-contents) |
+| [top](#travel--places) | :house_with_garden: | `:house_with_garden:` | :office: | `:office:` | [top](#table-of-contents) |
+| [top](#travel--places) | :post_office: | `:post_office:` | :european_post_office: | `:european_post_office:` | [top](#table-of-contents) |
+| [top](#travel--places) | :hospital: | `:hospital:` | :bank: | `:bank:` | [top](#table-of-contents) |
+| [top](#travel--places) | :hotel: | `:hotel:` | :love_hotel: | `:love_hotel:` | [top](#table-of-contents) |
+| [top](#travel--places) | :convenience_store: | `:convenience_store:` | :school: | `:school:` | [top](#table-of-contents) |
+| [top](#travel--places) | :department_store: | `:department_store:` | :factory: | `:factory:` | [top](#table-of-contents) |
+| [top](#travel--places) | :japanese_castle: | `:japanese_castle:` | :european_castle: | `:european_castle:` | [top](#table-of-contents) |
+| [top](#travel--places) | :wedding: | `:wedding:` | :tokyo_tower: | `:tokyo_tower:` | [top](#table-of-contents) |
+| [top](#travel--places) | :statue_of_liberty: | `:statue_of_liberty:` | | | [top](#table-of-contents) |
+
+### Place Religious
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#travel--places) | :church: | `:church:` | :mosque: | `:mosque:` | [top](#table-of-contents) |
+| [top](#travel--places) | :hindu_temple: | `:hindu_temple:` | :synagogue: | `:synagogue:` | [top](#table-of-contents) |
+| [top](#travel--places) | :shinto_shrine: | `:shinto_shrine:` | :kaaba: | `:kaaba:` | [top](#table-of-contents) |
+
+### Place Other
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#travel--places) | :fountain: | `:fountain:` | :tent: | `:tent:` | [top](#table-of-contents) |
+| [top](#travel--places) | :foggy: | `:foggy:` | :night_with_stars: | `:night_with_stars:` | [top](#table-of-contents) |
+| [top](#travel--places) | :cityscape: | `:cityscape:` | :sunrise_over_mountains: | `:sunrise_over_mountains:` | [top](#table-of-contents) |
+| [top](#travel--places) | :sunrise: | `:sunrise:` | :city_sunset: | `:city_sunset:` | [top](#table-of-contents) |
+| [top](#travel--places) | :city_sunrise: | `:city_sunrise:` | :bridge_at_night: | `:bridge_at_night:` | [top](#table-of-contents) |
+| [top](#travel--places) | :hotsprings: | `:hotsprings:` | :carousel_horse: | `:carousel_horse:` | [top](#table-of-contents) |
+| [top](#travel--places) | :playground_slide: | `:playground_slide:` | :ferris_wheel: | `:ferris_wheel:` | [top](#table-of-contents) |
+| [top](#travel--places) | :roller_coaster: | `:roller_coaster:` | :barber: | `:barber:` | [top](#table-of-contents) |
+| [top](#travel--places) | :circus_tent: | `:circus_tent:` | | | [top](#table-of-contents) |
+
+### Transport Ground
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#travel--places) | :steam_locomotive: | `:steam_locomotive:` | :railway_car: | `:railway_car:` | [top](#table-of-contents) |
+| [top](#travel--places) | :bullettrain_side: | `:bullettrain_side:` | :bullettrain_front: | `:bullettrain_front:` | [top](#table-of-contents) |
+| [top](#travel--places) | :train2: | `:train2:` | :metro: | `:metro:` | [top](#table-of-contents) |
+| [top](#travel--places) | :light_rail: | `:light_rail:` | :station: | `:station:` | [top](#table-of-contents) |
+| [top](#travel--places) | :tram: | `:tram:` | :monorail: | `:monorail:` | [top](#table-of-contents) |
+| [top](#travel--places) | :mountain_railway: | `:mountain_railway:` | :train: | `:train:` | [top](#table-of-contents) |
+| [top](#travel--places) | :bus: | `:bus:` | :oncoming_bus: | `:oncoming_bus:` | [top](#table-of-contents) |
+| [top](#travel--places) | :trolleybus: | `:trolleybus:` | :minibus: | `:minibus:` | [top](#table-of-contents) |
+| [top](#travel--places) | :ambulance: | `:ambulance:` | :fire_engine: | `:fire_engine:` | [top](#table-of-contents) |
+| [top](#travel--places) | :police_car: | `:police_car:` | :oncoming_police_car: | `:oncoming_police_car:` | [top](#table-of-contents) |
+| [top](#travel--places) | :taxi: | `:taxi:` | :oncoming_taxi: | `:oncoming_taxi:` | [top](#table-of-contents) |
+| [top](#travel--places) | :car: | `:car:` `:red_car:` | :oncoming_automobile: | `:oncoming_automobile:` | [top](#table-of-contents) |
+| [top](#travel--places) | :blue_car: | `:blue_car:` | :pickup_truck: | `:pickup_truck:` | [top](#table-of-contents) |
+| [top](#travel--places) | :truck: | `:truck:` | :articulated_lorry: | `:articulated_lorry:` | [top](#table-of-contents) |
+| [top](#travel--places) | :tractor: | `:tractor:` | :racing_car: | `:racing_car:` | [top](#table-of-contents) |
+| [top](#travel--places) | :motorcycle: | `:motorcycle:` | :motor_scooter: | `:motor_scooter:` | [top](#table-of-contents) |
+| [top](#travel--places) | :manual_wheelchair: | `:manual_wheelchair:` | :motorized_wheelchair: | `:motorized_wheelchair:` | [top](#table-of-contents) |
+| [top](#travel--places) | :auto_rickshaw: | `:auto_rickshaw:` | :bike: | `:bike:` | [top](#table-of-contents) |
+| [top](#travel--places) | :kick_scooter: | `:kick_scooter:` | :skateboard: | `:skateboard:` | [top](#table-of-contents) |
+| [top](#travel--places) | :roller_skate: | `:roller_skate:` | :busstop: | `:busstop:` | [top](#table-of-contents) |
+| [top](#travel--places) | :motorway: | `:motorway:` | :railway_track: | `:railway_track:` | [top](#table-of-contents) |
+| [top](#travel--places) | :oil_drum: | `:oil_drum:` | :fuelpump: | `:fuelpump:` | [top](#table-of-contents) |
+| [top](#travel--places) | :wheel: | `:wheel:` | :rotating_light: | `:rotating_light:` | [top](#table-of-contents) |
+| [top](#travel--places) | :traffic_light: | `:traffic_light:` | :vertical_traffic_light: | `:vertical_traffic_light:` | [top](#table-of-contents) |
+| [top](#travel--places) | :stop_sign: | `:stop_sign:` | :construction: | `:construction:` | [top](#table-of-contents) |
+
+### Transport Water
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#travel--places) | :anchor: | `:anchor:` | :ring_buoy: | `:ring_buoy:` | [top](#table-of-contents) |
+| [top](#travel--places) | :boat: | `:boat:` `:sailboat:` | :canoe: | `:canoe:` | [top](#table-of-contents) |
+| [top](#travel--places) | :speedboat: | `:speedboat:` | :passenger_ship: | `:passenger_ship:` | [top](#table-of-contents) |
+| [top](#travel--places) | :ferry: | `:ferry:` | :motor_boat: | `:motor_boat:` | [top](#table-of-contents) |
+| [top](#travel--places) | :ship: | `:ship:` | | | [top](#table-of-contents) |
+
+### Transport Air
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#travel--places) | :airplane: | `:airplane:` | :small_airplane: | `:small_airplane:` | [top](#table-of-contents) |
+| [top](#travel--places) | :flight_departure: | `:flight_departure:` | :flight_arrival: | `:flight_arrival:` | [top](#table-of-contents) |
+| [top](#travel--places) | :parachute: | `:parachute:` | :seat: | `:seat:` | [top](#table-of-contents) |
+| [top](#travel--places) | :helicopter: | `:helicopter:` | :suspension_railway: | `:suspension_railway:` | [top](#table-of-contents) |
+| [top](#travel--places) | :mountain_cableway: | `:mountain_cableway:` | :aerial_tramway: | `:aerial_tramway:` | [top](#table-of-contents) |
+| [top](#travel--places) | :artificial_satellite: | `:artificial_satellite:` | :rocket: | `:rocket:` | [top](#table-of-contents) |
+| [top](#travel--places) | :flying_saucer: | `:flying_saucer:` | | | [top](#table-of-contents) |
+
+### Hotel
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#travel--places) | :bellhop_bell: | `:bellhop_bell:` | :luggage: | `:luggage:` | [top](#table-of-contents) |
+
+### Time
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#travel--places) | :hourglass: | `:hourglass:` | :hourglass_flowing_sand: | `:hourglass_flowing_sand:` | [top](#table-of-contents) |
+| [top](#travel--places) | :watch: | `:watch:` | :alarm_clock: | `:alarm_clock:` | [top](#table-of-contents) |
+| [top](#travel--places) | :stopwatch: | `:stopwatch:` | :timer_clock: | `:timer_clock:` | [top](#table-of-contents) |
+| [top](#travel--places) | :mantelpiece_clock: | `:mantelpiece_clock:` | :clock12: | `:clock12:` | [top](#table-of-contents) |
+| [top](#travel--places) | :clock1230: | `:clock1230:` | :clock1: | `:clock1:` | [top](#table-of-contents) |
+| [top](#travel--places) | :clock130: | `:clock130:` | :clock2: | `:clock2:` | [top](#table-of-contents) |
+| [top](#travel--places) | :clock230: | `:clock230:` | :clock3: | `:clock3:` | [top](#table-of-contents) |
+| [top](#travel--places) | :clock330: | `:clock330:` | :clock4: | `:clock4:` | [top](#table-of-contents) |
+| [top](#travel--places) | :clock430: | `:clock430:` | :clock5: | `:clock5:` | [top](#table-of-contents) |
+| [top](#travel--places) | :clock530: | `:clock530:` | :clock6: | `:clock6:` | [top](#table-of-contents) |
+| [top](#travel--places) | :clock630: | `:clock630:` | :clock7: | `:clock7:` | [top](#table-of-contents) |
+| [top](#travel--places) | :clock730: | `:clock730:` | :clock8: | `:clock8:` | [top](#table-of-contents) |
+| [top](#travel--places) | :clock830: | `:clock830:` | :clock9: | `:clock9:` | [top](#table-of-contents) |
+| [top](#travel--places) | :clock930: | `:clock930:` | :clock10: | `:clock10:` | [top](#table-of-contents) |
+| [top](#travel--places) | :clock1030: | `:clock1030:` | :clock11: | `:clock11:` | [top](#table-of-contents) |
+| [top](#travel--places) | :clock1130: | `:clock1130:` | | | [top](#table-of-contents) |
+
+### Sky & Weather
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#travel--places) | :new_moon: | `:new_moon:` | :waxing_crescent_moon: | `:waxing_crescent_moon:` | [top](#table-of-contents) |
+| [top](#travel--places) | :first_quarter_moon: | `:first_quarter_moon:` | :moon: | `:moon:` `:waxing_gibbous_moon:` | [top](#table-of-contents) |
+| [top](#travel--places) | :full_moon: | `:full_moon:` | :waning_gibbous_moon: | `:waning_gibbous_moon:` | [top](#table-of-contents) |
+| [top](#travel--places) | :last_quarter_moon: | `:last_quarter_moon:` | :waning_crescent_moon: | `:waning_crescent_moon:` | [top](#table-of-contents) |
+| [top](#travel--places) | :crescent_moon: | `:crescent_moon:` | :new_moon_with_face: | `:new_moon_with_face:` | [top](#table-of-contents) |
+| [top](#travel--places) | :first_quarter_moon_with_face: | `:first_quarter_moon_with_face:` | :last_quarter_moon_with_face: | `:last_quarter_moon_with_face:` | [top](#table-of-contents) |
+| [top](#travel--places) | :thermometer: | `:thermometer:` | :sunny: | `:sunny:` | [top](#table-of-contents) |
+| [top](#travel--places) | :full_moon_with_face: | `:full_moon_with_face:` | :sun_with_face: | `:sun_with_face:` | [top](#table-of-contents) |
+| [top](#travel--places) | :ringed_planet: | `:ringed_planet:` | :star: | `:star:` | [top](#table-of-contents) |
+| [top](#travel--places) | :star2: | `:star2:` | :stars: | `:stars:` | [top](#table-of-contents) |
+| [top](#travel--places) | :milky_way: | `:milky_way:` | :cloud: | `:cloud:` | [top](#table-of-contents) |
+| [top](#travel--places) | :partly_sunny: | `:partly_sunny:` | :cloud_with_lightning_and_rain: | `:cloud_with_lightning_and_rain:` | [top](#table-of-contents) |
+| [top](#travel--places) | :sun_behind_small_cloud: | `:sun_behind_small_cloud:` | :sun_behind_large_cloud: | `:sun_behind_large_cloud:` | [top](#table-of-contents) |
+| [top](#travel--places) | :sun_behind_rain_cloud: | `:sun_behind_rain_cloud:` | :cloud_with_rain: | `:cloud_with_rain:` | [top](#table-of-contents) |
+| [top](#travel--places) | :cloud_with_snow: | `:cloud_with_snow:` | :cloud_with_lightning: | `:cloud_with_lightning:` | [top](#table-of-contents) |
+| [top](#travel--places) | :tornado: | `:tornado:` | :fog: | `:fog:` | [top](#table-of-contents) |
+| [top](#travel--places) | :wind_face: | `:wind_face:` | :cyclone: | `:cyclone:` | [top](#table-of-contents) |
+| [top](#travel--places) | :rainbow: | `:rainbow:` | :closed_umbrella: | `:closed_umbrella:` | [top](#table-of-contents) |
+| [top](#travel--places) | :open_umbrella: | `:open_umbrella:` | :umbrella: | `:umbrella:` | [top](#table-of-contents) |
+| [top](#travel--places) | :parasol_on_ground: | `:parasol_on_ground:` | :zap: | `:zap:` | [top](#table-of-contents) |
+| [top](#travel--places) | :snowflake: | `:snowflake:` | :snowman_with_snow: | `:snowman_with_snow:` | [top](#table-of-contents) |
+| [top](#travel--places) | :snowman: | `:snowman:` | :comet: | `:comet:` | [top](#table-of-contents) |
+| [top](#travel--places) | :fire: | `:fire:` | :droplet: | `:droplet:` | [top](#table-of-contents) |
+| [top](#travel--places) | :ocean: | `:ocean:` | | | [top](#table-of-contents) |
+
+## Activities
+
+- [Event](#event)
+- [Award Medal](#award-medal)
+- [Sport](#sport)
+- [Game](#game)
+- [Arts & Crafts](#arts--crafts)
+
+### Event
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#activities) | :jack_o_lantern: | `:jack_o_lantern:` | :christmas_tree: | `:christmas_tree:` | [top](#table-of-contents) |
+| [top](#activities) | :fireworks: | `:fireworks:` | :sparkler: | `:sparkler:` | [top](#table-of-contents) |
+| [top](#activities) | :firecracker: | `:firecracker:` | :sparkles: | `:sparkles:` | [top](#table-of-contents) |
+| [top](#activities) | :balloon: | `:balloon:` | :tada: | `:tada:` | [top](#table-of-contents) |
+| [top](#activities) | :confetti_ball: | `:confetti_ball:` | :tanabata_tree: | `:tanabata_tree:` | [top](#table-of-contents) |
+| [top](#activities) | :bamboo: | `:bamboo:` | :dolls: | `:dolls:` | [top](#table-of-contents) |
+| [top](#activities) | :flags: | `:flags:` | :wind_chime: | `:wind_chime:` | [top](#table-of-contents) |
+| [top](#activities) | :rice_scene: | `:rice_scene:` | :red_envelope: | `:red_envelope:` | [top](#table-of-contents) |
+| [top](#activities) | :ribbon: | `:ribbon:` | :gift: | `:gift:` | [top](#table-of-contents) |
+| [top](#activities) | :reminder_ribbon: | `:reminder_ribbon:` | :tickets: | `:tickets:` | [top](#table-of-contents) |
+| [top](#activities) | :ticket: | `:ticket:` | | | [top](#table-of-contents) |
+
+### Award Medal
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#activities) | :medal_military: | `:medal_military:` | :trophy: | `:trophy:` | [top](#table-of-contents) |
+| [top](#activities) | :medal_sports: | `:medal_sports:` | :1st_place_medal: | `:1st_place_medal:` | [top](#table-of-contents) |
+| [top](#activities) | :2nd_place_medal: | `:2nd_place_medal:` | :3rd_place_medal: | `:3rd_place_medal:` | [top](#table-of-contents) |
+
+### Sport
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#activities) | :soccer: | `:soccer:` | :baseball: | `:baseball:` | [top](#table-of-contents) |
+| [top](#activities) | :softball: | `:softball:` | :basketball: | `:basketball:` | [top](#table-of-contents) |
+| [top](#activities) | :volleyball: | `:volleyball:` | :football: | `:football:` | [top](#table-of-contents) |
+| [top](#activities) | :rugby_football: | `:rugby_football:` | :tennis: | `:tennis:` | [top](#table-of-contents) |
+| [top](#activities) | :flying_disc: | `:flying_disc:` | :bowling: | `:bowling:` | [top](#table-of-contents) |
+| [top](#activities) | :cricket_game: | `:cricket_game:` | :field_hockey: | `:field_hockey:` | [top](#table-of-contents) |
+| [top](#activities) | :ice_hockey: | `:ice_hockey:` | :lacrosse: | `:lacrosse:` | [top](#table-of-contents) |
+| [top](#activities) | :ping_pong: | `:ping_pong:` | :badminton: | `:badminton:` | [top](#table-of-contents) |
+| [top](#activities) | :boxing_glove: | `:boxing_glove:` | :martial_arts_uniform: | `:martial_arts_uniform:` | [top](#table-of-contents) |
+| [top](#activities) | :goal_net: | `:goal_net:` | :golf: | `:golf:` | [top](#table-of-contents) |
+| [top](#activities) | :ice_skate: | `:ice_skate:` | :fishing_pole_and_fish: | `:fishing_pole_and_fish:` | [top](#table-of-contents) |
+| [top](#activities) | :diving_mask: | `:diving_mask:` | :running_shirt_with_sash: | `:running_shirt_with_sash:` | [top](#table-of-contents) |
+| [top](#activities) | :ski: | `:ski:` | :sled: | `:sled:` | [top](#table-of-contents) |
+| [top](#activities) | :curling_stone: | `:curling_stone:` | | | [top](#table-of-contents) |
+
+### Game
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#activities) | :dart: | `:dart:` | :yo_yo: | `:yo_yo:` | [top](#table-of-contents) |
+| [top](#activities) | :kite: | `:kite:` | :gun: | `:gun:` | [top](#table-of-contents) |
+| [top](#activities) | :8ball: | `:8ball:` | :crystal_ball: | `:crystal_ball:` | [top](#table-of-contents) |
+| [top](#activities) | :magic_wand: | `:magic_wand:` | :video_game: | `:video_game:` | [top](#table-of-contents) |
+| [top](#activities) | :joystick: | `:joystick:` | :slot_machine: | `:slot_machine:` | [top](#table-of-contents) |
+| [top](#activities) | :game_die: | `:game_die:` | :jigsaw: | `:jigsaw:` | [top](#table-of-contents) |
+| [top](#activities) | :teddy_bear: | `:teddy_bear:` | :pinata: | `:pinata:` | [top](#table-of-contents) |
+| [top](#activities) | :mirror_ball: | `:mirror_ball:` | :nesting_dolls: | `:nesting_dolls:` | [top](#table-of-contents) |
+| [top](#activities) | :spades: | `:spades:` | :hearts: | `:hearts:` | [top](#table-of-contents) |
+| [top](#activities) | :diamonds: | `:diamonds:` | :clubs: | `:clubs:` | [top](#table-of-contents) |
+| [top](#activities) | :chess_pawn: | `:chess_pawn:` | :black_joker: | `:black_joker:` | [top](#table-of-contents) |
+| [top](#activities) | :mahjong: | `:mahjong:` | :flower_playing_cards: | `:flower_playing_cards:` | [top](#table-of-contents) |
+
+### Arts & Crafts
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#activities) | :performing_arts: | `:performing_arts:` | :framed_picture: | `:framed_picture:` | [top](#table-of-contents) |
+| [top](#activities) | :art: | `:art:` | :thread: | `:thread:` | [top](#table-of-contents) |
+| [top](#activities) | :sewing_needle: | `:sewing_needle:` | :yarn: | `:yarn:` | [top](#table-of-contents) |
+| [top](#activities) | :knot: | `:knot:` | | | [top](#table-of-contents) |
+
+## Objects
+
+- [Clothing](#clothing)
+- [Sound](#sound)
+- [Music](#music)
+- [Musical Instrument](#musical-instrument)
+- [Phone](#phone)
+- [Computer](#computer)
+- [Light & Video](#light--video)
+- [Book Paper](#book-paper)
+- [Money](#money)
+- [Mail](#mail)
+- [Writing](#writing)
+- [Office](#office)
+- [Lock](#lock)
+- [Tool](#tool)
+- [Science](#science)
+- [Medical](#medical)
+- [Household](#household)
+- [Other Object](#other-object)
+
+### Clothing
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :eyeglasses: | `:eyeglasses:` | :dark_sunglasses: | `:dark_sunglasses:` | [top](#table-of-contents) |
+| [top](#objects) | :goggles: | `:goggles:` | :lab_coat: | `:lab_coat:` | [top](#table-of-contents) |
+| [top](#objects) | :safety_vest: | `:safety_vest:` | :necktie: | `:necktie:` | [top](#table-of-contents) |
+| [top](#objects) | :shirt: | `:shirt:` `:tshirt:` | :jeans: | `:jeans:` | [top](#table-of-contents) |
+| [top](#objects) | :scarf: | `:scarf:` | :gloves: | `:gloves:` | [top](#table-of-contents) |
+| [top](#objects) | :coat: | `:coat:` | :socks: | `:socks:` | [top](#table-of-contents) |
+| [top](#objects) | :dress: | `:dress:` | :kimono: | `:kimono:` | [top](#table-of-contents) |
+| [top](#objects) | :sari: | `:sari:` | :one_piece_swimsuit: | `:one_piece_swimsuit:` | [top](#table-of-contents) |
+| [top](#objects) | :swim_brief: | `:swim_brief:` | :shorts: | `:shorts:` | [top](#table-of-contents) |
+| [top](#objects) | :bikini: | `:bikini:` | :womans_clothes: | `:womans_clothes:` | [top](#table-of-contents) |
+| [top](#objects) | :folding_hand_fan: | `:folding_hand_fan:` | :purse: | `:purse:` | [top](#table-of-contents) |
+| [top](#objects) | :handbag: | `:handbag:` | :pouch: | `:pouch:` | [top](#table-of-contents) |
+| [top](#objects) | :shopping: | `:shopping:` | :school_satchel: | `:school_satchel:` | [top](#table-of-contents) |
+| [top](#objects) | :thong_sandal: | `:thong_sandal:` | :mans_shoe: | `:mans_shoe:` `:shoe:` | [top](#table-of-contents) |
+| [top](#objects) | :athletic_shoe: | `:athletic_shoe:` | :hiking_boot: | `:hiking_boot:` | [top](#table-of-contents) |
+| [top](#objects) | :flat_shoe: | `:flat_shoe:` | :high_heel: | `:high_heel:` | [top](#table-of-contents) |
+| [top](#objects) | :sandal: | `:sandal:` | :ballet_shoes: | `:ballet_shoes:` | [top](#table-of-contents) |
+| [top](#objects) | :boot: | `:boot:` | :hair_pick: | `:hair_pick:` | [top](#table-of-contents) |
+| [top](#objects) | :crown: | `:crown:` | :womans_hat: | `:womans_hat:` | [top](#table-of-contents) |
+| [top](#objects) | :tophat: | `:tophat:` | :mortar_board: | `:mortar_board:` | [top](#table-of-contents) |
+| [top](#objects) | :billed_cap: | `:billed_cap:` | :military_helmet: | `:military_helmet:` | [top](#table-of-contents) |
+| [top](#objects) | :rescue_worker_helmet: | `:rescue_worker_helmet:` | :prayer_beads: | `:prayer_beads:` | [top](#table-of-contents) |
+| [top](#objects) | :lipstick: | `:lipstick:` | :ring: | `:ring:` | [top](#table-of-contents) |
+| [top](#objects) | :gem: | `:gem:` | | | [top](#table-of-contents) |
+
+### Sound
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :mute: | `:mute:` | :speaker: | `:speaker:` | [top](#table-of-contents) |
+| [top](#objects) | :sound: | `:sound:` | :loud_sound: | `:loud_sound:` | [top](#table-of-contents) |
+| [top](#objects) | :loudspeaker: | `:loudspeaker:` | :mega: | `:mega:` | [top](#table-of-contents) |
+| [top](#objects) | :postal_horn: | `:postal_horn:` | :bell: | `:bell:` | [top](#table-of-contents) |
+| [top](#objects) | :no_bell: | `:no_bell:` | | | [top](#table-of-contents) |
+
+### Music
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :musical_score: | `:musical_score:` | :musical_note: | `:musical_note:` | [top](#table-of-contents) |
+| [top](#objects) | :notes: | `:notes:` | :studio_microphone: | `:studio_microphone:` | [top](#table-of-contents) |
+| [top](#objects) | :level_slider: | `:level_slider:` | :control_knobs: | `:control_knobs:` | [top](#table-of-contents) |
+| [top](#objects) | :microphone: | `:microphone:` | :headphones: | `:headphones:` | [top](#table-of-contents) |
+| [top](#objects) | :radio: | `:radio:` | | | [top](#table-of-contents) |
+
+### Musical Instrument
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :saxophone: | `:saxophone:` | :accordion: | `:accordion:` | [top](#table-of-contents) |
+| [top](#objects) | :guitar: | `:guitar:` | :musical_keyboard: | `:musical_keyboard:` | [top](#table-of-contents) |
+| [top](#objects) | :trumpet: | `:trumpet:` | :violin: | `:violin:` | [top](#table-of-contents) |
+| [top](#objects) | :banjo: | `:banjo:` | :drum: | `:drum:` | [top](#table-of-contents) |
+| [top](#objects) | :long_drum: | `:long_drum:` | :maracas: | `:maracas:` | [top](#table-of-contents) |
+| [top](#objects) | :flute: | `:flute:` | | | [top](#table-of-contents) |
+
+### Phone
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :iphone: | `:iphone:` | :calling: | `:calling:` | [top](#table-of-contents) |
+| [top](#objects) | :phone: | `:phone:` `:telephone:` | :telephone_receiver: | `:telephone_receiver:` | [top](#table-of-contents) |
+| [top](#objects) | :pager: | `:pager:` | :fax: | `:fax:` | [top](#table-of-contents) |
+
+### Computer
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :battery: | `:battery:` | :low_battery: | `:low_battery:` | [top](#table-of-contents) |
+| [top](#objects) | :electric_plug: | `:electric_plug:` | :computer: | `:computer:` | [top](#table-of-contents) |
+| [top](#objects) | :desktop_computer: | `:desktop_computer:` | :printer: | `:printer:` | [top](#table-of-contents) |
+| [top](#objects) | :keyboard: | `:keyboard:` | :computer_mouse: | `:computer_mouse:` | [top](#table-of-contents) |
+| [top](#objects) | :trackball: | `:trackball:` | :minidisc: | `:minidisc:` | [top](#table-of-contents) |
+| [top](#objects) | :floppy_disk: | `:floppy_disk:` | :cd: | `:cd:` | [top](#table-of-contents) |
+| [top](#objects) | :dvd: | `:dvd:` | :abacus: | `:abacus:` | [top](#table-of-contents) |
+
+### Light & Video
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :movie_camera: | `:movie_camera:` | :film_strip: | `:film_strip:` | [top](#table-of-contents) |
+| [top](#objects) | :film_projector: | `:film_projector:` | :clapper: | `:clapper:` | [top](#table-of-contents) |
+| [top](#objects) | :tv: | `:tv:` | :camera: | `:camera:` | [top](#table-of-contents) |
+| [top](#objects) | :camera_flash: | `:camera_flash:` | :video_camera: | `:video_camera:` | [top](#table-of-contents) |
+| [top](#objects) | :vhs: | `:vhs:` | :mag: | `:mag:` | [top](#table-of-contents) |
+| [top](#objects) | :mag_right: | `:mag_right:` | :candle: | `:candle:` | [top](#table-of-contents) |
+| [top](#objects) | :bulb: | `:bulb:` | :flashlight: | `:flashlight:` | [top](#table-of-contents) |
+| [top](#objects) | :izakaya_lantern: | `:izakaya_lantern:` `:lantern:` | :diya_lamp: | `:diya_lamp:` | [top](#table-of-contents) |
+
+### Book Paper
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :notebook_with_decorative_cover: | `:notebook_with_decorative_cover:` | :closed_book: | `:closed_book:` | [top](#table-of-contents) |
+| [top](#objects) | :book: | `:book:` `:open_book:` | :green_book: | `:green_book:` | [top](#table-of-contents) |
+| [top](#objects) | :blue_book: | `:blue_book:` | :orange_book: | `:orange_book:` | [top](#table-of-contents) |
+| [top](#objects) | :books: | `:books:` | :notebook: | `:notebook:` | [top](#table-of-contents) |
+| [top](#objects) | :ledger: | `:ledger:` | :page_with_curl: | `:page_with_curl:` | [top](#table-of-contents) |
+| [top](#objects) | :scroll: | `:scroll:` | :page_facing_up: | `:page_facing_up:` | [top](#table-of-contents) |
+| [top](#objects) | :newspaper: | `:newspaper:` | :newspaper_roll: | `:newspaper_roll:` | [top](#table-of-contents) |
+| [top](#objects) | :bookmark_tabs: | `:bookmark_tabs:` | :bookmark: | `:bookmark:` | [top](#table-of-contents) |
+| [top](#objects) | :label: | `:label:` | | | [top](#table-of-contents) |
+
+### Money
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :moneybag: | `:moneybag:` | :coin: | `:coin:` | [top](#table-of-contents) |
+| [top](#objects) | :yen: | `:yen:` | :dollar: | `:dollar:` | [top](#table-of-contents) |
+| [top](#objects) | :euro: | `:euro:` | :pound: | `:pound:` | [top](#table-of-contents) |
+| [top](#objects) | :money_with_wings: | `:money_with_wings:` | :credit_card: | `:credit_card:` | [top](#table-of-contents) |
+| [top](#objects) | :receipt: | `:receipt:` | :chart: | `:chart:` | [top](#table-of-contents) |
+
+### Mail
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :envelope: | `:envelope:` | :e-mail: | `:e-mail:` `:email:` | [top](#table-of-contents) |
+| [top](#objects) | :incoming_envelope: | `:incoming_envelope:` | :envelope_with_arrow: | `:envelope_with_arrow:` | [top](#table-of-contents) |
+| [top](#objects) | :outbox_tray: | `:outbox_tray:` | :inbox_tray: | `:inbox_tray:` | [top](#table-of-contents) |
+| [top](#objects) | :package: | `:package:` | :mailbox: | `:mailbox:` | [top](#table-of-contents) |
+| [top](#objects) | :mailbox_closed: | `:mailbox_closed:` | :mailbox_with_mail: | `:mailbox_with_mail:` | [top](#table-of-contents) |
+| [top](#objects) | :mailbox_with_no_mail: | `:mailbox_with_no_mail:` | :postbox: | `:postbox:` | [top](#table-of-contents) |
+| [top](#objects) | :ballot_box: | `:ballot_box:` | | | [top](#table-of-contents) |
+
+### Writing
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :pencil2: | `:pencil2:` | :black_nib: | `:black_nib:` | [top](#table-of-contents) |
+| [top](#objects) | :fountain_pen: | `:fountain_pen:` | :pen: | `:pen:` | [top](#table-of-contents) |
+| [top](#objects) | :paintbrush: | `:paintbrush:` | :crayon: | `:crayon:` | [top](#table-of-contents) |
+| [top](#objects) | :memo: | `:memo:` `:pencil:` | | | [top](#table-of-contents) |
+
+### Office
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :briefcase: | `:briefcase:` | :file_folder: | `:file_folder:` | [top](#table-of-contents) |
+| [top](#objects) | :open_file_folder: | `:open_file_folder:` | :card_index_dividers: | `:card_index_dividers:` | [top](#table-of-contents) |
+| [top](#objects) | :date: | `:date:` | :calendar: | `:calendar:` | [top](#table-of-contents) |
+| [top](#objects) | :spiral_notepad: | `:spiral_notepad:` | :spiral_calendar: | `:spiral_calendar:` | [top](#table-of-contents) |
+| [top](#objects) | :card_index: | `:card_index:` | :chart_with_upwards_trend: | `:chart_with_upwards_trend:` | [top](#table-of-contents) |
+| [top](#objects) | :chart_with_downwards_trend: | `:chart_with_downwards_trend:` | :bar_chart: | `:bar_chart:` | [top](#table-of-contents) |
+| [top](#objects) | :clipboard: | `:clipboard:` | :pushpin: | `:pushpin:` | [top](#table-of-contents) |
+| [top](#objects) | :round_pushpin: | `:round_pushpin:` | :paperclip: | `:paperclip:` | [top](#table-of-contents) |
+| [top](#objects) | :paperclips: | `:paperclips:` | :straight_ruler: | `:straight_ruler:` | [top](#table-of-contents) |
+| [top](#objects) | :triangular_ruler: | `:triangular_ruler:` | :scissors: | `:scissors:` | [top](#table-of-contents) |
+| [top](#objects) | :card_file_box: | `:card_file_box:` | :file_cabinet: | `:file_cabinet:` | [top](#table-of-contents) |
+| [top](#objects) | :wastebasket: | `:wastebasket:` | | | [top](#table-of-contents) |
+
+### Lock
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :lock: | `:lock:` | :unlock: | `:unlock:` | [top](#table-of-contents) |
+| [top](#objects) | :lock_with_ink_pen: | `:lock_with_ink_pen:` | :closed_lock_with_key: | `:closed_lock_with_key:` | [top](#table-of-contents) |
+| [top](#objects) | :key: | `:key:` | :old_key: | `:old_key:` | [top](#table-of-contents) |
+
+### Tool
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :hammer: | `:hammer:` | :axe: | `:axe:` | [top](#table-of-contents) |
+| [top](#objects) | :pick: | `:pick:` | :hammer_and_pick: | `:hammer_and_pick:` | [top](#table-of-contents) |
+| [top](#objects) | :hammer_and_wrench: | `:hammer_and_wrench:` | :dagger: | `:dagger:` | [top](#table-of-contents) |
+| [top](#objects) | :crossed_swords: | `:crossed_swords:` | :bomb: | `:bomb:` | [top](#table-of-contents) |
+| [top](#objects) | :boomerang: | `:boomerang:` | :bow_and_arrow: | `:bow_and_arrow:` | [top](#table-of-contents) |
+| [top](#objects) | :shield: | `:shield:` | :carpentry_saw: | `:carpentry_saw:` | [top](#table-of-contents) |
+| [top](#objects) | :wrench: | `:wrench:` | :screwdriver: | `:screwdriver:` | [top](#table-of-contents) |
+| [top](#objects) | :nut_and_bolt: | `:nut_and_bolt:` | :gear: | `:gear:` | [top](#table-of-contents) |
+| [top](#objects) | :clamp: | `:clamp:` | :balance_scale: | `:balance_scale:` | [top](#table-of-contents) |
+| [top](#objects) | :probing_cane: | `:probing_cane:` | :link: | `:link:` | [top](#table-of-contents) |
+| [top](#objects) | :chains: | `:chains:` | :hook: | `:hook:` | [top](#table-of-contents) |
+| [top](#objects) | :toolbox: | `:toolbox:` | :magnet: | `:magnet:` | [top](#table-of-contents) |
+| [top](#objects) | :ladder: | `:ladder:` | | | [top](#table-of-contents) |
+
+### Science
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :alembic: | `:alembic:` | :test_tube: | `:test_tube:` | [top](#table-of-contents) |
+| [top](#objects) | :petri_dish: | `:petri_dish:` | :dna: | `:dna:` | [top](#table-of-contents) |
+| [top](#objects) | :microscope: | `:microscope:` | :telescope: | `:telescope:` | [top](#table-of-contents) |
+| [top](#objects) | :satellite: | `:satellite:` | | | [top](#table-of-contents) |
+
+### Medical
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :syringe: | `:syringe:` | :drop_of_blood: | `:drop_of_blood:` | [top](#table-of-contents) |
+| [top](#objects) | :pill: | `:pill:` | :adhesive_bandage: | `:adhesive_bandage:` | [top](#table-of-contents) |
+| [top](#objects) | :crutch: | `:crutch:` | :stethoscope: | `:stethoscope:` | [top](#table-of-contents) |
+| [top](#objects) | :x_ray: | `:x_ray:` | | | [top](#table-of-contents) |
+
+### Household
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :door: | `:door:` | :elevator: | `:elevator:` | [top](#table-of-contents) |
+| [top](#objects) | :mirror: | `:mirror:` | :window: | `:window:` | [top](#table-of-contents) |
+| [top](#objects) | :bed: | `:bed:` | :couch_and_lamp: | `:couch_and_lamp:` | [top](#table-of-contents) |
+| [top](#objects) | :chair: | `:chair:` | :toilet: | `:toilet:` | [top](#table-of-contents) |
+| [top](#objects) | :plunger: | `:plunger:` | :shower: | `:shower:` | [top](#table-of-contents) |
+| [top](#objects) | :bathtub: | `:bathtub:` | :mouse_trap: | `:mouse_trap:` | [top](#table-of-contents) |
+| [top](#objects) | :razor: | `:razor:` | :lotion_bottle: | `:lotion_bottle:` | [top](#table-of-contents) |
+| [top](#objects) | :safety_pin: | `:safety_pin:` | :broom: | `:broom:` | [top](#table-of-contents) |
+| [top](#objects) | :basket: | `:basket:` | :roll_of_paper: | `:roll_of_paper:` | [top](#table-of-contents) |
+| [top](#objects) | :bucket: | `:bucket:` | :soap: | `:soap:` | [top](#table-of-contents) |
+| [top](#objects) | :bubbles: | `:bubbles:` | :toothbrush: | `:toothbrush:` | [top](#table-of-contents) |
+| [top](#objects) | :sponge: | `:sponge:` | :fire_extinguisher: | `:fire_extinguisher:` | [top](#table-of-contents) |
+| [top](#objects) | :shopping_cart: | `:shopping_cart:` | | | [top](#table-of-contents) |
+
+### Other Object
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#objects) | :smoking: | `:smoking:` | :coffin: | `:coffin:` | [top](#table-of-contents) |
+| [top](#objects) | :headstone: | `:headstone:` | :funeral_urn: | `:funeral_urn:` | [top](#table-of-contents) |
+| [top](#objects) | :nazar_amulet: | `:nazar_amulet:` | :hamsa: | `:hamsa:` | [top](#table-of-contents) |
+| [top](#objects) | :moyai: | `:moyai:` | :placard: | `:placard:` | [top](#table-of-contents) |
+| [top](#objects) | :identification_card: | `:identification_card:` | | | [top](#table-of-contents) |
+
+## Symbols
+
+- [Transport Sign](#transport-sign)
+- [Warning](#warning)
+- [Arrow](#arrow)
+- [Religion](#religion)
+- [Zodiac](#zodiac)
+- [Av Symbol](#av-symbol)
+- [Gender](#gender)
+- [Math](#math)
+- [Punctuation](#punctuation)
+- [Currency](#currency)
+- [Other Symbol](#other-symbol)
+- [Keycap](#keycap)
+- [Alphanum](#alphanum)
+- [Geometric](#geometric)
+
+### Transport Sign
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :atm: | `:atm:` | :put_litter_in_its_place: | `:put_litter_in_its_place:` | [top](#table-of-contents) |
+| [top](#symbols) | :potable_water: | `:potable_water:` | :wheelchair: | `:wheelchair:` | [top](#table-of-contents) |
+| [top](#symbols) | :mens: | `:mens:` | :womens: | `:womens:` | [top](#table-of-contents) |
+| [top](#symbols) | :restroom: | `:restroom:` | :baby_symbol: | `:baby_symbol:` | [top](#table-of-contents) |
+| [top](#symbols) | :wc: | `:wc:` | :passport_control: | `:passport_control:` | [top](#table-of-contents) |
+| [top](#symbols) | :customs: | `:customs:` | :baggage_claim: | `:baggage_claim:` | [top](#table-of-contents) |
+| [top](#symbols) | :left_luggage: | `:left_luggage:` | | | [top](#table-of-contents) |
+
+### Warning
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :warning: | `:warning:` | :children_crossing: | `:children_crossing:` | [top](#table-of-contents) |
+| [top](#symbols) | :no_entry: | `:no_entry:` | :no_entry_sign: | `:no_entry_sign:` | [top](#table-of-contents) |
+| [top](#symbols) | :no_bicycles: | `:no_bicycles:` | :no_smoking: | `:no_smoking:` | [top](#table-of-contents) |
+| [top](#symbols) | :do_not_litter: | `:do_not_litter:` | :non-potable_water: | `:non-potable_water:` | [top](#table-of-contents) |
+| [top](#symbols) | :no_pedestrians: | `:no_pedestrians:` | :no_mobile_phones: | `:no_mobile_phones:` | [top](#table-of-contents) |
+| [top](#symbols) | :underage: | `:underage:` | :radioactive: | `:radioactive:` | [top](#table-of-contents) |
+| [top](#symbols) | :biohazard: | `:biohazard:` | | | [top](#table-of-contents) |
+
+### Arrow
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :arrow_up: | `:arrow_up:` | :arrow_upper_right: | `:arrow_upper_right:` | [top](#table-of-contents) |
+| [top](#symbols) | :arrow_right: | `:arrow_right:` | :arrow_lower_right: | `:arrow_lower_right:` | [top](#table-of-contents) |
+| [top](#symbols) | :arrow_down: | `:arrow_down:` | :arrow_lower_left: | `:arrow_lower_left:` | [top](#table-of-contents) |
+| [top](#symbols) | :arrow_left: | `:arrow_left:` | :arrow_upper_left: | `:arrow_upper_left:` | [top](#table-of-contents) |
+| [top](#symbols) | :arrow_up_down: | `:arrow_up_down:` | :left_right_arrow: | `:left_right_arrow:` | [top](#table-of-contents) |
+| [top](#symbols) | :leftwards_arrow_with_hook: | `:leftwards_arrow_with_hook:` | :arrow_right_hook: | `:arrow_right_hook:` | [top](#table-of-contents) |
+| [top](#symbols) | :arrow_heading_up: | `:arrow_heading_up:` | :arrow_heading_down: | `:arrow_heading_down:` | [top](#table-of-contents) |
+| [top](#symbols) | :arrows_clockwise: | `:arrows_clockwise:` | :arrows_counterclockwise: | `:arrows_counterclockwise:` | [top](#table-of-contents) |
+| [top](#symbols) | :back: | `:back:` | :end: | `:end:` | [top](#table-of-contents) |
+| [top](#symbols) | :on: | `:on:` | :soon: | `:soon:` | [top](#table-of-contents) |
+| [top](#symbols) | :top: | `:top:` | | | [top](#table-of-contents) |
+
+### Religion
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :place_of_worship: | `:place_of_worship:` | :atom_symbol: | `:atom_symbol:` | [top](#table-of-contents) |
+| [top](#symbols) | :om: | `:om:` | :star_of_david: | `:star_of_david:` | [top](#table-of-contents) |
+| [top](#symbols) | :wheel_of_dharma: | `:wheel_of_dharma:` | :yin_yang: | `:yin_yang:` | [top](#table-of-contents) |
+| [top](#symbols) | :latin_cross: | `:latin_cross:` | :orthodox_cross: | `:orthodox_cross:` | [top](#table-of-contents) |
+| [top](#symbols) | :star_and_crescent: | `:star_and_crescent:` | :peace_symbol: | `:peace_symbol:` | [top](#table-of-contents) |
+| [top](#symbols) | :menorah: | `:menorah:` | :six_pointed_star: | `:six_pointed_star:` | [top](#table-of-contents) |
+| [top](#symbols) | :khanda: | `:khanda:` | | | [top](#table-of-contents) |
+
+### Zodiac
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :aries: | `:aries:` | :taurus: | `:taurus:` | [top](#table-of-contents) |
+| [top](#symbols) | :gemini: | `:gemini:` | :cancer: | `:cancer:` | [top](#table-of-contents) |
+| [top](#symbols) | :leo: | `:leo:` | :virgo: | `:virgo:` | [top](#table-of-contents) |
+| [top](#symbols) | :libra: | `:libra:` | :scorpius: | `:scorpius:` | [top](#table-of-contents) |
+| [top](#symbols) | :sagittarius: | `:sagittarius:` | :capricorn: | `:capricorn:` | [top](#table-of-contents) |
+| [top](#symbols) | :aquarius: | `:aquarius:` | :pisces: | `:pisces:` | [top](#table-of-contents) |
+| [top](#symbols) | :ophiuchus: | `:ophiuchus:` | | | [top](#table-of-contents) |
+
+### Av Symbol
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :twisted_rightwards_arrows: | `:twisted_rightwards_arrows:` | :repeat: | `:repeat:` | [top](#table-of-contents) |
+| [top](#symbols) | :repeat_one: | `:repeat_one:` | :arrow_forward: | `:arrow_forward:` | [top](#table-of-contents) |
+| [top](#symbols) | :fast_forward: | `:fast_forward:` | :next_track_button: | `:next_track_button:` | [top](#table-of-contents) |
+| [top](#symbols) | :play_or_pause_button: | `:play_or_pause_button:` | :arrow_backward: | `:arrow_backward:` | [top](#table-of-contents) |
+| [top](#symbols) | :rewind: | `:rewind:` | :previous_track_button: | `:previous_track_button:` | [top](#table-of-contents) |
+| [top](#symbols) | :arrow_up_small: | `:arrow_up_small:` | :arrow_double_up: | `:arrow_double_up:` | [top](#table-of-contents) |
+| [top](#symbols) | :arrow_down_small: | `:arrow_down_small:` | :arrow_double_down: | `:arrow_double_down:` | [top](#table-of-contents) |
+| [top](#symbols) | :pause_button: | `:pause_button:` | :stop_button: | `:stop_button:` | [top](#table-of-contents) |
+| [top](#symbols) | :record_button: | `:record_button:` | :eject_button: | `:eject_button:` | [top](#table-of-contents) |
+| [top](#symbols) | :cinema: | `:cinema:` | :low_brightness: | `:low_brightness:` | [top](#table-of-contents) |
+| [top](#symbols) | :high_brightness: | `:high_brightness:` | :signal_strength: | `:signal_strength:` | [top](#table-of-contents) |
+| [top](#symbols) | :wireless: | `:wireless:` | :vibration_mode: | `:vibration_mode:` | [top](#table-of-contents) |
+| [top](#symbols) | :mobile_phone_off: | `:mobile_phone_off:` | | | [top](#table-of-contents) |
+
+### Gender
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :female_sign: | `:female_sign:` | :male_sign: | `:male_sign:` | [top](#table-of-contents) |
+| [top](#symbols) | :transgender_symbol: | `:transgender_symbol:` | | | [top](#table-of-contents) |
+
+### Math
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :heavy_multiplication_x: | `:heavy_multiplication_x:` | :heavy_plus_sign: | `:heavy_plus_sign:` | [top](#table-of-contents) |
+| [top](#symbols) | :heavy_minus_sign: | `:heavy_minus_sign:` | :heavy_division_sign: | `:heavy_division_sign:` | [top](#table-of-contents) |
+| [top](#symbols) | :heavy_equals_sign: | `:heavy_equals_sign:` | :infinity: | `:infinity:` | [top](#table-of-contents) |
+
+### Punctuation
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :bangbang: | `:bangbang:` | :interrobang: | `:interrobang:` | [top](#table-of-contents) |
+| [top](#symbols) | :question: | `:question:` | :grey_question: | `:grey_question:` | [top](#table-of-contents) |
+| [top](#symbols) | :grey_exclamation: | `:grey_exclamation:` | :exclamation: | `:exclamation:` `:heavy_exclamation_mark:` | [top](#table-of-contents) |
+| [top](#symbols) | :wavy_dash: | `:wavy_dash:` | | | [top](#table-of-contents) |
+
+### Currency
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :currency_exchange: | `:currency_exchange:` | :heavy_dollar_sign: | `:heavy_dollar_sign:` | [top](#table-of-contents) |
+
+### Other Symbol
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :medical_symbol: | `:medical_symbol:` | :recycle: | `:recycle:` | [top](#table-of-contents) |
+| [top](#symbols) | :fleur_de_lis: | `:fleur_de_lis:` | :trident: | `:trident:` | [top](#table-of-contents) |
+| [top](#symbols) | :name_badge: | `:name_badge:` | :beginner: | `:beginner:` | [top](#table-of-contents) |
+| [top](#symbols) | :o: | `:o:` | :white_check_mark: | `:white_check_mark:` | [top](#table-of-contents) |
+| [top](#symbols) | :ballot_box_with_check: | `:ballot_box_with_check:` | :heavy_check_mark: | `:heavy_check_mark:` | [top](#table-of-contents) |
+| [top](#symbols) | :x: | `:x:` | :negative_squared_cross_mark: | `:negative_squared_cross_mark:` | [top](#table-of-contents) |
+| [top](#symbols) | :curly_loop: | `:curly_loop:` | :loop: | `:loop:` | [top](#table-of-contents) |
+| [top](#symbols) | :part_alternation_mark: | `:part_alternation_mark:` | :eight_spoked_asterisk: | `:eight_spoked_asterisk:` | [top](#table-of-contents) |
+| [top](#symbols) | :eight_pointed_black_star: | `:eight_pointed_black_star:` | :sparkle: | `:sparkle:` | [top](#table-of-contents) |
+| [top](#symbols) | :copyright: | `:copyright:` | :registered: | `:registered:` | [top](#table-of-contents) |
+| [top](#symbols) | :tm: | `:tm:` | | | [top](#table-of-contents) |
+
+### Keycap
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :hash: | `:hash:` | :asterisk: | `:asterisk:` | [top](#table-of-contents) |
+| [top](#symbols) | :zero: | `:zero:` | :one: | `:one:` | [top](#table-of-contents) |
+| [top](#symbols) | :two: | `:two:` | :three: | `:three:` | [top](#table-of-contents) |
+| [top](#symbols) | :four: | `:four:` | :five: | `:five:` | [top](#table-of-contents) |
+| [top](#symbols) | :six: | `:six:` | :seven: | `:seven:` | [top](#table-of-contents) |
+| [top](#symbols) | :eight: | `:eight:` | :nine: | `:nine:` | [top](#table-of-contents) |
+| [top](#symbols) | :keycap_ten: | `:keycap_ten:` | | | [top](#table-of-contents) |
+
+### Alphanum
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :capital_abcd: | `:capital_abcd:` | :abcd: | `:abcd:` | [top](#table-of-contents) |
+| [top](#symbols) | :1234: | `:1234:` | :symbols: | `:symbols:` | [top](#table-of-contents) |
+| [top](#symbols) | :abc: | `:abc:` | :a: | `:a:` | [top](#table-of-contents) |
+| [top](#symbols) | :ab: | `:ab:` | :b: | `:b:` | [top](#table-of-contents) |
+| [top](#symbols) | :cl: | `:cl:` | :cool: | `:cool:` | [top](#table-of-contents) |
+| [top](#symbols) | :free: | `:free:` | :information_source: | `:information_source:` | [top](#table-of-contents) |
+| [top](#symbols) | :id: | `:id:` | :m: | `:m:` | [top](#table-of-contents) |
+| [top](#symbols) | :new: | `:new:` | :ng: | `:ng:` | [top](#table-of-contents) |
+| [top](#symbols) | :o2: | `:o2:` | :ok: | `:ok:` | [top](#table-of-contents) |
+| [top](#symbols) | :parking: | `:parking:` | :sos: | `:sos:` | [top](#table-of-contents) |
+| [top](#symbols) | :up: | `:up:` | :vs: | `:vs:` | [top](#table-of-contents) |
+| [top](#symbols) | :koko: | `:koko:` | :sa: | `:sa:` | [top](#table-of-contents) |
+| [top](#symbols) | :u6708: | `:u6708:` | :u6709: | `:u6709:` | [top](#table-of-contents) |
+| [top](#symbols) | :u6307: | `:u6307:` | :ideograph_advantage: | `:ideograph_advantage:` | [top](#table-of-contents) |
+| [top](#symbols) | :u5272: | `:u5272:` | :u7121: | `:u7121:` | [top](#table-of-contents) |
+| [top](#symbols) | :u7981: | `:u7981:` | :accept: | `:accept:` | [top](#table-of-contents) |
+| [top](#symbols) | :u7533: | `:u7533:` | :u5408: | `:u5408:` | [top](#table-of-contents) |
+| [top](#symbols) | :u7a7a: | `:u7a7a:` | :congratulations: | `:congratulations:` | [top](#table-of-contents) |
+| [top](#symbols) | :secret: | `:secret:` | :u55b6: | `:u55b6:` | [top](#table-of-contents) |
+| [top](#symbols) | :u6e80: | `:u6e80:` | | | [top](#table-of-contents) |
+
+### Geometric
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#symbols) | :red_circle: | `:red_circle:` | :orange_circle: | `:orange_circle:` | [top](#table-of-contents) |
+| [top](#symbols) | :yellow_circle: | `:yellow_circle:` | :green_circle: | `:green_circle:` | [top](#table-of-contents) |
+| [top](#symbols) | :large_blue_circle: | `:large_blue_circle:` | :purple_circle: | `:purple_circle:` | [top](#table-of-contents) |
+| [top](#symbols) | :brown_circle: | `:brown_circle:` | :black_circle: | `:black_circle:` | [top](#table-of-contents) |
+| [top](#symbols) | :white_circle: | `:white_circle:` | :red_square: | `:red_square:` | [top](#table-of-contents) |
+| [top](#symbols) | :orange_square: | `:orange_square:` | :yellow_square: | `:yellow_square:` | [top](#table-of-contents) |
+| [top](#symbols) | :green_square: | `:green_square:` | :blue_square: | `:blue_square:` | [top](#table-of-contents) |
+| [top](#symbols) | :purple_square: | `:purple_square:` | :brown_square: | `:brown_square:` | [top](#table-of-contents) |
+| [top](#symbols) | :black_large_square: | `:black_large_square:` | :white_large_square: | `:white_large_square:` | [top](#table-of-contents) |
+| [top](#symbols) | :black_medium_square: | `:black_medium_square:` | :white_medium_square: | `:white_medium_square:` | [top](#table-of-contents) |
+| [top](#symbols) | :black_medium_small_square: | `:black_medium_small_square:` | :white_medium_small_square: | `:white_medium_small_square:` | [top](#table-of-contents) |
+| [top](#symbols) | :black_small_square: | `:black_small_square:` | :white_small_square: | `:white_small_square:` | [top](#table-of-contents) |
+| [top](#symbols) | :large_orange_diamond: | `:large_orange_diamond:` | :large_blue_diamond: | `:large_blue_diamond:` | [top](#table-of-contents) |
+| [top](#symbols) | :small_orange_diamond: | `:small_orange_diamond:` | :small_blue_diamond: | `:small_blue_diamond:` | [top](#table-of-contents) |
+| [top](#symbols) | :small_red_triangle: | `:small_red_triangle:` | :small_red_triangle_down: | `:small_red_triangle_down:` | [top](#table-of-contents) |
+| [top](#symbols) | :diamond_shape_with_a_dot_inside: | `:diamond_shape_with_a_dot_inside:` | :radio_button: | `:radio_button:` | [top](#table-of-contents) |
+| [top](#symbols) | :white_square_button: | `:white_square_button:` | :black_square_button: | `:black_square_button:` | [top](#table-of-contents) |
+
+## Flags
+
+- [Flag](#flag)
+- [Country Flag](#country-flag)
+- [Subdivision Flag](#subdivision-flag)
+
+### Flag
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#flags) | :checkered_flag: | `:checkered_flag:` | :triangular_flag_on_post: | `:triangular_flag_on_post:` | [top](#table-of-contents) |
+| [top](#flags) | :crossed_flags: | `:crossed_flags:` | :black_flag: | `:black_flag:` | [top](#table-of-contents) |
+| [top](#flags) | :white_flag: | `:white_flag:` | :rainbow_flag: | `:rainbow_flag:` | [top](#table-of-contents) |
+| [top](#flags) | :transgender_flag: | `:transgender_flag:` | :pirate_flag: | `:pirate_flag:` | [top](#table-of-contents) |
+
+### Country Flag
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#flags) | :ascension_island: | `:ascension_island:` | :andorra: | `:andorra:` | [top](#table-of-contents) |
+| [top](#flags) | :united_arab_emirates: | `:united_arab_emirates:` | :afghanistan: | `:afghanistan:` | [top](#table-of-contents) |
+| [top](#flags) | :antigua_barbuda: | `:antigua_barbuda:` | :anguilla: | `:anguilla:` | [top](#table-of-contents) |
+| [top](#flags) | :albania: | `:albania:` | :armenia: | `:armenia:` | [top](#table-of-contents) |
+| [top](#flags) | :angola: | `:angola:` | :antarctica: | `:antarctica:` | [top](#table-of-contents) |
+| [top](#flags) | :argentina: | `:argentina:` | :american_samoa: | `:american_samoa:` | [top](#table-of-contents) |
+| [top](#flags) | :austria: | `:austria:` | :australia: | `:australia:` | [top](#table-of-contents) |
+| [top](#flags) | :aruba: | `:aruba:` | :aland_islands: | `:aland_islands:` | [top](#table-of-contents) |
+| [top](#flags) | :azerbaijan: | `:azerbaijan:` | :bosnia_herzegovina: | `:bosnia_herzegovina:` | [top](#table-of-contents) |
+| [top](#flags) | :barbados: | `:barbados:` | :bangladesh: | `:bangladesh:` | [top](#table-of-contents) |
+| [top](#flags) | :belgium: | `:belgium:` | :burkina_faso: | `:burkina_faso:` | [top](#table-of-contents) |
+| [top](#flags) | :bulgaria: | `:bulgaria:` | :bahrain: | `:bahrain:` | [top](#table-of-contents) |
+| [top](#flags) | :burundi: | `:burundi:` | :benin: | `:benin:` | [top](#table-of-contents) |
+| [top](#flags) | :st_barthelemy: | `:st_barthelemy:` | :bermuda: | `:bermuda:` | [top](#table-of-contents) |
+| [top](#flags) | :brunei: | `:brunei:` | :bolivia: | `:bolivia:` | [top](#table-of-contents) |
+| [top](#flags) | :caribbean_netherlands: | `:caribbean_netherlands:` | :brazil: | `:brazil:` | [top](#table-of-contents) |
+| [top](#flags) | :bahamas: | `:bahamas:` | :bhutan: | `:bhutan:` | [top](#table-of-contents) |
+| [top](#flags) | :bouvet_island: | `:bouvet_island:` | :botswana: | `:botswana:` | [top](#table-of-contents) |
+| [top](#flags) | :belarus: | `:belarus:` | :belize: | `:belize:` | [top](#table-of-contents) |
+| [top](#flags) | :canada: | `:canada:` | :cocos_islands: | `:cocos_islands:` | [top](#table-of-contents) |
+| [top](#flags) | :congo_kinshasa: | `:congo_kinshasa:` | :central_african_republic: | `:central_african_republic:` | [top](#table-of-contents) |
+| [top](#flags) | :congo_brazzaville: | `:congo_brazzaville:` | :switzerland: | `:switzerland:` | [top](#table-of-contents) |
+| [top](#flags) | :cote_divoire: | `:cote_divoire:` | :cook_islands: | `:cook_islands:` | [top](#table-of-contents) |
+| [top](#flags) | :chile: | `:chile:` | :cameroon: | `:cameroon:` | [top](#table-of-contents) |
+| [top](#flags) | :cn: | `:cn:` | :colombia: | `:colombia:` | [top](#table-of-contents) |
+| [top](#flags) | :clipperton_island: | `:clipperton_island:` | :costa_rica: | `:costa_rica:` | [top](#table-of-contents) |
+| [top](#flags) | :cuba: | `:cuba:` | :cape_verde: | `:cape_verde:` | [top](#table-of-contents) |
+| [top](#flags) | :curacao: | `:curacao:` | :christmas_island: | `:christmas_island:` | [top](#table-of-contents) |
+| [top](#flags) | :cyprus: | `:cyprus:` | :czech_republic: | `:czech_republic:` | [top](#table-of-contents) |
+| [top](#flags) | :de: | `:de:` | :diego_garcia: | `:diego_garcia:` | [top](#table-of-contents) |
+| [top](#flags) | :djibouti: | `:djibouti:` | :denmark: | `:denmark:` | [top](#table-of-contents) |
+| [top](#flags) | :dominica: | `:dominica:` | :dominican_republic: | `:dominican_republic:` | [top](#table-of-contents) |
+| [top](#flags) | :algeria: | `:algeria:` | :ceuta_melilla: | `:ceuta_melilla:` | [top](#table-of-contents) |
+| [top](#flags) | :ecuador: | `:ecuador:` | :estonia: | `:estonia:` | [top](#table-of-contents) |
+| [top](#flags) | :egypt: | `:egypt:` | :western_sahara: | `:western_sahara:` | [top](#table-of-contents) |
+| [top](#flags) | :eritrea: | `:eritrea:` | :es: | `:es:` | [top](#table-of-contents) |
+| [top](#flags) | :ethiopia: | `:ethiopia:` | :eu: | `:eu:` `:european_union:` | [top](#table-of-contents) |
+| [top](#flags) | :finland: | `:finland:` | :fiji: | `:fiji:` | [top](#table-of-contents) |
+| [top](#flags) | :falkland_islands: | `:falkland_islands:` | :micronesia: | `:micronesia:` | [top](#table-of-contents) |
+| [top](#flags) | :faroe_islands: | `:faroe_islands:` | :fr: | `:fr:` | [top](#table-of-contents) |
+| [top](#flags) | :gabon: | `:gabon:` | :gb: | `:gb:` `:uk:` | [top](#table-of-contents) |
+| [top](#flags) | :grenada: | `:grenada:` | :georgia: | `:georgia:` | [top](#table-of-contents) |
+| [top](#flags) | :french_guiana: | `:french_guiana:` | :guernsey: | `:guernsey:` | [top](#table-of-contents) |
+| [top](#flags) | :ghana: | `:ghana:` | :gibraltar: | `:gibraltar:` | [top](#table-of-contents) |
+| [top](#flags) | :greenland: | `:greenland:` | :gambia: | `:gambia:` | [top](#table-of-contents) |
+| [top](#flags) | :guinea: | `:guinea:` | :guadeloupe: | `:guadeloupe:` | [top](#table-of-contents) |
+| [top](#flags) | :equatorial_guinea: | `:equatorial_guinea:` | :greece: | `:greece:` | [top](#table-of-contents) |
+| [top](#flags) | :south_georgia_south_sandwich_islands: | `:south_georgia_south_sandwich_islands:` | :guatemala: | `:guatemala:` | [top](#table-of-contents) |
+| [top](#flags) | :guam: | `:guam:` | :guinea_bissau: | `:guinea_bissau:` | [top](#table-of-contents) |
+| [top](#flags) | :guyana: | `:guyana:` | :hong_kong: | `:hong_kong:` | [top](#table-of-contents) |
+| [top](#flags) | :heard_mcdonald_islands: | `:heard_mcdonald_islands:` | :honduras: | `:honduras:` | [top](#table-of-contents) |
+| [top](#flags) | :croatia: | `:croatia:` | :haiti: | `:haiti:` | [top](#table-of-contents) |
+| [top](#flags) | :hungary: | `:hungary:` | :canary_islands: | `:canary_islands:` | [top](#table-of-contents) |
+| [top](#flags) | :indonesia: | `:indonesia:` | :ireland: | `:ireland:` | [top](#table-of-contents) |
+| [top](#flags) | :israel: | `:israel:` | :isle_of_man: | `:isle_of_man:` | [top](#table-of-contents) |
+| [top](#flags) | :india: | `:india:` | :british_indian_ocean_territory: | `:british_indian_ocean_territory:` | [top](#table-of-contents) |
+| [top](#flags) | :iraq: | `:iraq:` | :iran: | `:iran:` | [top](#table-of-contents) |
+| [top](#flags) | :iceland: | `:iceland:` | :it: | `:it:` | [top](#table-of-contents) |
+| [top](#flags) | :jersey: | `:jersey:` | :jamaica: | `:jamaica:` | [top](#table-of-contents) |
+| [top](#flags) | :jordan: | `:jordan:` | :jp: | `:jp:` | [top](#table-of-contents) |
+| [top](#flags) | :kenya: | `:kenya:` | :kyrgyzstan: | `:kyrgyzstan:` | [top](#table-of-contents) |
+| [top](#flags) | :cambodia: | `:cambodia:` | :kiribati: | `:kiribati:` | [top](#table-of-contents) |
+| [top](#flags) | :comoros: | `:comoros:` | :st_kitts_nevis: | `:st_kitts_nevis:` | [top](#table-of-contents) |
+| [top](#flags) | :north_korea: | `:north_korea:` | :kr: | `:kr:` | [top](#table-of-contents) |
+| [top](#flags) | :kuwait: | `:kuwait:` | :cayman_islands: | `:cayman_islands:` | [top](#table-of-contents) |
+| [top](#flags) | :kazakhstan: | `:kazakhstan:` | :laos: | `:laos:` | [top](#table-of-contents) |
+| [top](#flags) | :lebanon: | `:lebanon:` | :st_lucia: | `:st_lucia:` | [top](#table-of-contents) |
+| [top](#flags) | :liechtenstein: | `:liechtenstein:` | :sri_lanka: | `:sri_lanka:` | [top](#table-of-contents) |
+| [top](#flags) | :liberia: | `:liberia:` | :lesotho: | `:lesotho:` | [top](#table-of-contents) |
+| [top](#flags) | :lithuania: | `:lithuania:` | :luxembourg: | `:luxembourg:` | [top](#table-of-contents) |
+| [top](#flags) | :latvia: | `:latvia:` | :libya: | `:libya:` | [top](#table-of-contents) |
+| [top](#flags) | :morocco: | `:morocco:` | :monaco: | `:monaco:` | [top](#table-of-contents) |
+| [top](#flags) | :moldova: | `:moldova:` | :montenegro: | `:montenegro:` | [top](#table-of-contents) |
+| [top](#flags) | :st_martin: | `:st_martin:` | :madagascar: | `:madagascar:` | [top](#table-of-contents) |
+| [top](#flags) | :marshall_islands: | `:marshall_islands:` | :macedonia: | `:macedonia:` | [top](#table-of-contents) |
+| [top](#flags) | :mali: | `:mali:` | :myanmar: | `:myanmar:` | [top](#table-of-contents) |
+| [top](#flags) | :mongolia: | `:mongolia:` | :macau: | `:macau:` | [top](#table-of-contents) |
+| [top](#flags) | :northern_mariana_islands: | `:northern_mariana_islands:` | :martinique: | `:martinique:` | [top](#table-of-contents) |
+| [top](#flags) | :mauritania: | `:mauritania:` | :montserrat: | `:montserrat:` | [top](#table-of-contents) |
+| [top](#flags) | :malta: | `:malta:` | :mauritius: | `:mauritius:` | [top](#table-of-contents) |
+| [top](#flags) | :maldives: | `:maldives:` | :malawi: | `:malawi:` | [top](#table-of-contents) |
+| [top](#flags) | :mexico: | `:mexico:` | :malaysia: | `:malaysia:` | [top](#table-of-contents) |
+| [top](#flags) | :mozambique: | `:mozambique:` | :namibia: | `:namibia:` | [top](#table-of-contents) |
+| [top](#flags) | :new_caledonia: | `:new_caledonia:` | :niger: | `:niger:` | [top](#table-of-contents) |
+| [top](#flags) | :norfolk_island: | `:norfolk_island:` | :nigeria: | `:nigeria:` | [top](#table-of-contents) |
+| [top](#flags) | :nicaragua: | `:nicaragua:` | :netherlands: | `:netherlands:` | [top](#table-of-contents) |
+| [top](#flags) | :norway: | `:norway:` | :nepal: | `:nepal:` | [top](#table-of-contents) |
+| [top](#flags) | :nauru: | `:nauru:` | :niue: | `:niue:` | [top](#table-of-contents) |
+| [top](#flags) | :new_zealand: | `:new_zealand:` | :oman: | `:oman:` | [top](#table-of-contents) |
+| [top](#flags) | :panama: | `:panama:` | :peru: | `:peru:` | [top](#table-of-contents) |
+| [top](#flags) | :french_polynesia: | `:french_polynesia:` | :papua_new_guinea: | `:papua_new_guinea:` | [top](#table-of-contents) |
+| [top](#flags) | :philippines: | `:philippines:` | :pakistan: | `:pakistan:` | [top](#table-of-contents) |
+| [top](#flags) | :poland: | `:poland:` | :st_pierre_miquelon: | `:st_pierre_miquelon:` | [top](#table-of-contents) |
+| [top](#flags) | :pitcairn_islands: | `:pitcairn_islands:` | :puerto_rico: | `:puerto_rico:` | [top](#table-of-contents) |
+| [top](#flags) | :palestinian_territories: | `:palestinian_territories:` | :portugal: | `:portugal:` | [top](#table-of-contents) |
+| [top](#flags) | :palau: | `:palau:` | :paraguay: | `:paraguay:` | [top](#table-of-contents) |
+| [top](#flags) | :qatar: | `:qatar:` | :reunion: | `:reunion:` | [top](#table-of-contents) |
+| [top](#flags) | :romania: | `:romania:` | :serbia: | `:serbia:` | [top](#table-of-contents) |
+| [top](#flags) | :ru: | `:ru:` | :rwanda: | `:rwanda:` | [top](#table-of-contents) |
+| [top](#flags) | :saudi_arabia: | `:saudi_arabia:` | :solomon_islands: | `:solomon_islands:` | [top](#table-of-contents) |
+| [top](#flags) | :seychelles: | `:seychelles:` | :sudan: | `:sudan:` | [top](#table-of-contents) |
+| [top](#flags) | :sweden: | `:sweden:` | :singapore: | `:singapore:` | [top](#table-of-contents) |
+| [top](#flags) | :st_helena: | `:st_helena:` | :slovenia: | `:slovenia:` | [top](#table-of-contents) |
+| [top](#flags) | :svalbard_jan_mayen: | `:svalbard_jan_mayen:` | :slovakia: | `:slovakia:` | [top](#table-of-contents) |
+| [top](#flags) | :sierra_leone: | `:sierra_leone:` | :san_marino: | `:san_marino:` | [top](#table-of-contents) |
+| [top](#flags) | :senegal: | `:senegal:` | :somalia: | `:somalia:` | [top](#table-of-contents) |
+| [top](#flags) | :suriname: | `:suriname:` | :south_sudan: | `:south_sudan:` | [top](#table-of-contents) |
+| [top](#flags) | :sao_tome_principe: | `:sao_tome_principe:` | :el_salvador: | `:el_salvador:` | [top](#table-of-contents) |
+| [top](#flags) | :sint_maarten: | `:sint_maarten:` | :syria: | `:syria:` | [top](#table-of-contents) |
+| [top](#flags) | :swaziland: | `:swaziland:` | :tristan_da_cunha: | `:tristan_da_cunha:` | [top](#table-of-contents) |
+| [top](#flags) | :turks_caicos_islands: | `:turks_caicos_islands:` | :chad: | `:chad:` | [top](#table-of-contents) |
+| [top](#flags) | :french_southern_territories: | `:french_southern_territories:` | :togo: | `:togo:` | [top](#table-of-contents) |
+| [top](#flags) | :thailand: | `:thailand:` | :tajikistan: | `:tajikistan:` | [top](#table-of-contents) |
+| [top](#flags) | :tokelau: | `:tokelau:` | :timor_leste: | `:timor_leste:` | [top](#table-of-contents) |
+| [top](#flags) | :turkmenistan: | `:turkmenistan:` | :tunisia: | `:tunisia:` | [top](#table-of-contents) |
+| [top](#flags) | :tonga: | `:tonga:` | :tr: | `:tr:` | [top](#table-of-contents) |
+| [top](#flags) | :trinidad_tobago: | `:trinidad_tobago:` | :tuvalu: | `:tuvalu:` | [top](#table-of-contents) |
+| [top](#flags) | :taiwan: | `:taiwan:` | :tanzania: | `:tanzania:` | [top](#table-of-contents) |
+| [top](#flags) | :ukraine: | `:ukraine:` | :uganda: | `:uganda:` | [top](#table-of-contents) |
+| [top](#flags) | :us_outlying_islands: | `:us_outlying_islands:` | :united_nations: | `:united_nations:` | [top](#table-of-contents) |
+| [top](#flags) | :us: | `:us:` | :uruguay: | `:uruguay:` | [top](#table-of-contents) |
+| [top](#flags) | :uzbekistan: | `:uzbekistan:` | :vatican_city: | `:vatican_city:` | [top](#table-of-contents) |
+| [top](#flags) | :st_vincent_grenadines: | `:st_vincent_grenadines:` | :venezuela: | `:venezuela:` | [top](#table-of-contents) |
+| [top](#flags) | :british_virgin_islands: | `:british_virgin_islands:` | :us_virgin_islands: | `:us_virgin_islands:` | [top](#table-of-contents) |
+| [top](#flags) | :vietnam: | `:vietnam:` | :vanuatu: | `:vanuatu:` | [top](#table-of-contents) |
+| [top](#flags) | :wallis_futuna: | `:wallis_futuna:` | :samoa: | `:samoa:` | [top](#table-of-contents) |
+| [top](#flags) | :kosovo: | `:kosovo:` | :yemen: | `:yemen:` | [top](#table-of-contents) |
+| [top](#flags) | :mayotte: | `:mayotte:` | :south_africa: | `:south_africa:` | [top](#table-of-contents) |
+| [top](#flags) | :zambia: | `:zambia:` | :zimbabwe: | `:zimbabwe:` | [top](#table-of-contents) |
+
+### Subdivision Flag
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#flags) | :england: | `:england:` | :scotland: | `:scotland:` | [top](#table-of-contents) |
+| [top](#flags) | :wales: | `:wales:` | | | [top](#table-of-contents) |
+
+## GitHub Custom Emoji
+
+| | ico | shortcode | ico | shortcode | |
+| - | :-: | - | :-: | - | - |
+| [top](#github-custom-emoji) | :accessibility: | `:accessibility:` | :atom: | `:atom:` | [top](#table-of-contents) |
+| [top](#github-custom-emoji) | :basecamp: | `:basecamp:` | :basecampy: | `:basecampy:` | [top](#table-of-contents) |
+| [top](#github-custom-emoji) | :bowtie: | `:bowtie:` | :dependabot: | `:dependabot:` | [top](#table-of-contents) |
+| [top](#github-custom-emoji) | :electron: | `:electron:` | :feelsgood: | `:feelsgood:` | [top](#table-of-contents) |
+| [top](#github-custom-emoji) | :finnadie: | `:finnadie:` | :fishsticks: | `:fishsticks:` | [top](#table-of-contents) |
+| [top](#github-custom-emoji) | :goberserk: | `:goberserk:` | :godmode: | `:godmode:` | [top](#table-of-contents) |
+| [top](#github-custom-emoji) | :hurtrealbad: | `:hurtrealbad:` | :neckbeard: | `:neckbeard:` | [top](#table-of-contents) |
+| [top](#github-custom-emoji) | :octocat: | `:octocat:` | :rage1: | `:rage1:` | [top](#table-of-contents) |
+| [top](#github-custom-emoji) | :rage2: | `:rage2:` | :rage3: | `:rage3:` | [top](#table-of-contents) |
+| [top](#github-custom-emoji) | :rage4: | `:rage4:` | :shipit: | `:shipit:` | [top](#table-of-contents) |
+| [top](#github-custom-emoji) | :suspect: | `:suspect:` | :trollface: | `:trollface:` | [top](#table-of-contents) |
diff --git a/documents/markdown/hugo-docs/en_quick-reference_functions.md b/documents/markdown/hugo-docs/en_quick-reference_functions.md
new file mode 100644
index 0000000..72235d0
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_functions.md
@@ -0,0 +1,8 @@
+---
+title: Functions
+description: A quick reference guide to Hugo's functions, grouped by namespace. Aliases, if any, appear in parentheses to the right of the function name.
+categories: []
+keywords: []
+---
+
+{{% quick-reference section="functions" %}}
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glob-patterns.md b/documents/markdown/hugo-docs/en_quick-reference_glob-patterns.md
new file mode 100644
index 0000000..13cd01f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glob-patterns.md
@@ -0,0 +1,38 @@
+---
+title: Glob patterns
+description: A quick reference guide to glob pattern syntax and matching rules for wildcards, character sets, and delimiters, featuring illustrative examples.
+categories: []
+keywords: []
+---
+
+{{% glossary-term "glob pattern" %}}
+
+The table below details the supported glob pattern syntax and its matching behavior. Each example illustrates a specific match type, the pattern used, and the expected boolean result when evaluated against a test string.
+
+| Match type | Glob pattern | Test string | Match? |
+| :--- | :--- | :--- | :--- |
+| Simple wildcard | `a/*.md` | `a/page.md` | true |
+| Literal match | `'a/*.md'` | `a/*.md` | true |
+| Single-level wildcard | `a/*/page.md` | `a/b/page.md` | true |
+| Single-level wildcard | `a/*/page.md` | `a/b/c/page.md` | false |
+| Multi-level wildcard | `a/**/page.md` | `a/b/c/page.md` | true |
+| Single character | `file.???` | `file.txt` | true |
+| Single character | `file.???` | `file.js` | false |
+| Delimiter exclusion | `?at` | `f/at` | false |
+| Character list | `f.[jt]xt` | `f.txt` | true |
+| Negated list | `f.[!j]xt` | `f.txt` | true |
+| Character range | `f.[a-c].txt` | `f.b.txt` | true |
+| Character range | `f.[a-c].txt` | `f.z.txt` | false |
+| Negated range | `f.[!a-c].txt` | `f.z.txt` | true |
+| Pattern alternates | `*.{jpg,png}` | `logo.png` | true |
+| No match | `*.{jpg,png}` | `logo.webp` | false |
+
+The matching logic follows these rules:
+
+- Standard wildcard (`*`) matches any character except for a delimiter.
+- Super wildcard (`**`) matches any character including delimiters.
+- Single character (`?`) matches exactly one character, excluding delimiters.
+- Negation (`!`) matches any character except those specified in a list or range when used inside brackets.
+- Character ranges (`[a-z]`) match any single character within the specified range.
+
+The delimiter is a slash (`/`), except when matching semantic version strings, where the delimiter is a dot (`.`).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary__index.md b/documents/markdown/hugo-docs/en_quick-reference_glossary__index.md
new file mode 100644
index 0000000..8940fd7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary__index.md
@@ -0,0 +1,20 @@
+---
+title: Glossary
+description: Terms commonly used throughout the documentation.
+categories: []
+keywords: []
+build:
+ render: always
+ list: always
+cascade:
+ build:
+ render: never
+ list: local
+layout: single
+params:
+ hide_in_this_section: true
+ searchable: true
+aliases: [/getting-started/glossary/]
+---
+
+{{% glossary %}}
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_archetype.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_archetype.md
new file mode 100644
index 0000000..d22fae9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_archetype.md
@@ -0,0 +1,7 @@
+---
+title: archetype
+params:
+ reference: /content-management/archetypes/
+---
+
+An _archetype_ is a template for new content.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_argument.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_argument.md
new file mode 100644
index 0000000..912951d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_argument.md
@@ -0,0 +1,5 @@
+---
+title: argument
+---
+
+An _argument_ is a [_scalar_](g), [_array_](g), [_slice_](g), [_map_](g), or [_object_](g) passed to a [_function_](g), [_method_](g), or [_shortcode_](g).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_array.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_array.md
new file mode 100644
index 0000000..0df45f2
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_array.md
@@ -0,0 +1,6 @@
+---
+title: array
+reference: https://go.dev/ref/spec#Array_types
+---
+
+An _array_ is a numbered sequence of [_elements_](g). Unlike Go's [_slice_](g) data type, an array has a fixed length. Elements within an array can be [_scalars_](g), slices, [_maps_](g), pages, or other arrays.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_asset-pipeline.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_asset-pipeline.md
new file mode 100644
index 0000000..5f3264a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_asset-pipeline.md
@@ -0,0 +1,5 @@
+---
+title: asset pipeline
+---
+
+An _asset pipeline_ is a system that automates and optimizes the handling of static assets like images, stylesheets, and JavaScript files.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_boolean.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_boolean.md
new file mode 100644
index 0000000..e727c40
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_boolean.md
@@ -0,0 +1,5 @@
+---
+title: boolean
+---
+
+A _boolean_ is a data type with two possible values, either `true` or `false`.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_branch-bundle.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_branch-bundle.md
new file mode 100644
index 0000000..d5688ba
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_branch-bundle.md
@@ -0,0 +1,6 @@
+---
+title: branch bundle
+reference: /content-management/page-bundles
+---
+
+A _branch bundle_ is a top-level content directory or any content directory containing an `_index.md` file. Analogous to a physical branch, a branch bundle may have descendants including [_leaf bundles_](g) and other branch bundles. A branch bundle may also contain [_page resources_](g) such as images.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_build-artifacts.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_build-artifacts.md
new file mode 100644
index 0000000..c3c2dbd
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_build-artifacts.md
@@ -0,0 +1,5 @@
+---
+title: build artifacts
+---
+
+The _build artifacts_ are the static files produced during the [_build_](g) process. These assets are stored in the `public` directory by default and represent the final, ready-to-deploy output of the project.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_build.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_build.md
new file mode 100644
index 0000000..4d4f73c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_build.md
@@ -0,0 +1,5 @@
+---
+title: build
+---
+
+To _build_ (verb) is to generate the static files for a [_project_](g), including HTML, images, CSS, and JavaScript. This process involves rendering templates, transforming resources, and resolving the matrix of [_language_](g), [_role_](g), and [_version_](g) defined in your project configuration.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_cache.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_cache.md
new file mode 100644
index 0000000..a86068e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_cache.md
@@ -0,0 +1,5 @@
+---
+title: cache
+---
+
+A _cache_ is a software component that stores data so that future requests for the same data are faster.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_canonical-output-format.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_canonical-output-format.md
new file mode 100644
index 0000000..d360083
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_canonical-output-format.md
@@ -0,0 +1,14 @@
+---
+title: canonical output format
+---
+
+The _canonical output format_ is the [_output format_](g) for the current page where the format's [`rel`][] property is set to `canonical` in your project configuration, if such a format exists. If there is only one _output format_ for the current page, that is the _canonical output format_, regardless of whether the format's `rel` property is set to `canonical`.
+
+ By default, `html` is the only predefined _output format_ with this setting; the `rel` property for all others is set to `alternate`. If two or more _output formats_ for the current page have their `rel` property set to `canonical`, the _canonical output format_ is the first one specified in:
+
+ - The [`outputs`][outputs_front_matter] front matter field of the current page, or
+ - The [`outputs`][outputs_project_config] section of your project configuration for the current [_page kind_](g).
+
+ [`rel`]: /configuration/output-formats/#rel
+ [outputs_front_matter]: /configuration/outputs/#outputs-per-page
+ [outputs_project_config]: /configuration/outputs/#outputs-per-page-kind
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_chain.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_chain.md
new file mode 100644
index 0000000..c5d19b1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_chain.md
@@ -0,0 +1,5 @@
+---
+title: chain
+---
+
+To _chain_ (verb) is to connect one or more [_identifiers_](g) with a dot. An identifier can represent a [_method_](g), [_object_](g), or [_field_](g). For example, `.Site.Params.author.name` or `.Date.UTC.Hour`.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_cicd.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_cicd.md
new file mode 100644
index 0000000..594a60e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_cicd.md
@@ -0,0 +1,16 @@
+---
+title: CI/CD
+params:
+ reference: https://en.wikipedia.org/wiki/CI/CD
+---
+
+The term _CI/CD_ is an abbreviation for Continuous Integration and Continuous Delivery or Continuous Deployment depending on context.
+
+ Popular _CI/CD_ platforms for building and deploying Hugo sites include [Cloudflare][], [GitHub Pages][], [GitLab Pages][], [Netlify][], [Render][], and [Vercel][].
+
+ [Cloudflare]: /host-and-deploy/host-on-cloudflare/
+ [GitHub Pages]: /host-and-deploy/host-on-github-pages/
+ [GitLab Pages]: /host-and-deploy/host-on-gitlab-pages/
+ [Netlify]: /host-and-deploy/host-on-netlify/
+ [Render]: /host-and-deploy/host-on-render/
+ [Vercel]: /host-and-deploy/host-on-vercel/
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_cli.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_cli.md
new file mode 100644
index 0000000..8f898e3
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_cli.md
@@ -0,0 +1,5 @@
+---
+title: CLI
+---
+
+_CLI_ stands for command-line interface, a text-based method for interacting with computer programs or operating systems.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_component.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_component.md
new file mode 100644
index 0000000..1843b18
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_component.md
@@ -0,0 +1,16 @@
+---
+title: component
+---
+
+A _component_ is a collection of related files, housed within the [_unified file system_](g), that fulfills a specific function in building a Hugo [_project_](g). These components are categorized into seven types: [_archetypes_](g), assets, content, data, templates, [_translation tables_](g), and static files, and can be defined within the project or provided by [_modules_](g). Each component has a dedicated directory within the unified file system:
+
+ Component|Directory within the unified file system
+ :--|:--
+ archetypes|`archetypes`
+ assets|`assets`
+ content|`content`
+ data|`data`
+ templates|`layouts`
+ translation tables|`i18n`
+ static files|`static`
+ {class="!mt-0"}
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_content-adapter.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_content-adapter.md
new file mode 100644
index 0000000..974e61d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_content-adapter.md
@@ -0,0 +1,6 @@
+---
+title: content adapter
+reference: /content-management/content-adapters
+---
+
+A _content adapter_ is a template that dynamically creates pages when building a site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_content-format.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_content-format.md
new file mode 100644
index 0000000..ea459de
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_content-format.md
@@ -0,0 +1,6 @@
+---
+title: content format
+reference: /content-management/formats
+---
+
+A _content format_ is a markup language for creating content. Typically Markdown, but may also be HTML, AsciiDoc, Org, Pandoc, or reStructuredText.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_content-type.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_content-type.md
new file mode 100644
index 0000000..758800c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_content-type.md
@@ -0,0 +1,5 @@
+---
+title: content type
+---
+
+A _content type_ is a classification of content inferred from the top-level directory name or the `type` set in [_front matter_](g). Pages in the root of the `content` directory, including the home page, are of type "page". The content type is a contributing factor in the template lookup order and determines which [_archetype_](g) template to use when creating new content.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_content-view.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_content-view.md
new file mode 100644
index 0000000..443a07a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_content-view.md
@@ -0,0 +1,6 @@
+---
+title: content view
+reference: /templates/types/#content-view
+---
+
+A _content view_ is a template called with the [`Render`](/methods/page/render/) method on a `Page` object.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_context.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_context.md
new file mode 100644
index 0000000..75afc70
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_context.md
@@ -0,0 +1,6 @@
+---
+title: context
+reference: /templates/introduction/#context
+---
+
+Represented by a dot (`.`) within a [_template action_](g), _context_ is the current location in a data structure. For example, while iterating over a [_collection_](g) of pages, the context within each iteration is the page's data structure. The context received by each template depends on template type and/or how it was called.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_default-language.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_default-language.md
new file mode 100644
index 0000000..5264343
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_default-language.md
@@ -0,0 +1,9 @@
+---
+title: default language
+---
+
+The _default language_ is the value defined by the [`defaultContentLanguage`][] setting, falling back to the first language in the project, and finally to `en`. The first language is identified by the lowest [_weight_](g), using lexicographical order as the final fallback if weights are tied or undefined.
+
+ See also: [_language_](g).
+
+ [`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_default-role.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_default-role.md
new file mode 100644
index 0000000..f065189
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_default-role.md
@@ -0,0 +1,9 @@
+---
+title: default role
+---
+
+The _default role_ is the value defined by the [`defaultContentRole`][] setting, falling back to the first role in the project, and finally to `guest`. The first role is identified by the lowest [_weight_](g), using lexicographical order as the final fallback if weights are tied or undefined.
+
+ See also: [_role_](g).
+
+ [`defaultContentRole`]: /configuration/all/#defaultcontentrole
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_default-site.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_default-site.md
new file mode 100644
index 0000000..3acad31
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_default-site.md
@@ -0,0 +1,5 @@
+---
+title: default site
+---
+
+The _default site_ is the [_site_](g) with the [_default language_](g), [_default version_](g), and [_default role_](g).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_default-sort-order.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_default-sort-order.md
new file mode 100644
index 0000000..9b981a7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_default-sort-order.md
@@ -0,0 +1,10 @@
+---
+title: default sort order
+---
+
+The _default sort order_ for [_page collections_](g), used when no other criteria are set, follows this priority:
+
+ 1. [`weight`](/content-management/front-matter/#weight) (ascending)
+ 1. [`date`](/content-management/front-matter/#date) (descending)
+ 1. [`linkTitle`](/content-management/front-matter/#linktitle) falling back to [`title`](/content-management/front-matter/#title) (ascending)
+ 1. [logical path](g) (ascending)
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_default-version.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_default-version.md
new file mode 100644
index 0000000..dc29047
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_default-version.md
@@ -0,0 +1,9 @@
+---
+title: default version
+---
+
+The _default version_ is the value defined by the [`defaultContentVersion`][] setting, falling back to the first version in the project, and finally to `v1.0.0`. The first version is identified by the lowest [_weight_](g), using a descending semantic sort as the final fallback if weights are tied or undefined.
+
+ See also: [_version_](g).
+
+ [`defaultContentVersion`]: /configuration/all/#defaultcontentversion
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_dependency-graph.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_dependency-graph.md
new file mode 100644
index 0000000..946e5b1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_dependency-graph.md
@@ -0,0 +1,5 @@
+---
+title: dependency graph
+---
+
+A _dependency graph_ visually represents the relationships between the [_modules_](g) used in a Hugo project. It shows how modules depend on each other, forming a network of dependencies.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_dimension.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_dimension.md
new file mode 100644
index 0000000..9db6d64
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_dimension.md
@@ -0,0 +1,5 @@
+---
+title: dimension
+---
+
+A _dimension_ is a categorized axis of content variation that allows multiple variations of a logical page to exist simultaneously. The three dimensions are [_language_](g), [_role_](g), and [_version_](g). For example, a logical page may exist in 6 languages, 4 versions, and 2 roles.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_duration.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_duration.md
new file mode 100644
index 0000000..21fd3c8
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_duration.md
@@ -0,0 +1,5 @@
+---
+title: duration
+---
+
+A _duration_ is a data type that represent a length of time, expressed using units such as seconds (represented by `s`), minutes (represented by `m`), and hours (represented by `h`). For example, `42s` means 42 seconds, `6m7s` means 6 minutes and 7 seconds, and `6h7m42s` means 6 hours, 7 minutes, and 42 seconds.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_embedded-template.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_embedded-template.md
new file mode 100644
index 0000000..3a08716
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_embedded-template.md
@@ -0,0 +1,5 @@
+---
+title: embedded template
+---
+
+An _embedded template_ is a built-in component within the Hugo application. This includes features like [_partials_](g), [_shortcodes_](g), and [_render hooks_](g) that provide pre-defined structures or functionalities for creating website content.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_environment.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_environment.md
new file mode 100644
index 0000000..0cfba95
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_environment.md
@@ -0,0 +1,9 @@
+---
+title: environment
+---
+
+Typically one of `development`, `staging`, or `production`, each _environment_ may exhibit different behavior depending on configuration and template logic. For example, in a production environment you might minify and fingerprint CSS, but that probably doesn't make sense in a development environment.
+
+ When running the built-in development server with the `hugo server` command, the environment is set to `development`. When building your project with the `hugo build` command, the environment is set to `production`. To override the environment value, use the `--environment` command line flag or the `HUGO_ENVIRONMENT` environment variable.
+
+ To determine the current environment within a template, use the [`hugo.Environment`](/functions/hugo/environment/) function.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_field.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_field.md
new file mode 100644
index 0000000..a32eb3a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_field.md
@@ -0,0 +1,5 @@
+---
+title: field
+---
+
+A _field_ is a predefined key-value pair in front matter such as `date` or `title`.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_flag.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_flag.md
new file mode 100644
index 0000000..e7b6c57
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_flag.md
@@ -0,0 +1,6 @@
+---
+title: flag
+reference: /commands/hugo
+---
+
+A _flag_ is an option passed to a command-line program, beginning with one or two hyphens.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_floating-point.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_floating-point.md
new file mode 100644
index 0000000..38ba9f0
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_floating-point.md
@@ -0,0 +1,5 @@
+---
+title: floating point
+---
+
+The term _floating point_ refers to a numeric data type with a fractional component. For example, `3.14159`.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_fragment.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_fragment.md
new file mode 100644
index 0000000..57ef1b4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_fragment.md
@@ -0,0 +1,5 @@
+---
+title: fragment
+---
+
+A _fragment_ is the final segment of a URL, beginning with a hash (`#`) mark, that references an `id` attribute of an HTML element on the page.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_front-matter.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_front-matter.md
new file mode 100644
index 0000000..5a3cd30
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_front-matter.md
@@ -0,0 +1,6 @@
+---
+title: front matter
+reference: /content-management/front-matter
+---
+
+The term _front matter_ refers to the metadata at the beginning of each content page, separated from the content by format-specific delimiters.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_function.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_function.md
new file mode 100644
index 0000000..a7da52c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_function.md
@@ -0,0 +1,6 @@
+---
+title: function
+reference: /functions
+---
+
+Used within a [_template action_](g), a _function_ takes one or more [_arguments_](g) and returns a value. Unlike [_methods_](g), functions are not associated with an [_object_](g).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_glob-pattern.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_glob-pattern.md
new file mode 100644
index 0000000..c57b452
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_glob-pattern.md
@@ -0,0 +1,6 @@
+---
+title: glob pattern
+reference: /quick-reference/glob-patterns/
+---
+
+A _glob pattern_ is a pattern used to match sets of values. It is a shorthand for specifying multiple targets at once, making it easier to work with groups of data or configurations.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_glob-slice.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_glob-slice.md
new file mode 100644
index 0000000..df37718
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_glob-slice.md
@@ -0,0 +1,16 @@
+---
+title: glob slice
+---
+
+A _glob slice_ is a [_slice_](g) of [_glob patterns_](g). Within the _slice_, a _glob_ can be negated by prefixing it with an exclamation mark (`!`) and one space. Matches in negated patterns short-circuit the evaluation of the rest of the _slice_, and are useful for early coarse grained exclusions.
+
+ The following example illustrates how to use _glob slices_ to define a [_sites matrix_](g) in your project configuration:
+
+ ```toml
+ [sites.matrix]
+ languages = [ "! no", "**" ]
+ versions = [ "! v1.2.3", "v1.*.*", "v2.*.*" ]
+ roles = [ "{member, guest}" ]
+ ```
+
+ The `versions` example above evaluates as: `(not v1.2.3) AND (v1.*.* OR v2.*.*)`.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_global-resource.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_global-resource.md
new file mode 100644
index 0000000..a4df65f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_global-resource.md
@@ -0,0 +1,5 @@
+---
+title: global resource
+---
+
+A _global resource_ is file within the `assets` directory, or within any directory mounted to the `assets` directory.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_headless-bundle.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_headless-bundle.md
new file mode 100644
index 0000000..ac7bf79
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_headless-bundle.md
@@ -0,0 +1,6 @@
+---
+title: headless bundle
+reference: /content-management/build-options/
+---
+
+A _headless bundle_ is an unpublished [_leaf bundle_](g) or an unpublished [_branch bundle_](g) whose content and resources you can include in other pages.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_iana.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_iana.md
new file mode 100644
index 0000000..89497f7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_iana.md
@@ -0,0 +1,6 @@
+---
+title: IANA
+reference: https://www.iana.org/about
+---
+
+_IANA_ is an abbreviation for the Internet Assigned Numbers Authority, a non-profit organization that manages the allocation of global IP addresses, autonomous system numbers, DNS root zone, media types, and other Internet Protocol-related resources.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_identifier.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_identifier.md
new file mode 100644
index 0000000..f53472f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_identifier.md
@@ -0,0 +1,5 @@
+---
+title: identifier
+---
+
+An _identifier_ is a string that represents a variable, method, object, or field. It must conform to Go's [language specification](https://go.dev/ref/spec#Identifiers), beginning with a letter or underscore, followed by zero or more letters, digits, or underscores.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_integer.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_integer.md
new file mode 100644
index 0000000..0af8213
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_integer.md
@@ -0,0 +1,5 @@
+---
+title: integer
+---
+
+An _integer_ is a numeric data type without a fractional component. For example, `42`.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_interleave.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_interleave.md
new file mode 100644
index 0000000..077ff7e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_interleave.md
@@ -0,0 +1,5 @@
+---
+title: interleave
+---
+
+To _interleave_ (verb) is to insert a string at the beginning, the end, and between every character of another string.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_internationalization.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_internationalization.md
new file mode 100644
index 0000000..4e8b019
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_internationalization.md
@@ -0,0 +1,5 @@
+---
+title: internationalization
+---
+
+The term _internationalization_ refers to software design and development efforts that enable [_localization_](g).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_interpreted-string-literal.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_interpreted-string-literal.md
new file mode 100644
index 0000000..fa92c97
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_interpreted-string-literal.md
@@ -0,0 +1,6 @@
+---
+title: interpreted string literal
+reference: https://go.dev/ref/spec#String_literals
+---
+
+An _interpreted string literal_ is a character sequence between double quotes, as in `"foo"`. Within the quotes, any character may appear except a newline and an unescaped double quote. The text between the quotes forms the value of the literal, with backslash escapes interpreted.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_interval.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_interval.md
new file mode 100644
index 0000000..a7ed8a6
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_interval.md
@@ -0,0 +1,11 @@
+---
+title: interval
+---
+
+An [_interval_](https://en.wikipedia.org/wiki/Interval_(mathematics)) is a range of numbers between two endpoints: closed, open, or half-open.
+
+ - A _closed interval_, denoted by brackets, includes its endpoints. For example, [0, 1] is the interval where `0 <= x <= 1`.
+
+ - An _open interval_, denoted by parentheses, excludes its endpoints. For example, (0, 1) is the interval where `0 < x < 1`.
+
+ - A _half-open interval_ includes only one of its endpoints. For example, (0, 1] is the _left-open_ interval where `0 < x <= 1`, while [0, 1) is the _right-open_ interval where `0 <= x < 1`.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_language.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_language.md
new file mode 100644
index 0000000..551dc69
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_language.md
@@ -0,0 +1,7 @@
+---
+title: language
+---
+
+A _language_ is a [_dimension_](g) that facilitates the localization and internationalization of content. While [_version_](g) focuses on lifecycle and [_role_](g) focuses on audience, the language dimension allows a logical page to be represented in different locales across the project.
+
+ See also: [_default language_](g).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_leaf-bundle.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_leaf-bundle.md
new file mode 100644
index 0000000..aa41384
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_leaf-bundle.md
@@ -0,0 +1,6 @@
+---
+title: leaf bundle
+reference: /content-management/page-bundles/
+---
+
+A _leaf bundle_ is a directory that contains an `index.md` file and zero or more [_resources_](g). Analogous to a physical leaf, a leaf bundle is at the end of a [_branch bundle_](g). It has no descendants.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_lexer.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_lexer.md
new file mode 100644
index 0000000..a462231
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_lexer.md
@@ -0,0 +1,5 @@
+---
+title: lexer
+---
+
+A _lexer_ is a software component that identifies keywords, identifiers, operators, numbers, and other basic building blocks of a programming language within the input text.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_list-page.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_list-page.md
new file mode 100644
index 0000000..d18efcf
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_list-page.md
@@ -0,0 +1,5 @@
+---
+title: list page
+---
+
+A list page is any [_page kind_](g) that receives a page [_collection_](g) in [_context_](g). This includes the home page, [_section pages_](g), [_taxonomy pages_](g), and [_term pages_](g).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_localization.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_localization.md
new file mode 100644
index 0000000..01f4506
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_localization.md
@@ -0,0 +1,6 @@
+---
+title: localization
+reference: /content-management/multilingual/
+---
+
+The term _localization_ refers to the process of adapting a site to meet language and regional requirements. This includes translations, date formats, number formats, currency formats, and collation order.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_logical-path.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_logical-path.md
new file mode 100644
index 0000000..2eeee75
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_logical-path.md
@@ -0,0 +1,6 @@
+---
+title: logical path
+reference: /methods/page/path/#examples
+---
+
+A _logical path_ is a page or page resource identifier derived from the file path, excluding its extension and language identifier. This value is neither a file path nor a URL. Starting with a file path relative to the `content` directory, Hugo determines the logical path by stripping the file extension and language identifier, converting to lower case, then replacing spaces with hyphens. Path segments are separated with a slash (`/`).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_map.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_map.md
new file mode 100644
index 0000000..b4605d2
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_map.md
@@ -0,0 +1,6 @@
+---
+title: map
+reference: https://go.dev/ref/spec#Map_types
+---
+
+A _map_ is an unordered group of elements, each indexed by a unique key.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_markdown-attribute.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_markdown-attribute.md
new file mode 100644
index 0000000..f5c57c7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_markdown-attribute.md
@@ -0,0 +1,6 @@
+---
+title: Markdown attribute
+reference: /content-management/markdown-attributes/
+---
+
+A _Markdown attribute_ is a key-value pair attached to a Markdown element. These attributes are commonly used to add HTML attributes, like `class` and `id`, to the element when it's rendered into HTML. They provide a way to extend the basic Markdown syntax and add more semantic meaning or styling hooks to your content.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_marshal.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_marshal.md
new file mode 100644
index 0000000..ce7d769
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_marshal.md
@@ -0,0 +1,6 @@
+---
+title: marshal
+reference: /functions/transform/remarshal/
+---
+
+To _marshal_ (verb) is to transform a data structure into a serialized object. For example, transforming a [_map_](g) into a JSON string.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_media-type.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_media-type.md
new file mode 100644
index 0000000..2994360
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_media-type.md
@@ -0,0 +1,6 @@
+---
+title: media type
+reference: /configuration/media-types/
+---
+
+A _media type_ (formerly known as a MIME type) is a two-part identifier for file formats and transmitted content. For example, the media type for JSON data is `application/json`.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_method.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_method.md
new file mode 100644
index 0000000..634cd4b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_method.md
@@ -0,0 +1,5 @@
+---
+title: method
+---
+
+Used within a [_template action_](g) and associated with an [_object_](g), a _method_ takes zero or more [_arguments_](g) and either returns a value or performs an action. For example, `IsHome` is a method on a `Page` object which returns `true` if the current page is the home page. See also [_function_](g).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_module.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_module.md
new file mode 100644
index 0000000..30ec49e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_module.md
@@ -0,0 +1,5 @@
+---
+title: module
+---
+
+A _module_ is a packaged combination of [_components_](g) which may include [_archetypes_](g), assets, content, data, templates, [_translation tables_](g), and static files. A module may be a [_theme_](g), a complete project, or a smaller collection of one or more components.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_mount.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_mount.md
new file mode 100644
index 0000000..1608e75
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_mount.md
@@ -0,0 +1,7 @@
+---
+title: mount
+params:
+ reference: /configuration/module
+---
+
+A _mount_ is a configuration object that maps a file path (source) to a [_component_](g) path (target) within Hugo's [_unified file system_](g).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_node.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_node.md
new file mode 100644
index 0000000..b722e07
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_node.md
@@ -0,0 +1,5 @@
+---
+title: node
+---
+
+A _node_ is a class of [_page kinds_](g) including `home`, `section`, `taxonomy`, and `term`.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_noop.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_noop.md
new file mode 100644
index 0000000..bd159bb
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_noop.md
@@ -0,0 +1,5 @@
+---
+title: noop
+---
+
+An abbreviated form of "no operation", a _noop_ is a statement that does nothing.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_ordered-taxonomy.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_ordered-taxonomy.md
new file mode 100644
index 0000000..9b6c1d9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_ordered-taxonomy.md
@@ -0,0 +1,5 @@
+---
+title: ordered taxonomy
+---
+
+Created by invoking the [`Alphabetical`](/methods/taxonomy/alphabetical/) or [`ByCount`](/methods/taxonomy/bycount/) method on a [`Taxonomy`](g) object, which is a [_map_](g), an _ordered taxonomy_ is a [_slice_](g), where each element is an object that contains the [_term_](g) and a slice of its [_weighted pages_](g).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_output-format.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_output-format.md
new file mode 100644
index 0000000..aa5ddbd
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_output-format.md
@@ -0,0 +1,6 @@
+---
+title: output format
+reference: /configuration/output-formats/
+---
+
+An _output format_ is a collection of settings that defines how Hugo renders a file when building a site. For example, `html`, `json`, and `rss` are built-in output formats. You can create multiple output formats and control their generation based on [_page kind_](g), or by enabling one or more output formats for specific pages.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_page-bundle.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_page-bundle.md
new file mode 100644
index 0000000..af76da2
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_page-bundle.md
@@ -0,0 +1,6 @@
+---
+title: page bundle
+reference: /content-management/page-bundles/
+---
+
+A _page bundle_ is a directory that encapsulates both content and associated [_resources_](g). There are two types of page bundles: [_leaf bundles_](g) and [_branch bundles_](g).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_page-kind.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_page-kind.md
new file mode 100644
index 0000000..ee47fe0
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_page-kind.md
@@ -0,0 +1,6 @@
+---
+title: page kind
+reference: /methods/page/kind/
+---
+
+A _page kind_ is a classification of pages, one of `home`, `page`, `section`, `taxonomy`, or `term`.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_page-relative.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_page-relative.md
new file mode 100644
index 0000000..d12327b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_page-relative.md
@@ -0,0 +1,7 @@
+---
+title: page-relative
+---
+
+A _page-relative_ path is resolved relative to the current page's location in the content hierarchy. These paths do not begin with a leading slash. Examples include `old-name`, `./old-name`, and `../old-name`.
+
+ See also: [_site-relative_](g), [_server-relative_](g).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_pager.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_pager.md
new file mode 100644
index 0000000..f58874e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_pager.md
@@ -0,0 +1,5 @@
+---
+title: pager
+---
+
+Created during [_pagination_](g), a _pager_ contains a subset of a list page and navigation links to other pagers.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_pagination.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_pagination.md
new file mode 100644
index 0000000..136341d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_pagination.md
@@ -0,0 +1,6 @@
+---
+title: pagination
+reference: /templates/pagination
+---
+
+The term _pagination_ refers to the process of [_paginating_](g) a list page.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_parameter.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_parameter.md
new file mode 100644
index 0000000..f1a45ea
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_parameter.md
@@ -0,0 +1,5 @@
+---
+title: parameter
+---
+
+A _parameter_ is typically a user-defined key-value pair at the site or page level, but may also refer to a configuration setting or an [_argument_](g).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_partial-decorator.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_partial-decorator.md
new file mode 100644
index 0000000..149e17e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_partial-decorator.md
@@ -0,0 +1,8 @@
+---
+title: partial decorator
+reference: /templates/partial-decorators/
+---
+
+A _partial decorator_ is specific type of [_partial_](g) that functions as a [_wrapper component_](g). While a standard partial simply renders data within a fixed template, a decorator uses composition to enclose an entire block of content. It utilizes the [`templates.Inner`][] function as a placeholder to define exactly where that external content should be injected within the wrapper's layout.
+
+ [`templates.Inner`]: /functions/templates/inner/
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_partial.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_partial.md
new file mode 100644
index 0000000..a5dd5e5
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_partial.md
@@ -0,0 +1,5 @@
+---
+title: partial
+---
+
+A _partial_ is a [_template_](g) called from any other template including [_shortcodes_](g), [render hooks](g), and other partials. A partial either renders something or returns something. A partial can also call itself, for example, to [_walk_](g) a data structure.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_permalink.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_permalink.md
new file mode 100644
index 0000000..45651de
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_permalink.md
@@ -0,0 +1,5 @@
+---
+title: permalink
+---
+
+A _permalink_ is the absolute URL of a published resource or a rendered page, including scheme and host.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_pipeline.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_pipeline.md
new file mode 100644
index 0000000..6dab525
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_pipeline.md
@@ -0,0 +1,7 @@
+---
+title: pipeline
+---
+
+Within a [_template action_](g), a _pipeline_ is a possibly chained sequence of values, [_function_](g) calls, or [_method_](g) calls. Functions and methods in the pipeline may take multiple [_arguments_](g).
+
+ A pipeline may be chained by separating a sequence of commands with pipeline characters (`|`). In a chained pipeline, the result of each command is passed as the last argument to the following command. The output of the final command in the pipeline is the value of the pipeline.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_primary-output-format.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_primary-output-format.md
new file mode 100644
index 0000000..d89fe25
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_primary-output-format.md
@@ -0,0 +1,10 @@
+---
+title: primary output format
+details: /configuration/outputs/
+---
+
+A _primary output format_ defines the default URL returned by the [`Permalink`] and [`RelPermalink`] methods for a given [_page kind_](g). It is specified as the first entry within the [outputs configuration] for that page kind.
+
+[`Permalink`]: /methods/page/permalink/
+[`RelPermalink`]: /methods/page/relpermalink/
+[outputs configuration]: /configuration/outputs/
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_processable-image.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_processable-image.md
new file mode 100644
index 0000000..eed69f1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_processable-image.md
@@ -0,0 +1,19 @@
+---
+title: processable image
+---
+
+A _processable image_ is an image file characterized by one of the following [_media types_](g):
+
+ - `image/bmp`
+ - `image/gif`
+ - `image/jpeg`
+ - `image/png`
+ - `image/tiff`
+ - `image/webp`
+
+ Hugo can decode and encode these image formats, allowing you to use any of the [resource methods][] applicable to images such as `Width`, `Height`, `Crop`, `Fill`, `Fit`, `Filter`, `Process`, `Resize`, etc.
+
+ Use the [`reflect.IsImageResourceProcessable`][] function to determine if an image can be processed.
+
+ [`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
+ [resource methods]: /methods/resource
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_project.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_project.md
new file mode 100644
index 0000000..86a3f63
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_project.md
@@ -0,0 +1,5 @@
+---
+title: project
+---
+
+A _project_ is a collection of [_components_](g) used to generate one or more [sites](g). While a project may consist of only a single site, Hugo allows a single project to generate a matrix of sites based on [_language_](g), [role](g), and [_version_](g). The project serves as the parent container for the common assets and logic used across all sites within the build.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_raw-string-literal.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_raw-string-literal.md
new file mode 100644
index 0000000..056c0e6
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_raw-string-literal.md
@@ -0,0 +1,6 @@
+---
+title: raw string literal
+reference: https://go.dev/ref/spec#String_literals
+---
+
+A _raw string literal_ is a character sequence between backticks, as in `` `bar` ``. Within the backticks, any character may appear except a backtick. Backslashes have no special meaning and the string may contain newlines. Carriage return characters (`\r`) inside raw string literals are discarded from the raw string value.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_regular-expression.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_regular-expression.md
new file mode 100644
index 0000000..82f8d98
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_regular-expression.md
@@ -0,0 +1,8 @@
+---
+title: regular expression
+reference:
+---
+
+A _regular expression_, also known as a _regex_, is a sequence of characters that defines a search pattern. Use the [RE2 syntax] when defining regular expressions in your templates or in your project configuration.
+
+ [RE2 syntax]: https://github.com/google/re2/wiki/syntax
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_regular-page.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_regular-page.md
new file mode 100644
index 0000000..084408e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_regular-page.md
@@ -0,0 +1,5 @@
+---
+title: regular page
+---
+
+A _regular page_ is a page with the "page" [_page kind_](g). See also [_section page_](g).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_relative-permalink.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_relative-permalink.md
new file mode 100644
index 0000000..a272133
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_relative-permalink.md
@@ -0,0 +1,5 @@
+---
+title: relative permalink
+---
+
+A _relative permalink_ is the host-relative URL of a published resource or a rendered page.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_remote-resource.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_remote-resource.md
new file mode 100644
index 0000000..1637497
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_remote-resource.md
@@ -0,0 +1,5 @@
+---
+title: remote resource
+---
+
+A _remote resource_ is a file on a remote server, accessible via HTTP or HTTPS.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_render-hook.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_render-hook.md
new file mode 100644
index 0000000..2cdb98e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_render-hook.md
@@ -0,0 +1,6 @@
+---
+title: render hook
+reference: /render-hooks
+---
+
+A _render hook_ is a [_template_](g) that overrides standard Markdown rendering.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_resource-type.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_resource-type.md
new file mode 100644
index 0000000..b10cd59
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_resource-type.md
@@ -0,0 +1,5 @@
+---
+title: resource type
+---
+
+A _resource type_ is the main type of a resource's [_media type_](g). Content files such as Markdown, HTML, AsciiDoc, Pandoc, reStructuredText, and Emacs Org Mode have resource type `page`. Other resource types include `image`, `text`, `video`, and others. Retrieve the resource type using the [`ResourceType`](/methods/resource/resourcetype/) method on a `Resource` object.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_resource.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_resource.md
new file mode 100644
index 0000000..0864bc4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_resource.md
@@ -0,0 +1,7 @@
+---
+title: resource
+---
+
+A _resource_ is any file consumed by the build process to augment or generate content, structure, behavior, or presentation. For example: images, videos, content snippets, CSS, Sass, JavaScript, and data.
+
+ Hugo supports three types of resources: [_global resources_](g), [_page resources_](g), and [_remote resources_](g).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_role.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_role.md
new file mode 100644
index 0000000..f491d36
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_role.md
@@ -0,0 +1,7 @@
+---
+title: role
+---
+
+A _role_ is a [_dimension_](g) that allows a logical page to be served in different forms depending on the target audience. While [_language_](g) focuses on localization and [_version_](g) focuses on lifecycle, the role dimension allows a project to generate variations of a page without duplicating content.
+
+ See also: [_default role_](g).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_rune-literal.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_rune-literal.md
new file mode 100644
index 0000000..8a19b48
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_rune-literal.md
@@ -0,0 +1,10 @@
+---
+title: rune literal
+reference: https://go.dev/ref/spec#Rune_literals
+---
+
+A _rune literal_ is the textual representation of a [_rune_](g) within a [_template_](g). It consists of a character sequence enclosed in single quotes, such as `'x'`, `'\n'`, or `'ü'`.
+
+ Unlike [_interpreted string literals_](g) or [_raw string literals_](g), which represent a sequence of characters, a _rune literal_ represents a single [_integer_](g) value identifying a Unicode [code point][]. Within the quotes, any character may appear except a newline or an unescaped single quote. Multi-character sequences starting with a backslash (`\`) can be used to encode specific values, such as `\n` for a newline or `\u00FC` for the letter `ü`.
+
+ [code point]: https://en.wikipedia.org/wiki/Code_point
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_rune.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_rune.md
new file mode 100644
index 0000000..74dfa4b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_rune.md
@@ -0,0 +1,11 @@
+---
+title: rune
+---
+
+A _rune_ is a way to represent a single character as a number. In Hugo and Go, text is stored as a sequence of bytes. However, while a basic letter like `x` uses only one byte, a single character such as the German `ü` is made up of multiple bytes. A _rune_ represents the entire character as one single value, no matter how many bytes it takes to store it.
+
+ Technically, a _rune_ is just another name for a 32-bit [_integer_](g). It stores the Unicode [code point][], which is the official number assigned to that specific character.
+
+ When you want to manipulate text character-by-character rather than by raw data size, you are working with _runes_. You write a _rune_ in a [_template_](g) using a [_rune literal_](g), such as `'x'`, `'\n'`, or `'ü'`.
+
+ [code point]: https://en.wikipedia.org/wiki/Code_point
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_scalar.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_scalar.md
new file mode 100644
index 0000000..63ae27d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_scalar.md
@@ -0,0 +1,5 @@
+---
+title: scalar
+---
+
+A _scalar_ is a single value, one of [_string_](g), [_integer_](g), [floating point](g), or [_boolean_](g).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_scope.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_scope.md
new file mode 100644
index 0000000..5230340
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_scope.md
@@ -0,0 +1,5 @@
+---
+title: scope
+---
+
+The term _scope_ refers to the specific region of code where a [_variable_](g) or [_object_](g) is accessible. For example, a variable initialized in one [_template_](g) is not available within another.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_scratch-pad.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_scratch-pad.md
new file mode 100644
index 0000000..4792ce1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_scratch-pad.md
@@ -0,0 +1,5 @@
+---
+title: scratch pad
+---
+
+Conceptually, a _scratch pad_ is a [_map_](g) with [_methods_](g) to set, get, update, and delete values. Attach the data structure to a `Page` or `Site` object using the [`Store`](/methods/page/store/) method, or create a locally scoped scratch pad using the [`newScratch`](/functions/collections/newscratch/) function.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_section-page.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_section-page.md
new file mode 100644
index 0000000..fd84ed5
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_section-page.md
@@ -0,0 +1,5 @@
+---
+title: section page
+---
+
+A _section page_ is a page with the "section" [_page kind_](g). Typically a listing of [_regular pages_](g) and/or other section pages within the current [_section_](g).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_section.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_section.md
new file mode 100644
index 0000000..45d1203
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_section.md
@@ -0,0 +1,5 @@
+---
+title: section
+---
+
+A _section_ is a top-level content directory or any content directory containing an `_index.md` file.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_seed.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_seed.md
new file mode 100644
index 0000000..bbb6e48
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_seed.md
@@ -0,0 +1,6 @@
+---
+title: seed
+reference: https://en.wikipedia.org/wiki/Random_seed
+---
+
+A _seed_ is the starting point for a computer algorithm that generates pseudo-random numbers. Using the same seed will always produce the identical sequence of numbers, which is essential for reproducibility in areas like simulations, cryptography, and video games.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_segment.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_segment.md
new file mode 100644
index 0000000..21c6255
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_segment.md
@@ -0,0 +1,7 @@
+---
+title: segment
+params:
+ reference: /configuration/segments/
+---
+
+A _segment_ is a subset of a site, filtered by [_logical path_](g), [_sites matrix_](g), [_page kind_](g), or [_output format_](g).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_server-relative.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_server-relative.md
new file mode 100644
index 0000000..8783a25
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_server-relative.md
@@ -0,0 +1,9 @@
+---
+title: server-relative
+---
+
+A _server-relative_ path is the final path from the web server's root, used in the generated site. These paths always begin with a leading slash and account for the [`baseURL`] and [_content dimension_](g) prefixes such as language, [_role_](g), or version. For example, `/en/examples/old-name/` is a server-relative path.
+
+ See also: [_page-relative_](g), [_site-relative_](g).
+
+ [`baseURL`]: /configuration/all/#baseurl
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_shortcode.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_shortcode.md
new file mode 100644
index 0000000..a6503ea
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_shortcode.md
@@ -0,0 +1,6 @@
+---
+title: shortcode
+reference: /content-management/shortcodes
+---
+
+A _shortcode_ is a [_template_](g) invoked within markup, accepting any number of [_arguments_](g). They can be used with any [_content format_](g) to insert elements such as videos, images, and social media embeds into your content.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_site-relative.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_site-relative.md
new file mode 100644
index 0000000..b434fd1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_site-relative.md
@@ -0,0 +1,7 @@
+---
+title: site-relative
+---
+
+A _site-relative_ path is resolved relative to the root of the content directory. These paths begin with a leading slash. For example, `/old-name` is a site-relative path.
+
+ See also: [_page-relative_](g), [_server-relative_](g).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_site-root.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_site-root.md
new file mode 100644
index 0000000..1066acb
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_site-root.md
@@ -0,0 +1,13 @@
+---
+title: site root
+---
+
+The _site root_ is the root directory of the current [_site_](g), relative to the [`publishDir`][]. The _site root_ may include one or more content [_dimension_](g) prefixes, such as [_language_](g), [_role_](g), or [_version_](g).
+
+ Project description|Site root examples
+ :--|:--|:--
+ Monolingual|`/`, `/guest`, `/guest/v1.2.3`
+ Multilingual single-host|`/en`, `/guest/en`, `/guest/v1.2.3/en`
+ Multilingual multihost|`/en`, `/en/guest`, `/en/guest/v1.2.3`
+
+ [`publishDir`]: /configuration/all/#publishdir
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_site.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_site.md
new file mode 100644
index 0000000..f3be3a1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_site.md
@@ -0,0 +1,5 @@
+---
+title: site
+---
+
+A _site_ is a specific instance of your [_project_](g) representing a unique combination of [_language_](g), [_role_](g), and [_version_](g). While a simple project may consist of only a single site, Hugo's multidimensional content model allows a single codebase to generate a matrix of sites simultaneously.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_sites-complements.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_sites-complements.md
new file mode 100644
index 0000000..80213e1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_sites-complements.md
@@ -0,0 +1,5 @@
+---
+title: sites complements
+---
+
+A _sites complements_ is a configuration object defined in content front matter or a file mount. The links will point to the complementary [_sites_](g). The configuration is structured as a map of [_glob slices_](g).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_sites-matrix.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_sites-matrix.md
new file mode 100644
index 0000000..8e6838d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_sites-matrix.md
@@ -0,0 +1,7 @@
+---
+title: sites matrix
+---
+
+A _sites matrix_ is a configuration object defined in content front matter or a file mount to precisely control which [_sites_](g) the content should be generated for. When defined in a file mount for templates, it controls which sites the template will be applied to. In Hugo multidimensional content model, the matrix defines the intersection of three dimensions: [_language_](g), [_role_](g), and [_version_](g). The configuration is structured as a map of [_glob slices_](g).
+
+ See also [_sites complements_](g), [front matter: sites](/content-management/front-matter/#sites), [module mounts: sites](/configuration/module/#sites), and [segments: sites](/configuration/segments/#sites).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_slice.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_slice.md
new file mode 100644
index 0000000..5d83bed
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_slice.md
@@ -0,0 +1,6 @@
+---
+title: slice
+reference: https://go.dev/ref/spec#Slice_types
+---
+
+A _slice_ is a numbered sequence of elements. Unlike Go's [_array_](g) data type, slices are dynamically sized. [_Elements_](g) within a slice can be [_scalars_](g), [_arrays_](g), [_maps_](g), pages, or other slices.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_taxonomic-weight.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_taxonomic-weight.md
new file mode 100644
index 0000000..90bd804
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_taxonomic-weight.md
@@ -0,0 +1,6 @@
+---
+title: taxonomic weight
+reference: /content-management/taxonomies/#taxonomic-weight
+---
+
+Defined in front matter and unique to each taxonomy, a _taxonomic weight_ is a [_weight_](g) that determines the sort order of page collections contained within a [`Taxonomy`](g) object.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_taxonomy-object.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_taxonomy-object.md
new file mode 100644
index 0000000..525446a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_taxonomy-object.md
@@ -0,0 +1,5 @@
+---
+title: taxonomy object
+---
+
+A _taxonomy object_ is a [_map_](g) of [_terms_](g) and the [_weighted pages_](g) associated with each term.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_taxonomy-page.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_taxonomy-page.md
new file mode 100644
index 0000000..6b62f09
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_taxonomy-page.md
@@ -0,0 +1,5 @@
+---
+title: taxonomy page
+---
+
+A _taxonomy page_ is a page with the "taxonomy" [_page kind_](g). Typically a listing of [_terms_](g) within a given [_taxonomy_](g).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_taxonomy.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_taxonomy.md
new file mode 100644
index 0000000..ce35a63
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_taxonomy.md
@@ -0,0 +1,5 @@
+---
+title: taxonomy
+reference: /content-management/taxonomies
+---
+A _taxonomy_ is a group of related [_terms_](g) used to classify content. For example, a "colors" taxonomy might include the terms "red", "green", and "blue".
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_template-action.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_template-action.md
new file mode 100644
index 0000000..e40c228
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_template-action.md
@@ -0,0 +1,6 @@
+---
+title: template action
+reference: https://pkg.go.dev/text/template#hdr-Actions
+---
+
+A data evaluation or control structure within a [_template_](g), delimited by `{{` and `}}`.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_template.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_template.md
new file mode 100644
index 0000000..d442c0a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_template.md
@@ -0,0 +1,6 @@
+---
+title: template
+reference: /templates
+---
+
+A _template_ is a file with [_template actions_](g), located within the `layouts` directory of a project, theme, or module.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_term-page.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_term-page.md
new file mode 100644
index 0000000..78eabc1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_term-page.md
@@ -0,0 +1,5 @@
+---
+title: term page
+---
+
+A _term page_ is a page with the "term" [_page kind_](g). Typically a listing of [_regular pages_](g) and [_section pages_](g) with a given [_term_](g).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_term.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_term.md
new file mode 100644
index 0000000..cafd925
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_term.md
@@ -0,0 +1,6 @@
+---
+title: term
+reference: /content-management/taxonomies
+---
+
+A _term_ is a member of a [_taxonomy_](g), used to classify content.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_theme.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_theme.md
new file mode 100644
index 0000000..4c6d15e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_theme.md
@@ -0,0 +1,5 @@
+---
+title: theme
+---
+
+A _theme_ is a [_module_](g) that delivers a complete set of [_components_](g) defining a site's layout, presentation, and behavior. While every theme is a module, not every module is a theme.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_token.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_token.md
new file mode 100644
index 0000000..f8c12d5
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_token.md
@@ -0,0 +1,5 @@
+---
+title: token
+---
+
+A _token_ is an identifier within a format string, beginning with a colon and replaced with a value when rendered. For example, use tokens in format strings for both [permalinks](/content-management/urls/#permalinks) and [dates](/functions/time/format/#localization).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_translation-table.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_translation-table.md
new file mode 100644
index 0000000..a48febb
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_translation-table.md
@@ -0,0 +1,5 @@
+---
+title: translation table
+---
+
+A _translation table_ is a data file within the `i18n` directory, holding translations for a single language.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_unified-file-system.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_unified-file-system.md
new file mode 100644
index 0000000..4e5f430
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_unified-file-system.md
@@ -0,0 +1,5 @@
+---
+title: unified file system
+---
+
+Hugo's _unified file system_ provides a layered view for each of its seven [_component_](g) types: [_archetypes_](g), assets, content, data, templates, [_translation tables_](g), and static files. Project component directories are layered over [_module_](g) component directories. When multiple layers contain the same file, Hugo uses the version from the highest layer.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_unmarshal.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_unmarshal.md
new file mode 100644
index 0000000..d449b0b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_unmarshal.md
@@ -0,0 +1,6 @@
+---
+title: unmarshal
+reference: /functions/transform/unmarshal/
+---
+
+To _unmarshal_ (verb) is to transform a serialized object into a data structure. For example, transforming a JSON file into a [_map_](g) that you can access within a template.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_utc.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_utc.md
new file mode 100644
index 0000000..a4627be
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_utc.md
@@ -0,0 +1,6 @@
+---
+title: UTC
+reference: https://en.wikipedia.org/wiki/Coordinated_Universal_Time
+---
+
+_UTC_ is an abbreviation for Coordinated Universal Time, the primary time standard used worldwide to regulate clocks and time. It is the basis for civil time and time zones across the globe.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_variable.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_variable.md
new file mode 100644
index 0000000..f8139a4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_variable.md
@@ -0,0 +1,5 @@
+---
+title: variable
+---
+
+A _variable_ is a user-defined [_identifier_](g) prepended with a `$` symbol, representing a value of any data type, initialized or assigned within a [_template action_](g). For example, `$foo` and `$bar` are variables.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_vendor.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_vendor.md
new file mode 100644
index 0000000..f745a4e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_vendor.md
@@ -0,0 +1,7 @@
+---
+title: vendor
+---
+
+To _vendor_ (verb) in a software context is the process of including the source code of third-party dependencies directly within your own project's repository, rather than downloading them on the fly from an external package manager.
+
+ When you are asked to "vendor the dependencies into the project root," you are being told to move those external libraries from a temporary cache into a dedicated folder that gets committed to your version control system.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_version.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_version.md
new file mode 100644
index 0000000..62eb8f3
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_version.md
@@ -0,0 +1,9 @@
+---
+title: version
+---
+
+A _version_ is a [_dimension_](g) that represents a specific iteration, release, or lifecycle stage of content. While [_language_](g) focuses on localization and [_role_](g) focuses on audience, the version dimension allows you to maintain multiple states of the same content simultaneously using [semantic versioning].
+
+ See also: [_default version_](g).
+
+ [semantic versioning]: https://semver.org/
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_walk.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_walk.md
new file mode 100644
index 0000000..2b2a844
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_walk.md
@@ -0,0 +1,5 @@
+---
+title: walk
+---
+
+To _walk_ (verb) is to recursively traverse a nested data structure. For example, rendering a multilevel menu.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_weight.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_weight.md
new file mode 100644
index 0000000..01b91fe
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_weight.md
@@ -0,0 +1,5 @@
+---
+title: weight
+---
+
+A _weight_ is a numeric value used to position an element within a sorted [_collection_](g). Assign weights using non-zero integers. Lighter items float to the top, while heavier items sink to the bottom. Unweighted or zero-weighted elements are placed at the end of the collection. Weights are typically assigned to pages, menu entries, languages, [_roles_](g), versions, and output formats.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_weighted-page.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_weighted-page.md
new file mode 100644
index 0000000..e6cf8d6
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_weighted-page.md
@@ -0,0 +1,5 @@
+---
+title: weighted page
+---
+
+Contained within a [_taxonomy object_](g), a _weighted page_ is a [_map_](g) with two [_elements_](g): a `Page` object, and its [_taxonomic weight_](g) as defined in front matter. Access the elements using the `Page` and `Weight` keys.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_workspace.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_workspace.md
new file mode 100644
index 0000000..6eda9ba
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_workspace.md
@@ -0,0 +1,7 @@
+---
+title: workspace
+params:
+ reference: /hugo-modules/use-modules/#workspace
+---
+
+A _workspace_ is a collection of [_modules_](g) on disk.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_wrapper-component.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_wrapper-component.md
new file mode 100644
index 0000000..ada5d46
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_wrapper-component.md
@@ -0,0 +1,7 @@
+---
+title: wrapper component
+---
+
+A _wrapper component_ is an interface pattern that encloses other content through composition rather than fixed parameters. It provides a reusable shell to handle layout, styling, or logic, allowing the calling template to inject arbitrary content into the component's interior.
+
+ See also: [_partial decorator_](g).
diff --git a/documents/markdown/hugo-docs/en_quick-reference_glossary_zero-time.md b/documents/markdown/hugo-docs/en_quick-reference_glossary_zero-time.md
new file mode 100644
index 0000000..9701f39
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_glossary_zero-time.md
@@ -0,0 +1,5 @@
+---
+title: zero time
+---
+
+The _zero time_ is January 1, 0001, 00:00:00 UTC. Formatted per [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) the _zero time_ is 0001-01-01T00:00:00-00:00.
diff --git a/documents/markdown/hugo-docs/en_quick-reference_methods.md b/documents/markdown/hugo-docs/en_quick-reference_methods.md
new file mode 100644
index 0000000..524713c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_methods.md
@@ -0,0 +1,8 @@
+---
+title: Methods
+description: A quick reference guide to Hugo's methods, grouped by object.
+categories: []
+keywords: []
+---
+
+{{% quick-reference section="methods" %}}
diff --git a/documents/markdown/hugo-docs/en_quick-reference_page-collections.md b/documents/markdown/hugo-docs/en_quick-reference_page-collections.md
new file mode 100644
index 0000000..14beded
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_page-collections.md
@@ -0,0 +1,38 @@
+---
+title: Page collections
+description: A quick reference guide to Hugo's page collections.
+categories: []
+keywords: []
+---
+
+## Page
+
+Use these `Page` methods when rendering lists on [section pages](g), [taxonomy pages](g), [term pages](g), and the home page.
+
+{{% render-list-of-pages-in-section path=/methods/page filter=methods_page_page_collections filterType=include titlePrefix=PAGE. %}}
+
+## Site
+
+Use these `Site` methods when rendering lists on any page.
+
+{{% render-list-of-pages-in-section path=/methods/site filter=methods_site_page_collections filterType=include titlePrefix=SITE. %}}
+
+## Filter
+
+Use the [`where`][] function to filter page collections.
+
+## Sort
+
+{{% glossary-term "default sort order" %}}
+
+Use these methods to sort page collections by different criteria.
+
+{{% render-list-of-pages-in-section path=/methods/pages filter=methods_pages_sort filterType=include titlePrefix=. titlePrefix=PAGES. %}}
+
+## Group
+
+Use these methods to group page collections.
+
+{{% render-list-of-pages-in-section path=/methods/pages filter=methods_pages_group filterType=include titlePrefix=. titlePrefix=PAGES. %}}
+
+[`where`]: /functions/collections/where/
diff --git a/documents/markdown/hugo-docs/en_quick-reference_syntax-highlighting-styles.md b/documents/markdown/hugo-docs/en_quick-reference_syntax-highlighting-styles.md
new file mode 100644
index 0000000..3ba6fd8
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_quick-reference_syntax-highlighting-styles.md
@@ -0,0 +1,35 @@
+---
+title: Syntax highlighting styles
+description: Highlight code examples using one of these styles.
+categories: []
+keywords: [highlight]
+---
+
+## Overview
+
+Hugo provides several methods to add syntax highlighting to code examples:
+
+- Use the [`transform.Highlight`] function within your templates
+- Use the [`highlight`] shortcode with any [content format](g)
+- Use [fenced code blocks] with the Markdown content format
+
+Regardless of method, use any of the syntax highlighting styles below.
+
+Set the default syntax highlighting style in your project configuration:
+
+{{< code-toggle file=hugo >}}
+[markup.highlight]
+style = 'monokai'
+{{< /code-toggle >}}
+
+See [configure Markup](/configuration/markup/#highlight).
+
+[`transform.Highlight`]: /functions/transform/highlight/
+[`highlight`]: /shortcodes/highlight/
+[fenced code blocks]: /content-management/syntax-highlighting/#fenced-code-blocks
+
+## Styles
+
+This gallery demonstrates the application of each syntax highlighting style with code examples written in different programming languages.
+
+{{% syntax-highlighting-styles %}}
diff --git a/documents/markdown/hugo-docs/en_render-hooks__index.md b/documents/markdown/hugo-docs/en_render-hooks__index.md
new file mode 100644
index 0000000..a957cb4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_render-hooks__index.md
@@ -0,0 +1,8 @@
+---
+title: Render hooks
+description: Create render hook templates to override the rendering of Markdown to HTML.
+categories: []
+keywords: []
+weight: 10
+aliases: [/templates/render-hooks/]
+---
diff --git a/documents/markdown/hugo-docs/en_render-hooks_blockquotes.md b/documents/markdown/hugo-docs/en_render-hooks_blockquotes.md
new file mode 100755
index 0000000..77e7059
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_render-hooks_blockquotes.md
@@ -0,0 +1,183 @@
+---
+title: Blockquote render hooks
+linkTitle: Blockquotes
+description: Create blockquote render hook templates to override the rendering of Markdown blockquotes to HTML.
+categories: []
+keywords: []
+---
+
+{{< new-in 0.132.0 />}}
+
+## Context
+
+Blockquote _render hook_ templates receive the following [context](g):
+
+AlertType
+: (`string`) Applicable when [`Type`](#type) is `alert`, this is the alert type converted to lowercase. See the [alerts](#alerts) section below.
+
+AlertTitle
+: {{< new-in 0.134.0 />}}
+: (`template.HTML`) Applicable when [`Type`](#type) is `alert`, this is the alert title. See the [alerts](#alerts) section below.
+
+AlertSign
+: {{< new-in 0.134.0 />}}
+: (`string`) Applicable when [`Type`](#type) is `alert`, this is the alert sign. Typically used to indicate whether an alert is graphically foldable, this is one of `+`, `-`, or an empty string. See the [alerts](#alerts) section below.
+
+Attributes
+: (`map`) The [Markdown attributes], available if you configure your site as follows:
+
+ {{< code-toggle file=hugo >}}
+ [markup.goldmark.parser.attribute]
+ block = true
+ {{< /code-toggle >}}
+
+Ordinal
+: (`int`) The zero-based ordinal of the blockquote on the page.
+
+Page
+: (`page`) A reference to the current page.
+
+PageInner
+: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
+
+Position
+: (`string`) The position of the blockquote within the page content.
+
+Text
+: (`template.HTML`) The blockquote text, excluding the first line if [`Type`](#type) is `alert`. See the [alerts](#alerts) section below.
+
+Type
+: (`string`) The blockquote type. Returns `alert` if the blockquote has an alert designator, else `regular`. See the [alerts](#alerts) section below.
+
+## Examples
+
+In its default configuration, Hugo renders Markdown blockquotes according to the [CommonMark specification]. To create a render hook that does the same thing:
+
+```go-html-template {file="layouts/_markup/render-blockquote.html" copy=true}
+<blockquote>
+ {{ .Text }}
+</blockquote>
+```
+
+To render a blockquote as an HTML `figure` element with an optional citation and caption:
+
+```go-html-template {file="layouts/_markup/render-blockquote.html" copy=true}
+<figure>
+ <blockquote {{ with .Attributes.cite }}cite="{{ . }}"{{ end }}>
+ {{ .Text }}
+ </blockquote>
+ {{ with .Attributes.caption }}
+ <figcaption class="blockquote-caption">
+ {{ . | safeHTML }}
+ </figcaption>
+ {{ end }}
+</figure>
+```
+
+Then in your markdown:
+
+```text
+> Some text
+{cite="https://gohugo.io" caption="Some caption"}
+```
+
+## Alerts
+
+Also known as _callouts_ or _admonitions_, alerts are blockquotes used to emphasize critical information.
+
+### Basic syntax
+
+With the basic Markdown syntax, the first line of each alert is an alert designator consisting of an exclamation point followed by the alert type, wrapped within brackets. For example:
+
+```text {file="content/example.md"}
+> [!NOTE]
+> Useful information that users should know, even when skimming content.
+
+> [!TIP]
+> Helpful advice for doing things better or more easily.
+
+> [!IMPORTANT]
+> Key information users need to know to achieve their goal.
+
+> [!WARNING]
+> Urgent info that needs immediate user attention to avoid problems.
+
+> [!CAUTION]
+> Advises about risks or negative outcomes of certain actions.
+```
+
+The basic syntax is compatible with [GitHub], [Obsidian], and [Typora].
+
+### Extended syntax
+
+With the extended Markdown syntax, you may optionally include an alert sign and/or an alert title. The alert sign is one of `+` or `-`, typically used to indicate whether an alert is graphically foldable. For example:
+
+```text {file="content/example.md"}
+> [!WARNING]+ Radiation hazard
+> Do not approach or handle without protective gear.
+```
+
+The extended syntax is compatible with [Obsidian].
+
+> [!note]
+> The extended syntax is not compatible with GitHub or Typora. If you include an alert sign or an alert title, these applications render the Markdown as a blockquote.
+
+### Example
+
+This blockquote render hook renders a multilingual alert if an alert designator is present, otherwise it renders a blockquote according to the CommonMark specification.
+
+```go-html-template {file="layouts/_markup/render-blockquote.html" copy=true}
+{{ $emojis := dict
+ "caution" ":exclamation:"
+ "important" ":information_source:"
+ "note" ":information_source:"
+ "tip" ":bulb:"
+ "warning" ":information_source:"
+}}
+
+{{ if eq .Type "alert" }}
+ <blockquote class="alert alert-{{ .AlertType }}">
+ <p class="alert-heading">
+ {{ transform.Emojify (index $emojis .AlertType) }}
+ {{ with .AlertTitle }}
+ {{ . }}
+ {{ else }}
+ {{ or (i18n .AlertType) (title .AlertType) }}
+ {{ end }}
+ </p>
+ {{ .Text }}
+ </blockquote>
+{{ else }}
+ <blockquote>
+ {{ .Text }}
+ </blockquote>
+{{ end }}
+```
+
+To override the label, create these entries in your i18n files:
+
+{{< code-toggle file=i18n/en.toml >}}
+caution = 'Caution'
+important = 'Important'
+note = 'Note'
+tip = 'Tip'
+warning = 'Warning'
+{{< /code-toggle >}}
+
+Although you can use one template with conditional logic as shown above, you can also create separate templates for each [`Type`](#type) of blockquote:
+
+```text
+layouts/
+ └── _markup/
+ ├── render-blockquote-alert.html
+ └── render-blockquote-regular.html
+```
+
+{{% include "/_common/render-hooks/pageinner.md" %}}
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes
+[CommonMark specification]: https://spec.commonmark.org/current/
+[GitHub]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts
+[Markdown attributes]: /content-management/markdown-attributes/
+[Obsidian]: https://help.obsidian.md/Editing+and+formatting/Callouts
+[Typora]: https://support.typora.io/Markdown-Reference/#callouts--github-style-alerts
diff --git a/documents/markdown/hugo-docs/en_render-hooks_code-blocks.md b/documents/markdown/hugo-docs/en_render-hooks_code-blocks.md
new file mode 100755
index 0000000..5b22646
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_render-hooks_code-blocks.md
@@ -0,0 +1,125 @@
+---
+title: Code block render hooks
+linkTitle: Code blocks
+description: Create code block render hook templates to override the rendering of Markdown code blocks to HTML.
+categories: []
+keywords: []
+---
+
+## Markdown
+
+This Markdown example contains a fenced code block:
+
+````text {file="content/example.md"}
+```sh {class="my-class" id="my-codeblock" lineNos=inline tabWidth=2}
+declare a=1
+echo "$a"
+exit
+```
+````
+
+A fenced code block consists of:
+
+- A leading [code fence]
+- An optional [info string]
+- A code sample
+- A trailing code fence
+
+In the previous example, the info string contains:
+
+- The language of the code sample (the first word)
+- An optional space-delimited or comma-delimited list of attributes (everything within braces)
+
+The attributes in the info string can be generic attributes or highlighting options.
+
+In the example above, the _generic attributes_ are `class` and `id`. In the absence of special handling within a code block render hook, Hugo adds each generic attribute to the HTML element surrounding the rendered code block. Consistent with its content security model, Hugo removes HTML event attributes such as `onclick` and `onmouseover`. Generic attributes are typically global HTML attributes, but you may include custom attributes as well.
+
+In the example above, the _highlighting options_ are `lineNos` and `tabWidth`. Hugo uses the [Chroma] syntax highlighter to render the code sample. You can control the appearance of the rendered code by specifying one or more [highlighting options].
+
+> [!note]
+> Although `style` is a global HTML attribute, when used in an info string it is a highlighting option.
+
+## Context
+
+Code block _render hook_ templates receive the following [context](g):
+
+Attributes
+: (`map`) The generic attributes from the info string.
+
+Inner
+: (`string`) The content between the leading and trailing code fences, excluding the info string.
+
+Options
+: (`map`) The highlighting options from the info string. This map is empty if [`Type`](#type) is an empty string or a code language that is not supported by the Chroma syntax highlighter. However, in this case, the highlighting options are available in the [`Attributes`](#attributes) map.
+
+Ordinal
+: (`int`) The zero-based ordinal of the code block on the page.
+
+Page
+: (`page`) A reference to the current page.
+
+PageInner
+: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
+
+Position
+: (`text.Position`) The position of the code block within the page content.
+
+Type
+: (`string`) The first word of the info string, typically the code language.
+
+## Examples
+
+In its default configuration, Hugo renders fenced code blocks by passing the code sample through the Chroma syntax highlighter and wrapping the result. To create a render hook that does the same thing:
+
+```go-html-template {file="layouts/_markup/render-codeblock.html" copy=true}
+{{ $result := transform.HighlightCodeBlock . }}
+{{ $result.Wrapped }}
+```
+
+Although you can use one template with conditional logic to control the behavior on a per-language basis, you can also create language-specific templates.
+
+```text
+layouts/
+ └── _markup/
+ ├── render-codeblock-mermaid.html
+ ├── render-codeblock-python.html
+ └── render-codeblock.html
+```
+
+For example, to create a code block render hook to render [Mermaid] diagrams:
+
+```go-html-template {file="layouts/_markup/render-codeblock-mermaid.html" copy=true}
+<pre class="mermaid">
+ {{ .Inner | htmlEscape | safeHTML }}
+</pre>
+{{ .Page.Store.Set "hasMermaid" true }}
+```
+
+Then include this snippet at the _bottom_ of your base template, before the closing `body` tag:
+
+```go-html-template {file="layouts/baseof.html" copy=true}
+{{ if .Store.Get "hasMermaid" }}
+ <script type="module">
+ import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
+ mermaid.initialize({ startOnLoad: true });
+ </script>
+{{ end }}
+```
+
+See the [diagrams] page for details.
+
+## Embedded
+
+Hugo includes an [embedded code block render hook] to render [GoAT diagrams].
+
+{{% include "/_common/render-hooks/pageinner.md" %}}
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes
+[Chroma]: https://github.com/alecthomas/chroma/
+[code fence]: https://spec.commonmark.org/current/#code-fence
+[diagrams]: /content-management/diagrams/#mermaid-diagrams
+[embedded code block render hook]: <{{% eturl render-codeblock-goat %}}>
+[GoAT diagrams]: /content-management/diagrams/#goat-diagrams-ascii
+[highlighting options]: /functions/transform/highlight/#options
+[info string]: https://spec.commonmark.org/current/#info-string
+[Mermaid]: https://mermaid.js.org/
diff --git a/documents/markdown/hugo-docs/en_render-hooks_headings.md b/documents/markdown/hugo-docs/en_render-hooks_headings.md
new file mode 100755
index 0000000..75c57d3
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_render-hooks_headings.md
@@ -0,0 +1,63 @@
+---
+title: Heading render hooks
+linkTitle: Headings
+description: Create heading render hook templates to override the rendering of Markdown headings to HTML.
+categories: []
+keywords: []
+---
+
+## Context
+
+Heading _render hook_ templates receive the following [context](g):
+
+Anchor
+: (`string`) The `id` attribute of the heading element.
+
+Attributes
+: (`map`) The [Markdown attributes], available if you configure your site as follows:
+
+ {{< code-toggle file=hugo >}}
+ [markup.goldmark.parser.attribute]
+ title = true
+ {{< /code-toggle >}}
+
+Level
+: (`int`) The heading level, 1 through 6.
+
+Page
+: (`page`) A reference to the current page.
+
+PageInner
+: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
+
+PlainText
+: (`string`) The heading text as plain text.
+
+Text
+: (`template.HTML`) The heading text.
+
+[Markdown attributes]: /content-management/markdown-attributes/
+[`RenderShortcodes`]: /methods/page/rendershortcodes
+
+## Examples
+
+In its default configuration, Hugo renders Markdown headings according to the [CommonMark specification] with the addition of automatic `id` attributes. To create a render hook that does the same thing:
+
+[CommonMark specification]: https://spec.commonmark.org/current/
+
+```go-html-template {file="layouts/_markup/render-heading.html" copy=true}
+<h{{ .Level }} id="{{ .Anchor }}" {{- with .Attributes.class }} class="{{ . }}" {{- end }}>
+ {{- .Text -}}
+</h{{ .Level }}>
+```
+
+To add an anchor link to the right of each heading:
+
+```go-html-template {file="layouts/_markup/render-heading.html" copy=true}
+<h{{ .Level }} id="{{ .Anchor }}" {{- with .Attributes.class }} class="{{ . }}" {{- end }}>
+ {{ .Text }}
+ <a href="#{{ .Anchor }}">#</a>
+</h{{ .Level }}>
+```
+
+{{% include "/_common/render-hooks/pageinner.md" %}}
diff --git a/documents/markdown/hugo-docs/en_render-hooks_images.md b/documents/markdown/hugo-docs/en_render-hooks_images.md
new file mode 100755
index 0000000..91fe40f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_render-hooks_images.md
@@ -0,0 +1,134 @@
+---
+title: Image render hooks
+linkTitle: Images
+description: Create image render hook templates to override the rendering of Markdown images to HTML.
+categories: []
+keywords: []
+---
+
+## Markdown
+
+A Markdown image has three components: the image description, the image destination, and optionally the image title.
+
+```text
+
+ ------------ ------------------ ---------
+ description destination title
+```
+
+These components are passed into the render hook [context](g) as shown below.
+
+## Context
+
+Image _render hook_ templates receive the following context:
+
+Attributes
+: (`map`) The [Markdown attributes], available if you configure your site as follows:
+
+ {{< code-toggle file=hugo >}}
+ [markup.goldmark.parser]
+ wrapStandAloneImageWithinParagraph = false
+ [markup.goldmark.parser.attribute]
+ block = true
+ {{< /code-toggle >}}
+
+Destination
+: (`string`) The image destination.
+
+IsBlock
+: (`bool`) Reports whether a standalone image is not wrapped within a paragraph element.
+
+Ordinal
+: (`int`) The zero-based ordinal of the image on the page.
+
+Page
+: (`page`) A reference to the current page.
+
+PageInner
+: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
+
+PlainText
+: (`string`) The image description as plain text.
+
+Text
+: (`template.HTML`) The image description.
+
+Title
+: (`string`) The image title.
+
+## Examples
+
+> [!note]
+> With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text.
+
+In its default configuration, Hugo renders Markdown images according to the [CommonMark specification]. To create a render hook that does the same thing:
+
+```go-html-template {file="layouts/_markup/render-image.html" copy=true}
+<img src="{{ .Destination | safeURL }}"
+ {{- with .PlainText }} alt="{{ . }}"{{ end -}}
+ {{- with .Title }} title="{{ . }}"{{ end -}}
+>
+{{- /* chomp trailing newline */ -}}
+```
+
+To render standalone images within `figure` elements:
+
+```go-html-template {file="layouts/_markup/render-image.html" copy=true}
+{{- if .IsBlock -}}
+ <figure>
+ <img src="{{ .Destination | safeURL }}"
+ {{- with .PlainText }} alt="{{ . }}"{{ end -}}
+ >
+ {{- with .Title }}<figcaption>{{ . }}</figcaption>{{ end -}}
+ </figure>
+{{- else -}}
+ <img src="{{ .Destination | safeURL }}"
+ {{- with .PlainText }} alt="{{ . }}"{{ end -}}
+ {{- with .Title }} title="{{ . }}"{{ end -}}
+ >
+{{- end -}}
+```
+
+Note that the above requires the following project configuration:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.parser]
+wrapStandAloneImageWithinParagraph = false
+{{< /code-toggle >}}
+
+## Embedded
+
+Hugo includes an [embedded image render hook] to resolve Markdown image destinations. You can adjust its behavior in your project configuration. This is the default setting:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.renderHooks.image]
+useEmbedded = 'auto'
+{{< /code-toggle >}}
+
+When set to `auto` as shown above, Hugo automatically uses the embedded image render hook for multilingual single-host projects, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such projects. If custom image render hooks are defined by your project, modules, or themes, these will be used instead.
+
+You can also configure Hugo to `always` use the embedded image render hook, use it only as a `fallback`, or `never` use it. See [details](/configuration/markup/#renderhooksimageuseembedded).
+
+The embedded image render hook resolves internal Markdown destinations by looking for a matching [page resource](g), falling back to a matching [global resource](g). Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination.
+
+You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your project configuration:
+
+{{< code-toggle file=hugo >}}
+[[module.mounts]]
+source = 'assets'
+target = 'assets'
+
+[[module.mounts]]
+source = 'static'
+target = 'assets'
+{{< /code-toggle >}}
+
+Note that the embedded image render hook does not perform image processing. Its sole purpose is to resolve Markdown image destinations.
+
+{{% include "/_common/render-hooks/pageinner.md" %}}
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes
+[CommonMark specification]: https://spec.commonmark.org/current/
+[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
+[embedded image render hook]: <{{% eturl render-image %}}>
+[Markdown attributes]: /content-management/markdown-attributes/
diff --git a/documents/markdown/hugo-docs/en_render-hooks_introduction.md b/documents/markdown/hugo-docs/en_render-hooks_introduction.md
new file mode 100755
index 0000000..aafebf3
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_render-hooks_introduction.md
@@ -0,0 +1,79 @@
+---
+title: Introduction
+description: An introduction to Hugo's render hooks.
+categories: []
+keywords: []
+weight: 10
+---
+
+When rendering Markdown to HTML, render hooks override the conversion. Each render hook is a template, with one template for each supported element type:
+
+- [Blockquotes](/render-hooks/blockquotes)
+- [Code blocks](/render-hooks/code-blocks)
+- [Headings](/render-hooks/headings)
+- [Images](/render-hooks/images)
+- [Links](/render-hooks/links)
+- [Passthrough elements](/render-hooks/passthrough)
+- [Tables](/render-hooks/tables)
+
+> [!note]
+> Hugo supports multiple [content formats] including Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, and reStructuredText.
+>
+> The render hook capability is limited to Markdown. You cannot create render hooks for the other content formats.
+
+For example, consider this Markdown:
+
+```text
+[Hugo](https://gohugo.io)
+
+
+```
+
+Without link or image render hooks, the example above is rendered to:
+
+```html
+<p><a href="https://gohugo.io">Hugo</a></p>
+<p><img alt="kitten" src="kitten.jpg"></p>
+```
+
+By creating link and image render hooks, you can alter the conversion from Markdown to HTML. For example:
+
+```html
+<p><a href="https://gohugo.io" rel="external">Hugo</a></p>
+<p><img alt="kitten" src="kitten.jpg" width="600" height="400"></p>
+```
+
+Each render hook is a template, with one template for each supported element type:
+
+```text
+layouts/
+ └── _markup/
+ ├── render-blockquote.html
+ ├── render-codeblock.html
+ ├── render-heading.html
+ ├── render-image.html
+ ├── render-link.html
+ ├── render-passthrough.html
+ └── render-table.html
+```
+
+The template lookup order allows you to create different render hooks for each page [type](g), [kind](g), language, and [output format](g). For example:
+
+```text
+layouts/
+├── _markup/
+│ ├── render-link.html
+│ └── render-link.rss.xml
+├── books/
+│ └── _markup/
+│ ├── render-link.html
+│ └── render-link.rss.xml
+└── films/
+ └── _markup/
+ ├── render-link.html
+ └── render-link.rss.xml
+```
+
+The remaining pages in this section describe each type of render hook, including examples and the context received by each template.
+
+[content formats]: /content-management/formats/
diff --git a/documents/markdown/hugo-docs/en_render-hooks_links.md b/documents/markdown/hugo-docs/en_render-hooks_links.md
new file mode 100755
index 0000000..7cd65bd
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_render-hooks_links.md
@@ -0,0 +1,104 @@
+---
+title: Link render hooks
+linkTitle: Links
+description: Create a link render hook to override the rendering of Markdown links to HTML.
+categories: []
+keywords: []
+---
+
+## Markdown
+
+A Markdown link has three components: the link text, the link destination, and optionally the link title.
+
+```text
+[Post 1](/posts/post-1 "My first post")
+ ------ ------------- -------------
+ text destination title
+```
+
+These components are passed into the render hook [context](g) as shown below.
+
+## Context
+
+Link _render hook_ templates receive the following context:
+
+Destination
+: (`string`) The link destination.
+
+Page
+: (`page`) A reference to the current page.
+
+PageInner
+: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
+
+PlainText
+: (`string`) The link description as plain text.
+
+Text
+: (`template.HTML`) The link description.
+
+Title
+: (`string`) The link title.
+
+## Examples
+
+> [!note]
+> With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text.
+
+In its default configuration, Hugo renders Markdown links according to the [CommonMark specification]. To create a render hook that does the same thing:
+
+```go-html-template {file="layouts/_markup/render-link.html" copy=true}
+<a href="{{ .Destination | safeURL }}"
+ {{- with .Title }} title="{{ . }}"{{ end -}}
+>
+ {{- with .Text }}{{ . }}{{ end -}}
+</a>
+{{- /* chomp trailing newline */ -}}
+```
+
+To include a `rel` attribute set to `external` for external links:
+
+```go-html-template {file="layouts/_markup/render-link.html" copy=true}
+{{- $u := urls.Parse .Destination -}}
+<a href="{{ .Destination | safeURL }}"
+ {{- with .Title }} title="{{ . }}"{{ end -}}
+ {{- if $u.IsAbs }} rel="external"{{ end -}}
+>
+ {{- with .Text }}{{ . }}{{ end -}}
+</a>
+{{- /* chomp trailing newline */ -}}
+```
+
+## Embedded
+
+Hugo includes an [embedded link render hook] to resolve Markdown link destinations. You can adjust its behavior in your project configuration. This is the default setting:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.renderHooks.link]
+useEmbedded = 'auto'
+{{< /code-toggle >}}
+
+When set to `auto` as shown above, Hugo automatically uses the embedded link render hook for multilingual single-host projects, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such projects. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
+
+You can also configure Hugo to `always` use the embedded link render hook, use it only as a `fallback`, or `never` use it. See [details](/configuration/markup/#renderhookslinkuseembedded).
+
+The embedded link render hook resolves internal Markdown destinations by looking for a matching page, falling back to a matching [page resource](g), then falling back to a matching [global resource](g). Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination.
+
+You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your project configuration:
+
+{{< code-toggle file=hugo >}}
+[[module.mounts]]
+source = 'assets'
+target = 'assets'
+
+[[module.mounts]]
+source = 'static'
+target = 'assets'
+{{< /code-toggle >}}
+
+{{% include "/_common/render-hooks/pageinner.md" %}}
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes
+[CommonMark specification]: https://spec.commonmark.org/current/
+[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
+[embedded link render hook]: <{{% eturl render-link %}}>
diff --git a/documents/markdown/hugo-docs/en_render-hooks_passthrough.md b/documents/markdown/hugo-docs/en_render-hooks_passthrough.md
new file mode 100755
index 0000000..7aada57
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_render-hooks_passthrough.md
@@ -0,0 +1,128 @@
+---
+title: Passthrough render hooks
+linkTitle: Passthrough
+description: Create passthrough render hook templates to override the rendering of text snippets captured by the Goldmark Passthrough extension.
+categories: []
+keywords: []
+---
+
+{{< new-in 0.132.0 />}}
+
+## Overview
+
+Hugo uses [Goldmark] to render Markdown to HTML. Goldmark supports custom extensions to extend its core functionality. The [Passthrough] extension captures and preserves raw Markdown within delimited snippets of text, including the delimiters themselves. These are known as _passthrough elements_.
+
+[Goldmark]: https://github.com/yuin/goldmark
+[Passthrough]: /configuration/markup/#passthrough
+
+Depending on your choice of delimiters, Hugo will classify a passthrough element as either _block_ or _inline_. Consider this contrived example:
+
+```text {file="content/example.md"}
+This is a
+
+\[block\]
+
+passthrough element with opening and closing block delimiters.
+
+This is an \(inline\) passthrough element with opening and closing inline delimiters.
+```
+
+Update your project configuration to enable the Passthrough extension and define opening and closing delimiters for each passthrough element type, either `block` or `inline`. For example:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.extensions.passthrough]
+enable = true
+[markup.goldmark.extensions.passthrough.delimiters]
+block = [['\[', '\]'], ['$$', '$$']]
+inline = [['\(', '\)']]
+{{< /code-toggle >}}
+
+In the example above there are two sets of `block` delimiters. You may use either one in your Markdown.
+
+The Passthrough extension is often used in conjunction with the MathJax or KaTeX display engine to render [mathematical expressions] written in the LaTeX markup language.
+
+[mathematical expressions]: /content-management/mathematics/
+
+To enable custom rendering of passthrough elements, create a passthrough render hook.
+
+## Context
+
+Passthrough _render hook_ templates receive the following [context](g):
+
+Attributes
+: (`map`) The [Markdown attributes], available if you configure your site as follows:
+
+ {{< code-toggle file=hugo >}}
+ [markup.goldmark.parser.attribute]
+ block = true
+ {{< /code-toggle >}}
+
+ Hugo populates the `Attributes` map for _block_ passthrough elements. Markdown attributes are not applicable to _inline_ elements.
+
+Inner
+: (`string`) The inner content of the passthrough element, excluding the delimiters.
+
+Ordinal
+: (`int`) The zero-based ordinal of the passthrough element on the page.
+
+Page
+: (`page`) A reference to the current page.
+
+PageInner
+: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
+
+Position
+: (`string`) The position of the passthrough element within the page content.
+
+Type
+: (`string`) The passthrough element type, either `block` or `inline`.
+
+[Markdown attributes]: /content-management/markdown-attributes/
+[`RenderShortcodes`]: /methods/page/rendershortcodes
+
+## Example
+
+Instead of client-side JavaScript rendering of mathematical markup using MathJax or KaTeX, create a passthrough render hook which calls the [`transform.ToMath`] function.
+
+[`transform.ToMath`]: /functions/transform/tomath/
+
+```go-html-template {file="layouts/_markup/render-passthrough.html" copy=true}
+{{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }}
+{{- with try (transform.ToMath .Inner $opts) }}
+ {{- with .Err }}
+ {{- errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }}
+ {{- else }}
+ {{- .Value }}
+ {{- $.Page.Store.Set "hasMath" true }}
+ {{- end }}
+{{- end -}}
+```
+
+Then, in your base template, conditionally include the KaTeX CSS within the head element:
+
+```go-html-template {file="layouts/baseof.html" copy=true}
+<head>
+ {{ $noop := .WordCount }}
+ {{ if .Page.Store.Get "hasMath" }}
+ <link
+ rel="stylesheet"
+ href="https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.css"
+ integrity="sha384-WcoG4HRXMzYzfCgiyfrySxx90XSl2rxY5mnVY5TwtWE6KLrArNKn0T/mOgNL0Mmi"
+ crossorigin="anonymous"
+ >
+ {{ end }}
+</head>
+```
+
+In the above, note the use of a [noop](g) statement to force content rendering before we check the value of `hasMath` with the `Store.Get` method.
+
+Although you can use one template with conditional logic as shown above, you can also create separate templates for each [`Type`](#type) of passthrough element:
+
+```text
+layouts/
+ └── _markup/
+ ├── render-passthrough-block.html
+ └── render-passthrough-inline.html
+```
+
+{{% include "/_common/render-hooks/pageinner.md" %}}
diff --git a/documents/markdown/hugo-docs/en_render-hooks_tables.md b/documents/markdown/hugo-docs/en_render-hooks_tables.md
new file mode 100755
index 0000000..852f67e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_render-hooks_tables.md
@@ -0,0 +1,100 @@
+---
+title: Table render hooks
+linkTitle: Tables
+description: Create table render hook templates to override the rendering of Markdown tables to HTML.
+categories: []
+keywords: []
+---
+
+{{< new-in 0.134.0 />}}
+
+## Context
+
+Table _render hook_ templates receive the following [context](g):
+
+Attributes
+: (`map`) The [Markdown attributes], available if you configure your site as follows:
+
+ {{< code-toggle file=hugo >}}
+ [markup.goldmark.parser.attribute]
+ block = true
+ {{< /code-toggle >}}
+
+Ordinal
+: (`int`) The zero-based ordinal of the table on the page.
+
+Page
+: (`page`) A reference to the current page.
+
+PageInner
+: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
+
+Position
+: (`string`) The position of the table within the page content.
+
+THead
+: (`slice`) A slice of table header rows, where each element is a slice of table cells.
+
+TBody
+: (`slice`) A slice of table body rows, where each element is a slice of table cells.
+
+[Markdown attributes]: /content-management/markdown-attributes/
+[`RenderShortcodes`]: /methods/page/rendershortcodes
+
+## Table cells
+
+Each table cell within the slice of slices returned by the `THead` and `TBody` methods has the following fields:
+
+Alignment
+: (`string`) The alignment of the text within the table cell, one of `left`, `center`, or `right`.
+
+Text
+: (`template.HTML`) The text within the table cell.
+
+## Example
+
+In its default configuration, Hugo renders Markdown tables according to the [GitHub Flavored Markdown specification]. To create a render hook that does the same thing:
+
+[GitHub Flavored Markdown specification]: https://github.github.com/gfm/#tables-extension-
+
+```go-html-template {file="layouts/_markup/render-table.html" copy=true}
+<table
+ {{- range $k, $v := .Attributes }}
+ {{- if $v }}
+ {{- printf " %s=%q" $k $v | safeHTMLAttr }}
+ {{- end }}
+ {{- end }}>
+ <thead>
+ {{- range .THead }}
+ <tr>
+ {{- range . }}
+ <th
+ {{- with .Alignment }}
+ {{- printf " style=%q" (printf "text-align: %s" .) | safeHTMLAttr }}
+ {{- end -}}
+ >
+ {{- .Text -}}
+ </th>
+ {{- end }}
+ </tr>
+ {{- end }}
+ </thead>
+ <tbody>
+ {{- range .TBody }}
+ <tr>
+ {{- range . }}
+ <td
+ {{- with .Alignment }}
+ {{- printf " style=%q" (printf "text-align: %s" .) | safeHTMLAttr }}
+ {{- end -}}
+ >
+ {{- .Text -}}
+ </td>
+ {{- end }}
+ </tr>
+ {{- end }}
+ </tbody>
+</table>
+```
+
+{{% include "/_common/render-hooks/pageinner.md" %}}
diff --git a/documents/markdown/hugo-docs/en_shortcodes__index.md b/documents/markdown/hugo-docs/en_shortcodes__index.md
new file mode 100644
index 0000000..826ee57
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_shortcodes__index.md
@@ -0,0 +1,7 @@
+---
+title: Shortcodes
+description: Insert elements such as videos, images, and social media embeds into your content using Hugo's embedded shortcodes.
+categories: []
+keywords: []
+weight: 10
+---
diff --git a/documents/markdown/hugo-docs/en_shortcodes_details.md b/documents/markdown/hugo-docs/en_shortcodes_details.md
new file mode 100755
index 0000000..5df6c11
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_shortcodes_details.md
@@ -0,0 +1,74 @@
+---
+title: Details shortcode
+linkTitle: Details
+description: Insert an HTML details element into your content using the details shortcode.
+categories: []
+keywords: []
+---
+
+{{< new-in 0.140.0 />}}
+
+> [!note]
+> To override Hugo's embedded `details` shortcode, copy the [source code] to a file with the same name in the `layouts/_shortcodes` directory.
+
+## Example
+
+With this markup:
+
+```text
+{{</* details summary="See the details" */>}}
+This is a **bold** word.
+{{</* /details */>}}
+```
+
+Hugo renders this HTML:
+
+```html
+<details>
+ <summary>See the details</summary>
+ <p>This is a <strong>bold</strong> word.</p>
+</details>
+```
+
+Which looks like this in your browser:
+
+{{< details summary="See the details" >}}
+This is a **bold** word.
+{{< /details >}}
+
+## Arguments
+
+summary
+: (`string`) The content of the child `summary` element rendered from Markdown to HTML. Default is `Details`.
+
+open
+: (`bool`) Whether to initially display the content of the `details` element. Default is `false`.
+
+class
+: (`string`) The `class` attribute of the `details` element.
+
+name
+: (`string`) The `name` attribute of the `details` element.
+
+title
+: (`string`) The `title` attribute of the `details` element.
+
+## Styling
+
+Use CSS to style the `details` element, the `summary` element, and the content itself.
+
+```css
+/* target the details element */
+details { }
+
+/* target the summary element */
+details > summary { }
+
+/* target the children of the summary element */
+details > summary > * { }
+
+/* target the content */
+details > :not(summary) { }
+```
+
+[source code]: <{{% eturl details %}}>
diff --git a/documents/markdown/hugo-docs/en_shortcodes_figure.md b/documents/markdown/hugo-docs/en_shortcodes_figure.md
new file mode 100755
index 0000000..42438f7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_shortcodes_figure.md
@@ -0,0 +1,109 @@
+---
+title: Figure shortcode
+linkTitle: Figure
+description: Insert an HTML figure element into your content using the figure shortcode.
+categories: []
+keywords: []
+---
+
+> [!note]
+> To override Hugo's embedded `figure` shortcode, copy the [source code] to a file with the same name in the `layouts/_shortcodes` directory.
+
+## Example
+
+With this markup:
+
+```text
+{{</* figure
+ src="/images/examples/zion-national-park.jpg"
+ alt="A photograph of Zion National Park"
+ link="https://www.nps.gov/zion/index.htm"
+ caption="Zion National Park"
+ class="ma0 w-75"
+*/>}}
+```
+
+Hugo renders this HTML:
+
+```html
+<figure class="ma0 w-75">
+ <a href="https://www.nps.gov/zion/index.htm">
+ <img
+ src="/images/examples/zion-national-park.jpg"
+ alt="A photograph of Zion National Park"
+ >
+ </a>
+ <figcaption>
+ <p>Zion National Park</p>
+ </figcaption>
+</figure>
+```
+
+Which looks like this in your browser:
+
+{{< figure
+ src="/images/examples/zion-national-park.jpg"
+ alt="A photograph of Zion National Park"
+ link="https://www.nps.gov/zion/index.htm"
+ caption="Zion National Park"
+ class="ma0 w-75"
+>}}
+
+## Arguments
+
+src
+: (`string`) The `src` attribute of the `img` element. Typically this is a [page resource](g) or a [global resource](g).
+
+alt
+: (`string`) The `alt` attribute of the `img` element.
+
+width
+: (`int`) The `width` attribute of the `img` element.
+
+height
+: (`int`) The `height` attribute of the `img` element.
+
+loading
+: (`string`) The `loading` attribute of the `img` element.
+
+class
+: (`string`) The `class` attribute of the `figure` element.
+
+link
+: (`string`) The `href` attribute of the anchor element that wraps the `img` element.
+
+target
+: (`string`) The `target` attribute of the anchor element that wraps the `img` element.
+
+rel
+: (`rel`) The `rel` attribute of the anchor element that wraps the `img` element.
+
+title
+: (`string`) Within the `figurecaption` element, the title is at the top, wrapped within an `h4` element.
+
+caption
+: (`string`) Within the `figurecaption` element, the caption is at the bottom and may contain plain text or markdown.
+
+attr
+: (`string`) Within the `figurecaption` element, the attribution appears next to the caption and may contain plain text or markdown.
+
+attrlink
+: (`string`) The `href` attribute of the anchor element that wraps the attribution.
+
+## Image location
+
+The `figure` shortcode resolves internal Markdown destinations by looking for a matching [page resource](g), falling back to a matching [global resource](g). Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination.
+
+You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your project configuration:
+
+{{< code-toggle file=hugo >}}
+[[module.mounts]]
+source = 'assets'
+target = 'assets'
+
+[[module.mounts]]
+source = 'static'
+target = 'assets'
+{{< /code-toggle >}}
+
+[source code]: <{{% eturl figure %}}>
diff --git a/documents/markdown/hugo-docs/en_shortcodes_highlight.md b/documents/markdown/hugo-docs/en_shortcodes_highlight.md
new file mode 100755
index 0000000..d427da7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_shortcodes_highlight.md
@@ -0,0 +1,107 @@
+---
+title: Highlight shortcode
+linkTitle: Highlight
+description: Insert syntax-highlighted code into your content using the highlight shortcode.
+categories: []
+keywords: [highlight]
+---
+
+> [!note]
+> To override Hugo's embedded `highlight` shortcode, copy the [source code] to a file with the same name in the `layouts/_shortcodes` directory.
+
+> [!note]
+> With the Markdown [content format], the `highlight` shortcode is rarely needed because, by default, Hugo automatically applies syntax highlighting to fenced code blocks.
+>
+> The primary use case for the `highlight` shortcode in Markdown is to apply syntax highlighting to inline code snippets.
+
+The `highlight` shortcode calls the [`transform.Highlight`] function which uses the [Chroma] syntax highlighter, supporting over 200 languages with more than 40 [highlighting styles].
+
+## Arguments
+
+The `highlight` shortcode takes three arguments.
+
+```text
+{{</* highlight LANG OPTIONS */>}}
+CODE
+{{</* /highlight */>}}
+```
+
+CODE
+: (`string`) The code to highlight.
+
+LANG
+: (`string`) The language of the code to highlight. Choose from one of the [supported languages]. This value is case-insensitive.
+
+OPTIONS
+: (`string`) Zero or more space-separated key-value pairs wrapped in quotation marks. Set default values for each option in your [project configuration]. The key names are case-insensitive.
+
+## Example
+
+```text
+{{</* highlight go "linenos=inline, hl_lines=3 6-8, style=emacs" */>}}
+package main
+
+import "fmt"
+
+func main() {
+ for i := 0; i < 3; i++ {
+ fmt.Println("Value of i:", i)
+ }
+}
+{{</* /highlight */>}}
+```
+
+Hugo renders this to:
+
+{{< highlight go "linenos=inline, hl_Lines=3 6-8, noClasses=true" >}}
+package main
+
+import "fmt"
+
+func main() {
+ for i := 0; i < 3; i++ {
+ fmt.Println("Value of i:", i)
+ }
+}
+{{< /highlight >}}
+
+You can also use the `highlight` shortcode for inline code snippets:
+
+```text
+This is some {{</* highlight go "hl_inline=true" */>}}fmt.Println("inline"){{</* /highlight */>}} code.
+```
+
+Hugo renders this to:
+
+This is some {{< highlight go "hl_inline=true, noClasses=true" >}}fmt.Println("inline"){{< /highlight >}} code.
+
+Given the verbosity of the example above, if you need to frequently highlight inline code snippets, create your own shortcode using a shorter name with preset options.
+
+```go-html-template {file="layouts/_shortcodes/hl.html"}
+{{ $code := .Inner | strings.TrimSpace }}
+{{ $lang := or (.Get 0) "go" }}
+{{ $opts := dict "hl_inline" true "noClasses" true }}
+{{ transform.Highlight $code $lang $opts }}
+```
+
+```text
+This is some {{</* hl */>}}fmt.Println("inline"){{</* /hl */>}} code.
+```
+
+Hugo renders this to:
+
+This is some {{< hl >}}fmt.Println("inline"){{< /hl >}} code.
+
+## Options
+
+Pass the options when calling the shortcode. You can set their default values in your [project configuration].
+
+{{% include "_common/syntax-highlighting-options.md" %}}
+
+[`transform.Highlight`]: /functions/transform/highlight/
+[Chroma]: https://github.com/alecthomas/chroma
+[content format]: /content-management/formats/
+[highlighting styles]: /quick-reference/syntax-highlighting-styles/
+[project configuration]: /configuration/markup/#highlight
+[source code]: <{{% eturl highlight %}}>
+[supported languages]: /content-management/syntax-highlighting/#languages
diff --git a/documents/markdown/hugo-docs/en_shortcodes_instagram.md b/documents/markdown/hugo-docs/en_shortcodes_instagram.md
new file mode 100755
index 0000000..f3223e7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_shortcodes_instagram.md
@@ -0,0 +1,42 @@
+---
+title: Instagram shortcode
+linkTitle: Instagram
+description: Embed an Instagram post in your content using the instagram shortcode.
+categories: []
+keywords: []
+---
+
+> [!note]
+> To override Hugo's embedded `instagram` shortcode, copy the [source code] to a file with the same name in the `layouts/_shortcodes` directory.
+
+## Example
+
+To display an Instagram post with this URL:
+
+```text
+https://www.instagram.com/p/CxOWiQNP2MO/
+```
+
+Include this in your Markdown:
+
+```text
+{{</* instagram CxOWiQNP2MO */>}}
+```
+
+Huge renders this to:
+
+{{< instagram CxOWiQNP2MO >}}
+
+## Privacy
+
+Adjust the relevant privacy settings in your project configuration.
+
+{{< code-toggle config=privacy.instagram />}}
+
+disable
+: (`bool`) Whether to disable the shortcode. Default is `false`.
+
+simple
+: (`bool`) Whether to enable simple mode for image card generation. If `true`, Hugo creates a static card without JavaScript. This mode only supports image cards, and the image is fetched directly from Instagram's servers. Default is `false`.
+
+[source code]: <{{% eturl instagram %}}>
diff --git a/documents/markdown/hugo-docs/en_shortcodes_param.md b/documents/markdown/hugo-docs/en_shortcodes_param.md
new file mode 100755
index 0000000..51310a2
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_shortcodes_param.md
@@ -0,0 +1,38 @@
+---
+title: Param shortcode
+linkTitle: Param
+description: Insert a parameter from front matter or your project configuration into your content using the param shortcode.
+categories: []
+keywords: []
+---
+
+> [!note]
+> To override Hugo's embedded `param` shortcode, copy the [source code] to a file with the same name in the `layouts/_shortcodes` directory.
+
+The `param` shortcode renders a parameter from front matter, falling back to a site parameter of the same name. The shortcode throws an error if the parameter does not exist.
+
+```text {file="content/example.md"}
+---
+title: Example
+date: 2025-01-15T23:29:46-08:00
+params:
+ color: red
+ size: medium
+---
+
+We found a {{%/* param "color" */%}} shirt.
+```
+
+Hugo renders this to:
+
+```html
+<p>We found a red shirt.</p>
+```
+
+Access nested values by [chaining](g) the [identifiers](g):
+
+```text
+{{%/* param my.nested.param */%}}
+```
+
+[source code]: <{{% eturl param %}}>
diff --git a/documents/markdown/hugo-docs/en_shortcodes_qr.md b/documents/markdown/hugo-docs/en_shortcodes_qr.md
new file mode 100755
index 0000000..d83be2a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_shortcodes_qr.md
@@ -0,0 +1,107 @@
+---
+title: QR shortcode
+linkTitle: QR
+description: Insert a QR code into your content using the qr shortcode.
+categories: []
+keywords: []
+---
+
+{{< new-in 0.141.0 />}}
+
+> [!note]
+> To override Hugo's embedded `qr` shortcode, copy the [source code] to a file with the same name in the `layouts/_shortcodes` directory.
+
+The `qr` shortcode encodes the given text into a [QR code] using the specified options and renders the resulting image.
+
+Internally this shortcode calls the `images.QR` function. Please read the [related documentation] for implementation details and guidance.
+
+## Examples
+
+Use the self-closing syntax to pass the text as an argument:
+
+```text
+{{</* qr text="https://gohugo.io" /*/>}}
+```
+
+Or insert the text between the opening and closing tags:
+
+```text
+{{</* qr */>}}
+https://gohugo.io
+{{</* /qr */>}}
+```
+
+Both of the above produce this image:
+
+{{< qr text="https://gohugo.io" class="qrcode" targetDir="images/qr" />}}
+
+To create a QR code for a phone number:
+
+```text
+{{</* qr text="tel:+12065550101" /*/>}}
+```
+
+{{< qr text="tel:+12065550101" class="qrcode" targetDir="images/qr" />}}
+
+To create a QR code containing contact information in the [vCard] format:
+
+```text
+{{</* qr level="low" scale=2 alt="QR code of vCard for John Smith" */>}}
+BEGIN:VCARD
+VERSION:2.1
+N;CHARSET=UTF-8:Smith;John;R.;Dr.;PhD
+FN;CHARSET=UTF-8:Dr. John R. Smith, PhD.
+ORG;CHARSET=UTF-8:ABC Widgets
+TITLE;CHARSET=UTF-8:Vice President Engineering
+TEL;TYPE=WORK:+12065550101
+EMAIL;TYPE=WORK:jsmith@example.org
+END:VCARD
+{{</* /qr */>}}
+```
+
+{{< qr level="low" scale=2 alt="QR code of vCard for John Smith" class="qrcode" targetDir="images/qr" >}}
+BEGIN:VCARD
+VERSION:2.1
+N;CHARSET=UTF-8:Smith;John;R.;Dr.;PhD
+FN;CHARSET=UTF-8:Dr. John R. Smith, PhD.
+ORG;CHARSET=UTF-8:ABC Widgets
+TITLE;CHARSET=UTF-8:Vice President Engineering
+TEL;TYPE=WORK:+12065550101
+EMAIL;TYPE=WORK:jsmith@example.org
+END:VCARD
+{{< /qr >}}
+
+## Arguments
+
+text
+: (`string`) The text to encode, falling back to the text between the opening and closing shortcode tags.
+
+level
+: (`string`) The error correction level to use when encoding the text, one of `low`, `medium`, `quartile`, or `high`. Default is `medium`.
+
+scale
+: (`int`) The number of image pixels per QR code module. Must be greater than or equal to 2. Default is `4`.
+
+targetDir
+: (`string`) The subdirectory within the [`publishDir`] where Hugo will place the generated image.
+
+alt
+: (`string`) The `alt` attribute of the `img` element.
+
+class
+: (`string`) The `class` attribute of the `img` element.
+
+id
+: (`string`) The `id` attribute of the `img` element.
+
+loading
+: (`string`) The `loading` attribute of the `img` element, either `eager` or `lazy`.
+
+title
+: (`string`) The `title` attribute of the `img` element.
+
+[`publishDir`]: /configuration/all/#publishdir
+[QR code]: https://en.wikipedia.org/wiki/QR_code
+[related documentation]: /functions/images/qr/
+[source code]: <{{% eturl qr %}}>
+[vCard]: <https://en.wikipedia.org/wiki/VCard>
diff --git a/documents/markdown/hugo-docs/en_shortcodes_ref.md b/documents/markdown/hugo-docs/en_shortcodes_ref.md
new file mode 100755
index 0000000..29c4b0b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_shortcodes_ref.md
@@ -0,0 +1,65 @@
+---
+title: Ref shortcode
+linkTitle: Ref
+description: Insert a permalink to the given page reference using the ref shortcode.
+categories: []
+keywords: []
+---
+
+> [!note]
+> To override Hugo's embedded `ref` shortcode, copy the [source code] to a file with the same name in the `layouts/_shortcodes` directory.
+
+> [!note]
+> When working with Markdown this shortcode is obsolete. Instead, to properly resolve Markdown link destinations, use the [embedded link render hook] or create your own.
+>
+> In its default configuration, Hugo automatically uses the embedded link render hook for multilingual single-host projects, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such projects. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
+>
+> You can also configure Hugo to `always` use the embedded link render hook, use it only as a `fallback`, or `never` use it. See [details](/configuration/markup/#renderhookslinkuseembedded).
+
+## Usage
+
+The `ref` shortcode accepts either a single positional argument (the path) or one or more named arguments, as listed below.
+
+## Arguments
+
+{{% include "_common/ref-and-relref-options.md" %}}
+
+## Examples
+
+The `ref` shortcode typically provides the destination for a Markdown link.
+
+> [!note]
+> Always use [Markdown notation] notation when calling this shortcode.
+
+The following examples show the rendered output for a page on the English version of the site:
+
+```md
+[Link A]({{%/* ref "/books/book-1" */%}})
+
+[Link B]({{%/* ref path="/books/book-1" */%}})
+
+[Link C]({{%/* ref path="/books/book-1" lang="de" */%}})
+
+[Link D]({{%/* ref path="/books/book-1" lang="de" outputFormat="json" */%}})
+```
+
+Rendered:
+
+```html
+<a href="https://example.org/en/books/book-1/">Link A</a>
+
+<a href="https://example.org/en/books/book-1/">Link B</a>
+
+<a href="https://example.org/de/books/book-1/">Link C</a>
+
+<a href="https://example.org/de/books/book-1/index.json">Link D</a>
+```
+
+## Error handling
+
+{{% include "_common/ref-and-relref-error-handling.md" %}}
+
+[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
+[embedded link render hook]: /render-hooks/links/#embedded
+[Markdown notation]: /content-management/shortcodes/#notation
+[source code]: <{{% eturl relref %}}>
diff --git a/documents/markdown/hugo-docs/en_shortcodes_relref.md b/documents/markdown/hugo-docs/en_shortcodes_relref.md
new file mode 100755
index 0000000..1045ee9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_shortcodes_relref.md
@@ -0,0 +1,65 @@
+---
+title: Relref shortcode
+linkTitle: Relref
+description: Insert a relative permalink to the given page reference using the relref shortcode.
+categories: []
+keywords: []
+---
+
+> [!note]
+> To override Hugo's embedded `relref` shortcode, copy the [source code] to a file with the same name in the `layouts/_shortcodes` directory.
+
+> [!note]
+> When working with Markdown this shortcode is obsolete. Instead, to properly resolve Markdown link destinations, use the [embedded link render hook] or create your own.
+>
+> In its default configuration, Hugo automatically uses the embedded link render hook for multilingual single-host projects, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such projects. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
+>
+> You can also configure Hugo to `always` use the embedded link render hook, use it only as a `fallback`, or `never` use it. See [details](/configuration/markup/#renderhookslinkuseembedded).
+
+## Usage
+
+The `relref` shortcode accepts either a single positional argument (the path) or one or more named arguments, as listed below.
+
+## Arguments
+
+{{% include "_common/ref-and-relref-options.md" %}}
+
+## Examples
+
+The `relref` shortcode typically provides the destination for a Markdown link.
+
+> [!note]
+> Always use [Markdown notation] notation when calling this shortcode.
+
+The following examples show the rendered output for a page on the English version of the site:
+
+```md
+[Link A]({{%/* relref "/books/book-1" */%}})
+
+[Link B]({{%/* relref path="/books/book-1" */%}})
+
+[Link C]({{%/* relref path="/books/book-1" lang="de" */%}})
+
+[Link D]({{%/* relref path="/books/book-1" lang="de" outputFormat="json" */%}})
+```
+
+Rendered:
+
+```html
+<a href="/en/books/book-1/">Link A</a>
+
+<a href="/en/books/book-1/">Link B</a>
+
+<a href="/de/books/book-1/">Link C</a>
+
+<a href="/de/books/book-1/index.json">Link D</a>
+```
+
+## Error handling
+
+{{% include "_common/ref-and-relref-error-handling.md" %}}
+
+[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
+[embedded link render hook]: /render-hooks/links/#embedded
+[Markdown notation]: /content-management/shortcodes/#notation
+[source code]: <{{% eturl relref %}}>
diff --git a/documents/markdown/hugo-docs/en_shortcodes_vimeo.md b/documents/markdown/hugo-docs/en_shortcodes_vimeo.md
new file mode 100755
index 0000000..7bca4b8
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_shortcodes_vimeo.md
@@ -0,0 +1,73 @@
+---
+title: Vimeo shortcode
+linkTitle: Vimeo
+description: Embed a Vimeo video in your content using the vimeo shortcode.
+categories: []
+keywords: []
+---
+
+> [!note]
+> To override Hugo's embedded `vimeo` shortcode, copy the [source code] to a file with the same name in the `layouts/_shortcodes` directory.
+
+## Example
+
+To display a Vimeo video with this URL:
+
+```text
+https://vimeo.com/19899678
+```
+
+Include this in your Markdown:
+
+```text
+{{</* vimeo 19899678 */>}}
+```
+
+Hugo renders this to:
+
+{{< vimeo 19899678 >}}
+
+## Arguments
+
+id
+: (string) The video `id`. Optional if the `id` is the first and only positional argument.
+
+allowFullScreen
+: {{< new-in 0.146.0 />}}
+: (`bool`) Whether the `iframe` element can activate full screen mode. Default is `true`.
+
+class
+: (`string`) The `class` attribute of the wrapping `div` element. Adding one or more CSS classes disables inline styling.
+
+loading
+: {{< new-in 0.146.0 />}}
+: (`string`) The loading attribute of the `iframe` element, either `eager` or `lazy`. Default is `eager`.
+
+title
+: (`string`) The `title` attribute of the `iframe` element.
+
+Here's an example using some of the available arguments:
+
+```text
+{{</* vimeo id=19899678 allowFullScreen=false loading=lazy */>}}
+```
+
+## Privacy
+
+Adjust the relevant privacy settings in your project configuration.
+
+{{< code-toggle config=privacy.vimeo />}}
+
+disable
+: (`bool`) Whether to disable the shortcode. Default is `false`.
+
+enableDNT
+: (`bool`) Whether to block the Vimeo player from tracking session data and analytics. Default is `false`.
+
+simple
+: (`bool`) Whether to enable simple mode. If `true`, the video thumbnail is fetched from Vimeo and overlaid with a play button. Clicking the thumbnail opens the video in a new Vimeo tab. Default is `false`.
+
+The source code for the simple version of the shortcode is available [in this file].
+
+[in this file]: <{{% eturl vimeo_simple %}}>
+[source code]: <{{% eturl vimeo %}}>
diff --git a/documents/markdown/hugo-docs/en_shortcodes_x.md b/documents/markdown/hugo-docs/en_shortcodes_x.md
new file mode 100755
index 0000000..1ca8794
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_shortcodes_x.md
@@ -0,0 +1,54 @@
+---
+title: X shortcode
+linkTitle: X
+description: Embed an X post in your content using the x shortcode.
+categories: []
+keywords: []
+---
+
+{{< new-in 0.141.0 />}}
+
+> [!note]
+> To override Hugo's embedded `x` shortcode, copy the [source code] to a file with the same name in the `layouts/_shortcodes` directory.
+
+## Example
+
+To display an X post with this URL:
+
+```txt
+https://x.com/SanDiegoZoo/status/1453110110599868418
+```
+
+Include this in your Markdown:
+
+```text
+{{</* x user="SanDiegoZoo" id="1453110110599868418" */>}}
+```
+
+Rendered:
+
+{{< x user="SanDiegoZoo" id="1453110110599868418" >}}
+
+## Privacy
+
+Adjust the relevant privacy settings in your project configuration.
+
+{{< code-toggle config=privacy.x />}}
+
+disable
+: (`bool`) Whether to disable the shortcode. Default is `false`.
+
+enableDNT
+: (`bool`) Whether to prevent X from using post and embedded page data for personalized suggestions and ads. Default is `false`.
+
+simple
+: (`bool`) Whether to enable simple mode. If `true`, Hugo builds a static version of the of the post without JavaScript. Default is `false`.
+
+The source code for the simple version of the shortcode is available [in this file].
+
+If you enable simple mode you may want to disable the hardcoded inline styles by setting `disableInlineCSS` to `true` in your project configuration. The default value for this setting is `false`.
+
+{{< code-toggle config=services.x />}}
+
+[in this file]: <{{% eturl x_simple %}}>
+[source code]: <{{% eturl x %}}>
diff --git a/documents/markdown/hugo-docs/en_shortcodes_youtube.md b/documents/markdown/hugo-docs/en_shortcodes_youtube.md
new file mode 100755
index 0000000..c76c5f3
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_shortcodes_youtube.md
@@ -0,0 +1,83 @@
+---
+title: YouTube shortcode
+linkTitle: YouTube
+description: Embed a YouTube video in your content using the youtube shortcode.
+categories: []
+keywords: []
+---
+
+> [!note]
+> To override Hugo's embedded `youtube` shortcode, copy the [source code] to a file with the same name in the `layouts/_shortcodes` directory.
+
+## Example
+
+To display a YouTube video with this URL:
+
+```text
+https://www.youtube.com/watch?v=0RKpf3rK57I
+```
+
+Include this in your Markdown:
+
+```texts
+{{</* youtube 0RKpf3rK57I */>}}
+```
+
+Hugo renders this to:
+
+{{< youtube 0RKpf3rK57I >}}
+
+## Arguments
+
+id
+: (`string`) The video `id`. Optional if the `id` is the first and only positional argument.
+
+allowFullScreen
+: (`bool`) Whether the `iframe` element can activate full screen mode. Default is `true`.
+
+autoplay
+: (`bool`) Whether to automatically play the video. Forces `mute` to `true`. Default is `false`.
+
+class
+: (`string`) The `class` attribute of the wrapping `div` element. When specified, removes the `style` attributes from the `iframe` element and its wrapping `div` element.
+
+controls
+: (`bool`) Whether to display the video controls. Default is `true`.
+
+end
+: (`int`) The time, measured in seconds from the start of the video, when the player should stop playing the video.
+
+loading
+: (`string`) The loading attribute of the `iframe` element, either `eager` or `lazy`. Default is `eager`.
+
+loop
+: (`bool`) Whether to indefinitely repeat the video. Ignores the `start` and `end` arguments after the first play. Default is `false`.
+
+mute
+: (`bool`) Whether to mute the video. Always `true` when `autoplay` is `true`. Default is `false`.
+
+start
+: (`int`) The time, measured in seconds from the start of the video, when the player should start playing the video.
+
+title
+: (`string`) The `title` attribute of the `iframe` element. Defaults to "YouTube video".
+
+Here's an example using some of the available arguments:
+
+```text
+{{</* youtube id=0RKpf3rK57I start=30 end=60 loading=lazy */>}}
+```
+
+## Privacy
+
+Adjust the relevant privacy settings in your project configuration.
+
+{{< code-toggle config=privacy.youTube />}}
+
+disable
+: (`bool`) Whether to disable the shortcode. Default is `false`.
+
+privacyEnhanced
+: (`bool`) Whether to block YouTube from storing information about visitors on your website unless the user plays the embedded video. Default is `false`.
+
+[source code]: {{% eturl youtube %}}
diff --git a/documents/markdown/hugo-docs/en_showcase_1password-support_bio.md b/documents/markdown/hugo-docs/en_showcase_1password-support_bio.md
new file mode 100644
index 0000000..32d299b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_1password-support_bio.md
@@ -0,0 +1,3 @@
+**1Password** is a password manager that keeps you safe online. It protects your secure information behind the one password only you know.
+
+The [1Password Support](https://support.1password.com/) website was built from scratch with **Hugo** and enhanced with **React** and **Elasticsearch** to give us the best of both worlds: The simplicity and performance of a static site, with the richness of a hosted web app.
diff --git a/documents/markdown/hugo-docs/en_showcase_1password-support_index.md b/documents/markdown/hugo-docs/en_showcase_1password-support_index.md
new file mode 100644
index 0000000..b75e54e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_1password-support_index.md
@@ -0,0 +1,37 @@
+---
+title: 1Password Support
+date: 2018-02-22
+description: 'Showcase: "Compiles 400 pages in five languages in the blink of an eye."'
+siteURL: https://support.1password.com/
+byline: "[Mitch Cohen](https://github.com/mitchchn), Documentation Team Lead"
+aliases: [/showcase/1password/]
+---
+
+At 1Password, we used to go through a different documentation platform every month: blog engines, ebooks, wikis, site generators written in Ruby and JavaScript. Each was inadequate in its own special way. Then we found **Hugo**. We made one last switch, and we're glad we did.
+
+## Not all static site generators are created equal
+
+Finding a tool that will make your customers, writers, designers, _and_ DevOps team happy is no easy task, but we managed it with Hugo:
+
+**Hugo is static**. We're a security company, so we swear by static sites and use them wherever possible. We feel much safer pointing customers at HTML files than at a complicated server which needs to be hardened.
+
+**Hugo is Go**. We love the Go programming language at 1Password, and we were delighted to learn that Hugo used the same Go template syntax that our designers and front-end developers had already mastered.
+
+**Hugo is FAST**. Our previous static site generator took nearly a minute to compile our (then much smaller) site. Developers might be used to this, but it wasn't cutting it for writers who wanted to see live previews of their work. Hugo did the same job in milliseconds, and to this day compiles 400 pages in five languages in the blink of an eye.
+
+**Hugo is flexible**. Thanks to Hugo's content and layout system, we were able to preserve our existing file and directory structure and port our entire production site in a few days. We could then create new content types that weren't possible before, like these snazzy [showcases](https://support.1password.com/explore/extension/).
+
+**Hugo is great for writers**. Our documentation team was already comfortable with Markdown and Git and could start creating content for Hugo with zero downtime. Once we added shortcodes, our writers were able to dress up articles with features like [platform boxes](https://support.1password.com/get-the-apps/) with just a bit of new syntax.
+
+**Hugo has an amazing developer community**. Hugo updates are frequent and filled to the brim with features and fixes. As we developed the multilingual version of our site, we submitted PRs for features we needed and were helped through the process by [@bep](https://github.com/bep) and others.
+
+**Hugo is simple to deploy**. Hugo has just the right amount of configuration options to fit into our build system without being too complicated.
+
+### Tech specs
+
+- [1Password Support](https://support.1password.com) uses Hugo with a custom theme. It shares styles and some template code with [1Password.com](https://1password.com), which we also moved to Hugo in 2016.
+- Code and articles live in a private GitHub repository, which is deployed to a static content server using Git hooks.
+- Writers build and preview the site on their computers and contribute content using pull requests.
+- We use Hugo's [multilingual support](/content-management/multilingual/) to build the site in English, Spanish, French, Italian, German, and Russian. With the help of Hugo, 1Password Support became our very first site in multiple languages.
+- Our [contact form](https://support.1password.com/contact) is a single-page React app. We were able to integrate it with Hugo seamlessly thanks to its support for static files.
+- The one part of the support site which is not static is our search engine, which we developed with Elasticsearch and host on AWS.
diff --git a/documents/markdown/hugo-docs/en_showcase__template_bio.md b/documents/markdown/hugo-docs/en_showcase__template_bio.md
new file mode 100644
index 0000000..5ea3896
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase__template_bio.md
@@ -0,0 +1,6 @@
+Add some **general info** about Myshowcase here.
+
+The site is built by:
+
+- [Person 1](https://example.org)
+- [Person 1](https://example.org)
diff --git a/documents/markdown/hugo-docs/en_showcase__template_index.md b/documents/markdown/hugo-docs/en_showcase__template_index.md
new file mode 100644
index 0000000..6a11596
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase__template_index.md
@@ -0,0 +1,31 @@
+---
+title: Myshowcase
+date:
+draft: true
+description: A short description of this page.
+# The URL to the site on the internet.
+siteURL: https://gohugo.io/
+# Link to the site's Hugo source code if public and you can/want to share.
+# Remove or leave blank if not needed/wanted.
+siteSource: https://github.com/gohugoio/hugoDocs
+# Add credit to the article author. Leave blank or remove if not needed/wanted.
+byline: '[bep](https://github.com/bep), Hugo Lead'
+---
+
+To complete this showcase:
+
+1. Write the story about your site in this file.
+1. Add a summary to the `bio.md` file in this directory.
+1. Replace the `featured-template.png` with a screenshot of your site. You can rename it, but it must contain the word `featured`.
+1. Create a new pull request in <https://github.com/gohugoio/hugoDocs/pulls>
+
+The content of this bundle explained:
+
+index.md
+: The main content file. Fill in required front matter metadata and write your story. I does not have to be a novel. It can even be self-promotional, but it should include Hugo in some form.
+
+bio.md
+: A short summary of the website. Site credits (who built it) fits nicely here.
+
+featured.png
+: A reasonably sized screenshot of your website. It can be named anything, but the name must start with "featured". The sample image is `1500x750` (2:1 aspect ratio).
diff --git a/documents/markdown/hugo-docs/en_showcase_alora-labs_bio.md b/documents/markdown/hugo-docs/en_showcase_alora-labs_bio.md
new file mode 100644
index 0000000..f14a90b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_alora-labs_bio.md
@@ -0,0 +1,3 @@
+**Alora Labs** is a product development consultancy headquartered in Toronto, Canada.
+
+We help companies build software and IoT products and were recently recognized as one of the [**top IoT development firms**](https://aloralabs.com/insights/alora-labs-receives-clutch-2021-top-iot-agency-award) in Toronto.
diff --git a/documents/markdown/hugo-docs/en_showcase_alora-labs_index.md b/documents/markdown/hugo-docs/en_showcase_alora-labs_index.md
new file mode 100644
index 0000000..5e676ba
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_alora-labs_index.md
@@ -0,0 +1,18 @@
+---
+title: Alora Labs
+date: 2021-05-27
+description: 'Showcase: "Making performant websites accessible for everyone."'
+siteURL: https://aloralabs.com/
+siteSource: https://github.com/aloralabs/homepage
+aliases: [/showcase/aloralabs/]
+---
+
+At Alora Labs we always have an eye open for new tools and technology that we can utilize to the benefit of our customers or internal projects like our website.
+
+The previous iteration of our site was built with Jekyll, which served us well at first. However as time went on, we became frustrated with the number of dependencies we had to rely on, that would often break at the most inconvenient times.
+
+Hugo was a breath of fresh air in this regard, a single binary that works equally well on Windows as it did on macOS or Linux. We no longer need additional tools for image optimization, Sass compilation or JavaScript bundling. Everything just works, and with a substantial performance boost too.
+
+Hugo has become a favorite tool in the tool belt and the foundation for many client projects. We couldn't be happier with the switch and we are optimistic about recommending Hugo for many years to come.
+
+Thank you to the vibrant community and talented development team for all the hard work in making Hugo a success. As excellent as Hugo is now, we cannot wait to see what the release notes have in store for us next.
diff --git a/documents/markdown/hugo-docs/en_showcase_ampio-help_bio.md b/documents/markdown/hugo-docs/en_showcase_ampio-help_bio.md
new file mode 100644
index 0000000..bc0a9a9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_ampio-help_bio.md
@@ -0,0 +1,10 @@
+We are Ampio. We design and manufacture a building automation system that provides control, comfort, safety and reliability. Visit [our page](http://ampio.com/) to learn more about our solution!
+
+Ampio Knowledge Base is a service built and maintained with Hugo. It is a self-service support platform for our customers and certified installers. It also contains a complete portfolio of our modules---building blocks of the Ampio building automation system.
+
+The site is built by:
+
+- [@mgetka](https://github.com/mgetka), developer
+- [@SteynAnna](https://github.com/SteynAnna), maintainer
+
+and other members of the Ampio team responsible for content creation.
diff --git a/documents/markdown/hugo-docs/en_showcase_ampio-help_index.md b/documents/markdown/hugo-docs/en_showcase_ampio-help_index.md
new file mode 100644
index 0000000..20e7672
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_ampio-help_index.md
@@ -0,0 +1,76 @@
+---
+title: Ampio Knowledge Base
+date: 2022-10-30
+description: "Knowledge base for the Ampio building automation system."
+siteURL: https://help.ampio.com/
+---
+
+As a company that specializes in highly customizable smart solutions for various industries, Ampio has accumulated a vast amount of knowledge throughout the years. We were on the lookout for a user-friendly platform to impart this knowledge to our clients and installers. Delivering a service that caters to both audiences, scattered around the globe with vastly divergent needs and expectations, was a challenge.
+
+On the one hand, we needed something that would let us educate a client with no technical knowledge about our system in a visually appealing way.
+
+On the other hand, our installers required technical drawings, offline manuals, and a deep dive into highly specialized subjects.
+
+Over and above that, we could not overlook the fact that our internal team of editors and maintainers of the Knowledge Base included non-programmers who had to be able to create content and navigate the architecture of the site just as well as those adept at coding.
+
+We started our journey with the following requirements:
+
+- Ease of contribution
+- Efficient search capabilities
+- The possibility of deployment to simple shared hosting
+- Proper support for multilingualism
+
+## Dark ages of WordPress
+
+With the above-mentioned in mind, we built our first revision of the service in WordPress with a commercial knowledge base plugin. The initial requirements seemed not to be exorbitant, and yet we were surprised to see that only a few of the available solutions covered them. Especially, the case of multilingualism appeared to be particularly neglected across the available products.
+
+The WordPress-based products made big promises: pay some bucks, bootstrap the service in minutes, and forget about all the development troubles. And although those promises could possibly be deliverable on WordPress' end, it was definitely not true for anything more than the most generic deployments. In our case, we were dealing with more and more trade-offs. Plus, the solution was just slow on the simple shared hosting environment that we dedicated to the job.
+
+## Turning point
+
+The turning point was the introduction of a new key requirement---each document was to be downloadable in the PDF format. Such functionality was not available in the plugins we owned, nor did it look like any of the other existing WordPress plugins could fulfill our needs to a satisfactory degree. Nobody in our team was brave enough to add such a functionality to the current stack, so we decided to start from scratch.
+
+On top of that new development, we had to remember another one of our key requirements, namely, that mostly non-programmers were to be responsible for the service maintenance and content creation. Initially, we were leaning towards headless CMS-based solutions, but finally we made a bold move and decided to create a Git-managed Jamstack service and see what happens.
+
+## Hugo to the rescue
+
+Hugo was our first choice of SSG. The multilingualism support was the primary feature that convinced us. Later on, going through the documentation, we continued to discover new exciting features that we didn't even know we needed when we started.
+
+The rich functionalities of WordPress WYSIWYG editors soon turned out to be a curse. It became burdensome to maintain formatting consistency across documents prepared by multiple contributors. When we considered Markdown, we knew that it would give us a lot less flexibility. In our case, it proved to be a blessing in disguise---the constraints imposed by the notation ensured that each document was prepared in the same way. And in the cases where Markdown was not enough, Hugo shortcodes gave us all that we needed to get the results we anticipated.
+
+In terms of PDF generation, we utilized [custom output formats](/configuration/output-formats/) to produce intermediary document representations, which are consumed by our custom tool transforming them to TeX documents, which are finally used to produce PDF files.
+
+Custom output formats were also used to create search indexes. The search functionality is built on the brilliant [TNTSearch](https://github.com/teamtnt/tntsearch) library. The search queries and results are handled by PHP snippets embedded into static documents handled by Hugo.
+
+We even implemented a simple REST API generated by Hugo! We have yet to find something that cannot be achieved with this stack, while in WordPress-based solutions we were struggling with things as simple as defining custom document ordering in one of the categories list views.
+
+When talking about Hugo, we cannot forget about the speed. At the beginning we were not considering it a killer feature, but as our document base grew bigger, we appreciated it more and more. Dry-runs are not so common---most of the time we are working on one of the documents with cache already built during one of the previous Hugo runs. In such a scenario, Hugo rebuilds the site in about a second and we consider it a very good result.
+
+```text
+ | EN | PL
+-------------------+-----+------
+ Pages | 483 | 486
+ Paginator pages | 56 | 55
+ Non-page files | 745 | 749
+ Static files | 917 | 917
+ Processed images | 487 | 490
+ Aliases | 80 | 79
+ Sitemaps | 2 | 1
+ Cleaned | 0 | 0
+
+Total in 1096 ms
+```
+
+## Adaptation among the contributors
+
+Very quickly it became apparent that our initial concerns about the adaptation of the workflow among contributors were grossly exaggerated. Markdown is fairly straightforward and did not cause any trouble for the contributors.
+
+We recommended that our colleagues use Visual Studio Code as a tool for content creation. The project's repository tracks project-scoped configuration of the editor, which includes a set of _tasks_ allowing to run a live server from the GUI level. This is very useful for those who are easily frightened when faced with the mighty terminal.
+
+The basic skills of the Git workflow were also easily acquired. At the end of the day, builds and deployments are fully managed by [CI/CD](g) processes, so the administration of the service drills down to reviewing and accepting merge requests in the Git frontend. As a side effect, we receive a full and clear history of contributions, which is well appreciated by our quality assurance auditors.
+
+We could even say that our experiment spread the love for Git among non-programmers in our organization!
+
+## Summary
+
+Hugo is the best! Definitely give it a try if you are ever faced with a challenge similar to ours. And do not give it a second thought if your service contributors are not too technically inclined---it might still turn out great!
diff --git a/documents/markdown/hugo-docs/en_showcase_bypasscensorship_bio.md b/documents/markdown/hugo-docs/en_showcase_bypasscensorship_bio.md
new file mode 100644
index 0000000..a6c98f9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_bypasscensorship_bio.md
@@ -0,0 +1,6 @@
+Bypass Censorship find and promote tools that provide Internet access to everyone.
+
+The site is built by:
+
+- [Leyla Avsar](https://www.leylaavsar.com/) (designer)
+- [Fredrik Jonsson](https://xdeb.net/) (dev)
diff --git a/documents/markdown/hugo-docs/en_showcase_bypasscensorship_index.md b/documents/markdown/hugo-docs/en_showcase_bypasscensorship_index.md
new file mode 100644
index 0000000..bd1a072
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_bypasscensorship_index.md
@@ -0,0 +1,23 @@
+---
+title: Bypass Censorship
+date: 2019-06-16
+description: 'Showcase: "Bypass Censorship find and promote tools that provide Internet access to everyone."'
+siteURL: https://www.bypasscensorship.org/
+byline: "[Fredrik Jonsson](https://xdeb.net/), Web developer & Linux sysadmin"
+---
+
+The British Broadcasting Corporation (BBC) (UK), Deutsche Welle (DW) (Germany), France Médias Monde (FMM) (France), the U.S. Agency for Global Media (USAGM) (US) and the Open Technology Fund (OTF) (US) co-sponsor the Bypass Censorship website.
+
+Websites of international news agencies are often blocked in many countries. In order to connect people to these sites, Bypass Censorship feature and recommend tools in the following languages: English, French, Spanish, Arabic, Farsi, Chinese, and Russian.
+
+One of the tools is the Bypass Censorship Extension for Firefox and Chrome. The extension help direct people to mirrors of partners sites if they are being censored.
+
+The first version of the site was built in Drupal 8 but it was relaunched as a static site built with Hugo in 2019.
+
+Security, page load time and easy of hosting is the main reasons for switching to a static site. As the lead developer I had good experience with Hugo and was interested in exploring the multilingual features.
+
+It's a simply site, basically one page in seven languages. I had no problems getting Hugo to output what I wanted. Found the multilingual support straight forward and easy to work with.
+
+Thanks to the design by [Leyla Avsar](https://www.leylaavsar.com/) the site also looks good. I used the [Hugo Zen theme](https://github.com/frjo/hugo-theme-zen) with a few custom templates and the needed CSS.
+
+The editors can maintain content via [Forestry.io CMS](https://forestry.io/) or directly via Git. Forestry does unfortunately not have multilingual support. All the language versions are in one pile making it harder to find the right file to edit, but it works.
diff --git a/documents/markdown/hugo-docs/en_showcase_digitalgov_bio.md b/documents/markdown/hugo-docs/en_showcase_digitalgov_bio.md
new file mode 100644
index 0000000..70bb990
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_digitalgov_bio.md
@@ -0,0 +1 @@
+**Digital.gov** helps people in the U.S. government deliver better, more accessible digital services through publishing essential guidance, resources, tools, and online events that make it easier for people to design, build, and deliver essential services for the public.
diff --git a/documents/markdown/hugo-docs/en_showcase_digitalgov_index.md b/documents/markdown/hugo-docs/en_showcase_digitalgov_index.md
new file mode 100644
index 0000000..7f05847
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_digitalgov_index.md
@@ -0,0 +1,64 @@
+---
+title: Digital.gov
+date: 2020-05-01
+description: 'Showcase: "Guidance on building better digital services in government."'
+siteURL: https://digital.gov/
+siteSource: https://github.com/gsa/digitalgov.gov
+---
+
+For over a decade, Digital.gov has provided guidance, training, and community support to the people who are responsible for delivering digital services in the U.S. government. Essentially, it is a place where people can find examples of problems being solved in government, and get links to the tools and resources they need.
+
+Through collaboration in our communities of practice, Digital.gov is a window into the people who work in technology in government and the challenges they face making digital services stronger and more effective. [Read more about our site »](https://digital.gov/2019/12/19/a-new-digitalgov/)
+
+Digital.gov is built using the [U.S. Web Design System](https://designsystem.digital.gov/) (USWDS) and have followed the [design principles](https://designsystem.digital.gov/maturity-model/) in building out our new site:
+
+- **Start with real user needs** — We used human-centered design methods to inform our product decisions (like qualitative user research), and gathered feedback from real users. We also continually test our assumptions with small experiments.
+- **Earn trust** —We recognize that trust has to be earned every time. We are including all [required links and content](https://digital.gov/resources/required-web-content-and-links/) on our site, clearly identifying as a government site, building with modern best practices, and using HTTPS.
+- **Embrace accessibility** — [Accessibility](https://digital.gov/resources/intro-accessibility/) affects everybody, and we built it into every decision. We're continually working to conform to Section 508 requirements, use user experience best practices, and support a wide range of devices.
+- **Promote continuity** — We started from shared solutions like USWDS and [Federalist](https://federalist.18f.gov/). We designed our site to clearly identify as a government site by including USWDS's .gov banner, common colors and patterns, and built with modern best practices.
+- **Listen** — We actively collect user feedback and web metrics. We use the [Digital Analytics Program](https://digital.gov/services/dap/) (DAP) and analyze the data to discover actionable insights. We make small, incremental changes to continuously improve our website by listening to readers and learning from what we hear.
+
+_More on the [USWDS maturity model »](https://designsystem.digital.gov/maturity-model/)_
+
+## Open tools
+
+We didn't start from scratch. We built and designed the Digital.gov using many of the open-source tools and services that we develop for government here in the [Technology Transformation Services](https://www.gsa.gov/tts/) (TTS).
+
+Using services that make it possible to design, build, and iterate quickly are essential to modern web design and development, which is why [Federalist](https://federalist.18f.gov/) and the [U.S. Web Design System](https://designsystem.digital.gov/) are such a great combination.
+
+**Why Hugo?** Well, with around `~3,000` files _(and growing)_ and `~9,000` built pages, we needed a site generator that could handle that volume with lightning fast speed.
+
+Hugo was the clear option. The [Federalist](https://federalist.18f.gov/) team quickly added it to their available site generators, and we were off.
+
+At the moment, it takes around `32 seconds` to build close to `~10,000` pages!
+
+Take a look:
+
+```text
+
+ | EN
+-------------------+-------
+ Pages | 7973
+ Paginator pages | 600
+ Non-page files | 108
+ Static files | 851
+ Processed images | 0
+ Aliases | 1381
+ Sitemaps | 1
+ Cleaned | 0
+
+Built in 32.427 seconds
+```
+
+In addition to Hugo, we are proudly using a number of other tools and services, all built by government are free to use:
+
+- [Federalist](https://federalist.18f.gov/)
+- [Search.gov](https://www.search.gov/) — A free, hosted search platform for federal websites.
+- [Cloud.gov](https://www.cloud.gov/) — helps teams build, run, and authorize cloud-ready or legacy government systems quickly and cheaply.
+- [Federal CrowdSource Mobile Testing Program](https://digital.gov/services/service_mobile-testing-program/) — Free mobile compatibility testing by feds, for feds.
+- [Digital Analytics Program](https://digital.gov/services/dap/) (DAP) — A free analytics tool for measuring digital services in the federal government
+- [Section508.gov](https://www.section508.gov/) and [PlainLanguage.gov](https://www.plainlanguage.gov/) resources
+- [API.data.gov](https://api.data.gov/) — a free API management service for federal agencies
+- [U.S. Digital Registry](https://digital.gov/services/u-s-digital-registry/) — A resource for confirming the official status of government social media accounts, mobile apps, and mobile websites.
+
+**Questions or feedback?** [Submit an issue](https://github.com/GSA/digitalgov.gov/issues) or send us an email to [digitalgov@gsa.gov](mailto:digitalgov@gsa.gov) :heart:
diff --git a/documents/markdown/hugo-docs/en_showcase_fireship_bio.md b/documents/markdown/hugo-docs/en_showcase_fireship_bio.md
new file mode 100644
index 0000000..2a5639a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_fireship_bio.md
@@ -0,0 +1,5 @@
+**Fireship.io** is an ecosystem of detailed and practical resources for developers who want to build and ship high-quality apps.
+
+The site is built by:
+
+- [Jeff Delaney](https://fireship.io/contributors/jeff-delaney/)
diff --git a/documents/markdown/hugo-docs/en_showcase_fireship_index.md b/documents/markdown/hugo-docs/en_showcase_fireship_index.md
new file mode 100644
index 0000000..454ee87
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_fireship_index.md
@@ -0,0 +1,17 @@
+---
+title: fireship.io
+date: 2019-02-02
+description: 'Showcase: "Hugo helps us create complex technical content that integrates engaging web components."'
+siteURL: https://fireship.io
+siteSource: https://github.com/fireship-io/fireship.io
+byline: "[Jeff Delaney](https://github.com/codediodeio), Fireship.io Creator"
+---
+
+After careful consideration of JavaScript/JSX-based static site generators, it became clear that Hugo was the only tool capable of handling our project's complex demands. Not only do we have multiple content formats and taxonomies, but we often need to customize the experience at a more granular level. The problems Hugo has solved for us include:
+
+- **Render speed.** We know from past experience that JavaScript-based static site generators become very slow when you have thousands of pages and images.
+- **Feature-rich.** Our site has a long list of specialized needs and Hugo somehow manages to cover every single use case.
+- **Composability.** Hugo's partial and shortcode systems empower us to write DRY and maintainable templates.
+- **Simplicity.** Hugo is easy to learn (even without Go experience) and doesn't burden us with brittle dependencies.
+
+The site is able to achieve Lighthouse performance scores of 95+, despite the fact that it is a fully interactive PWA that ships Angular and Firebase in the JS bundle. This is made possible by (1) prerendering content with Hugo and (2) lazily embedding native web components directly in the HTML and Markdown. We provide a [detailed explanation](https://youtu.be/gun8OiGtlNc) of the architecture on YouTube and can't imagine development without Hugo.
diff --git a/documents/markdown/hugo-docs/en_showcase_forestry_bio.md b/documents/markdown/hugo-docs/en_showcase_forestry_bio.md
new file mode 100644
index 0000000..23951a1
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_forestry_bio.md
@@ -0,0 +1,3 @@
+Forestry.io is a Git-backed CMS (content management system) for websites and web products built using static site generators such as Hugo.
+
+Forestry bridges the gap between developers and their teams, by making development fun and easy, while providing powerful content management for their teams.
diff --git a/documents/markdown/hugo-docs/en_showcase_forestry_index.md b/documents/markdown/hugo-docs/en_showcase_forestry_index.md
new file mode 100644
index 0000000..58ff8ee
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_forestry_index.md
@@ -0,0 +1,48 @@
+---
+title: Forestry.io
+date: 2018-03-16
+description: 'Showcase: "Seeing Hugo in action is a whole different world of awesome."'
+siteURL: https://forestry.io/
+siteSource: https://github.com/forestryio/forestry.io
+---
+
+It was clear from the get-go that we had to go with a static site generator. Static sites are secure, performant, and give you 100% flexibility. At [Forestry.io](https://forestry.io/) we provide Content Management Solutions for websites built with static site generators, so we might be a little biased. The only question: Which static site generator was the right choice for us?
+
+## Why Hugo?
+
+In our early research we looked at Ionic's [site](https://github.com/ionic-team/ionic) to get some inspiration. They used Jekyll to build their website. While Jekyll is a great generator, the build times for larger sites can be painfully slow. With more than 150 pages plus many custom configurations and add-ons, our website doesn't fall into the low-volume category anymore. Our developers want a smooth experience when working on the website and our content editors need the ability to preview content quickly. In short, we need our builds to be lightning fast.
+
+We knew Hugo was fast but we did [some additional benchmarking](https://forestry.io/blog/hugo-vs-jekyll-benchmark/) before making our decision. Seeing Hugo in action is a whole different world of awesome. Hugo takes less than one second to build our 150-page site! Take a look:
+
+```text
+ | EN
++------------------+-----+
+ Pages | 141
+ Paginator pages | 4
+ Non-page files | 0
+ Static files | 537
+ Processed images | 0
+ Aliases | 60
+ Sitemaps | 1
+ Cleaned | 0
+
+Total in 739 ms
+```
+
+In fact, we liked Hugo so much that our wizard Chris made his workflow public and we started the open-source project [Create-Static-Site](https://github.com/forestryio/create-static-site). It's [a simple way to spin up sites](https://forestry.io/blog/up-and-running-with-hugo/) and set up a modern web development workflow with one line of code. Essentially it adds build configurations as a dependency for JS, CSS and Image Processing.
+
+Lastly, we want to take the opportunity to give some love to other amazing tools we used building our website.
+
+### What tools did we use?
+
+- Our Norwegian designer Nichlas is in love with [**Sketch**](https://www.sketchapp.com/). From what we hear it's a designer's dream come true.
+- Some say our main graphic is [mesmerizing](https://x.com/hmncllctv/status/968907474664284160). Nichlas created it using [**3DS Max**](https://www.autodesk.com/products/3ds-max/overview).
+- [**Hugo**](https://gohugo.io/) -- of course.
+- Chris can't think of modern web development without [**Gulp**](https://gulpjs.com/) & [**Webpack**](https://webpack.js.org/). We used them to add additional build steps such as Browsersync, CSS, JS and SVG optimization.
+- Speaking about adding steps to our build, our lives would be much harder without [**CircleCI**](https://circleci.com/) for continuous deployment and automated testing purposes.
+- We can't stop raving about [**Algolia**](https://www.algolia.com/). Chris loves it and even wrote a tutorial on [how to implement Algolia](https://forestry.io/blog/search-with-algolia-in-hugo/) into static sites using Hugo's [custom output formats](/configuration/output-formats/).
+- [**Cloudinary**](https://cloudinary.com/) is probably one of the easiest ways to get responsive images into your website.
+- We might be a little biased on this one - We think [**Forestry.io**](https://forestry.io/) is a great way to add a content management system with a clean UI on top of your site without interrupting your experience as a developer.
+- For hosting purposes we use the almighty [**AWS**](https://aws.amazon.com/).
+- [**Formspree.io**](https://formspree.io/) is managing our support and enterprise requests.
+- We also use browser cookies and JS to customize our user's experience and give it a more dynamic feel.
diff --git a/documents/markdown/hugo-docs/en_showcase_godot-tutorials_bio.md b/documents/markdown/hugo-docs/en_showcase_godot-tutorials_bio.md
new file mode 100644
index 0000000..fd849f8
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_godot-tutorials_bio.md
@@ -0,0 +1,7 @@
+[Godot Tutorials](https://godottutorials.com) aims to teach beginners how to get up and running with basic game programming and game development skills.
+
+The website is built with the **Hugo Framework** alongside aws+cloudfront+lambda.
+
+The site is built by:
+
+- [Godot Tutorials](https://godottutorials.com)
diff --git a/documents/markdown/hugo-docs/en_showcase_godot-tutorials_index.md b/documents/markdown/hugo-docs/en_showcase_godot-tutorials_index.md
new file mode 100644
index 0000000..fe4f933
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_godot-tutorials_index.md
@@ -0,0 +1,17 @@
+---
+title: Godot Tutorials
+date: 2021-01-07
+description: "Teaching game development skills with love."
+siteURL: https://godottutorials.com
+byline: "[Godot Tutorials](https://godottutorials.com), Web Developer & Game Programmer"
+---
+
+[Godot Tutorials](https://godottutorials.com) started as a way to teach beginners game programming and game development.
+As I created videos, I ran into a problem; if I made a mistake with a YouTube video, it was difficult to correct errors.
+
+I discovered that blogging episodes and having articles that teach on top of my videos is a fantastic solution to my problem.
+
+As I researched blogging platforms, I came across two solutions; however, I chose [Hugo](https://gohugo.io) because it's built with Markdown in mind and simplified my workflow.
+
+In a sense, with [Hugo](https://gohugo.io) programmed the right way, I can focus **more time on planning, creating, and editing**
+my videos and **less time maintaining and fixing** my website.
diff --git a/documents/markdown/hugo-docs/en_showcase_hapticmedia_index.md b/documents/markdown/hugo-docs/en_showcase_hapticmedia_index.md
new file mode 100644
index 0000000..52c3337
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_hapticmedia_index.md
@@ -0,0 +1,31 @@
+---
+title: Hapticmedia Blog
+date: 2019-10-01
+description: 'Showcase: "A simple, but powerful, multilingual blog."'
+siteURL: https://hapticmedia.fr/blog/en/
+byline: "[Cyril Bonnet](https://github.com/monsieurnebo), Web Developer"
+---
+
+Our goal was to create a simple, effective and multilingual blog on [3D technology](https://hapticmedia.fr/blog/en/3d-technology/) that could be managed by a non-technical profile.
+
+## Why Hugo?
+
+Hugo addresses all these needs, coupled with [Forestry.io](https://forestry.io/) for its administration via a "turnkey" interface. We have attached particular importance to SEO, and therefore to the creation of an advanced taxonomy system. Thus, each author and tag has a dedicated page, listing the related posts.
+
+## What we liked
+
+- The **multilingual** content support, especially simple to setup.
+- The **multiple environments** support (develop, staging, test, production, ...).
+- Although a hard start with the Go language, the power of the **Hugo's templating**.
+- The **partial layouts**, including the `internals` (e.g. social meta tags).
+- The **build time**, unbeatable ⚡️⚡️⚡️.
+
+## Tools & workflow
+
+- We used the same design as **[our website](https://hapticmedia.fr/en/)**, recreated as a Hugo HTML template.
+- **[Hugo](https://gohugo.io)** for the static website generator.
+- **[CircleCI](https://circleci.com)** for continuous integration & deployment.
+- **[AWS](https://aws.amazon.com/)** for web hosting.
+- **[Forestry.io](https://forestry.io)** for the content management.
+
+**All of these tools allow our editor to manage the blog's content without having to worry about its technical aspect, which is managed by the developers.**
diff --git a/documents/markdown/hugo-docs/en_showcase_hartwell-insurance_bio.md b/documents/markdown/hugo-docs/en_showcase_hartwell-insurance_bio.md
new file mode 100644
index 0000000..4cded7b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_hartwell-insurance_bio.md
@@ -0,0 +1,5 @@
+Hartwell Insurance is an insurance company set up solely to service the Broker community.
+
+By combining **Hugo**, **Service Worker** and **Netlify**, we were able to achieve incredible global site performance.
+
+The site was built by [Tomango](https://www.tomango.co.uk)
diff --git a/documents/markdown/hugo-docs/en_showcase_hartwell-insurance_index.md b/documents/markdown/hugo-docs/en_showcase_hartwell-insurance_index.md
new file mode 100644
index 0000000..1e15510
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_hartwell-insurance_index.md
@@ -0,0 +1,63 @@
+---
+title: Hartwell Insurance
+date: 2018-02-09
+description: 'Showcase: "Hugo + Netlify + PWA makes for a rapid website."'
+siteURL: https://www.hartwell-insurance.com/
+byline: "[Trys Mudford](http://www.trysmudford.com), Lead Developer, Tomango"
+---
+
+We've just launched a shiny new website for [Hartwell Insurance](https://www.hartwell-insurance.com/). I'm really proud of it. It was tackled in a different way to most previous Tomango site builds, using some fancy new tools and some vintage web standards.
+
+It's a multi-page, single-page (!) website written in Hugo, a static site generator built with performance as a first-class feature. I've outlined a load of benefits to Hugo and static sites [on a page explaining the benefits of static sites](https://why-static.netlify.com/), in case you're interested.
+
+> **In essence, a static site generator pre-renders the whole site into HTML files and serves them like it's 1995.**
+
+There's no Apache or Node backend that does compilation at runtime, it's all done at the build step. This means the server; Netlify in this case, only has to do one thing: serve files. Unsurprisingly, serving simple files is VERY quick.
+
+The starter point was the [Victor Hugo](https://github.com/netlify/victor-hugo) repository that Netlify have created. It let me dive in with Hugo, PostCSS, Browsersync and ES6 without setting up any tooling myself---always a win!
+
+I then took all the content from the design file and moved it into Markdown, putting shortcodes in where necessary. This site did need a number of custom shortcodes for the presentational elements like the expanding circles and full width backgrounds. But mostly it was just clean, semantic HTML with some CSS and JS enhancement thrown in.
+
+For example, this two column layout shown below. I used CSS Columns with a `break-after: always;` on the `<h1>`. No multi-wrapper or difficult-to-clear shortcodes, just clean HTML.
+
+
+
+For the ripple effects on the section headings, I used JS to prepend a `<canvas>` element then animated it with `RequestAnimationFrame`. It adds a nice bit of movement on the page.
+
+On the Hartwell Profitmaker section, I toyed with the idea of using Vue.js for the calculator, but after giving it some thought, I decided to code in Vanilla. The result, all of the site JS comes in at 3.2KB!
+
+The plan was to host with Netlify and therefore get access to Netlify Forms. It meant spending 0 minutes on getting a backend set up so I could focus fully on the frontend.
+
+Cache invalidation isn't normally something I spend all that much time thinking about when building a site. But as this site was going to be a Progressive Web App, invalidating files would be important to ensure the site didn't appear broken when we made changes. As I was using Victor-Hugo, I wasn't really sure how to best tackle this and sadly spent far too many hours wrangling with Webpack and Gulp files to try and get hashed file names working nicely.
+
+Then; while I was waiting for a haircut, I read a [Netlify blog post](https://www.netlify.com/blog/2017/02/23/better-living-through-caching/) on how they do cache invalidation with HTTP2 and it promptly blew my mind.
+
+When you request an asset, they send an ETag in the headers which is a hash of the file. There's also a header to tell the browser not to trust it's own cache (which sounds a little bit bonkers).
+
+So when you request the page, it opens a persistent HTTP2 connection up (so no new connections for file requests). When it gets to requesting that asset, the browser sends the ETag back to Netlify and they either return nothing if the ETag matches, or the new file with the new ETag. No `app.klfjlkdsfjdslkfjdslkfdsj.js` or `app.js?v=20180112`. Just a clean `app.js` with instant cache invalidation. Amazing.
+
+Finally, the [Service Worker](https://www.hartwell-insurance.com/sw.js) could be added. This turned out to be straightforward as the Netlify cache invalidation system solved most of the pain points. I went for a network-first, cache-fallback setup for both assets and HTML. This does mean flaky speeds are reliant on the page connection time, but given we're on HTTP2, I'm hoping the persistent connection and tiny ETag size will keep it quick. For online connections, every request is up to date and instantly live after any update. Offline connections fall back to every assets' last cached state. It seems to work really nicely, and there's no need for an update prompt if assets have changed.
+
+---
+
+## The results
+
+The WebPageTest results are looking good. The speed index is 456, 10x smaller than the average Alexa top 300,000 score.
+
+
+
+[TestMySite.io](https://testmysite.io/5a7e1bb2df99531a23c9ad2f/hartwell-insurance.com) is return ~2ms time to first byte from the CDN edge nodes. Lighthouse audits are also very promising. There's still some improvement to be gained lazy-loading the images and inlining the CSS. I'm less excited about the [second suggestion](http://www.trysmudford.com/css-in-2017/), but I'll certainly look at some lazy-loading, especially as I'm already using `IntersectionObserver` for some animations.
+
+
+
+The most encouraging result is how quick the site is around the world. Most Tomango clients (and their customers) are pretty local and almost exclusively UK-based. We have a dedicated server in Surrey that serves our market pretty well. It did take me by surprise just how much slower a connection from the USA, Australia and Japan to our server was. They're waiting ~500ms just for the first byte, let alone downloading each asset.
+
+[Hartwell Insurance](https://www.hartwell-insurance.com/) are a US company so by putting them on our server, we'd be instantly hampering their local response times by literally seconds. This was one of the main reasons for going with Netlify. They provide global CDN hosting that's quick from anywhere in the world.
+
+---
+
+This project was such a blast to develop, it's a real pleasure to put new technologies to good use in production, and to see real performance and usability benefits from them. Even using classic web methods of serving directories with files is fun when you've been using dynamic systems for a while---there's something really pure about it.
+
+---
+
+_This was originally posted on [my website](http://www.trysmudford.com/perfomance-wins-with-hugo-and-netlify/)_
diff --git a/documents/markdown/hugo-docs/en_showcase_keycdn_bio.md b/documents/markdown/hugo-docs/en_showcase_keycdn_bio.md
new file mode 100644
index 0000000..90f623d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_keycdn_bio.md
@@ -0,0 +1 @@
+[KeyCDN](https://www.keycdn.com) is a high performance content delivery network (CDN) offering many powerful features, including image processing that can transform and optimize images in real time. Our network offers global coverage to speed up content delivery and is capable of delivering entire static websites, like those built with Hugo, at the edge.
diff --git a/documents/markdown/hugo-docs/en_showcase_keycdn_index.md b/documents/markdown/hugo-docs/en_showcase_keycdn_index.md
new file mode 100644
index 0000000..c697232
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_keycdn_index.md
@@ -0,0 +1,28 @@
+---
+title: KeyCDN
+date: 2020-04-10
+description: 'Showcase: "Hugo has become an integral part of our stack."'
+siteURL: https://www.keycdn.com
+---
+
+At KeyCDN one of our primary focuses is on performance. With speed being ingrained in our DNA we knew from the start that we must use a fast static website generator that could meet our requirements. When evaluating the right solution, Hugo met our requirements and we looked no further as it was the fastest and most flexible.
+
+## Why we chose Hugo
+
+Before our migration to Hugo our website was powered by a PHP-based website that had about 50 pages and a WordPress website that had over 500 posts between our blog and knowledge base. This became harder to maintain as time continued. We felt like we were losing the speed and flexibility that we require. To overcome this we knew we needed to convert our website to be static. This would allow our website to be faster and more secure as it could be delivered by all of our edge locations.
+
+It wasn't an easy task at the beginning, however, after evaluating Hugo and benchmarking it we knew we had found the ideal solution. Hugo was by far the fastest setup and offered an intuitive way to build our entire website exactly as needed. The Go-based templates, shortcodes, and configuration options made it easy to build a complex website.
+
+In the fall of 2018 we started the migration and within a couple short months we had built a custom static website with Hugo and migrated all content from our old systems. The simplicity and vast amount of functionality that Hugo offers made this process fast and left our entire team, including all of our writers and developers, happy with the migration. Since migrating to Hugo we haven't looked back. Hugo has become an integral part of our stack. We're grateful to all those who have contributed to make Hugo what it is today.
+
+## Technical overview
+
+Below is an overview of what we used with Hugo to build our website:
+
+- [KeyCDN](https://www.keycdn.com) uses a custom theme and is our primary hub for all style sheets and JavaScript. Our other websites, like [KeyCDN Tools](https://tools.keycdn.com), only import the required style sheets and JavaScript.
+- We use [Gulp](https://gulpjs.com) in our build process for many tasks, such as combining, versioning, and compressing our style sheets as well as our JavaScript.
+- Our search is powered by a custom solution that we've built. It allows our pages, blog, and knowledge base to be searched. It uses [Axios](https://github.com/axios/axios) to send a `POST` request containing the search query. An index file in JSON generated by Hugo is searched and the results are then returned.
+- Our commenting system is also powered by a custom solution that we've built. It uses Axios to send a `GET` request containing the slug to pull the comment thread and a `POST` request containing the name, email address, and comment when submitting a comment.
+- Our contact form is a simple HTML form, which uses Axios as well.
+- Our writers use shortcodes to enhance the capability of Markdown.
+- Our entire website is delivered through KeyCDN using a Pull Zone, which means all of our edge locations are delivering our website.
diff --git a/documents/markdown/hugo-docs/en_showcase_letsencrypt_bio.md b/documents/markdown/hugo-docs/en_showcase_letsencrypt_bio.md
new file mode 100644
index 0000000..62c5479
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_letsencrypt_bio.md
@@ -0,0 +1 @@
+Let's Encrypt is a free, automated, and open certificate authority (CA), run for the public's benefit. It is a service provided by the [Internet Security Research Group (ISRG)](https://www.abetterinternet.org/).
diff --git a/documents/markdown/hugo-docs/en_showcase_letsencrypt_index.md b/documents/markdown/hugo-docs/en_showcase_letsencrypt_index.md
new file mode 100644
index 0000000..8696cb7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_letsencrypt_index.md
@@ -0,0 +1,18 @@
+---
+title: Let's Encrypt
+date: 2018-03-13
+description: 'Showcase: "Lessons learned from taking letsencrypt.org to Hugo."'
+siteURL: https://letsencrypt.org/
+siteSource: https://github.com/letsencrypt/website
+byline: "[bep](https://github.com/bep), Hugo Lead"
+---
+
+The **Let's Encrypt website** has a common set of elements: A landing page and some other static info-pages, a document section, a blog, and a documentation section. Having it moved to Hugo was mostly motivated by a _simpler administration and Hugo's [multilingual support](/content-management/multilingual/)_. They already serve HTTPS to more than 60 million domains, and having the documentation available in more languages will increase that reach.[^1]
+
+{{< x user="letsencrypt" id="971755920639307777" >}}
+
+I helped them port the site from Jekyll to Hugo. There are usually very few surprises doing this. I know Hugo very well, but working on sites with a history usually comes up with something new.
+
+That site is bookmarked in many browsers, so preserving the URLs was a must. Hugo's URL handling is very flexible, but there was one challenge. The website has a mix of standard and what we in Hugo call _ugly URLs_ (`https://letsencrypt.org/2017/12/07/looking-forward-to-2018.html`). In Hugo this is handled automatically, and you can turn it on globally or per language. But before Hugo `0.33` you could not configure it for parts of your site. You could set it manually for the relevant pages in front matter -- which is how it was done in Jekyll -- but that would be hard to manage, especially when you start to introduce translations. So, in Hugo 0.33 I added support for _ugly URLs_ per section and also `url` set in front matter for list pages (`https://letsencrypt.org/blog/`).
+
+[^1]: The work on getting the content translated is in progress.
diff --git a/documents/markdown/hugo-docs/en_showcase_linode_bio.md b/documents/markdown/hugo-docs/en_showcase_linode_bio.md
new file mode 100644
index 0000000..52c7204
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_linode_bio.md
@@ -0,0 +1,3 @@
+**Linode** is a cloud hosting provider that offers high performance SSD Linux servers for your infrastructure needs.
+
+**Hugo** offers the documentation team incredible performance as we scale and continue providing quality Linux tutorials.
diff --git a/documents/markdown/hugo-docs/en_showcase_linode_index.md b/documents/markdown/hugo-docs/en_showcase_linode_index.md
new file mode 100644
index 0000000..f91c99d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_linode_index.md
@@ -0,0 +1,15 @@
+---
+title: Linode Docs
+date: 2018-02-12
+description: 'Showcase: "Hugo allows us to build thousands of pages in seconds."'
+siteURL: https://linode.com/docs/
+siteSource: https://github.com/linode/docs
+---
+
+The documentation team at Linode has been writing guides since 2009, with the goal of helping new and experienced Linux users find the best tools and get the most out of their systems.
+
+As our library grew into thousands of guides, we needed a fast static site generator with intuitive templating and the flexibility to extend Markdown without constantly writing HTML and CSS.
+
+Hugo solved a lot of our growing pains with features like shortcodes, customizable URLs, LiveReload, and more. We have already brought our site build time down from minutes to just a few seconds, and we are excited to see what future developments in Hugo will bring.
+
+Thank you to all the [Hugo contributors](https://github.com/gohugoio/hugo/graphs/contributors) and especially [@bep](https://github.com/bep) for helping us with the adoption of Hugo.
diff --git a/documents/markdown/hugo-docs/en_showcase_overmindstudios_bio.md b/documents/markdown/hugo-docs/en_showcase_overmindstudios_bio.md
new file mode 100644
index 0000000..080de69
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_overmindstudios_bio.md
@@ -0,0 +1,5 @@
+**Overmind Studios** is a visual effects studio headquartered in Southern Germany.
+
+The site is built by:
+
+- [Tobias Kummer](https://www.overmind-studios.de/about/)
diff --git a/documents/markdown/hugo-docs/en_showcase_overmindstudios_index.md b/documents/markdown/hugo-docs/en_showcase_overmindstudios_index.md
new file mode 100644
index 0000000..00b09c5
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_overmindstudios_index.md
@@ -0,0 +1,14 @@
+---
+title: Overmind Studios
+description: "A fresh start to make things easier in the future."
+siteURL: https://www.overmind-studios.de/
+byline: "[tobkum](https://github.com/tobkum), Co-Founder Overmind Studios"
+---
+
+After many years of running our site on WordPress, we decided to switch to Hugo.
+
+WordPress is a great CMS for many people, but it has some downsides, especially for those who need a fast, secure, and customizable site. Plugins can become outdated, customization can be difficult, and bloat can slow down page loading times.
+
+Hugo is a static site generator that addresses many of these problems. It is fast to build and iterate, does not require PHP, is highly customizable, and is easy to learn and use. It is also secure, as it does not have a backend or MySQL database that can be hacked.
+
+We are very happy with our switch to Hugo. It is easy to update our site with new projects, and our Lighthouse score and loading times are both excellent. We now have more time to be creative instead of troubleshooting WordPress quirks and updates.
diff --git a/documents/markdown/hugo-docs/en_showcase_pharmaseal_bio.md b/documents/markdown/hugo-docs/en_showcase_pharmaseal_bio.md
new file mode 100644
index 0000000..7477f1c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_pharmaseal_bio.md
@@ -0,0 +1,7 @@
+PHARMASEAL began in 2016 with the purpose of disrupting the Clinical Trials Management market through continuous validation and integration
+
+We've been using **Hugo + Webpack + Netlify** to provide a scalable, modular design for the website, complete with Forestry building blocks to quickly be able to generate engagement pages.
+
+The site is built by:
+
+- [Roboto Studio](https://roboto.studio)
diff --git a/documents/markdown/hugo-docs/en_showcase_pharmaseal_index.md b/documents/markdown/hugo-docs/en_showcase_pharmaseal_index.md
new file mode 100644
index 0000000..fa8c8a8
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_pharmaseal_index.md
@@ -0,0 +1,25 @@
+---
+title: PHARMASEAL
+date: 2019-04-29
+description: "Pharmaseal website developed using Hugo, Forestry, hosted and deployed by Netlify."
+siteURL: https://pharmaseal.co/
+byline: "[Roboto Studio](https://roboto.studio), Jonathan Alford"
+---
+
+We wanted to shake the status quo with PHARMASEAL, opting for a fast and scalable website built with Hugo instead of slower monolithic systems the competitors were using.
+
+We had two goals:
+
+## Make it fast
+
+We wanted to optimize the site as much as possible, so we opted for using Cloudinary, enabling us to take advantage of on-the-fly image manipulation, and thanks to the sheer speed of static sites, we achieved a perfect optimization score with Google audits.
+
+Because we're hosting the site through Netlify and our target audience is in America, we are taking advantage of Netlify edge (Their alternative to a CDN). We're talking blazing fast.
+
+## Make it easy
+
+We're big fans of simplicity, and that's what we delivered with the Forestry building blocks. Every element on the site is built with building blocks in mind, allowing PHARMASEAL to generate multiple pages in the blink of an eye.
+
+PHARMASEAL have found Forestry CMS combined with HUGO to be so effective at producing fast, purpose driven pages, that we have worked with them to add even more blocks in a scalable, modular fashion.
+
+**TLDR:** We're blown away with HUGO, the sheer speed, scalability and deployment possibilities with Netlify is the 💣
diff --git a/documents/markdown/hugo-docs/en_showcase_quiply-employee-communications-app_bio.md b/documents/markdown/hugo-docs/en_showcase_quiply-employee-communications-app_bio.md
new file mode 100644
index 0000000..f79677a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_quiply-employee-communications-app_bio.md
@@ -0,0 +1,4 @@
+**Quiply** is an employee communications app enabling mobile collaboration across an entire organization.
+Our customers get their own branded app enabling them to communicate fast and effectively with all employees, also non-desk and shift workers.
+
+As the Quiply app's build process is based on **Gulp**, we have started to build our company and product website using **Gulp + Hugo** which is super-fast and gives us exactly the flexibility we need.
diff --git a/documents/markdown/hugo-docs/en_showcase_quiply-employee-communications-app_index.md b/documents/markdown/hugo-docs/en_showcase_quiply-employee-communications-app_index.md
new file mode 100644
index 0000000..2c8854a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_quiply-employee-communications-app_index.md
@@ -0,0 +1,15 @@
+---
+title: Quiply Employee Communications App
+date: 2018-02-13
+description: '"It became immediately clear that we would use Hugo going forward as it compiles super-fast, is intuitive to use, and offers all the features we need."'
+siteURL: https://www.quiply.com
+byline: "[Sebastian Schirmer](mailto:sebastian.schirmer@quiply.com), Quiply Co-Founder"
+---
+
+With the launch of our Employee Communications app Quiply we created a very simple and static one-page website to showcase our product.
+
+As our customer base and demand for marketing and communication started to grow, we needed a solution to easily grow and extend the contents of our web presence. As we do not have the need to serve dynamic content, we decided to use a static site generator. Amongst a couple of others, we tried Hugo and it became immediately clear that we'd use Hugo going forward as it compiles super-fast, is intuitive to use and offers all the features we need.
+
+Our website which we launched a couple of weeks ago is still growing and new content is being added constantly. By using Hugo, this can be easily done by content authors writing Markdown files without always having to touch HTML or CSS code. It is available in German only for the time being, an English version is in the works.
+
+Huge thanks to everyone involved in making Hugo a success.
diff --git a/documents/markdown/hugo-docs/en_showcase_tomango_bio.md b/documents/markdown/hugo-docs/en_showcase_tomango_bio.md
new file mode 100644
index 0000000..c90e481
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_tomango_bio.md
@@ -0,0 +1,5 @@
+We help ambitious businesses grow by getting more of the customers they want.
+
+Our new site runs quickly, anywhere in the world, regardless of internet connectivity.
+
+The site was built by [Tomango](https://www.tomango.co.uk)
diff --git a/documents/markdown/hugo-docs/en_showcase_tomango_index.md b/documents/markdown/hugo-docs/en_showcase_tomango_index.md
new file mode 100644
index 0000000..d07abf9
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_showcase_tomango_index.md
@@ -0,0 +1,22 @@
+---
+title: Tomango
+date: 2018-05-04
+description: 'Showcase: "Tomango site relaunch: Building our JAMstack site"'
+siteURL: https://www.tomango.co.uk
+siteSource: https://github.com/trys/tomango-2018
+byline: "[Trys Mudford](https://www.trysmudford.com), Lead Developer, Tomango"
+---
+
+Hugo is our static site generator (SSG) of choice. It's **really quick**. After using it on a number of [client projects](/showcase/hartwell-insurance/), it became clear that our new site _had_ to be built with Hugo.
+
+The big benefit of an SSG is how it moves all the heavy lifting to the build time.
+
+For example in WordPress, all the category pages are created at runtime, generating a lot of database queries. In Hugo, the paginated category pages are created at build time - so all the computational complexity is done once, and doesn't impact the user at all.
+
+Similarly, instead of running a live, or even a heavily cached Instagram feed that checked for new photos on page load, we used IFTTT to flip the feature to work performantly. I've [written about it](https://www.trysmudford.com/blog/making-the-static-dynamic-instagram-importer/) in detail on my blog but in essence: IFTTT sends a webhook to a Netlify Cloud Function every time a photo is uploaded. The function scrapes the photo and commits it to our GitHub repo which triggers a Hugo build on Netlify, deploying the site immediately!
+
+Shortcodes allow copy editors to continue using WordPress-esque features, Markdown keeps our developers happy, and our users don't have any of the database overheads. It's win-win!
+
+---
+
+This is an extract from our [technical launch post](https://www.tomango.co.uk/thinks/tomango-progressive-web-app/).
diff --git a/documents/markdown/hugo-docs/en_templates_404.md b/documents/markdown/hugo-docs/en_templates_404.md
new file mode 100644
index 0000000..6bcf815
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_templates_404.md
@@ -0,0 +1,50 @@
+---
+title: Custom 404 page
+linkTitle: 404 templates
+description: Create a template to render a 404 error page.
+categories: []
+keywords: []
+weight: 200
+---
+
+To render a 404 error page in the root of your site, create a 404 template in the root of the `layouts` directory. For example:
+
+```go-html-template {file="layouts/404.html"}
+{{ define "main" }}
+ <h1>404 Not Found</h1>
+ <p>The page you requested cannot be found.</p>
+ <p>
+ <a href="{{ .Site.Home.RelPermalink }}">
+ Return to the home page
+ </a>
+ </p>
+{{ end }}
+```
+
+For multilingual projects, add the language key to the file name:
+
+```text
+layouts/
+├── 404.de.html
+├── 404.en.html
+└── 404.fr.html
+```
+
+Your production server redirects the browser to the 404 page when a page is not found. Capabilities and configuration vary by host.
+
+Host|Capabilities and configuration
+:--|:--
+Amazon CloudFront|See [details](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/GeneratingCustomErrorResponses.html).
+Amazon S3|See [details](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CustomErrorDocSupport.html).
+Apache|See [details](https://httpd.apache.org/docs/2.4/custom-error.html).
+Azure Static Web Apps|See [details](https://learn.microsoft.com/en-us/azure/static-web-apps/configuration#response-overrides).
+Azure Storage|See [details](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website#setting-up-a-static-website).
+Caddy|See [details](https://caddyserver.com/docs/caddyfile/directives/handle_errors).
+Codeberg Pages|See [details](https://docs.codeberg.org/codeberg-pages/advanced-usage/#custom-error-page-for-404s).
+Cloudflare Pages|See [details](https://developers.cloudflare.com/pages/configuration/serving-pages/#not-found-behavior).
+DigitalOcean App Platform|See [details](https://docs.digitalocean.com/products/app-platform/how-to/manage-static-sites/#configure-a-static-site).
+Firebase|See [details](https://firebase.google.com/docs/hosting/full-config#404).
+GitHub Pages|Redirection to is automatic and not configurable.
+GitLab Pages|See [details](https://docs.gitlab.com/ee/user/project/pages/introduction.html#custom-error-codes-pages).
+NGINX|See [details](https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page).
+Netlify|See [details](https://docs.netlify.com/routing/redirects/redirect-options/).
diff --git a/documents/markdown/hugo-docs/en_templates__index.md b/documents/markdown/hugo-docs/en_templates__index.md
new file mode 100644
index 0000000..ea293e8
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_templates__index.md
@@ -0,0 +1,8 @@
+---
+title: Templates
+description: Create templates to render your content, resources, and data.
+categories: []
+keywords: []
+weight: 10
+aliases: [/templates/overview/,/templates/content]
+---
diff --git a/documents/markdown/hugo-docs/en_templates_embedded.md b/documents/markdown/hugo-docs/en_templates_embedded.md
new file mode 100644
index 0000000..755a232
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_templates_embedded.md
@@ -0,0 +1,219 @@
+---
+title: Embedded partial templates
+description: Hugo provides embedded partial templates for common use cases.
+categories: []
+keywords: []
+weight: 180
+aliases: [/templates/internal]
+---
+
+{{< newtemplatesystem >}}
+
+## Disqus
+
+> [!note]
+> To override Hugo's embedded Disqus template, copy the [source code](<{{% eturl disqus %}}>) to a file with the same name in the `layouts/_partials` directory, then call it from your templates using the [`partial`] function:
+>
+> `{{ partial "disqus.html" . }}`
+
+Hugo includes an embedded template for [Disqus], a popular commenting system for both static and dynamic websites. To effectively use Disqus, secure a Disqus "shortname" by [signing up] for the free service.
+
+To include the embedded template:
+
+```go-html-template
+{{ partial "disqus.html" . }}
+```
+
+### Configuration {#configuration-disqus}
+
+To use Hugo's Disqus template, first set up a single configuration value:
+
+{{< code-toggle file=hugo >}}
+[services.disqus]
+shortname = 'your-disqus-shortname'
+{{</ code-toggle >}}
+
+Hugo's Disqus template accesses this value with:
+
+```go-html-template
+{{ .Site.Config.Services.Disqus.Shortname }}
+```
+
+You can also set the following in the front matter for a given piece of content:
+
+- `disqus_identifier`
+- `disqus_title`
+- `disqus_url`
+
+### Privacy {#privacy-disqus}
+
+Adjust the relevant privacy settings in your project configuration.
+
+{{< code-toggle config=privacy.disqus />}}
+
+disable
+: (`bool`) Whether to disable the template. Default is `false`.
+
+## Google Analytics
+
+> [!note]
+> To override Hugo's embedded Google Analytics template, copy the [source code](<{{% eturl google_analytics %}}>) to a file with the same name in the `layouts/_partials` directory, then call it from your templates using the [`partial`] function:
+>
+> `{{ partial "google_analytics.html" . }}`
+
+Hugo includes an embedded template supporting [Google Analytics 4].
+
+To include the embedded template:
+
+```go-html-template
+{{ partial "google_analytics.html" . }}
+```
+
+### Configuration {#configuration-google-analytics}
+
+Provide your tracking ID in your configuration file:
+
+{{< code-toggle file=hugo >}}
+[services.googleAnalytics]
+id = 'G-MEASUREMENT_ID'
+{{</ code-toggle >}}
+
+To use this value in your own template, access the configured ID with `{{ site.Config.Services.GoogleAnalytics.ID }}`.
+
+### Privacy {#privacy-google-analytics}
+
+Adjust the relevant privacy settings in your project configuration.
+
+{{< code-toggle config=privacy.googleAnalytics />}}
+
+disable
+: (`bool`) Whether to disable the template. Default is `false`.
+
+respectDoNotTrack
+: (`bool`) Whether to respect the browser's "do not track" setting. Default is `true`.
+
+## Open Graph
+
+> [!note]
+> To override Hugo's embedded Open Graph template, copy the [source code](<{{% eturl opengraph %}}>) to a file with the same name in the `layouts/_partials` directory, then call it from your templates using the [`partial`] function:
+>
+> `{{ partial "opengraph.html" . }}`
+
+Hugo includes an embedded template for the [Open Graph protocol](https://ogp.me/), metadata that enables a page to become a rich object in a social graph.
+This format is used for Facebook and some other sites.
+
+To include the embedded template:
+
+```go-html-template
+{{ partial "opengraph.html" . }}
+```
+
+### Configuration {#configuration-open-graph}
+
+Hugo's Open Graph template is configured using a mix of configuration settings and [front matter](/content-management/front-matter/) on individual pages.
+
+{{< code-toggle file=hugo >}}
+[params]
+ description = 'Text about my cool site'
+ images = ['site-feature-image.jpg']
+ title = 'My cool site'
+ [params.social]
+ facebook_admin = 'jsmith'
+[taxonomies]
+ series = 'series'
+{{</ code-toggle >}}
+
+{{< code-toggle file=content/blog/my-post.md fm=true >}}
+title = 'Post title'
+description = 'Text about this post'
+date = 2024-03-08T08:18:11-08:00
+images = ["post-cover.png"]
+audio = []
+videos = []
+series = []
+tags = []
+{{</ code-toggle >}}
+
+Hugo uses the page title and description for the title and description metadata. The first 6 URLs from the `images` array are used for image metadata. If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with file names matching `*feature*`, `*cover*`, or `*thumbnail*` are used for image metadata.
+
+Various optional metadata can also be set:
+
+- Date, published date, and last modified data are used to set the published time metadata if specified.
+- `audio` and `videos` are URL arrays like `images` for the audio and video metadata tags, respectively.
+- The first 6 `tags` on the page are used for the tags metadata.
+- The `series` taxonomy is used to specify related "see also" pages by placing them in the same series.
+
+If using YouTube this will produce a og:video tag like `<meta property="og:video" content="url">`. Use the `https://youtu.be/<id>` format with YouTube videos (example: `https://youtu.be/qtIqKaDlqXo`).
+
+## Pagination
+
+See [details](/templates/pagination/).
+
+## Schema
+
+> [!note]
+> To override Hugo's embedded Schema template, copy the [source code](<{{% eturl schema %}}>) to a file with the same name in the `layouts/_partials` directory, then call it from your templates using the [`partial`] function:
+>
+> `{{ partial "schema.html" . }}`
+
+Hugo includes an embedded template to render [microdata] `meta` elements within the `head` element of your templates.
+
+To include the embedded template:
+
+```go-html-template
+{{ partial "schema.html" . }}
+```
+
+## X (Twitter) Cards
+
+> [!note]
+> To override Hugo's embedded Twitter Cards template, copy the [source code](<{{% eturl twitter_cards %}}>) to a file with the same name in the `layouts/_partials` directory, then call it from your templates using the [`partial`] function:
+>
+> `{{ partial "twitter_cards.html" . }}`
+
+Hugo includes an embedded template for [X (Twitter) Cards](https://developer.x.com/en/docs/twitter-for-websites/cards/overview/abouts-cards), metadata used to attach rich media to Tweets linking to your site.
+
+To include the embedded template:
+
+```go-html-template
+{{ partial "twitter_cards.html" . }}
+```
+
+### Configuration {#configuration-x-cards}
+
+Hugo's X (Twitter) Card template is configured using a mix of configuration settings and [front-matter](/content-management/front-matter/) values on individual pages.
+
+{{< code-toggle file=hugo >}}
+[params]
+ images = ["site-feature-image.jpg"]
+ description = 'Text about my cool site'
+{{</ code-toggle >}}
+
+{{< code-toggle file=content/blog/my-post.md fm=true >}}
+title = 'Post title'
+description = 'Text about this post'
+images = ["post-cover.png"]
+{{</ code-toggle >}}
+
+If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with file names matching `*feature*`, `*cover*`, or `*thumbnail*` are used for image metadata. If no image resources with those names are found, the images defined in your [project configuration](/configuration/) are used instead. If no images are found at all, then an image-less Twitter `summary` card is used instead of `summary_large_image`.
+
+Hugo uses the page title and description for the card's title and description fields. The page summary is used if no description is given.
+
+Set the value of `twitter:site` in your project configuration:
+
+{{< code-toggle file=hugo >}}
+[params.social]
+twitter = 'GoHugoIO'
+{{</ code-toggle >}}
+
+NOTE: The `@` will be added for you
+
+```html
+<meta name="twitter:site" content="@GoHugoIO"/>
+```
+
+[`partial`]: /functions/partials/include/
+[Disqus]: https://disqus.com
+[Google Analytics 4]: https://support.google.com/analytics/answer/10089681
+[microdata]: https://html.spec.whatwg.org/multipage/microdata.html#microdata
+[signing up]: https://disqus.com/profile/signup/
diff --git a/documents/markdown/hugo-docs/en_templates_introduction.md b/documents/markdown/hugo-docs/en_templates_introduction.md
new file mode 100644
index 0000000..505724b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_templates_introduction.md
@@ -0,0 +1,579 @@
+---
+title: Introduction to templating
+linkTitle: Introduction
+description: An introduction to Hugo's templating syntax.
+categories: []
+keywords: []
+weight: 10
+---
+
+{{< newtemplatesystem >}}
+
+{{% glossary-term template %}}
+
+Templates use [variables][], [functions][], and [methods][] to transform your content, resources, and data into a published page.
+
+> [!note]
+> Hugo uses Go's [`text/template`][] and [`html/template`][] packages.
+>
+> The `text/template` package implements data-driven templates for generating textual output, while the `html/template` package implements data-driven templates for generating HTML output safe against code injection.
+>
+> By default, Hugo uses the `html/template` package when rendering HTML files.
+
+For example, this HTML template initializes the `$v1` and `$v2` variables, then displays them and their product within an HTML paragraph.
+
+```go-html-template
+{{ $v1 := 6 }}
+{{ $v2 := 7 }}
+<p>The product of {{ $v1 }} and {{ $v2 }} is {{ mul $v1 $v2 }}.</p>
+```
+
+While HTML templates are the most common, you can create templates for any [output format](g) including CSV, JSON, RSS, and plain text.
+
+## Context
+
+The most important concept to understand before creating a template is _context_, the data passed into each template. The data may be a simple value, or more commonly [objects](g) and associated [methods](g).
+
+For example, a _page_ template receives a `Page` object, and the `Page` object provides methods to return values or perform actions.
+
+### Current context
+
+Within a template, the dot (`.`) represents the current context.
+
+```go-html-template {file="layouts/page.html"}
+<h2>{{ .Title }}</h2>
+```
+
+In the example above the dot represents the `Page` object, and we call its [`Title`][] method to return the title as defined in [front matter][].
+
+The current context may change within a template. For example, at the top of a template the context might be a `Page` object, but we rebind the context to another value or object within [`range`][] or [`with`][] blocks.
+
+```go-html-template {file="layouts/page.html"}
+<h2>{{ .Title }}</h2>
+
+{{ range slice "foo" "bar" }}
+ <p>{{ . }}</p>
+{{ end }}
+
+{{ with "baz" }}
+ <p>{{ . }}</p>
+{{ end }}
+```
+
+In the example above, the context changes as we `range` through the [slice](g) of values. In the first iteration the context is "foo", and in the second iteration the context is "bar". Inside of the `with` block the context is "baz". Hugo renders the above to:
+
+```html
+<h2>My Page Title</h2>
+<p>foo</p>
+<p>bar</p>
+<p>baz</p>
+```
+
+### Template context
+
+Within a `range` or `with` block you can access the context passed into the template by prepending a dollar sign (`$`) to the dot:
+
+```go-html-template {file="layouts/page.html"}
+{{ with "foo" }}
+ <p>{{ $.Title }} - {{ . }}</p>
+{{ end }}
+```
+
+Hugo renders this to:
+
+```html
+<p>My Page Title - foo</p>
+```
+
+> [!note]
+> Make sure that you thoroughly understand the concept of _context_ before you continue reading. The most common templating errors made by new users relate to context.
+
+## Actions
+
+In the examples above, the paired opening and closing braces represent the beginning and end of a template action, a data evaluation or control structure within a template.
+
+A template action may contain literal values ([boolean](g), [string](g), [integer](g), and [float](g)), the [current context](#current-context), [variables](#variables), [functions](#functions), [methods](#methods), and the [`nil`](#nil) keyword.
+
+```go-html-template {file="layouts/page.html"}
+{{ $convertToLower := true }}
+{{ if $convertToLower }}
+ <h2>{{ strings.ToLower .Title }}</h2>
+{{ end }}
+```
+
+In the example above:
+
+- `$convertToLower` is a variable
+- `true` is a literal boolean value
+- `if` is the beginning of a control structure
+- `strings.ToLower` is a function that converts all characters to lowercase
+- `Title` is a method on a the `Page` object
+- `end` is the end of a control structure
+
+Hugo renders the above to:
+
+```html {trim=false}
+
+
+ <h2>my page title</h2>
+
+```
+
+### Whitespace
+
+Notice the blank lines and indentation in the previous example? Although irrelevant in production when you typically minify the output, you can remove the adjacent whitespace by using template action delimiters with hyphens:
+
+```go-html-template {file="layouts/page.html"}
+{{- $convertToLower := true -}}
+{{- if $convertToLower -}}
+ <h2>{{ strings.ToLower .Title }}</h2>
+{{- end -}}
+```
+
+Hugo renders this to:
+
+```html
+<h2>my page title</h2>
+```
+
+Whitespace includes spaces, horizontal tabs, carriage returns, and newlines.
+
+### Quote characters
+
+Hugo templates use different quote characters to define how text and characters are processed.
+
+Use double quotes for [interpreted string literals](g). These interpret backslashes as special instructions:
+
+```go-html-template
+{{ print "Hello world\u0021" }} → Hello world!
+```
+
+Use backticks for [raw string literals](g). These ignore backslashes and treat every character literally:
+
+```go-html-template
+{{ print `Hello world\u0021` }} → Hello world\u0021
+```
+
+Use single quotes for [rune literals](g). Unlike strings, these represent a single character as its numerical Unicode value:
+
+```go-html-template
+{{ print '!' }} → 33
+```
+
+In practical terms, you will rarely, if ever, use rune literals in your template code. They are most commonly used in low-level programming; in a Hugo template, you will almost always want a string instead.
+
+### Pipes
+
+Within a template action you may [pipe](g) a value to a function or method. The piped value becomes the final argument to the function or method. For example, these are equivalent:
+
+```go-html-template
+{{ strings.ToLower "Hugo" }} → hugo
+{{ "Hugo" | strings.ToLower }} → hugo
+```
+
+You can pipe the result of one function or method into another. For example, these are equivalent:
+
+```go-html-template
+{{ strings.TrimSuffix "o" (strings.ToLower "Hugo") }} → hug
+{{ "Hugo" | strings.ToLower | strings.TrimSuffix "o" }} → hug
+```
+
+These are also equivalent:
+
+```go-html-template
+{{ mul 6 (add 2 5) }} → 42
+{{ 5 | add 2 | mul 6 }} → 42
+```
+
+> [!note]
+> Remember that the piped value becomes the final argument to the function or method to which you are piping.
+
+### Line splitting
+
+You can split a template action over two or more lines. For example, these are equivalent:
+
+```go-html-template
+{{ $v := or $arg1 $arg2 }}
+
+{{ $v := or
+ $arg1
+ $arg2
+}}
+```
+
+You can also split [raw string literals](g) over two or more lines. For example, these are equivalent:
+
+```go-html-template
+{{ $msg := "This is line one.\nThis is line two." }}
+
+{{ $msg := `This is line one.
+This is line two.`
+}}
+```
+
+### Nil
+
+Other than using the `nil` keyword in comparisons, you may not use it as an argument to any function or method, nor may you assign it to a variable. For example, these are valid uses of the `nil` keyword:
+
+```go-html-template
+{{ if gt 42 nil }}
+ <p>42 is greater than nil</p>
+{{ end }}
+
+{{ $pages := where .Site.RegularPages "Params.color" "ne" nil }}
+```
+
+These, on the other hand, are invalid:
+
+```go-html-template
+{{ $a := nil }}
+{{ add 3 nil }}
+{{ nil | print}}
+```
+
+The actions above throw an error.
+
+## Variables
+
+A variable is a user-defined [identifier](g) prepended with a dollar sign (`$`), representing a value of any data type, initialized or assigned within a template action. For example, `$foo` and `$bar` are variables.
+
+Variables may contain [scalars](g), [slices](g), [maps](g), or [objects](g).
+
+Use `:=` to initialize a variable, and use `=` to assign a value to a variable that has been previously initialized. For example:
+
+```go-html-template
+{{ $total := 3 }}
+{{ range slice 7 11 21 }}
+ {{ $total = add $total . }}
+{{ end }}
+{{ $total }} → 42
+```
+
+Variables initialized inside of an `if`, `range`, or `with` block are scoped to the block. Variables initialized outside of these blocks are scoped to the template.
+
+With variables that represent a slice or map, use the [`index`][] function to return the desired value.
+
+```go-html-template
+{{ $slice := slice "foo" "bar" "baz" }}
+{{ index $slice 2 }} → baz
+
+{{ $map := dict "a" "foo" "b" "bar" "c" "baz" }}
+{{ index $map "c" }} → baz
+```
+
+> [!note]
+> Slices and arrays are zero-based; element 0 is the first element.
+
+With variables that represent a map or object, [chain](g) identifiers to return the desired value or to access the desired method.
+
+```go-html-template
+{{ $map := dict "a" "foo" "b" "bar" "c" "baz" }}
+{{ $map.c }} → baz
+
+{{ $homePage := .Site.Home }}
+{{ $homePage.Title }} → My Homepage
+```
+
+> [!note]
+> As seen above, object and method names are capitalized. Although not required, to avoid confusion we recommend beginning variable and map key names with a lowercase letter or underscore.
+
+## Functions
+
+Used within a template action, a function takes one or more arguments and returns a value. Unlike methods, functions are not associated with an object.
+
+Go's `text/template` and `html/template` packages provide a small set of functions, operators, and statements for general use. See the [go-templates][] section of the function documentation for details.
+
+Hugo provides hundreds of custom [functions][] categorized by namespace. For example, the `strings` namespace includes these and other functions:
+
+Function|Alias
+:--|:--
+[`strings.ToLower`](/functions/strings/tolower)|`lower`
+[`strings.ToUpper`](/functions/strings/toupper)|`upper`
+[`strings.Replace`](/functions/strings/replace)|`replace`
+
+As shown above, frequently used functions have an alias. Use aliases in your templates to reduce code length.
+
+When calling a function, separate the arguments from the function, and from each other, with a space. For example:
+
+```go-html-template
+{{ $total := add 1 2 3 4 }}
+```
+
+## Methods
+
+Used within a template action and associated with an object, a method takes zero or more arguments and either returns a value or performs an action.
+
+The most commonly accessed objects are the [`Page`][] and [`Site`][] objects. This is a small sampling of the [methods][] available to each object.
+
+Object|Method|Description
+:--|:--|:--
+`Page`|[`Date`](methods/page/date/)|Returns the date of the given page.
+`Page`|[`Params`](methods/page/params/)|Returns a map of custom parameters as defined in the front matter of the given page.
+`Page`|[`Title`](methods/page/title/)|Returns the title of the given page.
+`Site`|[`Data`](methods/site/data/)|Returns a data structure composed from the files in the `data` directory.
+`Site`|[`Params`](methods/site/params/)|Returns a map of custom parameters as defined in your project configuration.
+`Site`|[`Title`](methods/site/title/)|Returns the title as defined in the your project configuration.
+
+Chain the method to its object with a dot (`.`) as shown below, remembering that the leading dot represents the [current context][].
+
+```go-html-template {file="layouts/page.html"}
+{{ .Site.Title }} → My Site Title
+{{ .Page.Title }} → My Page Title
+```
+
+The context passed into most templates is a `Page` object, so this is equivalent to the previous example:
+
+```go-html-template {file="layouts/page.html"}
+{{ .Site.Title }} → My Site Title
+{{ .Title }} → My Page Title
+```
+
+Some methods take an argument. Separate the argument from the method with a space. For example:
+
+```go-html-template {file="layouts/page.html"}
+{{ $page := .Page.GetPage "/books/les-miserables" }}
+{{ $page.Title }} → Les Misérables
+```
+
+## Comments
+
+> [!note]
+> Do not attempt to use HTML comment delimiters to comment out template code.
+>
+> Hugo strips HTML comments when rendering a page, but first evaluates any template code within the HTML comment delimiters. Depending on the template code within the HTML comment delimiters, this could cause unexpected results or fail the build.
+
+Template comments are similar to template actions. Paired opening and closing braces represent the beginning and end of a comment. For example:
+
+```text
+{{/* This is an inline comment. */}}
+{{- /* This is an inline comment with adjacent whitespace removed. */ -}}
+```
+
+Code within a comment is not parsed, executed, or displayed. Comments may be inline, as shown above, or in block form:
+
+```text
+{{/*
+This is a block comment.
+*/}}
+
+{{- /*
+This is a block comment with
+adjacent whitespace removed.
+*/ -}}
+```
+
+You may not nest one comment inside of another.
+
+To render an HTML comment, pass a string through the [`safeHTML`][] template function. For example:
+
+```go-html-template
+{{ "<!-- I am an HTML comment. -->" | safeHTML }}
+{{ printf "<!-- This is the %s site. -->" .Site.Title | safeHTML }}
+```
+
+## Include
+
+Use the [`template`][] function to include one or more of Hugo's [embedded templates]:
+
+```go-html-template
+{{ partial "google_analytics.html" . }}
+{{ partial "opengraph" . }}
+{{ partial "pagination.html" . }}
+{{ partial "schema.html" . }}
+{{ partial "twitter_cards.html" . }}
+```
+
+Use the [`partial`][] or [`partialCached`][] function to include one or more [partial templates][]:
+
+```go-html-template
+{{ partial "breadcrumbs.html" . }}
+{{ partialCached "css.html" . }}
+```
+
+Create your _partial_ templates in the `layouts/_partials` directory.
+
+> [!note]
+> In the examples above, note that we are passing the current context (the dot) to each of the templates.
+
+## Examples
+
+This limited set of contrived examples demonstrates some of concepts described above. Please see the [functions][], [methods][], and [templates][] documentation for specific examples.
+
+### Conditional blocks
+
+See documentation for [`if`][], [`else`][], and [`end`][].
+
+```go-html-template
+{{ $var := 42 }}
+{{ if eq $var 6 }}
+ {{ print "var is 6" }}
+{{ else if eq $var 7 }}
+ {{ print "var is 7" }}
+{{ else if eq $var 42 }}
+ {{ print "var is 42" }}
+{{ else }}
+ {{ print "var is something else" }}
+{{ end }}
+```
+
+### Logical operators
+
+See documentation for [`and`][] and [`or`][].
+
+```go-html-template
+{{ $v1 := true }}
+{{ $v2 := false }}
+{{ $v3 := false }}
+{{ $result := false }}
+
+{{ if and $v1 $v2 $v3 }}
+ {{ $result = true }}
+{{ end }}
+{{ $result }} → false
+
+{{ if or $v1 $v2 $v3 }}
+ {{ $result = true }}
+{{ end }}
+{{ $result }} → true
+```
+
+### Loops
+
+See documentation for [`range`][], [`else`][], and [`end`][].
+
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $s }}
+ <p>{{ . }}</p>
+{{ else }}
+ <p>The collection is empty</p>
+{{ end }}
+```
+
+To loop a specified number of times:
+
+```go-html-template
+{{ $s := slice }}
+{{ range 3 }}
+ {{ $s = $s | append . }}
+{{ end }}
+{{ $s }} → [0 1 2]
+```
+
+### Rebind context
+
+See documentation for [`with`][], [`else`][], and [`end`][].
+
+```go-html-template
+{{ $var := "foo" }}
+{{ with $var }}
+ {{ . }} → foo
+{{ else }}
+ {{ print "var is falsy" }}
+{{ end }}
+```
+
+To test multiple conditions:
+
+```go-html-template
+{{ $v1 := 0 }}
+{{ $v2 := 42 }}
+{{ with $v1 }}
+ {{ . }}
+{{ else with $v2 }}
+ {{ . }} → 42
+{{ else }}
+ {{ print "v1 and v2 are falsy" }}
+{{ end }}
+```
+
+### Access site parameters
+
+See documentation for the [`Params`](/methods/site/params/) method on a `Site` object.
+
+With this project configuration:
+
+{{< code-toggle file=hugo >}}
+title = 'ABC Widgets'
+baseURL = 'https://example.org'
+[params]
+ subtitle = 'The Best Widgets on Earth'
+ copyright-year = '2023'
+ [params.author]
+ email = 'jsmith@example.org'
+ name = 'John Smith'
+ [params.layouts]
+ rfc_1123 = 'Mon, 02 Jan 2006 15:04:05 MST'
+ rfc_3339 = '2006-01-02T15:04:05-07:00'
+{{< /code-toggle >}}
+
+Access the custom site parameters by chaining the identifiers:
+
+```go-html-template
+{{ .Site.Params.subtitle }} → The Best Widgets on Earth
+{{ .Site.Params.author.name }} → John Smith
+
+{{ $layout := .Site.Params.layouts.rfc_1123 }}
+{{ .Site.Lastmod.Format $layout }} → Tue, 17 Oct 2023 13:21:02 PDT
+```
+
+### Access page parameters
+
+See documentation for the [`Params`](/methods/page/params/) method on a `Page` object.
+
+By way of example, consider this front matter:
+
+{{< code-toggle file=content/annual-conference.md fm=true >}}
+title = 'Annual conference'
+date = 2023-10-17T15:11:37-07:00
+[params]
+display_related = true
+key-with-hyphens = 'must use index function'
+[params.author]
+ email = 'jsmith@example.org'
+ name = 'John Smith'
+{{< /code-toggle >}}
+
+The `title` and `date` fields are standard [front matter fields][], while the other fields are user-defined.
+
+Access the custom fields by [chaining](g) the [identifiers](g) when needed:
+
+```go-html-template
+{{ .Params.display_related }} → true
+{{ .Params.author.email }} → jsmith@example.org
+{{ .Params.author.name }} → John Smith
+```
+
+In the template example above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`][] function:
+
+```go-html-template
+{{ index .Params "key-with-hyphens" }} → must use index function
+```
+
+[`and`]: /functions/go-template/and
+[`else`]: /functions/go-template/else/
+[`end`]: /functions/go-template/end/
+[`if`]: /functions/go-template/if/
+[`index`]: /functions/collections/indexfunction/
+[`or`]: /functions/go-template/or
+[`Page`]: /methods/page/
+[`partial`]: /functions/partials/include/
+[`partialCached`]: /functions/partials/includecached/
+[`range`]: /functions/go-template/range/
+[`safeHTML`]: /functions/safe/html
+[`Site`]: /methods/site/
+[`template`]: /functions/go-template/template/
+[`Title`]: /methods/page/title
+[`with`]: /functions/go-template/with/
+[current context]: #current-context
+[embedded templates]: /templates/embedded/
+[front matter fields]: /content-management/front-matter/#fields
+[front matter]: /content-management/front-matter/
+[functions]: /functions/
+[go-templates]: /functions/go-template/
+[`html/template`]: https://pkg.go.dev/html/template
+[methods]: /methods/
+[partial templates]: /templates/types/#partial
+[templates]: /templates/
+[`text/template`]: https://pkg.go.dev/text/template
+[variables]: #variables
diff --git a/documents/markdown/hugo-docs/en_templates_lookup-order.md b/documents/markdown/hugo-docs/en_templates_lookup-order.md
new file mode 100644
index 0000000..05108fc
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_templates_lookup-order.md
@@ -0,0 +1,95 @@
+---
+title: Template lookup order
+linkTitle: Lookup order
+description: Hugo uses the rules below to select a template for a given page, starting from the most specific.
+categories: []
+keywords: []
+weight: 20
+---
+
+{{< newtemplatesystem >}}
+
+## Lookup rules
+
+Hugo takes the parameters listed below into consideration when choosing a template for a given page. The templates are ordered by specificity. This should feel natural, but look at the table below for concrete examples of the different parameter variations.
+
+Kind
+: The page `Kind` (the home page is one). See the example tables below per kind. This also determines if it is a **single page** (i.e. a regular content page. We then look for a template in `_default/single.html` for HTML) or a **list page** (section listings, home page, taxonomy lists, taxonomy terms. We then look for a template in `_default/list.html` for HTML).
+
+Layout
+: Can be set in front matter.
+
+Output Format
+: See [configure output formats](/configuration/output-formats/). An output format has both a `name` (e.g. `rss`, `amp`, `html`) and a `suffix` (e.g. `xml`, `html`). We prefer matches with both (e.g. `index.amp.html`), but look for less specific templates.
+
+Note that if the output format's Media Type has more than one suffix defined, only the first is considered.
+
+Language
+: We will consider a language tag in the template name. If the site language is `fr`, `index.fr.amp.html` will win over `index.amp.html`, but `index.amp.html` will be chosen before `index.fr.html`.
+
+Type
+: Is value of `type` if set in front matter, else it is the name of the root section (e.g. "blog"). It will always have a value, so if not set, the value is "page".
+
+Section
+: Is relevant for `section`, `taxonomy` and `term` types.
+
+> [!note]
+> Templates can live in either the project's or the themes' `layout` directories, and the most specific templates will be chosen. Hugo will interleave the lookups listed below, finding the most specific one either in the project or themes.
+
+## Target a template
+
+You cannot change the lookup order to target a content page, but you can change a content page to target a template. Specify `type`, `layout`, or both in front matter.
+
+Consider this content structure:
+
+```text
+content/
+├── about.md
+└── contact.md
+```
+
+Files in the root of the `content` directory have a [content type](g) of `page`. To render these pages with a unique template, create a matching subdirectory:
+
+```text
+layouts/
+└── page/
+ └── single.html
+```
+
+But the contact page probably has a form and requires a different template. In the front matter specify `layout`:
+
+{{< code-toggle file=content/contact.md fm=true >}}
+title = 'Contact'
+layout = 'contact'
+{{< /code-toggle >}}
+
+Then create the template for the contact page:
+
+```text
+layouts/
+└── page/
+ └── contact.html <-- renders contact.md
+ └── single.html <-- renders about.md
+```
+
+As a content type, the word `page` is vague. Perhaps `miscellaneous` would be better. Add `type` to the front matter of each page:
+
+{{< code-toggle file=content/about.md fm=true >}}
+title = 'About'
+type = 'miscellaneous'
+{{< /code-toggle >}}
+
+{{< code-toggle file=content/contact.md fm=true >}}
+title = 'Contact'
+type = 'miscellaneous'
+layout = 'contact'
+{{< /code-toggle >}}
+
+Now place the layouts in the corresponding directory:
+
+```text
+layouts/
+└── miscellaneous/
+ └── contact.html <-- renders contact.md
+ └── single.html <-- renders about.md
+```
diff --git a/documents/markdown/hugo-docs/en_templates_menu.md b/documents/markdown/hugo-docs/en_templates_menu.md
new file mode 100644
index 0000000..976e9f8
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_templates_menu.md
@@ -0,0 +1,127 @@
+---
+title: Menu templates
+description: Create templates to render one or more menus.
+categories: []
+keywords: []
+weight: 150
+aliases: [/templates/menus/,/templates/menu-templates/]
+---
+
+## Overview
+
+After [defining menu entries], use [menu methods] to render a menu.
+
+Three factors determine how to render a menu:
+
+1. The method used to define the menu entries: [automatic], in [front matter], or in your [project configuration]
+1. The menu structure: flat or nested
+1. The method used to [localize the menu entries]: project configuration or translation tables
+
+The example below handles every combination.
+
+## Example
+
+This _partial_ template recursively "walks" a menu structure, rendering a localized, accessible nested list.
+
+```go-html-template {file="layouts/_partials/menu.html" copy=true}
+{{- $page := .page }}
+{{- $menuID := .menuID }}
+
+{{- with index site.Menus $menuID }}
+ <nav>
+ <ul>
+ {{- partial "inline/menu/walk.html" (dict "page" $page "menuEntries" .) }}
+ </ul>
+ </nav>
+{{- end }}
+
+{{- define "_partials/inline/menu/walk.html" }}
+ {{- $page := .page }}
+ {{- range .menuEntries }}
+ {{- $attrs := dict "href" .URL }}
+ {{- if $page.IsMenuCurrent .Menu . }}
+ {{- $attrs = merge $attrs (dict "class" "active" "aria-current" "page") }}
+ {{- else if $page.HasMenuCurrent .Menu .}}
+ {{- $attrs = merge $attrs (dict "class" "ancestor" "aria-current" "true") }}
+ {{- end }}
+ {{- $name := .Name }}
+ {{- with .Identifier }}
+ {{- with T . }}
+ {{- $name = . }}
+ {{- end }}
+ {{- end }}
+ <li>
+ <a
+ {{- range $k, $v := $attrs }}
+ {{- with $v }}
+ {{- printf " %s=%q" $k $v | safeHTMLAttr }}
+ {{- end }}
+ {{- end -}}
+ >{{ $name }}</a>
+ {{- with .Children }}
+ <ul>
+ {{- partial "inline/menu/walk.html" (dict "page" $page "menuEntries" .) }}
+ </ul>
+ {{- end }}
+ </li>
+ {{- end }}
+{{- end }}
+```
+
+Call the partial above, passing a menu ID and the current page in context.
+
+```go-html-template {file="layouts/page.html"}
+{{ partial "menu.html" (dict "menuID" "main" "page" .) }}
+{{ partial "menu.html" (dict "menuID" "footer" "page" .) }}
+```
+
+## Page references
+
+Regardless of how you [define menu entries], an entry associated with a page has access to page context.
+
+This simplistic example renders a page parameter named `version` next to each entry's `name`. Code defensively using `with` or `if` to handle entries where (a) the entry points to an external resource, or (b) the `version` parameter is not defined.
+
+```go-html-template {file="layouts/page.html"}
+{{- range site.Menus.main }}
+ <a href="{{ .URL }}">
+ {{ .Name }}
+ {{- with .Page }}
+ {{- with .Params.version -}}
+ ({{ . }})
+ {{- end }}
+ {{- end }}
+ </a>
+{{- end }}
+```
+
+## Menu entry parameters
+
+When you define menu entries in your [project configuration] or in [front matter], you can include a `params` key as shown in these examples:
+
+- [Menu entry defined in your project configuration]
+- [Menu entry defined in front matter]
+
+This simplistic example renders a `class` attribute for each anchor element. Code defensively using `with` or `if` to handle entries where `params.class` is not defined.
+
+```go-html-template {file="layouts/_partials/menu.html"}
+{{- range site.Menus.main }}
+ <a {{ with .Params.class -}} class="{{ . }}" {{ end -}} href="{{ .URL }}">
+ {{ .Name }}
+ </a>
+{{- end }}
+```
+
+## Localize
+
+Hugo provides two methods to localize your menu entries. See [multilingual].
+
+[automatic]: /content-management/menus/#define-automatically
+[define menu entries]: /content-management/menus/
+[defining menu entries]: /content-management/menus/
+[front matter]: /content-management/menus/#define-in-front-matter
+[localize the menu entries]: /content-management/multilingual/#menus
+[menu entry defined in front matter]: /content-management/menus/#example
+[menu entry defined in your project configuration]: /configuration/menus
+[menu methods]: /methods/menu/
+[multilingual]: /content-management/multilingual/#menus
+[project configuration]: /content-management/menus/#define-in-project-configuration
diff --git a/documents/markdown/hugo-docs/en_templates_new-templatesystem-overview.md b/documents/markdown/hugo-docs/en_templates_new-templatesystem-overview.md
new file mode 100644
index 0000000..6f3f93f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_templates_new-templatesystem-overview.md
@@ -0,0 +1,99 @@
+---
+title: New template system in Hugo v0.146.0
+linktitle: New template system
+description: Overview of the new template system in Hugo v0.146.0.
+categories: []
+keywords: []
+weight: 1
+---
+
+In [Hugo v0.146.0], we performed a full re-implementation of how Go templates are handled in Hugo. This includes structural changes to the `layouts` folder and a new, more powerful template lookup system.
+
+We have aimed to maintain as much backward compatibility as possible by mapping "old to new," but some reported breakages have occurred. We're working on a full overhaul of the documentation on this topic – until then, this is a one-pager with the most important changes.
+
+## Changes to the `layouts` folder
+
+| Description | Action required |
+|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| The `_default` folder is removed. | Move all files in `layouts/_default` up to the `layouts/` root. |
+| The `layouts/partials` folder is renamed to `layouts/_partials`. | Rename the folder. |
+| The `layouts/shortcodes` folder is renamed to `layouts/_shortcodes`. | Rename the folder. |
+| Any folder in `layouts` that does not start with `_` represents the root of a [Page path]. In [Hugo v0.146.0], this can be nested as deeply as needed, and `_shortcodes` and `_markup` folders can be placed at any level in the tree. | No action required. |
+| The above also means that there's no top-level `layouts/taxonomy` or `layouts/section` folders anymore, unless it represents a [Page path]. | Move them up to `layouts/` with one of the [Page kinds] `section`, `taxonomy` or `term` as the base name, or place the layouts into the taxonomy [Page path]. |
+| A template named `taxonomy.html` used to be a candidate for both Page kind `term` and `taxonomy`, now it's only considered for `taxonomy`. | Create both `taxonomy.html` and `term.html` or create a more general layout, e.g. `list.html`. |
+| For base templates (e.g., `baseof.html`), in previous Hugo versions, you could prepend one identifier (layout, type, or kind) with a hyphen in front of the baseof keyword. | Move that identifier after the first "dot," e.g., rename`list-baseof.html` to `baseof.list.html`. |
+| We have added a new `all` "catch-all" layout. This means that if you have, e.g., `layouts/all.html` and that is the only template, that layout will be used for all HTML page rendering. | |
+| We have removed the concept of `_internal` Hugo templates.[^internal] | Replace constructs similar to `{{ template "_internal/opengraph.html" . }}` with `{{ partial "opengraph.html" . }}`. |
+| The identifiers that can be used in a template filename are one of the [Page kinds] (`home`, `page`, `section`, `taxonomy`, or `term`), one of the standard layouts (`list`, `single`, or `all`), a custom layout (as defined in the `layout` front matter field), a language (e.g., `en`), an output format (e.g., `html`, `rss`), and a suffix representing the media type. E.g., `all.en.html` and `home.rss.xml`. | |
+| The above means that there's no such thing as an `index.html` template for the home page anymore. | Rename `index.html` to `home.html`. |
+
+Also, see the [Example folder structure] below for a more concrete example of the new layout system.
+
+## Changes to template lookup order
+
+We have consolidated the template lookup so it works the same across all [template types]. The previous setup was very hard to understand and had a massive number of variants. The new setup aims to feel natural with few surprises.
+
+The identifiers used in the template weighting, in order of importance, are:
+
+| Identifier | Description |
+|--------------------|-------------------------------------------------------|
+| Layout custom | The custom `layout` set in front matter. |
+| [Page kinds][] | One of `home`, `section`, `taxonomy`, `term`, `page`. |
+| Layouts standard 1 | `list` or `single`. |
+| Output format | The output format (e.g., `html`, `rss`). |
+| Layouts standard 2 | `all`. |
+| Language | The language (e.g., `en`). |
+| Media type | The media type (e.g., `text/html`). |
+| [Page path][] | The page path (e.g., `/blog/mypost`). |
+| Type | `type` set in front matter.[^type] |
+
+For templates placed in a `layouts` folder partly or completely matching a [Page path], a closer match upwards will be considered _better_. In the [Example folder structure] below, this means that:
+
+- `layouts/docs/api/_markup/render-link.html` will be used to render links from the Page path `/docs/api` and below.
+- `layouts/docs/baseof.html` will be used as the base template for the Page path `/docs` and below.
+- `layouts/tags/term.html` will be used for all `term` rendering in the `tags` taxonomy, except for the `blue` term, which will use `layouts/tags/blue/list.html`.
+
+## Example folder structure
+
+```text
+layouts
+├── baseof.html
+├── baseof.term.html
+├── home.html
+├── page.html
+├── section.html
+├── taxonomy.html
+├── term.html
+├── term.mylayout.en.rss.xml
+├── _markup
+│ ├── render-codeblock-go.term.mylayout.no.rss.xml
+│ └── render-link.html
+├── _partials
+│ └── mypartial.html
+├── _shortcodes
+│ ├── myshortcode.html
+│ └── myshortcode.section.mylayout.en.rss.xml
+├── docs
+│ ├── baseof.html
+│ ├── _shortcodes
+│ │ └── myshortcode.html
+│ └── api
+│ ├── mylayout.html
+│ ├── page.html
+│ └── _markup
+│ └── render-link.html
+└── tags
+ ├── taxonomy.html
+ ├── term.html
+ └── blue
+ └── list.html
+```
+
+[^type]: The `type` set in front matter will effectively replace the `section` folder in [Page path] when doing lookups.
+[^internal]: The old way of doing it made it very hard/impossible to, e.g., override `_internal/disqus.html` in a theme. Now you can just create a partial with the same name.
+
+[Example folder structure]: #example-folder-structure
+[Hugo v0.146.0]: https://github.com/gohugoio/hugo/releases/tag/v0.146.0
+[Page kinds]: https://gohugo.io/methods/page/kind/
+[Page path]: https://gohugo.io/methods/page/path/
+[template types]: /templates/types/
diff --git a/documents/markdown/hugo-docs/en_templates_pagination.md b/documents/markdown/hugo-docs/en_templates_pagination.md
new file mode 100644
index 0000000..363b18a
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_templates_pagination.md
@@ -0,0 +1,240 @@
+---
+title: Pagination
+description: Split a list page into two or more subsets.
+categories: []
+keywords: []
+weight: 160
+aliases: [/extras/pagination,/doc/pagination/]
+---
+
+Displaying a large page collection on a list page is not user-friendly:
+
+- A massive list can be intimidating and difficult to navigate. Users may get lost in the sheer volume of information.
+- Large pages take longer to load, which can frustrate users and lead to them abandoning the site.
+- Without any filtering or organization, finding a specific item becomes a tedious scrolling exercise.
+
+Improve usability by paginating `home`, `section`, `taxonomy`, and `term` pages.
+
+> [!note]
+> The most common templating mistake related to pagination is invoking pagination more than once for a given list page. See the [caching](#caching) section below.
+
+## Terminology
+
+paginate
+: To split a [list page](g) into two or more subsets.
+
+pagination
+: The process of paginating a list page.
+
+pager
+: Created during pagination, a pager contains a subset of a list page and navigation links to other pagers.
+
+paginator
+: A collection of pagers.
+
+## Configuration
+
+See [configure pagination](/configuration/pagination).
+
+## Methods
+
+To paginate a `home`, `section`, `taxonomy`, or `term` page, invoke either of these methods on the `Page` object in the corresponding template:
+
+- [`Paginate`][]
+- [`Paginator`][]
+
+The `Paginate` method is more flexible, allowing you to:
+
+- Paginate any page collection
+- Filter, sort, and group the page collection
+- Override the number of pages per pager as defined in your project configuration
+
+By comparison, the `Paginator` method paginates the page collection passed into the template, and you cannot override the number of pages per pager.
+
+## Examples
+
+To paginate a list page using the `Paginate` method:
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages.ByTitle 7 }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ partial "pagination.html" . }}
+```
+
+In the example above, we:
+
+1. Build a page collection
+1. Sort the page collection by title
+1. Paginate the page collection, with 7 pages per pager
+1. Range over the paginated page collection, rendering a link to each page
+1. Call the embedded pagination template to create navigation links between pagers
+
+To paginate a list page using the `Paginator` method:
+
+```go-html-template
+{{ range .Paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ partial "pagination.html" . }}
+```
+
+In the example above, we:
+
+1. Paginate the page collection passed into the template, with the default number of pages per pager
+1. Range over the paginated page collection, rendering a link to each page
+1. Call the embedded pagination template to create navigation links between pagers
+
+## Caching
+
+> [!note]
+> The most common templating mistake related to pagination is invoking pagination more than once for a given list page.
+
+Regardless of pagination method, the initial invocation is cached and cannot be changed. If you invoke pagination more than once for a given list page, subsequent invocations use the cached result. This means that subsequent invocations will not behave as written.
+
+When paginating conditionally, do not use the `compare.Conditional` function due to its eager evaluation of arguments. Use an `if-else` construct instead.
+
+## Grouping
+
+Use pagination with any of the [grouping methods][]. For example:
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate ($pages.GroupByDate "Jan 2006") }}
+
+{{ range $paginator.PageGroups }}
+ <h2>{{ .Key }}</h2>
+ {{ range .Pages }}
+ <h3><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h3>
+ {{ end }}
+{{ end }}
+
+{{ partial "pagination.html" . }}
+```
+
+## Navigation
+
+As shown in the examples above, the easiest way to add navigation between pagers is with Hugo's embedded pagination template:
+
+```go-html-template
+{{ partial "pagination.html" . }}
+```
+
+The embedded pagination template has two formats: `default` and `terse`. The above is equivalent to:
+
+```go-html-template
+{{ partial "pagination.html" (dict "page" . "format" "default") }}
+```
+
+The `terse` format has fewer controls and page slots, consuming less space when styled as a horizontal list. To use the `terse` format:
+
+```go-html-template
+{{ partial "pagination.html" (dict "page" . "format" "terse") }}
+```
+
+> [!note]
+> To override Hugo's embedded pagination template, copy the [source code][] to a file with the same name in the `layouts/_partials` directory, then call it from your templates using the [`partial`][] function:
+>
+> `{{ partial "pagination.html" . }}`
+
+Create custom navigation components using any of the `Pager` methods:
+
+{{% render-list-of-pages-in-section path=/methods/pager %}}
+
+## Structure
+
+The example below depicts the published site structure when paginating a list page.
+
+With this content:
+
+```text
+content/
+├── posts/
+│ ├── _index.md
+│ ├── post-1.md
+│ ├── post-2.md
+│ ├── post-3.md
+│ └── post-4.md
+└── _index.md
+```
+
+And this project configuration:
+
+{{< code-toggle file=hugo >}}
+[pagination]
+ disableAliases = false
+ pagerSize = 2
+ path = 'page'
+{{< /code-toggle >}}
+
+And this _section_ template:
+
+```go-html-template {file="layouts/section.html"}
+{{ range (.Paginate .Pages).Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ partial "pagination.html" . }}
+```
+
+The published site has this structure:
+
+```text
+public/
+├── posts/
+│ ├── page/
+│ │ ├── 1/
+│ │ │ └── index.html <-- alias to public/posts/index.html
+│ │ └── 2/
+│ │ └── index.html
+│ ├── post-1/
+│ │ └── index.html
+│ ├── post-2/
+│ │ └── index.html
+│ ├── post-3/
+│ │ └── index.html
+│ ├── post-4/
+│ │ └── index.html
+│ └── index.html
+└── index.html
+```
+
+To disable alias generation for the first pager, change your project configuration:
+
+{{< code-toggle file=hugo >}}
+[pagination]
+ disableAliases = true
+ pagerSize = 2
+ path = 'page'
+{{< /code-toggle >}}
+
+Now the published site will have this structure:
+
+```text
+public/
+├── posts/
+│ ├── page/
+│ │ └── 2/
+│ │ └── index.html
+│ ├── post-1/
+│ │ └── index.html
+│ ├── post-2/
+│ │ └── index.html
+│ ├── post-3/
+│ │ └── index.html
+│ ├── post-4/
+│ │ └── index.html
+│ └── index.html
+└── index.html
+```
+
+[`Paginate`]: /methods/page/paginate/
+[`Paginator`]: /methods/page/paginator/
+[`partial`]: /functions/partials/include/
+[grouping methods]: /quick-reference/page-collections/#group
+[source code]: <{{% eturl pagination %}}>
diff --git a/documents/markdown/hugo-docs/en_templates_partial-decorators.md b/documents/markdown/hugo-docs/en_templates_partial-decorators.md
new file mode 100644
index 0000000..ff70353
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_templates_partial-decorators.md
@@ -0,0 +1,125 @@
+---
+title: Partial decorators
+description: Use partial decorators to create reusable wrapper components that enclose and compose template content.
+categories: []
+keywords: [decorator]
+weight: 170
+---
+
+{{< new-in "0.154.0" />}}
+
+## Overview
+
+{{% glossary-term "partial decorator" %}}
+
+This approach creates a connection between two files. The calling template provides a block of code and the partial decorator determines where that code appears. This allows the partial to wrap around content without needing to know the specific markup or internal logic of the enclosed block.
+
+## Implementation
+
+To use a partial decorator, use a block-style call in your templates. The [`with`][] statement is required to initiate the partial and create a container for the content. This block can include any valid template code including page methods and functions.
+
+```go-html-template {file="layouts/home.html" copy=true}
+{{ with partial "components/wrapper.html" . }}
+ <p>Everything in this block will be wrapped.</p>
+ <p>{{ .Content | transform.Plainify | strings.Truncate 200 }}</p>
+{{ end }}
+```
+
+Inside the partial template, place the `templates.Inner` function call where the wrapped content should appear.
+
+```go-html-template {file="layouts/_partials/components/wrapper.html" copy=true}
+<div class="wrapper-styling">
+ {{ templates.Inner . }}
+</div>
+```
+
+The `with` statement creates a new [scope](g). Variables defined outside of the `with` block are not available inside it. To use external data within the wrapped content, you must ensure it is part of the [context](g) passed in the partial call.
+
+A key feature of the `templates.Inner` function is its ability to accept a context argument. By passing a context to the function, you define what the dot (`.`) represents inside the wrapped block. This ensures that the injected content has access to the correct data even when nested inside multiple layers of wrappers.
+
+## Benefits of composition
+
+Using partial decorators to build wrapper components provides several advantages:
+
+- It eliminates the need to use separate partials for opening and closing tags when encapsulating a block of code.
+- It prevents parameter bloat because a standard partial no longer requires an extensive list of arguments to account for every possible variation of the content inside it.
+- It enables clean composition where the wrapped block can execute any template logic without the wrapper needing to receive or process that data.
+
+This approach separates container logic from content logic. The wrapper handles structural requirements like specific class hierarchies or CSS grid containers. The calling template retains control over the inner markup and how data is displayed.
+
+## Example
+
+The following templates illustrate how to nest three wrapper components including a section, a column, and a card while passing context through each layer.
+
+The home template initiates the structure by calling the section, column, and card partials as decorators:
+
+```go-html-template {file="layouts/home.html" copy=true}
+{{ $ctx := dict
+ "page" .
+ "label" "Recent Posts"
+ "pageCollection" ((site.GetPage "/posts").RegularPages)
+}}
+
+{{ with partial "components/section.html" $ctx }}
+ <div class="grid-wrapper">
+ {{ range .pageCollection }}
+ {{ with partial "components/column.html" (dict "page" . "class" "col-half") }}
+ {{ with partial "components/card.html" (dict "page" .page "url" .page.RelPermalink "title" .page.LinkTitle) }}
+ <p>
+ {{ .page.Content | plainify | strings.Truncate 240 }}
+ </p>
+ {{ end }}
+ {{ end }}
+ {{ end }}
+ </div>
+{{ end }}
+```
+
+The section component provides a semantic container and an optional heading:
+
+```go-html-template {file="layouts/_partials/components/section.html" copy=true}
+<section class="content-section">
+ {{ with .label }}
+ <h2 class="section-label">{{ . }}</h2>
+ {{ end }}
+ <div class="section-content">
+ {{ templates.Inner . }}
+ </div>
+</section>
+```
+
+The column component manages layout width by applying a CSS class:
+
+```go-html-template {file="layouts/_partials/components/column.html" copy=true}
+<div class="{{ .class | default `column-default` }}">
+ {{ templates.Inner . }}
+</div>
+```
+
+The card component defines the visual boundary for the content:
+
+```go-html-template {file="layouts/_partials/components/card.html" copy=true}
+<div class="card">
+ {{ with .title }}
+ <h2 class="card-title">
+ {{ if $.url }}
+ <a href="{{ $.url }}">{{ . }}</a>
+ {{ else }}
+ {{ . }}
+ {{ end }}
+ </h2>
+ {{ end }}
+
+ <div class="card-body">
+ {{ templates.Inner . }}
+ </div>
+
+ {{ with .url }}
+ <div class="card-footer">
+ <a href="{{ . }}">Read more</a>
+ </div>
+ {{ end }}
+</div>
+```
+
+[`with`]: /functions/go-template/with/
diff --git a/documents/markdown/hugo-docs/en_templates_robots.md b/documents/markdown/hugo-docs/en_templates_robots.md
new file mode 100644
index 0000000..00ca20e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_templates_robots.md
@@ -0,0 +1,52 @@
+---
+title: robots.txt template
+linkTitle: robots.txt templates
+description: Hugo can generate a customized robots.txt in the same way as any other template.
+categories: []
+keywords: []
+weight: 190
+aliases: [/extras/robots-txt/]
+---
+
+To generate a robots.txt file from a template, change your [project configuration]:
+
+{{< code-toggle file=hugo >}}
+enableRobotsTXT = true
+{{< /code-toggle >}}
+
+By default, Hugo generates robots.txt using an [embedded template].
+
+```text
+User-agent: *
+```
+
+Search engines that honor the Robots Exclusion Protocol will interpret this as permission to crawl everything on the site.
+
+## robots.txt template lookup order
+
+You may overwrite the internal template with a custom template. Hugo selects the template using this lookup order:
+
+1. `/layouts/robots.txt`
+1. `/themes/<THEME>/layouts/robots.txt`
+
+## robots.txt template example
+
+```text {file="layouts/robots.txt"}
+User-agent: *
+{{ range .Pages }}
+Disallow: {{ .RelPermalink }}
+{{ end }}
+```
+
+This template creates a robots.txt file with a `Disallow` directive for each page on the site. Search engines that honor the Robots Exclusion Protocol will not crawl any page on the site.
+
+> [!note]
+> To create a robots.txt file without using a template:
+>
+> 1. Set `enableRobotsTXT` to `false` in your project configuration.
+> 1. Create a robots.txt file in the `static` directory.
+>
+> Remember that Hugo copies everything in the static director to the root of `publishDir` (typically `public`) when you build your project.
+
+[embedded template]: <{{% eturl robots %}}>
+[project configuration]: /configuration/
diff --git a/documents/markdown/hugo-docs/en_templates_rss.md b/documents/markdown/hugo-docs/en_templates_rss.md
new file mode 100644
index 0000000..e0c64e4
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_templates_rss.md
@@ -0,0 +1,75 @@
+---
+title: RSS templates
+description: Use the embedded RSS template, or create your own.
+categories: []
+keywords: []
+weight: 140
+---
+
+## Configuration
+
+By default, when you build your project, Hugo generates RSS feeds for home, section, taxonomy, and term pages. Control feed generation in your project configuration. For example, to generate feeds for home and section pages, but not for taxonomy and term pages:
+
+{{< code-toggle file=hugo >}}
+[outputs]
+home = ['html', 'rss']
+section = ['html', 'rss']
+taxonomy = ['html']
+term = ['html']
+{{< /code-toggle >}}
+
+To disable feed generation for all [page kinds](g):
+
+{{< code-toggle file=hugo >}}
+disableKinds = ['rss']
+{{< /code-toggle >}}
+
+By default, the number of items in each feed is unlimited. Change this as needed in your project configuration:
+
+{{< code-toggle file=hugo >}}
+[services.rss]
+limit = 42
+{{< /code-toggle >}}
+
+Set `limit` to `-1` to generate an unlimited number of items per feed.
+
+The built-in RSS template will render the following values, if present, from your project configuration:
+
+{{< code-toggle file=hugo >}}
+copyright = '© 2023 ABC Widgets, Inc.'
+[params.author]
+name = 'John Doe'
+email = 'jdoe@example.org'
+{{< /code-toggle >}}
+
+## Include feed reference
+
+To include a feed reference in the `head` element of your rendered pages, place this within the `head` element of your templates:
+
+```go-html-template
+{{ with .OutputFormats.Get "rss" }}
+ {{ printf `<link rel=%q type=%q href=%q title=%q>` .Rel .MediaType.Type .Permalink site.Title | safeHTML }}
+{{ end }}
+```
+
+Hugo will render this to:
+
+```html
+<link rel="alternate" type="application/rss+xml" href="https://example.org/index.xml" title="ABC Widgets">
+```
+
+## Custom templates
+
+Override Hugo's [embedded RSS template] by creating one or more of your own. For example, to use different templates for home, section, taxonomy, and term pages:
+
+```text
+layouts/
+ ├── home.rss.xml
+ ├── section.rss.xml
+ ├── taxonomy.rss.xml
+ └── term.rss.xml
+```
+
+RSS templates receive the `.Page` and `.Site` objects in context.
+
+[embedded RSS template]: <{{% eturl rss %}}>
diff --git a/documents/markdown/hugo-docs/en_templates_shortcode.md b/documents/markdown/hugo-docs/en_templates_shortcode.md
new file mode 100644
index 0000000..69c2f17
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_templates_shortcode.md
@@ -0,0 +1,340 @@
+---
+title: Shortcode templates
+description: Create custom shortcodes to simplify and standardize content creation.
+categories: []
+keywords: []
+weight: 120
+aliases: [/templates/shortcode-templates/]
+---
+
+{{< newtemplatesystem >}}
+
+> [!note]
+> Before creating custom shortcodes, please review the [shortcodes][] page in the [content management][] section. Understanding the usage details will help you design and create better templates.
+
+## Introduction
+
+Hugo provides [embedded shortcodes][] for many common tasks, but you'll likely need to create your own for more specific needs. Some examples of custom shortcodes you might develop include:
+
+- Audio players
+- Video players
+- Image galleries
+- Diagrams
+- Maps
+- Tables
+- And many other custom elements
+
+## Directory structure
+
+Create _shortcode_ templates within the `layouts/_shortcodes` directory, either at its root or organized into subdirectories.
+
+```text
+layouts/
+└── _shortcodes/
+ ├── diagrams/
+ │ ├── kroki.html
+ │ └── plotly.html
+ ├── media/
+ │ ├── audio.html
+ │ ├── gallery.html
+ │ └── video.html
+ ├── capture.html
+ ├── column.html
+ ├── include.html
+ └── row.html
+```
+
+When calling a shortcode in a subdirectory, specify its path relative to the `_shortcode` directory, excluding the file extension.
+
+```text
+{{</* media/audio path=/audio/podcast/episode-42.mp3 */>}}
+```
+
+## Lookup order
+
+Hugo selects _shortcode_ templates based on the shortcode name, the current output format, and the current language. The examples below are sorted by specificity in descending order. The least specific path is at the bottom of the list.
+
+Shortcode name|Output format|Language|Template path
+:--|:--|:--|:--
+foo|html|en|`layouts/_shortcodes/foo.en.html`
+foo|html|en|`layouts/_shortcodes/foo.html.html`
+foo|html|en|`layouts/_shortcodes/foo.html`
+foo|html|en|`layouts/_shortcodes/foo.html.en.html`
+
+Shortcode name|Output format|Language|Template path
+:--|:--|:--|:--
+foo|rss|en|`layouts/_shortcodes/foo.en.rss.xml`
+foo|rss|en|`layouts/_shortcodes/foo.rss.xml`
+foo|rss|en|`layouts/_shortcodes/foo.en.xml`
+foo|rss|en|`layouts/_shortcodes/foo.xml`
+
+## Methods
+
+Use these methods in your _shortcode_ templates. Refer to each methods's documentation for details and examples.
+
+{{% render-list-of-pages-in-section path=/methods/shortcode %}}
+
+## Examples
+
+These examples range in complexity from simple to moderately advanced, with some simplified for clarity.
+
+### Insert year
+
+Create a shortcode to insert the current year:
+
+```go-html-template {file="layouts/_shortcodes/year.html"}
+{{- now.Format "2006" -}}
+```
+
+Then call the shortcode from within your markup:
+
+```text {file="content/example.md"}
+This is {{</* year */>}}, and look at how far we've come.
+```
+
+This shortcode can be used inline or as a block on its own line. If a shortcode might be used inline, remove the surrounding [whitespace][] by using [template action](g) delimiters with hyphens.
+
+### Insert image
+
+This example assumes the following content structure, where `content/example/index.md` is a [page bundle](g) containing one or more [page resources](g).
+
+```text
+content/
+├── example/
+│ ├── a.jpg
+│ └── index.md
+└── _index.md
+```
+
+Create a shortcode to capture an image as a page resource, resize it to the given width, convert it to the WebP format, and add an `alt` attribute:
+
+```go-html-template {file="layouts/_shortcodes/image.html"}
+{{- with .Page.Resources.Get (.Get "path") }}
+ {{- with .Process (printf "resize %dx wepb" ($.Get "width")) -}}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="{{ $.Get "alt" }}">
+ {{- end }}
+{{- end -}}
+```
+
+Then call the shortcode from within your markup:
+
+```text {file="content/example/index.md"}
+{{</* image path=a.jpg width=300 alt="A white kitten" */>}}
+```
+
+The example above uses:
+
+- The [`with`][] statement to rebind the [context](g) after each successful operation
+- The [`Get`][] method to retrieve arguments by name
+- The `$` to access the template context
+
+> [!note]
+> Make sure that you thoroughly understand the concept of context. The most common templating errors made by new users relate to context.
+>
+> Read more about context in the [introduction to templating][].
+
+### Insert image with error handling
+
+The previous example, while functional, silently fails if the image is missing, and does not gracefully exit if a required argument is missing. We'll add error handling to address these issues:
+
+```go-html-template {file="layouts/_shortcodes/image.html"}
+{{- with .Get "path" }}
+ {{- with $r := $.Page.Resources.Get ($.Get "path") }}
+ {{- with $.Get "width" }}
+ {{- with $r.Process (printf "resize %dx wepb" ($.Get "width" )) }}
+ {{- $alt := or ($.Get "alt") "" -}}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="{{ $alt }}">
+ {{- end }}
+ {{- else }}
+ {{- errorf "The %q shortcode requires a 'width' argument: see %s" $.Name $.Position }}
+ {{- end }}
+ {{- else }}
+ {{- warnf "The %q shortcode was unable to find %s: see %s" $.Name ($.Get "path") $.Position }}
+ {{- end }}
+{{- else }}
+ {{- errorf "The %q shortcode requires a 'path' argument: see %s" .Name .Position }}
+{{- end -}}
+```
+
+This template throws an error and gracefully fails the build if the author neglected to provide a `path` or `width` argument, and it emits a warning if it cannot find the image at the specified path. If the author does not provide an `alt` argument, the `alt` attribute is set to an empty string.
+
+The [`Name`][] and [`Position`][] methods provide helpful context for errors and warnings. For example, a missing `width` argument causes the shortcode to throw this error:
+
+```text
+ERROR The "image" shortcode requires a 'width' argument: see "/home/user/project/content/example/index.md:7:1"
+```
+
+### Positional arguments
+
+Shortcode arguments can be [named or positional][]. We used named arguments previously; let's explore positional arguments. Here's the named argument version of our example:
+
+```text {file="content/example/index.md"}
+{{</* image path=a.jpg width=300 alt="A white kitten" */>}}
+```
+
+Here's how to call it with positional arguments:
+
+```text {file="content/example/index.md"}
+{{</* image a.jpg 300 "A white kitten" */>}}
+```
+
+Using the `Get` method with zero-indexed keys, we'll initialize variables with descriptive names in our template:
+
+```go-html-template {file="layouts/_shortcodes/image.html"}
+{{ $path := .Get 0 }}
+{{ $width := .Get 1 }}
+{{ $alt := .Get 2 }}
+```
+
+> [!note]
+> Positional arguments work well for frequently used shortcodes with one or two arguments. Since you'll use them often, the argument order will be easy to remember. For less frequently used shortcodes, or those with more than two arguments, named arguments improve readability and reduce the chance of errors.
+
+### Named and positional arguments
+
+You can create a shortcode that will accept both named and positional arguments, but not at the same time. Use the [`IsNamedParams`][] method to determine whether the shortcode call used named or positional arguments:
+
+```go-html-template {file="layouts/_shortcodes/image.html"}
+{{ $path := cond (.IsNamedParams) (.Get "path") (.Get 0) }}
+{{ $width := cond (.IsNamedParams) (.Get "width") (.Get 1) }}
+{{ $alt := cond (.IsNamedParams) (.Get "alt") (.Get 2) }}
+```
+
+This example uses the `cond` alias for the [`compare.Conditional`][] function to get the argument by name if `IsNamedParams` returns `true`, otherwise get the argument by position.
+
+### Argument collection
+
+Use the [`Params`][] method to access the arguments as a collection.
+
+When using named arguments, the `Params` method returns a map:
+
+```text {file="content/example/index.md"}
+{{</* image path=a.jpg width=300 alt="A white kitten" */>}}
+```
+
+```go-html-template {file="layouts/_shortcodes/image.html"}
+{{ .Params.path }} → a.jpg
+{{ .Params.width }} → 300
+{{ .Params.alt }} → A white kitten
+```
+
+ When using positional arguments, the `Params` method returns a slice:
+
+```text {file="content/example/index.md"}
+{{</* image a.jpg 300 "A white kitten" */>}}
+```
+
+```go-html-template {file="layouts/_shortcodes/image.html"}
+{{ index .Params 0 }} → a.jpg
+{{ index .Params 1 }} → 300
+{{ index .Params 1 }} → A white kitten
+```
+
+Combine the `Params` method with the [`collections.IsSet`][] function to determine if a parameter is set, even if its value is falsy.
+
+### Inner content
+
+Extract the content enclosed within shortcode tags using the [`Inner`][] method. This example demonstrates how to pass both content and a title to a shortcode. The shortcode then generates a `div` element containing an `h2` element (displaying the title) and the provided content.
+
+```text {file="content/example.md"}
+{{</* contrived title="A Contrived Example" */>}}
+This is a **bold** word, and this is an _emphasized_ word.
+{{</* /contrived */>}}
+```
+
+```go-html-template {file="layouts/_shortcodes/contrived.html"}
+<div class="contrived">
+ <h2>{{ .Get "title" }}</h2>
+ {{ .Inner | .Page.RenderString }}
+</div>
+```
+
+The preceding example called the shortcode using [standard notation][], requiring us to process the inner content with the [`RenderString`][] method to convert the Markdown to HTML. This conversion is unnecessary when calling a shortcode using [Markdown notation][].
+
+### Nesting
+
+The [`Parent`][] method provides access to the parent shortcode context when the shortcode in question is called within the context of a parent shortcode. This provides an inheritance model.
+
+The following example is contrived but demonstrates the concept. Assume you have a `gallery` shortcode that expects one named `class` argument:
+
+```go-html-template {file="layouts/_shortcodes/gallery.html"}
+<div class="{{ .Get "class" }}">
+ {{ .Inner }}
+</div>
+```
+
+You also have an `img` shortcode with a single named `src` argument that you want to call inside of `gallery` and other shortcodes, so that the parent defines the context of each `img`:
+
+```go-html-template {file="layouts/_shortcodes/img.html"}
+{{ $src := .Get "src" }}
+{{ with .Parent }}
+ <img src="{{ $src }}" class="{{ .Get "class" }}-image">
+{{ else }}
+ <img src="{{ $src }}">
+{{ end }}
+```
+
+You can then call your shortcode in your content as follows:
+
+```text {file="content/example.md"}
+{{</* gallery class="content-gallery" */>}}
+ {{</* img src="/images/one.jpg" */>}}
+ {{</* img src="/images/two.jpg" */>}}
+{{</* /gallery */>}}
+{{</* img src="/images/three.jpg" */>}}
+```
+
+This will output the following HTML. Note how the first two `img` shortcodes inherit the `class` value of `content-gallery` set with the call to the parent `gallery`, whereas the third `img` only uses `src`:
+
+```html
+<div class="content-gallery">
+ <img src="/images/one.jpg" class="content-gallery-image">
+ <img src="/images/two.jpg" class="content-gallery-image">
+</div>
+<img src="/images/three.jpg">
+```
+
+### Other examples
+
+For guidance, consider examining Hugo's embedded shortcodes. The source code, available on [GitHub][], can provide a useful model.
+
+## Detection
+
+The [`HasShortcode`][] method allows you to check if a specific shortcode has been called on a page. For example, consider a custom audio shortcode:
+
+```text {file="content/example.md"}
+{{</* audio src=/audio/test.mp3 */>}}
+```
+
+You can use the `HasShortcode` method in your base template to conditionally load CSS if the audio shortcode was used on the page:
+
+```go-html-template {file="layouts/baseof.html"}
+<head>
+ ...
+ {{ if .HasShortcode "audio" }}
+ <link rel="stylesheet" src="/css/audio.css">
+ {{ end }}
+ ...
+</head>
+```
+
+[`collections.IsSet`]: /functions/collections/isset/
+[`compare.Conditional`]: /functions/compare/conditional/
+[`Get`]: /methods/shortcode/get/
+[`HasShortcode`]: /methods/page/hasshortcode/
+[`Inner`]: /methods/shortcode/inner/
+[`IsNamedParams`]: /methods/shortcode/isnamedparams/
+[`Name`]: /methods/shortcode/name/
+[`Params`]: /methods/shortcode/params/
+[`Parent`]: /methods/shortcode/parent/
+[`Position`]: /methods/shortcode/position/
+[`RenderString`]: /methods/page/renderstring/
+[`with`]: /functions/go-template/with/
+[content management]: /content-management/shortcodes/
+[embedded shortcodes]: /shortcodes/
+[GitHub]: https://github.com/gohugoio/hugo/tree/master/tpl/tplimpl/embedded/templates/_shortcodes
+[introduction to templating]: /templates/introduction/
+[Markdown notation]: /content-management/shortcodes/#markdown-notation
+[named or positional]: /content-management/shortcodes/#arguments
+[shortcodes]: /content-management/shortcodes/
+[standard notation]: /content-management/shortcodes/#standard-notation
+[whitespace]: /templates/introduction/#whitespace
diff --git a/documents/markdown/hugo-docs/en_templates_sitemap.md b/documents/markdown/hugo-docs/en_templates_sitemap.md
new file mode 100644
index 0000000..221cb6c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_templates_sitemap.md
@@ -0,0 +1,54 @@
+---
+title: Sitemap templates
+description: Hugo provides built-in sitemap templates.
+categories: []
+keywords: []
+weight: 130
+aliases: [/layout/sitemap/,/templates/sitemap-template/]
+---
+
+## Overview
+
+Hugo's embedded sitemap templates conform to v0.9 of the [sitemap protocol].
+
+With a monolingual project, Hugo generates a sitemap.xml file in the root of the [`publishDir`] using the [embedded sitemap template].
+
+With a multilingual project, Hugo generates:
+
+- A sitemap.xml file in the root of each site (language) using the [embedded sitemap template]
+- A sitemap.xml file in the root of the [`publishDir`] using the [embedded sitemapindex template]
+
+## Configuration
+
+See [configure sitemap](/configuration/sitemap).
+
+## Override default values
+
+Override the default values for a given page in front matter.
+
+{{< code-toggle file=news.md fm=true >}}
+title = 'News'
+[sitemap]
+ changefreq = 'weekly'
+ disable = true
+ priority = 0.8
+{{</ code-toggle >}}
+
+## Override built-in templates
+
+To override the built-in sitemap.xml template, create a new `layouts/sitemap.xml` file. When ranging through the page collection, access the _change frequency_ and _priority_ with `.Sitemap.ChangeFreq` and `.Sitemap.Priority` respectively.
+
+To override the built-in sitemapindex.xml template, create a new `layouts/sitemapindex.xml` file.
+
+## Disable sitemap generation
+
+You may disable sitemap generation in your project configuration:
+
+{{< code-toggle file=hugo >}}
+disableKinds = ['sitemap']
+{{</ code-toggle >}}
+
+[`publishDir`]: /configuration/all/#publishdir
+[embedded sitemap template]: <{{% eturl sitemap %}}>
+[embedded sitemapindex template]: <{{% eturl sitemapindex %}}>
+[sitemap protocol]: https://www.sitemaps.org/protocol.html
diff --git a/documents/markdown/hugo-docs/en_templates_types.md b/documents/markdown/hugo-docs/en_templates_types.md
new file mode 100644
index 0000000..ce9ef98
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_templates_types.md
@@ -0,0 +1,404 @@
+---
+title: Template types
+description: Create templates of different types to render your content, resources, and data.
+categories: []
+keywords: []
+weight: 30
+aliases: [
+ '/templates/base/',
+ '/templates/content-view/',
+ '/templates/home/',
+ '/templates/lists/',
+ '/templates/partial/',
+ '/templates/section/',
+ '/templates/single/',
+ '/templates/taxonomy/',
+ '/templates/term/',
+]
+---
+
+## Structure
+
+Create templates in the `layouts` directory in the root of your project.
+
+Although your site may not require each of these templates, the example below is typical for a site of medium complexity.
+
+```text
+layouts/
+├── _markup/
+│ ├── render-image.html <-- render hook
+│ └── render-link.html <-- render hook
+├── _partials/
+│ ├── footer.html
+│ └── header.html
+├── _shortcodes/
+│ ├── audio.html
+│ └── video.html
+├── books/
+│ ├── page.html
+│ └── section.html
+├── films/
+│ ├── view_card.html <-- content view
+│ ├── view_li.html <-- content view
+│ ├── page.html
+│ └── section.html
+├── baseof.html
+├── home.html
+├── page.html
+├── section.html
+├── taxonomy.html
+└── term.html
+```
+
+Hugo's [template lookup order] determines the template path, allowing you to create unique templates for any page.
+
+> [!note]
+> You must have thorough understanding of the template lookup order when creating templates. Template selection is based on template type, page kind, content type, section, language, and output format.
+
+The purpose of each template type is described below.
+
+## Base
+
+A _base_ template serves as a foundational layout that other templates can build upon. It typically defines the common structural components of your HTML, such as the `html`, `head`, and `body` elements. It also often includes recurring features like headers, footers, navigation, and script inclusions that appear across multiple pages of your site. By defining these common aspects once in a _base_ template, you avoid redundancy, ensure consistency, and simplify the maintenance of your website.
+
+Hugo can apply a _base_ template to the following template types: [home](#home), [page](#page), [section](#section), [taxonomy](#taxonomy), [term](#term), [single](#single), [list](#list), and [all](#all). When Hugo parses any of these template types, it will apply a _base_ template only if the template being parsed meets these specific conditions:
+
+- It must include at least one [`define`] [action](g).
+- It can only contain `define` actions, whitespace, and [template comments]. No other content is allowed.
+
+> [!note]
+> If a template doesn't meet all these criteria, Hugo executes it exactly as provided, without applying a _base_ template.
+
+When Hugo applies a _base_ template, it replaces its [`block`] actions with content from the corresponding `define` actions found in the template to which the base template is applied.
+
+For example, the _base_ template below calls the [`partial`] function to include `head`, `header`, and `footer` elements. The `block` action acts as a placeholder, and its content will be replaced by a matching `define` action from the template to which it is applied.
+
+```go-html-template {file="layouts/baseof.html"}
+<!DOCTYPE html>
+<html lang="{{ site.Language.Locale }}" dir="{{ or site.Language.Direction `ltr` }}">
+<head>
+ {{ partial "head.html" . }}
+</head>
+<body>
+ <header>
+ {{ partial "header.html" . }}
+ </header>
+ <main>
+ {{ block "main" . }}
+ This will be replaced with content from the
+ corresponding "define" action found in the template
+ to which this base template is applied.
+ {{ end }}
+ </main>
+ <footer>
+ {{ partial "footer.html" . }}
+ </footer>
+</body>
+</html>
+```
+
+```go-html-template {file="layouts/home.html"}
+{{ define "main" }}
+ This will replace the content of the "block" action
+ found in the base template.
+{{ end }}
+```
+
+## Home
+
+A _home_ template renders your site's home page.
+
+For example, Hugo applies a _base_ template to the _home_ template below, then renders the page content and a list of the site's regular pages.
+
+```go-html-template {file="layouts/home.html"}
+{{ define "main" }}
+ {{ .Content }}
+ {{ range .Site.RegularPages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ end }}
+{{ end }}
+```
+
+{{% include "/_common/filter-sort-group.md" %}}
+
+## Page
+
+A _page_ template renders a regular page.
+
+For example, Hugo applies a _base_ template to the _page_ template below, then renders the page title and page content.
+
+```go-html-template {file="layouts/page.html"}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+{{ end }}
+```
+
+## Section
+
+A _section_ template renders a list of pages within a [section](g).
+
+For example, Hugo applies a _base_ template to the _section_ template below, then renders the page title, page content, and a list of pages in the current section.
+
+```go-html-template {file="layouts/section.html"}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+ {{ range .Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ end }}
+{{ end }}
+```
+
+{{% include "/_common/filter-sort-group.md" %}}
+
+## Taxonomy
+
+A _taxonomy_ template renders a list of terms in a [taxonomy](g).
+
+For example, Hugo applies a _base_ template to the _taxonomy_ template below, then renders the page title, page content, and a list of [terms](g) in the current taxonomy.
+
+```go-html-template {file="layouts/taxonomy.html"}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+ {{ range .Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ end }}
+{{ end }}
+```
+
+{{% include "/_common/filter-sort-group.md" %}}
+
+Within a _taxonomy_ template, the [`Data`] object provides these taxonomy-specific methods:
+
+- [`Singular`][taxonomy-singular]
+- [`Plural`][taxonomy-plural]
+- [`Terms`]
+
+The `Terms` method returns a [taxonomy object](g), allowing you to call any of its methods including [`Alphabetical`] and [`ByCount`]. For example, use the `ByCount` method to render a list of terms sorted by the number of pages associated with each term:
+
+```go-html-template {file="layouts/taxonomy.html"}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+ {{ range .Data.Terms.ByCount }}
+ <h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a> ({{ .Count }})</h2>
+ {{ end }}
+{{ end }}
+```
+
+## Term
+
+A _term_ template renders a list of pages associated with a [term](g).
+
+For example, Hugo applies a _base_ template to the _term_ template below, then renders the page title, page content, and a list of pages associated with the current term.
+
+```go-html-template {file="layouts/term.html"}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+ {{ range .Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ end }}
+{{ end }}
+```
+
+{{% include "/_common/filter-sort-group.md" %}}
+
+Within a _term_ template, the [`Data`] object provides these term-specific methods:
+
+- [`Singular`][term-singular]
+- [`Plural`][term-plural]
+- [`Term`]
+
+## Single
+
+A _single_ template is a fallback for a _page_ template. If a _page_ template does not exist, Hugo will look for a _single_ template instead.
+
+For example, Hugo applies a _base_ template to the _single_ template below, then renders the page title and page content.
+
+```go-html-template {file="layouts/single.html"}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+{{ end }}
+```
+
+## List
+
+A _list_ template is a fallback for [home](#home), [section](#section), [taxonomy](#taxonomy), and [term](#term) templates. If one of these template types does not exist, Hugo will look for a _list_ template instead.
+
+For example, Hugo applies a _base_ template to the _list_ template below, then renders the page title, page content, and a list of pages.
+
+```go-html-template {file="layouts/list.html"}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+ {{ range .Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ end }}
+{{ end }}
+```
+
+## All
+
+An _all_ template is a fallback for [home](#home), [page](#page), [section](#section), [taxonomy](#taxonomy), [term](#term), [single](#single), and [list](#list) templates. If one of these template types does not exist, Hugo will look for an _all_ template instead.
+
+For example, Hugo applies a _base_ template to the _all_ template below, then conditionally renders a page based on its page kind.
+
+```go-html-template {file="layouts/all.html"}
+{{ define "main" }}
+ {{ if eq .Kind "home" }}
+ {{ .Content }}
+ {{ range .Site.RegularPages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ end }}
+ {{ else if eq .Kind "page" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+ {{ else if in (slice "section" "taxonomy" "term") .Kind }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+ {{ range .Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ end }}
+ {{ else }}
+ {{ errorf "Unsupported page kind: %s" .Kind }}
+ {{ end }}
+{{ end }}
+```
+
+## Partial
+
+A _partial_ template is typically used to render a component of your site, though you may also create _partial_ templates that return values.
+
+For example, the _partial_ template below renders copyright information:
+
+```go-html-template {file="layouts/_partials/footer.html"}
+<p>Copyright {{ now.Year }}. All rights reserved.</p>
+```
+
+Execute the _partial_ template by calling the [`partial`] or [`partialCached`] function, optionally passing context as the second argument:
+
+```go-html-template {file="layouts/baseof.html"}
+{{ partial "footer.html" . }}
+```
+
+<!-- https://github.com/gohugoio/hugo/pull/13614#issuecomment-2805977008 -->
+Unlike other template types, Hugo does not consider the current page kind, content type, logical path, language, or output format when searching for a matching _partial_ template. However, it _does_ apply the same _name_ matching logic it uses for other template types. This means it tries to find the most specific match first, then progressively looks for more general versions if the specific one isn't found.
+
+For example, with this call:
+
+```go-html-template {file="layouts/baseof.html"}
+{{ partial "footer.section.de.html" . }}
+```
+
+Hugo uses this lookup order to find a matching template:
+
+1. `layouts/_partials/footer.section.de.html`
+1. `layouts/_partials/footer.section.html`
+1. `layouts/_partials/footer.de.html`
+1. `layouts/_partials/footer.html`
+
+A _partial_ template can also be defined inline within another template. However, it's important to note that the template namespace is global; ensuring unique names for these _partial_ templates is necessary to prevent conflicts.
+
+```go-html-template
+Value: {{ partial "my-inline-partial.html" . }}
+
+{{ define "_partials/my-inline-partial.html" }}
+ {{ $value := 32 }}
+ {{ return $value }}
+{{ end }}
+```
+
+## Content view
+
+A _content view_ template is similar to a _partial_ template, invoked by calling the [`Render`] method on a `Page` object. Unlike _partial_ templates, _content view_ templates:
+
+- Inherit the context of the current page
+- Can target any page kind, content type, logical path, language, or output format
+- Can reside at any level within the `layouts` directory
+
+For example, Hugo applies a _base_ template to the _home_ template below, then renders the page content and a card component for each page within the "films" section of your site.
+
+```go-html-template {file="layouts/home.html"}
+{{ define "main" }}
+ {{ .Content }}
+ <ul>
+ {{ range where site.RegularPages "Section" "films" }}
+ {{ .Render "view_card" }}
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+```go-html-template {file="layouts/films/view_card.html"}
+<div class="card">
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ .Summary }}
+</div>
+```
+
+In the example above, the content view template's name starts with `view_`. While not strictly required, this naming convention helps distinguish content view templates from other templates within the same directory, improving organization and clarity.
+
+## Render hook
+
+A _render hook_ template overrides the conversion of Markdown to HTML.
+
+For example, the _render hook_ template below adds an anchor link to the right of each heading.
+
+```go-html-template {file="layouts/_markup/render-heading.html"}
+<h{{ .Level }} id="{{ .Anchor }}" {{- with .Attributes.class }} class="{{ . }}" {{- end }}>
+ {{ .Text }}
+ <a href="#{{ .Anchor }}">#</a>
+</h{{ .Level }}>
+```
+
+Learn more about [render hook templates](/render-hooks/).
+
+## Shortcode
+
+A _shortcode_ template is used to render a component of your site. Unlike _partial_ or _content view_ templates, _shortcode_ templates are called from content pages.
+
+For example, the _shortcode_ template below renders an audio element from a [global resource](g).
+
+```go-html-template {file="layouts/_shortcodes/audio.html"}
+{{ with resources.Get (.Get "src") }}
+ <audio controls preload="auto" src="{{ .RelPermalink }}"></audio>
+{{ end }}
+```
+
+Then call the shortcode from within markup:
+
+```text {file="content/example.md"}
+{{</* audio src=/audio/test.mp3 */>}}
+```
+
+Learn more about [shortcode templates](/templates/shortcode/).
+
+## Other
+
+Use other specialized templates to create:
+
+- [Sitemaps](/templates/sitemap)
+- [RSS feeds](/templates/rss/)
+- [404 error pages](/templates/404/)
+- [robots.txt files](/templates/robots/)
+
+[`Alphabetical`]: /methods/taxonomy/alphabetical/
+[`block`]: /functions/go-template/block/
+[`ByCount`]: /methods/taxonomy/bycount/
+[`Data`]: /methods/page/data/
+[`define`]: /functions/go-template/define/
+[`partial`]: /functions/partials/include/
+[`partialCached`]: /functions/partials/includeCached/
+[`Render`]: /methods/page/render/
+[`Term`]: /methods/page/data/#term
+[`Terms`]: /methods/page/data/#terms
+[taxonomy-plural]: /methods/page/data/#plural
+[taxonomy-singular]: /methods/page/data/#singular
+[template comments]: /templates/introduction/#comments
+[template lookup order]: /templates/lookup-order/
+[term-plural]: /methods/page/data/#plural-1
+[term-singular]: /methods/page/data/#singular-1
diff --git a/documents/markdown/hugo-docs/en_tools__index.md b/documents/markdown/hugo-docs/en_tools__index.md
new file mode 100644
index 0000000..3acc287
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_tools__index.md
@@ -0,0 +1,7 @@
+---
+title: Developer tools
+description: Third-party tools to help you create and manage sites.
+categories: []
+keywords: []
+weight: 10
+---
diff --git a/documents/markdown/hugo-docs/en_tools_editors.md b/documents/markdown/hugo-docs/en_tools_editors.md
new file mode 100644
index 0000000..4679ec0
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_tools_editors.md
@@ -0,0 +1,63 @@
+---
+title: Editor plugins
+description: The Hugo community uses a wide range of tools and has developed plugins for some of the most popular text editors to help automate parts of your workflow.
+categories: []
+keywords: []
+weight: 10
+---
+
+## Visual Studio Code
+
+[Front Matter](https://marketplace.visualstudio.com/items?itemName=eliostruyf.vscode-front-matter)
+: Once you go for a static site, you need to think about how you are going to manage your articles. Front matter is a tool that helps you maintain the metadata/front matter of your articles like: creation date, modified date, slug, tile, SEO check, and more.
+
+[Hugo Helper](https://marketplace.visualstudio.com/items?itemName=rusnasonov.vscode-hugo)
+: Hugo Helper is a plugin for Visual Studio Code that has some useful commands for Hugo. The source code can be found on its [GitHub repository](https://github.com/rusnasonov/vscode-hugo).
+
+[Hugo Language and Syntax Support](https://marketplace.visualstudio.com/items?itemName=budparr.language-hugo-vscode)
+: Hugo Language and Syntax Support is a Visual Studio Code plugin for Hugo syntax highlighting and snippets. The source code can be found on its [GitHub repository](https://github.com/budparr/language-hugo-vscode).
+
+[Hugo Themer](https://marketplace.visualstudio.com/items?itemName=eliostruyf.vscode-hugo-themer)
+: Hugo Themer is an extension to help you while developing themes. It allows you to easily navigate through your theme files.
+
+[Hugofy](https://marketplace.visualstudio.com/items?itemName=akmittal.hugofy)
+: Hugofy is a plugin for Visual Studio Code to "make life easier" when developing with Hugo. The source code can be found on its [GitHub repository](https://github.com/akmittal/hugofy-vscode).
+
+[Prettier Plugin for Go Templates](https://github.com/NiklasPor/prettier-plugin-go-template)
+: Format Hugo templates using this [Prettier](https://prettier.io/) plugin. See [installation instructions](https://discourse.gohugo.io/t/38403).
+
+[Syntax Highlighting for Hugo Shortcodes](https://marketplace.visualstudio.com/items?itemName=kaellarkin.hugo-shortcode-syntax)
+: This extension adds some syntax highlighting for Shortcodes, making visual identification of individual pieces easier.
+
+## JetBrains IDEs
+
+[Smart Hugo](https://smarthugo.dev)
+: Plugin for IntelliJ IDEA, WebStorm, PhpStorm, and other JetBrains IDEs that adds Hugo template support including syntax highlighting, actions completion, code formatting, and optional advanced features.
+
+## Emacs
+
+[emacs-easy-hugo](https://github.com/masasam/emacs-easy-hugo)
+: Emacs major mode for managing hugo blogs. Note that Hugo also supports [Org-mode][formats].
+
+[ox-hugo.el](https://ox-hugo.scripter.co)
+: Native Org-mode exporter that exports to Blackfriday Markdown with Hugo front-matter. `ox-hugo` supports two common Org blogging flows --- exporting multiple Org subtrees in a single file to multiple Hugo posts, and exporting a single Org file to a single Hugo post. It also leverages the Org tag and property inheritance features. See [Why ox-hugo?](https://ox-hugo.scripter.co/doc/why-ox-hugo/) for more.
+
+## Sublime Text
+
+[Hugofy](https://github.com/akmittal/Hugofy)
+: Hugofy is a plugin for Sublime Text 3 to make life easier to use Hugo static site generator.
+
+[Hugo Snippets](https://packagecontrol.io/packages/Hugo%20Snippets)
+: Hugo Snippets is a useful plugin for adding automatic snippets to Sublime Text 3.
+
+## Vim
+
+[Vim Hugo Helper]: https://github.com/robertbasic/vim-hugo-helper
+
+[Vim Hugo Helper]
+: A small Vim plugin that facilitates authoring pages and blog posts with Hugo.
+
+[vim-hugo](https://github.com/phelipetls/vim-hugo)
+: A Vim plugin with syntax highlighting for templates and a few other features.
+
+[formats]: /content-management/formats/
diff --git a/documents/markdown/hugo-docs/en_tools_front-ends.md b/documents/markdown/hugo-docs/en_tools_front-ends.md
new file mode 100644
index 0000000..8afb61b
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_tools_front-ends.md
@@ -0,0 +1,37 @@
+---
+title: Front-end interfaces
+linkTitle: Front-ends
+description: Do you prefer a graphical user interface over a text editor? Give these front-ends a try.
+categories: []
+keywords: []
+weight: 20
+aliases: [/tools/frontends/]
+---
+
+## Commercial
+
+[CloudCannon](https://cloudcannon.com/hugo-cms/)
+: The intuitive Git-based CMS for your Hugo website. CloudCannon syncs changes from your Git repository and pushes content changes back, so your development and content teams are always in sync. Edit all of your content on the page with visual editing, build entire pages with reusable custom components and then publish confidently.
+
+[DatoCMS](https://www.datocms.com)
+: DatoCMS is a fully customizable administrative area for your static websites. Use your favorite website generator, let your clients publish new content independently, and the host the site anywhere you like.
+
+[PubCrank](https://www.pubcrank.com/)
+: PubCrank is a static site editor which lets you define templates for different front matter layouts in your site. This gives writers an easy-to-use visual interface to create and edit content while maintaining the guardrails that the developer has created. PubCrank is free for local editing.
+
+[Sitepins](https://sitepins.com)
+: Sitepins is a Git-based CMS built for static site generators like Hugo. It offers a clean visual editor, media management, role-based permissions, shortcode support, and more. To get started, simply connect your GitHub repository, configure your content folders, and start visually editing your Hugo site with Sitepins.
+
+## Open-source
+
+[Decap CMS](https://decapcms.org/)
+: Decap CMS is an open-source, serverless solution for managing Git based content in static sites, and it works on any platform that can host static sites. A [Hugo/Decap CMS starter](https://github.com/decaporg/one-click-hugo-cms) is available to get new projects running quickly.
+
+[Pages CMS](https://pagescms.org/)
+: Pages CMS is an open-source, Git-based CMS for static sites and apps. It lets you edit Hugo content stored in a GitHub repository through a web interface, with support for front matter fields, media management, rich text editing, etc.
+
+[Quiqr Desktop](https://quiqr.org/)
+: Quiqr Desktop is a open-source, cross-platform, offline desktop CMS for Hugo with built-in Git functionality for deploying static sites to any hosting server.
+
+[Sveltia CMS](https://github.com/sveltia/sveltia-cms/)
+: Sveltia CMS is a drop-in replacement for Decap CMS which is built from the ground up with powerful and performant modern UI library Svelte. Sveltia CMS incorporates i18n into every corner of the product, while striving to radically improve UX, performance and productivity.
diff --git a/documents/markdown/hugo-docs/en_tools_migrations.md b/documents/markdown/hugo-docs/en_tools_migrations.md
new file mode 100644
index 0000000..0af57aa
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_tools_migrations.md
@@ -0,0 +1,103 @@
+---
+title: Migrate to Hugo
+linkTitle: Migrations
+description: A list of community-developed tools for migrating from your existing static site generator or content management system to Hugo.
+categories: []
+keywords: []
+weight: 40
+aliases: [/developer-tools/migrations/, /developer-tools/migrated/]
+---
+
+This section highlights some independently developed projects related to Hugo. These tools extend functionality or help you to get started.
+
+Take a look at this list of migration tools if you currently use other blogging tools like Jekyll or WordPress but intend to switch to Hugo instead. They'll help you export your content into Hugo-friendly formats.
+
+## Jekyll
+
+Alternatively, you can use the [Jekyll import command](/commands/hugo_import_jekyll/).
+
+[JekyllToHugo](https://github.com/fredrikloch/JekyllToHugo)
+: A Small script for converting Jekyll blog posts to a Hugo site.
+
+[ConvertToHugo](https://github.com/coderzh/ConvertToHugo)
+: Convert your blog from Jekyll to Hugo.
+
+## Octopress
+
+[octohug](https://github.com/codebrane/octohug)
+: Octopress to Hugo migrator.
+
+## DokuWiki
+
+[dokuwiki-to-hugo](https://github.com/wgroeneveld/dokuwiki-to-hugo)
+: Migrates your DokuWiki source pages from [DokuWiki syntax](https://www.dokuwiki.org/wiki:syntax) to Hugo Markdown syntax. Includes extras like the TODO plugin. Written with extensibility in mind using Python 3. Also generates a TOML header for each page. Designed to copy-paste the wiki directory into your `content` directory.
+
+## WordPress
+
+[wordpress-to-hugo-exporter](https://github.com/SchumacherFM/wordpress-to-hugo-exporter)
+: A one-click WordPress plugin that converts all posts, pages, taxonomies, metadata, and settings to Markdown and YAML which can be dropped into Hugo. (Note: If you have trouble using this plugin, you can [export your site for Jekyll](https://wordpress.org/plugins/jekyll-exporter/) and use Hugo's built-in Jekyll converter listed above.)
+
+[blog2md](https://github.com/palaniraja/blog2md)
+: Works with [exported xml](https://en.support.wordpress.com/export/) file of your free YOUR-TLD.wordpress.com website. It also saves approved comments to `YOUR-POST-NAME-comments.md` file along with posts.
+
+[wordhugopress](https://github.com/nantipov/wordhugopress)
+: A small utility written in Java that exports the entire WordPress site from the database and resource (e.g., images) files stored locally or remotely. Therefore, migration from the backup files is possible. Supports merging multiple WordPress sites into a single Hugo site.
+
+[wp2hugo](https://github.com/ashishb/wp2hugo)
+: A Go-based CLI tool to migrate WordPress websites to Hugo. It preserves original URLs, GUIDs, image URLs, code highlights, tables of contents, and WordPress navigation categories. It migrates WordPress custom post types, custom taxonomies, custom fields, and page hierarchy. It supports translated WordPress blogs via Polylang or WPML. It imports a WordPress media library database with original titles and dates. The tool can download all media or only media inserted into pages from the original server. It converts WordPress shortcodes and Gutenberg blocks to Hugo shortcodes including galleries, images, audio, YouTube embeds, Gists, and Google Maps.
+
+## Medium
+
+[medium2md](https://github.com/gautamdhameja/medium-2-md)
+: A simple Medium to Hugo exporter able to import stories in one command, including front matter.
+
+[medium-to-hugo](https://github.com/bgadrian/medium-to-hugo)
+: A CLI tool written in Go to export medium posts into a Hugo-compatible Markdown format. Tags and images are included. All images will be downloaded locally and linked appropriately.
+
+## Tumblr
+
+[tumblr-importr](https://github.com/carlmjohnson/tumblr-importr)
+: An importer that uses the Tumblr API to create a Hugo static site.
+
+[tumblr2hugomarkdown](https://github.com/Wysie/tumblr2hugomarkdown)
+: Export all your Tumblr content to Hugo Markdown files with preserved original formatting.
+
+[Tumblr to Hugo](https://github.com/jipiboily/tumblr-to-hugo)
+: A migration tool that converts each of your Tumblr posts to a content file with a proper title and path. It also generates a CSV file to help you set up URL redirects.
+
+## Drupal
+
+[drupal2hugo](https://github.com/danapsimer/drupal2hugo)
+: Convert a Drupal site to Hugo.
+
+## Joomla
+
+[hugojoomla](https://github.com/davetcc/hugojoomla)
+: This utility written in Java takes a Joomla database and converts all the content into Markdown files. It changes any URLs that are in Joomla's internal format and converts them to a suitable form.
+
+## Blogger
+
+[blogimport](https://github.com/natefinch/blogimport)
+: A tool to import from Blogger posts to Hugo.
+
+[blogger-to-hugo](https://pypi.org/project/blogger-to-hugo/)
+: Another tool to import Blogger posts to Hugo. It also downloads embedded images so they will be stored locally.
+
+[blog2md](https://github.com/palaniraja/blog2md)
+: Works with [exported xml](https://support.google.com/blogger/answer/41387?hl=en) file of your YOUR-TLD.blogspot.com website. It also saves comments to `YOUR-POST-NAME-comments.md` file along with posts.
+
+[BloggerToHugo](https://github.com/huanlin/blogger-to-hugo)
+: Yet another tool to import Blogger posts to Hugo. For Windows platform only, and .NET Framework 4.5 is required. See README.md before using this tool.
+
+[blogger2hugo](https://github.com/noorkhafidzin/blogger2hugo)
+: Converts a Blogger backup file (`.atom`) from [Google Takeout](https://takeout.google.com/takeout/custom/blogger?hl=en) to Markdown (`.md`) files. The tool generates output compatible with the Hugo `content/` structure.
+
+## Contentful
+
+[contentful-hugo](https://github.com/ModiiMedia/contentful-hugo)
+: A tool to create content-files for Hugo from content on [Contentful](https://www.contentful.com/).
+
+## BlogML
+
+[BlogML2Hugo](https://github.com/jijiechen/BlogML2Hugo)
+: A tool that helps you convert BlogML xml file to Hugo Markdown files. Users need to take care of links to attachments and images by themselves. This helps the blogs that export BlogML files (e.g. BlogEngine.NET) transform to hugo sites easily.
diff --git a/documents/markdown/hugo-docs/en_tools_other.md b/documents/markdown/hugo-docs/en_tools_other.md
new file mode 100644
index 0000000..052041c
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_tools_other.md
@@ -0,0 +1,20 @@
+---
+title: Other community projects
+linkTitle: Other projects
+description: Some interesting projects developed by the Hugo community that don't quite fit into our other developer tool categories.
+categories: []
+keywords: []
+weight: 50
+---
+
+And for all the other community projects around Hugo:
+
+- [diego](https://github.com/ttybitnik/diego) - A CLI tool that integrates with Hugo to assist in importing and utilizing exported social media data from popular services on Hugo websites.
+- [Emacs Easy Hugo](https://github.com/masasam/emacs-easy-hugo) - Emacs package for writing blog posts in Markdown or org-mode and building your project with Hugo.
+- [Hugo SFTP Upload](https://github.com/thomasmey/HugoSftpUpload) - Sync the local build of your Hugo website with your remote web server via SFTP.
+- [HugoPhotoSwipe](https://github.com/GjjvdBurg/HugoPhotoSwipe) - Make it easy to create image galleries using PhotoSwipe.
+- [JAMStack Themes](https://jamstackthemes.dev/ssg/hugo/) - A collection of site themes filterable by static site generator and supported CMS to help build CMS-connected sites using Hugo (linking to Hugo-specific themes).
+- [flickr-hugo-embed](https://github.com/nikhilm/flickr-hugo-embed) - Print shortcodes to embed a set of images from an album on Flickr into Hugo.
+- [hugo-gallery](https://github.com/icecreammatt/hugo-gallery) - Create an image gallery for Hugo sites.
+- [hugo-openapispec-shortcode](https://github.com/tenfourty/hugo-openapispec-shortcode) - A shortcode that allows you to include [Open API Spec](https://openapis.org) (formerly known as Swagger Spec) in a page.
+- [plausible-hugo](https://github.com/divinerites/plausible-hugo) - Easy Hugo integration for Plausible Analytics, a simple, open-source, lightweight and privacy-friendly web analytics alternative to Google Analytics.
diff --git a/documents/markdown/hugo-docs/en_tools_search.md b/documents/markdown/hugo-docs/en_tools_search.md
new file mode 100644
index 0000000..2c392c7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_tools_search.md
@@ -0,0 +1,53 @@
+---
+title: Search tools
+linkTitle: Search
+description: See some of the open-source and commercial search options for your newly created Hugo website.
+categories: []
+keywords: []
+weight: 30
+---
+
+A static website with a dynamic search function? Yes, Hugo provides an alternative to embeddable scripts from Google or other search engines for static websites. Hugo allows you to provide your visitors with a custom search function by indexing your content files directly.
+
+## Open-source
+
+[Pagefind](https://github.com/cloudcannon/pagefind)
+: A fully static search library that aims to perform well on large sites, while using as little of your users' bandwidth as possible.
+
+[GitHub Gist for Hugo Workflow](https://gist.github.com/sebz/efddfc8fdcb6b480f567)
+: This gist contains a simple workflow to create a search index for your static website. It uses a simple Grunt script to index all your content files and [lunr.js](https://lunrjs.com/) to serve the search results.
+
+[hugo-lunr](https://www.npmjs.com/package/hugo-lunr)
+: A simple way to add site search to your static Hugo site using [lunr.js](https://lunrjs.com/). Hugo-lunr will create an index file of any HTML and Markdown documents in your Hugo project.
+
+[hugo-lunr-zh](https://www.npmjs.com/package/hugo-lunr-zh)
+: A bit like Hugo-lunr, but Hugo-lunr-zh can help you separate the Chinese keywords.
+
+[GitHub Gist for Fuse.js integration](https://gist.github.com/eddiewebb/735feb48f50f0ddd65ae5606a1cb41ae)
+: This gist demonstrates how to leverage Hugo's existing build time processing to generate a searchable JSON index used by [Fuse.js](https://fusejs.io/) on the client side. Although this gist uses Fuse.js for fuzzy matching, any client-side search tool capable of reading JSON indexes will work. Does not require npm, grunt, or other build-time tools except Hugo!
+
+[hugo-search-index](https://www.npmjs.com/package/hugo-search-index)
+: A library containing Gulp tasks and a prebuilt browser script that implements search. Gulp generates a search index from project Markdown files.
+
+[hugofastsearch](https://gist.github.com/cmod/5410eae147e4318164258742dd053993)
+: A usability and speed update to "GitHub Gist for Fuse.js integration" — global, keyboard-optimized search.
+
+[JS & Fuse.js tutorial](https://makewithhugo.com/add-search-to-a-hugo-site/)
+: A simple client-side search solution, using FuseJS (does not require jQuery).
+
+[Hugo Lyra](https://github.com/paolomainardi/hugo-lyra)
+: Hugo-Lyra is a JavaScript module to integrate [Lyra](https://github.com/LyraSearch/lyra) into a Hugo website. It contains the server-side part to generate the index and the client-side library (optional) to bootstrap the search engine easily.
+
+[INFINI Pizza for WebAssembly](https://github.com/infinilabs/pizza-docsearch)
+: Pizza is a super-lightweight yet fully featured search engine written in Rust. You can quickly add offline search functionality to your Hugo website in just five minutes with only three lines of code. For a step-by-step guide on integrating it with Hugo, check out [this blog tutorial](https://dev.to/medcl/adding-search-functionality-to-a-hugo-static-site-based-on-infini-pizza-for-webassembly-4h5e).
+
+## Commercial
+
+[Algolia DocSearch](https://docsearch.algolia.com/)
+: Algolia DocSearch is free for public technical documentation sites and easy to set up. For other use cases, [Algolia's Search API](https://www.algolia.com) makes it easy to deliver a great search experience in your apps and websites. Algolia Search provides hosted full-text, numerical, faceted, and geolocalized search.
+
+[Bonsai](https://www.bonsai.io)
+: Bonsai is a fully-managed hosted Elasticsearch service that is fast, reliable, and simple to set up. Easily ingest your docs from Hugo into Elasticsearch following [this guide from the docs](https://bonsai.io/docs/hugo).
+
+[ExpertRec](https://www.expertrec.com/)
+: ExpertRec is a hosted search-as-a-service solution that is fast and scalable. Set-up and integration is extremely easy and takes only a few minutes. The search settings can be modified without coding using a dashboard.
diff --git a/documents/markdown/hugo-docs/en_troubleshooting__index.md b/documents/markdown/hugo-docs/en_troubleshooting__index.md
new file mode 100644
index 0000000..fd51b4f
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_troubleshooting__index.md
@@ -0,0 +1,8 @@
+---
+title: Troubleshooting
+description: Use these techniques when troubleshooting your site.
+categories: []
+keywords: []
+weight: 10
+aliases: [/templates/template-debugging/]
+---
diff --git a/documents/markdown/hugo-docs/en_troubleshooting_audit_index.md b/documents/markdown/hugo-docs/en_troubleshooting_audit_index.md
new file mode 100644
index 0000000..a20b336
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_troubleshooting_audit_index.md
@@ -0,0 +1,68 @@
+---
+title: Site audit
+linkTitle: Audit
+description: Run this audit before deploying your production site.
+categories: []
+keywords: []
+---
+
+There are several conditions that can produce errors in your published site which are not detected during the build. Run this audit before your final build.
+
+```text {copy=true}
+HUGO_MINIFY_TDEWOLFF_HTML_KEEPCOMMENTS=true HUGO_ENABLEMISSINGTRANSLATIONPLACEHOLDERS=true hugo && grep -inorE "<\!-- raw HTML omitted -->|ZgotmplZ|\[i18n\]|\(<nil>\)|(<nil>)|hahahugo" public/
+```
+
+_Tested with GNU Bash 5.1 and GNU grep 3.7._
+
+## Example output
+
+
+
+## Explanation
+
+### Environment variables
+
+`HUGO_MINIFY_TDEWOLFF_HTML_KEEPCOMMENTS=true`
+: Retain HTML comments even if minification is enabled. This takes precedence over `minify.tdewolff.html.keepComments` in your project configuration. If you minify without keeping HTML comments when performing this audit, you will not be able to detect when raw HTML has been omitted.
+
+`HUGO_ENABLEMISSINGTRANSLATIONPLACEHOLDERS=true`
+: Show a placeholder instead of the default value or an empty string if a translation is missing. This takes precedence over `enableMissingTranslationPlaceholders` in your project configuration.
+
+### Grep options
+
+`-i, --ignore-case`
+: Ignore case distinctions in patterns and input data, so that characters that differ only in case match each other.
+
+`-n, --line-number`
+: Prefix each line of output with the 1-based line number within its input file.
+
+`-o, --only-matching`
+: Print only the matched (non-empty) parts of a matching line, with each such part on a separate output line.
+
+`-r, --recursive`
+: Read all files under each directory, recursively, following symbolic links only if they are on the command line.
+
+`-E, --extended-regexp`
+: Interpret PATTERNS as extended regular expressions.
+
+### Patterns
+
+`<!-- raw HTML omitted -->`
+: By default, Hugo strips raw HTML from your Markdown prior to rendering, and leaves this HTML comment in its place.
+
+`ZgotmplZ`
+: ZgotmplZ is a special value that indicates that unsafe content reached a CSS or URL context at runtime. See [details].
+
+[details]: https://pkg.go.dev/html/template
+
+`[i18n]`
+: This is the placeholder produced instead of the default value or an empty string if a translation is missing.
+
+`(<nil>)`
+: This string will appear in the rendered HTML when passing a nil value to the `printf` function.
+
+`(<nil>)`
+: Same as above when the value returned from the `printf` function has not been passed through `safeHTML`.
+
+`HAHAHUGO`
+: Under certain conditions a rendered shortcode may include all or a portion of the string HAHAHUGOSHORTCODE in either uppercase or lowercase. This is difficult to detect in all circumstances, but a case-insensitive search of the output for `HAHAHUGO` is likely to catch the majority of cases without producing false positives.
diff --git a/documents/markdown/hugo-docs/en_troubleshooting_deprecation.md b/documents/markdown/hugo-docs/en_troubleshooting_deprecation.md
new file mode 100644
index 0000000..a627a0e
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_troubleshooting_deprecation.md
@@ -0,0 +1,51 @@
+---
+title: Deprecation
+description: The Hugo project follows a formal and consistent process to deprecate functions, methods, and configuration settings.
+categories: []
+keywords: []
+---
+
+When a project _deprecates_ something, they are telling its users:
+
+1. Don't use Thing One anymore.
+1. Use Thing Two instead.
+1. We're going to remove Thing One at some point in the future.
+
+[reasons for deprecation]: https://en.wikipedia.org/wiki/Deprecation
+
+Common [reasons for deprecation]:
+
+- A feature has been replaced by a more powerful alternative.
+- A feature contains a design flaw.
+- A feature is considered extraneous, and will be removed in the future in order to simplify the system as a whole.
+- A future version of the software will make major structural changes, making it impossible or impractical to support older features.
+- Standardization or increased consistency in naming.
+- A feature that once was available only independently is now combined with its co-feature.
+
+After the project team deprecates something in code, Hugo will:
+
+1. Log an INFO message for 3 minor releases[^1]
+1. Log a WARN message for another 12 minor releases
+1. Log an ERROR message and fail the build thereafter
+
+The project team will:
+
+1. On the deprecation date, update the documentation with a note describing the deprecation and any relevant alternatives.
+1. Remove the code six or more minor releases after Hugo begins logging ERROR messages and failing the build. At that point, Hugo will throw an error, but the error message will no longer mention the deprecation.
+1. Remove the corresponding documentation two years after the deprecation date.
+
+To see the INFO messages, you must use the `--logLevel` command line flag:
+
+```text
+hugo build --logLevel info
+```
+
+To limit the output to deprecation notices:
+
+```text
+hugo build --logLevel info | grep deprecate
+```
+
+Run the above command every time you upgrade Hugo.
+
+[^1]: For example, v0.1.1 => v0.2.0 is a minor release.
diff --git a/documents/markdown/hugo-docs/en_troubleshooting_faq.md b/documents/markdown/hugo-docs/en_troubleshooting_faq.md
new file mode 100644
index 0000000..3e519b0
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_troubleshooting_faq.md
@@ -0,0 +1,110 @@
+---
+title: Frequently asked questions
+linkTitle: FAQs
+description: These questions are frequently asked by new users.
+categories: []
+keywords: []
+---
+
+Hugo's [forum] is an active community of users and developers who answer questions, share knowledge, and provide examples. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question.
+
+These are just a few of the questions most frequently asked by new users.
+
+An error message indicates that a feature is not available. Why?
+: <!-- do not remove preceding space -->
+ {{% include "/_common/installation/01-editions.md" %}}
+
+ When you attempt to use a feature that is not available in the edition that you installed, Hugo throws this error:
+
+ ```go-html-template
+ this feature is not available in this edition of Hugo
+ ```
+
+ To resolve, install a different edition based on the feature table above. See the [installation] section for details.
+
+Why do I see "Page Not Found" when visiting the home page?
+: In the `content/_index.md` file:
+
+ - Is `draft` set to `true`?
+ - Is the `date` in the future?
+ - Is the `publishDate` in the future?
+ - Is the `expiryDate` in the past?
+
+ If the answer to any of these questions is yes, either change the field values, or use one of these command line flags: `--buildDrafts`, `--buildFuture`, or `--buildExpired`.
+
+Why is a given page not published?
+: In the `content/section/page.md` file, or in the `content/section/page/index.md` file:
+
+ - Is `draft` set to `true`?
+ - Is the `date` in the future?
+ - Is the `publishDate` in the future?
+ - Is the `expiryDate` in the past?
+
+ If the answer to any of these questions is yes, either change the field values, or use one of these command line flags: `--buildDrafts`, `--buildFuture`, or `--buildExpired`.
+
+Why can't I see any of a page's descendants?
+: You may have an `index.md` file instead of an `_index.md` file. See [details](/content-management/page-bundles/).
+
+What is the difference between an `index.md` file and an `_index.md` file?
+: A directory with an `index.md file` is a [leaf bundle](g). A directory with an `_index.md` file is a [branch bundle](g). See [details](/content-management/page-bundles/).
+
+Why is my _partial_ template not rendered as expected?
+: You may have neglected to pass the required [context](g) when calling the partial. For example:
+
+ ```go-html-template
+ {{/* incorrect */}}
+ {{ partial "pagination.html" }}
+
+ {{/* correct */}}
+ {{ partial "pagination.html" . }}
+ ```
+
+In a template, what's the difference between `:=` and `=` when assigning values to variables?
+: Use `:=` to initialize a variable, and use `=` to assign a value to a variable that has been previously initialized. See [details](https://pkg.go.dev/text/template#hdr-Variables).
+
+When I paginate a list page, why is the page collection not filtered as specified?
+: You are probably invoking the [`Paginate`] or [`Paginator`] method more than once on the same page. See [details](/templates/pagination/).
+
+Why are there two ways to call a shortcode?
+: Use the `{{%/* shortcode */%}}` notation if the _shortcode_ template, or the content between the opening and closing shortcode tags, contains Markdown. Otherwise use the\
+`{{</* shortcode */>}}` notation. See [details](/content-management/shortcodes/#notation).
+
+Can I use environment variables to control configuration?
+: Yes. See [details](/configuration/introduction/#environment-variables).
+
+Why am I seeing inconsistent output from one build to the next?
+: The most common causes are page collisions (publishing two pages to the same path) and the effects of concurrency. Use the `--printPathWarnings` command line flag to check for page collisions, and create a topic on the [forum] if you suspect concurrency problems.
+
+Why isn't Hugo's development server detecting file changes?
+: In its default configuration, Hugo's file watcher may not be able detect file changes when:
+
+ - Running Hugo within Windows Subsystem for Linux (WSL/WSL2) with project files on a Windows partition
+ - Running Hugo locally with project files on a removable drive
+ - Running Hugo locally with project files on a storage server accessed via the NFS, SMB, or CIFS protocols
+
+ In these cases, instead of monitoring native file system events, use the `--poll` command line flag. For example, to poll the project files every 700 milliseconds, use `--poll 700ms`.
+
+Why is my page Store missing a value?
+: The [`Store`] method on a `Page` object allows you to create a [scratch pad](g) on the given page to store and manipulate data. Values are often set within a _shortcode_ template, a _partial_ template called by a _shortcode_ template, or by a _render hook_ template. In all three cases, the scratch pad values are not determinate until Hugo renders the page content.
+
+ If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop](g) variable:
+
+ ```go-html-template
+ {{ $noop := .Content }}
+ {{ .Store.Get "mykey" }}
+ ```
+
+ You can trigger content rendering with other methods as well. See next FAQ.
+
+Which page methods trigger content rendering?
+: The following methods on a `Page` object trigger content rendering: `Content`, `ContentWithoutSummary`, `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount`.
+
+> [!note]
+> For other questions please visit the [forum]. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question.
+
+[`Paginate`]: /methods/page/paginate/
+[`Paginator`]: /methods/page/paginator/
+[`Store`]: /methods/page/store
+[forum]: https://discourse.gohugo.io
+[installation]: /installation/
+[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132
diff --git a/documents/markdown/hugo-docs/en_troubleshooting_inspection.md b/documents/markdown/hugo-docs/en_troubleshooting_inspection.md
new file mode 100644
index 0000000..ea3c097
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_troubleshooting_inspection.md
@@ -0,0 +1,44 @@
+---
+title: Data inspection
+linkTitle: Inspection
+description: Use template functions to inspect values and data structures.
+categories: []
+keywords: []
+---
+
+Use the [`debug.Dump`] function to inspect a data structure:
+
+```go-html-template
+<pre>{{ debug.Dump .Params }}</pre>
+```
+
+```text
+{
+ "date": "2023-11-10T15:10:42-08:00",
+ "draft": false,
+ "iscjklanguage": false,
+ "lastmod": "2023-11-10T15:10:42-08:00",
+ "publishdate": "2023-11-10T15:10:42-08:00",
+ "tags": [
+ "foo",
+ "bar"
+ ],
+ "title": "My first post"
+}
+```
+
+Use the [`printf`] function (render) or [`warnf`] function (log to console) to inspect simple data structures. The layout string below displays both value and data type.
+
+```go-html-template
+{{ $value := 42 }}
+{{ printf "%[1]v (%[1]T)" $value }} → 42 (int)
+```
+
+{{< new-in 0.146.0 />}}
+
+Use the [`templates.Current`] function to visually mark template execution boundaries or to display the template call stack.
+
+[`debug.Dump`]: /functions/debug/dump/
+[`printf`]: /functions/fmt/printf/
+[`warnf`]: /functions/fmt/warnf/
+[`templates.Current`]: /functions/templates/current/
diff --git a/documents/markdown/hugo-docs/en_troubleshooting_logging.md b/documents/markdown/hugo-docs/en_troubleshooting_logging.md
new file mode 100644
index 0000000..709845d
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_troubleshooting_logging.md
@@ -0,0 +1,65 @@
+---
+title: Logging
+description: Enable logging to inspect events while building your project.
+categories: []
+keywords: []
+---
+
+## Command line
+
+Enable console logging with the `--logLevel` command line flag.
+
+Hugo has four logging levels:
+
+error
+: Display error messages only.
+
+ ```sh
+ hugo build --logLevel error
+ ```
+
+warn
+: Display warning and error messages.
+
+ ```sh
+ hugo build --logLevel warn
+ ```
+
+info
+: Display information, warning, and error messages.
+
+ ```sh
+ hugo build --logLevel info
+ ```
+
+debug
+: Display debug, information, warning, and error messages.
+
+ ```sh
+ hugo build --logLevel debug
+ ```
+
+> [!note]
+> If you do not specify a logging level with the `--logLevel` flag, warnings and errors are always displayed.
+
+## Template functions
+
+You can also use template functions to print warnings or errors to the console. These functions are typically used to report data validation errors, missing files, etc.
+
+{{% render-list-of-pages-in-section path=/functions/fmt filter=functions_fmt_logging filterType=include %}}
+
+## LiveReload
+
+To log Hugo's LiveReload requests in your browser, add this query string to the URL when running Hugo's development server:
+
+```text
+debug=LR-verbose
+```
+
+For example:
+
+```text
+http://localhost:1313/?debug=LR-verbose
+```
+
+Then monitor the reload requests in your browser's dev tools console. Make sure the dev tools "preserve log" option is enabled.
diff --git a/documents/markdown/hugo-docs/en_troubleshooting_performance.md b/documents/markdown/hugo-docs/en_troubleshooting_performance.md
new file mode 100644
index 0000000..45be5c7
--- /dev/null
+++ b/documents/markdown/hugo-docs/en_troubleshooting_performance.md
@@ -0,0 +1,102 @@
+---
+title: Performance
+description: Tools and suggestions for evaluating and improving performance.
+categories: []
+keywords: []
+aliases: [/troubleshooting/build-performance/]
+---
+
+## Virus scanning
+
+Virus scanners are an essential component of system protection, but the performance impact can be severe for applications like Hugo that frequently read and write to disk. For example, with Microsoft Defender Antivirus, build times for some sites may increase by 400% or more.
+
+Before building a site, your virus scanner has already evaluated the files in your project directory. Scanning them again while building the site is superfluous. To improve performance, add Hugo's executable to your virus scanner's process exclusion list.
+
+For example, with Microsoft Defender Antivirus:
+
+**Start** > **Settings** > **Privacy & security** > **Windows Security** > **Open Windows Security** > **Virus & threat protection** > **Manage settings** > **Add or remove exclusions** > **Add an exclusion** > **Process**
+
+Then type `hugo.exe` add press the **Add** button.
+
+> [!note]
+> Virus scanning exclusions are common, but use caution when changing these settings. See the [Microsoft Defender Antivirus documentation] for details.
+
+Other virus scanners have similar exclusion mechanisms. See their respective documentation.
+
+## Template metrics
+
+Hugo is fast, but inefficient templates impede performance. Enable template metrics to determine which templates take the most time, and to identify caching opportunities:
+
+```sh
+hugo build --templateMetrics --templateMetricsHints
+```
+
+The result will look something like this:
+
+```text
+Template Metrics:
+
+ cumulative average maximum cache percent cached total
+ duration duration duration potential cached count count template
+ ---------- -------- -------- --------- ------- ------ ----- --------
+ 36.037476822s 135.990478ms 225.765245ms 11 0 0 265 _partials/head.html
+ 35.920040902s 164.018451ms 233.475072ms 0 0 0 219 articles/page.html
+ 34.163268129s 128.917992ms 224.816751ms 23 0 0 265 _partials/head/meta/opengraph.html
+ 1.041227437s 3.92916ms 186.303376ms 47 0 0 265 _partials/head/meta/schema.html
+ 805.628827ms 27.780304ms 114.678523ms 0 0 0 29 section.html
+ 624.08354ms 15.221549ms 108.420729ms 8 0 0 41 _partials/utilities/render-page-collection.html
+ 545.968801ms 775.523µs 105.045775ms 0 0 0 704 summary.html
+ 334.680981ms 1.262947ms 127.412027ms 100 0 0 265 _partials/head/js.html
+ 272.763205ms 2.050851ms 24.371757ms 0 0 0 133 _markup/render-codeblock.html
+ 163.951469ms 14.904679ms 70.267953ms 0 0 0 11 articles/section.html
+ 153.07021ms 577.623µs 73.593597ms 100 0 0 265 _partials/head/init.html
+ 150.910984ms 150.910984ms 150.910984ms 0 0 0 1 page.html
+ 146.785804ms 146.785804ms 146.785804ms 0 0 0 1 contact.html
+ 115.364617ms 115.364617ms 115.364617ms 0 0 0 1 authors/term.html
+ 87.392071ms 329.781µs 10.687132ms 100 0 0 265 _partials/head/css.html
+ 86.803122ms 86.803122ms 86.803122ms 0 0 0 1 home.html
+```
+
+From left to right, the columns represent:
+
+cumulative duration
+: The cumulative time spent executing the template.
+
+average duration
+: The average time spent executing the template.
+
+maximum duration
+: The maximum time spent executing the template.
+
+cache potential
+: Displayed as a percentage, any _partial_ template with a 100% cache potential should be called with the [`partialCached`] function instead of the [`partial`] function. See the [caching](#caching) section below.
+
+percent cached
+: The number of times the rendered templated was cached divided by the number of times the template was executed.
+
+cached count
+: The number of times the rendered templated was cached.
+
+total count
+: The number of times the template was executed.
+
+template
+: The path to the template, relative to the `layouts` directory.
+
+> [!note]
+> Hugo builds pages in parallel where multiple pages are generated simultaneously. Because of this parallelism, the sum of "cumulative duration" values is usually greater than the actual time it takes to build a site.
+
+## Caching
+
+Some _partial_ templates such as sidebars or menus are executed many times during a site build. Depending on the content within the _partial_ template and the desired output, the template may benefit from caching to reduce the number of executions. The [`partialCached`] template function provides caching capabilities for _partial_ templates.
+
+> [!note]
+> Note that you can create cached variants of each partial by passing additional arguments to `partialCached` beyond the initial context. See the `partialCached` documentation for more details.
+
+## Timers
+
+Use the `debug.Timer` function to determine execution time for a block of code, useful for finding performance bottlenecks in templates. See [details](/functions/debug/timer/).
+
+[`partial`]: /functions/partials/include/
+[`partialCached`]: /functions/partials/includecached/
+[Microsoft Defender Antivirus documentation]: https://support.microsoft.com/en-us/topic/how-to-add-a-file-type-or-process-exclusion-to-windows-security-e524cbc2-3975-63c2-f9d1-7c2eb5331e53
diff --git a/documents/markdown/markdown-it/4.0_migration.md b/documents/markdown/markdown-it/4.0_migration.md
new file mode 100644
index 0000000..f8abedf
--- /dev/null
+++ b/documents/markdown/markdown-it/4.0_migration.md
@@ -0,0 +1,35 @@
+Migration to v4
+===============
+
+v4 has the same external API as v3, but significantly changed internals. Plugin
+authors should update their packages.
+
+## For users
+
+External API did not change.
+
+- If you used `markdown-it` with plugins - make sure to update those.
+- If you modified renderer - see dev info below.
+- If you did not use plugins and renderer modification - no changes needed.
+
+
+## For developers
+
+### Tokens and renderer
+
+- [Tokens](https://github.com/markdown-it/markdown-it/blob/master/lib/token.js)
+ are now classes, and allow arbitrary attributes.
+ - new tokens are created with `token = state.push(type, tag, nesting)`.
+ See [this commit](https://github.com/markdown-it/markdown-it/commit/4aabd5592ea55fb43d6a215b316c89c6f6f1f7db) to understand
+ how to create tokens in new way. Also see changes in plugins from other
+ repos in this org.
+- [Renderer](https://github.com/markdown-it/markdown-it/blob/master/lib/renderer.js)
+ methods were unified. Number of custom renderer rules were significantly reduced.
+ Custom renderer functions need update due to tokens format change.
+
+### Other changes
+
+- `.validateUrl()` -> moved to root class `.validateLink()`
+- added `.normalizeLink()` & `.normalizeLinkText()` to root class, and removed
+ `normalizeUrl()` from utils.
+- removed `replaceEntities()` in `utils`.
diff --git a/documents/markdown/markdown-it/5.0_migration.md b/documents/markdown/markdown-it/5.0_migration.md
new file mode 100644
index 0000000..d2055eb
--- /dev/null
+++ b/documents/markdown/markdown-it/5.0_migration.md
@@ -0,0 +1,23 @@
+Migration to v5
+===============
+
+v5 has the same external API as v4, only internals were changed. Some external
+plugins may need update (all plugins from `markdown-it` github organization are
+up to date).
+
+
+## For users
+
+External API did not change.
+
+- If you use `markdown-it` with plugins, make sure to update them.
+
+
+## For plugin developers
+
+- added `stateBlock.sCount` to calculate indents instead of `stateBlock.tShift`, it only differs if tabs are present:
+ - `stateBlock.tShift` is used to calculate a number of *characters* (tab is 1 character)
+ - `stateBlock.sCount` is used to calculate the block *offset* (tab is 1-4 characters depending on position)
+- added `stateInline.ruler2` and `stateInline.delimiters` needed to parse emphasis-like markup better
+ - emphasis-like tags now can't be skipped with `stateInline.skipToken`, they treat a sequence of markers (e.g. `***`) as a token instead
+ - `stateInline.delimiters` is linked with `stateInline.tokens`, so truncating/splicing `stateInline.tokens` may break things
diff --git a/documents/markdown/markdown-it/CHANGELOG.md b/documents/markdown/markdown-it/CHANGELOG.md
new file mode 100644
index 0000000..9943d76
--- /dev/null
+++ b/documents/markdown/markdown-it/CHANGELOG.md
@@ -0,0 +1,735 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [14.1.1] - 2026-01-11
+### Security
+- Fixed regression from v13 in linkify inline rule. Specific patterns could
+ cause high CPU use. Thanks to @ltduc147 for report.
+
+
+## [14.1.0] - 2024-03-19
+### Changed
+- Updated CM spec compatibility to 0.31.2, #1009.
+
+### Fixed
+- Fixed quadratic complexity when parsing references, #996.
+- Fixed quadratic output size with pathological user input in tables, #1000.
+
+
+## [14.0.0] - 2023-12-08
+### Changed
+- Drop ancient browsers support (use `.fromCodePoint` and other features).
+- Rewrite to ESM (including all plugins/deps). CJS fallback still available.
+ No signatures changed, except `markdown-it-emoji` plugin.
+- Dropped `dist/` folder from repo, build on package publish.
+- Set `punicode.js` as external dependency.
+
+### Fixed
+- Html tokens inside img alt are now rendered as their original text, #896.
+- Hardbreaks inside img alt are now rendered as newlines.
+
+
+## [13.0.2] - 2023-09-26
+### Security
+- Fixed crash/infinite loop caused by linkify inline rule, #957.
+
+### Fixed
+- Throw an error if 3rd party plugin doesn't increment `line` or `pos` counters
+ (previously, markdown-it would likely go into infinite loop instead), #847.
+
+
+## [13.0.1] - 2022-05-03
+### Fixed
+- Bumped `linkify-it` to 4.0.1. That should fix some hangs, caused by wrong
+ data, returned from `linkify-it`.
+
+
+## [13.0.0] - 2022-04-22
+### Added
+- Added a new token type `text_special` to store escaped characters, same as `text` but
+ unaffected by replacement plugins (smartquotes, typographer, linkifier, etc.).
+- Added a new rule `text_join` in `core` ruler. Text replacement plugins may choose to
+ insert themselves before it.
+
+### Changed
+- `(p)` is no longer replaced with § by typographer (conflicts with ℗), #763.
+- `text_collapse` rule is renamed to `fragments_join`.
+
+### Fixed
+- Smartquotes, typographic replacements and plain text links can now be escaped
+ with backslash (e.g. `\(c)` or `google\.com` are no longer replaced).
+- Fixed collision of emphasis and linkifier (so `http://example.org/foo._bar_-_baz`
+ is now a single link, not emphasized). Emails and fuzzy links are not affected by this.
+
+
+## [12.3.2] - 2022-01-08
+### Security
+- Fix possible ReDOS in newline rule. Thanks to @MakeNowJust.
+
+
+## [12.3.1] - 2022-01-07
+### Fixed
+- Fix corner case when tab prevents paragraph continuation in lists, #830.
+
+
+## [12.3.0] - 2021-12-09
+### Changed
+- `StateInline.delimiters[].jump` is removed.
+
+### Fixed
+- Fixed quadratic complexity in pathological `***<10k stars>***a***<10k stars>***` case.
+
+
+## [12.2.0] - 2021-08-02
+### Added
+- Ordered lists: add order value to token info.
+
+### Fixed
+- Always suffix indented code block with a newline, #799.
+
+
+## [12.1.0] - 2021-07-01
+### Changed
+- Updated CM spec compatibility to 0.30.
+
+
+## [12.0.6] - 2021-04-16
+### Fixed
+- Newline in `alt` should be rendered, #775.
+
+
+## [12.0.5] - 2021-04-15
+### Fixed
+- HTML block tags with `===` inside are no longer incorrectly interpreted as headers, #772.
+- Fix table/list parsing ambiguity, #767.
+
+
+## [12.0.4] - 2020-12-20
+### Fixed
+- Fix crash introduced in `12.0.3` when processing strikethrough (`~~`) and similar plugins, #742.
+- Avoid fenced token mutation, #745.
+
+
+## [12.0.3] - 2020-12-07
+### Fixed
+- `[](<foo<bar>)` is no longer a valid link.
+- `[](url (xxx())` is no longer a valid link.
+- `[](url\ xxx)` is no longer a valid link.
+- Fix performance issues when parsing links (#732, #734), backticks, (#733, #736),
+ emphases (#735), and autolinks (#737).
+- Allow newline in `<? ... ?>` in an inline context.
+- Allow `<meta>` html tag to appear in an inline context.
+
+
+## [12.0.2] - 2020-10-23
+### Fixed
+- Three pipes (`|\n|\n|`) are no longer rendered as a table with no columns, #724.
+
+
+## [12.0.1] - 2020-10-19
+### Fixed
+- Fix tables inside lists indented with tabs, #721.
+
+
+## [12.0.0] - 2020-10-14
+### Added
+- `.gitattributes`, force unix eol under windows, for development.
+
+### Changed
+- Added 3rd argument to `highlight(code, lang, attrs)`, #626.
+- Rewrite tables according to latest GFM spec, #697.
+- Use `rollup.js` to browserify sources.
+- Drop `bower.json` (bower reached EOL).
+- Deps bump.
+- Tune `specsplit.js` options.
+- Drop `Makefile` in favour of npm scrips.
+
+### Fixed
+- Fix mappings for table rows (amended fix made in 11.0.1), #705.
+- `%25` is no longer decoded in beautified urls, #720.
+
+
+## [11.0.1] - 2020-09-14
+### Fixed
+- Fix blockquote lazy newlines, #696.
+- Fix missed mappings for table rows, #705.
+
+
+## [11.0.0] - 2020-05-20
+### Changed
+- Bumped `linkify-it` to 3.0.0, #661 + allow unlimited `.` inside links.
+- Dev deps bump.
+- Switch to `nyc` for coverage reports.
+- Partially moved tasks from Makefile to npm scripts.
+- Automate web update on npm publish.
+
+### Fixed
+- Fix em- and en-dashes not being typographed when separated by 1 char, #624.
+- Allow opening quote after another punctuation char in typographer, #641.
+- Assorted wording & typo fixes.
+
+
+## [10.0.0] - 2019-09-11
+### Security
+- Fix quadratic parse time for some combinations of pairs, #583. Algorithm is
+ now similar to one in reference implementation.
+
+### Changed
+- Minor internal structs change, to make pairs parse more effective (cost is
+ linear now). If you use external "pairs" extensions, you need sync those with
+ "official ones". Without update, old code will work, but can cause invalid
+ result in rare case. This is the only reason of major version bump. With high probability you don't need to change your code, only update version dependency.
+- Updated changelog format.
+- Deps bump.
+
+
+## [9.1.0] - 2019-08-11
+### Changed
+- Remove extra characters from line break check. Leave only 0x0A & 0x0D, as in
+ CommonMark spec, #581.
+
+
+## [9.0.1] - 2019-07-12
+### Fixed
+- Fix possible corruption of open/close tag levels, #466
+
+
+## [9.0.0] - 2019-07-09
+### Changed
+- Updated CM spec compatibility to 0.29.
+- Update Travis-CI node version to actual (8 & latest).
+- Deps bump.
+
+
+## [8.4.2] - 2018-02-15
+### Fixed
+- Fix `--no-html` CLI option, #476.
+
+
+## [8.4.1] - 2018-02-15
+### Fixed
+- Fix smartquotes around softbreaks, #430.
+
+
+## [8.4.0] - 2017-08-24
+### Changed
+- Updated CM spec compatibility to 0.28.
+
+
+## [8.3.2] - 2017-08-03
+### Fixed
+- Fix blockquote termination inside lists, #386.
+
+
+## [8.3.1] - 2017-03-06
+### Fixed
+- Fix blockquote termination by list item, #338.
+
+
+## [8.3.0] - 2017-02-16
+### Changed
+- Remove tabs at the beginning of the line in paragraphs.
+- Better error message for bad input type, #324.
+
+### Fixed
+- Fix table indentation issues, #325, #224.
+- Fix blockquote termination inside indented lists, #329.
+
+
+## [8.2.2] - 2016-12-15
+### Added
+- Add `-o` / `--output` option to CLI, #312.
+
+
+## [8.2.1] - 2016-12-02
+### Fixed
+- Add missed h2..h6 to whitelisted block tags.
+
+
+## [8.2.0] - 2016-12-01
+### Changed
+- Updated CM spec compatibility to 0.27 (no significant changes).
+
+### Fixed
+- Fix backticks handle inside tables, #303.
+- Fix edge case for fenced blocks with `~~~` in info, #301.
+- Fix fallback to reference if link is not valid, #302.
+
+
+## [8.1.0] - 2016-11-03
+### Changed
+- Make link parse helpers (`md.helpers`) pluggable, #299.
+
+
+## [8.0.1] - 2016-10-18
+### Fixed
+- Tables: allow tab characters in markup
+
+
+## [8.0.0] - 2016-09-16
+### Changed
+- Benchmarks src cleanup.
+- Remove testing in old nodes (but still use es5).
+- Updated CM spec compatibility to 0.26 (see list below):
+- Two consecutive newlines no longer terminate a list.
+- Ordered list terminating a paragraph can now only start with 1.
+- Adjust emphasis algorithm (`*foo**bar**baz*` is now parsed as `<strong>`
+ inside `<em>`).
+- Fix tab width calculation inside lists and blockquotes.
+
+
+## [7.0.1] - 2016-08-16
+### Fixed
+- Fence renderer: fix concat of class array, #276.
+- Code renderer: do not render double space before attrs, #275.
+- Replacer: disable replacements inside autolinks, #272.
+
+
+## [7.0.0] - 2016-06-22
+### Changed
+- Bump `linkify-it` dependency to 2.0.0. `---` no longer terminates
+ autodetected links by default. `md.linkifier.set('---', true)` will return old
+ behaviour.
+- Major version bumped, because internals or `linkify-it` was changed.
+ You will not be affected anyhow, if not used direct access to
+ `require('linkify-it/re')` for customizations.
+
+
+## [6.1.1] - 2016-06-21
+### Changed
+- Render `code_inline` & `code_block` attributes if exist.
+
+
+## [6.1.0] - 2016-06-19
+### Changed
+- Updated `fence` renderer to not mutate token. Token stream should be
+ immutable after renderer call.
+
+
+## [6.0.5] - 2016-06-01
+### Fixed
+- Process `\r` the same way as `\n` and `\r\n\`, #252.
+
+
+## [6.0.4] - 2016-05-30
+### Added
+- Added `Token.attrGet()` method for convenience, #251.
+
+
+## [6.0.3] - 2016-05-30
+### Security
+- Security fix: possible ReDOS in `linkify-it` (forced bump of `linkify-it` &
+ `uc-micro` dependencies). New installs will use fixed packages automatically,
+ but we bumped `markdown-it` version for sure & for web builds.
+
+
+## [6.0.2] - 2016-05-16
+### Fixed
+- Fix: should not escape twice content of image alt attribute, #246.
+
+
+## [6.0.1] - 2016-04-02
+### Fixed
+- Improve support of missing values in tables, #224.
+
+
+## [6.0.0] - 2016-02-11
+### Changed
+- Maintenance release. Version bump caused by notable changes in CM spec
+ (multiline setext headers, no spaces inside links, ...). API was not changed.
+- Fit CM 0.24 spec requirements.
+
+### Fixed
+- Fixed nesting limit check in inline blocks, #197.
+- Fixed posible tail loss in CLI ouput.
+
+
+## [5.1.0] - 2016-01-07
+### Added
+- Token: added `.attrSet()` & `.attrJoin()` methods.
+- Highlighter: allow wrapper override (if result starts with "<pre").
+
+
+## [5.0.3] - 2016-01-04
+### Fixed
+- Allow single column and mismatched columns count in tables.
+- Smartquotes: take into account adjacent tokens.
+- Fill `content` property in image token with `alt` source.
+
+
+## [5.0.2] - 2015-11-20
+### Fixed
+- Fix meta information (`token.markup` and `token.info`) for autolink tokens.
+
+
+## [5.0.1] - 2015-10-30
+### Fixed
+- Improved tables compatibility with github, #120.
+
+
+## [5.0.0] - 2015-10-05
+### Changed
+- Internal API change. Due to new CM spec requirements, we had to update
+ internals. That should not touch ordinary users, but can affect some external
+ plugins. If you are plugin developper - see migration guide:
+ https://github.com/markdown-it/markdown-it/blob/master/docs/5.0_migration.md.
+- Updated CM spec compatibility to 0.22 (see list below).
+- Keep tabs (don't replace with spaces).
+- Don't wrap iframes with paragraphs.
+- Rewritten emphasis algorithm.
+
+### Fixed
+- Fix closure compiler collisions (don't use reserved words), #159.
+
+
+## [4.4.0] - 2015-07-18
+### Changed
+- Updated HTML blocks logic to CM 0.21 spec.
+- Minor fixes.
+
+
+## [4.3.1] - 2015-07-15
+### Security
+- Fix class name injection in fence renderer.
+
+### Fixed
+- Allow numbered lists starting from zero.
+
+
+## [4.3.0] - 2015-06-29
+### Changed
+- `linkify-it` dependency update (1.2.0). Now accepts dash at the end of links.
+
+
+## [4.2.2] - 2015-06-10
+### Changed
+- CM spec 0.20.
+
+### Added
+- Added support for multichar substituition in smartquites, #115.
+
+### Fixed
+- Fixed code block render inside blockquites, #116.
+- Doc fixes.
+
+
+## [4.2.1] - 2015-05-01
+### Changed
+- Minor emphasis update to match CM spec 0.19.
+
+
+## [4.2.0] - 2015-04-21
+### Changed
+- Bumped [linkify-it](https://github.com/markdown-it/linkify-it) version to
+ 1.1.0. Now links with IP hosts and without protocols are not linkified by
+ default, due possible collisions with some version numbers patterns (0.5.0.0).
+ You still can return back old behaviour by `md.linkify.set({ fuzzyIP: true })`.
+
+
+## [4.1.2] - 2015-04-19
+### Changed
+- Bumped linkifier version. More strict 2-chars tald support for links without
+ schema. Should not linkify things like `io.js` and `node.js`.
+
+
+## [4.1.1] - 2015-04-15
+### Fixed
+- Improved pipe chars support in table cells, #86 (thanks to @jbt).
+
+
+## [4.1.0] - 2015-03-31
+### Security
+- Disabled `data:` URLs by default (except some image mimes), to avoid
+ possible XSS. Version bumped, because features changed (formally). If you did
+ not used `data:` URLs, consider this version as 4.0.4 (no API changes).
+
+### Changed
+- Simplified link validator code. Now more easy to understand and to copy
+ into your projects for customization.
+
+
+## [4.0.3] - 2015-03-25
+### Changed
+- Updated linkifier.
+- Smartquotes rule cleanup (#76).
+
+### Fixed
+- Fixed replacements rule bug in PhantomJS (#77).
+
+
+## [4.0.2] - 2015-03-22
+### Fixed
+- Fixed emphasis `marker` fields in tokens (#69).
+- Fixed html block tokens with numbers in name (#74).
+
+
+## [4.0.1] - 2015-03-13
+### Added
+- Added custom container plugin demo.
+
+### Changed
+- Updated `linkify-it` version.
+
+
+## [4.0.0] - 2015-03-11
+### Changed
+- Breaking internal API changes. See [v4 migration notes](https://github.com/markdown-it/markdown-it/blob/master/docs/4.0_migration.md). In usual case you will need to update plugins.
+- Token internals changed
+- Unified the most of renderer methods.
+- Changed tokens creation - use `state.push(...)` (see sources)
+- Moved `normalizeUrl()` to root class as `.normalizeLink()` &
+ added `normalizeLinkText()` method.
+- Moved `.validateUrl()` to root class and simplified logic - no more need to
+ replace entities.
+- Joined md unescape & replace entities logic to `utils.unescapeAll()`.
+- Removed `replaceEntities()` in `utils`.
+- `md.utils.lib` now exposes useful libs for plugins.
+- Use entities data from external package.
+
+### Fixed
+- Fixed emphasis regression, caused by CM v0.18 spec (#65).
+
+
+## [3.1.0] - 2015-03-05
+### Changed
+- Spec conformance update to 0.18.
+- Significantly improved autolinking quality (use `linkify-it` package), #2.
+
+### Fixed
+- Rewritten links normalizer to solve different edge cases (use `mdurl`
+ package), #29.
+- Moved link title entities replace out of renderer.
+- Fixed escaped entities in links (`foo\&/bar`).
+- Improved smartquotes logic, #61.
+
+
+## [3.0.7] - 2015-02-22
+### Added
+- Added basic CLI support.
+
+### Changed
+- Use external package for unicode data (punctuation).
+
+### Fixed
+- Added \v \f to valid whitespaces.
+- Match table columns count by header.
+
+
+## [3.0.6] - 2015-02-12
+### Added
+- Sync scroll result => source in demo.
+
+### Changed
+- Moved `normalizeReference()` to utils.
+
+### Fixed
+- Fixed hang on long vertical list of links. Appeared in 3.0.5. See #54 for
+ details. Thanks to @fengmk2 for report!
+- Table lines now can have escaped pipe char `\|` (#5).
+
+
+## [3.0.5] - 2015-02-06
+### Changed
+- Significantly improved tests coverage (with dead code removal and other
+ related things).
+
+### Fixed
+- Fixed link validator - could skip some kind of javascript links with uppercase
+ digital entities (thanks to @opennota)
+
+
+## [3.0.4] - 2015-01-13
+### Changed
+- Improved errors processing in url normalizer (for broken sequences).
+- Improved nesting limit processing in inline parser.
+- Reorganized tests & improved coverage.
+- Show inline diffs for failed tests.
+
+
+## [3.0.3] - 2015-01-11
+### Fixed
+- Fixed punctuation check in emphasis.
+
+
+## [3.0.2] - 2015-01-09
+### Fixed
+- Allow dashes in HTML tag names (needed for custom HTML tags).
+
+
+## [3.0.1] - 2015-01-07
+### Changed
+- Added # to terminator chars.
+
+### Fixed
+- Improved link encoder - fix invalid surrogates to avoid errors.
+
+
+## [3.0.0] - 2015-01-04
+### Changed
+- Big split. All "rare" rules moved to external plugins (deflist, abbr, footnote,
+ sub, sup, ins, mark).
+- Updated CM spec conformance to v0.15 (better unicode support).
+- Added `md` (parser instance) link to all state objects (instead of former
+ options/parser).
+- References/Footnotes/Abbrs moved to `block` chain.
+- Input normalization moved to `core` chain.
+- Splitted links and images to separate rules.
+- Renamed some rules.
+- Removed `full` preset. Not needed anymore.
+- enable/disable methods now throw by default on invalid rules (exceptions can
+ be disabled).
+- Replace NULL characters with 0xFFFD instead of strip.
+- Removed custom fences sugar (overcomplication).
+- Rewritten link components parse helpers.
+- More functions in `md.utils`.
+
+### Fixed
+- Fixed inline html comments & cdata parse.
+
+
+## [2.2.1] - 2014-12-29
+### Added
+- Added development info.
+
+### Changed
+- .use() now pass any number of params to plugins.
+
+### Fixed
+- Fixed line breaks in definitions lists.
+
+
+## [2.2.0] - 2014-12-28
+### Added
+- API docs.
+- Added 'zero' preset.
+
+### Changed
+- Updated CM spec conformance to v0.13.
+
+### Fixed
+- Fixed several crashes, when some basic rules are disabled
+ (block termination check, references check).
+
+
+## [2.1.3] - 2014-12-24
+### Added
+- Added curring to `set`/`configure`/`enable`/`disable` methods.
+
+### Changed
+- Demo rework - now can include plugins.
+- Docs update.
+
+
+## [2.1.2] - 2014-12-23
+### Changed
+- Exposed helpers into parser instances (for plugins).
+- Removed utils from global export - been in instances seems enougth.
+- Refactored demo & added markdown-it-emoji to it.
+
+
+## [2.1.1] - 2014-12-22
+### Changed
+- Refreshed browser builds, missed in prev release.
+- Minor changes.
+
+
+## [2.1.0] - 2014-12-21
+### Changed
+- Separated method to enable rules by whitelist (enableOnly).
+- Changed second param of enable/disable ruler methods.
+- Shortcuts in main class for bulk enable/disable rules.
+- ASCII-friendly browserified files.
+- Separate package for spec tests.
+
+
+## [2.0.0] - 2014-12-20
+### Changed
+- New project name & home! Now it's `markdown-it`,
+- Sugar for constructor call - `new` is not mandatory now.
+- Renamed presets folder (configs -> presets).
+
+
+[14.1.1]: https://github.com/markdown-it/markdown-it/compare/14.1.0...14.1.1
+[14.1.0]: https://github.com/markdown-it/markdown-it/compare/14.0.0...14.1.0
+[14.0.0]: https://github.com/markdown-it/markdown-it/compare/13.0.2...14.0.0
+[13.0.2]: https://github.com/markdown-it/markdown-it/compare/13.0.1...13.0.2
+[13.0.1]: https://github.com/markdown-it/markdown-it/compare/13.0.0...13.0.1
+[13.0.0]: https://github.com/markdown-it/markdown-it/compare/12.3.2...13.0.0
+[12.3.2]: https://github.com/markdown-it/markdown-it/compare/12.3.1...12.3.2
+[12.3.1]: https://github.com/markdown-it/markdown-it/compare/12.3.0...12.3.1
+[12.3.0]: https://github.com/markdown-it/markdown-it/compare/12.2.0...12.3.0
+[12.2.0]: https://github.com/markdown-it/markdown-it/compare/12.1.0...12.2.0
+[12.1.0]: https://github.com/markdown-it/markdown-it/compare/12.0.6...12.1.0
+[12.0.6]: https://github.com/markdown-it/markdown-it/compare/12.0.5...12.0.6
+[12.0.5]: https://github.com/markdown-it/markdown-it/compare/12.0.4...12.0.5
+[12.0.4]: https://github.com/markdown-it/markdown-it/compare/12.0.3...12.0.4
+[12.0.3]: https://github.com/markdown-it/markdown-it/compare/12.0.2...12.0.3
+[12.0.2]: https://github.com/markdown-it/markdown-it/compare/12.0.1...12.0.2
+[12.0.1]: https://github.com/markdown-it/markdown-it/compare/12.0.0...12.0.1
+[12.0.0]: https://github.com/markdown-it/markdown-it/compare/11.0.1...12.0.0
+[11.0.1]: https://github.com/markdown-it/markdown-it/compare/11.0.0...11.0.1
+[11.0.0]: https://github.com/markdown-it/markdown-it/compare/10.0.0...11.0.0
+[10.0.0]: https://github.com/markdown-it/markdown-it/compare/9.1.0...10.0.0
+[9.1.0]: https://github.com/markdown-it/markdown-it/compare/9.0.1...9.1.0
+[9.0.1]: https://github.com/markdown-it/markdown-it/compare/9.0.0...9.0.1
+[9.0.0]: https://github.com/markdown-it/markdown-it/compare/8.4.2...9.0.0
+[8.4.2]: https://github.com/markdown-it/markdown-it/compare/8.4.1...8.4.2
+[8.4.1]: https://github.com/markdown-it/markdown-it/compare/8.4.0...8.4.1
+[8.4.0]: https://github.com/markdown-it/markdown-it/compare/8.3.2...8.4.0
+[8.3.2]: https://github.com/markdown-it/markdown-it/compare/8.3.1...8.3.2
+[8.3.1]: https://github.com/markdown-it/markdown-it/compare/8.3.0...8.3.1
+[8.3.0]: https://github.com/markdown-it/markdown-it/compare/8.2.2...8.3.0
+[8.2.2]: https://github.com/markdown-it/markdown-it/compare/8.2.1...8.2.2
+[8.2.1]: https://github.com/markdown-it/markdown-it/compare/8.2.0...8.2.1
+[8.2.0]: https://github.com/markdown-it/markdown-it/compare/8.1.0...8.2.0
+[8.1.0]: https://github.com/markdown-it/markdown-it/compare/8.0.1...8.1.0
+[8.0.1]: https://github.com/markdown-it/markdown-it/compare/8.0.0...8.0.1
+[8.0.0]: https://github.com/markdown-it/markdown-it/compare/7.0.1...8.0.0
+[7.0.1]: https://github.com/markdown-it/markdown-it/compare/7.0.0...7.0.1
+[7.0.0]: https://github.com/markdown-it/markdown-it/compare/6.1.1...7.0.0
+[6.1.1]: https://github.com/markdown-it/markdown-it/compare/6.1.0...6.1.1
+[6.1.0]: https://github.com/markdown-it/markdown-it/compare/6.0.5...6.1.0
+[6.0.5]: https://github.com/markdown-it/markdown-it/compare/6.0.4...6.0.5
+[6.0.4]: https://github.com/markdown-it/markdown-it/compare/6.0.3...6.0.4
+[6.0.3]: https://github.com/markdown-it/markdown-it/compare/6.0.2...6.0.3
+[6.0.2]: https://github.com/markdown-it/markdown-it/compare/6.0.1...6.0.2
+[6.0.1]: https://github.com/markdown-it/markdown-it/compare/6.0.0...6.0.1
+[6.0.0]: https://github.com/markdown-it/markdown-it/compare/5.1.0...6.0.0
+[5.1.0]: https://github.com/markdown-it/markdown-it/compare/5.0.3...5.1.0
+[5.0.3]: https://github.com/markdown-it/markdown-it/compare/5.0.2...5.0.3
+[5.0.2]: https://github.com/markdown-it/markdown-it/compare/5.0.1...5.0.2
+[5.0.1]: https://github.com/markdown-it/markdown-it/compare/5.0.0...5.0.1
+[5.0.0]: https://github.com/markdown-it/markdown-it/compare/4.4.0...5.0.0
+[4.4.0]: https://github.com/markdown-it/markdown-it/compare/4.3.1...4.4.0
+[4.3.1]: https://github.com/markdown-it/markdown-it/compare/4.3.0...4.3.1
+[4.3.0]: https://github.com/markdown-it/markdown-it/compare/4.2.2...4.3.0
+[4.2.2]: https://github.com/markdown-it/markdown-it/compare/4.2.1...4.2.2
+[4.2.1]: https://github.com/markdown-it/markdown-it/compare/4.2.0...4.2.1
+[4.2.0]: https://github.com/markdown-it/markdown-it/compare/4.1.2...4.2.0
+[4.1.2]: https://github.com/markdown-it/markdown-it/compare/4.1.1...4.1.2
+[4.1.1]: https://github.com/markdown-it/markdown-it/compare/4.1.0...4.1.1
+[4.1.0]: https://github.com/markdown-it/markdown-it/compare/4.0.3...4.1.0
+[4.0.3]: https://github.com/markdown-it/markdown-it/compare/4.0.2...4.0.3
+[4.0.2]: https://github.com/markdown-it/markdown-it/compare/4.0.1...4.0.2
+[4.0.1]: https://github.com/markdown-it/markdown-it/compare/4.0.0...4.0.1
+[4.0.0]: https://github.com/markdown-it/markdown-it/compare/3.1.0...4.0.0
+[3.1.0]: https://github.com/markdown-it/markdown-it/compare/3.0.7...3.1.0
+[3.0.7]: https://github.com/markdown-it/markdown-it/compare/3.0.6...3.0.7
+[3.0.6]: https://github.com/markdown-it/markdown-it/compare/3.0.5...3.0.6
+[3.0.5]: https://github.com/markdown-it/markdown-it/compare/3.0.4...3.0.5
+[3.0.4]: https://github.com/markdown-it/markdown-it/compare/3.0.3...3.0.4
+[3.0.3]: https://github.com/markdown-it/markdown-it/compare/3.0.2...3.0.3
+[3.0.2]: https://github.com/markdown-it/markdown-it/compare/3.0.1...3.0.2
+[3.0.1]: https://github.com/markdown-it/markdown-it/compare/3.0.0...3.0.1
+[3.0.0]: https://github.com/markdown-it/markdown-it/compare/2.2.1...3.0.0
+[2.2.1]: https://github.com/markdown-it/markdown-it/compare/2.2.0...2.2.1
+[2.2.0]: https://github.com/markdown-it/markdown-it/compare/2.1.3...2.2.0
+[2.1.3]: https://github.com/markdown-it/markdown-it/compare/2.1.2...2.1.3
+[2.1.2]: https://github.com/markdown-it/markdown-it/compare/2.1.1...2.1.2
+[2.1.1]: https://github.com/markdown-it/markdown-it/compare/2.1.0...2.1.1
+[2.1.0]: https://github.com/markdown-it/markdown-it/compare/2.0.0...2.1.0
+[2.0.0]: https://github.com/markdown-it/markdown-it/releases/tag/2.0.0
diff --git a/documents/markdown/markdown-it/CONTRIBUTING.md b/documents/markdown/markdown-it/CONTRIBUTING.md
new file mode 100644
index 0000000..2f75aed
--- /dev/null
+++ b/documents/markdown/markdown-it/CONTRIBUTING.md
@@ -0,0 +1,15 @@
+### If you commit changes:
+
+1. Make sure all tests pass.
+2. Run `./benchmark/benchmark.mjs`, make sure that performance not degraded.
+3. DON'T include auto-generated browser files to commit.
+
+### Other things:
+
+1. Prefer [gitter](https://gitter.im/markdown-it/markdown-it) for short "questions".
+ Keep issues for bug reports, suggestions and so on.
+2. Make sure to read [dev info](https://github.com/markdown-it/markdown-it/tree/master/docs)
+ prior to ask about plugins development.
+3. __Provide examples with [demo](https://markdown-it.github.io/) when possible.__
+4. Issues of "question" type are closed after several days of inactivity,
+ if not qualified as bug report, enhancement etc (see 1).
diff --git a/documents/markdown/markdown-it/README.md b/documents/markdown/markdown-it/README.md
new file mode 100644
index 0000000..1769fba
--- /dev/null
+++ b/documents/markdown/markdown-it/README.md
@@ -0,0 +1,3 @@
+This repo is generated from __[markdown-it](https://github.com/markdown-it/markdown-it)__ by script.
+
+Please, use __[markdown-it](https://github.com/markdown-it)__ for all questions & PRs.
diff --git a/documents/markdown/markdown-it/api_header.md b/documents/markdown/markdown-it/api_header.md
new file mode 100644
index 0000000..65da378
--- /dev/null
+++ b/documents/markdown/markdown-it/api_header.md
@@ -0,0 +1,215 @@
+# markdown-it
+
+## Install
+
+**node.js**:
+
+```bash
+npm install markdown-it
+```
+
+**browser (CDN):**
+
+- [jsDeliver CDN](http://www.jsdelivr.com/#!markdown-it "jsDelivr CDN")
+- [cdnjs.com CDN](https://cdnjs.com/libraries/markdown-it "cdnjs.com")
+
+
+## Usage examples
+
+See also:
+
+- [Development info](https://github.com/markdown-it/markdown-it/tree/master/docs) -
+ for plugins writers.
+
+
+### Simple
+
+```js
+// node.js
+// can use `require('markdown-it')` for CJS
+import markdownit from 'markdown-it'
+const md = markdownit()
+const result = md.render('# markdown-it rulezz!');
+
+// browser with UMD build, added to "window" on script load
+// Note, there is no dash in "markdownit".
+const md = window.markdownit();
+const result = md.render('# markdown-it rulezz!');
+```
+
+Single line rendering, without paragraph wrap:
+
+```js
+import markdownit from 'markdown-it'
+const md = markdownit()
+const result = md.renderInline('__markdown-it__ rulezz!');
+```
+
+
+### Init with presets and options
+
+(*) presets define combinations of active rules and options. Can be
+`"commonmark"`, `"zero"` or `"default"` (if skipped). See
+[API docs](https://markdown-it.github.io/markdown-it/#MarkdownIt.new) for more details.
+
+```js
+import markdownit from 'markdown-it'
+
+// commonmark mode
+const md = markdownit('commonmark')
+
+// default mode
+const md = markdownit()
+
+// enable everything
+const md = markdownit({
+ html: true,
+ linkify: true,
+ typographer: true
+})
+
+// full options list (defaults)
+const md = markdownit({
+ // Enable HTML tags in source
+ html: false,
+
+ // Use '/' to close single tags (<br />).
+ // This is only for full CommonMark compatibility.
+ xhtmlOut: false,
+
+ // Convert '\n' in paragraphs into <br>
+ breaks: false,
+
+ // CSS language prefix for fenced blocks. Can be
+ // useful for external highlighters.
+ langPrefix: 'language-',
+
+ // Autoconvert URL-like text to links
+ linkify: false,
+
+ // Enable some language-neutral replacement + quotes beautification
+ // For the full list of replacements, see https://github.com/markdown-it/markdown-it/blob/master/lib/rules_core/replacements.mjs
+ typographer: false,
+
+ // Double + single quotes replacement pairs, when typographer enabled,
+ // and smartquotes on. Could be either a String or an Array.
+ //
+ // For example, you can use '«»„“' for Russian, '„“‚‘' for German,
+ // and ['«\xA0', '\xA0»', '‹\xA0', '\xA0›'] for French (including nbsp).
+ quotes: '“”‘’',
+
+ // Highlighter function. Should return escaped HTML,
+ // or '' if the source string is not changed and should be escaped externally.
+ // If result starts with <pre... internal wrapper is skipped.
+ highlight: function (/*str, lang*/) { return ''; }
+});
+```
+
+
+### Plugins load
+
+```js
+import markdownit from 'markdown-it'
+
+const md = markdownit
+ .use(plugin1)
+ .use(plugin2, opts, ...)
+ .use(plugin3);
+```
+
+
+### Syntax highlighting
+
+Apply syntax highlighting to fenced code blocks with the `highlight` option:
+
+```js
+import markdownit from 'markdown-it'
+import hljs from 'highlight.js' // https://highlightjs.org
+
+// Actual default values
+const md = markdownit({
+ highlight: function (str, lang) {
+ if (lang && hljs.getLanguage(lang)) {
+ try {
+ return hljs.highlight(str, { language: lang }).value;
+ } catch (__) {}
+ }
+
+ return ''; // use external default escaping
+ }
+});
+```
+
+Or with full wrapper override (if you need assign class to `<pre>` or `<code>`):
+
+```js
+import markdownit from 'markdown-it'
+import hljs from 'highlight.js' // https://highlightjs.org
+
+// Actual default values
+const md = markdownit({
+ highlight: function (str, lang) {
+ if (lang && hljs.getLanguage(lang)) {
+ try {
+ return '<pre><code class="hljs">' +
+ hljs.highlight(str, { language: lang, ignoreIllegals: true }).value +
+ '</code></pre>';
+ } catch (__) {}
+ }
+
+ return '<pre><code class="hljs">' + md.utils.escapeHtml(str) + '</code></pre>';
+ }
+});
+```
+
+### Linkify
+
+`linkify: true` uses [linkify-it](https://github.com/markdown-it/linkify-it). To
+configure linkify-it, access the linkify instance through `md.linkify`:
+
+```js
+md.linkify.set({ fuzzyEmail: false }); // disables converting email to link
+```
+
+## Syntax extensions
+
+Embedded (enabled by default):
+
+- [Tables](https://help.github.com/articles/organizing-information-with-tables/) (GFM)
+- [Strikethrough](https://help.github.com/articles/basic-writing-and-formatting-syntax/#styling-text) (GFM)
+
+Via plugins:
+
+- [subscript](https://github.com/markdown-it/markdown-it-sub)
+- [superscript](https://github.com/markdown-it/markdown-it-sup)
+- [footnote](https://github.com/markdown-it/markdown-it-footnote)
+- [definition list](https://github.com/markdown-it/markdown-it-deflist)
+- [abbreviation](https://github.com/markdown-it/markdown-it-abbr)
+- [emoji](https://github.com/markdown-it/markdown-it-emoji)
+- [custom container](https://github.com/markdown-it/markdown-it-container)
+- [insert](https://github.com/markdown-it/markdown-it-ins)
+- [mark](https://github.com/markdown-it/markdown-it-mark)
+- ... and [others](https://www.npmjs.org/browse/keyword/markdown-it-plugin)
+
+
+### Manage rules
+
+By default all rules are enabled, but can be restricted by options. On plugin
+load all its rules are enabled automatically.
+
+```js
+import markdownit from 'markdown-it'
+
+// Activate/deactivate rules, with currying
+const md = markdownit()
+ .disable(['link', 'image'])
+ .enable(['link'])
+ .enable('image');
+
+// Enable everything
+const md = markdownit({
+ html: true,
+ linkify: true,
+ typographer: true,
+});
+```
diff --git a/documents/markdown/markdown-it/architecture.md b/documents/markdown/markdown-it/architecture.md
new file mode 100644
index 0000000..a3cccdb
--- /dev/null
+++ b/documents/markdown/markdown-it/architecture.md
@@ -0,0 +1,186 @@
+# markdown-it design principles
+
+## Data flow
+
+Input data is parsed via nested chains of rules. There are 3 nested chains --
+`core`, `block`, & `inline`:
+
+```
+core
+ core.rule1 (normalize)
+ ...
+ core.ruleX
+
+ block
+ block.rule1 (blockquote)
+ ...
+ block.ruleX
+
+ core.ruleX1 (intermediate rule that applies on block tokens, nothing yet)
+ ...
+ core.ruleXX
+
+ inline (applied to each block token with "inline" type)
+ inline.rule1 (text)
+ ...
+ inline.ruleX
+
+ core.ruleYY (applies to all tokens)
+ ... (abbreviation, footnote, typographer, linkifier)
+```
+
+The result of parsing is a token stream that will be passed to the renderer to generate HTML content.
+
+These tokens can themselves be parsed again to generate more tokens (ex: a `list` token can be divided into multiple `inline` tokens).
+
+An `env` object can be used alongside tokens to inject external variables into your parsers and renderers.
+
+Each chain (`core`, `block`, & `inline`) uses an independent `state` object when parsing data so that each parsing operation is independent and can be disabled on the fly.
+
+
+## Token stream
+
+Instead of a traditional AST, we use more low-level data representation -- *tokens*.
+The difference is simple:
+
+- Tokens are a simple sequence (an array).
+- Opening and closing tags are separate.
+- There are special token objects, "inline containers", that have nested tokens.
+ These are sequences with inline markup, such as bold, italic, text, etc.
+
+See the [`Token`](https://github.com/markdown-it/markdown-it/blob/master/lib/token.mjs) class
+for details about each token's content.
+
+In total, a token stream is:
+
+- On the top level -- an array of paired or single "block" tokens:
+ - open/close for headers, lists, blockquotes, paragraphs, etc.
+ - code blocks, fenced blocks, horizontal rules, HTML blocks, inline containers
+- Each inline token has a `children` property with a nested token stream for inline content:
+ - open/close for bold, italic, links, inline code, etc.
+ - text, line breaks
+
+Why not an AST? It's not needed for our tasks. We follow the KISS principle.
+If you wish, you can call a parser without a renderer and convert the token stream
+into an AST.
+
+More details about tokens:
+
+- [`Renderer` source](https://github.com/markdown-it/markdown-it/blob/master/lib/renderer.mjs)
+- [`Token` source](https://github.com/markdown-it/markdown-it/blob/master/lib/token.mjs)
+- [Live demo](https://markdown-it.github.io/) - type your text and click the `debug` tab.
+
+
+## Rules
+
+Rules are functions, doing "magic" with parser `state` objects. A rule is associated with one or more *chains* and is unique. For instance, a `blockquote` token is associated with the `blockquote`, `paragraph`, `heading`, and `list` chains.
+
+Rules are managed by name via [`Ruler`](https://markdown-it.github.io/markdown-it/#Ruler) instances and can be enabled and disabled from [`MarkdownIt`](https://markdown-it.github.io/markdown-it/#MarkdownIt)'s methods.
+
+Note that some rules have a `validation mode` -- in this mode, rules do not
+modify the token stream and only look ahead for the end of a token. It's one
+important design principle -- a token stream is "write only" on the `block` & `inline` parse stages.
+
+Parsers are designed to keep rules independent of each other. You can safely enable/disable them or
+add new ones. There are no universal recipes for how to create new rules -- the design of
+distributed state machines with good data isolation is a tricky business. However, you
+can investigate existing rules & plugins to see possible approaches.
+
+In complex cases you can try to ask for help in the [issue tracker](https://github.com/markdown-it/markdown-it/issues).
+The condition is very simple -- it should be clear from your ticket that you studied the docs, sources,
+and tried to do something yourself. We never reject with help to real developers.
+
+
+## Renderer
+
+After the token stream is generated, it's passed to a [`Renderer`](https://markdown-it.github.io/markdown-it/#Renderer).
+It then iterates through all the tokens, passing each to a rule with the same name as its token type.
+
+Renderer rules are located in `md.renderer.rules[name]` and are simple functions
+with the same signature:
+
+```js
+function (tokens, idx, options, env, renderer) {
+ // ...
+ return htmlResult;
+}
+```
+
+In many cases, that allows easy output changes even without parser intrusion.
+For example, let's convert every image that uses a Vimeo link into a player iframe:
+
+```js
+var md = require('markdown-it')();
+
+var defaultRender = md.renderer.rules.image,
+ vimeoRE = /^https?:\/\/(www\.)?vimeo.com\/(\d+)($|\/)/;
+
+md.renderer.rules.image = function (tokens, idx, options, env, self) {
+ var src = tokens[idx].attrGet('src');
+
+ if (vimeoRE.test(src)) {
+ var id = src.match(vimeoRE)[2];
+
+ return '<div class="embed-responsive embed-responsive-16by9">\n' +
+ ' <iframe class="embed-responsive-item" src="//player.vimeo.com/video/' + id + '"></iframe>\n' +
+ '</div>\n';
+ }
+
+ // Pass the token to the default renderer.
+ return defaultRender(tokens, idx, options, env, self);
+};
+```
+
+Here is another example on how to add `target="_blank"` to all links:
+
+```js
+// Remember the old renderer if overridden, or proxy to the default renderer.
+var defaultRender = md.renderer.rules.link_open || function (tokens, idx, options, env, self) {
+ return self.renderToken(tokens, idx, options);
+};
+
+md.renderer.rules.link_open = function (tokens, idx, options, env, self) {
+ // Add a new `target` attribute, or replace the value of the existing one.
+ tokens[idx].attrSet('target', '_blank');
+
+ // Pass the token to the default renderer.
+ return defaultRender(tokens, idx, options, env, self);
+};
+```
+
+Note that if you need to add attributes, you can do so without a renderer override.
+For example, you can update tokens in the `core` chain. This is slower than a direct
+renderer override, but it can be more simple. Let's use the
+[`markdown-it-for-inline`](https://github.com/markdown-it/markdown-it-for-inline) plugin
+to do the same thing as in previous example:
+
+```js
+var iterator = require('markdown-it-for-inline');
+
+var md = require('markdown-it')()
+ .use(iterator, 'url_new_win', 'link_open', function (tokens, idx) {
+ tokens[idx].attrSet('target', '_blank');
+ });
+```
+
+You also can write your own renderer to generate formats other than HTML, such as
+JSON and XML. You can even use it to generate an AST.
+
+
+## Summary
+
+This was mentioned in [Data flow](#data-flow), but let's repeat the sequence again:
+
+1. Blocks are parsed, and the top level of each token stream is filled with block tokens.
+2. Content in inline containers is parsed, filling their `children` properties.
+3. Rendering happens.
+
+And somewhere in between, you can apply additional transformations.
+
+Source code for each chain can be seen in the following files:
+
+- [`parser_core.mjs`](https://github.com/markdown-it/markdown-it/blob/master/lib/parser_core.mjs)
+- [`parser_block.mjs`](https://github.com/markdown-it/markdown-it/blob/master/lib/parser_block.mjs)
+- [`parser_inline.mjs`](https://github.com/markdown-it/markdown-it/blob/master/lib/parser_inline.mjs)
+
+Also, you can change output directly in a [`Renderer`](https://markdown-it.github.io/markdown-it/#Renderer) for many simple cases.
diff --git a/documents/markdown/markdown-it/block-ref-list.md b/documents/markdown/markdown-it/block-ref-list.md
new file mode 100644
index 0000000..00ff675
--- /dev/null
+++ b/documents/markdown/markdown-it/block-ref-list.md
@@ -0,0 +1,50 @@
+[item 1]: <1>
+[item 2]: <2>
+[item 3]: <3>
+[item 4]: <4>
+[item 5]: <5>
+[item 6]: <6>
+[item 7]: <7>
+[item 8]: <8>
+[item 9]: <9>
+[item 10]: <10>
+[item 11]: <11>
+[item 12]: <12>
+[item 13]: <13>
+[item 14]: <14>
+[item 15]: <15>
+[item 16]: <16>
+[item 17]: <17>
+[item 18]: <18>
+[item 19]: <19>
+[item 20]: <20>
+[item 21]: <21>
+[item 22]: <22>
+[item 23]: <23>
+[item 24]: <24>
+[item 25]: <25>
+[item 26]: <26>
+[item 27]: <27>
+[item 28]: <28>
+[item 29]: <29>
+[item 30]: <30>
+[item 31]: <31>
+[item 32]: <32>
+[item 33]: <33>
+[item 34]: <34>
+[item 35]: <35>
+[item 36]: <36>
+[item 37]: <37>
+[item 38]: <38>
+[item 39]: <39>
+[item 40]: <40>
+[item 41]: <41>
+[item 42]: <42>
+[item 43]: <43>
+[item 44]: <44>
+[item 45]: <45>
+[item 46]: <46>
+[item 47]: <47>
+[item 48]: <48>
+[item 49]: <49>
+[item 50]: <50>
diff --git a/documents/markdown/markdown-it/block-tables.md b/documents/markdown/markdown-it/block-tables.md
new file mode 100644
index 0000000..5fd6321
--- /dev/null
+++ b/documents/markdown/markdown-it/block-tables.md
@@ -0,0 +1,21 @@
+| Heading 1 | Heading 2
+| --------- | ---------
+| Cell 1 | Cell 2
+| Cell 3 | Cell 4
+
+| Header 1 | Header 2 | Header 3 | Header 4 |
+| :------: | -------: | :------- | -------- |
+| Cell 1 | Cell 2 | Cell 3 | Cell 4 |
+| Cell 5 | Cell 6 | Cell 7 | Cell 8 |
+
+ Test code
+
+Header 1 | Header 2
+-------- | --------
+Cell 1 | Cell 2
+Cell 3 | Cell 4
+
+Header 1|Header 2|Header 3|Header 4
+:-------|:------:|-------:|--------
+Cell 1 |Cell 2 |Cell 3 |Cell 4
+*Cell 5*|Cell 6 |Cell 7 |Cell 8
diff --git a/documents/markdown/markdown-it/bug_report.md b/documents/markdown/markdown-it/bug_report.md
new file mode 100644
index 0000000..9ecb043
--- /dev/null
+++ b/documents/markdown/markdown-it/bug_report.md
@@ -0,0 +1,28 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+<!--
+
+Please note, this package is about IMPLEMENTATION of CommonMark https://commonmark.org/, not about markdown itself. We stay aside of markup discussions. Prior to report a bug, make sure it's about this package, not generic thing.
+
+**Before you post**
+
+1. https://spec.commonmark.org/ - make sure you've read CommonMark spec.
+2. https://spec.commonmark.org/dingus/ - if you think you found parse error, check it in reference implementation first.
+
+**In your report**
+
+It will be very helpful, if you can provide permalinks with online samples and explain the difference:
+
+- https://markdown-it.github.io/ - online demo of `markdown-it`.
+- https://spec.commonmark.org/dingus/ - online demo of reference CommonMark's implementation.
+
+If you wish to provide code sample - make sure it is as small as possible and can be executed.
+
+-->
diff --git a/documents/markdown/markdown-it/commonmark_extras.md b/documents/markdown/markdown-it/commonmark_extras.md
new file mode 100644
index 0000000..558c011
--- /dev/null
+++ b/documents/markdown/markdown-it/commonmark_extras.md
@@ -0,0 +1,742 @@
+Issue commonmark/cmark#383:
+.
+*****Hello*world****
+.
+<p>**<em><strong>Hello<em>world</em></strong></em></p>
+.
+
+Issue #246. Double escaping in ALT
+.
+
+.
+<p><img src="#" alt="&"></p>
+.
+
+Strip markdown in ALT tags
+.
+](#)
+.
+<p><img src="#" alt="strip markdown in alt"></p>
+.
+
+Issue #55:
+.
+![test]
+
+
+.
+<p>![test]</p>
+<p></p>
+.
+
+
+Reference labels: 'i̇θωkå'.toUpperCase() is 'İΘΩKÅ', but these should still be equivalent
+.
+[İϴΩKÅ]
+
+[i̇θωkå]: /url
+.
+<p><a href="/url">İϴΩKÅ</a></p>
+.
+
+
+Reference labels: support ligatures (equivalent according to unicode case folding)
+.
+[fffifl]
+
+[fffifl]: /url
+.
+<p><a href="/url">fffifl</a></p>
+.
+
+Reference can be interrupted by other rules
+.
+[foo]: /url 'title
+ - - -
+'
+
+[foo]
+.
+<p>[foo]: /url 'title</p>
+<hr>
+<p>’</p>
+<p>[foo]</p>
+.
+
+Escape character in link reference title doesn't escape newlines
+.
+[foo]: /url "
+hello
+\
+\
+\
+world
+"
+
+[foo]
+.
+<p><a href="/url" title="
+hello
+\
+\
+\
+world
+">foo</a></p>
+.
+
+Issue #35. `<` should work as punctuation
+.
+an **(:**<br>
+.
+<p>an <strong>(:</strong><br></p>
+.
+
+
+Should unescape only needed things in link destinations/titles:
+.
+[test](<\f\o\o\>\\>)
+
+[test](foo "\\\"\b\a\r")
+.
+<p><a href="%5Cf%5Co%5Co%3E%5C">test</a></p>
+<p><a href="foo" title="\"\b\a\r">test</a></p>
+.
+
+
+Not a closing tag
+.
+</ 123>
+.
+<p></ 123></p>
+.
+
+
+
+Escaping entities in links:
+.
+[](<"> "&ö")
+
+[](<\"> "\&\ö")
+
+[](<\\"> "\\"\\ö")
+.
+<p><a href="%22" title="&ö"></a></p>
+<p><a href="&quot;" title="&amp;&ouml;"></a></p>
+<p><a href="%5C%22" title="\"\ö"></a></p>
+.
+
+
+Checking combination of replaceEntities and unescapeMd:
+.
+~~~ &&bad;\&\\&
+just a funny little fence
+~~~
+.
+<pre><code class="&&bad;&amp;\&">just a funny little fence
+</code></pre>
+.
+
+Underscore between punctuation chars should be able to close emphasis.
+
+.
+_(hai)_.
+.
+<p><em>(hai)</em>.</p>
+.
+
+Regression test, should not match emphasis markers in different link tags:
+.
+[*b]() [c*]()
+.
+<p><a href="">*b</a> <a href="">c*</a></p>
+.
+
+Those are two separate blockquotes:
+.
+ - > foo
+ > bar
+.
+<ul>
+<li>
+<blockquote>
+<p>foo</p>
+</blockquote>
+</li>
+</ul>
+<blockquote>
+<p>bar</p>
+</blockquote>
+.
+
+Blockquote should terminate itself after paragraph continuation
+.
+- list
+ > blockquote
+blockquote continuation
+ - next list item
+.
+<ul>
+<li>list
+<blockquote>
+<p>blockquote
+blockquote continuation</p>
+</blockquote>
+<ul>
+<li>next list item</li>
+</ul>
+</li>
+</ul>
+.
+
+Regression test (code block + regular paragraph)
+.
+> foo
+> bar
+.
+<blockquote>
+<pre><code>foo
+</code></pre>
+<p>bar</p>
+</blockquote>
+.
+
+Regression test (tabs in lists, #830)
+.
+1. asd
+ 2. asd
+
+---
+
+1. asd
+ 2. asd
+.
+<ol>
+<li>asd
+2. asd</li>
+</ol>
+<hr>
+<ol>
+<li>asd
+2. asd</li>
+</ol>
+.
+
+Blockquotes inside indented lists should terminate correctly
+.
+ - a
+ > b
+ ```
+ c
+ ```
+ - d
+.
+<ul>
+<li>a
+<blockquote>
+<p>b</p>
+</blockquote>
+<pre><code>c
+</code></pre>
+</li>
+<li>d</li>
+</ul>
+.
+
+Don't output empty class here:
+.
+``` 
+test
+```
+.
+<pre><code>test
+</code></pre>
+.
+
+Setext header text supports lazy continuations:
+.
+ - foo
+bar
+ ===
+.
+<ul>
+<li>
+<h1>foo
+bar</h1>
+</li>
+</ul>
+.
+
+But setext header underline doesn't:
+.
+ - foo
+ bar
+ ===
+.
+<ul>
+<li>foo
+bar
+===</li>
+</ul>
+.
+
+Tabs should be stripped from the beginning of the line
+.
+ foo
+ bar
+ baz
+.
+<p>foo
+bar
+baz</p>
+.
+
+Tabs should not cause hardbreak, EOL tabs aren't stripped in commonmark 0.27
+.
+foo1
+foo2
+bar
+.
+<p>foo1
+foo2<br>
+bar</p>
+.
+
+List item terminating quote should not be paragraph continuation
+.
+1. foo
+ > quote
+2. bar
+.
+<ol>
+<li>foo
+<blockquote>
+<p>quote</p>
+</blockquote>
+</li>
+<li>bar</li>
+</ol>
+.
+
+
+Link destination cannot contain '<'
+.
+[](<foo<bar>)
+
+[](<foo\<bar>)
+.
+<p>[](<foo<bar>)</p>
+<p><a href="foo%3Cbar"></a></p>
+.
+
+
+Link title cannot contain '(' when opened with it
+.
+[](url (xxx())
+
+[](url (xxx\())
+.
+<p>[](url (xxx())</p>
+<p><a href="url" title="xxx("></a></p>
+.
+
+
+Escaped space is not allowed in link destination, commonmark/CommonMark#493.
+.
+[link](a\ b)
+.
+<p>[link](a\ b)</p>
+.
+
+
+Allow EOL in processing instructions, commonmark/commonmark.js#196.
+.
+a <?
+?>
+.
+<p>a <?
+?></p>
+.
+
+
+Allow meta tag in an inline context, commonmark/commonmark-spec#527.
+.
+City:
+<span itemprop="contentLocation" itemscope itemtype="https://schema.org/City">
+ <meta itemprop="name" content="Springfield">
+</span>
+.
+<p>City:
+<span itemprop="contentLocation" itemscope itemtype="https://schema.org/City">
+<meta itemprop="name" content="Springfield">
+</span></p>
+.
+
+
+Coverage. Directive can terminate paragraph.
+.
+a
+<?php
+.
+<p>a</p>
+<?php
+.
+
+
+Coverage. Nested email autolink (silent mode)
+.
+*<foo@bar.com>*
+.
+<p><em><a href="mailto:foo@bar.com">foo@bar.com</a></em></p>
+.
+
+
+Coverage. Unpaired nested backtick (silent mode)
+.
+*`foo*
+.
+<p><em>`foo</em></p>
+.
+
+
+Coverage. Should continue scanning after closing "```" despite cache
+.
+```aaa``bbb``ccc```ddd``eee``
+.
+<p><code>aaa``bbb``ccc</code>ddd<code>eee</code></p>
+.
+
+
+Coverage. Entities.
+.
+*&*
+
+* *
+
+*&*
+.
+<p><em>&</em></p>
+<p><em> </em></p>
+<p><em>&</em></p>
+.
+
+
+Coverage. Escape.
+.
+*\a*
+.
+<p><em>\a</em></p>
+.
+
+
+Coverage. parseLinkDestination
+.
+[foo](<
+bar>)
+
+[foo](<bar)
+.
+<p>[foo](<
+bar>)</p>
+<p>[foo](<bar)</p>
+.
+
+
+Coverage. parseLinkTitle
+.
+[foo](bar "ba)
+
+[foo](bar "ba\
+z")
+.
+<p>[foo](bar "ba)</p>
+<p><a href="bar" title="ba\
+z">foo</a></p>
+.
+
+
+Coverage. Image
+.
+
+.
+<p><img src="x" alt="test"></p>
+.
+.
+![test][foo]
+
+[bar]: 123
+.
+<p>![test][foo]</p>
+.
+.
+![test][[[
+
+[bar]: 123
+.
+<p>![test][[[</p>
+.
+.
+![test](
+.
+<p>![test](</p>
+.
+
+
+Coverage. Link
+.
+[test](
+.
+<p>[test](</p>
+.
+
+
+Coverage. Reference
+.
+[
+test\
+]: 123
+foo
+bar
+.
+<p>foo
+bar</p>
+.
+.
+[
+test
+]
+.
+<p>[
+test
+]</p>
+.
+.
+> [foo]: bar
+[foo]
+.
+<blockquote></blockquote>
+<p><a href="bar">foo</a></p>
+.
+
+Coverage. Tabs in blockquotes.
+.
+> test
+
+ > test
+
+ > test
+
+> ---
+> test
+
+ > ---
+ > test
+
+ > ---
+ > test
+
+> test
+
+ > test
+
+ > test
+
+> ---
+> test
+
+ > ---
+ > test
+
+ > ---
+ > test
+.
+<blockquote>
+<pre><code> test
+</code></pre>
+</blockquote>
+<blockquote>
+<pre><code> test
+</code></pre>
+</blockquote>
+<blockquote>
+<pre><code>test
+</code></pre>
+</blockquote>
+<blockquote>
+<hr>
+<pre><code> test
+</code></pre>
+</blockquote>
+<blockquote>
+<hr>
+<pre><code> test
+</code></pre>
+</blockquote>
+<blockquote>
+<hr>
+<pre><code>test
+</code></pre>
+</blockquote>
+<blockquote>
+<pre><code> test
+</code></pre>
+</blockquote>
+<blockquote>
+<pre><code> test
+</code></pre>
+</blockquote>
+<blockquote>
+<pre><code> test
+</code></pre>
+</blockquote>
+<blockquote>
+<hr>
+<pre><code> test
+</code></pre>
+</blockquote>
+<blockquote>
+<hr>
+<pre><code> test
+</code></pre>
+</blockquote>
+<blockquote>
+<hr>
+<pre><code> test
+</code></pre>
+</blockquote>
+.
+
+Coverage. Tabs in lists.
+.
+1. foo
+
+ bar
+.
+<ol>
+<li>
+<p>foo</p>
+<pre><code> bar
+</code></pre>
+</li>
+</ol>
+.
+
+Coverage. Various tags not interrupting blockquotes because of indentation:
+.
+> foo
+ - - - -
+
+> foo
+ # not a heading
+.
+<blockquote>
+<p>foo
+- - - -</p>
+</blockquote>
+<blockquote>
+<p>foo
+# not a heading</p>
+</blockquote>
+.
+
+Coverage, entities with code > 10FFFF. Made this way for compatibility with commonmark.js.
+.
+�
+
+�
+.
+<p>�</p>
+<p>&#x1100000;</p>
+.
+
+Issue #696. Blockquotes should remember their level.
+.
+>>> foo
+bar
+>>> baz
+.
+<blockquote>
+<blockquote>
+<blockquote>
+<p>foo
+bar
+baz</p>
+</blockquote>
+</blockquote>
+</blockquote>
+.
+
+Issue #696. Blockquotes should stop when outdented from a list.
+.
+1. >>> foo
+ bar
+baz
+ >>> foo
+ >>> bar
+ >>> baz
+.
+<ol>
+<li>
+<blockquote>
+<blockquote>
+<blockquote>
+<p>foo
+bar
+baz
+foo</p>
+</blockquote>
+</blockquote>
+</blockquote>
+</li>
+</ol>
+<blockquote>
+<blockquote>
+<blockquote>
+<p>bar
+baz</p>
+</blockquote>
+</blockquote>
+</blockquote>
+.
+
+Issue #772. Header rule should not interfere with html tags.
+.
+<!--
+==
+-->
+
+<pre>
+==
+</pre>
+.
+<!--
+==
+-->
+<pre>
+==
+</pre>
+.
+
+Softbreak in image description
+.
+There is a newline in this image 
+.
+<p>There is a newline in this image <img src="https://github.com/executablebooks/" alt="here
+it is"></p>
+.
+
+Hardbreak in image description
+.
+There is a newline in this image 
+.
+<p>There is a newline in this image <img src="https://github.com/executablebooks/" alt="here
+it is"></p>
+.
+
+Html in image description
+.
+
+.
+<p><img src="image.png" alt="text <textarea> text"></p>
+.
diff --git a/documents/markdown/markdown-it/development-question.md b/documents/markdown/markdown-it/development-question.md
new file mode 100644
index 0000000..6380ce2
--- /dev/null
+++ b/documents/markdown/markdown-it/development-question.md
@@ -0,0 +1,25 @@
+---
+name: Development question
+about: ''
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+<!--
+
+Note, we have some time constrains, but we always try to help developers, who write plugins. So:
+
+- Please, avoid generic programming questions.
+- Avoid questions about markdown. Use CommonMark resources for that https://commonmark.org/.
+- If you have issue with plugin - report it to plugin's repo/author.
+- Make sure you are familiar with dev docs https://github.com/markdown-it/markdown-it/tree/master/docs, and tried to do something.
+- Code samples are welcome.
+
+Also, you may find useful this links (may be someone already solved your problem):
+
+- https://github.com/markdown-it - list of "officially" provided plugins.
+- https://www.npmjs.com/search?q=keywords:markdown-it-plugin - community-written plugins.
+
+-->
diff --git a/documents/markdown/markdown-it/development.md b/documents/markdown/markdown-it/development.md
new file mode 100644
index 0000000..782b75c
--- /dev/null
+++ b/documents/markdown/markdown-it/development.md
@@ -0,0 +1,87 @@
+# Development recommendations
+
+Before continuing, make sure you've read:
+
+1. [README](https://github.com/markdown-it/markdown-it#markdown-it)
+2. [API documentation](https://markdown-it.github.io/markdown-it/)
+3. [Architecture description](architecture.md)
+
+
+## General considerations for plugins.
+
+1. Try to find the right place for your plugin rule:
+ - Will it conflict with existing markup (by priority)?
+ - If yes - you need to write an inline or block rule.
+ - If no - you can morph tokens within core chains.
+ - Remember that token morphing in core chains is always more simple than writing
+ block or inline rules, if you don't copy existing ones. However,
+ block and inline rules are usually faster.
+ - Sometimes, it's enough to only modify the renderer, for example, to add
+ header IDs or `target="_blank"` for the links.
+ - Plugins should not require the `markdown-it` package as dependency in `package.json`.
+ If you need access to internals, those are available via a parser instance,
+ passed on plugin load. See properties of main class and nested objects.
+2. Search existing
+ [plugins](https://www.npmjs.org/browse/keyword/markdown-it-plugin)
+ or [rules](https://github.com/markdown-it/markdown-it/tree/master/lib),
+ doing something similar. It can be more simple to modify existing code,
+ instead of writing all from scratch.
+3. If you did all steps above, but still has questions - ask in
+ [tracker](https://github.com/markdown-it/markdown-it/issues). But, please:
+ - Be specific. Generic questions like "how to do plugins" and
+ "how to learn programming" are not accepted.
+ - Don't ask us to break [CommonMark](http://commonmark.org/) specification.
+ Such things should be discussed first on [CommonMark forum](http://talk.commonmark.org/).
+
+
+## Notes for NPM packages
+
+To simplify search:
+
+- add to `package.json` keywords `markdown-it` and `markdown-it-plugin` for plugins.
+- add keyword `markdown-it` for any other related packages.
+
+
+## FAQ
+
+
+#### I need async rule, how to do it?
+
+Sorry. You can't do it directly. All complex parsers are sync by nature. But you
+can use workarounds:
+
+1. On parse phase, replace content by random number and store it in `env`.
+2. Do async processing over collected data.
+3. Render content and replace those random numbers with text; or replace first, then render.
+
+Alternatively, you can render HTML, then parse it to DOM, or
+[cheerio](https://github.com/cheeriojs/cheerio) AST, and apply transformations
+in a more convenient way.
+
+
+#### How to replace part of text token with link?
+
+The right sequence is to split text to several tokens and add link tokens in between.
+The result will be: `text` + `link_open` + `text` + `link_close` + `text`.
+
+See implementations of [linkify](https://github.com/markdown-it/markdown-it/blob/master/lib/rules_core/linkify.mjs) and [emoji](https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/replace.mjs) - those do text token splits.
+
+__Note.__ Don't try to replace text with HTML markup! That's not secure.
+
+
+#### Why my inline rule is not executed?
+
+The inline parser skips pieces of texts to optimize speed. It stops only on [a small set of chars](https://github.com/markdown-it/markdown-it/blob/master/lib/rules_inline/text.mjs), which can be tokens. We did not made this list extensible for performance reasons too.
+
+If you are absolutely sure that something important is missing there - create a
+ticket and we will consider adding it as a new charcode.
+
+
+#### Why do you reject some useful things?
+
+We do a markdown parser. It should keep the "markdown spirit". Other things should
+be kept separate, in plugins, for example. We have no clear criteria, sorry.
+Probably, you will find [CommonMark forum](http://talk.commonmark.org/) a useful read to understand us better.
+
+Of course, if you find the architecture of this parser interesting for another type
+of markup, you are welcome to reuse it in another project.
diff --git a/documents/markdown/markdown-it/document_post_processing.md b/documents/markdown/markdown-it/document_post_processing.md
new file mode 100644
index 0000000..d6fd0e0
--- /dev/null
+++ b/documents/markdown/markdown-it/document_post_processing.md
@@ -0,0 +1,130 @@
+# Document-Wide Post Processing
+
+An overview of how to tweak and augment the token stream just before rendering.
+
+## Goal
+
+The output document will be surrounded by `<section>` tags. Second-level headings (`h2`) will also trigger section breaks (i.e. `</section><section>`) immediately preceding the heading.
+
+## Core Rules
+
+The top-level rule pipeline turning raw Markdown into a token array consists of **core rules**.
+The *block* and *inline* rule pipelines are run within a single "wrapper" rule in the core pipeline.
+The wrapper rules appear relatively early in the [core pipeline](https://github.com/markdown-it/markdown-it/blob/0fe7ccb4b7f30236fb05f623be6924961d296d3d/lib/parser_core.mjs#L19).
+
+```javascript
+const _rules = [
+ ['normalize', r_normalize],
+ ['block', r_block],
+ ['inline', r_inline],
+ ['linkify', r_linkify],
+ ['replacements', r_replacements],
+ ['smartquotes', r_smartquotes],
+ ['text_join', r_text_join]
+]
+```
+
+Core rules typically do *not* scan through the source text or interpret Markdown syntax.
+Rather, they usually modify or augment the token stream after an initial pass over the Markdown is complete.
+
+> [!NOTE]
+> The `normalize` rule is an exception.
+> It modifies the raw markdown (`state.src`),
+> *normalizing* (as the name implies) idiosyncrasies like platform-specific newlines and null characters.
+
+Core rules can do much more,
+but "post-processing" tasks are the most common use case.
+
+## Entry Point
+
+The new rule will be called `sectionize`.
+The plugin entry point will look like the following:
+
+```typescript
+export default function sectionize_plugin(md: MarkdownIt) {
+ md.core.ruler.push("sectionize", sectionize)
+}
+
+function sectionize(state: StateCore) {
+ return
+}
+```
+
+The new rule is pushed to the very end of the core pipeline.
+While there are valid reasons to insert plugin rules elsewhere in the pipeline,
+pushing to the end is a good default choice.
+
+> [!IMPORTANT]
+> When in doubt, always put plugin rules at the end of the pipeline.
+> This strategy minimizes the potential of breaking other rules' assumptions about state.
+
+In this case specifically, surrounding the document with `<section>` tags will **increase the nesting level** of every other token in the document.
+Certain rules might iterate over the token stream and keep a running-total nesting level,
+making assumptions about nesting level zero (for example).
+Placing the new rule at the very end keeps it from affecting those other rules.
+
+## Section Insertion Logic
+
+Because we will be inserting tokens into the token array,
+we will iterate *backwards* over the existing array so that our index pointer isn't affected by the insertions.
+
+```typescript
+function sectionize(state: StateCore) {
+ const slugs: Record<string, boolean> = {}
+ const toProcess: Array<{ slug: string; anchor: Token; target: Token }> = []
+
+ // Iterate backwards since we're splicing elements into the array
+ for (let i = state.tokens.length - 1; i >= 0; i--) {
+ const token = state.tokens[i]
+
+ if (token.type === "heading_open" && token.tag === "h2") {
+ const { open, close } = getSectionPair(state)
+ state.tokens.splice(i, 0, close, open)
+ }
+ }
+
+ // ...The plugin isn't quite done yet
+}
+
+function getSectionPair(state: StateCore) {
+ const open = new state.Token("section_open", "section", 1)
+ open.block = true
+ const close = new state.Token("section_close", "section", -1)
+ close.block = true
+
+ return { open, close }
+}
+```
+
+At this point, the tokens array now has a `</section><section>` pair immediately preceding each `<h2>`.
+However, the document itself is not yet wrapped in an overarching section.
+
+There are two cases to consider:
+
+- The document originally started with a `h2`, so it now starts with `</section>`
+- The document did not start with a `h2`
+
+Both cases are addressed with just a few lines of code:
+
+```typescript
+function sectionize(state: StateCore) {
+ // ...iteration logic from above
+
+ if (state.tokens[0].type === "section_close") {
+ state.tokens.push(state.tokens.shift()!)
+ } else {
+ const { open, close } = getSectionPair(state)
+ state.tokens.unshift(open)
+ state.tokens.push(close)
+ }
+}
+```
+
+## Conclusion
+
+That's right: simple augmentation tasks like sectionization are straightforward to implement with core rule plugins.
+No traversal of `state.src` is required,
+because this rule is running *after* all of the block and inline rule sets.
+
+With a careful selection of rule positioning (defaulting to the end of the pipeline when in doubt),
+post-processing rules are some of the simplest to write.
diff --git a/documents/markdown/markdown-it/fatal.md b/documents/markdown/markdown-it/fatal.md
new file mode 100644
index 0000000..57e085d
--- /dev/null
+++ b/documents/markdown/markdown-it/fatal.md
@@ -0,0 +1,41 @@
+Should not throw exception on invalid chars in URL (`*` not allowed in path) [mailformed URI]
+.
+[foo](<%test>)
+.
+<p><a href="%25test">foo</a></p>
+.
+
+
+Should not throw exception on broken utf-8 sequence in URL [mailformed URI]
+.
+[foo](%C3)
+.
+<p><a href="%C3">foo</a></p>
+.
+
+
+Should not throw exception on broken utf-16 surrogates sequence in URL [mailformed URI]
+.
+[foo](�)
+.
+<p><a href="&#xD800;">foo</a></p>
+.
+
+
+Should not hang comments regexp
+.
+foo <!--- xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ->
+
+foo <!------------------------------------------------------------------->
+.
+<p>foo <!— xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx -></p>
+<p>foo <!-------------------------------------------------------------------></p>
+.
+
+
+Should not hang cdata regexp
+.
+foo <![CDATA[ xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ]>
+.
+<p>foo <![CDATA[ xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ]></p>
+.
diff --git a/documents/markdown/markdown-it/feature_request.md b/documents/markdown/markdown-it/feature_request.md
new file mode 100644
index 0000000..3f31f7b
--- /dev/null
+++ b/documents/markdown/markdown-it/feature_request.md
@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+<!--
+
+Please note, this package is highly extendable. Prior to request new feature, make sure it can not be implemented via plugins.
+
+You may also find useful this links:
+
+- https://github.com/markdown-it - list of "officially" provided plugins.
+- https://www.npmjs.com/search?q=keywords:markdown-it-plugin - community-written plugins.
+- https://github.com/markdown-it/markdown-it/tree/master/docs - docs for plugin developers.
+
+-->
diff --git a/documents/markdown/markdown-it/good.md b/documents/markdown/markdown-it/good.md
new file mode 100644
index 0000000..1dcf05d
--- /dev/null
+++ b/documents/markdown/markdown-it/good.md
@@ -0,0 +1,7839 @@
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 354
+
+.
+ foo baz bim
+.
+<pre><code>foo baz bim
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 361
+
+.
+ foo baz bim
+.
+<pre><code>foo baz bim
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 368
+
+.
+ a a
+ ὐ a
+.
+<pre><code>a a
+ὐ a
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 381
+
+.
+ - foo
+
+ bar
+.
+<ul>
+<li>
+<p>foo</p>
+<p>bar</p>
+</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 394
+
+.
+- foo
+
+ bar
+.
+<ul>
+<li>
+<p>foo</p>
+<pre><code> bar
+</code></pre>
+</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 417
+
+.
+> foo
+.
+<blockquote>
+<pre><code> foo
+</code></pre>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 426
+
+.
+- foo
+.
+<ul>
+<li>
+<pre><code> foo
+</code></pre>
+</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 438
+
+.
+ foo
+ bar
+.
+<pre><code>foo
+bar
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 447
+
+.
+ - foo
+ - bar
+ - baz
+.
+<ul>
+<li>foo
+<ul>
+<li>bar
+<ul>
+<li>baz</li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 465
+
+.
+# Foo
+.
+<h1>Foo</h1>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 471
+
+.
+* * *
+.
+<hr />
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 488
+
+.
+\!\"\#\$\%\&\'\(\)\*\+\,\-\.\/\:\;\<\=\>\?\@\[\\\]\^\_\`\{\|\}\~
+.
+<p>!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 498
+
+.
+\ \A\a\ \3\φ\«
+.
+<p>\ \A\a\ \3\φ\«</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 508
+
+.
+\*not emphasized*
+\<br/> not a tag
+\[not a link](/foo)
+\`not code`
+1\. not a list
+\* not a list
+\# not a heading
+\[foo]: /url "not a reference"
+\ö not a character entity
+.
+<p>*not emphasized*
+<br/> not a tag
+[not a link](/foo)
+`not code`
+1. not a list
+* not a list
+# not a heading
+[foo]: /url "not a reference"
+&ouml; not a character entity</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 533
+
+.
+\\*emphasis*
+.
+<p>\<em>emphasis</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 542
+
+.
+foo\
+bar
+.
+<p>foo<br />
+bar</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 554
+
+.
+`` \[\` ``
+.
+<p><code>\[\`</code></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 561
+
+.
+ \[\]
+.
+<pre><code>\[\]
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 569
+
+.
+~~~
+\[\]
+~~~
+.
+<pre><code>\[\]
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 579
+
+.
+<https://example.com?find=\*>
+.
+<p><a href="https://example.com?find=%5C*">https://example.com?find=\*</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 586
+
+.
+<a href="/bar\/)">
+.
+<a href="/bar\/)">
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 596
+
+.
+[foo](/bar\* "ti\*tle")
+.
+<p><a href="/bar*" title="ti*tle">foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 603
+
+.
+[foo]
+
+[foo]: /bar\* "ti\*tle"
+.
+<p><a href="/bar*" title="ti*tle">foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 612
+
+.
+``` foo\+bar
+foo
+```
+.
+<pre><code class="language-foo+bar">foo
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 648
+
+.
+ & © Æ Ď
+¾ ℋ ⅆ
+∲ ≧̸
+.
+<p> & © Æ Ď
+¾ ℋ ⅆ
+∲ ≧̸</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 667
+
+.
+# Ӓ Ϡ �
+.
+<p># Ӓ Ϡ �</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 680
+
+.
+" ആ ಫ
+.
+<p>" ആ ಫ</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 689
+
+.
+  &x; &#; &#x;
+�
+&#abcdef0;
+&ThisIsNotDefined; &hi?;
+.
+<p>&nbsp &x; &#; &#x;
+&#87654321;
+&#abcdef0;
+&ThisIsNotDefined; &hi?;</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 706
+
+.
+©
+.
+<p>&copy</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 716
+
+.
+&MadeUpEntity;
+.
+<p>&MadeUpEntity;</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 727
+
+.
+<a href="öö.html">
+.
+<a href="öö.html">
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 734
+
+.
+[foo](/föö "föö")
+.
+<p><a href="/f%C3%B6%C3%B6" title="föö">foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 741
+
+.
+[foo]
+
+[foo]: /föö "föö"
+.
+<p><a href="/f%C3%B6%C3%B6" title="föö">foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 750
+
+.
+``` föö
+foo
+```
+.
+<pre><code class="language-föö">foo
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 763
+
+.
+`föö`
+.
+<p><code>f&ouml;&ouml;</code></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 770
+
+.
+ föfö
+.
+<pre><code>f&ouml;f&ouml;
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 782
+
+.
+*foo*
+*foo*
+.
+<p>*foo*
+<em>foo</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 790
+
+.
+* foo
+
+* foo
+.
+<p>* foo</p>
+<ul>
+<li>foo</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 801
+
+.
+foo bar
+.
+<p>foo
+
+bar</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 809
+
+.
+	foo
+.
+<p> foo</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 816
+
+.
+[a](url "tit")
+.
+<p>[a](url "tit")</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 839
+
+.
+- `one
+- two`
+.
+<ul>
+<li>`one</li>
+<li>two`</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 878
+
+.
+***
+---
+___
+.
+<hr />
+<hr />
+<hr />
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 891
+
+.
++++
+.
+<p>+++</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 898
+
+.
+===
+.
+<p>===</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 907
+
+.
+--
+**
+__
+.
+<p>--
+**
+__</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 920
+
+.
+ ***
+ ***
+ ***
+.
+<hr />
+<hr />
+<hr />
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 933
+
+.
+ ***
+.
+<pre><code>***
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 941
+
+.
+Foo
+ ***
+.
+<p>Foo
+***</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 952
+
+.
+_____________________________________
+.
+<hr />
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 961
+
+.
+ - - -
+.
+<hr />
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 968
+
+.
+ ** * ** * ** * **
+.
+<hr />
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 975
+
+.
+- - - -
+.
+<hr />
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 984
+
+.
+- - - -
+.
+<hr />
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 993
+
+.
+_ _ _ _ a
+
+a------
+
+---a---
+.
+<p>_ _ _ _ a</p>
+<p>a------</p>
+<p>---a---</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1009
+
+.
+ *-*
+.
+<p><em>-</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1018
+
+.
+- foo
+***
+- bar
+.
+<ul>
+<li>foo</li>
+</ul>
+<hr />
+<ul>
+<li>bar</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1035
+
+.
+Foo
+***
+bar
+.
+<p>Foo</p>
+<hr />
+<p>bar</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1052
+
+.
+Foo
+---
+bar
+.
+<h2>Foo</h2>
+<p>bar</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1065
+
+.
+* Foo
+* * *
+* Bar
+.
+<ul>
+<li>Foo</li>
+</ul>
+<hr />
+<ul>
+<li>Bar</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1082
+
+.
+- Foo
+- * * *
+.
+<ul>
+<li>Foo</li>
+<li>
+<hr />
+</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1111
+
+.
+# foo
+## foo
+### foo
+#### foo
+##### foo
+###### foo
+.
+<h1>foo</h1>
+<h2>foo</h2>
+<h3>foo</h3>
+<h4>foo</h4>
+<h5>foo</h5>
+<h6>foo</h6>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1130
+
+.
+####### foo
+.
+<p>####### foo</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1145
+
+.
+#5 bolt
+
+#hashtag
+.
+<p>#5 bolt</p>
+<p>#hashtag</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1157
+
+.
+\## foo
+.
+<p>## foo</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1166
+
+.
+# foo *bar* \*baz\*
+.
+<h1>foo <em>bar</em> *baz*</h1>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1175
+
+.
+# foo
+.
+<h1>foo</h1>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1184
+
+.
+ ### foo
+ ## foo
+ # foo
+.
+<h3>foo</h3>
+<h2>foo</h2>
+<h1>foo</h1>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1197
+
+.
+ # foo
+.
+<pre><code># foo
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1205
+
+.
+foo
+ # bar
+.
+<p>foo
+# bar</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1216
+
+.
+## foo ##
+ ### bar ###
+.
+<h2>foo</h2>
+<h3>bar</h3>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1227
+
+.
+# foo ##################################
+##### foo ##
+.
+<h1>foo</h1>
+<h5>foo</h5>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1238
+
+.
+### foo ###
+.
+<h3>foo</h3>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1249
+
+.
+### foo ### b
+.
+<h3>foo ### b</h3>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1258
+
+.
+# foo#
+.
+<h1>foo#</h1>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1268
+
+.
+### foo \###
+## foo #\##
+# foo \#
+.
+<h3>foo ###</h3>
+<h2>foo ###</h2>
+<h1>foo #</h1>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1282
+
+.
+****
+## foo
+****
+.
+<hr />
+<h2>foo</h2>
+<hr />
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1293
+
+.
+Foo bar
+# baz
+Bar foo
+.
+<p>Foo bar</p>
+<h1>baz</h1>
+<p>Bar foo</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1306
+
+.
+##
+#
+### ###
+.
+<h2></h2>
+<h1></h1>
+<h3></h3>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1346
+
+.
+Foo *bar*
+=========
+
+Foo *bar*
+---------
+.
+<h1>Foo <em>bar</em></h1>
+<h2>Foo <em>bar</em></h2>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1360
+
+.
+Foo *bar
+baz*
+====
+.
+<h1>Foo <em>bar
+baz</em></h1>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1374
+
+.
+ Foo *bar
+baz*
+====
+.
+<h1>Foo <em>bar
+baz</em></h1>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1386
+
+.
+Foo
+-------------------------
+
+Foo
+=
+.
+<h2>Foo</h2>
+<h1>Foo</h1>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1401
+
+.
+ Foo
+---
+
+ Foo
+-----
+
+ Foo
+ ===
+.
+<h2>Foo</h2>
+<h2>Foo</h2>
+<h1>Foo</h1>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1419
+
+.
+ Foo
+ ---
+
+ Foo
+---
+.
+<pre><code>Foo
+---
+
+Foo
+</code></pre>
+<hr />
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1438
+
+.
+Foo
+ ----
+.
+<h2>Foo</h2>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1448
+
+.
+Foo
+ ---
+.
+<p>Foo
+---</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1459
+
+.
+Foo
+= =
+
+Foo
+--- -
+.
+<p>Foo
+= =</p>
+<p>Foo</p>
+<hr />
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1475
+
+.
+Foo
+-----
+.
+<h2>Foo</h2>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1485
+
+.
+Foo\
+----
+.
+<h2>Foo\</h2>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1496
+
+.
+`Foo
+----
+`
+
+<a title="a lot
+---
+of dashes"/>
+.
+<h2>`Foo</h2>
+<p>`</p>
+<h2><a title="a lot</h2>
+<p>of dashes"/></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1515
+
+.
+> Foo
+---
+.
+<blockquote>
+<p>Foo</p>
+</blockquote>
+<hr />
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1526
+
+.
+> foo
+bar
+===
+.
+<blockquote>
+<p>foo
+bar
+===</p>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1539
+
+.
+- Foo
+---
+.
+<ul>
+<li>Foo</li>
+</ul>
+<hr />
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1554
+
+.
+Foo
+Bar
+---
+.
+<h2>Foo
+Bar</h2>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1567
+
+.
+---
+Foo
+---
+Bar
+---
+Baz
+.
+<hr />
+<h2>Foo</h2>
+<h2>Bar</h2>
+<p>Baz</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1584
+
+.
+
+====
+.
+<p>====</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1596
+
+.
+---
+---
+.
+<hr />
+<hr />
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1605
+
+.
+- foo
+-----
+.
+<ul>
+<li>foo</li>
+</ul>
+<hr />
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1616
+
+.
+ foo
+---
+.
+<pre><code>foo
+</code></pre>
+<hr />
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1626
+
+.
+> foo
+-----
+.
+<blockquote>
+<p>foo</p>
+</blockquote>
+<hr />
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1640
+
+.
+\> foo
+------
+.
+<h2>> foo</h2>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1671
+
+.
+Foo
+
+bar
+---
+baz
+.
+<p>Foo</p>
+<h2>bar</h2>
+<p>baz</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1687
+
+.
+Foo
+bar
+
+---
+
+baz
+.
+<p>Foo
+bar</p>
+<hr />
+<p>baz</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1705
+
+.
+Foo
+bar
+* * *
+baz
+.
+<p>Foo
+bar</p>
+<hr />
+<p>baz</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1720
+
+.
+Foo
+bar
+\---
+baz
+.
+<p>Foo
+bar
+---
+baz</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1748
+
+.
+ a simple
+ indented code block
+.
+<pre><code>a simple
+ indented code block
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1762
+
+.
+ - foo
+
+ bar
+.
+<ul>
+<li>
+<p>foo</p>
+<p>bar</p>
+</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1776
+
+.
+1. foo
+
+ - bar
+.
+<ol>
+<li>
+<p>foo</p>
+<ul>
+<li>bar</li>
+</ul>
+</li>
+</ol>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1796
+
+.
+ <a/>
+ *hi*
+
+ - one
+.
+<pre><code><a/>
+*hi*
+
+- one
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1812
+
+.
+ chunk1
+
+ chunk2
+
+
+
+ chunk3
+.
+<pre><code>chunk1
+
+chunk2
+
+
+
+chunk3
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1835
+
+.
+ chunk1
+
+ chunk2
+.
+<pre><code>chunk1
+
+ chunk2
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1850
+
+.
+Foo
+ bar
+
+.
+<p>Foo
+bar</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1864
+
+.
+ foo
+bar
+.
+<pre><code>foo
+</code></pre>
+<p>bar</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1877
+
+.
+# Heading
+ foo
+Heading
+------
+ foo
+----
+.
+<h1>Heading</h1>
+<pre><code>foo
+</code></pre>
+<h2>Heading</h2>
+<pre><code>foo
+</code></pre>
+<hr />
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1897
+
+.
+ foo
+ bar
+.
+<pre><code> foo
+bar
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1910
+
+.
+
+
+ foo
+
+
+.
+<pre><code>foo
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1924
+
+.
+ foo
+.
+<pre><code>foo
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1979
+
+.
+```
+<
+ >
+```
+.
+<pre><code><
+ >
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 1993
+
+.
+~~~
+<
+ >
+~~~
+.
+<pre><code><
+ >
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2006
+
+.
+``
+foo
+``
+.
+<p><code>foo</code></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2017
+
+.
+```
+aaa
+~~~
+```
+.
+<pre><code>aaa
+~~~
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2029
+
+.
+~~~
+aaa
+```
+~~~
+.
+<pre><code>aaa
+```
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2043
+
+.
+````
+aaa
+```
+``````
+.
+<pre><code>aaa
+```
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2055
+
+.
+~~~~
+aaa
+~~~
+~~~~
+.
+<pre><code>aaa
+~~~
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2070
+
+.
+```
+.
+<pre><code></code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2077
+
+.
+`````
+
+```
+aaa
+.
+<pre><code>
+```
+aaa
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2090
+
+.
+> ```
+> aaa
+
+bbb
+.
+<blockquote>
+<pre><code>aaa
+</code></pre>
+</blockquote>
+<p>bbb</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2106
+
+.
+```
+
+
+```
+.
+<pre><code>
+
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2120
+
+.
+```
+```
+.
+<pre><code></code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2132
+
+.
+ ```
+ aaa
+aaa
+```
+.
+<pre><code>aaa
+aaa
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2144
+
+.
+ ```
+aaa
+ aaa
+aaa
+ ```
+.
+<pre><code>aaa
+aaa
+aaa
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2158
+
+.
+ ```
+ aaa
+ aaa
+ aaa
+ ```
+.
+<pre><code>aaa
+ aaa
+aaa
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2174
+
+.
+ ```
+ aaa
+ ```
+.
+<pre><code>```
+aaa
+```
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2189
+
+.
+```
+aaa
+ ```
+.
+<pre><code>aaa
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2199
+
+.
+ ```
+aaa
+ ```
+.
+<pre><code>aaa
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2211
+
+.
+```
+aaa
+ ```
+.
+<pre><code>aaa
+ ```
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2225
+
+.
+``` ```
+aaa
+.
+<p><code> </code>
+aaa</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2234
+
+.
+~~~~~~
+aaa
+~~~ ~~
+.
+<pre><code>aaa
+~~~ ~~
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2248
+
+.
+foo
+```
+bar
+```
+baz
+.
+<p>foo</p>
+<pre><code>bar
+</code></pre>
+<p>baz</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2265
+
+.
+foo
+---
+~~~
+bar
+~~~
+# baz
+.
+<h2>foo</h2>
+<pre><code>bar
+</code></pre>
+<h1>baz</h1>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2287
+
+.
+```ruby
+def foo(x)
+ return 3
+end
+```
+.
+<pre><code class="language-ruby">def foo(x)
+ return 3
+end
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2301
+
+.
+~~~~ ruby startline=3 $%@#$
+def foo(x)
+ return 3
+end
+~~~~~~~
+.
+<pre><code class="language-ruby">def foo(x)
+ return 3
+end
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2315
+
+.
+````;
+````
+.
+<pre><code class="language-;"></code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2325
+
+.
+``` aa ```
+foo
+.
+<p><code>aa</code>
+foo</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2336
+
+.
+~~~ aa ``` ~~~
+foo
+~~~
+.
+<pre><code class="language-aa">foo
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2348
+
+.
+```
+``` aaa
+```
+.
+<pre><code>``` aaa
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2427
+
+.
+<table><tr><td>
+<pre>
+**Hello**,
+
+_world_.
+</pre>
+</td></tr></table>
+.
+<table><tr><td>
+<pre>
+**Hello**,
+<p><em>world</em>.
+</pre></p>
+</td></tr></table>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2456
+
+.
+<table>
+ <tr>
+ <td>
+ hi
+ </td>
+ </tr>
+</table>
+
+okay.
+.
+<table>
+ <tr>
+ <td>
+ hi
+ </td>
+ </tr>
+</table>
+<p>okay.</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2478
+
+.
+ <div>
+ *hello*
+ <foo><a>
+.
+ <div>
+ *hello*
+ <foo><a>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2491
+
+.
+</div>
+*foo*
+.
+</div>
+*foo*
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2502
+
+.
+<DIV CLASS="foo">
+
+*Markdown*
+
+</DIV>
+.
+<DIV CLASS="foo">
+<p><em>Markdown</em></p>
+</DIV>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2518
+
+.
+<div id="foo"
+ class="bar">
+</div>
+.
+<div id="foo"
+ class="bar">
+</div>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2529
+
+.
+<div id="foo" class="bar
+ baz">
+</div>
+.
+<div id="foo" class="bar
+ baz">
+</div>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2541
+
+.
+<div>
+*foo*
+
+*bar*
+.
+<div>
+*foo*
+<p><em>bar</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2557
+
+.
+<div id="foo"
+*hi*
+.
+<div id="foo"
+*hi*
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2566
+
+.
+<div class
+foo
+.
+<div class
+foo
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2578
+
+.
+<div *???-&&&-<---
+*foo*
+.
+<div *???-&&&-<---
+*foo*
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2590
+
+.
+<div><a href="bar">*foo*</a></div>
+.
+<div><a href="bar">*foo*</a></div>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2597
+
+.
+<table><tr><td>
+foo
+</td></tr></table>
+.
+<table><tr><td>
+foo
+</td></tr></table>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2614
+
+.
+<div></div>
+``` c
+int x = 33;
+```
+.
+<div></div>
+``` c
+int x = 33;
+```
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2631
+
+.
+<a href="foo">
+*bar*
+</a>
+.
+<a href="foo">
+*bar*
+</a>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2644
+
+.
+<Warning>
+*bar*
+</Warning>
+.
+<Warning>
+*bar*
+</Warning>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2655
+
+.
+<i class="foo">
+*bar*
+</i>
+.
+<i class="foo">
+*bar*
+</i>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2666
+
+.
+</ins>
+*bar*
+.
+</ins>
+*bar*
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2681
+
+.
+<del>
+*foo*
+</del>
+.
+<del>
+*foo*
+</del>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2696
+
+.
+<del>
+
+*foo*
+
+</del>
+.
+<del>
+<p><em>foo</em></p>
+</del>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2714
+
+.
+<del>*foo*</del>
+.
+<p><del><em>foo</em></del></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2730
+
+.
+<pre language="haskell"><code>
+import Text.HTML.TagSoup
+
+main :: IO ()
+main = print $ parseTags tags
+</code></pre>
+okay
+.
+<pre language="haskell"><code>
+import Text.HTML.TagSoup
+
+main :: IO ()
+main = print $ parseTags tags
+</code></pre>
+<p>okay</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2751
+
+.
+<script type="text/javascript">
+// JavaScript example
+
+document.getElementById("demo").innerHTML = "Hello JavaScript!";
+</script>
+okay
+.
+<script type="text/javascript">
+// JavaScript example
+
+document.getElementById("demo").innerHTML = "Hello JavaScript!";
+</script>
+<p>okay</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2770
+
+.
+<textarea>
+
+*foo*
+
+_bar_
+
+</textarea>
+.
+<textarea>
+
+*foo*
+
+_bar_
+
+</textarea>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2790
+
+.
+<style
+ type="text/css">
+h1 {color:red;}
+
+p {color:blue;}
+</style>
+okay
+.
+<style
+ type="text/css">
+h1 {color:red;}
+
+p {color:blue;}
+</style>
+<p>okay</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2813
+
+.
+<style
+ type="text/css">
+
+foo
+.
+<style
+ type="text/css">
+
+foo
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2826
+
+.
+> <div>
+> foo
+
+bar
+.
+<blockquote>
+<div>
+foo
+</blockquote>
+<p>bar</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2840
+
+.
+- <div>
+- foo
+.
+<ul>
+<li>
+<div>
+</li>
+<li>foo</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2855
+
+.
+<style>p{color:red;}</style>
+*foo*
+.
+<style>p{color:red;}</style>
+<p><em>foo</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2864
+
+.
+<!-- foo -->*bar*
+*baz*
+.
+<!-- foo -->*bar*
+<p><em>baz</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2876
+
+.
+<script>
+foo
+</script>1. *bar*
+.
+<script>
+foo
+</script>1. *bar*
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2889
+
+.
+<!-- Foo
+
+bar
+ baz -->
+okay
+.
+<!-- Foo
+
+bar
+ baz -->
+<p>okay</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2907
+
+.
+<?php
+
+ echo '>';
+
+?>
+okay
+.
+<?php
+
+ echo '>';
+
+?>
+<p>okay</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2926
+
+.
+<!DOCTYPE html>
+.
+<!DOCTYPE html>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2935
+
+.
+<![CDATA[
+function matchwo(a,b)
+{
+ if (a < b && a < 0) then {
+ return 1;
+
+ } else {
+
+ return 0;
+ }
+}
+]]]]><![CDATA[>
+okay
+.
+<![CDATA[
+function matchwo(a,b)
+{
+ if (a < b && a < 0) then {
+ return 1;
+
+ } else {
+
+ return 0;
+ }
+}
+]]]]><![CDATA[>
+<p>okay</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2969
+
+.
+ <!-- foo -->
+
+ <!-- foo -->
+.
+ <!-- foo -->
+<pre><code><!-- foo -->
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2980
+
+.
+ <div>
+
+ <div>
+.
+ <div>
+<pre><code><div>
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 2994
+
+.
+Foo
+<div>
+bar
+</div>
+.
+<p>Foo</p>
+<div>
+bar
+</div>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3011
+
+.
+<div>
+bar
+</div>
+*foo*
+.
+<div>
+bar
+</div>
+*foo*
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3026
+
+.
+Foo
+<a href="bar">
+baz
+.
+<p>Foo
+<a href="bar">
+baz</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3067
+
+.
+<div>
+
+*Emphasized* text.
+
+</div>
+.
+<div>
+<p><em>Emphasized</em> text.</p>
+</div>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3080
+
+.
+<div>
+*Emphasized* text.
+</div>
+.
+<div>
+*Emphasized* text.
+</div>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3102
+
+.
+<table>
+
+<tr>
+
+<td>
+Hi
+</td>
+
+</tr>
+
+</table>
+.
+<table>
+<tr>
+<td>
+Hi
+</td>
+</tr>
+</table>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3129
+
+.
+<table>
+
+ <tr>
+
+ <td>
+ Hi
+ </td>
+
+ </tr>
+
+</table>
+.
+<table>
+ <tr>
+<pre><code><td>
+ Hi
+</td>
+</code></pre>
+ </tr>
+</table>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3178
+
+.
+[foo]: /url "title"
+
+[foo]
+.
+<p><a href="/url" title="title">foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3187
+
+.
+ [foo]:
+ /url
+ 'the title'
+
+[foo]
+.
+<p><a href="/url" title="the title">foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3198
+
+.
+[Foo*bar\]]:my_(url) 'title (with parens)'
+
+[Foo*bar\]]
+.
+<p><a href="my_(url)" title="title (with parens)">Foo*bar]</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3207
+
+.
+[Foo bar]:
+<my url>
+'title'
+
+[Foo bar]
+.
+<p><a href="my%20url" title="title">Foo bar</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3220
+
+.
+[foo]: /url '
+title
+line1
+line2
+'
+
+[foo]
+.
+<p><a href="/url" title="
+title
+line1
+line2
+">foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3239
+
+.
+[foo]: /url 'title
+
+with blank line'
+
+[foo]
+.
+<p>[foo]: /url 'title</p>
+<p>with blank line'</p>
+<p>[foo]</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3254
+
+.
+[foo]:
+/url
+
+[foo]
+.
+<p><a href="/url">foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3266
+
+.
+[foo]:
+
+[foo]
+.
+<p>[foo]:</p>
+<p>[foo]</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3278
+
+.
+[foo]: <>
+
+[foo]
+.
+<p><a href="">foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3289
+
+.
+[foo]: <bar>(baz)
+
+[foo]
+.
+<p>[foo]: <bar>(baz)</p>
+<p>[foo]</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3302
+
+.
+[foo]: /url\bar\*baz "foo\"bar\baz"
+
+[foo]
+.
+<p><a href="/url%5Cbar*baz" title="foo"bar\baz">foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3313
+
+.
+[foo]
+
+[foo]: url
+.
+<p><a href="url">foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3325
+
+.
+[foo]
+
+[foo]: first
+[foo]: second
+.
+<p><a href="first">foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3338
+
+.
+[FOO]: /url
+
+[Foo]
+.
+<p><a href="/url">Foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3347
+
+.
+[ΑΓΩ]: /φου
+
+[αγω]
+.
+<p><a href="/%CF%86%CE%BF%CF%85">αγω</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3362
+
+.
+[foo]: /url
+.
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3370
+
+.
+[
+foo
+]: /url
+bar
+.
+<p>bar</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3383
+
+.
+[foo]: /url "title" ok
+.
+<p>[foo]: /url "title" ok</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3392
+
+.
+[foo]: /url
+"title" ok
+.
+<p>"title" ok</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3403
+
+.
+ [foo]: /url "title"
+
+[foo]
+.
+<pre><code>[foo]: /url "title"
+</code></pre>
+<p>[foo]</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3417
+
+.
+```
+[foo]: /url
+```
+
+[foo]
+.
+<pre><code>[foo]: /url
+</code></pre>
+<p>[foo]</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3432
+
+.
+Foo
+[bar]: /baz
+
+[bar]
+.
+<p>Foo
+[bar]: /baz</p>
+<p>[bar]</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3447
+
+.
+# [Foo]
+[foo]: /url
+> bar
+.
+<h1><a href="/url">Foo</a></h1>
+<blockquote>
+<p>bar</p>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3458
+
+.
+[foo]: /url
+bar
+===
+[foo]
+.
+<h1>bar</h1>
+<p><a href="/url">foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3468
+
+.
+[foo]: /url
+===
+[foo]
+.
+<p>===
+<a href="/url">foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3481
+
+.
+[foo]: /foo-url "foo"
+[bar]: /bar-url
+ "bar"
+[baz]: /baz-url
+
+[foo],
+[bar],
+[baz]
+.
+<p><a href="/foo-url" title="foo">foo</a>,
+<a href="/bar-url" title="bar">bar</a>,
+<a href="/baz-url">baz</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3502
+
+.
+[foo]
+
+> [foo]: /url
+.
+<p><a href="/url">foo</a></p>
+<blockquote>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3524
+
+.
+aaa
+
+bbb
+.
+<p>aaa</p>
+<p>bbb</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3536
+
+.
+aaa
+bbb
+
+ccc
+ddd
+.
+<p>aaa
+bbb</p>
+<p>ccc
+ddd</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3552
+
+.
+aaa
+
+
+bbb
+.
+<p>aaa</p>
+<p>bbb</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3565
+
+.
+ aaa
+ bbb
+.
+<p>aaa
+bbb</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3577
+
+.
+aaa
+ bbb
+ ccc
+.
+<p>aaa
+bbb
+ccc</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3591
+
+.
+ aaa
+bbb
+.
+<p>aaa
+bbb</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3600
+
+.
+ aaa
+bbb
+.
+<pre><code>aaa
+</code></pre>
+<p>bbb</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3614
+
+.
+aaa
+bbb
+.
+<p>aaa<br />
+bbb</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3631
+
+.
+
+
+aaa
+
+
+# aaa
+
+
+.
+<p>aaa</p>
+<h1>aaa</h1>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3699
+
+.
+> # Foo
+> bar
+> baz
+.
+<blockquote>
+<h1>Foo</h1>
+<p>bar
+baz</p>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3714
+
+.
+># Foo
+>bar
+> baz
+.
+<blockquote>
+<h1>Foo</h1>
+<p>bar
+baz</p>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3729
+
+.
+ > # Foo
+ > bar
+ > baz
+.
+<blockquote>
+<h1>Foo</h1>
+<p>bar
+baz</p>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3744
+
+.
+ > # Foo
+ > bar
+ > baz
+.
+<pre><code>> # Foo
+> bar
+> baz
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3759
+
+.
+> # Foo
+> bar
+baz
+.
+<blockquote>
+<h1>Foo</h1>
+<p>bar
+baz</p>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3775
+
+.
+> bar
+baz
+> foo
+.
+<blockquote>
+<p>bar
+baz
+foo</p>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3799
+
+.
+> foo
+---
+.
+<blockquote>
+<p>foo</p>
+</blockquote>
+<hr />
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3819
+
+.
+> - foo
+- bar
+.
+<blockquote>
+<ul>
+<li>foo</li>
+</ul>
+</blockquote>
+<ul>
+<li>bar</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3837
+
+.
+> foo
+ bar
+.
+<blockquote>
+<pre><code>foo
+</code></pre>
+</blockquote>
+<pre><code>bar
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3850
+
+.
+> ```
+foo
+```
+.
+<blockquote>
+<pre><code></code></pre>
+</blockquote>
+<p>foo</p>
+<pre><code></code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3866
+
+.
+> foo
+ - bar
+.
+<blockquote>
+<p>foo
+- bar</p>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3890
+
+.
+>
+.
+<blockquote>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3898
+
+.
+>
+>
+>
+.
+<blockquote>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3910
+
+.
+>
+> foo
+>
+.
+<blockquote>
+<p>foo</p>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3923
+
+.
+> foo
+
+> bar
+.
+<blockquote>
+<p>foo</p>
+</blockquote>
+<blockquote>
+<p>bar</p>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3945
+
+.
+> foo
+> bar
+.
+<blockquote>
+<p>foo
+bar</p>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3958
+
+.
+> foo
+>
+> bar
+.
+<blockquote>
+<p>foo</p>
+<p>bar</p>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3972
+
+.
+foo
+> bar
+.
+<p>foo</p>
+<blockquote>
+<p>bar</p>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 3986
+
+.
+> aaa
+***
+> bbb
+.
+<blockquote>
+<p>aaa</p>
+</blockquote>
+<hr />
+<blockquote>
+<p>bbb</p>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4004
+
+.
+> bar
+baz
+.
+<blockquote>
+<p>bar
+baz</p>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4015
+
+.
+> bar
+
+baz
+.
+<blockquote>
+<p>bar</p>
+</blockquote>
+<p>baz</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4027
+
+.
+> bar
+>
+baz
+.
+<blockquote>
+<p>bar</p>
+</blockquote>
+<p>baz</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4043
+
+.
+> > > foo
+bar
+.
+<blockquote>
+<blockquote>
+<blockquote>
+<p>foo
+bar</p>
+</blockquote>
+</blockquote>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4058
+
+.
+>>> foo
+> bar
+>>baz
+.
+<blockquote>
+<blockquote>
+<blockquote>
+<p>foo
+bar
+baz</p>
+</blockquote>
+</blockquote>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4080
+
+.
+> code
+
+> not code
+.
+<blockquote>
+<pre><code>code
+</code></pre>
+</blockquote>
+<blockquote>
+<p>not code</p>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4134
+
+.
+A paragraph
+with two lines.
+
+ indented code
+
+> A block quote.
+.
+<p>A paragraph
+with two lines.</p>
+<pre><code>indented code
+</code></pre>
+<blockquote>
+<p>A block quote.</p>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4156
+
+.
+1. A paragraph
+ with two lines.
+
+ indented code
+
+ > A block quote.
+.
+<ol>
+<li>
+<p>A paragraph
+with two lines.</p>
+<pre><code>indented code
+</code></pre>
+<blockquote>
+<p>A block quote.</p>
+</blockquote>
+</li>
+</ol>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4189
+
+.
+- one
+
+ two
+.
+<ul>
+<li>one</li>
+</ul>
+<p>two</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4201
+
+.
+- one
+
+ two
+.
+<ul>
+<li>
+<p>one</p>
+<p>two</p>
+</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4215
+
+.
+ - one
+
+ two
+.
+<ul>
+<li>one</li>
+</ul>
+<pre><code> two
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4228
+
+.
+ - one
+
+ two
+.
+<ul>
+<li>
+<p>one</p>
+<p>two</p>
+</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4250
+
+.
+ > > 1. one
+>>
+>> two
+.
+<blockquote>
+<blockquote>
+<ol>
+<li>
+<p>one</p>
+<p>two</p>
+</li>
+</ol>
+</blockquote>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4277
+
+.
+>>- one
+>>
+ > > two
+.
+<blockquote>
+<blockquote>
+<ul>
+<li>one</li>
+</ul>
+<p>two</p>
+</blockquote>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4296
+
+.
+-one
+
+2.two
+.
+<p>-one</p>
+<p>2.two</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4309
+
+.
+- foo
+
+
+ bar
+.
+<ul>
+<li>
+<p>foo</p>
+<p>bar</p>
+</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4326
+
+.
+1. foo
+
+ ```
+ bar
+ ```
+
+ baz
+
+ > bam
+.
+<ol>
+<li>
+<p>foo</p>
+<pre><code>bar
+</code></pre>
+<p>baz</p>
+<blockquote>
+<p>bam</p>
+</blockquote>
+</li>
+</ol>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4354
+
+.
+- Foo
+
+ bar
+
+
+ baz
+.
+<ul>
+<li>
+<p>Foo</p>
+<pre><code>bar
+
+
+baz
+</code></pre>
+</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4376
+
+.
+123456789. ok
+.
+<ol start="123456789">
+<li>ok</li>
+</ol>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4385
+
+.
+1234567890. not ok
+.
+<p>1234567890. not ok</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4394
+
+.
+0. ok
+.
+<ol start="0">
+<li>ok</li>
+</ol>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4403
+
+.
+003. ok
+.
+<ol start="3">
+<li>ok</li>
+</ol>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4414
+
+.
+-1. not ok
+.
+<p>-1. not ok</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4437
+
+.
+- foo
+
+ bar
+.
+<ul>
+<li>
+<p>foo</p>
+<pre><code>bar
+</code></pre>
+</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4454
+
+.
+ 10. foo
+
+ bar
+.
+<ol start="10">
+<li>
+<p>foo</p>
+<pre><code>bar
+</code></pre>
+</li>
+</ol>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4473
+
+.
+ indented code
+
+paragraph
+
+ more code
+.
+<pre><code>indented code
+</code></pre>
+<p>paragraph</p>
+<pre><code>more code
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4488
+
+.
+1. indented code
+
+ paragraph
+
+ more code
+.
+<ol>
+<li>
+<pre><code>indented code
+</code></pre>
+<p>paragraph</p>
+<pre><code>more code
+</code></pre>
+</li>
+</ol>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4510
+
+.
+1. indented code
+
+ paragraph
+
+ more code
+.
+<ol>
+<li>
+<pre><code> indented code
+</code></pre>
+<p>paragraph</p>
+<pre><code>more code
+</code></pre>
+</li>
+</ol>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4537
+
+.
+ foo
+
+bar
+.
+<p>foo</p>
+<p>bar</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4547
+
+.
+- foo
+
+ bar
+.
+<ul>
+<li>foo</li>
+</ul>
+<p>bar</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4564
+
+.
+- foo
+
+ bar
+.
+<ul>
+<li>
+<p>foo</p>
+<p>bar</p>
+</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4591
+
+.
+-
+ foo
+-
+ ```
+ bar
+ ```
+-
+ baz
+.
+<ul>
+<li>foo</li>
+<li>
+<pre><code>bar
+</code></pre>
+</li>
+<li>
+<pre><code>baz
+</code></pre>
+</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4617
+
+.
+-
+ foo
+.
+<ul>
+<li>foo</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4631
+
+.
+-
+
+ foo
+.
+<ul>
+<li></li>
+</ul>
+<p>foo</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4645
+
+.
+- foo
+-
+- bar
+.
+<ul>
+<li>foo</li>
+<li></li>
+<li>bar</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4660
+
+.
+- foo
+-
+- bar
+.
+<ul>
+<li>foo</li>
+<li></li>
+<li>bar</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4675
+
+.
+1. foo
+2.
+3. bar
+.
+<ol>
+<li>foo</li>
+<li></li>
+<li>bar</li>
+</ol>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4690
+
+.
+*
+.
+<ul>
+<li></li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4700
+
+.
+foo
+*
+
+foo
+1.
+.
+<p>foo
+*</p>
+<p>foo
+1.</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4722
+
+.
+ 1. A paragraph
+ with two lines.
+
+ indented code
+
+ > A block quote.
+.
+<ol>
+<li>
+<p>A paragraph
+with two lines.</p>
+<pre><code>indented code
+</code></pre>
+<blockquote>
+<p>A block quote.</p>
+</blockquote>
+</li>
+</ol>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4746
+
+.
+ 1. A paragraph
+ with two lines.
+
+ indented code
+
+ > A block quote.
+.
+<ol>
+<li>
+<p>A paragraph
+with two lines.</p>
+<pre><code>indented code
+</code></pre>
+<blockquote>
+<p>A block quote.</p>
+</blockquote>
+</li>
+</ol>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4770
+
+.
+ 1. A paragraph
+ with two lines.
+
+ indented code
+
+ > A block quote.
+.
+<ol>
+<li>
+<p>A paragraph
+with two lines.</p>
+<pre><code>indented code
+</code></pre>
+<blockquote>
+<p>A block quote.</p>
+</blockquote>
+</li>
+</ol>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4794
+
+.
+ 1. A paragraph
+ with two lines.
+
+ indented code
+
+ > A block quote.
+.
+<pre><code>1. A paragraph
+ with two lines.
+
+ indented code
+
+ > A block quote.
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4824
+
+.
+ 1. A paragraph
+with two lines.
+
+ indented code
+
+ > A block quote.
+.
+<ol>
+<li>
+<p>A paragraph
+with two lines.</p>
+<pre><code>indented code
+</code></pre>
+<blockquote>
+<p>A block quote.</p>
+</blockquote>
+</li>
+</ol>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4848
+
+.
+ 1. A paragraph
+ with two lines.
+.
+<ol>
+<li>A paragraph
+with two lines.</li>
+</ol>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4861
+
+.
+> 1. > Blockquote
+continued here.
+.
+<blockquote>
+<ol>
+<li>
+<blockquote>
+<p>Blockquote
+continued here.</p>
+</blockquote>
+</li>
+</ol>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4878
+
+.
+> 1. > Blockquote
+> continued here.
+.
+<blockquote>
+<ol>
+<li>
+<blockquote>
+<p>Blockquote
+continued here.</p>
+</blockquote>
+</li>
+</ol>
+</blockquote>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4906
+
+.
+- foo
+ - bar
+ - baz
+ - boo
+.
+<ul>
+<li>foo
+<ul>
+<li>bar
+<ul>
+<li>baz
+<ul>
+<li>boo</li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4932
+
+.
+- foo
+ - bar
+ - baz
+ - boo
+.
+<ul>
+<li>foo</li>
+<li>bar</li>
+<li>baz</li>
+<li>boo</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4949
+
+.
+10) foo
+ - bar
+.
+<ol start="10">
+<li>foo
+<ul>
+<li>bar</li>
+</ul>
+</li>
+</ol>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4965
+
+.
+10) foo
+ - bar
+.
+<ol start="10">
+<li>foo</li>
+</ol>
+<ul>
+<li>bar</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4980
+
+.
+- - foo
+.
+<ul>
+<li>
+<ul>
+<li>foo</li>
+</ul>
+</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 4993
+
+.
+1. - 2. foo
+.
+<ol>
+<li>
+<ul>
+<li>
+<ol start="2">
+<li>foo</li>
+</ol>
+</li>
+</ul>
+</li>
+</ol>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5012
+
+.
+- # Foo
+- Bar
+ ---
+ baz
+.
+<ul>
+<li>
+<h1>Foo</h1>
+</li>
+<li>
+<h2>Bar</h2>
+baz</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5248
+
+.
+- foo
+- bar
++ baz
+.
+<ul>
+<li>foo</li>
+<li>bar</li>
+</ul>
+<ul>
+<li>baz</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5263
+
+.
+1. foo
+2. bar
+3) baz
+.
+<ol>
+<li>foo</li>
+<li>bar</li>
+</ol>
+<ol start="3">
+<li>baz</li>
+</ol>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5282
+
+.
+Foo
+- bar
+- baz
+.
+<p>Foo</p>
+<ul>
+<li>bar</li>
+<li>baz</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5359
+
+.
+The number of windows in my house is
+14. The number of doors is 6.
+.
+<p>The number of windows in my house is
+14. The number of doors is 6.</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5369
+
+.
+The number of windows in my house is
+1. The number of doors is 6.
+.
+<p>The number of windows in my house is</p>
+<ol>
+<li>The number of doors is 6.</li>
+</ol>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5383
+
+.
+- foo
+
+- bar
+
+
+- baz
+.
+<ul>
+<li>
+<p>foo</p>
+</li>
+<li>
+<p>bar</p>
+</li>
+<li>
+<p>baz</p>
+</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5404
+
+.
+- foo
+ - bar
+ - baz
+
+
+ bim
+.
+<ul>
+<li>foo
+<ul>
+<li>bar
+<ul>
+<li>
+<p>baz</p>
+<p>bim</p>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5434
+
+.
+- foo
+- bar
+
+<!-- -->
+
+- baz
+- bim
+.
+<ul>
+<li>foo</li>
+<li>bar</li>
+</ul>
+<!-- -->
+<ul>
+<li>baz</li>
+<li>bim</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5455
+
+.
+- foo
+
+ notcode
+
+- foo
+
+<!-- -->
+
+ code
+.
+<ul>
+<li>
+<p>foo</p>
+<p>notcode</p>
+</li>
+<li>
+<p>foo</p>
+</li>
+</ul>
+<!-- -->
+<pre><code>code
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5486
+
+.
+- a
+ - b
+ - c
+ - d
+ - e
+ - f
+- g
+.
+<ul>
+<li>a</li>
+<li>b</li>
+<li>c</li>
+<li>d</li>
+<li>e</li>
+<li>f</li>
+<li>g</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5507
+
+.
+1. a
+
+ 2. b
+
+ 3. c
+.
+<ol>
+<li>
+<p>a</p>
+</li>
+<li>
+<p>b</p>
+</li>
+<li>
+<p>c</p>
+</li>
+</ol>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5531
+
+.
+- a
+ - b
+ - c
+ - d
+ - e
+.
+<ul>
+<li>a</li>
+<li>b</li>
+<li>c</li>
+<li>d
+- e</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5551
+
+.
+1. a
+
+ 2. b
+
+ 3. c
+.
+<ol>
+<li>
+<p>a</p>
+</li>
+<li>
+<p>b</p>
+</li>
+</ol>
+<pre><code>3. c
+</code></pre>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5574
+
+.
+- a
+- b
+
+- c
+.
+<ul>
+<li>
+<p>a</p>
+</li>
+<li>
+<p>b</p>
+</li>
+<li>
+<p>c</p>
+</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5596
+
+.
+* a
+*
+
+* c
+.
+<ul>
+<li>
+<p>a</p>
+</li>
+<li></li>
+<li>
+<p>c</p>
+</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5618
+
+.
+- a
+- b
+
+ c
+- d
+.
+<ul>
+<li>
+<p>a</p>
+</li>
+<li>
+<p>b</p>
+<p>c</p>
+</li>
+<li>
+<p>d</p>
+</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5640
+
+.
+- a
+- b
+
+ [ref]: /url
+- d
+.
+<ul>
+<li>
+<p>a</p>
+</li>
+<li>
+<p>b</p>
+</li>
+<li>
+<p>d</p>
+</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5663
+
+.
+- a
+- ```
+ b
+
+
+ ```
+- c
+.
+<ul>
+<li>a</li>
+<li>
+<pre><code>b
+
+
+</code></pre>
+</li>
+<li>c</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5689
+
+.
+- a
+ - b
+
+ c
+- d
+.
+<ul>
+<li>a
+<ul>
+<li>
+<p>b</p>
+<p>c</p>
+</li>
+</ul>
+</li>
+<li>d</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5713
+
+.
+* a
+ > b
+ >
+* c
+.
+<ul>
+<li>a
+<blockquote>
+<p>b</p>
+</blockquote>
+</li>
+<li>c</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5733
+
+.
+- a
+ > b
+ ```
+ c
+ ```
+- d
+.
+<ul>
+<li>a
+<blockquote>
+<p>b</p>
+</blockquote>
+<pre><code>c
+</code></pre>
+</li>
+<li>d</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5756
+
+.
+- a
+.
+<ul>
+<li>a</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5765
+
+.
+- a
+ - b
+.
+<ul>
+<li>a
+<ul>
+<li>b</li>
+</ul>
+</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5782
+
+.
+1. ```
+ foo
+ ```
+
+ bar
+.
+<ol>
+<li>
+<pre><code>foo
+</code></pre>
+<p>bar</p>
+</li>
+</ol>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5801
+
+.
+* foo
+ * bar
+
+ baz
+.
+<ul>
+<li>
+<p>foo</p>
+<ul>
+<li>bar</li>
+</ul>
+<p>baz</p>
+</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5819
+
+.
+- a
+ - b
+ - c
+
+- d
+ - e
+ - f
+.
+<ul>
+<li>
+<p>a</p>
+<ul>
+<li>b</li>
+<li>c</li>
+</ul>
+</li>
+<li>
+<p>d</p>
+<ul>
+<li>e</li>
+<li>f</li>
+</ul>
+</li>
+</ul>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5853
+
+.
+`hi`lo`
+.
+<p><code>hi</code>lo`</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5885
+
+.
+`foo`
+.
+<p><code>foo</code></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5896
+
+.
+`` foo ` bar ``
+.
+<p><code>foo ` bar</code></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5906
+
+.
+` `` `
+.
+<p><code>``</code></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5914
+
+.
+` `` `
+.
+<p><code> `` </code></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5923
+
+.
+` a`
+.
+<p><code> a</code></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5932
+
+.
+` b `
+.
+<p><code> b </code></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5940
+
+.
+` `
+` `
+.
+<p><code> </code>
+<code> </code></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5951
+
+.
+``
+foo
+bar
+baz
+``
+.
+<p><code>foo bar baz</code></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5961
+
+.
+``
+foo
+``
+.
+<p><code>foo </code></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5972
+
+.
+`foo bar
+baz`
+.
+<p><code>foo bar baz</code></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 5989
+
+.
+`foo\`bar`
+.
+<p><code>foo\</code>bar`</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6000
+
+.
+``foo`bar``
+.
+<p><code>foo`bar</code></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6006
+
+.
+` foo `` bar `
+.
+<p><code>foo `` bar</code></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6018
+
+.
+*foo`*`
+.
+<p>*foo<code>*</code></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6027
+
+.
+[not a `link](/foo`)
+.
+<p>[not a <code>link](/foo</code>)</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6037
+
+.
+`<a href="`">`
+.
+<p><code><a href="</code>">`</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6046
+
+.
+<a href="`">`
+.
+<p><a href="`">`</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6055
+
+.
+`<https://foo.bar.`baz>`
+.
+<p><code><https://foo.bar.</code>baz>`</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6064
+
+.
+<https://foo.bar.`baz>`
+.
+<p><a href="https://foo.bar.%60baz">https://foo.bar.`baz</a>`</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6074
+
+.
+```foo``
+.
+<p>```foo``</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6081
+
+.
+`foo
+.
+<p>`foo</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6090
+
+.
+`foo``bar``
+.
+<p>`foo<code>bar</code></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6307
+
+.
+*foo bar*
+.
+<p><em>foo bar</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6317
+
+.
+a * foo bar*
+.
+<p>a * foo bar*</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6328
+
+.
+a*"foo"*
+.
+<p>a*"foo"*</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6337
+
+.
+* a *
+.
+<p>* a *</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6346
+
+.
+*$*alpha.
+
+*£*bravo.
+
+*€*charlie.
+.
+<p>*$*alpha.</p>
+<p>*£*bravo.</p>
+<p>*€*charlie.</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6361
+
+.
+foo*bar*
+.
+<p>foo<em>bar</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6368
+
+.
+5*6*78
+.
+<p>5<em>6</em>78</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6377
+
+.
+_foo bar_
+.
+<p><em>foo bar</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6387
+
+.
+_ foo bar_
+.
+<p>_ foo bar_</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6397
+
+.
+a_"foo"_
+.
+<p>a_"foo"_</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6406
+
+.
+foo_bar_
+.
+<p>foo_bar_</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6413
+
+.
+5_6_78
+.
+<p>5_6_78</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6420
+
+.
+пристаням_стремятся_
+.
+<p>пристаням_стремятся_</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6430
+
+.
+aa_"bb"_cc
+.
+<p>aa_"bb"_cc</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6441
+
+.
+foo-_(bar)_
+.
+<p>foo-<em>(bar)</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6453
+
+.
+_foo*
+.
+<p>_foo*</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6463
+
+.
+*foo bar *
+.
+<p>*foo bar *</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6472
+
+.
+*foo bar
+*
+.
+<p>*foo bar
+*</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6485
+
+.
+*(*foo)
+.
+<p>*(*foo)</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6495
+
+.
+*(*foo*)*
+.
+<p><em>(<em>foo</em>)</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6504
+
+.
+*foo*bar
+.
+<p><em>foo</em>bar</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6517
+
+.
+_foo bar _
+.
+<p>_foo bar _</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6527
+
+.
+_(_foo)
+.
+<p>_(_foo)</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6536
+
+.
+_(_foo_)_
+.
+<p><em>(<em>foo</em>)</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6545
+
+.
+_foo_bar
+.
+<p>_foo_bar</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6552
+
+.
+_пристаням_стремятся
+.
+<p>_пристаням_стремятся</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6559
+
+.
+_foo_bar_baz_
+.
+<p><em>foo_bar_baz</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6570
+
+.
+_(bar)_.
+.
+<p><em>(bar)</em>.</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6579
+
+.
+**foo bar**
+.
+<p><strong>foo bar</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6589
+
+.
+** foo bar**
+.
+<p>** foo bar**</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6600
+
+.
+a**"foo"**
+.
+<p>a**"foo"**</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6609
+
+.
+foo**bar**
+.
+<p>foo<strong>bar</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6618
+
+.
+__foo bar__
+.
+<p><strong>foo bar</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6628
+
+.
+__ foo bar__
+.
+<p>__ foo bar__</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6636
+
+.
+__
+foo bar__
+.
+<p>__
+foo bar__</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6648
+
+.
+a__"foo"__
+.
+<p>a__"foo"__</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6657
+
+.
+foo__bar__
+.
+<p>foo__bar__</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6664
+
+.
+5__6__78
+.
+<p>5__6__78</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6671
+
+.
+пристаням__стремятся__
+.
+<p>пристаням__стремятся__</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6678
+
+.
+__foo, __bar__, baz__
+.
+<p><strong>foo, <strong>bar</strong>, baz</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6689
+
+.
+foo-__(bar)__
+.
+<p>foo-<strong>(bar)</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6702
+
+.
+**foo bar **
+.
+<p>**foo bar **</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6715
+
+.
+**(**foo)
+.
+<p>**(**foo)</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6725
+
+.
+*(**foo**)*
+.
+<p><em>(<strong>foo</strong>)</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6732
+
+.
+**Gomphocarpus (*Gomphocarpus physocarpus*, syn.
+*Asclepias physocarpa*)**
+.
+<p><strong>Gomphocarpus (<em>Gomphocarpus physocarpus</em>, syn.
+<em>Asclepias physocarpa</em>)</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6741
+
+.
+**foo "*bar*" foo**
+.
+<p><strong>foo "<em>bar</em>" foo</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6750
+
+.
+**foo**bar
+.
+<p><strong>foo</strong>bar</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6762
+
+.
+__foo bar __
+.
+<p>__foo bar __</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6772
+
+.
+__(__foo)
+.
+<p>__(__foo)</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6782
+
+.
+_(__foo__)_
+.
+<p><em>(<strong>foo</strong>)</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6791
+
+.
+__foo__bar
+.
+<p>__foo__bar</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6798
+
+.
+__пристаням__стремятся
+.
+<p>__пристаням__стремятся</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6805
+
+.
+__foo__bar__baz__
+.
+<p><strong>foo__bar__baz</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6816
+
+.
+__(bar)__.
+.
+<p><strong>(bar)</strong>.</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6828
+
+.
+*foo [bar](/url)*
+.
+<p><em>foo <a href="/url">bar</a></em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6835
+
+.
+*foo
+bar*
+.
+<p><em>foo
+bar</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6847
+
+.
+_foo __bar__ baz_
+.
+<p><em>foo <strong>bar</strong> baz</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6854
+
+.
+_foo _bar_ baz_
+.
+<p><em>foo <em>bar</em> baz</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6861
+
+.
+__foo_ bar_
+.
+<p><em><em>foo</em> bar</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6868
+
+.
+*foo *bar**
+.
+<p><em>foo <em>bar</em></em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6875
+
+.
+*foo **bar** baz*
+.
+<p><em>foo <strong>bar</strong> baz</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6881
+
+.
+*foo**bar**baz*
+.
+<p><em>foo<strong>bar</strong>baz</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6905
+
+.
+*foo**bar*
+.
+<p><em>foo**bar</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6918
+
+.
+***foo** bar*
+.
+<p><em><strong>foo</strong> bar</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6925
+
+.
+*foo **bar***
+.
+<p><em>foo <strong>bar</strong></em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6932
+
+.
+*foo**bar***
+.
+<p><em>foo<strong>bar</strong></em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6943
+
+.
+foo***bar***baz
+.
+<p>foo<em><strong>bar</strong></em>baz</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6949
+
+.
+foo******bar*********baz
+.
+<p>foo<strong><strong><strong>bar</strong></strong></strong>***baz</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6958
+
+.
+*foo **bar *baz* bim** bop*
+.
+<p><em>foo <strong>bar <em>baz</em> bim</strong> bop</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6965
+
+.
+*foo [*bar*](/url)*
+.
+<p><em>foo <a href="/url"><em>bar</em></a></em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6974
+
+.
+** is not an empty emphasis
+.
+<p>** is not an empty emphasis</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6981
+
+.
+**** is not an empty strong emphasis
+.
+<p>**** is not an empty strong emphasis</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 6994
+
+.
+**foo [bar](/url)**
+.
+<p><strong>foo <a href="/url">bar</a></strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7001
+
+.
+**foo
+bar**
+.
+<p><strong>foo
+bar</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7013
+
+.
+__foo _bar_ baz__
+.
+<p><strong>foo <em>bar</em> baz</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7020
+
+.
+__foo __bar__ baz__
+.
+<p><strong>foo <strong>bar</strong> baz</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7027
+
+.
+____foo__ bar__
+.
+<p><strong><strong>foo</strong> bar</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7034
+
+.
+**foo **bar****
+.
+<p><strong>foo <strong>bar</strong></strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7041
+
+.
+**foo *bar* baz**
+.
+<p><strong>foo <em>bar</em> baz</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7048
+
+.
+**foo*bar*baz**
+.
+<p><strong>foo<em>bar</em>baz</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7055
+
+.
+***foo* bar**
+.
+<p><strong><em>foo</em> bar</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7062
+
+.
+**foo *bar***
+.
+<p><strong>foo <em>bar</em></strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7071
+
+.
+**foo *bar **baz**
+bim* bop**
+.
+<p><strong>foo <em>bar <strong>baz</strong>
+bim</em> bop</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7080
+
+.
+**foo [*bar*](/url)**
+.
+<p><strong>foo <a href="/url"><em>bar</em></a></strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7089
+
+.
+__ is not an empty emphasis
+.
+<p>__ is not an empty emphasis</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7096
+
+.
+____ is not an empty strong emphasis
+.
+<p>____ is not an empty strong emphasis</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7106
+
+.
+foo ***
+.
+<p>foo ***</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7113
+
+.
+foo *\**
+.
+<p>foo <em>*</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7120
+
+.
+foo *_*
+.
+<p>foo <em>_</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7127
+
+.
+foo *****
+.
+<p>foo *****</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7134
+
+.
+foo **\***
+.
+<p>foo <strong>*</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7141
+
+.
+foo **_**
+.
+<p>foo <strong>_</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7152
+
+.
+**foo*
+.
+<p>*<em>foo</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7159
+
+.
+*foo**
+.
+<p><em>foo</em>*</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7166
+
+.
+***foo**
+.
+<p>*<strong>foo</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7173
+
+.
+****foo*
+.
+<p>***<em>foo</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7180
+
+.
+**foo***
+.
+<p><strong>foo</strong>*</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7187
+
+.
+*foo****
+.
+<p><em>foo</em>***</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7197
+
+.
+foo ___
+.
+<p>foo ___</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7204
+
+.
+foo _\__
+.
+<p>foo <em>_</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7211
+
+.
+foo _*_
+.
+<p>foo <em>*</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7218
+
+.
+foo _____
+.
+<p>foo _____</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7225
+
+.
+foo __\___
+.
+<p>foo <strong>_</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7232
+
+.
+foo __*__
+.
+<p>foo <strong>*</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7239
+
+.
+__foo_
+.
+<p>_<em>foo</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7250
+
+.
+_foo__
+.
+<p><em>foo</em>_</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7257
+
+.
+___foo__
+.
+<p>_<strong>foo</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7264
+
+.
+____foo_
+.
+<p>___<em>foo</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7271
+
+.
+__foo___
+.
+<p><strong>foo</strong>_</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7278
+
+.
+_foo____
+.
+<p><em>foo</em>___</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7288
+
+.
+**foo**
+.
+<p><strong>foo</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7295
+
+.
+*_foo_*
+.
+<p><em><em>foo</em></em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7302
+
+.
+__foo__
+.
+<p><strong>foo</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7309
+
+.
+_*foo*_
+.
+<p><em><em>foo</em></em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7319
+
+.
+****foo****
+.
+<p><strong><strong>foo</strong></strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7326
+
+.
+____foo____
+.
+<p><strong><strong>foo</strong></strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7337
+
+.
+******foo******
+.
+<p><strong><strong><strong>foo</strong></strong></strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7346
+
+.
+***foo***
+.
+<p><em><strong>foo</strong></em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7353
+
+.
+_____foo_____
+.
+<p><em><strong><strong>foo</strong></strong></em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7362
+
+.
+*foo _bar* baz_
+.
+<p><em>foo _bar</em> baz_</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7369
+
+.
+*foo __bar *baz bim__ bam*
+.
+<p><em>foo <strong>bar *baz bim</strong> bam</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7378
+
+.
+**foo **bar baz**
+.
+<p>**foo <strong>bar baz</strong></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7385
+
+.
+*foo *bar baz*
+.
+<p>*foo <em>bar baz</em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7394
+
+.
+*[bar*](/url)
+.
+<p>*<a href="/url">bar*</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7401
+
+.
+_foo [bar_](/url)
+.
+<p>_foo <a href="/url">bar_</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7408
+
+.
+*<img src="foo" title="*"/>
+.
+<p>*<img src="foo" title="*"/></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7415
+
+.
+**<a href="**">
+.
+<p>**<a href="**"></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7422
+
+.
+__<a href="__">
+.
+<p>__<a href="__"></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7429
+
+.
+*a `*`*
+.
+<p><em>a <code>*</code></em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7436
+
+.
+_a `_`_
+.
+<p><em>a <code>_</code></em></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7443
+
+.
+**a<https://foo.bar/?q=**>
+.
+<p>**a<a href="https://foo.bar/?q=**">https://foo.bar/?q=**</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7450
+
+.
+__a<https://foo.bar/?q=__>
+.
+<p>__a<a href="https://foo.bar/?q=__">https://foo.bar/?q=__</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7538
+
+.
+[link](/uri "title")
+.
+<p><a href="/uri" title="title">link</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7548
+
+.
+[link](/uri)
+.
+<p><a href="/uri">link</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7554
+
+.
+[](./target.md)
+.
+<p><a href="./target.md"></a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7561
+
+.
+[link]()
+.
+<p><a href="">link</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7568
+
+.
+[link](<>)
+.
+<p><a href="">link</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7575
+
+.
+[]()
+.
+<p><a href=""></a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7584
+
+.
+[link](/my uri)
+.
+<p>[link](/my uri)</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7590
+
+.
+[link](</my uri>)
+.
+<p><a href="/my%20uri">link</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7599
+
+.
+[link](foo
+bar)
+.
+<p>[link](foo
+bar)</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7607
+
+.
+[link](<foo
+bar>)
+.
+<p>[link](<foo
+bar>)</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7618
+
+.
+[a](<b)c>)
+.
+<p><a href="b)c">a</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7626
+
+.
+[link](<foo\>)
+.
+<p>[link](<foo>)</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7635
+
+.
+[a](<b)c
+[a](<b)c>
+[a](<b>c)
+.
+<p>[a](<b)c
+[a](<b)c>
+[a](<b>c)</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7647
+
+.
+[link](\(foo\))
+.
+<p><a href="(foo)">link</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7656
+
+.
+[link](foo(and(bar)))
+.
+<p><a href="foo(and(bar))">link</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7665
+
+.
+[link](foo(and(bar))
+.
+<p>[link](foo(and(bar))</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7672
+
+.
+[link](foo\(and\(bar\))
+.
+<p><a href="foo(and(bar)">link</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7679
+
+.
+[link](<foo(and(bar)>)
+.
+<p><a href="foo(and(bar)">link</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7689
+
+.
+[link](foo\)\:)
+.
+<p><a href="foo):">link</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7698
+
+.
+[link](#fragment)
+
+[link](https://example.com#fragment)
+
+[link](https://example.com?foo=3#frag)
+.
+<p><a href="#fragment">link</a></p>
+<p><a href="https://example.com#fragment">link</a></p>
+<p><a href="https://example.com?foo=3#frag">link</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7714
+
+.
+[link](foo\bar)
+.
+<p><a href="foo%5Cbar">link</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7730
+
+.
+[link](foo%20bä)
+.
+<p><a href="foo%20b%C3%A4">link</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7741
+
+.
+[link]("title")
+.
+<p><a href="%22title%22">link</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7750
+
+.
+[link](/url "title")
+[link](/url 'title')
+[link](/url (title))
+.
+<p><a href="/url" title="title">link</a>
+<a href="/url" title="title">link</a>
+<a href="/url" title="title">link</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7764
+
+.
+[link](/url "title \""")
+.
+<p><a href="/url" title="title """>link</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7775
+
+.
+[link](/url "title")
+.
+<p><a href="/url%C2%A0%22title%22">link</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7784
+
+.
+[link](/url "title "and" title")
+.
+<p>[link](/url "title "and" title")</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7793
+
+.
+[link](/url 'title "and" title')
+.
+<p><a href="/url" title="title "and" title">link</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7818
+
+.
+[link]( /uri
+ "title" )
+.
+<p><a href="/uri" title="title">link</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7829
+
+.
+[link] (/uri)
+.
+<p>[link] (/uri)</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7839
+
+.
+[link [foo [bar]]](/uri)
+.
+<p><a href="/uri">link [foo [bar]]</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7846
+
+.
+[link] bar](/uri)
+.
+<p>[link] bar](/uri)</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7853
+
+.
+[link [bar](/uri)
+.
+<p>[link <a href="/uri">bar</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7860
+
+.
+[link \[bar](/uri)
+.
+<p><a href="/uri">link [bar</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7869
+
+.
+[link *foo **bar** `#`*](/uri)
+.
+<p><a href="/uri">link <em>foo <strong>bar</strong> <code>#</code></em></a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7876
+
+.
+[](/uri)
+.
+<p><a href="/uri"><img src="moon.jpg" alt="moon" /></a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7885
+
+.
+[foo [bar](/uri)](/uri)
+.
+<p>[foo <a href="/uri">bar</a>](/uri)</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7892
+
+.
+[foo *[bar [baz](/uri)](/uri)*](/uri)
+.
+<p>[foo <em>[bar <a href="/uri">baz</a>](/uri)</em>](/uri)</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7899
+
+.
+](uri2)](uri3)
+.
+<p><img src="uri3" alt="[foo](uri2)" /></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7909
+
+.
+*[foo*](/uri)
+.
+<p>*<a href="/uri">foo*</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7916
+
+.
+[foo *bar](baz*)
+.
+<p><a href="baz*">foo *bar</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7926
+
+.
+*foo [bar* baz]
+.
+<p><em>foo [bar</em> baz]</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7936
+
+.
+[foo <bar attr="](baz)">
+.
+<p>[foo <bar attr="](baz)"></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7943
+
+.
+[foo`](/uri)`
+.
+<p>[foo<code>](/uri)</code></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7950
+
+.
+[foo<https://example.com/?search=](uri)>
+.
+<p>[foo<a href="https://example.com/?search=%5D(uri)">https://example.com/?search=](uri)</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 7988
+
+.
+[foo][bar]
+
+[bar]: /url "title"
+.
+<p><a href="/url" title="title">foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8003
+
+.
+[link [foo [bar]]][ref]
+
+[ref]: /uri
+.
+<p><a href="/uri">link [foo [bar]]</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8012
+
+.
+[link \[bar][ref]
+
+[ref]: /uri
+.
+<p><a href="/uri">link [bar</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8023
+
+.
+[link *foo **bar** `#`*][ref]
+
+[ref]: /uri
+.
+<p><a href="/uri">link <em>foo <strong>bar</strong> <code>#</code></em></a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8032
+
+.
+[][ref]
+
+[ref]: /uri
+.
+<p><a href="/uri"><img src="moon.jpg" alt="moon" /></a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8043
+
+.
+[foo [bar](/uri)][ref]
+
+[ref]: /uri
+.
+<p>[foo <a href="/uri">bar</a>]<a href="/uri">ref</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8052
+
+.
+[foo *bar [baz][ref]*][ref]
+
+[ref]: /uri
+.
+<p>[foo <em>bar <a href="/uri">baz</a></em>]<a href="/uri">ref</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8067
+
+.
+*[foo*][ref]
+
+[ref]: /uri
+.
+<p>*<a href="/uri">foo*</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8076
+
+.
+[foo *bar][ref]*
+
+[ref]: /uri
+.
+<p><a href="/uri">foo *bar</a>*</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8088
+
+.
+[foo <bar attr="][ref]">
+
+[ref]: /uri
+.
+<p>[foo <bar attr="][ref]"></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8097
+
+.
+[foo`][ref]`
+
+[ref]: /uri
+.
+<p>[foo<code>][ref]</code></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8106
+
+.
+[foo<https://example.com/?search=][ref]>
+
+[ref]: /uri
+.
+<p>[foo<a href="https://example.com/?search=%5D%5Bref%5D">https://example.com/?search=][ref]</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8117
+
+.
+[foo][BaR]
+
+[bar]: /url "title"
+.
+<p><a href="/url" title="title">foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8128
+
+.
+[ẞ]
+
+[SS]: /url
+.
+<p><a href="/url">ẞ</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8140
+
+.
+[Foo
+ bar]: /url
+
+[Baz][Foo bar]
+.
+<p><a href="/url">Baz</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8153
+
+.
+[foo] [bar]
+
+[bar]: /url "title"
+.
+<p>[foo] <a href="/url" title="title">bar</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8162
+
+.
+[foo]
+[bar]
+
+[bar]: /url "title"
+.
+<p>[foo]
+<a href="/url" title="title">bar</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8203
+
+.
+[foo]: /url1
+
+[foo]: /url2
+
+[bar][foo]
+.
+<p><a href="/url1">bar</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8218
+
+.
+[bar][foo\!]
+
+[foo!]: /url
+.
+<p>[bar][foo!]</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8230
+
+.
+[foo][ref[]
+
+[ref[]: /uri
+.
+<p>[foo][ref[]</p>
+<p>[ref[]: /uri</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8240
+
+.
+[foo][ref[bar]]
+
+[ref[bar]]: /uri
+.
+<p>[foo][ref[bar]]</p>
+<p>[ref[bar]]: /uri</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8250
+
+.
+[[[foo]]]
+
+[[[foo]]]: /url
+.
+<p>[[[foo]]]</p>
+<p>[[[foo]]]: /url</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8260
+
+.
+[foo][ref\[]
+
+[ref\[]: /uri
+.
+<p><a href="/uri">foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8271
+
+.
+[bar\\]: /uri
+
+[bar\\]
+.
+<p><a href="/uri">bar\</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8283
+
+.
+[]
+
+[]: /uri
+.
+<p>[]</p>
+<p>[]: /uri</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8293
+
+.
+[
+ ]
+
+[
+ ]: /uri
+.
+<p>[
+]</p>
+<p>[
+]: /uri</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8316
+
+.
+[foo][]
+
+[foo]: /url "title"
+.
+<p><a href="/url" title="title">foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8325
+
+.
+[*foo* bar][]
+
+[*foo* bar]: /url "title"
+.
+<p><a href="/url" title="title"><em>foo</em> bar</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8336
+
+.
+[Foo][]
+
+[foo]: /url "title"
+.
+<p><a href="/url" title="title">Foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8349
+
+.
+[foo]
+[]
+
+[foo]: /url "title"
+.
+<p><a href="/url" title="title">foo</a>
+[]</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8369
+
+.
+[foo]
+
+[foo]: /url "title"
+.
+<p><a href="/url" title="title">foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8378
+
+.
+[*foo* bar]
+
+[*foo* bar]: /url "title"
+.
+<p><a href="/url" title="title"><em>foo</em> bar</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8387
+
+.
+[[*foo* bar]]
+
+[*foo* bar]: /url "title"
+.
+<p>[<a href="/url" title="title"><em>foo</em> bar</a>]</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8396
+
+.
+[[bar [foo]
+
+[foo]: /url
+.
+<p>[[bar <a href="/url">foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8407
+
+.
+[Foo]
+
+[foo]: /url "title"
+.
+<p><a href="/url" title="title">Foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8418
+
+.
+[foo] bar
+
+[foo]: /url
+.
+<p><a href="/url">foo</a> bar</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8430
+
+.
+\[foo]
+
+[foo]: /url "title"
+.
+<p>[foo]</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8442
+
+.
+[foo*]: /url
+
+*[foo*]
+.
+<p>*<a href="/url">foo*</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8454
+
+.
+[foo][bar]
+
+[foo]: /url1
+[bar]: /url2
+.
+<p><a href="/url2">foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8463
+
+.
+[foo][]
+
+[foo]: /url1
+.
+<p><a href="/url1">foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8473
+
+.
+[foo]()
+
+[foo]: /url1
+.
+<p><a href="">foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8481
+
+.
+[foo](not a link)
+
+[foo]: /url1
+.
+<p><a href="/url1">foo</a>(not a link)</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8492
+
+.
+[foo][bar][baz]
+
+[baz]: /url
+.
+<p>[foo]<a href="/url">bar</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8504
+
+.
+[foo][bar][baz]
+
+[baz]: /url1
+[bar]: /url2
+.
+<p><a href="/url2">foo</a><a href="/url1">baz</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8517
+
+.
+[foo][bar][baz]
+
+[baz]: /url1
+[foo]: /url2
+.
+<p>[foo]<a href="/url1">bar</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8540
+
+.
+
+.
+<p><img src="/url" alt="foo" title="title" /></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8547
+
+.
+![foo *bar*]
+
+[foo *bar*]: train.jpg "train & tracks"
+.
+<p><img src="train.jpg" alt="foo bar" title="train & tracks" /></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8556
+
+.
+](/url2)
+.
+<p><img src="/url2" alt="foo bar" /></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8563
+
+.
+](/url2)
+.
+<p><img src="/url2" alt="foo bar" /></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8577
+
+.
+![foo *bar*][]
+
+[foo *bar*]: train.jpg "train & tracks"
+.
+<p><img src="train.jpg" alt="foo bar" title="train & tracks" /></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8586
+
+.
+![foo *bar*][foobar]
+
+[FOOBAR]: train.jpg "train & tracks"
+.
+<p><img src="train.jpg" alt="foo bar" title="train & tracks" /></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8595
+
+.
+
+.
+<p><img src="train.jpg" alt="foo" /></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8602
+
+.
+My 
+.
+<p>My <img src="/path/to/train.jpg" alt="foo bar" title="title" /></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8609
+
+.
+
+.
+<p><img src="url" alt="foo" /></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8616
+
+.
+
+.
+<p><img src="/url" alt="" /></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8625
+
+.
+![foo][bar]
+
+[bar]: /url
+.
+<p><img src="/url" alt="foo" /></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8634
+
+.
+![foo][bar]
+
+[BAR]: /url
+.
+<p><img src="/url" alt="foo" /></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8645
+
+.
+![foo][]
+
+[foo]: /url "title"
+.
+<p><img src="/url" alt="foo" title="title" /></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8654
+
+.
+![*foo* bar][]
+
+[*foo* bar]: /url "title"
+.
+<p><img src="/url" alt="foo bar" title="title" /></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8665
+
+.
+![Foo][]
+
+[foo]: /url "title"
+.
+<p><img src="/url" alt="Foo" title="title" /></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8677
+
+.
+![foo]
+[]
+
+[foo]: /url "title"
+.
+<p><img src="/url" alt="foo" title="title" />
+[]</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8690
+
+.
+![foo]
+
+[foo]: /url "title"
+.
+<p><img src="/url" alt="foo" title="title" /></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8699
+
+.
+![*foo* bar]
+
+[*foo* bar]: /url "title"
+.
+<p><img src="/url" alt="foo bar" title="title" /></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8710
+
+.
+![[foo]]
+
+[[foo]]: /url "title"
+.
+<p>![[foo]]</p>
+<p>[[foo]]: /url "title"</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8722
+
+.
+![Foo]
+
+[foo]: /url "title"
+.
+<p><img src="/url" alt="Foo" title="title" /></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8734
+
+.
+!\[foo]
+
+[foo]: /url "title"
+.
+<p>![foo]</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8746
+
+.
+\![foo]
+
+[foo]: /url "title"
+.
+<p>!<a href="/url" title="title">foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8779
+
+.
+<http://foo.bar.baz>
+.
+<p><a href="http://foo.bar.baz">http://foo.bar.baz</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8786
+
+.
+<https://foo.bar.baz/test?q=hello&id=22&boolean>
+.
+<p><a href="https://foo.bar.baz/test?q=hello&id=22&boolean">https://foo.bar.baz/test?q=hello&id=22&boolean</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8793
+
+.
+<irc://foo.bar:2233/baz>
+.
+<p><a href="irc://foo.bar:2233/baz">irc://foo.bar:2233/baz</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8802
+
+.
+<MAILTO:FOO@BAR.BAZ>
+.
+<p><a href="MAILTO:FOO@BAR.BAZ">MAILTO:FOO@BAR.BAZ</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8814
+
+.
+<a+b+c:d>
+.
+<p><a href="a+b+c:d">a+b+c:d</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8821
+
+.
+<made-up-scheme://foo,bar>
+.
+<p><a href="made-up-scheme://foo,bar">made-up-scheme://foo,bar</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8828
+
+.
+<https://../>
+.
+<p><a href="https://../">https://../</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8835
+
+.
+<localhost:5001/foo>
+.
+<p><a href="localhost:5001/foo">localhost:5001/foo</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8844
+
+.
+<https://foo.bar/baz bim>
+.
+<p><https://foo.bar/baz bim></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8853
+
+.
+<https://example.com/\[\>
+.
+<p><a href="https://example.com/%5C%5B%5C">https://example.com/\[\</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8875
+
+.
+<foo@bar.example.com>
+.
+<p><a href="mailto:foo@bar.example.com">foo@bar.example.com</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8882
+
+.
+<foo+special@Bar.baz-bar0.com>
+.
+<p><a href="mailto:foo+special@Bar.baz-bar0.com">foo+special@Bar.baz-bar0.com</a></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8891
+
+.
+<foo\+@bar.example.com>
+.
+<p><foo+@bar.example.com></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8900
+
+.
+<>
+.
+<p><></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8907
+
+.
+< https://foo.bar >
+.
+<p>< https://foo.bar ></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8914
+
+.
+<m:abc>
+.
+<p><m:abc></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8921
+
+.
+<foo.bar.baz>
+.
+<p><foo.bar.baz></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8928
+
+.
+https://example.com
+.
+<p>https://example.com</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 8935
+
+.
+foo@bar.example.com
+.
+<p>foo@bar.example.com</p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 9015
+
+.
+<a><bab><c2c>
+.
+<p><a><bab><c2c></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 9024
+
+.
+<a/><b2/>
+.
+<p><a/><b2/></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 9033
+
+.
+<a /><b2
+data="foo" >
+.
+<p><a /><b2
+data="foo" ></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 9044
+
+.
+<a foo="bar" bam = 'baz <em>"</em>'
+_boolean zoop:33=zoop:33 />
+.
+<p><a foo="bar" bam = 'baz <em>"</em>'
+_boolean zoop:33=zoop:33 /></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 9055
+
+.
+Foo <responsive-image src="foo.jpg" />
+.
+<p>Foo <responsive-image src="foo.jpg" /></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 9064
+
+.
+<33> <__>
+.
+<p><33> <__></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 9073
+
+.
+<a h*#ref="hi">
+.
+<p><a h*#ref="hi"></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 9082
+
+.
+<a href="hi'> <a href=hi'>
+.
+<p><a href="hi'> <a href=hi'></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 9091
+
+.
+< a><
+foo><bar/ >
+<foo bar=baz
+bim!bop />
+.
+<p>< a><
+foo><bar/ >
+<foo bar=baz
+bim!bop /></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 9106
+
+.
+<a href='bar'title=title>
+.
+<p><a href='bar'title=title></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 9115
+
+.
+</a></foo >
+.
+<p></a></foo ></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 9124
+
+.
+</a href="foo">
+.
+<p></a href="foo"></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 9133
+
+.
+foo <!-- this is a --
+comment - with hyphens -->
+.
+<p>foo <!-- this is a --
+comment - with hyphens --></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 9141
+
+.
+foo <!--> foo -->
+
+foo <!---> foo -->
+.
+<p>foo <!--> foo --></p>
+<p>foo <!---> foo --></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 9153
+
+.
+foo <?php echo $a; ?>
+.
+<p>foo <?php echo $a; ?></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 9162
+
+.
+foo <!ELEMENT br EMPTY>
+.
+<p>foo <!ELEMENT br EMPTY></p>
+.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+src line: 9171
+
+.
+foo <![CDATA[>&<]]]]><![CDATA[>
+.
+<p>foo <![CDATA[>&<]]]]><
+.
+<p><a href="https://example.com">https://example.com</a></p>
+.
+
+
+don't touch text in autolinks
+.
+<https://example.com>
+.
+<p><a href="https://example.com">https://example.com</a></p>
+.
+
+
+don't touch text in html <a> tags
+.
+<a href="https://example.com">https://example.com</a>
+.
+<p><a href="https://example.com">https://example.com</a></p>
+.
+
+
+entities inside raw links
+.
+https://example.com/foo&bar
+.
+<p><a href="https://example.com/foo&amp;bar">https://example.com/foo&amp;bar</a></p>
+.
+
+
+emphasis inside raw links (asterisk, can happen in links with params)
+.
+https://example.com/foo*bar*baz
+.
+<p><a href="https://example.com/foo*bar*baz">https://example.com/foo*bar*baz</a></p>
+.
+
+
+emphasis inside raw links (underscore)
+.
+http://example.org/foo._bar_-_baz
+.
+<p><a href="http://example.org/foo._bar_-_baz">http://example.org/foo._bar_-_baz</a></p>
+.
+
+
+backticks inside raw links
+.
+https://example.com/foo`bar`baz
+.
+<p><a href="https://example.com/foo%60bar%60baz">https://example.com/foo`bar`baz</a></p>
+.
+
+
+links inside raw links
+.
+https://example.com/foo[123](456)bar
+.
+<p><a href="https://example.com/foo%5B123%5D(456)bar">https://example.com/foo[123](456)bar</a></p>
+.
+
+
+escapes not allowed at the start
+.
+\https://example.com
+.
+<p>\https://example.com</p>
+.
+
+
+escapes not allowed at comma
+.
+https\://example.com
+.
+<p>https://example.com</p>
+.
+
+
+escapes not allowed at slashes
+.
+https:\//aa.org https://bb.org
+.
+<p>https://aa.org <a href="https://bb.org">https://bb.org</a></p>
+.
+
+
+fuzzy link shouldn't match cc.org
+.
+https:/\/cc.org
+.
+<p>https://cc.org</p>
+.
+
+
+bold links (exclude markup of pairs from link tail)
+.
+**http://example.com/foobar**
+.
+<p><strong><a href="http://example.com/foobar">http://example.com/foobar</a></strong></p>
+.
+
+
+match links without protocol
+.
+www.example.org
+.
+<p><a href="http://www.example.org">www.example.org</a></p>
+.
+
+
+emails
+.
+test@example.com
+
+mailto:test@example.com
+.
+<p><a href="mailto:test@example.com">test@example.com</a></p>
+<p><a href="mailto:test@example.com">mailto:test@example.com</a></p>
+.
+
+
+typorgapher should not break href
+.
+http://example.com/(c)
+.
+<p><a href="http://example.com/(c)">http://example.com/(c)</a></p>
+.
+
+
+coverage, prefix not valid
+.
+http:/example.com/
+.
+<p>http:/example.com/</p>
+.
+
+
+coverage, negative link level
+.
+</a>[https://example.com](https://example.com)
+.
+<p></a><a href="https://example.com"><a href="https://example.com">https://example.com</a></a></p>
+.
+
+
+emphasis with '*', real link:
+.
+http://cdecl.ridiculousfish.com/?q=int+%28*f%29+%28float+*%29%3B
+.
+<p><a href="http://cdecl.ridiculousfish.com/?q=int+%28*f%29+%28float+*%29%3B">http://cdecl.ridiculousfish.com/?q=int+(*f)+(float+*)%3B</a></p>
+.
+
+
+emphasis with '_', real link:
+.
+https://www.sell.fi/sites/default/files/elainlaakarilehti/tieteelliset_artikkelit/kahkonen_t._et_al.canine_pancreatitis-_review.pdf
+.
+<p><a href="https://www.sell.fi/sites/default/files/elainlaakarilehti/tieteelliset_artikkelit/kahkonen_t._et_al.canine_pancreatitis-_review.pdf">https://www.sell.fi/sites/default/files/elainlaakarilehti/tieteelliset_artikkelit/kahkonen_t._et_al.canine_pancreatitis-_review.pdf</a></p>
+.
+
+regression test, invalid link:
+.
+i.org[x[x][xx: htt://a.b://a
+.
+<p><a href="http://i.org">i.org</a>[x[x][xx: htt://a.b://a</p>
+.
diff --git a/documents/markdown/markdown-it/mit_README.md b/documents/markdown/markdown-it/mit_README.md
new file mode 100644
index 0000000..6c79f3c
--- /dev/null
+++ b/documents/markdown/markdown-it/mit_README.md
@@ -0,0 +1,324 @@
+# markdown-it <!-- omit in toc -->
+
+[](https://github.com/markdown-it/markdown-it/actions/workflows/ci.yml)
+[](https://www.npmjs.org/package/markdown-it)
+[](https://coveralls.io/github/markdown-it/markdown-it?branch=master)
+[](https://gitter.im/markdown-it/markdown-it)
+
+> Markdown parser done right. Fast and easy to extend.
+
+__[Live demo](https://markdown-it.github.io)__
+
+- Follows the __[CommonMark spec](http://spec.commonmark.org/)__ + adds syntax extensions & sugar (URL autolinking, typographer).
+- Configurable syntax! You can add new rules and even replace existing ones.
+- High speed.
+- [Safe](https://github.com/markdown-it/markdown-it/tree/master/docs/security.md) by default.
+- Community-written __[plugins](https://www.npmjs.org/browse/keyword/markdown-it-plugin)__ and [other packages](https://www.npmjs.org/browse/keyword/markdown-it) on npm.
+
+__Table of content__
+
+- [Install](#install)
+- [Usage examples](#usage-examples)
+ - [Simple](#simple)
+ - [Init with presets and options](#init-with-presets-and-options)
+ - [Plugins load](#plugins-load)
+ - [Syntax highlighting](#syntax-highlighting)
+ - [Linkify](#linkify)
+- [API](#api)
+- [Syntax extensions](#syntax-extensions)
+ - [Manage rules](#manage-rules)
+- [Benchmark](#benchmark)
+- [markdown-it for enterprise](#markdown-it-for-enterprise)
+- [Authors](#authors)
+- [References / Thanks](#references--thanks)
+
+## Install
+
+**node.js**:
+
+```bash
+npm install markdown-it
+```
+
+**browser (CDN):**
+
+- [jsDeliver CDN](http://www.jsdelivr.com/#!markdown-it "jsDelivr CDN")
+- [cdnjs.com CDN](https://cdnjs.com/libraries/markdown-it "cdnjs.com")
+
+
+## Usage examples
+
+See also:
+
+- __[API documentation](https://markdown-it.github.io/markdown-it/)__ - for more
+ info and examples.
+- [Development info](https://github.com/markdown-it/markdown-it/tree/master/docs) -
+ for plugins writers.
+
+
+### Simple
+
+```js
+// node.js
+// can use `require('markdown-it')` for CJS
+import markdownit from 'markdown-it'
+const md = markdownit()
+const result = md.render('# markdown-it rulezz!');
+
+// browser with UMD build, added to "window" on script load
+// Note, there is no dash in "markdownit".
+const md = window.markdownit();
+const result = md.render('# markdown-it rulezz!');
+```
+
+Single line rendering, without paragraph wrap:
+
+```js
+import markdownit from 'markdown-it'
+const md = markdownit()
+const result = md.renderInline('__markdown-it__ rulezz!');
+```
+
+
+### Init with presets and options
+
+(*) presets define combinations of active rules and options. Can be
+`"commonmark"`, `"zero"` or `"default"` (if skipped). See
+[API docs](https://markdown-it.github.io/markdown-it/#MarkdownIt.new) for more details.
+
+```js
+import markdownit from 'markdown-it'
+
+// commonmark mode
+const md = markdownit('commonmark')
+
+// default mode
+const md = markdownit()
+
+// enable everything
+const md = markdownit({
+ html: true,
+ linkify: true,
+ typographer: true
+})
+
+// full options list (defaults)
+const md = markdownit({
+ // Enable HTML tags in source
+ html: false,
+
+ // Use '/' to close single tags (<br />).
+ // This is only for full CommonMark compatibility.
+ xhtmlOut: false,
+
+ // Convert '\n' in paragraphs into <br>
+ breaks: false,
+
+ // CSS language prefix for fenced blocks. Can be
+ // useful for external highlighters.
+ langPrefix: 'language-',
+
+ // Autoconvert URL-like text to links
+ linkify: false,
+
+ // Enable some language-neutral replacement + quotes beautification
+ // For the full list of replacements, see https://github.com/markdown-it/markdown-it/blob/master/lib/rules_core/replacements.mjs
+ typographer: false,
+
+ // Double + single quotes replacement pairs, when typographer enabled,
+ // and smartquotes on. Could be either a String or an Array.
+ //
+ // For example, you can use '«»„“' for Russian, '„“‚‘' for German,
+ // and ['«\xA0', '\xA0»', '‹\xA0', '\xA0›'] for French (including nbsp).
+ quotes: '“”‘’',
+
+ // Highlighter function. Should return escaped HTML,
+ // or '' if the source string is not changed and should be escaped externally.
+ // If result starts with <pre... internal wrapper is skipped.
+ highlight: function (/*str, lang*/) { return ''; }
+});
+```
+
+### Plugins load
+
+```js
+import markdownit from 'markdown-it'
+
+const md = markdownit
+ .use(plugin1)
+ .use(plugin2, opts, ...)
+ .use(plugin3);
+```
+
+
+### Syntax highlighting
+
+Apply syntax highlighting to fenced code blocks with the `highlight` option:
+
+```js
+import markdownit from 'markdown-it'
+import hljs from 'highlight.js' // https://highlightjs.org
+
+// Actual default values
+const md = markdownit({
+ highlight: function (str, lang) {
+ if (lang && hljs.getLanguage(lang)) {
+ try {
+ return hljs.highlight(str, { language: lang }).value;
+ } catch (__) {}
+ }
+
+ return ''; // use external default escaping
+ }
+});
+```
+
+Or with full wrapper override (if you need assign class to `<pre>` or `<code>`):
+
+```js
+import markdownit from 'markdown-it'
+import hljs from 'highlight.js' // https://highlightjs.org
+
+// Actual default values
+const md = markdownit({
+ highlight: function (str, lang) {
+ if (lang && hljs.getLanguage(lang)) {
+ try {
+ return '<pre><code class="hljs">' +
+ hljs.highlight(str, { language: lang, ignoreIllegals: true }).value +
+ '</code></pre>';
+ } catch (__) {}
+ }
+
+ return '<pre><code class="hljs">' + md.utils.escapeHtml(str) + '</code></pre>';
+ }
+});
+```
+
+### Linkify
+
+`linkify: true` uses [linkify-it](https://github.com/markdown-it/linkify-it). To
+configure linkify-it, access the linkify instance through `md.linkify`:
+
+```js
+md.linkify.set({ fuzzyEmail: false }); // disables converting email to link
+```
+
+
+## API
+
+__[API documentation](https://markdown-it.github.io/markdown-it/)__
+
+If you are going to write plugins, please take a look at
+[Development info](https://github.com/markdown-it/markdown-it/tree/master/docs).
+
+
+## Syntax extensions
+
+Embedded (enabled by default):
+
+- [Tables](https://help.github.com/articles/organizing-information-with-tables/) (GFM)
+- [Strikethrough](https://help.github.com/articles/basic-writing-and-formatting-syntax/#styling-text) (GFM)
+
+Via plugins:
+
+- [subscript](https://github.com/markdown-it/markdown-it-sub)
+- [superscript](https://github.com/markdown-it/markdown-it-sup)
+- [footnote](https://github.com/markdown-it/markdown-it-footnote)
+- [definition list](https://github.com/markdown-it/markdown-it-deflist)
+- [abbreviation](https://github.com/markdown-it/markdown-it-abbr)
+- [emoji](https://github.com/markdown-it/markdown-it-emoji)
+- [custom container](https://github.com/markdown-it/markdown-it-container)
+- [insert](https://github.com/markdown-it/markdown-it-ins)
+- [mark](https://github.com/markdown-it/markdown-it-mark)
+- ... and [others](https://www.npmjs.org/browse/keyword/markdown-it-plugin)
+
+
+### Manage rules
+
+By default all rules are enabled, but can be restricted by options. On plugin
+load all its rules are enabled automatically.
+
+```js
+import markdownit from 'markdown-it'
+
+// Activate/deactivate rules, with currying
+const md = markdownit()
+ .disable(['link', 'image'])
+ .enable(['link'])
+ .enable('image');
+
+// Enable everything
+const md = markdownit({
+ html: true,
+ linkify: true,
+ typographer: true,
+});
+```
+
+You can find all rules in sources:
+
+- [`parser_core.mjs`](lib/parser_core.mjs)
+- [`parser_block.mjs`](lib/parser_block.mjs)
+- [`parser_inline.mjs`](lib/parser_inline.mjs)
+
+
+## Benchmark
+
+Here is the result of readme parse at MB Pro Retina 2013 (2.4 GHz):
+
+```bash
+npm run benchmark-deps
+benchmark/benchmark.mjs readme
+
+Selected samples: (1 of 28)
+ > README
+
+Sample: README.md (7774 bytes)
+ > commonmark-reference x 1,222 ops/sec ±0.96% (97 runs sampled)
+ > current x 743 ops/sec ±0.84% (97 runs sampled)
+ > current-commonmark x 1,568 ops/sec ±0.84% (98 runs sampled)
+ > marked x 1,587 ops/sec ±4.31% (93 runs sampled)
+```
+
+__Note.__ CommonMark version runs with [simplified link normalizers](https://github.com/markdown-it/markdown-it/blob/master/benchmark/implementations/current-commonmark/index.mjs)
+for more "honest" compare. Difference is ≈1.5×.
+
+As you can see, `markdown-it` doesn't pay with speed for its flexibility.
+Slowdown of "full" version caused by additional features not available in
+other implementations.
+
+
+## markdown-it for enterprise
+
+Available as part of the Tidelift Subscription.
+
+The maintainers of `markdown-it` and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-markdown-it?utm_source=npm-markdown-it&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)
+
+
+## Authors
+
+- Alex Kocharin [github/rlidwka](https://github.com/rlidwka)
+- Vitaly Puzrin [github/puzrin](https://github.com/puzrin)
+
+_markdown-it_ is the result of the decision of the authors who contributed to
+99% of the _Remarkable_ code to move to a project with the same authorship but
+new leadership (Vitaly and Alex). It's not a fork.
+
+## References / Thanks
+
+Big thanks to [John MacFarlane](https://github.com/jgm) for his work on the
+CommonMark spec and reference implementations. His work saved us a lot of time
+during this project's development.
+
+**Related Links:**
+
+- https://github.com/jgm/CommonMark - reference CommonMark implementations in C & JS,
+ also contains latest spec & online demo.
+- http://talk.commonmark.org - CommonMark forum, good place to collaborate
+ developers' efforts.
+
+**Ports**
+
+- [motion-markdown-it](https://github.com/digitalmoksha/motion-markdown-it) - Ruby/RubyMotion
+- [markdown-it-py](https://github.com/ExecutableBookProject/markdown-it-py)- Python
diff --git a/documents/markdown/markdown-it/normalize.md b/documents/markdown/markdown-it/normalize.md
new file mode 100644
index 0000000..6faed59
--- /dev/null
+++ b/documents/markdown/markdown-it/normalize.md
@@ -0,0 +1,109 @@
+
+Encode link destination, decode text inside it:
+
+.
+<http://example.com/α%CE%B2γ%CE%B4>
+.
+<p><a href="http://example.com/%CE%B1%CE%B2%CE%B3%CE%B4">http://example.com/αβγδ</a></p>
+.
+
+.
+[foo](http://example.com/α%CE%B2γ%CE%B4)
+.
+<p><a href="http://example.com/%CE%B1%CE%B2%CE%B3%CE%B4">foo</a></p>
+.
+
+
+Keep %25 as is because decoding it may break urls, #720
+.
+<https://www.google.com/search?q=hello%2E%252Ehello>
+.
+<p><a href="https://www.google.com/search?q=hello%2E%252Ehello">https://www.google.com/search?q=hello.%252Ehello</a></p>
+.
+
+
+Should decode punycode:
+
+.
+<http://xn--n3h.net/>
+.
+<p><a href="http://xn--n3h.net/">http://☃.net/</a></p>
+.
+
+.
+<http://☃.net/>
+.
+<p><a href="http://xn--n3h.net/">http://☃.net/</a></p>
+.
+
+Invalid punycode:
+
+.
+<http://xn--xn.com/>
+.
+<p><a href="http://xn--xn.com/">http://xn--xn.com/</a></p>
+.
+
+Invalid punycode (non-ascii):
+
+.
+<http://xn--γ.com/>
+.
+<p><a href="http://xn--xn---emd.com/">http://xn--γ.com/</a></p>
+.
+
+Two slashes should start a domain:
+
+.
+[](//☃.net/)
+.
+<p><a href="//xn--n3h.net/"></a></p>
+.
+
+Don't encode domains in unknown schemas:
+
+.
+[](skype:γγγ)
+.
+<p><a href="skype:%CE%B3%CE%B3%CE%B3"></a></p>
+.
+
+Should auto-add protocol to autolinks:
+
+.
+test google.com foo
+.
+<p>test <a href="http://google.com">google.com</a> foo</p>
+.
+
+Should support IDN in autolinks:
+
+.
+test http://xn--n3h.net/ foo
+.
+<p>test <a href="http://xn--n3h.net/">http://☃.net/</a> foo</p>
+.
+
+.
+test http://☃.net/ foo
+.
+<p>test <a href="http://xn--n3h.net/">http://☃.net/</a> foo</p>
+.
+
+.
+test //xn--n3h.net/ foo
+.
+<p>test <a href="//xn--n3h.net/">//☃.net/</a> foo</p>
+.
+
+.
+test xn--n3h.net foo
+.
+<p>test <a href="http://xn--n3h.net">☃.net</a> foo</p>
+.
+
+.
+test xn--n3h@xn--n3h.net foo
+.
+<p>test <a href="mailto:xn--n3h@xn--n3h.net">xn--n3h@☃.net</a> foo</p>
+.
diff --git a/documents/markdown/markdown-it/proto.md b/documents/markdown/markdown-it/proto.md
new file mode 100644
index 0000000..87fdccf
--- /dev/null
+++ b/documents/markdown/markdown-it/proto.md
@@ -0,0 +1,16 @@
+.
+[__proto__]
+
+[__proto__]: blah
+.
+<p><a href="blah"><strong>proto</strong></a></p>
+.
+
+
+.
+[hasOwnProperty]
+
+[hasOwnProperty]: blah
+.
+<p><a href="blah">hasOwnProperty</a></p>
+.
diff --git a/documents/markdown/markdown-it/question.md b/documents/markdown/markdown-it/question.md
new file mode 100644
index 0000000..91b3bba
--- /dev/null
+++ b/documents/markdown/markdown-it/question.md
@@ -0,0 +1,25 @@
+---
+name: Question
+about: For developpers
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+<!--
+
+Note, we have some time constraints, but we always try to help developers, who write plugins. So:
+
+- Please, avoid generic programming questions.
+- Avoid questions about markdown. Use CommonMark resources for that https://commonmark.org/.
+- If you have issue with plugin - report it to plugin's repo/author.
+- Make sure you are familiar with dev docs https://github.com/markdown-it/markdown-it/tree/master/docs, and tried to do something.
+- Code samples are welcome.
+
+Also, you may find useful this links (may be someone already solved your problem):
+
+- https://github.com/markdown-it - list of "officially" provided plugins.
+- https://www.npmjs.com/search?q=keywords:markdown-it-plugin - community-written plugins.
+
+-->
diff --git a/documents/markdown/markdown-it/renderer_rules.md b/documents/markdown/markdown-it/renderer_rules.md
new file mode 100644
index 0000000..ae101f9
--- /dev/null
+++ b/documents/markdown/markdown-it/renderer_rules.md
@@ -0,0 +1,262 @@
+# Adding or modifying rules
+## Default renderer rules
+Rules on how to translate markdown content to HTML elements are stored in `renderer.rules`:
+
+```js
+const MarkdownIt = require('markdown-it');
+const md = new MarkdownIt();
+
+console.log(Object.keys(md.renderer.rules))
+```
+Output:
+```js
+[
+ 'code_inline',
+ 'code_block',
+ 'fence',
+ 'image',
+ 'hardbreak',
+ 'softbreak',
+ 'text',
+ 'html_block',
+ 'html_inline'
+]
+```
+These are the default renderer rules. For any element that is not explicitly listed in this array its default rule applies. For example the rule `bullet_list_open` is not defined, so when markdown-it tries to parse a list to HTML it defaults to ua generic renderer called `Renderer.prototype.renderToken`.
+
+## The demo tool
+
+You can use the [demo tool](https://markdown-it.github.io/) to see which specific rule name corresponds to which HTML tag (switch to the debug tab in the output).
+
+Let's use a Hello World example:
+ [Link to Demo](https://markdown-it.github.io/#md3=%7B%22source%22%3A%22-%20Hello%20World%22%2C%22defaults%22%3A%7B%22html%22%3Afalse%2C%22xhtmlOut%22%3Afalse%2C%22breaks%22%3Afalse%2C%22langPrefix%22%3A%22language-%22%2C%22linkify%22%3Afalse%2C%22typographer%22%3Afalse%2C%22_highlight%22%3Afalse%2C%22_strict%22%3Afalse%2C%22_view%22%3A%22debug%22%7D%7D)
+
+Now take a closer look at the first element in the resulting list:
+```js
+{
+ "type": "bullet_list_open",
+ "tag": "ul",
+ "attrs": null,
+ "map": [
+ 0,
+ 1
+ ],
+ "nesting": 1,
+ "level": 0,
+ "children": null,
+ "content": "",
+ "markup": "-",
+ "info": "",
+ "meta": null,
+ "block": true,
+ "hidden": false
+ }
+```
+This is a [Token](https://markdown-it.github.io/markdown-it/#Token). Its corresponding HTML `tag` is `ul` and its nesting is `1`. This means this specific token represents the opening tag of the HTML list we want to generate from markdown.
+
+* `{ nesting: 1}` is an opening tag: `<ul>`
+* `{ nesting: -1}` is a closing tag: `</ul>`
+* `{ nesting: 0}` is a self-closing tag: `<br />`
+
+## Adding new rules
+### To add a default CSS class to an element
+
+Let's set ourself a goal:
+```
+Create a rule to add the CSS class "lorem_ipsum" to every <ul>
+```
+
+Rules are functions that accept a number of parameters:
+```js
+const MarkdownIt = require('markdown-it');
+const md = new MarkdownIt();
+
+md.renderer.rules.bullet_list_open = function(tokens, idx, options, env, self) {
+ // tokes: List of all tokens being parsed
+ // idx: Number that corresponds to the key of the current token in tokens
+ // options: The options defined when creating the new markdown-it object ({} in our case)
+ // env ???
+ // self: A reference to the renderer itself
+};
+```
+We assign the new rule to the key that corresponds to the html tag we want to modify.
+
+#### Reusing existing rules
+
+It is good practice however to save the default renderer for your element and only make minimal chances to the rules in place, instead of reinventing the wheel:
+
+```js
+const MarkdownIt = require('markdown-it');
+const md = new MarkdownIt();
+
+const proxy = (tokens, idx, options, env, self) => self.renderToken(tokens, idx, options);
+const defaultBulletListOpenRenderer = md.renderer.rules.bullet_list_open || proxy;
+
+md.renderer.rules.bullet_list_open = function(tokens, idx, options, env, self) {
+ // Make your changes here ...
+ // ... then render it using the existing logic
+ return defaultBulletListOpenRenderer(tokens, idx, options, env, self)
+};
+```
+Earlier we noticed that `renderer.rules.bullet_list_open` is undefined by default. So `proxy` is the most basic rule to render a token and is used if the specific rule is undefined.
+
+CSS classes are attributes on HTML elements. If we think back to the object representation of the `ul` element we looked at, we might remember that it contained an `attrs` key with the value `null`. This means this token had no attributes. `attrs` can be an array of `[key, value]` pairs which describe attributes to be added to the token.
+
+Looking at [the API documention for Token objects](https://markdown-it.github.io/markdown-it/#Token.attrJoin) we find the `attrJoin` method. This method allows us to join an existing attributes value with a new value or create the attribute if it doens't exist yet. Simply pushing the value (for example with `token.attr.push(["key", "value"]`) would overwrite any previous change:
+
+```js
+const MarkdownIt = require('markdown-it');
+const md = new MarkdownIt();
+
+const proxy = (tokens, idx, options, env, self) => self.renderToken(tokens, idx, options);
+const defaultBulletListOpenRenderer = md.renderer.rules.bullet_list_open || proxy;
+
+md.renderer.rules.bullet_list_open = function(tokens, idx, options, env, self) {
+ // Make your changes here ...
+ tokens[idx].attrJoin("class", "lorem_ipsum")
+ // ... then render it using the existing logic
+ return defaultBulletListOpenRenderer(tokens, idx, options, env, self)
+};
+```
+Let's test the finished rule:
+```js
+const MarkdownIt = require('markdown-it');
+const md = new MarkdownIt();
+
+const proxy = (tokens, idx, options, env, self) => self.renderToken(tokens, idx, options);
+const defaultBulletListOpenRenderer = md.renderer.rules.bullet_list_open || proxy;
+
+md.renderer.rules.bullet_list_open = function(tokens, idx, options, env, self) {
+ // Make your changes here ...
+ tokens[idx].attrJoin("class", "lorem_ipsum");
+ // ... then render it using the existing logic
+ return defaultBulletListOpenRenderer(tokens, idx, options, env, self)
+};
+
+console.log(md.render("- Hello World"));
+```
+Output:
+```html
+<ul class="lorem_ipsum">
+<li>Hello World</li>
+</ul>
+```
+### To add a wrapper element
+Let's imagine we are using CSS pseudo classes such as `:before` and `:after` to style our list because using `list-style-type` doesn't provide the bullet types we want and `list-style-image` isn't flexible enough to position itself properly across all major browsers.
+
+To keep a proper line wrapping in our list we have set all elements in our `li` to display as a block (`li * {display: block;}`). This works for our pseudo classes and other `HTMLElements`. However, it does not work for `TextNodes`. So having this output will produce weird line indents:
+```html
+<ul>
+ <li>Hello World</li>
+<ul>
+```
+
+To fix this we can use a wrapper element which can be properly displayed as a block:
+
+```html
+<ul>
+ <li>
+ <span>Hello World</span>
+ </li>
+<ul>
+```
+
+So our next goal is:
+```
+Add a rule that wraps the content of every <li> in a <span>
+```
+
+Keen observers might have already noticed that rules return their HTML tags as strings. So this modification is rather straight forward.
+
+Let's use the [demo tool](https://markdown-it.github.io/#md3=%7B%22source%22%3A%22-%20Hello%20World%22%2C%22defaults%22%3A%7B%22html%22%3Afalse%2C%22xhtmlOut%22%3Afalse%2C%22breaks%22%3Afalse%2C%22langPrefix%22%3A%22language-%22%2C%22linkify%22%3Afalse%2C%22typographer%22%3Afalse%2C%22_highlight%22%3Afalse%2C%22_strict%22%3Afalse%2C%22_view%22%3A%22debug%22%7D%7D) again and check which keys we need to add in the `renderer.rules` object to access the opening and closing tags of an `li` element:
+
+```
+list_item_open
+list_item_close
+```
+
+Now use this information to add the new rules:
+
+```js
+const MarkdownIt = require('markdown-it');
+const md = new MarkdownIt();
+
+const proxy = (tokens, idx, options, env, self) => self.renderToken(tokens, idx, options);
+const defaultListItemOpenRenderer = md.renderer.rules.list_item_open || proxy;
+
+md.renderer.rules.list_item_open = function(tokens, idx, options, env, self) {
+ return `${defaultListItemOpenRenderer(tokens, idx, options, env, self)}<span>`;
+};
+
+const defaultListItemCloseRenderer = md.renderer.rules.list_item_close || proxy;
+
+md.renderer.rules.list_item_close = function(tokens, idx, options, env, self) {
+ return `</span>${defaultListItemCloseRenderer(tokens, idx, options, env, self)}`;
+};
+```
+Testing our modification:
+
+```js
+const MarkdownIt = require('markdown-it');
+const md = new MarkdownIt();
+
+const proxy = (tokens, idx, options, env, self) => self.renderToken(tokens, idx, options);
+const defaultListItemOpenRenderer = md.renderer.rules.list_item_open || proxy;
+
+md.renderer.rules.list_item_open = function(tokens, idx, options, env, self) {
+ return `${defaultListItemOpenRenderer(tokens, idx, options, env, self)}<span>`;
+};
+
+const defaultListItemCloseRenderer = md.renderer.rules.list_item_close || proxy;
+
+md.renderer.rules.list_item_close = function(tokens, idx, options, env, self) {
+ return `</span>${defaultListItemCloseRenderer(tokens, idx, options, env, self)}`;
+};
+
+console.log(md.render("- Hello World"));
+```
+Output:
+```html
+<ul>
+ <li>
+ <span>Hello World</span>
+ </li>
+</ul>
+```
+
+Of course using string manipulation might get really messy for bigger changes. So consider using `markdown-it`s Token class instead:
+```js
+const MarkdownIt = require('markdown-it');
+const Token = require('markdown-it/lib/token');
+const md = new MarkdownIt();
+
+const proxy = (tokens, idx, options, env, self) => self.renderToken(tokens, idx, options);
+
+const defaultListItemOpenRenderer = md.renderer.rules.list_item_open || proxy;
+const defaultSpanOpenRenderer = md.renderer.rules.span_open || proxy;
+
+md.renderer.rules.list_item_open = function(tokens, idx, options, env, self) {
+ const span = new Token("span_open", "span", 1);
+ return `${defaultListItemOpenRenderer(tokens, idx, options, env, self)}${defaultSpanOpenRenderer([span], 0, options, env, self)}`;
+};
+
+const defaultListItemCloseRenderer = md.renderer.rules.list_item_close || proxy;
+const defaultSpanCloseRenderer = md.renderer.rules.span_close|| proxy;
+
+md.renderer.rules.list_item_close = function(tokens, idx, options, env, self) {
+ const span = new Token("span_close", "span", -1);
+ return `${defaultSpanCloseRenderer([span], 0, options, env, self)}${defaultListItemCloseRenderer(tokens, idx, options, env, self)}`;
+};
+
+console.log(md.render("- Hello World"));
+```
+
+Output:
+
+```html
+<ul>
+ <li>
+ <span>Hello World<span>
+ </li>
+</ul>
+```
diff --git a/documents/markdown/markdown-it/safety.md b/documents/markdown/markdown-it/safety.md
new file mode 100644
index 0000000..ab94d64
--- /dev/null
+++ b/documents/markdown/markdown-it/safety.md
@@ -0,0 +1,35 @@
+# Safety
+
+Many people don't understand that markdown format does not care much about
+security. In many cases you have to pass output to sanitizers. `markdown-it`
+provides 2 possible strategies to produce safe output:
+
+1. Don't enable HTML. Extend markup features with [plugins](https://www.npmjs.org/browse/keyword/markdown-it-plugin). We think it's the best choice and use it by default.
+ - That's ok for 99% of user needs.
+ - Output will be safe without sanitizer.
+2. Enable HTML and use external sanitizer package.
+
+Also by default `markdown-it` prohibits some kind of links, which could be used
+for XSS:
+
+- `javascript:`, `vbscript:`
+- `file:`
+- `data:`, except some images (gif/png/jpeg/webp).
+
+So, by default `markdown-it` should be safe. We care about it.
+
+If you find a security problem - contact us via tracker or email. Such reports
+are fixed with top priority.
+
+
+## Plugins
+
+Usually, plugins operate with tokenized content, and that's enough to provide
+safe output.
+
+But there is one non-evident case you should know - don't allow plugins to
+generate arbitrary element `id` and `name`. If those depend on user input -
+always add prefixes to avoid DOM clobbering. See [discussion](https://github.com/markdown-it/markdown-it/issues/28) for details.
+
+So, if you decide to use plugins that add extended class syntax or
+autogenerating header anchors - be careful.
diff --git a/documents/markdown/markdown-it/sample.md b/documents/markdown/markdown-it/sample.md
new file mode 100644
index 0000000..365cad8
--- /dev/null
+++ b/documents/markdown/markdown-it/sample.md
@@ -0,0 +1,245 @@
+---
+__Advertisement :)__
+
+- __[pica](https://nodeca.github.io/pica/demo/)__ - high quality and fast image
+ resize in browser.
+- __[babelfish](https://github.com/nodeca/babelfish/)__ - developer friendly
+ i18n with plurals support and easy syntax.
+
+You will like those projects!
+
+---
+
+# h1 Heading 8-)
+## h2 Heading
+### h3 Heading
+#### h4 Heading
+##### h5 Heading
+###### h6 Heading
+
+
+## Horizontal Rules
+
+___
+
+---
+
+***
+
+
+## Typographic replacements
+
+Enable typographer option to see result.
+
+(c) (C) (r) (R) (tm) (TM) (p) (P) +-
+
+test.. test... test..... test?..... test!....
+
+!!!!!! ???? ,, -- ---
+
+"Smartypants, double quotes" and 'single quotes'
+
+
+## Emphasis
+
+**This is bold text**
+
+__This is bold text__
+
+*This is italic text*
+
+_This is italic text_
+
+~~Strikethrough~~
+
+
+## Blockquotes
+
+
+> Blockquotes can also be nested...
+>> ...by using additional greater-than signs right next to each other...
+> > > ...or with spaces between arrows.
+
+
+## Lists
+
+Unordered
+
++ Create a list by starting a line with `+`, `-`, or `*`
++ Sub-lists are made by indenting 2 spaces:
+ - Marker character change forces new list start:
+ * Ac tristique libero volutpat at
+ + Facilisis in pretium nisl aliquet
+ - Nulla volutpat aliquam velit
++ Very easy!
+
+Ordered
+
+1. Lorem ipsum dolor sit amet
+2. Consectetur adipiscing elit
+3. Integer molestie lorem at massa
+
+
+1. You can use sequential numbers...
+1. ...or keep all the numbers as `1.`
+
+Start numbering with offset:
+
+57. foo
+1. bar
+
+
+## Code
+
+Inline `code`
+
+Indented code
+
+ // Some comments
+ line 1 of code
+ line 2 of code
+ line 3 of code
+
+
+Block code "fences"
+
+```
+Sample text here...
+```
+
+Syntax highlighting
+
+``` js
+var foo = function (bar) {
+ return bar++;
+};
+
+console.log(foo(5));
+```
+
+## Tables
+
+| Option | Description |
+| ------ | ----------- |
+| data | path to data files to supply the data that will be passed into templates. |
+| engine | engine to be used for processing templates. Handlebars is the default. |
+| ext | extension to be used for dest files. |
+
+Right aligned columns
+
+| Option | Description |
+| ------:| -----------:|
+| data | path to data files to supply the data that will be passed into templates. |
+| engine | engine to be used for processing templates. Handlebars is the default. |
+| ext | extension to be used for dest files. |
+
+
+## Links
+
+[link text](http://dev.nodeca.com)
+
+[link with title](http://nodeca.github.io/pica/demo/ "title text!")
+
+Autoconverted link https://github.com/nodeca/pica (enable linkify to see)
+
+
+## Images
+
+
+
+
+Like links, Images also have a footnote style syntax
+
+![Alt text][id]
+
+With a reference later in the document defining the URL location:
+
+[id]: https://octodex.github.com/images/dojocat.jpg "The Dojocat"
+
+
+## Plugins
+
+The killer feature of `markdown-it` is very effective support of
+[syntax plugins](https://www.npmjs.org/browse/keyword/markdown-it-plugin).
+
+
+### [Emojies](https://github.com/markdown-it/markdown-it-emoji)
+
+> Classic markup: :wink: :cry: :laughing: :yum:
+>
+> Shortcuts (emoticons): :-) :-( 8-) ;)
+
+see [how to change output](https://github.com/markdown-it/markdown-it-emoji#change-output) with twemoji.
+
+
+### [Subscript](https://github.com/markdown-it/markdown-it-sub) / [Superscript](https://github.com/markdown-it/markdown-it-sup)
+
+- 19^th^
+- H~2~O
+
+
+### [\<ins>](https://github.com/markdown-it/markdown-it-ins)
+
+++Inserted text++
+
+
+### [\<mark>](https://github.com/markdown-it/markdown-it-mark)
+
+==Marked text==
+
+
+### [Footnotes](https://github.com/markdown-it/markdown-it-footnote)
+
+Footnote 1 link[^first].
+
+Footnote 2 link[^second].
+
+Inline footnote^[Text of inline footnote] definition.
+
+Duplicated footnote reference[^second].
+
+[^first]: Footnote **can have markup**
+
+ and multiple paragraphs.
+
+[^second]: Footnote text.
+
+
+### [Definition lists](https://github.com/markdown-it/markdown-it-deflist)
+
+Term 1
+
+: Definition 1
+with lazy continuation.
+
+Term 2 with *inline markup*
+
+: Definition 2
+
+ { some code, part of Definition 2 }
+
+ Third paragraph of definition 2.
+
+_Compact style:_
+
+Term 1
+ ~ Definition 1
+
+Term 2
+ ~ Definition 2a
+ ~ Definition 2b
+
+
+### [Abbreviations](https://github.com/markdown-it/markdown-it-abbr)
+
+This is HTML abbreviation example.
+
+It converts "HTML", but keep intact partial entries like "xxxHTMLyyy" and so on.
+
+*[HTML]: Hyper Text Markup Language
+
+### [Custom containers](https://github.com/markdown-it/markdown-it-container)
+
+::: warning
+*here be dragons*
+:::
diff --git a/documents/markdown/markdown-it/smartquotes.md b/documents/markdown/markdown-it/smartquotes.md
new file mode 100644
index 0000000..afab445
--- /dev/null
+++ b/documents/markdown/markdown-it/smartquotes.md
@@ -0,0 +1,192 @@
+Should parse nested quotes:
+.
+"foo 'bar' baz"
+
+'foo 'bar' baz'
+.
+<p>“foo ‘bar’ baz”</p>
+<p>‘foo ‘bar’ baz’</p>
+.
+
+
+Should not overlap quotes:
+.
+'foo "bar' baz"
+.
+<p>‘foo "bar’ baz"</p>
+.
+
+
+Should match quotes on the same level:
+.
+"foo *bar* baz"
+.
+<p>“foo <em>bar</em> baz”</p>
+.
+
+
+Should handle adjacent nested quotes:
+.
+'"double in single"'
+
+"'single in double'"
+.
+<p>‘“double in single”’</p>
+<p>“‘single in double’”</p>
+.
+
+
+
+Should not match quotes on different levels:
+.
+*"foo* bar"
+
+"foo *bar"*
+
+*"foo* bar *baz"*
+.
+<p><em>"foo</em> bar"</p>
+<p>"foo <em>bar"</em></p>
+<p><em>"foo</em> bar <em>baz"</em></p>
+.
+
+Smartquotes should not overlap with other tags:
+.
+*foo "bar* *baz" quux*
+.
+<p><em>foo "bar</em> <em>baz" quux</em></p>
+.
+
+
+Should try and find matching quote in this case:
+.
+"foo "bar 'baz"
+.
+<p>"foo “bar 'baz”</p>
+.
+
+
+Should not touch 'inches' in quotes:
+.
+"Monitor 21"" and "Monitor""
+.
+<p>“Monitor 21"” and “Monitor”"</p>
+.
+
+
+Should render an apostrophe as a rsquo:
+.
+This isn't and can't be the best approach to implement this...
+.
+<p>This isn’t and can’t be the best approach to implement this…</p>
+.
+
+
+Apostrophe could end the word, that's why original smartypants replaces all of them as rsquo:
+.
+users' stuff
+.
+<p>users’ stuff</p>
+.
+
+Quotes between punctuation chars:
+
+.
+"(hai)".
+.
+<p>“(hai)”.</p>
+.
+
+Quotes at the start/end of the tokens:
+.
+"*foo* bar"
+
+"foo *bar*"
+
+"*foo bar*"
+.
+<p>“<em>foo</em> bar”</p>
+<p>“foo <em>bar</em>”</p>
+<p>“<em>foo bar</em>”</p>
+.
+
+Should treat softbreak as a space:
+.
+"this"
+and "that".
+
+"this" and
+"that".
+.
+<p>“this”
+and “that”.</p>
+<p>“this” and
+“that”.</p>
+.
+
+Should treat hardbreak as a space:
+.
+"this"\
+and "that".
+
+"this" and\
+"that".
+.
+<p>“this”<br>
+and “that”.</p>
+<p>“this” and<br>
+“that”.</p>
+.
+
+Should allow quotes adjacent to other punctuation characters, #643:
+.
+The dog---"'man's' best friend"
+.
+<p>The dog—“‘man’s’ best friend”</p>
+.
+
+Should parse quotes adjacent to code block, #677:
+.
+"test `code`"
+
+"`code` test"
+.
+<p>“test <code>code</code>”</p>
+<p>“<code>code</code> test”</p>
+.
+
+Should parse quotes adjacent to inline html, #677:
+.
+"test <br>"
+
+"<br> test"
+.
+<p>“test <br>”</p>
+<p>“<br> test”</p>
+.
+
+Should be escapable:
+.
+"foo"
+
+\"foo"
+
+"foo\"
+.
+<p>“foo”</p>
+<p>"foo"</p>
+<p>"foo"</p>
+.
+
+Should not replace entities:
+.
+"foo"
+
+"foo"
+
+"foo"
+.
+<p>"foo"</p>
+<p>"foo"</p>
+<p>"foo"</p>
+.
diff --git a/documents/markdown/markdown-it/spec.md b/documents/markdown/markdown-it/spec.md
new file mode 100644
index 0000000..f1fab28
--- /dev/null
+++ b/documents/markdown/markdown-it/spec.md
@@ -0,0 +1,9756 @@
+---
+title: CommonMark Spec
+author: John MacFarlane
+version: '0.31.2'
+date: '2024-01-28'
+license: '[CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)'
+...
+
+# Introduction
+
+## What is Markdown?
+
+Markdown is a plain text format for writing structured documents,
+based on conventions for indicating formatting in email
+and usenet posts. It was developed by John Gruber (with
+help from Aaron Swartz) and released in 2004 in the form of a
+[syntax description](https://daringfireball.net/projects/markdown/syntax)
+and a Perl script (`Markdown.pl`) for converting Markdown to
+HTML. In the next decade, dozens of implementations were
+developed in many languages. Some extended the original
+Markdown syntax with conventions for footnotes, tables, and
+other document elements. Some allowed Markdown documents to be
+rendered in formats other than HTML. Websites like Reddit,
+StackOverflow, and GitHub had millions of people using Markdown.
+And Markdown started to be used beyond the web, to author books,
+articles, slide shows, letters, and lecture notes.
+
+What distinguishes Markdown from many other lightweight markup
+syntaxes, which are often easier to write, is its readability.
+As Gruber writes:
+
+> The overriding design goal for Markdown's formatting syntax is
+> to make it as readable as possible. The idea is that a
+> Markdown-formatted document should be publishable as-is, as
+> plain text, without looking like it's been marked up with tags
+> or formatting instructions.
+> (<https://daringfireball.net/projects/markdown/>)
+
+The point can be illustrated by comparing a sample of
+[AsciiDoc](https://asciidoc.org/) with
+an equivalent sample of Markdown. Here is a sample of
+AsciiDoc from the AsciiDoc manual:
+
+```
+1. List item one.
++
+List item one continued with a second paragraph followed by an
+Indented block.
++
+.................
+$ ls *.sh
+$ mv *.sh ~/tmp
+.................
++
+List item continued with a third paragraph.
+
+2. List item two continued with an open block.
++
+--
+This paragraph is part of the preceding list item.
+
+a. This list is nested and does not require explicit item
+continuation.
++
+This paragraph is part of the preceding list item.
+
+b. List item b.
+
+This paragraph belongs to item two of the outer list.
+--
+```
+
+And here is the equivalent in Markdown:
+```
+1. List item one.
+
+ List item one continued with a second paragraph followed by an
+ Indented block.
+
+ $ ls *.sh
+ $ mv *.sh ~/tmp
+
+ List item continued with a third paragraph.
+
+2. List item two continued with an open block.
+
+ This paragraph is part of the preceding list item.
+
+ 1. This list is nested and does not require explicit item continuation.
+
+ This paragraph is part of the preceding list item.
+
+ 2. List item b.
+
+ This paragraph belongs to item two of the outer list.
+```
+
+The AsciiDoc version is, arguably, easier to write. You don't need
+to worry about indentation. But the Markdown version is much easier
+to read. The nesting of list items is apparent to the eye in the
+source, not just in the processed document.
+
+## Why is a spec needed?
+
+John Gruber's [canonical description of Markdown's
+syntax](https://daringfireball.net/projects/markdown/syntax)
+does not specify the syntax unambiguously. Here are some examples of
+questions it does not answer:
+
+1. How much indentation is needed for a sublist? The spec says that
+ continuation paragraphs need to be indented four spaces, but is
+ not fully explicit about sublists. It is natural to think that
+ they, too, must be indented four spaces, but `Markdown.pl` does
+ not require that. This is hardly a "corner case," and divergences
+ between implementations on this issue often lead to surprises for
+ users in real documents. (See [this comment by John
+ Gruber](https://web.archive.org/web/20170611172104/http://article.gmane.org/gmane.text.markdown.general/1997).)
+
+2. Is a blank line needed before a block quote or heading?
+ Most implementations do not require the blank line. However,
+ this can lead to unexpected results in hard-wrapped text, and
+ also to ambiguities in parsing (note that some implementations
+ put the heading inside the blockquote, while others do not).
+ (John Gruber has also spoken [in favor of requiring the blank
+ lines](https://web.archive.org/web/20170611172104/http://article.gmane.org/gmane.text.markdown.general/2146).)
+
+3. Is a blank line needed before an indented code block?
+ (`Markdown.pl` requires it, but this is not mentioned in the
+ documentation, and some implementations do not require it.)
+
+ ``` markdown
+ paragraph
+ code?
+ ```
+
+4. What is the exact rule for determining when list items get
+ wrapped in `<p>` tags? Can a list be partially "loose" and partially
+ "tight"? What should we do with a list like this?
+
+ ``` markdown
+ 1. one
+
+ 2. two
+ 3. three
+ ```
+
+ Or this?
+
+ ``` markdown
+ 1. one
+ - a
+
+ - b
+ 2. two
+ ```
+
+ (There are some relevant comments by John Gruber
+ [here](https://web.archive.org/web/20170611172104/http://article.gmane.org/gmane.text.markdown.general/2554).)
+
+5. Can list markers be indented? Can ordered list markers be right-aligned?
+
+ ``` markdown
+ 8. item 1
+ 9. item 2
+ 10. item 2a
+ ```
+
+6. Is this one list with a thematic break in its second item,
+ or two lists separated by a thematic break?
+
+ ``` markdown
+ * a
+ * * * * *
+ * b
+ ```
+
+7. When list markers change from numbers to bullets, do we have
+ two lists or one? (The Markdown syntax description suggests two,
+ but the perl scripts and many other implementations produce one.)
+
+ ``` markdown
+ 1. fee
+ 2. fie
+ - foe
+ - fum
+ ```
+
+8. What are the precedence rules for the markers of inline structure?
+ For example, is the following a valid link, or does the code span
+ take precedence ?
+
+ ``` markdown
+ [a backtick (`)](/url) and [another backtick (`)](/url).
+ ```
+
+9. What are the precedence rules for markers of emphasis and strong
+ emphasis? For example, how should the following be parsed?
+
+ ``` markdown
+ *foo *bar* baz*
+ ```
+
+10. What are the precedence rules between block-level and inline-level
+ structure? For example, how should the following be parsed?
+
+ ``` markdown
+ - `a long code span can contain a hyphen like this
+ - and it can screw things up`
+ ```
+
+11. Can list items include section headings? (`Markdown.pl` does not
+ allow this, but does allow blockquotes to include headings.)
+
+ ``` markdown
+ - # Heading
+ ```
+
+12. Can list items be empty?
+
+ ``` markdown
+ * a
+ *
+ * b
+ ```
+
+13. Can link references be defined inside block quotes or list items?
+
+ ``` markdown
+ > Blockquote [foo].
+ >
+ > [foo]: /url
+ ```
+
+14. If there are multiple definitions for the same reference, which takes
+ precedence?
+
+ ``` markdown
+ [foo]: /url1
+ [foo]: /url2
+
+ [foo][]
+ ```
+
+In the absence of a spec, early implementers consulted `Markdown.pl`
+to resolve these ambiguities. But `Markdown.pl` was quite buggy, and
+gave manifestly bad results in many cases, so it was not a
+satisfactory replacement for a spec.
+
+Because there is no unambiguous spec, implementations have diverged
+considerably. As a result, users are often surprised to find that
+a document that renders one way on one system (say, a GitHub wiki)
+renders differently on another (say, converting to docbook using
+pandoc). To make matters worse, because nothing in Markdown counts
+as a "syntax error," the divergence often isn't discovered right away.
+
+## About this document
+
+This document attempts to specify Markdown syntax unambiguously.
+It contains many examples with side-by-side Markdown and
+HTML. These are intended to double as conformance tests. An
+accompanying script `spec_tests.py` can be used to run the tests
+against any Markdown program:
+
+ python test/spec_tests.py --spec spec.txt --program PROGRAM
+
+Since this document describes how Markdown is to be parsed into
+an abstract syntax tree, it would have made sense to use an abstract
+representation of the syntax tree instead of HTML. But HTML is capable
+of representing the structural distinctions we need to make, and the
+choice of HTML for the tests makes it possible to run the tests against
+an implementation without writing an abstract syntax tree renderer.
+
+Note that not every feature of the HTML samples is mandated by
+the spec. For example, the spec says what counts as a link
+destination, but it doesn't mandate that non-ASCII characters in
+the URL be percent-encoded. To use the automatic tests,
+implementers will need to provide a renderer that conforms to
+the expectations of the spec examples (percent-encoding
+non-ASCII characters in URLs). But a conforming implementation
+can use a different renderer and may choose not to
+percent-encode non-ASCII characters in URLs.
+
+This document is generated from a text file, `spec.txt`, written
+in Markdown with a small extension for the side-by-side tests.
+The script `tools/makespec.py` can be used to convert `spec.txt` into
+HTML or CommonMark (which can then be converted into other formats).
+
+In the examples, the `→` character is used to represent tabs.
+
+# Preliminaries
+
+## Characters and lines
+
+Any sequence of [characters] is a valid CommonMark
+document.
+
+A [character](@) is a Unicode code point. Although some
+code points (for example, combining accents) do not correspond to
+characters in an intuitive sense, all code points count as characters
+for purposes of this spec.
+
+This spec does not specify an encoding; it thinks of lines as composed
+of [characters] rather than bytes. A conforming parser may be limited
+to a certain encoding.
+
+A [line](@) is a sequence of zero or more [characters]
+other than line feed (`U+000A`) or carriage return (`U+000D`),
+followed by a [line ending] or by the end of file.
+
+A [line ending](@) is a line feed (`U+000A`), a carriage return
+(`U+000D`) not followed by a line feed, or a carriage return and a
+following line feed.
+
+A line containing no characters, or a line containing only spaces
+(`U+0020`) or tabs (`U+0009`), is called a [blank line](@).
+
+The following definitions of character classes will be used in this spec:
+
+A [Unicode whitespace character](@) is a character in the Unicode `Zs` general
+category, or a tab (`U+0009`), line feed (`U+000A`), form feed (`U+000C`), or
+carriage return (`U+000D`).
+
+[Unicode whitespace](@) is a sequence of one or more
+[Unicode whitespace characters].
+
+A [tab](@) is `U+0009`.
+
+A [space](@) is `U+0020`.
+
+An [ASCII control character](@) is a character between `U+0000–1F` (both
+including) or `U+007F`.
+
+An [ASCII punctuation character](@)
+is `!`, `"`, `#`, `$`, `%`, `&`, `'`, `(`, `)`,
+`*`, `+`, `,`, `-`, `.`, `/` (U+0021–2F),
+`:`, `;`, `<`, `=`, `>`, `?`, `@` (U+003A–0040),
+`[`, `\`, `]`, `^`, `_`, `` ` `` (U+005B–0060),
+`{`, `|`, `}`, or `~` (U+007B–007E).
+
+A [Unicode punctuation character](@) is a character in the Unicode `P`
+(puncuation) or `S` (symbol) general categories.
+
+## Tabs
+
+Tabs in lines are not expanded to [spaces]. However,
+in contexts where spaces help to define block structure,
+tabs behave as if they were replaced by spaces with a tab stop
+of 4 characters.
+
+Thus, for example, a tab can be used instead of four spaces
+in an indented code block. (Note, however, that internal
+tabs are passed through as literal tabs, not expanded to
+spaces.)
+
+```````````````````````````````` example
+→foo→baz→→bim
+.
+<pre><code>foo→baz→→bim
+</code></pre>
+````````````````````````````````
+
+```````````````````````````````` example
+ →foo→baz→→bim
+.
+<pre><code>foo→baz→→bim
+</code></pre>
+````````````````````````````````
+
+```````````````````````````````` example
+ a→a
+ ὐ→a
+.
+<pre><code>a→a
+ὐ→a
+</code></pre>
+````````````````````````````````
+
+In the following example, a continuation paragraph of a list
+item is indented with a tab; this has exactly the same effect
+as indentation with four spaces would:
+
+```````````````````````````````` example
+ - foo
+
+→bar
+.
+<ul>
+<li>
+<p>foo</p>
+<p>bar</p>
+</li>
+</ul>
+````````````````````````````````
+
+```````````````````````````````` example
+- foo
+
+→→bar
+.
+<ul>
+<li>
+<p>foo</p>
+<pre><code> bar
+</code></pre>
+</li>
+</ul>
+````````````````````````````````
+
+Normally the `>` that begins a block quote may be followed
+optionally by a space, which is not considered part of the
+content. In the following case `>` is followed by a tab,
+which is treated as if it were expanded into three spaces.
+Since one of these spaces is considered part of the
+delimiter, `foo` is considered to be indented six spaces
+inside the block quote context, so we get an indented
+code block starting with two spaces.
+
+```````````````````````````````` example
+>→→foo
+.
+<blockquote>
+<pre><code> foo
+</code></pre>
+</blockquote>
+````````````````````````````````
+
+```````````````````````````````` example
+-→→foo
+.
+<ul>
+<li>
+<pre><code> foo
+</code></pre>
+</li>
+</ul>
+````````````````````````````````
+
+
+```````````````````````````````` example
+ foo
+→bar
+.
+<pre><code>foo
+bar
+</code></pre>
+````````````````````````````````
+
+```````````````````````````````` example
+ - foo
+ - bar
+→ - baz
+.
+<ul>
+<li>foo
+<ul>
+<li>bar
+<ul>
+<li>baz</li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+````````````````````````````````
+
+```````````````````````````````` example
+#→Foo
+.
+<h1>Foo</h1>
+````````````````````````````````
+
+```````````````````````````````` example
+*→*→*→
+.
+<hr />
+````````````````````````````````
+
+
+## Insecure characters
+
+For security reasons, the Unicode character `U+0000` must be replaced
+with the REPLACEMENT CHARACTER (`U+FFFD`).
+
+
+## Backslash escapes
+
+Any ASCII punctuation character may be backslash-escaped:
+
+```````````````````````````````` example
+\!\"\#\$\%\&\'\(\)\*\+\,\-\.\/\:\;\<\=\>\?\@\[\\\]\^\_\`\{\|\}\~
+.
+<p>!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~</p>
+````````````````````````````````
+
+
+Backslashes before other characters are treated as literal
+backslashes:
+
+```````````````````````````````` example
+\→\A\a\ \3\φ\«
+.
+<p>\→\A\a\ \3\φ\«</p>
+````````````````````````````````
+
+
+Escaped characters are treated as regular characters and do
+not have their usual Markdown meanings:
+
+```````````````````````````````` example
+\*not emphasized*
+\<br/> not a tag
+\[not a link](/foo)
+\`not code`
+1\. not a list
+\* not a list
+\# not a heading
+\[foo]: /url "not a reference"
+\ö not a character entity
+.
+<p>*not emphasized*
+<br/> not a tag
+[not a link](/foo)
+`not code`
+1. not a list
+* not a list
+# not a heading
+[foo]: /url "not a reference"
+&ouml; not a character entity</p>
+````````````````````````````````
+
+
+If a backslash is itself escaped, the following character is not:
+
+```````````````````````````````` example
+\\*emphasis*
+.
+<p>\<em>emphasis</em></p>
+````````````````````````````````
+
+
+A backslash at the end of the line is a [hard line break]:
+
+```````````````````````````````` example
+foo\
+bar
+.
+<p>foo<br />
+bar</p>
+````````````````````````````````
+
+
+Backslash escapes do not work in code blocks, code spans, autolinks, or
+raw HTML:
+
+```````````````````````````````` example
+`` \[\` ``
+.
+<p><code>\[\`</code></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+ \[\]
+.
+<pre><code>\[\]
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+~~~
+\[\]
+~~~
+.
+<pre><code>\[\]
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<https://example.com?find=\*>
+.
+<p><a href="https://example.com?find=%5C*">https://example.com?find=\*</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<a href="/bar\/)">
+.
+<a href="/bar\/)">
+````````````````````````````````
+
+
+But they work in all other contexts, including URLs and link titles,
+link references, and [info strings] in [fenced code blocks]:
+
+```````````````````````````````` example
+[foo](/bar\* "ti\*tle")
+.
+<p><a href="/bar*" title="ti*tle">foo</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo]
+
+[foo]: /bar\* "ti\*tle"
+.
+<p><a href="/bar*" title="ti*tle">foo</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+``` foo\+bar
+foo
+```
+.
+<pre><code class="language-foo+bar">foo
+</code></pre>
+````````````````````````````````
+
+
+## Entity and numeric character references
+
+Valid HTML entity references and numeric character references
+can be used in place of the corresponding Unicode character,
+with the following exceptions:
+
+- Entity and character references are not recognized in code
+ blocks and code spans.
+
+- Entity and character references cannot stand in place of
+ special characters that define structural elements in
+ CommonMark. For example, although `*` can be used
+ in place of a literal `*` character, `*` cannot replace
+ `*` in emphasis delimiters, bullet list markers, or thematic
+ breaks.
+
+Conforming CommonMark parsers need not store information about
+whether a particular character was represented in the source
+using a Unicode character or an entity reference.
+
+[Entity references](@) consist of `&` + any of the valid
+HTML5 entity names + `;`. The
+document <https://html.spec.whatwg.org/entities.json>
+is used as an authoritative source for the valid entity
+references and their corresponding code points.
+
+```````````````````````````````` example
+ & © Æ Ď
+¾ ℋ ⅆ
+∲ ≧̸
+.
+<p> & © Æ Ď
+¾ ℋ ⅆ
+∲ ≧̸</p>
+````````````````````````````````
+
+
+[Decimal numeric character
+references](@)
+consist of `&#` + a string of 1--7 arabic digits + `;`. A
+numeric character reference is parsed as the corresponding
+Unicode character. Invalid Unicode code points will be replaced by
+the REPLACEMENT CHARACTER (`U+FFFD`). For security reasons,
+the code point `U+0000` will also be replaced by `U+FFFD`.
+
+```````````````````````````````` example
+# Ӓ Ϡ �
+.
+<p># Ӓ Ϡ �</p>
+````````````````````````````````
+
+
+[Hexadecimal numeric character
+references](@) consist of `&#` +
+either `X` or `x` + a string of 1-6 hexadecimal digits + `;`.
+They too are parsed as the corresponding Unicode character (this
+time specified with a hexadecimal numeral instead of decimal).
+
+```````````````````````````````` example
+" ആ ಫ
+.
+<p>" ആ ಫ</p>
+````````````````````````````````
+
+
+Here are some nonentities:
+
+```````````````````````````````` example
+  &x; &#; &#x;
+�
+&#abcdef0;
+&ThisIsNotDefined; &hi?;
+.
+<p>&nbsp &x; &#; &#x;
+&#87654321;
+&#abcdef0;
+&ThisIsNotDefined; &hi?;</p>
+````````````````````````````````
+
+
+Although HTML5 does accept some entity references
+without a trailing semicolon (such as `©`), these are not
+recognized here, because it makes the grammar too ambiguous:
+
+```````````````````````````````` example
+©
+.
+<p>&copy</p>
+````````````````````````````````
+
+
+Strings that are not on the list of HTML5 named entities are not
+recognized as entity references either:
+
+```````````````````````````````` example
+&MadeUpEntity;
+.
+<p>&MadeUpEntity;</p>
+````````````````````````````````
+
+
+Entity and numeric character references are recognized in any
+context besides code spans or code blocks, including
+URLs, [link titles], and [fenced code block][] [info strings]:
+
+```````````````````````````````` example
+<a href="öö.html">
+.
+<a href="öö.html">
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo](/föö "föö")
+.
+<p><a href="/f%C3%B6%C3%B6" title="föö">foo</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo]
+
+[foo]: /föö "föö"
+.
+<p><a href="/f%C3%B6%C3%B6" title="föö">foo</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+``` föö
+foo
+```
+.
+<pre><code class="language-föö">foo
+</code></pre>
+````````````````````````````````
+
+
+Entity and numeric character references are treated as literal
+text in code spans and code blocks:
+
+```````````````````````````````` example
+`föö`
+.
+<p><code>f&ouml;&ouml;</code></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+ föfö
+.
+<pre><code>f&ouml;f&ouml;
+</code></pre>
+````````````````````````````````
+
+
+Entity and numeric character references cannot be used
+in place of symbols indicating structure in CommonMark
+documents.
+
+```````````````````````````````` example
+*foo*
+*foo*
+.
+<p>*foo*
+<em>foo</em></p>
+````````````````````````````````
+
+```````````````````````````````` example
+* foo
+
+* foo
+.
+<p>* foo</p>
+<ul>
+<li>foo</li>
+</ul>
+````````````````````````````````
+
+```````````````````````````````` example
+foo bar
+.
+<p>foo
+
+bar</p>
+````````````````````````````````
+
+```````````````````````````````` example
+	foo
+.
+<p>→foo</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[a](url "tit")
+.
+<p>[a](url "tit")</p>
+````````````````````````````````
+
+
+
+# Blocks and inlines
+
+We can think of a document as a sequence of
+[blocks](@)---structural elements like paragraphs, block
+quotations, lists, headings, rules, and code blocks. Some blocks (like
+block quotes and list items) contain other blocks; others (like
+headings and paragraphs) contain [inline](@) content---text,
+links, emphasized text, images, code spans, and so on.
+
+## Precedence
+
+Indicators of block structure always take precedence over indicators
+of inline structure. So, for example, the following is a list with
+two items, not a list with one item containing a code span:
+
+```````````````````````````````` example
+- `one
+- two`
+.
+<ul>
+<li>`one</li>
+<li>two`</li>
+</ul>
+````````````````````````````````
+
+
+This means that parsing can proceed in two steps: first, the block
+structure of the document can be discerned; second, text lines inside
+paragraphs, headings, and other block constructs can be parsed for inline
+structure. The second step requires information about link reference
+definitions that will be available only at the end of the first
+step. Note that the first step requires processing lines in sequence,
+but the second can be parallelized, since the inline parsing of
+one block element does not affect the inline parsing of any other.
+
+## Container blocks and leaf blocks
+
+We can divide blocks into two types:
+[container blocks](#container-blocks),
+which can contain other blocks, and [leaf blocks](#leaf-blocks),
+which cannot.
+
+# Leaf blocks
+
+This section describes the different kinds of leaf block that make up a
+Markdown document.
+
+## Thematic breaks
+
+A line consisting of optionally up to three spaces of indentation, followed by a
+sequence of three or more matching `-`, `_`, or `*` characters, each followed
+optionally by any number of spaces or tabs, forms a
+[thematic break](@).
+
+```````````````````````````````` example
+***
+---
+___
+.
+<hr />
+<hr />
+<hr />
+````````````````````````````````
+
+
+Wrong characters:
+
+```````````````````````````````` example
++++
+.
+<p>+++</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+===
+.
+<p>===</p>
+````````````````````````````````
+
+
+Not enough characters:
+
+```````````````````````````````` example
+--
+**
+__
+.
+<p>--
+**
+__</p>
+````````````````````````````````
+
+
+Up to three spaces of indentation are allowed:
+
+```````````````````````````````` example
+ ***
+ ***
+ ***
+.
+<hr />
+<hr />
+<hr />
+````````````````````````````````
+
+
+Four spaces of indentation is too many:
+
+```````````````````````````````` example
+ ***
+.
+<pre><code>***
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+Foo
+ ***
+.
+<p>Foo
+***</p>
+````````````````````````````````
+
+
+More than three characters may be used:
+
+```````````````````````````````` example
+_____________________________________
+.
+<hr />
+````````````````````````````````
+
+
+Spaces and tabs are allowed between the characters:
+
+```````````````````````````````` example
+ - - -
+.
+<hr />
+````````````````````````````````
+
+
+```````````````````````````````` example
+ ** * ** * ** * **
+.
+<hr />
+````````````````````````````````
+
+
+```````````````````````````````` example
+- - - -
+.
+<hr />
+````````````````````````````````
+
+
+Spaces and tabs are allowed at the end:
+
+```````````````````````````````` example
+- - - -
+.
+<hr />
+````````````````````````````````
+
+
+However, no other characters may occur in the line:
+
+```````````````````````````````` example
+_ _ _ _ a
+
+a------
+
+---a---
+.
+<p>_ _ _ _ a</p>
+<p>a------</p>
+<p>---a---</p>
+````````````````````````````````
+
+
+It is required that all of the characters other than spaces or tabs be the same.
+So, this is not a thematic break:
+
+```````````````````````````````` example
+ *-*
+.
+<p><em>-</em></p>
+````````````````````````````````
+
+
+Thematic breaks do not need blank lines before or after:
+
+```````````````````````````````` example
+- foo
+***
+- bar
+.
+<ul>
+<li>foo</li>
+</ul>
+<hr />
+<ul>
+<li>bar</li>
+</ul>
+````````````````````````````````
+
+
+Thematic breaks can interrupt a paragraph:
+
+```````````````````````````````` example
+Foo
+***
+bar
+.
+<p>Foo</p>
+<hr />
+<p>bar</p>
+````````````````````````````````
+
+
+If a line of dashes that meets the above conditions for being a
+thematic break could also be interpreted as the underline of a [setext
+heading], the interpretation as a
+[setext heading] takes precedence. Thus, for example,
+this is a setext heading, not a paragraph followed by a thematic break:
+
+```````````````````````````````` example
+Foo
+---
+bar
+.
+<h2>Foo</h2>
+<p>bar</p>
+````````````````````````````````
+
+
+When both a thematic break and a list item are possible
+interpretations of a line, the thematic break takes precedence:
+
+```````````````````````````````` example
+* Foo
+* * *
+* Bar
+.
+<ul>
+<li>Foo</li>
+</ul>
+<hr />
+<ul>
+<li>Bar</li>
+</ul>
+````````````````````````````````
+
+
+If you want a thematic break in a list item, use a different bullet:
+
+```````````````````````````````` example
+- Foo
+- * * *
+.
+<ul>
+<li>Foo</li>
+<li>
+<hr />
+</li>
+</ul>
+````````````````````````````````
+
+
+## ATX headings
+
+An [ATX heading](@)
+consists of a string of characters, parsed as inline content, between an
+opening sequence of 1--6 unescaped `#` characters and an optional
+closing sequence of any number of unescaped `#` characters.
+The opening sequence of `#` characters must be followed by spaces or tabs, or
+by the end of line. The optional closing sequence of `#`s must be preceded by
+spaces or tabs and may be followed by spaces or tabs only. The opening
+`#` character may be preceded by up to three spaces of indentation. The raw
+contents of the heading are stripped of leading and trailing space or tabs
+before being parsed as inline content. The heading level is equal to the number
+of `#` characters in the opening sequence.
+
+Simple headings:
+
+```````````````````````````````` example
+# foo
+## foo
+### foo
+#### foo
+##### foo
+###### foo
+.
+<h1>foo</h1>
+<h2>foo</h2>
+<h3>foo</h3>
+<h4>foo</h4>
+<h5>foo</h5>
+<h6>foo</h6>
+````````````````````````````````
+
+
+More than six `#` characters is not a heading:
+
+```````````````````````````````` example
+####### foo
+.
+<p>####### foo</p>
+````````````````````````````````
+
+
+At least one space or tab is required between the `#` characters and the
+heading's contents, unless the heading is empty. Note that many
+implementations currently do not require the space. However, the
+space was required by the
+[original ATX implementation](http://www.aaronsw.com/2002/atx/atx.py),
+and it helps prevent things like the following from being parsed as
+headings:
+
+```````````````````````````````` example
+#5 bolt
+
+#hashtag
+.
+<p>#5 bolt</p>
+<p>#hashtag</p>
+````````````````````````````````
+
+
+This is not a heading, because the first `#` is escaped:
+
+```````````````````````````````` example
+\## foo
+.
+<p>## foo</p>
+````````````````````````````````
+
+
+Contents are parsed as inlines:
+
+```````````````````````````````` example
+# foo *bar* \*baz\*
+.
+<h1>foo <em>bar</em> *baz*</h1>
+````````````````````````````````
+
+
+Leading and trailing spaces or tabs are ignored in parsing inline content:
+
+```````````````````````````````` example
+# foo
+.
+<h1>foo</h1>
+````````````````````````````````
+
+
+Up to three spaces of indentation are allowed:
+
+```````````````````````````````` example
+ ### foo
+ ## foo
+ # foo
+.
+<h3>foo</h3>
+<h2>foo</h2>
+<h1>foo</h1>
+````````````````````````````````
+
+
+Four spaces of indentation is too many:
+
+```````````````````````````````` example
+ # foo
+.
+<pre><code># foo
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo
+ # bar
+.
+<p>foo
+# bar</p>
+````````````````````````````````
+
+
+A closing sequence of `#` characters is optional:
+
+```````````````````````````````` example
+## foo ##
+ ### bar ###
+.
+<h2>foo</h2>
+<h3>bar</h3>
+````````````````````````````````
+
+
+It need not be the same length as the opening sequence:
+
+```````````````````````````````` example
+# foo ##################################
+##### foo ##
+.
+<h1>foo</h1>
+<h5>foo</h5>
+````````````````````````````````
+
+
+Spaces or tabs are allowed after the closing sequence:
+
+```````````````````````````````` example
+### foo ###
+.
+<h3>foo</h3>
+````````````````````````````````
+
+
+A sequence of `#` characters with anything but spaces or tabs following it
+is not a closing sequence, but counts as part of the contents of the
+heading:
+
+```````````````````````````````` example
+### foo ### b
+.
+<h3>foo ### b</h3>
+````````````````````````````````
+
+
+The closing sequence must be preceded by a space or tab:
+
+```````````````````````````````` example
+# foo#
+.
+<h1>foo#</h1>
+````````````````````````````````
+
+
+Backslash-escaped `#` characters do not count as part
+of the closing sequence:
+
+```````````````````````````````` example
+### foo \###
+## foo #\##
+# foo \#
+.
+<h3>foo ###</h3>
+<h2>foo ###</h2>
+<h1>foo #</h1>
+````````````````````````````````
+
+
+ATX headings need not be separated from surrounding content by blank
+lines, and they can interrupt paragraphs:
+
+```````````````````````````````` example
+****
+## foo
+****
+.
+<hr />
+<h2>foo</h2>
+<hr />
+````````````````````````````````
+
+
+```````````````````````````````` example
+Foo bar
+# baz
+Bar foo
+.
+<p>Foo bar</p>
+<h1>baz</h1>
+<p>Bar foo</p>
+````````````````````````````````
+
+
+ATX headings can be empty:
+
+```````````````````````````````` example
+##
+#
+### ###
+.
+<h2></h2>
+<h1></h1>
+<h3></h3>
+````````````````````````````````
+
+
+## Setext headings
+
+A [setext heading](@) consists of one or more
+lines of text, not interrupted by a blank line, of which the first line does not
+have more than 3 spaces of indentation, followed by
+a [setext heading underline]. The lines of text must be such
+that, were they not followed by the setext heading underline,
+they would be interpreted as a paragraph: they cannot be
+interpretable as a [code fence], [ATX heading][ATX headings],
+[block quote][block quotes], [thematic break][thematic breaks],
+[list item][list items], or [HTML block][HTML blocks].
+
+A [setext heading underline](@) is a sequence of
+`=` characters or a sequence of `-` characters, with no more than 3
+spaces of indentation and any number of trailing spaces or tabs.
+
+The heading is a level 1 heading if `=` characters are used in
+the [setext heading underline], and a level 2 heading if `-`
+characters are used. The contents of the heading are the result
+of parsing the preceding lines of text as CommonMark inline
+content.
+
+In general, a setext heading need not be preceded or followed by a
+blank line. However, it cannot interrupt a paragraph, so when a
+setext heading comes after a paragraph, a blank line is needed between
+them.
+
+Simple examples:
+
+```````````````````````````````` example
+Foo *bar*
+=========
+
+Foo *bar*
+---------
+.
+<h1>Foo <em>bar</em></h1>
+<h2>Foo <em>bar</em></h2>
+````````````````````````````````
+
+
+The content of the header may span more than one line:
+
+```````````````````````````````` example
+Foo *bar
+baz*
+====
+.
+<h1>Foo <em>bar
+baz</em></h1>
+````````````````````````````````
+
+The contents are the result of parsing the headings's raw
+content as inlines. The heading's raw content is formed by
+concatenating the lines and removing initial and final
+spaces or tabs.
+
+```````````````````````````````` example
+ Foo *bar
+baz*→
+====
+.
+<h1>Foo <em>bar
+baz</em></h1>
+````````````````````````````````
+
+
+The underlining can be any length:
+
+```````````````````````````````` example
+Foo
+-------------------------
+
+Foo
+=
+.
+<h2>Foo</h2>
+<h1>Foo</h1>
+````````````````````````````````
+
+
+The heading content can be preceded by up to three spaces of indentation, and
+need not line up with the underlining:
+
+```````````````````````````````` example
+ Foo
+---
+
+ Foo
+-----
+
+ Foo
+ ===
+.
+<h2>Foo</h2>
+<h2>Foo</h2>
+<h1>Foo</h1>
+````````````````````````````````
+
+
+Four spaces of indentation is too many:
+
+```````````````````````````````` example
+ Foo
+ ---
+
+ Foo
+---
+.
+<pre><code>Foo
+---
+
+Foo
+</code></pre>
+<hr />
+````````````````````````````````
+
+
+The setext heading underline can be preceded by up to three spaces of
+indentation, and may have trailing spaces or tabs:
+
+```````````````````````````````` example
+Foo
+ ----
+.
+<h2>Foo</h2>
+````````````````````````````````
+
+
+Four spaces of indentation is too many:
+
+```````````````````````````````` example
+Foo
+ ---
+.
+<p>Foo
+---</p>
+````````````````````````````````
+
+
+The setext heading underline cannot contain internal spaces or tabs:
+
+```````````````````````````````` example
+Foo
+= =
+
+Foo
+--- -
+.
+<p>Foo
+= =</p>
+<p>Foo</p>
+<hr />
+````````````````````````````````
+
+
+Trailing spaces or tabs in the content line do not cause a hard line break:
+
+```````````````````````````````` example
+Foo
+-----
+.
+<h2>Foo</h2>
+````````````````````````````````
+
+
+Nor does a backslash at the end:
+
+```````````````````````````````` example
+Foo\
+----
+.
+<h2>Foo\</h2>
+````````````````````````````````
+
+
+Since indicators of block structure take precedence over
+indicators of inline structure, the following are setext headings:
+
+```````````````````````````````` example
+`Foo
+----
+`
+
+<a title="a lot
+---
+of dashes"/>
+.
+<h2>`Foo</h2>
+<p>`</p>
+<h2><a title="a lot</h2>
+<p>of dashes"/></p>
+````````````````````````````````
+
+
+The setext heading underline cannot be a [lazy continuation
+line] in a list item or block quote:
+
+```````````````````````````````` example
+> Foo
+---
+.
+<blockquote>
+<p>Foo</p>
+</blockquote>
+<hr />
+````````````````````````````````
+
+
+```````````````````````````````` example
+> foo
+bar
+===
+.
+<blockquote>
+<p>foo
+bar
+===</p>
+</blockquote>
+````````````````````````````````
+
+
+```````````````````````````````` example
+- Foo
+---
+.
+<ul>
+<li>Foo</li>
+</ul>
+<hr />
+````````````````````````````````
+
+
+A blank line is needed between a paragraph and a following
+setext heading, since otherwise the paragraph becomes part
+of the heading's content:
+
+```````````````````````````````` example
+Foo
+Bar
+---
+.
+<h2>Foo
+Bar</h2>
+````````````````````````````````
+
+
+But in general a blank line is not required before or after
+setext headings:
+
+```````````````````````````````` example
+---
+Foo
+---
+Bar
+---
+Baz
+.
+<hr />
+<h2>Foo</h2>
+<h2>Bar</h2>
+<p>Baz</p>
+````````````````````````````````
+
+
+Setext headings cannot be empty:
+
+```````````````````````````````` example
+
+====
+.
+<p>====</p>
+````````````````````````````````
+
+
+Setext heading text lines must not be interpretable as block
+constructs other than paragraphs. So, the line of dashes
+in these examples gets interpreted as a thematic break:
+
+```````````````````````````````` example
+---
+---
+.
+<hr />
+<hr />
+````````````````````````````````
+
+
+```````````````````````````````` example
+- foo
+-----
+.
+<ul>
+<li>foo</li>
+</ul>
+<hr />
+````````````````````````````````
+
+
+```````````````````````````````` example
+ foo
+---
+.
+<pre><code>foo
+</code></pre>
+<hr />
+````````````````````````````````
+
+
+```````````````````````````````` example
+> foo
+-----
+.
+<blockquote>
+<p>foo</p>
+</blockquote>
+<hr />
+````````````````````````````````
+
+
+If you want a heading with `> foo` as its literal text, you can
+use backslash escapes:
+
+```````````````````````````````` example
+\> foo
+------
+.
+<h2>> foo</h2>
+````````````````````````````````
+
+
+**Compatibility note:** Most existing Markdown implementations
+do not allow the text of setext headings to span multiple lines.
+But there is no consensus about how to interpret
+
+``` markdown
+Foo
+bar
+---
+baz
+```
+
+One can find four different interpretations:
+
+1. paragraph "Foo", heading "bar", paragraph "baz"
+2. paragraph "Foo bar", thematic break, paragraph "baz"
+3. paragraph "Foo bar --- baz"
+4. heading "Foo bar", paragraph "baz"
+
+We find interpretation 4 most natural, and interpretation 4
+increases the expressive power of CommonMark, by allowing
+multiline headings. Authors who want interpretation 1 can
+put a blank line after the first paragraph:
+
+```````````````````````````````` example
+Foo
+
+bar
+---
+baz
+.
+<p>Foo</p>
+<h2>bar</h2>
+<p>baz</p>
+````````````````````````````````
+
+
+Authors who want interpretation 2 can put blank lines around
+the thematic break,
+
+```````````````````````````````` example
+Foo
+bar
+
+---
+
+baz
+.
+<p>Foo
+bar</p>
+<hr />
+<p>baz</p>
+````````````````````````````````
+
+
+or use a thematic break that cannot count as a [setext heading
+underline], such as
+
+```````````````````````````````` example
+Foo
+bar
+* * *
+baz
+.
+<p>Foo
+bar</p>
+<hr />
+<p>baz</p>
+````````````````````````````````
+
+
+Authors who want interpretation 3 can use backslash escapes:
+
+```````````````````````````````` example
+Foo
+bar
+\---
+baz
+.
+<p>Foo
+bar
+---
+baz</p>
+````````````````````````````````
+
+
+## Indented code blocks
+
+An [indented code block](@) is composed of one or more
+[indented chunks] separated by blank lines.
+An [indented chunk](@) is a sequence of non-blank lines,
+each preceded by four or more spaces of indentation. The contents of the code
+block are the literal contents of the lines, including trailing
+[line endings], minus four spaces of indentation.
+An indented code block has no [info string].
+
+An indented code block cannot interrupt a paragraph, so there must be
+a blank line between a paragraph and a following indented code block.
+(A blank line is not needed, however, between a code block and a following
+paragraph.)
+
+```````````````````````````````` example
+ a simple
+ indented code block
+.
+<pre><code>a simple
+ indented code block
+</code></pre>
+````````````````````````````````
+
+
+If there is any ambiguity between an interpretation of indentation
+as a code block and as indicating that material belongs to a [list
+item][list items], the list item interpretation takes precedence:
+
+```````````````````````````````` example
+ - foo
+
+ bar
+.
+<ul>
+<li>
+<p>foo</p>
+<p>bar</p>
+</li>
+</ul>
+````````````````````````````````
+
+
+```````````````````````````````` example
+1. foo
+
+ - bar
+.
+<ol>
+<li>
+<p>foo</p>
+<ul>
+<li>bar</li>
+</ul>
+</li>
+</ol>
+````````````````````````````````
+
+
+
+The contents of a code block are literal text, and do not get parsed
+as Markdown:
+
+```````````````````````````````` example
+ <a/>
+ *hi*
+
+ - one
+.
+<pre><code><a/>
+*hi*
+
+- one
+</code></pre>
+````````````````````````````````
+
+
+Here we have three chunks separated by blank lines:
+
+```````````````````````````````` example
+ chunk1
+
+ chunk2
+
+
+
+ chunk3
+.
+<pre><code>chunk1
+
+chunk2
+
+
+
+chunk3
+</code></pre>
+````````````````````````````````
+
+
+Any initial spaces or tabs beyond four spaces of indentation will be included in
+the content, even in interior blank lines:
+
+```````````````````````````````` example
+ chunk1
+
+ chunk2
+.
+<pre><code>chunk1
+
+ chunk2
+</code></pre>
+````````````````````````````````
+
+
+An indented code block cannot interrupt a paragraph. (This
+allows hanging indents and the like.)
+
+```````````````````````````````` example
+Foo
+ bar
+
+.
+<p>Foo
+bar</p>
+````````````````````````````````
+
+
+However, any non-blank line with fewer than four spaces of indentation ends
+the code block immediately. So a paragraph may occur immediately
+after indented code:
+
+```````````````````````````````` example
+ foo
+bar
+.
+<pre><code>foo
+</code></pre>
+<p>bar</p>
+````````````````````````````````
+
+
+And indented code can occur immediately before and after other kinds of
+blocks:
+
+```````````````````````````````` example
+# Heading
+ foo
+Heading
+------
+ foo
+----
+.
+<h1>Heading</h1>
+<pre><code>foo
+</code></pre>
+<h2>Heading</h2>
+<pre><code>foo
+</code></pre>
+<hr />
+````````````````````````````````
+
+
+The first line can be preceded by more than four spaces of indentation:
+
+```````````````````````````````` example
+ foo
+ bar
+.
+<pre><code> foo
+bar
+</code></pre>
+````````````````````````````````
+
+
+Blank lines preceding or following an indented code block
+are not included in it:
+
+```````````````````````````````` example
+
+
+ foo
+
+
+.
+<pre><code>foo
+</code></pre>
+````````````````````````````````
+
+
+Trailing spaces or tabs are included in the code block's content:
+
+```````````````````````````````` example
+ foo
+.
+<pre><code>foo
+</code></pre>
+````````````````````````````````
+
+
+
+## Fenced code blocks
+
+A [code fence](@) is a sequence
+of at least three consecutive backtick characters (`` ` ``) or
+tildes (`~`). (Tildes and backticks cannot be mixed.)
+A [fenced code block](@)
+begins with a code fence, preceded by up to three spaces of indentation.
+
+The line with the opening code fence may optionally contain some text
+following the code fence; this is trimmed of leading and trailing
+spaces or tabs and called the [info string](@). If the [info string] comes
+after a backtick fence, it may not contain any backtick
+characters. (The reason for this restriction is that otherwise
+some inline code would be incorrectly interpreted as the
+beginning of a fenced code block.)
+
+The content of the code block consists of all subsequent lines, until
+a closing [code fence] of the same type as the code block
+began with (backticks or tildes), and with at least as many backticks
+or tildes as the opening code fence. If the leading code fence is
+preceded by N spaces of indentation, then up to N spaces of indentation are
+removed from each line of the content (if present). (If a content line is not
+indented, it is preserved unchanged. If it is indented N spaces or less, all
+of the indentation is removed.)
+
+The closing code fence may be preceded by up to three spaces of indentation, and
+may be followed only by spaces or tabs, which are ignored. If the end of the
+containing block (or document) is reached and no closing code fence
+has been found, the code block contains all of the lines after the
+opening code fence until the end of the containing block (or
+document). (An alternative spec would require backtracking in the
+event that a closing code fence is not found. But this makes parsing
+much less efficient, and there seems to be no real downside to the
+behavior described here.)
+
+A fenced code block may interrupt a paragraph, and does not require
+a blank line either before or after.
+
+The content of a code fence is treated as literal text, not parsed
+as inlines. The first word of the [info string] is typically used to
+specify the language of the code sample, and rendered in the `class`
+attribute of the `code` tag. However, this spec does not mandate any
+particular treatment of the [info string].
+
+Here is a simple example with backticks:
+
+```````````````````````````````` example
+```
+<
+ >
+```
+.
+<pre><code><
+ >
+</code></pre>
+````````````````````````````````
+
+
+With tildes:
+
+```````````````````````````````` example
+~~~
+<
+ >
+~~~
+.
+<pre><code><
+ >
+</code></pre>
+````````````````````````````````
+
+Fewer than three backticks is not enough:
+
+```````````````````````````````` example
+``
+foo
+``
+.
+<p><code>foo</code></p>
+````````````````````````````````
+
+The closing code fence must use the same character as the opening
+fence:
+
+```````````````````````````````` example
+```
+aaa
+~~~
+```
+.
+<pre><code>aaa
+~~~
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+~~~
+aaa
+```
+~~~
+.
+<pre><code>aaa
+```
+</code></pre>
+````````````````````````````````
+
+
+The closing code fence must be at least as long as the opening fence:
+
+```````````````````````````````` example
+````
+aaa
+```
+``````
+.
+<pre><code>aaa
+```
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+~~~~
+aaa
+~~~
+~~~~
+.
+<pre><code>aaa
+~~~
+</code></pre>
+````````````````````````````````
+
+
+Unclosed code blocks are closed by the end of the document
+(or the enclosing [block quote][block quotes] or [list item][list items]):
+
+```````````````````````````````` example
+```
+.
+<pre><code></code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+`````
+
+```
+aaa
+.
+<pre><code>
+```
+aaa
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+> ```
+> aaa
+
+bbb
+.
+<blockquote>
+<pre><code>aaa
+</code></pre>
+</blockquote>
+<p>bbb</p>
+````````````````````````````````
+
+
+A code block can have all empty lines as its content:
+
+```````````````````````````````` example
+```
+
+
+```
+.
+<pre><code>
+
+</code></pre>
+````````````````````````````````
+
+
+A code block can be empty:
+
+```````````````````````````````` example
+```
+```
+.
+<pre><code></code></pre>
+````````````````````````````````
+
+
+Fences can be indented. If the opening fence is indented,
+content lines will have equivalent opening indentation removed,
+if present:
+
+```````````````````````````````` example
+ ```
+ aaa
+aaa
+```
+.
+<pre><code>aaa
+aaa
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+ ```
+aaa
+ aaa
+aaa
+ ```
+.
+<pre><code>aaa
+aaa
+aaa
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+ ```
+ aaa
+ aaa
+ aaa
+ ```
+.
+<pre><code>aaa
+ aaa
+aaa
+</code></pre>
+````````````````````````````````
+
+
+Four spaces of indentation is too many:
+
+```````````````````````````````` example
+ ```
+ aaa
+ ```
+.
+<pre><code>```
+aaa
+```
+</code></pre>
+````````````````````````````````
+
+
+Closing fences may be preceded by up to three spaces of indentation, and their
+indentation need not match that of the opening fence:
+
+```````````````````````````````` example
+```
+aaa
+ ```
+.
+<pre><code>aaa
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+ ```
+aaa
+ ```
+.
+<pre><code>aaa
+</code></pre>
+````````````````````````````````
+
+
+This is not a closing fence, because it is indented 4 spaces:
+
+```````````````````````````````` example
+```
+aaa
+ ```
+.
+<pre><code>aaa
+ ```
+</code></pre>
+````````````````````````````````
+
+
+
+Code fences (opening and closing) cannot contain internal spaces or tabs:
+
+```````````````````````````````` example
+``` ```
+aaa
+.
+<p><code> </code>
+aaa</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+~~~~~~
+aaa
+~~~ ~~
+.
+<pre><code>aaa
+~~~ ~~
+</code></pre>
+````````````````````````````````
+
+
+Fenced code blocks can interrupt paragraphs, and can be followed
+directly by paragraphs, without a blank line between:
+
+```````````````````````````````` example
+foo
+```
+bar
+```
+baz
+.
+<p>foo</p>
+<pre><code>bar
+</code></pre>
+<p>baz</p>
+````````````````````````````````
+
+
+Other blocks can also occur before and after fenced code blocks
+without an intervening blank line:
+
+```````````````````````````````` example
+foo
+---
+~~~
+bar
+~~~
+# baz
+.
+<h2>foo</h2>
+<pre><code>bar
+</code></pre>
+<h1>baz</h1>
+````````````````````````````````
+
+
+An [info string] can be provided after the opening code fence.
+Although this spec doesn't mandate any particular treatment of
+the info string, the first word is typically used to specify
+the language of the code block. In HTML output, the language is
+normally indicated by adding a class to the `code` element consisting
+of `language-` followed by the language name.
+
+```````````````````````````````` example
+```ruby
+def foo(x)
+ return 3
+end
+```
+.
+<pre><code class="language-ruby">def foo(x)
+ return 3
+end
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+~~~~ ruby startline=3 $%@#$
+def foo(x)
+ return 3
+end
+~~~~~~~
+.
+<pre><code class="language-ruby">def foo(x)
+ return 3
+end
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+````;
+````
+.
+<pre><code class="language-;"></code></pre>
+````````````````````````````````
+
+
+[Info strings] for backtick code blocks cannot contain backticks:
+
+```````````````````````````````` example
+``` aa ```
+foo
+.
+<p><code>aa</code>
+foo</p>
+````````````````````````````````
+
+
+[Info strings] for tilde code blocks can contain backticks and tildes:
+
+```````````````````````````````` example
+~~~ aa ``` ~~~
+foo
+~~~
+.
+<pre><code class="language-aa">foo
+</code></pre>
+````````````````````````````````
+
+
+Closing code fences cannot have [info strings]:
+
+```````````````````````````````` example
+```
+``` aaa
+```
+.
+<pre><code>``` aaa
+</code></pre>
+````````````````````````````````
+
+
+
+## HTML blocks
+
+An [HTML block](@) is a group of lines that is treated
+as raw HTML (and will not be escaped in HTML output).
+
+There are seven kinds of [HTML block], which can be defined by their
+start and end conditions. The block begins with a line that meets a
+[start condition](@) (after up to three optional spaces of indentation).
+It ends with the first subsequent line that meets a matching
+[end condition](@), or the last line of the document, or the last line of
+the [container block](#container-blocks) containing the current HTML
+block, if no line is encountered that meets the [end condition]. If
+the first line meets both the [start condition] and the [end
+condition], the block will contain just that line.
+
+1. **Start condition:** line begins with the string `<pre`,
+`<script`, `<style`, or `<textarea` (case-insensitive), followed by a space,
+a tab, the string `>`, or the end of the line.\
+**End condition:** line contains an end tag
+`</pre>`, `</script>`, `</style>`, or `</textarea>` (case-insensitive; it
+need not match the start tag).
+
+2. **Start condition:** line begins with the string `<!--`.\
+**End condition:** line contains the string `-->`.
+
+3. **Start condition:** line begins with the string `<?`.\
+**End condition:** line contains the string `?>`.
+
+4. **Start condition:** line begins with the string `<!`
+followed by an ASCII letter.\
+**End condition:** line contains the character `>`.
+
+5. **Start condition:** line begins with the string
+`<![CDATA[`.\
+**End condition:** line contains the string `]]]]><![CDATA[>`.
+
+6. **Start condition:** line begins with the string `<` or `</`
+followed by one of the strings (case-insensitive) `address`,
+`article`, `aside`, `base`, `basefont`, `blockquote`, `body`,
+`caption`, `center`, `col`, `colgroup`, `dd`, `details`, `dialog`,
+`dir`, `div`, `dl`, `dt`, `fieldset`, `figcaption`, `figure`,
+`footer`, `form`, `frame`, `frameset`,
+`h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `head`, `header`, `hr`,
+`html`, `iframe`, `legend`, `li`, `link`, `main`, `menu`, `menuitem`,
+`nav`, `noframes`, `ol`, `optgroup`, `option`, `p`, `param`,
+`search`, `section`, `summary`, `table`, `tbody`, `td`,
+`tfoot`, `th`, `thead`, `title`, `tr`, `track`, `ul`, followed
+by a space, a tab, the end of the line, the string `>`, or
+the string `/>`.\
+**End condition:** line is followed by a [blank line].
+
+7. **Start condition:** line begins with a complete [open tag]
+(with any [tag name] other than `pre`, `script`,
+`style`, or `textarea`) or a complete [closing tag],
+followed by zero or more spaces and tabs, followed by the end of the line.\
+**End condition:** line is followed by a [blank line].
+
+HTML blocks continue until they are closed by their appropriate
+[end condition], or the last line of the document or other [container
+block](#container-blocks). This means any HTML **within an HTML
+block** that might otherwise be recognised as a start condition will
+be ignored by the parser and passed through as-is, without changing
+the parser's state.
+
+For instance, `<pre>` within an HTML block started by `<table>` will not affect
+the parser state; as the HTML block was started in by start condition 6, it
+will end at any blank line. This can be surprising:
+
+```````````````````````````````` example
+<table><tr><td>
+<pre>
+**Hello**,
+
+_world_.
+</pre>
+</td></tr></table>
+.
+<table><tr><td>
+<pre>
+**Hello**,
+<p><em>world</em>.
+</pre></p>
+</td></tr></table>
+````````````````````````````````
+
+In this case, the HTML block is terminated by the blank line — the `**Hello**`
+text remains verbatim — and regular parsing resumes, with a paragraph,
+emphasised `world` and inline and block HTML following.
+
+All types of [HTML blocks] except type 7 may interrupt
+a paragraph. Blocks of type 7 may not interrupt a paragraph.
+(This restriction is intended to prevent unwanted interpretation
+of long tags inside a wrapped paragraph as starting HTML blocks.)
+
+Some simple examples follow. Here are some basic HTML blocks
+of type 6:
+
+```````````````````````````````` example
+<table>
+ <tr>
+ <td>
+ hi
+ </td>
+ </tr>
+</table>
+
+okay.
+.
+<table>
+ <tr>
+ <td>
+ hi
+ </td>
+ </tr>
+</table>
+<p>okay.</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+ <div>
+ *hello*
+ <foo><a>
+.
+ <div>
+ *hello*
+ <foo><a>
+````````````````````````````````
+
+
+A block can also start with a closing tag:
+
+```````````````````````````````` example
+</div>
+*foo*
+.
+</div>
+*foo*
+````````````````````````````````
+
+
+Here we have two HTML blocks with a Markdown paragraph between them:
+
+```````````````````````````````` example
+<DIV CLASS="foo">
+
+*Markdown*
+
+</DIV>
+.
+<DIV CLASS="foo">
+<p><em>Markdown</em></p>
+</DIV>
+````````````````````````````````
+
+
+The tag on the first line can be partial, as long
+as it is split where there would be whitespace:
+
+```````````````````````````````` example
+<div id="foo"
+ class="bar">
+</div>
+.
+<div id="foo"
+ class="bar">
+</div>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<div id="foo" class="bar
+ baz">
+</div>
+.
+<div id="foo" class="bar
+ baz">
+</div>
+````````````````````````````````
+
+
+An open tag need not be closed:
+```````````````````````````````` example
+<div>
+*foo*
+
+*bar*
+.
+<div>
+*foo*
+<p><em>bar</em></p>
+````````````````````````````````
+
+
+
+A partial tag need not even be completed (garbage
+in, garbage out):
+
+```````````````````````````````` example
+<div id="foo"
+*hi*
+.
+<div id="foo"
+*hi*
+````````````````````````````````
+
+
+```````````````````````````````` example
+<div class
+foo
+.
+<div class
+foo
+````````````````````````````````
+
+
+The initial tag doesn't even need to be a valid
+tag, as long as it starts like one:
+
+```````````````````````````````` example
+<div *???-&&&-<---
+*foo*
+.
+<div *???-&&&-<---
+*foo*
+````````````````````````````````
+
+
+In type 6 blocks, the initial tag need not be on a line by
+itself:
+
+```````````````````````````````` example
+<div><a href="bar">*foo*</a></div>
+.
+<div><a href="bar">*foo*</a></div>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<table><tr><td>
+foo
+</td></tr></table>
+.
+<table><tr><td>
+foo
+</td></tr></table>
+````````````````````````````````
+
+
+Everything until the next blank line or end of document
+gets included in the HTML block. So, in the following
+example, what looks like a Markdown code block
+is actually part of the HTML block, which continues until a blank
+line or the end of the document is reached:
+
+```````````````````````````````` example
+<div></div>
+``` c
+int x = 33;
+```
+.
+<div></div>
+``` c
+int x = 33;
+```
+````````````````````````````````
+
+
+To start an [HTML block] with a tag that is *not* in the
+list of block-level tags in (6), you must put the tag by
+itself on the first line (and it must be complete):
+
+```````````````````````````````` example
+<a href="foo">
+*bar*
+</a>
+.
+<a href="foo">
+*bar*
+</a>
+````````````````````````````````
+
+
+In type 7 blocks, the [tag name] can be anything:
+
+```````````````````````````````` example
+<Warning>
+*bar*
+</Warning>
+.
+<Warning>
+*bar*
+</Warning>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<i class="foo">
+*bar*
+</i>
+.
+<i class="foo">
+*bar*
+</i>
+````````````````````````````````
+
+
+```````````````````````````````` example
+</ins>
+*bar*
+.
+</ins>
+*bar*
+````````````````````````````````
+
+
+These rules are designed to allow us to work with tags that
+can function as either block-level or inline-level tags.
+The `<del>` tag is a nice example. We can surround content with
+`<del>` tags in three different ways. In this case, we get a raw
+HTML block, because the `<del>` tag is on a line by itself:
+
+```````````````````````````````` example
+<del>
+*foo*
+</del>
+.
+<del>
+*foo*
+</del>
+````````````````````````````````
+
+
+In this case, we get a raw HTML block that just includes
+the `<del>` tag (because it ends with the following blank
+line). So the contents get interpreted as CommonMark:
+
+```````````````````````````````` example
+<del>
+
+*foo*
+
+</del>
+.
+<del>
+<p><em>foo</em></p>
+</del>
+````````````````````````````````
+
+
+Finally, in this case, the `<del>` tags are interpreted
+as [raw HTML] *inside* the CommonMark paragraph. (Because
+the tag is not on a line by itself, we get inline HTML
+rather than an [HTML block].)
+
+```````````````````````````````` example
+<del>*foo*</del>
+.
+<p><del><em>foo</em></del></p>
+````````````````````````````````
+
+
+HTML tags designed to contain literal content
+(`pre`, `script`, `style`, `textarea`), comments, processing instructions,
+and declarations are treated somewhat differently.
+Instead of ending at the first blank line, these blocks
+end at the first line containing a corresponding end tag.
+As a result, these blocks can contain blank lines:
+
+A pre tag (type 1):
+
+```````````````````````````````` example
+<pre language="haskell"><code>
+import Text.HTML.TagSoup
+
+main :: IO ()
+main = print $ parseTags tags
+</code></pre>
+okay
+.
+<pre language="haskell"><code>
+import Text.HTML.TagSoup
+
+main :: IO ()
+main = print $ parseTags tags
+</code></pre>
+<p>okay</p>
+````````````````````````````````
+
+
+A script tag (type 1):
+
+```````````````````````````````` example
+<script type="text/javascript">
+// JavaScript example
+
+document.getElementById("demo").innerHTML = "Hello JavaScript!";
+</script>
+okay
+.
+<script type="text/javascript">
+// JavaScript example
+
+document.getElementById("demo").innerHTML = "Hello JavaScript!";
+</script>
+<p>okay</p>
+````````````````````````````````
+
+
+A textarea tag (type 1):
+
+```````````````````````````````` example
+<textarea>
+
+*foo*
+
+_bar_
+
+</textarea>
+.
+<textarea>
+
+*foo*
+
+_bar_
+
+</textarea>
+````````````````````````````````
+
+A style tag (type 1):
+
+```````````````````````````````` example
+<style
+ type="text/css">
+h1 {color:red;}
+
+p {color:blue;}
+</style>
+okay
+.
+<style
+ type="text/css">
+h1 {color:red;}
+
+p {color:blue;}
+</style>
+<p>okay</p>
+````````````````````````````````
+
+
+If there is no matching end tag, the block will end at the
+end of the document (or the enclosing [block quote][block quotes]
+or [list item][list items]):
+
+```````````````````````````````` example
+<style
+ type="text/css">
+
+foo
+.
+<style
+ type="text/css">
+
+foo
+````````````````````````````````
+
+
+```````````````````````````````` example
+> <div>
+> foo
+
+bar
+.
+<blockquote>
+<div>
+foo
+</blockquote>
+<p>bar</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+- <div>
+- foo
+.
+<ul>
+<li>
+<div>
+</li>
+<li>foo</li>
+</ul>
+````````````````````````````````
+
+
+The end tag can occur on the same line as the start tag:
+
+```````````````````````````````` example
+<style>p{color:red;}</style>
+*foo*
+.
+<style>p{color:red;}</style>
+<p><em>foo</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<!-- foo -->*bar*
+*baz*
+.
+<!-- foo -->*bar*
+<p><em>baz</em></p>
+````````````````````````````````
+
+
+Note that anything on the last line after the
+end tag will be included in the [HTML block]:
+
+```````````````````````````````` example
+<script>
+foo
+</script>1. *bar*
+.
+<script>
+foo
+</script>1. *bar*
+````````````````````````````````
+
+
+A comment (type 2):
+
+```````````````````````````````` example
+<!-- Foo
+
+bar
+ baz -->
+okay
+.
+<!-- Foo
+
+bar
+ baz -->
+<p>okay</p>
+````````````````````````````````
+
+
+
+A processing instruction (type 3):
+
+```````````````````````````````` example
+<?php
+
+ echo '>';
+
+?>
+okay
+.
+<?php
+
+ echo '>';
+
+?>
+<p>okay</p>
+````````````````````````````````
+
+
+A declaration (type 4):
+
+```````````````````````````````` example
+<!DOCTYPE html>
+.
+<!DOCTYPE html>
+````````````````````````````````
+
+
+CDATA (type 5):
+
+```````````````````````````````` example
+<![CDATA[
+function matchwo(a,b)
+{
+ if (a < b && a < 0) then {
+ return 1;
+
+ } else {
+
+ return 0;
+ }
+}
+]]]]><![CDATA[>
+okay
+.
+<![CDATA[
+function matchwo(a,b)
+{
+ if (a < b && a < 0) then {
+ return 1;
+
+ } else {
+
+ return 0;
+ }
+}
+]]]]><![CDATA[>
+<p>okay</p>
+````````````````````````````````
+
+
+The opening tag can be preceded by up to three spaces of indentation, but not
+four:
+
+```````````````````````````````` example
+ <!-- foo -->
+
+ <!-- foo -->
+.
+ <!-- foo -->
+<pre><code><!-- foo -->
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+ <div>
+
+ <div>
+.
+ <div>
+<pre><code><div>
+</code></pre>
+````````````````````````````````
+
+
+An HTML block of types 1--6 can interrupt a paragraph, and need not be
+preceded by a blank line.
+
+```````````````````````````````` example
+Foo
+<div>
+bar
+</div>
+.
+<p>Foo</p>
+<div>
+bar
+</div>
+````````````````````````````````
+
+
+However, a following blank line is needed, except at the end of
+a document, and except for blocks of types 1--5, [above][HTML
+block]:
+
+```````````````````````````````` example
+<div>
+bar
+</div>
+*foo*
+.
+<div>
+bar
+</div>
+*foo*
+````````````````````````````````
+
+
+HTML blocks of type 7 cannot interrupt a paragraph:
+
+```````````````````````````````` example
+Foo
+<a href="bar">
+baz
+.
+<p>Foo
+<a href="bar">
+baz</p>
+````````````````````````````````
+
+
+This rule differs from John Gruber's original Markdown syntax
+specification, which says:
+
+> The only restrictions are that block-level HTML elements —
+> e.g. `<div>`, `<table>`, `<pre>`, `<p>`, etc. — must be separated from
+> surrounding content by blank lines, and the start and end tags of the
+> block should not be indented with spaces or tabs.
+
+In some ways Gruber's rule is more restrictive than the one given
+here:
+
+- It requires that an HTML block be preceded by a blank line.
+- It does not allow the start tag to be indented.
+- It requires a matching end tag, which it also does not allow to
+ be indented.
+
+Most Markdown implementations (including some of Gruber's own) do not
+respect all of these restrictions.
+
+There is one respect, however, in which Gruber's rule is more liberal
+than the one given here, since it allows blank lines to occur inside
+an HTML block. There are two reasons for disallowing them here.
+First, it removes the need to parse balanced tags, which is
+expensive and can require backtracking from the end of the document
+if no matching end tag is found. Second, it provides a very simple
+and flexible way of including Markdown content inside HTML tags:
+simply separate the Markdown from the HTML using blank lines:
+
+Compare:
+
+```````````````````````````````` example
+<div>
+
+*Emphasized* text.
+
+</div>
+.
+<div>
+<p><em>Emphasized</em> text.</p>
+</div>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<div>
+*Emphasized* text.
+</div>
+.
+<div>
+*Emphasized* text.
+</div>
+````````````````````````````````
+
+
+Some Markdown implementations have adopted a convention of
+interpreting content inside tags as text if the open tag has
+the attribute `markdown=1`. The rule given above seems a simpler and
+more elegant way of achieving the same expressive power, which is also
+much simpler to parse.
+
+The main potential drawback is that one can no longer paste HTML
+blocks into Markdown documents with 100% reliability. However,
+*in most cases* this will work fine, because the blank lines in
+HTML are usually followed by HTML block tags. For example:
+
+```````````````````````````````` example
+<table>
+
+<tr>
+
+<td>
+Hi
+</td>
+
+</tr>
+
+</table>
+.
+<table>
+<tr>
+<td>
+Hi
+</td>
+</tr>
+</table>
+````````````````````````````````
+
+
+There are problems, however, if the inner tags are indented
+*and* separated by spaces, as then they will be interpreted as
+an indented code block:
+
+```````````````````````````````` example
+<table>
+
+ <tr>
+
+ <td>
+ Hi
+ </td>
+
+ </tr>
+
+</table>
+.
+<table>
+ <tr>
+<pre><code><td>
+ Hi
+</td>
+</code></pre>
+ </tr>
+</table>
+````````````````````````````````
+
+
+Fortunately, blank lines are usually not necessary and can be
+deleted. The exception is inside `<pre>` tags, but as described
+[above][HTML blocks], raw HTML blocks starting with `<pre>`
+*can* contain blank lines.
+
+## Link reference definitions
+
+A [link reference definition](@)
+consists of a [link label], optionally preceded by up to three spaces of
+indentation, followed
+by a colon (`:`), optional spaces or tabs (including up to one
+[line ending]), a [link destination],
+optional spaces or tabs (including up to one
+[line ending]), and an optional [link
+title], which if it is present must be separated
+from the [link destination] by spaces or tabs.
+No further character may occur.
+
+A [link reference definition]
+does not correspond to a structural element of a document. Instead, it
+defines a label which can be used in [reference links]
+and reference-style [images] elsewhere in the document. [Link
+reference definitions] can come either before or after the links that use
+them.
+
+```````````````````````````````` example
+[foo]: /url "title"
+
+[foo]
+.
+<p><a href="/url" title="title">foo</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+ [foo]:
+ /url
+ 'the title'
+
+[foo]
+.
+<p><a href="/url" title="the title">foo</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[Foo*bar\]]:my_(url) 'title (with parens)'
+
+[Foo*bar\]]
+.
+<p><a href="my_(url)" title="title (with parens)">Foo*bar]</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[Foo bar]:
+<my url>
+'title'
+
+[Foo bar]
+.
+<p><a href="my%20url" title="title">Foo bar</a></p>
+````````````````````````````````
+
+
+The title may extend over multiple lines:
+
+```````````````````````````````` example
+[foo]: /url '
+title
+line1
+line2
+'
+
+[foo]
+.
+<p><a href="/url" title="
+title
+line1
+line2
+">foo</a></p>
+````````````````````````````````
+
+
+However, it may not contain a [blank line]:
+
+```````````````````````````````` example
+[foo]: /url 'title
+
+with blank line'
+
+[foo]
+.
+<p>[foo]: /url 'title</p>
+<p>with blank line'</p>
+<p>[foo]</p>
+````````````````````````````````
+
+
+The title may be omitted:
+
+```````````````````````````````` example
+[foo]:
+/url
+
+[foo]
+.
+<p><a href="/url">foo</a></p>
+````````````````````````````````
+
+
+The link destination may not be omitted:
+
+```````````````````````````````` example
+[foo]:
+
+[foo]
+.
+<p>[foo]:</p>
+<p>[foo]</p>
+````````````````````````````````
+
+ However, an empty link destination may be specified using
+ angle brackets:
+
+```````````````````````````````` example
+[foo]: <>
+
+[foo]
+.
+<p><a href="">foo</a></p>
+````````````````````````````````
+
+The title must be separated from the link destination by
+spaces or tabs:
+
+```````````````````````````````` example
+[foo]: <bar>(baz)
+
+[foo]
+.
+<p>[foo]: <bar>(baz)</p>
+<p>[foo]</p>
+````````````````````````````````
+
+
+Both title and destination can contain backslash escapes
+and literal backslashes:
+
+```````````````````````````````` example
+[foo]: /url\bar\*baz "foo\"bar\baz"
+
+[foo]
+.
+<p><a href="/url%5Cbar*baz" title="foo"bar\baz">foo</a></p>
+````````````````````````````````
+
+
+A link can come before its corresponding definition:
+
+```````````````````````````````` example
+[foo]
+
+[foo]: url
+.
+<p><a href="url">foo</a></p>
+````````````````````````````````
+
+
+If there are several matching definitions, the first one takes
+precedence:
+
+```````````````````````````````` example
+[foo]
+
+[foo]: first
+[foo]: second
+.
+<p><a href="first">foo</a></p>
+````````````````````````````````
+
+
+As noted in the section on [Links], matching of labels is
+case-insensitive (see [matches]).
+
+```````````````````````````````` example
+[FOO]: /url
+
+[Foo]
+.
+<p><a href="/url">Foo</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[ΑΓΩ]: /φου
+
+[αγω]
+.
+<p><a href="/%CF%86%CE%BF%CF%85">αγω</a></p>
+````````````````````````````````
+
+
+Whether something is a [link reference definition] is
+independent of whether the link reference it defines is
+used in the document. Thus, for example, the following
+document contains just a link reference definition, and
+no visible content:
+
+```````````````````````````````` example
+[foo]: /url
+.
+````````````````````````````````
+
+
+Here is another one:
+
+```````````````````````````````` example
+[
+foo
+]: /url
+bar
+.
+<p>bar</p>
+````````````````````````````````
+
+
+This is not a link reference definition, because there are
+characters other than spaces or tabs after the title:
+
+```````````````````````````````` example
+[foo]: /url "title" ok
+.
+<p>[foo]: /url "title" ok</p>
+````````````````````````````````
+
+
+This is a link reference definition, but it has no title:
+
+```````````````````````````````` example
+[foo]: /url
+"title" ok
+.
+<p>"title" ok</p>
+````````````````````````````````
+
+
+This is not a link reference definition, because it is indented
+four spaces:
+
+```````````````````````````````` example
+ [foo]: /url "title"
+
+[foo]
+.
+<pre><code>[foo]: /url "title"
+</code></pre>
+<p>[foo]</p>
+````````````````````````````````
+
+
+This is not a link reference definition, because it occurs inside
+a code block:
+
+```````````````````````````````` example
+```
+[foo]: /url
+```
+
+[foo]
+.
+<pre><code>[foo]: /url
+</code></pre>
+<p>[foo]</p>
+````````````````````````````````
+
+
+A [link reference definition] cannot interrupt a paragraph.
+
+```````````````````````````````` example
+Foo
+[bar]: /baz
+
+[bar]
+.
+<p>Foo
+[bar]: /baz</p>
+<p>[bar]</p>
+````````````````````````````````
+
+
+However, it can directly follow other block elements, such as headings
+and thematic breaks, and it need not be followed by a blank line.
+
+```````````````````````````````` example
+# [Foo]
+[foo]: /url
+> bar
+.
+<h1><a href="/url">Foo</a></h1>
+<blockquote>
+<p>bar</p>
+</blockquote>
+````````````````````````````````
+
+```````````````````````````````` example
+[foo]: /url
+bar
+===
+[foo]
+.
+<h1>bar</h1>
+<p><a href="/url">foo</a></p>
+````````````````````````````````
+
+```````````````````````````````` example
+[foo]: /url
+===
+[foo]
+.
+<p>===
+<a href="/url">foo</a></p>
+````````````````````````````````
+
+
+Several [link reference definitions]
+can occur one after another, without intervening blank lines.
+
+```````````````````````````````` example
+[foo]: /foo-url "foo"
+[bar]: /bar-url
+ "bar"
+[baz]: /baz-url
+
+[foo],
+[bar],
+[baz]
+.
+<p><a href="/foo-url" title="foo">foo</a>,
+<a href="/bar-url" title="bar">bar</a>,
+<a href="/baz-url">baz</a></p>
+````````````````````````````````
+
+
+[Link reference definitions] can occur
+inside block containers, like lists and block quotations. They
+affect the entire document, not just the container in which they
+are defined:
+
+```````````````````````````````` example
+[foo]
+
+> [foo]: /url
+.
+<p><a href="/url">foo</a></p>
+<blockquote>
+</blockquote>
+````````````````````````````````
+
+
+## Paragraphs
+
+A sequence of non-blank lines that cannot be interpreted as other
+kinds of blocks forms a [paragraph](@).
+The contents of the paragraph are the result of parsing the
+paragraph's raw content as inlines. The paragraph's raw content
+is formed by concatenating the lines and removing initial and final
+spaces or tabs.
+
+A simple example with two paragraphs:
+
+```````````````````````````````` example
+aaa
+
+bbb
+.
+<p>aaa</p>
+<p>bbb</p>
+````````````````````````````````
+
+
+Paragraphs can contain multiple lines, but no blank lines:
+
+```````````````````````````````` example
+aaa
+bbb
+
+ccc
+ddd
+.
+<p>aaa
+bbb</p>
+<p>ccc
+ddd</p>
+````````````````````````````````
+
+
+Multiple blank lines between paragraphs have no effect:
+
+```````````````````````````````` example
+aaa
+
+
+bbb
+.
+<p>aaa</p>
+<p>bbb</p>
+````````````````````````````````
+
+
+Leading spaces or tabs are skipped:
+
+```````````````````````````````` example
+ aaa
+ bbb
+.
+<p>aaa
+bbb</p>
+````````````````````````````````
+
+
+Lines after the first may be indented any amount, since indented
+code blocks cannot interrupt paragraphs.
+
+```````````````````````````````` example
+aaa
+ bbb
+ ccc
+.
+<p>aaa
+bbb
+ccc</p>
+````````````````````````````````
+
+
+However, the first line may be preceded by up to three spaces of indentation.
+Four spaces of indentation is too many:
+
+```````````````````````````````` example
+ aaa
+bbb
+.
+<p>aaa
+bbb</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+ aaa
+bbb
+.
+<pre><code>aaa
+</code></pre>
+<p>bbb</p>
+````````````````````````````````
+
+
+Final spaces or tabs are stripped before inline parsing, so a paragraph
+that ends with two or more spaces will not end with a [hard line
+break]:
+
+```````````````````````````````` example
+aaa
+bbb
+.
+<p>aaa<br />
+bbb</p>
+````````````````````````````````
+
+
+## Blank lines
+
+[Blank lines] between block-level elements are ignored,
+except for the role they play in determining whether a [list]
+is [tight] or [loose].
+
+Blank lines at the beginning and end of the document are also ignored.
+
+```````````````````````````````` example
+
+
+aaa
+
+
+# aaa
+
+
+.
+<p>aaa</p>
+<h1>aaa</h1>
+````````````````````````````````
+
+
+
+# Container blocks
+
+A [container block](#container-blocks) is a block that has other
+blocks as its contents. There are two basic kinds of container blocks:
+[block quotes] and [list items].
+[Lists] are meta-containers for [list items].
+
+We define the syntax for container blocks recursively. The general
+form of the definition is:
+
+> If X is a sequence of blocks, then the result of
+> transforming X in such-and-such a way is a container of type Y
+> with these blocks as its content.
+
+So, we explain what counts as a block quote or list item by explaining
+how these can be *generated* from their contents. This should suffice
+to define the syntax, although it does not give a recipe for *parsing*
+these constructions. (A recipe is provided below in the section entitled
+[A parsing strategy](#appendix-a-parsing-strategy).)
+
+## Block quotes
+
+A [block quote marker](@),
+optionally preceded by up to three spaces of indentation,
+consists of (a) the character `>` together with a following space of
+indentation, or (b) a single character `>` not followed by a space of
+indentation.
+
+The following rules define [block quotes]:
+
+1. **Basic case.** If a string of lines *Ls* constitute a sequence
+ of blocks *Bs*, then the result of prepending a [block quote
+ marker] to the beginning of each line in *Ls*
+ is a [block quote](#block-quotes) containing *Bs*.
+
+2. **Laziness.** If a string of lines *Ls* constitute a [block
+ quote](#block-quotes) with contents *Bs*, then the result of deleting
+ the initial [block quote marker] from one or
+ more lines in which the next character other than a space or tab after the
+ [block quote marker] is [paragraph continuation
+ text] is a block quote with *Bs* as its content.
+ [Paragraph continuation text](@) is text
+ that will be parsed as part of the content of a paragraph, but does
+ not occur at the beginning of the paragraph.
+
+3. **Consecutiveness.** A document cannot contain two [block
+ quotes] in a row unless there is a [blank line] between them.
+
+Nothing else counts as a [block quote](#block-quotes).
+
+Here is a simple example:
+
+```````````````````````````````` example
+> # Foo
+> bar
+> baz
+.
+<blockquote>
+<h1>Foo</h1>
+<p>bar
+baz</p>
+</blockquote>
+````````````````````````````````
+
+
+The space or tab after the `>` characters can be omitted:
+
+```````````````````````````````` example
+># Foo
+>bar
+> baz
+.
+<blockquote>
+<h1>Foo</h1>
+<p>bar
+baz</p>
+</blockquote>
+````````````````````````````````
+
+
+The `>` characters can be preceded by up to three spaces of indentation:
+
+```````````````````````````````` example
+ > # Foo
+ > bar
+ > baz
+.
+<blockquote>
+<h1>Foo</h1>
+<p>bar
+baz</p>
+</blockquote>
+````````````````````````````````
+
+
+Four spaces of indentation is too many:
+
+```````````````````````````````` example
+ > # Foo
+ > bar
+ > baz
+.
+<pre><code>> # Foo
+> bar
+> baz
+</code></pre>
+````````````````````````````````
+
+
+The Laziness clause allows us to omit the `>` before
+[paragraph continuation text]:
+
+```````````````````````````````` example
+> # Foo
+> bar
+baz
+.
+<blockquote>
+<h1>Foo</h1>
+<p>bar
+baz</p>
+</blockquote>
+````````````````````````````````
+
+
+A block quote can contain some lazy and some non-lazy
+continuation lines:
+
+```````````````````````````````` example
+> bar
+baz
+> foo
+.
+<blockquote>
+<p>bar
+baz
+foo</p>
+</blockquote>
+````````````````````````````````
+
+
+Laziness only applies to lines that would have been continuations of
+paragraphs had they been prepended with [block quote markers].
+For example, the `> ` cannot be omitted in the second line of
+
+``` markdown
+> foo
+> ---
+```
+
+without changing the meaning:
+
+```````````````````````````````` example
+> foo
+---
+.
+<blockquote>
+<p>foo</p>
+</blockquote>
+<hr />
+````````````````````````````````
+
+
+Similarly, if we omit the `> ` in the second line of
+
+``` markdown
+> - foo
+> - bar
+```
+
+then the block quote ends after the first line:
+
+```````````````````````````````` example
+> - foo
+- bar
+.
+<blockquote>
+<ul>
+<li>foo</li>
+</ul>
+</blockquote>
+<ul>
+<li>bar</li>
+</ul>
+````````````````````````````````
+
+
+For the same reason, we can't omit the `> ` in front of
+subsequent lines of an indented or fenced code block:
+
+```````````````````````````````` example
+> foo
+ bar
+.
+<blockquote>
+<pre><code>foo
+</code></pre>
+</blockquote>
+<pre><code>bar
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+> ```
+foo
+```
+.
+<blockquote>
+<pre><code></code></pre>
+</blockquote>
+<p>foo</p>
+<pre><code></code></pre>
+````````````````````````````````
+
+
+Note that in the following case, we have a [lazy
+continuation line]:
+
+```````````````````````````````` example
+> foo
+ - bar
+.
+<blockquote>
+<p>foo
+- bar</p>
+</blockquote>
+````````````````````````````````
+
+
+To see why, note that in
+
+```markdown
+> foo
+> - bar
+```
+
+the `- bar` is indented too far to start a list, and can't
+be an indented code block because indented code blocks cannot
+interrupt paragraphs, so it is [paragraph continuation text].
+
+A block quote can be empty:
+
+```````````````````````````````` example
+>
+.
+<blockquote>
+</blockquote>
+````````````````````````````````
+
+
+```````````````````````````````` example
+>
+>
+>
+.
+<blockquote>
+</blockquote>
+````````````````````````````````
+
+
+A block quote can have initial or final blank lines:
+
+```````````````````````````````` example
+>
+> foo
+>
+.
+<blockquote>
+<p>foo</p>
+</blockquote>
+````````````````````````````````
+
+
+A blank line always separates block quotes:
+
+```````````````````````````````` example
+> foo
+
+> bar
+.
+<blockquote>
+<p>foo</p>
+</blockquote>
+<blockquote>
+<p>bar</p>
+</blockquote>
+````````````````````````````````
+
+
+(Most current Markdown implementations, including John Gruber's
+original `Markdown.pl`, will parse this example as a single block quote
+with two paragraphs. But it seems better to allow the author to decide
+whether two block quotes or one are wanted.)
+
+Consecutiveness means that if we put these block quotes together,
+we get a single block quote:
+
+```````````````````````````````` example
+> foo
+> bar
+.
+<blockquote>
+<p>foo
+bar</p>
+</blockquote>
+````````````````````````````````
+
+
+To get a block quote with two paragraphs, use:
+
+```````````````````````````````` example
+> foo
+>
+> bar
+.
+<blockquote>
+<p>foo</p>
+<p>bar</p>
+</blockquote>
+````````````````````````````````
+
+
+Block quotes can interrupt paragraphs:
+
+```````````````````````````````` example
+foo
+> bar
+.
+<p>foo</p>
+<blockquote>
+<p>bar</p>
+</blockquote>
+````````````````````````````````
+
+
+In general, blank lines are not needed before or after block
+quotes:
+
+```````````````````````````````` example
+> aaa
+***
+> bbb
+.
+<blockquote>
+<p>aaa</p>
+</blockquote>
+<hr />
+<blockquote>
+<p>bbb</p>
+</blockquote>
+````````````````````````````````
+
+
+However, because of laziness, a blank line is needed between
+a block quote and a following paragraph:
+
+```````````````````````````````` example
+> bar
+baz
+.
+<blockquote>
+<p>bar
+baz</p>
+</blockquote>
+````````````````````````````````
+
+
+```````````````````````````````` example
+> bar
+
+baz
+.
+<blockquote>
+<p>bar</p>
+</blockquote>
+<p>baz</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+> bar
+>
+baz
+.
+<blockquote>
+<p>bar</p>
+</blockquote>
+<p>baz</p>
+````````````````````````````````
+
+
+It is a consequence of the Laziness rule that any number
+of initial `>`s may be omitted on a continuation line of a
+nested block quote:
+
+```````````````````````````````` example
+> > > foo
+bar
+.
+<blockquote>
+<blockquote>
+<blockquote>
+<p>foo
+bar</p>
+</blockquote>
+</blockquote>
+</blockquote>
+````````````````````````````````
+
+
+```````````````````````````````` example
+>>> foo
+> bar
+>>baz
+.
+<blockquote>
+<blockquote>
+<blockquote>
+<p>foo
+bar
+baz</p>
+</blockquote>
+</blockquote>
+</blockquote>
+````````````````````````````````
+
+
+When including an indented code block in a block quote,
+remember that the [block quote marker] includes
+both the `>` and a following space of indentation. So *five spaces* are needed
+after the `>`:
+
+```````````````````````````````` example
+> code
+
+> not code
+.
+<blockquote>
+<pre><code>code
+</code></pre>
+</blockquote>
+<blockquote>
+<p>not code</p>
+</blockquote>
+````````````````````````````````
+
+
+
+## List items
+
+A [list marker](@) is a
+[bullet list marker] or an [ordered list marker].
+
+A [bullet list marker](@)
+is a `-`, `+`, or `*` character.
+
+An [ordered list marker](@)
+is a sequence of 1--9 arabic digits (`0-9`), followed by either a
+`.` character or a `)` character. (The reason for the length
+limit is that with 10 digits we start seeing integer overflows
+in some browsers.)
+
+The following rules define [list items]:
+
+1. **Basic case.** If a sequence of lines *Ls* constitute a sequence of
+ blocks *Bs* starting with a character other than a space or tab, and *M* is
+ a list marker of width *W* followed by 1 ≤ *N* ≤ 4 spaces of indentation,
+ then the result of prepending *M* and the following spaces to the first line
+ of *Ls*, and indenting subsequent lines of *Ls* by *W + N* spaces, is a
+ list item with *Bs* as its contents. The type of the list item
+ (bullet or ordered) is determined by the type of its list marker.
+ If the list item is ordered, then it is also assigned a start
+ number, based on the ordered list marker.
+
+ Exceptions:
+
+ 1. When the first list item in a [list] interrupts
+ a paragraph---that is, when it starts on a line that would
+ otherwise count as [paragraph continuation text]---then (a)
+ the lines *Ls* must not begin with a blank line, and (b) if
+ the list item is ordered, the start number must be 1.
+ 2. If any line is a [thematic break][thematic breaks] then
+ that line is not a list item.
+
+For example, let *Ls* be the lines
+
+```````````````````````````````` example
+A paragraph
+with two lines.
+
+ indented code
+
+> A block quote.
+.
+<p>A paragraph
+with two lines.</p>
+<pre><code>indented code
+</code></pre>
+<blockquote>
+<p>A block quote.</p>
+</blockquote>
+````````````````````````````````
+
+
+And let *M* be the marker `1.`, and *N* = 2. Then rule #1 says
+that the following is an ordered list item with start number 1,
+and the same contents as *Ls*:
+
+```````````````````````````````` example
+1. A paragraph
+ with two lines.
+
+ indented code
+
+ > A block quote.
+.
+<ol>
+<li>
+<p>A paragraph
+with two lines.</p>
+<pre><code>indented code
+</code></pre>
+<blockquote>
+<p>A block quote.</p>
+</blockquote>
+</li>
+</ol>
+````````````````````````````````
+
+
+The most important thing to notice is that the position of
+the text after the list marker determines how much indentation
+is needed in subsequent blocks in the list item. If the list
+marker takes up two spaces of indentation, and there are three spaces between
+the list marker and the next character other than a space or tab, then blocks
+must be indented five spaces in order to fall under the list
+item.
+
+Here are some examples showing how far content must be indented to be
+put under the list item:
+
+```````````````````````````````` example
+- one
+
+ two
+.
+<ul>
+<li>one</li>
+</ul>
+<p>two</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+- one
+
+ two
+.
+<ul>
+<li>
+<p>one</p>
+<p>two</p>
+</li>
+</ul>
+````````````````````````````````
+
+
+```````````````````````````````` example
+ - one
+
+ two
+.
+<ul>
+<li>one</li>
+</ul>
+<pre><code> two
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+ - one
+
+ two
+.
+<ul>
+<li>
+<p>one</p>
+<p>two</p>
+</li>
+</ul>
+````````````````````````````````
+
+
+It is tempting to think of this in terms of columns: the continuation
+blocks must be indented at least to the column of the first character other than
+a space or tab after the list marker. However, that is not quite right.
+The spaces of indentation after the list marker determine how much relative
+indentation is needed. Which column this indentation reaches will depend on
+how the list item is embedded in other constructions, as shown by
+this example:
+
+```````````````````````````````` example
+ > > 1. one
+>>
+>> two
+.
+<blockquote>
+<blockquote>
+<ol>
+<li>
+<p>one</p>
+<p>two</p>
+</li>
+</ol>
+</blockquote>
+</blockquote>
+````````````````````````````````
+
+
+Here `two` occurs in the same column as the list marker `1.`,
+but is actually contained in the list item, because there is
+sufficient indentation after the last containing blockquote marker.
+
+The converse is also possible. In the following example, the word `two`
+occurs far to the right of the initial text of the list item, `one`, but
+it is not considered part of the list item, because it is not indented
+far enough past the blockquote marker:
+
+```````````````````````````````` example
+>>- one
+>>
+ > > two
+.
+<blockquote>
+<blockquote>
+<ul>
+<li>one</li>
+</ul>
+<p>two</p>
+</blockquote>
+</blockquote>
+````````````````````````````````
+
+
+Note that at least one space or tab is needed between the list marker and
+any following content, so these are not list items:
+
+```````````````````````````````` example
+-one
+
+2.two
+.
+<p>-one</p>
+<p>2.two</p>
+````````````````````````````````
+
+
+A list item may contain blocks that are separated by more than
+one blank line.
+
+```````````````````````````````` example
+- foo
+
+
+ bar
+.
+<ul>
+<li>
+<p>foo</p>
+<p>bar</p>
+</li>
+</ul>
+````````````````````````````````
+
+
+A list item may contain any kind of block:
+
+```````````````````````````````` example
+1. foo
+
+ ```
+ bar
+ ```
+
+ baz
+
+ > bam
+.
+<ol>
+<li>
+<p>foo</p>
+<pre><code>bar
+</code></pre>
+<p>baz</p>
+<blockquote>
+<p>bam</p>
+</blockquote>
+</li>
+</ol>
+````````````````````````````````
+
+
+A list item that contains an indented code block will preserve
+empty lines within the code block verbatim.
+
+```````````````````````````````` example
+- Foo
+
+ bar
+
+
+ baz
+.
+<ul>
+<li>
+<p>Foo</p>
+<pre><code>bar
+
+
+baz
+</code></pre>
+</li>
+</ul>
+````````````````````````````````
+
+Note that ordered list start numbers must be nine digits or less:
+
+```````````````````````````````` example
+123456789. ok
+.
+<ol start="123456789">
+<li>ok</li>
+</ol>
+````````````````````````````````
+
+
+```````````````````````````````` example
+1234567890. not ok
+.
+<p>1234567890. not ok</p>
+````````````````````````````````
+
+
+A start number may begin with 0s:
+
+```````````````````````````````` example
+0. ok
+.
+<ol start="0">
+<li>ok</li>
+</ol>
+````````````````````````````````
+
+
+```````````````````````````````` example
+003. ok
+.
+<ol start="3">
+<li>ok</li>
+</ol>
+````````````````````````````````
+
+
+A start number may not be negative:
+
+```````````````````````````````` example
+-1. not ok
+.
+<p>-1. not ok</p>
+````````````````````````````````
+
+
+
+2. **Item starting with indented code.** If a sequence of lines *Ls*
+ constitute a sequence of blocks *Bs* starting with an indented code
+ block, and *M* is a list marker of width *W* followed by
+ one space of indentation, then the result of prepending *M* and the
+ following space to the first line of *Ls*, and indenting subsequent lines
+ of *Ls* by *W + 1* spaces, is a list item with *Bs* as its contents.
+ If a line is empty, then it need not be indented. The type of the
+ list item (bullet or ordered) is determined by the type of its list
+ marker. If the list item is ordered, then it is also assigned a
+ start number, based on the ordered list marker.
+
+An indented code block will have to be preceded by four spaces of indentation
+beyond the edge of the region where text will be included in the list item.
+In the following case that is 6 spaces:
+
+```````````````````````````````` example
+- foo
+
+ bar
+.
+<ul>
+<li>
+<p>foo</p>
+<pre><code>bar
+</code></pre>
+</li>
+</ul>
+````````````````````````````````
+
+
+And in this case it is 11 spaces:
+
+```````````````````````````````` example
+ 10. foo
+
+ bar
+.
+<ol start="10">
+<li>
+<p>foo</p>
+<pre><code>bar
+</code></pre>
+</li>
+</ol>
+````````````````````````````````
+
+
+If the *first* block in the list item is an indented code block,
+then by rule #2, the contents must be preceded by *one* space of indentation
+after the list marker:
+
+```````````````````````````````` example
+ indented code
+
+paragraph
+
+ more code
+.
+<pre><code>indented code
+</code></pre>
+<p>paragraph</p>
+<pre><code>more code
+</code></pre>
+````````````````````````````````
+
+
+```````````````````````````````` example
+1. indented code
+
+ paragraph
+
+ more code
+.
+<ol>
+<li>
+<pre><code>indented code
+</code></pre>
+<p>paragraph</p>
+<pre><code>more code
+</code></pre>
+</li>
+</ol>
+````````````````````````````````
+
+
+Note that an additional space of indentation is interpreted as space
+inside the code block:
+
+```````````````````````````````` example
+1. indented code
+
+ paragraph
+
+ more code
+.
+<ol>
+<li>
+<pre><code> indented code
+</code></pre>
+<p>paragraph</p>
+<pre><code>more code
+</code></pre>
+</li>
+</ol>
+````````````````````````````````
+
+
+Note that rules #1 and #2 only apply to two cases: (a) cases
+in which the lines to be included in a list item begin with a
+character other than a space or tab, and (b) cases in which
+they begin with an indented code
+block. In a case like the following, where the first block begins with
+three spaces of indentation, the rules do not allow us to form a list item by
+indenting the whole thing and prepending a list marker:
+
+```````````````````````````````` example
+ foo
+
+bar
+.
+<p>foo</p>
+<p>bar</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+- foo
+
+ bar
+.
+<ul>
+<li>foo</li>
+</ul>
+<p>bar</p>
+````````````````````````````````
+
+
+This is not a significant restriction, because when a block is preceded by up to
+three spaces of indentation, the indentation can always be removed without
+a change in interpretation, allowing rule #1 to be applied. So, in
+the above case:
+
+```````````````````````````````` example
+- foo
+
+ bar
+.
+<ul>
+<li>
+<p>foo</p>
+<p>bar</p>
+</li>
+</ul>
+````````````````````````````````
+
+
+3. **Item starting with a blank line.** If a sequence of lines *Ls*
+ starting with a single [blank line] constitute a (possibly empty)
+ sequence of blocks *Bs*, and *M* is a list marker of width *W*,
+ then the result of prepending *M* to the first line of *Ls*, and
+ preceding subsequent lines of *Ls* by *W + 1* spaces of indentation, is a
+ list item with *Bs* as its contents.
+ If a line is empty, then it need not be indented. The type of the
+ list item (bullet or ordered) is determined by the type of its list
+ marker. If the list item is ordered, then it is also assigned a
+ start number, based on the ordered list marker.
+
+Here are some list items that start with a blank line but are not empty:
+
+```````````````````````````````` example
+-
+ foo
+-
+ ```
+ bar
+ ```
+-
+ baz
+.
+<ul>
+<li>foo</li>
+<li>
+<pre><code>bar
+</code></pre>
+</li>
+<li>
+<pre><code>baz
+</code></pre>
+</li>
+</ul>
+````````````````````````````````
+
+When the list item starts with a blank line, the number of spaces
+following the list marker doesn't change the required indentation:
+
+```````````````````````````````` example
+-
+ foo
+.
+<ul>
+<li>foo</li>
+</ul>
+````````````````````````````````
+
+
+A list item can begin with at most one blank line.
+In the following example, `foo` is not part of the list
+item:
+
+```````````````````````````````` example
+-
+
+ foo
+.
+<ul>
+<li></li>
+</ul>
+<p>foo</p>
+````````````````````````````````
+
+
+Here is an empty bullet list item:
+
+```````````````````````````````` example
+- foo
+-
+- bar
+.
+<ul>
+<li>foo</li>
+<li></li>
+<li>bar</li>
+</ul>
+````````````````````````````````
+
+
+It does not matter whether there are spaces or tabs following the [list marker]:
+
+```````````````````````````````` example
+- foo
+-
+- bar
+.
+<ul>
+<li>foo</li>
+<li></li>
+<li>bar</li>
+</ul>
+````````````````````````````````
+
+
+Here is an empty ordered list item:
+
+```````````````````````````````` example
+1. foo
+2.
+3. bar
+.
+<ol>
+<li>foo</li>
+<li></li>
+<li>bar</li>
+</ol>
+````````````````````````````````
+
+
+A list may start or end with an empty list item:
+
+```````````````````````````````` example
+*
+.
+<ul>
+<li></li>
+</ul>
+````````````````````````````````
+
+However, an empty list item cannot interrupt a paragraph:
+
+```````````````````````````````` example
+foo
+*
+
+foo
+1.
+.
+<p>foo
+*</p>
+<p>foo
+1.</p>
+````````````````````````````````
+
+
+4. **Indentation.** If a sequence of lines *Ls* constitutes a list item
+ according to rule #1, #2, or #3, then the result of preceding each line
+ of *Ls* by up to three spaces of indentation (the same for each line) also
+ constitutes a list item with the same contents and attributes. If a line is
+ empty, then it need not be indented.
+
+Indented one space:
+
+```````````````````````````````` example
+ 1. A paragraph
+ with two lines.
+
+ indented code
+
+ > A block quote.
+.
+<ol>
+<li>
+<p>A paragraph
+with two lines.</p>
+<pre><code>indented code
+</code></pre>
+<blockquote>
+<p>A block quote.</p>
+</blockquote>
+</li>
+</ol>
+````````````````````````````````
+
+
+Indented two spaces:
+
+```````````````````````````````` example
+ 1. A paragraph
+ with two lines.
+
+ indented code
+
+ > A block quote.
+.
+<ol>
+<li>
+<p>A paragraph
+with two lines.</p>
+<pre><code>indented code
+</code></pre>
+<blockquote>
+<p>A block quote.</p>
+</blockquote>
+</li>
+</ol>
+````````````````````````````````
+
+
+Indented three spaces:
+
+```````````````````````````````` example
+ 1. A paragraph
+ with two lines.
+
+ indented code
+
+ > A block quote.
+.
+<ol>
+<li>
+<p>A paragraph
+with two lines.</p>
+<pre><code>indented code
+</code></pre>
+<blockquote>
+<p>A block quote.</p>
+</blockquote>
+</li>
+</ol>
+````````````````````````````````
+
+
+Four spaces indent gives a code block:
+
+```````````````````````````````` example
+ 1. A paragraph
+ with two lines.
+
+ indented code
+
+ > A block quote.
+.
+<pre><code>1. A paragraph
+ with two lines.
+
+ indented code
+
+ > A block quote.
+</code></pre>
+````````````````````````````````
+
+
+
+5. **Laziness.** If a string of lines *Ls* constitute a [list
+ item](#list-items) with contents *Bs*, then the result of deleting
+ some or all of the indentation from one or more lines in which the
+ next character other than a space or tab after the indentation is
+ [paragraph continuation text] is a
+ list item with the same contents and attributes. The unindented
+ lines are called
+ [lazy continuation line](@)s.
+
+Here is an example with [lazy continuation lines]:
+
+```````````````````````````````` example
+ 1. A paragraph
+with two lines.
+
+ indented code
+
+ > A block quote.
+.
+<ol>
+<li>
+<p>A paragraph
+with two lines.</p>
+<pre><code>indented code
+</code></pre>
+<blockquote>
+<p>A block quote.</p>
+</blockquote>
+</li>
+</ol>
+````````````````````````````````
+
+
+Indentation can be partially deleted:
+
+```````````````````````````````` example
+ 1. A paragraph
+ with two lines.
+.
+<ol>
+<li>A paragraph
+with two lines.</li>
+</ol>
+````````````````````````````````
+
+
+These examples show how laziness can work in nested structures:
+
+```````````````````````````````` example
+> 1. > Blockquote
+continued here.
+.
+<blockquote>
+<ol>
+<li>
+<blockquote>
+<p>Blockquote
+continued here.</p>
+</blockquote>
+</li>
+</ol>
+</blockquote>
+````````````````````````````````
+
+
+```````````````````````````````` example
+> 1. > Blockquote
+> continued here.
+.
+<blockquote>
+<ol>
+<li>
+<blockquote>
+<p>Blockquote
+continued here.</p>
+</blockquote>
+</li>
+</ol>
+</blockquote>
+````````````````````````````````
+
+
+
+6. **That's all.** Nothing that is not counted as a list item by rules
+ #1--5 counts as a [list item](#list-items).
+
+The rules for sublists follow from the general rules
+[above][List items]. A sublist must be indented the same number
+of spaces of indentation a paragraph would need to be in order to be included
+in the list item.
+
+So, in this case we need two spaces indent:
+
+```````````````````````````````` example
+- foo
+ - bar
+ - baz
+ - boo
+.
+<ul>
+<li>foo
+<ul>
+<li>bar
+<ul>
+<li>baz
+<ul>
+<li>boo</li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+````````````````````````````````
+
+
+One is not enough:
+
+```````````````````````````````` example
+- foo
+ - bar
+ - baz
+ - boo
+.
+<ul>
+<li>foo</li>
+<li>bar</li>
+<li>baz</li>
+<li>boo</li>
+</ul>
+````````````````````````````````
+
+
+Here we need four, because the list marker is wider:
+
+```````````````````````````````` example
+10) foo
+ - bar
+.
+<ol start="10">
+<li>foo
+<ul>
+<li>bar</li>
+</ul>
+</li>
+</ol>
+````````````````````````````````
+
+
+Three is not enough:
+
+```````````````````````````````` example
+10) foo
+ - bar
+.
+<ol start="10">
+<li>foo</li>
+</ol>
+<ul>
+<li>bar</li>
+</ul>
+````````````````````````````````
+
+
+A list may be the first block in a list item:
+
+```````````````````````````````` example
+- - foo
+.
+<ul>
+<li>
+<ul>
+<li>foo</li>
+</ul>
+</li>
+</ul>
+````````````````````````````````
+
+
+```````````````````````````````` example
+1. - 2. foo
+.
+<ol>
+<li>
+<ul>
+<li>
+<ol start="2">
+<li>foo</li>
+</ol>
+</li>
+</ul>
+</li>
+</ol>
+````````````````````````````````
+
+
+A list item can contain a heading:
+
+```````````````````````````````` example
+- # Foo
+- Bar
+ ---
+ baz
+.
+<ul>
+<li>
+<h1>Foo</h1>
+</li>
+<li>
+<h2>Bar</h2>
+baz</li>
+</ul>
+````````````````````````````````
+
+
+### Motivation
+
+John Gruber's Markdown spec says the following about list items:
+
+1. "List markers typically start at the left margin, but may be indented
+ by up to three spaces. List markers must be followed by one or more
+ spaces or a tab."
+
+2. "To make lists look nice, you can wrap items with hanging indents....
+ But if you don't want to, you don't have to."
+
+3. "List items may consist of multiple paragraphs. Each subsequent
+ paragraph in a list item must be indented by either 4 spaces or one
+ tab."
+
+4. "It looks nice if you indent every line of the subsequent paragraphs,
+ but here again, Markdown will allow you to be lazy."
+
+5. "To put a blockquote within a list item, the blockquote's `>`
+ delimiters need to be indented."
+
+6. "To put a code block within a list item, the code block needs to be
+ indented twice — 8 spaces or two tabs."
+
+These rules specify that a paragraph under a list item must be indented
+four spaces (presumably, from the left margin, rather than the start of
+the list marker, but this is not said), and that code under a list item
+must be indented eight spaces instead of the usual four. They also say
+that a block quote must be indented, but not by how much; however, the
+example given has four spaces indentation. Although nothing is said
+about other kinds of block-level content, it is certainly reasonable to
+infer that *all* block elements under a list item, including other
+lists, must be indented four spaces. This principle has been called the
+*four-space rule*.
+
+The four-space rule is clear and principled, and if the reference
+implementation `Markdown.pl` had followed it, it probably would have
+become the standard. However, `Markdown.pl` allowed paragraphs and
+sublists to start with only two spaces indentation, at least on the
+outer level. Worse, its behavior was inconsistent: a sublist of an
+outer-level list needed two spaces indentation, but a sublist of this
+sublist needed three spaces. It is not surprising, then, that different
+implementations of Markdown have developed very different rules for
+determining what comes under a list item. (Pandoc and python-Markdown,
+for example, stuck with Gruber's syntax description and the four-space
+rule, while discount, redcarpet, marked, PHP Markdown, and others
+followed `Markdown.pl`'s behavior more closely.)
+
+Unfortunately, given the divergences between implementations, there
+is no way to give a spec for list items that will be guaranteed not
+to break any existing documents. However, the spec given here should
+correctly handle lists formatted with either the four-space rule or
+the more forgiving `Markdown.pl` behavior, provided they are laid out
+in a way that is natural for a human to read.
+
+The strategy here is to let the width and indentation of the list marker
+determine the indentation necessary for blocks to fall under the list
+item, rather than having a fixed and arbitrary number. The writer can
+think of the body of the list item as a unit which gets indented to the
+right enough to fit the list marker (and any indentation on the list
+marker). (The laziness rule, #5, then allows continuation lines to be
+unindented if needed.)
+
+This rule is superior, we claim, to any rule requiring a fixed level of
+indentation from the margin. The four-space rule is clear but
+unnatural. It is quite unintuitive that
+
+``` markdown
+- foo
+
+ bar
+
+ - baz
+```
+
+should be parsed as two lists with an intervening paragraph,
+
+``` html
+<ul>
+<li>foo</li>
+</ul>
+<p>bar</p>
+<ul>
+<li>baz</li>
+</ul>
+```
+
+as the four-space rule demands, rather than a single list,
+
+``` html
+<ul>
+<li>
+<p>foo</p>
+<p>bar</p>
+<ul>
+<li>baz</li>
+</ul>
+</li>
+</ul>
+```
+
+The choice of four spaces is arbitrary. It can be learned, but it is
+not likely to be guessed, and it trips up beginners regularly.
+
+Would it help to adopt a two-space rule? The problem is that such
+a rule, together with the rule allowing up to three spaces of indentation for
+the initial list marker, allows text that is indented *less than* the
+original list marker to be included in the list item. For example,
+`Markdown.pl` parses
+
+``` markdown
+ - one
+
+ two
+```
+
+as a single list item, with `two` a continuation paragraph:
+
+``` html
+<ul>
+<li>
+<p>one</p>
+<p>two</p>
+</li>
+</ul>
+```
+
+and similarly
+
+``` markdown
+> - one
+>
+> two
+```
+
+as
+
+``` html
+<blockquote>
+<ul>
+<li>
+<p>one</p>
+<p>two</p>
+</li>
+</ul>
+</blockquote>
+```
+
+This is extremely unintuitive.
+
+Rather than requiring a fixed indent from the margin, we could require
+a fixed indent (say, two spaces, or even one space) from the list marker (which
+may itself be indented). This proposal would remove the last anomaly
+discussed. Unlike the spec presented above, it would count the following
+as a list item with a subparagraph, even though the paragraph `bar`
+is not indented as far as the first paragraph `foo`:
+
+``` markdown
+ 10. foo
+
+ bar
+```
+
+Arguably this text does read like a list item with `bar` as a subparagraph,
+which may count in favor of the proposal. However, on this proposal indented
+code would have to be indented six spaces after the list marker. And this
+would break a lot of existing Markdown, which has the pattern:
+
+``` markdown
+1. foo
+
+ indented code
+```
+
+where the code is indented eight spaces. The spec above, by contrast, will
+parse this text as expected, since the code block's indentation is measured
+from the beginning of `foo`.
+
+The one case that needs special treatment is a list item that *starts*
+with indented code. How much indentation is required in that case, since
+we don't have a "first paragraph" to measure from? Rule #2 simply stipulates
+that in such cases, we require one space indentation from the list marker
+(and then the normal four spaces for the indented code). This will match the
+four-space rule in cases where the list marker plus its initial indentation
+takes four spaces (a common case), but diverge in other cases.
+
+## Lists
+
+A [list](@) is a sequence of one or more
+list items [of the same type]. The list items
+may be separated by any number of blank lines.
+
+Two list items are [of the same type](@)
+if they begin with a [list marker] of the same type.
+Two list markers are of the
+same type if (a) they are bullet list markers using the same character
+(`-`, `+`, or `*`) or (b) they are ordered list numbers with the same
+delimiter (either `.` or `)`).
+
+A list is an [ordered list](@)
+if its constituent list items begin with
+[ordered list markers], and a
+[bullet list](@) if its constituent list
+items begin with [bullet list markers].
+
+The [start number](@)
+of an [ordered list] is determined by the list number of
+its initial list item. The numbers of subsequent list items are
+disregarded.
+
+A list is [loose](@) if any of its constituent
+list items are separated by blank lines, or if any of its constituent
+list items directly contain two block-level elements with a blank line
+between them. Otherwise a list is [tight](@).
+(The difference in HTML output is that paragraphs in a loose list are
+wrapped in `<p>` tags, while paragraphs in a tight list are not.)
+
+Changing the bullet or ordered list delimiter starts a new list:
+
+```````````````````````````````` example
+- foo
+- bar
++ baz
+.
+<ul>
+<li>foo</li>
+<li>bar</li>
+</ul>
+<ul>
+<li>baz</li>
+</ul>
+````````````````````````````````
+
+
+```````````````````````````````` example
+1. foo
+2. bar
+3) baz
+.
+<ol>
+<li>foo</li>
+<li>bar</li>
+</ol>
+<ol start="3">
+<li>baz</li>
+</ol>
+````````````````````````````````
+
+
+In CommonMark, a list can interrupt a paragraph. That is,
+no blank line is needed to separate a paragraph from a following
+list:
+
+```````````````````````````````` example
+Foo
+- bar
+- baz
+.
+<p>Foo</p>
+<ul>
+<li>bar</li>
+<li>baz</li>
+</ul>
+````````````````````````````````
+
+`Markdown.pl` does not allow this, through fear of triggering a list
+via a numeral in a hard-wrapped line:
+
+``` markdown
+The number of windows in my house is
+14. The number of doors is 6.
+```
+
+Oddly, though, `Markdown.pl` *does* allow a blockquote to
+interrupt a paragraph, even though the same considerations might
+apply.
+
+In CommonMark, we do allow lists to interrupt paragraphs, for
+two reasons. First, it is natural and not uncommon for people
+to start lists without blank lines:
+
+``` markdown
+I need to buy
+- new shoes
+- a coat
+- a plane ticket
+```
+
+Second, we are attracted to a
+
+> [principle of uniformity](@):
+> if a chunk of text has a certain
+> meaning, it will continue to have the same meaning when put into a
+> container block (such as a list item or blockquote).
+
+(Indeed, the spec for [list items] and [block quotes] presupposes
+this principle.) This principle implies that if
+
+``` markdown
+ * I need to buy
+ - new shoes
+ - a coat
+ - a plane ticket
+```
+
+is a list item containing a paragraph followed by a nested sublist,
+as all Markdown implementations agree it is (though the paragraph
+may be rendered without `<p>` tags, since the list is "tight"),
+then
+
+``` markdown
+I need to buy
+- new shoes
+- a coat
+- a plane ticket
+```
+
+by itself should be a paragraph followed by a nested sublist.
+
+Since it is well established Markdown practice to allow lists to
+interrupt paragraphs inside list items, the [principle of
+uniformity] requires us to allow this outside list items as
+well. ([reStructuredText](https://docutils.sourceforge.net/rst.html)
+takes a different approach, requiring blank lines before lists
+even inside other list items.)
+
+In order to solve the problem of unwanted lists in paragraphs with
+hard-wrapped numerals, we allow only lists starting with `1` to
+interrupt paragraphs. Thus,
+
+```````````````````````````````` example
+The number of windows in my house is
+14. The number of doors is 6.
+.
+<p>The number of windows in my house is
+14. The number of doors is 6.</p>
+````````````````````````````````
+
+We may still get an unintended result in cases like
+
+```````````````````````````````` example
+The number of windows in my house is
+1. The number of doors is 6.
+.
+<p>The number of windows in my house is</p>
+<ol>
+<li>The number of doors is 6.</li>
+</ol>
+````````````````````````````````
+
+but this rule should prevent most spurious list captures.
+
+There can be any number of blank lines between items:
+
+```````````````````````````````` example
+- foo
+
+- bar
+
+
+- baz
+.
+<ul>
+<li>
+<p>foo</p>
+</li>
+<li>
+<p>bar</p>
+</li>
+<li>
+<p>baz</p>
+</li>
+</ul>
+````````````````````````````````
+
+```````````````````````````````` example
+- foo
+ - bar
+ - baz
+
+
+ bim
+.
+<ul>
+<li>foo
+<ul>
+<li>bar
+<ul>
+<li>
+<p>baz</p>
+<p>bim</p>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+````````````````````````````````
+
+
+To separate consecutive lists of the same type, or to separate a
+list from an indented code block that would otherwise be parsed
+as a subparagraph of the final list item, you can insert a blank HTML
+comment:
+
+```````````````````````````````` example
+- foo
+- bar
+
+<!-- -->
+
+- baz
+- bim
+.
+<ul>
+<li>foo</li>
+<li>bar</li>
+</ul>
+<!-- -->
+<ul>
+<li>baz</li>
+<li>bim</li>
+</ul>
+````````````````````````````````
+
+
+```````````````````````````````` example
+- foo
+
+ notcode
+
+- foo
+
+<!-- -->
+
+ code
+.
+<ul>
+<li>
+<p>foo</p>
+<p>notcode</p>
+</li>
+<li>
+<p>foo</p>
+</li>
+</ul>
+<!-- -->
+<pre><code>code
+</code></pre>
+````````````````````````````````
+
+
+List items need not be indented to the same level. The following
+list items will be treated as items at the same list level,
+since none is indented enough to belong to the previous list
+item:
+
+```````````````````````````````` example
+- a
+ - b
+ - c
+ - d
+ - e
+ - f
+- g
+.
+<ul>
+<li>a</li>
+<li>b</li>
+<li>c</li>
+<li>d</li>
+<li>e</li>
+<li>f</li>
+<li>g</li>
+</ul>
+````````````````````````````````
+
+
+```````````````````````````````` example
+1. a
+
+ 2. b
+
+ 3. c
+.
+<ol>
+<li>
+<p>a</p>
+</li>
+<li>
+<p>b</p>
+</li>
+<li>
+<p>c</p>
+</li>
+</ol>
+````````````````````````````````
+
+Note, however, that list items may not be preceded by more than
+three spaces of indentation. Here `- e` is treated as a paragraph continuation
+line, because it is indented more than three spaces:
+
+```````````````````````````````` example
+- a
+ - b
+ - c
+ - d
+ - e
+.
+<ul>
+<li>a</li>
+<li>b</li>
+<li>c</li>
+<li>d
+- e</li>
+</ul>
+````````````````````````````````
+
+And here, `3. c` is treated as in indented code block,
+because it is indented four spaces and preceded by a
+blank line.
+
+```````````````````````````````` example
+1. a
+
+ 2. b
+
+ 3. c
+.
+<ol>
+<li>
+<p>a</p>
+</li>
+<li>
+<p>b</p>
+</li>
+</ol>
+<pre><code>3. c
+</code></pre>
+````````````````````````````````
+
+
+This is a loose list, because there is a blank line between
+two of the list items:
+
+```````````````````````````````` example
+- a
+- b
+
+- c
+.
+<ul>
+<li>
+<p>a</p>
+</li>
+<li>
+<p>b</p>
+</li>
+<li>
+<p>c</p>
+</li>
+</ul>
+````````````````````````````````
+
+
+So is this, with a empty second item:
+
+```````````````````````````````` example
+* a
+*
+
+* c
+.
+<ul>
+<li>
+<p>a</p>
+</li>
+<li></li>
+<li>
+<p>c</p>
+</li>
+</ul>
+````````````````````````````````
+
+
+These are loose lists, even though there are no blank lines between the items,
+because one of the items directly contains two block-level elements
+with a blank line between them:
+
+```````````````````````````````` example
+- a
+- b
+
+ c
+- d
+.
+<ul>
+<li>
+<p>a</p>
+</li>
+<li>
+<p>b</p>
+<p>c</p>
+</li>
+<li>
+<p>d</p>
+</li>
+</ul>
+````````````````````````````````
+
+
+```````````````````````````````` example
+- a
+- b
+
+ [ref]: /url
+- d
+.
+<ul>
+<li>
+<p>a</p>
+</li>
+<li>
+<p>b</p>
+</li>
+<li>
+<p>d</p>
+</li>
+</ul>
+````````````````````````````````
+
+
+This is a tight list, because the blank lines are in a code block:
+
+```````````````````````````````` example
+- a
+- ```
+ b
+
+
+ ```
+- c
+.
+<ul>
+<li>a</li>
+<li>
+<pre><code>b
+
+
+</code></pre>
+</li>
+<li>c</li>
+</ul>
+````````````````````````````````
+
+
+This is a tight list, because the blank line is between two
+paragraphs of a sublist. So the sublist is loose while
+the outer list is tight:
+
+```````````````````````````````` example
+- a
+ - b
+
+ c
+- d
+.
+<ul>
+<li>a
+<ul>
+<li>
+<p>b</p>
+<p>c</p>
+</li>
+</ul>
+</li>
+<li>d</li>
+</ul>
+````````````````````````````````
+
+
+This is a tight list, because the blank line is inside the
+block quote:
+
+```````````````````````````````` example
+* a
+ > b
+ >
+* c
+.
+<ul>
+<li>a
+<blockquote>
+<p>b</p>
+</blockquote>
+</li>
+<li>c</li>
+</ul>
+````````````````````````````````
+
+
+This list is tight, because the consecutive block elements
+are not separated by blank lines:
+
+```````````````````````````````` example
+- a
+ > b
+ ```
+ c
+ ```
+- d
+.
+<ul>
+<li>a
+<blockquote>
+<p>b</p>
+</blockquote>
+<pre><code>c
+</code></pre>
+</li>
+<li>d</li>
+</ul>
+````````````````````````````````
+
+
+A single-paragraph list is tight:
+
+```````````````````````````````` example
+- a
+.
+<ul>
+<li>a</li>
+</ul>
+````````````````````````````````
+
+
+```````````````````````````````` example
+- a
+ - b
+.
+<ul>
+<li>a
+<ul>
+<li>b</li>
+</ul>
+</li>
+</ul>
+````````````````````````````````
+
+
+This list is loose, because of the blank line between the
+two block elements in the list item:
+
+```````````````````````````````` example
+1. ```
+ foo
+ ```
+
+ bar
+.
+<ol>
+<li>
+<pre><code>foo
+</code></pre>
+<p>bar</p>
+</li>
+</ol>
+````````````````````````````````
+
+
+Here the outer list is loose, the inner list tight:
+
+```````````````````````````````` example
+* foo
+ * bar
+
+ baz
+.
+<ul>
+<li>
+<p>foo</p>
+<ul>
+<li>bar</li>
+</ul>
+<p>baz</p>
+</li>
+</ul>
+````````````````````````````````
+
+
+```````````````````````````````` example
+- a
+ - b
+ - c
+
+- d
+ - e
+ - f
+.
+<ul>
+<li>
+<p>a</p>
+<ul>
+<li>b</li>
+<li>c</li>
+</ul>
+</li>
+<li>
+<p>d</p>
+<ul>
+<li>e</li>
+<li>f</li>
+</ul>
+</li>
+</ul>
+````````````````````````````````
+
+
+# Inlines
+
+Inlines are parsed sequentially from the beginning of the character
+stream to the end (left to right, in left-to-right languages).
+Thus, for example, in
+
+```````````````````````````````` example
+`hi`lo`
+.
+<p><code>hi</code>lo`</p>
+````````````````````````````````
+
+`hi` is parsed as code, leaving the backtick at the end as a literal
+backtick.
+
+
+
+## Code spans
+
+A [backtick string](@)
+is a string of one or more backtick characters (`` ` ``) that is neither
+preceded nor followed by a backtick.
+
+A [code span](@) begins with a backtick string and ends with
+a backtick string of equal length. The contents of the code span are
+the characters between these two backtick strings, normalized in the
+following ways:
+
+- First, [line endings] are converted to [spaces].
+- If the resulting string both begins *and* ends with a [space]
+ character, but does not consist entirely of [space]
+ characters, a single [space] character is removed from the
+ front and back. This allows you to include code that begins
+ or ends with backtick characters, which must be separated by
+ whitespace from the opening or closing backtick strings.
+
+This is a simple code span:
+
+```````````````````````````````` example
+`foo`
+.
+<p><code>foo</code></p>
+````````````````````````````````
+
+
+Here two backticks are used, because the code contains a backtick.
+This example also illustrates stripping of a single leading and
+trailing space:
+
+```````````````````````````````` example
+`` foo ` bar ``
+.
+<p><code>foo ` bar</code></p>
+````````````````````````````````
+
+
+This example shows the motivation for stripping leading and trailing
+spaces:
+
+```````````````````````````````` example
+` `` `
+.
+<p><code>``</code></p>
+````````````````````````````````
+
+Note that only *one* space is stripped:
+
+```````````````````````````````` example
+` `` `
+.
+<p><code> `` </code></p>
+````````````````````````````````
+
+The stripping only happens if the space is on both
+sides of the string:
+
+```````````````````````````````` example
+` a`
+.
+<p><code> a</code></p>
+````````````````````````````````
+
+Only [spaces], and not [unicode whitespace] in general, are
+stripped in this way:
+
+```````````````````````````````` example
+` b `
+.
+<p><code> b </code></p>
+````````````````````````````````
+
+No stripping occurs if the code span contains only spaces:
+
+```````````````````````````````` example
+` `
+` `
+.
+<p><code> </code>
+<code> </code></p>
+````````````````````````````````
+
+
+[Line endings] are treated like spaces:
+
+```````````````````````````````` example
+``
+foo
+bar
+baz
+``
+.
+<p><code>foo bar baz</code></p>
+````````````````````````````````
+
+```````````````````````````````` example
+``
+foo
+``
+.
+<p><code>foo </code></p>
+````````````````````````````````
+
+
+Interior spaces are not collapsed:
+
+```````````````````````````````` example
+`foo bar
+baz`
+.
+<p><code>foo bar baz</code></p>
+````````````````````````````````
+
+Note that browsers will typically collapse consecutive spaces
+when rendering `<code>` elements, so it is recommended that
+the following CSS be used:
+
+ code{white-space: pre-wrap;}
+
+
+Note that backslash escapes do not work in code spans. All backslashes
+are treated literally:
+
+```````````````````````````````` example
+`foo\`bar`
+.
+<p><code>foo\</code>bar`</p>
+````````````````````````````````
+
+
+Backslash escapes are never needed, because one can always choose a
+string of *n* backtick characters as delimiters, where the code does
+not contain any strings of exactly *n* backtick characters.
+
+```````````````````````````````` example
+``foo`bar``
+.
+<p><code>foo`bar</code></p>
+````````````````````````````````
+
+```````````````````````````````` example
+` foo `` bar `
+.
+<p><code>foo `` bar</code></p>
+````````````````````````````````
+
+
+Code span backticks have higher precedence than any other inline
+constructs except HTML tags and autolinks. Thus, for example, this is
+not parsed as emphasized text, since the second `*` is part of a code
+span:
+
+```````````````````````````````` example
+*foo`*`
+.
+<p>*foo<code>*</code></p>
+````````````````````````````````
+
+
+And this is not parsed as a link:
+
+```````````````````````````````` example
+[not a `link](/foo`)
+.
+<p>[not a <code>link](/foo</code>)</p>
+````````````````````````````````
+
+
+Code spans, HTML tags, and autolinks have the same precedence.
+Thus, this is code:
+
+```````````````````````````````` example
+`<a href="`">`
+.
+<p><code><a href="</code>">`</p>
+````````````````````````````````
+
+
+But this is an HTML tag:
+
+```````````````````````````````` example
+<a href="`">`
+.
+<p><a href="`">`</p>
+````````````````````````````````
+
+
+And this is code:
+
+```````````````````````````````` example
+`<https://foo.bar.`baz>`
+.
+<p><code><https://foo.bar.</code>baz>`</p>
+````````````````````````````````
+
+
+But this is an autolink:
+
+```````````````````````````````` example
+<https://foo.bar.`baz>`
+.
+<p><a href="https://foo.bar.%60baz">https://foo.bar.`baz</a>`</p>
+````````````````````````````````
+
+
+When a backtick string is not closed by a matching backtick string,
+we just have literal backticks:
+
+```````````````````````````````` example
+```foo``
+.
+<p>```foo``</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+`foo
+.
+<p>`foo</p>
+````````````````````````````````
+
+The following case also illustrates the need for opening and
+closing backtick strings to be equal in length:
+
+```````````````````````````````` example
+`foo``bar``
+.
+<p>`foo<code>bar</code></p>
+````````````````````````````````
+
+
+## Emphasis and strong emphasis
+
+John Gruber's original [Markdown syntax
+description](https://daringfireball.net/projects/markdown/syntax#em) says:
+
+> Markdown treats asterisks (`*`) and underscores (`_`) as indicators of
+> emphasis. Text wrapped with one `*` or `_` will be wrapped with an HTML
+> `<em>` tag; double `*`'s or `_`'s will be wrapped with an HTML `<strong>`
+> tag.
+
+This is enough for most users, but these rules leave much undecided,
+especially when it comes to nested emphasis. The original
+`Markdown.pl` test suite makes it clear that triple `***` and
+`___` delimiters can be used for strong emphasis, and most
+implementations have also allowed the following patterns:
+
+``` markdown
+***strong emph***
+***strong** in emph*
+***emph* in strong**
+**in strong *emph***
+*in emph **strong***
+```
+
+The following patterns are less widely supported, but the intent
+is clear and they are useful (especially in contexts like bibliography
+entries):
+
+``` markdown
+*emph *with emph* in it*
+**strong **with strong** in it**
+```
+
+Many implementations have also restricted intraword emphasis to
+the `*` forms, to avoid unwanted emphasis in words containing
+internal underscores. (It is best practice to put these in code
+spans, but users often do not.)
+
+``` markdown
+internal emphasis: foo*bar*baz
+no emphasis: foo_bar_baz
+```
+
+The rules given below capture all of these patterns, while allowing
+for efficient parsing strategies that do not backtrack.
+
+First, some definitions. A [delimiter run](@) is either
+a sequence of one or more `*` characters that is not preceded or
+followed by a non-backslash-escaped `*` character, or a sequence
+of one or more `_` characters that is not preceded or followed by
+a non-backslash-escaped `_` character.
+
+A [left-flanking delimiter run](@) is
+a [delimiter run] that is (1) not followed by [Unicode whitespace],
+and either (2a) not followed by a [Unicode punctuation character], or
+(2b) followed by a [Unicode punctuation character] and
+preceded by [Unicode whitespace] or a [Unicode punctuation character].
+For purposes of this definition, the beginning and the end of
+the line count as Unicode whitespace.
+
+A [right-flanking delimiter run](@) is
+a [delimiter run] that is (1) not preceded by [Unicode whitespace],
+and either (2a) not preceded by a [Unicode punctuation character], or
+(2b) preceded by a [Unicode punctuation character] and
+followed by [Unicode whitespace] or a [Unicode punctuation character].
+For purposes of this definition, the beginning and the end of
+the line count as Unicode whitespace.
+
+Here are some examples of delimiter runs.
+
+ - left-flanking but not right-flanking:
+
+ ```
+ ***abc
+ _abc
+ **"abc"
+ _"abc"
+ ```
+
+ - right-flanking but not left-flanking:
+
+ ```
+ abc***
+ abc_
+ "abc"**
+ "abc"_
+ ```
+
+ - Both left and right-flanking:
+
+ ```
+ abc***def
+ "abc"_"def"
+ ```
+
+ - Neither left nor right-flanking:
+
+ ```
+ abc *** def
+ a _ b
+ ```
+
+(The idea of distinguishing left-flanking and right-flanking
+delimiter runs based on the character before and the character
+after comes from Roopesh Chander's
+[vfmd](https://web.archive.org/web/20220608143320/http://www.vfmd.org/vfmd-spec/specification/#procedure-for-identifying-emphasis-tags).
+vfmd uses the terminology "emphasis indicator string" instead of "delimiter
+run," and its rules for distinguishing left- and right-flanking runs
+are a bit more complex than the ones given here.)
+
+The following rules define emphasis and strong emphasis:
+
+1. A single `*` character [can open emphasis](@)
+ iff (if and only if) it is part of a [left-flanking delimiter run].
+
+2. A single `_` character [can open emphasis] iff
+ it is part of a [left-flanking delimiter run]
+ and either (a) not part of a [right-flanking delimiter run]
+ or (b) part of a [right-flanking delimiter run]
+ preceded by a [Unicode punctuation character].
+
+3. A single `*` character [can close emphasis](@)
+ iff it is part of a [right-flanking delimiter run].
+
+4. A single `_` character [can close emphasis] iff
+ it is part of a [right-flanking delimiter run]
+ and either (a) not part of a [left-flanking delimiter run]
+ or (b) part of a [left-flanking delimiter run]
+ followed by a [Unicode punctuation character].
+
+5. A double `**` [can open strong emphasis](@)
+ iff it is part of a [left-flanking delimiter run].
+
+6. A double `__` [can open strong emphasis] iff
+ it is part of a [left-flanking delimiter run]
+ and either (a) not part of a [right-flanking delimiter run]
+ or (b) part of a [right-flanking delimiter run]
+ preceded by a [Unicode punctuation character].
+
+7. A double `**` [can close strong emphasis](@)
+ iff it is part of a [right-flanking delimiter run].
+
+8. A double `__` [can close strong emphasis] iff
+ it is part of a [right-flanking delimiter run]
+ and either (a) not part of a [left-flanking delimiter run]
+ or (b) part of a [left-flanking delimiter run]
+ followed by a [Unicode punctuation character].
+
+9. Emphasis begins with a delimiter that [can open emphasis] and ends
+ with a delimiter that [can close emphasis], and that uses the same
+ character (`_` or `*`) as the opening delimiter. The
+ opening and closing delimiters must belong to separate
+ [delimiter runs]. If one of the delimiters can both
+ open and close emphasis, then the sum of the lengths of the
+ delimiter runs containing the opening and closing delimiters
+ must not be a multiple of 3 unless both lengths are
+ multiples of 3.
+
+10. Strong emphasis begins with a delimiter that
+ [can open strong emphasis] and ends with a delimiter that
+ [can close strong emphasis], and that uses the same character
+ (`_` or `*`) as the opening delimiter. The
+ opening and closing delimiters must belong to separate
+ [delimiter runs]. If one of the delimiters can both open
+ and close strong emphasis, then the sum of the lengths of
+ the delimiter runs containing the opening and closing
+ delimiters must not be a multiple of 3 unless both lengths
+ are multiples of 3.
+
+11. A literal `*` character cannot occur at the beginning or end of
+ `*`-delimited emphasis or `**`-delimited strong emphasis, unless it
+ is backslash-escaped.
+
+12. A literal `_` character cannot occur at the beginning or end of
+ `_`-delimited emphasis or `__`-delimited strong emphasis, unless it
+ is backslash-escaped.
+
+Where rules 1--12 above are compatible with multiple parsings,
+the following principles resolve ambiguity:
+
+13. The number of nestings should be minimized. Thus, for example,
+ an interpretation `<strong>...</strong>` is always preferred to
+ `<em><em>...</em></em>`.
+
+14. An interpretation `<em><strong>...</strong></em>` is always
+ preferred to `<strong><em>...</em></strong>`.
+
+15. When two potential emphasis or strong emphasis spans overlap,
+ so that the second begins before the first ends and ends after
+ the first ends, the first takes precedence. Thus, for example,
+ `*foo _bar* baz_` is parsed as `<em>foo _bar</em> baz_` rather
+ than `*foo <em>bar* baz</em>`.
+
+16. When there are two potential emphasis or strong emphasis spans
+ with the same closing delimiter, the shorter one (the one that
+ opens later) takes precedence. Thus, for example,
+ `**foo **bar baz**` is parsed as `**foo <strong>bar baz</strong>`
+ rather than `<strong>foo **bar baz</strong>`.
+
+17. Inline code spans, links, images, and HTML tags group more tightly
+ than emphasis. So, when there is a choice between an interpretation
+ that contains one of these elements and one that does not, the
+ former always wins. Thus, for example, `*[foo*](bar)` is
+ parsed as `*<a href="bar">foo*</a>` rather than as
+ `<em>[foo</em>](bar)`.
+
+These rules can be illustrated through a series of examples.
+
+Rule 1:
+
+```````````````````````````````` example
+*foo bar*
+.
+<p><em>foo bar</em></p>
+````````````````````````````````
+
+
+This is not emphasis, because the opening `*` is followed by
+whitespace, and hence not part of a [left-flanking delimiter run]:
+
+```````````````````````````````` example
+a * foo bar*
+.
+<p>a * foo bar*</p>
+````````````````````````````````
+
+
+This is not emphasis, because the opening `*` is preceded
+by an alphanumeric and followed by punctuation, and hence
+not part of a [left-flanking delimiter run]:
+
+```````````````````````````````` example
+a*"foo"*
+.
+<p>a*"foo"*</p>
+````````````````````````````````
+
+
+Unicode nonbreaking spaces count as whitespace, too:
+
+```````````````````````````````` example
+* a *
+.
+<p>* a *</p>
+````````````````````````````````
+
+
+Unicode symbols count as punctuation, too:
+
+```````````````````````````````` example
+*$*alpha.
+
+*£*bravo.
+
+*€*charlie.
+.
+<p>*$*alpha.</p>
+<p>*£*bravo.</p>
+<p>*€*charlie.</p>
+````````````````````````````````
+
+
+Intraword emphasis with `*` is permitted:
+
+```````````````````````````````` example
+foo*bar*
+.
+<p>foo<em>bar</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+5*6*78
+.
+<p>5<em>6</em>78</p>
+````````````````````````````````
+
+
+Rule 2:
+
+```````````````````````````````` example
+_foo bar_
+.
+<p><em>foo bar</em></p>
+````````````````````````````````
+
+
+This is not emphasis, because the opening `_` is followed by
+whitespace:
+
+```````````````````````````````` example
+_ foo bar_
+.
+<p>_ foo bar_</p>
+````````````````````````````````
+
+
+This is not emphasis, because the opening `_` is preceded
+by an alphanumeric and followed by punctuation:
+
+```````````````````````````````` example
+a_"foo"_
+.
+<p>a_"foo"_</p>
+````````````````````````````````
+
+
+Emphasis with `_` is not allowed inside words:
+
+```````````````````````````````` example
+foo_bar_
+.
+<p>foo_bar_</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+5_6_78
+.
+<p>5_6_78</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+пристаням_стремятся_
+.
+<p>пристаням_стремятся_</p>
+````````````````````````````````
+
+
+Here `_` does not generate emphasis, because the first delimiter run
+is right-flanking and the second left-flanking:
+
+```````````````````````````````` example
+aa_"bb"_cc
+.
+<p>aa_"bb"_cc</p>
+````````````````````````````````
+
+
+This is emphasis, even though the opening delimiter is
+both left- and right-flanking, because it is preceded by
+punctuation:
+
+```````````````````````````````` example
+foo-_(bar)_
+.
+<p>foo-<em>(bar)</em></p>
+````````````````````````````````
+
+
+Rule 3:
+
+This is not emphasis, because the closing delimiter does
+not match the opening delimiter:
+
+```````````````````````````````` example
+_foo*
+.
+<p>_foo*</p>
+````````````````````````````````
+
+
+This is not emphasis, because the closing `*` is preceded by
+whitespace:
+
+```````````````````````````````` example
+*foo bar *
+.
+<p>*foo bar *</p>
+````````````````````````````````
+
+
+A line ending also counts as whitespace:
+
+```````````````````````````````` example
+*foo bar
+*
+.
+<p>*foo bar
+*</p>
+````````````````````````````````
+
+
+This is not emphasis, because the second `*` is
+preceded by punctuation and followed by an alphanumeric
+(hence it is not part of a [right-flanking delimiter run]:
+
+```````````````````````````````` example
+*(*foo)
+.
+<p>*(*foo)</p>
+````````````````````````````````
+
+
+The point of this restriction is more easily appreciated
+with this example:
+
+```````````````````````````````` example
+*(*foo*)*
+.
+<p><em>(<em>foo</em>)</em></p>
+````````````````````````````````
+
+
+Intraword emphasis with `*` is allowed:
+
+```````````````````````````````` example
+*foo*bar
+.
+<p><em>foo</em>bar</p>
+````````````````````````````````
+
+
+
+Rule 4:
+
+This is not emphasis, because the closing `_` is preceded by
+whitespace:
+
+```````````````````````````````` example
+_foo bar _
+.
+<p>_foo bar _</p>
+````````````````````````````````
+
+
+This is not emphasis, because the second `_` is
+preceded by punctuation and followed by an alphanumeric:
+
+```````````````````````````````` example
+_(_foo)
+.
+<p>_(_foo)</p>
+````````````````````````````````
+
+
+This is emphasis within emphasis:
+
+```````````````````````````````` example
+_(_foo_)_
+.
+<p><em>(<em>foo</em>)</em></p>
+````````````````````````````````
+
+
+Intraword emphasis is disallowed for `_`:
+
+```````````````````````````````` example
+_foo_bar
+.
+<p>_foo_bar</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+_пристаням_стремятся
+.
+<p>_пристаням_стремятся</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+_foo_bar_baz_
+.
+<p><em>foo_bar_baz</em></p>
+````````````````````````````````
+
+
+This is emphasis, even though the closing delimiter is
+both left- and right-flanking, because it is followed by
+punctuation:
+
+```````````````````````````````` example
+_(bar)_.
+.
+<p><em>(bar)</em>.</p>
+````````````````````````````````
+
+
+Rule 5:
+
+```````````````````````````````` example
+**foo bar**
+.
+<p><strong>foo bar</strong></p>
+````````````````````````````````
+
+
+This is not strong emphasis, because the opening delimiter is
+followed by whitespace:
+
+```````````````````````````````` example
+** foo bar**
+.
+<p>** foo bar**</p>
+````````````````````````````````
+
+
+This is not strong emphasis, because the opening `**` is preceded
+by an alphanumeric and followed by punctuation, and hence
+not part of a [left-flanking delimiter run]:
+
+```````````````````````````````` example
+a**"foo"**
+.
+<p>a**"foo"**</p>
+````````````````````````````````
+
+
+Intraword strong emphasis with `**` is permitted:
+
+```````````````````````````````` example
+foo**bar**
+.
+<p>foo<strong>bar</strong></p>
+````````````````````````````````
+
+
+Rule 6:
+
+```````````````````````````````` example
+__foo bar__
+.
+<p><strong>foo bar</strong></p>
+````````````````````````````````
+
+
+This is not strong emphasis, because the opening delimiter is
+followed by whitespace:
+
+```````````````````````````````` example
+__ foo bar__
+.
+<p>__ foo bar__</p>
+````````````````````````````````
+
+
+A line ending counts as whitespace:
+```````````````````````````````` example
+__
+foo bar__
+.
+<p>__
+foo bar__</p>
+````````````````````````````````
+
+
+This is not strong emphasis, because the opening `__` is preceded
+by an alphanumeric and followed by punctuation:
+
+```````````````````````````````` example
+a__"foo"__
+.
+<p>a__"foo"__</p>
+````````````````````````````````
+
+
+Intraword strong emphasis is forbidden with `__`:
+
+```````````````````````````````` example
+foo__bar__
+.
+<p>foo__bar__</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+5__6__78
+.
+<p>5__6__78</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+пристаням__стремятся__
+.
+<p>пристаням__стремятся__</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+__foo, __bar__, baz__
+.
+<p><strong>foo, <strong>bar</strong>, baz</strong></p>
+````````````````````````````````
+
+
+This is strong emphasis, even though the opening delimiter is
+both left- and right-flanking, because it is preceded by
+punctuation:
+
+```````````````````````````````` example
+foo-__(bar)__
+.
+<p>foo-<strong>(bar)</strong></p>
+````````````````````````````````
+
+
+
+Rule 7:
+
+This is not strong emphasis, because the closing delimiter is preceded
+by whitespace:
+
+```````````````````````````````` example
+**foo bar **
+.
+<p>**foo bar **</p>
+````````````````````````````````
+
+
+(Nor can it be interpreted as an emphasized `*foo bar *`, because of
+Rule 11.)
+
+This is not strong emphasis, because the second `**` is
+preceded by punctuation and followed by an alphanumeric:
+
+```````````````````````````````` example
+**(**foo)
+.
+<p>**(**foo)</p>
+````````````````````````````````
+
+
+The point of this restriction is more easily appreciated
+with these examples:
+
+```````````````````````````````` example
+*(**foo**)*
+.
+<p><em>(<strong>foo</strong>)</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+**Gomphocarpus (*Gomphocarpus physocarpus*, syn.
+*Asclepias physocarpa*)**
+.
+<p><strong>Gomphocarpus (<em>Gomphocarpus physocarpus</em>, syn.
+<em>Asclepias physocarpa</em>)</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+**foo "*bar*" foo**
+.
+<p><strong>foo "<em>bar</em>" foo</strong></p>
+````````````````````````````````
+
+
+Intraword emphasis:
+
+```````````````````````````````` example
+**foo**bar
+.
+<p><strong>foo</strong>bar</p>
+````````````````````````````````
+
+
+Rule 8:
+
+This is not strong emphasis, because the closing delimiter is
+preceded by whitespace:
+
+```````````````````````````````` example
+__foo bar __
+.
+<p>__foo bar __</p>
+````````````````````````````````
+
+
+This is not strong emphasis, because the second `__` is
+preceded by punctuation and followed by an alphanumeric:
+
+```````````````````````````````` example
+__(__foo)
+.
+<p>__(__foo)</p>
+````````````````````````````````
+
+
+The point of this restriction is more easily appreciated
+with this example:
+
+```````````````````````````````` example
+_(__foo__)_
+.
+<p><em>(<strong>foo</strong>)</em></p>
+````````````````````````````````
+
+
+Intraword strong emphasis is forbidden with `__`:
+
+```````````````````````````````` example
+__foo__bar
+.
+<p>__foo__bar</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+__пристаням__стремятся
+.
+<p>__пристаням__стремятся</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+__foo__bar__baz__
+.
+<p><strong>foo__bar__baz</strong></p>
+````````````````````````````````
+
+
+This is strong emphasis, even though the closing delimiter is
+both left- and right-flanking, because it is followed by
+punctuation:
+
+```````````````````````````````` example
+__(bar)__.
+.
+<p><strong>(bar)</strong>.</p>
+````````````````````````````````
+
+
+Rule 9:
+
+Any nonempty sequence of inline elements can be the contents of an
+emphasized span.
+
+```````````````````````````````` example
+*foo [bar](/url)*
+.
+<p><em>foo <a href="/url">bar</a></em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*foo
+bar*
+.
+<p><em>foo
+bar</em></p>
+````````````````````````````````
+
+
+In particular, emphasis and strong emphasis can be nested
+inside emphasis:
+
+```````````````````````````````` example
+_foo __bar__ baz_
+.
+<p><em>foo <strong>bar</strong> baz</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+_foo _bar_ baz_
+.
+<p><em>foo <em>bar</em> baz</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+__foo_ bar_
+.
+<p><em><em>foo</em> bar</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*foo *bar**
+.
+<p><em>foo <em>bar</em></em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*foo **bar** baz*
+.
+<p><em>foo <strong>bar</strong> baz</em></p>
+````````````````````````````````
+
+```````````````````````````````` example
+*foo**bar**baz*
+.
+<p><em>foo<strong>bar</strong>baz</em></p>
+````````````````````````````````
+
+Note that in the preceding case, the interpretation
+
+``` markdown
+<p><em>foo</em><em>bar<em></em>baz</em></p>
+```
+
+
+is precluded by the condition that a delimiter that
+can both open and close (like the `*` after `foo`)
+cannot form emphasis if the sum of the lengths of
+the delimiter runs containing the opening and
+closing delimiters is a multiple of 3 unless
+both lengths are multiples of 3.
+
+
+For the same reason, we don't get two consecutive
+emphasis sections in this example:
+
+```````````````````````````````` example
+*foo**bar*
+.
+<p><em>foo**bar</em></p>
+````````````````````````````````
+
+
+The same condition ensures that the following
+cases are all strong emphasis nested inside
+emphasis, even when the interior whitespace is
+omitted:
+
+
+```````````````````````````````` example
+***foo** bar*
+.
+<p><em><strong>foo</strong> bar</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*foo **bar***
+.
+<p><em>foo <strong>bar</strong></em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*foo**bar***
+.
+<p><em>foo<strong>bar</strong></em></p>
+````````````````````````````````
+
+
+When the lengths of the interior closing and opening
+delimiter runs are *both* multiples of 3, though,
+they can match to create emphasis:
+
+```````````````````````````````` example
+foo***bar***baz
+.
+<p>foo<em><strong>bar</strong></em>baz</p>
+````````````````````````````````
+
+```````````````````````````````` example
+foo******bar*********baz
+.
+<p>foo<strong><strong><strong>bar</strong></strong></strong>***baz</p>
+````````````````````````````````
+
+
+Indefinite levels of nesting are possible:
+
+```````````````````````````````` example
+*foo **bar *baz* bim** bop*
+.
+<p><em>foo <strong>bar <em>baz</em> bim</strong> bop</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*foo [*bar*](/url)*
+.
+<p><em>foo <a href="/url"><em>bar</em></a></em></p>
+````````````````````````````````
+
+
+There can be no empty emphasis or strong emphasis:
+
+```````````````````````````````` example
+** is not an empty emphasis
+.
+<p>** is not an empty emphasis</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+**** is not an empty strong emphasis
+.
+<p>**** is not an empty strong emphasis</p>
+````````````````````````````````
+
+
+
+Rule 10:
+
+Any nonempty sequence of inline elements can be the contents of an
+strongly emphasized span.
+
+```````````````````````````````` example
+**foo [bar](/url)**
+.
+<p><strong>foo <a href="/url">bar</a></strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+**foo
+bar**
+.
+<p><strong>foo
+bar</strong></p>
+````````````````````````````````
+
+
+In particular, emphasis and strong emphasis can be nested
+inside strong emphasis:
+
+```````````````````````````````` example
+__foo _bar_ baz__
+.
+<p><strong>foo <em>bar</em> baz</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+__foo __bar__ baz__
+.
+<p><strong>foo <strong>bar</strong> baz</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+____foo__ bar__
+.
+<p><strong><strong>foo</strong> bar</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+**foo **bar****
+.
+<p><strong>foo <strong>bar</strong></strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+**foo *bar* baz**
+.
+<p><strong>foo <em>bar</em> baz</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+**foo*bar*baz**
+.
+<p><strong>foo<em>bar</em>baz</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+***foo* bar**
+.
+<p><strong><em>foo</em> bar</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+**foo *bar***
+.
+<p><strong>foo <em>bar</em></strong></p>
+````````````````````````````````
+
+
+Indefinite levels of nesting are possible:
+
+```````````````````````````````` example
+**foo *bar **baz**
+bim* bop**
+.
+<p><strong>foo <em>bar <strong>baz</strong>
+bim</em> bop</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+**foo [*bar*](/url)**
+.
+<p><strong>foo <a href="/url"><em>bar</em></a></strong></p>
+````````````````````````````````
+
+
+There can be no empty emphasis or strong emphasis:
+
+```````````````````````````````` example
+__ is not an empty emphasis
+.
+<p>__ is not an empty emphasis</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+____ is not an empty strong emphasis
+.
+<p>____ is not an empty strong emphasis</p>
+````````````````````````````````
+
+
+
+Rule 11:
+
+```````````````````````````````` example
+foo ***
+.
+<p>foo ***</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo *\**
+.
+<p>foo <em>*</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo *_*
+.
+<p>foo <em>_</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo *****
+.
+<p>foo *****</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo **\***
+.
+<p>foo <strong>*</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo **_**
+.
+<p>foo <strong>_</strong></p>
+````````````````````````````````
+
+
+Note that when delimiters do not match evenly, Rule 11 determines
+that the excess literal `*` characters will appear outside of the
+emphasis, rather than inside it:
+
+```````````````````````````````` example
+**foo*
+.
+<p>*<em>foo</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*foo**
+.
+<p><em>foo</em>*</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+***foo**
+.
+<p>*<strong>foo</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+****foo*
+.
+<p>***<em>foo</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+**foo***
+.
+<p><strong>foo</strong>*</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*foo****
+.
+<p><em>foo</em>***</p>
+````````````````````````````````
+
+
+
+Rule 12:
+
+```````````````````````````````` example
+foo ___
+.
+<p>foo ___</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo _\__
+.
+<p>foo <em>_</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo _*_
+.
+<p>foo <em>*</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo _____
+.
+<p>foo _____</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo __\___
+.
+<p>foo <strong>_</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo __*__
+.
+<p>foo <strong>*</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+__foo_
+.
+<p>_<em>foo</em></p>
+````````````````````````````````
+
+
+Note that when delimiters do not match evenly, Rule 12 determines
+that the excess literal `_` characters will appear outside of the
+emphasis, rather than inside it:
+
+```````````````````````````````` example
+_foo__
+.
+<p><em>foo</em>_</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+___foo__
+.
+<p>_<strong>foo</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+____foo_
+.
+<p>___<em>foo</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+__foo___
+.
+<p><strong>foo</strong>_</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+_foo____
+.
+<p><em>foo</em>___</p>
+````````````````````````````````
+
+
+Rule 13 implies that if you want emphasis nested directly inside
+emphasis, you must use different delimiters:
+
+```````````````````````````````` example
+**foo**
+.
+<p><strong>foo</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*_foo_*
+.
+<p><em><em>foo</em></em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+__foo__
+.
+<p><strong>foo</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+_*foo*_
+.
+<p><em><em>foo</em></em></p>
+````````````````````````````````
+
+
+However, strong emphasis within strong emphasis is possible without
+switching delimiters:
+
+```````````````````````````````` example
+****foo****
+.
+<p><strong><strong>foo</strong></strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+____foo____
+.
+<p><strong><strong>foo</strong></strong></p>
+````````````````````````````````
+
+
+
+Rule 13 can be applied to arbitrarily long sequences of
+delimiters:
+
+```````````````````````````````` example
+******foo******
+.
+<p><strong><strong><strong>foo</strong></strong></strong></p>
+````````````````````````````````
+
+
+Rule 14:
+
+```````````````````````````````` example
+***foo***
+.
+<p><em><strong>foo</strong></em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+_____foo_____
+.
+<p><em><strong><strong>foo</strong></strong></em></p>
+````````````````````````````````
+
+
+Rule 15:
+
+```````````````````````````````` example
+*foo _bar* baz_
+.
+<p><em>foo _bar</em> baz_</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*foo __bar *baz bim__ bam*
+.
+<p><em>foo <strong>bar *baz bim</strong> bam</em></p>
+````````````````````````````````
+
+
+Rule 16:
+
+```````````````````````````````` example
+**foo **bar baz**
+.
+<p>**foo <strong>bar baz</strong></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*foo *bar baz*
+.
+<p>*foo <em>bar baz</em></p>
+````````````````````````````````
+
+
+Rule 17:
+
+```````````````````````````````` example
+*[bar*](/url)
+.
+<p>*<a href="/url">bar*</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+_foo [bar_](/url)
+.
+<p>_foo <a href="/url">bar_</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*<img src="foo" title="*"/>
+.
+<p>*<img src="foo" title="*"/></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+**<a href="**">
+.
+<p>**<a href="**"></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+__<a href="__">
+.
+<p>__<a href="__"></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*a `*`*
+.
+<p><em>a <code>*</code></em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+_a `_`_
+.
+<p><em>a <code>_</code></em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+**a<https://foo.bar/?q=**>
+.
+<p>**a<a href="https://foo.bar/?q=**">https://foo.bar/?q=**</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+__a<https://foo.bar/?q=__>
+.
+<p>__a<a href="https://foo.bar/?q=__">https://foo.bar/?q=__</a></p>
+````````````````````````````````
+
+
+
+## Links
+
+A link contains [link text] (the visible text), a [link destination]
+(the URI that is the link destination), and optionally a [link title].
+There are two basic kinds of links in Markdown. In [inline links] the
+destination and title are given immediately after the link text. In
+[reference links] the destination and title are defined elsewhere in
+the document.
+
+A [link text](@) consists of a sequence of zero or more
+inline elements enclosed by square brackets (`[` and `]`). The
+following rules apply:
+
+- Links may not contain other links, at any level of nesting. If
+ multiple otherwise valid link definitions appear nested inside each
+ other, the inner-most definition is used.
+
+- Brackets are allowed in the [link text] only if (a) they
+ are backslash-escaped or (b) they appear as a matched pair of brackets,
+ with an open bracket `[`, a sequence of zero or more inlines, and
+ a close bracket `]`.
+
+- Backtick [code spans], [autolinks], and raw [HTML tags] bind more tightly
+ than the brackets in link text. Thus, for example,
+ `` [foo`]` `` could not be a link text, since the second `]`
+ is part of a code span.
+
+- The brackets in link text bind more tightly than markers for
+ [emphasis and strong emphasis]. Thus, for example, `*[foo*](url)` is a link.
+
+A [link destination](@) consists of either
+
+- a sequence of zero or more characters between an opening `<` and a
+ closing `>` that contains no line endings or unescaped
+ `<` or `>` characters, or
+
+- a nonempty sequence of characters that does not start with `<`,
+ does not include [ASCII control characters][ASCII control character]
+ or [space] character, and includes parentheses only if (a) they are
+ backslash-escaped or (b) they are part of a balanced pair of
+ unescaped parentheses.
+ (Implementations may impose limits on parentheses nesting to
+ avoid performance issues, but at least three levels of nesting
+ should be supported.)
+
+A [link title](@) consists of either
+
+- a sequence of zero or more characters between straight double-quote
+ characters (`"`), including a `"` character only if it is
+ backslash-escaped, or
+
+- a sequence of zero or more characters between straight single-quote
+ characters (`'`), including a `'` character only if it is
+ backslash-escaped, or
+
+- a sequence of zero or more characters between matching parentheses
+ (`(...)`), including a `(` or `)` character only if it is
+ backslash-escaped.
+
+Although [link titles] may span multiple lines, they may not contain
+a [blank line].
+
+An [inline link](@) consists of a [link text] followed immediately
+by a left parenthesis `(`, an optional [link destination], an optional
+[link title], and a right parenthesis `)`.
+These four components may be separated by spaces, tabs, and up to one line
+ending.
+If both [link destination] and [link title] are present, they *must* be
+separated by spaces, tabs, and up to one line ending.
+
+The link's text consists of the inlines contained
+in the [link text] (excluding the enclosing square brackets).
+The link's URI consists of the link destination, excluding enclosing
+`<...>` if present, with backslash-escapes in effect as described
+above. The link's title consists of the link title, excluding its
+enclosing delimiters, with backslash-escapes in effect as described
+above.
+
+Here is a simple inline link:
+
+```````````````````````````````` example
+[link](/uri "title")
+.
+<p><a href="/uri" title="title">link</a></p>
+````````````````````````````````
+
+
+The title, the link text and even
+the destination may be omitted:
+
+```````````````````````````````` example
+[link](/uri)
+.
+<p><a href="/uri">link</a></p>
+````````````````````````````````
+
+```````````````````````````````` example
+[](./target.md)
+.
+<p><a href="./target.md"></a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[link]()
+.
+<p><a href="">link</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[link](<>)
+.
+<p><a href="">link</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[]()
+.
+<p><a href=""></a></p>
+````````````````````````````````
+
+The destination can only contain spaces if it is
+enclosed in pointy brackets:
+
+```````````````````````````````` example
+[link](/my uri)
+.
+<p>[link](/my uri)</p>
+````````````````````````````````
+
+```````````````````````````````` example
+[link](</my uri>)
+.
+<p><a href="/my%20uri">link</a></p>
+````````````````````````````````
+
+The destination cannot contain line endings,
+even if enclosed in pointy brackets:
+
+```````````````````````````````` example
+[link](foo
+bar)
+.
+<p>[link](foo
+bar)</p>
+````````````````````````````````
+
+```````````````````````````````` example
+[link](<foo
+bar>)
+.
+<p>[link](<foo
+bar>)</p>
+````````````````````````````````
+
+The destination can contain `)` if it is enclosed
+in pointy brackets:
+
+```````````````````````````````` example
+[a](<b)c>)
+.
+<p><a href="b)c">a</a></p>
+````````````````````````````````
+
+Pointy brackets that enclose links must be unescaped:
+
+```````````````````````````````` example
+[link](<foo\>)
+.
+<p>[link](<foo>)</p>
+````````````````````````````````
+
+These are not links, because the opening pointy bracket
+is not matched properly:
+
+```````````````````````````````` example
+[a](<b)c
+[a](<b)c>
+[a](<b>c)
+.
+<p>[a](<b)c
+[a](<b)c>
+[a](<b>c)</p>
+````````````````````````````````
+
+Parentheses inside the link destination may be escaped:
+
+```````````````````````````````` example
+[link](\(foo\))
+.
+<p><a href="(foo)">link</a></p>
+````````````````````````````````
+
+Any number of parentheses are allowed without escaping, as long as they are
+balanced:
+
+```````````````````````````````` example
+[link](foo(and(bar)))
+.
+<p><a href="foo(and(bar))">link</a></p>
+````````````````````````````````
+
+However, if you have unbalanced parentheses, you need to escape or use the
+`<...>` form:
+
+```````````````````````````````` example
+[link](foo(and(bar))
+.
+<p>[link](foo(and(bar))</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[link](foo\(and\(bar\))
+.
+<p><a href="foo(and(bar)">link</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[link](<foo(and(bar)>)
+.
+<p><a href="foo(and(bar)">link</a></p>
+````````````````````````````````
+
+
+Parentheses and other symbols can also be escaped, as usual
+in Markdown:
+
+```````````````````````````````` example
+[link](foo\)\:)
+.
+<p><a href="foo):">link</a></p>
+````````````````````````````````
+
+
+A link can contain fragment identifiers and queries:
+
+```````````````````````````````` example
+[link](#fragment)
+
+[link](https://example.com#fragment)
+
+[link](https://example.com?foo=3#frag)
+.
+<p><a href="#fragment">link</a></p>
+<p><a href="https://example.com#fragment">link</a></p>
+<p><a href="https://example.com?foo=3#frag">link</a></p>
+````````````````````````````````
+
+
+Note that a backslash before a non-escapable character is
+just a backslash:
+
+```````````````````````````````` example
+[link](foo\bar)
+.
+<p><a href="foo%5Cbar">link</a></p>
+````````````````````````````````
+
+
+URL-escaping should be left alone inside the destination, as all
+URL-escaped characters are also valid URL characters. Entity and
+numerical character references in the destination will be parsed
+into the corresponding Unicode code points, as usual. These may
+be optionally URL-escaped when written as HTML, but this spec
+does not enforce any particular policy for rendering URLs in
+HTML or other formats. Renderers may make different decisions
+about how to escape or normalize URLs in the output.
+
+```````````````````````````````` example
+[link](foo%20bä)
+.
+<p><a href="foo%20b%C3%A4">link</a></p>
+````````````````````````````````
+
+
+Note that, because titles can often be parsed as destinations,
+if you try to omit the destination and keep the title, you'll
+get unexpected results:
+
+```````````````````````````````` example
+[link]("title")
+.
+<p><a href="%22title%22">link</a></p>
+````````````````````````````````
+
+
+Titles may be in single quotes, double quotes, or parentheses:
+
+```````````````````````````````` example
+[link](/url "title")
+[link](/url 'title')
+[link](/url (title))
+.
+<p><a href="/url" title="title">link</a>
+<a href="/url" title="title">link</a>
+<a href="/url" title="title">link</a></p>
+````````````````````````````````
+
+
+Backslash escapes and entity and numeric character references
+may be used in titles:
+
+```````````````````````````````` example
+[link](/url "title \""")
+.
+<p><a href="/url" title="title """>link</a></p>
+````````````````````````````````
+
+
+Titles must be separated from the link using spaces, tabs, and up to one line
+ending.
+Other [Unicode whitespace] like non-breaking space doesn't work.
+
+```````````````````````````````` example
+[link](/url "title")
+.
+<p><a href="/url%C2%A0%22title%22">link</a></p>
+````````````````````````````````
+
+
+Nested balanced quotes are not allowed without escaping:
+
+```````````````````````````````` example
+[link](/url "title "and" title")
+.
+<p>[link](/url "title "and" title")</p>
+````````````````````````````````
+
+
+But it is easy to work around this by using a different quote type:
+
+```````````````````````````````` example
+[link](/url 'title "and" title')
+.
+<p><a href="/url" title="title "and" title">link</a></p>
+````````````````````````````````
+
+
+(Note: `Markdown.pl` did allow double quotes inside a double-quoted
+title, and its test suite included a test demonstrating this.
+But it is hard to see a good rationale for the extra complexity this
+brings, since there are already many ways---backslash escaping,
+entity and numeric character references, or using a different
+quote type for the enclosing title---to write titles containing
+double quotes. `Markdown.pl`'s handling of titles has a number
+of other strange features. For example, it allows single-quoted
+titles in inline links, but not reference links. And, in
+reference links but not inline links, it allows a title to begin
+with `"` and end with `)`. `Markdown.pl` 1.0.1 even allows
+titles with no closing quotation mark, though 1.0.2b8 does not.
+It seems preferable to adopt a simple, rational rule that works
+the same way in inline links and link reference definitions.)
+
+Spaces, tabs, and up to one line ending is allowed around the destination and
+title:
+
+```````````````````````````````` example
+[link]( /uri
+ "title" )
+.
+<p><a href="/uri" title="title">link</a></p>
+````````````````````````````````
+
+
+But it is not allowed between the link text and the
+following parenthesis:
+
+```````````````````````````````` example
+[link] (/uri)
+.
+<p>[link] (/uri)</p>
+````````````````````````````````
+
+
+The link text may contain balanced brackets, but not unbalanced ones,
+unless they are escaped:
+
+```````````````````````````````` example
+[link [foo [bar]]](/uri)
+.
+<p><a href="/uri">link [foo [bar]]</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[link] bar](/uri)
+.
+<p>[link] bar](/uri)</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[link [bar](/uri)
+.
+<p>[link <a href="/uri">bar</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[link \[bar](/uri)
+.
+<p><a href="/uri">link [bar</a></p>
+````````````````````````````````
+
+
+The link text may contain inline content:
+
+```````````````````````````````` example
+[link *foo **bar** `#`*](/uri)
+.
+<p><a href="/uri">link <em>foo <strong>bar</strong> <code>#</code></em></a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[](/uri)
+.
+<p><a href="/uri"><img src="moon.jpg" alt="moon" /></a></p>
+````````````````````````````````
+
+
+However, links may not contain other links, at any level of nesting.
+
+```````````````````````````````` example
+[foo [bar](/uri)](/uri)
+.
+<p>[foo <a href="/uri">bar</a>](/uri)</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo *[bar [baz](/uri)](/uri)*](/uri)
+.
+<p>[foo <em>[bar <a href="/uri">baz</a>](/uri)</em>](/uri)</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+](uri2)](uri3)
+.
+<p><img src="uri3" alt="[foo](uri2)" /></p>
+````````````````````````````````
+
+
+These cases illustrate the precedence of link text grouping over
+emphasis grouping:
+
+```````````````````````````````` example
+*[foo*](/uri)
+.
+<p>*<a href="/uri">foo*</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo *bar](baz*)
+.
+<p><a href="baz*">foo *bar</a></p>
+````````````````````````````````
+
+
+Note that brackets that *aren't* part of links do not take
+precedence:
+
+```````````````````````````````` example
+*foo [bar* baz]
+.
+<p><em>foo [bar</em> baz]</p>
+````````````````````````````````
+
+
+These cases illustrate the precedence of HTML tags, code spans,
+and autolinks over link grouping:
+
+```````````````````````````````` example
+[foo <bar attr="](baz)">
+.
+<p>[foo <bar attr="](baz)"></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo`](/uri)`
+.
+<p>[foo<code>](/uri)</code></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo<https://example.com/?search=](uri)>
+.
+<p>[foo<a href="https://example.com/?search=%5D(uri)">https://example.com/?search=](uri)</a></p>
+````````````````````````````````
+
+
+There are three kinds of [reference link](@)s:
+[full](#full-reference-link), [collapsed](#collapsed-reference-link),
+and [shortcut](#shortcut-reference-link).
+
+A [full reference link](@)
+consists of a [link text] immediately followed by a [link label]
+that [matches] a [link reference definition] elsewhere in the document.
+
+A [link label](@) begins with a left bracket (`[`) and ends
+with the first right bracket (`]`) that is not backslash-escaped.
+Between these brackets there must be at least one character that is not a space,
+tab, or line ending.
+Unescaped square bracket characters are not allowed inside the
+opening and closing square brackets of [link labels]. A link
+label can have at most 999 characters inside the square
+brackets.
+
+One label [matches](@)
+another just in case their normalized forms are equal. To normalize a
+label, strip off the opening and closing brackets,
+perform the *Unicode case fold*, strip leading and trailing
+spaces, tabs, and line endings, and collapse consecutive internal
+spaces, tabs, and line endings to a single space. If there are multiple
+matching reference link definitions, the one that comes first in the
+document is used. (It is desirable in such cases to emit a warning.)
+
+The link's URI and title are provided by the matching [link
+reference definition].
+
+Here is a simple example:
+
+```````````````````````````````` example
+[foo][bar]
+
+[bar]: /url "title"
+.
+<p><a href="/url" title="title">foo</a></p>
+````````````````````````````````
+
+
+The rules for the [link text] are the same as with
+[inline links]. Thus:
+
+The link text may contain balanced brackets, but not unbalanced ones,
+unless they are escaped:
+
+```````````````````````````````` example
+[link [foo [bar]]][ref]
+
+[ref]: /uri
+.
+<p><a href="/uri">link [foo [bar]]</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[link \[bar][ref]
+
+[ref]: /uri
+.
+<p><a href="/uri">link [bar</a></p>
+````````````````````````````````
+
+
+The link text may contain inline content:
+
+```````````````````````````````` example
+[link *foo **bar** `#`*][ref]
+
+[ref]: /uri
+.
+<p><a href="/uri">link <em>foo <strong>bar</strong> <code>#</code></em></a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[][ref]
+
+[ref]: /uri
+.
+<p><a href="/uri"><img src="moon.jpg" alt="moon" /></a></p>
+````````````````````````````````
+
+
+However, links may not contain other links, at any level of nesting.
+
+```````````````````````````````` example
+[foo [bar](/uri)][ref]
+
+[ref]: /uri
+.
+<p>[foo <a href="/uri">bar</a>]<a href="/uri">ref</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo *bar [baz][ref]*][ref]
+
+[ref]: /uri
+.
+<p>[foo <em>bar <a href="/uri">baz</a></em>]<a href="/uri">ref</a></p>
+````````````````````````````````
+
+
+(In the examples above, we have two [shortcut reference links]
+instead of one [full reference link].)
+
+The following cases illustrate the precedence of link text grouping over
+emphasis grouping:
+
+```````````````````````````````` example
+*[foo*][ref]
+
+[ref]: /uri
+.
+<p>*<a href="/uri">foo*</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo *bar][ref]*
+
+[ref]: /uri
+.
+<p><a href="/uri">foo *bar</a>*</p>
+````````````````````````````````
+
+
+These cases illustrate the precedence of HTML tags, code spans,
+and autolinks over link grouping:
+
+```````````````````````````````` example
+[foo <bar attr="][ref]">
+
+[ref]: /uri
+.
+<p>[foo <bar attr="][ref]"></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo`][ref]`
+
+[ref]: /uri
+.
+<p>[foo<code>][ref]</code></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo<https://example.com/?search=][ref]>
+
+[ref]: /uri
+.
+<p>[foo<a href="https://example.com/?search=%5D%5Bref%5D">https://example.com/?search=][ref]</a></p>
+````````````````````````````````
+
+
+Matching is case-insensitive:
+
+```````````````````````````````` example
+[foo][BaR]
+
+[bar]: /url "title"
+.
+<p><a href="/url" title="title">foo</a></p>
+````````````````````````````````
+
+
+Unicode case fold is used:
+
+```````````````````````````````` example
+[ẞ]
+
+[SS]: /url
+.
+<p><a href="/url">ẞ</a></p>
+````````````````````````````````
+
+
+Consecutive internal spaces, tabs, and line endings are treated as one space for
+purposes of determining matching:
+
+```````````````````````````````` example
+[Foo
+ bar]: /url
+
+[Baz][Foo bar]
+.
+<p><a href="/url">Baz</a></p>
+````````````````````````````````
+
+
+No spaces, tabs, or line endings are allowed between the [link text] and the
+[link label]:
+
+```````````````````````````````` example
+[foo] [bar]
+
+[bar]: /url "title"
+.
+<p>[foo] <a href="/url" title="title">bar</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo]
+[bar]
+
+[bar]: /url "title"
+.
+<p>[foo]
+<a href="/url" title="title">bar</a></p>
+````````````````````````````````
+
+
+This is a departure from John Gruber's original Markdown syntax
+description, which explicitly allows whitespace between the link
+text and the link label. It brings reference links in line with
+[inline links], which (according to both original Markdown and
+this spec) cannot have whitespace after the link text. More
+importantly, it prevents inadvertent capture of consecutive
+[shortcut reference links]. If whitespace is allowed between the
+link text and the link label, then in the following we will have
+a single reference link, not two shortcut reference links, as
+intended:
+
+``` markdown
+[foo]
+[bar]
+
+[foo]: /url1
+[bar]: /url2
+```
+
+(Note that [shortcut reference links] were introduced by Gruber
+himself in a beta version of `Markdown.pl`, but never included
+in the official syntax description. Without shortcut reference
+links, it is harmless to allow space between the link text and
+link label; but once shortcut references are introduced, it is
+too dangerous to allow this, as it frequently leads to
+unintended results.)
+
+When there are multiple matching [link reference definitions],
+the first is used:
+
+```````````````````````````````` example
+[foo]: /url1
+
+[foo]: /url2
+
+[bar][foo]
+.
+<p><a href="/url1">bar</a></p>
+````````````````````````````````
+
+
+Note that matching is performed on normalized strings, not parsed
+inline content. So the following does not match, even though the
+labels define equivalent inline content:
+
+```````````````````````````````` example
+[bar][foo\!]
+
+[foo!]: /url
+.
+<p>[bar][foo!]</p>
+````````````````````````````````
+
+
+[Link labels] cannot contain brackets, unless they are
+backslash-escaped:
+
+```````````````````````````````` example
+[foo][ref[]
+
+[ref[]: /uri
+.
+<p>[foo][ref[]</p>
+<p>[ref[]: /uri</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo][ref[bar]]
+
+[ref[bar]]: /uri
+.
+<p>[foo][ref[bar]]</p>
+<p>[ref[bar]]: /uri</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[[[foo]]]
+
+[[[foo]]]: /url
+.
+<p>[[[foo]]]</p>
+<p>[[[foo]]]: /url</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[foo][ref\[]
+
+[ref\[]: /uri
+.
+<p><a href="/uri">foo</a></p>
+````````````````````````````````
+
+
+Note that in this example `]` is not backslash-escaped:
+
+```````````````````````````````` example
+[bar\\]: /uri
+
+[bar\\]
+.
+<p><a href="/uri">bar\</a></p>
+````````````````````````````````
+
+
+A [link label] must contain at least one character that is not a space, tab, or
+line ending:
+
+```````````````````````````````` example
+[]
+
+[]: /uri
+.
+<p>[]</p>
+<p>[]: /uri</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[
+ ]
+
+[
+ ]: /uri
+.
+<p>[
+]</p>
+<p>[
+]: /uri</p>
+````````````````````````````````
+
+
+A [collapsed reference link](@)
+consists of a [link label] that [matches] a
+[link reference definition] elsewhere in the
+document, followed by the string `[]`.
+The contents of the link label are parsed as inlines,
+which are used as the link's text. The link's URI and title are
+provided by the matching reference link definition. Thus,
+`[foo][]` is equivalent to `[foo][foo]`.
+
+```````````````````````````````` example
+[foo][]
+
+[foo]: /url "title"
+.
+<p><a href="/url" title="title">foo</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[*foo* bar][]
+
+[*foo* bar]: /url "title"
+.
+<p><a href="/url" title="title"><em>foo</em> bar</a></p>
+````````````````````````````````
+
+
+The link labels are case-insensitive:
+
+```````````````````````````````` example
+[Foo][]
+
+[foo]: /url "title"
+.
+<p><a href="/url" title="title">Foo</a></p>
+````````````````````````````````
+
+
+
+As with full reference links, spaces, tabs, or line endings are not
+allowed between the two sets of brackets:
+
+```````````````````````````````` example
+[foo]
+[]
+
+[foo]: /url "title"
+.
+<p><a href="/url" title="title">foo</a>
+[]</p>
+````````````````````````````````
+
+
+A [shortcut reference link](@)
+consists of a [link label] that [matches] a
+[link reference definition] elsewhere in the
+document and is not followed by `[]` or a link label.
+The contents of the link label are parsed as inlines,
+which are used as the link's text. The link's URI and title
+are provided by the matching link reference definition.
+Thus, `[foo]` is equivalent to `[foo][]`.
+
+```````````````````````````````` example
+[foo]
+
+[foo]: /url "title"
+.
+<p><a href="/url" title="title">foo</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[*foo* bar]
+
+[*foo* bar]: /url "title"
+.
+<p><a href="/url" title="title"><em>foo</em> bar</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[[*foo* bar]]
+
+[*foo* bar]: /url "title"
+.
+<p>[<a href="/url" title="title"><em>foo</em> bar</a>]</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[[bar [foo]
+
+[foo]: /url
+.
+<p>[[bar <a href="/url">foo</a></p>
+````````````````````````````````
+
+
+The link labels are case-insensitive:
+
+```````````````````````````````` example
+[Foo]
+
+[foo]: /url "title"
+.
+<p><a href="/url" title="title">Foo</a></p>
+````````````````````````````````
+
+
+A space after the link text should be preserved:
+
+```````````````````````````````` example
+[foo] bar
+
+[foo]: /url
+.
+<p><a href="/url">foo</a> bar</p>
+````````````````````````````````
+
+
+If you just want bracketed text, you can backslash-escape the
+opening bracket to avoid links:
+
+```````````````````````````````` example
+\[foo]
+
+[foo]: /url "title"
+.
+<p>[foo]</p>
+````````````````````````````````
+
+
+Note that this is a link, because a link label ends with the first
+following closing bracket:
+
+```````````````````````````````` example
+[foo*]: /url
+
+*[foo*]
+.
+<p>*<a href="/url">foo*</a></p>
+````````````````````````````````
+
+
+Full and collapsed references take precedence over shortcut
+references:
+
+```````````````````````````````` example
+[foo][bar]
+
+[foo]: /url1
+[bar]: /url2
+.
+<p><a href="/url2">foo</a></p>
+````````````````````````````````
+
+```````````````````````````````` example
+[foo][]
+
+[foo]: /url1
+.
+<p><a href="/url1">foo</a></p>
+````````````````````````````````
+
+Inline links also take precedence:
+
+```````````````````````````````` example
+[foo]()
+
+[foo]: /url1
+.
+<p><a href="">foo</a></p>
+````````````````````````````````
+
+```````````````````````````````` example
+[foo](not a link)
+
+[foo]: /url1
+.
+<p><a href="/url1">foo</a>(not a link)</p>
+````````````````````````````````
+
+In the following case `[bar][baz]` is parsed as a reference,
+`[foo]` as normal text:
+
+```````````````````````````````` example
+[foo][bar][baz]
+
+[baz]: /url
+.
+<p>[foo]<a href="/url">bar</a></p>
+````````````````````````````````
+
+
+Here, though, `[foo][bar]` is parsed as a reference, since
+`[bar]` is defined:
+
+```````````````````````````````` example
+[foo][bar][baz]
+
+[baz]: /url1
+[bar]: /url2
+.
+<p><a href="/url2">foo</a><a href="/url1">baz</a></p>
+````````````````````````````````
+
+
+Here `[foo]` is not parsed as a shortcut reference, because it
+is followed by a link label (even though `[bar]` is not defined):
+
+```````````````````````````````` example
+[foo][bar][baz]
+
+[baz]: /url1
+[foo]: /url2
+.
+<p>[foo]<a href="/url1">bar</a></p>
+````````````````````````````````
+
+
+
+## Images
+
+Syntax for images is like the syntax for links, with one
+difference. Instead of [link text], we have an
+[image description](@). The rules for this are the
+same as for [link text], except that (a) an
+image description starts with `
+.
+<p><img src="/url" alt="foo" title="title" /></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+![foo *bar*]
+
+[foo *bar*]: train.jpg "train & tracks"
+.
+<p><img src="train.jpg" alt="foo bar" title="train & tracks" /></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+](/url2)
+.
+<p><img src="/url2" alt="foo bar" /></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+](/url2)
+.
+<p><img src="/url2" alt="foo bar" /></p>
+````````````````````````````````
+
+
+Though this spec is concerned with parsing, not rendering, it is
+recommended that in rendering to HTML, only the plain string content
+of the [image description] be used. Note that in
+the above example, the alt attribute's value is `foo bar`, not `foo
+[bar](/url)` or `foo <a href="/url">bar</a>`. Only the plain string
+content is rendered, without formatting.
+
+```````````````````````````````` example
+![foo *bar*][]
+
+[foo *bar*]: train.jpg "train & tracks"
+.
+<p><img src="train.jpg" alt="foo bar" title="train & tracks" /></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+![foo *bar*][foobar]
+
+[FOOBAR]: train.jpg "train & tracks"
+.
+<p><img src="train.jpg" alt="foo bar" title="train & tracks" /></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+
+.
+<p><img src="train.jpg" alt="foo" /></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+My 
+.
+<p>My <img src="/path/to/train.jpg" alt="foo bar" title="title" /></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+
+.
+<p><img src="url" alt="foo" /></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+
+.
+<p><img src="/url" alt="" /></p>
+````````````````````````````````
+
+
+Reference-style:
+
+```````````````````````````````` example
+![foo][bar]
+
+[bar]: /url
+.
+<p><img src="/url" alt="foo" /></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+![foo][bar]
+
+[BAR]: /url
+.
+<p><img src="/url" alt="foo" /></p>
+````````````````````````````````
+
+
+Collapsed:
+
+```````````````````````````````` example
+![foo][]
+
+[foo]: /url "title"
+.
+<p><img src="/url" alt="foo" title="title" /></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+![*foo* bar][]
+
+[*foo* bar]: /url "title"
+.
+<p><img src="/url" alt="foo bar" title="title" /></p>
+````````````````````````````````
+
+
+The labels are case-insensitive:
+
+```````````````````````````````` example
+![Foo][]
+
+[foo]: /url "title"
+.
+<p><img src="/url" alt="Foo" title="title" /></p>
+````````````````````````````````
+
+
+As with reference links, spaces, tabs, and line endings, are not allowed
+between the two sets of brackets:
+
+```````````````````````````````` example
+![foo]
+[]
+
+[foo]: /url "title"
+.
+<p><img src="/url" alt="foo" title="title" />
+[]</p>
+````````````````````````````````
+
+
+Shortcut:
+
+```````````````````````````````` example
+![foo]
+
+[foo]: /url "title"
+.
+<p><img src="/url" alt="foo" title="title" /></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+![*foo* bar]
+
+[*foo* bar]: /url "title"
+.
+<p><img src="/url" alt="foo bar" title="title" /></p>
+````````````````````````````````
+
+
+Note that link labels cannot contain unescaped brackets:
+
+```````````````````````````````` example
+![[foo]]
+
+[[foo]]: /url "title"
+.
+<p>![[foo]]</p>
+<p>[[foo]]: /url "title"</p>
+````````````````````````````````
+
+
+The link labels are case-insensitive:
+
+```````````````````````````````` example
+![Foo]
+
+[foo]: /url "title"
+.
+<p><img src="/url" alt="Foo" title="title" /></p>
+````````````````````````````````
+
+
+If you just want a literal `!` followed by bracketed text, you can
+backslash-escape the opening `[`:
+
+```````````````````````````````` example
+!\[foo]
+
+[foo]: /url "title"
+.
+<p>![foo]</p>
+````````````````````````````````
+
+
+If you want a link after a literal `!`, backslash-escape the
+`!`:
+
+```````````````````````````````` example
+\![foo]
+
+[foo]: /url "title"
+.
+<p>!<a href="/url" title="title">foo</a></p>
+````````````````````````````````
+
+
+## Autolinks
+
+[Autolink](@)s are absolute URIs and email addresses inside
+`<` and `>`. They are parsed as links, with the URL or email address
+as the link label.
+
+A [URI autolink](@) consists of `<`, followed by an
+[absolute URI] followed by `>`. It is parsed as
+a link to the URI, with the URI as the link's label.
+
+An [absolute URI](@),
+for these purposes, consists of a [scheme] followed by a colon (`:`)
+followed by zero or more characters other than [ASCII control
+characters][ASCII control character], [space], `<`, and `>`.
+If the URI includes these characters, they must be percent-encoded
+(e.g. `%20` for a space).
+
+For purposes of this spec, a [scheme](@) is any sequence
+of 2--32 characters beginning with an ASCII letter and followed
+by any combination of ASCII letters, digits, or the symbols plus
+("+"), period ("."), or hyphen ("-").
+
+Here are some valid autolinks:
+
+```````````````````````````````` example
+<http://foo.bar.baz>
+.
+<p><a href="http://foo.bar.baz">http://foo.bar.baz</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<https://foo.bar.baz/test?q=hello&id=22&boolean>
+.
+<p><a href="https://foo.bar.baz/test?q=hello&id=22&boolean">https://foo.bar.baz/test?q=hello&id=22&boolean</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<irc://foo.bar:2233/baz>
+.
+<p><a href="irc://foo.bar:2233/baz">irc://foo.bar:2233/baz</a></p>
+````````````````````````````````
+
+
+Uppercase is also fine:
+
+```````````````````````````````` example
+<MAILTO:FOO@BAR.BAZ>
+.
+<p><a href="MAILTO:FOO@BAR.BAZ">MAILTO:FOO@BAR.BAZ</a></p>
+````````````````````````````````
+
+
+Note that many strings that count as [absolute URIs] for
+purposes of this spec are not valid URIs, because their
+schemes are not registered or because of other problems
+with their syntax:
+
+```````````````````````````````` example
+<a+b+c:d>
+.
+<p><a href="a+b+c:d">a+b+c:d</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<made-up-scheme://foo,bar>
+.
+<p><a href="made-up-scheme://foo,bar">made-up-scheme://foo,bar</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<https://../>
+.
+<p><a href="https://../">https://../</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<localhost:5001/foo>
+.
+<p><a href="localhost:5001/foo">localhost:5001/foo</a></p>
+````````````````````````````````
+
+
+Spaces are not allowed in autolinks:
+
+```````````````````````````````` example
+<https://foo.bar/baz bim>
+.
+<p><https://foo.bar/baz bim></p>
+````````````````````````````````
+
+
+Backslash-escapes do not work inside autolinks:
+
+```````````````````````````````` example
+<https://example.com/\[\>
+.
+<p><a href="https://example.com/%5C%5B%5C">https://example.com/\[\</a></p>
+````````````````````````````````
+
+
+An [email autolink](@)
+consists of `<`, followed by an [email address],
+followed by `>`. The link's label is the email address,
+and the URL is `mailto:` followed by the email address.
+
+An [email address](@),
+for these purposes, is anything that matches
+the [non-normative regex from the HTML5
+spec](https://html.spec.whatwg.org/multipage/forms.html#e-mail-state-(type=email)):
+
+ /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?
+ (?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/
+
+Examples of email autolinks:
+
+```````````````````````````````` example
+<foo@bar.example.com>
+.
+<p><a href="mailto:foo@bar.example.com">foo@bar.example.com</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<foo+special@Bar.baz-bar0.com>
+.
+<p><a href="mailto:foo+special@Bar.baz-bar0.com">foo+special@Bar.baz-bar0.com</a></p>
+````````````````````````````````
+
+
+Backslash-escapes do not work inside email autolinks:
+
+```````````````````````````````` example
+<foo\+@bar.example.com>
+.
+<p><foo+@bar.example.com></p>
+````````````````````````````````
+
+
+These are not autolinks:
+
+```````````````````````````````` example
+<>
+.
+<p><></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+< https://foo.bar >
+.
+<p>< https://foo.bar ></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<m:abc>
+.
+<p><m:abc></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<foo.bar.baz>
+.
+<p><foo.bar.baz></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+https://example.com
+.
+<p>https://example.com</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo@bar.example.com
+.
+<p>foo@bar.example.com</p>
+````````````````````````````````
+
+
+## Raw HTML
+
+Text between `<` and `>` that looks like an HTML tag is parsed as a
+raw HTML tag and will be rendered in HTML without escaping.
+Tag and attribute names are not limited to current HTML tags,
+so custom tags (and even, say, DocBook tags) may be used.
+
+Here is the grammar for tags:
+
+A [tag name](@) consists of an ASCII letter
+followed by zero or more ASCII letters, digits, or
+hyphens (`-`).
+
+An [attribute](@) consists of spaces, tabs, and up to one line ending,
+an [attribute name], and an optional
+[attribute value specification].
+
+An [attribute name](@)
+consists of an ASCII letter, `_`, or `:`, followed by zero or more ASCII
+letters, digits, `_`, `.`, `:`, or `-`. (Note: This is the XML
+specification restricted to ASCII. HTML5 is laxer.)
+
+An [attribute value specification](@)
+consists of optional spaces, tabs, and up to one line ending,
+a `=` character, optional spaces, tabs, and up to one line ending,
+and an [attribute value].
+
+An [attribute value](@)
+consists of an [unquoted attribute value],
+a [single-quoted attribute value], or a [double-quoted attribute value].
+
+An [unquoted attribute value](@)
+is a nonempty string of characters not
+including spaces, tabs, line endings, `"`, `'`, `=`, `<`, `>`, or `` ` ``.
+
+A [single-quoted attribute value](@)
+consists of `'`, zero or more
+characters not including `'`, and a final `'`.
+
+A [double-quoted attribute value](@)
+consists of `"`, zero or more
+characters not including `"`, and a final `"`.
+
+An [open tag](@) consists of a `<` character, a [tag name],
+zero or more [attributes], optional spaces, tabs, and up to one line ending,
+an optional `/` character, and a `>` character.
+
+A [closing tag](@) consists of the string `</`, a
+[tag name], optional spaces, tabs, and up to one line ending, and the character
+`>`.
+
+An [HTML comment](@) consists of `<!-->`, `<!--->`, or `<!--`, a string of
+characters not including the string `-->`, and `-->` (see the
+[HTML spec](https://html.spec.whatwg.org/multipage/parsing.html#markup-declaration-open-state)).
+
+A [processing instruction](@)
+consists of the string `<?`, a string
+of characters not including the string `?>`, and the string
+`?>`.
+
+A [declaration](@) consists of the string `<!`, an ASCII letter, zero or more
+characters not including the character `>`, and the character `>`.
+
+A [CDATA section](@) consists of
+the string `<![CDATA[`, a string of characters not including the string
+`]]]]><![CDATA[>`, and the string `]]]]>< consists of an [open tag], a [closing tag],
+an [HTML comment], a [processing instruction], a [declaration],
+or a [CDATA section].
+
+Here are some simple open tags:
+
+```````````````````````````````` example
+<a><bab><c2c>
+.
+<p><a><bab><c2c></p>
+````````````````````````````````
+
+
+Empty elements:
+
+```````````````````````````````` example
+<a/><b2/>
+.
+<p><a/><b2/></p>
+````````````````````````````````
+
+
+Whitespace is allowed:
+
+```````````````````````````````` example
+<a /><b2
+data="foo" >
+.
+<p><a /><b2
+data="foo" ></p>
+````````````````````````````````
+
+
+With attributes:
+
+```````````````````````````````` example
+<a foo="bar" bam = 'baz <em>"</em>'
+_boolean zoop:33=zoop:33 />
+.
+<p><a foo="bar" bam = 'baz <em>"</em>'
+_boolean zoop:33=zoop:33 /></p>
+````````````````````````````````
+
+
+Custom tag names can be used:
+
+```````````````````````````````` example
+Foo <responsive-image src="foo.jpg" />
+.
+<p>Foo <responsive-image src="foo.jpg" /></p>
+````````````````````````````````
+
+
+Illegal tag names, not parsed as HTML:
+
+```````````````````````````````` example
+<33> <__>
+.
+<p><33> <__></p>
+````````````````````````````````
+
+
+Illegal attribute names:
+
+```````````````````````````````` example
+<a h*#ref="hi">
+.
+<p><a h*#ref="hi"></p>
+````````````````````````````````
+
+
+Illegal attribute values:
+
+```````````````````````````````` example
+<a href="hi'> <a href=hi'>
+.
+<p><a href="hi'> <a href=hi'></p>
+````````````````````````````````
+
+
+Illegal whitespace:
+
+```````````````````````````````` example
+< a><
+foo><bar/ >
+<foo bar=baz
+bim!bop />
+.
+<p>< a><
+foo><bar/ >
+<foo bar=baz
+bim!bop /></p>
+````````````````````````````````
+
+
+Missing whitespace:
+
+```````````````````````````````` example
+<a href='bar'title=title>
+.
+<p><a href='bar'title=title></p>
+````````````````````````````````
+
+
+Closing tags:
+
+```````````````````````````````` example
+</a></foo >
+.
+<p></a></foo ></p>
+````````````````````````````````
+
+
+Illegal attributes in closing tag:
+
+```````````````````````````````` example
+</a href="foo">
+.
+<p></a href="foo"></p>
+````````````````````````````````
+
+
+Comments:
+
+```````````````````````````````` example
+foo <!-- this is a --
+comment - with hyphens -->
+.
+<p>foo <!-- this is a --
+comment - with hyphens --></p>
+````````````````````````````````
+
+```````````````````````````````` example
+foo <!--> foo -->
+
+foo <!---> foo -->
+.
+<p>foo <!--> foo --></p>
+<p>foo <!---> foo --></p>
+````````````````````````````````
+
+
+Processing instructions:
+
+```````````````````````````````` example
+foo <?php echo $a; ?>
+.
+<p>foo <?php echo $a; ?></p>
+````````````````````````````````
+
+
+Declarations:
+
+```````````````````````````````` example
+foo <!ELEMENT br EMPTY>
+.
+<p>foo <!ELEMENT br EMPTY></p>
+````````````````````````````````
+
+
+CDATA sections:
+
+```````````````````````````````` example
+foo <![CDATA[>&<]]]]><![CDATA[>
+.
+<p>foo <![CDATA[>&<]]]]>< (rendered
+in HTML as a `<br />` tag):
+
+```````````````````````````````` example
+foo
+baz
+.
+<p>foo<br />
+baz</p>
+````````````````````````````````
+
+
+For a more visible alternative, a backslash before the
+[line ending] may be used instead of two or more spaces:
+
+```````````````````````````````` example
+foo\
+baz
+.
+<p>foo<br />
+baz</p>
+````````````````````````````````
+
+
+More than two spaces can be used:
+
+```````````````````````````````` example
+foo
+baz
+.
+<p>foo<br />
+baz</p>
+````````````````````````````````
+
+
+Leading spaces at the beginning of the next line are ignored:
+
+```````````````````````````````` example
+foo
+ bar
+.
+<p>foo<br />
+bar</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo\
+ bar
+.
+<p>foo<br />
+bar</p>
+````````````````````````````````
+
+
+Hard line breaks can occur inside emphasis, links, and other constructs
+that allow inline content:
+
+```````````````````````````````` example
+*foo
+bar*
+.
+<p><em>foo<br />
+bar</em></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+*foo\
+bar*
+.
+<p><em>foo<br />
+bar</em></p>
+````````````````````````````````
+
+
+Hard line breaks do not occur inside code spans
+
+```````````````````````````````` example
+`code
+span`
+.
+<p><code>code span</code></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+`code\
+span`
+.
+<p><code>code\ span</code></p>
+````````````````````````````````
+
+
+or HTML tags:
+
+```````````````````````````````` example
+<a href="foo
+bar">
+.
+<p><a href="foo
+bar"></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+<a href="foo\
+bar">
+.
+<p><a href="foo\
+bar"></p>
+````````````````````````````````
+
+
+Hard line breaks are for separating inline content within a block.
+Neither syntax for hard line breaks works at the end of a paragraph or
+other block element:
+
+```````````````````````````````` example
+foo\
+.
+<p>foo\</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+foo
+.
+<p>foo</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+### foo\
+.
+<h3>foo\</h3>
+````````````````````````````````
+
+
+```````````````````````````````` example
+### foo
+.
+<h3>foo</h3>
+````````````````````````````````
+
+
+## Soft line breaks
+
+A regular line ending (not in a code span or HTML tag) that is not
+preceded by two or more spaces or a backslash is parsed as a
+[softbreak](@). (A soft line break may be rendered in HTML either as a
+[line ending] or as a space. The result will be the same in
+browsers. In the examples here, a [line ending] will be used.)
+
+```````````````````````````````` example
+foo
+baz
+.
+<p>foo
+baz</p>
+````````````````````````````````
+
+
+Spaces at the end of the line and beginning of the next line are
+removed:
+
+```````````````````````````````` example
+foo
+ baz
+.
+<p>foo
+baz</p>
+````````````````````````````````
+
+
+A conforming parser may render a soft line break in HTML either as a
+line ending or as a space.
+
+A renderer may also provide an option to render soft line breaks
+as hard line breaks.
+
+## Textual content
+
+Any characters not given an interpretation by the above rules will
+be parsed as plain textual content.
+
+```````````````````````````````` example
+hello $.;'there
+.
+<p>hello $.;'there</p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+Foo χρῆν
+.
+<p>Foo χρῆν</p>
+````````````````````````````````
+
+
+Internal spaces are preserved verbatim:
+
+```````````````````````````````` example
+Multiple spaces
+.
+<p>Multiple spaces</p>
+````````````````````````````````
+
+
+<!-- END TESTS -->
+
+# Appendix: A parsing strategy
+
+In this appendix we describe some features of the parsing strategy
+used in the CommonMark reference implementations.
+
+## Overview
+
+Parsing has two phases:
+
+1. In the first phase, lines of input are consumed and the block
+structure of the document---its division into paragraphs, block quotes,
+list items, and so on---is constructed. Text is assigned to these
+blocks but not parsed. Link reference definitions are parsed and a
+map of links is constructed.
+
+2. In the second phase, the raw text contents of paragraphs and headings
+are parsed into sequences of Markdown inline elements (strings,
+code spans, links, emphasis, and so on), using the map of link
+references constructed in phase 1.
+
+At each point in processing, the document is represented as a tree of
+**blocks**. The root of the tree is a `document` block. The `document`
+may have any number of other blocks as **children**. These children
+may, in turn, have other blocks as children. The last child of a block
+is normally considered **open**, meaning that subsequent lines of input
+can alter its contents. (Blocks that are not open are **closed**.)
+Here, for example, is a possible document tree, with the open blocks
+marked by arrows:
+
+``` tree
+-> document
+ -> block_quote
+ paragraph
+ "Lorem ipsum dolor\nsit amet."
+ -> list (type=bullet tight=true bullet_char=-)
+ list_item
+ paragraph
+ "Qui *quodsi iracundia*"
+ -> list_item
+ -> paragraph
+ "aliquando id"
+```
+
+## Phase 1: block structure
+
+Each line that is processed has an effect on this tree. The line is
+analyzed and, depending on its contents, the document may be altered
+in one or more of the following ways:
+
+1. One or more open blocks may be closed.
+2. One or more new blocks may be created as children of the
+ last open block.
+3. Text may be added to the last (deepest) open block remaining
+ on the tree.
+
+Once a line has been incorporated into the tree in this way,
+it can be discarded, so input can be read in a stream.
+
+For each line, we follow this procedure:
+
+1. First we iterate through the open blocks, starting with the
+root document, and descending through last children down to the last
+open block. Each block imposes a condition that the line must satisfy
+if the block is to remain open. For example, a block quote requires a
+`>` character. A paragraph requires a non-blank line.
+In this phase we may match all or just some of the open
+blocks. But we cannot close unmatched blocks yet, because we may have a
+[lazy continuation line].
+
+2. Next, after consuming the continuation markers for existing
+blocks, we look for new block starts (e.g. `>` for a block quote).
+If we encounter a new block start, we close any blocks unmatched
+in step 1 before creating the new block as a child of the last
+matched container block.
+
+3. Finally, we look at the remainder of the line (after block
+markers like `>`, list markers, and indentation have been consumed).
+This is text that can be incorporated into the last open
+block (a paragraph, code block, heading, or raw HTML).
+
+Setext headings are formed when we see a line of a paragraph
+that is a [setext heading underline].
+
+Reference link definitions are detected when a paragraph is closed;
+the accumulated text lines are parsed to see if they begin with
+one or more reference link definitions. Any remainder becomes a
+normal paragraph.
+
+We can see how this works by considering how the tree above is
+generated by four lines of Markdown:
+
+``` markdown
+> Lorem ipsum dolor
+sit amet.
+> - Qui *quodsi iracundia*
+> - aliquando id
+```
+
+At the outset, our document model is just
+
+``` tree
+-> document
+```
+
+The first line of our text,
+
+``` markdown
+> Lorem ipsum dolor
+```
+
+causes a `block_quote` block to be created as a child of our
+open `document` block, and a `paragraph` block as a child of
+the `block_quote`. Then the text is added to the last open
+block, the `paragraph`:
+
+``` tree
+-> document
+ -> block_quote
+ -> paragraph
+ "Lorem ipsum dolor"
+```
+
+The next line,
+
+``` markdown
+sit amet.
+```
+
+is a "lazy continuation" of the open `paragraph`, so it gets added
+to the paragraph's text:
+
+``` tree
+-> document
+ -> block_quote
+ -> paragraph
+ "Lorem ipsum dolor\nsit amet."
+```
+
+The third line,
+
+``` markdown
+> - Qui *quodsi iracundia*
+```
+
+causes the `paragraph` block to be closed, and a new `list` block
+opened as a child of the `block_quote`. A `list_item` is also
+added as a child of the `list`, and a `paragraph` as a child of
+the `list_item`. The text is then added to the new `paragraph`:
+
+``` tree
+-> document
+ -> block_quote
+ paragraph
+ "Lorem ipsum dolor\nsit amet."
+ -> list (type=bullet tight=true bullet_char=-)
+ -> list_item
+ -> paragraph
+ "Qui *quodsi iracundia*"
+```
+
+The fourth line,
+
+``` markdown
+> - aliquando id
+```
+
+causes the `list_item` (and its child the `paragraph`) to be closed,
+and a new `list_item` opened up as child of the `list`. A `paragraph`
+is added as a child of the new `list_item`, to contain the text.
+We thus obtain the final tree:
+
+``` tree
+-> document
+ -> block_quote
+ paragraph
+ "Lorem ipsum dolor\nsit amet."
+ -> list (type=bullet tight=true bullet_char=-)
+ list_item
+ paragraph
+ "Qui *quodsi iracundia*"
+ -> list_item
+ -> paragraph
+ "aliquando id"
+```
+
+## Phase 2: inline structure
+
+Once all of the input has been parsed, all open blocks are closed.
+
+We then "walk the tree," visiting every node, and parse raw
+string contents of paragraphs and headings as inlines. At this
+point we have seen all the link reference definitions, so we can
+resolve reference links as we go.
+
+``` tree
+document
+ block_quote
+ paragraph
+ str "Lorem ipsum dolor"
+ softbreak
+ str "sit amet."
+ list (type=bullet tight=true bullet_char=-)
+ list_item
+ paragraph
+ str "Qui "
+ emph
+ str "quodsi iracundia"
+ list_item
+ paragraph
+ str "aliquando id"
+```
+
+Notice how the [line ending] in the first paragraph has
+been parsed as a `softbreak`, and the asterisks in the first list item
+have become an `emph`.
+
+### An algorithm for parsing nested emphasis and links
+
+By far the trickiest part of inline parsing is handling emphasis,
+strong emphasis, links, and images. This is done using the following
+algorithm.
+
+When we're parsing inlines and we hit either
+
+- a run of `*` or `_` characters, or
+- a `[` or `.
+
+The [delimiter stack] is a doubly linked list. Each
+element contains a pointer to a text node, plus information about
+
+- the type of delimiter (`[`, `![`, `*`, `_`)
+- the number of delimiters,
+- whether the delimiter is "active" (all are active to start), and
+- whether the delimiter is a potential opener, a potential closer,
+ or both (which depends on what sort of characters precede
+ and follow the delimiters).
+
+When we hit a `]` character, we call the *look for link or image*
+procedure (see below).
+
+When we hit the end of the input, we call the *process emphasis*
+procedure (see below), with `stack_bottom` = NULL.
+
+#### *look for link or image*
+
+Starting at the top of the delimiter stack, we look backwards
+through the stack for an opening `[` or `![` delimiter.
+
+- If we don't find one, we return a literal text node `]`.
+
+- If we do find one, but it's not *active*, we remove the inactive
+ delimiter from the stack, and return a literal text node `]`.
+
+- If we find one and it's active, then we parse ahead to see if
+ we have an inline link/image, reference link/image, collapsed reference
+ link/image, or shortcut reference link/image.
+
+ + If we don't, then we remove the opening delimiter from the
+ delimiter stack and return a literal text node `]`.
+
+ + If we do, then
+
+ * We return a link or image node whose children are the inlines
+ after the text node pointed to by the opening delimiter.
+
+ * We run *process emphasis* on these inlines, with the `[` opener
+ as `stack_bottom`.
+
+ * We remove the opening delimiter.
+
+ * If we have a link (and not an image), we also set all
+ `[` delimiters before the opening delimiter to *inactive*. (This
+ will prevent us from getting links within links.)
+
+#### *process emphasis*
+
+Parameter `stack_bottom` sets a lower bound to how far we
+descend in the [delimiter stack]. If it is NULL, we can
+go all the way to the bottom. Otherwise, we stop before
+visiting `stack_bottom`.
+
+Let `current_position` point to the element on the [delimiter stack]
+just above `stack_bottom` (or the first element if `stack_bottom`
+is NULL).
+
+We keep track of the `openers_bottom` for each delimiter
+type (`*`, `_`), indexed to the length of the closing delimiter run
+(modulo 3) and to whether the closing delimiter can also be an
+opener. Initialize this to `stack_bottom`.
+
+Then we repeat the following until we run out of potential
+closers:
+
+- Move `current_position` forward in the delimiter stack (if needed)
+ until we find the first potential closer with delimiter `*` or `_`.
+ (This will be the potential closer closest
+ to the beginning of the input -- the first one in parse order.)
+
+- Now, look back in the stack (staying above `stack_bottom` and
+ the `openers_bottom` for this delimiter type) for the
+ first matching potential opener ("matching" means same delimiter).
+
+- If one is found:
+
+ + Figure out whether we have emphasis or strong emphasis:
+ if both closer and opener spans have length >= 2, we have
+ strong, otherwise regular.
+
+ + Insert an emph or strong emph node accordingly, after
+ the text node corresponding to the opener.
+
+ + Remove any delimiters between the opener and closer from
+ the delimiter stack.
+
+ + Remove 1 (for regular emph) or 2 (for strong emph) delimiters
+ from the opening and closing text nodes. If they become empty
+ as a result, remove them and remove the corresponding element
+ of the delimiter stack. If the closing node is removed, reset
+ `current_position` to the next element in the stack.
+
+- If none is found:
+
+ + Set `openers_bottom` to the element before `current_position`.
+ (We know that there are no openers for this kind of closer up to and
+ including this point, so this puts a lower bound on future searches.)
+
+ + If the closer at `current_position` is not a potential opener,
+ remove it from the delimiter stack (since we know it can't
+ be a closer either).
+
+ + Advance `current_position` to the next element in the stack.
+
+After we're done, we remove all delimiters above `stack_bottom` from the
+delimiter stack.
diff --git a/documents/markdown/markdown-it/strikethrough.md b/documents/markdown/markdown-it/strikethrough.md
new file mode 100644
index 0000000..3e3b17b
--- /dev/null
+++ b/documents/markdown/markdown-it/strikethrough.md
@@ -0,0 +1,136 @@
+.
+~~Strikeout~~
+.
+<p><s>Strikeout</s></p>
+.
+
+.
+x ~~~~foo~~ bar~~
+.
+<p>x <s><s>foo</s> bar</s></p>
+.
+
+.
+x ~~foo ~~bar~~~~
+.
+<p>x <s>foo <s>bar</s></s></p>
+.
+
+.
+x ~~~~foo~~~~
+.
+<p>x <s><s>foo</s></s></p>
+.
+
+.
+x ~~a ~~foo~~~~~~~~~~~bar~~ b~~
+
+x ~~a ~~foo~~~~~~~~~~~~bar~~ b~~
+.
+<p>x <s>a <s>foo</s></s>~~~<s><s>bar</s> b</s></p>
+<p>x <s>a <s>foo</s></s>~~~~<s><s>bar</s> b</s></p>
+.
+
+
+Strikeouts have the same priority as emphases:
+.
+**~~test**~~
+
+~~**test~~**
+.
+<p><strong>~~test</strong>~~</p>
+<p><s>**test</s>**</p>
+.
+
+
+Strikeouts have the same priority as emphases with respect to links:
+.
+[~~link]()~~
+
+~~[link~~]()
+.
+<p><a href="">~~link</a>~~</p>
+<p>~~<a href="">link~~</a></p>
+.
+
+
+Strikeouts have the same priority as emphases with respect to backticks:
+.
+~~`code~~`
+
+`~~code`~~
+.
+<p>~~<code>code~~</code></p>
+<p><code>~~code</code>~~</p>
+.
+
+
+Nested strikeouts:
+.
+~~foo ~~bar~~ baz~~
+
+~~f **o ~~o b~~ a** r~~
+.
+<p><s>foo <s>bar</s> baz</s></p>
+<p><s>f <strong>o <s>o b</s> a</strong> r</s></p>
+.
+
+
+Should not have a whitespace between text and "~~":
+.
+foo ~~ bar ~~ baz
+.
+<p>foo ~~ bar ~~ baz</p>
+.
+
+
+Should parse strikethrough within link tags:
+.
+[~~foo~~]()
+.
+<p><a href=""><s>foo</s></a></p>
+.
+
+
+Newline should be considered a whitespace:
+.
+~~test
+~~
+
+~~
+test~~
+
+~~
+test
+~~
+.
+<p>~~test
+~~</p>
+<p>~~
+test~~</p>
+<p>~~
+test
+~~</p>
+.
+
+From CommonMark test suite, replacing `**` with our marker:
+
+.
+a~~"foo"~~
+.
+<p>a~~“foo”~~</p>
+.
+
+Coverage: single tilde
+.
+~a~
+.
+<p>~a~</p>
+.
+
+Regression test for #742:
+.
+-~~~~;~~~~~~
+.
+<p>-<s><s>;</s></s>~~</p>
+.
diff --git a/documents/markdown/markdown-it/tables.md b/documents/markdown/markdown-it/tables.md
new file mode 100644
index 0000000..4737df7
--- /dev/null
+++ b/documents/markdown/markdown-it/tables.md
@@ -0,0 +1,808 @@
+Simple:
+.
+| Heading 1 | Heading 2
+| --------- | ---------
+| Cell 1 | Cell 2
+| Cell 3 | Cell 4
+.
+<table>
+<thead>
+<tr>
+<th>Heading 1</th>
+<th>Heading 2</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Cell 1</td>
+<td>Cell 2</td>
+</tr>
+<tr>
+<td>Cell 3</td>
+<td>Cell 4</td>
+</tr>
+</tbody>
+</table>
+.
+
+
+Column alignment:
+.
+| Header 1 | Header 2 | Header 3 | Header 4 |
+| :------: | -------: | :------- | -------- |
+| Cell 1 | Cell 2 | Cell 3 | Cell 4 |
+| Cell 5 | Cell 6 | Cell 7 | Cell 8 |
+.
+<table>
+<thead>
+<tr>
+<th style="text-align:center">Header 1</th>
+<th style="text-align:right">Header 2</th>
+<th style="text-align:left">Header 3</th>
+<th>Header 4</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td style="text-align:center">Cell 1</td>
+<td style="text-align:right">Cell 2</td>
+<td style="text-align:left">Cell 3</td>
+<td>Cell 4</td>
+</tr>
+<tr>
+<td style="text-align:center">Cell 5</td>
+<td style="text-align:right">Cell 6</td>
+<td style="text-align:left">Cell 7</td>
+<td>Cell 8</td>
+</tr>
+</tbody>
+</table>
+.
+
+
+Nested emphases:
+.
+Header 1|Header 2|Header 3|Header 4
+:-------|:------:|-------:|--------
+Cell 1 |Cell 2 |Cell 3 |Cell 4
+*Cell 5*|Cell 6 |Cell 7 |Cell 8
+.
+<table>
+<thead>
+<tr>
+<th style="text-align:left">Header 1</th>
+<th style="text-align:center">Header 2</th>
+<th style="text-align:right">Header 3</th>
+<th>Header 4</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td style="text-align:left">Cell 1</td>
+<td style="text-align:center">Cell 2</td>
+<td style="text-align:right">Cell 3</td>
+<td>Cell 4</td>
+</tr>
+<tr>
+<td style="text-align:left"><em>Cell 5</em></td>
+<td style="text-align:center">Cell 6</td>
+<td style="text-align:right">Cell 7</td>
+<td>Cell 8</td>
+</tr>
+</tbody>
+</table>
+.
+
+
+Nested tables inside blockquotes:
+.
+> foo|foo
+> ---|---
+> bar|bar
+baz|baz
+.
+<blockquote>
+<table>
+<thead>
+<tr>
+<th>foo</th>
+<th>foo</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>bar</td>
+<td>bar</td>
+</tr>
+</tbody>
+</table>
+</blockquote>
+<p>baz|baz</p>
+.
+
+
+Minimal one-column:
+.
+| foo
+|----
+| test2
+.
+<table>
+<thead>
+<tr>
+<th>foo</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>test2</td>
+</tr>
+</tbody>
+</table>
+.
+
+
+This is parsed as one big table:
+.
+- foo|foo
+---|---
+bar|bar
+.
+<table>
+<thead>
+<tr>
+<th>- foo</th>
+<th>foo</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>bar</td>
+<td>bar</td>
+</tr>
+</tbody>
+</table>
+.
+
+
+Second line should not contain symbols except "-", ":", "|" and " ":
+.
+foo|foo
+-----|-----s
+bar|bar
+.
+<p>foo|foo
+-----|-----s
+bar|bar</p>
+.
+
+
+Second line should contain "|" symbol:
+.
+foo|foo
+-----:-----
+bar|bar
+.
+<p>foo|foo
+-----:-----
+bar|bar</p>
+.
+
+
+Second line should not have empty columns in the middle:
+.
+foo|foo
+-----||-----
+bar|bar
+.
+<p>foo|foo
+-----||-----
+bar|bar</p>
+.
+
+
+Wrong alignment symbol position:
+.
+foo|foo
+-----|-::-
+bar|bar
+.
+<p>foo|foo
+-----|-::-
+bar|bar</p>
+.
+
+
+Title line should contain "|" symbol:
+.
+foo
+-----|-----
+bar|bar
+.
+<p>foo
+-----|-----
+bar|bar</p>
+.
+
+
+Allow tabs as a separator on 2nd line
+.
+| foo | bar |
+| --- | --- |
+| baz | quux |
+.
+<table>
+<thead>
+<tr>
+<th>foo</th>
+<th>bar</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>baz</td>
+<td>quux</td>
+</tr>
+</tbody>
+</table>
+.
+
+
+Should terminate paragraph:
+.
+paragraph
+foo|foo
+---|---
+bar|bar
+.
+<p>paragraph</p>
+<table>
+<thead>
+<tr>
+<th>foo</th>
+<th>foo</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>bar</td>
+<td>bar</td>
+</tr>
+</tbody>
+</table>
+.
+
+
+Another complicated backticks case
+.
+| Heading 1 | Heading 2
+| --------- | ---------
+| Cell 1 | Cell 2
+| \\\`|\\\`
+.
+<table>
+<thead>
+<tr>
+<th>Heading 1</th>
+<th>Heading 2</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Cell 1</td>
+<td>Cell 2</td>
+</tr>
+<tr>
+<td>\`</td>
+<td>\`</td>
+</tr>
+</tbody>
+</table>
+.
+
+`\` in tables should not count as escaped backtick
+.
+# | 1 | 2
+--|--|--
+x | `\` | `x`
+.
+<table>
+<thead>
+<tr>
+<th>#</th>
+<th>1</th>
+<th>2</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>x</td>
+<td><code>\</code></td>
+<td><code>x</code></td>
+</tr>
+</tbody>
+</table>
+.
+
+Tables should handle escaped backticks
+.
+# | 1 | 2
+--|--|--
+x | \`\` | `x`
+.
+<table>
+<thead>
+<tr>
+<th>#</th>
+<th>1</th>
+<th>2</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>x</td>
+<td>``</td>
+<td><code>x</code></td>
+</tr>
+</tbody>
+</table>
+.
+
+
+An amount of rows might be different across the table (issue #171):
+.
+| 1 | 2 |
+| :-----: | :-----: |
+| 3 | 4 | 5 | 6 |
+.
+<table>
+<thead>
+<tr>
+<th style="text-align:center">1</th>
+<th style="text-align:center">2</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td style="text-align:center">3</td>
+<td style="text-align:center">4</td>
+</tr>
+</tbody>
+</table>
+.
+
+
+An amount of rows might be different across the table #2:
+.
+| 1 | 2 | 3 | 4 |
+| :-----: | :-----: | :-----: | :-----: |
+| 5 | 6 |
+.
+<table>
+<thead>
+<tr>
+<th style="text-align:center">1</th>
+<th style="text-align:center">2</th>
+<th style="text-align:center">3</th>
+<th style="text-align:center">4</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td style="text-align:center">5</td>
+<td style="text-align:center">6</td>
+<td style="text-align:center"></td>
+<td style="text-align:center"></td>
+</tr>
+</tbody>
+</table>
+.
+
+
+Allow one-column tables (issue #171):
+.
+| foo |
+:-----:
+| bar |
+.
+<table>
+<thead>
+<tr>
+<th style="text-align:center">foo</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td style="text-align:center">bar</td>
+</tr>
+</tbody>
+</table>
+.
+
+
+Allow indented tables (issue #325):
+.
+ | Col1a | Col2a |
+ | ----- | ----- |
+ | Col1b | Col2b |
+.
+<table>
+<thead>
+<tr>
+<th>Col1a</th>
+<th>Col2a</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Col1b</td>
+<td>Col2b</td>
+</tr>
+</tbody>
+</table>
+.
+
+
+Tables should not be indented more than 4 spaces (1st line):
+.
+ | Col1a | Col2a |
+ | ----- | ----- |
+ | Col1b | Col2b |
+.
+<pre><code>| Col1a | Col2a |
+</code></pre>
+<p>| ----- | ----- |
+| Col1b | Col2b |</p>
+.
+
+
+Tables should not be indented more than 4 spaces (2nd line):
+.
+ | Col1a | Col2a |
+ | ----- | ----- |
+ | Col1b | Col2b |
+.
+<p>| Col1a | Col2a |
+| ----- | ----- |
+| Col1b | Col2b |</p>
+.
+
+
+Tables should not be indented more than 4 spaces (3rd line):
+.
+ | Col1a | Col2a |
+ | ----- | ----- |
+ | Col1b | Col2b |
+.
+<table>
+<thead>
+<tr>
+<th>Col1a</th>
+<th>Col2a</th>
+</tr>
+</thead>
+</table>
+<pre><code>| Col1b | Col2b |
+</code></pre>
+.
+
+
+Allow tables with empty body:
+.
+ | Col1a | Col2a |
+ | ----- | ----- |
+.
+<table>
+<thead>
+<tr>
+<th>Col1a</th>
+<th>Col2a</th>
+</tr>
+</thead>
+</table>
+.
+
+
+Align row should be at least as large as any actual rows:
+.
+Col1a | Col1b | Col1c
+----- | -----
+Col2a | Col2b | Col2c
+.
+<p>Col1a | Col1b | Col1c
+----- | -----
+Col2a | Col2b | Col2c</p>
+.
+
+Escaped pipes inside backticks don't split cells:
+.
+| Heading 1 | Heading 2
+| --------- | ---------
+| Cell 1 | Cell 2
+| `Cell 3\|` | Cell 4
+.
+<table>
+<thead>
+<tr>
+<th>Heading 1</th>
+<th>Heading 2</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Cell 1</td>
+<td>Cell 2</td>
+</tr>
+<tr>
+<td><code>Cell 3|</code></td>
+<td>Cell 4</td>
+</tr>
+</tbody>
+</table>
+.
+
+Escape before escaped Pipes inside backticks don't split cells:
+.
+| Heading 1 | Heading 2
+| --------- | ---------
+| Cell 1 | Cell 2
+| `Cell 3\\|` | Cell 4
+.
+<table>
+<thead>
+<tr>
+<th>Heading 1</th>
+<th>Heading 2</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Cell 1</td>
+<td>Cell 2</td>
+</tr>
+<tr>
+<td><code>Cell 3\|</code></td>
+<td>Cell 4</td>
+</tr>
+</tbody>
+</table>
+.
+
+Regression test for #721, table in a list indented with tabs:
+.
+- Level 1
+
+ - Level 2
+
+ | Column 1 | Column 2 |
+ | -------- | -------- |
+ | abcdefgh | ijklmnop |
+.
+<ul>
+<li>
+<p>Level 1</p>
+<ul>
+<li>
+<p>Level 2</p>
+<table>
+<thead>
+<tr>
+<th>Column 1</th>
+<th>Column 2</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>abcdefgh</td>
+<td>ijklmnop</td>
+</tr>
+</tbody>
+</table>
+</li>
+</ul>
+</li>
+</ul>
+.
+
+
+Table without any columns is not a table, #724
+.
+|
+|
+|
+.
+<p>|
+|
+|</p>
+.
+
+
+GFM 4.10 Tables (extension), Example 198
+.
+| foo | bar |
+| --- | --- |
+| baz | bim |
+.
+<table>
+<thead>
+<tr>
+<th>foo</th>
+<th>bar</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>baz</td>
+<td>bim</td>
+</tr>
+</tbody>
+</table>
+.
+
+GFM 4.10 Tables (extension), Example 199
+.
+| abc | defghi |
+:-: | -----------:
+bar | baz
+.
+<table>
+<thead>
+<tr>
+<th style="text-align:center">abc</th>
+<th style="text-align:right">defghi</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td style="text-align:center">bar</td>
+<td style="text-align:right">baz</td>
+</tr>
+</tbody>
+</table>
+.
+
+GFM 4.10 Tables (extension), Example 200
+.
+| f\|oo |
+| ------ |
+| b `\|` az |
+| b **\|** im |
+.
+<table>
+<thead>
+<tr>
+<th>f|oo</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>b <code>|</code> az</td>
+</tr>
+<tr>
+<td>b <strong>|</strong> im</td>
+</tr>
+</tbody>
+</table>
+.
+
+GFM 4.10 Tables (extension), Example 201
+.
+| abc | def |
+| --- | --- |
+| bar | baz |
+> bar
+.
+<table>
+<thead>
+<tr>
+<th>abc</th>
+<th>def</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>bar</td>
+<td>baz</td>
+</tr>
+</tbody>
+</table>
+<blockquote>
+<p>bar</p>
+</blockquote>
+.
+
+GFM 4.10 Tables (extension), Example 202
+.
+| abc | def |
+| --- | --- |
+| bar | baz |
+bar
+
+bar
+.
+<table>
+<thead>
+<tr>
+<th>abc</th>
+<th>def</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>bar</td>
+<td>baz</td>
+</tr>
+<tr>
+<td>bar</td>
+<td></td>
+</tr>
+</tbody>
+</table>
+<p>bar</p>
+.
+
+GFM 4.10 Tables (extension), Example 203
+.
+| abc | def |
+| --- |
+| bar |
+.
+<p>| abc | def |
+| — |
+| bar |</p>
+.
+
+GFM 4.10 Tables (extension), Example 204
+.
+| abc | def |
+| --- | --- |
+| bar |
+| bar | baz | boo |
+.
+<table>
+<thead>
+<tr>
+<th>abc</th>
+<th>def</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>bar</td>
+<td></td>
+</tr>
+<tr>
+<td>bar</td>
+<td>baz</td>
+</tr>
+</tbody>
+</table>
+.
+
+GFM 4.10 Tables (extension), Example 205
+.
+| abc | def |
+| --- | --- |
+.
+<table>
+<thead>
+<tr>
+<th>abc</th>
+<th>def</th>
+</tr>
+</thead>
+</table>
+.
+
+A list takes precedence in case of ambiguity
+.
+a | b
+- | -
+1 | 2
+.
+<p>a | b</p>
+<ul>
+<li>| -
+1 | 2</li>
+</ul>
+.
diff --git a/documents/markdown/markdown-it/text_decoration.md b/documents/markdown/markdown-it/text_decoration.md
new file mode 100644
index 0000000..02f0dd6
--- /dev/null
+++ b/documents/markdown/markdown-it/text_decoration.md
@@ -0,0 +1,288 @@
+# Adding New Text Decorators
+
+A step-by-step example of adding a new text decoration style via **inline rules**.
+
+## Goal
+
+Text surrounded by double-carets (e.g. `^^like this^^`) will be given the `<small>` tag in the output HTML.
+
+## Inline Rules
+
+Markdown-It processes inline sequences of text in **two** passes, each with their own list of rules:
+
+- Tokenization
+- Post Processing
+
+The Tokenization phase is responsible for **identifying** inline markers, like `**` (bold/strong text) or `^^` (our new "small text" delimiter).
+It is unaware of marker nesting, or whether markers form matched pairs.
+
+The Post Processing phase handles **matching** pairs of tokens.
+This phase holds a lot of hidden complexity.
+Base Markdown supports a single asterisk for italics/emphasis, double asterisk for bold/strong text, and triple asterisk for both styles combined.
+Even if a new plugin isn't implementing such a nuanced delimiter, an awareness of the complexity helps the developer inject code in the proper locations.
+
+> [!IMPORTANT]
+> Every matched-pair inline marker should provide **both** a tokenization and post-processing rule.
+
+## Entry Point
+
+The new rule will be named `smalltext`.
+The plugin entry point will look like the following:
+
+```typescript
+export default function smalltext_plugin(md: MarkdownIt) {
+ md.inline.ruler.after("emphasis", "smalltext", smalltext_tokenize)
+ md.inline.ruler2.after("emphasis", "smalltext", smalltext_postProcess)
+}
+
+function smalltext_tokenize(state: StateInline, silent: boolean) {
+ return false
+}
+
+function smalltext_postProcess(state: StateInline) {
+ return false
+}
+```
+
+Note the use of `ruler2` to register the post-processing step.
+This pattern is unique to matched-pair inline marker rules:
+it isn't seen anywhere else in the library (e.g. for block or core rules).
+
+## Tokenization
+
+All that needs to happen here is identifying the string `^^`,
+adding a Token to `state.tokens`,
+and adding a Delimiter to `state.delimiters`.
+
+> [!TIP]
+> A `delimiter` points to a token and provides extra information:
+>
+> - whether that token is a valid choice for opening or closing styled text
+> - a pointer to the matching end token
+> - information about how many characters the token is (useful for disambiguating italics and bold)
+>
+> Most of this information is used in the `balance_pairs` post-processing rule.
+> So long as the `delimiters` array is constructed well in the tokenization phase,
+> the developer doesn't need to worry about the complexity within `balance_pairs`.
+
+```typescript
+function smalltext_tokenize(state: StateInline, silent: boolean) {
+ const start = state.pos
+ const marker = state.src.charCodeAt(start)
+
+ if (silent) {
+ return false
+ }
+
+ if (marker !== 0x5e /* ^ */) {
+ return false
+ }
+
+ const scanned = state.scanDelims(state.pos, true)
+ let len = scanned.length
+ const ch = String.fromCharCode(marker)
+
+ if (len < 2) {
+ return false
+ }
+
+ let token
+
+ if (len % 2) {
+ token = state.push("text", "", 0)
+ token.content = ch
+ len--
+ }
+
+ for (let i = 0; i < len; i += 2) {
+ token = state.push("text", "", 0)
+ token.content = ch + ch
+
+ state.delimiters.push({
+ marker,
+ length: 0, // disable "rule of 3" length checks meant for emphasis
+ token: state.tokens.length - 1,
+ end: -1, // This pointer is filled in by the core balance_pairs post-processing rule
+ open: scanned.can_open,
+ close: scanned.can_close,
+ jump: 0
+ })
+ }
+
+ state.pos += scanned.length
+
+ return true
+}
+```
+
+Note the `scanDelims` call.
+It handles determining whether a given sequence of characters (`^` in this case) can start or end an inline styling sequence.
+
+A single caret will have no meaning in this plugin,
+so much of the complexity in this rule is removed:
+
+- For an odd-numbered length of carets, the first caret is added as plain text
+- The `length` property of the delimiters is always set to zero, skipping unnecessary logic in the `balance_pairs` rule
+
+Note also that **no matching was attempted in the tokenization phase**.
+The `end` property is always set to `-1`.
+The `balance_pairs` rule does all the heavy lifting later on, behind the scenes.
+
+## Post Processing
+
+### Grunt Work
+
+The main logic of this rule will go into a utility function, called `postProcess`.
+The top-level rule function gets a confusing bit of grunt work:
+
+```typescript
+function smalltext_postProcess(state: StateInline) {
+ const tokens_meta = state.tokens_meta
+ const max = state.tokens_meta.length
+
+ postProcess(state, state.delimiters)
+
+ for (let curr = 0; curr < max; curr++) {
+ if (tokens_meta[curr]?.delimiters) {
+ postProcess(state, tokens_meta[curr]?.delimiters || [])
+ }
+ }
+
+ // post-process return value is unused
+ return false
+}
+
+function postProcess(state: StateInline, delimiters: StateInline.Delimiter[]) {
+ return
+}
+```
+
+> [!TIP]
+> What is `tokens_meta`?
+>
+> Every time a token with a positive `nesting` value is pushed to the inline state's tokens (i.e. an opening tag),
+> the inline state does the following:
+>
+> - throws the current `delimiters` array onto a stack
+> - creates a new, empty `delimiters` array, exposing it as `state.delimiters`
+> - gives the open-tag token a `token_meta` object with the new `delimiters` array
+> - *also* stores the `token_meta` object in `state.tokens_meta`
+>
+> The intrepid reader will notice that in the tokenization rule, **the created delimiters were likely being pushed to different arrays** throughout execution.
+>
+> Now, in post-processing, each `delimiters` array will only hold delimiters at matching nesting levels.
+>
+> If the details of this implementation are of interest, check out [the source](https://github.com/markdown-it/markdown-it/blob/0fe7ccb4b7f30236fb05f623be6924961d296d3d/lib/rules_inline/state_inline.mjs#L60).
+
+### Main Logic
+
+As previously mentioned, `balance_pairs` took care of building out and cleaning up the delimiter data.
+This post-processing rule will mainly read the data and add tokens as appropriate:
+
+```typescript
+function postProcess(state: StateInline, delimiters: StateInline.Delimiter[]) {
+ let token
+ const loneMarkers = []
+ const max = delimiters.length
+
+ for (let i = 0; i < max; i++) {
+ const startDelim = delimiters[i]
+
+ if (startDelim.marker !== 0x5e /* ^ */) {
+ continue
+ }
+
+ // balance_pairs wrote the appropriate `end` pointer value here.
+ // If it's still -1, there was a balancing problem,
+ // and the delimiter can be ignored.
+ if (startDelim.end === -1) {
+ continue
+ }
+
+ const endDelim = delimiters[startDelim.end]
+
+ token = state.tokens[startDelim.token]
+ token.type = "smalltext_open"
+ token.tag = "small"
+ token.nesting = 1
+ token.markup = "^^"
+ token.content = ""
+
+ token = state.tokens[endDelim.token]
+ token.type = "smalltext_close"
+ token.tag = "small"
+ token.nesting = -1
+ token.markup = "^^"
+ token.content = ""
+
+ if (
+ state.tokens[endDelim.token - 1].type === "text" &&
+ state.tokens[endDelim.token - 1].content === "^"
+ ) {
+ loneMarkers.push(endDelim.token - 1)
+ }
+ }
+
+ // If a marker sequence has an odd number of characters, it is split
+ // like this: `^^^^^` -> `^` + `^^` + `^^`, leaving one marker at the
+ // start of the sequence.
+ //
+ // So, we have to move all those markers after subsequent closing tags.
+ //
+ while (loneMarkers.length) {
+ const i = loneMarkers.pop() || 0
+ let j = i + 1
+
+ while (j < state.tokens.length && state.tokens[j].type === "smalltext_close") {
+ j++
+ }
+
+ j--
+
+ if (i !== j) {
+ token = state.tokens[j]
+ state.tokens[j] = state.tokens[i]
+ state.tokens[i] = token
+ }
+ }
+}
+```
+
+The lone-marker handling is a point of interest.
+While a five- or seven-character sequence of carets is unlikely,
+it could still be matched with a different string of carets elsewhere in the line of text.
+Due to how tokenization runs,
+both the opening **and** closing sequences are split leaving the lone caret at the start:
+
+```
+^^^^^^^hey this text would actually be small^^^^^^^
+
+gets parsed somewhat like this:
+
+^ ^^ ^^ ^^ hey this text would actually be small ^ ^^ ^^ ^^
+| | | | | |
+| | opening tag | | open and close
+| open and close | balanced closing tag
+lone caret lone caret
+```
+
+Because the very first caret in the opening sequence is *not* placed within the `<small>` tags,
+neither should the first caret in the closing sequence.
+The end of the post-processing rule handles that edge case.
+
+## Conclusion
+
+That's everything!
+
+This rule is almost a verbatim copy of the [strikethrough rule](https://github.com/markdown-it/markdown-it/blob/0fe7ccb4b7f30236fb05f623be6924961d296d3d/lib/rules_inline/strikethrough.mjs) in the core library.
+If a full-on emphasis-style rule is desired, the [source code](https://github.com/markdown-it/markdown-it/blob/0fe7ccb4b7f30236fb05f623be6924961d296d3d/lib/rules_inline/emphasis.mjs) isn't much longer,
+thanks in large part to the heavy lifting that [balance_pairs](https://github.com/markdown-it/markdown-it/blob/0fe7ccb4b7f30236fb05f623be6924961d296d3d/lib/rules_inline/balance_pairs.mjs) accomplishes.
+
+> [!CAUTION]
+>
+> If the plugin being developed is a "standalone" inline element without a open/close pair
+> (think about links `[text](url)` or images ``),
+> **the post-processing infrastructure can be safely ignored**!
+> Markdown parsing is complicated enough.
+> Please don't introduce any unnecessary complexity!
+
diff --git a/documents/markdown/markdown-it/typographer.md b/documents/markdown/markdown-it/typographer.md
new file mode 100644
index 0000000..9e4bd76
--- /dev/null
+++ b/documents/markdown/markdown-it/typographer.md
@@ -0,0 +1,110 @@
+.
+(bad)
+.
+<p>(bad)</p>
+.
+
+
+copyright
+.
+(c) (C)
+.
+<p>© ©</p>
+.
+
+
+reserved
+.
+(r) (R)
+.
+<p>® ®</p>
+.
+
+
+trademark
+.
+(tm) (TM)
+.
+<p>™ ™</p>
+.
+
+
+plus-minus
+.
++-5
+.
+<p>±5</p>
+.
+
+
+ellipsis
+.
+test.. test... test..... test?..... test!....
+.
+<p>test… test… test… test?.. test!..</p>
+.
+
+
+dupes
+.
+!!!!!! ???? ,,
+.
+<p>!!! ??? ,</p>
+.
+
+copyright should be escapable
+.
+\(c)
+.
+<p>(c)</p>
+.
+
+shouldn't replace entities
+.
+(c) (c) (c)
+.
+<p>(c) (c) ©</p>
+.
+
+
+dashes
+.
+---markdownit --- super---
+
+markdownit---awesome
+
+abc ----
+
+--markdownit -- super--
+
+markdownit--awesome
+.
+<p>—markdownit — super—</p>
+<p>markdownit—awesome</p>
+<p>abc ----</p>
+<p>–markdownit – super–</p>
+<p>markdownit–awesome</p>
+.
+
+dashes should be escapable
+.
+foo \-- bar
+
+foo -\- bar
+.
+<p>foo -- bar</p>
+<p>foo -- bar</p>
+.
+
+regression tests for #624
+.
+1---2---3
+
+1--2--3
+
+1 -- -- 3
+.
+<p>1—2—3</p>
+<p>1–2–3</p>
+<p>1 – – 3</p>
+.
diff --git a/documents/markdown/markdown-it/xss.md b/documents/markdown/markdown-it/xss.md
new file mode 100644
index 0000000..7c0512e
--- /dev/null
+++ b/documents/markdown/markdown-it/xss.md
@@ -0,0 +1,128 @@
+.
+[normal link](javascript)
+.
+<p><a href="javascript">normal link</a></p>
+.
+
+
+Should not allow some protocols in links and images
+.
+[xss link](javascript:alert(1))
+
+[xss link](JAVASCRIPT:alert(1))
+
+[xss link](vbscript:alert(1))
+
+[xss link](VBSCRIPT:alert(1))
+
+[xss link](file:///123)
+.
+<p>[xss link](javascript:alert(1))</p>
+<p>[xss link](JAVASCRIPT:alert(1))</p>
+<p>[xss link](vbscript:alert(1))</p>
+<p>[xss link](VBSCRIPT:alert(1))</p>
+<p>[xss link](file:///123)</p>
+.
+
+
+.
+[xss link]("><script>alert("xss")</script>)
+
+[xss link](Javascript:alert(1))
+
+[xss link](&#74;avascript:alert(1))
+
+[xss link](\Javascript:alert(1))
+.
+<p><a href="%22%3E%3Cscript%3Ealert(%22xss%22)%3C/script%3E">xss link</a></p>
+<p>[xss link](Javascript:alert(1))</p>
+<p><a href="&#74;avascript:alert(1)">xss link</a></p>
+<p><a href="&#74;avascript:alert(1)">xss link</a></p>
+.
+
+.
+[xss link](<javascript:alert(1)>)
+.
+<p>[xss link](<javascript:alert(1)>)</p>
+.
+
+.
+[xss link](javascript:alert(1))
+.
+<p>[xss link](javascript:alert(1))</p>
+.
+
+
+Should not allow data-uri except some whitelisted mimes
+.
+
+.
+<p><img src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7" alt=""></p>
+.
+
+.
+[xss link](data:text/html;base64,PHNjcmlwdD5hbGVydCgnWFNTJyk8L3NjcmlwdD4K)
+.
+<p>[xss link](data:text/html;base64,PHNjcmlwdD5hbGVydCgnWFNTJyk8L3NjcmlwdD4K)</p>
+.
+
+.
+[normal link](/javascript:link)
+.
+<p><a href="/javascript:link">normal link</a></p>
+.
+
+
+Image parser use the same code base as link.
+.
+)
+.
+<p>)</p>
+.
+
+
+Autolinks
+.
+<javascript:alert(1)>
+
+<javascript:alert(1)>
+.
+<p><javascript:alert(1)></p>
+<p><javascript:alert(1)></p>
+.
+
+
+Linkifier
+.
+javascript:alert(1)
+
+javascript:alert(1)
+.
+<p>javascript:alert(1)</p>
+<p>javascript:alert(1)</p>
+.
+
+
+References
+.
+[test]: javascript:alert(1)
+.
+<p>[test]: javascript:alert(1)</p>
+.
+
+
+Make sure we decode entities before split:
+.
+```js custom-class
+test1
+```
+
+```jscustom-class
+test2
+```
+.
+<pre><code class="js">test1
+</code></pre>
+<pre><code class="js">test2
+</code></pre>
+.
diff --git a/documents/markdown/markdownlint/.github_ISSUE_TEMPLATE_BUG_TEMPLATE.md b/documents/markdown/markdownlint/.github_ISSUE_TEMPLATE_BUG_TEMPLATE.md
new file mode 100644
index 0000000..8636a48
--- /dev/null
+++ b/documents/markdown/markdownlint/.github_ISSUE_TEMPLATE_BUG_TEMPLATE.md
@@ -0,0 +1,22 @@
+---
+name: 🐛 Bug Report
+about: If something isn't working as expected 🤔.
+labels: "bug"
+---
+## Description
+<!--- Briefly describe the issue -->
+
+### Environment
+<!--- Tell us any details about the environment where you're running mdl. -->
+**MDL Version**
+<!--- Tell us which version of mdl you are using. -->
+
+### Expected Behavior
+<!-- Tell us what should happen -->
+
+### Actual Behavior
+<!-- Tell us what happens instead; including any error messages, stacktraces, or a link to a gist with it. -->
+
+## Replication Case
+<!--- Tell us what steps to take to replicate your problem, don't just say what you did, but explain how you did it. See [How to create a Minimal, Complete, and Verifiable example](https://stackoverflow.com/help/mcve)
+for information on how to create a good replication case -->
diff --git a/documents/markdown/markdownlint/.github_ISSUE_TEMPLATE_DESIGN_PROPOSAL.md b/documents/markdown/markdownlint/.github_ISSUE_TEMPLATE_DESIGN_PROPOSAL.md
new file mode 100644
index 0000000..ddc8149
--- /dev/null
+++ b/documents/markdown/markdownlint/.github_ISSUE_TEMPLATE_DESIGN_PROPOSAL.md
@@ -0,0 +1,40 @@
+---
+name: Design Proposal
+about: I have a significant change I would like to propose and discuss before starting
+labels: "design proposal"
+---
+
+### When a Change Needs a Design Proposal
+
+A design proposal should be opened any time a change meets one of the following qualifications:
+
+- Significantly changes the user experience of a project in a way that impacts users.
+- Significantly changes the underlying architecture of the project in a way that impacts other developers.
+- Changes the development or testing process of the project such as a change of CI systems or test frameworks.
+
+### Why We Use This Process
+
+- Allows all interested parties (including any community member) to discuss large impact changes to a project.
+- Serves as a durable paper trail for discussions regarding project architecture.
+- Forces design discussions to occur before PRs are created.
+- Reduces PR refactoring and rejected PRs.
+
+---
+
+<!--- Proposal description and rationale. -->
+
+## Motivation
+
+<!---
+ As a <<user_profile>>,
+ I want to <<functionality>>,
+ so that <<benefit>>.
+ -->
+
+## Specification
+
+<!--- A detailed description of the planned implementation. -->
+
+## Downstream Impact
+
+<!--- Which other tools will be impacted by this work? -->
diff --git a/documents/markdown/markdownlint/.github_ISSUE_TEMPLATE_ENHANCEMENT_REQUEST.md b/documents/markdown/markdownlint/.github_ISSUE_TEMPLATE_ENHANCEMENT_REQUEST.md
new file mode 100644
index 0000000..fcbe7f8
--- /dev/null
+++ b/documents/markdown/markdownlint/.github_ISSUE_TEMPLATE_ENHANCEMENT_REQUEST.md
@@ -0,0 +1,20 @@
+---
+name: 🚀 Enhancement Request
+about: I have a suggestion (and may want to implement it 🙂)!
+labels: "enhancement"
+---
+
+## Describe the Enhancement:
+<!--- What you are trying to achieve that you can't? -->
+
+### Impacted Rules:
+<!-- List any existing rules that would be impacted or changed by this enhancement -->
+
+## Describe the Need:
+<!--- What kind of user do you believe would utilize this enhancement, and how many users might want this functionality -->
+
+## Current Alternative
+<!--- Is there a current alternative that you can utilize to workaround the lack of this enhancement -->
+
+## Can We Help You Implement This?:
+<!--- The best way to ensure your enhancement is built is to help implement the enhancement yourself. If you're interested in helping out we'd love to give you a hand to make this possible. Let us know if there's something you need. -->
diff --git a/documents/markdown/markdownlint/.github_ISSUE_TEMPLATE_RULE_REQUEST.md b/documents/markdown/markdownlint/.github_ISSUE_TEMPLATE_RULE_REQUEST.md
new file mode 100644
index 0000000..144b429
--- /dev/null
+++ b/documents/markdown/markdownlint/.github_ISSUE_TEMPLATE_RULE_REQUEST.md
@@ -0,0 +1,20 @@
+---
+name: 💪 Rule Request
+about: I have a suggestion for a new rule for markdownlint (and may want to implement it 🙌)!
+labels: "new rule"
+---
+
+## New Rule Checklist
+
+Before suggesting a rule for inclusion please make sure your suggestion meets these criteria for rule built into markdownlint:
+ - [ ] allows a user to lint for a specific syntax divergence across the multiple flavors and styles of markdown
+ - [ ] does not dictate any one specific style, but enables an end user to enable, disable, or configure the specific style of enforcement desired
+
+## Describe The Rule:
+<!--- Tell us about the rule -->
+
+## Why Should This Be Included In Markdownlint?:
+<!--- Tell us why you believe this rule should be added, considering any possible side-effects, negative impact, or changes to the behavior of existing rules -->
+
+## Can We Help You Implement This?:
+<!--- The best way to move a rule into markdownlint is to create it yourself. If you're interested in helping out we'd love to give you a hand to make this possible. Let us know if there's something you need. -->
diff --git a/documents/markdown/markdownlint/.github_PULL_REQUEST_TEMPLATE.md b/documents/markdown/markdownlint/.github_PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..582cf3f
--- /dev/null
+++ b/documents/markdown/markdownlint/.github_PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,23 @@
+## Description
+<!--- Describe your changes in detail, what problems does it solve? See [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) for tips on writing a good commit message -->
+
+## Related Issues
+<!--- If you are suggesting a new feature or change, please create an issue first -->
+<!--- Add a link to all corresponding GitHub issues here, using any [appropriate keywords](https://help.github.com/en/articles/closing-issues-using-keywords) as appropriate -->
+
+## Types of changes
+<!--- What types of changes does your code introduce? Put an `x` in all the boxes that apply: -->
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] Documentation (non-breaking change that does not add functionality but updates documentation)
+- [ ] Chore (non-breaking change that does not add functionality or fix an issue)
+
+## Checklist:
+<!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
+<!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
+- [ ] I have read the [**CONTRIBUTING**](https://github.com/markdownlint/markdownlint/blob/main/CONTRIBUTING.md) document.
+- [ ] Wrote [good commit messages](https://chris.beams.io/posts/git-commit/)
+- [ ] Feature branch is up-to-date with `main`, if not - rebase it
+- [ ] Added tests for all new/changed functionality, including tests for positive and negative scenarios
+- [ ] The PR relates to *only* one subject with a clear title and description in grammatically correct, complete sentences
diff --git a/documents/markdown/markdownlint/CHANGELOG.md b/documents/markdown/markdownlint/CHANGELOG.md
new file mode 100644
index 0000000..3e7df06
--- /dev/null
+++ b/documents/markdown/markdownlint/CHANGELOG.md
@@ -0,0 +1,368 @@
+# Change Log
+
+## Unreleased
+
+## [v0.15.0] (2025-11-25)
+
+### Changed
+
+* Bumped minum ruby version to 3.2
+ [#531](https://github.com/markdownlint/markdownlint/pull/531), and associated
+ changes
+
+## [v0.14.0] (2025-11-25)
+
+### Fixed
+
+* Fix Markdown lint version in SARIF output test
+ [#469](https://github.com/markdownlint/markdownlint/pull/469)
+* Fix example for rulesets flag in configuration docs
+ [#473](https://github.com/markdownlint/markdownlint/pull/473)
+* Require ruby-3.3.0 for standalone pre-commit hook
+ [#528](https://github.com/markdownlint/markdownlint/pull/528)
+
+### Rules Removed
+
+* Removed MD055, MD056, MD057 - These rules for tables caused regressions and
+ were removed (see
+ [#472](https://github.com/markdownlint/markdownlint/issues/472) for details)
+
+## [v0.13.0] (2023-10-01)
+
+### Rules Added
+
+* MD055 - Tables: Each row must start and end with a `|` [#464](https://github.com/markdownlint/markdownlint/pull/464)
+* MD056 - Tables: Number of columns is the same for all
+ rows [#464](https://github.com/markdownlint/markdownlint/pull/464)
+* MD057 - Tables: In the second row every column must have at least `---`,
+ possibly surrounded with alignment `:` chars [#464](https://github.com/markdownlint/markdownlint/pull/464)
+
+### Added
+
+* Add SARIF output [#459](https://github.com/markdownlint/markdownlint/pull/459)
+* Document DCO process better [#448](https://github.com/markdownlint/markdownlint/pull/448)
+ and [#449](https://github.com/markdownlint/markdownlint/pull/449)
+
+### Changed
+
+* MD009 - Allow exactly 2 trailing spaces by default [#452](https://github.com/markdownlint/markdownlint/pull/452)
+* MD033 - Add `allowed_elements` parameter [#450](https://github.com/markdownlint/markdownlint/pull/450)
+* Updated build instructions [#431](https://github.com/markdownlint/markdownlint/pull/431)
+
+### Fixed
+
+* MD027 - handle anchor elements correctly [#463](https://github.com/markdownlint/markdownlint/pull/463)
+* Fix examples for RULES.md for MD007 [#462](https://github.com/markdownlint/markdownlint/pull/462)
+* Fix links to use https instead of http [#447](https://github.com/markdownlint/markdownlint/pull/447)
+* Make RULES.md comply with our own rules [#439](https://github.com/markdownlint/markdownlint/pull/439)
+* Fix docker builds [#429](https://github.com/markdownlint/markdownlint/pull/429)
+
+## [v0.12.0] (2022-10-17)
+
+### Rules Added
+
+* MD047 - File should end with a blank line
+
+### Added
+
+* New 'docs' method on rules to provide a URL and longer description
+* `docker_image`-based pre-commit
+
+### Changed
+
+* Changed the default for MD007 to 3 spaces to match minimum spaces for ordered lists
+* Added option `:ignore_code_blocks` to rule MD010. If set to true, hard tabs in
+ code blocks will be ignored.
+* Added option `:ignore_code_blocks` to rule MD013. If set to true, hard tabs in
+ code blocks will be ignored. The option `:code_blocks` has been marked as
+ deprecated in the documentation. If `:code_blocks` is set to false in the
+ configuration, a deprecation warning is printed.
+* Improved documentation on custom rules and rulesets
+* Handle non-printable characters gracefully
+* Support configurable sublist styles for MD004
+
+### Fixed
+
+* Fixed directory argument with `--git-recurse`
+* Preserve empty lines at the end of a file
+
+## [v0.11.0] (2020-08-22)
+
+### Fixed
+
+* Fixed crash when using `-g`
+* Fixed missing dependencies in docker image
+
+## [v0.10.0] (2020-08-08)
+
+### Added
+
+* More examples of mdlrc and style files
+* Added CI for Rubocop and Markdownlint on our own repo
+
+### Fixed
+
+* Update Dockerfile to work with modern mdl
+* Update minimum version of kramdown for security advisory
+* Update minimum version of rubocop for security advisory
+
+## [v0.9.0] (2020-02-21)
+
+### Changed
+
+* Better error messages on missing styles [#302](https://github.com/markdownlint/markdownlint/pull/302)
+* Use require_relative to speed up requires [#297](https://github.com/markdownlint/markdownlint/pull/297)
+* Bumped alpine version in the Dockerfile [#155](https://github.com/markdownlint/markdownlint/pull/155)
+
+### Fixed
+
+* Fix crash in --json [#286](https://github.com/markdownlint/markdownlint/pull/286)
+* Handle codeblocks that are nested [#293](https://github.com/markdownlint/markdownlint/pull/293)
+* Fix handling of blockquoted list items [#284](https://github.com/markdownlint/markdownlint/pull/284)
+
+## [v0.8.0] (2019-11-08)
+
+### Changed
+
+* Don't ship test / example files in the gem artifact [#282](https://github.com/markdownlint/markdownlint/pull/282)
+
+### Fixed
+
+* Handle newlines on Windows better [#238](https://github.com/markdownlint/markdownlint/pull/238)
+
+## [v0.7.0] (2019-10-24)
+
+### Added
+
+* Pull request and issue templates for users and contributors
+* Move to kramdown 2
+* Handle Kramdown TOC
+* Loosen various dependencies and move minimum ruby version to 2.4
+
+## [v0.6.0] (2019-10-19)
+
+### Added
+
+* There are now CONTRIBUTING.md and MAINTAINERS.md docs
+* There is now a `.pre-commit-hooks.yaml` for those who want to use pre-commit.com
+
+### Changed
+
+* Ignore blank line after front matter [#248](https://github.com/markdownlint/markdownlint/pull/248)
+* Only import JSON when necessary [#231](https://github.com/markdownlint/markdownlint/pull/231)
+* Use newere mixlib-cli [#265](https://github.com/markdownlint/markdownlint/pull/265)
+* Nicer error message when activating nonexistent rule [#246](https://github.com/markdownlint/markdownlint/pull/246)
+* Fix documentation on `ignore_front_matter` [#241](https://github.com/markdownlint/markdownlint/pull/241)
+* Update docs to use "MY" prefix for custom rule example [#245](https://github.com/markdownlint/markdownlint/pull/245)
+* Fix crash in MD039 when the link text is empty [#256](https://github.com/markdownlint/markdownlint/pull/256)
+* Reference Node.js markdownlint [#229](https://github.com/markdownlint/markdownlint/pull/229)
+* Added table of contents to RULES.md for easier
+ navigation [#232](https://github.com/markdownlint/markdownlint/pull/232)
+* Fix typos in MD046 docs [#219](https://github.com/markdownlint/markdownlint/pull/219)
+* Fixed MD036 crash [#222](https://github.com/markdownlint/markdownlint/pull/222)
+
+### Removed
+
+## [v0.5.0] (2018-07-01)
+
+### Added
+
+* Add md042 to enforce code block style
+* JSON formatter/output
+
+### Changed
+
+* Allow different nesting on headers duplication check [#200](https://github.com/markdownlint/markdownlint/pull/200)
+* MD036 - Ignore multi-line emphasized paragraphs, and emphasized paragraphs
+ that end in punctuation [#140](https://github.com/markdownlint/markdownlint/pull/140)
+
+### Fixed
+
+* Fix issue numbers false positives [#168](https://github.com/markdownlint/markdownlint/pull/168)
+* Lint MD039 checking for nodes inside link text [#102](https://github.com/markdownlint/markdownlint/issues/102)
+
+## [v0.4.0] (2016-08-22)
+
+### Added
+
+* Ignore yaml front matter option [#130](https://github.com/markdownlint/markdownlint/pull/130)
+ and [#143](https://github.com/markdownlint/markdownlint/pull/143)
+
+### Changed
+
+* Allow top level header rules (MD002, MD025, MD041) to be
+ configurable [#142](https://github.com/markdownlint/markdownlint/pull/142)
+
+### Fixed
+
+* Read UTF-8 files correctly even if locale is set to
+ C [#135](https://github.com/markdownlint/markdownlint/pull/135),
+ [#146](https://github.com/markdownlint/markdownlint/pull/146),
+ [#147](https://github.com/markdownlint/markdownlint/pull/147)
+ and [#148](https://github.com/markdownlint/markdownlint/pull/148)
+* Fix issues loading .mdlrc
+ file [#126](https://github.com/markdownlint/markdownlint/pull/126),
+ [#129](https://github.com/markdownlint/markdownlint/pull/129),
+ [#133](https://github.com/markdownlint/markdownlint/pull/133)
+ and [#148](https://github.com/markdownlint/markdownlint/pull/148)
+* Fix erroneous triggering of MD022/MD023 in some cases [#144](https://github.com/markdownlint/markdownlint/pull/144)
+* Detect codeblock lines correctly when ignoring them [#141](https://github.com/markdownlint/markdownlint/pull/141)
+
+## [v0.3.1] (2016-03-20)
+
+### Fixed
+
+* Fix error on starting mdl
+
+## [v0.3.0] (2016-03-19)
+
+### Rules added
+
+* MD041 - First line in file should be a top level header
+
+### Added
+
+* You can now load your own custom rules with the `-u` option. See
+ [rules.rb](https://github.com/markdownlint/markdownlint/blob/main/lib/mdl/rules.rb)
+ for an example of what a rules file looks like. Use the `-d` option if you
+ don't want to load markdownlint's default ruleset.
+* You can now refer to rules by human-readable/writable aliases, such as
+ 'ul-style' instead of 'MD004'. See RULES.md for a list of the rule aliases.
+ You can pass the `-a` option to display rule aliases instead of MDxxx rule
+ IDs.
+
+### Changed
+
+* MD003 - An additional header style, setext_with_atx, was added to require
+ setext style headers for levels 1 and 2, but allow atx style headers for
+ levels 3 and above (i.e. header levels that can't be expressed with setext
+ style headers)
+* MD013 - You now have the option to exclude code blocks and tables from the
+ line length limit check.
+
+### Fixed
+
+* Crash with MD034 and pipe character [#93](https://github.com/markdownlint/markdownlint/pull/93)
+ and [#97](https://github.com/markdownlint/markdownlint/pull/97)
+* MD031 failed on nested code blocks [#100](https://github.com/markdownlint/markdownlint/pull/100)
+ and [#109](https://github.com/markdownlint/markdownlint/pull/109)
+* MD037 crashes on <li> with underscores [#83](https://github.com/markdownlint/markdownlint/pull/83)
+* Regression introduced in v0.2.1 - ignoring rules/tags on the command line
+ caused a crash [#108](https://github.com/markdownlint/markdownlint/pull/108)
+* MD027 false positive when line starts with a backtick [#105](https://github.com/markdownlint/markdownlint/pull/105)
+
+### Merged pull requests
+
+* [Add support for nested code fences to MD031/MD032 - David
+ Anson](https://github.com/markdownlint/markdownlint/pull/109)
+* [Add missing word to description of MD035 in RULES.md - David
+ Anson](https://github.com/markdownlint/markdownlint/pull/86)
+* [Probe for .mdlrc in current and parent directories - Loic
+ Nageleisen](https://github.com/markdownlint/markdownlint/pull/111)
+* [MD013: allow excluding code blocks and tables - Loic
+ Nageleisen](https://github.com/markdownlint/markdownlint/pull/112)
+
+## [v0.2.1] (2015-04-13)
+
+### Fixed
+
+* Incorrect parsing of rules/tags specification in .mdlrc [#81](https://github.com/markdownlint/markdownlint/pull/81)
+* Exception on image links with MD039 [#82](https://github.com/markdownlint/markdownlint/pull/82)
+* MD037 flags on two words beginning with underscores on the same
+ line [#83](https://github.com/markdownlint/markdownlint/pull/83)
+
+### Known issues
+
+* Exception on some lines with raw html list items in them [#83](https://github.com/markdownlint/markdownlint/pull/83)
+
+## [v0.2.0] (2015-04-13)
+
+### Rules added
+
+* MD033 - Inline HTML
+* MD034 - Bare URL used
+* MD035 - Horizontal rule style
+* MD036 - Emphasis used instead of a header
+* MD037 - Spaces inside emphasis markers
+* MD038 - Spaces inside code span elements
+* MD039 - Spaces inside link text
+* MD040 - Fenced code blocks should have a language specified
+
+## Added
+
+* Trailing spaces rule should allow an excemption for deliberate <br/\>
+ insertion.
+* Rules can be excluded in .mdlrc and on the command line by specifying a rule
+ as ~MD000.
+
+### Merged pull requests
+
+* [Add parameter (value and default) information to rule documentation. - David Anson](https://github.com/markdownlint/markdownlint/pull/76)
+
+## [v0.1.0] (2015-02-22)
+
+### Rules added
+
+* MD031 - Fenced code blocks should be surrounded by blank lines
+* MD032 - Lists should be surrounded by blank lines
+
+### Fixed
+
+* MD014 triggers when it shouldn't
+
+### Merged pull requests
+
+* [MD032 - Lists should be surrounded by blank lines - David Anson](https://github.com/markdownlint/markdownlint/pull/70)
+* [MD031 - Fenced code blocks should be surrounded by blank lines - David Anson](https://github.com/markdownlint/markdownlint/pull/68)
+* [Clarify how to specify your own style - mjankowski](https://github.com/markdownlint/markdownlint/pull/65)
+* [Use single quotes to prevent early escaping - highb](https://github.com/markdownlint/markdownlint/pull/64)
+
+## [v0.0.1] (2014-09-07)
+
+### Rules added
+
+* MD001 - Header levels should only increment by one level at a time
+* MD002 - First header should be a h1 header
+* MD003 - Header style
+* MD004 - Unordered list style
+* MD005 - Inconsistent indentation for list items at the same level
+* MD006 - Consider starting bulleted lists at the beginning of the line
+* MD007 - Unordered list indentation
+* MD009 - Trailing spaces
+* MD010 - Hard tabs
+* MD011 - Reversed link syntax
+* MD012 - Multiple consecutive blank lines
+* MD013 - Line length
+* MD014 - Dollar signs used before commands without showing output
+* MD018 - No space after hash on atx style header
+* MD019 - Multiple spaces after hash on atx style header
+* MD020 - No space inside hashes on closed atx style header
+* MD021 - Multiple spaces inside hashes on closed atx style header
+* MD022 - Headers should be surrounded by blank lines
+* MD023 - Headers must start at the beginning of the line
+* MD024 - Multiple headers with the same content
+* MD025 - Multiple top level headers in the same document
+* MD026 - Trailing punctuation in header
+* MD027 - Multiple spaces after blockquote symbol
+* MD028 - Blank line inside blockquote
+* MD029 - Ordered list item prefix
+* MD030 - Spaces after list markers
+
+[v0.15.0]: https://github.com/markdownlint/markdownlint/tree/v0.15.0
+[v0.14.0]: https://github.com/markdownlint/markdownlint/tree/v0.14.0
+[v0.13.0]: https://github.com/markdownlint/markdownlint/tree/v0.13.0
+[v0.12.0]: https://github.com/markdownlint/markdownlint/tree/v0.12.0
+[v0.11.0]: https://github.com/markdownlint/markdownlint/tree/v0.11.0
+[v0.10.0]: https://github.com/markdownlint/markdownlint/tree/v0.10.0
+[v0.9.0]: https://github.com/markdownlint/markdownlint/tree/v0.9.0
+[v0.8.0]: https://github.com/markdownlint/markdownlint/tree/v0.8.0
+[v0.7.0]: https://github.com/markdownlint/markdownlint/tree/v0.7.0
+[v0.6.0]: https://github.com/markdownlint/markdownlint/tree/v0.6.0
+[v0.5.0]: https://github.com/markdownlint/markdownlint/tree/v0.5.0
+[v0.4.0]: https://github.com/markdownlint/markdownlint/tree/v0.4.0
+[v0.3.1]: https://github.com/markdownlint/markdownlint/tree/v0.3.1
+[v0.3.0]: https://github.com/markdownlint/markdownlint/tree/v0.3.0
+[v0.2.1]: https://github.com/markdownlint/markdownlint/tree/v0.2.1
+[v0.2.0]: https://github.com/markdownlint/markdownlint/tree/v0.2.0
+[v0.1.0]: https://github.com/markdownlint/markdownlint/tree/v0.1.0
+[v0.0.1]: https://github.com/markdownlint/markdownlint/tree/v0.0.1
diff --git a/documents/markdown/markdownlint/CONTRIBUTING.md b/documents/markdown/markdownlint/CONTRIBUTING.md
new file mode 100644
index 0000000..424b424
--- /dev/null
+++ b/documents/markdown/markdownlint/CONTRIBUTING.md
@@ -0,0 +1,127 @@
+# Contributing to Markdownlint
+
+We're glad you want to contribute markdownlint! This document will help answer
+common questions you may have during your first contribution. Please, try to
+follow these guidelines when you do so.
+
+## Issue Reporting
+
+Not every contribution comes in the form of code. Submitting, confirming, and
+triaging issues is an important task for any project. We use GitHub to track
+all project issues. If you discover bugs, have ideas for improvements or new
+features, please start by [opening an
+issue](https://github.com/markdownlint/markdownlint/issues) on this repository.
+We use issues to centralize the discussion and agree on a plan of action before
+spending time and effort writing code that might not get used.
+
+### Submitting An Issue
+
+* Check that the issue has not already been reported
+* Check that the issue has not already been fixed in the latest code
+ (a.k.a. `main`)
+* Select the appropriate issue type and open an issue with a descriptive title
+* Be clear, concise, and precise using grammatically correct, complete sentences
+ in your summary of the problem
+* Include the output of `mdl -V` or `mdl --version`
+* Include any relevant code in the issue
+
+## Code Contributions
+
+Markdownlint follows a [forking
+workflow](https://guides.github.com/activities/forking/), and we have a simple
+process for contributions:
+
+1. Open an issue on the [project
+ repository](https://github.com/markdownlint/markdownlint/issues), if
+ appropriate
+1. If you're adding or making changes to rules, read the [Development
+ docs](#local-development)
+1. Follow the [forking workflow](https://guides.github.com/activities/forking/)
+ steps:
+ 1. Fork the project ( <https://github.com/markdownlint/markdownlint/fork> )
+ 1. Create your feature branch (`git checkout -b my-new-feature`)
+ 1. Commit your changes (`git commit -am 'Add some feature'`)
+ 1. Sign your changes (`git commit --amend -s`)
+ 1. Push to the branch (`git push origin my-new-feature`)
+1. Create a [GitHub Pull
+ Request](https://help.github.com/articles/about-pull-requests/) for your
+ change, following all [pull request
+ requirements](#pull-request-requirements) and any instructions in the pull
+ request template
+1. Participate in a [Code Review](#code-review-process) with the project
+ maintainers on the pull request
+
+### Your First Code Contribution
+
+Unsure where to begin contributing to Markdownlint? You can start by looking
+through these beginner and help-wanted issues:
+
+* [Beginner issues](https://github.com/markdownlint/markdownlint/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+sort%3Acomments-desc)
+ * Issues which should only require a few lines of code, and a test or two.
+* [Help wanted issues](https://github.com/markdownlint/markdownlint/issues?q=is%3aissue+is%3aopen+label%3a%22help+wanted%22+sort%3Acomments-desc)
+ * Issues which should be a bit more involved than beginner issues. Both
+ issue lists are sorted by total number of comments. While not perfect,
+ number of comments is a reasonable proxy for impact a given change will
+ have.
+
+### Pull Request Requirements
+
+Markdownlint strives to ensure high quality for the project. In order to
+promote this, we require that all pull requests to meet these specifications:
+
+* **Tests:** To ensure high quality code and protect against future
+ regressions, we require tests for all new/changed functionality in
+ Markdownlint. Test positive and negative scenarios, try to break the new code
+ now.
+* **Green CI Tests:** We use [GitHub
+ Actions](https://github.com/markdownlint/markdownlint/actions) to test all pull
+ requests. We require these test runs to succeed on every pull request before
+ being merged.
+* **Signed Commits:** With [Developer Certificates of
+ Origin](https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin), we
+ want to ascertain your contribution rightfully may enter the project. GitHub
+ hence [automatically checks](https://github.com/apps/dco) your PR in line as
+ one prerequisite for a merge. For additional context, see e.g. the discussion
+ on
+ [stackoverflow](https://stackoverflow.com/questions/1962094/what-is-the-sign-off-feature-in-git-for)
+ or the reasoning on
+ [ProgressChef](https://www.chef.io/blog/introducing-developer-certificate-of-origin).
+
+### Code Review Process
+
+Code review takes place in GitHub pull requests. See [this
+article](https://help.github.com/articles/about-pull-requests/) if you're not
+familiar with GitHub Pull Requests.
+
+Once you open a pull request, project maintainers will review your code and
+respond to your pull request with any feedback they might have. The process at
+this point is as follows:
+
+1. A review is required from at least one of the project maintainers. See the
+ maintainers document for Markdownlint project at
+ <https://github.com/markdownlint/markdownlint/blob/main/MAINTAINERS.md>.
+1. Your change will be merged into the project's `main` branch, and all
+ [commits will be
+ squashed](https://help.github.com/en/articles/about-pull-request-merges#squash-and-merge-your-pull-request-commits)
+ during the merge.
+
+If you would like to learn about when your code will be available in a release
+of Markdownlint, read more about [Markdownlint Release
+Cycles](#release-cycles).
+
+## Releases
+
+We release Markdownlint as a gem to [Rubygems](https://rubygems.org/gems/mdl)
+and maintain a [Docker image](https://hub.docker.com/r/markdownlint/markdownlint)
+
+Markdownlint follows the [Semantic Versioning](https://semver.org/) standard.
+Our standard version numbers look like `X.Y.Z` and translates to:
+
+* `X` is a major release: has changes that may be incompatible with prior major
+ releases
+* `Y` is a minor release: adds new functionality and bug fixes in a backwards
+ compatible manner
+* `Z` is a patch release: adds backwards compatible bug fixes
+
+*Exception: Versions < 1.0 may introduce backwards-incompatible changes in a
+minor version*
diff --git a/documents/markdown/markdownlint/MAINTAINERS.md b/documents/markdown/markdownlint/MAINTAINERS.md
new file mode 100644
index 0000000..48cdc16
--- /dev/null
+++ b/documents/markdown/markdownlint/MAINTAINERS.md
@@ -0,0 +1,20 @@
+# Markdownlint
+
+We aim to make sure this project has longevity, and to that end we want to make
+adding new maintainers a simple process.
+
+If you would like to be a maintainer, you need to demonstrate some ongoing
+contributions - either reviews of PRs or PR contributions. They need not be large.
+Then send a PR to add yourself to this list. The existing maintainers will
+have a discussion, and assuming there are no objections, you'll be added.
+
+## Current Maintainers
+
+* [Phil Dibowitz](https://github.com/jaymzh)
+* [Naomi Reeves](https://github.com/NaomiReeves)
+* [Bryan Wann](https://github.com/bwann)
+
+## Past Maintainers
+
+* [psyomn](https://github.com/psyomn)
+* [Mark Harrison](https://github.com/mivok)
diff --git a/documents/markdown/markdownlint/README.md b/documents/markdown/markdownlint/README.md
new file mode 100644
index 0000000..6d9fc16
--- /dev/null
+++ b/documents/markdown/markdownlint/README.md
@@ -0,0 +1,111 @@
+# Markdown lint tool
+
+[](https://github.com/markdownlint/markdownlint/actions?query=workflow%3A%22Continuous+Integration%22)
+[](https://badge.fury.io/rb/mdl)
+
+A tool to check markdown files and flag style issues.
+
+## Installation
+
+Markdownlint is packaged in some distributions as well as distributed via
+RubyGems. Check the list below to see if it's packaged for your distribution,
+and if so, feel free to use your distros package manager to install it.
+
+[](https://repology.org/project/mdl-markdownlint/versions)
+
+To install from rubygems, run:
+
+```shell
+gem install mdl
+```
+
+Alternatively you can build it from source:
+
+```shell
+git clone https://github.com/markdownlint/markdownlint
+cd markdownlint
+rake install
+```
+
+Note that you will need [rake](https://github.com/ruby/rake)
+(`gem install rake`) and [bundler](https://github.com/bundler/bundler)
+(`gem install bundler`) in order to build from source.
+
+## Usage
+
+To have markdownlint check your markdown files, simply run `mdl` with the
+filenames as a parameter:
+
+```shell
+mdl README.md
+```
+
+Markdownlint can also take a directory, and it will scan all markdown files
+within the directory (and nested directories):
+
+```shell
+mdl docs/
+```
+
+If you don't specify a filename, markdownlint will use stdin:
+
+```shell
+cat foo.md | mdl
+```
+
+Markdownlint will output a list of issues it finds, and the line number where
+the issue is. See [RULES.md](docs/RULES.md) for information on each issue, as
+well as how to correct it:
+
+```shell
+README.md:1: MD013 Line length
+README.md:70: MD029 Ordered list item prefix
+README.md:71: MD029 Ordered list item prefix
+README.md:72: MD029 Ordered list item prefix
+README.md:73: MD029 Ordered list item prefix
+```
+
+Markdownlint has many more options you can pass on the command line, run
+`mdl --help` to see what they are, or see the documentation on
+[configuring markdownlint](docs/configuration.md).
+
+### Styles
+
+Not everyone writes markdown in the same way, and there are multiple flavors
+and styles, each of which are valid. While markdownlint's default settings
+will result in markdown files that reflect the author's preferred markdown
+authoring preferences, your project may have different guidelines.
+
+It's not markdownlint's intention to dictate any one specific style, and in
+order to support these differing styles and/or preferences, markdownlint
+supports what are called 'style files'. A style file is a file describing
+which rules markdownlint should enable, and also what settings to apply to
+individual rules. For example, rule [MD013](docs/RULES.md#md013---line-length)
+checks for long lines, and by default will report an issue for any line longer
+than 80 characters. If your project has a different maximum line length limit,
+or if you don't want to enforce a line limit at all, then this can be
+configured in a style file.
+
+For more information on creating style files, see the
+[creating styles](docs/creating_styles.md) document.
+
+### Custom rules and rulesets
+
+It may be that the rules provided in this project don't cover your stylistic
+needs. To account for this, markdownlint supports the creation and use of custom
+rules.
+
+For more information, see the [creating rules](docs/creating_rules.md) document.
+
+## Related projects
+
+- [markdownlint](https://github.com/DavidAnson/markdownlint) - A similar
+ project, but limited in Node.js
+- [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli) - A CLI
+ for the above Node.js project
+- [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) - An
+ alternative CLI for the Node.js project
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
diff --git a/documents/markdown/markdownlint/atx_closed_header_spacing.md b/documents/markdown/markdownlint/atx_closed_header_spacing.md
new file mode 100644
index 0000000..e9a296b
--- /dev/null
+++ b/documents/markdown/markdownlint/atx_closed_header_spacing.md
@@ -0,0 +1,17 @@
+#Header 1 {MD020} #
+
+## Header 2 {MD020}##
+
+##Header 3 {MD020}##
+
+## Header 4 {MD021} ##
+
+## Header 5 {MD021} ##
+
+## Header 6 {MD021} ##
+
+## Header 7 {MD021} ##
+
+## Header 8 \#
+
+## Header 9 \#
diff --git a/documents/markdown/markdownlint/blockquote_blank_lines.md b/documents/markdown/markdownlint/blockquote_blank_lines.md
new file mode 100644
index 0000000..e163a76
--- /dev/null
+++ b/documents/markdown/markdownlint/blockquote_blank_lines.md
@@ -0,0 +1,31 @@
+Some text
+
+> a quote
+> same quote
+
+> blank line above me
+
+
+> two blank lines above me
+
+> space above me
+
+* List with embedded blockquote
+
+ > Test
+ > Test
+
+ > Test
+
+* Item 2
+
+ > Test. The blank line below should _not_ trigger MD028 as one blockquote is
+ > inside the list, and the other is outside it.
+
+> Test
+
+Expected errors:
+
+{MD028:5} {MD028:8} {MD028:10} {MD028:17}
+{MD009:10} (trailing space is intentional)
+{MD012:8} (multiple blank lines are intentional)
diff --git a/documents/markdown/markdownlint/blockquote_spaces.md b/documents/markdown/markdownlint/blockquote_spaces.md
new file mode 100644
index 0000000..a54cf66
--- /dev/null
+++ b/documents/markdown/markdownlint/blockquote_spaces.md
@@ -0,0 +1,29 @@
+Some text
+
+> Hello world
+> Foo {MD027}
+> Bar {MD027}
+
+This tests other things embedded in the blockquote:
+
+- foo
+
+> *Hello world*
+> *foo* {MD027}
+> **bar** {MD027}
+> "Baz" {MD027}
+> `qux` {MD027}
+> *foo* more text
+> **bar** more text
+> 'baz' more text
+> `qux` more text
+> [link](example.com) to site
+> [link](#link) {MD027}
+>
+> - foo
+
+Test the first line being indented too much:
+
+> Foo {MD027}
+> Bar {MD027}
+> Baz
diff --git a/documents/markdown/markdownlint/bulleted_list_2_space_indent.md b/documents/markdown/markdownlint/bulleted_list_2_space_indent.md
new file mode 100644
index 0000000..268c9b0
--- /dev/null
+++ b/documents/markdown/markdownlint/bulleted_list_2_space_indent.md
@@ -0,0 +1,6 @@
+This is a document where the lists are indented by 2 spaces, but the style is
+set to 4 space indents for lists:
+
+* Test X
+ * Test Y {MD007}
+ * Test Z {MD007}
diff --git a/documents/markdown/markdownlint/bulleted_list_not_at_beginning_of_line.md b/documents/markdown/markdownlint/bulleted_list_not_at_beginning_of_line.md
new file mode 100644
index 0000000..809da83
--- /dev/null
+++ b/documents/markdown/markdownlint/bulleted_list_not_at_beginning_of_line.md
@@ -0,0 +1,14 @@
+Some text
+
+ * Item {MD006}
+ * Item
+ * Item
+ * Item
+ * Item
+ * Item
+ * Item
+
+Some more text
+
+ * Item {MD006}
+ * Item
diff --git a/documents/markdown/markdownlint/bulleted_list_sublist.md b/documents/markdown/markdownlint/bulleted_list_sublist.md
new file mode 100644
index 0000000..7cad2f2
--- /dev/null
+++ b/documents/markdown/markdownlint/bulleted_list_sublist.md
@@ -0,0 +1,15 @@
+This is a document where the lists are consisent style per-sublist
+
+* stuff
+* other stuff
+ - indented stuff
+ - more indented stuff
+ + thing {MD004}
+ - stuff
+ + woah
+ + this
+ + is
+ + ok but...
+ - not this {MD004}
+ + but this
+* thing
diff --git a/documents/markdown/markdownlint/code_block_consistency.md b/documents/markdown/markdownlint/code_block_consistency.md
new file mode 100644
index 0000000..783ec12
--- /dev/null
+++ b/documents/markdown/markdownlint/code_block_consistency.md
@@ -0,0 +1,11 @@
+This is text.
+
+ This is a
+ code block.
+
+And here is more text
+
+```
+and here is a different {MD046:8}
+code block
+```
diff --git a/documents/markdown/markdownlint/code_block_dollar.md b/documents/markdown/markdownlint/code_block_dollar.md
new file mode 100644
index 0000000..3a74361
--- /dev/null
+++ b/documents/markdown/markdownlint/code_block_dollar.md
@@ -0,0 +1,43 @@
+The following code block shouldn't have $ before the commands:
+
+```bash
+$ ls
+$ less foo
+
+$ cat bar
+```
+
+However the following code block shows output, and $ can be used to
+distinguish between command and output:
+
+```bash
+$ ls
+foo bar
+$ less foo
+Hello world
+
+$ cat bar
+baz
+```
+
+The following code block uses variable names, and likewise shouldn't fire:
+
+```bash
+$foo = 'bar';
+$baz = 'qux';
+```
+
+The following code block doesn't have any dollar signs, and shouldn't fire:
+
+```bash
+ls foo
+cat bar
+```
+
+The following (fenced) code block doesn't have any content at all, and
+shouldn't fire:
+
+```bash
+```
+
+{MD014:3}
diff --git a/documents/markdown/markdownlint/code_block_dollar_fence.md b/documents/markdown/markdownlint/code_block_dollar_fence.md
new file mode 100644
index 0000000..a20acb6
--- /dev/null
+++ b/documents/markdown/markdownlint/code_block_dollar_fence.md
@@ -0,0 +1,29 @@
+# header
+
+```fence
+$ code
+```
+
+text
+
+```fence
+$ code
+```
+
+text
+
+```fence
+$ code
+$ code
+```
+
+text
+
+```fence
+$ code
+$ code
+```
+
+text
+
+{MD014:3} {MD014:9} {MD014:15} {MD014:22}
diff --git a/documents/markdown/markdownlint/code_block_fenced.md b/documents/markdown/markdownlint/code_block_fenced.md
new file mode 100644
index 0000000..ed73b27
--- /dev/null
+++ b/documents/markdown/markdownlint/code_block_fenced.md
@@ -0,0 +1,17 @@
+This is text.
+
+ This is a {MD046}
+ code block.
+
+And here is more text
+
+```
+This is a code block that won't trigger.
+```
+
+But we'll do another:
+
+ And this {MD046}
+ will.
+
+Final text is here
diff --git a/documents/markdown/markdownlint/code_block_indented.md b/documents/markdown/markdownlint/code_block_indented.md
new file mode 100644
index 0000000..a03dc8d
--- /dev/null
+++ b/documents/markdown/markdownlint/code_block_indented.md
@@ -0,0 +1,17 @@
+This is text.
+
+ This is a
+ code block.
+
+And here is more text
+
+```
+This is {MD046:8} also a code block.
+```
+
+But we'll do another:
+
+ And this
+ will.
+
+Final text is here
diff --git a/documents/markdown/markdownlint/consecutive_blank_lines.md b/documents/markdown/markdownlint/consecutive_blank_lines.md
new file mode 100644
index 0000000..77ffb19
--- /dev/null
+++ b/documents/markdown/markdownlint/consecutive_blank_lines.md
@@ -0,0 +1,13 @@
+Some text
+
+
+Some text {MD012:3}
+
+```fenced
+This is a code block
+
+
+with two blank lines in it
+```
+
+Some more text
diff --git a/documents/markdown/markdownlint/docs_RULES.md b/documents/markdown/markdownlint/docs_RULES.md
new file mode 100644
index 0000000..017caf2
--- /dev/null
+++ b/documents/markdown/markdownlint/docs_RULES.md
@@ -0,0 +1,1320 @@
+
+* [Rules](#rules)
+ * [MD001 - Header levels should only increment by one level at a time](#md001---header-levels-should-only-increment-by-one-level-at-a-time)
+ * [MD002 - First header should be a top level header](#md002---first-header-should-be-a-top-level-header)
+ * [MD003 - Header style](#md003---header-style)
+ * [MD004 - Unordered list style](#md004---unordered-list-style)
+ * [MD005 - Inconsistent indentation for list items at the same level](#md005---inconsistent-indentation-for-list-items-at-the-same-level)
+ * [MD006 - Consider starting bulleted lists at the beginning of the line](#md006---consider-starting-bulleted-lists-at-the-beginning-of-the-line)
+ * [MD007 - Unordered list indentation](#md007---unordered-list-indentation)
+ * [MD009 - Trailing spaces](#md009---trailing-spaces)
+ * [MD010 - Hard tabs](#md010---hard-tabs)
+ * [MD011 - Reversed link syntax](#md011---reversed-link-syntax)
+ * [MD012 - Multiple consecutive blank lines](#md012---multiple-consecutive-blank-lines)
+ * [MD013 - Line length](#md013---line-length)
+ * [MD014 - Dollar signs used before commands without showing output](#md014---dollar-signs-used-before-commands-without-showing-output)
+ * [MD018 - No space after hash on atx style header](#md018---no-space-after-hash-on-atx-style-header)
+ * [MD019 - Multiple spaces after hash on atx style header](#md019---multiple-spaces-after-hash-on-atx-style-header)
+ * [MD020 - No space inside hashes on closed atx style header](#md020---no-space-inside-hashes-on-closed-atx-style-header)
+ * [MD021 - Multiple spaces inside hashes on closed atx style header](#md021---multiple-spaces-inside-hashes-on-closed-atx-style-header)
+ * [MD022 - Headers should be surrounded by blank lines](#md022---headers-should-be-surrounded-by-blank-lines)
+ * [MD023 - Headers must start at the beginning of the line](#md023---headers-must-start-at-the-beginning-of-the-line)
+ * [MD024 - Multiple headers with the same content](#md024---multiple-headers-with-the-same-content)
+ * [MD025 - Multiple top level headers in the same document](#md025---multiple-top-level-headers-in-the-same-document)
+ * [MD026 - Trailing punctuation in header](#md026---trailing-punctuation-in-header)
+ * [MD027 - Multiple spaces after blockquote symbol](#md027---multiple-spaces-after-blockquote-symbol)
+ * [MD028 - Blank line inside blockquote](#md028---blank-line-inside-blockquote)
+ * [MD029 - Ordered list item prefix](#md029---ordered-list-item-prefix)
+ * [MD030 - Spaces after list markers](#md030---spaces-after-list-markers)
+ * [MD031 - Fenced code blocks should be surrounded by blank lines](#md031---fenced-code-blocks-should-be-surrounded-by-blank-lines)
+ * [MD032 - Lists should be surrounded by blank lines](#md032---lists-should-be-surrounded-by-blank-lines)
+ * [MD033 - Inline HTML](#md033---inline-html)
+ * [MD034 - Bare URL used](#md034---bare-url-used)
+ * [MD035 - Horizontal rule style](#md035---horizontal-rule-style)
+ * [MD036 - Emphasis used instead of a header](#md036---emphasis-used-instead-of-a-header)
+ * [MD037 - Spaces inside emphasis markers](#md037---spaces-inside-emphasis-markers)
+ * [MD038 - Spaces inside code span elements](#md038---spaces-inside-code-span-elements)
+ * [MD039 - Spaces inside link text](#md039---spaces-inside-link-text)
+ * [MD040 - Fenced code blocks should have a language specified](#md040---fenced-code-blocks-should-have-a-language-specified)
+ * [MD041 - First line in file should be a top level header](#md041---first-line-in-file-should-be-a-top-level-header)
+ * [MD046 - Code block style](#md046---code-block-style)
+ * [MD047 - File should end with a single newline character](#md047---file-should-end-with-a-single-newline-character)
+
+# Rules
+
+This document contains a description of all rules, what they are checking for,
+as well as an examples of documents that break the rule and corrected
+versions of the examples.
+
+## MD001 - Header levels should only increment by one level at a time
+
+Tags: headers
+
+Aliases: header-increment
+
+This rule is triggered when you skip header levels in a markdown document, for
+example:
+
+```markdown
+# Header 1
+
+### Header 3
+
+We skipped out a 2nd level header in this document
+```
+
+When using multiple header levels, nested headers should increase by only one
+level at a time:
+
+```markdown
+# Header 1
+
+## Header 2
+
+### Header 3
+
+#### Header 4
+
+## Another Header 2
+
+### Another Header 3
+```
+
+## MD002 - First header should be a top level header
+
+Tags: headers
+
+Aliases: first-header-h1
+
+Parameters: level (number; default 1)
+
+This rule is triggered when the first header in the document isn't a h1 header:
+
+```markdown
+## This isn't a H1 header
+
+### Another header
+```
+
+The first header in the document should be a h1 header:
+
+```markdown
+# Start with a H1 header
+
+## Then use a H2 for subsections
+```
+
+## MD003 - Header style
+
+Tags: headers
+
+Aliases: header-style
+
+Parameters: style (`:consistent`, `:atx`, `:atx_closed`, `:setext`,
+`:setext_with_atx`; default `:consistent`)
+
+This rule is triggered when different header styles (atx, setext, and 'closed'
+atx) are used in the same document:
+
+```markdown
+# ATX style H1
+
+## Closed ATX style H2 ##
+
+Setext style H1
+===============
+```
+
+Be consistent with the style of header used in a document:
+
+```markdown
+# ATX style H1
+
+## ATX style H2
+```
+
+The setext_with_atx doc style allows atx-style headers of level 3 or more in
+documents with setext style headers:
+
+```markdown
+Setext style H1
+===============
+
+Setext style H2
+---------------
+
+### ATX style H3
+```
+
+Note: the configured header style can be a specific style to use (atx,
+atx_closed, setext, setext_with_atx), or simply require that the usage be
+consistent within the document.
+
+## MD004 - Unordered list style
+
+Tags: bullet, ul
+
+Aliases: ul-style
+
+Parameters: style (`:consistent`, `:asterisk`, `:plus`, `:dash`, `:sublist`;
+default `:consistent`)
+
+This rule is triggered when the symbols used in the document for unordered
+list items do not match the configured unordered list style:
+
+```markdown
+* Item 1
++ Item 2
+- Item 3
+```
+
+To fix this issue, use the configured style for list items throughout the
+document:
+
+```markdown
+* Item 1
+* Item 2
+* Item 3
+```
+
+Note: the configured list style can be a specific symbol to use (asterisk,
+plus, dash), or simply require that the usage be consistent within the
+document (consistent) or within a level (sublist).
+
+For sublist, each level must be consistent within a document, even if they
+are separate lists. So this is allowed:
+
+```markdown
+* Item 1
+* Item 2
+ - Item 2a
+ + Item 2a1
+ - Item 2b
+* Item 3
+
+Other stuff
+
+* Item 1
+* Item 2
+```
+
+But this is not allowed:
+
+```markdown
+* Item 1
+* Item 2
+ - Item 2a
+ + Item 2a1
+ - Item 2b
+* Item 3
+
+Other stuff
+
+- Item 1
+- Item 2
+```
+
+## MD005 - Inconsistent indentation for list items at the same level
+
+Tags: bullet, ul, indentation
+
+Aliases: list-indent
+
+This rule is triggered when list items are parsed as being at the same level,
+but don't have the same indentation:
+
+```markdown
+* Item 1
+ * Nested Item 1
+ * Nested Item 2
+ * A misaligned item
+```
+
+Usually this rule will be triggered because of a typo. Correct the indentation
+for the list to fix it:
+
+```markdown
+* Item 1
+ * Nested Item 1
+ * Nested Item 2
+ * Nested Item 3
+```
+
+## MD006 - Consider starting bulleted lists at the beginning of the line
+
+Tags: bullet, ul, indentation
+
+Aliases: ul-start-left
+
+This rule is triggered when top level lists don't start at the beginning of a
+line:
+
+```markdown
+Some text
+
+ * List item
+ * List item
+```
+
+To fix, ensure that top level list items are not indented:
+
+```markdown
+Some test
+
+* List item
+* List item
+```
+
+Rationale: Starting lists at the beginning of the line means that nested list
+items can all be indented by the same amount when an editor's indent function
+or the tab key is used to indent. Starting a list 1 space in means that the
+indent of the first nested list is less than the indent of the second level
+(3 characters if you use 4 space tabs, or 1 character if you use 2 space tabs).
+
+## MD007 - Unordered list indentation
+
+Tags: bullet, ul, indentation
+
+Aliases: ul-indent
+
+Parameters: indent (number; default 3)
+
+This rule is triggered when list items are not indented by the configured
+number of spaces (default: 3).
+
+Example:
+
+```markdown
+* List item
+ * Nested list item indented by 2 spaces
+```
+
+Corrected Example:
+
+```markdown
+* List item
+ * Nested list item indented by 3 spaces
+```
+
+Rationale (3 space indent): This matches the minimum possible indentation
+for _ordered_ lists (i.e Kramdown won't parse anything less than 3 spaces
+as a sublist on OLs), and since MD005 requires consistent indentation
+across lists, anything less than three on this rule will cause a violation
+of MD005 if you have both kinds of lists in the same document.
+
+This means if you want to set this to 2, you'll need to disable MD005.
+
+Rationale (4 space indent): Same indent as code blocks, simpler for editors to
+implement. See
+<https://cirosantilli.com/markdown-style-guide#spaces-before-list-marker>
+for more information.
+
+In addition, this is a compatibility issue with multi-markdown parsers, which
+require a 4 space indents. See
+<http://support.markedapp.com/discussions/problems/21-sub-lists-not-indenting>
+for a description of the problem.
+
+## MD009 - Trailing spaces
+
+Tags: whitespace
+
+Aliases: no-trailing-spaces
+
+Parameters: br_spaces (number; default: 2)
+
+This rule is triggered on any lines that end with whitespace. To fix this,
+find the line that is triggered and remove any trailing spaces from the end.
+
+The br_spaces parameter allows an exception to this rule for a specific amount
+of trailing spaces used to insert an explicit line break/br element. For
+example, set br_spaces to 2 to allow exactly 2 spaces at the end of a line.
+
+Note: you have to set br_spaces to 2 or higher for this exception to take
+effect - you can't insert a br element with just a single trailing space, so
+if you set br_spaces to 1, the exception will be disabled, just as if it was
+set to 0.
+
+## MD010 - Hard tabs
+
+Tags: whitespace, hard_tab
+
+Aliases: no-hard-tabs
+
+Parameters: ignore_code_blocks (boolean; default false)
+
+This rule is triggered by any lines that contain hard tab characters instead
+of using spaces for indentation. To fix this, replace any hard tab characters
+with spaces instead.
+
+Example:
+
+```markdown
+Some text
+
+ * hard tab character used to indent the list item
+```
+
+Corrected example:
+
+```markdown
+Some text
+
+ * Spaces used to indent the list item instead
+```
+
+You have the option to exclude this rule for code blocks. To do this, set the
+`ignore_code_blocks` parameter to true.
+
+## MD011 - Reversed link syntax
+
+Tags: links
+
+Aliases: no-reversed-links
+
+This rule is triggered when text that appears to be a link is encountered, but
+where the syntax appears to have been reversed (the `[]` and `()` are
+reversed):
+
+```markdown
+(Incorrect link syntax)[http://www.example.com/]
+```
+
+To fix this, swap the `[]` and `()` around:
+
+```markdown
+[Correct link syntax](http://www.example.com/)
+```
+
+## MD012 - Multiple consecutive blank lines
+
+Tags: whitespace, blank_lines
+
+Aliases: no-multiple-blanks
+
+This rule is triggered when there are multiple consecutive blank lines in the
+document:
+
+```markdown
+Some text here
+
+
+Some more text here
+```
+
+To fix this, delete the offending lines:
+
+```markdown
+Some text here
+
+Some more text here
+```
+
+Note: this rule will not be triggered if there are multiple consecutive blank
+lines inside code blocks.
+
+## MD013 - Line length
+
+Tags: line_length
+
+Aliases: line-length
+
+Parameters: line_length, ignore_code_blocks, code_blocks, tables, headings (number; default 80, boolean; default false, boolean; default true, boolean; default true, boolean; default true)
+
+This rule is triggered when there are lines that are longer than the
+configured line length (default: 80 characters). To fix this, split the line
+up into multiple lines.
+
+This rule has an exception where there is no whitespace beyond the configured
+line length. This allows you to still include items such as long URLs without
+being forced to break them in the middle.
+
+You also have the option to exclude this rule for code blocks. To
+do this, set the `ignore_code_blocks` parameter to true. To exclude this rule
+for tables set the `tables` parameter to false. To exclude this rule for
+headings set the `headings` parameter to false. Setting the parameter `code_blocks` to false to exclude the rule for
+code blocks is deprecated and will be removed in a future release.
+
+Code blocks are included in this rule by default since it is often a
+requirement for document readability, and tentatively compatible with code
+rules. Still, some languages do not lend themselves to short lines.
+
+## MD014 - Dollar signs used before commands without showing output
+
+Tags: code
+
+Aliases: commands-show-output
+
+This rule is triggered when there are code blocks showing shell commands to be
+typed, and the shell commands are preceded by dollar signs ($):
+
+```markdown
+$ ls
+$ cat foo
+$ less bar
+```
+
+The dollar signs are unnecessary in the above situation, and should not be
+included:
+
+```markdown
+ls
+cat foo
+less bar
+```
+
+However, an exception is made when there is a need to distinguish between
+typed commands and command output, as in the following example:
+
+```markdown
+$ ls
+foo bar
+$ cat foo
+Hello world
+$ cat bar
+baz
+```
+
+Rationale: it is easier to copy and paste and less noisy if the dollar signs
+are omitted when they are not needed. See
+<https://cirosantilli.com/markdown-style-guide#dollar-signs-in-shell-code>
+for more information.
+
+## MD018 - No space after hash on atx style header
+
+Tags: headers, atx, spaces
+
+Aliases: no-missing-space-atx
+
+This rule is triggered when spaces are missing after the hash characters
+in an atx style header:
+
+```markdown
+#Header 1
+
+##Header 2
+```
+
+To fix this, separate the header text from the hash character by a single
+space:
+
+```markdown
+# Header 1
+
+## Header 2
+```
+
+## MD019 - Multiple spaces after hash on atx style header
+
+Tags: headers, atx, spaces
+
+Aliases: no-multiple-space-atx
+
+This rule is triggered when more than one space is used to separate the
+header text from the hash characters in an atx style header:
+
+```markdown
+# Header 1
+
+## Header 2
+```
+
+To fix this, separate the header text from the hash character by a single
+space:
+
+```markdown
+# Header 1
+
+## Header 2
+```
+
+## MD020 - No space inside hashes on closed atx style header
+
+Tags: headers, atx_closed, spaces
+
+Aliases: no-missing-space-closed-atx
+
+This rule is triggered when spaces are missing inside the hash characters
+in a closed atx style header:
+
+```markdown
+#Header 1#
+
+##Header 2##
+```
+
+To fix this, separate the header text from the hash character by a single
+space:
+
+```markdown
+# Header 1 #
+
+## Header 2 ##
+```
+
+Note: this rule will fire if either side of the header is missing spaces.
+
+## MD021 - Multiple spaces inside hashes on closed atx style header
+
+Tags: headers, atx_closed, spaces
+
+Aliases: no-multiple-space-closed-atx
+
+This rule is triggered when more than one space is used to separate the
+header text from the hash characters in a closed atx style header:
+
+```markdown
+# Header 1 #
+
+## Header 2 ##
+```
+
+To fix this, separate the header text from the hash character by a single
+space:
+
+```markdown
+# Header 1 #
+
+## Header 2 ##
+```
+
+Note: this rule will fire if either side of the header contains multiple
+spaces.
+
+## MD022 - Headers should be surrounded by blank lines
+
+Tags: headers, blank_lines
+
+Aliases: blanks-around-headers
+
+This rule is triggered when headers (any style) are either not preceded or not
+followed by a blank line:
+
+```markdown
+# Header 1
+Some text
+
+Some more text
+## Header 2
+```
+
+To fix this, ensure that all headers have a blank line both before and after
+(except where the header is at the beginning or end of the document):
+
+```markdown
+# Header 1
+
+Some text
+
+Some more text
+
+## Header 2
+```
+
+Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will
+not parse headers that don't have a blank line before, and will parse them as
+regular text.
+
+## MD023 - Headers must start at the beginning of the line
+
+Tags: headers, spaces
+
+Aliases: header-start-left
+
+This rule is triggered when a header is indented by one or more spaces:
+
+```markdown
+Some text
+
+ # Indented header
+```
+
+To fix this, ensure that all headers start at the beginning of the line:
+
+```markdown
+Some text
+
+# Header
+```
+
+Rationale: Headers that don't start at the beginning of the line will not be
+parsed as headers, and will instead appear as regular text.
+
+## MD024 - Multiple headers with the same content
+
+Tags: headers
+
+Aliases: no-duplicate-header
+
+Parameters: allow_different_nesting (boolean; default false)
+
+This rule is triggered if there are multiple headers in the document that have
+the same text:
+
+```markdown
+# Some text
+
+## Some text
+```
+
+To fix this, ensure that the content of each header is different:
+
+```markdown
+# Some text
+
+## Some more text
+```
+
+Rationale: Some markdown parses generate anchors for headers based on the
+header name, and having headers with the same content can cause problems with
+this.
+
+If the parameter `allow_different_nesting` is set to `true`, header duplication
+under different nesting is allowed, like it usually happens in change logs:
+
+```markdown
+# Change log
+
+## 2.0.0
+
+### Bug fixes
+
+### Features
+
+## 1.0.0
+
+### Bug fixes
+```
+
+## MD025 - Multiple top level headers in the same document
+
+Tags: headers
+
+Aliases: single-h1
+
+Parameters: level (number; default 1)
+
+This rule is triggered when a top level header is in use (the first line of
+the file is a h1 header), and more than one h1 header is in use in the
+document:
+
+```markdown
+# Top level header
+
+# Another top level header
+```
+
+To fix, structure your document so that there is a single h1 header that is
+the title for the document, and all later headers are h2 or lower level
+headers:
+
+```markdown
+# Title
+
+## Header
+
+## Another header
+```
+
+Rationale: A top level header is a h1 on the first line of the file, and
+serves as the title for the document. If this convention is in use, then there
+can not be more than one title for the document, and the entire document
+should be contained within this header.
+
+Note: The `level` parameter can be used to change the top level (ex: to h2) in
+cases where an h1 is added externally.
+
+## MD026 - Trailing punctuation in header
+
+Tags: headers
+
+Aliases: no-trailing-punctuation
+
+Parameters: punctuation (string; default ".,;:!?")
+
+This rule is triggered on any header that has a punctuation character as the
+last character in the line:
+
+```markdown
+# This is a header.
+```
+
+To fix this, remove any trailing punctuation:
+
+```markdown
+# This is a header
+```
+
+Note: The punctuation parameter can be used to specify what characters class
+as punctuation at the end of the header. For example, you can set it to
+`'.,;:!'` to allow headers with question marks in them, such as might be used
+in an FAQ.
+
+## MD027 - Multiple spaces after blockquote symbol
+
+Tags: blockquote, whitespace, indentation
+
+Aliases: no-multiple-space-blockquote
+
+This rule is triggered when blockquotes have more than one space after the
+blockquote (`>`) symbol:
+
+```markdown
+> This is a block quote with bad indentation
+> there should only be one.
+```
+
+To fix, remove any extraneous space:
+
+```markdown
+> This is a blockquote with correct
+> indentation.
+```
+
+## MD028 - Blank line inside blockquote
+
+Tags: blockquote, whitespace
+
+Aliases: no-blanks-blockquote
+
+This rule is triggered when two blockquote blocks are separated by nothing
+except for a blank line:
+
+```markdown
+> This is a blockquote
+> which is immediately followed by
+
+> this blockquote. Unfortunately
+> In some parsers, these are treated as the same blockquote.
+```
+
+To fix this, ensure that any blockquotes that are right next to each other
+have some text in between:
+
+```markdown
+> This is a blockquote.
+
+And Jimmy also said:
+
+> This too is a blockquote.
+```
+
+Alternatively, if they are supposed to be the same quote, then add the
+blockquote symbol at the beginning of the blank line:
+
+```markdown
+> This is a blockquote.
+>
+> This is the same blockquote.
+```
+
+Rationale: Some markdown parsers will treat two blockquotes separated by one
+or more blank lines as the same blockquote, while others will treat them as
+separate blockquotes.
+
+## MD029 - Ordered list item prefix
+
+Tags: ol
+
+Aliases: ol-prefix
+
+Parameters: style (`:one`, `:ordered`; default `:one`)
+
+This rule is triggered on ordered lists that do not either start with '1.' or
+do not have a prefix that increases in numerical order (depending on the
+configured style, which defaults to 'one').
+
+Example valid list if the style is configured as 'one':
+
+```markdown
+1. Do this.
+1. Do that.
+1. Done.
+```
+
+Example valid list if the style is configured as 'ordered':
+
+```markdown
+1. Do this.
+2. Do that.
+3. Done.
+```
+
+## MD030 - Spaces after list markers
+
+Tags: ol, ul, whitespace
+
+Aliases: list-marker-space
+
+Parameters: ul_single, ol_single, ul_multi, ol_multi (number, default 1)
+
+This rule checks for the number of spaces between a list marker (e.g. '`-`',
+'`*`', '`+`' or '`1.`') and the text of the list item.
+
+The number of spaces checked for depends on the document style in use, but the
+default is 1 space after any list marker:
+
+```markdown
+* Foo
+* Bar
+* Baz
+
+1. Foo
+1. Bar
+1. Baz
+
+1. Foo
+ * Bar
+1. Baz
+```
+
+A document style may change the number of spaces after unordered list items
+and ordered list items independently, as well as based on whether the content
+of every item in the list consists of a single paragraph, or multiple
+paragraphs (including sub-lists and code blocks).
+
+For example, the style guide at
+<https://cirosantilli.com/markdown-style-guide#spaces-after-list-marker>
+specifies that 1 space after the list marker should be used if every item in
+the list fits within a single paragraph, but to use 2 or 3 spaces (for ordered
+and unordered lists respectively) if there are multiple paragraphs of content
+inside the list:
+
+```markdown
+* Foo
+* Bar
+* Baz
+```
+
+vs.
+
+```markdown
+* Foo
+
+ Second paragraph
+
+* Bar
+```
+
+or
+
+```markdown
+1. Foo
+
+ Second paragraph
+
+1. Bar
+```
+
+To fix this, ensure the correct number of spaces are used after list marker
+for your selected document style.
+
+## MD031 - Fenced code blocks should be surrounded by blank lines
+
+Tags: code, blank_lines
+
+Aliases: blanks-around-fences
+
+This rule is triggered when fenced code blocks are either not preceded or not
+followed by a blank line:
+
+ Some text
+ ```
+ Code block
+ ```
+
+ ```
+ Another code block
+ ```
+ Some more text
+
+To fix this, ensure that all fenced code blocks have a blank line both before
+and after (except where the block is at the beginning or end of the document):
+
+ Some text
+
+ ```
+ Code block
+ ```
+
+ ```
+ Another code block
+ ```
+
+ Some more text
+
+Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will
+not parse fenced code blocks that don't have blank lines before and after them.
+
+## MD032 - Lists should be surrounded by blank lines
+
+Tags: bullet, ul, ol, blank_lines
+
+Aliases: blanks-around-lists
+
+This rule is triggered when lists (of any kind) are either not preceded or not
+followed by a blank line:
+
+```markdown
+Some text
+* Some
+* List
+
+1. Some
+2. List
+Some text
+```
+
+To fix this, ensure that all lists have a blank line both before and after
+(except where the block is at the beginning or end of the document):
+
+```markdown
+Some text
+
+* Some
+* List
+
+1. Some
+2. List
+
+Some text
+```
+
+Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will
+not parse lists that don't have blank lines before and after them.
+
+Note: List items without hanging indents are a violation of this rule; list
+items with hanging indents are okay:
+
+```markdown
+* This is
+not okay
+
+* This is
+ okay
+```
+
+## MD033 - Inline HTML
+
+Tags: html
+
+Aliases: no-inline-html
+
+Parameters: allowed_elements (string; default `''`)
+
+This rule is triggered whenever raw HTML is used in a markdown document:
+
+```markdown
+<h1>Inline HTML header</h1>
+```
+
+To fix this, use 'pure' markdown instead of including raw HTML:
+
+```markdown
+# Markdown header
+```
+
+Note: To allow specific HTML elements, use the `allowed_elements` parameter:
+
+```ruby
+rule 'MD033', :allowed_elements => 'br, p'
+```
+
+Rationale: Raw HTML is allowed in markdown, but this rule is included for
+those who want their documents to only include "pure" markdown, or for those
+who are rendering markdown documents in something other than HTML.
+
+## MD034 - Bare URL used
+
+Tags: links, url
+
+Aliases: no-bare-urls
+
+This rule is triggered whenever a URL is given that isn't surrounded by angle
+brackets:
+
+```markdown
+For more information, see http://www.example.com/.
+```
+
+To fix this, add angle brackets around the URL:
+
+```markdown
+For more information, see <http://www.example.com/>.
+```
+
+Rationale: Without angle brackets, the URL isn't converted into a link in many
+markdown parsers.
+
+Note: if you do want a bare URL without it being converted into a link,
+enclose it in a code block, otherwise in some markdown parsers it _will_ be
+converted:
+
+```markdown
+`http://www.example.com`
+```
+
+## MD035 - Horizontal rule style
+
+Tags: hr
+
+Aliases: hr-style
+
+Parameters: style (`:consistent`, "---", "***", or other string specifying the
+horizontal rule; default `:consistent`)
+
+This rule is triggered when inconsistent styles of horizontal rules are used
+in the document:
+
+```markdown
+---
+
+- - -
+
+***
+
+* * *
+
+****
+```
+
+To fix this, ensure any horizontal rules used in the document are consistent,
+or match the given style if the rule is so configured:
+
+```markdown
+---
+
+---
+```
+
+Note: by default, this rule is configured to just require that all horizontal
+rules in the document are the same, and will trigger if any of the horizontal
+rules are different than the first one encountered in the document. If you
+want to configure the rule to match a specific style, the parameter given to
+the 'style' option is a string containing the exact horizontal rule text that
+is allowed.
+
+## MD036 - Emphasis used instead of a header
+
+Tags: headers, emphasis
+
+Parameters: punctuation (string; default ".,;:!?")
+
+Aliases: no-emphasis-as-header
+
+This check looks for instances where emphasized (i.e. bold or italic) text is
+used to separate sections, where a header should be used instead:
+
+```markdown
+**My document**
+
+Lorem ipsum dolor sit amet...
+
+_Another section_
+
+Consectetur adipiscing elit, sed do eiusmod.
+```
+
+To fix this, use markdown headers instead of emphasized text to denote
+sections:
+
+```markdown
+# My document
+
+Lorem ipsum dolor sit amet...
+
+## Another section
+
+Consectetur adipiscing elit, sed do eiusmod.
+```
+
+Note: this rule looks for single line paragraphs that consist entirely of
+emphasized text. It won't fire on emphasis used within regular text,
+multi-line emphasized paragraphs, and paragraphs ending in punctuation.
+Similarly to rule MD026, you can configure what characters are recognized as
+punctuation.
+
+## MD037 - Spaces inside emphasis markers
+
+Tags: whitespace, emphasis
+
+Aliases: no-space-in-emphasis
+
+This rule is triggered when emphasis markers (bold, italic) are used, but they
+have spaces between the markers and the text:
+
+```markdown
+Here is some ** bold ** text.
+
+Here is some * italic * text.
+
+Here is some more __ bold __ text.
+
+Here is some more _ italic _ text.
+```
+
+To fix this, remove the spaces around the emphasis markers:
+
+```markdown
+Here is some **bold** text.
+
+Here is some *italic* text.
+
+Here is some more __bold__ text.
+
+Here is some more _italic_ text.
+```
+
+Rationale: Emphasis is only parsed as such when the asterisks/underscores
+aren't completely surrounded by spaces. This rule attempts to detect where
+they were surrounded by spaces, but it appears that emphasized text was
+intended by the author.
+
+## MD038 - Spaces inside code span elements
+
+Tags: whitespace, code
+
+Aliases: no-space-in-code
+
+This rule is triggered on code span elements that have spaces right inside the
+backticks:
+
+```markdown
+` some text `
+
+`some text `
+
+` some text`
+```
+
+To fix this, remove the spaces inside the codespan markers:
+
+```markdown
+`some text`
+```
+
+## MD039 - Spaces inside link text
+
+Tags: whitespace, links
+
+Aliases: no-space-in-links
+
+This rule is triggered on links that have spaces surrounding the link text:
+
+```markdown
+[ a link ](http://www.example.com/)
+```
+
+To fix this, remove the spaces surrounding the link text:
+
+```markdown
+[a link](http://www.example.com/)
+```
+
+## MD040 - Fenced code blocks should have a language specified
+
+Tags: code, language
+
+Aliases: fenced-code-language
+
+This rule is triggered when fenced code blocks are used, but a language isn't
+specified:
+
+ ```
+ #!/bin/bash
+ echo Hello world
+ ```
+
+To fix this, add a language specifier to the code block:
+
+ ```bash
+ #!/bin/bash
+ echo Hello world
+ ```
+
+If no specific language is used, you can specify `text` as language.
+
+## MD041 - First line in file should be a top level header
+
+Tags: headers
+
+Aliases: first-line-h1
+
+Parameters: level (number; default 1)
+
+This rule is triggered when the first line in the file isn't a top level (h1)
+header:
+
+```markdown
+This is a file without a header
+```
+
+To fix this, add a header to the top of your file:
+
+```markdown
+# File with header
+
+This is a file with a top level header
+```
+
+Note: The `level` parameter can be used to change the top level (ex: to h2) in
+cases where an h1 is added externally.
+
+## MD046 - Code block style
+
+Tags: code
+
+Aliases: code-block-style
+
+Parameters: style (`:fenced`, `:indented`, `:consistent`, default `:fenced`)
+
+This rule is triggered when a different code block style is used than the
+configured one. For example, in the default configuration this rule is triggered
+for the following document:
+
+ Some text.
+
+ Code block
+
+ Some more text.
+
+To fix this, used fenced code blocks:
+
+ Some text.
+
+ ```ruby
+ Code block
+ ```
+
+ Some more text.
+
+The reverse is true if the rule is configured to use the `indented` style.
+
+## MD047 - File should end with a single newline character
+
+Tags: blank_lines
+
+Aliases: single-trailing-newline
+
+This rule is triggered when there is not a single newline character at the end
+of a file.
+
+Example that triggers the rule:
+
+```markdown
+# Heading
+
+This file ends without a newline.[EOF]
+```
+
+To fix the violation, add a newline character to the end of the file:
+
+```markdown
+# Heading
+
+This file ends with a newline.
+[EOF]
+```
+
+Rationale: Some programs have trouble with files that do not end with a newline.
+More information:
+<https://unix.stackexchange.com/questions/18743/whats-the-point-in-adding-a-new-line-to-the-end-of-a-file>.
diff --git a/documents/markdown/markdownlint/docs_configuration.md b/documents/markdown/markdownlint/docs_configuration.md
new file mode 100644
index 0000000..fc2f026
--- /dev/null
+++ b/documents/markdown/markdownlint/docs_configuration.md
@@ -0,0 +1,125 @@
+# Mdl configuration
+
+Markdownlint has several options you can configure both on the command line, or
+in markdownlint's configuration file: `.mdlrc`, first looked for in the working
+directory, then in your home directory. While markdownlint will work perfectly
+well out of the box, this page documents some of the options you can change to
+suit your needs.
+
+In general, anything you pass on the command line can also be put into
+`~/.mdlrc` with the same option. For example, if you pass `--style foo` on the
+command line, you can make this the default by putting `style "foo"` into your
+`~/.mdlrc` file.
+
+## Configuration options
+
+### General options
+
+Verbose - Print additional information about what markdownlint is doing.
+
+* Command line: `-v`, `--verbose`
+* Config file: `verbose true`
+* Default: false
+
+Show warnings - Kramdown will generate warnings of its own for some issues
+found with documents during parsing, and markdownlint can print these out in
+addition to using the built in rules. This option enables/disables that
+behavior.
+
+* Command line: `-w`, `--warnings`
+* Config file: `show_kramdown_warnings true`
+* Default: true
+
+Recurse using files known to git - When mdl is given a directory name on the
+command line, it will recurse into that directory looking for markdown files to
+process. If this option is enabled, it will use git to look for files instead,
+and ignore any files git doesn't know about.
+
+* Command line: `-g`, `--git-recurse`
+* Config file: `git_recurse true`
+* Default: false
+
+Ignore YAML front matter - If this option is enabled markdownlint will ignore
+content within valid [YAML front
+matter](https://jekyllrb.com/docs/frontmatter/). Reported line numbers will
+still match the file contents but markdownlint will consider the line following
+front matter to be the first line.
+
+* Command line: `-i`, `--ignore-front-matter`
+* Config file: `ignore_front_matter true`
+* Default: false
+
+### Specifying which rules mdl processes
+
+Tags - Limit the rules mdl enables to those containing the provided tags.
+
+* Command line: `-t tag1,tag2`, `--tags tag1,tag2`, `-t ~tag1,~tag2`
+* Config file: `tags "tag1", "tag2"`
+* Default: process all rules (no tag limit)
+
+Rules - Limit the rules mdl enables to those provided in this option.
+
+* Command line: `-r MD001,MD002`, `--rules MD001,MD002`, `-r ~MD001,~MD002`
+* Config file: `rules "MD001", "MD002"`
+* Default: process all rules (no rule limit)
+
+If a rule or tag ID is preceded by a tilde (`~`), then it _disables_ the
+matching rules instead of enabling them, starting with all rules being enabled.
+
+Note: If both `--rules` and `--tags` are provided, then a given rule has to
+both be in the list of enabled rules, as well as be tagged with one of the tags
+provided with the `--tags` option. Use the `-l/--list-rules` option to test
+this behavior.
+
+Style - Select which style mdl uses. A 'style' is a file containing a list of
+enabled/disable rules, as well as options for some rules that take them. For
+example, one style might enforce a line length of 80 characters, while another
+might choose 72 characters, and another might have no line length limit at all
+(rule MD013).
+
+* Command line: `-s style_name`, `--style style_name`
+* Config file: `style "style_name"`
+* Default: Use the style called 'default'
+
+Note: The value for `style_name` must either end with `.rb` or have `/` in it
+in order to tell `mdl` to look for a custom style, and not a built-in style.
+
+Note: When setting `style` in `mdlrc`, it is highly recommended that either a
+fully-qualified path be used, or that the relative values be passed in a form
+like `File.join(File.dirname(__FILE__), '.mdl.style')` so that the value is
+relative to the `mdlrc` and not the path the user happens to be in.
+
+Rulesets - Load a custom ruleset file. This option allows you to load custom
+rules in addition to those included with markdownlint.
+
+* Command line: `-u ruleset.rb,ruleset2.rb`, `--rulesets ruleset.rb,ruleset2.rb`
+* Config file: `rulesets ['ruleset.rb', 'ruleset2.rb']`
+* Default: Don't load any additional rulesets
+
+No default ruleset - Skip loading the default ruleset file included with
+markdownlint. Use this option if you only want to load custom rulesets.
+
+* Command line: `-d`, `--skip-default-ruleset`
+* Config file: `skip_default_ruleset true`
+* Default: Load the default ruleset.
+
+## Creating your own .mdlrc files
+
+You can configure `mdl` using your own `.mdlrc` file. You can specify and
+command-line option in this file.
+
+In particular you can specify a `style` file, where you have configured any
+rules. Here's a simple example that just points to a style file:
+
+```ruby
+style "#{File.dirname(__FILE__)}/{your_markdown_rule_file_path}.rb"
+```
+
+As commented, this path is relative to `.mdlrc` file. You can find a basic
+example of `.mdlrc` file [here](../example/.mdlrc_example).
+
+Then you should create your new [rule](creating_rules.md) or
+[style](creating_styles.md).
+
+You can find a basic example of new style file
+[here](../example/new_style_example.rb).
diff --git a/documents/markdown/markdownlint/docs_creating_rules.md b/documents/markdown/markdownlint/docs_creating_rules.md
new file mode 100644
index 0000000..1a786f2
--- /dev/null
+++ b/documents/markdown/markdownlint/docs_creating_rules.md
@@ -0,0 +1,129 @@
+# Creating Rules and Rulesets
+
+If the rules provided in this project don't cover your stylistic needs then you
+can create a custom ruleset. A ruleset is a Ruby file that contains rules. Rules
+are small pieces of Ruby code; these are [described below](#rule-syntax).
+
+## Using custom rules
+
+When a custom ruleset has been created, the ruleset can be loaded using the
+configuration options described in [the configuration
+document](./configuration.md) and referred to in the style document.
+
+As a minimal example: if `foo.rb` is a custom ruleset in the same directory as
+`.mdlrc`, and if `foo.rb` contains the custom rules `BAR001` and `BAR002`, then
+these can be used by adding the following lines to `.mdlrc`
+
+```ruby
+rulesets ["#{File.dirname(__FILE__)}/foo.rb"]
+style "#{File.dirname(__FILE__)}/baz.rb"
+```
+
+where `baz.rb` is a style file that contains the contents
+
+```ruby
+rule "BAR001"
+rule "BAR002"
+```
+
+## Rule syntax
+
+Rules are written in ruby, using a rule DSL for defining rules. A rule looks
+like:
+
+```ruby
+rule "MY000", "Rule description" do
+ tags :foo, :bar
+ docs 'https://docs.example.org/more/info#MY000'
+ aliases 'rule-name'
+ params :style => :foo
+ check do |doc|
+ # check code goes here
+ # return a list of line numbers that break the rule, or an empty list
+ # (or nil) if there are no problems.
+ end
+end
+```
+
+The first line specifies the rule name and description. By convention, built in
+markdownlint rules use the prefix 'MD' followed by a number to identify rules.
+Any custom rules should use an alternate prefix to avoid conflicting with
+current or future rules. The description is simply a short description
+explaining what the rule is checking, which will be printed alongside the rule
+name when rules are triggered.
+
+Next, the rule's tags are specified. These are simply ruby symbols, and can be
+used by a user to limit which rules are checks. For example, if your rule
+checks whitespace usage in a document, you can add the `:whitespace` tag, and
+users who don't care about whitespace can exclude that tag on the command line
+or in style files.
+
+You can optionally provide a URL with more context on this rule and why it
+exists. `markdownlint` links to this URL when this rule fails, which can help
+the people receiving a failure understand how to fix it. Docs URLs can also be
+specified once for many rules in a ruleset, the built-in rules
+[use this feature](
+https://github.com/markdownlint/markdownlint/blob/81e99c03f1f096aa200011ff7a1043a6f81167e7/lib/mdl/rules.rb#L1-L5
+) to set a URL dynamically using the rule id and/or description.
+
+You can also specify aliases for the rule, which can be used to refer to the
+rule with a human-readable name rather than MD000. To do this, add then with
+the 'aliases' directive. Whenever you refer to a rule, such as for
+including/excluding in the configuration or in style files, you can use an
+alias for the rule instead of its ID.
+
+After that, any parameters the rule takes are specified. If your rule checks
+for a specific number of things, or if you can envision multiple variants of
+the same rule, then you should add parameters to allow your rule to be
+customized in a style file. Any parameters specified here are accessible inside
+the check itself using `params[:foo]`.
+
+Finally, the check itself is specified. This is simply a ruby block that should
+return a list of line numbers for any issues found. If no line numbers are
+found, you can either return an empty list, or nil, whichever is easiest for
+your check.
+
+### Document objects
+
+The check takes a single parameter `doc`, which is an object containing a
+representation of the markdown document along with several helper functions
+used for making rules. The [doc.rb](../lib/mdl/doc.rb) file is documented using
+rdoc, and you will want to take a look there to see all the methods you can
+use, as well as look at some of the existing rules, but a quick summary is as
+follows:
+
+* `doc` - Object containing a representation of the markdown document
+* `doc.lines` - The raw markdown file as an array of lines
+ * You can also look up a line given an element with
+ `doc.element_line(element)`
+* `doc.parsed` - The kramdown internal representation of the doc. Most of the
+ time you will want to interact with the parsed version of the document
+ rather than looking at `doc.lines`.
+* `doc.find_type_elements` - A method to find all elements of a given type.
+ You pass the type as a symbol, such as `:ul` or `:p`. Most element types
+ match the name of the element in HTML output. This method returns a list of
+ the matching elements.
+* `doc.find_type` - This is like `doc.find_type_elements`, but returns just
+ the options hashes (see below) for each element. This is useful if you don't
+ need all the element information, but you do need the line numbers.
+* `doc.element_line_number` - Pass in an element (or an options hash), and
+ this will return the line number for the element. You need to return the
+ line number in the list of errors.
+
+### Element objects
+
+The document contains an internal representation of the markdown document as
+parsed by kramdown. Kramdown's representation of the document is as a tree of
+'element' objects. The following is a quick summary of those objects:
+
+* element.type - a symbol denoting the type of the element, such as `:li`,
+ `:p`, `:text`
+* element.value - the value of the element. Note that most block level
+ elements such as paragraphs don't have any value themselves, but have child
+ text elements containing their contents instead.
+* element.children - A list of the element's child elements.
+* element.options - A hash containing:
+ * `:location` - line number of element
+ * `:element_level` - A value filled in by markdownlint to denote the nesting
+ level of the element, i.e. how deep in the tree is it.
+ * Other options that are element type specific.
diff --git a/documents/markdown/markdownlint/docs_creating_styles.md b/documents/markdown/markdownlint/docs_creating_styles.md
new file mode 100644
index 0000000..295f738
--- /dev/null
+++ b/documents/markdown/markdownlint/docs_creating_styles.md
@@ -0,0 +1,57 @@
+# Creating styles
+
+A 'style' in markdownlint is simply a ruby file specifying the list of enabled
+and disabled rules, as well as specifying parameters for any rules that need
+parameters different than the defaults.
+
+The various options you can use in a style file are:
+
+* `all` - include all rules
+* `rule` - include a specific rule.
+
+```ruby
+rule 'MD001'
+```
+
+* `exclude_rule` - exclude a previously included rule. Used if you want to
+ include all except for a few rules.
+
+```ruby
+exclude_rule 'MD000'
+```
+
+* `tag` - include all rules that are tagged with a specific value
+
+```ruby
+tag :whitespace
+```
+
+* `exclude_tag` - exclude all rules tagged with the specified tag
+
+```ruby
+exclude_tag :line_length
+```
+
+Note that tags are specified as symbols, and rule names as strings, just as in
+the rule definitions themselves.
+
+The last matching option wins, so you should always put `all` at the top of the
+file (if you want to include all rules), then tags (and tag excludes), then
+specific rules. In other words, go from least to most specific.
+
+## Parameters
+
+If you specify any parameters after a rule ID, then those values will be used
+for the rules instead of the default. You only need to specify parameters for
+any values you wish to override. For example, the default values for the
+parameters in MD030 (spaces after list markers) are all 1. If you still want
+the spaces after the list markers to be 1 in some cases, then you can exclude
+those parameters:
+
+```ruby
+rule 'MD030', :ol_multi => 2, :ul_multi => 3
+```
+
+Even if a rule is included already by a tag specification (or `all`), it is not
+a problem to add a specific `rule` entry in order to set custom parameters, and
+is in fact necessary to do so.
diff --git a/documents/markdown/markdownlint/docs_rolling_a_release.md b/documents/markdown/markdownlint/docs_rolling_a_release.md
new file mode 100644
index 0000000..9921f2f
--- /dev/null
+++ b/documents/markdown/markdownlint/docs_rolling_a_release.md
@@ -0,0 +1,54 @@
+# Rolling a new release
+
+Bump the version. Markdownlint uses semantic versioning. From
+<https://semver.org/>:
+
+* Major version for backwards-incompatible changes
+* Minor version for functionality added in a backwards-compatible manner
+* Patch version for backwards-compatible bug fixes
+* Exception: Versions < 1.0 may introduce backwards-incompatible changes in a
+ minor version.
+
+To bump the version, edit `lib/mdl/version.rb` and commit to the main branch.
+
+Update the changelog:
+
+* Add a new header and link for the new release, replacing any 'Unreleased'
+ header.
+
+```markdown
+## [v0.2.0] (2015-04-13)
+
+This goes at the bottom:
+
+[v0.2.0]: https://github.com/markdownlint/markdownlint/tree/v0.2.0
+```
+
+* Changelog entries can and should be added in an 'Unreleased' section as
+ commits are made. However, the following steps can be performed before each
+ release to catch anything that was missed.
+* Add a 'Rules added' section, listing every new rule added for this version.
+ * Use `git diff v0.1.0..v0.2.0 docs/RULES.md | grep '## MD'` to discover
+ what these are.
+* Search for closed issues:
+ * Go to <https://github.com/markdownlint/markdownlint/issues>
+ * Search for `closed:>1900-01-01`, changing the date to the date
+ of the last release.
+ * From this list of issues, make sections for:
+ * Added - for new features
+ * Changed - for changes in existing functionality
+ * Deprecated - for once-stable features removed in upcoming releases
+ * Removed - for deprecated features removed in this release
+ * Fixed - for any bug fixes
+ * Security - for any security issues
+
+Next, run `rake release`. This will:
+
+* Tag vX.Y.Z in git
+* Upload the new gem to rubygems.org
+
+Then `git push --tags upstream` to push the tag.
+
+Build and push a docker image per the docs in tools/docker/README.md
+
+Finally, add a new 'Unreleased' section to the changelog for the next release.
diff --git a/documents/markdown/markdownlint/emphasis_instead_of_headers.md b/documents/markdown/markdownlint/emphasis_instead_of_headers.md
new file mode 100644
index 0000000..e96f6dd
--- /dev/null
+++ b/documents/markdown/markdownlint/emphasis_instead_of_headers.md
@@ -0,0 +1,42 @@
+**Section 1: the first section {MD036}**
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
+nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore
+eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt
+in culpa qui officia deserunt mollit anim id est laborum.
+
+__Section 1.1: another section {MD036}__
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
+nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore
+eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt
+in culpa qui officia deserunt mollit anim id est laborum.
+
+*Section 2: yet more sections {MD036}*
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
+nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore
+eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt
+in culpa qui officia deserunt mollit anim id est laborum.
+
+_Section 3: oh no more sections {MD036}_
+
+This is a normal paragraph
+**that just happens to have emphasized text in**
+even though the emphasized text is on its own line.
+
+This is another **normal** paragraph with some text in it. This also should
+not trigger the rule.
+
+**This is an entire paragraph that has been emphasized, and shouldn't be
+detected as a header because it's on multiple lines**
+
+**This also shouldn't be detected as a header as it ends in punctuation.**
+
+**[This as well since it is a link](https://example.com)**
diff --git a/documents/markdown/markdownlint/example_exclude_example_README.md b/documents/markdown/markdownlint/example_exclude_example_README.md
new file mode 100644
index 0000000..75e881d
--- /dev/null
+++ b/documents/markdown/markdownlint/example_exclude_example_README.md
@@ -0,0 +1,8 @@
+# Example of a custom .mdlrc and style sheet
+
+This directory has a sample .mdlrc file and the style sheet it calls.
+
+This would be used, for example, in a repository with CI checks that include checking .md
+files where you would have the style sheet and .mdlrc in the same directory as your code.
+
+It will exclude a very long line like this one that would ordinarily be flagged by mdl as a violation.
diff --git a/documents/markdown/markdownlint/example_markdown_spec.md b/documents/markdown/markdownlint/example_markdown_spec.md
new file mode 100644
index 0000000..a8c129f
--- /dev/null
+++ b/documents/markdown/markdownlint/example_markdown_spec.md
@@ -0,0 +1,896 @@
+Markdown: Syntax
+================
+
+<ul id="ProjectSubmenu">
+ <li><a href="/projects/markdown/" title="Markdown Project Page">Main</a></li>
+ <li><a href="/projects/markdown/basics" title="Markdown Basics">Basics</a></li>
+ <li><a class="selected" title="Markdown Syntax Documentation">Syntax</a></li>
+ <li><a href="/projects/markdown/license" title="Pricing and License Information">License</a></li>
+ <li><a href="/projects/markdown/dingus" title="Online Markdown Web Form">Dingus</a></li>
+</ul>
+
+
+* [Overview](#overview)
+ * [Philosophy](#philosophy)
+ * [Inline HTML](#html)
+ * [Automatic Escaping for Special Characters](#autoescape)
+* [Block Elements](#block)
+ * [Paragraphs and Line Breaks](#p)
+ * [Headers](#header)
+ * [Blockquotes](#blockquote)
+ * [Lists](#list)
+ * [Code Blocks](#precode)
+ * [Horizontal Rules](#hr)
+* [Span Elements](#span)
+ * [Links](#link)
+ * [Emphasis](#em)
+ * [Code](#code)
+ * [Images](#img)
+* [Miscellaneous](#misc)
+ * [Backslash Escapes](#backslash)
+ * [Automatic Links](#autolink)
+
+
+**Note:** This document is itself written using Markdown; you
+can [see the source for it by adding '.text' to the URL][src].
+
+ [src]: /projects/markdown/syntax.text
+
+* * *
+
+<h2 id="overview">Overview</h2>
+
+<h3 id="philosophy">Philosophy</h3>
+
+Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
+
+Readability, however, is emphasized above all else. A Markdown-formatted
+document should be publishable as-is, as plain text, without looking
+like it's been marked up with tags or formatting instructions. While
+Markdown's syntax has been influenced by several existing text-to-HTML
+filters -- including [Setext] [1], [atx] [2], [Textile] [3], [reStructuredText] [4],
+[Grutatext] [5], and [EtText] [6] -- the single biggest source of
+inspiration for Markdown's syntax is the format of plain text email.
+
+ [1]: http://docutils.sourceforge.net/mirror/setext.html
+ [2]: http://www.aaronsw.com/2002/atx/
+ [3]: http://textism.com/tools/textile/
+ [4]: http://docutils.sourceforge.net/rst.html
+ [5]: http://www.triptico.com/software/grutatxt.html
+ [6]: http://ettext.taint.org/doc/
+
+To this end, Markdown's syntax is comprised entirely of punctuation
+characters, which punctuation characters have been carefully chosen so
+as to look like what they mean. E.g., asterisks around a word actually
+look like \*emphasis\*. Markdown lists look like, well, lists. Even
+blockquotes look like quoted passages of text, assuming you've ever
+used email.
+
+
+
+<h3 id="html">Inline HTML</h3>
+
+Markdown's syntax is intended for one purpose: to be used as a
+format for *writing* for the web.
+
+Markdown is not a replacement for HTML, or even close to it. Its
+syntax is very small, corresponding only to a very small subset of
+HTML tags. The idea is *not* to create a syntax that makes it easier
+to insert HTML tags. In my opinion, HTML tags are already easy to
+insert. The idea for Markdown is to make it easy to read, write, and
+edit prose. HTML is a *publishing* format; Markdown is a *writing*
+format. Thus, Markdown's formatting syntax only addresses issues that
+can be conveyed in plain text.
+
+For any markup that is not covered by Markdown's syntax, you simply
+use HTML itself. There's no need to preface it or delimit it to
+indicate that you're switching from Markdown to HTML; you just use
+the tags.
+
+The only restrictions are that block-level HTML elements -- e.g. `<div>`,
+`<table>`, `<pre>`, `<p>`, etc. -- must be separated from surrounding
+content by blank lines, and the start and end tags of the block should
+not be indented with tabs or spaces. Markdown is smart enough not
+to add extra (unwanted) `<p>` tags around HTML block-level tags.
+
+For example, to add an HTML table to a Markdown article:
+
+ This is a regular paragraph.
+
+ <table>
+ <tr>
+ <td>Foo</td>
+ </tr>
+ </table>
+
+ This is another regular paragraph.
+
+Note that Markdown formatting syntax is not processed within block-level
+HTML tags. E.g., you can't use Markdown-style `*emphasis*` inside an
+HTML block.
+
+Span-level HTML tags -- e.g. `<span>`, `<cite>`, or `<del>` -- can be
+used anywhere in a Markdown paragraph, list item, or header. If you
+want, you can even use HTML tags instead of Markdown formatting; e.g. if
+you'd prefer to use HTML `<a>` or `<img>` tags instead of Markdown's
+link or image syntax, go right ahead.
+
+Unlike block-level HTML tags, Markdown syntax *is* processed within
+span-level tags.
+
+
+<h3 id="autoescape">Automatic Escaping for Special Characters</h3>
+
+In HTML, there are two characters that demand special treatment: `<`
+and `&`. Left angle brackets are used to start tags; ampersands are
+used to denote HTML entities. If you want to use them as literal
+characters, you must escape them as entities, e.g. `<`, and
+`&`.
+
+Ampersands in particular are bedeviling for web writers. If you want to
+write about 'AT&T', you need to write '`AT&T`'. You even need to
+escape ampersands within URLs. Thus, if you want to link to:
+
+ http://images.google.com/images?num=30&q=larry+bird
+
+you need to encode the URL as:
+
+ http://images.google.com/images?num=30&q=larry+bird
+
+in your anchor tag `href` attribute. Needless to say, this is easy to
+forget, and is probably the single most common source of HTML validation
+errors in otherwise well-marked-up web sites.
+
+Markdown allows you to use these characters naturally, taking care of
+all the necessary escaping for you. If you use an ampersand as part of
+an HTML entity, it remains unchanged; otherwise it will be translated
+into `&`.
+
+So, if you want to include a copyright symbol in your article, you can write:
+
+ ©
+
+and Markdown will leave it alone. But if you write:
+
+ AT&T
+
+Markdown will translate it to:
+
+ AT&T
+
+Similarly, because Markdown supports [inline HTML](#html), if you use
+angle brackets as delimiters for HTML tags, Markdown will treat them as
+such. But if you write:
+
+ 4 < 5
+
+Markdown will translate it to:
+
+ 4 < 5
+
+However, inside Markdown code spans and blocks, angle brackets and
+ampersands are *always* encoded automatically. This makes it easy to use
+Markdown to write about HTML code. (As opposed to raw HTML, which is a
+terrible format for writing about HTML syntax, because every single `<`
+and `&` in your example code needs to be escaped.)
+
+
+* * *
+
+
+<h2 id="block">Block Elements</h2>
+
+
+<h3 id="p">Paragraphs and Line Breaks</h3>
+
+A paragraph is simply one or more consecutive lines of text, separated
+by one or more blank lines. (A blank line is any line that looks like a
+blank line -- a line containing nothing but spaces or tabs is considered
+blank.) Normal paragraphs should not be indented with spaces or tabs.
+
+The implication of the "one or more consecutive lines of text" rule is
+that Markdown supports "hard-wrapped" text paragraphs. This differs
+significantly from most other text-to-HTML formatters (including Movable
+Type's "Convert Line Breaks" option) which translate every line break
+character in a paragraph into a `<br />` tag.
+
+When you *do* want to insert a `<br />` break tag using Markdown, you
+end a line with two or more spaces, then type return.
+
+Yes, this takes a tad more effort to create a `<br />`, but a simplistic
+"every line break is a `<br />`" rule wouldn't work for Markdown.
+Markdown's email-style [blockquoting][bq] and multi-paragraph [list items][l]
+work best -- and look better -- when you format them with hard breaks.
+
+ [bq]: #blockquote
+ [l]: #list
+
+
+
+<h3 id="header">Headers</h3>
+
+Markdown supports two styles of headers, [Setext] [1] and [atx] [2].
+
+Setext-style headers are "underlined" using equal signs (for first-level
+headers) and dashes (for second-level headers). For example:
+
+ This is an H1
+ =============
+
+ This is an H2
+ -------------
+
+Any number of underlining `=`'s or `-`'s will work.
+
+Atx-style headers use 1-6 hash characters at the start of the line,
+corresponding to header levels 1-6. For example:
+
+ # This is an H1
+
+ ## This is an H2
+
+ ###### This is an H6
+
+Optionally, you may "close" atx-style headers. This is purely
+cosmetic -- you can use this if you think it looks better. The
+closing hashes don't even need to match the number of hashes
+used to open the header. (The number of opening hashes
+determines the header level.) :
+
+ # This is an H1 #
+
+ ## This is an H2 ##
+
+ ### This is an H3 ######
+
+
+<h3 id="blockquote">Blockquotes</h3>
+
+Markdown uses email-style `>` characters for blockquoting. If you're
+familiar with quoting passages of text in an email message, then you
+know how to create a blockquote in Markdown. It looks best if you hard
+wrap the text and put a `>` before every line:
+
+ > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
+ > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
+ > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
+ >
+ > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
+ > id sem consectetuer libero luctus adipiscing.
+
+Markdown allows you to be lazy and only put the `>` before the first
+line of a hard-wrapped paragraph:
+
+ > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
+ consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
+ Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
+
+ > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
+ id sem consectetuer libero luctus adipiscing.
+
+Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by
+adding additional levels of `>`:
+
+ > This is the first level of quoting.
+ >
+ > > This is nested blockquote.
+ >
+ > Back to the first level.
+
+Blockquotes can contain other Markdown elements, including headers, lists,
+and code blocks:
+
+ > ## This is a header.
+ >
+ > 1. This is the first list item.
+ > 2. This is the second list item.
+ >
+ > Here's some example code:
+ >
+ > return shell_exec("echo $input | $markdown_script");
+
+Any decent text editor should make email-style quoting easy. For
+example, with BBEdit, you can make a selection and choose Increase
+Quote Level from the Text menu.
+
+
+<h3 id="list">Lists</h3>
+
+Markdown supports ordered (numbered) and unordered (bulleted) lists.
+
+Unordered lists use asterisks, pluses, and hyphens -- interchangably
+-- as list markers:
+
+ * Red
+ * Green
+ * Blue
+
+is equivalent to:
+
+ + Red
+ + Green
+ + Blue
+
+and:
+
+ - Red
+ - Green
+ - Blue
+
+Ordered lists use numbers followed by periods:
+
+ 1. Bird
+ 2. McHale
+ 3. Parish
+
+It's important to note that the actual numbers you use to mark the
+list have no effect on the HTML output Markdown produces. The HTML
+Markdown produces from the above list is:
+
+ <ol>
+ <li>Bird</li>
+ <li>McHale</li>
+ <li>Parish</li>
+ </ol>
+
+If you instead wrote the list in Markdown like this:
+
+ 1. Bird
+ 1. McHale
+ 1. Parish
+
+or even:
+
+ 3. Bird
+ 1. McHale
+ 8. Parish
+
+you'd get the exact same HTML output. The point is, if you want to,
+you can use ordinal numbers in your ordered Markdown lists, so that
+the numbers in your source match the numbers in your published HTML.
+But if you want to be lazy, you don't have to.
+
+If you do use lazy list numbering, however, you should still start the
+list with the number 1. At some point in the future, Markdown may support
+starting ordered lists at an arbitrary number.
+
+List markers typically start at the left margin, but may be indented by
+up to three spaces. List markers must be followed by one or more spaces
+or a tab.
+
+To make lists look nice, you can wrap items with hanging indents:
+
+ * Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
+ Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
+ viverra nec, fringilla in, laoreet vitae, risus.
+ * Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
+ Suspendisse id sem consectetuer libero luctus adipiscing.
+
+But if you want to be lazy, you don't have to:
+
+ * Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
+ Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
+ viverra nec, fringilla in, laoreet vitae, risus.
+ * Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
+ Suspendisse id sem consectetuer libero luctus adipiscing.
+
+If list items are separated by blank lines, Markdown will wrap the
+items in `<p>` tags in the HTML output. For example, this input:
+
+ * Bird
+ * Magic
+
+will turn into:
+
+ <ul>
+ <li>Bird</li>
+ <li>Magic</li>
+ </ul>
+
+But this:
+
+ * Bird
+
+ * Magic
+
+will turn into:
+
+ <ul>
+ <li><p>Bird</p></li>
+ <li><p>Magic</p></li>
+ </ul>
+
+List items may consist of multiple paragraphs. Each subsequent
+paragraph in a list item must be indented by either 4 spaces
+or one tab:
+
+ 1. This is a list item with two paragraphs. Lorem ipsum dolor
+ sit amet, consectetuer adipiscing elit. Aliquam hendrerit
+ mi posuere lectus.
+
+ Vestibulum enim wisi, viverra nec, fringilla in, laoreet
+ vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
+ sit amet velit.
+
+ 2. Suspendisse id sem consectetuer libero luctus adipiscing.
+
+It looks nice if you indent every line of the subsequent
+paragraphs, but here again, Markdown will allow you to be
+lazy:
+
+ * This is a list item with two paragraphs.
+
+ This is the second paragraph in the list item. You're
+ only required to indent the first line. Lorem ipsum dolor
+ sit amet, consectetuer adipiscing elit.
+
+ * Another item in the same list.
+
+To put a blockquote within a list item, the blockquote's `>`
+delimiters need to be indented:
+
+ * A list item with a blockquote:
+
+ > This is a blockquote
+ > inside a list item.
+
+To put a code block within a list item, the code block needs
+to be indented *twice* -- 8 spaces or two tabs:
+
+ * A list item with a code block:
+
+ <code goes here>
+
+
+It's worth noting that it's possible to trigger an ordered list by
+accident, by writing something like this:
+
+ 1986. What a great season.
+
+In other words, a *number-period-space* sequence at the beginning of a
+line. To avoid this, you can backslash-escape the period:
+
+ 1986\. What a great season.
+
+
+
+<h3 id="precode">Code Blocks</h3>
+
+Pre-formatted code blocks are used for writing about programming or
+markup source code. Rather than forming normal paragraphs, the lines
+of a code block are interpreted literally. Markdown wraps a code block
+in both `<pre>` and `<code>` tags.
+
+To produce a code block in Markdown, simply indent every line of the
+block by at least 4 spaces or 1 tab. For example, given this input:
+
+ This is a normal paragraph:
+
+ This is a code block.
+
+Markdown will generate:
+
+ <p>This is a normal paragraph:</p>
+
+ <pre><code>This is a code block.
+ </code></pre>
+
+One level of indentation -- 4 spaces or 1 tab -- is removed from each
+line of the code block. For example, this:
+
+ Here is an example of AppleScript:
+
+ tell application "Foo"
+ beep
+ end tell
+
+will turn into:
+
+ <p>Here is an example of AppleScript:</p>
+
+ <pre><code>tell application "Foo"
+ beep
+ end tell
+ </code></pre>
+
+A code block continues until it reaches a line that is not indented
+(or the end of the article).
+
+Within a code block, ampersands (`&`) and angle brackets (`<` and `>`)
+are automatically converted into HTML entities. This makes it very
+easy to include example HTML source code using Markdown -- just paste
+it and indent it, and Markdown will handle the hassle of encoding the
+ampersands and angle brackets. For example, this:
+
+ <div class="footer">
+ © 2004 Foo Corporation
+ </div>
+
+will turn into:
+
+ <pre><code><div class="footer">
+ &copy; 2004 Foo Corporation
+ </div>
+ </code></pre>
+
+Regular Markdown syntax is not processed within code blocks. E.g.,
+asterisks are just literal asterisks within a code block. This means
+it's also easy to use Markdown to write about Markdown's own syntax.
+
+
+
+<h3 id="hr">Horizontal Rules</h3>
+
+You can produce a horizontal rule tag (`<hr />`) by placing three or
+more hyphens, asterisks, or underscores on a line by themselves. If you
+wish, you may use spaces between the hyphens or asterisks. Each of the
+following lines will produce a horizontal rule:
+
+ * * *
+
+ ***
+
+ *****
+
+ - - -
+
+ ---------------------------------------
+
+
+* * *
+
+<h2 id="span">Span Elements</h2>
+
+<h3 id="link">Links</h3>
+
+Markdown supports two style of links: *inline* and *reference*.
+
+In both styles, the link text is delimited by [square brackets].
+
+To create an inline link, use a set of regular parentheses immediately
+after the link text's closing square bracket. Inside the parentheses,
+put the URL where you want the link to point, along with an *optional*
+title for the link, surrounded in quotes. For example:
+
+ This is [an example](http://example.com/ "Title") inline link.
+
+ [This link](http://example.net/) has no title attribute.
+
+Will produce:
+
+ <p>This is <a href="http://example.com/" title="Title">
+ an example</a> inline link.</p>
+
+ <p><a href="http://example.net/">This link</a> has no
+ title attribute.</p>
+
+If you're referring to a local resource on the same server, you can
+use relative paths:
+
+ See my [About](/about/) page for details.
+
+Reference-style links use a second set of square brackets, inside
+which you place a label of your choosing to identify the link:
+
+ This is [an example][id] reference-style link.
+
+You can optionally use a space to separate the sets of brackets:
+
+ This is [an example] [id] reference-style link.
+
+Then, anywhere in the document, you define your link label like this,
+on a line by itself:
+
+ [id]: http://example.com/ "Optional Title Here"
+
+That is:
+
+* Square brackets containing the link identifier (optionally
+ indented from the left margin using up to three spaces);
+* followed by a colon;
+* followed by one or more spaces (or tabs);
+* followed by the URL for the link;
+* optionally followed by a title attribute for the link, enclosed
+ in double or single quotes, or enclosed in parentheses.
+
+The following three link definitions are equivalent:
+
+ [foo]: http://example.com/ "Optional Title Here"
+ [foo]: http://example.com/ 'Optional Title Here'
+ [foo]: http://example.com/ (Optional Title Here)
+
+**Note:** There is a known bug in Markdown.pl 1.0.1 which prevents
+single quotes from being used to delimit link titles.
+
+The link URL may, optionally, be surrounded by angle brackets:
+
+ [id]: <http://example.com/> "Optional Title Here"
+
+You can put the title attribute on the next line and use extra spaces
+or tabs for padding, which tends to look better with longer URLs:
+
+ [id]: http://example.com/longish/path/to/resource/here
+ "Optional Title Here"
+
+Link definitions are only used for creating links during Markdown
+processing, and are stripped from your document in the HTML output.
+
+Link definition names may consist of letters, numbers, spaces, and
+punctuation -- but they are *not* case sensitive. E.g. these two
+links:
+
+ [link text][a]
+ [link text][A]
+
+are equivalent.
+
+The *implicit link name* shortcut allows you to omit the name of the
+link, in which case the link text itself is used as the name.
+Just use an empty set of square brackets -- e.g., to link the word
+"Google" to the google.com web site, you could simply write:
+
+ [Google][]
+
+And then define the link:
+
+ [Google]: http://google.com/
+
+Because link names may contain spaces, this shortcut even works for
+multiple words in the link text:
+
+ Visit [Daring Fireball][] for more information.
+
+And then define the link:
+
+ [Daring Fireball]: http://daringfireball.net/
+
+Link definitions can be placed anywhere in your Markdown document. I
+tend to put them immediately after each paragraph in which they're
+used, but if you want, you can put them all at the end of your
+document, sort of like footnotes.
+
+Here's an example of reference links in action:
+
+ I get 10 times more traffic from [Google] [1] than from
+ [Yahoo] [2] or [MSN] [3].
+
+ [1]: http://google.com/ "Google"
+ [2]: http://search.yahoo.com/ "Yahoo Search"
+ [3]: http://search.msn.com/ "MSN Search"
+
+Using the implicit link name shortcut, you could instead write:
+
+ I get 10 times more traffic from [Google][] than from
+ [Yahoo][] or [MSN][].
+
+ [google]: http://google.com/ "Google"
+ [yahoo]: http://search.yahoo.com/ "Yahoo Search"
+ [msn]: http://search.msn.com/ "MSN Search"
+
+Both of the above examples will produce the following HTML output:
+
+ <p>I get 10 times more traffic from <a href="http://google.com/"
+ title="Google">Google</a> than from
+ <a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
+ or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
+
+For comparison, here is the same paragraph written using
+Markdown's inline link style:
+
+ I get 10 times more traffic from [Google](http://google.com/ "Google")
+ than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
+ [MSN](http://search.msn.com/ "MSN Search").
+
+The point of reference-style links is not that they're easier to
+write. The point is that with reference-style links, your document
+source is vastly more readable. Compare the above examples: using
+reference-style links, the paragraph itself is only 81 characters
+long; with inline-style links, it's 176 characters; and as raw HTML,
+it's 234 characters. In the raw HTML, there's more markup than there
+is text.
+
+With Markdown's reference-style links, a source document much more
+closely resembles the final output, as rendered in a browser. By
+allowing you to move the markup-related metadata out of the paragraph,
+you can add links without interrupting the narrative flow of your
+prose.
+
+
+<h3 id="em">Emphasis</h3>
+
+Markdown treats asterisks (`*`) and underscores (`_`) as indicators of
+emphasis. Text wrapped with one `*` or `_` will be wrapped with an
+HTML `<em>` tag; double `*`'s or `_`'s will be wrapped with an HTML
+`<strong>` tag. E.g., this input:
+
+ *single asterisks*
+
+ _single underscores_
+
+ **double asterisks**
+
+ __double underscores__
+
+will produce:
+
+ <em>single asterisks</em>
+
+ <em>single underscores</em>
+
+ <strong>double asterisks</strong>
+
+ <strong>double underscores</strong>
+
+You can use whichever style you prefer; the lone restriction is that
+the same character must be used to open and close an emphasis span.
+
+Emphasis can be used in the middle of a word:
+
+ un*frigging*believable
+
+But if you surround an `*` or `_` with spaces, it'll be treated as a
+literal asterisk or underscore.
+
+To produce a literal asterisk or underscore at a position where it
+would otherwise be used as an emphasis delimiter, you can backslash
+escape it:
+
+ \*this text is surrounded by literal asterisks\*
+
+
+
+<h3 id="code">Code</h3>
+
+To indicate a span of code, wrap it with backtick quotes (`` ` ``).
+Unlike a pre-formatted code block, a code span indicates code within a
+normal paragraph. For example:
+
+ Use the `printf()` function.
+
+will produce:
+
+ <p>Use the <code>printf()</code> function.</p>
+
+To include a literal backtick character within a code span, you can use
+multiple backticks as the opening and closing delimiters:
+
+ ``There is a literal backtick (`) here.``
+
+which will produce this:
+
+ <p><code>There is a literal backtick (`) here.</code></p>
+
+The backtick delimiters surrounding a code span may include spaces --
+one after the opening, one before the closing. This allows you to place
+literal backtick characters at the beginning or end of a code span:
+
+ A single backtick in a code span: `` ` ``
+
+ A backtick-delimited string in a code span: `` `foo` ``
+
+will produce:
+
+ <p>A single backtick in a code span: <code>`</code></p>
+
+ <p>A backtick-delimited string in a code span: <code>`foo`</code></p>
+
+With a code span, ampersands and angle brackets are encoded as HTML
+entities automatically, which makes it easy to include example HTML
+tags. Markdown will turn this:
+
+ Please don't use any `<blink>` tags.
+
+into:
+
+ <p>Please don't use any <code><blink></code> tags.</p>
+
+You can write this:
+
+ `—` is the decimal-encoded equivalent of `—`.
+
+to produce:
+
+ <p><code>&#8212;</code> is the decimal-encoded
+ equivalent of <code>&mdash;</code>.</p>
+
+
+
+<h3 id="img">Images</h3>
+
+Admittedly, it's fairly difficult to devise a "natural" syntax for
+placing images into a plain text document format.
+
+Markdown uses an image syntax that is intended to resemble the syntax
+for links, allowing for two styles: *inline* and *reference*.
+
+Inline image syntax looks like this:
+
+ 
+
+ 
+
+That is:
+
+* An exclamation mark: `!`;
+* followed by a set of square brackets, containing the `alt`
+ attribute text for the image;
+* followed by a set of parentheses, containing the URL or path to
+ the image, and an optional `title` attribute enclosed in double
+ or single quotes.
+
+Reference-style image syntax looks like this:
+
+ ![Alt text][id]
+
+Where "id" is the name of a defined image reference. Image references
+are defined using syntax identical to link references:
+
+ [id]: url/to/image "Optional title attribute"
+
+As of this writing, Markdown has no syntax for specifying the
+dimensions of an image; if this is important to you, you can simply
+use regular HTML `<img>` tags.
+
+
+* * *
+
+
+<h2 id="misc">Miscellaneous</h2>
+
+<h3 id="autolink">Automatic Links</h3>
+
+Markdown supports a shortcut style for creating "automatic" links for URLs and email addresses: simply surround the URL or email address with angle brackets. What this means is that if you want to show the actual text of a URL or email address, and also have it be a clickable link, you can do this:
+
+ <http://example.com/>
+
+Markdown will turn this into:
+
+ <a href="http://example.com/">http://example.com/</a>
+
+Automatic links for email addresses work similarly, except that
+Markdown will also perform a bit of randomized decimal and hex
+entity-encoding to help obscure your address from address-harvesting
+spambots. For example, Markdown will turn this:
+
+ <address@example.com>
+
+into something like this:
+
+ <a href="mailto:addre
+ ss@example.co
+ m">address@exa
+ mple.com</a>
+
+which will render in a browser as a clickable link to "address@example.com".
+
+(This sort of entity-encoding trick will indeed fool many, if not
+most, address-harvesting bots, but it definitely won't fool all of
+them. It's better than nothing, but an address published in this way
+will probably eventually start receiving spam.)
+
+
+
+<h3 id="backslash">Backslash Escapes</h3>
+
+Markdown allows you to use backslash escapes to generate literal
+characters which would otherwise have special meaning in Markdown's
+formatting syntax. For example, if you wanted to surround a word
+with literal asterisks (instead of an HTML `<em>` tag), you can use
+backslashes before the asterisks, like this:
+
+ \*literal asterisks\*
+
+Markdown provides backslash escapes for the following characters:
+
+ \ backslash
+ ` backtick
+ * asterisk
+ _ underscore
+ {} curly braces
+ [] square brackets
+ () parentheses
+ # hash mark
+ + plus sign
+ - minus sign (hyphen)
+ . dot
+ ! exclamation mark
diff --git a/documents/markdown/markdownlint/fenced_code_blocks.md b/documents/markdown/markdownlint/fenced_code_blocks.md
new file mode 100644
index 0000000..cf90284
--- /dev/null
+++ b/documents/markdown/markdownlint/fenced_code_blocks.md
@@ -0,0 +1,27 @@
+This is a GFM-style fenced code block:
+
+``` bash
+#!/bin/bash
+
+# Print something to stdout:
+echo "Hello"
+echo "World"
+```
+
+This is a kramdown-style fenced code block:
+
+~~~ bash
+#!/bin/bash
+
+# Print something to stdout:
+echo "Hello"
+echo "World"
+~~~
+
+None of the above should trigger any heading related rules.
+
+```
+Code block without a language specifier
+```
+
+{MD040:23}
diff --git a/documents/markdown/markdownlint/fenced_code_blocks_in_lists.md b/documents/markdown/markdownlint/fenced_code_blocks_in_lists.md
new file mode 100644
index 0000000..ed5302a
--- /dev/null
+++ b/documents/markdown/markdownlint/fenced_code_blocks_in_lists.md
@@ -0,0 +1,40 @@
+# test doc
+
+this is some text
+
+* This is a list item
+
+ ```fenced
+ this is a code block within the list item.
+ ```
+
+ with more text here
+
+* and another list item here
+
+And another paragraph.
+
+ But this code block {MD046}
+
+ is *NOT* in a list and should error.
+
+And in addition to that...
+
+ ```text
+ This code block is both indented
+ and fenced and should *also* error.
+ ```
+
+And finally:
+
+```text
+This is a code block
+
+ And this is a code block in a code block and should *not* error
+
+More stuff here
+```
+
+all
+
+{MD046:23}
diff --git a/documents/markdown/markdownlint/fenced_code_with_nesting.md b/documents/markdown/markdownlint/fenced_code_with_nesting.md
new file mode 100644
index 0000000..373399e
--- /dev/null
+++ b/documents/markdown/markdownlint/fenced_code_with_nesting.md
@@ -0,0 +1,73 @@
+# header
+
+text
+```fence {MD031}
+code
+``` {MD031}
+text
+~~~fence {MD031}
+code
+~~~ {MD031}
+text
+```fence {MD031}
+~~~fence
+code
+~~~
+``` {MD031}
+text
+~~~fence {MD031}
+```fence
+code
+```
+~~~ {MD031}
+text
+```fence {MD031}
+
+~~~fence
+code
+~~~
+
+``` {MD031}
+text
+~~~fence {MD031}
+
+```fence
+code
+```
+
+~~~ {MD031}
+text
+```fence {MD031}
+code
+~~~
+``` {MD031}
+text
+~~~fence {MD031}
+code
+```
+~~~ {MD031}
+text
+````fence {MD031}
+```fence
+code
+```
+```` {MD031}
+text
+~~~~fence {MD031}
+~~~fence
+code
+~~~
+~~~~ {MD031}
+text
+````fence {MD031}
+```fence
+code
+```
+````` {MD031}
+text
+~~~~fence {MD031}
+~~~fence
+code
+~~~
+~~~~~ {MD031}
+text
diff --git a/documents/markdown/markdownlint/fenced_code_without_blank_lines.md b/documents/markdown/markdownlint/fenced_code_without_blank_lines.md
new file mode 100644
index 0000000..c40cdc4
--- /dev/null
+++ b/documents/markdown/markdownlint/fenced_code_without_blank_lines.md
@@ -0,0 +1,42 @@
+```
+code at start of file
+```
+
+text
+
+```ruby
+code
+```
+
+text
+``` {MD031}
+code
+``` {MD031}
+text
+
+```
+code
+``` {MD031}
+text
+
+text
+``` {MD031}
+code
+```
+
+text
+
+```js
+code
+code
+code
+```
+
+```html
+```
+
+text
+
+```
+code at end of file without newline
+```{MD047}
\ No newline at end of file
diff --git a/documents/markdown/markdownlint/file_ends_with_single_newline_character_bad.md b/documents/markdown/markdownlint/file_ends_with_single_newline_character_bad.md
new file mode 100644
index 0000000..68b0063
--- /dev/null
+++ b/documents/markdown/markdownlint/file_ends_with_single_newline_character_bad.md
@@ -0,0 +1,3 @@
+# File not ending with a single newline character
+
+This file does not end with a single newline character{MD047}
\ No newline at end of file
diff --git a/documents/markdown/markdownlint/fix_102_extra_nodes_in_link_text.md b/documents/markdown/markdownlint/fix_102_extra_nodes_in_link_text.md
new file mode 100644
index 0000000..07d0bba
--- /dev/null
+++ b/documents/markdown/markdownlint/fix_102_extra_nodes_in_link_text.md
@@ -0,0 +1,8 @@
+[test _test_ test](www.test.com)
+[test `test` test](www.test.com)
+[test *test* test](www.test.com)
+[test *test* *test* test](www.test.com)
+[test *test* *test* *test* test](www.test.com)
+[test **test** test](www.test.com)
+[test __test__ test](www.test.com)
+[this should not raise](www.shouldnotraise.com)
diff --git a/documents/markdown/markdownlint/header_trailing_punctuation.md b/documents/markdown/markdownlint/header_trailing_punctuation.md
new file mode 100644
index 0000000..66dde23
--- /dev/null
+++ b/documents/markdown/markdownlint/header_trailing_punctuation.md
@@ -0,0 +1,15 @@
+# Heading 1 {MD026}.
+
+## Heading 2 {MD026},
+
+## Heading 3 {MD026}!
+
+## Heading 4 {MD026}:
+
+## Heading 5 {MD026};
+
+## Heading 6 {MD026}?
+
+## :warning: WARNING :warning:
+
+## Heading with emoji :rocket:
diff --git a/documents/markdown/markdownlint/header_trailing_punctuation_customized.md b/documents/markdown/markdownlint/header_trailing_punctuation_customized.md
new file mode 100644
index 0000000..e44f548
--- /dev/null
+++ b/documents/markdown/markdownlint/header_trailing_punctuation_customized.md
@@ -0,0 +1,14 @@
+# Heading 1 {MD026}.
+
+## Heading 2 {MD026},
+
+## Heading 3 {MD026}!
+
+## Heading 4 {MD026}:
+
+## Heading 5 {MD026};
+
+## Heading 6?
+
+The rule has been customized to allow question marks while disallowing
+everything else.
diff --git a/documents/markdown/markdownlint/headers_good_with_issue_numbers.md b/documents/markdown/markdownlint/headers_good_with_issue_numbers.md
new file mode 100644
index 0000000..824fae2
--- /dev/null
+++ b/documents/markdown/markdownlint/headers_good_with_issue_numbers.md
@@ -0,0 +1,12 @@
+# Heading 1
+
+## Heading 2
+
+See the following issues:
+
+* #1234
+* #5678 (and related)
+ * #5678
+ * #9101
+
+## Heading 3
diff --git a/documents/markdown/markdownlint/headers_surrounding_space_atx.md b/documents/markdown/markdownlint/headers_surrounding_space_atx.md
new file mode 100644
index 0000000..da18557
--- /dev/null
+++ b/documents/markdown/markdownlint/headers_surrounding_space_atx.md
@@ -0,0 +1,12 @@
+# Header 1
+
+## Header 2 {MD022}
+Some text
+## Header 3 {MD022}
+Some text
+## Header 4 {MD022}
+
+## Header 5
+
+* This shouldn't trigger MD022, but did because of some bug where we tried to
+ #catch headers that kramdown didn't parse correctly.
diff --git a/documents/markdown/markdownlint/headers_surrounding_space_setext.md b/documents/markdown/markdownlint/headers_surrounding_space_setext.md
new file mode 100644
index 0000000..8099bfd
--- /dev/null
+++ b/documents/markdown/markdownlint/headers_surrounding_space_setext.md
@@ -0,0 +1,15 @@
+Header 1
+========
+
+Header 2 {MD022}
+----------------
+Some text
+Header 3 {MD022}
+================
+Some text
+Header 4 {MD022}
+================
+Some text
+
+Header 5
+--------
diff --git a/documents/markdown/markdownlint/headers_with_spaces_at_the_beginning.md b/documents/markdown/markdownlint/headers_with_spaces_at_the_beginning.md
new file mode 100644
index 0000000..e2d5c0c
--- /dev/null
+++ b/documents/markdown/markdownlint/headers_with_spaces_at_the_beginning.md
@@ -0,0 +1,20 @@
+Some text
+
+ # Header 1 {MD023}
+
+ Setext style fully indented {MD023}
+ ===================================
+
+ Setext style title only indented {MD023}
+=========================================
+
+* Test situations in which MD023 shouldn't be triggered.
+
+ ```rb
+ # This shouldn't trigger MD023 as it is a code comment.
+ foo = "And here is some code"
+ ```
+
+* This is another case where MD023 shouldn't be triggered
+ # Test
+ # Test
diff --git a/documents/markdown/markdownlint/hr_style_dashes.md b/documents/markdown/markdownlint/hr_style_dashes.md
new file mode 100644
index 0000000..9a69225
--- /dev/null
+++ b/documents/markdown/markdownlint/hr_style_dashes.md
@@ -0,0 +1,22 @@
+***
+
+* * *
+
+*****
+
+---
+
+- - -
+
+-----
+
+___
+
+_ _ _
+
+_____
+
+***
+
+{MD035:1} {MD035:3} {MD035:5} {MD035:9} {MD035:11} {MD035:13} {MD035:15}
+{MD035:17} {MD035:19}
diff --git a/documents/markdown/markdownlint/hr_style_inconsistent.md b/documents/markdown/markdownlint/hr_style_inconsistent.md
new file mode 100644
index 0000000..df3cc72
--- /dev/null
+++ b/documents/markdown/markdownlint/hr_style_inconsistent.md
@@ -0,0 +1,22 @@
+***
+
+* * *
+
+*****
+
+---
+
+- - -
+
+-----
+
+___
+
+_ _ _
+
+_____
+
+***
+
+{MD035:3} {MD035:5} {MD035:7} {MD035:9} {MD035:11} {MD035:13} {MD035:15}
+{MD035:17}
diff --git a/documents/markdown/markdownlint/hr_style_long.md b/documents/markdown/markdownlint/hr_style_long.md
new file mode 100644
index 0000000..0e9b1db
--- /dev/null
+++ b/documents/markdown/markdownlint/hr_style_long.md
@@ -0,0 +1,22 @@
+***
+
+* * *
+
+*****
+
+---
+
+- - -
+
+-----
+
+___
+
+_ _ _
+
+_____
+
+***
+
+{MD035:1} {MD035:3} {MD035:5} {MD035:7} {MD035:9} {MD035:11} {MD035:13}
+{MD035:15} {MD035:19}
diff --git a/documents/markdown/markdownlint/inconsistent_bullet_styles_asterisk.md b/documents/markdown/markdownlint/inconsistent_bullet_styles_asterisk.md
new file mode 100644
index 0000000..ac1378a
--- /dev/null
+++ b/documents/markdown/markdownlint/inconsistent_bullet_styles_asterisk.md
@@ -0,0 +1,9 @@
+* Item
+ + Item {MD004}
+ - Item {MD004}
+ * Item
+
+> * Item
+> + Item {MD004}
+> - Item {MD004}
+> * Item
diff --git a/documents/markdown/markdownlint/inconsistent_bullet_styles_dash.md b/documents/markdown/markdownlint/inconsistent_bullet_styles_dash.md
new file mode 100644
index 0000000..a8aaf6e
--- /dev/null
+++ b/documents/markdown/markdownlint/inconsistent_bullet_styles_dash.md
@@ -0,0 +1,9 @@
+- Item
+ * Item {MD004}
+ + Item {MD004}
+ - Item
+
+> - Item
+> * Item {MD004}
+> + Item {MD004}
+> - Item
diff --git a/documents/markdown/markdownlint/inconsistent_bullet_styles_plus.md b/documents/markdown/markdownlint/inconsistent_bullet_styles_plus.md
new file mode 100644
index 0000000..f7e7d3b
--- /dev/null
+++ b/documents/markdown/markdownlint/inconsistent_bullet_styles_plus.md
@@ -0,0 +1,9 @@
++ Item
+ * Item {MD004}
+ - Item {MD004}
+ + Item
+
+> + Item
+> * Item {MD004}
+> - Item {MD004}
+> + Item
diff --git a/documents/markdown/markdownlint/inline_html.md b/documents/markdown/markdownlint/inline_html.md
new file mode 100644
index 0000000..96af8cf
--- /dev/null
+++ b/documents/markdown/markdownlint/inline_html.md
@@ -0,0 +1,19 @@
+# Regular header
+
+<h1>Inline HTML Header {MD033}</h1>
+
+<p>More inline HTML {MD033}
+but this time on multiple lines
+</p>
+
+ <h1>This shouldn't trigger as it's inside a code block</h1>
+
+```text
+<p>Neither should this as it's also in a code block</p>
+```
+
+The rule has been customized to allow some elements while disallowing
+everything else.
+
+Test case for the line break element<br>
+present on `allowed_elements` and it should be permitted.
diff --git a/documents/markdown/markdownlint/links.md b/documents/markdown/markdownlint/links.md
new file mode 100644
index 0000000..4abcb09
--- /dev/null
+++ b/documents/markdown/markdownlint/links.md
@@ -0,0 +1,13 @@
+# Link test
+
+For more information, please see the
+following page: http://www.example.com/ {MD034}
+which will tell you all you want to know.
+
+http://www.google.com/ {MD034}
+
+This link should be fine: <http://www.google.com/>
+
+* [Pipe | in link text](https://example.com)
+
+* [Text | More text](https://blog.sean.taipei/2017/05/test)
diff --git a/documents/markdown/markdownlint/lists_without_blank_lines.md b/documents/markdown/markdownlint/lists_without_blank_lines.md
new file mode 100644
index 0000000..07cddc3
--- /dev/null
+++ b/documents/markdown/markdownlint/lists_without_blank_lines.md
@@ -0,0 +1,75 @@
+* list (on first line)
+
+text
+
+* list
+
+text
+* list {MD032}
+text
++ list {MD032}
+text
+- list {MD032}
+text
+1. list {MD032}
+text
+
+* list
+* list {MD032}
+text
+
+text
+10. list {MD032}
+20. list
+
+text
+
+* list
+ * list
+ * list
+
+text
+
+* list
+ with hanging indent
+ * list
+ with hanging indent
+* list
+ with hanging indent
+
+Note: list without hanging indent violates MD032
+
+* list
+
+ item with blank lines
+
+* list
+
+ item with blank lines
+
+text
+
+```js
+/*
+ * code block
+ * not a list
+ */
+```
+
+text
+
+* list {MD032}
+``` {MD031}
+code
+```
+
+text
+
+```
+code
+``` {MD031}
+* list {MD032}
+
+text
+
+* list (on last line without newline){MD047}
\ No newline at end of file
diff --git a/documents/markdown/markdownlint/long_lines.md b/documents/markdown/markdownlint/long_lines.md
new file mode 100644
index 0000000..a1c30c9
--- /dev/null
+++ b/documents/markdown/markdownlint/long_lines.md
@@ -0,0 +1,3 @@
+This is a very very very very very very very very very very very very very very long line {MD013}
+
+This line however, while very long, doesn't have whitespace after the 80th columnwhichallowsforURLsandotherlongthings. {MD013}
diff --git a/documents/markdown/markdownlint/long_lines_100.md b/documents/markdown/markdownlint/long_lines_100.md
new file mode 100644
index 0000000..9769a5e
--- /dev/null
+++ b/documents/markdown/markdownlint/long_lines_100.md
@@ -0,0 +1,7 @@
+This is a very very very very very very very very long line over 80 chars but less than 100
+
+This is a very very very very very very very very very very long line over 80 chars, and also over 100. {MD013}
+
+This is a very very very very very very very very very long line that is exactly 100 characters long
+
+This line however, while very long, doesn't have whitespace after the 100th columnwhichallowsforURLsandotherlongthings. {MD013}
diff --git a/documents/markdown/markdownlint/long_lines_code.md b/documents/markdown/markdownlint/long_lines_code.md
new file mode 100644
index 0000000..633249e
--- /dev/null
+++ b/documents/markdown/markdownlint/long_lines_code.md
@@ -0,0 +1,45 @@
+This is a short line.
+
+This is a very very very very very very very very very very very very very very very very very very very very long line. {MD013}
+
+This is a short line.
+
+```text
+Here is a short line in a code block.
+Here is a very very very very very very very very very very very very very very very very very very very long line in a code block.
+```
+
+```text
+test
+test
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
+```
+
+This is a short line.
+
+| First Header | Second Header | Third Header | Fourth Header | Fifth Header | Sixth Header |
+| ------------- | ------------- | ------------- | ------------- | ------------- | ------------- |
+| Content Cell | Content Cell | Content Cell | Content Cell | Content Cell | Content Cell |
+| Content Cell | Content Cell | Content Cell | Content Cell | Content Cell | Content Cell |
+| ------------- | ------------- | ------------- | ------------- | ------------- | ------------- |
+| Content Cell | Content Cell | Content Cell | Content Cell | Content Cell | Content Cell |
+| Content Cell | Content Cell | Content Cell | Content Cell | Content Cell | Content Cell |
+| ============= | ============= | ============= | ============= | ============= | ============= |
+| Footer Cell | Footer Cell | Footer Cell | Footer Cell | Footer Cell | Footer Cell |
+{: rules="groups"}
+
+This is a very very very very very very very very very very very very very very very very very very very very long line. {MD013}
+
+Another line.
+
+| First Header | Second Header | Third Header | Fourth Header | Fifth Header | Sixth Header |
+| ------------- | ------------- | ------------- | ------------- | ------------- | ------------- |
+| Content Cell | Content Cell | Content Cell | Content Cell | Content Cell | Content Cell |
+| Content Cell | Content Cell | Content Cell | Content Cell | Content Cell | Content Cell |
+| ------------- | ------------- | ------------- | ------------- | ------------- | ------------- |
+| Content Cell | Content Cell | Content Cell | Content Cell | Content Cell | Content Cell |
+| Content Cell | Content Cell | Content Cell | Content Cell | Content Cell | Content Cell |
+| ============= | ============= | ============= | ============= | ============= | ============= |
+| Footer Cell | Footer Cell | Footer Cell | Footer Cell | Footer Cell | Footer Cell |
+{: rules="groups"}
diff --git a/documents/markdown/markdownlint/md013_ignore_long_lines_in_code_block.md b/documents/markdown/markdownlint/md013_ignore_long_lines_in_code_block.md
new file mode 100644
index 0000000..419ac6e
--- /dev/null
+++ b/documents/markdown/markdownlint/md013_ignore_long_lines_in_code_block.md
@@ -0,0 +1,10 @@
+This is a short line.
+
+This is a very very very very very very very very very very very very very very very very very very very very long line. {MD013}
+
+This is a short line.
+
+```text
+Here is a short line in a code block.
+Here is a very very very very very very very very very very very very very very very very very very very long line in a code block.
+```
diff --git a/documents/markdown/markdownlint/md013_ignore_long_lines_in_headers.md b/documents/markdown/markdownlint/md013_ignore_long_lines_in_headers.md
new file mode 100644
index 0000000..1756aba
--- /dev/null
+++ b/documents/markdown/markdownlint/md013_ignore_long_lines_in_headers.md
@@ -0,0 +1,9 @@
+# This is a very very very very very very very very very very very very very very very very very very long heading
+
+This is a short line.
+
+This is a very very very very very very very very very very very very very very very very very very very very long line. {MD013}
+
+This is a short line.
+
+## This is another very very very very very very very very very very very very very very very very very long heading
diff --git a/documents/markdown/markdownlint/md013_ignore_long_lines_in_tables.md b/documents/markdown/markdownlint/md013_ignore_long_lines_in_tables.md
new file mode 100644
index 0000000..4c6de29
--- /dev/null
+++ b/documents/markdown/markdownlint/md013_ignore_long_lines_in_tables.md
@@ -0,0 +1,16 @@
+This is a short line.
+
+This is a very very very very very very very very very very very very very very very very very very very very long line. {MD013}
+
+This is a short line.
+
+| Column A | Column B | Column C | Column D | Column E | Column F | Column G | Column H | Column I |
+| -------- | -------- | -------- | -------- | -------- | -------- | -------- | -------- | -------- |
+| Cell A | Cell B | Cell C | Cell D | Cell E | Cell F | Cell G | Cell H | Cell I |
+
+This line is fine.
+
+# Header
+| Column A | Column B | Column C | Column D | Column E | Column F | Column G | Column H | Column I |
+| -------- | -------- | -------- | -------- | -------- | -------- | -------- | -------- | -------- |
+| Cell A | Cell B | Cell C | Cell D | Cell E | Cell F | Cell G | Cell H | Cell I |
diff --git a/documents/markdown/markdownlint/mixed_list_type_indent.md b/documents/markdown/markdownlint/mixed_list_type_indent.md
new file mode 100644
index 0000000..652b5a7
--- /dev/null
+++ b/documents/markdown/markdownlint/mixed_list_type_indent.md
@@ -0,0 +1,7 @@
+# Mixed ordered and unordered lists
+
+1. Ordered level one
+ 1. Ordered level two
+
+- Unordered level one
+ - Unordered level two
diff --git a/documents/markdown/markdownlint/ordered_list_item_prefix.md b/documents/markdown/markdownlint/ordered_list_item_prefix.md
new file mode 100644
index 0000000..35f7313
--- /dev/null
+++ b/documents/markdown/markdownlint/ordered_list_item_prefix.md
@@ -0,0 +1,19 @@
+Good list:
+
+1. Do this.
+1. Do that.
+1. ???
+1. Profit!
+
+Bad list:
+
+1. Do this.
+2. Do nothing. {MD029}
+3. ??? {MD029}
+4. Failed! {MD029}
+
+Good list in blockquote:
+
+> 1. Do this.
+> 1. Do that.
+> 1. Profit!
diff --git a/documents/markdown/markdownlint/ordered_list_item_prefix_ordered.md b/documents/markdown/markdownlint/ordered_list_item_prefix_ordered.md
new file mode 100644
index 0000000..1d9895d
--- /dev/null
+++ b/documents/markdown/markdownlint/ordered_list_item_prefix_ordered.md
@@ -0,0 +1,13 @@
+Good list:
+
+1. Do this.
+2. Do that.
+3. ???
+4. Profit!
+
+Bad list:
+
+1. Do this.
+1. Do nothing. {MD029}
+1. ??? {MD029}
+1. Failed! {MD029}
diff --git a/documents/markdown/markdownlint/reversed_link.md b/documents/markdown/markdownlint/reversed_link.md
new file mode 100644
index 0000000..8fa769c
--- /dev/null
+++ b/documents/markdown/markdownlint/reversed_link.md
@@ -0,0 +1,9 @@
+Go to (this website)[http://www.example.com] {MD011} {MD034}
+
+However, this shouldn't trigger inside code blocks:
+
+```fenced
+myObj.getFiles("test")[0]
+```
+
+Nor inline code: `myobj.getFiles("test")[0]`
diff --git a/documents/markdown/markdownlint/spaces_after_list_marker.md b/documents/markdown/markdownlint/spaces_after_list_marker.md
new file mode 100644
index 0000000..f9eee73
--- /dev/null
+++ b/documents/markdown/markdownlint/spaces_after_list_marker.md
@@ -0,0 +1,74 @@
+Normal list
+
+* Foo
+* Bar
+* Baz
+
+List with incorrect spacing
+
+* Foo {MD030}
+* Bar {MD030}
+* Baz {MD030}
+
+List with children:
+
+* Foo {MD030}
+ * Bar {MD030}
+ * Baz
+
+List with children and correct spacing:
+
+* Foo
+ * Bar
+ * Baz (This sublist has no children)
+
+List with Multiple paragraphs and correct spacing
+
+* Foo
+
+ Here is the second paragraph
+
+* All items in the list need the same indent
+
+List with multiple paragraphs and incorrect spacing
+
+* Foo {MD030}
+
+ Here is the second paragraph
+
+* Bar {MD030}
+
+List with code blocks:
+
+* Foo
+
+ Here is some code
+
+* Bar
+
+Ordered lists:
+
+1. Foo
+1. Bar
+1. Baz
+
+And with incorrect spacing:
+
+1. Foo {MD030}
+1. Bar {MD030}
+1. Baz {MD030}
+
+Ordered lists with children:
+
+1. Foo {MD030}
+ * Hi
+1. Bar {MD030}
+1. Baz {MD030}
+
+Ordered lists with children (correct spacing), and with something other than
+the first item determining that the entire list has children:
+
+1. Foo
+1. Bar
+ * Hi
+1. Baz
diff --git a/documents/markdown/markdownlint/spaces_inside_codespan_elements.md b/documents/markdown/markdownlint/spaces_inside_codespan_elements.md
new file mode 100644
index 0000000..9403797
--- /dev/null
+++ b/documents/markdown/markdownlint/spaces_inside_codespan_elements.md
@@ -0,0 +1,8 @@
+`normal codespan element`
+
+`codespan element with space inside right ` {MD038}
+
+We SHOULD have the following two tests marked with MD038 failurs
+` codespan element with space inside left`
+` codespan element with spaces inside ` but
+kramdown doesn't see that as a codespans so we can't detect them anymore.
diff --git a/documents/markdown/markdownlint/spaces_inside_emphasis_markers.md b/documents/markdown/markdownlint/spaces_inside_emphasis_markers.md
new file mode 100644
index 0000000..e2c9511
--- /dev/null
+++ b/documents/markdown/markdownlint/spaces_inside_emphasis_markers.md
@@ -0,0 +1,35 @@
+Line with *Normal emphasis*
+
+Line with **Normal strong**
+
+Line with _Normal emphasis_
+
+Line with __Normal strong__
+
+Broken * emphasis * with spaces in {MD037}
+
+Broken ** strong ** with spaces in {MD037}
+
+Broken _ emphasis _ with spaces in {MD037}
+
+Broken __ strong __ with spaces in {MD037}
+
+Mixed *ok emphasis* and * broken emphasis * {MD037}
+
+Mixed **ok strong** and ** broken strong ** {MD037}
+
+Mixed _ok emphasis_ and _ broken emphasis _ {MD037}
+
+Mixed __ok strong__ and __ broken strong __ {MD037}
+
+Mixed *ok emphasis* **ok strong** * broken emphasis * {MD037}
+
+Multiple * broken emphasis * _ broken emphasis _ {MD037}
+
+One-sided *broken emphasis * {MD037}
+
+One-sided * broken emphasis* {MD037}
+
+Don't _flag on _words with underscores before them.
+
+The same goes for words* with asterisks* after them.
diff --git a/documents/markdown/markdownlint/spaces_inside_link_text.md b/documents/markdown/markdownlint/spaces_inside_link_text.md
new file mode 100644
index 0000000..e05f50a
--- /dev/null
+++ b/documents/markdown/markdownlint/spaces_inside_link_text.md
@@ -0,0 +1,28 @@
+[](http://bar/)
+
+[foo](http://bar/)
+
+["foo"](http:/bar/)
+
+[`foo`](http://bar/)
+
+[*foo*](http://bar/)
+
+[**foo**](http://bar/)
+
+[foo "bar"](http:/baz/)
+
+[foo ](http://bar/) {MD039}
+
+[ foo](http://bar/) {MD039}
+
+[ foo ](http://bar/) {MD039}
+
+[ "foo" ](http://bar/) {MD039}
+
+[ `foo` ](http://bar/) {MD039}
+
+[ *foo* ](http://bar/) {MD039}
+
+The following shouldn't break anything:
+[](/images/Screenshot.png)
diff --git a/documents/markdown/markdownlint/test_fixtures_front_matter_jekyll_post.md b/documents/markdown/markdownlint/test_fixtures_front_matter_jekyll_post.md
new file mode 100644
index 0000000..3b75370
--- /dev/null
+++ b/documents/markdown/markdownlint/test_fixtures_front_matter_jekyll_post.md
@@ -0,0 +1,16 @@
+---
+layout: post
+title: Hello World!
+category: Meta
+tags:
+- tag
+- another tag
+- one more tag
+url: http://example.com
+excerpt: Hello World! Vestibulum imperdiet adipiscing arcu, quis aliquam dolor condimentum dapibus. Aliquam fermentum leo aliquet quam volutpat et molestie mauris mattis. Suspendisse semper consequat velit in suscipit.
+---
+# header1
+
+This is just a sample post.
+
+### offending header3
diff --git a/documents/markdown/markdownlint/test_fixtures_front_matter_jekyll_post_2.md b/documents/markdown/markdownlint/test_fixtures_front_matter_jekyll_post_2.md
new file mode 100644
index 0000000..e34bbf9
--- /dev/null
+++ b/documents/markdown/markdownlint/test_fixtures_front_matter_jekyll_post_2.md
@@ -0,0 +1,17 @@
+---
+layout: post
+title: Hello World!
+category: Meta
+tags:
+- tag
+- another tag
+- one more tag
+url: http://example.com
+excerpt: Hello World! Vestibulum imperdiet adipiscing arcu, quis aliquam dolor condimentum dapibus. Aliquam fermentum leo aliquet quam volutpat et molestie mauris mattis. Suspendisse semper consequat velit in suscipit.
+---
+
+# header1
+
+This is just a sample post.
+
+### offending header3
diff --git a/documents/markdown/markdownlint/test_rule_tests_trailing_spaces_br.md b/documents/markdown/markdownlint/test_rule_tests_trailing_spaces_br.md
new file mode 100644
index 0000000..a619772
--- /dev/null
+++ b/documents/markdown/markdownlint/test_rule_tests_trailing_spaces_br.md
@@ -0,0 +1,4 @@
+This line has a single trailing space {MD009}
+This line has two trailing spaces and should be allowed
+This line has three trailing spaces {MD009}
+This line has four trailing spaces {MD009}
diff --git a/documents/markdown/markdownlint/tools_README.md b/documents/markdown/markdownlint/tools_README.md
new file mode 100644
index 0000000..d5311f1
--- /dev/null
+++ b/documents/markdown/markdownlint/tools_README.md
@@ -0,0 +1,5 @@
+# Tools
+
+This directory contains a few scripts that, while not part of markdownlint
+directly, can be useful for inspecting markdown documents and debugging
+issues.
diff --git a/documents/markdown/markdownlint/tools_docker_README.md b/documents/markdown/markdownlint/tools_docker_README.md
new file mode 100644
index 0000000..6c1d583
--- /dev/null
+++ b/documents/markdown/markdownlint/tools_docker_README.md
@@ -0,0 +1,27 @@
+# Docker container for markdownlint
+
+## Using the docker image
+
+To check a single file:
+
+```shell
+docker run --rm -v ${PWD}:/data markdownlint/markdownlint myfile.md
+```
+
+Or, to check all files in a directory:
+
+```shell
+docker run --rm -v ${PWD}:/data markdownlint/markdownlint .
+```
+
+## Building from a docker file
+
+The following will tag and upload a new release. Replace X.Y.Z as appropriate.
+
+```shell
+VERSION=X.Y.Z
+podman build -t markdownlint/markdownlint:latest \
+ -t markdownlint/markdownlint:${VERSION?} .
+podman push markdownlint/markdownlint:latest
+podman push markdownlint/markdownlint:${VERSION?}
+```
diff --git a/documents/markdown/mkdocs-material/alternatives.md b/documents/markdown/mkdocs-material/alternatives.md
new file mode 100644
index 0000000..dcfbda7
--- /dev/null
+++ b/documents/markdown/mkdocs-material/alternatives.md
@@ -0,0 +1,112 @@
+# Alternatives
+
+There are tons of static site generators and themes out there and choosing the
+right one for your tech stack is a tough decision. If you're unsure if Material
+for MkDocs is the right solution for you, this section should help you evaluate
+alternative solutions.
+
+## Docusaurus
+
+[Docusaurus] by Facebook is a very popular documentation generator and a good
+choice if you or your company are already using [React] to build your site.
+It will generate a [single page application] which is fundamentally different
+from the site Material for MkDocs generates for you.
+
+__Advantages__
+
+- Very powerful, customizable and extendable
+- Provides many components that aid in technical writing
+- Large and rich ecosystem, backed by Facebook
+
+__Challenges__
+
+- High learning curve, JavaScript knowledge mandatory
+- JavaScript ecosystem is very volatile, rather high maintenance
+- More time needed to get up and running
+
+While [Docusaurus] is one of the best choices when it comes to documentation
+sites that output a single page application, there are many more solutions,
+including [Docz], [Gatsby], [Vuepress] and [Docsify] that approach
+this problem similarly.
+
+ [Docusaurus]: https://docusaurus.io/
+ [React]: https://reactjs.org/
+ [single page application]: https://en.wikipedia.org/wiki/Single-page_application
+ [Docz]: https://www.docz.site/
+ [Gatsby]: https://www.gatsbyjs.com/
+ [VuePress]: https://vuepress.vuejs.org/
+ [Docsify]: https://docsify.js.org/
+
+## Jekyll
+
+[Jekyll] is probably one of the most mature and widespread static site
+generators and is written in [Ruby]. It is not specifically geared towards
+technical project documentation and has many themes to choose from, which
+can be challenging.
+
+__Advantages__
+
+- Battle-tested, rich ecosystem, many themes to choose from
+- Brings great capabilities for blogging (permalinks, tags, etc.)
+- Generates a SEO-friendly site, similar to Material for MkDocs
+
+__Challenges__
+
+- Not specifically geared towards technical project documentation
+- Limited Markdown capabilities, not as advanced as Python Markdown
+- More time needed to get up and running
+
+ [Jekyll]: https://jekyllrb.com/
+ [Ruby]: https://www.ruby-lang.org/de/
+
+## Sphinx
+
+[Sphinx] is an alternative static site generator specifically geared towards
+generating reference documentation, offering powerful capabilities that are
+lacking in MkDocs. It uses [reStructured text], a format similar to Markdown,
+which some users find harder to use.
+
+__Advantages__
+
+- Very powerful, customizable and extendable
+- Generates reference documentation from [Python docstrings]
+- Large and rich ecosystem, used by many Python projects
+
+__Challenges__
+
+- High learning curve, [reStructured text] syntax might be challenging
+- Search is less powerful than the one provided by MkDocs
+- More time needed to get up and running
+
+If you're considering using Sphinx because you need to generate reference
+documentation, you should give [mkdocstrings] a try – an actively maintained
+and popular framework building on top of MkDocs, implementing Sphinx-like
+functionality.
+
+ [Sphinx]: https://www.sphinx-doc.org/
+ [reStructured text]: https://en.wikipedia.org/wiki/ReStructuredText
+ [Python docstrings]: https://www.python.org/dev/peps/pep-0257/
+ [mkdocstrings]: https://github.com/mkdocstrings/mkdocstrings
+
+## GitBook
+
+[GitBook] offers a hosted documentation solution that generates a beautiful and
+functional site from Markdown files in your GitHub repository. However, it was
+once Open Source, but turned into a closed source solution some time ago.
+
+__Advantages__
+
+- Hosted solution, minimal technical knowledge required
+- Custom domains, authentication and other enterprise features
+- Great collaboration features for teams
+
+__Challenges__
+
+- Closed source, not free for proprietary projects
+- Limited Markdown capabilities, not as advanced as Python Markdown
+- Many Open Source projects moved away from GitBook
+
+Many users switched from [GitBook] to Material for MkDocs, as they want to keep
+control and ownership of their documentation, favoring an Open Source solution.
+
+ [GitBook]: https://www.gitbook.com/
diff --git a/documents/markdown/mkdocs-material/blog_posts_adding-a-badge-to-your-project.md b/documents/markdown/mkdocs-material/blog_posts_adding-a-badge-to-your-project.md
new file mode 100644
index 0000000..26fd7bd
--- /dev/null
+++ b/documents/markdown/mkdocs-material/blog_posts_adding-a-badge-to-your-project.md
@@ -0,0 +1,37 @@
+---
+title: Adding a badge to your project
+date: 2023-11-30
+authors: [squidfunk]
+slug: adding-a-badge-to-your-project
+description: >
+ Share the love – you can now add a badge to your README, showing that your
+ project is built with Material for MkDocs
+categories:
+ - General
+---
+
+# Adding a :simple-materialformkdocs: badge to your project
+
+__You enjoy working with Material for MkDocs? Share the love! You can now add
+a badge to your project's README, showing that your project is built with
+Material for MkDocs.__
+
+Material for MkDocs' logo was just added to [Simple Icons], which is used by
+[Shields.io] to include logos in badges. We generated a badge for you, which
+you can add to your project's README:
+
+[![Material for MkDocs][badge]](#usage)
+
+<!-- more -->
+
+## Usage
+
+Just copy the following snippet and paste it into your project's `README.md`:
+
+``` markdown
+[](https://squidfunk.github.io/mkdocs-material/)
+```
+
+ [Simple Icons]: https://simpleicons.org/
+ [Shields.io]: https://shields.io/
+ [badge]: https://img.shields.io/badge/Material_for_MkDocs-526CFE?style=for-the-badge&logo=MaterialForMkDocs&logoColor=white
diff --git a/documents/markdown/mkdocs-material/blog_posts_blog-support-just-landed.md b/documents/markdown/mkdocs-material/blog_posts_blog-support-just-landed.md
new file mode 100644
index 0000000..8d83ecf
--- /dev/null
+++ b/documents/markdown/mkdocs-material/blog_posts_blog-support-just-landed.md
@@ -0,0 +1,228 @@
+---
+date: 2022-09-12
+authors: [squidfunk]
+description: >
+ Our new blog is built with the brand new built-in blog plugin. You can build
+ a blog alongside your documentation or standalone
+categories:
+ - Blog
+links:
+ - setup/setting-up-a-blog.md
+ - plugins/blog.md
+---
+
+# Blog support just landed
+
+__Hey there! You're looking at our new blog, built with the brand new
+[built-in blog plugin]. With this plugin, you can easily build a blog alongside
+your documentation or standalone.__
+
+Proper support for blogging, as requested by many users over the past few years,
+was something that was desperately missing from Material for MkDocs' feature set.
+While everybody agreed that blogging support was a blind spot, it was not
+obvious whether MkDocs could be extended in a way to allow for blogging as we
+know it from [Jekyll] and friends. The [built-in blog plugin] proves that it is,
+after all, possible to build a blogging engine on top of MkDocs, in order to
+create a technical blog alongside your documentation, or as the main thing.
+
+<!-- more -->
+
+_This article explains how to build a standalone blog with Material for MkDocs.
+If you want to build a blog alongside your documentation, please refer to
+[the plugin's documentation][built-in blog plugin]._
+
+ [built-in blog plugin]: ../../plugins/blog.md
+ [Jekyll]: https://jekyllrb.com/
+
+## Quick start
+
+### Creating a standalone blog
+
+You can bootstrap a new project using the `mkdocs` executable:
+
+```
+mkdocs new .
+```
+
+This will create the following structure:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+│ └─ index.md
+└─ mkdocs.yml
+```
+
+#### Configuration
+
+In this article, we're going to build a standalone blog, which means that the
+blog lives at the root of your project. For this reason, open `mkdocs.yml`,
+and replace its contents with:
+
+``` yaml
+site_name: My Blog
+theme:
+ name: material
+ features:
+ - navigation.sections
+plugins:
+ - blog:
+ blog_dir: . # (1)!
+ - search
+ - tags
+nav:
+ - index.md
+```
+
+1. This is the important part – we're hosting the blog at the root of the
+ project, and not in a subdirectory. For more information, see the
+ [`blog_dir`][blog_dir] configuration option.
+
+ [blog_dir]: ../../plugins/blog.md#config.blog_dir
+
+#### Blog setup
+
+The blog index page lives in `docs/index.md`. This page was pre-filled by
+MkDocs with some content, so we're going to replace it with what we need to
+bootstrap the blog:
+
+``` markdown
+# Blog
+```
+
+That's it.
+
+### Writing your first post
+
+Now that we have set up the [built-in blog plugin], we can start writing our
+first post. All blog posts are written with the [exact same Markdown flavor] as
+already included with Material for MkDocs. First, create a folder called `posts`
+with a file called `hello-world.md`:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+│ ├─ posts/
+│ │ └─ hello-world.md # (1)!
+│ └─ index.md
+└─ mkdocs.yml
+```
+
+1. If you'd like to arrange posts differently, you're free to do so. The URLs
+ are built from the format specified in [`post_url_format`][post slugs] and
+ the titles and dates of posts, no matter how they are organized
+ inside the `posts` directory.
+
+Then, open up `hello-world.md`, and add the following lines:
+
+``` yaml
+---
+draft: true # (1)!
+date: 2022-01-31
+categories:
+ - Hello
+ - World
+---
+
+# Hello world!
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque nec
+maximus ex. Sed consequat, nulla quis malesuada dapibus, elit metus vehicula
+erat, ut egestas tellus eros at risus. In hac habitasse platea dictumst.
+Phasellus id lacus pulvinar erat consequat pretium. Morbi malesuada arcu mauris
+Nam vel justo sem. Nam placerat purus non varius luctus. Integer pretium leo in
+sem rhoncus, quis gravida orci mollis. Proin id aliquam est. Vivamus in nunc ac
+metus tristique pellentesque. Suspendisse viverra urna in accumsan aliquet.
+
+<!-- more -->
+
+Donec volutpat, elit ac volutpat laoreet, turpis dolor semper nibh, et dictum
+massa ex pulvinar elit. Curabitur commodo sit amet dolor sed mattis. Etiam
+tempor odio eu nisi gravida cursus. Maecenas ante enim, fermentum sit amet
+molestie nec, mollis ac libero. Vivamus sagittis suscipit eros ut luctus.
+
+Nunc vehicula sagittis condimentum. Cras facilisis bibendum lorem et feugiat.
+In auctor accumsan ligula, at consectetur erat commodo quis. Morbi ac nunc
+pharetra, pellentesque risus in, consectetur urna. Nulla id enim facilisis
+arcu tincidunt pulvinar. Vestibulum laoreet risus scelerisque porta congue.
+In velit purus, dictum quis neque nec, molestie viverra risus. Nam pellentesque
+tellus id elit ultricies, vel finibus erat cursus.
+```
+
+1. If you mark a post as a [draft], a red marker appears next to the post date
+ on index pages. When the site is built, drafts are not included in the
+ output. [This behavior can be changed], e.g. for rendering drafts when
+ building deploy previews.
+
+When you spin up the [live preview server], you should be greeted by your first
+post! You'll also realize, that [archive] and [category] indexes have been
+automatically generated for you:
+
+ ![Blog]
+
+However, this is just the start. The [built-in blog plugin] packs a lot of
+functionality needed in day-to-day blogging. Visit the documentation of the
+plugin to learn about the following topics:
+
+<div class="mdx-columns" markdown>
+
+- [Adding an excerpt]
+- [Adding authors]
+- [Adding categories]
+- [Adding tags]
+- [Adding related links]
+- [Linking from and to posts]
+- [Setting the reading time]
+- [Setting defaults]
+
+</div>
+
+Additionally, the [built-in blog plugin] has dozens of [configuration options]
+which allow for fine-tuning the output. You can configure post slugs, general
+behavior and much more.
+
+ [exact same Markdown flavor]: ../../reference/index.md
+ [post slugs]: ../../plugins/blog.md#config.post_url_format
+ [draft]: ../../plugins/blog.md#meta.draft
+ [This behavior can be changed]: ../../plugins/blog.md#config.draft
+ [live preview server]: ../../creating-your-site.md#previewing-as-you-write
+ [archive]: ../../plugins/blog.md#config.archive
+ [category]: ../../plugins/blog.md#config.categories
+ [Blog]: blog-support-just-landed/blog.png
+ [Blog post]: blog-support-just-landed/blog-post.png
+ [Adding an excerpt]: ../../setup/setting-up-a-blog.md#adding-an-excerpt
+ [Adding authors]: ../../setup/setting-up-a-blog.md#adding-authors
+ [Adding categories]: ../../setup/setting-up-a-blog.md#adding-categories
+ [Adding tags]: ../../setup/setting-up-a-blog.md#adding-tags
+ [Adding related links]: ../../setup/setting-up-a-blog.md#adding-related-links
+ [Linking from and to posts]: ../../setup/setting-up-a-blog.md#linking-from-and-to-posts
+ [Setting the reading time]: ../../setup/setting-up-a-blog.md#setting-the-reading-time
+ [Setting defaults]: ../../setup/setting-up-a-blog.md#setting-defaults
+ [configuration options]: ../../setup/setting-up-a-blog.md#configuration
+
+## What's next?
+
+Getting basic blogging support out the door was quite a challenge – the
+[built-in blog plugin] is probably the biggest release this year and already
+packs a lot of functionality. However, Material for MkDocs is used in many
+different contexts, which is why we'd expect to iterate, as always.
+
+Some ideas already proposed by users:
+
+- __Blog series__: Authors should be able to create so called blog series and
+ assign posts to a blog series using simple identifiers. For each post that is
+ part of a series, a list with links to all other posts should be included in
+ the post's content.
+
+- __Author indexes__: Besides [archive] and [category] indexes, authors should
+ be able to create per-author indexes, which list all posts linked to an
+ author. Additionally, a profile should be created for each author and linked
+ from posts.
+
+- __Social share buttons__: It should be easy to share blog posts via social
+ media or other ways. For this reason, it should be possible to automatically
+ include social sharing buttons with each post.
+
+What's still missing from the brand new [built-in blog plugin]? Feel free to
+share your ideas in the comments. Together, we can build one of the best modern
+engines for technical blogging!
diff --git a/documents/markdown/mkdocs-material/blog_posts_chinese-search-support.md b/documents/markdown/mkdocs-material/blog_posts_chinese-search-support.md
new file mode 100644
index 0000000..541da99
--- /dev/null
+++ b/documents/markdown/mkdocs-material/blog_posts_chinese-search-support.md
@@ -0,0 +1,82 @@
+---
+date: 2022-05-05
+authors: [squidfunk]
+title: Chinese search support
+description: >
+ Insiders adds Chinese language support for the built-in search plugin – a
+ feature that has been requested many times
+categories:
+ - Search
+links:
+ - blog/posts/search-better-faster-smaller.md
+ - plugins/search.md#segmentation
+---
+
+# Chinese search support – 中文搜索支持
+
+__Insiders adds experimental Chinese language support for the [built-in search
+plugin] – a feature that has been requested for a long time given the large
+number of Chinese users.__
+
+After the United States and Germany, the third-largest country of origin of
+Material for MkDocs users is China. For a long time, the [built-in search plugin]
+didn't allow for proper segmentation of Chinese characters, mainly due to
+missing support in [lunr-languages] which is used for search tokenization and
+stemming. The latest Insiders release adds long-awaited Chinese language support
+for the built-in search plugin, something that has been requested by many users.
+
+<!-- more -->
+
+_Material for MkDocs終於支持中文了！文本被正確分割並且更容易找到。_
+{ style="display: inline" }
+
+_This article explains how to set up Chinese language support for the built-in
+search plugin in a few minutes._
+{ style="display: inline" }
+
+ [built-in search plugin]: ../../plugins/search.md
+ [lunr-languages]: https://github.com/MihaiValentin/lunr-languages
+
+## Configuration
+
+Chinese language support for Material for MkDocs is provided by [jieba], an
+excellent Chinese text segmentation library. If [jieba] is installed, the
+built-in search plugin automatically detects Chinese characters and runs them
+through the segmenter. You can install [jieba] with:
+
+```
+pip install jieba
+```
+
+The next step is only required if you specified the [`separator`][separator]
+configuration in `mkdocs.yml`. Text is segmented with [zero-width whitespace]
+characters, so it renders exactly the same in the search modal. Adjust
+`mkdocs.yml` so that the [`separator`][separator] includes the `\u200b`
+character:
+
+``` yaml
+plugins:
+ - search:
+ separator: '[\s\u200b\-]'
+```
+
+That's all that is necessary.
+
+## Usage
+
+If you followed the instructions in the configuration guide, Chinese words will
+now be tokenized using [jieba]. Try searching for
+[:octicons-search-24: 支持][q=支持] to see how it integrates with the
+built-in search plugin.
+
+---
+
+Note that this is an experimental feature, and I, @squidfunk, am not
+proficient in Chinese (yet?). If you find a bug or think something can be
+improved, please [open an issue].
+
+ [jieba]: https://pypi.org/project/jieba/
+ [zero-width whitespace]: https://en.wikipedia.org/wiki/Zero-width_space
+ [separator]: ../../plugins/search.md#config.separator
+ [q=支持]: ?q=支持
+ [open an issue]: https://github.com/squidfunk/mkdocs-material/issues/new/choose
diff --git a/documents/markdown/mkdocs-material/blog_posts_excluding-content-from-search.md b/documents/markdown/mkdocs-material/blog_posts_excluding-content-from-search.md
new file mode 100644
index 0000000..b838008
--- /dev/null
+++ b/documents/markdown/mkdocs-material/blog_posts_excluding-content-from-search.md
@@ -0,0 +1,206 @@
+---
+date: 2021-09-26
+authors: [squidfunk]
+description: >
+ Three new simple ways to exclude dedicated parts of a document from the search
+ index, allowing for more fine-grained control
+categories:
+ - Search
+links:
+ - blog/posts/search-better-faster-smaller.md
+ - setup/setting-up-site-search.md#search-exclusion
+---
+
+# Excluding content from search
+
+__The latest Insiders release brings three new simple ways to exclude
+dedicated parts of a document from the search index, allowing for more
+fine-grained control.__
+
+Two weeks ago, Material for MkDocs Insiders shipped a [brand new search
+plugin], yielding [massive improvements in usability], but also in [speed
+and size] of the search index. Interestingly, as discussed in the previous
+blog article, we only scratched the surface of what's now possible. This
+release brings some useful features that enhance the writing experience,
+allowing for more fine-grained control of what pages, sections and blocks of a
+Markdown file should be indexed by the built-in search functionality.
+
+<!-- more -->
+
+_The following section discusses existing solutions for excluding pages and
+sections from the search index. If you immediately want to learn what's new,
+skip to the [section just after that][what's new]._
+
+ [brand new search plugin]: search-better-faster-smaller.md
+ [massive improvements in usability]: search-better-faster-smaller.md#whats-new
+ [speed and size]: search-better-faster-smaller.md#benchmarks
+ [what's new]: #whats-new
+
+## Prior art
+
+MkDocs has a rich and thriving ecosystem of [plugins], and it comes as no
+surprise that there's already a fantastic plugin by @chrieke to exclude specific
+sections of a Markdown file – the [mkdocs-exclude-search] plugin. It can be
+installed with:
+
+```
+pip install mkdocs-exclude-search
+```
+
+__How it works__: the plugin post-processes the `search_index.json` file that
+is generated by the built-in search plugin, giving the author the ability to
+exclude certain pages and sections by adding a few lines of configuration to
+`mkdocs.yml`. An example:
+
+``` yaml
+plugins:
+ - search
+ - exclude-search:
+ exclude:
+ - page.md
+ - page.md#section
+ - directory/*
+ - /*/page.md
+```
+
+It's easy to see that the plugin follows a configuration-centric approach, which
+adds support for advanced filtering techniques like infix- and suffix-filtering
+using wildcards. While this is a very powerful idea, it comes with some
+downsides:
+
+1. __Exclusion patterns and content are not co-located__: exclusion patterns
+ need to be defined in `mkdocs.yml`, and not as part of the respective
+ document or section to be excluded. This might result in stale exclusion
+ patterns, leading to unintended behavior:
+
+ - When a headline is changed, its slug (permalink) also changes, which might
+ suddenly match (or unmatch) a pattern, e.g., when an author fixes a typo
+ in a headline.
+
+ - As exclusion patterns support the use of wildcards, different authors
+ might overwrite each other's patterns without any immediate feedback since
+ the plugin does only report the number of excluded documents – not _what_
+ has been excluded.[^1]
+
+ [^1]:
+ When the log level is set to `DEBUG`, the plugin will report exactly which
+ pages and sections have been excluded from the search index, but MkDocs will
+ now flood the terminal with debug output from its core and other plugins.
+
+2. __Exclusion control might be too coarse__: The [mkdocs-exclude-search]
+ plugin only allows for the exclusion of pages and sections. It's not
+ possible to exclude parts of a section, e.g., content that is irrelevant
+ to search but must be included as part of the documentation.
+
+ [plugins]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins
+ [mkdocs-exclude-search]: https://github.com/chrieke/mkdocs-exclude-search
+
+## What's new?
+
+The latest Insiders release brings fine-grained control for [__excluding pages,
+sections, and blocks__][search exclusion] from the search index, implemented
+through front matter, as well as the [Attribute Lists]. Note that it doesn't
+replace the [mkdocs-exclude-search] plugin but __complements__ it.
+
+ [search exclusion]: ../../setup/setting-up-site-search.md#search-exclusion
+ [Attribute Lists]: ../../setup/extensions/python-markdown.md#attribute-lists
+
+### Excluding pages
+
+An entire page can be excluded from the search index by adding a simple
+directive to the front matter of the respective Markdown file. The good thing
+is that the author now only has to check the top of the document to learn
+whether it is excluded or not:
+
+``` yaml
+---
+search:
+ exclude: true
+---
+
+# Page title
+...
+```
+
+### Excluding sections
+
+If a section should be excluded, the author can use the [Attribute Lists]
+extension to add a __pragma__ called `data-search-exclude` at the end of a
+heading. The pragma is not included in the final HTML, as search pragmas are
+filtered by the search plugin before the page is rendered:
+
+=== ":octicons-file-code-16: `docs/page.md`"
+
+ ``` markdown
+ # Page title
+
+ ## Section 1
+
+ The content of this section is included
+
+ ## Section 2 { data-search-exclude }
+
+ The content of this section is excluded
+ ```
+
+=== ":octicons-codescan-16: `search_index.json`"
+
+ ``` json
+ {
+ ...
+ "docs": [
+ {
+ "location":"page/",
+ "text":"",
+ "title":"Document title"
+ },
+ {
+ "location":"page/#section-1",
+ "text":"<p>The content of this section is included</p>",
+ "title":"Section 1"
+ }
+ ]
+ }
+ ```
+
+### Excluding blocks
+
+If even more fine-grained control is desired, the __pragma__ can be added to
+any [block-level element] or [inline-level element] that is officially
+supported by the [Attribute Lists] extension:
+
+=== ":octicons-file-code-16: `docs/page.md`"
+
+ ``` markdown
+ # Page title
+
+ The content of this block is included
+
+ The content of this block is excluded
+ { data-search-exclude }
+ ```
+
+=== ":octicons-codescan-16: `search_index.json`"
+
+ ``` json
+ {
+ ...
+ "docs": [
+ {
+ "location":"page/",
+ "text":"<p>The content of this block is included</p>",
+ "title":"Document title"
+ },
+ ]
+ }
+ ```
+
+ [block-level element]: https://python-markdown.github.io/extensions/attr_list/#block-level
+ [inline-level element]: https://python-markdown.github.io/extensions/attr_list/#inline
+
+## Conclusion
+
+The latest release brings three simple ways to control more precisely what goes
+into the search index and what doesn't. It complements the already very powerful
+[mkdocs-exclude-search] plugin, allowing for new methods of shaping the
+structure, size and content of the search index.
diff --git a/documents/markdown/mkdocs-material/blog_posts_git-sparse-checkout.md b/documents/markdown/mkdocs-material/blog_posts_git-sparse-checkout.md
new file mode 100644
index 0000000..e16b2a6
--- /dev/null
+++ b/documents/markdown/mkdocs-material/blog_posts_git-sparse-checkout.md
@@ -0,0 +1,100 @@
+---
+date: 2023-09-22
+authors: [squidfunk]
+categories:
+ - Build
+ - Performance
+links:
+ - publishing-your-site.md#with-github-actions
+ - creating-your-site.md#building-your-site
+---
+
+# Using `git sparse-checkout` for faster documentation builds
+
+__Leveraging `git sparse-checkout` in GitHub Actions enabled us to speed up
+documentation builds in our repository, cutting checkout times from 20 to 30
+seconds to just 2 seconds.__
+
+Developing an efficient approach to build documentation in CI workflows is
+essential, especially when working in large repositories with thousands of
+commits, like ours. Of course, we want to build documentation quickly and
+efficiently, ensuring fast and productive workflows. When using both the
+wonderful [`git-committers`][git-committers] and [`git-revision-date-localized`]
+[git-revision-date-localized] plugins to display [document contributors] and
+[dates] at the bottom of each page, we are required to set `fetch-depth: 0`,
+which resulted in checkout times of 20 to 30 seconds on our repository. By
+leveraging [`git sparse-checkout`][git sparse-checkout] within [GitHub Actions],
+check out time was brought down to 2 seconds.
+
+ [git sparse-checkout]: https://git-scm.com/docs/git-sparse-checkout
+ [GitHub Actions]: ../../publishing-your-site.md#with-github-actions
+ [git-revision-date-localized]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
+ [git-committers]: https://github.com/ojacques/mkdocs-git-committers-plugin-2
+ [document contributors]: ../../setup/adding-a-git-repository.md#document-contributors
+ [dates]: ../../setup/adding-a-git-repository.md#document-dates
+
+<!-- more -->
+
+## A Primer
+
+[`git sparse-checkout`][git sparse-checkout] allows you to check out only a
+subset of the files in a repository, making it incredibly useful for large
+repositories where a full checkout takes long and includes many files that are
+not relevant when building documentation.
+
+## GitHub Actions
+
+To enable [`git sparse-checkout`][git sparse-checkout] within [GitHub Actions]
+and ensure that you are only building the documentation that you need, add the
+following lines to your workflow file:
+
+``` yaml
+- uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+ sparse-checkout: |
+ docs
+ includes
+```
+
+[`git sparse-checkout`][git sparse-checkout] always checks out all files
+residing in the repository’s root. This means that regardless of the specified
+paths or directories for sparse checkout, the files located in the root of the
+repository will always be included in the checkout process.
+
+Thus, you only need to specify the directories that are necessary for building
+documentation. In our case, we only need the `docs` and `includes` folders,
+but if you need additional directories, you can just add them to the end of the
+list. A complete example workflow for [GitHub Actions]:
+
+``` yaml hl_lines="13-18"
+name: documentation
+on:
+ push:
+ branches:
+ - master
+ - main
+permissions:
+ contents: write
+jobs:
+ deploy:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+ sparse-checkout: |
+ docs
+ includes
+ - uses: actions/setup-python@v4
+ with:
+ python-version: 3.x
+ - run: pip install mkdocs-material
+ - run: mkdocs gh-deploy --force
+```
+
+## Conclusion
+
+That's all there is! We're super happy with the results and hope that this will
+help you to speed up your documentation builds in [GitHub Actions] as well. As
+always, feel free to share your thoughts and experiences in the comments below.
diff --git a/documents/markdown/mkdocs-material/blog_posts_goodbye-github-discussions.md b/documents/markdown/mkdocs-material/blog_posts_goodbye-github-discussions.md
new file mode 100644
index 0000000..6747caf
--- /dev/null
+++ b/documents/markdown/mkdocs-material/blog_posts_goodbye-github-discussions.md
@@ -0,0 +1,164 @@
+---
+date: 2025-11-18
+authors:
+ - squidfunk
+ - alexvoss
+ - katharinalisalin
+ - pawamoy
+categories:
+ - General
+icon: material/comment-off-outline
+description: >
+ As Material for MkDocs entered maintenance mode and we're focusing our efforts on Zensical, our discussion board is now read-only
+---
+
+# Goodbye, GitHub Discussions
+
+__With the launch of [Zensical], we're evolving how we work together with the community to ensure long-term sustainability and professional support, fostering meaningful collaboration.__
+
+The launch of Zensical [two weeks ago] marked a significant milestone, as it establishes a new foundation for our mission to build scalable Open Source systems for technical writing. Additionally, we're adopting a structured, transparent, and community-driven approach to guide the evolution of our projects – prioritizing what to build, and shaping Zensical's future together.
+
+[Our new approach] distills a decade of experience maintaining Material for MkDocs, allowing us to professionalize and scale our efforts from a small team to a fully organized operation, while keeping the software free and open to everyone.
+
+As Material for MkDocs has entered [maintenance mode], __our discussion board is now read-only__.
+
+In this article, we reflect on the challenges we've navigated, the lessons we've learned, as these experiences have shaped our approach to community management and support that we're building with Zensical.
+
+_You can subscribe to [our newsletter] to stay in the loop_.
+
+<!-- more -->
+
+ [Our new approach]: https://zensical.org/docs/community/how-we-work/
+ [maintenance mode]: https://github.com/squidfunk/mkdocs-material/issues/8523
+ [Zensical]: https://zensical.org
+ [two weeks ago]: zensical.md
+ [our newsletter]: https://zensical.org/about/newsletter/
+
+---
+
+__This is the fourth and final article in a four-part series:__
+
+1. [Transforming Material for MkDocs]
+2. [Zensical – A modern static site generator built by the creators of Material for MkDocs]
+3. [Material for MkDocs Insiders – Now free for everyone]
+4. [Goodbye, GitHub Discussions]
+
+ [Transforming Material for MkDocs]: transforming-material-for-mkdocs.md
+ [Zensical – A modern static site generator built by the creators of Material for MkDocs]: zensical.md
+ [Material for MkDocs Insiders – Now free for everyone]: insiders-now-free-for-everyone.md
+ [Goodbye, GitHub Discussions]: goodbye-github-discussions.md
+
+## GitHub Issues
+
+Engagement with an Open Source project can take many forms – reporting bugs, submitting feature requests, seeking help, sharing ideas, participating in discussions, and contributing code. Each type of interaction requires a distinct approach to management.
+
+Historically, we relied on our GitHub issue tracker to handle bug reports and feature requests. However, a significant portion of user inquiries – questions, support requests, and guidance – also found their way into the issue tracker. Over time, this blurred the lines between development work and support, making it increasingly difficult to maintain focus on core development tasks.
+
+This is not unique to our project; many Open Source maintainers face similar challenges due to diverse skill levels and varying expectations within their communities. Clearly, Open Source projects needed a better solution to separate user support from development work.
+
+## GitHub Discussions
+
+In 2020, GitHub launched [GitHub Discussions] as a dedicated space for community interaction – a new channel to move support requests away from issue trackers. We immediately enabled discussions for Material for MkDocs, and redirected users to post questions and seek help.[^1]
+
+ [^1]:
+ Before adopting GitHub Discussions, we maintained a Gitter channel, but ultimately chose to [consolidate our support efforts into a single platform]. While GitHub Discussions appeared promising, its mechanics proved ineffective.
+
+ [consolidate our support efforts into a single platform]: sunsetting-gitter.md
+
+Then, as our community continued to expand – and as the vast majority of participants were seeking help rather than offering it – we launched the [Community Experts Program], giving those community members free access to Insiders for consistently providing high-quality assistance.
+
+### Structural challenges
+
+Despite these measures, we faced serveral structural challenges:
+
+1. __Material for MkDocs? MkDocs? Same, same__ – All too often, we were perceived as the entry point for the entire ecosystem. As a result, many issues and discussions that actually belonged upstream – such as problems with Python Markdown, MkDocs plugins, or MkDocs itself – landed on our desk. This created additional triage work for redirecting issues.
+
+2. __Yet another inbox__ – Although the discussion board was separate from the issue tracker, we ended up handling the majority of questions, effectively turning the discussion board into yet another inbox for us. Because the board is tied to the repository, unanswered discussions could be perceived as the project being unmaintained, putting pressure on us to respond.
+
+3. __A notification for everything__ – GitHub's notification system contributed to this problem. Any interaction within an issue or a discussion subscribes you to the entire thread, resulting in notifications for every comment, including: __+1__ – taking 2 seconds to type and submit, delivering a notification to the inbox of all other participants.
+
+4. __GitHub Discussions is a chat__ – Many users began treating GitHub Discussions more like a chat platform than a structured knowledge base. This created notification fatigue, reinforcing a pattern in which the community implicitly relied on maintainers to handle support requests. Everybody got a message, so the assumption was that things were taken care of – right?
+
+5. __Bug reports on our discussion board__ – From time to time, our [contribution guidelines] were ignored, leading to spurious bug reports on our discussion board instead of our issue tracker – "search doesn't work" is not an actionable bug report. However, when users followed our [bug reporting guidelines], we were able to fix most bugs within 24-48 hours.
+
+ [Community Experts Program]: https://github.com/squidfunk/mkdocs-material/discussions/6363
+ [GitHub Discussions]: https://github.com/features/discussions
+ [contribution guidelines]: https://squidfunk.github.io/mkdocs-material/contributing/
+ [bug reporting guidelines]: https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/
+
+### Addressing these challenges
+
+We actively addressed these challenges in various ways over time: by introducing carefully crafted issue templates on our issue tracker and creating detailed step-by-step guides on how to report bugs, request changes, and create pull requests effectively.
+
+Despite these efforts, success was limited. The underlying problem was that GitHub Discussions, while a step in the right direction, was not designed to handle the scale and diversity of our community. It lacked the structure and features necessary to support a large, active user base seeking help, making it impossible to fully resolve the challenges we faced. We believe that this is not unique to our project, but rather a systemic issue with GitHub Discussions, and that many Open Source maintainers encounter similar difficulties.
+
+The [Community Experts Program] helped reduce some of the support burden, but it could not fully address the structural limitations of using GitHub Discussions for user support.
+
+## Discussions now read-only
+
+With Material for MkDocs in [maintenance mode], __our GitHub Discussion board is now read-only__ – it remains accessible but will no longer accept new discussions or comments. All existing answers stay in place, ensuring that users can still find solutions to previously solved problems.
+
+!!! warning "Material for MkDocs is now in maintenance mode"
+
+ We want to be transparent about the risks of staying on Material for MkDocs. With [MkDocs unmaintained] and facing fundamental supply chain concerns, we cannot guarantee Material for MkDocs will continue working reliably in the future. We're aware that transitioning takes time, which is why we commit to support it at least for the next 12 months, fixing critical bugs and security vulnerabilities as needed, but the path forward is with Zensical.
+
+ If documentation plays a critical role in your organization, and you're worried how this might affect your business, consider joining [Zensical Spark](https://zensical.org/spark/), or feel free to schedule a call by reaching out at hello@zensical.org.
+
+ [MkDocs unmaintained]: https://github.com/squidfunk/mkdocs-material/discussions/8461
+
+### What this means for you
+
+For issues and questions related to the broader MkDocs ecosystem, we encourage users to ask for assistance on the issue trackers and discussion boards of the respective upstream projects:
+
+__MkDocs & Python Markdown__
+
+- [MkDocs] – [Issues][MkDocs issues], [Discussions][MkDocs discussions]
+- [Python Markdown] – [Issues][Python Markdown issues]
+- [Pymdown Extensions] – [Issues][Pymdown Extensions issues], [Discussions][Pymdown Extensions discussions]
+
+__Popular MkDocs plugins__
+
+- [Mike] – [Issues][Mike issues], [Discussions][Mike discussions]
+- [Macros] – [Issues][Macros issues], [Discussions][Macros discussions]
+- [Git Revision Date Localized] – [Issues][Git Revision Date Localized issues]
+- [Awesome Nav] – [Issues][Awesome Nav issues]
+- [Static i18n] – [Issues][Static i18n issues]
+- [MkDocs Literate Nav] – [Issues][MkDocs Literate Nav issues]
+
+_For all other MkDocs plugins and Markdown extensions, please consult the [MkDocs catalog], and reach out to the maintainers of the respective projects._
+
+_Join our [Discord] to become part of Zensical's growing community!_
+
+## Looking ahead
+
+This article concludes our four-part series reflecting on the journey of maintaining Material for MkDocs and how it has paved the way for Zensical – our next chapter.
+
+[Our new approach] to community management and support is built directly on the lessons we've learned over the years. We are excited to begin this next chapter together with you and look forward to cultivating a vibrant, engaged, and sustainable community together.
+
+_You can subscribe to [our newsletter] to stay in the loop_.
+
+ [MkDocs]: https://github.com/mkdocs/mkdocs
+ [MkDocs issues]: https://github.com/mkdocs/mkdocs/issues
+ [MkDocs discussions]: https://github.com/mkdocs/mkdocs/discussions
+ [Pymdown Extensions]: https://github.com/facelessuser/pymdown-extensions
+ [Pymdown Extensions discussions]: https://github.com/facelessuser/pymdown-extensions/discussions
+ [Pymdown Extensions issues]: https://github.com/facelessuser/pymdown-extensions/issues
+ [Python Markdown]: https://github.com/Python-Markdown/markdown
+ [Python Markdown issues]: https://github.com/Python-Markdown/markdown/issues
+ [Mike]: https://github.com/jimporter/mike
+ [Mike issues]: https://github.com/jimporter/mike/issues
+ [Mike discussions]: https://github.com/jimporter/mike/discussions
+ [Macros]: https://github.com/fralau/mkdocs-macros-plugin
+ [Macros issues]: https://github.com/fralau/mkdocs-macros-plugin/issues
+ [Macros discussions]: https://github.com/fralau/mkdocs-macros-plugin/discussions
+ [Git Revision Date Localized]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
+ [Git Revision Date Localized issues]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/issues
+ [Awesome Nav]: https://github.com/lukasgeiter/mkdocs-awesome-nav
+ [Awesome Nav issues]: https://github.com/lukasgeiter/mkdocs-awesome-nav/issues
+ [Static i18n]: https://github.com/ultrabug/mkdocs-static-i18n
+ [Static i18n issues]: https://github.com/ultrabug/mkdocs-static-i18n/issues
+ [Static i18n discussions]: https://github.com/ultrabug/mkdocs-static-i18n/discussions
+ [MkDocs Literate Nav]: https://github.com/oprypin/mkdocs-literate-nav
+ [MkDocs Literate Nav issues]: https://github.com/oprypin/mkdocs-literate-nav/issues
+ [MkDocs catalog]: https://github.com/mkdocs/catalog
+ [Discord]: https://discord.gg/hqXRNq9CjT
diff --git a/documents/markdown/mkdocs-material/blog_posts_insiders-now-free-for-everyone.md b/documents/markdown/mkdocs-material/blog_posts_insiders-now-free-for-everyone.md
new file mode 100644
index 0000000..c586bf9
--- /dev/null
+++ b/documents/markdown/mkdocs-material/blog_posts_insiders-now-free-for-everyone.md
@@ -0,0 +1,205 @@
+---
+date: 2025-11-11
+authors:
+ - squidfunk
+ - alexvoss
+ - katharinalisalin
+ - pawamoy
+categories:
+ - General
+icon: material/lock-open
+description: >
+ We just released 9.7.0 – the final version of Material for MkDocs, which includes all features that were previously exclusive to sponsors
+title: Insiders – Now free for everyone
+slug: insiders-now-free-for-everyone
+---
+
+# Material for MkDocs Insiders – Now free for everyone
+
+__[9.7.0], the final version of Material for MkDocs, includes all features that were previously exclusive to sponsors, making Material for MkDocs Insiders available to everyone!__
+
+As we're shifting our efforts to [Zensical], Material for MkDocs is entering [maintenance mode]. This means that while we'll continue to fix critical bugs and security issues for 12 month at least, no new features will be added to Material for MkDocs.
+
+We're also discontinuing our sponsorware model, saying [goodbye to GitHub Sponsors]. If you were a sponsor of our work, you already received an email mentioning that your sponsorship was cancelled. As one of the numerous individuals and organizations sponsoring Material for MkDocs over the past years – thank you! Your continued support has been invaluable.
+
+Now, we want everyone to benefit from all features we have developed for Material for MkDocs, which is why we're making all Insiders features available to everyone!
+
+This is the logical next step in our journey as we focus on Zensical – our next-generation static site generator built from the ground up to overcome MkDocs' technical limitations. Zensical is fully [Open Source, licensed under MIT], maintains [compatibility with Material for MkDocs], and can build your existing projects with minimal changes.
+
+In the coming months, we'll close the [feature parity] gap, bringing the expressiveness of Material for MkDocs to Zensical.
+
+_You can subscribe to [our newsletter] to stay in the loop_.
+
+<!-- more -->
+
+ [9.7.0]: ../../changelog/index.md#9.7.0
+ [Zensical]: https://zensical.org
+ [maintenance mode]: https://github.com/squidfunk/mkdocs-material/issues/8523
+ [goodbye to GitHub Sponsors]: zensical.md#goodbye-github-sponsors
+ [compatibility with Material for MkDocs]: zensical.md#maximum-compatibility
+ [Open Source, licensed under MIT]: https://zensical.org/about/license/
+ [feature parity]: https://zensical.org/compatibility/features/
+ [our newsletter]: https://zensical.org/about/newsletter/
+
+---
+
+__This is the third article in a four-part series:__
+
+1. [Transforming Material for MkDocs]
+2. [Zensical – A modern static site generator built by the creators of Material for MkDocs]
+3. [Material for MkDocs Insiders – Now free for everyone]
+4. [Goodbye, GitHub Discussions]
+
+ [Transforming Material for MkDocs]: transforming-material-for-mkdocs.md
+ [Zensical – A modern static site generator built by the creators of Material for MkDocs]: zensical.md
+ [Material for MkDocs Insiders – Now free for everyone]: insiders-now-free-for-everyone.md
+ [Goodbye, GitHub Discussions]: goodbye-github-discussions.md
+
+## Available features
+
+Our sponsors have enjoyed exclusive access to the following premium features
+for quite some time. With the release of [9.7.0], all these features are now available to everyone:
+
+<div class="mdx-columns" markdown>
+
+- [x] [Blog plugin: pinned posts]
+- [x] [Instant previews]
+- [x] [Footnote tooltips]
+- [x] [Tags plugin: advanced settings]
+- [x] [Tags plugin: nested tags]
+- [x] [Tags plugin: shadow tags]
+- [x] [Stay on page when switching languages]
+- [x] [Blog plugin: author profiles]
+- [x] [Blog plugin: advanced settings]
+- [x] [Projects plugin]
+- [x] [Instant prefetching]
+- [x] [Social plugin: custom layouts]
+- [x] [Social plugin: background images]
+- [x] [Code range selection]
+- [x] [Code annotations: custom selectors]
+- [x] [Privacy plugin: advanced settings]
+- [x] [Optimize plugin]
+- [x] [Navigation path] (Breadcrumbs)
+- [x] [Typeset plugin]
+- [x] [Privacy plugin: external links]
+
+</div>
+
+ [Optimize plugin]: ../../plugins/optimize.md
+ [Navigation path]: ../../setup/setting-up-navigation.md#navigation-path
+ [Blog plugin: advanced settings]: ../../setup/setting-up-a-blog.md#advanced-settings
+ [Blog plugin: author profiles]: ../../setup/setting-up-a-blog.md#adding-author-profiles
+ [Blog plugin: pinned posts]: ../../setup/setting-up-a-blog.md#pinning-a-post
+ [Instant prefetching]: ../../setup/setting-up-navigation.md#instant-prefetching
+ [Typeset plugin]: ../../plugins/typeset.md
+ [Footnote tooltips]: ../../reference/footnotes.md#footnote-tooltips
+ [Privacy plugin: external links]: ../../plugins/privacy.md#external-links
+ [Privacy plugin: advanced settings]: ../../setup/ensuring-data-privacy.md#advanced-settings
+ [Instant previews]: ../../setup/setting-up-navigation.md#instant-previews
+ [Social plugin: custom layouts]: ../../setup/setting-up-social-cards.md#customization
+ [Social plugin: background images]: ../../plugins/social.md#option.background_image
+ [Code range selection]: ../../reference/code-blocks.md#code-selection-button
+ [Code annotations: custom selectors]: ../../reference/code-blocks.md#custom-selectors
+ [Stay on page when switching languages]: ../../setup/changing-the-language.md#stay-on-page
+ [Projects plugin]: ../../plugins/projects.md
+ [Tags plugin: nested tags]: ../../setup/setting-up-tags.md#nested-tags
+ [Tags plugin: shadow tags]: ../../setup/setting-up-tags.md#shadow-tags
+ [Tags plugin: advanced settings]: ../../setup/setting-up-tags.md#advanced-settings
+
+!!! tip "[mkdocstrings Insiders is now free] as well"
+
+ With [Timothée joining the Zensical team], he announced that all features previously reserved to his sponsors as part of [mkdocstrings] Insiders are now free for everyone as well!
+
+ [mkdocstrings Insiders is now free]: https://pawamoy.github.io/posts/sunsetting-the-sponsorware-strategy/
+ [Timothée joining the Zensical team]: zensical.md#were-growing-our-team
+ [mkdocstrings]: https://mkdocstrings.github.io/
+
+## How to upgrade
+
+You can upgrade with the following command:
+
+```
+pip install --upgrade --force-reinstall mkdocs-material
+```
+
+## Switching from Insiders
+
+If you've been a user of Insiders, we recommend to switch to the community edition as soon as possible, as it includes all Insiders features. This will make it much easier to handle third-party contributions, since no personal access tokens are necessary.
+
+__From now on, bug fixes that we make to Material for MkDocs will only be released to the community edition. Security vulnerabilities will be fixed in both editions.__
+
+Thus, please adjust your `requirements.txt` and GitHub Actions workflows:
+
+```diff
+- pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders. git
++ pip install mkdocs-material
+
+```
+
+The Insiders repository itself will remain available for the next 6 months. When you build your project with Insiders, it will now show an informational message pointing to this blog post.
+
+- __On February 1, 2026, this message will be turned into a warning__.
+- __On May 1, 2026, the Insiders repository will be deleted__.
+
+## Sunsetting preparation
+
+Entering [maintenance mode], we're preparing Material for MkDocs for sunsetting.
+
+!!! warning "Material for MkDocs is now in maintenance mode"
+
+ We want to be transparent about the risks of staying on Material for MkDocs. With [MkDocs unmaintained] and facing fundamental supply chain concerns, we cannot guarantee Material for MkDocs will continue working reliably in the future. We're aware that transitioning takes time, which is why we commit to support it at least for the next 12 months, fixing critical bugs and security vulnerabilities as needed, but the path forward is with Zensical.
+
+ If documentation plays a critical role in your organization, and you're worried how this might affect your business, consider joining [Zensical Spark](https://zensical.org/spark/), or feel free to schedule a call by reaching out at hello@zensical.org.
+
+ [MkDocs unmaintained]: https://github.com/squidfunk/mkdocs-material/discussions/8461
+
+### Deprecations
+
+While we release all features to the general public, at the same time, we're deprecating the [Projects plugin] and the [Typeset plugin] due to maintainability issues. This means that these plugins will not receive any further updates, including no more bug fixes.
+
+The reason for this decision is that both plugins rely on too many workarounds to make them work with MkDocs, and subsequently have been key motivators to create [Zensical]. If you rely on these plugins, and they work for your use case, you can of course continue to use them.
+
+__With Zensical, we'll be shipping proper [sub-project support], including [internationalization] and [versioning], designing these features together with our professional users in [Zensical Spark].__
+
+ [Zensical Spark]: https://zensical.org/spark/
+ [sub-project support]: https://zensical.org/about/roadmap/#subprojects
+ [internationalization]: https://zensical.org/about/roadmap/#internationalization
+ [versioning]: https://zensical.org/about/roadmap/#versioning
+
+### Version ranges
+
+Material for MkDocs has used semver version ranges for dependencies to ensure compatibility. With the advent of [9.7.0], we're switching from semver to minimal version ranges. This provides more flexibility in dependency resolution, specifically to allow users to use newer versions of dependencies that include important bug fixes or security patches.
+
+### Security
+
+We will not transfer ownership of the Material for MkDocs repository to another individual or organization. The repository and PyPI package will remain under the ownership of @squidfunk, which preserves the trusted supply chain our users depend on.
+
+Thus, if you wish to take on maintenance of Material for MkDocs, please create a fork.
+
+## Looking ahead
+
+### Achieving sustainability
+
+Where Material for MkDocs relied on sponsorware, Zensical takes a new approach,
+to ensure it evolves to meet the needs of organizations building complex, enterprise-scale documentation.
+
+[Zensical Spark] is a collaborative space where professional users have a direct voice in shaping Zensical's future. Through a [structured design process] and together with our Zensical Spark members, we identify opportunities, validate proposals, and define priorities – turning their real-world documentation challenges into features that benefit the entire community.
+
+Reach out at hello@zensical.org to schedule a call to learn more about Zensical Spark, discuss your organization's needs, and how it helps us to make Zensical sustainable.
+
+ [Zensical Spark]: https://zensical.org/spark/
+ [structured design process]: https://zensical.org/docs/community/how-we-work/
+
+### Our commitment to you
+
+If you're currently using Material for MkDocs, there's no need to rush. We're committed to keeping it secure and functional for the next 12 months while we focus our efforts on [Zensical].
+
+The [9.7.0] release marks a significant shift – every Insiders feature is now available to everyone, with no sponsorship required. As we build [Zensical], each of these features will be rearchitected and improved. Zensical is entirely free and Open Source, ensuring the entire community benefits from our work without barriers.
+
+When you're ready to explore what's next, [Zensical is compatible with Material for MkDocs] and designed to be a natural evolution of the ideas and principles you already know.
+
+_If you loved Material for MkDocs and are excited about Zensical, we'll be providing new methods to support our work in the coming months, with the possibility of getting exclusive goodies._
+
+_Subscribe to [our newsletter] to stay in the loop._
+
+ [Zensical is compatible with Material for MkDocs]: zensical.md#maximum-compatibility
diff --git a/documents/markdown/mkdocs-material/blog_posts_mkdocs-2.0.md b/documents/markdown/mkdocs-material/blog_posts_mkdocs-2.0.md
new file mode 100644
index 0000000..946d87c
--- /dev/null
+++ b/documents/markdown/mkdocs-material/blog_posts_mkdocs-2.0.md
@@ -0,0 +1,167 @@
+---
+date:
+ created: 2026-02-18
+ updated: 2026-03-22
+authors:
+ - squidfunk
+ - alexvoss
+ - katharinalisalin
+categories:
+ - General
+description: >
+ MkDocs 2.0 is a ground-up rewrite of the documentation tool tens of thousands of projects rely on, introducing potentially significant breaking changes
+slug: mkdocs-2.0
+---
+
+
+# What MkDocs 2.0 means for your documentation projects
+
+Last update: March 27, 2026 – see [update log].
+
+---
+
+__Three weeks ago, MkDocs 2.0 was announced – a ground-up rewrite of the documentation tool tens of thousands of projects rely on, introducing potentially significant breaking changes.__
+
+Material for MkDocs depends on MkDocs as its underlying framework and central dependency. We maintain Material for MkDocs, but we have no control over MkDocs itself.
+
+We've taken the time to thoroughly evaluate and test the [MkDocs 2.0 pre-release] and want to share our findings, including what it might mean for your documentation projects, and where [Zensical], our new static site generator that is _compatible with MkDocs 1.x_, fits into the picture.
+
+__If you've missed it__: [MkDocs 1.x is unmaintained], with issues and PRs piling up and no releases in the past 18 months, and seemingly no plans to fix long-standing issues like [live-reload problems]. More importantly, it's unclear whether security issues will be addressed, and whether the project will receive any updates at all in the future.
+
+_Please note that MkDocs 2.0 is still in pre-release, and the information in this article is based on the current state of the project. We keep it updated as we learn more._
+
+ [MkDocs 2.0 pre-release]: https://github.com/encode/mkdocs
+ [Zensical]: zensical.md
+ [update log]: #updates
+
+<!-- more -->
+
+## What's changing in MkDocs 2.0
+
+Based on the [official announcement], the published [roadmap], and several prior comments and statements from the project's maintainer, MkDocs 2.0 is intended as a ground-up rewrite of the project to reduce complexity – and it comes with some important trade-offs:
+
+- __MkDocs 2.0 is incompatible with Material for MkDocs__ – If your documentation is built with Material for MkDocs, it will cease to work with MkDocs 2.0. Material for MkDocs makes extensive use of the templating and plugin systems of MkDocs 1.x, and the changes that MkDocs 2.0 introduces are not backward-compatible.
+
+- __MkDocs 2.0 won't have a plugin system__ – MkDocs 2.0 is being rewritten with a focus on theming, deliberately [removing plugin support to simplify the codebase]. We believe [the plugin ecosystem] is one of the cornerstones of MkDocs' success and widespread adoption, and its removal will affect workflows and customizations that teams have built over time.
+
+- __MkDocs 2.0 brings breaking changes for themes__ – MkDocs 2.0 comes with a completely rewritten theming system. For instance, [navigation is passed to themes as pre-rendered HTML] rather than structured data. This makes it technically impossible to implement features like navigation tabs, collapsible sections, and other advanced navigation patterns.
+
+ It also limits how navigation can be styled in themes, since the HTML of the navigation cannot be adjusted to fit the theme's structure and design.
+
+- __MkDocs 2.0 has a closed contribution model__ – MkDocs 2.0 moves to a "maintainer-driven issues" model, where community members are [asked not to open issues or pull requests], and "feature requests are generally not accepted". It's unclear how users should report bugs or seek fixes when they encounter problems.
+
+- __MkDocs 2.0 is currently unlicensed__ – MkDocs 2.0 doesn't specify a license, which has implications for how it can be used and contributed to by the community. It's unclear what the rationale behind this decision is, but it should be critically evaluated by teams and organizations that rely on MkDocs for their documentation projects.
+
+- __MkDocs 2.0 has a new configuration format__ – MkDocs 2.0 uses TOML for configuration, which is incompatible with the YAML format used in MkDocs 1.x. As a result, existing `mkdocs.yml` files will currently not work with MkDocs 2.0. There is no migration path for existing projects.
+
+A release date has not been announced, so planning around a specific timeline remains difficult. However, the direction of travel has been hinted at by the maintainer on several occasions, and the pre-release version already confirms the impact of these changes on existing projects.
+
+ [official announcement]: https://github.com/mkdocs/mkdocs/discussions/4077
+ [roadmap]: https://github.com/squidfunk/mkdocs-material/issues/8478#issuecomment-3778358483
+ [asked not to open issues or pull requests]: https://github.com/encode/mkdocs?tab=contributing-ov-file#maintainer-driven-issues
+ [removing plugin support to simplify the codebase]: https://github.com/mkdocs/mkdocs/discussions/3815#discussioncomment-10398312
+ [the plugin ecosystem]: https://github.com/mkdocs/catalog?tab=readme-ov-file#contents
+ [navigation is passed to themes as pre-rendered HTML]: https://www.encode.io/mkdocs/styling/#templates
+ [MkDocs 1.x is unmaintained]: https://github.com/mkdocs/mkdocs/discussions/4010
+ [live-reload problems]: https://github.com/squidfunk/mkdocs-material/issues/8478
+
+## What this means for you
+
+It's worth paying attention: the long-term direction of MkDocs is shifting in ways that diverge from how many documentation teams – and their tooling – currently operate.
+
+While your existing MkDocs projects should continue to work today, be aware that future updates to MkDocs 1.x are unlikely. MkDocs 2.0, in its current form, is not a drop-in replacement for MkDocs 1.x, and does not provide a clear migration path for existing projects.
+
+??? info "How to disable the MkDocs 2.0 incompatibility warning"
+
+ Starting in Material for Mkdocs 9.7.2, a warning is printed during a build about the upcoming MkDocs 2.0 changes. We added this warning to ensure users are aware of the potential impact of MkDocs 2.0 on their projects, and to encourage them to evaluate their options and plan accordingly.
+
+ To disable this warning, set this environment variable:
+
+ ``` bash
+ export NO_MKDOCS_2_WARNING=1
+ ```
+
+## We raised concerns early
+
+All of this isn't coming as a surprise to us, given that the maintainer has presented his plans in an open video call [back in August 2024]. Since it was unclear whether the maintainer would follow through with these plans, we only mentioned it in a footnote, but the pre-release version of MkDocs 2.0 confirms that there will be significant breaking changes for existing projects:
+
+Here's a summary of [the timeline of events]:
+
+> After [we raised this issue] with the maintainers of MkDocs [...], and [maintainership changed] mid 2024, work on a [ground-up rewrite] that aims to address slow reloads by [rendering only the page currently being built] has started. It's still unclear how this rewrite will integrate with the requirements of existing plugins. Complex plugins such as [mkdocstrings], or our [built-in blog] and [tags] plugins require a coordinated build of all pages to accurately resolve links between pages and to computed resources, which cannot be determined without building the entire project.
+
+> __Update__{ title="August 21, 2024" }: The new maintainer now publicly stated that he's working towards a new version of MkDocs that [does not require or support plugins], and mentions it will be equally capable through offering customization via templating, themes, and styling, which he also mentioned to us and several other users in [a team call on August 1]. In this call, [we raised objections multiple times] in regards to how this will impact the ecosystem, to no avail. No intention or roadmap for plugin support was provided. This development is orthogonal to our goal empowering users and organizations to adapt the core framework to their requirements by the means of modularity. We're working on resolving this situation, and will provide a way forward for our community.
+
+The moment we learned about these plans, [we immediately started working] on what would eventually become [Zensical] – a new static site generator designed to be backward-compatible with MkDocs 1.x and a reliable long-term home for your existing documentation projects.
+
+For years, we were trying to improve MkDocs from within. We authored [12 plugins], which gave us a deep understanding of the plugin API's limitations. We conducted quantitative and qualitative analyses of the ecosystem to identify where MkDocs was falling short and talked to dozens of organizations and key ecosystem members. We raised these issues and repeatedly got nowhere. When the new direction of MkDocs 2.0 became apparent, the thinking was already done.
+
+We considered forking MkDocs, but quickly realized it wasn't viable: every plugin in the ecosystem has a direct dependency on `mkdocs`, which means forking MkDocs would require forking every single one of its [300 plugins] – __like moving an entire city at once__.[^1]
+
+ [^1]:
+ Forking is technically feasible by interposing on all MkDocs imports at runtime using Python's import hook machinery (i.e., custom `sys.meta_path` finders/loaders or `importlib` wrappers). In this model, one effectively shadows MkDocs modules by resolving import requests to alternative implementations, or by proxying and patching objects during module initialization.
+
+ However, this approach fundamentally relies on strict API and behavioral compatibility with MkDocs' internal module graph. Because imports are resolved dynamically and cached after first load, any divergence in function signatures, class layouts, side effects, or import order can introduce subtle breakage. As a result, all internal APIs – not just the public surface – must be preserved with near-exact fidelity.
+
+ In practice, this reduces the "fork" to a thin layer of indirection rather than a true divergence. Core functionality cannot be meaningfully refactored or redesigned without violating the implicit contracts embedded throughout the codebase. Consequently, the deeper systemic and structural limitations of MkDocs 1.x remain effectively unchanged under this strategy.
+
+With forking being impractical, we had to start from scratch.
+
+ [we immediately started working]: transforming-material-for-mkdocs.md
+ [the timeline of events]: transforming-material-for-mkdocs.md#fn:7
+ [back in August 2024]: https://github.com/mkdocs/mkdocs/discussions/3671#discussioncomment-10164237
+ [300 plugins]: https://github.com/mkdocs/catalog?tab=readme-ov-file#contents
+ [we raised this issue]: https://github.com/mkdocs/mkdocs/issues/3695
+ [maintainership changed]: https://github.com/mkdocs/mkdocs/discussions/3677
+ [ground-up rewrite]: https://github.com/mkdocs/sketch
+ [rendering only the page currently being built]: https://github.com/mkdocs/mkdocs/issues/3695#issuecomment-2117939743
+ [mkdocstrings]: https://mkdocstrings.github.io/
+ [built-in blog]: ../../plugins/blog.md
+ [tags]: ../../plugins/tags.md
+ [does not require or support plugins]: https://github.com/mkdocs/mkdocs/discussions/3815#discussioncomment-10398312
+ [a team call on August 1]: https://github.com/mkdocs/mkdocs/discussions/3671#discussioncomment-10164237
+ [we raised objections multiple times]: https://github.com/mkdocs/mkdocs/discussions/3671#discussioncomment-10215445
+ [a reliable, backward-compatible home]: https://zensical.org/compatibility/
+ [12 plugins]: ../../plugins/index.md
+
+## Where Zensical comes in
+
+[Zensical][website] is designed to be a __drop-in replacement for MkDocs 1.x__, with the goal of building your existing projects without any changes. _We're not fully there yet_ – supporting the most popular MkDocs plugins in the ecosystem is an ambitious undertaking – but it's our current focus, and we're fully committed to getting there.
+
+Rather than turning this into a marketing pitch, we encourage you to read the [announcement post][Zensical] if you'd like to understand how Zensical differs from MkDocs and what you can already expect today. Additionally, the [compatibility section] on our website offers an overview of what features are already supported without changes.
+
+We also encourage you to do your own research, evaluate the implications for your projects, and consider all available options. If you've relied on Material for MkDocs professionally, valued our work, and are looking for a clear path forward, we're offering [hands-on support for migration].
+
+_If you have any questions, feel free to reach out to Kathi at hello@zensical.org._
+
+## Updates
+
+- __March 27, 2026__: In [Talk Python To Me #542](https://talkpython.fm/episodes/show/542), Martin Donath shares the backstory of Zensical, and reflects on the lessons learned maintaining Material for MkDocs for almost a decade.
+
+- __March 22, 2026__: In _[The Slow Collapse of MkDocs]_, Florian Maas outlines the entire timeline of events starting in 2014 that eventually led to the fracturing of the MkDocs ecosystem.
+
+- __March 10, 2026__: We released 9.7.5, which limits the version range of MkDocs to `<2`. This ensures that your builds will continue to work, even if MkDocs 2.0 is released.
+
+- __March 10, 2026__: Access to the `mkdocs` package for the maintainers removed on March 9 [seems to have been restored](https://github.com/orgs/ProperDocs/discussions/1#discussioncomment-16060966), including the original creator of MkDocs.
+
+- __March 9, 2026__: One of the previous maintainers [changed ownership of the `mkdocs` package on PyPI](https://web.archive.org/web/20260310162839/https://github.com/mkdocs/mkdocs/discussions/4089)[^2], removing access for all other maintainers, including the original creator of MkDocs.
+
+[^2]:
+ The link points to the web archive, as the original post has been edited multiple times by the previous maintainer.
+
+- __March 4, 2026__: We added a paragraph explaining that prior attempts on resolving the situation were unsuccessful and why we decided to find a new path for our community.
+
+- __March 3, 2026__: We added a paragraph on the new contribution model that MkDocs 2.0 is adopting, and the implications for users and contributors from our perspective.
+
+- __February 27, 2026__: We added a note on the `NO_MKDOCS_2_WARNING` environment variable to disable the MkDocs 2.0 incompatibility warning in Material for MkDocs.
+
+- __February 19, 2026__: The published MkDocs 2.0 roadmap was deleted. The link now points to an issue comment that contains a screenshot of the last available version of the roadmap.
+
+- __February 13, 2026__: The mention of compatibility planned for MkDocs 1.x and MkDocs 2.0 projects was removed from the MkDocs 2.0 [`README.md`](https://github.com/encode/mkdocs/commit/313d3e8#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L52).
+
+ [The Slow Collapse of MkDocs]: https://fpgmaas.com/blog/collapse-of-mkdocs/
+ [compatibility section]: https://zensical.org/compatibility/features/
+ [hands-on support for migration]: https://zensical.org/spark/
+ [website]: https://zensical.org
+ [why we built Zensical]: zensical.md
+ [feature parity]: https://zensical.org/compatibility/features/
+ [module system]: https://zensical.org/about/roadmap/#module-system
diff --git a/documents/markdown/mkdocs-material/blog_posts_search-better-faster-smaller.md b/documents/markdown/mkdocs-material/blog_posts_search-better-faster-smaller.md
new file mode 100644
index 0000000..969d897
--- /dev/null
+++ b/documents/markdown/mkdocs-material/blog_posts_search-better-faster-smaller.md
@@ -0,0 +1,629 @@
+---
+date: 2021-09-13
+authors: [squidfunk]
+readtime: 15
+description: >
+ How we rebuilt client-side search, delivering a better user experience while
+ making it faster and smaller at the same time
+categories:
+ - Search
+ - Performance
+links:
+ - plugins/search.md
+---
+
+# Search: better, faster, smaller
+
+__This is the story of how we managed to completely rebuild client-side search,
+delivering a significantly better user experience while making it faster and
+smaller at the same time.__
+
+The [search] of Material for MkDocs is by far one of its best and most-loved
+assets: [multilingual], [offline-capable], and most importantly: _all
+client-side_. It provides a solution to empower the users of your documentation
+to find what they're searching for instantly without the headache of managing
+additional servers. However, even though several iterations have been made,
+there's still some room for improvement, which is why we rebuilt the search
+plugin and integration from the ground up. This article shines some light on the
+internals of the new search, why it's much more powerful than the previous
+version, and what's about to come.
+
+<!-- more -->
+
+_The next section discusses the architecture and issues of the current search
+implementation. If you immediately want to learn what's new, skip to the
+[section just after that][what's new]._
+
+ [search]: ../../setup/setting-up-site-search.md
+ [multilingual]: ../../plugins/search.md#config.lang
+ [offline-capable]: ../../setup/building-for-offline-usage.md
+ [what's new]: #whats-new
+
+## Architecture
+
+Material for MkDocs uses [lunr] together with [lunr-languages] to implement
+its client-side search capabilities. When a documentation page is loaded and
+JavaScript is available, the search index as generated by the
+[built-in search plugin] during the build process is requested from the
+server:
+
+``` ts
+const index$ = document.forms.namedItem("search")
+ ? __search?.index || requestJSON<SearchIndex>(
+ new URL("search/search_index.json", config.base)
+ )
+ : NEVER
+```
+
+ [lunr]: https://lunrjs.com
+ [lunr-languages]: https://github.com/MihaiValentin/lunr-languages
+ [built-in search plugin]: ../../plugins/search.md
+
+### Search index
+
+The search index includes a stripped-down version of all pages. Let's take a
+look at an example to understand precisely what the search index contains from
+the original Markdown file:
+
+??? example "Expand to inspect example"
+
+ === ":octicons-file-code-16: `docs/page.md`"
+
+ ```` markdown
+ # Example
+
+ ## Text
+
+ It's very easy to make some words **bold** and other words *italic*
+ with Markdown. You can even add [links](#), or even `code`:
+
+ ```
+ if (isAwesome) {
+ return true
+ }
+ ```
+
+ ## Lists
+
+ Sometimes you want numbered lists:
+
+ 1. One
+ 2. Two
+ 3. Three
+
+ Sometimes you want bullet points:
+
+ * Start a line with a star
+ * Profit!
+ ````
+
+ === ":octicons-codescan-16: `search_index.json`"
+
+ ``` json
+ {
+ "config": {
+ "indexing": "full",
+ "lang": [
+ "en"
+ ],
+ "min_search_length": 3,
+ "prebuild_index": false,
+ "separator": "[\\s\\-]+"
+ },
+ "docs": [
+ {
+ "location": "page/",
+ "title": "Example",
+ "text": "Example Text It's very easy to make some words bold and other words italic with Markdown. You can even add links , or even code : if (isAwesome) { return true } Lists Sometimes you want numbered lists: One Two Three Sometimes you want bullet points: Start a line with a star Profit!"
+ },
+ {
+ "location": "page/#example",
+ "title": "Example",
+ "text": ""
+ },
+ {
+ "location": "page/#text",
+ "title": "Text",
+ "text": "It's very easy to make some words bold and other words italic with Markdown. You can even add links , or even code : if (isAwesome) { return true }"
+ },
+ {
+ "location": "page/#lists",
+ "title": "Lists",
+ "text": "Sometimes you want numbered lists: One Two Three Sometimes you want bullet points: Start a line with a star Profit!"
+ }
+ ]
+ }
+ ```
+
+If we inspect the search index, we immediately see several problems:
+
+ 1. __All content is included twice__: the search index contains one entry
+ with the entire contents of the page, and one entry for each section of
+ the page, i.e., each block preceded by a headline or subheadline. This
+ significantly contributes to the size of the search index.
+
+ 2. __All structure is lost__: when the search index is built, all structural
+ information like HTML tags and attributes are stripped from the content.
+ While this approach works well for paragraphs and inline formatting, it
+ might be problematic for lists and code blocks. An excerpt:
+
+ ```
+ … links , or even code : if (isAwesome) { … } Lists Sometimes you want …
+ ```
+
+ - __Context__: for an untrained eye, the result can look like gibberish, as
+ it's not immediately apparent what classifies as text and what as code.
+ Furthermore, it's not clear that `Lists` is a headline as it's merged
+ with the code block before and the paragraph after it.
+
+ - __Punctuation__: inline elements like links that are immediately followed
+ by punctuation are separated by whitespace (see `,` and `:` in the
+ excerpt). This is because all extracted text is joined with a whitespace
+ character during the construction of the search index.
+
+It's not difficult to see that it can be quite challenging to implement a good
+search experience for theme authors, which is why Material for MkDocs (up to
+now) did some [monkey patching] to be able to render slightly more
+meaningful search previews.
+
+ [monkey patching]: https://github.com/squidfunk/mkdocs-material/blob/ec7ccd2b2d15dd033740f388912f7be7738feec2/src/assets/javascripts/integrations/search/document/index.ts#L68-L71
+
+### Search worker
+
+The actual search functionality is implemented as part of a web worker[^1],
+which creates and manages the [lunr] search index. When search is initialized,
+the following steps are taken:
+
+ [^1]:
+ Prior to <!-- md:version 5.0.0 -->, search was carried out in the main
+ thread which locked up the browser, rendering it unusable. This problem was
+ first reported in #904 and, after some back and forth, fixed and released in
+ <!-- md:version 5.0.0 -->.
+
+1. __Linking sections with pages__: The search index is parsed, and each
+ section is linked to its parent page. The parent page itself is _not
+ indexed_, as it would lead to duplicate results, so only the sections
+ remain. Linking is necessary, as search results are grouped by page.
+
+2. __Tokenization__: The `title` and `text` values of each section are split
+ into tokens by using the [`separator`][separator] as configured in
+ `mkdocs.yml`. Tokenization itself is carried out by
+ [lunr's default tokenizer][default tokenizer], which doesn't allow for
+ lookahead or separators spanning multiple characters.
+
+ > Why is this important and a big deal? We will see later how much more we
+ > can achieve with a tokenizer that is capable of separating strings with
+ > lookahead.
+
+3. __Indexing__: As a final step, each section is indexed. When querying the
+ index, if a search query includes one of the tokens as returned by step 2.,
+ the section is considered to be part of the search result and passed to the
+ main thread.
+
+Now, that's basically how the search worker operates. Sure, there's a little
+more magic involved, e.g., search results are [post-processed] and [rescored] to
+account for some shortcomings of [lunr], but in general, this is how data gets
+into and out of the index.
+
+ [separator]: ../../plugins/search.md#config.separator
+ [default tokenizer]: https://github.com/olivernn/lunr.js/blob/aa5a878f62a6bba1e8e5b95714899e17e8150b38/lunr.js#L413-L456
+ [post-processed]: https://github.com/squidfunk/mkdocs-material/blob/ec7ccd2b2d15dd033740f388912f7be7738feec2/src/assets/javascripts/integrations/search/_/index.ts#L249-L272
+ [rescored]: https://github.com/squidfunk/mkdocs-material/blob/ec7ccd2b2d15dd033740f388912f7be7738feec2/src/assets/javascripts/integrations/search/_/index.ts#L274-L275
+
+### Search previews
+
+Users should be able to quickly scan and evaluate the relevance of a search
+result in the given context, which is why a concise summary with highlighted
+occurrences of the search terms found is an essential part of a great search
+experience.
+
+This is where the current search preview generation falls short, as some of the
+search previews appear not to include any occurrence of any of the search
+terms. This was due to the fact that search previews were [truncated after a
+maximum of 320 characters][truncated], as can be seen here:
+
+<figure markdown>
+
+![search preview]
+
+ <figcaption markdown>
+
+The first two results look like they're not relevant, as they don't seem to
+include the query string the user just searched for. Yet, they are.
+
+ </figcaption>
+</figure>
+
+A better solution to this problem has been on the roadmap for a very, very long
+time, but in order to solve this once and for all, several factors need to be
+carefully considered:
+
+1. __Word boundaries__: some themes[^2] for static site generators generate
+ search previews by expanding the text left and right next to an occurrence,
+ stopping at a whitespace character when enough words have been consumed. A
+ preview might look like this:
+
+ ```
+ … channels, e.g., or which can be configured via mkdocs.yml …
+ ```
+
+ While this may work for languages that use whitespace as a separator
+ between words, it breaks down for languages like Japanese or Chinese[^3],
+ as they have non-whitespace word boundaries and use dedicated segmenters to
+ split strings into tokens.
+
+ [^2]:
+ At the time of writing, [Just the Docs] and [Docusaurus] use this method
+ for generating search previews. Note that the latter also integrates with
+ Algolia, which is a fully managed server-based solution.
+
+ [^3]:
+ China and Japan are both within the top 5 countries of origin of users of
+ Material for MkDocs.
+
+ [truncated]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/assets/javascripts/templates/search/index.tsx#L90
+ [search preview]: search-better-faster-smaller/search-preview.png
+ [Just the Docs]: https://just-the-docs.com
+ [Docusaurus]: https://github.com/lelouch77/docusaurus-lunr-search
+
+1. __Context-awareness__: Although whitespace doesn't work for all languages,
+ one could argue that it could be a good enough solution. Unfortunately, this
+ is not necessarily true for code blocks, as the removal of whitespace might
+ change meaning in some languages.
+
+3. __Structure__: Preserving structural information is not a must, but
+ apparently beneficial to build more meaningful search previews which allow
+ for a quick evaluation of relevance. If a word occurrence is part of a code
+ block, it should be rendered as a code block.
+
+## What's new?
+
+After we built a solid understanding of the problem space and before we dive
+into the internals of our new search implementation to see which of the
+problems it already solves, a quick overview of what features and improvements
+it brings:
+
+- __Better__: support for [rich search previews], preserving the structural
+ information of code blocks, inline code, and lists, so they are rendered
+ as-is, as well as [lookahead tokenization], [more accurate highlighting], and
+ improved stability of typeahead. Also, a [slightly better UX].
+- __Faster__ and __smaller__: significant decrease in search index size of up
+ to 48% due to improved extraction and construction techniques, resulting in a
+ search experience that is up to 95% faster, which is particularly helpful for
+ large documentation projects.
+
+ [rich search previews]: #rich-search-previews
+ [lookahead tokenization]: #tokenizer-lookahead
+ [more accurate highlighting]: #accurate-highlighting
+ [slightly better UX]: #user-interface
+
+### Rich search previews
+
+As we rebuilt the search plugin from scratch, we reworked the construction of
+the search index to preserve the structural information of code blocks, inline
+code, as well as unordered and ordered lists. Using the example from the
+[search index] section, here's how it looks:
+
+=== "Now"
+
+ ![search preview now]
+
+=== "Before"
+
+ ![search preview before]
+
+Now, __code blocks are first-class citizens of search previews__, and even
+inline code formatting is preserved. Let's take a look at the new structure of
+the search index to understand why:
+
+??? example "Expand to inspect search index"
+
+ === "Now"
+
+ ``` json
+ {
+ ...
+ "docs": [
+ {
+ "location": "page/",
+ "title": "Example",
+ "text": ""
+ },
+ {
+ "location": "page/#text",
+ "title": "Text",
+ "text": "<p>It's very easy to make some words bold and other words italic with Markdown. You can even add links, or even <code>code</code>:</p> <pre><code>if (isAwesome){\n return true\n}\n</code></pre>"
+ },
+ {
+ "location": "page/#lists",
+ "title": "Lists",
+ "text": "<p>Sometimes you want numbered lists:</p> <ol> <li>One</li> <li>Two</li> <li>Three</li> </ol> <p>Sometimes you want bullet points:</p> <ul> <li>Start a line with a star</li> <li>Profit!</li> </ul>"
+ }
+ ]
+ }
+ ```
+
+ === "Before"
+
+ ``` json
+ {
+ ...
+ "docs": [
+ {
+ "location": "page/",
+ "title": "Example",
+ "text": "Example Text It's very easy to make some words bold and other words italic with Markdown. You can even add links , or even code : if (isAwesome) { return true } Lists Sometimes you want numbered lists: One Two Three Sometimes you want bullet points: Start a line with a star Profit!"
+ },
+ {
+ "location": "page/#example",
+ "title": "Example",
+ "text": ""
+ },
+ {
+ "location": "page/#text",
+ "title": "Text",
+ "text": "It's very easy to make some words bold and other words italic with Markdown. You can even add links , or even code : if (isAwesome) { return true }"
+ },
+ {
+ "location": "page/#lists",
+ "title": "Lists",
+ "text": "Sometimes you want numbered lists: One Two Three Sometimes you want bullet points: Start a line with a star Profit!"
+ }
+ ]
+ }
+ ```
+
+If we inspect the search index again, we can see how the situation improved:
+
+1. __Content is included only once__: the search index does not include the
+ content of the page twice, as only the sections of a page are part of the
+ search index. This leads to a significant reduction in size, fewer bytes to
+ transfer, and a smaller search index.
+
+2. __Some structure is preserved__: each section of the search index includes
+ a small subset of HTML to provide the necessary structure to allow for more
+ sophisticated search previews. Revisiting our example from before, let's
+ look at an excerpt:
+
+ === "Now"
+
+ ``` html
+ … links, or even <code>code</code>:</p> <pre><code>if (isAwesome){ … }\n</code></pre>
+ ```
+
+ === "Before"
+
+ ```
+ … links , or even code : if (isAwesome) { … }
+ ```
+
+ The punctuation issue is gone, as no additional whitespace is inserted, and
+ the preserved markup yields additional context to make scanning search
+ results more effective.
+
+On to the next step in the process: __tokenization__.
+
+ [search index]: #search-index
+ [search preview now]: search-better-faster-smaller/search-preview-now.png
+ [search preview before]: search-better-faster-smaller/search-preview-before.png
+
+### Tokenizer lookahead
+
+The [default tokenizer] of [lunr] uses a regular expression to split a given
+string by matching each character against the [`separator`][separator] as
+defined in `mkdocs.yml`. This doesn't allow for more complex separators based
+on lookahead or multiple characters.
+
+Fortunately, __our new search implementation provides an advanced tokenizer__
+that doesn't have these shortcomings and supports more complex regular
+expressions. As a result, Material for MkDocs just changed its own separator
+configuration to the following value:
+
+```
+[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;
+```
+
+While the first part up to the first `|` contains a list of single control
+characters at which the string should be split, the following three sections
+explain the remainder of the regular expression.[^4]
+
+ [^4]:
+ As a fun fact: the [`separator`][separator] [default value] of the search
+ plugin being `[\s\-]+` always has been kind of irritating, as it suggests
+ that multiple characters can be considered being a separator. However, the
+ `+` is completely irrelevant, as regular expression groups involving
+ multiple characters were never supported by
+ [lunr's default tokenizer][default tokenizer].
+
+ [default value]: https://www.mkdocs.org/user-guide/configuration/#separator
+
+#### Case changes
+
+Many programming languages use `PascalCase` or `camelCase` naming conventions.
+When a user searches for the term `case`, it's quite natural to expect for
+`PascalCase` and `camelCase` to show up. By adding the following match group to
+the separator, this can now be achieved with ease:
+
+```
+(?!\b)(?=[A-Z][a-z])
+```
+
+This regular expression is a combination of a negative lookahead (`\b`, i.e.,
+not a word boundary) and a positive lookahead (`[A-Z][a-z]`, i.e., an uppercase
+character followed by a lowercase character), and has the following behavior:
+
+- `PascalCase` :octicons-arrow-right-24: `Pascal`, `Case`
+- `camelCase` :octicons-arrow-right-24: `camel`, `Case`
+- `UPPERCASE` :octicons-arrow-right-24: `UPPERCASE`
+
+Searching for [:octicons-search-24: searchHighlight][q=searchHighlight]
+now brings up the section discussing the `search.highlight` feature flag, which
+also demonstrates that this now even works properly for search queries.[^5]
+
+ [^5]:
+ Previously, the search query was not correctly tokenized due to the way
+ [lunr] treats wildcards, as it disables the pipeline for search terms that
+ contain wildcards. In order to provide a good typeahead experience,
+ Material for MkDocs adds wildcards to the end of each search term not
+ explicitly preceded with `+` or `-`, effectively disabling tokenization.
+
+ [q=searchHighlight]: ?q=searchHighlight
+
+#### Version numbers
+
+Indexing version numbers is another problem that can be solved with a small
+lookahead. Usually, `.` should be considered a separator to split words like
+`search.highlight`. However, splitting version numbers at `.` will make them
+undiscoverable. Thus, the following expression:
+
+```
+\.(?!\d)
+```
+
+This regular expression matches a `.` only if not immediately followed by a
+digit `\d`, which leaves version numbers discoverable. Searching for
+[:octicons-search-24: 7.2.6][q=7.2.6] brings up the [7.2.6] release notes.
+
+ [q=7.2.6]: ?q=7.2.6
+ [7.2.6]: ../../changelog/index.md#7.2.6
+
+#### HTML/XML tags
+
+If your documentation includes HTML/XML code examples, you may want to allow
+users to find specific tag names. Unfortunately, the `<` and `>` control
+characters are encoded in code blocks as `<` and `>`. Now, adding the
+following expression to the separator allows for just that:
+
+```
+&[lg]t;
+```
+
+---
+
+_We've only just begun to scratch the surface of the new possibilities
+tokenizer lookahead brings. If you found other useful expressions, you're
+invited to share them in the comment section._
+
+### Accurate highlighting
+
+Highlighting is the last step in the process of search and involves the
+highlighting of all search term occurrences in a given search result. For a
+long time, highlighting was implemented through dynamically generated
+[regular expressions].[^6]
+
+This approach has some problems with non-whitespace languages like Japanese or
+Chinese[^3] since it only works if the highlighted term is at a word boundary.
+However, Asian languages are tokenized using a [dedicated segmenter], which
+cannot be modeled with regular expressions.
+
+ [^6]:
+ Using the separator as defined in `mkdocs.yml`, a regular expression was
+ constructed that was trying to mimic the tokenizer. As an example, the
+ search query `search highlight` was transformed into the rather cumbersome
+ regular expression `(^|<separator>)(search|highlight)`, which only matches
+ at word boundaries.
+
+Now, as a direct result of the [new tokenization approach], __our new search
+implementation uses token positions for highlighting__, making it exactly as
+powerful as tokenization:
+
+1. __Word boundaries__: as the new highlighter uses token positions, word
+ boundaries are equal to token boundaries. This means that more complex cases
+ of tokenization (e.g., [case changes], [version numbers], [HTML/XML tags]),
+ are now all highlighted accurately.
+
+2. __Context-awareness__: as the new search index preserves some of the
+ structural information of the original document, the content of a section
+ is now divided into separate content blocks – paragraphs, code blocks, and
+ lists.
+
+ Now, only the content blocks that actually contain occurrences of one of
+ the search terms are considered for inclusion into the search preview. If a
+ term only occurs in a code block, it's the code block that gets rendered,
+ see, for example, the results of
+ [:octicons-search-24: twitter][q=twitter].
+
+ [regular expressions]: https://github.com/squidfunk/mkdocs-material/blob/ec7ccd2b2d15dd033740f388912f7be7738feec2/src/assets/javascripts/integrations/search/highlighter/index.ts#L61-L91
+ [dedicated segmenter]: http://chasen.org/~taku/software/TinySegmenter/
+ [new tokenization approach]: #tokenizer-lookahead
+ [case changes]: #case-changes
+ [version numbers]: #version-numbers
+ [HTML/XML tags]: #htmlxml-tags
+ [q=twitter]: ?q=twitter
+
+### Benchmarks
+
+We conducted two benchmarks – one with the documentation of Material for MkDocs
+itself, and one with a very massive corpus of Markdown files with more than
+800,000 words – a size most documentation projects will likely never
+reach:
+
+<figure markdown>
+
+| | Before | Now | Relative |
+| ----------------------- | -------: | -------------: | -----------: |
+| __Material for MkDocs__ | | | |
+| Index size | 573 kB | __335 kB__ | __–42%__ |
+| Index size (`gzip`) | 105 kB | __78 kB__ | __–27%__ |
+| Indexing time[^7] | 265 ms | __177 ms__ | __–34%__ |
+| __KJV Markdown[^8]__ | | | |
+| Index size | 8.2 MB | __4.4 MB__ | __–47%__ |
+| Index size (`gzip`) | 2.3 MB | __1.2 MB__ | __–48%__ |
+| Indexing time | 2,700 ms | __1,390 ms__ | __–48%__ |
+
+<figcaption>
+ <p>Benchmark results</p>
+</figcaption>
+
+</figure>
+
+ [^7]:
+ Smallest value of ten distinct runs.
+
+ [^8]:
+ We agnostically use [KJV Markdown] as a tool for testing to learn how
+ Material for MkDocs behaves on large corpora, as it's a very large set of
+ Markdown files with over 800k words.
+
+The results show that indexing time, which is the time that it takes to set up
+the search when the page is loaded, has dropped by up to 48%, which means __the
+new search is up to 95% faster__. This is a significant improvement,
+particularly relevant for large documentation projects.
+
+While 1,3s still may sound like a long time, using the new client-side search
+together with [instant loading] only creates the search index on the initial
+page load. When navigating, the search index is preserved across pages, so the
+cost does only have to be paid once.
+
+ [KJV Markdown]: https://github.com/arleym/kjv-markdown
+ [instant loading]: ../../setup/setting-up-navigation.md#instant-loading
+
+### User interface
+
+Additionally, some small improvements have been made, most prominently the
+__more results on this page__ button, which now sticks to the top of the search
+result list when open. This enables the user to jump out of the list more
+quickly.
+
+## What's next?
+
+Our new search implementation is a big improvement to Material for MkDocs. It
+solves some long-standing issues which needed to be tackled for years. Yet,
+it's only the start of a search experience that is going to get better and
+better. Next up:
+
+- __Context-aware search summarization__: currently, the first two matching
+ content blocks are rendered as a search preview. With the new tokenization
+ technique, we laid the groundwork for more sophisticated shortening and
+ summarization methods, which we're tackling next.
+
+- __User interface improvements__: as we now gained full control over the
+ search plugin, we can now add meaningful metadata to provide more context and
+ a better experience. We'll explore some of those paths in the future.
+
+If you've made it this far, thank you for your time and interest in Material
+for MkDocs! This is the first blog article that I decided to write after a
+short [Twitter survey] made me to. You're invited to leave a comment
+to share your experiences with the new search implementation.
+
+ [X survey]: https://x.com/squidfunk/status/1434477478823743488
diff --git a/documents/markdown/mkdocs-material/blog_posts_sunsetting-gitter.md b/documents/markdown/mkdocs-material/blog_posts_sunsetting-gitter.md
new file mode 100644
index 0000000..4cc9660
--- /dev/null
+++ b/documents/markdown/mkdocs-material/blog_posts_sunsetting-gitter.md
@@ -0,0 +1,96 @@
+---
+date: 2023-10-02
+authors: [squidfunk, alexvoss]
+categories:
+ - General
+---
+
+# Sunsetting Gitter: Towards Efficient Community Engagement
+
+__As we're starting to build a team around Material for MkDocs, we've decided to
+sunset and archive our [Gitter] channel on October 13, 2023 in favor of
+[GitHub Discussions].__
+
+As part of our efforts to improve the processes for maintaining Material for
+MkDocs and for supporting the community, we have reviewed the use of different
+communication channels. At the moment, both [Gitter] and [GitHub Discussions]
+allow to ask the community for support and to discuss ideas and issues. In the
+past weeks, we have begun to question whether this duplication is in the best
+interest of our project. This post explains the rationale behind our decision.
+
+ [Gitter]: https://gitter.im/squidfunk/mkdocs-material
+ [GitHub discussions]: https://github.com/squidfunk/mkdocs-material/discussions
+
+<!-- more -->
+
+## The Constraints of Gitter
+
+In the first years of Material for MkDocs, [Gitter] served as a helpful platform
+for quick community interactions and questions. However, there are some inherent
+constraints that necessitated a shift. Here's a breakdown of the challenges we
+encountered:
+
+1. __Thread utilization__ –
+ Even with the introduction of threads, many Gitter users were reticent to
+ use them, leading to cluttered and disconnected conversations, making it
+ difficult to follow.
+
+2. __Search and discovery__ –
+ Gitter's structure and interface makes it cumbersome to search for and
+ retrieve past messages, resulting in lost insights and repeated conversations.
+
+1. __User interface__ –
+ After the acquisition by [Element], the user interface of Gitter has
+ experienced a severe decline, becoming more complicated, less intuitive and
+ user-friendly.
+
+1. __Access mandate__ –
+ The necessity for users to grant access to their GitHub accounts to use
+ Gitter posed an unnecessary access barrier and potential security concerns.
+
+ [Element]: https://element.io/blog/gitter-is-joining-element/
+
+## GitHub Discussions
+
+Thankfully, [GitHub Discussions] emerged and continues to evolve to be a much
+better alternative, eliminating many of Gitter's constraints and offering
+enhanced functionality:
+
+1. __Threaded conversations__ –
+ GitHub Discussions supports structured, threaded conversations, ensuring
+ discussions are coherent, contextual, and easy to follow for everyone.
+
+2. __Integration and linking__ –
+ the platform facilitates seamless linking to other discussions, issues, code,
+ and much more, enriching conversations and providing comprehensive context.
+
+3. __A unified platform__ –
+ GitHub acts as a one-stop shop for support, allowing users to access varied
+ resources and support channels in one place, greatly improving user
+ experience.
+
+4. __Discoverability__ –
+ GitHub Discussions are easily searchable and allow for categorization,
+ preventing loss of valuable insights and fostering knowledge sharing.
+
+## Conclusion
+
+Sunsetting [Gitter] is a leap towards creating more efficient, user-friendly,
+and enriched community interactions. By consolidating communication to
+[GitHub Discussions], we seek to mitigate the fragmentation of information,
+ease the user journey, and fortify the bonds within our community.
+
+This concentrated approach enables us to provide consistent, fast and quality
+support to our users. In the past, the nature of queries raised on Gitter
+typically necessitated supplementary information or reproductions, prompting us
+to advise users to initiate a discussion subsequently. The shift to a
+centralized discussion forum is designed to simplify and accelerate this
+procedure, ensuring swift and efficient resolutions for our community. It is a
+testament to our ongoing commitment to support the community that helps Material
+for MkDocs flourish.
+
+We are confident that this streamlined approach will spur more
+fruitful discussions, innovative ideas, and collective growth, and we are
+excited to continue our journey with the unwavering support and active
+participation of our community.
+
diff --git a/documents/markdown/mkdocs-material/blog_posts_the-past-present-and-future.md b/documents/markdown/mkdocs-material/blog_posts_the-past-present-and-future.md
new file mode 100644
index 0000000..f3ec964
--- /dev/null
+++ b/documents/markdown/mkdocs-material/blog_posts_the-past-present-and-future.md
@@ -0,0 +1,263 @@
+---
+date: 2021-12-27
+authors: [squidfunk]
+description: >
+ 2021 was a fantastic year for this project as we shipped many new awesome
+ features and made this project sustainable
+categories:
+ - General
+---
+
+# The past, present and future
+
+__2021 was a fantastic year for this project as we shipped many new awesome
+features, saw significant user growth and leveraged GitHub Sponsors to make the
+project sustainable.__
+
+Today, together, [MkDocs] and Material for MkDocs are among the most popular
+options when it comes to choosing a static site generator and theme for your
+technical documentation project. Material for MkDocs ensures that your
+content is always perfectly presented to your audience, regardless of screen
+resolution or device capabilities. It has evolved to a framework for technical
+writing, offering many features, some of which are yet to be found in other
+static site generators. However, we're far from the end, as 2022 is going to
+bring some interesting new capabilities.
+
+<!-- more -->
+
+_This article showcases all features that were added in 2021 and gives an
+outlook on what's going to drop in 2022. Additionally, it provides some context
+on the history of the project._
+
+ [MkDocs]: https://www.mkdocs.org
+
+## A little history
+
+In 2015, albeit 10 years in the industry, I was still quite new in Open Source.
+I wanted to release my latest Open Source project [protobluff], a zero-copy
+Protocol Buffers implementation for C, which I've created as part of my former
+startup. As the project has a significant degree of complexity, I quickly
+realized that I was in need of good user documentation.
+
+After evaluating static site generators in general and Hugo, Sphinx and MkDocs
+in particular, I quickly decided that MkDocs seemed a good choice, as it was
+specifically aimed at technical project documentation and easy to use.
+Unfortunately, all of the available themes looked dated and given that I'm a
+very visual person, I just couldn't convince myself to call it a day.
+
+I _had_ to build a theme.
+
+Months later, in February 2016, I released [the first version] of Material for
+MkDocs (and with it, [protobluff], the project I wanted to release in the first
+place), and it looked like this:
+
+![Material for MkDocs 0.1.0][Material for MkDocs 0.1.0]
+
+It was already fully responsive and overall, well, quite okayish, but barely
+customizable, as only the logo could be changed. Beyond that, it had no options:
+No color or navigation options, no instant loading, etc. The search was very
+rudimentary and only supported section titles:
+
+![Material for MkDocs 0.1.0 Search][Material for MkDocs 0.1.0 Search]
+
+It's important to know that at this point in time I've built Material for
+MkDocs for [protobluff], the project I was really caring about. Almost 6 years
+later, nobody knows protobluff, but this little side project has taken off. If
+back in those days, you would've told me big organizations like AWS,
+Microsoft and CERN, as well as extremely popular Open Source projects like
+FastAPI and Kubernetes will be using this project in the future – I would've
+declared you insane.
+
+I still find the success of this project quite surprising, as I thought that
+themes exist in abundance and are very much a solved problem. There's no glory
+in themes, no stars to earn (remember that I was new in Open Source, so this was
+the metric I was optimizing for), as there are thousands and thousands of
+options. However, as the years progressed, I learned that _execution matters_:
+although Material for MkDocs solves a problem for which thousands of solutions
+exist, it excels in a specific niche, and that niche is to be known as
+_technical project documentation_.
+
+Today, this project is not only popular but funded by almost 300 individuals
+and organizations, resulting in a yearly budget of more than $50,000. This
+allows me to set aside enough time for the development of new features,
+bug fixing, stability improvement, issue triage and general support and still
+feels like a dream to me, as there are many failed stories of Open Source
+funding and people telling you: _don't do Open Source, you'll be working for
+free._
+
+Making Open Source sustainable is, after all, possible in 2021.
+
+ [the first version]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
+ [Material for MkDocs 0.1.0]: the-past-present-and-future/mkdocs-material-0.1.0.png
+ [Material for MkDocs 0.1.0 Search]: the-past-present-and-future/mkdocs-material-0.1.0-search.png
+ [protobluff]: https://github.com/squidfunk/protobluff
+
+## 2021 in numbers
+
+2021 was an exciting year, as the project has seen significant growth.
+
+__166k people__ visited the official documentation in 2021, totalling in __1,6m
+page views__ which is an increase of 83% when compared to 2020. The average
+visitor spends __1,5min__ on the site. While mobile phones make up 12% of
+visits, tablets only account for 0.6%. Visitors come from as many as __213
+countries__, which covers almost the whole world.
+
+### Features
+
+It's absolutely mind-blowing that __38 new features__ were added to Material
+for MkDocs throughout 2021 – __that's a new feature every 9,6 days__ –
+which was only possible because of the constantly improving funding situation.
+Following is a list of all features shipped in alphabetical order, some of which
+are still exclusively available to sponsors as part of [Insiders]:
+
+<div class="mdx-columns" markdown>
+
+- [Admonition inline blocks]
+- [Advanced search highlighting]
+- [Anchor tracking]
+- [Back-to-top button]
+- [Boosting pages in search]
+- [Brand new search plugin]
+- [Code annotations]
+- Code annotations: anchor links
+- [Code annotations: strip comments]
+- [Code block titles]
+- [Code block line anchors]
+- [Color palette toggle]
+- [Content tabs: improved support]
+- [Content tabs: auto-linking]
+- Content tabs: animated indicator
+- [Cookie consent]
+- [Custom admonition icons]
+- [Dark mode support for images]
+- [Dismissable announcement bar]
+- [Excluding content from search]
+- Latest release tag
+- [Mermaid.js integration]
+- [Navigation icons]
+- [Remove generator notice]
+- [Rich search previews]
+- Stay on page when switching versions
+- [Search highlighting]
+- [Search sharing]
+- [Search suggestions]
+- [Section index pages]
+- [Site language selection]
+- [Social cards]
+- [Sticky navigation tabs]
+- [Tags with search integration]
+- [Tokenizer with lookahead]
+- [Versioning]
+- [Version warning]
+- [Was this page helpful?]
+
+</div>
+
+Additionally, a lot of bugs were fixed in the __1,000 commits__ that were pushed
+to the repository this year. The [changelog] includes a list of all fixes.
+Furthermore, a large amount of time was invested into refactoring the code base
+to keep it in good shape. While the `mkdocs-material` package was released
+__55__ times, `mkdocs-material-insiders` was shipped __72__ times.
+
+ [Insiders]: ../../insiders/index.md
+ [Admonition inline blocks]: ../../reference/admonitions.md#inline-blocks
+ [Advanced search highlighting]: search-better-faster-smaller.md#accurate-highlighting
+ [Anchor tracking]: ../../setup/setting-up-navigation.md#anchor-tracking
+ [Back-to-top button]: ../../setup/setting-up-navigation.md#back-to-top-button
+ [Boosting pages in search]: ../../setup/setting-up-site-search.md#search-boosting
+ [Brand new search plugin]: search-better-faster-smaller.md
+ [Code annotations]: ../../reference/code-blocks.md#adding-annotations
+ [Code annotations: strip comments]: ../../reference/code-blocks.md#stripping-comments
+ [Code block titles]: ../../reference/code-blocks.md#adding-a-title
+ [Code block line anchors]: ../../setup/extensions/python-markdown-extensions.md#+pymdownx.highlight.anchor_linenums
+ [Color palette toggle]: ../../setup/changing-the-colors.md#color-palette-toggle
+ [Content tabs: improved support]: ../../reference/content-tabs.md
+ [Content tabs: auto-linking]: ../../reference/content-tabs.md#linked-content-tabs
+ [Cookie consent]: ../../setup/ensuring-data-privacy.md#cookie-consent
+ [Custom admonition icons]: ../../reference/admonitions.md#admonition-icons
+ [Dark mode support for images]: ../../reference/images.md#light-and-dark-mode
+ [Dismissable announcement bar]: ../../setup/setting-up-the-header.md#mark-as-read
+ [Excluding content from search]: ../../setup/setting-up-site-search.md#search-exclusion
+ [Mermaid.js integration]: ../../reference/diagrams.md
+ [Navigation icons]: ../../reference/index.md#setting-the-page-icon
+ [Remove generator notice]: ../../setup/setting-up-the-footer.md#generator-notice
+ [Rich search previews]: search-better-faster-smaller.md#rich-search-previews
+ [Search highlighting]: ../../setup/setting-up-site-search.md#search-highlighting
+ [Search sharing]: ../../setup/setting-up-site-search.md#search-sharing
+ [Search suggestions]: ../../setup/setting-up-site-search.md#search-suggestions
+ [Section index pages]: ../../setup/setting-up-navigation.md#section-index-pages
+ [Site language selection]: ../../setup/changing-the-language.md#site-language-selector
+ [Social cards]: ../../setup/setting-up-social-cards.md
+ [Sticky navigation tabs]: ../../setup/setting-up-navigation.md#sticky-navigation-tabs
+ [Tags with search integration]: ../../setup/setting-up-tags.md
+ [Tokenizer with lookahead]: search-better-faster-smaller.md#tokenizer-lookahead
+ [Versioning]: ../../setup/setting-up-versioning.md#versioning
+ [Version warning]: ../../setup/setting-up-versioning.md#version-warning
+ [Was this page helpful?]: ../../setup/setting-up-site-analytics.md#was-this-page-helpful
+ [changelog]: ../../changelog/index.md
+
+### Funding
+
+In 2021, monthly funding increased from $1,050 in the beginning of January to
+more than $4,300 (Dec 27, 2021), totaling in a yearly budget of more than
+$50,000. Compared to last year, __revenue from funding has increased by 617%__
+– which is absolutely unbelievable:
+
+![Funding]
+
+ [Funding]: the-past-present-and-future/funding.png
+
+I'm solely providing these numbers to fulfill the transparency pledge I'm giving
+to my awesome sponsors, and to show that it's possible to make existing Open
+Source projects sustainable by following a well-designed release strategy.
+
+You can learn about the strategy in the [Insiders] guide.
+
+## 2022
+
+Standing at the verge of the next year, it's safe to say that the project will
+continue to prosper and evolve, yielding many awesome features that will make
+technical writing more comfortable and flexible. Here's an excerpt of the
+features that will see the light of day in 2022:
+
+- __Instant previews__: [instant previews] will render a specific page section
+ inside a tooltip when hovering an internal link, which will allow to implement
+ things like glossaries. Further support for improving glossary functionality
+ will also be investigated.
+
+- __Text annotations__: as a logical progression of [code annotations] which
+ were added in 2021, authors will be able to add annotations to plain text,
+ yielding excellent opportunities for side content. Of course, text annotations
+ will be as easy to use as code annotations.
+
+- __Navigation pruning__: to optimize large documentation projects, Material
+ for MkDocs will introduce a new feature flag called `navigation.prune` that
+ will lead to significantly smaller HTML files for documentation projects with
+ huge navigation hierarchies.
+
+- __Navigation status badge__: as an addition to the recently added
+ [navigation icon][Navigation icons] support, a status will be attributable to
+ each page, allowing to mark a page in the navigation tree with an icon as
+ :material-alert-decagram: __new__ or :material-trash-can: __deprecated__.
+ Custom status types will also be supported.
+
+- __Card grids__: as a further component in the toolkit of technical writing,
+ [card grids] will allow arranging content in grids, which is especially
+ useful for overview pages. They will allow to arrange arbitrary content,
+ including code blocks, admonitions, etc.
+
+- __Blog support__: blogging support is still [under investigation] and expected
+ to be one of the major additions in 2022. Blogging will perfectly integrate
+ with writing documentation, allowing to use all components available in
+ Material for MkDocs.
+
+This list is incomplete. Additionally, many new smaller features will be added
+next year, just as in 2021. You can follow [@squidfunk on X] to stay
+updated.
+
+__Happy new year!__ :tada:
+
+ [Instant previews]: https://x.com/squidfunk/status/1466794654213492743
+ [card grids]: https://github.com/squidfunk/mkdocs-material/issues/3018
+ [under investigation]: https://github.com/squidfunk/mkdocs-material/issues/3353
+ [@squidfunk on X]: https://x.com/squidfunk
diff --git a/documents/markdown/mkdocs-material/blog_posts_transforming-material-for-mkdocs.md b/documents/markdown/mkdocs-material/blog_posts_transforming-material-for-mkdocs.md
new file mode 100644
index 0000000..d87dd6c
--- /dev/null
+++ b/documents/markdown/mkdocs-material/blog_posts_transforming-material-for-mkdocs.md
@@ -0,0 +1,225 @@
+---
+date: 2024-08-19
+authors:
+ - squidfunk
+ - alexvoss
+ - katharinalisalin
+categories:
+ - General
+description: >
+ We are transforming Material for MkDocs to ensure its community continues to thrive and doubling down on our commitment to Open Source.
+title: How we're transforming Material for MkDocs
+---
+
+# Transforming Material for MkDocs
+
+__We are working on an amazing set of features which has required some behind-the-scenes work we are now ready to share in a series of posts. Here, we give an overview of our goals, features in the making, things that kept us up at night, and our commitment to Open Source.__
+
+We know it's been quite a while since our last update, which is why we're eager to share what's happening in and around Material for MkDocs with you. For the largest part of 2024, we've been focused on transforming the core of Material for MkDocs preparing the ground for new, interconnected features that are amongst the most frequently requested.
+
+This article is part of a series where we'll explore how we aim to support our users through improved information retrieval, provide better support for multi-lingual sites and versioning, as well as improve the overall authoring experience. We outline our vision for the projects' evolution and describe what we have been working on. In this and the coming blog posts, we will share our progress with you, and we're excited to hear your thoughts.
+
+<!-- more -->
+
+_Please note that this post includes several technical details in the footnotes, specifically on challenges. Feel free to skip them if you're not interested in the specifics._
+
+---
+
+__This is the first article in a four-part series:__
+
+1. [Transforming Material for MkDocs]
+2. [Zensical – A modern static site generator built by the creators of Material for MkDocs]
+3. [Material for MkDocs Insiders – Now free for everyone]
+4. [Goodbye, GitHub Discussions]
+
+ [Transforming Material for MkDocs]: transforming-material-for-mkdocs.md
+ [Zensical – A modern static site generator built by the creators of Material for MkDocs]: zensical.md
+ [Material for MkDocs Insiders – Now free for everyone]: insiders-now-free-for-everyone.md
+ [Goodbye, GitHub Discussions]: goodbye-github-discussions.md
+
+## A success story
+
+In 2024, Material for MkDocs has firmly established itself as a leading tool in the documentation framework landscape, with more than 5 million downloads each month as of this writing. What began as @squidfunk's personal project has evolved into a versatile resource for creating comprehensive documentation sites, personal websites, blogs, and notably, for managing knowledge both within and outside of organizations.
+
+With almost [50,000] public GitHub projects depending on Material for MkDocs, it's clear that the framework has made a substantial impact. Tens of thousands of authors rely on us to deliver documentation to millions of users each month.[^1] Beyond its adoption by [many popular Open Source projects], Material for MkDocs is trusted and financially supported by major corporations such as [AWS], [Microsoft], and [Siemens], among many other companies and individuals. We're very grateful for the continued support we receive, which allows us to devote our time to this project, making writing documentation enjoyable.
+
+ [^1]:
+ We've collected invaluable feedback from enterprises and other Open Source maintainers, which revealed that the actual numbers are even higher. Many organizations leverage the framework within private infrastructures, such as self-hosted platforms like GitLab, for internal knowledge management. This suggests that the true reach of Material for MkDocs extends far beyond what is publicly visible.
+
+ [50,000]: https://github.com/squidfunk/mkdocs-material/network/dependents
+ [many popular Open Source projects]: https://github.com/squidfunk/mkdocs-material?tab=readme-ov-file#trusted-by-
+ [AWS]: https://x.com/squidfunk/status/1740389441284579767
+ [Microsoft]: https://x.com/squidfunk/status/1801909506391105840
+ [Siemens]: https://x.com/squidfunk/status/1699799988069646761
+
+Our users particularly appreciate Material for MkDocs for its ease of use and straightforward setup. It simplifies the process by handling the complexities of web technologies for you, so you can build a production-ready static site in minutes without needing to invest years into mastering frontend development or JavaScript. This makes it accessible to a wide range of users, regardless of their technical background. Additionally, Material for MkDocs is MIT-licensed and free to use, which has contributed to its widespread adoption, and allows everybody to build sophisticated documentation sites at no cost.
+
+Our vision is to provide you with the tools that allow you to __own your docs__, enable you to develop your own processes for producing amazing documentation and to avoid being locked into costly subscription services even for doing simple things. We believe it is important that these tools should be easy to set up and configure to suit your needs but should also give you the freedom to adapt them further, if needed. This is why we are always striving to ensure our architectures are modular and future-proof.[^2]
+
+ [^2]:
+ The [built-in plugins] that Material for MkDocs ships perfectly outline this principle, as they are complementary to each other and can be used in combination to build sophisticated pipelines. This modular design allows users to pick and choose the features they need, ensuring that the framework remains lightweight and flexible.
+
+ For instance, the [privacy plugin] can work together with the [optimize plugin] so that external assets can be passed through the same optimization pipeline as the rest of your documentation. This means you can store and edit unoptimized files outside of your repository, and let both plugins automatically build an optimized site for you.
+
+ [built-in plugins]: ../../plugins/index.md
+ [privacy plugin]: ../../plugins/privacy.md
+ [optimize plugin]: ../../plugins/optimize.md
+
+## Challenges
+
+Now, let's talk about our journey and the particular challenges we're addressing. With "we", we're referring to the incredible team that @squidfunk was fortunate to build around his original work, thanks to the financial support he receives from his [sponsors]. This remarkable team includes @alexvoss and @katharinalisalin, whose invaluable contributions in research, development, and community support have been essential to the project's ongoing success.
+
+Together, we've started exploring new technologies, incorporating the feedback we received from our users, and rethinking critical components from first principles, serving our growing community one of the best frameworks to create documentation.
+
+ [sponsors]: https://github.com/sponsors/squidfunk
+
+This section highlights the key areas we've been focusing on.
+
+### Search and discovery
+
+From our perspective, search is a cornerstone of any effective documentation site, enabling users to swiftly locate the information they need. From the start, we've relied on [Lunr.js], a popular client-side search library that has streamlined the deployment of documentation sites without needing an external service. Over the years, Lunr.js has served us well by answering millions of queries on sites built with Material for MkDocs. Yet, as our users' needs evolved, we encountered limitations that proved difficult to overcome.
+
+ [Lunr.js]: https://github.com/olivernn/lunr.js
+
+We learned that the [BM25 ranking algorithm] at the core of Lunr.js (as in many other search implementations) isn't well-suited for effective and stable typeahead. Adding new documents can influence existing rankings, requiring manual adjustments[^3] that are cumbersome and hard to scale. Furthermore, Lunr.js has performance issues that stem from its design not fully leveraging modern JavaScript engines and optimizations, making it slower and memory-intensive.[^4]
+
+ [^3]:
+ Boosting documents in [BM25][BM25 ranking algorithm] can lead to challenges, particularly with a changing corpus of documents. Relevance is calculated based on term frequency and the importance of terms across the entire corpus. Boosting a document involves adjusting its weight to make it more prominent in search results.
+
+ As new documents are added or existing ones are modified, the overall distribution of term frequencies and their importance can shift. This recalibration can diminish the effectiveness of the boost, making it harder to maintain consistent ranking across a changing dataset. Essentially, the boosted documents may not stay as prominent or relevant as intended, leading to imbalances and scalability issues in search results.
+
+ [^4]:
+ Lunr.js uses JavaScript objects to index and manage search data, which introduces inefficiencies due to how JavaScript engines handle object operations. JavaScript engines optimize performance using techniques like inline caching and object shape optimization. However, these optimizations rely on predictable and consistent object structures.
+
+ The dynamic nature of Lunr.js' indexing — where documents can have varying structures — prevents the engine from applying these optimizations effectively. This means that while JavaScript engines can optimize for fixed, predictable object structures, they struggle with the polymorphic and fluid nature of Lunr.js's indexing, leading to performance issues as the amount of data grows.
+
+ [BM25 ranking algorithm]: https://en.wikipedia.org/wiki/Okapi_BM25
+
+Over the last years, we've invested substantially into [improving the search experience]. For instance, expanding Lunr.js' functionality to add support for [rich search previews] and [tokenizer lookahead] demanded substantial engineering effort. Lunr.js allows to customize tasks such as stemming, stopword filtering, and trimming with [pipeline functions], but it makes it particularly hard to add extensions like term highlighting or alternative ranking methods. Compounded by the fact that Lunr.js has been [unmaintained since 2020], it became clear that we needed to find a more powerful solution. We've looked at alternative JavaScript-based libraries to keep our client-side search, but none met our requirements or lived up to our expectations.
+
+ [improving the search experience]: search-better-faster-smaller.md
+ [rich search previews]: search-better-faster-smaller.md#rich-search-previews
+ [tokenizer lookahead]: search-better-faster-smaller.md#tokenizer-lookahead
+ [pipeline functions]: https://lunrjs.com/guides/customising.html#pipeline-functions
+ [unmaintained since 2020]: https://github.com/olivernn/lunr.js/tag/
+
+To address these challenges, we've embarked on developing a new search system from first principles that not only matches but already exceeds the capabilities of Lunr.js. Built from the ground up, this system is faster, more compact, and most importantly: modular. It is based on a growing core evolving around two core concepts we isolated to be essential – engines and plugins – allowing for flexible configuration and assembly of components like text indexing, vector embeddings, filtering, ranking, highlighting, and more. Every part of it can be replaced or extended, enabling users to tailor the search system to their specific needs.
+
+Our new search system, which we will release as a separate MIT-licensed Open Source project, is designed to handle a wide range of scenarios — from small blogs to large documentation projects. Of course, it supports offline use and integrates seamlessly with both client and server environments. The advanced ranking system provides fine-tuned control, and integration with third-party services is now more straightforward.
+
+__:octicons-goal-16: Goal – Empower users to quickly find the information they need while freeing authors from managing external services, by providing a search system that adapts to diverse content types.__
+
+You might wonder why it's not yet available. The process of developing this system from scratch and uncovering its potential has led us to re-evaluate core concepts of Material for MkDocs. As a result, we've decided to postpone the release of the new search system to integrate it into the broader update that we've started to work on. If you keep on reading, you'll learn about further reasons why we've decided to follow this approach.
+
+We're excited to share more details about this update in one of the next posts in this series.
+
+### Translations and versioning
+
+Supporting multi-language sites in MkDocs is the [most requested feature on our discussion board] and in conversations with users, yet it presents significant challenges, as MkDocs does not natively support it. The same applies to versioning, which also involves synchronisation of multi-project builds. While the MkDocs ecosystem has developed [various plugins and tools] to address these issues, there is still substantial untapped potential. We began exploring these areas but quickly encountered problems that hindered our progress.
+
+ [most requested feature on our discussion board]: https://github.com/squidfunk/mkdocs-material/discussions/2346
+ [various plugins and tools]: https://github.com/mkdocs/catalog?tab=readme-ov-file#-site-building-site-management
+
+As you may know, our initial effort involved the [projects plugin] that aims to extend MkDocs to add support for multi-project environments as a solid foundation to support multi-language sites and versioning. Unfortunately, we encountered significant challenges due to MkDocs' internal architecture and design constraints, which we're working actively on resolving.[^5]
+
+ [^5]:
+ When developing the [projects plugin], we initially made [good progress], including adding support for nested projects and allowing for a tree structure where sub-projects can have further sub-projects. However, we quickly encountered difficulties, particularly with cross-project navigation. To illustrate, imagine that each project can link to any other project, which makes handling these interconnections complex, especially when dealing with circular dependencies — such as Project A linking to Project B and vice versa.
+
+ Implementing multi-project support in MkDocs is particularly challenging due to the lack of an official programmatic API, which complicates efforts to extend its functionality. Moreover, resolving navigation issues before building projects is crucial for ensuring proper interconnectivity. These challenges combined made the development of the projects plugin a complex endeavor.
+
+ [projects plugin]: ../../plugins/projects.md
+ [good progress]: https://github.com/squidfunk/mkdocs-material/discussions/5800
+
+__:octicons-goal-16: Goal – Enable scaling documentation to any size or team structure by offering seamless methods for integrating multiple documentation projects, whether they involve different languages, versions, or distinct sections of an overall body of work.__
+
+As a result, we are developing a new approach to offer a more comprehensive and robust solution for both multi-language support and versioning. This new approach also intersects with adjacent functionalities like search, as many of our users are interested in [federated search] capabilities that combine results from multiple documentation sites into a unified search interface. Overcoming this challenge is one of the major hurdles we need to address before releasing the new search system.
+
+ [federated search]: https://github.com/squidfunk/mkdocs-material/issues/5230
+
+### Editing and collaboration
+
+We had considered developing a live editor in response to MkDocs' [performance issues with large projects], which in most cases stem from compute-intensive plugins that don't employ caching. A [proof of concept] based on [Pyodide] (= running Python in the browser) [generated significant interest] among users and prompted many organizations and individuals to share their collaborative workflows for feedback. Sadly, implementing this live editor proved to be very challenging, as it would require rebuilding substantial parts of MkDocs.[^6] After discontinuing work on this approach, our progress with multi-project support has renewed our belief that we can finally solve the sluggish editing experience that was reported several times over the last years.[^7]
+
+ [performance issues with large projects]: https://github.com/mkdocs/mkdocs/issues/3695#issuecomment-2093299518
+ [proof of concept]: https://x.com/squidfunk/status/1338252230265360391
+ [Pyodide]: https://pyodide.org/
+ [generated significant interest]: https://github.com/squidfunk/mkdocs-material/issues/2110
+
+ [^6]:
+ Our [proof of concept] supported some features of Material for MkDocs but didn't cover them all. For instance, integrating support for icons or linking between documents would have necessitated reimplementing parts of MkDocs to bypass a full rebuild — something we obviously wanted to avoid. Additionally, certain links, such as those to blog posts generated from schemas, are not merely translated but computed dynamically, which means they cannot be inferred by replacing the `.md` extension with `.html`.
+
+ [^7]:
+ After [we raised this issue] with the maintainers of MkDocs again[^8], and [maintainership changed] mid 2024, work on a [ground-up rewrite] that aims to address slow reloads by [rendering only the page currently being built] has started. It's still unclear how this rewrite will integrate with the requirements of existing plugins. Complex plugins such as [mkdocstrings], or our [built-in blog] and [tags] plugins require a coordinated build of all pages to accurately resolve links between pages and to computed resources, which cannot be determined without building the entire project.
+
+ __Update__{ title="August 21, 2024" }: The new maintainer now publicly stated that he's working towards a new version of MkDocs that [does not require or support plugins], and mentions it will be equally capable through offering customization via templating, themes, and styling, which he also mentioned to us and several other users in [a team call on August 1]. In this call, [we raised objections multiple times] in regards to how this will impact the ecosystem, to no avail. No intention or roadmap for plugin support was provided. This development is orthogonal to our goal empowering users and organizations to adapt the core framework to their requirements by the means of modularity. We're working on resolving this situation, and will provide a way forward for our community.
+
+ [we raised this issue]: https://github.com/mkdocs/mkdocs/issues/3695
+ [maintainership changed]: https://github.com/mkdocs/mkdocs/discussions/3677
+ [ground-up rewrite]: https://github.com/mkdocs/sketch
+ [rendering only the page currently being built]: https://github.com/mkdocs/mkdocs/issues/3695#issuecomment-2117939743
+ [mkdocstrings]: https://mkdocstrings.github.io/
+ [built-in blog]: ../../plugins/blog.md
+ [tags]: ../../plugins/tags.md
+ [does not require or support plugins]: https://github.com/mkdocs/mkdocs/discussions/3815#discussioncomment-10398312
+ [a team call on August 1]: https://github.com/mkdocs/mkdocs/discussions/3671#discussioncomment-10164237
+ [we raised objections multiple times]: https://github.com/mkdocs/mkdocs/discussions/3671#discussioncomment-10215445
+
+ [^8]:
+ Previously raised issues include [#2418], [#2384], and [#1900].
+
+ [#1900]: https://github.com/mkdocs/mkdocs/issues/1900
+ [#2384]: https://github.com/mkdocs/mkdocs/issues/2384
+ [#2418]: https://github.com/mkdocs/mkdocs/issues/2418
+
+This brings us to collaboration, which wasn't initially on our list of priorities. However, throughout 2024, conversations with various organizations and maintainers of popular Open Source projects highlighted a frequent request for enhanced collaboration features. Many users expressed a need for capabilities that would allow non-technical team members to suggest and make changes to the documentation. We're genuinely grateful for this feedback, as it has come at a pivotal time. We recognize the need to streamline tracking and discussing changes, as well as to facilitate drive-by contributions.
+
+__:octicons-goal-16: Goal – Everyone, regardless of their technical skill level, can easily work on and improve the documentation and contribute to a growing corpus of knowledge.__[^9]
+
+ [^9]:
+ We are actively aligning our future development efforts to address this, recognizing it as a key area for improvement. While it's not something we can deliver immediately, we are committed to making this vision a reality in our work.
+
+This focus on collaboration aligns with how knowledge is managed in enterprises. In large organizations, documentation often exists in [information silos] — decentralized yet essential repositories of information. We understand the need to be able to unify these disparate sources into a coherent body of knowledge while preserving decentralized ownership. This also nicely aligns with our previously outlined work on multi-project support, as well as the new search system to implement [federated search] among multiple projects.
+
+ [information silos]: https://en.wikipedia.org/wiki/Information_silo
+
+### Large Language Models (LLMs)
+
+Almost a year ago, we introduced an [experimental chatbot] on our documentation site. It quickly became one of the most anticipated features, with users requesting the ability to deploy similar functionality on their own sites, underscoring the growing demand for interactive documentation tools. However, we found that adding to the myriad of existing chat solutions and simply building another thin wrapper on top of ChatGPT is nonsense.
+
+__:octicons-goal-16: Goal – We're envisioning creating a unified interface that seamlessly integrates advanced search, chat, and summarization features, providing an interactive documentation experience.__
+
+ [experimental chatbot]: https://github.com/squidfunk/mkdocs-material/discussions/6240
+
+As we delved into this ambitious project, we gained valuable insights from user feedback. Users began interacting with the chatbot in their native languages, an outcome we hadn't anticipated given that our documentation is in English. Remarkably (or obviously to those that work on LLMs year round), the chatbot responded in the same language. This ability of LLMs is one of the genuinely exciting features of these machine learning models as it has the potential to improve the accessibility of the documentation. However, while we employed state-of-the-art RAG methodologies, the results were mixed, and occasional hallucinations surfaced.
+
+These experiences led us to prioritize enhancing our search capabilities before integrating LLM-based features. Building a search engine from scratch was already a substantial effort, and adding more complexity without a solid search foundation would be premature. By rearchitecting our search functionalities, we aim to create a robust platform that will seamlessly support advanced information retrieval and deliver a cohesive interactive documentation experience.
+
+## Team, transparency, and growth
+
+While we navigate the challenges and explore the opportunities of this project, we consider it essential to demonstrate how we're building a solid foundation for its continued growth and success. Please consider this an overview rather than a formal roadmap — our detailed plans are in the works. The goals we've highlighted represent the most impactful areas we aim to address.
+
+Thanks to the generous support from our sponsors, we're fortunate to be assembling a team capable of dedicating significant time and expertise to this endeavor. This newfound capacity allows us to delve deeper into core development while also engaging more comprehensively with our user community. A special mention goes to @kamilkrzyskow, one of our invaluable community experts, who has been essential in supporting users and fostering discussions on our platform.
+
+With the team's support, @squidfunk can concentrate on the heart of development, while we have begun investing in user research. This effort is helping us understand how organizations and individuals interact with our tools, guiding the project's future direction based on real feedback from numerous conversations with users and companies.
+
+Looking to expand our team further, we are committed to improving transparency and communication. Our previous work often happened behind the scenes due to time constraints, but we're now focused on making our processes more open and inviting for new contributors. By embracing this collaborative approach, we aim to enhance our tools and ensure they meet the evolving needs of our community.
+
+## What's ahead of us
+
+As we look into the future, some of the groundwork we're laying now is crucial for the exciting developments on the horizon. Many of the initiatives we've discussed represent foundational work that will set the stage for much more ambitious and innovative features. Once these core elements are in place, we'll deliver a range of exciting new functionalities that align with our vision and goals.
+
+In the coming months, we'll be sharing more details about our plans and how they will contribute to our overarching objectives. While growth and innovation are at the forefront of our plans, we want to assure you that our core values remain unchanged. We are committed to maintaining the principles that have guided us thus far, ensuring that our growth is both healthy and consistent:
+
+- Against recent industry trends with companies moving away from core ideas of Open Source, we are doubling down on our commitment to Open Source because we believe it's at the heart of the value proposition of our work and the [docs as code] approach.
+
+ [docs as code]: https://www.writethedocs.org/guide/docs-as-code/
+
+- Our [organic approach to growth] is part of this strategy as it keeps us independent of individual funding sources and pressures to provide a return on investment, which is what causes many other projects to turn away from the principles of Open Source.
+
+ [organic approach to growth]: https://star-history.com/#squidfunk/mkdocs-material
+
+- Likewise, we are driven by the needs of the community for a rich ecosystem of adaptations of the core framework. Extensibility and modularity are key for this and we are working hard to improve the developer experience by providing clear interfaces.
+
+Stay tuned for updates as we continue to build on our progress and explore new possibilities. We're excited about the future and look forward to sharing more with you as we advance.
+
+_Martin, Alex and Kathi_ :octicons-heart-fill-24:{ .mdx-heart .mdx-insiders }
diff --git a/documents/markdown/mkdocs-material/blog_posts_zensical.md b/documents/markdown/mkdocs-material/blog_posts_zensical.md
new file mode 100644
index 0000000..c591a45
--- /dev/null
+++ b/documents/markdown/mkdocs-material/blog_posts_zensical.md
@@ -0,0 +1,236 @@
+---
+date: 2025-11-05
+authors:
+ - squidfunk
+ - alexvoss
+ - katharinalisalin
+ - pawamoy
+categories:
+ - General
+description: >
+ We are thrilled to announce Zensical, our next-gen static site generator
+ that addresses and overcomes the technical limitations of MkDocs
+social:
+ cards_layout: default/only/image
+ cards_layout_options:
+ background_image: docs/assets/images/zensical-social.png
+title: Zensical - A modern static site generator
+slug: zensical
+---
+
+# Zensical – A modern static site generator built by the Material for MkDocs team
+
+__We are thrilled to announce [Zensical], our next-gen static site generator designed to simplify the process of building documentation sites. Distilled from a decade of experience, Zensical is our effort to overcome the technical limitations of MkDocs, reaching far beyond its capabilities.__
+
+Zensical is the result of thousands of hours of work – built from the ground up for a modern and comfortable authoring experience, while making it easy for developers to extend and customize Zensical through its upcoming module system. Our goal is to support docs-as-code workflows with tens of thousands of pages, without compromising performance or usability.
+
+To make the transition seamless, [compatibility] comes first. We're putting significant effort into ensuring a smooth migration from Material for MkDocs for all users. Zensical can natively read `mkdocs.yml`, allowing you to build your existing project with minimal changes. As of now, a subset of plugins is supported, and we're working on feature parity in the coming months.
+
+Zensical is fully Open Source, licensed under MIT, and can be used for any purpose, including for commercial use. We're also saying goodbye to our sponsorware model, replacing it with our new offering for professional users: [Zensical Spark]. This allows us to stay independent, maximizing user value, as we shape the future of Zensical together with you.
+
+_You can subscribe to [our newsletter] to stay in the loop_.
+
+<!-- more -->
+
+ [Zensical]: https://zensical.org/
+ [compatibility]: #maximum-compatibility
+ [Zensical Spark]: #zensical-spark
+ [our newsletter]: https://zensical.org/about/newsletter/
+
+---
+
+__This is the second article in a four-part series:__
+
+1. [Transforming Material for MkDocs]
+2. [Zensical – A modern static site generator built by the creators of Material for MkDocs]
+3. [Material for MkDocs Insiders – Now free for everyone]
+4. [Goodbye, GitHub Discussions]
+
+ [Transforming Material for MkDocs]: transforming-material-for-mkdocs.md
+ [Zensical – A modern static site generator built by the creators of Material for MkDocs]: zensical.md
+ [Material for MkDocs Insiders – Now free for everyone]: insiders-now-free-for-everyone.md
+ [Goodbye, GitHub Discussions]: goodbye-github-discussions.md
+
+## Why Zensical?
+
+Since its initial release in 2016, Material for MkDocs has helped tens of thousands of teams to publish and maintain reliable documentation. However, in recent years, it has become apparent that we were running up against limitations of our core dependency, MkDocs. These limitations proved impossible to overcome as they are deeply rooted in its architecture.
+
+We also mentioned in our [update on our foundational work] that MkDocs must be considered a supply chain risk, since it's unmaintained since August 2024. It has seen no releases in over a year and is accumulating unresolved issues and pull requests. These developments have forced us to cut our ties to MkDocs as a dependency.
+
+In order to map out a path forward, we went back to the drawing board, talked to dozens of our professional users and thoroughly analyzed the MkDocs ecosystem. We didn't just want to create a fork or port of MkDocs, but decided to rethink static site generation from first principles.
+
+With Zensical, we are creating a modern static site generator, which is compatible with your content and customizations, and addresses MkDocs' limitations. While Material for MkDocs is built on top of MkDocs, __Zensical consolidates both projects into one coherent stack__, covering static site generation, theming, and customization. What you can expect today:
+
+- [5x faster rebuilds](#authoring-experience)
+- [Modern design](#modern-design)
+- [Blazing-fast search](#blazing-fast-search)
+
+Although we haven't reached full feature parity yet, you can already use Zensical to build your existing Material for MkDocs projects with minimal changes.
+
+_You can jump to the [compatibility] section to learn what is already supported._
+
+ [update on our foundational work]: https://github.com/squidfunk/mkdocs-material/discussions/8461
+
+## What you can expect
+
+### Solid foundation
+
+Our goal with Zensical is to create a coherent and modern stack, vertically integrating all parts of the authoring experience (AX), developer experience (DX), and user experience (UX). This gives us a significant competitive advantage over solutions that overly rely on third-party frameworks and dependencies, helping us to create much more robust Open Source software.
+
+[ZRX], our new differential build engine, creates a solid foundation for Zensical, and is an Open Source project of its own. It's a fresh take on making differential data flows easy to build and a joy to work with. Most engineering effort has gone into ZRX, as it forms the backbone of Zensical, and will allow us to ship features faster.
+
+Following the principle of architectural hoisting, we moved essential, reusable functionality into ZRX, which allows us to keep Zensical's core simple and focused on static site generation. ZRX handles the heavy lifting – differential builds, caching, and data flow orchestration.
+
+With the upcoming [module system] and [component system], both of which are on our public [roadmap], Zensical will gain more degrees of freedom in the coming months, allowing you to extend and customize Zensical in ways that were previously impossible with MkDocs.
+
+ [ZRX]: https://github.com/zensical/zrx/
+ [module system]: https://zensical.org/about/roadmap/#module-system
+ [component system]: https://zensical.org/about/roadmap/#component-system
+
+### Modern design
+
+Zensical brings a fresh, modern design that breaks out of the Materal Design aesthetic, creating a visual foundation that is more easily brandable and adaptable to different use cases. The new design prioritizes clarity, simplicity, and usability, while having a more professional finish:
+
+<figure markdown>
+
+
+
+
+
+ <figcaption markdown>Our public [roadmap], built with Zensical</figcaption>
+</figure>
+
+Right now, the layout and site structure of Zensical match Material for MkDocs closely, as we're focusing on ensuring maximum compatibility. Once we finish work on our upcoming [component system], we'll provide an alternative that is much more flexible and adaptable, and can be tailored to different use cases and branding requirements more easily.
+
+_You can also keep the Material for MkDocs look and feel with a single line of configuration._
+
+ [roadmap]: https://zensical.org/about/roadmap/
+
+### Blazing-fast search
+
+Client-side search isn't a compromise – for the vast majority of static sites, it's the best solution, since it's faster, involves zero maintenance, and doesn't require you to pay for a service.
+
+As covered in depth in [the first part of this series], the current search implementation in Material for MkDocs has severe limitations, and is based on a now unmaintained library, which is why we decided to build a new search engine from scratch. It's based on the same goals as Zensical itself: performance, flexibility, and extensibility.
+
+Disco, our modular and blazing-fast client-side search engine, is exclusively available in Zensical. When you build your site with Zensical, your users will immediately benefit from Disco's improved ranking algorithm, as well as its filtering and aggregation capabilities:
+
+ [the first part of this series]: transforming-material-for-mkdocs.md#search-and-discovery
+
+<figure markdown>
+
+
+
+
+ <figcaption markdown>Disco on [zensical.org]</figcaption>
+</figure>
+
+In early 2026, we'll be releasing Disco as a standalone Open Source project. With the feedback of our professional users in [Zensical Spark], we're going to evolve the search experience, turning Disco into a highly configurable and customizable search engine that adapts to your needs.
+
+_You can subscribe to [our newsletter] to receive news about Disco_.
+
+ [zensical.org]: https://zensical.org/
+
+### Authoring experience
+
+Slow feedback loops can be a major pain point when writing documentation. Almost all of us know the feeling of waiting for the static site generator to finish building the site, just to see a small change reflected in the output. With Zensical, we're finally addressing this issue.
+
+It's important to understand that we're not yet utilizing the differential capabilities of [ZRX] to the fullest extent, as we're forced to make several compromises to ensure maximum [compatibility] with Material for MkDocs at the moment. Markdown rendering needs to go through Python Markdown, which forces us to pay for extra marshalling costs.
+
+While the initial build can sometimes be slower than with MkDocs, repeated builds – especially when serving the site – are already 4 to 5x faster, as only changed files need to be rebuilt.
+
+We're also working on a new Markdown toolchain based on a CommonMark-compliant parser written in Rust, which will make Markdown processing significantly faster. We'll be tackling this as part of the upcoming [component system], which we'll start working on in early 2026. Once our new Markdown toolchain is ready, we'll provide automated tools to translate between Python Markdown and CommonMark, so you don't need to manually migrate your content.
+
+### Maximum compatibility
+
+[Compatibility with Material for MkDocs] is our top priority. We understand that switching to a new static site generator can be challenging, especially for large projects with many customizations. Therefore, we've put significant effort into ensuring that Zensical understands `mkdocs.yml` configuration files, so that you can build your projects with minimal changes.
+
+This means your existing Markdown files, template overrides, CSS and JavaScript extensions don't need to be touched, primarily because we did not change the generated HTML, and rely on Python Markdown for processing your content.
+
+However, plugins are a different story. In MkDocs, practically all plugins have side effects, making it impossible to parallelize builds. We started from first principles and asked: what should extensibility look like in a modern static site generator?
+Our answer is the upcoming [module system], which takes a fundamentally different approach based on four core principles:
+
+- Modules can inject, extend, and re-define functionality
+- Modules are deterministic through topological ordering
+- Modules foster reusability, with the possibility to remix them
+- Modules can cooperate through well-defined contracts
+
+We're working on shipping essential functionality as provided by MkDocs plugins as built-in modules. In early 2026, we will open the module system to third-party developers, so they can start building their own modules, as we see Zensical as the heart of a thriving ecosystem.
+
+ [Compatibility with Material for MkDocs]: https://zensical.org/compatibility/
+ [feature parity]: https://zensical.org/compatibility/features/
+ [search]: ../../plugins/search.md
+ [offline]: ../../plugins/offline.md
+
+## Zensical Spark
+
+Zensical Spark, [our offering for professionals], is the result of countless calls with professional users of Material for MkDocs. From startups to large enterprises, we enable organizations to realize complex projects in diverse environments. For this, we've created Zensical Spark as a collaborative space. If you're a professional user, Zensical Spark is for you, since:
+
+- You can be confident that Zensical will continue to be developed and maintained in the long term as a set of interconnected and sustainable OSI-compliant Open Source projects.
+
+- You can receive the support you need to successfully use, configure and customize Zensical in your organization, receiving first-class support from the Zensical team.
+
+- You can influence the future development of Zensical by participating in [our new approach] to Open Source software development, helping us to build exactly what you need.
+
+_Let's talk! If you're working in a professional context, reach out to hello@zensical.org to schedule a call and learn how Zensical Spark enables your team to transition to Zensical smoothly and have a voice in its continued development._
+
+_You should also consider joining the [waiting list], since seats are limited._
+
+ [our offering for professionals]: https://zensical.org/spark/
+ [our new approach]: https://zensical.org/docs/community/how-we-work/
+ [waiting list]: https://zensical.org/spark/join/
+
+## We're growing our team
+
+We're also excited to announce that we're growing [our team]:
+
+__Timothée Mazzucotelli, also known as @pawamoy, is joining Zensical!__
+
+At Zensical, Tim is focusing on providing the same seamless experience for generating API reference documentation from source code (via docstrings) as he has done with [mkdocstrings], the second biggest project in the MkDocs ecosystem. With his expertise, and Zensical's new stack, we'll be pushing the boundaries of what's possible with API reference documentation.
+
+ [mkdocstrings]: https://mkdocstrings.github.io/
+ [our team]: https://zensical.org/about/team/
+
+## Goodbye, GitHub Sponsors
+
+Thank you! To all of you who have supported us over the years through GitHub Sponsors – we are incredibly grateful for your support. It has been invaluable in helping us to build, maintain and evolve Material for MkDocs, and we couldn't have done it without you. __Seriously, thank you!__
+
+Material for MkDocs gave us something invaluable: experience building for tens of thousands of users, and the opportunity to build a team around Open Source software. It showed us that making a living from Open Source isn't just possible – we grew it into one of the largest sponsorware projects on GitHub and inspired others to pursue similar paths.
+
+Now we're breaking new ground. Zensical is our next chapter, and we're professionalizing how we approach Open Source development. Our vision is to make Zensical free for everyone to use while building a sustainable business around it through [our new approach].
+
+This transition means saying goodbye to GitHub Sponsors. It has served us exceptionally well, but as we professionalize and scale, we're making the leap from personal project to company – building a business and team that can meet the growing demands of professional users while staying true to our values.
+
+We're doubling down on Open Source, developing software for everyone.
+
+_If you want to continue supporting our work, please subscribe to [our newsletter]. We'll be providing new methods to support us in the coming months, with the possibility of getting exclusive goodies._
+
+## Looking Ahead
+
+Material for MkDocs grew organically in a pot that eventually became too small. With Zensical, we're building on solid foundations designed to grow with us – and with you.
+
+!!! warning "Material for MkDocs is now in maintenance mode"
+
+ We want to be transparent about the risks of staying on Material for MkDocs. With MkDocs unmaintained and facing fundamental supply chain concerns, we cannot guarantee Material for MkDocs will continue working reliably in the future. We're aware that transitioning takes time, which is why we commit to support it at least for the next 12 months, fixing critical bugs and security vulnerabilities as needed, but the path forward is with Zensical.
+
+ If documentation plays a critical role in your organization, and you're worried how this might affect your business, consider joining [Zensical Spark](https://zensical.org/spark/), or feel free to schedule a call by reaching out at hello@zensical.org.
+
+### Where we'll be in 12 months
+
+Over the next 12 months, following our [phased transition strategy], we'll reach Phase 2 and 3 – introducing our [module system] and [component system], as well as CommonMark support. By replacing Python Markdown with a Rust-based Markdown parser, we'll unlock performance improvements and the modularity needed for flexible templating. This is where Zensical truly starts to unfold its capabilities.
+
+Zensical is already powering real projects due to extensive [compatibility with Material for MkDocs][Compatibility with Material for MkDocs]. We're actively working on closing the gap to reach full [feature parity].
+
+You can [install Zensical now], and build your existing Material for MkDocs projects with it. If you run into a bug, please don't hesitate to [open an issue] – we're here to help.
+
+### Connect with us
+
+If you have questions we haven't addressed, please reach out to us at hello@zensical.org. We're currently collecting questions from the community about Zensical, and will address them in an FAQ section as part of our documentation in the coming weeks.
+
+We're incredibly thankful that you have been part of our journey so far. With Zensical, we're embarking on a new chapter, and we couldn't be more excited to have you with us.
+
+_You can subscribe to [our newsletter] to stay in the loop_.
+
+ [phased transition strategy]: https://zensical.org/compatibility/#phased-transition-strategy
+ [install Zensical now]: https://zensical.org/docs/get-started/
+ [GitHub repository]: https://github.com/zensical/zensical
+ [open an issue]: https://zensical.org/docs/community/get-involved/
diff --git a/documents/markdown/mkdocs-material/browser-support.md b/documents/markdown/mkdocs-material/browser-support.md
new file mode 100644
index 0000000..7cf4f5a
--- /dev/null
+++ b/documents/markdown/mkdocs-material/browser-support.md
@@ -0,0 +1,67 @@
+# Browser support
+
+Material for MkDocs goes at great lengths to support the largest possible range
+of browsers while retaining the simplest possibilities for customization via
+modern CSS features like [custom properties] and [mask images].
+
+ [custom properties]: https://caniuse.com/css-variables
+ [mask images]: https://caniuse.com/mdn-css_properties_mask-image
+
+## Supported browsers
+
+The following table lists all browsers for which Material for MkDocs offers full
+support, so it can be assumed that all features work without degradation. If you
+find that something doesn't look right in a browser which is in the supported
+version range, please [open an issue]:
+
+<figure markdown>
+
+| Browser | Version | Release date | | | Usage |
+| ------------------------------------ | ------: | -----------: | ------: | -----: | ---------: |
+| | | | desktop | mobile | overall |
+| :fontawesome-brands-chrome: Chrome | 49+ | 03/2016 | 25.65% | 38.33% | 63.98% |
+| :fontawesome-brands-safari: Safari | 10+ | 09/2016 | 4.63% | 14.96% | 19.59% |
+| :fontawesome-brands-edge: Edge | 79+ | 01/2020 | 3.95% | n/a | 3.95% |
+| :fontawesome-brands-firefox: Firefox | 53+ | 04/2017 | 3.40% | .30% | 3.70% |
+| :fontawesome-brands-opera: Opera | 36+ | 03/2016 | 1.44% | .01% | 1.45% |
+| | | | | | __92.67%__ |
+
+ <figcaption markdown>
+
+Browser support matrix sourced from [caniuse.com].[^1]
+
+ </figcaption>
+</figure>
+
+ [^1]:
+ The data was collected from [caniuse.com] in January 2022, and is primarily
+ based on browser support for [custom properties], [mask images] and the
+ [:is pseudo selector] which are not entirely polyfillable. Browsers with a
+ cumulated market share of less than 1% were not considered, but might still
+ be fully or partially supported.
+
+Note that the usage data is based on global browser market share, so it could
+in fact be entirely different for your target demographic. It's a good idea to
+check the distribution of browser types and versions among your users.
+
+ [open an issue]: https://github.com/squidfunk/mkdocs-material/issues/new/choose
+ [caniuse.com]: https://caniuse.com/
+ [:is pseudo selector]: https://caniuse.com/css-matches-pseudo
+ [browser support]: #supported-browsers
+ [built-in privacy plugin]: plugins/privacy.md
+
+## Other browsers
+
+Albeit your site might not look as perfect as when viewed with a modern browser,
+the following older browser versions might work with some additional effort:
+
+- :fontawesome-brands-firefox: __Firefox 31-52__ – icons will render as little
+ boxes due to missing support for [mask images]. While this cannot be
+ polyfilled, it might be mitigated by hiding the icons altogether.
+- :fontawesome-brands-edge: __Edge 16-18__ – the spacing of some elements might
+ be a little off due to missing support for the [:is pseudo selector], which
+ can be mitigated with some additional effort.
+- :fontawesome-brands-internet-explorer: __Internet Explorer__ - no support,
+ mainly due to missing support for [custom properties]. The last version of
+ Material for MkDocs to support Internet Explorer is
+ <!-- md:version 4.6.3 -->.
diff --git a/documents/markdown/mkdocs-material/changelog_index.md b/documents/markdown/mkdocs-material/changelog_index.md
new file mode 100644
index 0000000..b6b5911
--- /dev/null
+++ b/documents/markdown/mkdocs-material/changelog_index.md
@@ -0,0 +1,2705 @@
+# Changelog
+
+## Material for MkDocs
+
+### 9.7.6 <small>March 19, 2026</small> { id="9.7.6" }
+
+- Automatically disable MkDocs 2.0 warning for forks of MkDocs
+
+### 9.7.5 <small>March 10, 2026</small> { id="9.7.5" }
+
+- Limited version range of mkdocs to <2
+- Updated MkDocs 2.0 incompatibility warning (clarify relation with MkDocs)
+
+### 9.7.4 <small>March 3, 2026</small> { id="9.7.4" }
+
+- Hardened social cards plugin by switching to sandboxed environment
+- Updated MkDocs 2.0 incompatibility warning
+
+### 9.7.3 <small>February 24, 2026</small> { id="9.7.3" }
+
+- Fixed #8567: Print MkDocs 2.0 incompatibility warning to stderr
+
+### 9.7.2 <small>February 18, 2026</small> { id="9.7.2" }
+
+- Opened up version ranges of optional dependencies for forward-compatibility
+- Added warning to `mkdocs build` about impeding MkDocs 2.0 incompatibility
+
+### 9.7.1 <small>December 18, 2025</small> { id="9.7.1" }
+
+- Updated requests to 2.30+ to mitigate CVE in urllib
+- Fixed privacy plugin not picking up protocol-relative URLs
+- Fixed #8542: false positives and negatives captured in privacy plugin
+
+### 9.7.0 <small>November 11, 2025</small> { id="9.7.0" }
+
+!!! warning "Material for MkDocs is now in maintenance mode"
+
+ This is the last release of Material for MkDocs that will receive new features.
+ Going forward, the Material for MkDocs team focuses on [Zensical], a next-gen
+ static site generator built from first principles. We will provide critical
+ bug fixes and security updates for Material for MkDocs for 12 months at least.
+
+ [Read the full announcement on our blog]
+
+This release includes all features that were previously exclusive to the
+Insiders edition. These features are now freely available to everyone.
+
+__Note on deprecated plugins__: The [projects] and [typeset] plugins are
+included in this release, but must be considered deprecated. Both plugins
+proved unsustainable to maintain and represent architectural dead ends. They
+are provided as-is without ongoing support.
+
+__Changes__:
+
+- Added support for projects plugin (for compat, now deprecated)
+- Added support for typeset plugin (for compat, now deprecated)
+- Added support for pinned blog posts and author profiles
+- Added support for customizing pagination for blog index pages
+- Added support for customizing blog category sort order
+- Added support for staying on page when switching languages
+- Added support for disabling tags in table of contents
+- Added support for nested tags and shadow tags
+- Added support for footnote tooltips
+- Added support for instant previews
+- Added support for instant prefetching
+- Added support for custom social card layouts
+- Added support for custom social card background images
+- Added support for selectable rangs in code blocks
+- Added support for custom selectors for code annotations
+- Added support for configurable log level in privacy plugin
+- Added support for processing of external links in privacy plugin
+- Added support for automatic image optimization via optimize plugin
+- Added support for navigation paths (breadcrumbs)
+- Fixed #8519: Vector accents do not render when using KaTeX
+
+ [Zensical]: https://zensical.org
+ [Read the full announcement on our blog]: ../blog/posts/zensical.md
+ [projects]: ../plugins/projects.md
+ [typeset]: ../plugins/typeset.md
+
+### 9.6.23 <small>November 1, 2025</small> { id="9.6.23" }
+
+- Updated Burmese translation
+
+### 9.6.22 <small>October 15, 2025</small> { id="9.6.22" }
+
+- Updated Georgian translation
+
+### 9.6.21 <small>September 30, 2025</small> { id="9.6.21" }
+
+- Updated Serbian translations
+- Fixed #8458: Temporary pin of click dependency
+
+### 9.6.20 <small>September 15, 2025</small> { id="9.6.20" }
+
+- Fixed #8446: Deprecation warning as of Python 3.14 in Emoji extension
+- Fixed #8440: `&` character not escaped in search highlighting
+- Fixed #8439: FontAwesome icons color not set in social cards (regression)
+
+### 9.6.19 <small>September 7, 2025</small> { id="9.6.19" }
+
+- Added support for Python 3.14
+- Updated Bahasa Malaysia translations
+
+### 9.6.18 <small>August 22, 2025</small> { id="9.6.18" }
+
+- Updated Azerbaijani translations
+- Fixed last compat issues with [minijinja], now 100% compatible
+
+### 9.6.17 <small>August 15, 2025</small> { id="9.6.17" }
+
+- Fixed #8396: Videos do not autoplay when inside a content tab
+- Fixed #8394: Stroke width not effective in Mermaid.js diagrams
+- Fixed disappearing version selector when hiding page title
+
+### 9.6.16 <small>July 26, 2025</small> { id="9.6.16" }
+
+- Fixed #8349: Info plugin doesn't correctly detect virtualenv in some cases
+- Fixed #8334: Find-in-page detects matches in hidden search result list
+
+### 9.6.15 <small>July 1, 2025</small> { id="9.6.15" }
+
+- Updated Mongolian translations
+- Improved semantic markup of "edit this page" button
+- Improved info plugin virtual environment resolution
+- Fixed #8291: Large font size setting throws of breakpoints in JavaScript
+
+### 9.6.14 <small>May 13, 2025</small> { id="9.6.14" }
+
+- Fixed #8215: Social plugin crashes when CairoSVG is updated to 2.8
+
+### 9.6.13 <small>May 10, 2025</small> { id="9.6.13" }
+
+- Fixed #8204: Annotations showing list markers in print view
+- Fixed #8153: Improve style of cardinality symbols in Mermaid.js ER diagrams
+
+### 9.6.12 <small>April 17, 2025</small> { id="9.6.12" }
+
+- Fixed #8158: Flip footnote back reference icon for right-to-left languages
+
+### 9.6.11 <small>April 1, 2025</small> { id="9.6.11" }
+
+- Updated Docker image to latest Alpine Linux
+- Bump required Jinja version to 3.1
+- Fixed #8133: Jinja filter `items` not available (9.6.10 regression)
+- Fixed #8128: Search plugin not entirely disabled via enabled setting
+
+### 9.6.10 <small>March 30, 2025</small> { id="9.6.10" }
+
+This version is a pure refactoring release, and does not contain new features
+or bug fixes. It strives to improve the compatibility of our templates with
+alternative Jinja-like template engines that we're currently exploring,
+including [minijinja].
+
+Additionally, it replaces several instances of Python function invocations
+with idiomatic use of template filters. All instances where variables have
+been mutated inside templates have been replaced. Most changes have been made
+in partials, and only a few in blocks, and all of them are fully backward
+compatible, so no changes to overrides are necessary.
+
+Note that this release does not replace the Jinja template engine with
+minijinja. However, our templates are now 99% compatible with minijinja,
+which means we can explore alternative Jinja-compatible implementations.
+Additionally, immutability and removal of almost all Python function
+invocations means much more idiomatic templating.
+
+ [minijinja]: https://github.com/mitsuhiko/minijinja
+
+### 9.6.9 <small>March 17, 2025</small> { id="9.6.9" }
+
+- Updated Serbo-Croatian translations
+- Fixed #8086: Custom SVG icons containing hashes break rendering
+- Fixed #8067: Drawer has gap on right side in Firefox on some OSs
+
+### 9.6.8 <small>March 13, 2025</small> { id="9.6.8" }
+
+- Added Welsh translations
+- Fixed #8076: Privacy plugin crashes if HTTP download fails
+
+### 9.6.7 <small>March 3, 2025</small> { id="9.6.7" }
+
+- Fixed #8056: Error in backrefs implementation (9.6.6 regression)
+- Fixed #8054: Unescaped quotes in ARIA labels of table of contents
+
+### 9.6.6 <small>March 1, 2025</small> { id="9.6.6" }
+
+- Fixed #8040: Privacy plugin not replacing exteral assets (9.6.5 regression)
+- Fixed #8031: Replace unmaintained `regex` package in search plugin
+
+### 9.6.5 <small>February 20, 2025</small> { id="9.6.5" }
+
+- Fixed #8016: Tags listing not showing when when file name has spaces
+- Fixed #8012: Privacy plugin crashes if HTTP download fails
+
+### 9.6.4 <small>February 12, 2025</small> { id="9.6.4" }
+
+- Fixed #7985: Blog content sometimes not stretching to full width
+- Fixed #7978: Navigation rendering bug in Safari 18.3
+
+### 9.6.3 <small>February 7, 2025</small> { id="9.6.3" }
+
+- Fixed rendering of arrow heads in Mermaid.js class diagrams
+- Fixed #7960: Tags plugin crashes on numeric metadata titles
+
+### 9.6.2 <small>February 3, 2025</small> { id="9.6.2" }
+
+- Fixed #7955: Excessively long words don't break on narrow screens
+- Fixed #7947: Scope setting interferes with outdated version banner
+
+### 9.6.1 <small>January 31, 2025</small> { id="9.6.1" }
+
+- Fixed #7943: Tags plugin crashing due to merge error
+
+### 9.6.0 <small>January 31, 2025</small> { id="9.6.0" }
+
+- Added meta plugin
+- Rewrite of the tags plugin
+- Added support for allow lists in tags plugin
+- Added support for and custom sorting in tags plugin
+- Added support for related links in blog plugin
+- Added support for custom index pages in blog plugin
+- Added support for navigation subtitles
+- Fixed #7924: Anchors might require two clicks when using instant navigation
+
+### 9.5.50 <small>January 18, 2025</small> { id="9.5.50" }
+
+- Fixed #7913: Social plugin renders attribute lists in page title
+
+### 9.5.49 <small>December 16, 2024</small> { id="9.5.49" }
+
+- Adjusted title color in dark mode for all supported Mermaid.js diagrams
+- Fixed #7803: Privacy plugin crashes on generated files
+- Fixed #7781: Mermaid.js flow chart title not visible in dark mode
+
+### 9.5.48 <small>December 8, 2024</small> { id="9.5.48" }
+
+- Fixed #7774: Disabling social cards doesn't work
+
+### 9.5.47 <small>December 1, 2024</small> { id="9.5.47" }
+
+- Fixed #7750: Numeric tags break search
+- Fixed #7748: Blog plugin breaks when using future drafts (9.5.45 regression)
+
+### 9.5.46 <small>November 25, 2024</small> { id="9.5.46" }
+
+- Added support for removing `preload` hints in privacy plugin
+- Fixed #7734: Code blocks in h5 headlines are uppercased
+- Fixed #7725: Blog plugin crashing on missing timezone (9.5.45 regression)
+
+### 9.5.45 <small>November 20, 2024</small> { id="9.5.45" }
+
+- Reduced size of Docker image through multi-stage build
+- Fixed #7708: Blog plugin crashing on YAML dates with timezones
+
+### 9.5.44 <small>November 5, 2024</small> { id="9.5.44" }
+
+- Fixed #7672: Font CSS 404's when using privacy plugin (9.5.43 regression)
+
+### 9.5.43 <small>October 31, 2024</small> { id="9.5.43" }
+
+- Added support for external images in SVGs in privacy plugin
+- Fixed #7651: Privacy plugin doesn't handle quoted URLs in CSS
+
+### 9.5.42 <small>October 20, 2024</small> { id="9.5.42" }
+
+- Fixed #7625: Invalid encoding of boolean attributes in privacy plugin
+- Fixed #7624: Crash when disabling privacy plugin (9.5.41 regression)
+
+### 9.5.41 <small>October 15, 2024</small> { id="9.5.41" }
+
+- Fixed #7619: Improved tooltip on logo disappears after instant navigation
+- Fixed #7616: Race condition in built-in privacy plugin when inlining assets
+- Fixed #7615: Comments and "Was this page helpful?" visible when printing
+
+### 9.5.40 <small>October 10, 2024</small> { id="9.5.40" }
+
+- Updated Latvian translations
+- Fixed #7597: Social cards not using site name on home page
+
+### 9.5.39 <small>September 29, 2024</small> { id="9.5.39" }
+
+- Fixed #7226: not staying on page when using mike's canonical versioning
+
+### 9.5.38 <small>September 26, 2024</small> { id="9.5.38" }
+
+- Added Albanian translations
+
+### 9.5.37 <small>September 25, 2024</small> { id="9.5.37" }
+
+- Added 4th and 5th level ordered list styles
+- Fixed #7548: Tags have no spacing in search
+
+### 9.5.36 <small>September 21, 2024</small> { id="9.5.36" }
+
+- Fixed #7544: Social cards incorrectly rendering HTML entities
+- Fixed #7542: Improved support for setting custom list styles
+
+### 9.5.35 <small>September 18, 2024</small> { id="9.5.35" }
+
+- Fixed #7498: Search not showing for Vietnamese language
+
+### 9.5.34 <small>August 31, 2024</small> { id="9.5.34" }
+
+- Updated Mermaid.js to version 11 (latest)
+
+### 9.5.33 <small>August 23, 2024</small> { id="9.5.33" }
+
+- Fixed #7453: Incorrect position of tooltip when sorting table
+
+### 9.5.32 <small>August 19, 2024</small> { id="9.5.32" }
+
+- Fixed RXSS vulnerability via deep link in search results
+- Added support for fetching latest release from GitLab
+
+### 9.5.31 <small>August 2, 2024</small> { id="9.5.31" }
+
+- Fixed #7405: DockerHub missing images > 9.5.27 due to change in Alpine/APK
+
+### 9.5.30 <small>July 23, 2024</small> { id="9.5.30" }
+
+- Fixed #7380: Navigation icons disappearing on hover in Safari
+- Fixed #7367: Blog readtime computation includes SVG text content
+
+### 9.5.29 <small>July 14, 2024</small> { id="9.5.29" }
+
+- Updated Galician translations
+- Fixed #7362: Annotations in figure captions rendering incorrectly
+
+### 9.5.28 <small>July 2, 2024</small> { id="9.5.28" }
+
+- Fixed #7313: Improved tooltips mounted in sidebar when feature is disabled
+
+### 9.5.27 <small>June 16, 2024</small> { id="9.5.27" }
+
+- Updated Estonian translations
+
+### 9.5.26 <small>June 6, 2024</small> { id="9.5.26" }
+
+- Fixed #7232: Tab switches on scroll when linking tabs (9.5.19 regression)
+- Fixed #7230: Blog author avatar broken when referring to local file
+
+### 9.5.25 <small>May 27, 2024</small> { id="9.5.25" }
+
+- Fixed #7209: Tags plugin crashing on numeric tags
+
+### 9.5.24 <small>May 20, 2024</small> { id="9.5.24" }
+
+- Fixed #7187: Version selector title rendering issue
+
+### 9.5.23 <small>May 15, 2024</small> { id="9.5.23" }
+
+- Fixed #7183: Edge case in anchor navigation when using instant navigation
+- Fixed #6436: Version selector not showing version alias
+
+### 9.5.22 <small>May 12, 2024</small> { id="9.5.22" }
+
+- Fixed #7170: Copy button adds empty lines for line spans (9.5.18 regression)
+- Fixed #7160: Version switching doesn't stay on page (9.5.5 regression)
+- Fixed #5619: Links in Mermaid.js diagrams not discernible
+
+### 9.5.21 <small>May 3, 2024</small> { id="9.5.21" }
+
+- Fixed #7133: Ensure latest version of Mermaid.js is used
+- Fixed #7125: Added warning for dotfiles in info plugin
+
+### 9.5.20 <small>April 29, 2024</small> { id="9.5.20" }
+
+- Fixed deprecation warning in privacy plugin (9.5.19 regression)
+- Fixed #7119: Tags plugin emits deprecation warning (9.5.19 regression)
+- Fixed #7118: Social plugin crashes if fonts are disabled (9.5.19 regression)
+- Fixed #7085: Social plugin crashes on Windows when downloading fonts
+
+### 9.5.19 <small>April 25, 2024</small> { id="9.5.19" }
+
+- Updated MkDocs to 1.6 and limited version to < 2
+- Updated Docker image to latest Alpine Linux
+- Removed `setup.py`, now that GitHub fully understands `pyproject.toml`
+- Improved interop of social plugin with third-party MkDocs themes
+- Fixed #7099: Blog reading time not rendered correctly for Japanese
+- Fixed #7097: Improved resilience of tags plugin when no tags are given
+- Fixed #7090: Active tab indicator in nested content tabs rendering bug
+
+### 9.5.18 <small>April 16, 2024</small> { id="9.5.18" }
+
+- Refactored tooltips implementation to fix positioning issues
+- Fixed #7044: Rendering glitch when hovering contributor avatar in Chrome
+- Fixed #7043: Highlighted lines in code blocks cutoff on mobile
+- Fixed #6910: Incorrect position of tooltip for page status in sidebar
+- Fixed #6760: Incorrect position and overly long tooltip in tables
+- Fixed #6488: Incorrect position and cutoff tooltip in content tabs
+
+### 9.5.17 <small>April 2, 2024</small> { id="9.5.17" }
+
+- Updated Serbian translations
+- Fixed #7003: Confusing keyboard interaction for palette toggle
+- Fixed #7001: Blog posts now show time by default (9.5.16 regression)
+- Fixed edge case in backport of social plugin font loading logic
+
+### 9.5.16 <small>March 31, 2024</small> { id="9.5.16" }
+
+- Updated Russian translations
+- Improved error handling and reporting in social plugin
+- Improved error handling and reporting in privacy plugin
+- Fixed blog plugin not allowing to use time in format strings
+- Fixed #6983: Social plugin crashes because of Google Fonts API change
+
+### 9.5.15 <small>March 23, 2024</small> { id="9.5.15" }
+
+- Reverted fix for transparent iframes (9.5.14)
+- Fixed #6929: Interference of social plugin and auto dark mode
+- Fixed #6938: Giscus shows dark background in light mode (9.5.14 regression)
+
+### 9.5.14 <small>March 18, 2024</small> { id="9.5.14" }
+
+- Added support for hiding versions from selector when using mike
+- Added init system to improve signal handling in Docker image
+- Fixed edge cases in exclusion logic of info plugin
+- Fixed inability to reset pipeline in search plugin
+- Fixed syntax error in Finnish translations
+- Fixed #6917: UTF-8 encoding problems in blog plugin on Windows
+- Fixed #6889: Transparent iframes get background color
+
+### 9.5.13 <small>March 6, 2024</small> { id="9.5.13" }
+
+- Updated Slovak translations
+- Improved info plugin interop with projects plugin
+- Improved info plugin inclusion/exclusion logic
+- Fixed info plugin not gathering files recursively
+- Fixed #6750: Ensure info plugin packs up all necessary files
+
+### 9.5.12 <small>February 29, 2024</small> { id="9.5.12" }
+
+- Fixed #6846: Some meta tags removed on instant navigation (9.4.2 regression)
+- Fixed #6823: KaTex not rendering on instant navigation (9.5.5 regression)
+- Fixed #6821: Privacy plugin doesn't handle URLs with encoded characters
+
+### 9.5.11 <small>February 24, 2024</small> { id="9.5.11" }
+
+- Updated Finnish translation
+
+### 9.5.10 <small>February 19, 2024</small> { id="9.5.10" }
+
+- Updated Bahasa Malaysia translations
+- Fixed #6783: Hide continue reading link for blog posts without separators
+- Fixed #6779: Incorrect positioning of integrated table of contents
+
+### 9.5.9 <small>February 10, 2024</small> { id="9.5.9" }
+
+- Fixed navigation pruning with tabs and sections enabled
+
+### 9.5.8 <small>February 7, 2024</small> { id="9.5.8" }
+
+- Added Tamil translations
+- Updated Esperanto translations
+- Fixed relative images not being resolved for instant navigation
+
+### 9.5.7 <small>February 3, 2024</small> { id="9.5.7" }
+
+- Fixed #6731: Small images in figures are not centered
+- Fixed #6719: Instant navigation breaks table of contents (9.5.5 regression)
+
+### 9.5.6 <small>January 28, 2024</small> { id="9.5.6" }
+
+- Fixed #6700: Missing styles for Mermaid.js labels with Markdown
+
+### 9.5.5 <small>January 24, 2024</small> { id="9.5.5" }
+
+- Updated Tagalog translations
+- Updated Pillow to 10.2 to mitigate security vulnerabilities
+- Improved resilience of instant navigation
+- Fixed #6687: Updated Mermaid.js to version 10.7.0 (latest)
+- Fixed #6652: Keyboard events in custom elements captured
+- Fixed #6582: Instant navigation doesn't correctly handle alternate URLs
+- Fixed #6565: Instant navigation doesn't allow for `onclick` handlers
+- Fixed #6345: Instant navigation sometimes breaks browser back button
+- Fixed #6334: Instant navigation doesn't correctly position anchors (Safari)
+- Fixed #6275: Instant navigation doesn't correctly resolve after 404
+- Fixed #6102: Instant navigation reloads page on same link navigation
+
+### 9.5.4 <small>January 15, 2024</small> { id="9.5.4" }
+
+- Fixed #6645: Local storage with invalid value can break site
+- Fixed #6635: Tags icons before default ignored if default is set
+
+### 9.5.3 <small>December 23, 2023</small> { id="9.5.3" }
+
+- Limited version range of MkDocs to < 1.6
+- Updated Macedonian translations
+- Fixed #6520: Group plugin crashes when using mike
+- Fixed #6494: Hide author's email address if disabled in git-authors plugin
+
+### 9.5.2 <small>December 11, 2023</small> { id="9.5.2" }
+
+- Fixed types for `slugify` settings in blog plugin config
+- Fixed #6469: Horizontal scrollbars on MathJax containers
+
+### 9.5.1 <small>December 8, 2023</small> { id="9.5.1" }
+
+- Updated Greek translations
+- Fixed #6464: Privacy plugin cannot be enabled
+- Fixed #6461: Sorting blog posts ignores time component in date
+
+### 9.5.0 <small>December 7, 2023</small> { id="9.5.0" }
+
+Merged Insiders features of 'Goat's Horn' funding goal
+
+- Added privacy plugin: automatic downloading of external assets
+- Added support for card grids and grid layouts
+- Added support for improved tooltips
+- Added support for content tabs anchor links (deep linking)
+- Added support for automatic dark/light mode
+- Added support for document contributors
+
+### 9.4.14 <small>November 26, 2023</small> { id="9.4.14" }
+
+- Added support for linking authors in blog posts
+
+### 9.4.13 <small>November 26, 2023</small> { id="9.4.13" }
+
+- Fixed #6365: Blog plugin pagination links to previous pages broken
+- Fixed #5758: Updated Mermaid.js to version 10.6.1 (latest)
+
+### 9.4.12 <small>November 24, 2023</small> { id="9.4.12" }
+
+- Improved blog plugin to generate Unicode-aware slugs by default
+- Fixed non-deterministic order of categories in blog plugin
+
+### 9.4.11 <small>November 23, 2023</small> { id="9.4.11" }
+
+- Fixed #6364: Search plugin crashing when enabling theme while serving
+- Fixed blog plugin crashing when disabling pagination
+
+### 9.4.10 <small>November 19, 2023</small> { id="9.4.10" }
+
+- Fixed #6356: Version selector can't be disabled via mike's configuration
+- Fixed #6281: Navigation not rendering due to Safari bug (9.4.2 regression)
+- Fixed #6261: Navigation expansion animates on first load (9.4.2 regression)
+
+### 9.4.9 <small>November 17, 2023</small> { id="9.4.9" }
+
+- Fixed #6344: Long entries cutoff in table of contents
+- Fixed #6336: Custom template for glob archive not working with pagination
+- Fixed #6328: Blog plugin crashes for locales with dashes, e.g. `pt-BR`
+- Fixed #6327: Copy-to-clipboard button doesn't trim trailing line feed
+- Fixed #6302: Version strings not matched when using mike, only aliases
+- Fixed instant navigation progress indicator for gzipped content in Chrome
+- Fixed rendering bug on details marker rotation in Firefox
+
+### 9.4.8 <small>November 5, 2023</small> { id="9.4.8" }
+
+- Fixed invalid local address replacement when using instant loading
+- Fixed #6275: Crash after navigation caused 404 when using instant loading
+
+### 9.4.7 <small>October 27, 2023</small> { id="9.4.7" }
+
+- Added Azerbaijani translations
+
+### 9.4.6 <small>October 14, 2023</small> { id="9.4.6" }
+
+- Updated Danish and Norwegian (Nynorsk) translations
+- Fixed #6169: Blog post metadata layout overflows on small screens
+
+### 9.4.5 <small>October 10, 2023</small> { id="9.4.5" }
+
+- Fixed sidebar auto-positioning (9.4.2 regression)
+- Fixed #6166: Improve group plugin compatibility with Python < 3.10
+- Fixed #6157: Hiding tags does not work (9.4.3 regression)
+
+### 9.4.4 <small>October 5, 2023</small> { id="9.4.4" }
+
+- Added support for overriding text to be copied for code blocks
+- Fixed broken layout in some browsers at breakpoints when using zoom
+- Fixed #6132: Incomplete search highlighting for code blocks in titles
+
+### 9.4.3 <small>October 2, 2023</small> { id="9.4.3" }
+
+- Added support for instant navigation progress indicator
+- Improved spacing and alignment of tags
+- Moved back-to-top button into separate partial
+- Fixed #6104: Indentation for some code blocks lost in search
+- Fixed #6094: Blog post metadata overlaps with footer on small screens
+- Fixed #6069: Blog plugin crashes for categories with non-ASCII names
+
+__Updated templates__ ([diff](https://github.com/squidfunk/mkdocs-material/compare/9.4.2...9.4.3))
+
+- `base.html`
+
+### 9.4.2 <small>September 25, 2023</small> { id="9.4.2" }
+
+- Updated Slovenian translations
+- Added animation to sidebar navigation expansion and collapse
+- Added support for auto-replacement of document head for instant navigation
+- Improved compatibility of new emoji extension with Python < 3.10
+- Switched regex dependency to use minimal version
+- Refactored alignment and spacing of sidebar navigation
+- Fixed expansion button not focusable via keyboard in sidebar navigation
+- Fixed viewport offset restoration on first load when using instant navigation
+- Fixed accidental highlight of non-clickable elements in blog plugin sidebar
+- Fixed #6041: Blog plugin crashes when `nav` is defined and blog not included
+- Fixed #5972: Blog plugin ignores section index pages in paginated views
+- Fixed #5954: Repeated click on anchor ignored when using instant navigation
+- Fixed #5742: Keyboard navigation broken when using instant navigation
+
+__Updated templates__ ([diff](https://github.com/squidfunk/mkdocs-material/compare/9.4.1...9.4.2))
+
+- `partials/nav-item.html`
+- `blog-post.html`
+
+### 9.4.1 <small>September 22, 2023</small> { id="9.4.1" }
+
+- Improved colors and contrast in dark mode
+- Improved admonition borders to match font weight
+- Switched content tabs to neutral color
+
+### 9.4.0 <small>September 21, 2023</small> { id="9.4.0" }
+
+- Added Belarusian translations
+- Added version info to entrypoint of package
+- Added emoji extension as a replacement for `materialx`
+- Improved slate color scheme (dark mode) - now even darker
+- Restructured project to improve development experience
+- Updated MkDocs to 1.5.3
+- Fixed #3890: Development mode crash on Linux
+
+### 9.3.2 <small>September 19, 2023</small> { id="9.3.2" }
+
+- Updated Slovenian translations
+- Updated Python dependencies in requirements to use minimum versions
+- Fixed #6017: Code highlighting inconsistent in Community and Insiders edition
+- Fixed #6001: Contributor avatars display incorrectly in Firefox
+- Fixed #6000: Blog post drafts are included in navigation
+
+### 9.3.1 <small>September 11, 2023</small> { id="9.3.1" }
+
+- Fixed crash of group plugin when used together with hooks
+
+### 9.3.0 <small>September 11, 2023</small> { id="9.3.0" }
+
+- Improved configuration sharing between Community and Insiders edition
+- Added experimental built-in group plugin for enabling plugins conditionally
+- Added new settings in tags plugin for enabling/disabling
+- Dropped support for Python 3.7 (EOL)
+
+### 9.2.8 <small>September 4, 2023</small> { id="9.2.8" }
+
+- Updated Italian and Russian translations
+- Fixed #5952: Combining blog and tags plugin leads to wrong links
+- Fixed #5951: Blog plugin ignores post title in metadata
+- Fixed #5949: Blog plugin ignores post linked in nav
+
+### 9.2.7 <small>September 2, 2023</small> { id="9.2.7" }
+
+- Switched dependencies to compatible release clauses
+- Removed `readtime` and `lxml` dependencies for blog plugin
+- Reduced size of Docker image to improve CI build performance
+- Fixed #5945: Incorrect footer navigation for sibling pages of blog
+- Fixed #5939: Page jumps when changing color palette (Firefox 117)
+- Fixed #5901: Announcement bar reappears when using instant loading
+- Fixed #5824: Allow to customize styles of sequence diagrams
+
+### 9.2.6 <small>August 31, 2023</small> { id="9.2.6" }
+
+- Added Basque translations
+- Added template for simple redirects
+- Improved blog plugin interop by moving view generation to `on_files`
+- Fixed #5924: Social plugin still checks dependencies when disabled
+- Fixed #5916: Blog plugin crashes on Python 3.8 (9.2.0 regression)
+
+### 9.2.5 <small>August 27, 2023</small> { id="9.2.5" }
+
+- Fixed error in dirty serve mode when using blog plugin
+- Fixed page title not being consistent in blog plugin pagination
+- Fixed #5899: Blog plugin pagination breaks when disabling directory URLs
+
+### 9.2.4 <small>August 26, 2023</small> { id="9.2.4" }
+
+- Added version to bug report name in info plugin
+- Updated Afrikaans translations
+
+### 9.2.3 <small>August 22, 2023</small> { id="9.2.3" }
+
+- Fixed blog plugin rendering wrongly with `markdown.extensions.toc`
+- Fixed blog plugin entrypoint generation
+
+### 9.2.2 <small>August 22, 2023</small> { id="9.2.2" }
+
+- Fixed #5880: Blog plugin failing when building a standalone blog
+- Fixed #5881: Blog plugin not compatible with Python < 3.10
+
+### 9.2.1 <small>August 21, 2023</small> { id="9.2.1" }
+
+- Fixed #5879: Blog plugin failing when building a standalone blog
+- Fixed error in blog plugin when using draft tagging on future date
+- Fixed error in blog plugin when toc extension is not enabled
+
+### 9.2.0 <small>August 21, 2023</small> { id="9.2.0" }
+
+__Additions and improvements__
+
+- Added blogging support via built-in blog plugin
+- Added support for Chinese language segmentaiton in search plugin
+- Added support for adding custom dates to blog posts
+- Added support for paginating archive and category pages
+- Added support for annotations (outside of code blocks)
+- Added support for navigation icons
+- Added support for navigation pruning
+- Added support for navigation status
+- Added support for customizing site icons
+- Added support for customizing (code) annotation icons
+- Added focus outline to admonitions and details
+- Added prompt for bug report name to info plugin
+- Added Luxembourgish translations
+- Improved rendering of (code) annotation markers
+- Improved print styles for (code) annotations
+- Improved customizability of navigation tabs
+- Improved interop of plugins with external tools like mike
+- Improved interop of blog plugin with awesome pages plugin
+- Improved header partial by moving buttons into separate partials
+- Improved clarity of `site_url` warning in social plugin
+- Improved blog plugin to automatically setup directory structure
+- Switched info plugin to `importlib` to mitigate deprecations
+- Automatically download ResizeObserver polyfill when necessary
+- Automatically add iframe-worker polyfill when necessary in offline plugin
+- Automatically focus and bring up keyboard on touch devices
+- Updated Serbo-Croatian translations
+- Updated MkDocs to 1.5.2
+
+__Removals__
+
+- Removed Universal Analytics integration
+- Removed ancient polyfills to reduce size of bundled JavaScript by 20%
+- Removed necessity for `Array.flat` and `Array.flatMap` polyfill
+- Removed announcement bar button when JavaScript is not available
+
+__Fixes__
+
+- Fixed rendering of tags when announcement bar is present
+- Fixed tags plugin rendering pages excluded by other plugins
+- Fixed #5132: Blog plugin requires `nav` entry in `mkdocs.yml`
+- Fixed #5599: Insufficient contrast for default link color
+- Fixed #5715: Blog plugin missing integrated table of contents in pagination
+- Fixed #5806: Version selector not hoverable on some Android devices
+- Fixed #5826: Blog post drafts with tags show up in tags index
+
+### 9.1.21 <small>July 27, 2023</small> { id="9.1.21" }
+
+- Fixed MkDocs 1.4 compat issue in social plugin (9.1.20 regression)
+
+### 9.1.20 <small>July 27, 2023</small> { id="9.1.20" }
+
+- Updated Sanskrit translations
+- Fixed deprecation warnings for social plugin
+
+### 9.1.19 <small>July 18, 2023</small> { id="9.1.19" }
+
+- Added support for MkDocs 1.5+
+- Fixed #5699: Improve error reporting in social plugin
+
+### 9.1.18 <small>July 3, 2023</small> { id="9.1.18" }
+
+- Updated Danish translations
+- Added support for installing user requirements in Docker image
+- Fixed #5655: Search separator with lookbehind breaks highlighting
+
+### 9.1.17 <small>June 23, 2023</small> { id="9.1.17" }
+
+- Fixed #5633: Code annotations with nested lists incorrectly mounted
+- Fixed #5628: Regression in new social plugin configuration scheme
+
+### 9.1.16 <small>June 15, 2023</small> { id="9.1.16" }
+
+- Updated Indonesian translations
+- Ensure scroll bar follows color scheme of operating system
+
+### 9.1.15 <small>May 29, 2023</small> { id="9.1.15" }
+
+- Fixed #5566: Indicate color scheme to operating system
+- Fixed #5565: Update `Dockerfile` to latest version of base image
+- Fixed #5554: Add additional version tags (`9`, `9.1`) to Docker image
+- Fixed #5536: Strip tags of ARIA labels in table of contents
+
+### 9.1.14 <small>May 20, 2023</small> { id="9.1.14" }
+
+- Updated Armenian and Greek translations
+
+### 9.1.13 <small>May 16, 2023</small> { id="9.1.13" }
+
+- Fixed #5517: Social plugin crashes for some fonts (e.g. Open Sans)
+
+### 9.1.12 <small>May 12, 2023</small> { id="9.1.12" }
+
+- Updated Bengali (Bangla) translations
+- Fixed #5503: Docker image publish errors on uppercase characters
+- Fixed #5407: Auto-pause media when in hidden content tabs
+
+### 9.1.11 <small>May 8, 2023</small> { id="9.1.11" }
+
+- Fixed #5487: Social plugin crashes without options (9.1.10 regression)
+
+### 9.1.10 <small>May 8, 2023</small> { id="9.1.10" }
+
+- Added `cards_layout_options` setting for social cards
+- Deprecated `cards_color` and `cards_font` setting for social cards
+
+### 9.1.9 <small>May 2, 2023</small> { id="9.1.9" }
+
+- Added Telugu, Kannada and Sanskrit translations
+- Fixed #5428: Fixed margins for light/dark mode images in figures
+- Fixed #5420: Social plugin crashing for some specific Google Fonts
+- Fixed #5160: Instant loading makes code annotations jump (9.1.1 regression)
+- Fixed #4920: Social plugin not loading logo from custom icon set
+- Fixed social plugin crashing when only code font is specified
+
+### 9.1.8 <small>April 24, 2023</small> { id="9.1.8" }
+
+- Fixed #5417: Theme breaks when `palette` is not defined (9.1.7 regression)
+
+### 9.1.7 <small>April 22, 2023</small> { id="9.1.7" }
+
+- Updated Persian (Farsi) and Turkish translations
+- Fixed #5401: Added missing flag to disable built-in tags plugin
+- Fixed #5206: Ensure defaults are set for primary and accent colors
+- Fixed unnecessary inclusion of palette CSS when unused
+
+### 9.1.6 <small>April 7, 2023</small> { id="9.1.6" }
+
+- Updated Persian (Farsi) translations
+- Fixed #5300: Boxes in Mermaid sequence diagrams not color-abiding
+
+### 9.1.5 <small>March 31, 2023</small> { id="9.1.5" }
+
+- Updated Lithuanian and Japanese translations
+- Updated Mermaid.js to version 9.4.3
+- Fixed #5290: Footer previous/next labels cut-off for short page titles
+
+### 9.1.4 <small>March 24, 2023</small> { id="9.1.4" }
+
+- Fixed #5239: Instant loading breaks anchors in details (9.1.1 regression)
+- Fixed #5211: Anchor following not working for Chinese (9.1.2 regression)
+
+### 9.1.3 <small>March 14, 2023</small> { id="9.1.3" }
+
+- Added Kurdish (Soranî) translations
+- Updated Norwegian (Bokmål), Portuguese and Romanian translations
+- Improved compatibility with `mkdocs-jupyter` plugin
+- Fixed #5198: Built-in search plugin not filtering `script` and `style` tags
+- Fixed #5176: Back-to-top + instant loading not working (9.1.1 regression)
+
+### 9.1.2 <small>March 9, 2023</small> { id="9.1.2" }
+
+- Updated Icelandic, Korean and Swedish translations
+- Fixed #5168: Mermaid text boxes overflow (9.0.13 regression)
+- Fixed #5155: Table of contents not highlighting percent-encoded URLs
+
+### 9.1.1 <small>March 5, 2023</small> { id="9.1.1" }
+
+- Updated Czech and Thai translations
+- Improved instant loading (scroll restoration, slow connections)
+- Fixed #5023: Instant loading not allowing to go back to initial page
+- Fixed #3797: Instant loading does not work with section anchors in Safari
+
+### 9.1.0 <small>March 2, 2023</small> { id="9.1.0" }
+
+- Docker image now available for `amd64`, `arm64` and `arm/v7`
+- Updated Chinese (Taiwanese) translations
+- Generalized tag identifier implementation
+- Fixed flickering of header shadow on load
+- Fixed occasional flickering of announcement bar
+
+### 9.0.15 <small>February 26, 2023</small> { id="9.0.15" }
+
+- Updated Chinese (Traditional) translations
+- Updated Hebrew translations
+
+### 9.0.14 <small>February 23, 2023</small> { id="9.0.14" }
+
+- Fixed #5072: Rendering bug on navigation expand button in Firefox
+
+### 9.0.13 <small>February 18, 2023</small> { id="9.0.13" }
+
+- Updated Uzbek translations
+- Switched back to pre-9.0.0 headline detection in `content` partial
+- Fixed #5062: Version warning not readable when using slate scheme
+- Fixed #5061: Improved discernibility of table row hover color
+- Fixed #5034: Sequence actors in Mermaid diagrams not color-abiding
+- Fixed #4919: Allow to hide version warning in multiple versions
+
+### 9.0.12 <small>February 9, 2023</small> { id="9.0.12" }
+
+- Updated Catalan translations
+- Fixed #4975: Mermaid entity relationship rendering diagrams bug
+- Fixed #4924: Header title not reset when using instant loading
+
+### 9.0.11 <small>February 3, 2023</small> { id="9.0.11" }
+
+- Added Mastodon verification for social links (`rel=me`)
+- Updated Italian translations
+
+### 9.0.10 <small>February 2, 2023</small> { id="9.0.10" }
+
+- Updated Arabic translations
+- Updated Korean translations
+- Updated Hungarian translations
+- Updated Russian translations
+- Fixed #4977: Improved accessibility for content tabs
+- Fixed #4960: Sometimes anchor following doesn't bring last item into view
+
+### 9.0.9 <small>January 30, 2023</small> { id="9.0.9" }
+
+- Updated Bulgarian translations
+- Updated Chinese (Simplified) translations
+- Updated Dutch translations
+- Updated Hindi translations
+- Updated Japanese translations
+- Updated Polish translations
+
+### 9.0.8 <small>January 29, 2023</small> { id="9.0.8" }
+
+- Updated Croatian translations
+- Updated French translations
+- Updated Hungarian translations
+- Updated Portuguese (Brasilian) translations
+- Updated Spanish translations
+- Updated Ukrainian translations
+- Updated Urdu translations
+- Updated Vietnamese translations
+
+### 9.0.7 <small>January 28, 2023</small> { id="9.0.7" }
+
+- Improved accessibility of sidebar navigation
+- Moved all translations into Community edition
+- Updated Polish and Portuguese (Brasilian) translations
+- Fixed info plugin terminating on subsequent reload when serving
+- Fixed #4910: Sidebar navigation labels have invalid ARIA roles
+- Fixed #4884: Search query terms can't be separated by colons
+
+### 9.0.6 <small>January 19, 2023</small> { id="9.0.6" }
+
+- Fixed #4883: Automatically disable info plugin when serving
+- Fixed #4885: Search plugin crashes in some exotic cases (9.0.3 regression)
+
+### 9.0.5 <small>January 14, 2023</small> { id="9.0.5" }
+
+- Fixed #4842: Improved accessibility of search result list
+
+### 9.0.4 <small>January 12, 2023</small> { id="9.0.4" }
+
+- Fixed #4823: Improved contrast ratio in footer (9.0.2 regression)
+- Fixed #4832: Set navigation items back to black (9.0.3 regression)
+- Fixed #4843: Emojis broken due to maxcdn.com shutting down
+- Upgraded Python Markdown Extensions to 9.9.1
+
+### 9.0.3 <small>January 8, 2023</small> { id="9.0.3" }
+
+- Improved discernibility of section index pages in navigation
+- Improved collapsing of adjacent whitespace in search plugin
+- Updated Indonesian translations
+- Fixed view source of this page button when edit URL points to blob
+- Fixed #4829: Search overlay does not close for active anchor result
+- Fixed #4824: Search plugin crashes for `h[1-6]` contained in other elements
+- Fixed #4804: Nested navigation items not expandable with keyboard
+- Fixed #4689: anchor tracking not working for anchors in tables
+- Upgraded to Mermaid 9.3.0
+
+### 9.0.2 <small>January 4, 2023</small> { id="9.0.2" }
+
+- Fixed #4823: Improved contrast ratio in footer to meet WCAG guidelines
+- Fixed #4819: Social plugin crashes when card generation is disabled
+- Fixed #4817: Search plugin crashes on numeric page titles in `nav`
+
+### 9.0.1 <small>January 3, 2023</small> { id="9.0.1" }
+
+- Removed `pipdeptree` dependency for built-in info plugin
+- Fixed appearance of linked tags when hovered (9.0.0 regression)
+- Fixed #4810: Abbreviations run out of screen on touch devices
+- Fixed #4813: View source and edit button links are the same
+
+### 9.0.0 <small>January 2, 2023</small> { id="9.0.0" }
+
+__Additions and improvements__
+
+- Added support for rich search previews
+- Added support for tokenizer lookahead
+- Added support for better search highlighting
+- Added support for excluding content from search
+- Added support for configurable search pipeline
+- Added support for offline search via offline plugin
+- Added support for multiple instances of built-in tags plugin
+- Added support for removing copy-to-clipboard button
+- Added support for removing footer navigation
+- Added support for button to view the source of a page
+- Improved readability of query string for search sharing
+- Improved stability of search plugin when using `--dirtyreload`
+- Improved search result group button, now sticky and stable
+- Updated Norwegian translations
+- Updated MkDocs to 1.4.2
+
+__Removals__
+
+- Removed deprecated alternative admonition qualifiers
+- Removed `:is()` selectors (in output) for easier overriding
+- Removed `.title` suffix on translations
+- Removed legacy method for providing page title in feedback URL
+- Removed support for indexing only titles in search
+- Removed support for custom search transforms
+- Removed support for custom search workers
+- Removed temporary snow feature (easter egg)
+
+__Fixes__
+
+- Fixed Norwegian and Korean language code
+- Fixed detection of composition events in search interface
+- Fixed search plugin not using title set via front matter
+- Fixed search highlighting of tags
+- Fixed search sharing URL using post transformed string
+- Fixed theme-color meta tag getting out-of-sync with palette toggle
+- Fixed prev/next page keyboard navigation when footer is not present
+- Fixed overflowing navigation tabs not being scrollable
+- Fixed inclusion of code block line numbers from search
+
+---
+
+### 8.5.11 <small>November 30, 2022</small> { id="8.5.11" }
+
+- Let it snow, see https://x.com/squidfunk/status/1597939243090788352
+
+### 8.5.10 <small>November 11, 2022</small> { id="8.5.10" }
+
+- Adjusted CSS to better allow for custom primary and accent colors
+- Fixed #4620: Primary color is not applied (8.5.9 regression)
+
+### 8.5.9 <small>November 8, 2022</small> { id="8.5.9" }
+
+- Fixed #4600: Illegible link colors for black and white primary colors
+- Fixed #4594: Need to set schema to change link color
+
+### 8.5.8 <small>November 3, 2022</small> { id="8.5.8" }
+
+- Added support for always showing settings in cookie consent
+- Fixed #4571: Buttons invisible if primary color is `white` or `black`
+- Fixed #4517: Illegible note in sequence diagram when using `slate` scheme
+
+### 8.5.7 <small>October 22, 2022</small> { id="8.5.7" }
+
+- Deprecated additional admonition qualifiers to reduce size of CSS
+- Fixed #4511: Search boost does not apply to sections
+
+### 8.5.6 <small>October 2, 2022</small> { id="8.5.6" }
+
+- Modernized appearance of admonitions (with fallback, see docs)
+- Improved appearance of inline code blocks in admonition titles
+
+### 8.5.5 <small>October 1, 2022</small> { id="8.5.5" }
+
+- Updated MkDocs to 1.4
+- Fixed compatibility issues with MkDocs 1.4
+- Fixed #4430: build error when enabling consent without repository URL
+
+### 8.5.4 <small>September 30, 2022</small> { id="8.5.4" }
+
+- Fixed expand icons shift on sidebar overflow (using `scrollbar-gutter`)
+- Fixed #4429: Text in sequence diagrams overflows in Firefox
+
+### 8.5.3 <small>September 20, 2022</small> { id="8.5.3" }
+
+- Fixed build error when enabling cookie consent without analytics
+- Fixed #4381: Code blocks render ligatures for some fonts
+
+### 8.5.2 <small>September 18, 2022</small> { id="8.5.2" }
+
+- Updated Mermaid.js to version 9.1.7
+- Fixed overly large headlines in search results (8.5.0 regression)
+- Fixed #4358: Navigation sections appear as clickable (8.5.0 regression)
+- Fixed #4356: GitHub repository statistics fetched before cookie consent
+
+### 8.5.1 <small>September 15, 2022</small> { id="8.5.1" }
+
+- Fixed #4366: Removed dependencies with native extensions
+
+### 8.5.0 <small>September 13, 2022</small> { id="8.5.0" }
+
+- Added support for social cards
+- Added support for code annotation anchor links (deep linking)
+- Added support for code annotation comment stripping (syntax modifier)
+- Added support for sidebars scrolling automatically to active item
+- Added support for anchor following table of contents (= auto scroll)
+- Added support for tag icons
+
+### 8.4.4 <small>September 12, 2022</small> { id="8.4.4" }
+
+- Moved comments integration to separate partial (`comments.html`)
+
+### 8.4.3 <small>September 7, 2022</small> { id="8.4.3" }
+
+- Added Simple Icons to bundled icons (+2,300 icons)
+- Added support for changing edit icon
+- Moved page actions to separate partial (`actions.html`)
+- Fixed #4291: Version switching doesn't stay on page when anchors are used
+- Fixed #4327: Links in data tables do not receive link styling
+
+### 8.4.2 <small>August 27, 2022</small> { id="8.4.2" }
+
+- Updated Slovenian translations
+- Fixed #4277: Feedback widget hidden after navigation with instant loading
+- Fixed numeric tags in front matter breaking search functionality
+
+### 8.4.1 <small>August 21, 2022</small> { id="8.4.1" }
+
+- Updated Croatian and Hebrew translations
+
+### 8.4.0 <small>August 13, 2022</small> { id="8.4.0" }
+
+- Added support for cookie consent
+- Added support for feedback widget (Was this page helpful?)
+- Added support for dismissible announcement bar
+- Added Armenian, Lithuanian, Tagalog, and Urdu translations
+
+### 8.3.9 <small>July 4, 2022</small> { id="8.3.9" }
+
+- Updated Taiwanese translations for search
+- Allow ids for content tabs with special characters (for mkdocstrings)
+- Fixed #4083: home not clickable when using versioning (8.3.5 regression)
+
+### 8.3.8 <small>June 24, 2022</small> { id="8.3.8" }
+
+- Fixed #4053: Limit width of videos to content area
+- Fixed empty tags in front matter breaking search
+
+### 8.3.7 <small>June 22, 2022</small> { id="8.3.7" }
+
+- Fixed search being stuck initializing when using tags (8.3.4 regression)
+
+### 8.3.6 <small>June 16, 2022</small> { id="8.3.6" }
+
+- Fixed #4028: Links not clickable when using versioning (8.3.5 regression)
+
+### 8.3.5 <small>June 14, 2022</small> { id="8.3.5" }
+
+- Fixed #4012: Stay on page not working for alias of active version
+
+### 8.3.4 <small>June 11, 2022</small> { id="8.3.4" }
+
+- Fixed #4004: Tags with multiple words not searchable
+
+### 8.3.3 <small>June 7, 2022</small> { id="8.3.3" }
+
+- Fixed #4000: Mermaid diagrams too dark in dark mode (8.3.0 regression)
+
+### 8.3.2 <small>June 5, 2022</small> { id="8.3.2" }
+
+- Fixed #3987: Custom admonition icons don't work when defining color palette
+
+### 8.3.1 <small>June 4, 2022</small> { id="8.3.1" }
+
+- Bump required Jinja version to 3.0.2
+- Removed unnecessary conditions in templates
+- Fixed scroll offset when content tabs are brought into view
+- Fixed #3977: Content tabs snapping oddly in Firefox
+- Fixed #3983: Missing condition in footer partial (8.3.0 regression)
+
+### 8.3.0 <small>June 2, 2022</small> { id="8.3.0" }
+
+- Added support for custom admonition icons
+- Added support for linking of content tabs
+- Added support for boosting pages in search
+- Added support for hiding footer navigation
+- Added previous/next indicators to content tabs
+- Improved typeset link colors in light and dark modes
+
+### 8.2.16 <small>May 28, 2022</small> { id="8.2.16" }
+
+- Fixed #3957: Only animate code annotations when visible (save CPU cycles)
+
+### 8.2.15 <small>May 14, 2022</small> { id="8.2.15" }
+
+- Added Uzbek translations
+- Fixed spacing for code block results in content tabs
+
+### 8.2.14 <small>May 8, 2022</small> { id="8.2.14" }
+
+- Fixed missing top right rounded border on admonition
+- Fixed #3886: `4xx` status codes not handled when using instant loading
+
+### 8.2.13 <small>May 2, 2022</small> { id="8.2.13" }
+
+- Fixed #3865: Tags index links to tagged pages 404 on Windows
+- Fixed #3866: Bump required Python version from 3.6+ to 3.7+
+
+### 8.2.12 <small>April 30, 2022</small> { id="8.2.12" }
+
+- Added support for GitHub-style hash fragments for dark/light images
+- Improved rendering of nested code blocks in content tabs and annotations
+- Fixed #3862: Upgraded to latest Pygments and Python Markdown Extensions
+
+### 8.2.11 <small>April 25, 2022</small> { id="8.2.11" }
+
+- Temporarily pinned Pygments to `<2.12`
+- Temporarily pinned Python Markdown Extensions to `<9.4`
+- Improved rendering of code annotation markers
+
+### 8.2.10 <small>April 24, 2022</small> { id="8.2.10" }
+
+- Added Macedonian translations
+- Updated Mermaid.js to version 9.0.1
+- Switched sidebar title in mobile navigation to bold font
+- Fixed color of arrows in class and state diagrams for dark mode
+- Fixed #3836: Inline admonitions overlayed by code block titles
+
+### 8.2.9 <small>April 8, 2022</small> { id="8.2.9" }
+
+- Mitigate flicker on color palette switch by disabling all transitions
+- Fixed search suggestions not triggered when following deep link
+- Fixed incorrectly computed header height when using instant loading
+- Fixed #3782: Admonition titles have extra pixels on wide screens in Firefox
+- Fixed #3802: Always render table of contents container (except when hidden)
+
+### 8.2.8 <small>March 27, 2022</small> { id="8.2.8" }
+
+- Bumped MkDocs version to 1.3.0 to mitigate breaking changes in Jinja
+- Reverted Jinja version range limitation (added in 8.2.7)
+- Improved styling of annotations and fixed borders of code blocks in tabs
+- Added background color to code blocks in focused/hovered links
+- Added check in tags plugin whether tags overview page exists
+- Fixed #3744: Content tab indicator on wrong position when using back button
+
+### 8.2.7 <small>March 24, 2022</small> { id="8.2.7" }
+
+- Temporarily limit Jinja version range to < 3.1 due to breaking changes
+
+### 8.2.6 <small>March 23, 2022</small> { id="8.2.6" }
+
+- Fixed #3695: Deprecation warning for unescaped backslashes in templates
+- Fixed #3696: Annotations not mounted in some Terraform code blocks
+- Fixed #3698: Annotations not mounted in long code blocks (8.2.5 regression)
+
+### 8.2.5 <small>March 6, 2022</small> { id="8.2.5" }
+
+- Fixed #3596: Mermaid not working when headline with name 'Mermaid' present
+- Fixed #3643: Reduce time to render pages with thousands of code blocks
+- Fixed #3665: Missing styles for Mermaid.js flowcharts cluster labels
+
+### 8.2.4 <small>March 2, 2022</small> { id="8.2.4" }
+
+- Fixed malformed Google Fonts URL when a font setting was omitted
+- Fixed #3648: Fixed specificity issue with admonitions in lists
+- Fixed #3653: Invalid outdated version banner URL when using instant loading
+
+### 8.2.3 <small>February 27, 2022</small> { id="8.2.3" }
+
+- Fixed #3578: Active element in table of contents off-by-one on large screens
+
+### 8.2.2 <small>February 26, 2022</small> { id="8.2.2" }
+
+- Added automatic removal of query parameter when search is closed
+- Fixed #3599: Anchors always overridden when using navigation tracking
+
+### 8.2.1 <small>February 17, 2022</small> { id="8.2.1" }
+
+- Fixed module `material.plugins` not being found (8.2.0 regression)
+
+### 8.2.0 <small>February 17, 2022</small> { id="8.2.0" }
+
+- Added native support for Mermaid.js diagrams
+- Added native support for tags (with search integration)
+- Added support for staying on page when switching versions
+
+### 8.1.11 <small>February 10, 2022</small> { id="8.1.11" }
+
+- Added Portuguese (Brasilian) translations
+- Updated FontAwesome to v6 – [check which icons were renamed here]
+- Fixed #3545: Color palette toggle and search overlaying version selector
+
+ [check which icons were renamed here]: https://docs.fontawesome.com/v6/web/setup/upgrade/whats-changed#icons-renamed-in-version-6
+
+### 8.1.10 <small>February 6, 2022</small> { id="8.1.10" }
+
+- Fixed cutoff of very wide logos in the sidebar on mobile
+
+### 8.1.9 <small>January 30, 2022</small> { id="8.1.9" }
+
+- [Added support for `mkdocs.yml` validation and auto-complete][validation]
+- Fixed errors in Latvian translations
+
+ [validation]: ../creating-your-site.md#minimal-configuration
+
+### 8.1.8 <small>January 23, 2022</small> { id="8.1.8" }
+
+- Added Latvian translations
+- Updated Giscus example integration with dynamic theme change support
+- Fixed #3479: Back-to-top button not hidden when using sticky navigation tabs
+- Fixed #3491: Logo in header and drawer doesn't honor aspect ratio
+
+### 8.1.7 <small>January 16, 2022</small> { id="8.1.7" }
+
+- Improved back-to-top button behavior - now not shown on anchor jump
+
+### 8.1.6 <small>January 11, 2022</small> { id="8.1.6" }
+
+- Fixed spacing of blockquotes (8.1.5 regression)
+- Fixed edge cases for rounded corners on code blocks (8.1.5 regression)
+- Fixed issues with code annotation line heights
+
+### 8.1.5 <small>January 9, 2022</small> { id="8.1.5" }
+
+- Improved browser support: Chrome 49+, Safari 10+, Firefox 53+, Edge 79+
+- Improved rendering of inline code blocks in headlines
+- Added Bahasa Malaysian translations
+- Fixed #3354: MathJax formulas show vertical scrollbar
+
+### 8.1.4 <small>January 2, 2022</small> { id="8.1.4" }
+
+- Added indicator to navigation expander icon
+- Improved support for reduced motion preference
+- Fixed jitter of active content tab indicator
+
+### 8.1.3 <small>December 19, 2021</small> { id="8.1.3" }
+
+- Added animation to active content tab indicator
+- Fixed #3360: Highlighted lines add blank lines in copied text
+- Fixed usage of subsequent index files when using section index pages
+
+### 8.1.2 <small>December 15, 2021</small> { id="8.1.2" }
+
+- Switched CSS sources to logical properties
+- Added transformation of logical properties to `ltr`/`rtl` equivalents
+- Fixed spacing for admonitions inside lists (8.1.1 regression)
+
+### 8.1.1 <small>December 13, 2021</small> { id="8.1.1" }
+
+- Added support for `#only-light` and `#only-dark` image hash fragments
+- Fixed copy-to-clipboard adding blank lines when using line anchors
+- Fixed code annotation directionality for right-to-left languages
+- Fixed header title positioning for right-to-left languages
+- Fixed admonition borders for right-to-left languages (8.0.0 regression)
+- Fixed footer navigation link positioning (8.0.0 regression)
+- Fixed footer navigation title breaking out of container when too long
+- Fixed shrinking arrow in navigation title when too long
+- Fixed #3343: Filtered stopwords appear as missing search terms
+- Fixed #3346: Site unusable due to usage of `:not()` (Firefox 78 ESR)
+
+### 8.1.0 <small>December 10, 2021</small> { id="8.1.0" }
+
+- Added basic support for code block line anchors
+- Switched code annotation markers to `+` signs to improve usability
+- Switched main site title to bold font
+- Improved admonition icon positioning to align when `font-size` is increased
+- Improved and simplified footnotes CSS
+- Improved and simplified code annotation positioning
+- Fixed syntax error in Russian translations
+
+### 8.0.5 <small>December 6, 2021</small> { id="8.0.5" }
+
+- Fixed #3302: Footer refactoring induced ellipsis in some browsers
+- Fixed #3313: Details always rendered closed on load (8.0.4 regression)
+
+### 8.0.4 <small>December 4, 2021</small> { id="8.0.4" }
+
+- Improved support for deeply nested code annotations
+- Improved code annotation and copy-to-clipboard interop
+- Improved styling for code annotations inside admonitions
+- Fixed #3274: Invalid anchor positioning when using instant loading
+- Fixed #3294: Lists after code blocks without code annotations disappearing
+- Fixed several positioning issues for code annotations
+- Fixed JavaScript source map roots
+
+### 8.0.3 <small>December 2, 2021</small> { id="8.0.3" }
+
+- Removed deprecated `google_analytics` setting (was forgotten in 8.0.0)
+- Fixed syntax error in Swedish and Polish translations
+- Fixed #3283: Invalid back-to-top button position with sticky navigation tabs
+- Fixed #3285: Default details marker showing due to Safari bug
+
+### 8.0.2 <small>November 30, 2021</small> { id="8.0.2" }
+
+- Fixed #3275: Code annotations always disappear on click
+
+### 8.0.1 <small>November 28, 2021</small> { id="8.0.1" }
+
+- Improved rendering of code annotation markers
+- Fixed #3265: Wrong margin on nested admonitions
+- Fixed wrong `box-sizing` for code annotations in details
+
+### 8.0.0 <small>November 28, 2021</small> { id="8.0.0" }
+
+- Added support for code annotations
+- Added support for anchor tracking
+- Added support for version warning
+- Added `copyright` partial for easier override
+- Removed deprecated content tabs legacy implementation
+- Removed deprecated `seealso` admonition type
+- Removed deprecated `site_keywords` setting (unsupported by MkDocs)
+- Removed deprecated prebuilt search index support
+- Removed deprecated web app manifest – use customization
+- Removed `extracopyright` variable – use new `copyright` partial
+- Removed Disqus integration – use customization
+- Switched to `:is()` selectors for simple selector lists
+- Switched autoprefixer from `last 4 years` to `last 2 years`
+- Improved CSS overall to match modern standards
+- Improved CSS variable semantics for fonts
+- Improved extensibility by restructuring partials
+- Improved handling of `details` when printing
+- Improved keyboard navigation for footnotes
+- Fixed #3214: Search highlighting breaks site when empty
+
+---
+
+### 7.3.6 <small>October 30, 2021</small> { id="7.3.6" }
+
+- Added support for adding titles to code blocks
+
+### 7.3.5 <small>October 27, 2021</small> { id="7.3.5" }
+
+- Added support for setting table of contents title via `mkdocs.yml`
+- Fixed back-to-top button position for right-to-left languages
+
+### 7.3.4 <small>October 17, 2021</small> { id="7.3.4" }
+
+- Bumped MkDocs version to 1.2.3 to mitigate [CVE-2021-40978]
+- Fixed spacing issues when using integrate table of contents with tabs
+- Fixed some spacings issues for right-to-left languages
+- Fixed race condition in search initialization
+
+ [CVE-2021-40978]: https://nvd.nist.gov/vuln/detail/CVE-2021-40978
+
+### 7.3.3 <small>October 11, 2021</small> { id="7.3.3" }
+
+- Rewrite of entire documentation
+- Adjusted height of new content tabs to match single line code blocks
+- Fixed new content tabs missing right padding in some browsers on overflow
+- Fixed new content tabs bleeding out of flex container on overflow
+- Fixed new content tabs overflow scrolling bugs on some browsers
+- Fixed new content tabs stealing keyboard access when active
+- Fixed some spacings issues for right-to-left languages
+
+### 7.3.2 <small>October 6, 2021</small> { id="7.3.2" }
+
+- Deprecated prebuilding of search index
+- Improved graceful handling of broken search for `file://`
+- Added minimum Jinja version to list of requirements
+- Fixed #3071: Section index pages render empty directories
+- Fixed margin issues when using navigation tabs (7.3.1 regression)
+- Fixed search placeholder sometimes being shown too early
+
+### 7.3.1 <small>October 2, 2021</small> { id="7.3.1" }
+
+- Added new experimental content tabs implementation
+- Fixed #3069: GitHub stats broken for users/orgs (7.1.0 regression)
+- Fixed #3070: Sections not linking to index page
+- Fixed title not linking to index page when using tabs
+- Fixed Disqus integration when using instant loading
+- Fixed some spacing issues for right-to-left languages
+- Fixed syntax error in Serbian translations
+
+### 7.3.0 <small>September 23, 2021</small> { id="7.3.0" }
+
+- Added support for sticky navigation tabs
+- Added support for section index pages
+- Added support for removing generator notice
+
+### 7.2.8 <small>September 20, 2021</small> { id="7.2.8" }
+
+- Fixed #3039: Search modal overlays menu on mobile (7.2.7 regression)
+
+### 7.2.7 <small>September 19, 2021</small> { id="7.2.7" }
+
+- Updated Serbian and Serbo-Croatian translations
+- Improved appearance of outline on details
+- Fixed #2934: Scrollbar when header is hidden on some mobile browsers
+- Fixed #3032: Anchor in details doesn't open on load (7.0.0 regression)
+- Fixed back-to-top button being focusable when invisible
+- Fixed broken admonition icons (removed in upstream)
+
+### 7.2.6 <small>September 1, 2021</small> { id="7.2.6" }
+
+- Fixed rendering of `blockquote` elements (7.0.0 regression)
+- Fixed #2973: Custom search worker setting ignored
+
+### 7.2.5 <small>August 25, 2021</small> { id="7.2.5" }
+
+- Updated Portuguese translations
+- Fixed execution of RxJS teardown logic (7.2.3 regression)
+- Fixed #2970: Search results show escaped characters (7.2.2 regression)
+
+### 7.2.4 <small>August 11, 2021</small> { id="7.2.4" }
+
+- Fixed #2926: Version selector not working (7.2.3 regression)
+- Fixed #2929: Missing CSS class for banner (consistency with Insiders)
+
+### 7.2.3 <small>August 9, 2021</small> { id="7.2.3" }
+
+- Slight facelift of data tables, now closer to Material Design
+- Fixed instant loading not respecting clicks on search results
+- Fixed #2881: Invalid anchor offsets when using instant loading
+
+### 7.2.2 <small>July 31, 2021</small> { id="7.2.2" }
+
+- Updated Korean translations
+- Fixed #2879: Search highlighting does not properly escape HTML
+
+### 7.2.1 <small>July 25, 2021</small> { id="7.2.1" }
+
+- Fixed #2862: Back-to-top button overlays active search bar
+
+### 7.2.0 <small>July 21, 2021</small> { id="7.2.0" }
+
+- Added support for search suggestions to save keystrokes
+- Added support for search highlighting
+- Added support for search sharing (i.e. deep linking)
+
+### 7.1.11 <small>July 18, 2021</small> { id="7.1.11" }
+
+- Updated Spanish and Galician translations
+
+### 7.1.10 <small>July 10, 2021</small> { id="7.1.10" }
+
+- Refactored appearance of back-to-top button
+- Fixed graceful handling of search when browsing locally
+
+### 7.1.9 <small>June 25, 2021</small> { id="7.1.9" }
+
+- Improved search language support for Thai and Hindi
+- Fixed #2761: License comments lined up at end of file
+
+### 7.1.8 <small>June 12, 2021</small> { id="7.1.8" }
+
+- Refactored analytics integration (because of MkDocs 1.2)
+- Added support for Google Analytics 4 (`gtag.js`)
+- Fixed missing escape for `aria-label` in footer links
+
+### 7.1.7 <small>June 6, 2021</small> { id="7.1.7" }
+
+- Improved screen reader support
+
+### 7.1.6 <small>May 30, 2021</small> { id="7.1.6" }
+
+- Deprecated `seealso` admonition qualifier
+- Added Mongolian and updated Chinese translations
+- Fixed #2429: Version selector not touch-friendly on Android devices
+- Fixed #2703: Printed 'Initializing search' albeit ready on mobile
+
+### 7.1.5 <small>May 19, 2021</small> { id="7.1.5" }
+
+- Fixed #2655: Details breaking page margins on print
+
+### 7.1.4 <small>May 6, 2021</small> { id="7.1.4" }
+
+- Added support for git-revision-date-localized plugin creation date
+- Improved footnote styles on `:target` and `:focus`
+
+### 7.1.3 <small>April 24, 2021</small> { id="7.1.3" }
+
+- Fixed #2586: Empty table of contents shown (7.1.2 regression)
+
+### 7.1.2 <small>April 18, 2021</small> { id="7.1.2" }
+
+- Fixed #2554: List markers sometimes overlap floated elements
+- Fixed #2563: Adding a class to a `h1` breaks the table of contents
+- Fixed #2566: Back-to-top button clickable when invisible
+
+### 7.1.1 <small>April 10, 2021</small> { id="7.1.1" }
+
+- Fixed #2501: Nested definition lists compound bottom margin
+- Fixed #2508: Switch `extracopyright` block to template variable
+- Fixed #2533: Search (and other parts) not working in Safari <14
+- Fixed #2538: Visual quirk when opening language selector
+
+### 7.1.0 <small>March 29, 2021</small> { id="7.1.0" }
+
+- Added support for back-to-top button
+- Added support for color palette toggle
+- Added latest release to repository info (GitHub)
+- Slight facelift of repository info (lighter fonts, spacing and icons)
+
+### 7.0.7 <small>March 28, 2021</small> { id="7.0.7" }
+
+- Updated Hungarian translations
+- Fixed #2466: Docker image not based on latest Python and Alpine
+- Fixed #2488: Inconsistent header shadow behavior
+- Fixed #2492: Inline code blocks in admonition titles missing background
+
+### 7.0.6 <small>March 14, 2021</small> { id="7.0.6" }
+
+- Added trailing slash to version selector URL
+- Added support for out-of-order anchors in table of contents
+- Added `extra.homepage` option to link logo to arbitrary URL
+- Improved security of Docker image (always update apk)
+- Fixed horizontal spacing for nested inline admonitions
+- Fixed text color of nested code blocks inside links
+- Fixed version selector to always use version title
+- Fixed logo link when using versioning with instant loading
+
+### 7.0.5 <small>March 7, 2021</small> { id="7.0.5" }
+
+- Added `extracopyright` block to allow for custom copyright info
+- Fixed evaluation of third-party scripts when using instant loading
+- Fixed edge cases when using instant loading without directory URLs
+- Fixed handling of version selector when using instant loading
+- Fixed regression with header title not being updated correctly
+- Fixed expanded sections not opening on first click (7.0.4 regression)
+
+### 7.0.4 <small>March 4, 2021</small> { id="7.0.4" }
+
+- Added Icelandic translations
+- Fixed #2386: Section close requires two clicks (navigation expansion)
+- Fixed console error when search is disabled (7.0.0 regression)
+- Fixed localsearch integration (7.0.0 regression)
+
+### 7.0.3 <small>February 26, 2021</small> { id="7.0.3" }
+
+- Fixed JavaScript errors in older browsers (target ES2020 -> ES2015)
+
+### 7.0.2 <small>February 25, 2021</small> { id="7.0.2" }
+
+- Fixed #2343: Invalid source map URLs for JS and CSS files
+- Fixed #2347: Version selector missing when using versioning
+
+### 7.0.1 <small>February 24, 2021</small> { id="7.0.1" }
+
+- Fixed #2334: Google Analytics triggers page view twice (7.0.0 regression)
+- Fixed #2336: Details bleed into inline admonitions
+- Fixed #2337: Images don't align correctly (7.0.0 regression)
+
+### 7.0.0 <small>February 22, 2021</small> { id="7.0.0" }
+
+- Added support for deploying multiple versions
+- Added support for integrating a language selector
+- Added support for rendering admonitions as inline blocks
+- Rewrite of the underlying reactive architecture
+- Removed Webpack in favor of reactive build strategy (-480 dependencies)
+- Fixed keyboard navigation for code blocks after content tabs switch
+
+### 6.2.8 <small>February 4, 2021</small> { id="6.2.8" }
+
+- Updated Japanese and Polish translations
+- Fixed #2261: Print dialog auto-closing when using instant loading
+
+### 6.2.7 <small>January 31, 2021</small> { id="6.2.7" }
+
+- Fixed #2251: Updated Docker image to latest Alpine Linux
+
+### 6.2.6 <small>January 26, 2021</small> { id="6.2.6" }
+
+- Added Bulgarian translations
+- Fixed #2233: Search not shown when using header autohiding
+
+### 6.2.5 <small>January 17, 2021</small> { id="6.2.5" }
+
+- Fixed syntax error in Swedish translations
+- Optimized navigation partials to improve build speed for huge docs
+
+### 6.2.4 <small>January 9, 2021</small> { id="6.2.4" }
+
+- Fixed #2156: Missing syntax highlighting for binary numbers
+- Fixed #2186: Disqus showing on 404 page
+
+### 6.2.3 <small>December 27, 2020</small> { id="6.2.3" }
+
+- Added back hidden overflow on root container
+- Fixed #2142: MathJax formulas sometimes have vertical scrollbars
+
+### 6.2.2 <small>December 22, 2020</small> { id="6.2.2" }
+
+- Removed Markdown version range limit (6.2.0 regression)
+
+### 6.2.1 <small>December 22, 2020</small> { id="6.2.1" }
+
+- Fixed all import and asset paths in templates (6.2.0 regression)
+- Downgraded webpack-asset-manifest-plugin - broke all asset paths
+
+### 6.2.0 <small>December 22, 2020</small> { id="6.2.0" }
+
+- Added support for navigation sections
+- Added support for navigation expansion
+- Added support for integrating table of contents into navigation
+- Added support for autohiding header on scroll
+- Added support for hiding navigation and table of contents per page
+- Added support for arbitrary items in navigation tabs
+- Refactored navigation tabs to simplify grouping behavior
+- Fixed anchor offset for permalinks in Safari (partial revert)
+- Fixed #2098: Active tab sometimes not highlighted correctly
+- Improved appearance for horizontal rulers
+- Improved Spanish and Swedish translations
+
+### 6.1.7 <small>December 6, 2020</small> { id="6.1.7" }
+
+- Fixed #2081: Fixed stats for private GitHub repositories
+- Fixed alignment for admonition icon alignment for right-to-left languages
+
+### 6.1.6 <small>November 22, 2020</small> { id="6.1.6" }
+
+- Fixed #2048: Math formulas show scrollbars (Windows)
+
+### 6.1.5 <small>November 15, 2020</small> { id="6.1.5" }
+
+- Fixed search reset button not showing/hiding correctly
+
+### 6.1.4 <small>November 7, 2020</small> { id="6.1.4" }
+
+- Fixed sidebar jitter when scrolling footer into view
+
+### 6.1.3 <small>November 5, 2020</small> { id="6.1.3" }
+
+- Added support for keywords `meta` tag
+- Fixed #2027: Line numbers don't scale with smaller font size
+- Fixed link colors for black and white on `slate` color scheme
+- Removed focus outline on scrolling code blocks for pointer devices
+
+### 6.1.2 <small>October 31, 2020</small> { id="6.1.2" }
+
+- Fixed sizing of icons in admonitions, task lists, etc. (6.1.1 regression)
+
+### 6.1.1 <small>October 31, 2020</small> { id="6.1.1" }
+
+- Fixed #2019: Page title not correctly updated when using instant loading
+
+### 6.1.0 <small>October 17, 2020</small> { id="6.1.0" }
+
+- Fixed #1973: Added support for printing in dark mode
+- Fixed #1974: Added support for printing content tabs
+- Fixed #1995: Improved customizability of details extension
+
+### 6.0.2 <small>October 4, 2020</small> { id="6.0.2" }
+
+- Added Georgian translations
+- Added escaping for link `title` attributes where necessary
+- Fixed #1956: Pages with whitespace in names have invalid links in search
+- Removed unnecessary (duplicated) link `title` attributes
+
+### 6.0.1 <small>September 26, 2020</small> { id="6.0.1" }
+
+- Fixed stemmer support for `file://` protocol through `iframe-worker`
+- Fixed details marker showing for search result in Firefox
+- Fixed tabbing behavior when search query is not empty
+- Switched TypeScript compilation target to ES2015
+- Reduced size of JavaScript by 30% (`176kb` → `124kb`)
+- Removed `mkdocs` and `readthedocs` themes from Docker image
+
+### 6.0.0 <small>September 25, 2020</small> { id="6.0.0" }
+
+- Improved search result look and feel
+- Improved search result stability while typing
+- Improved search result grouping (pages + headings)
+- Improved search result relevance and scoring
+- Added display of missing query terms to search results
+- Reduced size of vendor bundle by 25% (`84kb` → `67kb`)
+- Reduced size of the Docker image to improve CI build performance
+- Removed hero partial in favor of custom implementation
+- Removed deprecated front matter features
+
+---
+
+### 5.5.14 <small>September 23, 2020</small> { id="5.5.14" }
+
+- Improved spacing around image captions
+- Fixed #1939: Long tables cause header overlap in print view
+
+### 5.5.13 <small>September 19, 2020</small> { id="5.5.13" }
+
+- Improved abbreviations on touch devices
+
+### 5.5.12 <small>August 31, 2020</small> { id="5.5.12" }
+
+- Fixed #1638: occasional `404` for images when using instant loading
+
+### 5.5.11 <small>August 28, 2020</small> { id="5.5.11" }
+
+- Fixed Disqus integration, as the minifier killed the config
+
+### 5.5.10 <small>August 28, 2020</small> { id="5.5.10" }
+
+- Improved rendering by moving Disqus integration after page load
+- Fixed #1887: Moved navigation icons to CSS to reduce size of HTML
+
+### 5.5.9 <small>August 26, 2020</small> { id="5.5.9" }
+
+- Added Esperanto translations
+- Fixed #1884: External links not included in navigation tabs
+
+### 5.5.8 <small>August 23, 2020</small> { id="5.5.8" }
+
+- Removed focus outline on `details` and content tabs for pointer devices
+- Improved accessibility of content tabs (now navigable via arrow keys)
+- Fixed #1877: `404` on search index when search is disabled
+- Fixed some memleaks in observable subscriptions
+- Fixed color definitions for `theme-color` meta tag
+
+### 5.5.7 <small>August 16, 2020</small> { id="5.5.7" }
+
+- Improved contrast ratio to 4.5:1 for syntax highlighting
+- Improved contrast ratio to 4.5:1 for table of contents
+
+### 5.5.6 <small>August 12, 2020</small> { id="5.5.6" }
+
+- Switched base template for `404.html` to `main.html`
+- Fixed #1864: GitHub organisation stats not loading
+
+### 5.5.5 <small>August 11, 2020</small> { id="5.5.5" }
+
+- Fixed missing vendor and worker distribution files
+
+### 5.5.4 <small>August 11, 2020</small> { id="5.5.4" }
+
+- Added support for sortable data tables
+
+### 5.5.3 <small>August 4, 2020</small> { id="5.5.3" }
+
+- Fixed search for languages other than English (5.5.1 regression)
+
+### 5.5.2 <small>August 3, 2020</small> { id="5.5.2" }
+
+- Improved highlight colors and spacing for `ins`, `del` and `mark`
+- Changed some keyboard symbols for better equivalents
+- Removed focus `outline` for details and code blocks on touch devices
+- Fixed margins for admonitions (5.5.1 regression)
+- Fixed too small content tab labels (5.5.1 regression)
+- Fixed icon repeating for custom admonition icons
+
+### 5.5.1 <small>August 1, 2020</small> { id="5.5.1" }
+
+- Improved typesetting by basing `font-size` and spacings on `em`
+- Improved print view by slightly scaling down `font-size`
+- Changed custom site title (metadata) to be suffixed with site name
+- Fixed top- and bottom spacing of paragraphs inside table cells
+
+### 5.5.0 <small>July 24, 2020</small> { id="5.5.0" }
+
+- Rewrite of entire documentation
+- Rewrite of syntax highlighting to be customizable with CSS variables
+- Improved syntax highlighting to work with light and dark theme
+- Improved `slate` color scheme to be more customizable and easier on the eyes
+- Added licenses of icon sets to distribution files
+- Fixed stale document titles in Google Analytics when using instant loading
+- Fixed width of previous and next footer links for tablet and above
+- Fixed issues with top scroll margin for footnotes
+- Fixed top margin for tabbed content when using a JavaScript highlighter
+- Deprecated metadata-based redirects, source links and heroes
+
+### 5.4.0 <small>June 29, 2020</small> { id="5.4.0" }
+
+- Added support to wrap searches in quotes to switch from `OR` to `AND`
+- Fixed highlighting of numbers in search results
+
+### 5.3.3 <small>June 24, 2020</small> { id="5.3.3" }
+
+- Added Bengali translations
+- Fixed #1773: Search for numbers does not return any result (regression)
+
+### 5.3.2 <small>June 21, 2020</small> { id="5.3.2" }
+
+- Improved search typeahead experience with non-Latin characters
+- Fixed #1753: Japanese search doesn't work anymore
+
+### 5.3.1 <small>June 20, 2020</small> { id="5.3.1" }
+
+- Fixed #1761: Duplication of search worker when subscribing to observable
+
+### 5.3.0 <small>June 15, 2020</small> { id="5.3.0" }
+
+- Added support for color schemes based on user preference
+- Fixed #1755: Tokenizer separator setting ignored
+
+### 5.2.3 <small>June 6, 2020</small> { id="5.2.3" }
+
+- Improved search typeahead behavior for some languages (`de`, `fr`, ...)
+- Improved styles for scrollbars on Firefox
+- Fixed #1741: Removed `preconnect` hint for Google Analytics
+
+### 5.2.2 <small>May 26, 2020</small> { id="5.2.2" }
+
+- Fixed #1728: Legacy Edge doesn't support `deg` values in `hsla` colors
+
+### 5.2.1 <small>May 22, 2020</small> { id="5.2.1" }
+
+- Fixed color of links in table headers, e.g. footnotes
+- Fixed color scheme not being applied without primary or accent color
+- Fixed hover delay for links inside code blocks
+
+### 5.2.0 <small>May 18, 2020</small> { id="5.2.0" }
+
+- Added color schemes implementation + dark mode
+- Fixed #1583: Missing option for separate link colors
+
+### 5.1.7 <small>May 16, 2020</small> { id="5.1.7" }
+
+- Added keyboard focus support for overflowing code blocks
+- Fixed #1696: Infinite loop in some cases when using instant loading
+
+### 5.1.6 <small>May 9, 2020</small> { id="5.1.6" }
+
+- Added Burmese translations
+- Added general anchor offset solution using `scroll-margin-top`
+- Fixed #1653: Instant loading shouldn't intercept links to `*.html` files
+
+### 5.1.5 <small>May 3, 2020</small> { id="5.1.5" }
+
+- Added `name` attribute for social links to set link `title`
+- Fixed #1623: Allow arbitrary links in social links
+- Fixed #1664: Height of `iframe` is not adjustable
+- Fixed #1667: Sidebars are scrolled to bottom on load (bug in Chrome 81+)
+
+### 5.1.4 <small>April 30, 2020</small> { id="5.1.4" }
+
+- Switched to [@mdi/svg] Material Design icon package
+- Fixed #1655: Navigation may disappear after switching viewports
+- Fixed #1659: Unnecessary scrollbar for search results on Windows
+- Fixed occasional distortions for images with explicit dimensions
+- Fixed errors in German translations
+
+ [@mdi/svg]: https://github.com/Templarian/MaterialDesign-SVG
+
+### 5.1.3 <small>April 26, 2020</small> { id="5.1.3" }
+
+- Fixed overflowing content area after switch to flexbox
+
+### 5.1.2 <small>April 26, 2020</small> { id="5.1.2" }
+
+- Added status information to search observable
+- Added status information to search modal
+- Removed announcement bar from print media
+- Removed media query packing logic due to race conditions
+- Fixed #1520: Gracefully disable search on `file://` if Worker fails
+- Fixed re-submission of query after search is initialized
+- Fixed jitter of sidebars on all browsers by switching to `sticky`
+
+### 5.1.1 <small>April 17, 2020</small> { id="5.1.1" }
+
+- Added new FontAwesome icons
+- Fixed #1609: Instant loading doesn't honor `target=_blank`
+- Fixed GitHub stars count rounding errors
+- Fixed GitLab stars count retrieval
+
+### 5.1.0 <small>April 12, 2020</small> { id="5.1.0" }
+
+- Added support for icons from Markdown through [mkdocs-material-extensions]
+
+ [mkdocs-material-extensions]: https://github.com/facelessuser/mkdocs-material-extensions
+
+### 5.0.2 <small>April 10, 2020</small> { id="5.0.2" }
+
+- Added CSS source maps to distribution files
+- Fixed errors in Chinese (Traditional) translations
+- Fixed creation of stale directory on installation from git
+- Improved overflow scrolling behavior on iOS (reduced bundle size by `4kb`)
+
+### 5.0.1 <small>April 7, 2020</small> { id="5.0.1" }
+
+- Fixed syntax error in Spanish translation
+
+### 5.0.0 <small>April 7, 2020</small> { id="5.0.0" }
+
+- Reactive architecture – try `app.dialog$.next("Hi!")` in the console
+- Instant loading – make Material behave like a Single Page Application
+- Improved CSS customization with CSS variables – set your brand's colors
+- Improved CSS resilience, e.g. proper sidebar locking for customized headers
+- Improved icon integration and configuration – now including over 5k icons
+- Added possibility to use any icon for logo, repository and social links
+- Search UI does not freeze anymore (moved to web worker)
+- Search index built only once when using instant loading
+- Improved extensible keyboard handling
+- Support for prebuilt search indexes
+- Support for displaying stars and forks for GitLab repositories
+- Support for scroll snapping of sidebars and search results
+- Reduced HTML and CSS footprint due to deprecation of Internet Explorer support
+- Slight facelifting of some UI elements (admonitions, tables, ...)
+
+### 4.6.3 <small>February 14, 2020</small> { id="4.6.3" }
+
+- Removed optional third-party plugins from `requirements.txt`
+- Updated Docker image to contain all supported third-party plugins
+
+### 4.6.2 <small>February 8, 2020</small> { id="4.6.2" }
+
+- Added Romanian translations
+- Fixed #1451: Inconsistent spacing for fenced code blocks
+
+### 4.6.1 <small>February 8, 2020</small> { id="4.6.1" }
+
+- Fixed #1324: Metadata author only rendering first character
+- Fixed #1393: Set `tabindex` to `0` for skip to content link
+- Fixed code blocks after Markdown 3.2 release
+- Fixed errors in Japanese translations
+- Improved Google Lighthouse score
+
+### 4.6.0 <small>December 11, 2019</small> { id="4.6.0" }
+
+- Added support for [git-revision-date-localized-plugin]
+- Fixed invalid character in Google Fonts URL
+
+ [git-revision-date-localized-plugin]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
+
+### 4.5.1 <small>December 2, 2019</small> { id="4.5.1" }
+
+- Added Thai translations
+- Fixed missing assets in GitHub release `.zip` and `.tar.gz`
+
+### 4.5.0 <small>November 16, 2019</small> { id="4.5.0" }
+
+- Fixed #1330: Upgraded EmojiOne to Tweomji due to licensing issues
+- Fixed #1339: Temporarily pinned PyMdown and Markdown due to
+- Fixed errors in Greek translations
+- Improved GitHub statistics retrieval
+
+### 4.4.3 <small>October 3, 2019</small> { id="4.4.3" }
+
+- Added Estonian translations
+- Fixed removal of copyright banners in minified JavaScript
+- Removed unnecessary title attributes from links in table of contents
+
+### 4.4.2 <small>August 27, 2019</small> { id="4.4.2" }
+
+- Added Afrikaans translations
+- Fixed broken page title when `h1` contained HTML tags
+- Improved accessibility for IE users
+- Removed unnecessary `title` attributes from links in navigation
+
+### 4.4.1 <small>August 22, 2019</small> { id="4.4.1" }
+
+- Added support for `black` as a primary color
+- Fixed broken footer bar when `h1` contained HTML tags
+
+### 4.4.0 <small>June 15, 2019</small> { id="4.4.0" }
+
+- Added Slovenian translations
+- Reverted template minification in favor of `mkdocs-minify-plugin`
+- Fixed #1114: Tabs don't reappear when default `font-size` is smaller than `16`
+
+### 4.3.1 <small>May 23, 2019</small> { id="4.3.1" }
+
+- Fixed spelling error in Danish translations
+
+### 4.3.0 <small>May 17, 2019</small> { id="4.3.0" }
+
+- Added support for changing header through metadata title property
+- Added `font-display: swap` to Google Font loading logic
+- Removed whitespace from templates, saving `4kb` (`.7kb` gzipped) per request
+- Fixed alignment of repository icons on tablet and desktop
+
+### 4.2.0 <small>April 28, 2019</small> { id="4.2.0" }
+
+- Added Norwegian (Nynorsk) translations
+- Fixed loss of focus in non-form input elements due to search hotkeys
+- Fixed #1067: Search hotkeys not working for mobile/tablet screensize
+- Fixed #1068: Search not correctly aligned for tablet screensize
+
+### 4.1.2 <small>April 16, 2019</small> { id="4.1.2" }
+
+- Fixed #1072: HTML tags appearing in navigation link titles
+
+### 4.1.1 <small>March 28, 2019</small> { id="4.1.1" }
+
+- Fixed minor CSS errors detected during validation
+
+### 4.1.0 <small>March 22, 2019</small> { id="4.1.0" }
+
+- Fixed #1023: Search for Asian languages broken after Lunr.js update
+- Fixed #1026: contenteditable elements loose focus on hotkeys
+
+### 4.0.2 <small>March 1, 2019</small> { id="4.0.2" }
+
+- Fixed #1012: HTML character entities appear in search result titles
+
+### 4.0.1 <small>February 13, 2019</small> { id="4.0.1" }
+
+- Fixed #762, #816: Glitch in sidebar when collapsing items
+- Fixed #869: Automatically expand details before printing
+
+### 4.0.0 <small>February 13, 2019</small> { id="4.0.0" }
+
+- Added background on hover for table rows
+- Removed Google Tag Manager and reverted to Google Analytics
+- Removed blocks in partials - Jinja doesn't support them
+- Fixed #911: Chrome breaks layout if system language is Chinese (**BREAKING**)
+- Fixed #976: Removed FastClick
+
+---
+
+### 3.3.0 <small>January 29, 2019</small> { id="3.3.0" }
+
+- Moved Google Analytics integration into `head` using Google Tag Manager
+- Fixed #972: Unicode slugifier breaks table of contents blur on scroll
+- Fixed #974: Additional links in table of contents break blur on scroll
+
+### 3.2.0 <small>December 28, 2018</small> { id="3.2.0" }
+
+- Added support for redirects using metadata refresh
+- Fixed #921: Load Google Analytics snippet asynchronously
+
+### 3.1.0 <small>November 17, 2018</small> { id="3.1.0" }
+
+- Added support for Progressive Web App Manifest
+- Fixed #915: Search bug in Safari (upgraded Lunr.js)
+
+### 3.0.6 <small>October 26, 2018</small> { id="3.0.6" }
+
+- Added Taiwanese translations
+- Fixed #906: JavaScript code blocks evaluated in search results
+
+### 3.0.5 <small>October 23, 2018</small> { id="3.0.5" }
+
+- Added Croatian and Indonesian translations
+- Fixed #899: Skip-to-content link invalid from 2nd level on
+- Fixed #902: Missing URL filter in footer for FontAwesome link
+
+### 3.0.4 <small>September 3, 2018</small> { id="3.0.4" }
+
+- Updated Dutch translations
+- Fixed #856: Removed preconnect meta tag if Google Fonts are disabled
+
+### 3.0.3 <small>August 7, 2018</small> { id="3.0.3" }
+
+- Fixed #841: Additional path levels for extra CSS and JS
+
+### 3.0.2 <small>August 6, 2018</small> { id="3.0.2" }
+
+- Fixed #839: Lunr.js stemmer imports incorrect
+
+### 3.0.1 <small>August 5, 2018</small> { id="3.0.1" }
+
+- Fixed #838: Search result links incorrect
+
+### 3.0.0 <small>August 5, 2018</small> { id="3.0.0" }
+
+- Upgraded MkDocs to 1.0 (**BREAKING**)
+- Upgraded Python in official Docker image to 3.6
+- Added Serbian and Serbo-Croatian translations
+
+---
+
+### 2.9.4 <small>July 29, 2018</small> { id="2.9.4" }
+
+- Fixed build error after MkDocs upgrade
+
+### 2.9.3 <small>July 29, 2018</small> { id="2.9.3" }
+
+- Added link to home for logo in drawer
+- Fixed dependency problems between MkDocs and Tornado
+
+### 2.9.2 <small>June 29, 2018</small> { id="2.9.2" }
+
+- Added Hindi and Czech translations
+
+### 2.9.1 <small>June 18, 2018</small> { id="2.9.1" }
+
+- Added support for different spellings for theme color
+- Fixed #799: Added support for webfont minification in production
+- Fixed #800: Added `.highlighttable` as an alias for `.codehilitetable`
+
+### 2.9.0 <small>June 13, 2018</small> { id="2.9.0" }
+
+- Added support for theme color on Android
+- Fixed #796: Rendering of nested tabbed code blocks
+
+### 2.8.0 <small>June 10, 2018</small> { id="2.8.0" }
+
+- Added support for grouping code blocks with tabs
+- Added Material and FontAwesome icon fonts to distribution files (GDPR)
+- Added note on compliance with GDPR
+- Added Slovak translations
+- Fixed #790: Prefixed `id` attributes with `__` to avoid name clashes
+
+### 2.7.3 <small>April 26, 2018</small> { id="2.7.3" }
+
+- Added Finnish translations
+
+### 2.7.2 <small>April 9, 2018</small> { id="2.7.2" }
+
+- Fixed rendering issue for `details` on Edge
+
+### 2.7.1 <small>March 21, 2018</small> { id="2.7.1" }
+
+- Added Galician translations
+- Fixed #730: Scroll chasing error on home page if Disqus is enabled
+- Fixed #736: Reset drawer and search upon back button invocation
+
+### 2.7.0 <small>March 6, 2018</small> { id="2.7.0" }
+
+- Added ability to set absolute URL for logo
+- Added Hebrew translations
+
+### 2.6.6 <small>February 22, 2018</small> { id="2.6.6" }
+
+- Added preconnect for Google Fonts for faster loading
+- Fixed #710: With tabs sidebar disappears if JavaScript is not available
+
+### 2.6.5 <small>February 22, 2018</small> { id="2.6.5" }
+
+- Reverted `--dev-addr` flag removal from `Dockerfile`
+
+### 2.6.4 <small>February 21, 2018</small> { id="2.6.4" }
+
+- Added Catalan translations
+- Fixed incorrect margins for buttons in Firefox and Safari
+- Replaced package manager `yarn` with `npm 5.6`
+- Reverted GitHub stars rounding method
+- Removed `--dev-addr` flag from `Dockerfile` for Windows compatibility
+
+### 2.6.3 <small>February 18, 2018</small> { id="2.6.3" }
+
+- Added Vietnamese translations
+
+### 2.6.2 <small>February 12, 2018</small> { id="2.6.2" }
+
+- Added Arabic translations
+- Fixed incorrect rounding of amount of GitHub stars
+- Fixed double-layered borders for tables
+
+### 2.6.1 <small>February 11, 2018</small> { id="2.6.1" }
+
+- Added ability to override Disqus integration using metadata
+- Fixed #690: Duplicate slashes in source file URLs
+- Fixed #696: Active page highlight not working with default palette
+- Adjusted German translations
+
+### 2.6.0 <small>February 2, 2018</small> { id="2.6.0" }
+
+- Moved default search configuration to default translation (English)
+- Added support to automatically set text direction from translation
+- Added support to disable search stop word filter in translation
+- Added support to disable search trimmer in translation
+- Added Persian translations
+- Fixed support for Polish search
+- Fixed disappearing GitHub, GitLab and Bitbucket repository icons
+
+### 2.5.5 <small>January 31, 2018</small> { id="2.5.5" }
+
+- Added Hungarian translations
+
+### 2.5.4 <small>January 29, 2018</small> { id="2.5.4" }
+
+- Fixed #683: `gh-deploy` fails inside Docker
+
+### 2.5.3 <small>January 25, 2018</small> { id="2.5.3" }
+
+- Added Ukrainian translations
+
+### 2.5.2 <small>January 22, 2018</small> { id="2.5.2" }
+
+- Added default search language mappings for all localizations
+- Fixed #673: Error loading non-existent search language
+- Fixed #675: Uncaught reference error when search plugin disabled
+
+### 2.5.1 <small>January 20, 2018</small> { id="2.5.1" }
+
+- Fixed permalink for main headline
+- Improved missing translation handling with English as a fallback
+- Improved accessibility with skip-to-content link
+
+### 2.5.0 <small>January 13, 2018</small> { id="2.5.0" }
+
+- Added support for right-to-left languages
+
+### 2.4.0 <small>January 11, 2018</small> { id="2.4.0" }
+
+- Added focus state for clipboard buttons
+- Fixed #400: Search bar steals tab focus
+- Fixed search not closing on ++enter++ when result is selected
+- Fixed search not closing when losing focus due to ++tab++
+- Fixed collapsed navigation links getting focus
+- Fixed `outline` being cut off on ++tab++ focus of navigation links
+- Fixed bug with first search result navigation being ignored
+- Removed search result navigation via ++tab++ (use ++up++ and ++down++)
+- Removed `outline` resets for links
+- Improved general tabbing behavior on desktop
+
+### 2.3.0 <small>January 9, 2018</small> { id="2.3.0" }
+
+- Added `example` (synonym: `snippet`) style for admonitions
+- Added synonym `abstract` for `summary` style for admonitions
+
+### 2.2.6 <small>December 27, 2017</small> { id="2.2.6" }
+
+- Added Turkish translations
+- Fixed unclickable area below header in case JavaScript is not available
+
+### 2.2.5 <small>December 18, 2017</small> { id="2.2.5" }
+
+- Fixed #639: Broken default favicon
+
+### 2.2.4 <small>December 18, 2017</small> { id="2.2.4" }
+
+- Fixed #638: Build breaks with Jinja < 2.9
+
+### 2.2.3 <small>December 13, 2017</small> { id="2.2.3" }
+
+- Fixed #630: Admonition sets padding on any last child
+- Adjusted Chinese (Traditional) translations
+
+### 2.2.2 <small>December 8, 2017</small> { id="2.2.2" }
+
+- Added Dutch translations
+- Adjusted targeted link and footnote offsets
+- Simplified admonition styles and fixed padding bug
+
+### 2.2.1 <small>December 2, 2017</small> { id="2.2.1" }
+
+- Fixed #616: Minor styling error with title-only admonitions
+- Removed border for table of contents and improved spacing
+
+### 2.2.0 <small>November 22, 2017</small> { id="2.2.0" }
+
+- Added support for hero teaser
+- Added Portuguese translations
+- Fixed #586: Footnote backref target offset regression
+- Fixed #605: Search stemmers not correctly loaded
+
+### 2.1.1 <small>November 21, 2017</small> { id="2.1.1" }
+
+- Replaced deprecated `babel-preset-es2015` with `babel-preset-env`
+- Refactored Gulp build pipeline with Webpack
+- Removed right border on sidebars
+- Fixed broken color transition on header
+
+### 2.1.0 <small>November 19, 2017</small> { id="2.1.0" }
+
+- Added support for `white` as a primary color
+- Added support for sliding site name and title
+- Fixed redundant clipboard button when using line numbers on code blocks
+- Improved header appearance by making it taller
+- Improved tabs appearance
+- Improved CSS customizability by leveraging inheritance
+- Removed scroll shadows via `background-attachment`
+
+### 2.0.4 <small>November 5, 2017</small> { id="2.0.4" }
+
+- Fixed `details` not opening with footnote reference
+
+### 2.0.3 <small>November 5, 2017</small> { id="2.0.3" }
+
+- Added Japanese translations
+- Fixed #540: Jumping to anchor inside `details` doesn't open it
+- Fixed active link colors in footer
+
+### 2.0.2 <small>November 1, 2017</small> { id="2.0.2" }
+
+- Added Russian translations
+- Fixed #542: Horizontal scrollbar between `1220px` and `1234px`
+- Fixed #553: Metadata values only rendering first character
+- Fixed #558: Flash of unstyled content
+- Fixed favicon regression caused by deprecation upstream
+
+### 2.0.1 <small>October 31, 2017</small> { id="2.0.1" }
+
+- Fixed error when initializing search
+- Fixed styles for link to edit the current page
+- Fixed styles on nested admonition in details
+
+### 2.0.0 <small>October 31, 2017</small> { id="2.0.0" }
+
+- Upgraded MkDocs to 0.17.1 (__BREAKING__)
+- Added support for easier configuration of search tokenizer
+- Added support to disable search
+- Added Korean translations
+
+---
+
+### 1.12.2 <small>October 26, 2017</small> { id="1.12.2" }
+
+- Added Italian, Norwegian, French and Chinese translations
+
+### 1.12.1 <small>October 22, 2017</small> { id="1.12.1" }
+
+- Added Polish, Swedish and Spanish translations
+- Improved downward compatibility with custom partials
+- Temporarily pinned MkDocs version within Docker image to 0.16.3
+- Fixed #519: Missing theme configuration file
+
+### 1.12.0 <small>October 20, 2017</small> { id="1.12.0" }
+
+- Added support for setting language(s) via `mkdocs.yml`
+- Added support for default localization
+- Added German and Danish translations
+- Fixed #374: Search bar misalignment on big screens
+
+### 1.11.0 <small>October 19, 2017</small> { id="1.11.0" }
+
+- Added localization to clipboard
+- Refactored localization logic
+
+### 1.10.4 <small>October 18, 2017</small> { id="1.10.4" }
+
+- Improved print styles of code blocks
+- Improved search UX (don't close on enter if no selection)
+- Fixed #495: Vertical scrollbar on short pages
+
+### 1.10.3 <small>October 11, 2017</small> { id="1.10.3" }
+
+- Fixed #484: Vertical scrollbar on some MathJax formulas
+- Fixed #483: Footnote backref target offset regression
+
+### 1.10.2 <small>October 6, 2017</small> { id="1.10.2" }
+
+- Fixed #468: Sidebar shows scrollbar if content is shorter (in Safari)
+
+### 1.10.1 <small>September 14, 2017</small> { id="1.10.1" }
+
+- Fixed #455: Bold code blocks rendered with normal font weight
+
+### 1.10.0 <small>September 1, 2017</small> { id="1.10.0" }
+
+- Added support to make logo default icon configurable
+- Fixed uninitialized overflow scrolling on main pane for iOS
+- Fixed error in mobile navigation in case JavaScript is not available
+- Fixed incorrect color transition for nested panes in mobile navigation
+- Improved checkbox styles for Tasklist from PyMdown Extension package
+
+### 1.9.0 <small>August 29, 2017</small> { id="1.9.0" }
+
+- Added `info` (synonym: `todo`) style for admonitions
+- Added `question` (synonym: `help`, `faq`) style for admonitions
+- Added support for Details from PyMdown Extensions package
+- Improved admonition styles to match details
+- Improved styles for social links in footer
+- Replaced ligatures with Unicode code points to avoid broken layout
+- Upgraded PyMdown Extensions package dependency to >= 3.4
+
+### 1.8.1 <small>August 7, 2017</small> { id="1.8.1" }
+
+- Fixed #421: Missing pagination for GitHub API
+
+### 1.8.0 <small>August 2, 2017</small> { id="1.8.0" }
+
+- Added support for lazy-loading of search results for better performance
+- Added support for customization of search tokenizer/separator
+- Fixed #424: Search doesn't handle capital letters anymore
+- Fixed #419: Search doesn't work on whole words
+
+### 1.7.5 <small>July 25, 2017</small> { id="1.7.5" }
+
+- Fixed #398: Forms broken due to search shortcuts
+- Improved search overall user experience
+- Improved search matching and highlighting
+- Improved search accessibility
+
+### 1.7.4 <small>June 21, 2017</small> { id="1.7.4" }
+
+- Fixed functional link colors in table of contents for active palette
+- Fixed #368: Compatibility issues with IE11
+
+### 1.7.3 <small>June 7, 2017</small> { id="1.7.3" }
+
+- Fixed error when setting language to Japanese for site search
+
+### 1.7.2 <small>June 6, 2017</small> { id="1.7.2" }
+
+- Fixed offset of search box when `repo_url` is not set
+- Fixed non-disappearing tooltip
+
+### 1.7.1 <small>June 1, 2017</small> { id="1.7.1" }
+
+- Fixed wrong `z-index` order of header, overlay and drawer
+- Fixed wrong offset of targeted footnote back references
+
+### 1.7.0 <small>June 1, 2017</small> { id="1.7.0" }
+
+- Added "copy to clipboard" buttons to code blocks
+- Added support for multilingual site search
+- Fixed search term highlighting for non-latin languages
+
+### 1.6.4 <small>May 24, 2017</small> { id="1.6.4" }
+
+- Fixed #337: JavaScript error for GitHub organization URLs
+
+### 1.6.3 <small>May 16, 2017</small> { id="1.6.3" }
+
+- Fixed #329: Broken source stats for private or unknown GitHub repos
+
+### 1.6.2 <small>May 15, 2017</small> { id="1.6.2" }
+
+- Fixed #316: Fatal error for git clone on Windows
+- Fixed #320: Chrome 58 creates double underline for `abbr` tags
+- Fixed #323: Ligatures rendered inside code blocks
+- Fixed miscalculated sidebar height due to missing margin collapse
+- Changed deprecated MathJax CDN to Cloudflare
+
+### 1.6.1 <small>April 23, 2017</small> { id="1.6.1" }
+
+- Fixed following of active/focused element if search input is focused
+- Fixed layer order of search component elements
+
+### 1.6.0 <small>April 22, 2017</small> { id="1.6.0" }
+
+- Added build test for Docker image on Travis
+- Added search overlay for better user experience (focus)
+- Added language from localizations to `html` tag
+- Fixed #270: source links broken for absolute URLs
+- Fixed missing top spacing for first targeted element in content
+- Fixed too small footnote divider when using larger font sizes
+
+### 1.5.5 <small>April 20, 2017</small> { id="1.5.5" }
+
+- Fixed #282: Browser search (<kbd>Meta</kbd>+<kbd>F</kbd>) is hijacked
+
+### 1.5.4 <small>April 8, 2017</small> { id="1.5.4" }
+
+- Fixed broken highlighting for two or more search terms
+- Fixed missing search results when only a `h1` is present
+- Fixed unresponsive overlay on Android
+
+### 1.5.3 <small>April 7, 2017</small> { id="1.5.3" }
+
+- Fixed deprecated calls for template variables
+- Fixed wrong palette color for focused search result
+- Fixed JavaScript errors on 404 page
+- Fixed missing top spacing on 404 page
+- Fixed missing right spacing on overflow of source container
+
+### 1.5.2 <small>April 5, 2017</small> { id="1.5.2" }
+
+- Added requirements as explicit dependencies in `setup.py`
+- Fixed non-synchronized transitions in search form
+
+### 1.5.1 <small>March 30, 2017</small> { id="1.5.1" }
+
+- Fixed rendering and offset of targeted footnotes
+- Fixed #238: Link on logo is not set to `site_url`
+
+### 1.5.0 <small>March 24, 2017</small> { id="1.5.0" }
+
+- Added support for localization of search placeholder
+- Added keyboard events for quick access of search
+- Added keyboard events for search control
+- Added opacity on hover for search buttons
+- Added git hook to skip CI build on non-src changes
+- Fixed non-resetting search placeholder when input is cleared
+- Fixed error for unescaped parentheses in search term
+- Fixed #229: Button to clear search missing
+- Fixed #231: Escape key doesn't exit search
+- Removed old-style figures from font feature settings
+
+### 1.4.1 <small>March 16, 2017</small> { id="1.4.1" }
+
+- Fixed invalid destructuring attempt on NodeList (in Safari, Edge, IE)
+
+### 1.4.0 <small>March 16, 2017</small> { id="1.4.0" }
+
+- Added support for grouping searched sections by documents
+- Added support for highlighting of search terms
+- Added support for localization of search results
+- Fixed #216: table of contents icon doesn't show if `h1` is not present
+- Reworked style and layout of search results for better usability
+
+### 1.3.0 <small>March 11, 2017</small> { id="1.3.0" }
+
+- Added support for page-specific title and description using metadata
+- Added support for linking source files to documentation
+- Fixed jitter and offset of sidebar when zooming browser
+- Fixed incorrectly initialized tablet sidebar height
+- Fixed regression for #1: GitHub stars break if `repo_url` ends with a `/`
+- Fixed undesired white line below copyright footer due to base font scaling
+- Fixed issue with whitespace in path for scripts
+- Fixed #205: support non-fixed (static) header
+- Refactored footnote references for better visibility
+- Reduced repaints to a minimum for non-tabs configuration
+- Reduced contrast of edit button (slightly)
+
+### 1.2.0 <small>March 3, 2017</small> { id="1.2.0" }
+
+- Added `quote` (synonym: `cite`) style for admonitions
+- Added help message to build pipeline
+- Fixed wrong navigation link colors when applying palette
+- Fixed #197: Link missing in tabs navigation on deeply nested items
+- Removed unnecessary dev dependencies
+
+### 1.1.1 <small>February 26, 2017</small> { id="1.1.1" }
+
+- Fixed incorrectly displayed nested lists when using tabs
+
+### 1.1.0 <small>February 26, 2017</small> { id="1.1.0" }
+
+- Added tabs navigation feature (optional)
+- Added Disqus integration (optional)
+- Added a high resolution Favicon with the new logo
+- Added static type checking using Facebook's Flow
+- Fixed #173: Dictionary elements have no bottom spacing
+- Fixed #175: Tables cannot be set to 100% width
+- Fixed race conditions in build related to asset revisioning
+- Fixed accidentally re-introduced Permalink on top-level headline
+- Fixed alignment of logo in drawer on IE11
+- Refactored styles related to tables
+- Refactored and automated Docker build and PyPI release
+- Refactored build scripts
+
+### 1.0.5 <small>February 18, 2017</small> { id="1.0.5" }
+
+- Fixed #153: Sidebar flows out of constrained area in Chrome 56
+- Fixed #159: Footer jitter due to JavaScript if content is short
+
+### 1.0.4 <small>February 16, 2017</small> { id="1.0.4" }
+
+- Fixed #142: Documentation build errors if `h1` is defined as raw HTML
+- Fixed #164: PyPI release does not build and install
+- Fixed offsets of targeted headlines
+- Increased sidebar font size by `0.12rem`
+
+### 1.0.3 <small>January 22, 2017</small> { id="1.0.3" }
+
+- Fixed #117: Table of contents items don't blur on fast scrolling
+- Refactored sidebar positioning logic
+- Further reduction of repaints
+
+### 1.0.2 <small>January 15, 2017</small> { id="1.0.2" }
+
+- Fixed #108: Horizontal scrollbar in content area
+
+### 1.0.1 <small>January 14, 2017</small> { id="1.0.1" }
+
+- Fixed massive repaints happening when scrolling
+- Fixed footer back reference positions in case of overflow
+- Fixed header logo from showing when the menu icon is rendered
+- Changed scrollbar behavior to only show when content overflows
+
+### 1.0.0 <small>January 13, 2017</small> { id="1.0.0" }
+
+- Introduced Webpack for more sophisticated JavaScript bundling
+- Introduced ESLint and Stylelint for code style checks
+- Introduced more accurate Material Design colors and shadows
+- Introduced modular scales for harmonic font sizing
+- Introduced git-hooks for better development workflow
+- Rewrite of CSS using the BEM methodology and SassDoc guidelines
+- Rewrite of JavaScript using ES6 and Babel as a transpiler
+- Rewrite of Admonition, Permalinks and CodeHilite integration
+- Rewrite of the complete typographical system
+- Rewrite of Gulp asset pipeline in ES6 and separation of tasks
+- Removed Bower as a dependency in favor of NPM
+- Removed custom icon build in favor of the Material Design icon set
+- Removed `_blank` targets on links due to vulnerability: http://bit.ly/1Mk2Rtw
+- Removed unversioned assets from build directory
+- Restructured templates into base templates and partials
+- Added build and watch scripts in `package.json`
+- Added support for Metadata and Footnotes Markdown extensions
+- Added support for PyMdown Extensions package
+- Added support for collapsible sections in navigation
+- Added support for separate table of contents
+- Added support for better accessibility through REM-based layout
+- Added icons for GitHub, GitLab and BitBucket integrations
+- Added more detailed documentation on specimen, extensions etc.
+- Added a `404.html` error page for deployment on GitHub Pages
+- Fixed live reload chain in watch mode when saving a template
+- Fixed variable references to work with MkDocs 0.16
+
+---
+
+### 0.2.4 <small>June 26, 2016</small> { id="0.2.4" }
+
+- Fixed improperly set default favicon
+- Fixed #33: Protocol relative URL for webfonts doesn't work with `file://`
+- Fixed #34: IE11 on Windows 7 doesn't honor `max-width` on `main` tag
+- Fixed #35: Add styling for blockquotes
+
+### 0.2.3 <small>May 16, 2016</small> { id="0.2.3" }
+
+- Fixed #25: Highlight inline fenced blocks
+- Fixed #26: Better highlighting for keystrokes
+- Fixed #30: Suboptimal syntax highlighting for PHP
+
+### 0.2.2 <small>March 20, 2016</small> { id="0.2.2" }
+
+- Fixed #15: Document Pygments dependency for CodeHilite
+- Fixed #16: Favicon could not be set through `mkdocs.yml`
+- Fixed #17: Put version into own container for styling
+- Fixed #20: Fix rounded borders for tables
+
+### 0.2.1 <small>March 12, 2016</small> { id="0.2.1" }
+
+- Fixed #10: Invisible header after closing search bar with <kbd>ESC</kbd> key
+- Fixed #13: Table cells don't wrap
+- Fixed empty list in table of contents when no headline is defined
+- Corrected wrong path for static asset monitoring in Gulpfile.js
+- Set up tracking of site search for Google Analytics
+
+### 0.2.0 <small>February 24, 2016</small> { id="0.2.0" }
+
+- Fixed #6: Include multiple color palettes via `mkdocs.yml`
+- Fixed #7: Better colors for links inside admonition notes and warnings
+- Fixed #9: Text for prev/next footer navigation should be customizable
+- Refactored templates (replaced `if`/`else` with modifiers where possible)
+
+### 0.1.3 <small>February 21, 2016</small> { id="0.1.3" }
+
+- Fixed #3: Ordered lists within an unordered list have `::before` content
+- Fixed #4: Click on Logo/Title without Github-Repository: `"None"`
+- Fixed #5: Page without headlines renders empty list in table of contents
+- Moved Modernizr to top to ensure basic usability in IE8
+
+### 0.1.2 <small>February 16, 2016</small> { id="0.1.2" }
+
+- Fixed styles for deep navigational hierarchies
+- Fixed webfont delivery problem when hosted in subdirectories
+- Fixed print styles in mobile/tablet configuration
+- Added option to configure fonts in `mkdocs.yml` with fallbacks
+- Changed styles for admonition notes and warnings
+- Set download link to latest version if available
+- Set up tracking of outgoing links and actions for Google Analytics
+
+### 0.1.1 <small>February 11, 2016</small> { id="0.1.1" }
+
+- Fixed #1: GitHub stars don't work if the repo_url ends with a `/`
+- Updated NPM and Bower dependencies to most recent versions
+- Changed footer/copyright link to Material theme to GitHub pages
+- Made MkDocs building/serving in build process optional
+- Set up continuous integration with Travis
+
+### 0.1.0 <small>February 9, 2016</small> { id="0.1.0" }
+
+- Initial release
diff --git a/documents/markdown/mkdocs-material/contributing_adding-translations.md b/documents/markdown/mkdocs-material/contributing_adding-translations.md
new file mode 100644
index 0000000..46696a7
--- /dev/null
+++ b/documents/markdown/mkdocs-material/contributing_adding-translations.md
@@ -0,0 +1,125 @@
+# Translations
+
+It's unbelievable – with the help of international community contributions,
+Material for MkDocs has been translated into 60+ languages. As you can imagine,
+it's impossible for us maintainers to keep all languages up-to-date, and new
+features sometimes require new translations.
+
+If you would like to help us to make Material for MkDocs even more globally
+accessible and have noticed a missing translation in your language, or would
+like to add a new language, you can help us by following the steps of the guide
+below.
+
+## Before creating an issue
+
+Translations change frequently, which is why we want to make sure that you don't
+invest your time in duplicating work. Before adding translations, please check
+the following things:
+
+### Check language availability
+
+With more than 60 languages, the chances are good that your language is already
+supported by Material for MkDocs. You can check if your language is available,
+or needs improvements or additional translations by inspecting the list of
+[supported languages]:
+
+- __Your language is already supported__ – in this case, you can check if there
+ are translations missing, and click the link underneath your language to add them, which takes 5 minutes.
+
+- __Your language is missing__ – in that case, you can help us add support
+ for your language to Material for MkDocs! Read on, to learn how to do this.
+
+ [supported languages]: ../setup/changing-the-language.md#site-language
+
+### Search our issue tracker
+
+Another user might have already created an issue supplying the missing
+translations for your language that still needs to be integrated by us
+maintainers. To avoid investing your time in duplicated work, please search the
+[issue tracker] beforehand.
+
+ [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+
+---
+
+At this point, when you have made sure that Material for MkDocs doesn't already
+support your language, you can add new translations for it by following the
+issue template.
+
+## Issue template
+
+We have created an issue template that makes contributing translations as simple
+as possible. It is the result of our experience with 60+ language contributions
+and updates over the last couple of years, and consists of the following parts:
+
+- [Title]
+- [Translations]
+- [Country flag] <small>optional</small>
+- [Checklist]
+
+ [Title]: #title
+ [Translations]: #translations
+ [Country flag]: #country-flag
+ [Checklist]: #checklist
+
+### Title
+
+When you update an already existing language, you can just leave the title as it
+is. Adding support for a new language, replace the `...` in the pre-filled title
+with the name of your language.
+
+| <!-- --> | Example |
+| -------- | -------- |
+| :material-check:{ style="color: #4DB6AC" } __Clear__ | Add translations for German
+| :material-close:{ style="color: #EF5350" } __Unclear__ | Add translations ...
+| :material-close:{ style="color: #EF5350" } __Useless__ | Help
+
+### Translations
+
+If a translation contains an :arrow_left: icon on the right side, it is missing.
+You can translate this line and remove the :arrow_left: icon. If you don't know
+how to translate specific lines, simply leave them for other contributors to
+complete. To ensure the accuracy of your translation, consider double-checking the
+context of the words by looking at our [English translations].
+
+[English translations]: https://github.com/squidfunk/mkdocs-material/tree/master/src/templates/partials/languages/en.html
+
+### Country flag <small>optional</small> { #country-flag }
+
+For a better overview, our list of [supported languages] includes country flags
+next to the language names. You can help us select a flag for your language by
+adding the shortcode for the country flag to this field. Go to our
+[emoji search] and enter `flag` to find all available shortcodes.
+
+!!! question "What if my flag is not available?"
+
+ [Twemoji] provides flag emojis for 260 countries – subdivisions of countries,
+ such as states, provinces, or regions, are not supported. If you're adding
+ translations for a subdivision, please choose the most appropriate available
+ flag.
+
+ [Twemoji]: https://github.com/jdecked/twemoji
+ [emoji search]: ../reference/icons-emojis.md#search
+
+> __Why this might be helpful__: adding a country flag next to the country name
+> can be helpful for you and for others to find the language in the list of
+> supported languages faster and easier. If your country's flag is not supported
+> by [Twemoji], you can help us choose an alternative.
+
+### Checklist
+
+Thanks for following the guide and helping us to add new translations to Material
+for MkDocs – you are almost done. The checklist ensures that you have read this
+guide and have worked to your best knowledge to provide us with everything we need
+to integrate your contribution.
+
+__We'll take it from here.__
+
+---
+
+## Attribution
+
+If you submit a translation using the template above, you will be __credited as
+a co-author__ in the commit, so you don't need to open a pull request. You have
+done a significant contribution to the project, making Material for MkDocs
+accessible to more people around the world. Thank you!
diff --git a/documents/markdown/mkdocs-material/contributing_index.md b/documents/markdown/mkdocs-material/contributing_index.md
new file mode 100644
index 0000000..fe84fd5
--- /dev/null
+++ b/documents/markdown/mkdocs-material/contributing_index.md
@@ -0,0 +1,269 @@
+# Contributing
+
+Material for MkDocs is an actively maintained and constantly evolving project
+serving a diverse user base with versatile backgrounds and needs. In order to
+efficiently address the requirements of all our users, evaluate change requests,
+and fix bugs, we put in a lot of work.
+
+Our ever-growing community includes many active users, who open new
+issues and discussions several times a day, evolving our [issue tracker] and
+[discussion board] into a knowledge base – an important addition to
+our [documentation] – yielding value to both new and experienced users.
+
+ [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
+ [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+ [documentation]: https://squidfunk.github.io/mkdocs-material/
+
+## How you can contribute
+
+We understand that reporting bugs, raising change requests, as well as engaging
+in discussions can be time-consuming, which is why we've carefully optimized our
+issue templates and defined guidelines to improve the overall interaction
+within the project. We've invested a lot of time and effort into making our
+[issue tracker] and [discussion board] as efficient as possible.
+
+Our goal is to ensure that our documentation, as well as issue tracker and
+discussion board, are __well-structured__, __easy to navigate__, and
+__searchable__, so you can find what you need quickly and efficiently. Thus,
+when you follow our guidelines, we can help you much faster.
+
+In this section, we guide your through our processes.
+
+### Creating an issue
+
+<div class="grid cards" markdown>
+
+- :material-bug-outline:
+ __Something is not working?__
+
+ ---
+
+ Report a bug in Material for MkDocs by creating an issue with a
+ reproduction
+
+ ---
+
+ [:octicons-arrow-right-24: Report a bug][report a bug]
+
+- :material-file-document-remove-outline:
+ __Missing information in our docs?__
+
+ ---
+
+ Report missing information or potential inconsistencies in our
+ documentation
+
+ ---
+
+ [:octicons-arrow-right-24: Report a docs issue][report a docs issue]
+
+- :material-lightbulb-on-20:
+ __Want to submit an idea?__
+
+ ---
+
+ Propose a change, feature request, or suggest an improvement
+
+ ---
+
+ [:octicons-arrow-right-24: Request a change][request a change]
+
+- :material-account-question-outline:
+ __Have a question or need help?__
+
+ ---
+
+ Ask a question on our [discussion board] and get in touch with our
+ community
+
+ ---
+
+ [:octicons-arrow-right-24: Ask a question][discussion board]
+
+</div>
+
+### Contributing
+
+<div class="grid cards" markdown>
+
+- :material-translate:
+ __Missing support for your language?__
+
+ ---
+
+ Add or improve translations for a new or already supported language
+
+ ---
+
+ [:octicons-arrow-right-24: Add translations][add translations]
+
+- :material-source-pull:
+ __Want to create a pull request?__
+
+ ---
+
+ Learn how to create a comprehensive and useful pull request (PR)
+
+ ---
+
+ [:octicons-arrow-right-24: Create a pull request][create a pull request]
+
+</div>
+
+ [report a bug]: reporting-a-bug.md
+ [report a docs issue]: reporting-a-docs-issue.md
+ [request a change]: requesting-a-change.md
+ [add translations]: adding-translations.md
+ [create a pull request]: making-a-pull-request.md
+
+## Checklist
+
+Before interacting within the project, please take a moment to consider the
+following questions. By doing so, you can ensure that you are using the correct
+issue template and that you provide all necessary information when interacting
+with our community.
+
+!!! warning "Issues, discussions, and comments are forever"
+
+ Please note that everything you write is permanent and will remain
+ for everyone to read – forever. Therefore, please always be nice and
+ constructive, follow our contribution guidelines, and comply with our
+ [Code of Conduct].
+
+### Before creating an issue
+
+- Are you using the appropriate issue template, or is there another issue
+ template that better fits the context of your request?
+
+- Have you checked if a similar bug report or change request has already been
+ created, or have you stumbled upon something that might be related?
+
+- Did your fill out every field as requested and did you provide all additional
+ information we maintainers need to comprehend your request?
+
+### Before asking a question
+
+- Is the topic a question for our [discussion board], or is it a bug report or
+ change request that should better be raised on our [issue tracker]?
+
+- Is there an open discussion on the topic of your request? If the answer is yes,
+ does your question match the direction of the discussion, or should you open a
+ new discussion?
+
+- Did your provide our community with all the necessary information to
+ understand your question and help you quickly, or can you make it easier to
+ help you?
+
+### Before commenting
+
+- Is your comment relevant to the topic of the current page, post, issue, or
+ discussion, or is it a better idea to create a new issue or discussion?
+
+- Does your comment add value to the conversation? Is it constructive and
+ respectful to our community and us maintainers? Could you just use a
+ [:octicons-smiley-16: reaction][reaction] instead?
+
+ [Code of Conduct]: https://github.com/squidfunk/mkdocs-material/blob/master/CODE_OF_CONDUCT.md
+ [reaction]: https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/
+
+## Rights and responsibilities
+
+As maintainers, we are entrusted with the __responsibility__ to moderate
+communication within our community, including the authority to close, remove,
+reject, or edit issues, discussions, comments, commits, and to block users who
+__do not align__ with our contribution guidelines and our [Code of Conduct].
+This role requires us to be actively involved in maintaining the integrity and
+positive atmosphere of our community. Upholding these standards decisively
+ensures a respectful and inclusive environment for all members.
+
+
+### Code of Conduct
+
+Our [Code of Conduct] outlines the expectation for all community members to
+treat one another with respect, employing inclusive and welcoming language. Our
+commitment is to foster a positive and supportive environment, free of
+inappropriate, offensive, or harmful behavior.
+
+We take any violations seriously and will take appropriate action in response to
+uphold these values.[^1]
+
+ [^1]:
+ __Warning and blocking policy:__
+ Given the increasing popularity of our project and our commitment to a
+ healthy community, we've defined clear guidelines on how we proceed with
+ violations:
+
+ 1.1. __First warning:__ Users displaying repeated inappropriate, offensive,
+ or harmful behavior will receive a first warning. This warning serves as a
+ formal notice that their behavior is not in alignment with our community
+ standards and Code of Conduct. The first warning is permanent.
+
+ 1.2. __Second warning and opportunity for resolution:__ If the behavior
+ persists, a second warning will be issued. Upon receiving the second
+ warning, the user will be given a 5-day period for reflection, during which
+ they are encouraged to publicly explain or apologize for their actions.
+ This period is designed to offer an opportunity for openly clearing out any
+ misunderstanding.
+
+ 1.3. __Blocking:__ Should there be no response or improvement in behavior
+ following the second warning, we reserve the right to block the user from
+ the community and repository. Blocking is considered a last resort, used
+ only when absolutely necessary to protect the community's integrity and
+ positive atmosphere.
+
+ Blocking has been an exceptionally rare necessity in our overwhelmingly
+ positive community, highlighting our preference for constructive dialogue
+ and mutual respect. It aims to protect our community members and team.
+
+### Incomplete issues and duplicates
+
+We have invested significant time and effort in the setup of our contribution
+process, ensuring that we assess the essential requirements for reviewing and
+responding to issues effectively. Each field in our issue templates is
+thoughtfully designed to help us fully understand your concerns and the nature
+of your matter. We encourage all members to utilize the search function before
+submitting new issues or starting discussions to help avoid duplicates. Your
+cooperation is crucial in keeping our community's discussions constructive and
+organized.
+
+ - __Mandatory completion of issue templates:__ We need all of the information
+ required in our issue templates because it ensures that every user and
+ maintainer, regardless of their experience, can understand the content and
+ severity of your bug report or change request.
+
+ - __Closing incomplete issues:__
+ We _reserve the right to close issues lacking essential information_, such as
+ but not limited to [minimal reproductions] or those not adhering to the
+ quality standards and requirements specified in our issue templates. Such
+ issues can be reopened once the missing information has been provided.
+
+ - __Handling duplicates:__ To maintain organized and efficient
+ communication within our [issue tracker] and [discussion board], we
+ _reserve the right to close any duplicated issues or lock duplicated
+ discussions_. Opening multiple channels to ask the same question or report the
+ same issue across different forums hinders our ability to manage and address
+ community concerns effectively. This approach is vital for efficient time
+ management, as duplicated questions can consume the time of multiple team
+ members simultaneously. Ensuring that each issue or discussion is unique and
+ progresses with new information helps us to maintain focus and support our
+ community.
+
+ We further _reserve the right to immediately close discussions or issues that
+ are reopened without providing new information_ or simply because users have
+ not yet received a response to their issue/question, as the issue is marked as
+ incomplete.
+
+ - __Limitations of automated tools:__ While we believe in the value and
+ efficiency that automated tools bring to identifying potential issues (such
+ as those identified by Lighthouse, Accessibility tools, and others), simply
+ submitting an issue generated by these tools does not constitute a complete
+ bug report. These tools sometimes produce verbose outputs and may include
+ false positives, which necessitate a critical evaluation. You are of course
+ welcome to attach generated reports to your issue. However, this does not
+ substitute the requirement for a minimal reproduction or a thorough discussion
+ of the findings. _We reserve the right to mark these issues as incomplete and
+ close them._ This practice ensures that we are addressing genuine concerns
+ with precision and clarity, rather than navigating through extensive automated
+ outputs.
+
+ [minimal reproductions]: ../guides/creating-a-reproduction.md
diff --git a/documents/markdown/mkdocs-material/contributing_making-a-pull-request.md b/documents/markdown/mkdocs-material/contributing_making-a-pull-request.md
new file mode 100644
index 0000000..6f1f0e1
--- /dev/null
+++ b/documents/markdown/mkdocs-material/contributing_making-a-pull-request.md
@@ -0,0 +1,402 @@
+# Pull Requests
+
+You can contribute to Material for MkDocs by making a [pull request] that
+will be reviewed by maintainers and integrated into the main repository when
+the changes made are approved. You can contribute bug fixes, changes to the
+documentation, or new functionality you have developed.
+
+[pull request]: https://docs.github.com/en/pull-requests
+
+!!! note "Considering a pull request"
+
+ Before deciding to spend effort on making changes and creating a pull
+ request, please discuss what you intend to do. If you are responding to
+ what you think might be a bug, please issue a [bug report] first. If you
+ intend to work on documentation, create a [documentation issue]. If you
+ want to work on a new feature, please create a [change request].
+
+ Keep in mind the guidance given and let people advise you. It might be that
+ there are easier solutions to the problem you perceive and want to address.
+ It might be that what you want to achieve can already be done by
+ configuration or [customization].
+
+[bug report]: reporting-a-bug.md
+[documentation issue]: reporting-a-docs-issue.md
+[change request]: requesting-a-change.md
+[customization]: ../customization.md
+
+## Learning about pull requests
+
+Pull requests are a concept layered on top of Git by services that provide Git
+hosting. Before you consider making a pull request, you should familiarize
+yourself with the documentation on GitHub, the service we are using. The
+following articles are of particular importance:
+
+1. [Forking a repository]
+2. [Creating a pull request from a fork]
+3. [Creating a pull request]
+
+Note that they provide tailored documentation for different operating systems
+and different ways of interacting with GitHub. We do our best in the
+documentation here to describe the process as it applies to Material for MkDocs
+but cannot cover all possible combinations of tools and ways of doing things.
+It is also important that you understand the concept of a pull-request in
+general before continuing.
+
+[Forking a repository]: https://docs.github.com/en/get-started/quickstart/fork-a-repo
+[Creating a pull request from a fork]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork
+[Creating a pull request]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
+
+## Pull request process
+
+In the following, we describe the general process for making pull requests. The
+aim here is to provide the 30k ft overview before describing details later on.
+
+### Preparing changes and draft PR
+
+The diagram below describes what typically happens to repositories in the
+process or preparing a pull request. We will be discussing the review-revise
+process below. It is important that you understand the overall process first
+before you worry about specific commands. This is why we cover this first before
+providing instructions below.
+
+``` mermaid
+sequenceDiagram
+ autonumber
+
+ participant mkdocs-material
+ participant PR
+ participant fork
+ participant local
+
+ mkdocs-material ->> fork: fork on GitHub
+ fork ->> local: clone to local
+ local ->> local: branch
+ loop prepare
+ loop push
+ loop edit
+ local ->> local: commit
+ end
+ local ->> fork: push
+ end
+ mkdocs-material ->> fork: merge in any changes
+ fork ->>+ PR: create draft PR
+ PR ->> PR: review your changes
+ end
+```
+
+1. The first step is that you create a fork of the Material for MkDocs
+ repository. This provides you with a repository that you can push changes to.
+ Note that it is not possible to have more than one fork of a given repository
+ at any point in time. So, the fork you create will be *the* fork you have.
+
+1. Once it is made, clone it to your local machine so you can start working on
+ your changes.
+
+2. All contributions should be made through a 'topic branch' with a name that
+ describes the work being done. This allows you to have more than one piece
+ of work in progress and, if you are working with the public version, also
+ shows others clearly that the code contained is work in progress. The topic
+ branch will be relatively short-lived and will disappear at the end, when
+ your changes have been incorporated into the codebase.
+
+3. If you intend to make any code changes, as opposed to working on
+ documentation only, you will need to [set up a development
+ environment](#setting-up-a-development-environment).
+
+4. Next comes the iterative process of making edits, committing them to your
+ clone. Please commit in sensible chunks that constitute a piece of work
+ instead of committing everything in one go.
+
+ Remember that fine-grained, incremental commits are much easier to
+ review in than large changes all over the place and with many files involved.
+ Try to keep your changes as small and localized as possible and keep the
+ reviewer in mind when committing. In particular, make sure to write
+ meaningful commit messages.
+
+5. Push your work up to your fork regularly.
+
+6. You should also keep an eye on changes in the Material for MkDocs repository
+ you cloned. This is especially important if you work takes a while. Please
+ try and merge any concurrent changes into your fork and into your branch
+ regularly. You *must* do this at least once before creating a pull request,
+ so make your life easier and do it more often so as to minimize the risk of
+ conflicting changes.
+
+7. Once you are happy that your changes are in a state that you can describe
+ them in a *draft* pull request, you should create this. Make sure to
+ reference any previous discussions or issues that gave rise to your work.
+ Creating a draft is a good way to get *early* feedback on your work from the
+ maintainer or others. You can explicitly request reviews at points where you
+ think this would be important.
+
+8. Review your work as if you were the reviewer and fix any issues with your
+ work so far. Look critically at the diffs of the files that you have changed.
+ In particular, pay attention to whether the changes are as small as possible
+ and whether you have follow the general coding style used in the project.
+ If you received feedback, iterate over the process so far as necessary.
+
+ You should choose a number of projects to test your changes with. You should
+ definitely make sure that the changes do not break the building of the
+ documentation for Material for MkDocs, which you can find in the `docs`
+ folder. You may also want to make sure that relevant examples from the
+ [examples repository] still build fine.
+
+[examples repository]: https://github.com/mkdocs-material/examples
+
+### Finalizing
+
+Once you are happy with your changes, you can move to the next step, finalizing
+your pull request and asking for a more formal and detailed review. The diagram
+below shows the process:
+
+``` mermaid
+sequenceDiagram
+ autonumber
+ participant mkdocs-material
+ participant PR
+ participant fork
+ participant local
+
+ activate PR
+ PR ->> PR : finalize PR
+ loop review
+ loop discuss
+ PR ->> PR: request review
+ PR ->> PR: discussion
+ local ->> fork: push further changes
+ end
+ PR ->> mkdocs-material: merge (and squash)
+ deactivate PR
+ fork ->> fork: delete branch
+ mkdocs-material ->> fork: pull
+ local ->> local: delete branch
+ fork ->> local: pull
+ end
+```
+
+1. When you are happy that the changes you made amount to a contribution that
+ the maintainer(s) could integrate into the codebase, finalize the pull
+ request. This signals to everyone that consider the work 'done' and that it
+ can be reviewed with a view to accepting and integrating it.
+
+2. Request a review from the maintainer, `@squidfunk`.
+
+3. The maintainer may make comments on your code, which you should discuss with
+ them. Bear in mind when doing this that the maintainer may have a different
+ point of view compared to yours. They will often take a more long-term
+ perspective of maintaining the project in the years to come while you may be
+ more focused on the specific issue or feature that you worked on. Please keep
+ the discussion respectful at all times.
+
+ It is important to note that not all pull requests get incorporated into the
+ codebase. The reasons can vary. The work may bring to light other issues that
+ block integration of the pull request. Sometimes it helps uncover better ways of
+ doing things or shows that a more general approach is needed. All of this is
+ fine and helps the project progress, even if specific changes are not,
+ ultimately, accepted.
+
+4. Make any requested changes by committing them to your local clone and
+ pushing them up to your fork. This will automatically update the pull request.
+ It may well take a few iterations to get your contributions to an acceptable
+ state. You can help the process along by carefully reading comments made and
+ making changes with care.
+
+5. Once the reviewer is fully satisfied with the changes, they can merge them
+ into the main branch (or 'master'). In the process, they may 'squash' your
+ commits together into a smaller number of commits and may edit the messages
+ that describe them. Congratulations, you have now contributed to this project
+ and should see the changes in the main branch under your name.
+
+6. You can now delete the fork and your local repository and start afresh again
+ next time around. Alternatively, you can keep the repository and local clone
+ around but it is important that you keep them in sync with the upstream
+ repository for any subsequent work. We recommend that you start by deleting
+ the branch you used on your fork.
+
+7. To make sure you have the changes you produced, pull them from the main
+ repository into the main branch of your fork.
+
+8. Similarly, delete the topic branch from your local clone and...
+
+9. pull the changes to its master branch.
+
+## Steps
+
+Now that the overall process is outlined, here are specific instructions and
+tips. There are many choices to be made when describing a process for
+contributing to a project via a pull request. In the following, we assume that
+you are working with the Git command-line tools. For most alternatives (such as
+using IDEs or using functionality provided through the GitHub web interface),
+the translation from the command-line instructions should be simple enough. We
+will add notes only where really necessary to keep the complexity of this to a
+reasonable level.
+
+### Forking the repository
+
+To make changes to Material for MkDocs, you would first fork one of its
+repositories on GitHub. This is so that you have a repository on GitHub that
+you can push changes to (only maintainers and collaborators have write access
+to the original repositories).
+
+Fork the [repository] if you want to make changes to code or to the documentation.
+It is a good idea to change the name of the repository by appending `-fork` so
+that people who come across it know that they have found a temporary fork rather
+than the original or a permanent fork of the project. You may also want to add
+a description that clarifies what the repository is for.
+
+[repository]: https://github.com/squidfunk/mkdocs-material
+
+### Setting up a development environment
+
+From this point onwards, please follow the [instructions for setting up the
+development environment]. They will take you through the process of setting up
+an environment in which you can make changes and review/test them.
+
+[instructions for setting up the development environment]: ../customization.md#environment-setup
+
+### Making changes
+
+When you make changes to the code or the documentation please follow the
+established style used in the project. Doing so increases readability and
+also helps with making diffs easier to read for those who will review the pull
+request. Avoid making any large-scale style changes such as asking your IDE
+to re-format all code.
+
+Study the code that you are modifying well to ensure that you fully understand
+how it works before you try to change it. This will not only help you solve the
+problem you are trying to address but also minimize the risks of creating
+unintended side effects.
+
+### Committing to a branch
+
+Development for pull requests is best done in a topic branch separate from the
+`master` branch. Create a new local branch with `git switch -c <name>` and
+commit your changes to this branch.
+
+When you want to push commits to your fork, you can do so with
+`git push -u origin <name>`. The `-u` argument is the short version of
+`--set-upstream`, which makes the newly created branch 'track' the branch with
+the same `<name>` in your fork. This means that then `pull` and `push` commands
+will work against that branch in your fork by default.
+
+### Merging concurrent changes
+
+If the work you do takes some time then the chances increase that changes will
+be made to the main repository while you work. It is probably a good idea to set
+up the original Material for MkDocs repository as an `upstream` repository for
+your local clone.
+
+This is what it might look like:
+
+```bash hl_lines="4"
+$ git remote -v
+origin git@github.com:<your_username>/mkdocs-material-fork.git (fetch)
+origin git@github.com:<your_username>/mkdocs-material-fork.git (push)
+$ git remote add upstream https://github.com/squidfunk/mkdocs-material.git
+$ git remote -v
+origin git@github.com:alexvoss/mkdocs-material-fork.git (fetch)
+origin git@github.com:alexvoss/mkdocs-material-fork.git (push)
+upstream https://github.com/squidfunk/mkdocs-material.git (fetch)
+upstream https://github.com/squidfunk/mkdocs-material.git (push)
+```
+
+After you have done this, you can pull any concurrent changes from the upstream
+repository directly into your clone and do any necessary merges there, then push
+them up to your fork. You will need to be explicit about which remote repository
+you want to use when you are doing a `pull`:
+
+```bash
+# making and committing some local changes
+push pull upstream master
+```
+
+This fetches changes from the `master` branch into your topic branch and merges
+them.
+
+### Testing and reviewing changes
+
+Before you commit any changes, you should make sure that they work as expected
+and do not create any unintended side effects. You should test them on at least
+these three [smoke tests]:
+
+- The documentation of Material for MkDocs itself. If you set up and run the
+development environment as outlined in the [instructions for setting up the
+development environment], `mkdocs serve` should be running and continuously
+building the documentation. Check that there are no error messages and, ideally,
+no (new) warnings.
+
+- Test on a project that represents the problem or a test for a newly developed
+feature. You may already have this if you have filed a bug report and created
+a [minimal reproduction]. If you are working on a new feature then you may need
+to build a project to serve as a test suite. It can double as documentation that
+shows how your new feature is meant to work.
+
+- Test with relevant examples from the [Material for MkDocs Examples]
+ repository.
+
+[smoke tests]: https://en.wikipedia.org/wiki/Smoke_testing_(software)
+[minimal reproduction]: https://squidfunk.github.io/mkdocs-material/guides/creating-a-reproduction/
+[Material for MkDocs Examples]: https://github.com/mkdocs-material/examples
+
+- Ideally, also test the examples in the [examples repository].
+
+[examples repository]: https://github.com/mkdocs-material/examples
+[projects plugin]: https://squidfunk.github.io/mkdocs-material/plugins/projects/
+
+### Creating the pull request
+
+Initially, create the pull request **as a draft**. You do this [through the
+various interfaces that GitHub provides]. Which one you use is entirely up to
+you. We do not provide specific instructions for using the interfaces as GitHub
+provide all the information that should be necessary.
+
+[through the various interfaces that GitHub provides]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
+
+### Commits, messages, mistakes and 'squash'
+
+### Deleting branches
+
+Once the pull request has been merged into the master branch of the Material
+for MkDocs repository, you should remove the branch both from the fork on
+GitHub and from the local clone on your computer. This avoids possible
+confusion about the state of development.
+
+First, switch back to the `master` branch with `git switch master` and then
+delete the branch used for the PR using `git branch -d <name>`.
+
+### Subsequent Pull Requests
+
+It is important that subsequent pull requests are started from an up-to-date
+history of the `master` branch. One way to achieve this is to delete the fork
+and start with an entirely new one next time round.
+
+If you contribute to Material for MkDocs more often or just happen to be
+doing two or more pull requests in succession, you can also just make sure
+to sync your fork (using the GitHub UI) and pull from it into your local
+repository. So, just delete the topic branch you created (both locally and in
+your fork) and pull from the main repository's `master` branch into your
+`master` branch before starting work on a new pull request.
+
+## Dos and Don'ts
+
+1. **Don't** just create a pull request with changes that are not explained.
+
+2. **Do** discuss what you intend to do with people in the discussions so that the
+ rationale for any changes is clear before you write or modify code.
+
+3. **Do** link to the discussion or any issues to provide the context for a pull
+ request.
+
+4. **Do** ask questions if you are uncertain about anything.
+
+5. **Do** ask yourself if what you are doing benefits the wider community and
+ makes Material for MkDocs a better product.
+
+6. **Do** ask yourself if the cost of making the changes stands in a good
+ relation to the benefits they will bring. Some otherwise sensible changes can
+ add complexity for comparatively little gain, might break existing behaviour
+ or might be brittle when other changes need to be made.
+
+7. **Do** merge in concurrent changes frequently to minimize the chance of
+ conflicting changes that may be difficult to resolve.
diff --git a/documents/markdown/mkdocs-material/contributing_reporting-a-bug.md b/documents/markdown/mkdocs-material/contributing_reporting-a-bug.md
new file mode 100644
index 0000000..8c84f8a
--- /dev/null
+++ b/documents/markdown/mkdocs-material/contributing_reporting-a-bug.md
@@ -0,0 +1,313 @@
+# Bug reports
+
+Material for MkDocs is an actively maintained project that we constantly strive
+to improve. With a project of this size and complexity, bugs may occur. If you
+think you have discovered a bug, you can help us by submitting an issue in our
+public [issue tracker], following this guide.
+
+ [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+
+## Before creating an issue
+
+With more than 20,000 users, issues are created every other day. The maintainers
+of this project are trying very hard to keep the number of open issues down by
+fixing bugs as fast as possible. By following this guide, you will know exactly
+what information we need to help you quickly.
+
+__But first, please do the following things before creating an issue.__
+
+### Upgrade to latest version
+
+Chances are that the bug you discovered was already fixed in a subsequent
+version. Thus, before reporting an issue, ensure that you're running the
+[latest version] of Material for MkDocs. Please consult our [upgrade guide] to
+learn how to upgrade to the latest version.
+
+!!! warning "Bug fixes are not backported"
+
+ Please understand that only bugs that occur in the latest version of
+ Material for MkDocs will be addressed. Also, to reduce duplicate efforts,
+ fixes cannot be backported to earlier versions.
+
+### Remove customizations
+
+If you're using [customizations] like [additional CSS], [JavaScript], or
+[theme extension], please remove them from `mkdocs.yml` before reporting a bug.
+We can't offer official support for bugs that might hide in your overrides, so
+make sure to omit the following settings from `mkdocs.yml`:
+
+ - [`theme.custom_dir`][theme.custom_dir]
+ - [`hooks`][hooks]
+ - [`extra_css`][extra_css]
+ - [`extra_javascript`][extra_javascript]
+
+If, after removing those settings, the bug is gone, the bug is likely caused by
+your customizations. A good idea is to add them back gradually to narrow down
+the root cause of the problem. If you did a major version upgrade, make sure you
+adjusted all partials you have overridden.
+
+!!! warning "Customizations mentioned in our documentation"
+
+ A handful of the features Material for MkDocs offers can only be implemented
+ with customizations. If you find a bug in any of the customizations [that
+ our documentation explicitly mentions], you are, of course, encouraged to
+ report it.
+
+__Don't be shy to ask on our [discussion board] for help if you run into
+problems.__
+
+ [latest version]: ../changelog/index.md
+ [upgrade guide]: ../upgrade.md
+ [Customizations]: ../customization.md
+ [additional CSS]: ../customization.md#additional-css
+ [JavaScript]: ../customization.md#additional-javascript
+ [theme extension]: ../customization.md#extending-the-theme
+ [theme.custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
+ [hooks]: https://www.mkdocs.org/user-guide/configuration/#hooks
+ [extra_css]: https://www.mkdocs.org/user-guide/configuration/#extra_css
+ [extra_javascript]: https://www.mkdocs.org/user-guide/configuration/#extra_javascript
+ [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
+ [StackOverflow]: https://stackoverflow.com
+ [that our documentation explicitly mentions]: ?q="extends+base"
+
+### Search for solutions
+
+At this stage, we know that the problem persists in the latest version and is
+not caused by any of your customizations. However, the problem might result from
+a small typo or a syntactical error in a configuration file, e.g., `mkdocs.yml`.
+
+Now, before you go through the trouble of creating a bug report that is answered
+and closed right away with a link to the relevant documentation section or
+another already reported or closed issue or discussion, you can save time for
+us and yourself by doing some research:
+
+1. [Search our documentation] and look for the relevant sections that could
+ be related to your problem. If found, make sure that you configured
+ everything correctly.[^1]
+
+ [^1]:
+ When adding lines to `mkdocs.yml`, make sure you are preserving the
+ indentation as mentioned in the documentation since YAML is a
+ whitespace-sensitive language. Many reported issues turn out to be
+ configuration errors.
+
+1. [Search our issue tracker][issue tracker], as another user might already
+ have reported the same problem, and there might even be a known workaround
+ or fix for it. Thus, no need to create a new issue.
+
+2. [Search our discussion board][discussion board] to learn if other users
+ are struggling with similar problems and work together with our great
+ community towards a solution. Many problems are solved here.
+
+__Keep track of all <u>search terms</u> and <u>relevant links</u>, you'll need
+them in the bug report.__[^2]
+
+ [^2]:
+ We might be using terminology in our documentation different from yours,
+ but we mean the same. When you include the search terms and related links
+ in your bug report, you help us to adjust and improve the documentation.
+
+---
+
+At this point, when you still haven't found a solution to your problem, we
+encourage you to create an issue because it's now very likely that you
+stumbled over something we don't know yet. Read the following section to learn
+how to create a complete and helpful bug report.
+
+ [Search our documentation]: ?q=
+
+## Issue template
+
+We have created a new issue template to make the bug reporting process as simple
+as possible and more efficient for our community and us. It is the result of
+our experience answering and fixing more than 1,600 issues (and counting) and
+consists of the following parts:
+
+- [Title]
+- [Context] <small>optional</small>
+- [Bug description]
+- [Related links]
+- [Reproduction]
+- [Steps to reproduce]
+- [Browser] <small>optional</small>
+- [Checklist]
+
+ [Title]: #title
+ [Context]: #context
+ [Bug description]: #bug-description
+ [Related links]: #related-links
+ [Reproduction]: #reproduction
+ [Steps to reproduce]: #steps-to-reproduce
+ [Browser]: #browser
+ [Checklist]: #checklist
+
+### Title
+
+A good title is short and descriptive. It should be a one-sentence executive
+summary of the issue, so the impact and severity of the bug you want to report
+can be inferred from the title.
+
+| <!-- --> | Example |
+| -------- | -------- |
+| :material-check:{ style="color: #4DB6AC" } __Clear__ | Built-in `typeset` plugin changes precedence of nav title over `h1`
+| :material-close:{ style="color: #EF5350" } __Wordy__ | The built-in `typeset` plugin changes the precedence of the nav title over the document headline
+| :material-close:{ style="color: #EF5350" } __Unclear__ | Title does not work
+| :material-close:{ style="color: #EF5350" } __Useless__ | Help
+
+### Context <small>optional</small> { #context }
+
+Before describing the bug, you can provide additional context for us to
+understand what you were trying to achieve. Explain the circumstances
+in which you're using Material for MkDocs, and what you _think_ might be
+relevant. Don't write about the bug here.
+
+> __Why this might be helpful__: some errors only manifest in specific settings,
+> environments or edge cases, for example, when your documentation contains
+> thousands of documents.
+
+### Bug description
+
+Now, to the bug you want to report. Provide a clear, focused, specific, and
+concise summary of the bug you encountered. Explain why you think this is a bug
+that should be reported to Material for MkDocs, and not to one of its
+dependencies.[^3] Adhere to the following principles:
+
+ [^3]:
+ Sometimes, users report bugs on our [issue tracker] that are caused by one
+ of our upstream dependencies, including [MkDocs], [Python Markdown],
+ [Python Markdown Extensions] or third-party plugins. A good rule of thumb is
+ to change the [`theme.name`][theme.name] to `mkdocs` or `readthedocs` and
+ check if the problem persists. If it does, the problem is likely not
+ related to Material for MkDocs and should be reported upstream. When in
+ doubt, use our [discussion board] to ask for help.
+
+- __Explain the <u>what</u>, not the <u>how</u>__ – don't explain
+ [how to reproduce the bug][Steps to reproduce] here, we're getting there.
+ Focus on articulating the problem and its impact as clearly as possible.
+
+- __Keep it short and concise__ – if the bug can be precisely explained in one
+ or two sentences, perfect. Don't inflate it – maintainers and future users
+ will be grateful for having to read less.
+
+- __One bug at a time__ – if you encounter several unrelated bugs, please
+ create separate issues for them. Don't report them in the same issue, as
+ this makes attribution difficult.
+
+---
+
+:material-run-fast: __Stretch goal__ – if you found a workaround or a way to fix
+the bug, you can help other users temporarily mitigate the problem before
+we maintainers can fix the bug in our code base.
+
+> __Why we need this__: in order for us to understand the problem, we
+> need a clear description of it and quantify its impact, which is essential
+> for triage and prioritization.
+
+ [MkDocs]: https://www.mkdocs.org
+ [Python Markdown]: https://python-markdown.github.io/extensions/
+ [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
+ [theme.name]: https://www.mkdocs.org/user-guide/configuration/#theme
+
+### Related links
+
+Of course, prior to reporting a bug, you have read our documentation and
+[could not find a working solution][search for solutions]. Please share links
+to all sections of our documentation that might be relevant to the bug, as it
+helps us gradually improve it.
+
+Additionally, since you have searched our [issue tracker] and [discussion board]
+before reporting an issue, and have possibly found several issues or
+discussions, include those as well. Every link to an issue or discussion creates
+a backlink, guiding us maintainers and other users in the future.
+
+---
+
+:material-run-fast: __Stretch goal__ – if you also include the search terms you
+used when [searching for a solution][search for solutions] to your problem, you
+make it easier for us maintainers to improve the documentation.
+
+> __Why we need this__: related links help us better understand what you were
+> trying to achieve and whether sections of our documentation need to be
+> adjusted, extended, or overhauled.
+
+ [search for solutions]: #search-for-solutions
+
+### Reproduction
+
+A minimal reproduction is at the heart of every well-written bug report, as
+it allows us maintainers to instantly recreate the necessary conditions to
+inspect the bug to quickly find its root cause. It's a proven fact that issues
+with concise and small reproductions can be fixed much faster.
+
+[:material-bug: Create reproduction][Create reproduction]{ .md-button .md-button--primary }
+
+---
+
+After you have created the reproduction, you should have a `.zip` file, ideally
+not larger than 1 MB. Just drag and drop the `.zip` file into this field, which
+will automatically upload it to GitHub.
+
+> __Why we need this__: if an issue contains no minimal reproduction or just
+> a link to a repository with thousands of files, the maintainers would need to
+> invest a lot of time into trying to recreate the right conditions to even
+> inspect the bug, let alone fix it.
+
+!!! warning "Don't share links to repositories"
+
+ While we know that it is a good practice among developers to include a link
+ to a repository with the bug report, we currently don't support those in our
+ process. The reason is that the reproduction, which is automatically
+ produced by the [built-in info plugin] contains all of the necessary
+ environment information that is often forgotten to be included.
+
+ Additionally, there are many non-technical users of Material for MkDocs that
+ have trouble creating repositories.
+
+ [Create reproduction]: ../guides/creating-a-reproduction.md
+ [built-in info plugin]: ../plugins/info.md
+
+### Steps to reproduce
+
+At this point, you provided us with enough information to understand the bug
+and provided us with a reproduction that we could run and inspect. However, when
+we run your reproduction, it might not be immediately apparent how we can see
+the bug in action.
+
+Thus, please list the specific steps we should follow when running your
+reproduction to observe the bug. Keep the steps short and concise, and make sure
+not to leave anything out. Use simple language as you would explain it to a
+five-year-old, and focus on continuity.
+
+> __Why we need this__: we must know how to navigate your reproduction in order
+> to observe the bug, as some bugs only occur at certain viewports or in
+> specific conditions.
+
+### Browser <small>optional</small> { #browser }
+
+If you're reporting a bug that only occurs in one or more _specific_ browsers,
+we need to know which browsers are affected. This field is optional, as it is
+only relevant when the bug you are reporting does not involve a crash when
+[previewing] or [building] your site.
+
+---
+
+:material-incognito: __Incognito mode__ – Please verify that a the bug is
+not caused by a browser extension. Switch to incognito mode and try to reproduce
+the bug. If it's gone, it's caused by an extension.
+
+> __Why we need this__: some bugs only occur in specific browsers or versions.
+> Since now, almost all browsers are evergreen, we usually don't need to know the
+> version in which it occurs, but we might ask for it later. When in doubt, add
+> the browser version as the first step in the field above.
+
+ [previewing]: http://localhost:8000/mkdocs-material/creating-your-site/#previewing-as-you-write
+ [building]: http://localhost:8000/mkdocs-material/creating-your-site/#building-your-site
+
+### Checklist
+
+Thanks for following the guide and creating a high-quality and complete bug
+report – you are almost done. The checklist ensures that you have read this guide
+and have worked to your best knowledge to provide us with everything we need to
+know to help you.
+
+__We'll take it from here.__
diff --git a/documents/markdown/mkdocs-material/contributing_reporting-a-docs-issue.md b/documents/markdown/mkdocs-material/contributing_reporting-a-docs-issue.md
new file mode 100644
index 0000000..460aadf
--- /dev/null
+++ b/documents/markdown/mkdocs-material/contributing_reporting-a-docs-issue.md
@@ -0,0 +1,91 @@
+# Documentation issues
+
+Our documentation is composed of more than 80 pages and includes extensive
+information on features, configurations, customizations, and much more. If you
+have found an inconsistency or see room for improvement, please follow this
+guide to submit an issue on our [issue tracker].
+
+ [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+
+## Issue template
+
+Reporting a documentation issue is usually less involved than reporting a bug,
+as we don't need a [reproduction]. Please thoroughly read this guide before
+creating a new documentation issue, and provide the following information as
+part of the issue:
+
+- [Title]
+- [Description]
+- [Related links]
+- [Proposed change] <small>optional</small>
+- [Checklist]
+
+ [reproduction]: ../guides/creating-a-reproduction.md
+ [Title]: #title
+ [Description]: #description
+ [Related links]: #related-links
+ [Proposed change]: #proposed-change
+ [Checklist]: #checklist
+
+### Title
+
+A good title should be a short, one-sentence description of the issue, contain
+all relevant information and, in particular, keywords to simplify the search in
+our issue tracker.
+
+| <!-- --> | Example |
+| -------- | -------- |
+| :material-check:{ style="color: #4DB6AC" } __Clear__ | Clarify social cards setup on Windows
+| :material-close:{ style="color: #EF5350" } __Unclear__ | Missing information in the docs
+| :material-close:{ style="color: #EF5350" } __Useless__ | Help
+
+### Description
+
+Provide a clear and concise summary of the inconsistency or issue you
+encountered in the documentation or the documentation section that needs
+improvement. Explain why you think the documentation should be adjusted and
+describe the severity of the issue:
+
+- __Keep it short and concise__ – if the inconsistency or issue can be
+ precisely explained in one or two sentences, perfect. Maintainers and future
+ users will be grateful for having to read less.
+
+- __One issue at a time__ – if you encounter several unrelated inconsistencies,
+ please create separate issues for them. Don't report them in the same issue
+ – it makes attribution difficult.
+
+> __Why we need this__: describing the problem clearly and concisely is a
+> prerequisite for improving our documentation – we need to understand what's
+> wrong, so we can fix it.
+
+### Related links
+
+After you described the documentation section that needs to be adjusted above,
+we now ask you to share the link to this specific documentation section and
+other possibly related sections. Make sure to use anchor links (permanent links)
+where possible, as it simplifies discovery.
+
+> __Why we need this__: providing the links to the documentation help us
+> understand which sections of our documentation need to be adjusted, extended,
+> or overhauled.
+
+
+### Proposed change <small>optional</small> { #proposed-change }
+
+Now that you have provided us with the description and links to the
+documentation sections, you can help us, maintainers, and the community by
+proposing an improvement. You can sketch out rough ideas or write a concrete
+proposal. This field is optional but very helpful.
+
+> __Why we need this__: an improvement proposal can be beneficial for other
+> users who encounter the same issue, as they offer solutions before we
+> maintainers can update the documentation.
+
+### Checklist
+
+Thanks for following the guide and providing valuable feedback for our
+documentation – you are almost done. The checklist ensures that you have read
+this guide and have worked to your best knowledge to provide us with every piece
+of information we need to improve it.
+
+__We'll take it from here.__
diff --git a/documents/markdown/mkdocs-material/contributing_requesting-a-change.md b/documents/markdown/mkdocs-material/contributing_requesting-a-change.md
new file mode 100644
index 0000000..3c58cb3
--- /dev/null
+++ b/documents/markdown/mkdocs-material/contributing_requesting-a-change.md
@@ -0,0 +1,282 @@
+# Change requests
+
+Material for MkDocs is a powerful tool for creating beautiful and functional
+documentation. With more than 20,000 users, we understand that our project
+serves a wide range of use cases, which is why we have created the following
+guide.
+
+---
+
+Put yourself in our shoes – with a project of this size, it can be challenging
+to maintain existing functionality while constantly adding new features at the
+same time. We highly value every idea or contribution from our community, and
+we kindly ask you to take the time to read the following guidelines before
+submitting your change request in our public [issue tracker]. This will help us
+better understand the proposed change and how it will benefit our community.
+
+This guide is our best effort to explain the criteria and reasoning behind our
+decisions when evaluating change requests and considering them for
+implementation.
+
+ [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+
+!!! warning "[How we manage change requests]"
+
+ Before submitting a new idea, please take a moment to read how we manage
+ change requests
+
+
+ [How we manage change requests]: #how-we-manage-change-requests
+
+## Before creating an issue
+
+Before you invest your time to fill out and submit a change request, we kindly
+ask you to do some preliminary work by answering some questions to determine if
+your idea is a good fit for Material for MkDocs and matches the project's
+[philosophy] and tone.
+
+__Please do the following things before creating an issue.__
+
+ [philosophy]: ../philosophy.md
+
+### It's not a bug, it's a feature
+
+Change requests are intended to suggest minor adjustments, ideas for new
+features, or to kindly influence the project's direction and vision. It is
+important to note that change requests are not intended for reporting bugs, as
+they're missing essential information for debugging.
+
+If you want to report a bug, please refer to our [bug reporting guide] instead.
+
+ [bug reporting guide]: reporting-a-bug.md
+
+### Look for sources of inspiration
+
+If you have seen your idea implemented in another static site generator or
+theme, make sure to collect enough information on its implementation before
+submitting, as this allows us to evaluate potential fit more quickly. Explain
+what you like and dislike about the implementation.
+
+### Connect with our community
+
+Our [discussion board] is the best place to connect with our community. When
+evaluating new ideas, it's essential to seek input from other users and consider
+alternative viewpoints. This approach helps to implement new features in a way
+that benefits a large number of users.
+
+__Keep track of all <u>search terms</u> and <u>relevant links</u>, you'll need
+them in the change request.__[^1]
+
+ [^1]:
+ We might be using terminology in our documentation different from yours,
+ but we mean the same. When you include the search terms and related links
+ in your change request, you help us to adjust and improve the documentation.
+
+[:octicons-comment-discussion-16: Start a discussion][discussion board]{ .md-button .md-button--primary }
+
+ [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
+
+## Issue template
+
+Now that you have taken the time to do the necessary preliminary work and ensure
+that your idea meets our requirements, you are invited to create a change
+request. The following guide will walk you through all the necessary steps to
+help you submit a comprehensive and useful issue:
+
+- [Title]
+- [Context] <small>optional</small>
+- [Description]
+- [Related links]
+- [Use cases]
+- [Visuals] <small>optional</small>
+- [Checklist]
+
+ [Title]: #title
+ [Context]: #context
+ [Description]: #description
+ [Related links]: #related-links
+ [Use cases]: #use-cases
+ [Visuals]: #visuals
+ [Checklist]: #checklist
+
+### Title
+
+A good title is short and descriptive. It should be a one-sentence executive
+summary of the idea, so the potential impact and benefit for our community can
+be inferred from the title.
+
+| <!-- --> | Example |
+| -------- | -------- |
+| :material-check:{ style="color: #4DB6AC" } __Clear__ | Index custom front matter in search
+| :material-close:{ style="color: #EF5350" } __Wordy__ | Add a feature where authors can define custom front matter to be indexed in search
+| :material-close:{ style="color: #EF5350" } __Unclear__ | Improve search
+| :material-close:{ style="color: #EF5350" } __Useless__ | Help
+
+### Context <small>optional</small> { #context }
+
+Before describing your idea, you can provide additional context for us to
+understand what you are trying to achieve. Explain the circumstances
+in which you're using Material for MkDocs, and what you _think_ might be
+relevant. Don't write about the change request here.
+
+> __Why this might be helpful__: some ideas might only benefit specific
+> settings, environments, or edge cases, for example, when your documentation
+> contains thousands of documents. With a little context, change requests
+> can be prioritized more accurately.
+
+### Description
+
+Next, provide a detailed and clear description of your idea. Explain why your
+idea is relevant to Material for MkDocs and must be implemented here and not
+in one of its dependencies:[^2]
+
+ [^2]:
+ Sometimes, users suggest ideas on our [issue tracker] that concern one of
+ our upstream dependencies, including [MkDocs][mkdocs], [Python Markdown],
+ [Python Markdown Extensions] or third-party plugins. It's a good idea to
+ think about whether your idea is beneficial to other themes, upstreaming
+ change requests for a bigger impact.
+
+- __Explain the <u>what</u>, not the <u>why</u>__ – don't explain
+ [the benefits of your idea][Use cases] here, we're getting there.
+ Focus on describing the proposed change request as precisely as possible.
+
+- __Keep it short and concise__ – be brief and to the point when describing
+ your idea, there is no need to over-describe it. Maintainers and future
+ users will be grateful for having to read less.
+
+- __One idea at a time__ – if you have multiple ideas that don't belong
+ together, please open separate change requests for each of those ideas.
+
+---
+
+:material-run-fast: __Stretch goal__ – if you have a customization or another
+way to add the proposed change, you can help other users by sharing it here
+before we maintainers can add it to our code base.
+
+> __Why we need this__: To understand and evaluate your proposed change, we
+> need to have a clear understanding of your idea. By providing a detailed and
+> precise description, you can help save you and us time spent discussing
+> further clarification of your idea in the comments.
+
+ [Python Markdown]: https://python-markdown.github.io/extensions/
+ [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
+
+### Related links
+
+Please provide any relevant links to issues, discussions, or documentation
+sections related to your change request. If you (or someone else) already
+discussed this idea with our community on our discussion board, please include
+the link to the discussion as well.
+
+> __Why we need this__: Related links help us gain a comprehensive
+> understanding of your change request by providing additional context.
+> Additionally, linking to previous issues and discussions allows us
+> to quickly evaluate the feedback and input already provided by our community.
+
+### Use cases
+
+Explain how your change request would work from an author's and user's
+perspective – what's the expected impact, and why does it not only benefit you,
+but other users? How many of them? Furthermore, would it potentially break
+existing functionality?
+
+> __Why we need this__: Understanding the use cases and benefits of an idea is
+> crucial in evaluating its potential impact and usefulness for the project and
+> its users. This information helps us to understand the expected value of the
+> idea and how it aligns with the goals of the project.
+
+### Visuals <small>optional</small> { #visuals }
+
+We now have a clear and detailed description of your idea, including information
+on its potential use cases and relevant links for context. If you have any
+visuals, such as sketches, screenshots, mockups, or external assets, you may
+present them in this section.
+
+__You can drag and drop the files here or include links to external assets.__
+
+Additionally, if you have seen this change, feature, or improvement used in
+other static site generators or themes, please provide an example by showcasing
+it and describing how it was implemented and incorporated.
+
+> __Why this might be helpful__: Illustrations and visuals can help us
+> maintainers better understand and envision your idea. Screenshots, sketches,
+> or mockups can create an additional level of detail and clarity that text
+> alone may not be able to convey. Also, seeing how your idea has been
+> implemented in other projects can help us understand its potential impact and
+> feasibility in Material for MkDocs, which helps us maintainers evaluate and
+> triage change requests.
+
+### Checklist
+
+Thanks for following the guide and creating a high-quality change request – you
+are almost done. The checklist ensures that you have read this guide and have
+worked to your best knowledge to provide us with every piece of information to
+review your idea for Material for MkDocs.
+
+__We'll take it from here.__
+
+---
+
+## How we manage change requests
+
+Change requests are submitted as issues on our public [issue tracker]. Since
+they often propose new features or enhancements, we review and manage them
+differently than bug reports.
+
+To maintain clarity and ensure that our roadmap remains focused and achievable,
+we've introduced a structured process and use a dedicated [backlog] to
+track and organize change requests, and how they fit into our roadmap.
+
+ [backlog]: https://github.com/users/squidfunk/projects/4/views/1
+
+Here’s how we handle new change requests:
+
+1. We read and review the request to understand the idea.
+2. We may leave comments to clarify intent or suggest alternatives.
+3. If the idea is out of scope, we will close the request and explain why.
+4. If the idea aligns with the project's vision, we'll categorize it as a change
+request, and add it to our [backlog].
+5. In either case, we close the request to keep the issue tracker clean and
+focused on open bugs.
+
+> Note: While the issue may be closed, that doesn't mean it's forgotten –
+> change requests added to the project board remain part of our long-term
+> planning.
+
+__Benefits of this approach:__
+- Users get a clearer and quicker overview of known issues and bugs, as change
+requests are managed separately, giving a better idea how actively this project
+is maintained.
+- Related ideas are grouped in the backlog, allowing us to track progress more
+effectively, and to more easily see which change requests are related.
+
+## Rejected requests
+
+__Your change request got rejected? We're sorry for that.__ We understand it can
+be frustrating when your ideas don't get accepted, but as the maintainers of a
+very popular project, we always need to consider the needs of our entire
+community, sometimes forcing us to make tough decisions.
+
+We always have to consider and balance many factors when evaluating change
+requests, and we explain the reasoning behind our decisions whenever we can.
+If you're unsure why your change request was rejected, please don't hesitate
+to ask for clarification.
+
+The following principles (in no particular order) form the basis for our
+decisions:
+
+- [ ] Alignment with vision and tone of the project
+- [ ] Compatibility with existing features and plugins
+- [ ] Compatibility with all screen sizes and browsers
+- [ ] Effort of implementation and maintenance
+- [ ] Usefulness to the majority of users
+- [ ] Simplicity and ease of use
+- [ ] Accessibility
+
+But that's not the end of your idea – you can always implement it on your own
+via [customization]. If you're unsure about how to do that or want to know if
+someone has already done it, feel free to get in touch with our community on
+the [discussion board].
+
+ [customization]: ../customization.md
diff --git a/documents/markdown/mkdocs-material/conventions.md b/documents/markdown/mkdocs-material/conventions.md
new file mode 100644
index 0000000..54b5619
--- /dev/null
+++ b/documents/markdown/mkdocs-material/conventions.md
@@ -0,0 +1,79 @@
+# Conventions
+
+This section explains several conventions used in this documentation.
+
+## Symbols
+
+This documentation use some symbols for illustration purposes. Before you read
+on, please make sure you've made yourself familiar with the following list of
+conventions:
+
+### <!-- md:version --> – Version { data-toc-label="Version" }
+
+The tag symbol in conjunction with a version number denotes when a specific
+feature or behavior was added. Make sure you're at least on this version
+if you want to use it.
+
+### <!-- md:default --> – Default value { #default data-toc-label="Default value" }
+
+Some properties in `mkdocs.yml` have default values for when the author does not
+explicitly define them. The default value of the property is always included.
+
+#### <!-- md:default computed --> – Default value is computed { #default data-toc-label="is computed" }
+
+Some default values are not set to static values but computed from other values,
+like the site language, repository provider, or other settings.
+
+#### <!-- md:default none --> – Default value is empty { #default data-toc-label="is empty" }
+
+Some properties do not contain default values. This means that the functionality
+that is associated with them is not available unless explicitly enabled.
+
+### <!-- md:flag metadata --> – Metadata property { #metadata data-toc-label="Metadata property" }
+
+This symbol denotes that the thing described is a metadata property, which can
+be used in Markdown documents as part of the front matter definition.
+
+### <!-- md:flag multiple --> – Multiple instances { #multiple-instances data-toc-label="Multiple instances" }
+
+This symbol denotes that the plugin supports multiple instances, i.e, that it
+can be used multiple times in the `plugins` setting in `mkdocs.yml`.
+
+### <!-- md:feature --> – Optional feature { #feature data-toc-label="Optional feature" }
+
+Most of the features are hidden behind feature flags, which means they must
+be explicitly enabled via `mkdocs.yml`. This allows for the existence of
+potentially orthogonal features.
+
+### <!-- md:flag experimental --> – Experimental { data-toc-label="Experimental" }
+
+Some newer features are still considered experimental, which means they might
+(although rarely) change at any time, including their complete removal (which
+hasn't happened yet).
+
+### <!-- md:plugin --> – Plugin { data-toc-label="Plugin" }
+
+Several features are implemented through MkDocs excellent plugin architecture,
+some of which are built-in and distributed with Material for MkDocs, so no
+installation is required.
+
+### <!-- md:extension --> – Markdown extension { data-toc-label="Markdown extension" #extension }
+
+This symbol denotes that the thing described is a Markdown extension, which can
+be enabled in `mkdocs.yml` and adds additional functionality to the Markdown
+parser.
+
+### <!-- md:flag required --> – Required value { #required data-toc-label="Required value" }
+
+Some (very few in fact) properties or settings are required, which means the
+authors must explicitly define them.
+
+### <!-- md:flag customization --> – Customization { #customization data-toc-label="Customization" }
+
+This symbol denotes that the thing described is a customization that must be
+added by the author.
+
+### <!-- md:utility --> – Utility { data-toc-label="Utility" }
+
+Besides plugins, there are some utilities that build on top of MkDocs in order
+to provide extended functionality, like for example support for versioning.
diff --git a/documents/markdown/mkdocs-material/creating-your-site.md b/documents/markdown/mkdocs-material/creating-your-site.md
new file mode 100644
index 0000000..cd0378e
--- /dev/null
+++ b/documents/markdown/mkdocs-material/creating-your-site.md
@@ -0,0 +1,269 @@
+# Creating your site
+
+After you've [installed] Material for MkDocs, you can bootstrap your project
+documentation using the `mkdocs` executable. Go to the directory where you want
+your project to be located and enter:
+
+```
+mkdocs new .
+```
+
+Alternatively, if you're running Material for MkDocs from within Docker, use:
+
+=== "Unix, Powershell"
+
+ ```
+ docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .
+ ```
+
+=== "Windows (cmd)"
+
+ ```
+ docker run --rm -it -v "%cd%":/docs squidfunk/mkdocs-material new .
+ ```
+
+This will create the following structure:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+│ └─ index.md
+└─ mkdocs.yml
+```
+
+ [installed]: getting-started.md
+
+## Configuration
+
+### Minimal configuration
+
+Simply set the `site_name` and add the following lines to `mkdocs.yml` to enable the theme:
+
+``` yaml hl_lines="2-5"
+site_name: My site
+site_url: https://mydomain.org/mysite
+theme:
+ name: material
+```
+
+The `site_url` setting is important for a number of reasons.
+By default, MkDocs will assume that your site is hosted at the root of
+your domain. This is not the case, for example, when [publishing to GitHub
+pages] - unless you use a custom domain. Another reason is that some of the
+plugins require the `site_url` to be set, so you should always do this.
+
+ [publishing to GitHub pages]: publishing-your-site.md#github-pages
+ [installation methods]: getting-started.md#installation
+
+???+ tip "Recommended: [configuration validation and auto-complete]"
+
+ In order to minimize friction and maximize productivity, Material for MkDocs
+ provides its own [schema.json][^1] for `mkdocs.yml`. If your editor supports
+ YAML schema validation, it's definitely recommended to set it up:
+
+ === "Visual Studio Code"
+
+ 1. Install [`vscode-yaml`][vscode-yaml] for YAML language support.
+ 2. Add the schema under the `yaml.schemas` key in your user or
+ workspace [`settings.json`][settings.json]:
+
+ ``` json
+ {
+ "yaml.schemas": {
+ "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
+ },
+ "yaml.customTags": [ // (1)!
+ "!ENV scalar",
+ "!ENV sequence",
+ "!relative scalar",
+ "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
+ "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
+ "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format",
+ "tag:yaml.org,2002:python/object/apply:pymdownx.slugs.slugify mapping"
+ ]
+ }
+ ```
+
+ 1. This setting is necessary if you plan to use [icons and emojis],
+ or Visual Studio Code will show errors on certain lines.
+
+ === "Other"
+
+ 1. Ensure your editor of choice has support for YAML schema validation.
+ 2. Add the following lines at the top of `mkdocs.yml`:
+
+ ``` yaml
+ # yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
+ ```
+
+ [^1]:
+ If you're a MkDocs plugin or Markdown extension author and your project
+ works with Material for MkDocs, you're very much invited to contribute a
+ schema for your [extension] or [plugin] as part of a pull request on GitHub.
+ If you already have a schema defined, or wish to self-host your schema to
+ reduce duplication, you can add it via [$ref].
+
+ [configuration validation and auto-complete]: https://x.com/squidfunk/status/1487746003692400642
+ [schema.json]: schema.json
+ [vscode-yaml]: https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml
+ [settings.json]: https://code.visualstudio.com/docs/getstarted/settings
+ [extension]: https://github.com/squidfunk/mkdocs-material/tree/master/docs/schema/extensions
+ [plugin]: https://github.com/squidfunk/mkdocs-material/tree/master/docs/schema/plugins
+ [$ref]: https://json-schema.org/understanding-json-schema/structuring.html#ref
+ [icons and emojis]: reference/icons-emojis.md
+
+### Advanced configuration
+
+Material for MkDocs comes with many configuration options. The setup section
+explains in great detail how to configure and customize colors, fonts, icons
+and much more:
+
+<div class="mdx-columns" markdown>
+
+- [Changing the colors]
+- [Changing the fonts]
+- [Changing the language]
+- [Changing the logo and icons]
+- [Ensuring data privacy]
+- [Setting up navigation]
+- [Setting up site search]
+- [Setting up site analytics]
+- [Setting up social cards]
+- [Setting up a blog]
+- [Setting up tags]
+- [Setting up versioning]
+- [Setting up the header]
+- [Setting up the footer]
+- [Adding a git repository]
+- [Adding a comment system]
+- [Building an optimized site]
+- [Building for offline usage]
+
+</div>
+
+Furthermore, see the list of supported [Markdown extensions] that are natively
+integrated with Material for MkDocs, delivering an unprecedented low-effort
+technical writing experience.
+
+ [Changing the colors]: setup/changing-the-colors.md
+ [Changing the fonts]: setup/changing-the-fonts.md
+ [Changing the language]: setup/changing-the-language.md
+ [Changing the logo and icons]: setup/changing-the-logo-and-icons.md
+ [Ensuring data privacy]: setup/ensuring-data-privacy.md
+ [Setting up navigation]: setup/setting-up-navigation.md
+ [Setting up site search]: setup/setting-up-site-search.md
+ [Setting up site analytics]: setup/setting-up-site-analytics.md
+ [Setting up social cards]: setup/setting-up-social-cards.md
+ [Setting up a blog]: setup/setting-up-a-blog.md
+ [Setting up tags]: setup/setting-up-tags.md
+ [Setting up versioning]: setup/setting-up-versioning.md
+ [Setting up the header]: setup/setting-up-the-header.md
+ [Setting up the footer]: setup/setting-up-the-footer.md
+ [Adding a git repository]: setup/adding-a-git-repository.md
+ [Adding a comment system]: setup/adding-a-comment-system.md
+ [Building for offline usage]: setup/building-for-offline-usage.md
+ [Building an optimized site]: setup/building-an-optimized-site.md
+ [Markdown extensions]: setup/extensions/index.md
+
+## Templates
+
+If you want to jump start a new project, you can use one of our growing
+collection of templates:
+
+<div class="grid cards" markdown>
+
+- :octicons-repo-template-24: __[Blog][blog-template]__
+
+ ---
+
+ Create a blog
+
+- :octicons-repo-template-24: __[Social cards][social-cards-template]__
+
+ ---
+
+ Create documentation with social cards
+
+</div>
+
+[blog-template]: https://github.com/mkdocs-material/create-blog
+[social-cards-template]: https://github.com/mkdocs-material/create-social-cards
+
+## Previewing as you write
+
+MkDocs includes a live preview server, so you can preview your changes as you
+write your documentation. The server will automatically rebuild the site upon
+saving. Start it with:
+
+``` sh
+mkdocs serve # (1)!
+```
+
+1. If you have a large documentation project, it might take minutes until
+ MkDocs has rebuilt all pages for you to preview. If you're only interested
+ in the current page, the [`--dirtyreload`][--dirtyreload] flag will make
+ rebuilds much faster:
+
+ ```
+ mkdocs serve --dirtyreload
+ ```
+
+If you're running Material for MkDocs from within Docker, use:
+
+=== "Unix, Powershell"
+
+ ```
+ docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
+ ```
+
+=== "Windows"
+
+ ```
+ docker run --rm -it -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material
+ ```
+
+Point your browser to [localhost:8000][live preview] and you should see:
+
+[![Creating your site]][Creating your site]
+
+ [--dirtyreload]: https://www.mkdocs.org/about/release-notes/#support-for-dirty-builds-990
+ [live preview]: http://localhost:8000
+ [Creating your site]: assets/screenshots/creating-your-site.png
+
+## Building your site
+
+When you're finished editing, you can build a static site from your Markdown
+files with:
+
+```
+mkdocs build
+```
+
+If you're running Material for MkDocs from within Docker, use:
+
+=== "Unix, Powershell"
+
+ ```
+ docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build
+ ```
+
+=== "Windows"
+
+ ```
+ docker run --rm -it -v "%cd%":/docs squidfunk/mkdocs-material build
+ ```
+
+The contents of this directory make up your project documentation. There's no
+need for operating a database or server, as it is completely self-contained.
+The site can be hosted on [GitHub Pages], [GitLab Pages], a CDN of your choice
+or your private web space.
+
+ [GitHub Pages]: publishing-your-site.md#github-pages
+ [GitLab pages]: publishing-your-site.md#gitlab-pages
+
+If you intend to distribute your documentation as a set of files to be
+read from a local filesystem rather than a web server (such as in a
+`.zip` file), please read the notes about [building for offline
+usage].
+
+ [building for offline usage]: setup/building-for-offline-usage.md
diff --git a/documents/markdown/mkdocs-material/customization.md b/documents/markdown/mkdocs-material/customization.md
new file mode 100644
index 0000000..8d5f8d7
--- /dev/null
+++ b/documents/markdown/mkdocs-material/customization.md
@@ -0,0 +1,367 @@
+# Customization
+
+Project documentation is as diverse as the projects themselves and Material for
+MkDocs is a great starting point for making it look beautiful. However, as you
+write your documentation, you may reach a point where small adjustments are
+necessary to preserve your brand's style.
+
+## Adding assets
+
+[MkDocs] provides several ways to customize a theme. In order to make a few
+small tweaks to Material for MkDocs, you can just add CSS and JavaScript files to
+the `docs` directory.
+
+ [MkDocs]: https://www.mkdocs.org
+
+### Additional CSS
+
+If you want to tweak some colors or change the spacing of certain elements,
+you can do this in a separate style sheet. The easiest way is by creating a
+new style sheet file in the `docs` directory:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+│ └─ stylesheets/
+│ └─ extra.css
+└─ mkdocs.yml
+```
+
+Then, add the following lines to `mkdocs.yml`:
+
+``` yaml
+extra_css:
+ - stylesheets/extra.css
+```
+
+### Additional JavaScript
+
+If you want to integrate another syntax highlighter or add some custom logic to
+your theme, create a new JavaScript file in the `docs` directory:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+│ └─ javascripts/
+│ └─ extra.js
+└─ mkdocs.yml
+```
+
+Then, add the following lines to `mkdocs.yml`:
+
+``` yaml
+extra_javascript:
+ - javascripts/extra.js
+```
+
+??? tip "How to integrate with third-party JavaScript libraries"
+
+ It is likely that you will want to run your JavaScript code only
+ once the page has been fully loaded by the browser. This means
+ installing a callback function subscribing to events on the
+ `document$` observable exported by Material for MkDocs.
+ Using the `document$` observable is particularly important if you
+ are using [instant loading] since it will not result in a page
+ refresh in the browser - but subscribers on the observable will be
+ notified.
+
+ ``` javascript
+ document$.subscribe(function() {
+ console.log("Initialize third-party libraries here")
+ })
+ ```
+
+ `document$` is an [RxJS Observable] and you can call the `subscribe()`
+ method any number of times to attach different functionality.
+
+ [instant loading]: setup/setting-up-navigation.md/#instant-loading
+ [RxJS Observable]: https://rxjs.dev/api/index/class/Observable
+
+## Extending the theme
+
+If you want to alter the HTML source (e.g. add or remove some parts), you can
+extend the theme. MkDocs supports [theme extension], an easy way to override
+parts of Material for MkDocs without forking from git. This ensures that you
+can update to the latest version more easily.
+
+ [theme extension]: https://www.mkdocs.org/user-guide/customizing-your-theme/#using-the-theme-custom_dir
+
+### Setup and theme structure
+
+Enable Material for MkDocs as usual in `mkdocs.yml`, and create a new folder
+for `overrides` which you then reference using the [`custom_dir`][custom_dir]
+setting:
+
+``` yaml
+theme:
+ name: material
+ custom_dir: overrides
+```
+
+!!! warning "Theme extension prerequisites"
+
+ As the [`custom_dir`][custom_dir] setting is used for the theme extension
+ process, Material for MkDocs needs to be installed via `pip` and referenced
+ with the [`name`][name] setting in `mkdocs.yml`. It will not work when
+ cloning from `git`.
+
+The structure in the `overrides` directory must mirror the directory structure
+of the original theme, as any file in the `overrides` directory will replace the
+file with the same name which is part of the original theme. Besides, further
+assets may also be put in the `overrides` directory:
+
+``` { .sh .no-copy }
+.
+├─ .icons/ # Bundled icon sets
+├─ assets/
+│ ├─ images/ # Images and icons
+│ ├─ javascripts/ # JavaScript files
+│ └─ stylesheets/ # Style sheets
+├─ partials/
+│ ├─ integrations/ # Third-party integrations
+│ │ ├─ analytics/ # Analytics integrations
+│ │ └─ analytics.html # Analytics setup
+│ ├─ languages/ # Translation languages
+│ ├─ actions.html # Actions
+│ ├─ alternate.html # Site language selector
+│ ├─ comments.html # Comment system (empty by default)
+│ ├─ consent.html # Consent
+│ ├─ content.html # Page content
+│ ├─ copyright.html # Copyright and theme information
+│ ├─ feedback.html # Was this page helpful?
+│ ├─ footer.html # Footer bar
+│ ├─ header.html # Header bar
+│ ├─ icons.html # Custom icons
+│ ├─ language.html # Translation setup
+│ ├─ logo.html # Logo in header and sidebar
+│ ├─ nav.html # Main navigation
+│ ├─ nav-item.html # Main navigation item
+│ ├─ pagination.html # Pagination (used for blog)
+│ ├─ palette.html # Color palette toggle
+│ ├─ post.html # Blog post excerpt
+│ ├─ progress.html # Progress indicator
+│ ├─ search.html # Search interface
+│ ├─ social.html # Social links
+│ ├─ source.html # Repository information
+│ ├─ source-file.html # Source file information
+│ ├─ tabs.html # Tabs navigation
+│ ├─ tabs-item.html # Tabs navigation item
+│ ├─ tags.html # Tags
+│ ├─ toc.html # Table of contents
+│ ├─ toc-item.html # Table of contents item
+│ └─ top.html # Back-to-top button
+├─ 404.html # 404 error page
+├─ base.html # Base template
+├─ blog.html # Blog index page
+├─ blog-archive.html # Blog archive index page
+├─ blog-category.html # Blog category index page
+├─ blog-post.html # Blog post page
+└─ main.html # Default page
+```
+
+ [custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
+ [name]: https://www.mkdocs.org/user-guide/configuration/#name
+
+### Overriding partials
+
+In order to override a partial, we can replace it with a file of the same name
+and location in the `overrides` directory. For example, to replace the original
+`footer.html` partial, create a new `footer.html` partial in the `overrides`
+directory:
+
+``` { .sh .no-copy }
+.
+├─ overrides/
+│ └─ partials/
+│ └─ footer.html
+└─ mkdocs.yml
+```
+
+MkDocs will now use the new partial when rendering the theme. This can be done
+with any file.
+
+### Overriding blocks <small>recommended</small> { #overriding-blocks data-toc-label="Overriding blocks" }
+
+Besides overriding partials, it's also possible to override (and extend)
+template blocks, which are defined inside the templates and wrap specific
+features. In order to set up block overrides, create a `main.html` file inside
+the `overrides` directory:
+
+``` { .sh .no-copy }
+.
+├─ overrides/
+│ └─ main.html
+└─ mkdocs.yml
+```
+
+Then, e.g. to override the site title, add the following lines to `main.html`:
+
+``` html
+{% extends "base.html" %}
+
+{% block htmltitle %}
+ <title>Lorem ipsum dolor sit amet</title>
+{% endblock %}
+```
+
+If you intend to __add__ something to a block rather than to replace it
+altogether with new content, use `{{ super() }}` inside the block to include the
+original block content. This is particularly useful when adding third-party
+scripts to your docs, e.g.
+
+``` html
+{% extends "base.html" %}
+
+{% block scripts %}
+ <!-- Add scripts that need to run before here -->
+ {{ super() }}
+ <!-- Add scripts that need to run afterwards here -->
+{% endblock %}
+```
+
+The following template blocks are provided by the theme:
+
+| Block name | Purpose |
+| :---------------- | :---------------------------------------------- |
+| `analytics` | Wraps the Google Analytics integration |
+| `announce` | Wraps the announcement bar |
+| `config` | Wraps the JavaScript application config |
+| `container` | Wraps the main content container |
+| `content` | Wraps the main content |
+| `extrahead` | Empty block to add custom meta tags |
+| `fonts` | Wraps the font definitions |
+| `footer` | Wraps the footer with navigation and copyright |
+| `header` | Wraps the fixed header bar |
+| `hero` | Wraps the hero teaser (if available) |
+| `htmltitle` | Wraps the `<title>` tag |
+| `libs` | Wraps the JavaScript libraries (header) |
+| `outdated` | Wraps the version warning |
+| `scripts` | Wraps the JavaScript application (footer) |
+| `site_meta` | Wraps the meta tags in the document head |
+| `site_nav` | Wraps the site navigation and table of contents |
+| `styles` | Wraps the style sheets (also extra sources) |
+| `tabs` | Wraps the tabs navigation (if available) |
+
+## Theme development
+
+Material for MkDocs is built on top of [TypeScript], [RxJS] and [SASS], and
+uses a lean, custom build process to put everything together.[^1] If you want
+to make more fundamental changes, it may be necessary to make the adjustments
+directly in the source of the theme and recompile it.
+
+ [^1]:
+ Prior to <!-- md:version 7.0.0 --> the build was based on Webpack, resulting
+ in occasional broken builds due to incompatibilities with loaders and
+ plugins. Therefore, we decided to swap Webpack for a leaner solution which
+ is now based on [RxJS] as the application itself. This allowed for the
+ pruning of more than 500 dependencies (~30% less).
+
+ [TypeScript]: https://www.typescriptlang.org/
+ [RxJS]: https://github.com/ReactiveX/rxjs
+ [SASS]: https://sass-lang.com
+
+### Environment setup
+
+First, clone the repository:
+
+```
+git clone https://github.com/squidfunk/mkdocs-material
+cd mkdocs-material
+```
+
+Next, create a new [Python virtual environment][venv] and
+[activate][venv-activate] it:
+
+```
+python -m venv venv
+source venv/bin/activate
+```
+
+!!! note "Ensure pip always runs in a virtual environment"
+
+ If you set the environment variable `PIP_REQUIRE_VIRTUALENV` to
+ `true`, `pip` will refuse to install anything outside a virtual
+ environment. Forgetting to activate a `venv` can be very annoying
+ as it will install all sorts of things outside virtual
+ environments over time, possibly leading to further errors. So,
+ you may want to add this to your `.bashrc` or `.zshrc` and
+ re-start your shell:
+
+ ```
+ export PIP_REQUIRE_VIRTUALENV=true
+ ```
+
+ [venv]: https://docs.python.org/3/library/venv.html
+ [venv-activate]: https://docs.python.org/3/library/venv.html#how-venvs-work
+
+Then, install all Python dependencies:
+
+```
+pip install -e ".[git, recommended, imaging]"
+pip install nodeenv
+```
+
+In addition, you will need to install the `cairo` and `pngquant` libraries in your
+system, as described in the [image processing] requirements guide.
+
+[image processing]: plugins/requirements/image-processing.md
+
+Finally, install the [Node.js] LTS version into the Python virtual environment
+and install all Node.js dependencies:
+
+```
+nodeenv -p -n lts
+npm install
+```
+
+ [Node.js]: https://nodejs.org
+
+### Development mode
+
+Start the watcher with:
+
+```
+npm start
+```
+
+Then, in a second terminal window, start the MkDocs live preview server with:
+
+```
+mkdocs serve --watch-theme
+```
+
+Point your browser to [localhost:8000][live preview] and you should see this
+very documentation in front of you.
+
+!!! warning "Automatically generated files"
+
+ Never make any changes in the `material` directory, as the contents of this
+ directory are automatically generated from the `src` directory and will be
+ overwritten when the theme is built.
+
+ [live preview]: http://localhost:8000
+
+### Building the theme
+
+When you're finished making your changes, you can build the theme by invoking:
+
+``` sh
+npm run build # (1)!
+```
+
+1. While this command will build all theme files, it will skip the overrides
+ used in Material for MkDocs' own documentation which are not distributed
+ with the theme. If you forked the theme and want to build the overrides
+ as well, e.g. before submitting a PR with changes, use:
+
+ ```
+ npm run build:all
+ ```
+
+ This will take longer, as now the icon search index, schema files, as
+ well as additional style sheet and JavaScript files are built.
+
+This triggers the production-level compilation and minification of all style
+sheets and JavaScript files. After the command exits, the compiled files are
+located in the `material` directory. When running `mkdocs build`, you should
+now see your changes to the original theme.
diff --git a/documents/markdown/mkdocs-material/getting-started.md b/documents/markdown/mkdocs-material/getting-started.md
new file mode 100644
index 0000000..b58a757
--- /dev/null
+++ b/documents/markdown/mkdocs-material/getting-started.md
@@ -0,0 +1,169 @@
+# Getting started
+
+Material for MkDocs is a powerful documentation framework on top of [MkDocs],
+a static site generator for project documentation.[^1] If you're familiar with
+Python, you can install Material for MkDocs with [`pip`][pip], the Python
+package manager. If not, we recommend using [`docker`][docker].
+
+ [^1]:
+ In 2016, Material for MkDocs started out as a simple theme for MkDocs, but
+ over the course of several years, it's now much more than that – with the
+ many built-in plugins, settings, and countless customization abilities,
+ Material for MkDocs is now one of the simplest and most powerful frameworks
+ for creating documentation for your project.
+
+ [MkDocs]: https://www.mkdocs.org
+ [pip]: #with-pip
+ [docker]: #with-docker
+
+## Installation
+
+### with pip <small>recommended</small> { #with-pip data-toc-label="with pip" }
+
+Material for MkDocs is published as a [Python package] and can be installed with
+`pip`, ideally by using a [virtual environment]. Open up a terminal and install
+Material for MkDocs with:
+
+=== "Latest"
+
+ ``` sh
+ pip install mkdocs-material
+ ```
+
+=== "9.x"
+
+ ``` sh
+ pip install mkdocs-material=="9.*" # (1)!
+ ```
+
+ 1. Material for MkDocs uses [semantic versioning][^2], which is why it's a
+ good idea to limit upgrades to the current major version.
+
+ This will make sure that you don't accidentally [upgrade to the next
+ major version], which may include breaking changes that silently corrupt
+ your site. Additionally, you can use `pip freeze` to create a lockfile,
+ so builds are reproducible at all times:
+
+ ```
+ pip freeze > requirements.txt
+ ```
+
+ Now, the lockfile can be used for installation:
+
+ ```
+ pip install -r requirements.txt
+ ```
+
+ [^2]:
+ Note that improvements of existing features are sometimes released as
+ patch releases, like for example improved rendering of content tabs, as
+ they're not considered to be new features.
+
+This will automatically install compatible versions of all dependencies:
+[MkDocs], [Markdown], [Pygments] and [Python Markdown Extensions]. Material for
+MkDocs always strives to support the latest versions, so there's no need to
+install those packages separately.
+
+---
+
+:fontawesome-brands-youtube:{ style="color: #EE0F0F" }
+__[How to set up Material for MkDocs]__ by @james-willett – :octicons-clock-24:
+27m – Learn how to create and host a documentation site using Material for
+MkDocs on GitHub Pages in a step-by-step guide.
+
+ [How to set up Material for MkDocs]: https://www.youtube.com/watch?v=xlABhbnNrfI
+
+---
+
+!!! tip
+
+ If you don't have prior experience with Python, we recommend reading
+ [Using Python's pip to Manage Your Projects' Dependencies], which is a
+ really good introduction on the mechanics of Python package management and
+ helps you troubleshoot if you run into errors.
+
+ [Python package]: https://pypi.org/project/mkdocs-material/
+ [virtual environment]: https://realpython.com/what-is-pip/#using-pip-in-a-python-virtual-environment
+ [semantic versioning]: https://semver.org/
+ [upgrade to the next major version]: upgrade.md
+ [Markdown]: https://python-markdown.github.io/
+ [Pygments]: https://pygments.org/
+ [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
+ [Using Python's pip to Manage Your Projects' Dependencies]: https://realpython.com/what-is-pip/
+
+### with docker
+
+The official [Docker image] is a great way to get up and running in a few
+minutes, as it comes with all dependencies pre-installed. Open up a terminal
+and pull the image with:
+
+=== "Latest"
+
+ ```
+ docker pull squidfunk/mkdocs-material
+ ```
+
+=== "9.x"
+
+ ```
+ docker pull squidfunk/mkdocs-material:9
+ ```
+
+The `mkdocs` executable is provided as an entry point and `serve` is the
+default command. If you're not familiar with Docker don't worry, we have you
+covered in the following sections.
+
+The following plugins are bundled with the Docker image:
+
+- [mkdocs-minify-plugin]
+- [mkdocs-redirects]
+
+ [Docker image]: https://hub.docker.com/r/squidfunk/mkdocs-material/
+ [mkdocs-minify-plugin]: https://github.com/byrnereese/mkdocs-minify-plugin
+ [mkdocs-redirects]: https://github.com/datarobot/mkdocs-redirects
+
+???+ warning
+
+ The Docker container is intended for local previewing purposes only and
+ is not suitable for deployment. This is because the web server used by
+ MkDocs for live previews is not designed for production use and may have
+ security vulnerabilities.
+
+??? question "How to add plugins to the Docker image?"
+
+ Material for MkDocs only bundles selected plugins in order to keep the size
+ of the official image small. If the plugin you want to use is not included,
+ you can add them easily. Create a `Dockerfile` and extend the official image:
+
+ ``` Dockerfile title="Dockerfile"
+ FROM squidfunk/mkdocs-material
+ RUN pip install mkdocs-macros-plugin
+ RUN pip install mkdocs-glightbox
+ ```
+
+ Next, build the image with the following command:
+
+ ```
+ docker build -t squidfunk/mkdocs-material .
+ ```
+
+ The new image will have additional packages installed and can be used
+ exactly like the official image.
+
+### with git
+
+Material for MkDocs can be directly used from [GitHub] by cloning the
+repository into a subfolder of your project root which might be useful if you
+want to use the very latest version:
+
+```
+git clone https://github.com/squidfunk/mkdocs-material.git
+```
+
+Next, install the theme and its dependencies with:
+
+```
+pip install -e mkdocs-material
+```
+
+ [GitHub]: https://github.com/squidfunk/mkdocs-material
diff --git a/documents/markdown/mkdocs-material/guides_creating-a-reproduction.md b/documents/markdown/mkdocs-material/guides_creating-a-reproduction.md
new file mode 100644
index 0000000..d7a4faa
--- /dev/null
+++ b/documents/markdown/mkdocs-material/guides_creating-a-reproduction.md
@@ -0,0 +1,124 @@
+# Creating a reproduction
+
+A reproduction is a simplified version of a bug that demonstrates the specific
+scenario in which the bug occurred. It includes all necessary minimal settings
+and instructions and should be as simple as possible while still demonstrating
+the issue.
+
+## Guide
+
+### Environment <small>optional</small> { #environment }
+
+We recommend using a [virtual environment], which is an isolated Python runtime.
+If you are in a virtual environment, any packages that you install or upgrade
+will be local to the environment. If you run into problems, you can
+just delete and recreate the environment. It's trivial to set up:
+
+- Create a new virtual environment with:
+
+ ```
+ python3 -m venv venv
+ ```
+
+- Activate the environment with:
+
+ === ":material-apple: macOS"
+
+ ``` sh
+ . venv/bin/activate
+ ```
+
+ === ":fontawesome-brands-windows: Windows"
+
+ ``` sh
+ . venv/Scripts/activate
+ ```
+
+ === ":material-linux: Linux"
+
+ ``` sh
+ . venv/bin/activate
+ ```
+
+
+ Your terminal should now print `(venv)` before the prompt, which is how you
+ know that you are inside the virtual environment that you just created.
+
+- Exit the environment with:
+
+ ```
+ deactivate
+ ```
+
+ [virtual environment]: https://realpython.com/what-is-pip/#using-pip-in-a-python-virtual-environment
+
+### Minimal reproduction
+
+Following the instructions below, you will set up a skeleton project to create
+a reproduction. As mentioned above, we recommend using a [virtual environment],
+so create a new folder in your working directory and a new virtual environment
+inside it. Next:
+
+1. As mentioned in our [bug reporting guide], ensure that you're running the
+ latest version of Material for MkDocs, which might already include a fix for
+ the bug:
+
+ ```
+ pip install --upgrade --force-reinstall mkdocs-material
+ ```
+
+2. Bootstrap a new documentation project using the `mkdocs` executable,
+ which you use as a basis for the reproduction. It's essential to create a
+ new, empty project for this:
+
+ ```
+ mkdocs new .
+ ```
+
+ Start by adding the [minimal configuration] in `mkdocs.yml`:
+
+ ``` yaml
+ theme:
+ name: material
+ ```
+
+3. Now, only add the necessary settings to `mkdocs.yml` to keep the
+ reproduction minimal. If you are creating a reproduction for a rendering
+ bug, create only the necessary amount of Markdown documents. __Repeat this
+ step until the bug you want to report can be observed.__
+
+4. As a last step, before packing everything into a `.zip` file, double-check
+ all settings and documents if they are essential to the reproduction, which
+ means that the bug does not occur when they are omitted. Remove all
+ non-essential lines and files.
+
+ [bug reporting guide]: ../contributing/reporting-a-bug.md#upgrade-to-latest-version
+ [minimal configuration]: ../creating-your-site.md#minimal-configuration
+
+### Creating a `.zip` file
+
+Material for MkDocs 9.0.0 includes a new plugin solely intended to create
+reproductions for bug reports. When the built-in info plugin is enabled, MkDocs
+will add all relevant files to a `.zip`, print a summary to the terminal and
+exit. Add the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - info
+```
+
+Now, when running `mkdocs build`, a file called `example.zip` is automatically
+created, containing the minimal reproduction you can directly attach to your bug
+report.
+
+```
+INFO - Started archive creation for bug report
+INFO - Archive successfully created:
+
+ example/.dependencies.json 859.0 B
+ example/.versions.log 83.0 B
+ example/docs/index.md 282.0 B
+ example/mkdocs.yml 56.0 B
+
+ example.zip 1.8 kB
+```
diff --git a/documents/markdown/mkdocs-material/index.md b/documents/markdown/mkdocs-material/index.md
new file mode 100644
index 0000000..3aea9df
--- /dev/null
+++ b/documents/markdown/mkdocs-material/index.md
@@ -0,0 +1,9 @@
+---
+template: home.html
+title: Material for MkDocs
+social:
+ cards_layout_options:
+ title: Documentation that simply works
+---
+
+Welcome to Material for MkDocs.
diff --git a/documents/markdown/mkdocs-material/insiders_changelog_index.md b/documents/markdown/mkdocs-material/insiders_changelog_index.md
new file mode 100644
index 0000000..4d7ba8b
--- /dev/null
+++ b/documents/markdown/mkdocs-material/insiders_changelog_index.md
@@ -0,0 +1,1127 @@
+# Changelog
+
+## Material for MkDocs Insiders
+
+### 4.53.17 <small>August 22, 2025</small> { id="4.53.17" }
+
+- Fixed #8408: Code annotations bug with custom selectors
+
+### 4.53.16 <small>March 13, 2025</small> { id="4.53.16" }
+
+- Fixed #8019: Tooltips have precedence over instant previews
+
+### 4.53.15 <small>January 15, 2025</small> { id="4.53.15" }
+
+- Fixed #7896: Scoped tags listings not rendering in subsections
+
+### 4.53.14 <small>September 29, 2024</small> { id="4.53.14" }
+
+- Fixed #7567: Empty headlines when using typeset plugin with anchorlinks
+
+### 4.53.13 <small>September 14, 2024</small> { id="4.53.13" }
+
+- Fixed #7520: Social plugin errors for generated files (MkDocs 1.6+)
+
+### 4.53.12 <small>August 2, 2024</small> { id="4.53.12" }
+
+- Fixed #7410: Instant previews jump on content tabs with anchor links
+- Fixed #7408: Instant previews jump on content tabs
+
+### 4.53.11 <small>May 27, 2024</small> { id="4.53.11" }
+
+- Fixed projects plugin crashing when serving before building subprojects
+
+### 4.53.10 <small>May 20, 2024</small> { id="4.53.10" }
+
+- Fixed projects plugin crashing in serve mode when disabled
+- Fixed projects plugin crashing when building nested projects
+
+### 4.53.9 <small>May 20, 2024</small> { id="4.53.9" }
+
+- Fixed #7191: Tags listings not rendering when `toc_depth` is changed
+
+### 4.53.8 <small>April 26, 2024</small> { id="4.53.8" }
+
+- Fixed #7052: Preview extension automatically including all pages
+- Fixed #7051: Instant previews mounting on footnote references
+- Fixed #5165: Improved tooltips not mounting in sidebar for typeset plugin
+
+### 4.53.7 <small>April 25, 2024</small> { id="4.53.7" }
+
+- Fixed #7060: Incorrect resolution of translation when using static-i18n
+
+### 4.53.6 <small>April 5, 2024</small> { id="4.53.6" }
+
+- Ensure working directory is set for projects when using projects plugin
+- Fixed #6970: Incorrect relative paths in git submodules with projects plugin
+
+### 4.53.5 <small>April 2, 2024</small> { id="4.53.5" }
+
+- Fixed social plugin crashing when no colors are specified in palettes
+
+### 4.53.4 <small>March 31, 2024</small> { id="4.53.4" }
+
+- Fixed #6973: Escaping issue in tags extra files deprecation helper
+
+### 4.53.3 <small>March 23, 2024</small> { id="4.53.3" }
+
+- Added support for font variants in social plugin
+- Improved resilience of font resolution in social plugin
+- Fixed tag listing sometimes not being auto-populated
+- Fixed tag listing scope not being correctly resolved
+- Fixed #6941: Meta plugin adding duplicate entries
+- Fixed #6928: Social plugin crashes for some fonts
+
+### 4.53.2 <small>March 18, 2024</small> { id="4.53.2" }
+
+- Fixed abort on first non-matching configuration in preview extension
+- Fixed #6914: Meta files take precedence over front matter
+
+### 4.53.1 <small>March 6, 2024</small> { id="4.53.1" }
+
+- Fixed #6877: Projects plugin computes incorrect path to assets
+- Fixed #6869: Blog plugin should emit warning on invalid related link
+
+### 4.53.0 <small>February 24, 2024</small> { id="4.53.0" }
+
+- Added support for automatic instant previews
+- Added support for pinned blog posts
+
+### 4.52.3 <small>February 21, 2024</small> { id="4.52.3" }
+
+- Fixed resolution of URLs in instant previews
+- Fixed instant previews not mounting for same-page links
+
+### 4.52.2 <small>February 7, 2024</small> { id="4.52.2" }
+
+- Fixed #6735: Instant previews misplaced when below tabs
+
+### 4.52.1 <small>January 30, 2024</small> { id="4.52.1" }
+
+- Fixed #6705: Navigation path not being hidden when specified
+- Fixed #6703: New tags plugin crashes on Windows (2nd attempt)
+
+### 4.52.0 <small>January 28, 2024</small> { id="4.52.0" }
+
+- Added support for instant previews
+- Fixed footnote tooltips positioning edge cases
+- Fixed #6703: New tags plugin crashes on Windows
+
+### 4.51.0 <small>January 24, 2024</small> { id="4.51.0" }
+
+- Added support for footnote tooltips
+
+### 4.50.0 <small>January 19, 2024</small> { id="4.50.0" }
+
+- Added configurable logging capabilities to privacy plugin
+
+### 4.49.2 <small>January 9, 2024</small> { id="4.49.2" }
+
+- Fixed missing attribute lists extension for tags plugin
+- Fixed #6627: New tags plugin crashes on Python 3.8
+
+### 4.49.1 <small>January 7, 2024</small> { id="4.49.1" }
+
+- Improved interop of new tags plugin with other plugins
+- Fixed #6594: Tags plugin doesn't work with mkdocs-macros plugin
+- Fixed #6569: Social plugin crashes if in different file system location
+
+### 4.49.0 <small>December 29, 2023</small> { id="4.49.0" }
+
+- Added support for exporting tags and mappings
+- Added support for disabling tags and/or listings or both
+- Fixed tag links from pages to listings on homepage
+
+### 4.48.0 <small>December 23, 2023</small> { id="4.48.0" }
+
+- Rewrite of tags plugin, now much more powerful
+- Added support for nested tags (tag hierarchies, e.g. foo/bar)
+- Added support for shadow tags (by list, prefix or suffix)
+- Added support for custom tag layouts and templates
+- Added support for hiding tags in table of contents
+- Added support for configurable inline tag listings
+- Added support for automatically linking to closest tag listing
+- Added support for scoped listings (limit to subsection of site)
+- Added support for multiple instances of tags plugin
+- Added support for changing front matter property and template variable
+- Added support for tag slugification format strings
+- Fixed #6510: Projects plugin out of memory on Linux (4.47.1 regression)
+- Fixed projects plugin not notifying plugins about serve mode
+- Fixed projects plugin skipping projects on prefix match
+- Deprecated tags_file and tags_extra_files settings
+- Modernized tags plugin code base
+
+### 4.47.1 <small>December 11, 2023</small> { id="4.47.1" }
+
+- Improved editing experience for projects plugin
+- Improved resilience of optimize and social plugin
+- Fixed race condition when writing manifest in optimize and social plugin
+- Fixed #6475: Logo not taking precedence over icon in social card
+- Fixed #6399: Projects plugin doesn't pick up added/removed projects
+- Fixed #6306: Projects plugin cache not correctly updated
+
+### 4.47.0 <small>December 8, 2023</small> { id="4.47.0" }
+
+- Added support for staying on page when switching languages
+- Added configurable logging capabilities to projects plugin
+- Removed temporary warning on blog plugin authors file format change
+- Fixed projects plugin logging messages twice on Linux systems
+- Fixed projects plugin trying to hoist theme assets of divergent themes
+- Fixed compatibility of optimize plugin and projects plugin
+- Fixed compatibility of social plugin and projects plugin
+- Fixed #6448: Code line selection broken for code blocks with custom ids
+- Fixed #6437: Projects plugin crashing for certain site URL configurations
+- Fixed #6414: Projects plugin doesn't prefix messages coming from projects
+
+### 4.46.0 <small>November 26, 2023</small> { id="4.46.0" }
+
+- Added support for author profiles in blog plugin
+- Fixed custom index pages yielding two navigation items (4.45.0 regression)
+
+### 4.45.0 <small>November 24, 2023</small> { id="4.45.0" }
+
+- Added support for sorting blog categories by post count or custom function
+- Improved tags plugin to generate Unicode-aware slugs by default
+- Fixed non-deterministic order of multiple authors in blog plugin
+
+### 4.44.0 <small>November 23, 2023</small> { id="4.44.0" }
+
+- Added pagination settings for archive pages in blog plugin
+- Added pagination settings for category pages in blog plugin
+
+### 4.43.1 <small>November 19, 2023</small> { id="4.43.1" }
+
+- Added third-party theme support in projects plugin, improving editing
+- Fixed #6360: Projects plugin crashes when theme is not Material for MkDocs
+- Fixed #6306: Projects plugin not reloading nested project configuration
+
+### 4.43.0 <small>November 5, 2023</small> { id="4.43.0" }
+
+- Added support for GitLab committers (document contributors)
+- Fixed #6264: Fixed compatibility with Python < 3.10
+- Fixed #6254: Meta plugin not applying meta files to blog posts
+
+### 4.42.3 <small>October 27, 2023</small> { id="4.42.3" }
+
+- Fixed #6251: Cards in grids cut off on very small screens
+- Fixed #6241: Using social plugin + static-i18n plugin errors
+
+### 4.42.2 <small>October 14, 2023</small> { id="4.42.2" }
+
+- Fixed #6186: Privacy plugin ignores hash fragments on images
+- Fixed #6180: Projects plugin crashing when adding or removing files
+
+### 4.42.1 <small>October 5, 2023</small> { id="4.42.1" }
+
+- Fixed spacing of related links in blog posts on small screens
+
+### 4.42.0 <small>September 19, 2023</small> { id="4.42.0" }
+
+- Added support for using git submodules in projects plugin
+- Added support for transforming project configurations
+- Improved resilience of optimize and blog plugin
+- Fixed optimize plugin crashing on `.jpeg` extension
+- Fixed project URLs not using site URLs in projects plugin
+
+### 4.41.0 <small>September 11, 2023</small> { id="4.41.0" }
+
+- Improved multi-instance support for optimize plugin
+- Added inclusion and exclusion patterns for optimize plugin
+- Added transparent keyword for color handling in social plugin
+- Changed default quality of PNGs to 3 in optimize plugin
+- Fixed #5979: meta file not detected in root of docs directory
+
+### 4.40.4 <small>September 4, 2023</small> { id="4.40.4" }
+
+- Fixed privacy plugin choking on boolean HTML5 attributes
+- Fixed wrapping of inline code blocks in typeset table of contents
+- Fixed blog plugin error when running under dirty reload
+
+### 4.40.3 <small>September 2, 2023</small> { id="4.40.3" }
+
+- Fixed #5946: Docker image missing pngquant for optimize plugin
+
+### 4.40.2 <small>August 31, 2023</small> { id="4.40.2" }
+
+- Added configurable error handling capabilities for social plugin
+- Fixed #5922: Blog plugin shows no posts when building a standalone blog
+- Fixed #5914: Tags plugin tags_extra_files errors (4.39.3 regression)
+- Fixed #5904: Blog plugin sometimes excludes files (4.40.1 regression)
+
+### 4.40.1 <small>August 27, 2023</small> { id="4.40.1" }
+
+- Fixed #5902: ResizeObserver polyfill not detected by privacy plugin
+- Fixed empty category pages in blog plugin (4.40.0 regression)
+
+### 4.40.0 <small>August 26, 2023</small> { id="4.40.0" }
+
+- Added logo, title and description options to social plugin default layouts
+- Fixed privacy plugin compatibility issue with Python < 3.10
+- Fixed #5896: Blog plugin errors when using custom index pages
+
+### 4.39.3 <small>August 24, 2023</small> { id="4.39.3" }
+
+- Fixed lxml dependency missing in Docker container (4.39.2 regression)
+
+### 4.39.2 <small>August 23, 2023</small> { id="4.39.2" }
+
+- Fixed color palette toggle being reversed (9.2.0 regression)
+
+### 4.39.1 <small>August 21, 2023</small> { id="4.39.1" }
+
+- Fixed git diff in tags plugin after merging back 9.2.0 changes
+
+### 4.39.0 <small>August 3, 2023</small> { id="4.39.0" }
+
+- Added support for hoisting theme media files when building projects
+- Added support for sorting pages on tags index for tags plugin
+- Added support for adding date of last update to blog posts
+- Fixed #5797: Parse error in typeset plugin (4.38.1 regression)
+
+### 4.38.1 <small>August 1, 2023</small> { id="4.38.1" }
+
+- Improved nested serve mode for projects plugin
+- Improved compat in privacy plugin with third-party plugins
+- Fixed #5790: Typeset plugin ignores data-toc-label attribute
+- Fixed #5778: Interplay of privacy plugin with git-revision-date-localized
+- Fixed #5773: Info plugin erroring when community edition is in beta
+
+### 4.38.0 <small>July 29, 2023</small> { id="4.38.0" }
+
+- Added projects plugin for building nested projects
+- Updated privacy plugin to new MkDocs API
+
+### 4.37.1 <small>July 28, 2023</small> { id="4.37.1" }
+
+- Updated MkDocs to 1.5.1
+- Fixed deprecation warning in social plugin due to MkDocs upgrade
+- Fixed #5772: Privacy plugin fails due to API change in MkDocs
+
+### 4.37.0 <small>July 7, 2023</small> { id="4.37.0" }
+
+- Added support for overriding social cards settings per page
+- Added new social card `default/only/image` layout
+- Improved resilience of optimize and social plugin
+- Fixed rendering bugs for pruned navigation items
+- Fixed jumping of content tabs anchor links when instant loading is enabled
+- Fixed #5676: Optimize plugin doesn't check for `pngquant`
+
+### 4.36.1 <small>June 23, 2023</small> { id="4.36.1" }
+
+- Fixed #5618: Date comparison breaking for drafts in blog plugin
+
+### 4.36.0 <small>June 15, 2023</small> { id="4.36.0" }
+
+- Added support for instant prefetching to speed up slow connections
+- Improved stability of anchor link removal in built-in typeset plugin
+- Improved performance of regular expressions in typeset plugin
+- Removed unnecessary import test for `cairosvg` in optimize plugin
+- Fixed #5590: Regular expression for anchor link removal too greedy
+
+### 4.35.3 <small>June 1, 2023</small> { id="4.35.3" }
+
+- Fixed #5579: Abbreviations in headlines filtered by typeset plugin
+
+### 4.35.2 <small>May 29, 2023</small> { id="4.35.2" }
+
+- Fixed #5555: Blog plugin crashes when computing readtime for emojis
+
+### 4.35.1 <small>May 20, 2023</small> { id="4.35.1" }
+
+- Fixed internal handling of errors in social plugin
+
+### 4.35.0 <small>May 20, 2023</small> { id="4.35.0" }
+
+- Improve editing experience and stability of social plugin
+- Added support for custom layout syntax validation in social plugin
+- Added support for layer origin for easier placement in social plugin
+- Added support for in- and exclusion patterns in social plugin
+- Catch and print syntax errors in custom layouts
+
+### 4.34.1 <small>May 16, 2023</small> { id="4.34.1" }
+
+- Disable social plugin debug mode by default on mkdocs build
+- Added warning in social plugin debug mode when font style couldn't be found
+- Set default concurrency of built-in multi-threaded plugins to CPUs - 1
+- Fixed #5521: Social plugin triggers race condition when downloading fonts
+- Fixed #5515: Social plugin crashes when concurrency is set to 1
+
+### 4.34.0 <small>May 14, 2023</small> { id="4.34.0" }
+
+- Added support for new overflow mode to auto-fit text in social plugin
+- Reduced subtle rendering bugs in (code) annotations due to subpixel rounding
+- Improved print styles for (code) annotation lists
+- Improved performance of social plugin, now 3x as fast
+- Improved interop of typeset plugin with MkDocstrings
+- Fixed logo location for variants of default template in social plugin
+- Fixed #5446: Built-in typeset plugin picks up headings in code blocks
+
+### 4.33.2 <small>May 12, 2023</small> { id="4.33.2" }
+
+- Fixed #5508: Social plugin crashes trying to copy cards on Docker/Windows
+- Fixed #5507: Social plugin crashes on serve when layouts folder doesn't exist
+- Fixed #5505: Social plugin trying to resolve logo in wrong location
+- Fixed #5496: Annotations with nested lists incorrectly mounted
+- Fixed #5493: Social plugin crashes on Python 3.8
+
+### 4.33.1 <small>May 9, 2023</small> { id="4.33.1" }
+
+- Added support for SVG background images in social plugin
+
+### 4.33.0 <small>May 8, 2023</small> { id="4.33.0" }
+
+- Added support for custom layouts for social plugin
+- Added support for background images for social cards
+
+### 4.32.6 <small>April 22, 2023</small> { id="4.32.6" }
+
+- Fixed #5336: Interplay of blog plugin with git-revision-date-localized
+
+### 4.32.5 <small>April 7, 2023</small> { id="4.32.5" }
+
+- Fixed #5322: Navigation tabs hoist nested page icons
+
+### 4.32.4 <small>March 24, 2023</small> { id="4.32.4" }
+
+- Fixed #5241: Built-in typeset plugin jams navigation for anchors in headings
+
+### 4.32.3 <small>March 9, 2023</small> { id="4.32.3" }
+
+- Fixed Docker image release workflow (9.1.0 regression)
+- Fixed #5159: Missing underline for abbreviations (9.1.0 regression)
+
+### 4.32.2 <small>February 23, 2023</small> { id="4.32.2" }
+
+- Fixed #5127: Privacy plugin not handling large number of occurrences
+- Fixed #5126: Privacy plugin breaks when replacing specific emojis
+
+### 4.32.1 <small>February 23, 2023</small> { id="4.32.1" }
+
+- Fixed code block spans interfering with copying
+- Fixed #5077: Privacy plugin breaks image `alt` text encoding
+- Fixed #5079: Privacy plugin removing `rel=me` on external links
+
+### 4.32.0 <small>February 19, 2023</small> { id="4.32.0" }
+
+- Added support for custom selectors for code annotations
+- Added support for code line range selection for better sharing
+
+### 4.31.0 <small>February 18, 2023</small> { id="4.31.0" }
+
+- Added support for table of contents on blog index and archive pages
+- Fixed #4512: Allow custom search field boosts (experimental)
+
+### 4.30.2 <small>February 13, 2023</small> { id="4.30.2" }
+
+- Fixed privacy plugin excludes not working (4.30.0 regression)
+
+### 4.30.1 <small>February 12, 2023</small> { id="4.30.1" }
+
+- Fixed privacy plugin not handling static templates (e.g. `404.html`)
+
+### 4.30.0 <small>February 6, 2023</small> { id="4.30.0" }
+
+- Rewrite of privacy plugin for concurrency, now twice as fast
+- Added support for explicit inclusion for privacy plugin
+- Added optimization support for privacy plugin (+ optimize plugin)
+
+### 4.29.0 <small>January 21, 2023</small> { id="4.29.0" }
+
+- Added built-in optimize plugin for automatically compressing images
+- Switched reporting in built-in privacy plugin to `info` level
+
+### 4.28.1 <small>January 17, 2023</small> { id="4.28.1" }
+
+- Fixed built-in info plugin erroring for Insiders on version check
+- Fixed #4865: Navigation paths render bug when there's no top-level section
+- Fixed #4875: Added support for hiding navigation paths
+- Improved navigation path to not render for a single item
+
+### 4.28.0 <small>January 14, 2023</small> { id="4.28.0" }
+
+- Added support for navigation path (breadcrumbs)
+
+### 4.27.1 <small>December 20, 2022</small> { id="4.27.1" }
+
+- Fixed rendering of succeeding navigation items in typeset plugin
+- Fixed #4795: Built-in typeset plugin changes MkDocs' title precedence
+- Fixed #4724: Blog plugin not rendering integrate table of contents
+
+### 4.27.0 <small>December 20, 2022</small> { id="4.27.0" }
+
+- Added built-in typeset plugin to preserve formatting in sidebars
+- Added URL and table of contents support for blog categories
+
+### 4.26.6 <small>November 28, 2022</small> { id="4.26.6" }
+
+- Fixed #4683: Tags plugin crashes when a tag is empty
+
+### 4.26.5 <small>November 27, 2022</small> { id="4.26.5" }
+
+- Fixed #4632: Post excerpt title link doesn't point to top of the page
+
+### 4.26.4 <small>November 27, 2022</small> { id="4.26.4" }
+
+- Fixed redundant file extension when using privacy plugin
+
+### 4.26.3 <small>November 15, 2022</small> { id="4.26.3" }
+
+- Fixed #4637: Attachments w/o titles in related links error in blog plugin
+- Fixed #4631: Remote favicons not downloaded and inlined by privacy plugin
+
+### 4.26.2 <small>November 3, 2022</small> { id="4.26.2" }
+
+- Updated MkDocs to 1.4.2
+- Added support for tag compare functions when sorting on index pages
+- Fixed footnotes being rendered in post excerpts without separators
+- Fixed error in blog plugin when `toc` extension is not enabled
+- Fixed issues with invalid asset paths and linked post titles
+- Fixed #4572: Privacy plugin fails when symlinks cannot be created
+- Fixed #4545: Blog plugin doesn't automatically link headline to post
+- Fixed #4542: Blog plugin doesn't allow for multiple instances
+- Fixed #4532: Blog plugin doesn't allow for mixed use of date and datetime
+
+### 4.26.1 <small>October 22, 2022</small> { id="4.26.1" }
+
+- Improved reporting of configuration errors in tags plugin
+- Fixed #4515: Privacy plugin fails when site URL is not defined
+- Fixed #4514: Privacy plugin doesn't fetch Google fonts (4.26.0 regression)
+
+### 4.26.0 <small>October 18, 2022</small> { id="4.26.0" }
+
+- Refactored privacy plugin to prepare for new features
+- Added support for `rel=noopener` links in privacy plugin
+- Resolve encoding issues with blog and privacy plugin
+
+### 4.25.5 <small>October 16, 2022</small> { id="4.25.5" }
+
+- Updated MkDocs to 1.4.1
+- Added namespace prefix to built-in plugins
+- Updated `content` and `header` partial
+
+### 4.25.4 <small>October 9, 2022</small> { id="4.25.4" }
+
+- Fixed other path issues for standalone blogs (4.24.2 regression)
+
+### 4.25.3 <small>October 9, 2022</small> { id="4.25.3" }
+
+- Fixed #4457: Posts not collected for standalone blog (4.24.2 regression)
+
+### 4.25.2 <small>October 4, 2022</small> { id="4.25.2" }
+
+- Fixed #4452: Blog and tags plugin crash when specifying slugify function
+
+### 4.25.1 <small>October 3, 2022</small> { id="4.25.1" }
+
+- Updated `mkdocs-rss-plugin` in `Dockerfile` to fix MkDocs compat errors
+
+### 4.25.0 <small>October 2, 2022</small> { id="4.25.0" }
+
+- Added support for navigation subtitles
+- Added support for defining an allow list for built-in tags plugin
+- Added support for custom slugify functions for built-in tags plugin
+- Improved stability of search plugin when using `--dirtyreload`
+
+### 4.24.2 <small>October 1, 2022</small> { id="4.24.2" }
+
+- Updated MkDocs to 1.4
+- Fixed compatibility issues with MkDocs 1.4
+- Fixed incorrectly generated paths in privacy plugin
+- Fixed blog index page not showing navigation when using meta plugin
+
+### 4.24.1 <small>September 30, 2022</small> { id="4.24.1" }
+
+- Fixed #4430: build error when enabling consent without repository URL
+
+### 4.24.0 <small>September 27, 2022</small> { id="4.24.0" }
+
+- Added support for custom content on index pages (blog)
+- Added support for keeping content on paginated index pages (blog)
+- Added support for limiting categories in post excerpts (blog)
+- Added support for simple override of templates via front matter (blog)
+- Added icon in navigation for pages with encrypted content
+- Fixed #4396: Front matter of index pages not inherited by pagination (blog)
+- Improved performance by building post excerpts once (blog)
+
+### 4.23.6 <small>September 22, 2022</small> { id="4.23.6" }
+
+- Fixed #4389: Blog posts in first week of year in wrong archive
+- Fixed (= switched) footer previous and next links for blog posts
+
+### 4.23.5 <small>September 18, 2022</small> { id="4.23.5" }
+
+- Fixed #4367: Improved blog plugin date handling for MultiMarkdown syntax
+- Fixed #4374: Fixed invalid URLs of related links to other blog posts
+
+### 4.23.4 <small>September 14, 2022</small> { id="4.23.4" }
+
+- Fixed #4365: Recursion error in blog plugin due to `deepcopy`
+- Fixed path errors for blog plugin on Windows
+- Fixed publishing workflow in forked repositories
+
+### 4.23.3 <small>September 13, 2022</small> { id="4.23.3" }
+
+- Fixed previous and next page links for drafts of blog posts
+
+### 4.23.2 <small>September 13, 2022</small> { id="4.23.2" }
+
+- Fixed #4348: Blog plugin crashes on custom `nav` title
+- Fixed blog plugin crashing when category contained only drafts
+- Fixed rendering of content from blog index file
+
+### 4.23.1 <small>September 12, 2022</small> { id="4.23.1" }
+
+- Fixed #4345: Blog plugin errors with default settings
+
+### 4.23.0 <small>September 12, 2022</small> { id="4.23.0" }
+
+- Added blogging support via built-in blog plugin
+
+### 4.22.1 <small>September 7, 2022</small> { id="4.22.1" }
+
+- Fixed #4217: Tooltips in data tables render in wrong position
+
+### 4.22.0 <small>August 21, 2022</small> { id="4.22.0" }
+
+- Added support for navigation status
+
+### 4.21.1 <small>August 13, 2022</small> { id="4.21.1" }
+
+- Fixed #4176: Broken image when avatar is served by Gravatar
+- Fixed #4212: Deferred search initialization for file:// locations
+
+### 4.21.0 <small>July 17, 2022</small> { id="4.21.0" }
+
+- Added meta plugin: set front matter for all pages in a folder
+- Fixed #4114: Tags plugin fails if only `tags_extra_files` is set
+
+### 4.20.1 <small>July 11, 2022</small> { id="4.20.1" }
+
+- Fixed #4105: Tags plugin fails if `tags_file` is not set (4.20.0 regression)
+
+### 4.20.0 <small>July 7, 2022</small> { id="4.20.0" }
+
+- Added support for additional tags indexes
+- Fixed #4100: Tag icons not shown in tags index
+
+### 4.19.2 <small>July 4, 2022</small> { id="4.19.2" }
+
+- Fixed #4051: Privacy plugin fails if symlinking isn't allowed on Windows
+
+### 4.19.1 <small>June 25, 2022</small> { id="4.19.1" }
+
+- Added `mkdocs-git-committers-plugin` to Dockerfile
+- Added `mkdocs-git-revision-date-localized-plugin` to Dockerfile
+
+### 4.19.0 <small>June 24, 2022</small> { id="4.19.0" }
+
+- Added support for document contributors
+- Updated French translations for cookie consent
+
+### 4.18.2 <small>June 16, 2022</small> { id="4.18.2" }
+
+- Fixed #4026: Fixed tooltips not mounted for nested navigation links
+
+### 4.18.1 <small>June 14, 2022</small> { id="4.18.1" }
+
+- Fixed #3990: Chinese search highlighting not working on non-boundaries
+
+### 4.18.0 <small>June 11, 2022</small> { id="4.18.0" }
+
+- Added support for automatic dark/light mode
+- Fixed #4009: Privacy plugin uses invalid paths for file cache on Windows
+
+### 4.17.2 <small>June 5, 2022</small> { id="4.17.2" }
+
+- Added support for custom jieba dictionaries (Chinese search)
+
+### 4.17.1 <small>June 5, 2022</small> { id="4.17.1" }
+
+- Added support for cookie consent reject button
+- Added support for cookie consent custom button ordering
+- Fixed #3988: Content tab not focused after alternating anchor links
+
+### 4.17.0 <small>June 4, 2022</small> { id="4.17.0" }
+
+- Added support for content tabs anchor links (deep linking)
+- Fixed #3975: Detect composition events in search interface (Chinese)
+- Fixed #3980: Search plugin doesn't use title set via front matter
+
+### 4.16.2 <small>May 29, 2022</small> { id="4.16.2" }
+
+- Fixed #3961: Nested sections triggered build error for navigation tabs
+
+### 4.16.1 <small>May 28, 2022</small> { id="4.16.1" }
+
+- Switched feedback widget rating titles to tooltips
+- Improved contrast of link colors for light/dark color schemes
+- Fixed #3950: Sticky navigation tabs rendering broken (4.15.2 regression)
+- Fixed #3958: Links invisible when using `white` primary color
+
+### 4.16.0 <small>May 25, 2022</small> { id="4.16.0" }
+
+- Added support for navigation pruning
+- Fixed search results for non-segmented characters (4.15.2 regression)
+
+### 4.15.2 <small>May 22, 2022</small> { id="4.15.2" }
+
+- Removed workaround for `abbr` on touch devices (superseded by tooltips)
+- Fixed #3915: Improved Chinese search query segmentation
+- Fixed #3938: Fixed tooltips position for navigation titles with ellipsis
+
+### 4.15.1 <small>May 14, 2022</small> { id="4.15.1" }
+
+- Improved performance of element focus observables
+- Fixed #3531: Added prev/next buttons to content tabs
+- Fixed tooltip positioning when host element is hidden
+
+### 4.15.0 <small>May 8, 2022</small> { id="4.15.0" }
+
+- Added support for improved tooltips
+- Fixed #3785: Show tooltip on hover for overflowing navigation link
+
+### 4.14.0 <small>May 5, 2022</small> { id="4.14.0" }
+
+- Added Chinese language support to built-in search plugin
+- Fixed all-numeric page titles raising error in social plugin
+
+### 4.13.2 <small>April 30, 2022</small> { id="4.13.2" }
+
+- Improved caching of downloaded resources in privacy plugin
+- Fixed #3851: External images not downloaded by privacy plugin
+
+### 4.13.1 <small>April 25, 2022</small> { id="4.13.1" }
+
+- Fixed #3839: Tags plugin breaks without icons (4.13.0 regression)
+
+### 4.13.0 <small>April 24, 2022</small> { id="4.13.0" }
+
+- Added support for tag icons
+
+### 4.12.0 <small>March 27, 2022</small> { id="4.12.0" }
+
+- Added support for card grids and grid layouts
+- Fixed #3685: Annotations sometimes broken when using instant loading
+- Fixed #3742: Automatically add Mermaid.js when building for offline usage
+
+### 4.11.0 <small>March 6, 2022</small> { id="4.11.0" }
+
+- Added support for excluding external assets from privacy plugin
+
+### 4.10.1 <small>March 2, 2022</small> { id="4.10.1" }
+
+- Added missing build dependencies to Dockerfile
+- Fixed encoding issues in privacy plugin, now forcing UTF-8 encoding
+- Fixed #3624: Scroll to active navigation item unreliable in Firefox
+- Fixed #3642: Privacy plugin errors when font setting was omitted
+
+### 4.10.0 <small>February 27, 2022</small> { id="4.10.0" }
+
+- Added support for offline plugin (supersedes offline search support)
+- Improved built-in privacy plugin to download nested JavaScript assets
+- Refactored configuration of built-in privacy plugin
+
+### 4.9.1 <small>February 21, 2022</small> { id="4.9.1" }
+
+- Fixed #3610: missing `lxml` dependency for privacy plugin
+- Fixed error when charset is missing in `content-type` header
+
+### 4.9.0 <small>February 20, 2022</small> { id="4.9.0" }
+
+- Added privacy plugin: automatic downloading of external assets
+
+### 4.8.3 <small>February 13, 2022</small> { id="4.8.3" }
+
+- Fixed #3560: Mermaid diagrams don't render for `file://` locations
+
+### 4.8.2 <small>February 10, 2022</small> { id="4.8.2" }
+
+- Fixed #3559: Mermaid diagrams don't render inside closed `details`
+
+### 4.8.1 <small>February 6, 2022</small> { id="4.8.1" }
+
+- Fixed jump back to top on mobile when using anchor following
+
+### 4.8.0 <small>February 6, 2022</small> { id="4.8.0" }
+
+- Added support for anchor following table of contents (= auto scroll)
+
+### 4.7.2 <small>February 2, 2022</small> { id="4.7.2" }
+
+- Fixed #3526: Transparent sidebar title due to Safari bug
+- Fixed #3528: Firefox sometimes clips text in flow chart diagrams
+
+### 4.7.1 <small>January 30, 2022</small> { id="4.7.1" }
+
+- Fixed #3506: Tags index not respecting title set via front matter
+
+### 4.7.0 <small>January 25, 2022</small> { id="4.7.0" }
+
+- Added native support for offline search
+
+### 4.6.1 <small>January 16, 2022</small> { id="4.6.1" }
+
+- Fixed #3459: Section index pages picking up wrong title
+
+### 4.6.0 <small>January 11, 2022</small> { id="4.6.0" }
+
+- Added support for annotations (outside of code blocks)
+
+### 4.5.2 <small>January 8, 2022</small> { id="4.5.2" }
+
+- Fixed #3440: Content tab indicator not moving when using linking
+- Fixed #3445: Content tab switch flickers/jitters when using linking
+
+### 4.5.1 <small>January 2, 2022</small> { id="4.5.1" }
+
+- Added support for setting initial state of cookie consent
+- Fixed #3396: Disappearing link in navigation due to Safari bug
+
+### 4.5.0 <small>December 16, 2021</small> { id="4.5.0" }
+
+- Added support for navigation icons
+
+### 4.4.0 <small>December 10, 2021</small> { id="4.4.0" }
+
+- Added support for code annotation anchor links (deep linking)
+- Added new code annotation syntax modifier to strip comment
+- Updated German translations for cookie consent
+
+### 4.3.0 <small>December 5, 2021</small> { id="4.3.0" }
+
+- Added support for custom fonts in social cards
+- Fixed #3300: Announcement bar reappearing when using instant loading
+
+### 4.2.0 <small>December 2, 2021</small> { id="4.2.0" }
+
+- Added support for dismissible announcement bar
+- Added support for named placeholders in feedback widget
+
+### 4.1.0 <small>November 30, 2021</small> { id="4.1.0" }
+
+- Added support for passing page title to feedback forms
+
+### 4.0.0 <small>November 28, 2021</small> { id="4.0.0" }
+
+- Removed deprecated content tabs legacy implementation
+- Removed deprecated `seealso` admonition type
+- Removed deprecated `site_keywords` setting (unsupported by MkDocs)
+- Removed deprecated prebuilt search index support
+- Removed deprecated web app manifest – use customization
+- Removed `extracopyright` variable – use new `copyright` partial
+- Removed Disqus integration – use customization
+- Switched to `:is()` selectors for simple selector lists
+- Switched autoprefixer from `last 4 years` to `last 2 years`
+- Improved CSS overall to match modern standards
+- Improved CSS variable semantics for fonts
+- Improved extensibility by restructuring partials
+- Improved handling of `details` when printing
+- Improved keyboard navigation for footnotes
+- Fixed #3214: Search highlighting breaks site when empty
+
+### 3.2.3 <small>November 20, 2021</small> { id="3.2.3" }
+
+- Updated Swedish and French translations
+- Removed support for `.mermaid-experimental` class (now `.mermaid`)
+- Fixed #3202: Cookie consent not dismissable on `file://` locations
+- Fixed #3216: Cookie consent not dismissed when invoked via anchor
+- Fixed #3232: Mermaid.js sometimes runs twice (race condition)
+
+### 3.2.2 <small>November 6, 2021</small> { id="3.2.2" }
+
+- Fixed always last feedback rating being sent
+- Fixed #3145: Code annotations eat whole comment lines
+- Fixed #3170: Feedback widget doesn't send data to GA4
+
+### 3.2.1 <small>November 4, 2021</small> { id="3.2.1" }
+
+- Added support for custom Mermaid.js version via additional JavaScript
+- Fixed some configuration edge cases for tags plugin (3.1.5 regression)
+- Fixed feedback widget title not being centered in Firefox
+- Fixed #3179: Safari doesn't send request for feedback widget
+
+### 3.2.0 <small>October 31, 2021</small> { id="3.2.0" }
+
+- Added support for feedback widget (Was this page helpful?)
+
+### 3.1.5 <small>October 28, 2021</small> { id="3.1.5" }
+
+- Fixed #3144: Rogue link when using tags with auto-populated navigation
+- Fixed #3147: Code block line numbers appear in search results
+- Fixed #3158: Social cards do not strip HTML tags from title
+
+### 3.1.4 <small>October 17, 2021</small> { id="3.1.4" }
+
+- Fixed #2974: Text cropped with other fonts than `Roboto` in social plugin
+- Fixed #3099: Encoding problems with non-latin character in social plugin
+- Fixed #3112: Japanese segmenter not executed as part of new tokenizer
+- Fixed tags (front matter) appearing in search with disabled tags plugin
+
+### 3.1.3 <small>October 12, 2021</small> { id="3.1.3" }
+
+- Added warnings to search plugin for unsupported options and syntax
+- Fixed #3503: Search sometimes returns entire page
+- Fixed #3089: Single-line code annotations disappear when printing
+
+### 3.1.2 <small>October 6, 2021</small> { id="3.1.2" }
+
+- Fixed incorrect path separators for social cards on Windows
+
+### 3.1.1 <small>September 26, 2021</small> { id="3.1.1" }
+
+- Fixed ordering bug in search exclusion logic
+
+### 3.1.0 <small>September 26, 2021</small> { id="3.1.0" }
+
+- Added support for excluding pages, sections, and elements from search
+- Fixed #2803: Code block annotations not visible when printing
+
+### 3.0.1 <small>September 19, 2021</small> { id="3.0.1" }
+
+- Added support for using literal `h1-6` tags for search plugin
+- Fixed search plugin breaking on void elements without slashes
+- Fixed search plugin filtering link contents from headlines
+- Fixed search plugin handling of multiple `h1` headlines
+- Fixed search plugin handling of missing `h1` headlines
+
+### 3.0.0 <small>September 13, 2021</small> { id="3.0.0" }
+
+- Rewrite of MkDocs' search plugin
+- Added support for rich search previews
+- Added support for tokenizer with lookahead
+- Improved search indexing performance (twice as fast)
+- Improved search highlighting
+
+### 2.13.3 <small>September 1, 2021</small> { id="2.13.3" }
+
+- Added support for disabling social card generation
+
+### 2.13.2 <small>August 25, 2021</small> { id="2.13.2" }
+
+- Fixed #2965: Social plugin error when primary color is not defined
+
+### 2.13.1 <small>August 21, 2021</small> { id="2.13.1" }
+
+- Fixed #2948: Social cards are not cached
+- Fixed #2953: Mermaid.js diagrams can't be centered anymore
+
+### 2.13.0 <small>August 7, 2021</small> { id="2.13.0" }
+
+- Added support for custom colors in social cards
+
+### 2.12.2 <small>August 4, 2021</small> { id="2.12.2" }
+
+- Fixed #2891: Division by zero error in social plugin
+
+### 2.12.1 <small>July 26, 2021</small> { id="2.12.1" }
+
+- Fixed error in social plugin when `site_description` was not set
+- Fixed error in social plugin for non-ASCII characters
+
+### 2.12.0 <small>July 25, 2021</small> { id="2.12.0" }
+
+- Added support for social cards
+
+### 2.11.1 <small>July 20, 2021</small> { id="2.11.1" }
+
+- Fixed order of tags index, now sorted alphabetically
+
+### 2.11.0 <small>July 18, 2021</small> { id="2.11.0" }
+
+- Improved Mermaid.js integration, now stable
+- Added support for sequence diagrams
+- Added support for entity relationship diagrams
+- Added support for cookie consent configuration
+- Added feature flag to always enable annotations
+
+### 2.10.0 <small>July 10, 2021</small> { id="2.10.0" }
+
+- Added support for cookie consent
+- Fixed #2807: Back-to-top button not hidden when using sticky tabs
+
+### 2.9.2 <small>May 30, 2021</small> { id="2.9.2" }
+
+- Moved tags to partial for easier customization
+- Added support for hiding tags on any page
+
+### 2.9.1 <small>May 24, 2021</small> { id="2.9.1" }
+
+- Added missing guard for linking of content tabs
+
+### 2.9.0 <small>May 23, 2021</small> { id="2.9.0" }
+
+- Added support for linking of content tabs
+
+### 2.8.0 <small>May 12, 2021</small> { id="2.8.0" }
+
+- Added support for boosting pages in search
+
+### 2.7.2 <small>May 8, 2021</small> { id="2.7.2" }
+
+- Fixed #2638: Warnings shown when using `tags` plugin without directory URLs
+
+### 2.7.1 <small>May 3, 2021</small> { id="2.7.1" }
+
+- Fixed `git-revision-date-localized` plugin integration (2.7.0 regression)
+
+### 2.7.0 <small>May 1, 2021</small> { id="2.7.0" }
+
+- Added support for tags (with search integration)
+
+### 2.6.0 <small>April 11, 2021</small> { id="2.6.0" }
+
+- Stay on page when switching versions
+
+### 2.5.0 <small>March 28, 2021</small> { id="2.5.0" }
+
+- Added support for version warning
+
+### 2.4.0 <small>March 20, 2021</small> { id="2.4.0" }
+
+- Added support for custom admonition icons
+- Fixed #2444: Code block annotations with extra comments have wrong index
+
+### 2.3.1 <small>March 14, 2021</small> { id="2.3.1" }
+
+- Fixed anchor offset for permalinks when using sticky navigation tabs
+
+### 2.3.0 <small>March 13, 2021</small> { id="2.3.0" }
+
+- Added support for back-to-top button
+
+### 2.2.1 <small>March 4, 2021</small> { id="2.2.1" }
+
+- Fixed #2382: Repository stats failing when no release tag is present
+
+### 2.2.0 <small>February 28, 2021</small> { id="2.2.0" }
+
+- Added support for code block annotations
+
+### 2.1.0 <small>February 26, 2021</small> { id="2.1.0" }
+
+- Added support for anchor tracking
+
+### 2.0.0 <small>February 24, 2021</small> { id="2.0.0" }
+
+- Migrated Insiders to the new architecture
+- Swapped color palette toggle configuration
+
+### 1.17.0 <small>January 31, 2021</small> { id="1.17.0" }
+
+- Added support for section index pages
+
+### 1.16.1 <small>January 26, 2021</small> { id="1.16.1" }
+
+- Fixed #2249: Instant loading + sticky tabs result in invalid links
+- Fixed #2248: Search highlighting URL parameter always added
+- Fixed #2235: Version selector doesn't select current version for aliases
+
+### 1.16.0 <small>January 7, 2021</small> { id="1.16.0" }
+
+- Added latest release to repository info (GitHub)
+- Slight facelift of repository info (lighter fonts, spacing and icons)
+
+### 1.15.0 <small>January 2, 2021</small> { id="1.15.0" }
+
+- Added support for native Mermaid.js integration
+
+### 1.14.0 <small>December 30, 2020</small> { id="1.14.0" }
+
+- Added support for sharing searches
+
+### 1.13.2 <small>December 22, 2020</small> { id="1.13.2" }
+
+- Fixed version selector + sticky tabs navigation rendering issues
+- Fixed version selector wrapping
+
+### 1.13.1 <small>December 20, 2020</small> { id="1.13.1" }
+
+- Removed horizontal scrollbars on language and version selector
+- Fixed type conversion in JavaScript config
+
+### 1.13.0 <small>December 13, 2020</small> { id="1.13.0" }
+
+- Refactored navigation tabs to simplify grouping behavior
+- Added support for sticky navigation tabs
+- Added support for arbitrary links in navigation tabs
+- Fixed #2098: Subsequent active subsection not highlighted correctly
+
+### 1.12.1 <small>December 8, 2020</small> { id="1.12.1" }
+
+- Fixed empty language selector being shown
+
+### 1.12.0 <small>December 6, 2020</small> { id="1.12.0" }
+
+- Added support for adding a language selector
+
+### 1.11.2 <small>November 29, 2020</small> { id="1.11.2" }
+
+- Fixed #2068: Search highlight interprets code blocks as JavaScript
+
+### 1.11.1 <small>November 29, 2020</small> { id="1.11.1" }
+
+- Refactored styling to be more stable and easier to adjust
+- Fixed some styling regressions from latest features
+
+### 1.11.0 <small>November 22, 2020</small> { id="1.11.0" }
+
+- Added support for rendering admonitions as inline blocks
+
+### 1.10.0 <small>November 15, 2020</small> { id="1.10.0" }
+
+- Added support for integrating table of contents into navigation
+
+### 1.9.0 <small>November 7, 2020</small> { id="1.9.0" }
+
+- Added support for hiding navigation and table of contents on any page
+- Removed autohiding table of contents when empty
+
+### 1.8.0 <small>November 1, 2020</small> { id="1.8.0" }
+
+- Added support for navigation sections
+- Fixed appearance of inactive search suggestions
+
+### 1.7.0 <small>October 25, 2020</small> { id="1.7.0" }
+
+- Added support for deploying multiple versions
+- Fixed alignment of sidebar when content area is too small
+
+### 1.6.0 <small>October 11, 2020</small> { id="1.6.0" }
+
+- Added support for search suggestions to save keystrokes
+- Added support for removing __Made with Material for MkDocs__ from footer
+- Fixed #1915: search should go to first result by pressing ++enter++
+
+### 1.5.1 <small>September 21, 2020</small> { id="1.5.1" }
+
+- Fixed content area stretching to whole width for long code blocks
+
+### 1.5.0 <small>September 19, 2020</small> { id="1.5.0" }
+
+- Added support for autohiding table of contents when empty
+
+### 1.4.1 <small>September 6, 2020</small> { id="1.4.1" }
+
+- Improved typeahead and search result relevance and scoring
+
+### 1.4.0 <small>August 30, 2020</small> { id="1.4.0" }
+
+- Added support for autohiding header on scroll
+
+### 1.3.0 <small>August 26, 2020</small> { id="1.3.0" }
+
+- Added support for user-selectable color palettes
+
+### 1.2.0 <small>August 11, 2020</small> { id="1.2.0" }
+
+- Added feature to expand navigation by default
+
+### 1.1.0 <small>August 3, 2020</small> { id="1.1.0" }
+
+- Added highlighting of search results
+
+### 1.0.0 <small>July 14, 2020</small> { id="1.0.0" }
+
+- Added grouping of search results
+- Added missing query terms to search result
+- Improved search result relevance and scoring
diff --git a/documents/markdown/mkdocs-material/insiders_getting-started.md b/documents/markdown/mkdocs-material/insiders_getting-started.md
new file mode 100644
index 0000000..97dfaa2
--- /dev/null
+++ b/documents/markdown/mkdocs-material/insiders_getting-started.md
@@ -0,0 +1,176 @@
+---
+title: Getting started with Insiders
+---
+
+# Getting started with Insiders
+
+Material for MkDocs Insiders is a compatible drop-in replacement for Material
+for MkDocs, and can be installed similarly using [`pip`][pip],
+[`docker`][docker] or [`git`][git].
+
+ [pip]: #with-pip
+ [docker]: #with-docker
+ [git]: #with-git
+
+## Requirements
+
+After you've been added to the list of collaborators and accepted the
+repository invitation, the next step is to create a [personal access token] for
+your GitHub account in order to access the Insiders repository programmatically
+(from the command line or GitHub Actions workflows):
+
+1. Go to https://github.com/settings/tokens
+2. Click on [Generate a new token]
+3. Enter a name and select the [`repo`][scopes] scope
+4. Generate the token and store it in a safe place
+
+ [personal access token]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
+ [Generate a new token]: https://github.com/settings/tokens/new
+ [scopes]: https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes
+
+Some of the instructions below require that the `GH_TOKEN` environment
+variable is set to the value of the personal access token you
+generated in the previous step. Note that the personal access token
+must be kept secret at all times, as it allows the owner to access
+your private repositories.
+
+## Installation
+
+### with pip
+
+Material for MkDocs Insiders can be installed with `pip`. You will
+normally want to install the latest release but can also install a
+specific older release or even the latest development version.
+Make sure you have the `GH_TOKEN` variable set as instructed above.
+
+=== "Specific release"
+
+ Pick the corresponding tag from the [list of tags] for the Insiders
+ repository. In the `pip` command below, replace the tag at the
+ end of the URL with the one you want.
+
+ ``` sh
+ pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git@9.4.2-insiders-4.42.0
+ ```
+
+=== "Latest"
+
+ ``` sh
+ pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
+ ```
+
+[list of tags]: https://github.com/squidfunk/mkdocs-material-insiders/tags
+
+### with docker
+
+In case you want to use Material for MkDocs Insiders from within Docker, some
+additional steps are necessary. While we cannot provide a hosted Docker image
+for Insiders[^2], [GitHub Container Registry] allows for simple and
+comfortable self-hosting:
+
+1. [Fork the Insiders repository]
+2. Enable [GitHub Actions] on your fork[^3]
+3. Create a new personal access token[^4]
+ 1. Go to https://github.com/settings/tokens
+ 2. Click on [Generate a new token]
+ 3. Enter a name and select the [`write:packages`][scopes] scope
+ 4. Generate the token and store it in a safe place
+4. Add a [GitHub Actions secret] on your fork
+ 1. Set the name to `GHCR_TOKEN`
+ 2. Set the value to the personal access token created in the previous step
+5. [Create a new release] to build and publish the Docker image
+6. Install [Pull App] on your fork to stay in-sync with upstream
+
+The [`build`][build] workflow is automatically run when a new tag
+(release) is created. When a new Insiders version is released on the upstream
+repository, the [Pull App] will create a pull request with the changes and
+pull in the new tag, which is picked up by the [`build`][build] workflow
+that builds and publishes the Docker image automatically to your private
+registry.
+
+Now, you should be able to pull the Docker image from your private registry:
+
+```
+docker login -u ${GH_USERNAME} -p ${GHCR_TOKEN} ghcr.io
+docker pull ghcr.io/${GH_USERNAME}/mkdocs-material-insiders
+```
+
+Should you wish to add additional plugins to the insiders container image, follow the steps
+outlined in the [Getting Started guide](../getting-started.md#with-docker).
+
+ [^2]:
+ Earlier, Insiders provided a dedicated Docker image which was available to
+ all sponsors. On March 21, 2021, the image was deprecated for the reasons
+ outlined and discussed in #2442. It was removed on June 1, 2021.
+
+ [^3]:
+ When forking a repository, GitHub will disable all workflows. While this
+ is a reasonable default setting, you need to enable GitHub Actions to be
+ able to automatically build and publish a Docker image on
+ [GitHub Container Registry].
+
+ [^4]:
+ While you could just add the `write:packages` scope to the personal access
+ token created to access the Insiders repository, it's safer to create a
+ dedicated token which you'll only use for publishing the Docker image.
+
+### with git
+
+Of course, you can use Material for MkDocs Insiders directly from `git`:
+
+```
+git clone git@github.com:squidfunk/mkdocs-material-insiders.git mkdocs-material
+```
+
+The theme will reside in the folder `mkdocs-material/material`. When cloning
+from `git`, the theme must be installed, so MkDocs can find the built-in
+plugins:
+
+```
+pip install -e mkdocs-material
+```
+
+ [GitHub Container Registry]: https://docs.github.com/en/packages/guides/about-github-container-registry
+ [Fork the Insiders repository]: https://github.com/squidfunk/mkdocs-material-insiders/fork
+ [GitHub Actions]: https://docs.github.com/en/github/administering-a-repository/disabling-or-limiting-github-actions-for-a-repository
+ [packages scope]: https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes
+ [GitHub Actions secret]: https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository
+ [Create a new release]: https://docs.github.com/en/github/administering-a-repository/managing-releases-in-a-repository#creating-a-release
+ [Pull App]: https://github.com/apps/pull
+ [build]: https://github.com/squidfunk/mkdocs-material-insiders/blob/master/.github/workflows/build.yml
+
+## Built-in plugins
+
+When you're using built-in plugins that are solely available via Insiders,
+outside contributors won't be able to build your documentation project on their
+local machine. This is the reason why we developed the [built-in group plugin]
+that allows to conditionally load plugins:
+
+``` yaml
+plugins:
+ - search
+ - social
+
+ # CI=true mkdocs build
+ - group:
+ enabled: !ENV CI
+ plugins:
+ - git-revision-date-localized
+ - git-committers
+
+ # INSIDERS=true mkdocs build
+ - group:
+ enabled: !ENV INSIDERS
+ plugins:
+ - optimize
+ - privacy
+```
+
+Of course, you can also enable both groups with:
+
+``` shell
+CI=true INSIDERS=true mkdocs build
+```
+
+ [built-in group plugin]: ../plugins/group.md
+ [configuration inheritance]: https://www.mkdocs.org/user-guide/configuration/#configuration-inheritance
diff --git a/documents/markdown/mkdocs-material/insiders_upgrade.md b/documents/markdown/mkdocs-material/insiders_upgrade.md
new file mode 100644
index 0000000..ec86ad9
--- /dev/null
+++ b/documents/markdown/mkdocs-material/insiders_upgrade.md
@@ -0,0 +1,79 @@
+# How to upgrade
+
+When upgrading Insiders, you should always check the version of Material for
+MkDocs which makes up the first part of the version qualifier, e.g., Insiders
+`4.x.x` is currently based on `9.x.x`:
+
+```
+9.x.x-insiders-4.x.x
+```
+
+If the major version increased, it's a good idea to consult the [upgrade
+guide] and go through the steps to ensure your configuration is up to date and
+all necessary changes have been made.
+
+ [upgrade guide]: ../upgrade.md
+ [list of tags]: https://github.com/squidfunk/mkdocs-material-insiders/tags
+
+Depending on how you installed and what you want to upgrade to you
+need to run different commands:
+
+=== "pip upgrade to release"
+
+ If you installed Insiders via `pip` and you want to upgrade to a
+ specific release, pick the tag from the [list of tags] and replace
+ the tag at the end of the URL of the command given below:
+
+ ```
+ pip install --upgrade git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git@9.4.2-insiders-4.42.0
+ ```
+
+=== "pip upgrade to latest development"
+
+ If you installed Insiders via `pip` and want to upgrade to the
+ latest development version, run:
+
+ ```
+ pip install --upgrade --force-reinstall git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
+ ```
+
+ The `--force-reinstall` option serves to make sure `pip` does, in fact,
+ install the latest development version, instead of deciding that nothing
+ is to be done based on the version numbers.
+ ```
+
+=== "git upgrade"
+
+ If you installed Insiders via `git`, you will first need to check
+ out the version you want to install into your workspace. After
+ this is done, you can run `pip` to install that version.
+
+ First, make sure that your local clone is up-to-date with the
+ upstream repository by running `git pull`.
+
+ You can look up the tags using `git tag --sort -refname` or you
+ can consult the [list of tags]. Then, checkout the tag you want to
+ use by replacing the one given in the command below (twice)and running
+ it from your workspace[^detached]:
+
+ [^detached]:
+ The `--detach` argument serves to tell `git` that you are ok to
+ have your workspace in the [detached head] state, which is
+ perfectly fine to have here.
+
+ [detached head]: https://www.git-tower.com/learn/git/faq/detached-head-when-checkout-commit/
+
+ ```
+ cd mkdocs-material
+ git checkout --detach tags/9.4.2-insiders-4.42.0
+ ```
+
+ Now, change back to the parent directory in which your Git
+ repository lives and run `pip`:
+
+ ```
+ cd ..
+ pip install -e mkdocs-material
+ ```
+
+
diff --git a/documents/markdown/mkdocs-material/license.md b/documents/markdown/mkdocs-material/license.md
new file mode 100644
index 0000000..5783e40
--- /dev/null
+++ b/documents/markdown/mkdocs-material/license.md
@@ -0,0 +1,23 @@
+# License
+
+**MIT License**
+
+Copyright (c) 2016-2025 Martin Donath
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
diff --git a/documents/markdown/mkdocs-material/philosophy.md b/documents/markdown/mkdocs-material/philosophy.md
new file mode 100644
index 0000000..35efcb1
--- /dev/null
+++ b/documents/markdown/mkdocs-material/philosophy.md
@@ -0,0 +1,24 @@
+# Philosophy
+
+Before settling for Material for MkDocs, it's a good idea to understand the
+philosophy behind the project, in order to make sure it aligns with your goals.
+This page explains the design principles anchored in Material for MkDocs, and
+discusses the [conventions] used in this documentation.
+
+ [conventions]: conventions.md
+
+## Design principles
+
+- **It's just Markdown**: Focus on the content of your documentation and create a professional static site in minutes. No need to know HTML, CSS or JavaScript – let Material for MkDocs do the heavy lifting for you.
+
+- **Works on all devices**: Serve your documentation with confidence – Material for MkDocs automatically adapts to perfectly fit the available screen estate, no matter the type or size of the viewing device. Desktop. Tablet. Mobile. All great.
+
+- **Made to measure**: Make it yours – change the colors, fonts, language, icons, logo, and more with a few lines of configuration. Material for MkDocs can be easily extended and provides many options to alter appearance and behavior.
+
+- **Fast and lightweight**: Don't let your users wait – get incredible value with a small footprint by using one of the fastest themes available with excellent performance, yielding optimal search engine rankings and happy users that return.
+
+- **Maintain ownership**: Make accessibility a priority – users can navigate your
+ documentation with touch devices, keyboard, and screen readers. Semantic
+ markup ensures that your documentation works for everyone.
+
+- **Open Source**: You're in good company – choose a mature and actively maintained solution built with state-of-the-art Open Source technologies, trusted by more than 50.000 individuals and organizations. Licensed under MIT.
diff --git a/documents/markdown/mkdocs-material/plugins_blog.md b/documents/markdown/mkdocs-material/plugins_blog.md
new file mode 100644
index 0000000..3ea555a
--- /dev/null
+++ b/documents/markdown/mkdocs-material/plugins_blog.md
@@ -0,0 +1,1723 @@
+---
+title: Built-in blog plugin
+icon: material/newspaper-variant-outline
+---
+
+# Built-in blog plugin
+
+The blog plugin makes it very easy to build a blog, either as a sidecar to
+your documentation or as the main thing. Focus on your content while the plugin
+does all the heavy lifting, generating a view of all latest posts, [archive] and
+[category] pages, configurable [pagination] and much more.
+
+ [archive]: #archive
+ [category]: #categories
+ [pagination]: #pagination
+
+## Objective
+
+### How it works
+
+The plugin scans the configured [`posts` directory][config.post_dir] for
+`.md` files from which paginated views[^1] are automatically generated. If not
+configured otherwise, the plugin expects that your project has the following
+directory layout, and will create any missing directories or files for you:
+
+ [^1]:
+ Views are pages that are automatically generated, i.e., the entry point to
+ your blog listing all latest posts, as well as [archive] and [category]
+ pages that list all posts associated with them through [metadata] in
+ chronological order.
+
+``` { .sh .no-copy }
+.
+├─ docs/
+│ └─ blog/
+│ ├─ posts/
+│ └─ index.md
+└─ mkdocs.yml
+```
+
+The `index.md` file in the [`blog` directory][config.blog_dir] is the entry
+point to your blog – a paginated view listing all posts in reverse chronological
+order. Besides that, the plugin supports automatically creating [archive] and
+[category] pages that list a subset of posts for a time interval or category.
+
+[Post URLs][config.post_url_format] are completely configurable, no matter if
+you want your URLs to include the post's date or not. Rendered dates always
+display in the locale of the [site language] of your project. Like in other
+static blog frameworks, posts can be annotated with a variety of [metadata],
+allowing for easy integration with other [built-in plugins], e.g., the
+[social] and [tags] plugin.
+
+Posts can be organized in nested folders with a directory layout that suits your
+specific needs, and can make use of all components and syntax that Material for
+MkDocs offers, including [admonitions], [annotations], [code blocks],
+[content tabs], [diagrams], [icons], [math], and more.
+
+ [metadata]: #metadata
+ [built-in plugins]: index.md
+ [social]: social.md
+ [tags]: tags.md
+ [admonitions]: ../reference/admonitions.md
+ [annotations]: ../reference/annotations.md
+ [code blocks]: ../reference/code-blocks.md
+ [content tabs]: ../reference/content-tabs.md
+ [diagrams]: ../reference/diagrams.md
+ [icons]: ../reference/icons-emojis.md
+ [math]: ../reference/math.md
+
+### When to use it
+
+If you want to add a blog to your project, or migrate from another blog
+framework to Material for MkDocs because of its excellent technical writing
+capabilities, this plugin is a great choice, as it integrates perfectly with
+many other built-in plugins:
+
+<div class="grid cards" markdown>
+
+- :material-file-tree: __[Built-in meta plugin][meta]__
+
+ ---
+
+ The meta plugin makes it easy to apply [metadata] to a subset of posts,
+ including authors, tags, categories, draft status, as well as social card
+ layouts.
+
+ ---
+
+ __Simpler organization, categorization and management of post metadata__
+
+- :material-share-circle: __[Built-in social plugin][social]__
+
+ ---
+
+ The social plugin automatically generates beautiful and customizable
+ social cards for each post and page, showing as previews on social media.
+
+ ---
+
+ __Links to your blog render beautiful social cards when shared on social
+ media__
+
+- :material-rabbit: __[Built-in optimize plugin][optimize]__
+
+ ---
+
+ The optimize plugin automatically identifies and optimizes all media files
+ that you reference in your project by using compression and conversion
+ techniques.
+
+ ---
+
+ __Your blog loads faster as smaller images are served to your users__
+
+- :material-tag-text: __[Built-in tags plugin][tags]__
+
+ ---
+
+ The tags plugin allows to categorize posts alongside with pages in your
+ project, to improve their discoverability and connect posts to your
+ documentation.
+
+ ---
+
+ __Your documentation's tag system integrates with your blog__
+
+</div>
+
+ [meta]: meta.md
+ [social]: social.md
+ [optimize]: optimize.md
+ [tags]: tags.md
+
+## Configuration
+
+<!-- md:version 9.2.0 -->
+<!-- md:plugin [blog] – built-in -->
+<!-- md:flag multiple -->
+<!-- md:flag experimental -->
+
+As with all [built-in plugins], getting started with the blog plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and you can
+start writing your first post:
+
+``` yaml
+plugins:
+ - blog
+```
+
+The blog plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [blog]: blog.md
+ [built-in plugins]: index.md
+
+### Navigation
+
+If you do not have site navigation configured in your `mkdocs.yml` then there is
+nothing more to do. The blog [archive] and [category] pages will automatically
+appear underneath the automatically generated navigation.
+
+If you do have a navigation structure defined then you will need to specify
+where the blog should appear in this. Create a [navigation section with an index
+page] for the blog:
+
+```yaml
+theme:
+ name: material
+ features:
+ - navigation.indexes
+nav:
+ - ...
+ - Blog:
+ - blog/index.md
+```
+
+The [archive] and [category] pages will appear within that section as
+subsections beneath pages in the blog section. In this case, they would appear
+after `index.md`. The path to the `index.md` file must match
+[blog_dir][config.blog_dir]. This means that you can name the blog navigation
+entry anything you like: 'Blog' or 'News' or perhaps 'Tips'.
+
+[navigation section with an index page]: ../setup/setting-up-navigation.md#section-index-pages
+
+### General
+
+The following settings are available:
+
+---
+
+#### <!-- md:setting config.enabled -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable the plugin when [building your project].
+It's normally not necessary to specify this setting, but if you want to disable
+the plugin, use:
+
+``` yaml
+plugins:
+ - blog:
+ enabled: false
+```
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+---
+
+#### <!-- md:setting config.blog_dir -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `blog` -->
+
+Use this setting to change the path where your blog is located in the
+[`docs` directory][mkdocs.docs_dir]. The path is included in the generated
+URLs as a prefix for all posts and views. You can change it with:
+
+=== "Documentation + Blog"
+
+ ``` yaml
+ plugins:
+ - blog:
+ blog_dir: blog
+ ```
+
+=== "Blog only"
+
+ ``` yaml
+ plugins:
+ - blog:
+ blog_dir: .
+ ```
+
+The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
+
+---
+
+#### <!-- md:setting config.blog_toc -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `false` -->
+
+Use this setting to leverage the table of contents to display post titles in
+views. This might be useful, if your post excerpts are rather long. If you want
+to enable it, use:
+
+``` yaml
+plugins:
+ - blog:
+ blog_toc: true
+```
+
+### Posts
+
+The following settings are available for posts:
+
+---
+
+#### <!-- md:setting config.post_dir -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `{blog}/posts` -->
+
+Use this setting to change the folder where your posts are located. It's
+normally not necessary to change this setting, but if you want to rename the
+folder or change its file system location, use:
+
+``` yaml
+plugins:
+ - blog:
+ post_dir: "{blog}/articles"
+```
+
+Note that the [`posts` directory][config.post_dir] is solely used for post
+organization – it is not included in post URLs, since they are automatically
+and comfortably generated by this plugin.
+
+The following placeholders are available:
+
+- `blog` – [`blog` directory][config.blog_dir]
+
+The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
+
+---
+
+#### <!-- md:setting config.post_date_format -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `long` -->
+
+Use this setting to change the date format of posts. This plugin uses [babel]
+to render dates in the configured [site language]. You can use [babel]'s
+[pattern syntax] or the following shortcodes:
+
+=== "Monday, January 31, 2024"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_date_format: full
+ ```
+
+=== "January 31, 2024"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_date_format: long
+ ```
+
+=== "Jan 31, 2024"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_date_format: medium
+ ```
+
+=== "1/31/24"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_date_format: short
+ ```
+
+Note that depending on the [site language], results might look different for
+other languages.
+
+ [babel]: https://pypi.org/project/Babel/
+ [site language]: ../setup/changing-the-language.md#site-language
+ [pattern syntax]: https://babel.pocoo.org/en/latest/dates.html#pattern-syntax
+
+---
+
+#### <!-- md:setting config.post_url_date_format -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `yyyy/MM/dd` -->
+
+Use this setting to change the date format used in post URLs. The format string
+must adhere to [babel]'s [pattern syntax] and should not contain whitespace.
+Some popular choices:
+
+=== ":material-link: blog/2024/01/31/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_url_date_format: yyyy/MM/dd
+ ```
+
+=== ":material-link: blog/2024/01/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_url_date_format: yyyy/MM
+ ```
+
+=== ":material-link: blog/2024/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_url_date_format: yyyy
+ ```
+
+If you want to remove the date from post URLs, e.g., when your blog features
+mostly evergreen content, you can remove the `date` placeholder from the
+[`post_url_format`][config.post_url_format] format string.
+
+---
+
+#### <!-- md:setting config.post_url_format -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `{date}/{slug}` -->
+
+Use this setting to change the format string that is used when generating post
+URLs. You can freely combine placeholders, and join them with slashes or other
+characters:
+
+=== ":material-link: blog/2024/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_url_format: "{date}/{slug}"
+ ```
+
+=== ":material-link: blog/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_url_format: "{slug}"
+ ```
+
+The following placeholders are available:
+
+- `categories` – Post categories, slugified with [`categories_slugify`][config.categories_slugify]
+- `date` – Post date, formatted with [`post_url_date_format`][config.post_url_date_format]
+- `slug` – Post title, slugified with [`post_slugify`][config.post_slugify], or explicitly set via [`slug`][meta.slug] metadata property
+- `file` – Post filename without `.md` file extension
+
+If you remove the `date` placeholder, make sure that post URLs don't collide
+with URLs of other pages hosted under the [`blog` directory][config.blog_dir],
+as this leads to undefined behavior.
+
+---
+
+#### <!-- md:setting config.post_url_max_categories -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `1` -->
+
+Use this setting to set an upper bound for the number of categories included in
+post URLs if the `categories` placeholder is part of [`post_url_format`]
+[config.post_url_format] and the post defines categories:
+
+``` yaml
+plugins:
+ - blog:
+ post_url_format: "{categories}/{slug}"
+ post_url_max_categories: 2
+```
+
+If more than one category is given, they are joined with `/` after slugifying.
+
+---
+
+#### <!-- md:setting config.post_slugify -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default [`pymdownx.slugs.slugify`][pymdownx.slugs.slugify] -->
+
+Use this setting to change the function for generating URL-compatible slugs
+from post titles. By default, the [`slugify`][pymdownx.slugs.slugify] function
+from [Python Markdown Extensions] is used as follows:
+
+``` yaml
+plugins:
+ - blog:
+ post_slugify: !!python/object/apply:pymdownx.slugs.slugify
+ kwds:
+ case: lower
+```
+
+The default configuration is Unicode-aware and should produce good slugs for all
+languages. Of course, you can also provide a custom slugification function for
+more granular control.
+
+ [pymdownx.slugs.slugify]: https://github.com/facelessuser/pymdown-extensions/blob/01c91ce79c91304c22b4e3d7a9261accc931d707/pymdownx/slugs.py#L59-L65
+ [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
+
+---
+
+#### <!-- md:setting config.post_slugify_separator -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `-` -->
+
+Use this setting to change the separator that is passed to the slugification
+function set as part of [`post_slugify`][config.post_slugify]. While the default
+is a hyphen, it can be set to any string, e.g., `_`:
+
+``` yaml
+plugins:
+ - blog:
+ post_slugify_separator: _
+```
+
+---
+
+#### <!-- md:setting config.post_excerpt -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `optional` -->
+
+By default, the plugin makes [post excerpts](../setup/setting-up-a-blog.md#adding-an-excerpt)
+optional. When a post doesn't define an excerpt, views include the entire post.
+This setting can be used to make post excerpts required:
+
+=== "Optional"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_excerpt: optional
+ ```
+
+=== "Required"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_excerpt: required
+ ```
+
+When post excerpts are required, posts without excerpt separators raise an
+error. Thus, this setting is useful when you want to make sure that all posts
+have excerpts defined.
+
+---
+
+#### <!-- md:setting config.post_excerpt_max_authors -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `1` -->
+
+Use this setting to set an upper bound for the number of authors rendered in
+post excerpts. While each post may be written by multiple authors, this setting
+allows to limit the display to just a few or even a single author, or disable
+authors in post excerpts:
+
+=== "Render up to 2 authors"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_excerpt_max_authors: 2
+ ```
+
+=== "Disable authors"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_excerpt_max_authors: 0
+ ```
+
+This only applies to post excerpts in views. Posts always render all authors.
+
+---
+
+#### <!-- md:setting config.post_excerpt_max_categories -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `5` -->
+
+Use this setting to set an upper bound for the number of categories rendered in
+post excerpts. While each post may be assigned to multiple categories, this
+setting allows to limit the display to just a few or even a single category, or
+disable categories in post excerpts:
+
+=== "Render up to 2 categories"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_excerpt_max_categories: 2
+ ```
+
+=== "Disable categories"
+
+ ``` yaml
+ plugins:
+ - blog:
+ post_excerpt_max_categories: 0
+ ```
+
+This only applies to post excerpts in views. Posts always render all categories.
+
+---
+
+#### <!-- md:setting config.post_excerpt_separator -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default <code><!-- more --></code> -->
+
+Use this setting to set the separator the plugin will look for in a post's
+content when generating post excerpts. All content __before__ the separator is
+considered to be part of the excerpt:
+
+``` yaml
+plugins:
+ - blog:
+ post_excerpt_separator: <!-- more -->
+```
+
+It is common practice to use an HTML comment as a separator.
+
+---
+
+#### <!-- md:setting config.post_readtime -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `true` -->
+
+Use this setting to control whether the plugin should automatically compute the
+reading time of a post, which is then rendered in post excerpts, as well as in
+posts themselves:
+
+``` yaml
+plugins:
+ - blog:
+ post_readtime: false
+```
+
+!!! warning "Chinese, Japanese and Korean characters"
+
+ Reading time computation currently does not take segmentation of Chinese,
+ Japanese and Korean characters into account. This means that the reading
+ time for posts in these languages may be inaccurate. We're planning on
+ adding support in the future. In the meantime, please use the `readtime`
+ front matter property to set the reading time.
+
+---
+
+#### <!-- md:setting config.post_readtime_words_per_minute -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `265` -->
+
+Use this setting to change the number of words that a reader is expected to read
+per minute when computing the reading time of a post. If you want to fine-tune
+it, use:
+
+``` yaml
+plugins:
+ - blog:
+ post_readtime_words_per_minute: 300
+```
+
+A reading time of 265 words per minute is considered to be the
+[average reading time of an adult].
+
+ [average reading time of an adult]: https://help.medium.com/hc/en-us/articles/214991667-Read-time
+
+### Archive
+
+The following settings are available for archive pages:
+
+---
+
+#### <!-- md:setting config.archive -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable archive pages. An archive page shows all
+posts for a specific interval (e.g. year, month, etc.) in reverse order. If you
+want to disable archive pages, use:
+
+``` yaml
+plugins:
+ - blog:
+ archive: false
+```
+
+---
+
+#### <!-- md:setting config.archive_name -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default computed -->
+
+Use this setting to change the title of the archive section the plugin adds to
+the navigation. If this setting is omitted, it's sourced from the translations.
+If you want to change it, use:
+
+``` yaml
+plugins:
+ - blog:
+ archive_name: Archive
+```
+
+---
+
+#### <!-- md:setting config.archive_date_format -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `yyyy` -->
+
+Use this setting to change the date format used for archive page titles. The
+format string must adhere to [babel]'s [pattern syntax]. Some popular choices:
+
+=== "2024"
+
+ ``` yaml
+ plugins:
+ - blog:
+ archive_date_format: yyyy
+ ```
+
+=== "January 2024"
+
+ ``` yaml
+ plugins:
+ - blog:
+ archive_date_format: MMMM yyyy
+ ```
+
+Note that depending on the [site language], results might look different for
+other languages.
+
+---
+
+#### <!-- md:setting config.archive_url_date_format -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `yyyy` -->
+
+Use this setting to change the date format used for archive page URLs. The
+format string must adhere to [babel]'s [pattern syntax] and should not contain
+whitespace. Some popular choices:
+
+=== ":material-link: blog/archive/2024/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ archive_url_date_format: yyyy
+ ```
+
+=== ":material-link: blog/archive/2024/01/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ archive_url_date_format: yyyy/MM
+ ```
+
+---
+
+#### <!-- md:setting config.archive_url_format -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `archive/{date}` -->
+
+Use this setting to change the format string that is used when generating
+archive page URLs. You can freely combine placeholders, and join them with
+slashes or other characters:
+
+=== ":material-link: blog/archive/2024/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ archive_url_format: "archive/{date}"
+ ```
+
+=== ":material-link: blog/2024/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ archive_url_format: "{date}"
+ ```
+
+The following placeholders are available:
+
+- `date` – Archive date, formatted with [`archive_url_date_format`][config.archive_url_date_format]
+
+---
+
+#### <!-- md:setting config.archive_pagination -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable pagination for archive pages. The value
+of this setting is inherited from [`pagination`][config.pagination], unless it's
+explicitly set. To disable pagination, use:
+
+``` yaml
+plugins:
+ - blog:
+ archive_pagination: false
+```
+
+---
+
+#### <!-- md:setting config.archive_pagination_per_page -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `10` -->
+
+Use this setting to change the number of posts rendered per archive page. The
+value of this setting is inherited from [`pagination_per_page`]
+[config.pagination_per_page], unless it's explicitly set. To change it, use:
+
+``` yaml
+plugins:
+ - blog:
+ archive_pagination_per_page: 5
+```
+
+---
+
+#### <!-- md:setting config.archive_toc -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `false` -->
+
+Use this setting to leverage the table of contents to display post titles on all
+archive pages. The value of this setting is inherited from [`blog_toc`]
+[config.blog_toc], unless it's explicitly set. To change it, use
+
+``` yaml
+plugins:
+ - blog:
+ archive_toc: true
+```
+
+### Categories
+
+The following settings are available for category pages:
+
+---
+
+#### <!-- md:setting config.categories -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable category pages. A category page shows all
+posts for a specific category in reverse chronological order. If you want to
+disable category pages, use:
+
+``` yaml
+plugins:
+ - blog:
+ categories: false
+```
+
+---
+
+#### <!-- md:setting config.categories_name -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default computed -->
+
+Use this setting to change the title of the category section the plugin adds to
+the navigation. If this setting is omitted, it's sourced from the translations.
+If you want to change it, use:
+
+``` yaml
+plugins:
+ - blog:
+ categories_name: Categories
+```
+
+---
+
+#### <!-- md:setting config.categories_url_format -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `category/{slug}` -->
+
+Use this setting to change the format string that is used when generating
+category page URLs. You can freely combine placeholders, and join them with
+slashes or other characters:
+
+=== ":material-link: blog/category/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ categories_url_format: "category/{slug}"
+ ```
+
+=== ":material-link: blog/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ categories_url_format: "{slug}"
+ ```
+
+The following placeholders are available:
+
+- `slug` – Category, slugified with [`categories_slugify`][config.categories_slugify]
+
+---
+
+#### <!-- md:setting config.categories_slugify -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default [`pymdownx.slugs.slugify`][pymdownx.slugs.slugify] -->
+
+Use this setting to change the function for generating URL-compatible slugs
+from categories. By default, the [`slugify`][pymdownx.slugs.slugify] function
+from [Python Markdown Extensions] is used as follows:
+
+``` yaml
+plugins:
+ - blog:
+ categories_slugify: !!python/object/apply:pymdownx.slugs.slugify
+ kwds:
+ case: lower
+```
+
+The default configuration is Unicode-aware and should produce good slugs for all
+languages. Of course, you can also provide a custom slugification function for
+more granular control.
+
+---
+
+#### <!-- md:setting config.categories_slugify_separator -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `-` -->
+
+Use this setting to change the separator that is passed to the slugification
+function set as part of [`categories_slugify`][config.categories_slugify]. While
+the default is a hyphen, it can be set to any string, e.g., `_`:
+
+``` yaml
+plugins:
+ - blog:
+ categories_slugify_separator: _
+```
+
+---
+
+#### <!-- md:setting config.categories_sort_by -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `material.plugins.blog.view_name` -->
+
+Use this setting to specify a custom function for sorting categories. For
+example, if you want to sort categories by the number of posts they contain,
+use the following configuration:
+
+``` yaml
+plugins:
+ - blog:
+ categories_sort_by: !!python/name:material.plugins.blog.view_post_count
+```
+
+Don't forget to enable [`categories_sort_reverse`][config.categories_sort_reverse].
+You can define your own comparison function, which must return something
+that can be compared while sorting, i.e., a string or number.
+
+---
+
+#### <!-- md:setting config.categories_sort_reverse -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `false` -->
+
+Use this setting to reverse the order in which categories are sorted. By
+default, categories are sorted in ascending order, but you can reverse ordering
+as follows:
+
+``` yaml
+plugins:
+ - blog:
+ categories_sort_reverse: true
+```
+
+---
+
+#### <!-- md:setting config.categories_allowed -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default none -->
+
+The plugin allows to check categories against a predefined list, in order to
+catch typos or make sure that categories are not arbitrarily added. Specify the
+categories you want to allow with:
+
+``` yaml
+plugins:
+ - blog:
+ categories_allowed:
+ - Search
+ - Performance
+```
+
+The plugin stops the build if a post references a category that is not part of
+this list. Posts can be assigned to categories by using the [`categories`]
+[meta.categories] metadata property.
+
+---
+
+#### <!-- md:setting config.categories_pagination -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable pagination for category pages. The value
+of this setting is inherited from [`pagination`][config.pagination], unless it's
+explicitly set. To disable pagination, use:
+
+``` yaml
+plugins:
+ - blog:
+ categories_pagination: false
+```
+
+---
+
+#### <!-- md:setting config.categories_pagination_per_page -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `10` -->
+
+Use this setting to change the number of posts rendered per category page. The
+value of this setting is inherited from [`pagination_per_page`]
+[config.pagination_per_page], unless it's explicitly set. To change it, use:
+
+``` yaml
+plugins:
+ - blog:
+ categories_pagination_per_page: 5
+```
+
+---
+
+#### <!-- md:setting config.categories_toc -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `false` -->
+
+Use this setting to leverage the table of contents to display post titles on all
+category pages. The value of this setting is inherited from [`blog_toc`]
+[config.blog_toc], unless it's explicitly set. To change it, use:
+
+``` yaml
+plugins:
+ - blog:
+ categories_toc: true
+```
+
+### Authors
+
+The following settings are available for authors:
+
+---
+
+#### <!-- md:setting config.authors -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable post authors. If this setting is enabled,
+the plugin will look for a file named [`.authors.yml`][config.authors_file] and
+render authors in posts and views. Disable this behavior with:
+
+``` yaml
+plugins:
+ - blog:
+ authors: false
+```
+
+---
+
+#### <!-- md:setting config.authors_file -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `{blog}/.authors.yml` -->
+
+Use this setting to change the path of the file where the author information for
+your posts resides. It's normally not necessary to change this setting, but if
+you need to, use:
+
+``` yaml
+plugins:
+ - blog:
+ authors_file: "{blog}/.authors.yml"
+```
+
+The following placeholders are available:
+
+- `blog` – [`blog` directory][config.blog_dir]
+
+The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
+
+!!! info "Format of author information"
+
+ The `.authors.yml` file must adhere to the following format:
+
+ ``` yaml title=".authors.yml"
+ authors:
+ <author>:
+ name: string # Author name
+ description: string # Author description
+ avatar: url # Author avatar
+ slug: url # Author profile slug
+ url: url # Author website URL
+ ```
+
+ Note that `<author>` must be set to an identifier for associating authors
+ with posts, e.g., a GitHub username like `squidfunk`. This identifier can
+ then be used in the [`authors`][meta.authors] metadata property of
+ a post. Multiple authors are supported. As an example, see
+ [the `.authors.yml` file][.authors.yml] we're using for our blog.
+
+ [.authors.yml]: https://github.com/squidfunk/mkdocs-material/blob/master/docs/blog/.authors.yml
+
+---
+
+#### <!-- md:setting config.authors_profiles -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `false` -->
+
+Use this setting to enable or disable automatically generated author profiles.
+An author profile shows all posts by an author in reverse chronological order.
+You can enable author profiles with:
+
+``` yaml
+plugins:
+ - blog:
+ authors_profiles: true
+```
+
+---
+
+#### <!-- md:setting config.authors_profiles_name -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default computed -->
+
+Use this setting to change the title of the authors section the plugin adds to
+the navigation. If this setting is omitted, it's sourced from the translations.
+If you want to change it, use:
+
+``` yaml
+plugins:
+ - blog:
+ authors_profiles_name: Authors
+```
+
+---
+
+#### <!-- md:setting config.authors_profiles_url_format -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `author/{slug}` -->
+
+Use this setting to change the format string that is used when generating
+author profile URLs. You can freely combine placeholders, and join them with
+slashes or other characters:
+
+=== ":material-link: blog/author/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ authors_profiles_url_format: "author/{slug}"
+ ```
+
+=== ":material-link: blog/:material-dots-horizontal:/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ authors_profiles_url_format: "{slug}"
+ ```
+
+The following placeholders are available:
+
+- `slug` – Author slug or identifier from [`authors_file`][config.authors_file]
+- `name` – Author name from [`authors_file`][config.authors_file]
+
+---
+
+#### <!-- md:setting config.authors_profiles_pagination -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable pagination for author profiles. The value
+of this setting is inherited from [`pagination`][config.pagination], unless it's
+explicitly set. To disable pagination, use:
+
+``` yaml
+plugins:
+ - blog:
+ authors_profiles_pagination: false
+```
+
+---
+
+#### <!-- md:setting config.authors_profiles_pagination_per_page -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `10` -->
+
+Use this setting to change the number of posts rendered per archive page. The
+value of this setting is inherited from [`pagination_per_page`]
+[config.pagination_per_page], unless it's explicitly set. To change it, use:
+
+``` yaml
+plugins:
+ - blog:
+ authors_profiles_pagination_per_page: 5
+```
+
+---
+
+#### <!-- md:setting config.authors_profiles_toc -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `false` -->
+
+Use this setting to leverage the table of contents to display post titles on all
+author profiles. The value of this setting is inherited from [`blog_toc`]
+[config.blog_toc], unless it's explicitly set. To change it, use:
+
+``` yaml
+plugins:
+ - blog:
+ authors_profiles_toc: true
+```
+
+### Pagination
+
+The following settings are available for pagination:
+
+---
+
+#### <!-- md:setting config.pagination -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable pagination in views – generated pages
+that show posts or subsets of posts in reverse chronological order. If you want
+to disable pagination, use:
+
+``` yaml
+plugins:
+ - blog:
+ pagination: false
+```
+
+---
+
+#### <!-- md:setting config.pagination_per_page -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `10` -->
+
+Use this setting to change the number of posts rendered per page. If you have
+rather long post excerpts, it can be a good idea to reduce the number of posts
+per page:
+
+``` yaml
+plugins:
+ - blog:
+ pagination_per_page: 5
+```
+
+---
+
+#### <!-- md:setting config.pagination_url_format -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `page/{page}` -->
+
+Use this setting to change the format string that is used when generating
+paginated view URLs. You can freely combine placeholders, and join them with
+slashes or other characters:
+
+=== ":material-link: blog/page/n/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ pagination_url_format: "page/{page}"
+ ```
+
+=== ":material-link: blog/n/"
+
+ ``` yaml
+ plugins:
+ - blog:
+ pagination_url_format: "{page}"
+ ```
+
+The following placeholders are available:
+
+- `page` – Page number
+
+---
+
+#### <!-- md:setting config.pagination_format -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `~2~` -->
+
+The plugin uses the [paginate] module to generate the pagination markup using a
+special syntax. Use this setting to customize how pagination is constructed.
+Some popular choices:
+
+=== "1 2 3 .. n"
+
+ ``` yaml
+ plugins:
+ - blog:
+ pagination_format: "~2~"
+ ```
+
+=== "1 2 3 .. n :material-chevron-right: :material-chevron-double-right:"
+
+ ``` yaml
+ plugins:
+ - blog:
+ pagination_format: "$link_first $link_previous ~2~ $link_next $link_last"
+ ```
+
+=== "1 :material-chevron-right:"
+
+ ``` yaml
+ plugins:
+ - blog:
+ pagination_format: "$link_previous $page $link_next"
+ ```
+
+The following placeholders are supported by [paginate]:
+
+- `#!css $first_page` – Number of first reachable page
+- `#!css $last_page` – Number of last reachable page
+- `#!css $page` – Number of currently selected page
+- `#!css $page_count` – Number of reachable pages
+- `#!css $items_per_page` – Maximal number of items per page
+- `#!css $first_item` – Index of first item on the current page
+- `#!css $last_item` – Index of last item on the current page
+- `#!css $item_count` – Total number of items
+- `#!css $link_first` – Link to first page (unless on first page)
+- `#!css $link_last` – Link to last page (unless on last page)
+- `#!css $link_previous` – Link to previous page (unless on first page)
+- `#!css $link_next` – Link to next page (unless on last page)
+
+ [paginate]: https://pypi.org/project/paginate/
+
+---
+
+#### <!-- md:setting config.pagination_if_single_page -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `false` -->
+
+Use this setting to control whether pagination should be automatically disabled
+when the view only consists of a single page. If you want to always render
+pagination, use:
+
+``` yaml
+plugins:
+ - blog:
+ pagination_if_single_page: true
+```
+
+---
+
+#### <!-- md:setting config.pagination_keep_content -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `false` -->
+
+Use this setting to enable or disable persistence of content, i.e., if paginated
+views should also display the content of their containing view. If you want to
+enable this behavior, use:
+
+``` yaml
+plugins:
+ - blog:
+ pagination_keep_content: true
+```
+
+### Drafts
+
+The following settings are available for drafts:
+
+---
+
+#### <!-- md:setting config.draft -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `false` -->
+
+Rendering [draft posts][meta.draft] can be useful in deploy previews. Use this
+setting to specify whether the plugin should include posts marked as drafts when
+[building your project]:
+
+=== "Render drafts"
+
+ ``` yaml
+ plugins:
+ - blog:
+ draft: true
+ ```
+
+=== "Don't render drafts"
+
+ ``` yaml
+ plugins:
+ - blog:
+ draft: false
+ ```
+
+---
+
+#### <!-- md:setting config.draft_on_serve -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `true` -->
+
+Use this setting to control whether the plugin should include posts marked as
+drafts when [previewing your site]. If you don't wish to include draft posts
+when previewing, use:
+
+``` yaml
+plugins:
+ - blog:
+ draft_on_serve: false
+```
+
+ [previewing your site]: ../creating-your-site.md#previewing-as-you-write
+
+---
+
+#### <!-- md:setting config.draft_if_future_date -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `false` -->
+
+The plugin can automatically mark posts with future dates as drafts. When the
+date is past today, the post is automatically included when
+[building your project], unless explicitly marked as draft:
+
+``` yaml
+plugins:
+ - blog:
+ draft_if_future_date: true
+```
+
+## Usage
+
+### Metadata
+
+Posts can define a handful of metadata properties that specify how the plugin
+renders them, in which views they are integrated, and how they are linked to
+each other. The metadata of each post is validated against a schema to allow for
+a quicker discovery of syntax errors.
+
+The following properties are available:
+
+---
+
+#### <!-- md:setting meta.authors -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:flag metadata -->
+<!-- md:default none -->
+
+Use this property to associate a post with [authors] by providing a list of
+identifiers as defined in the [`authors_file`][config.authors_file]. If an
+author can't be resolved, the plugin will terminate with an error:
+
+``` yaml
+---
+authors:
+ - squidfunk # (1)!
+---
+
+# Post title
+...
+```
+
+1. Authors are linked by using their identifiers. As an example, see
+ [the `.authors.yml` file][.authors.yml] we're using for our blog.
+
+ [authors]: #authors
+
+---
+
+#### <!-- md:setting meta.categories -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:flag metadata -->
+<!-- md:default none -->
+
+Use this property to associate a post with one or more [categories][category],
+making the post a part of the generated category page. Categories are defined
+as a list of strings (whitespaces are allowed):
+
+``` yaml
+---
+categories:
+ - Search
+ - Performance
+---
+
+# Post title
+...
+```
+
+If you want to prevent accidental typos assigning categories to posts, you
+can set a predefined list of allowed categories in `mkdocs.yml` by using
+the [`categories_allowed`][config.categories_allowed] setting.
+
+---
+
+#### <!-- md:setting meta.date -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:flag metadata -->
+<!-- md:flag required -->
+
+Use this property to specify a post's date. Note that this property is required,
+which means the build fails when it's not set. Additional dates can be set by
+using a slightly different syntax:
+
+=== "Date"
+
+ ``` yaml
+ ---
+ date: 2024-01-31
+ ---
+
+ # Post title
+ ...
+ ```
+
+=== "Update date"
+
+ ``` yaml
+ ---
+ date:
+ created: 2024-01-31 # (1)!
+ updated: 2024-02-01
+ ---
+
+ # Post title
+ ...
+ ```
+
+ 1. Each post must have a creation date set.
+
+=== "Custom date"
+
+ ``` yaml
+ ---
+ date:
+ created: 2024-01-31
+ my_custom_date: 2024-02-01 # (1)!
+ ---
+
+ # Post title
+ ...
+ ```
+
+ 1. The blog plugin validates all dates and allows to format them with
+ [babel]'s [pattern syntax] in templates. When using theme extension,
+ authors can add custom dates to templates.
+
+ This was first requested in #5733.
+
+The following date formats are supported:
+
+- `2024-01-31`
+- `2024-01-31T12:00:00`
+
+---
+
+#### <!-- md:setting meta.draft -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:flag metadata -->
+<!-- md:default none -->
+
+Use this property to mark a post as draft. The plugin allows to include or
+exclude posts marked as drafts when [building your project] using the
+[`draft`][config.draft] setting. Mark a post as draft with:
+
+``` yaml
+---
+draft: true
+---
+
+# Post title
+...
+```
+
+---
+
+#### <!-- md:setting meta.pin -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:flag metadata -->
+<!-- md:default `false` -->
+<!-- md:flag experimental -->
+
+Use this property to pin a post to the top of a view. In case multiple posts are
+pinned, the pinned posts are sorted by descending order and appear before all
+other posts. Pin a post with:
+
+``` yaml
+---
+pin: true
+---
+
+# Post title
+...
+```
+
+---
+
+#### <!-- md:setting meta.links -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:flag metadata -->
+<!-- md:default none -->
+<!-- md:flag experimental -->
+
+Use this property to define a list of links that are rendered in the sidebar of
+a post. The property follows the same syntax as [`nav`][mkdocs.nav] in
+`mkdocs.yml`, supporting sections and even anchors:
+
+=== "Links"
+
+ ``` yaml
+ ---
+ links:
+ - setup/setting-up-site-search.md
+ - insiders/index.md
+ ---
+
+ # Post title
+ ...
+ ```
+
+=== "Links with sections"
+
+ ``` yaml
+ ---
+ links:
+ - setup/setting-up-site-search.md
+ - Insiders:
+ - insiders/index.md
+ - insiders/getting-started.md
+ ---
+
+ # Post title
+ ...
+ ```
+
+=== "Links with anchors"
+
+ ``` yaml
+ ---
+ links:
+ - plugins/search.md # (1)!
+ - Insiders:
+ - insiders/how-to-sponsor.md
+ - insiders/getting-started.md#requirements
+ ---
+
+ # Post title
+ ...
+ ```
+
+ 1. If a link defines an anchor, the plugin resolves the anchor from the
+ linked page and sets the anchor title as a [subtitle].
+
+All relative links are resolved from the [`docs` directory][mkdocs.docs_dir].
+
+ [subtitle]: ../reference/index.md#setting-the-page-subtitle
+
+---
+
+#### <!-- md:setting meta.readtime -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:flag metadata -->
+<!-- md:default computed -->
+
+Use this property to explicitly set the reading time of a post in minutes. When
+[`post_readtime`][config.post_readtime] is enabled, the plugin computes the
+reading time of a post, which can be overridden with:
+
+``` yaml
+---
+readtime: 15
+---
+
+# Post title
+...
+```
+
+---
+
+#### <!-- md:setting meta.slug -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:flag metadata -->
+<!-- md:default computed -->
+
+Use this property to explicitly set the slug of a post. By default, the slug of
+a post is automatically computed by the [`post_slugify`][config.post_slugify]
+function from the post's title, which can be overridden with:
+
+``` yaml
+---
+slug: help-im-trapped-in-a-universe-factory
+---
+
+# Post title
+...
+```
+
+Slugs are passed to [`post_url_format`][config.post_url_format].
+
+---
+
+!!! question "Missing something?"
+
+ When setting up your blog or migrating from another blog framework, you
+ might discover that you're missing specific functionality – we're happy to
+ consider adding it to the plugin! You can [open a discussion] to
+ ask a question, or create a [change request] on our [issue tracker], so we
+ can find out if it might be a good fit for the plugin.
+
+ [open a discussion]: https://github.com/squidfunk/mkdocs-material/discussions
+ [change request]: ../contributing/requesting-a-change.md
+ [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
diff --git a/documents/markdown/mkdocs-material/plugins_group.md b/documents/markdown/mkdocs-material/plugins_group.md
new file mode 100644
index 0000000..6e17c4c
--- /dev/null
+++ b/documents/markdown/mkdocs-material/plugins_group.md
@@ -0,0 +1,121 @@
+---
+title: Built-in group plugin
+icon: material/format-list-group
+---
+
+# Built-in group plugin
+
+The group plugin allows to group plugins into logical units to conditionally
+enable or disable them for specific environments with the use of
+[environment variables][mkdocs.env], e.g., to only enable a subset of
+plugins when [building your project] during continuous integration (CI).
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+## Objective
+
+### How it works
+
+The plugin conditionally and lazily loads all plugins that are part of a group
+if and only if the group is enabled, which means that the plugin doesn't add any
+overhead when the group is disabled. It also means that the grouped plugins
+only need to be installed when the group is enabled.
+
+The plugins that are part of the group are executed in the same order as if
+they were defined at the top-level in the list of [`plugins`][mkdocs.plugins].
+Thus, order is preserved and deterministic.
+
+### When to use it
+
+Whenever you're using multiple plugins that are only required in specific
+environments, e.g., when building your project during continuous integration
+(CI), the plugin is the perfect utility for making configuration simpler, as it
+removes the need for splitting configuration into multiple files.
+
+It can be used with any built-in or third-party plugin.
+
+## Configuration
+
+<!-- md:version 9.3.0 -->
+<!-- md:plugin [group] – built-in -->
+<!-- md:flag multiple -->
+<!-- md:flag experimental -->
+
+As with all [built-in plugins], getting started with the group plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and start
+splitting plugins into logical units:
+
+``` yaml
+plugins:
+ - group
+```
+
+The group plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [group]: group.md
+ [built-in plugins]: index.md
+
+### General
+
+The following settings are available:
+
+---
+
+#### <!-- md:setting config.enabled -->
+
+<!-- md:version 9.3.0 -->
+<!-- md:default `false` -->
+
+Use this setting to enable or disable the plugin when [building your project].
+The plugin behaves differently than all other built-in plugins – __it is
+disabled by default__. To enable a group, use:
+
+``` yaml
+plugins:
+ - group:
+ enabled: !ENV CI # (1)!
+```
+
+1. If you only want to use the group plugin for better organization and
+ always want to enable the plugins that are part of it, use:
+
+ ``` yaml
+ plugins:
+ - group:
+ enabled: true
+ ```
+
+The decision to disable the plugin by default was made to simplify the usage
+of environment variables, as it removes the need to provide a default value for
+an environment variable.
+
+Now, when [building your project], you can enable a group by setting the
+[environment variable][mkdocs.env]:
+
+``` sh
+CI=true mkdocs build
+```
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+---
+
+#### <!-- md:setting config.plugins -->
+
+<!-- md:version 9.3.0 -->
+<!-- md:default none -->
+
+Use this setting to list the plugins that are part of the group. The syntax is
+exactly the same as for the [`plugins`][mkdocs.plugins] setting, so you can
+simply copy the list of plugins that you want to group, e.g:
+
+``` yaml
+plugins:
+ - group:
+ plugins:
+ - optimize
+ - minify
+```
+
+The plugins mentioned here are just used for illustration purposes.
diff --git a/documents/markdown/mkdocs-material/plugins_index.md b/documents/markdown/mkdocs-material/plugins_index.md
new file mode 100644
index 0000000..8bf6a8a
--- /dev/null
+++ b/documents/markdown/mkdocs-material/plugins_index.md
@@ -0,0 +1,246 @@
+# Built-in plugins
+
+Material for MkDocs started out as a theme for [MkDocs][mkdocs], but has since
+evolved into a full-fledged framework for building and maintaining documentation.
+The theme is still the core of the project, but it's now accompanied by a
+growing number of complementary built-in plugins.
+
+We strive to make those plugins as modular and generic as possible, so that they
+can be used in a wide variety of projects and use cases. By providing useful
+default settings, we also try to make them as easy to use as possible, so that
+you can get started quickly, tweaking their settings later on. When
+developing built-in plugins, we always adhere to the following design principles:
+
+- **Modularity:** Built-in plugins are designed to be modular, so that they can
+ be easily combined to implement sophisticated pipelines. For example, the
+ [offline], [optimize] and [privacy] plugins can be used together to build
+ truly [offline-capable documentation].
+
+- **Interoperability:** Built-in plugins are designed to be as compatible as
+ possible, so they can be used in combination with other plugins, including
+ third-party plugins. We strive to make it simple to integrate with the vast
+ ecosystem that has evolved around [MkDocs][mkdocs].
+
+- **Performance:** Built-in plugins are designed to be as fast and
+ memory-efficient as possible, so that they don't unnecessarily slow down
+ builds. This is particularly important for large documentation projects with
+ thousands of pages.
+
+ [mkdocs]: https://www.mkdocs.org/
+ [design principles]: ../design-principles.md
+ [offline-capable documentation]: ../setup/building-for-offline-usage.md
+
+## Categories
+
+### Management
+
+The following plugins greatly improve the authoring experience when working on
+documentation projects by providing better management capabilities, from the
+management of plugins, multiple projects, and metadata, to the creation of
+minimal reproductions for bug reports:
+
+<div class="grid cards" markdown>
+
+- :material-format-list-group: __[Built-in group plugin][group]__
+
+ ---
+
+ The group plugin allows to group plugins into logical units to conditionally
+ enable or disable them for specific environments with the use of
+ [environment variables][mkdocs.env].
+
+ ---
+
+ __Optimal management of plugins when building in different environments__
+
+- :material-file-tree: __[Built-in meta plugin][meta]__
+
+ ---
+
+ The meta plugin makes it easy to manage metadata (front matter) for all
+ pages in a folder, so a certain subset of pages uses specific tags or a
+ custom template.
+
+ ---
+
+ __Simpler organization, categorization and management of metadata__
+
+- :material-folder-open: __[Built-in projects plugin][projects]__
+
+ ---
+
+ The projects plugin allows to split your main project into multiple distinct
+ projects, build them concurrently and preview them together as one.
+
+ ---
+
+ __Connect multiple projects together, and build them separately or as one__
+
+- :material-information: __[Built-in info plugin][info]__
+
+ ---
+
+ The info plugin is a small and useful utility that helps to create
+ self-contained minimal reproductions, so we maintainers can fix reported
+ bugs more quickly.
+
+ ---
+
+ __Your bug reports are of the highest quality, so we can fix them as fast as
+ possible__
+
+
+</div>
+
+ [group]: group.md
+ [info]: info.md
+ [meta]: meta.md
+ [projects]: projects.md
+
+### Optimization
+
+The following plugins are designed to help you build optimized documentation,
+making it more accessible to your users through faster loading times, better
+search engine rankings, beautiful preview images on social media, and GDPR
+compliance with a few lines of configuration:
+
+<div class="grid cards" markdown>
+
+- :material-share-circle: __[Built-in social plugin][social]__
+
+ ---
+
+ The social plugin automatically generates beautiful and customizable
+ social cards for each page of your documentation, showing as previews on
+ social media.
+
+ ---
+
+ __Links to your site render beautiful social cards when shared on social
+ media__
+
+- :material-rabbit: __[Built-in optimize plugin][optimize]__
+
+ ---
+
+ The optimize plugin automatically identifies and optimizes all media files
+ that you reference in your project by using compression and conversion
+ techniques.
+
+ ---
+
+ __Your site loads faster as smaller images are served to your users__
+
+- :material-shield-account: __[Built-in privacy plugin][privacy]__
+
+ ---
+
+ The privacy plugin downloads external assets automatically for easy
+ self-hosting, allowing for GDPR compliance with a single line of
+ configuration.
+
+ ---
+
+ __Your documentation can be made GDPR compliant with minimal effort__
+
+- :material-connection: __[Built-in offline plugin][offline]__
+
+ ---
+
+ The offline plugin adds support for building [offline-capable documentation],
+ so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
+ file that can be downloaded.
+
+ ---
+
+ __Your documentation can work without connectivity to the internet__
+
+</div>
+
+ [offline]: offline.md
+ [optimize]: optimize.md
+ [privacy]: privacy.md
+ [social]: social.md
+
+### Content
+
+The following plugins are designed to help you set up a blog, provide search
+functionality to your users, add tags to pages and posts, and use the same
+typesetting capabilities in specific parts of the documentation exactly as in
+the main content:
+
+<div class="grid cards" markdown>
+
+- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__
+
+ ---
+
+ The blog plugin adds first-class support for blogging to Material for
+ MkDocs, either as a sidecar to your documentation or as a standalone
+ installation.
+
+ ---
+
+ __Your blog is built with the same powerful engine as your documentation__
+
+- :material-magnify: __[Built-in search plugin][search]__
+
+ ---
+
+ The search plugin adds a search bar to the header, allowing users to search
+ the entire documentation, so it's easier for them to find what they're
+ looking for.
+
+ ---
+
+ __Your documentation is searchable without any external services, even
+ offline__
+
+- :material-tag-text: __[Built-in tags plugin][tags]__
+
+ ---
+
+ The tags plugin adds first-class support for categorizing pages with tags,
+ adding the ability to group related pages to improve the discovery of
+ related content.
+
+ ---
+
+ __Your pages are categorized with tags, yielding additional context__
+
+- :material-format-title: __[Built-in typeset plugin][typeset]__
+
+ ---
+
+ The typeset plugin allows to preserve the enriched presentation of titles
+ and headlines within the navigation and table of contents.
+
+ ---
+
+ __Sidebars preserve the same formatting as section titles in pages__
+
+</div>
+
+ [blog]: blog.md
+ [search]: search.md
+ [tags]: tags.md
+ [typeset]: typeset.md
+
+## Architecture
+
+### Multiple instances
+
+Several built-in plugins have support for multiple instances, which means that
+they can be used multiple times in the same configuration file, allowing to
+fine-tune behavior for separate sections of your project. Currently, the
+following plugins have support for multiple instances:
+
+<div class="mdx-columns" markdown>
+
+- [Built-in blog plugin][blog]
+- [Built-in group plugin][group]
+- [Built-in optimize plugin][optimize]
+- [Built-in privacy plugin][privacy]
+- [Built-in social plugin][social]
+
+</div>
diff --git a/documents/markdown/mkdocs-material/plugins_info.md b/documents/markdown/mkdocs-material/plugins_info.md
new file mode 100644
index 0000000..b422daa
--- /dev/null
+++ b/documents/markdown/mkdocs-material/plugins_info.md
@@ -0,0 +1,155 @@
+---
+title: Built-in info plugin
+icon: material/information
+---
+
+# Built-in info plugin
+
+The info plugin is a utility that is solely intended to create self-contained
+[minimal reproductions] as `.zip` files when [reporting bugs] or proposing
+[change requests], making communication between us maintainers and you much
+easier, as we have a common ground to work on.
+
+ [minimal reproductions]: ../guides/creating-a-reproduction.md
+ [reporting bugs]: ../contributing/reporting-a-bug.md
+ [change requests]: ../contributing/requesting-a-change.md
+
+## Objective
+
+### How it works
+
+The plugin helps you to prepare a minimal reproduction by collecting the
+necessary information about the environment and configuration of your project.
+This makes it easier for us to fix bugs, as it requires that you
+[upgrade to the latest version] and [remove your customizations].
+
+When following these principles, you can be confident that you don't report a
+bug that has already been fixed in a subsequent release, or which is caused by
+one of your customizations. Even more importantly, you actively help
+us to fix the bug as quickly as possible.
+
+The output of the plugin is a `.zip` file that you can share with us maintainers.
+
+ [Upgrade to the latest version]: ../contributing/reporting-a-bug.md#upgrade-to-latest-version
+ [Remove your customizations]: ../contributing/reporting-a-bug.md#remove-customizations
+
+
+### When to use it
+
+Whenever you're [reporting a bug][reporting bugs] or have something to discuss,
+like a question or [change request][change requests], you should attach
+a small, self-contained minimal reproduction. Runnable examples help to make
+communication much more efficient, giving us maintainers more time to benefit
+more users by pushing the project forward. Minimal reproductions are mandatory
+for bug reports.
+
+## Configuration
+
+<!-- md:version 9.0.0 -->
+<!-- md:plugin [info] – built-in -->
+
+In order to get started with the built-in info plugin, just add the following
+lines to `mkdocs.yml`, and quickly [create a minimal reproduction] to share
+with us maintainers:
+
+``` yaml
+plugins:
+ - info
+```
+
+The info plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [info]: info.md
+ [create a minimal reproduction]: ../guides/creating-a-reproduction.md
+
+### General
+
+The following settings are available:
+
+---
+
+#### <!-- md:setting config.enabled -->
+
+<!-- md:version 9.0.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable the plugin when [building your project].
+It's normally not necessary to specify this setting, but if you want to disable
+the plugin, use:
+
+``` yaml
+plugins:
+ - info:
+ enabled: false
+```
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+---
+
+#### <!-- md:setting config.enabled_on_serve -->
+
+<!-- md:version 9.0.6 -->
+<!-- md:default `false` -->
+
+Use this setting to control whether the plugin should be enabled when
+[previewing your site]. It's normally not necessary to specify this setting,
+but if you want to change this behavior, use:
+
+``` yaml
+plugins:
+ - info:
+ enabled_on_serve: true
+```
+
+This setting streamlines the process of creating and inspecting minimal
+reproductions, as it allows to quickly iterate on the reproduction without
+having to disable the plugin first.
+
+ [previewing your site]: ../creating-your-site.md#previewing-as-you-write
+
+### Archive
+
+---
+
+#### <!-- md:setting config.archive -->
+
+<!-- md:version 9.0.0 -->
+<!-- md:default `true` -->
+
+Use this setting to control whether the plugin should create a `.zip` file
+from the project or exit after the version check. This setting is solely
+intended for debugging the plugin itself:
+
+``` yaml
+plugins:
+ - info:
+ archive: false
+```
+
+---
+
+#### <!-- md:setting config.archive_stop_on_violation -->
+
+<!-- md:version 9.0.0 -->
+<!-- md:default `true` -->
+
+Use this setting to control whether the plugin should stop creating the `.zip`
+file when one of the [requirements] is not satisfied. This setting must only be
+used when [reporting a bug][reporting bugs] that is related to a customization
+[explicitly mentioned in our documentation]. You can change it with:
+
+``` yaml
+plugins:
+ - info:
+ archive_stop_on_violation: false
+```
+
+If you're using this setting when [reporting a bug][reporting bugs], please
+explain why you think it is necessary to include customizations. If you're
+unsure, please ask us first by [creating a discussion].
+
+ [requirements]: #how-it-works
+ [explicitly mentioned in our documentation]: ?q=%22extends+base%22
+ [creating a discussion]: https://github.com/squidfunk/mkdocs-material/discussions
diff --git a/documents/markdown/mkdocs-material/plugins_meta.md b/documents/markdown/mkdocs-material/plugins_meta.md
new file mode 100644
index 0000000..4ef92ff
--- /dev/null
+++ b/documents/markdown/mkdocs-material/plugins_meta.md
@@ -0,0 +1,192 @@
+---
+title: Built-in meta plugin
+icon: material/file-tree
+---
+
+# Built-in meta plugin
+
+The meta plugin solves the problem of setting metadata (front matter) for all
+pages in a folder, i.e., a subsection of your project, which is particularly
+useful to ensure that a certain subset of pages features specific tags, uses a
+custom template, or is attributed to an author.
+
+## Objective
+
+### How it works
+
+The plugin scans the [`docs` directory][mkdocs.docs_dir] for `.meta.yml` files,
+and recursively merges the contents of those files with the metadata (front
+matter) of all pages that are contained in the same folder and all subfolders.
+For example, if you want to add the tag <span class="md-tag">Example</span> to
+multiple pages, use:
+
+``` yaml title=".meta.yml"
+tags:
+ - Example
+```
+
+Now, given the following directory layout, if you store the file in the folder
+named `example`, all pages in that folder receive the tag, while all pages
+outside of the folder remain unaffected:
+
+``` { .sh .no-copy hl_lines="4-8" }
+.
+├─ docs/
+│ ├─ ...
+│ ├─ example/
+│ │ ├─ .meta.yml
+│ │ ├─ a.md
+│ │ ├─ ...
+│ │ └─ z.md
+│ └─ ...
+└─ mkdocs.yml
+```
+
+When combining metadata, lists and dictionaries are recursively merged, which
+means you can append values to a list and add or set specific properties in a
+dictionary on arbitrary levels.
+
+### When to use it
+
+While the plugin itself doesn't offer much functionality beyond adding and
+merging metadata, it is a perfect companion for many of the other built-in
+plugins that Material for MkDocs offers. Some of the most powerful combinations
+of the meta plugin and other built-in plugins are:
+
+<div class="grid cards" markdown>
+
+- :material-share-circle: __[Built-in social plugin][social]__
+
+ ---
+
+ The meta plugin can be used to [change the layout] for social cards or
+ [change specific layout options] like [background] or [color]
+ for a subset of pages.
+
+ ``` yaml title=".meta.yml"
+ social:
+ cards_layout: default/variant
+ ```
+
+- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__
+
+ ---
+
+ The meta plugin allows to automatically associate blog posts with specific
+ [authors] and [categories], ensuring that blog posts are always correctly
+ annotated.
+
+ ``` yaml title=".meta.yml"
+ authors:
+ - squidfunk
+ ```
+
+- :material-tag-text: __[Built-in tags plugin][tags]__
+
+ ---
+
+ The meta plugin makes it possible to ensure that subsections of your
+ project are annotated with [specific tags], so they can't be forgotten when
+ adding pages.
+
+ ``` yaml title=".meta.yml"
+ tags:
+ - Example
+ ```
+
+- :material-magnify: __[Built-in search plugin][search]__
+
+ ---
+
+ The meta plugin makes it easy to [boost] specific sections in search results
+ or to [exclude] them entirely from being indexed, giving more granular
+ control over search.
+
+ ``` yaml title=".meta.yml"
+ search:
+ exclude: true
+ ```
+
+</div>
+
+ [social]: social.md
+ [change the layout]: social.md#meta.social.cards_layout
+ [change specific layout options]: social.md#meta.social.cards_layout_options
+ [background]: social.md#option.background_color
+ [color]: social.md#option.color
+ [blog]: blog.md
+ [authors]: blog.md#meta.authors
+ [categories]: blog.md#meta.categories
+ [tags]: tags.md
+ [specific tags]: tags.md#meta.tags
+ [search]: search.md
+ [exclude]: search.md#meta.search.exclude
+ [boost]: search.md#meta.search.boost
+
+## Configuration
+
+<!-- md:version 9.6.0 -->
+<!-- md:plugin [meta] – built-in -->
+<!-- md:flag experimental -->
+
+As with all [built-in plugins], getting started with the meta plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and start
+applying metadata for multiple pages at once:
+
+``` yaml
+plugins:
+ - meta
+```
+
+The meta plugin is included with Material for MkDocs and doesn't need to be
+installed.
+
+ [meta]: meta.md
+ [built-in plugins]: index.md
+
+### General
+
+The following settings are available:
+
+---
+
+#### <!-- md:setting config.enabled -->
+
+<!-- md:version 9.6.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable the plugin when [building your project].
+It's normally not necessary to specify this setting, but if you want to disable
+the plugin, use:
+
+``` yaml
+plugins:
+ - meta:
+ enabled: false
+```
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+### Meta file
+
+The following settings are available for meta files:
+
+---
+
+#### <!-- md:setting config.meta_file -->
+
+<!-- md:version 9.6.0 -->
+<!-- md:default `.meta.yml` -->
+
+Use this setting to change the meta file name the plugin will look for when
+scanning the [`docs` directory][mkdocs.docs_dir]. It's normally not necessary to
+change this setting, but if you want to change it, use:
+
+``` yaml
+plugins:
+ - meta:
+ meta_file: .meta.yml
+```
+
+The provided path is resolved from the [`docs` directory][mkdocs.docs_dir]
+recursively.
diff --git a/documents/markdown/mkdocs-material/plugins_offline.md b/documents/markdown/mkdocs-material/plugins_offline.md
new file mode 100644
index 0000000..243954d
--- /dev/null
+++ b/documents/markdown/mkdocs-material/plugins_offline.md
@@ -0,0 +1,154 @@
+---
+title: Built-in offline plugin
+icon: material/connection
+---
+
+
+# Built-in offline plugin
+
+[MkDocs][mkdocs] is one of the few frameworks that supports building
+offline-capable documentation that can be directly viewed by the user – no
+server needed. With the offline plugin, you can distribute the
+[`site` directory][mkdocs.site_dir] as a downloadable `.zip` file while
+retaining most interactive functionality.
+
+## Objective
+
+### How it works
+
+After [building your project], switch to the [`site` directory][mkdocs.site_dir]
+and open `index.html` in your browser – you're now viewing your documentation
+from your local file system! Most browsers will denote this by showing `file://`
+in the address bar. However, you'll realize that the site search is gone.
+
+Material for MkDocs offers many interactive features, some of which will not
+work from the local file system due to the restrictions of modern browsers. More
+specifically and technically, all calls to the [Fetch API] will error with a
+message like:
+
+```
+Cross origin requests are only supported for protocol schemes: http, [...]
+```
+
+While browsers impose those restriction for security reasons, it reduces the
+interactivity of your project. The offline plugin makes sure that site search
+keeps working by moving the search index to a JavaScript file, and leveraging
+@squidfunk's [iframe-worker] shim.
+
+Additionally, the plugin automatically disables the [`use_directory_urls`]
+[mkdocs.use_directory_urls] setting, ensuring that users can open your
+documentation directly from the local file system.
+
+There are some [limitations].
+
+ [building your project]: ../creating-your-site.md#building-your-site
+ [Fetch API]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
+ [iframe-worker]: https://github.com/squidfunk/iframe-worker
+ [limitations]: #limitations
+
+### When to use it
+
+As the name already indicates, the plugin should only be used when you're
+[building your project] for offline distribution. It's also good to know, that
+the offline plugin plays nicely with the following other plugins, helping to
+create even better offline-capable documentation:
+
+<div class="grid cards" markdown>
+
+- :material-shield-account: __[Built-in privacy plugin][privacy]__
+
+ ---
+
+ The privacy plugin makes it easy to use external assets when building for
+ offline usage, as it automatically downloads them for distribution with
+ your documentation.
+
+ ---
+
+ __Your documentation can work without connectivity to the internet[^1]__
+
+- :material-rabbit: __[Built-in optimize plugin][optimize]__
+
+ ---
+
+ The optimize plugin automatically identifies and optimizes all media files
+ that you reference in your project by using compression and conversion
+ techniques.
+
+ ---
+
+ __Your documentation can be distributed as a smaller `.zip` download__
+
+</div>
+
+ [^1]:
+ You might wonder why the [privacy plugin][privacy] is necessary to build
+ truly offline-capable documentation with the offline plugin. While it's
+ certainly possible to also add support for downloading external assets to
+ the offline plugin, this functionality is already fully implemented in the
+ privacy plugin and is its very raison d'être.
+
+ Material for MkDocs follows a modular approach for its plugin system – many
+ of the plugins work perfectly together and enhance each others
+ functionalities, allowing to solve complex problems with a few lines
+ of configuration.
+
+ [privacy]: privacy.md
+ [optimize]: optimize.md
+
+## Configuration
+
+<!-- md:version 9.0.0 -->
+<!-- md:plugin [offline] – built-in -->
+
+As with all [built-in plugins], getting started with the offline plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and start
+building offline-capable documentation:
+
+``` yaml
+plugins:
+ - offline
+```
+
+The offline plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [offline]: offline.md
+ [built-in plugins]: index.md
+
+### General
+
+The following settings are available:
+
+---
+
+#### <!-- md:setting config.enabled -->
+
+<!-- md:version 9.0.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable the plugin when [building your project].
+If you want to build online- as well as offline-capable documentation, it's a
+good idea to use an [environment variable][mkdocs.env]:
+
+``` yaml
+plugins:
+ - offline:
+ enabled: !ENV [OFFLINE, false]
+```
+
+## Limitations
+
+When enabling the offline plugin, make sure to disable the following settings,
+as they make use of the [Fetch API] which will error when invoked from the local
+file system:
+
+- [Instant loading]
+- [Site analytics]
+- [Versioning]
+- [Comment systems]
+
+ [Instant loading]: ../setup/setting-up-navigation.md#instant-loading
+ [Site analytics]: ../setup/setting-up-site-analytics.md
+ [Versioning]: ../setup/setting-up-versioning.md
+ [Comment systems]: ../setup/adding-a-comment-system.md
diff --git a/documents/markdown/mkdocs-material/plugins_optimize.md b/documents/markdown/mkdocs-material/plugins_optimize.md
new file mode 100644
index 0000000..6b30e1a
--- /dev/null
+++ b/documents/markdown/mkdocs-material/plugins_optimize.md
@@ -0,0 +1,427 @@
+---
+title: Built-in optimize plugin
+icon: material/rabbit
+---
+
+# Built-in optimize plugin
+
+The optimize plugin automatically identifies and optimizes all media files when
+[building your project] by using common compression and conversion techniques.
+As a result, your site loads significantly faster and yields better rankings in
+search engines.
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+## Objective
+
+### How it works
+
+The plugin scans the [`docs` directory][mkdocs.docs_dir] for media files and
+assets, optimizing them automatically in order to reduce the final size of the
+[`site` directory][mkdocs.site_dir]. This leads to faster loading times as you
+ship less bytes to your users, as well as a smaller download for
+[offline-capable documentation].
+
+Optimized images are [intelligently cached][intelligent caching], which is why
+the plugin will only optimize media files that changed since the last build.
+This makes it possible to swap out or update images, without having to worry
+about optimizing them, or even worse, forgetting to do so.
+
+In order to optimize media files, a few [dependencies] need to be available on
+your system.
+
+ [offline-capable documentation]: ../setup/building-for-offline-usage.md
+ [dependencies]: #configuration
+
+### When to use it
+
+It's generally recommended to use the plugin, as media files are optimized
+automatically without the need for intervention, ensuring that your site loads
+as fast as possible. Optimized media files are one of the key components for a
+high and consistent ranking in search engines.
+
+Additionally, the plugin can be combined with other built-in plugins
+that Material for MkDocs offers, in order to create sophisticated
+build pipelines tailored to your project:
+
+<div class="grid cards" markdown>
+
+- :material-shield-account: __[Built-in privacy plugin][privacy]__
+
+ ---
+
+ The privacy plugin makes it easy to use unoptimized external assets, passing
+ them to the optimize plugin before copying them to the [`site` directory]
+ [mkdocs.site_dir].
+
+ ---
+
+ __External media files can be automatically downloaded and optimized__
+
+- :material-connection: __[Built-in offline plugin][offline]__
+
+ ---
+
+ The offline plugin adds support for building offline-capable documentation,
+ so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
+ file that can be downloaded.
+
+ ---
+
+ __Your documentation can be distributed as a smaller `.zip` download__
+
+</div>
+
+ [privacy]: privacy.md
+ [offline]: offline.md
+
+## Configuration
+
+<!-- md:version 9.7.0 -->
+<!-- md:plugin [optimize] – built-in -->
+<!-- md:flag multiple -->
+<!-- md:flag experimental -->
+
+As with all [built-in plugins], getting started with the optimize plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and observe how
+media files are optimized automatically:
+
+``` yaml
+plugins:
+ - optimize
+```
+
+The optimize plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+However, in order to optimize all media files, it's necessary to install the
+dependencies for [image processing], if they're not already available on your
+system. The linked guide includes instructions for several operating systems
+and mentions some alternative environments.
+
+ [optimize]: optimize.md
+ [built-in plugins]: index.md
+ [image processing]: requirements/image-processing.md
+
+### General
+
+The following settings are available:
+
+---
+
+#### <!-- md:setting config.enabled -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable the plugin when [building your project].
+If you want to disable the plugin, e.g., for local builds, you can use an
+[environment variable][mkdocs.env] in `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - optimize:
+ enabled: !ENV [CI, false]
+```
+
+This configuration enables the plugin only during continuous integration (CI).
+
+---
+
+#### <!-- md:setting config.concurrency -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default available CPUs - 1 -->
+
+With more CPUs available, the plugin can do more work in parallel, and thus
+complete media file optimization faster. If you want to disable concurrent
+processing completely, use:
+
+``` yaml
+plugins:
+ - optimize:
+ concurrency: 1
+```
+
+By default, the plugin uses all available CPUs - 1 with a minimum of 1.
+
+### Caching
+
+The plugin implements an [intelligent caching] mechanism, ensuring that a media
+file or asset is only passed through the optimization pipeline when its contents
+change. If you swap out or update an image, the plugin detects it and updates
+the optimized version of the media file.
+
+The following settings are available for caching:
+
+ [intelligent caching]: requirements/caching.md
+
+---
+
+#### <!-- md:setting config.cache -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to instruct the plugin to bypass the cache, in order to
+re-optimize all media files, even though the cache may not be stale. It's
+normally not necessary to specify this setting, except for when debugging
+the plugin itself. Caching can be disabled with:
+
+``` yaml
+plugins:
+ - optimize:
+ cache: false
+```
+
+---
+
+#### <!-- md:setting config.cache_dir -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `.cache/plugin/optimize` -->
+
+It is normally not necessary to specify this setting, except for when you want
+to change the path within your root directory where media files are cached.
+If you want to change it, use:
+
+``` yaml
+plugins:
+ - optimize:
+ cache_dir: my/custom/dir
+```
+
+If you're using [multiple instances] of the plugin, it can be a good idea to
+set different cache directories for both instances, so that they don't interfere
+with each other.
+
+ [multiple instances]: index.md#multiple-instances
+
+### Optimization
+
+Documentation often makes use of screenshots or diagrams for better
+visualization of things, both of which are prime candidates for optimization.
+The plugin automatically optimizes images using [pngquant] for `.png` files,
+and [Pillow] for `.jpg` files.
+
+The following settings are available for optimization:
+
+ [pngquant]: https://pngquant.org/
+ [Pillow]: https://pillow.readthedocs.io/
+
+---
+
+#### <!-- md:setting config.optimize -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable media file optimization. Currently,
+the plugin's sole purpose is to optimize media files, so it's equivalent to the
+[`enabled`][config.enabled] setting, but in the near future, other features
+might be added. If you want to disable optimization, use:
+
+``` yaml
+plugins:
+ - optimize:
+ optimize: false
+```
+
+---
+
+#### <!-- md:setting config.optimize_png -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable the optimization of `.png` files. It's
+normally not necessary to specify this setting, but if you want to disable
+the optimization of `.png` files, use:
+
+``` yaml
+plugins:
+ - optimize:
+ optimize_png: false
+```
+
+---
+
+#### <!-- md:setting config.optimize_png_speed -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `3` of `1-10` -->
+
+Use this setting to specify the speed/quality tradeoff that [pngquant] applies
+when optimizing `.png` files. The lower the number, the more aggressively
+[pngquant] will try to optimize:
+
+=== "Slower <small>smaller</small>"
+
+ ``` yaml
+ plugins:
+ - optimize:
+ optimize_png_speed: 1
+ ```
+
+=== "Faster <small>larger</small>"
+
+ ``` yaml
+ plugins:
+ - optimize:
+ optimize_png_speed: 10
+ ```
+
+A factor of `10` has 5% lower quality, but is 8x faster than the default `3`.
+
+---
+
+#### <!-- md:setting config.optimize_png_strip -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to specify whether [pngquant] should strip optional metadata
+from `.png` files that are not required to display the image, e.g., [EXIF].
+If you want to preserve metadata, use:
+
+``` yaml
+plugins:
+ - optimize:
+ optimize_png_strip: false
+```
+
+ [EXIF]: https://en.wikipedia.org/wiki/Exif
+
+---
+
+#### <!-- md:setting config.optimize_jpg -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable the optimization of `.jpg` files. It's
+normally not necessary to specify this setting, but if you want to disable
+the optimization of `.jpg` files, use:
+
+``` yaml
+plugins:
+ - optimize:
+ optimize_jpg: false
+```
+
+---
+
+#### <!-- md:setting config.optimize_jpg_quality -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `60` of `0-100` -->
+
+Use this setting to specify the image quality that [Pillow] applies when
+optimizing `.jpg` files. If the images look blurry, it's a good idea to
+fine-tune and change this setting:
+
+``` yaml
+plugins:
+ - optimize:
+ optimize_jpg_quality: 75
+```
+
+---
+
+#### <!-- md:setting config.optimize_jpg_progressive -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to specify whether [Pillow] should use progressive encoding
+when optimizing `.jpg` files, rendering faster on slow connections. If you want
+to disable progressive encoding, use:
+
+``` yaml
+plugins:
+ - optimize:
+ optimize_jpg_progressive: false
+```
+
+ [progressive encoding]: https://medium.com/hd-pro/jpeg-formats-progressive-vs-baseline-73b3938c2339
+
+---
+
+#### <!-- md:setting config.optimize_include -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default none -->
+
+Use this setting to enable media file optimization for specific directories
+of your project, e.g., when using [multiple instances] of the plugin to optimize
+media files differently:
+
+``` yaml
+plugins:
+ - optimize:
+ optimize_include:
+ - screenshots/*
+```
+
+This configuration enables optimization for all media files that are contained
+in the `screenshots` folder and its subfolders inside the [`docs` directory]
+[mkdocs.docs_dir].
+
+---
+
+#### <!-- md:setting config.optimize_exclude -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default none -->
+
+Use this setting to disable media file optimization for specific directories
+of your project, e.g., when using [multiple instances] of the plugin to optimize
+media files differently:
+
+``` yaml
+plugins:
+ - social:
+ optimize_exclude:
+ - vendor/*
+```
+
+This configuration disables optimization for all media files that are contained
+in the `vendor` folder and its subfolders inside the [`docs` directory]
+[mkdocs.docs_dir].
+
+### Reporting
+
+The following settings are available for reporting:
+
+---
+
+#### <!-- md:setting config.print_gain -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to control whether the plugin should print the number of bytes
+gained after optimizing each file. If you want to disable this behavior, use:
+
+``` yaml
+plugins:
+ - optimize:
+ print_gain: false
+```
+
+---
+
+#### <!-- md:setting config.print_gain_summary -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to control whether the plugin should print the total number of
+bytes gained after optimizing all files. If you want to disable this behavior,
+use:
+
+``` yaml
+plugins:
+ - optimize:
+ print_gain_summary: false
+```
diff --git a/documents/markdown/mkdocs-material/plugins_privacy.md b/documents/markdown/mkdocs-material/plugins_privacy.md
new file mode 100644
index 0000000..d68f3b9
--- /dev/null
+++ b/documents/markdown/mkdocs-material/plugins_privacy.md
@@ -0,0 +1,497 @@
+---
+title: Built-in privacy plugin
+icon: material/shield-account
+---
+
+
+# Built-in privacy plugin
+
+The privacy plugin offers a streamlined solution for automatically self-hosting
+external assets. With just a single line of configuration, the plugin can
+automatically identify and download external assets, making GDPR compliance
+as effortless as it can possibly be.
+
+## Objective
+
+### How it works
+
+The plugin scans the generated HTML for external assets, i.e., scripts, style
+sheets, images, and web fonts, downloads them, stores them in the
+[`site` directory][mkdocs.site_dir] and replaces all references with links to
+the downloaded copies for effortless self-hosting. For example:
+
+``` html
+<script src="https://example.com/script.js"></script>
+```
+
+This external script is downloaded, and the link is replaced with:
+
+``` html
+<script src="assets/external/example.com/script.js"></script>
+```
+
+Of course, scripts and style sheets can reference further external assets,
+which is why this process is repeated recursively until no further external
+assets are detected:
+
+- Scripts are scanned for further scripts, style sheets and JSON files
+- Style sheets are scanned for images and web fonts
+
+Additionally, hints like [`preconnect`][preconnect], used to reduce latency when
+requesting external assets, are removed from the output, as they're not
+necessary when self-hosting. After the plugin has done its work, your project
+will be free of requests to external services.
+
+There are some [limitations].
+
+ [preconnect]: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preconnect
+ [limitations]: #limitations
+
+### When to use it
+
+The plugin was developed to make compliance with the 2018 European
+__General Data Protection Regulation__ (GDPR) as simple as possible, while
+retaining the flexibility and power that Material for MkDocs offers, like for
+example its tight integration with [Google Fonts].
+
+But, that's only the start. For example, if your project includes a lot of
+images, enabling the plugin allows to move them outside of your repository, as
+the plugin will automatically download and store them in the [`site` directory]
+[mkdocs.site_dir] when [building your project].
+
+Even more interestingly, the plugin can be combined with other built-in plugins
+that Material for MkDocs offers, in order to create sophisticated build
+pipelines tailored to your project:
+
+<div class="grid cards" markdown>
+
+- :material-rabbit: __[Built-in optimize plugin][optimize]__
+
+ ---
+
+ The optimize plugin allows to optimize all downloaded external assets
+ detected by the privacy plugin by using compression and conversion
+ techniques.
+
+ ---
+
+ __External media files are automatically downloaded and optimized__
+
+- :material-connection: __[Built-in offline plugin][offline]__
+
+ ---
+
+ The offline plugin adds support for building [offline-capable documentation],
+ so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
+ file that can be downloaded.
+
+ ---
+
+ __Your documentation can work without connectivity to the internet__
+
+</div>
+
+ [Google Fonts]: ../setup/changing-the-fonts.md
+ [building your project]: ../creating-your-site.md#building-your-site
+ [optimize]: optimize.md
+ [offline]: offline.md
+ [offline-capable documentation]: ../setup/building-for-offline-usage.md
+
+## Configuration
+
+<!-- md:version 9.5.0 -->
+<!-- md:plugin [privacy] – built-in -->
+<!-- md:flag multiple -->
+<!-- md:flag experimental -->
+
+As with all [built-in plugins], getting started with the privacy plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and start
+effortlessly self-hosting external assets:
+
+``` yaml
+plugins:
+ - privacy
+```
+
+The privacy plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [privacy]: privacy.md
+ [built-in plugins]: index.md
+
+### General
+
+The following settings are available:
+
+---
+
+#### <!-- md:setting config.enabled -->
+
+<!-- md:version 9.5.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable the plugin when [building your project].
+If you want to disable the plugin, e.g., for local builds, you can use an
+[environment variable][mkdocs.env] in `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - privacy:
+ enabled: !ENV [CI, false]
+```
+
+This configuration enables the plugin only during continuous integration (CI).
+
+---
+
+#### <!-- md:setting config.concurrency -->
+
+<!-- md:version 9.5.0 -->
+<!-- md:default available CPUs - 1 -->
+
+With more CPUs available, the plugin can do more work in parallel, and thus
+complete handling of external assets faster. If you want to disable concurrent
+processing completely, use:
+
+``` yaml
+plugins:
+ - privacy:
+ concurrency: 1
+```
+
+By default, the plugin uses all available CPUs - 1 with a minimum of 1.
+
+### Caching
+
+The plugin implements an [intelligent caching] mechanism, ensuring that external
+assets are only downloaded when they're not already contained in the cache.
+While the initial build might take some time, it's a good idea to use caching,
+as it will speed up consecutive builds.
+
+The following settings are available for caching:
+
+ [intelligent caching]: requirements/caching.md
+
+---
+
+#### <!-- md:setting config.cache -->
+
+<!-- md:version 9.5.0 -->
+<!-- md:default `true` -->
+
+Use this setting to instruct the plugin to bypass the cache, in order to
+re-schedule downloads for all external assets, even though the cache may not be
+stale. It's normally not necessary to specify this setting, except for when
+debugging the plugin itself. Caching can be disabled with:
+
+``` yaml
+plugins:
+ - privacy:
+ cache: false
+```
+
+---
+
+#### <!-- md:setting config.cache_dir -->
+
+<!-- md:version 9.5.0 -->
+<!-- md:default `.cache/plugin/privacy` -->
+
+It is normally not necessary to specify this setting, except for when you want
+to change the path within your root directory where downloaded copies are
+cached. If you want to change it, use:
+
+``` yaml
+plugins:
+ - privacy:
+ cache_dir: my/custom/dir
+```
+
+If you're using [multiple instances] of the plugin, it can be a good idea to
+set different cache directories for both instances, so that they don't interfere
+with each other.
+
+ [multiple instances]: index.md#multiple-instances
+
+### Logging
+
+The following settings are available for logging:
+
+---
+
+#### <!-- md:setting config.log -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to control whether the plugin should display log messages when
+building your site. While not being recommended, you can disable logging with:
+
+``` yaml
+plugins:
+ - privacy:
+ log: false
+```
+
+---
+
+#### <!-- md:setting config.log_level -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `info` -->
+
+Use this setting to control the log level that the plugin should employ when
+encountering errors, which requires that the [`log`][config.log] setting is
+enabled. The following log levels are available:
+
+=== "`error`"
+
+ ``` yaml
+ plugins:
+ - privacy:
+ log_level: error
+ ```
+
+ Only errors are reported.
+
+=== "`warn`"
+
+ ``` yaml
+ plugins:
+ - privacy:
+ log_level: warn
+ ```
+
+ Errors and warnings are reported, terminating the build in
+ [`strict`][mkdocs.strict] mode. This includes warnings when symlinks cannot
+ be created due to a lack of permissions on Windows systems (#6550).
+
+=== "`info`"
+
+ ``` yaml
+ plugins:
+ - privacy:
+ log_level: info
+ ```
+
+ Errors, warnings and informational messages are reported, including which
+ assets were successfully downloaded by the plugin.
+
+=== "`debug`"
+
+ ``` yaml
+ plugins:
+ - privacy:
+ log_level: debug
+ ```
+
+ All messages are reported, including debug messages, if and only if MkDocs
+ was started with the `--verbose` flag. Note that this will print a lot of
+ messages and is only useful for debugging.
+
+### External assets
+
+The following settings are available for external assets:
+
+---
+
+#### <!-- md:setting config.assets -->
+
+<!-- md:version 9.5.0 -->
+<!-- md:default `true` -->
+
+Use this setting to control whether the plugin should download external
+assets. If you only want the plugin to process [external links], you can disable
+handling of external assets with:
+
+``` yaml
+plugins:
+ - privacy:
+ assets: false
+```
+
+ [external links]: #external-links
+
+---
+
+#### <!-- md:setting config.assets_fetch -->
+
+<!-- md:version 9.5.0 -->
+<!-- md:default `true` -->
+
+Use this setting to control whether the plugin should downloads or only report
+external assets when they're encountered. If you already self-host all external
+assets, this setting can be used as a safety net to detect links to external
+assets placed by the author in pages:
+
+``` yaml
+plugins:
+ - privacy:
+ assets_fetch: true
+```
+
+---
+
+#### <!-- md:setting config.assets_fetch_dir -->
+
+<!-- md:version 9.5.0 -->
+<!-- md:default `assets/external` -->
+
+It is normally not necessary to specify this setting, except for when you want
+to change the path within the [`site` directory][mkdocs.site_dir] where
+external assets are stored. If you want to change it, use:
+
+``` yaml
+plugins:
+ - privacy:
+ assets_fetch_dir: my/custom/dir
+```
+
+This configuration stores the downloaded copies at `my/custom/dir` in the
+[`site` directory][mkdocs.site_dir].
+
+---
+
+#### <!-- md:setting config.assets_include -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default none -->
+
+Use this setting to enable downloading of external assets for specific origins,
+e.g., when using [multiple instances] of the plugin to fine-tune processing of
+external assets for different origins:
+
+``` yaml
+plugins:
+ - privacy:
+ assets_include:
+ - unsplash.com/*
+```
+
+---
+
+#### <!-- md:setting config.assets_exclude -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default none -->
+
+Use this setting to disable downloading of external assets for specific origins,
+e.g., when using [multiple instances] of the plugin to fine-tune processing of
+external assets for different origins:
+
+``` yaml
+plugins:
+ - privacy:
+ assets_exclude: # (1)!
+ - unpkg.com/mathjax@3/*
+ - giscus.app/*
+```
+
+1. [MathJax] loads web fonts for typesetting of mathematical content
+ through relative URLs, and thus cannot be automatically bundled by the
+ privacy plugin. [MathJax can be self-hosted].
+
+ [Giscus], which we recommend to use as a [comment system], uses a technique
+ called code-splitting to load only the code that is necessary, which
+ is implemented via relative URLs. [Giscus can be self-hosted] as well.
+
+ [MathJax]: ../reference/math.md
+ [MathJax can be self-hosted]: https://docs.mathjax.org/en/latest/web/hosting.html
+ [Giscus]: https://giscus.app/
+ [comment system]: ../setup/adding-a-comment-system.md
+ [Giscus can be self-hosted]: https://github.com/giscus/giscus/blob/main/SELF-HOSTING.md
+
+---
+
+### External links
+
+The following settings are available for external links:
+
+---
+
+#### <!-- md:setting config.links -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to instruct the plugin to parse and process external links to
+annotate them for [improved security], or to automatically add additional
+attributes to external links. If you want to disable processing of external
+links, use:
+
+``` yaml
+plugins:
+ - privacy:
+ links: false
+```
+
+ [improved security]: https://developer.chrome.com/en/docs/lighthouse/best-practices/external-anchors-use-rel-noopener/
+
+---
+
+#### <!-- md:setting config.links_attr_map -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default none -->
+
+Use this setting to specify additional attributes that should be added to
+external links, for example, to add `target="_blank"` to all external links
+so they open in a new tab:
+
+``` yaml
+plugins:
+ - privacy:
+ links_attr_map:
+ target: _blank
+```
+
+---
+
+#### <!-- md:setting config.links_noopener -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+It is normally not recommended to change this setting, as it will automatically
+annotate external links that open in a new window with `rel="noopener"` for
+[improved security]:
+
+``` yaml
+plugins:
+ - privacy:
+ links_noopener: true
+```
+
+## Limitations
+
+### Dynamic URLs
+
+Dynamically created URLs as part of scripts are not detected, and thus cannot be
+downloaded automatically, as the plugin does not execute scripts – it only detects fully qualified URLs for downloading and replacement. In short, don't do this:
+
+``` js
+const host = "https://example.com"
+const path = `${host}/script.js`
+```
+
+Instead, always use fully qualified URLs:
+
+``` js
+const url ="https://example.com/script.js"
+```
+
+### Embedded HTML
+
+By default, embedded HTML files (e.g. in iframes) are not scanned for external
+assets. This is a limitation of MkDocs, as it considers `.html` files to be
+templates, which must be explicitly listed under
+[`extra_templates`][mkdocs.extra_templates]. Thus, to self-host external assets
+of an embedded HTML file:
+
+``` yaml
+extra_templates:
+ - iframe.html
+```
+
+Note that the path to `iframe.html` is relative to the
+[`docs_dir`][mkdocs.docs_dir] directory.
diff --git a/documents/markdown/mkdocs-material/plugins_projects.md b/documents/markdown/mkdocs-material/plugins_projects.md
new file mode 100644
index 0000000..5a36247
--- /dev/null
+++ b/documents/markdown/mkdocs-material/plugins_projects.md
@@ -0,0 +1,444 @@
+---
+title: Built-in projects plugin
+icon: material/folder-open
+status: deprecated
+---
+
+# Built-in projects plugin
+
+The projects plugin adds the ability to split your main project into multiple
+distinct projects, build them concurrently and preview them together as one.
+This is particularly useful when creating a multi-language project, but can also
+be used to split very large projects into smaller parts.
+
+!!! bug "The built-in projects plugin is deprecated"
+
+ [Material for MkDocs is in maintenance mode]. The projects plugin, which was
+ formely part of the [Insiders] edition, was released in <!-- md:version 9.7.0 -->, the last release that includes all features from the Insiders edition.
+ Unfortunately, the projects plugin turned out impossible to maintain, and
+ was one of the key motivators to create [Zensical].
+
+ ---
+
+ __If you're considering the projects plugin, please be aware that known issues will <u>not</u> be fixed.__
+
+ [Material for MkDocs is in maintenance mode]: https://github.com/squidfunk/mkdocs-material/issues/8523
+ [Zensical]: ../blog/posts/zensical.md
+ [Insiders]: ../insiders/index.md
+
+## Objective
+
+### How it works
+
+The plugin scans the configured [`projects` directory][config.projects_dir] for
+`mkdocs.yml` files, identifies all nested projects and builds them concurrently.
+If not configured otherwise, the plugin expects that your project has
+the following directory layout, e.g. for a multi-language project:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+├─ projects/
+│ ├─ en/
+│ │ ├─ docs/
+│ │ └─ mkdocs.yml
+│ └─ de/
+│ ├─ docs/
+│ └─ mkdocs.yml
+└─ mkdocs.yml
+```
+
+One of the most useful and interesting features of the plugin is that it allows
+[previewing your site] from the main project, while still being able to preview
+and build each project individually. This is especially useful for
+multi-language projects.
+
+If, when [previewing your site], you change a file in one of the projects, the
+plugin only rebuilds this project and makes sure that MkDocs will also reload
+the associated files. This also creates the opportunity for splitting your
+main project into several projects for a better editing experience.
+
+There are some [limitations], but we're working hard to remove them.
+
+ [previewing your site]: ../creating-your-site.md#previewing-as-you-write
+ [limitations]: #limitations
+
+### When to use it
+
+The plugin came into existence because we needed a convenient and scalable
+method to build our [examples] repository, which features many self-contained
+and runnable projects that users can download and use as a basis when
+bootstrapping a new project or [creating a reproduction].
+
+When you want to create a multi-language project, or have a very large existing
+project, you might consider using the plugin, as it makes managing, editing
+and building more comfortable.
+
+ [examples]: https://github.com/mkdocs-material/examples
+ [creating a reproduction]: ../guides/creating-a-reproduction.md
+
+## Configuration
+
+<!-- md:version 9.7.0 -->
+<!-- md:plugin [projects] – built-in -->
+<!-- md:flag experimental -->
+
+In order to get started with the projects plugin, just add the following lines
+to `mkdocs.yml`, and split your main project into several distinct projects that
+can be built concurrently:
+
+``` yaml
+plugins:
+ - projects
+```
+
+The projects plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [projects]: projects.md
+
+### General
+
+The following settings are available:
+
+---
+
+#### <!-- md:setting config.enabled -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable the plugin when [building your project].
+If you want to disable the plugin, e.g., for local builds, you can use an
+[environment variable][mkdocs.env] in `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - projects:
+ enabled: !ENV [CI, false]
+```
+
+This configuration enables the plugin only during continuous integration (CI).
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+---
+
+#### <!-- md:setting config.concurrency -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default available CPUs - 1 -->
+
+With more CPUs available, the plugin can do more work in parallel, and thus
+build projects faster. If you want to disable concurrent processing completely,
+use:
+
+``` yaml
+plugins:
+ - projects:
+ concurrency: 1
+```
+
+By default, the plugin uses all available CPUs - 1 with a minimum of 1.
+
+### Caching
+
+The plugin implements an [intelligent caching] mechanism, ensuring that a
+project is only rebuilt when its contents change. While the initial build might
+take some time, it's a good idea to use caching, as it will speed up consecutive
+builds.
+
+The following settings are available for caching:
+
+ [intelligent caching]: requirements/caching.md
+
+---
+
+#### <!-- md:setting config.cache -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to instruct the plugin to bypass the cache, in order to
+rebuild all projects, even though the cache may not be stale. It's normally not
+necessary to specify this setting, except for when debugging the plugin itself.
+Caching can be disabled with:
+
+``` yaml
+plugins:
+ - projects:
+ cache: false
+```
+
+---
+
+#### <!-- md:setting config.cache_dir -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `.cache/plugin/projects` -->
+
+It is normally not necessary to specify this setting, except for when you want
+to change the path within your root directory where the metadata is cached.
+If you want to change it, use:
+
+``` yaml
+plugins:
+ - projects:
+ cache_dir: my/custom/dir
+```
+
+### Logging
+
+The following settings are available for logging:
+
+---
+
+#### <!-- md:setting config.log -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to control whether the plugin should display log messages from
+projects when building your site. While not being recommended, you can disable
+logging with:
+
+``` yaml
+plugins:
+ - projects:
+ log: false
+```
+
+---
+
+#### <!-- md:setting config.log_level -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `info` -->
+
+Use this setting to control the log level that the plugin should employ when
+encountering errors, which requires that the [`log`][config.log] setting is
+enabled. The following log levels are available:
+
+=== "`error`"
+
+ ``` yaml
+ plugins:
+ - projects:
+ log_level: error
+ ```
+
+ Only errors are reported.
+
+=== "`warn`"
+
+ ``` yaml
+ plugins:
+ - projects:
+ log_level: warn
+ ```
+
+ Errors and warnings are reported, terminating the build in
+ [`strict`][mkdocs.strict] mode.
+
+=== "`info`"
+
+ ``` yaml
+ plugins:
+ - projects:
+ log_level: info
+ ```
+
+ Errors, warnings and informational messages are reported.
+
+=== "`debug`"
+
+ ``` yaml
+ plugins:
+ - projects:
+ log_level: debug
+ ```
+
+ All messages are reported, including debug messages.
+
+### Projects
+
+The following settings are available for projects:
+
+---
+
+#### <!-- md:setting config.projects -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable building of projects. Currently, the
+plugin's sole purpose is to build projects, so it's equivalent to the
+[`enabled`][config.enabled] setting, but in the future, other features might be
+added. If you want to disable building of projects, use:
+
+``` yaml
+plugins:
+ - projects:
+ projects: false
+```
+
+---
+
+#### <!-- md:setting config.projects_dir -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `projects` -->
+
+Use this setting to change the folder where your projects are located. It's
+normally not necessary to change this setting, but if you want to rename the
+folder or change its file system location, use:
+
+``` yaml
+plugins:
+ - projects:
+ projects_dir: projects
+```
+
+Note that the [`projects` directory][config.projects_dir] is solely used for
+project organization – it is not included in project URLs, since projects are
+automatically hoisted by the plugin.
+
+The provided path is resolved from the root directory.
+
+---
+
+#### <!-- md:setting config.projects_config_files -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `*/mkdocs.yml` -->
+
+Use this setting to change the location or name of configuration files the
+plugin will look for when scanning the [`projects` directory]
+[config.projects_dir]. Adjusting this setting can be necessary when the
+configuration files are located in subdirectories of projects, e.g.
+`docs/mkdocs.yml`:
+
+``` yaml
+plugins:
+ - projects:
+ projects_config_files: "**/mkdocs.yml" # (1)!
+```
+
+1. If all projects share the same location for their configuration files, e.g.,
+ `docs/mkdocs.yml`, it's advisable to fully qualify the path, as it's faster
+ to resolve than a `**` glob pattern.
+
+ ``` yaml
+ plugins:
+ - projects:
+ projects_config_files: "*/docs/mkdocs.yml"
+ ```
+
+ This configuration fits the following directory structure, which is quite
+ common for projects using git submodules:
+
+ ``` { .sh .no-copy }
+ .
+ ├─ docs/
+ ├─ projects/
+ │ ├─ git-submodule-a/
+ │ │ └─ docs/
+ │ │ └─ mkdocs.yml
+ │ └─ git-submodule-b/
+ │ └─ docs/
+ │ └─ mkdocs.yml
+ └─ mkdocs.yml
+ ```
+
+The provided path is resolved from the [`projects` directory]
+[config.projects_dir].
+
+---
+
+#### <!-- md:setting config.projects_config_transform -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default none -->
+
+Use this setting to transform the configuration of each project as read from
+`mkdocs.yml` before it is built, which allows for adjusting the configuration
+of each project when building them together, but leave them untouched when
+building them individually:
+
+``` yaml
+plugins:
+ - projects:
+ projects_config_transform: !!python/name:projects.transform
+```
+
+The provided module and function name are looked up in Python's [module search
+path]. You need to add your root directory to the search path when building
+your site, so Python can resolve it. The easiest way is to add the working
+directory to the [`PYTHONPATH`][PYTHONPATH] environment variable:
+
+``` .sh
+export PYTHONPATH=.
+```
+
+!!! tip "How to define a configuration transformation function"
+
+ The [`python/name`][python-name] tag is provided by [PyYAML] and must point
+ to a valid module and function name within Python's [module search path].
+ The plugin passes the `project` and top-level `config` objects to the
+ function.
+
+ As an example, we can inherit the [`use_directory_urls`]
+ [mkdocs.use_directory_urls] setting for all projects from the top-level
+ configuration:
+
+ ``` py title="projects/__init__.py"
+ from mkdocs.config.defaults import MkDocsConfig
+
+ # Transform project configuration
+ def transform(project: MkDocsConfig, config: MkDocsConfig):
+ project.use_directory_urls = config.use_directory_urls
+ ```
+
+ [module search path]: https://docs.python.org/3/library/sys_path_init.html
+ [PYTHONPATH]: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH
+ [python-name]: https://pyyaml.org/wiki/PyYAMLDocumentation#yaml-tags-and-python-types
+ [PyYAML]: https://pyyaml.org/
+
+### Hoisting
+
+The following settings are available for hoisting:
+
+---
+
+#### <!-- md:setting config.hoisting -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable hoisting of themes files to the main
+project. If you disable this setting, each project receives a copy of the
+theme's files, which can be considered redundant:
+
+``` yaml
+plugins:
+ - projects:
+ hoisting: false
+```
+
+It's generally advisable to enable hoisting, as it yields faster deployments
+and faster loading of your project's sites, because the files are the same for
+all projects and can be deduplicated.
+
+### Limitations
+
+The plugin is one of the latest additions to Material for MkDocs, which means it
+is rather young and has some limitations. We're working hard to remove them, and
+we're happy to receive feedback and learn about your requirements in ?5800.
+Current limitations are:
+
+- __Basic multi-language support only__: we'll be investigating how to provide
+ better support for multi-language projects, allowing to easier interlink
+ projects and switch between them.
+
+- __Separate search indexes and sitemaps__: currently, the projects are entirely
+ separate, which means they will have separate search indexes and sitemaps.
diff --git a/documents/markdown/mkdocs-material/plugins_requirements_caching.md b/documents/markdown/mkdocs-material/plugins_requirements_caching.md
new file mode 100644
index 0000000..63b3f4a
--- /dev/null
+++ b/documents/markdown/mkdocs-material/plugins_requirements_caching.md
@@ -0,0 +1,35 @@
+---
+icon: material/database-outline
+---
+
+# Caching
+
+Some of the [built-in plugins] implement intelligent caching mechanisms, which
+massively speed up consecutive builds by reducing the amount of work that needs
+to be done. This guide explains how to configure caching in different
+environments.
+
+## Prerequisites
+
+Caching is entirely optional but enabled by default. It can be disabled per
+plugin. If not configured otherwise, plugins will cache their data in the
+`.cache` folder in the root of your project. For this reason it's recommended
+to create a `.gitignore` file in the root of your project:
+
+``` title=".gitignore"
+.cache
+```
+
+This ensures that cached files are not added to your git repository – something
+that is generally not recommended to do unless absolutely necessary. In some
+cases, you might need to check in cached files, e.g. when you need to
+pre-generate [social cards] locally, e.g., when you're not be able to install
+the image processing dependencies in your continuous integration (CI)
+environment.
+
+In this case, we recommend changing the `cache_dir` setting – something that all
+plugins that implement caching share – to a folder which you add to your git
+repository.
+
+ [built-in plugins]: ../index.md
+ [social cards]: ../../setup/setting-up-social-cards.md
diff --git a/documents/markdown/mkdocs-material/plugins_requirements_image-processing.md b/documents/markdown/mkdocs-material/plugins_requirements_image-processing.md
new file mode 100644
index 0000000..c309315
--- /dev/null
+++ b/documents/markdown/mkdocs-material/plugins_requirements_image-processing.md
@@ -0,0 +1,272 @@
+---
+icon: material/image-sync-outline
+---
+
+# Image processing
+
+Some of the [built-in plugins] depend on external libraries for efficient image
+processing, most notably the [social] plugin to generate [social cards], and the
+[optimize] plugin for applying [image optimization]. This guide explains how to
+install those libraries in different environments.
+
+ [built-in plugins]: ../index.md
+ [social]: ../social.md
+ [social cards]: ../../setup/setting-up-social-cards.md
+ [optimize]: ../optimize.md
+ [image optimization]: ../../setup/building-an-optimized-site.md
+
+## Dependencies
+
+The libraries for image processing are entirely optional, and only need to be
+installed if you want to use the [social] plugin or the [optimize] plugin. The
+libraries are listed under the `imaging` extra:
+
+```
+pip install "mkdocs-material[imaging]"
+```
+
+This will install compatible versions of the following packages:
+
+- [Pillow]
+- [CairoSVG]
+
+ [Pillow]: https://pillow.readthedocs.io/
+ [CairoSVG]: https://cairosvg.org/
+
+### Cairo Graphics
+
+[Cairo Graphics] is a graphics library and dependency of [Pillow], which
+Material for MkDocs makes use of for generating [social cards] and performing
+[image optimization]. See the following section which explains how to install
+[Cairo Graphics] and its dependencies on your system:
+
+=== ":material-apple: macOS"
+
+ Make sure [Homebrew] is installed, which is a modern package manager for
+ macOS. Next, use the following command to install all necessary
+ dependencies:
+
+ ```
+ brew install cairo freetype libffi libjpeg libpng zlib
+ ```
+
+=== ":fontawesome-brands-windows: Windows"
+
+ The easiest way to get up and running with the [Cairo Graphics] library is
+ by installing it via [MSYS2], which is a software distribution and building
+ platform for Windows. Run the following command inside of a MSYS2 shell:
+
+ ```
+ pacman -S mingw-w64-ucrt-x86_64-cairo
+ ```
+
+ MSYS2 provides the Cairo Graphics library in several different environments.
+ The above command uses the [UCRT64] environment, as recommended by the MSYS2
+ developers.
+
+=== ":material-linux: Linux"
+
+ There are several package managers for Linux with varying availability per
+ distribution. The [installation guide] explains how to install the [Cairo
+ Graphics] library for your distribution:
+
+ === ":material-ubuntu: Ubuntu"
+
+ ```
+ apt-get install libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev
+ ```
+
+ === ":material-fedora: Fedora"
+
+ ```
+ yum install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel
+ ```
+
+ === ":fontawesome-brands-suse: openSUSE"
+
+ ```
+ zypper install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel
+ ```
+
+The following environments come with a preinstalled version of [Cairo Graphics]:
+
+- [x] No installation needed in [Docker image]
+- [x] No installation needed in [GitHub Actions] (Ubuntu)
+
+ [Cairo Graphics]: https://www.cairographics.org/
+ [Homebrew]: https://brew.sh/
+ [installation guide]: https://www.cairographics.org/download/
+ [MSYS2]: https://www.msys2.org/
+ [UCRT64]: https://www.msys2.org/docs/environments/
+ [Docker image]: https://hub.docker.com/r/squidfunk/mkdocs-material/
+ [GitHub Actions]: ../../publishing-your-site.md#with-github-actions
+
+### pngquant
+
+[pngquant] is an excellent library for lossy PNG compression, and a direct
+dependency of the [built-in optimize plugin]. See the following section which
+explains how to install [pngquant] system:
+
+=== ":material-apple: macOS"
+
+ Make sure [Homebrew] is installed, which is a modern package manager for
+ macOS. Next, use the following command to install all necessary
+ dependencies:
+
+ ```
+ brew install pngquant
+ ```
+
+=== ":fontawesome-brands-windows: Windows"
+
+ The easiest way to get [pngquant] is by installing it via [MSYS2], which is
+ a software distribution and building platform for Windows. Run the following
+ command inside of a MSYS2 shell:
+
+ ```
+ pacman -S mingw-w64-ucrt-x86_64-pngquant
+ ```
+
+=== ":material-linux: Linux"
+
+ All popular Linux distributions, regardless of package manager, should
+ allow to install [pngquant] with the bundled package manager. For example,
+ on Ubuntu, [pngquant] can be installed with:
+
+ ```
+ apt-get install pngquant
+ ```
+
+ The same is true for `yum` and `zypper`.
+
+The following environments come with a preinstalled version of [pngquant]:
+
+- [x] No installation needed in [Docker image]
+
+ [pngquant]: https://pngquant.org/
+ [built-in optimize plugin]: ../../plugins/optimize.md
+ [pngquant-winbuild]: https://github.com/jibsen/pngquant-winbuild
+
+## Troubleshooting
+
+### Cairo library was not found
+
+After following the installation guide above it may happen that you still get
+the following error:
+
+```bash
+no library called "cairo-2" was found
+no library called "cairo" was found
+no library called "libcairo-2" was found
+cannot load library 'libcairo.so.2': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo.so.2'
+cannot load library 'libcairo.2.dylib': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo.2.dylib'
+cannot load library 'libcairo-2.dll': error 0x7e. Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo-2.dll'
+```
+
+This means that the [`cairosvg`][PyPi CairoSVG] package was installed, but the
+underlying [`cairocffi`][PyPi CairoCFFI] dependency couldn't [find][cffi-dopen]
+the installed library. Depending on the operating system the library lookup
+process is different:
+
+!!! tip
+ Before proceeding remember to fully restart any open Terminal windows, and
+ their parent hosts like IDEs to reload any environmental variables, which
+ were altered during the installation process. This might be the quick fix.
+
+=== ":material-apple: macOS"
+
+ On macOS the library lookup checks inside paths defined in [dyld][osx-dyld].
+ Additionally each library `name` is checked in [three variants][find-library-macOS]
+ with the `libname.dylib`, `name.dylib` and `name.framework/name` format.
+
+ [Homebrew] should set every needed variable to point at the installed
+ library directory, but if that didn't happen, you can use the debug script
+ below to see what paths are looked up.
+
+ A [known workaround][cffi-issue] is to add the Homebrew lib path directly
+ before running MkDocs:
+
+ ```bash
+ export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib
+ ```
+
+ View source code of [cairo-lookup-macos.py]
+
+ ```bash title="Python Debug macOS Script"
+ curl "https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-macos.py" | python -
+ ```
+
+=== ":fontawesome-brands-windows: Windows"
+
+ On Windows the library lookup checks inside the paths defined in the
+ environmental `PATH` variable. Additionally each library `name` is checked
+ in [two variants][find-library-Windows] with the `name` and `name.dll` format.
+
+ The default binary and shared library path for the [UCRT64] environment of
+ [MSYS2], in which the packages were installed using the above commands, is:
+
+ ```powershell
+ C:\msys64\ucrt64\bin
+ ```
+
+ Use the debug script below to check if the path is included. If it isn't then:
+
+ 1. Press ++windows+r++.
+ 2. Run the `SystemPropertiesAdvanced` applet.
+ 3. Select "Environmental Variables" at the bottom.
+ 4. Add the whole path to the above directory to your `Path` variable.
+ 5. Click OK on all open windows to apply changes.
+ 6. Fully restart any open Terminal windows and their parent hosts like IDEs.
+
+ ```powershell title="You can also list paths using PowerShell"
+ $env:Path -split ';'
+ ```
+
+ View source code of [cairo-lookup-windows.py]
+
+ ```powershell title="PowerShell - Python Debug Windows Script"
+ (Invoke-WebRequest "https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-windows.py").Content | python -
+ ```
+
+=== ":material-linux: Linux"
+
+ On Linux the library lookup can [differ greatly][find-library-Linux] and is
+ dependent from the installed distribution. For tested Ubuntu and Manjaro
+ systems Python runs shell commands to check which libraries are available in
+ [`ldconfig`][ubuntu-ldconfig], in the [`gcc`][ubuntu-gcc]/`cc` compiler, and
+ in [`ld`][ubuntu-ld].
+
+ You can extend the `LD_LIBRARY_PATH` environmental variable with an absolute
+ path to a library directory containing `libcairo.so` etc. Run this directly
+ before MkDocs:
+
+ ```bash
+ export LD_LIBRARY_PATH=/absolute/path/to/lib:$LD_LIBRARY_PATH
+ ```
+
+ You can also modify the `/etc/ld.so.conf` file.
+
+ The Python script below shows, which function is being run to find installed
+ libraries. You can check the source to find out what specific commands are
+ executed on your system during library lookup.
+
+ View source code of [cairo-lookup-linux.py]
+
+ ```bash title="Python Debug Linux Script"
+ curl "https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-linux.py" | python -
+ ```
+
+ [PyPi CairoSVG]: https://pypi.org/project/CairoSVG
+ [PyPi CairoCFFI]: https://pypi.org/project/CairoCFFI
+ [osx-dyld]: https://www.unix.com/man-page/osx/1/dyld/
+ [ubuntu-ldconfig]: https://manpages.ubuntu.com/manpages/focal/en/man8/ldconfig.8.html
+ [ubuntu-ld]: https://manpages.ubuntu.com/manpages/xenial/man1/ld.1.html
+ [ubuntu-gcc]: https://manpages.ubuntu.com/manpages/trusty/man1/gcc.1.html
+ [cffi-issue]: https://github.com/squidfunk/mkdocs-material/issues/5121
+ [cffi-dopen]: https://github.com/Kozea/cairocffi/blob/f1984d644bbc462ef0ec33b97782cf05733d7b53/cairocffi/__init__.py#L24-L49
+ [find-library-macOS]: https://github.com/python/cpython/blob/4d58a1d8fb27048c11bcbda3da1bebf78f979335/Lib/ctypes/util.py#L70-L81
+ [find-library-Windows]: https://github.com/python/cpython/blob/4d58a1d8fb27048c11bcbda3da1bebf78f979335/Lib/ctypes/util.py#L59-L67
+ [find-library-Linux]: https://github.com/python/cpython/blob/4d58a1d8fb27048c11bcbda3da1bebf78f979335/Lib/ctypes/util.py#L92
+ [cairo-lookup-macos.py]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-macos.py
+ [cairo-lookup-windows.py]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-windows.py
+ [cairo-lookup-linux.py]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/includes/debug/cairo-lookup-linux.py
diff --git a/documents/markdown/mkdocs-material/plugins_search.md b/documents/markdown/mkdocs-material/plugins_search.md
new file mode 100644
index 0000000..603501c
--- /dev/null
+++ b/documents/markdown/mkdocs-material/plugins_search.md
@@ -0,0 +1,427 @@
+---
+title: Built-in search plugin
+icon: material/magnify
+---
+
+# Built-in search plugin
+
+The search plugin adds a search bar to the header, allowing users to search your
+documentation. It's powered by [lunr.js], a lightweight full-text search engine
+for the browser, elimininating the need for external services, and even works
+when building [offline-capable documentation].
+
+ [lunr.js]: https://lunrjs.com/
+ [offline-capable documentation]: ../setup/building-for-offline-usage.md
+
+## Objective
+
+### How it works
+
+The plugin scans the generated HTML and builds a search index from all pages and
+sections by extracting the section titles and contents. It preserves some inline
+formatting like code blocks and lists, but removes all other formatting, so the
+search index is as small as possible.
+
+When a user visits your site, the search index is shipped to the browser,
+indexed with [lunr.js] and made available for fast and simple querying – no
+server needed. This ensures that the search index is always up to date with
+your documentation, yielding accurate results.
+
+### When to use it
+
+It's generally recommended to use the plugin, as interactive search functionality
+is a vital part of every good documentation. Additionally, the plugin integrates
+perfectly with several of the other [built-in plugins] that Material for MkDocs
+offers:
+
+<div class="grid cards" markdown>
+
+- :material-connection: __[Built-in offline plugin][offline]__
+
+ ---
+
+ The offline plugin adds support for building offline-capable documentation,
+ so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
+ file that can be downloaded.
+
+ ---
+
+ __Your documentation can work without connectivity to the internet__
+
+- :material-file-tree: __[Built-in meta plugin][meta]__
+
+ ---
+
+ The meta plugin makes it easy to [boost][meta.search.boost] specific
+ sections in search results or to [exclude][meta.search.exclude] them
+ entirely from being indexed, giving more granular control over search.
+
+ ---
+
+ __Simpler organization and management of search in different subsections__
+
+</div>
+
+ [offline]: offline.md
+ [meta]: meta.md
+ [built-in plugins]: index.md
+
+## Configuration
+
+<!-- md:version 9.0.0 -->
+<!-- md:plugin [search] – built-in -->
+
+As with all [built-in plugins], getting started with the search plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and your users
+will be able to search your documentation:
+
+``` yaml
+plugins:
+ - search
+```
+
+The search plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [search]: search.md
+ [built-in plugins]: index.md
+
+### General
+
+The following settings are available:
+
+---
+
+#### <!-- md:setting config.enabled -->
+
+<!-- md:version 9.3.2 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable the plugin when [building your project].
+It's normally not necessary to specify this setting, but if you want to disable
+the plugin, use:
+
+``` yaml
+plugins:
+ - search:
+ enabled: false
+```
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+### Search
+
+The following settings are available for search:
+
+---
+
+#### <!-- md:setting config.lang -->
+
+<!-- md:version 9.0.0 -->
+<!-- md:default computed -->
+
+Use this setting to specify the language of the search index, enabling [stemming]
+support for other languages than English. The default value is automatically
+computed from the [site language], but can be explicitly set to another language
+or even multiple languages with:
+
+=== "Set language"
+
+ ``` yaml
+ plugins:
+ - search:
+ lang: en
+ ```
+
+=== "Add further languages"
+
+ ``` yaml
+ plugins:
+ - search:
+ lang: # (1)!
+ - en
+ - de
+ ```
+
+ 1. Be aware that including support for further languages increases the
+ base JavaScript payload by around 20kb and by another 15-30kb per
+ language, all before `gzip`.
+
+ [stemming]: https://en.wikipedia.org/wiki/Stemming
+ [site language]: ../setup/changing-the-language.md#site-language
+ [lunr languages]: https://github.com/MihaiValentin/lunr-languages
+
+Language support is provided by [lunr languages], a collection of
+language-specific stemmers and stop words for [lunr.js] maintained by the
+Open Source community.
+
+---
+
+The following languages are currently supported by [lunr languages]:
+
+<div class="mdx-columns" markdown>
+
+- `ar` – Arabic
+- `da` – Danish
+- `de` – German
+- `du` – Dutch
+- `en` – English
+- `es` – Spanish
+- `fi` – Finnish
+- `fr` – French
+- `hi` – Hindi
+- `hu` – Hungarian
+- `hy` – Armenian
+- `it` – Italian
+- `ja` – Japanese
+- `kn` - Kannada
+- `ko` – Korean
+- `no` – Norwegian
+- `pt` – Portuguese
+- `ro` – Romanian
+- `ru` – Russian
+- `sa` – Sanskrit
+- `sv` – Swedish
+- `ta` – Tamil
+- `te` – Telugu
+- `th` – Thai
+- `tr` – Turkish
+- `vi` – Vietnamese
+- `zh` – Chinese
+
+</div>
+
+If [lunr languages] doesn't provide support for the selected [site language],
+the plugin falls back to another language that yields the best stemming results.
+If you discover that the search results are not satisfactory, you can contribute
+to [lunr languages] by adding support for your language.
+
+---
+
+#### <!-- md:setting config.separator -->
+
+<!-- md:version 9.0.0 -->
+<!-- md:default computed -->
+
+Use this setting to specify the separator used to split words when building the
+search index on the client side. The default value is automatically computed
+from the [site language], but can also be explicitly set to another value with:
+
+``` yaml
+plugins:
+ - search:
+ separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
+```
+
+Separators support [positive and negative lookahead assertions], which allows
+for rather complex expressions that yield precise control over how words are
+split when building the search index.
+
+Broken into its parts, this separator induces the following behavior:
+
+=== "Special characters"
+
+ ```
+ [\s\-,:!=\[\]()"/]+
+ ```
+
+ The first part of the expression inserts token boundaries for each
+ document before and after whitespace, hyphens, commas, brackets and
+ other special characters. If several of those special characters are
+ adjacent, they are treated as one.
+
+=== "Case changes"
+
+ ```
+ (?!\b)(?=[A-Z][a-z])
+ ```
+
+ Many programming languages have naming conventions like `PascalCase` or
+ `camelCase`. By adding this subexpression to the separator,
+ [words are split at case changes], tokenizing the word `PascalCase`
+ into `Pascal` and `Case`.
+
+=== "Version strings"
+
+ ```
+ \.(?!\d)
+ ```
+
+ When adding `.` to the separator, version strings like `1.2.3` are split
+ into `1`, `2` and `3`, which makes them undiscoverable via search. When
+ using this subexpression, a small lookahead is introduced which will
+ [preserve version strings] and keep them discoverable.
+
+=== "HTML/XML tags"
+
+ ```
+ &[lg]t;
+ ```
+
+ If your documentation includes HTML/XML code examples, you may want to allow
+ users to find [specific tag names]. Unfortunately, the `<` and `>` control
+ characters are encoded in code blocks as `<` and `>`. Adding this
+ subexpression to the separator allows for just that.
+
+ [positive and negative lookahead assertions]: https://www.regular-expressions.info/lookaround.html
+ [words are split at case changes]: ?q=searchHighlight
+ [preserve version strings]: ?q=9.0.0
+ [specific tag names]: ?q=script
+
+---
+
+#### <!-- md:setting config.pipeline -->
+
+<!-- md:version 9.0.0 -->
+<!-- md:default computed -->
+<!-- md:flag experimental -->
+
+Use this setting to specify the [pipeline functions] that are used to filter and
+expand tokens after tokenizing them with the [`separator`][config.separator] and
+before adding them to the search index. The default value is automatically
+computed from the [site language], but can also be explicitly set with:
+
+``` yaml
+plugins:
+ - search:
+ pipeline:
+ - stemmer
+ - stopWordFilter
+ - trimmer
+```
+
+The following pipeline functions can be used:
+
+- `stemmer` – Stem tokens to their root form, e.g. `running` to `run`
+- `stopWordFilter` – Filter common words according, e.g. `a`, `the`, etc.
+- `trimmer` – Trim whitespace from tokens
+
+ [pipeline functions]: https://lunrjs.com/guides/customising.html#pipeline-functions
+
+### Segmentation
+
+The plugin supports text segmentation of Chinese via [jieba], a popular
+Chinese text segmentation library. Other languages like Japanese and Korean are
+currently segmented on the client side, but we're considering to move this
+functionality into the plugin in the future.
+
+The following settings are available for segmentation:
+
+ [jieba]: https://pypi.org/project/jieba/
+
+---
+
+#### <!-- md:setting config.jieba_dict -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default none -->
+<!-- md:flag experimental -->
+
+Use this setting to specify a [custom dictionary] to be used by [jieba] for
+segmenting text, replacing the default dictionary. [jieba] comes with
+several dictionaries, which can be used with:
+
+``` yaml
+plugins:
+ - search:
+ jieba_dict: dict.txt
+```
+
+The following dictionaries are provided by [jieba]:
+
+- [dict.txt.small] – 占用内存较小的词典文件
+- [dict.txt.big] – 支持繁体分词更好的词典文件
+
+The provided path is resolved from the root directory.
+
+ [custom dictionary]: https://github.com/fxsjy/jieba#%E5%85%B6%E4%BB%96%E8%AF%8D%E5%85%B8
+ [dict.txt.small]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.small
+ [dict.txt.big]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.big
+
+---
+
+#### <!-- md:setting config.jieba_dict_user -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default none -->
+<!-- md:flag experimental -->
+
+Use this setting to specify an additional [user dictionary] to be used by
+[jieba] for segmenting text, augmenting the default dictionary. User
+dictionaries are ideal for tuning the segmenter:
+
+``` yaml
+plugins:
+ - search:
+ jieba_dict_user: user_dict.txt
+```
+
+The provided path is resolved from the root directory.
+
+ [user dictionary]: https://github.com/fxsjy/jieba#%E8%BD%BD%E5%85%A5%E8%AF%8D%E5%85%B8
+
+## Usage
+
+### Metadata
+
+The following properties are available:
+
+---
+
+#### <!-- md:setting meta.search.boost -->
+
+<!-- md:version 8.3.0 -->
+<!-- md:flag metadata -->
+<!-- md:default none -->
+
+Use this property to increase or decrease the relevance of a page in the search
+results, giving more weight to them. Use values above `1` to rank up and values
+below `1` to rank down:
+
+=== ":material-arrow-up-circle: Rank up"
+
+ ``` yaml
+ ---
+ search:
+ boost: 2 # (1)!
+ ---
+
+ # Page title
+ ...
+ ```
+
+ 1. When boosting pages, always start with low values.
+
+=== ":material-arrow-down-circle: Rank down"
+
+ ``` yaml
+ ---
+ search:
+ boost: 0.5
+ ---
+
+ # Page title
+ ...
+ ```
+
+---
+
+#### <!-- md:setting meta.search.exclude -->
+
+<!-- md:version 9.0.0 -->
+<!-- md:flag metadata -->
+<!-- md:default none -->
+
+Use this property to exclude a page from the search results. Note that this will
+not only remove the page, but also all subsections of the page from the search
+results:
+
+``` yaml
+---
+search:
+ exclude: true
+---
+
+# Page title
+...
+```
diff --git a/documents/markdown/mkdocs-material/plugins_social.md b/documents/markdown/mkdocs-material/plugins_social.md
new file mode 100644
index 0000000..d7aa8eb
--- /dev/null
+++ b/documents/markdown/mkdocs-material/plugins_social.md
@@ -0,0 +1,1063 @@
+---
+title: Built-in social plugin
+icon: material/share-circle
+---
+
+# Built-in social plugin
+
+The social plugin automatically and intelligently generates beautiful and highly
+customizable social cards in different [layouts][default layouts] for each page
+of your project, rendering as preview images whenever you or somebody else share
+a link to your project on social media.
+
+## Objective
+
+### How it works
+
+The plugin automatically generates a customizable social card for each page
+of your project, which appears as a preview image when sharing a link to your
+project on social media, without the use of external services and just
+[a single line of configuration][configuration].
+
+With the use of an efficient [image processing] library, the plugin allows to
+define [custom layouts] for social cards, which can be adapted to match your
+project's style and branding. While it would technically be much simpler to
+generate social cards by using a web browser and an automation framework like
+[Puppeteer][^1], it would add further liabilities to your toolchain, with the
+potential to make build pipelines more complex, much more resource intense,
+and significantly slower.
+
+ [^1]:
+ [GitHub wrote in their blog] that they use [Puppeteer] to generate social
+ card images for repositories, issues, commits, discussions, and basically
+ everything else that appear as preview images when shared on social media.
+
+The generated social cards are [cached] and stored in the
+[`site` directory][mkdocs.site_dir], and thus self-hosted, ensuring that your
+project doesn't depend on external services. In order to generate social cards
+images, a few [dependencies] need to be available on your system.
+
+ [configuration]: #configuration
+ [image processing]: requirements/image-processing.md
+ [custom layouts]: ../setup/setting-up-social-cards.md#customization
+ [Puppeteer]: https://github.com/puppeteer/puppeteer
+ [GitHub wrote in their blog]: https://github.blog/2021-06-22-framework-building-open-graph-images/
+ [cached]: #caching
+ [dependencies]: #configuration
+
+### When to use it
+
+There's one particular case when we don't recommend to use the plugin: when you
+build [offline-capable documentation] to offer it as a download. Otherwise, it
+always makes sense to enable the plugin, as links to your documentation shared
+on social media will appear much more appealing.
+
+Even more interestingly, the plugin can be combined with other built-in plugins
+that Material for MkDocs offers, in order to create sophisticated build
+pipelines tailored to your project:
+
+<div class="grid cards" markdown>
+
+- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__
+
+ ---
+
+ The social plugin automatically generates beautiful and customizable
+ social cards for each post and page, showing as previews on social media.
+
+ ---
+
+ __Links to your blog render beautiful social cards when shared on social media__
+
+- :material-file-tree: __[Built-in meta plugin][meta]__
+
+ ---
+
+ The meta plugin can be used to [change the layout][meta.social.cards_layout]
+ for social cards or [change specific layout options]
+ [meta.social.cards_layout_options] like [background][option.background_color]
+ or [color][option.color] for a subset of pages.
+
+ ---
+
+ __Your documentation can use completely different social cards per section__
+
+</div>
+
+ [offline-capable documentation]: ../setup/building-for-offline-usage.md
+ [blog]: blog.md
+ [meta]: meta.md
+
+## Configuration
+
+<!-- md:version 8.5.0 -->
+<!-- md:plugin [social] – built-in -->
+<!-- md:flag multiple -->
+<!-- md:flag experimental -->
+
+In order to get started with the social plugin, just add the following lines to
+`mkdocs.yml`, and observe how Material for MkDocs generates beautiful social
+cards for you:
+
+``` yaml
+plugins:
+ - social
+```
+
+The social plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+However, in order to generate social card images, it's necessary to install the
+dependencies for [image processing], if they're not already available on your
+system. The linked guide includes instructions for several operating systems
+and mentions some alternative environments.
+
+ [social]: social.md
+
+### General
+
+The following settings are available:
+
+---
+
+#### <!-- md:setting config.enabled -->
+
+<!-- md:version 8.5.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable the plugin when [building your project].
+If you want to disable the plugin, e.g., for local builds, you can use an
+[environment variable][mkdocs.env] in `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - social:
+ enabled: !ENV [CI, false]
+```
+
+This configuration enables the plugin only during continuous integration (CI).
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+---
+
+#### <!-- md:setting config.concurrency -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default available CPUs - 1 -->
+
+With more CPUs available, the plugin can do more work in parallel, and thus
+complete social card generation faster. If you want to disable concurrent
+processing completely, use:
+
+``` yaml
+plugins:
+ - social:
+ concurrency: 1
+```
+
+By default, the plugin uses all available CPUs - 1 with a minimum of 1.
+
+### Caching
+
+The plugin implements an [intelligent caching] mechanism, ensuring that social
+cards are only regenerated when their contents change or they're not already
+contained in the cache. If any of the variables used in a layout changes, the
+plugin detects it and regenerates the social card.
+
+The following settings are available for caching:
+
+ [intelligent caching]: requirements/caching.md
+
+---
+
+#### <!-- md:setting config.cache -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to instruct the plugin to bypass the cache, in order to
+re-generate social cards for all pages, even though the cache may not be stale.
+It's normally not necessary to specify this setting, except for when debugging
+the plugin itself. Caching can be disabled with:
+
+``` yaml
+plugins:
+ - social:
+ cache: false
+```
+
+---
+
+#### <!-- md:setting config.cache_dir -->
+
+<!-- md:version 8.5.0 -->
+<!-- md:default `.cache/plugin/social` -->
+
+It is normally not necessary to specify this setting, except for when you want
+to change the path within your root directory where social card images are
+cached. If you want to change it, use:
+
+``` yaml
+plugins:
+ - social:
+ cache_dir: my/custom/dir
+```
+
+If you're using [multiple instances] of the plugin, it can be a good idea to
+set different cache directories for both instances, so that they don't interfere
+with each other.
+
+ [multiple instances]: index.md#multiple-instances
+
+### Logging
+
+The following settings are available for logging:
+
+---
+
+#### <!-- md:setting config.log -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to control whether the plugin should only log errors when
+generating social cards without terminating the build, e.g., invalid references
+to icons. To terminate the build, use:
+
+``` yaml
+plugins:
+ - social:
+ log: false
+```
+
+---
+
+#### <!-- md:setting config.log_level -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `warn` -->
+
+Use this setting to control the log level that the plugin should employ when
+encountering errors, which requires that the [`log`][config.log] setting is
+enabled. The following log levels are available:
+
+=== "`warn`"
+
+ ``` yaml
+ plugins:
+ - social:
+ log_level: warn
+ ```
+
+ Errors are reported as warnings, terminating the build in
+ [`strict`][mkdocs.strict] mode.
+
+=== "`info`"
+
+ ``` yaml
+ plugins:
+ - social:
+ log_level: info
+ ```
+
+ Errors are only reported as informational messages.
+
+=== "`ignore`"
+
+ ``` yaml
+ plugins:
+ - social:
+ log_level: ignore
+ ```
+
+ Errors are only reported when using the `--verbose` flag.
+
+### Social cards
+
+The following settings are available for social card generation:
+
+---
+
+#### <!-- md:setting config.cards -->
+
+<!-- md:version 8.5.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable social card generation. Currently, the
+plugin's sole purpose is to generate social cards, so it's equivalent to the
+[`enabled`][config.enabled] setting, but in the future, other features might be
+added. If you want to disable social card generation, use:
+
+``` yaml
+plugins:
+ - social:
+ cards: false
+```
+
+---
+
+#### <!-- md:setting config.cards_dir -->
+
+<!-- md:version 8.5.0 -->
+<!-- md:default `assets/images/social` -->
+
+It is normally not necessary to specify this setting, except for when you want
+to change the path within the [`site` directory][mkdocs.site_dir] where
+social cards are stored. If you want to change it, use:
+
+``` yaml
+plugins:
+ - social:
+ cards_dir: my/custom/dir
+```
+
+This configuration stores the generated images at `my/custom/dir` in the
+[`site` directory][mkdocs.site_dir].
+
+---
+
+#### <!-- md:setting config.cards_layout_dir -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `layouts` -->
+
+If you want to build a [custom social card layout][custom layouts], use this
+setting to change the folder where you store your custom layouts, the default
+being a folder called `layouts` in your root directory:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout_dir: layouts
+```
+
+The provided path is resolved from the root directory.
+
+!!! tip "Where to store custom layouts"
+
+ Our recommendation is to locate the folder outside of the
+ [`docs` directory][mkdocs.docs_dir], to make sure that your [custom layouts]
+ are not copied to the [`site` directory][mkdocs.site_dir] when
+ [building your project], e.g., by adhering to the following directory
+ layout:
+
+ ``` { .sh .no-copy }
+ .
+ ├─ docs/
+ │ └─ *.md
+ ├─ layouts/
+ │ └─ *.yml
+ └─ mkdocs.yml
+ ```
+
+---
+
+#### <!-- md:setting config.cards_layout -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `default` -->
+
+The plugin ships a growing list of [`default` layouts][default layouts] for
+social cards. If you've created a [custom social card layout][custom layouts],
+you can instruct the plugin to use it exactly as one of the included layouts:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout: my-custom-layout
+```
+
+The provided path is resolved from the[
+`layouts` directory][config.cards_layout_dir].
+
+!!! tip "How custom layouts are resolved"
+
+ By default, the plugin will load your [custom layouts] from a folder named
+ `layouts` in your root directory. If your layout is called
+ `my-custom-layout`, the directory layout must adhere to:
+
+ ``` { .sh .no-copy }
+ .
+ ├─ docs/
+ │ └─ *.md
+ ├─ layouts/
+ │ └─ my-custom-layout.yml
+ └─ mkdocs.yml
+ ```
+
+---
+
+#### <!-- md:setting config.cards_layout_options -->
+
+<!-- md:version 9.1.10 -->
+<!-- md:default none -->
+
+Use this setting to set options for the layout specified via [`cards_layout`]
+[config.cards_layout] (if the layout supports it), which allows for making
+layouts easily and entirely configurable:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout_options:
+ <option>: <value>
+```
+
+When creating a [custom layout][custom layouts], you are completely free in
+defining which parts of your layout can be parametrized. The [`default` layouts]
+[default layouts] included with the plugin support the following options:
+
+<div class="mdx-columns" markdown>
+
+- [`background_color`][option.background_color]
+- [`background_image`][option.background_image]
+- [`color`][option.color]
+- [`font_family`][option.font_family]
+- [`font_variant`][option.font_variant]
+- [`logo`][option.logo]
+- [`title`][option.title]
+- [`description`][option.description]
+
+</div>
+
+
+ [default layouts]: #layouts
+
+---
+
+#### <!-- md:setting config.cards_include -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default none -->
+
+Use this setting to enable social card generation for subsections of your
+project, e.g., when using [multiple instances] of the plugin to generate
+different social cards for different subsections:
+
+``` yaml
+plugins:
+ - social:
+ cards_include:
+ - blog/*
+```
+
+This configuration enables social card generation for all pages that are
+contained in the `blog` folder and its subfolders inside the [`docs` directory]
+[mkdocs.docs_dir].
+
+---
+
+#### <!-- md:setting config.cards_exclude -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default none -->
+
+Use this setting to disable social card generation for subsections of your
+project, e.g., when using [multiple instances] of the plugin to generate
+different social cards for different subsections:
+
+``` yaml
+plugins:
+ - social:
+ cards_exclude:
+ - changelog/*
+```
+
+This configuration disables social card generation for all pages that are
+contained in the `changelog` folder and its subfolders inside the
+[`docs` directory][mkdocs.docs_dir].
+
+### Debugging
+
+The plugin includes a special mode for debugging layouts, which is very useful
+when creating [custom layouts], as it allows for quicker iteration and better
+understanding of composition.
+
+The following settings are available for debugging:
+
+---
+
+#### <!-- md:setting config.debug -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `false` -->
+
+Use this setting to enable a special mode for debugging your layout, which
+renders each layer with a colored outline and its `x` and `y` offsets, and
+overlays a dot grid for alignment, so it's easier to understand how the
+distinct layers of your layout are composed together:
+
+``` yaml
+plugins:
+ - social:
+ debug: true
+```
+
+---
+
+#### <!-- md:setting config.debug_on_build -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `false` -->
+
+By default, the plugin automatically disables [`debug`][config.debug] mode when
+[building your project], so you can be sure that debug overlays are never
+deployed to production. If you want to change that, use:
+
+``` yaml
+plugins:
+ - social:
+ debug_on_build: true
+```
+
+It's normally not necessary to change this setting, as it's just intended to
+be a safety net.
+
+---
+
+#### <!-- md:setting config.debug_grid -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+When [`debug`][config.debug] mode is enabled, this setting specifies whether a
+dot grid is rendered on top of all layers, to allow for better alignment. If you
+want to switch the grid off, use:
+
+``` yaml
+plugins:
+ - social:
+ debug_grid: false
+```
+
+---
+
+#### <!-- md:setting config.debug_grid_step -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `32` -->
+
+Use this setting to specify the step size of the dot grid in pixels, if enabled,
+which can be useful to create perfectly aligned layers for ideal composition.
+It you want to change it, use:
+
+``` yaml
+plugins:
+ - social:
+ debug_grid_step: 64
+```
+
+---
+
+#### <!-- md:setting config.debug_color -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `grey` -->
+
+Use this setting to specify the color of the outlines that are added to each
+layer and the dot grid that is rendered on top of all layers. If you need to
+change it, use:
+
+``` yaml
+plugins:
+ - social:
+ debug_color: yellow
+```
+
+In rare cases, it might be necessary to change this setting if the dot grid or
+the outlines are hard to distinguish, as the plugin will automatically adjust
+the color if not explicitly set.
+
+## Usage
+
+### Metadata
+
+The plugin allows to override a subset of settings through metadata (front
+matter) in order to customize social card generation, e.g., to set [options for
+the included `default` layouts][default layouts] for a single page, or even
+[for an entire subsection] of your project by leveraging the [meta] plugin.
+
+The following properties are available:
+
+ [for an entire subsection]: meta.md#how-it-works
+ [meta]: meta.md
+
+---
+
+#### <!-- md:setting meta.social.cards -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:flag metadata -->
+<!-- md:default none -->
+
+Use this property to override the [`cards`][config.cards] setting for the given
+page:
+
+``` yaml
+---
+social:
+ cards: false
+---
+
+# Page title
+...
+```
+
+---
+
+#### <!-- md:setting meta.social.cards_layout -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:flag metadata -->
+<!-- md:default none -->
+<!-- md:flag experimental -->
+
+Use this property to override the [`cards_layout`][config.cards_layout] setting
+for the given page:
+
+``` yaml
+---
+social:
+ cards_layout: my-custom-layout
+---
+
+# Page title
+...
+```
+
+---
+
+#### <!-- md:setting meta.social.cards_layout_options -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:flag metadata -->
+<!-- md:default none -->
+
+Use this property to override the [`cards_layout_options`]
+[config.cards_layout_options] setting for the given page:
+
+``` yaml
+---
+social:
+ cards_layout_options:
+ background_color: blue # Change background color
+ background_image: null # Remove background image
+---
+
+# Page title
+...
+```
+
+Setting an option to `#!yaml null` resets the option.
+
+### Layouts
+
+<!-- md:version 9.7.0 -->
+
+While it is possible and simple to build [custom layouts], the plugin ships
+several predefined layouts, all of which are prefixed with `default`. The
+following layouts are included:
+
+=== "`default`"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout: default
+ ```
+
+ <div class="result" markdown>
+
+ ![Layout default]
+
+ This layout sets the following defaults:
+
+ - [`background_color`][option.background_color]
+ – <!-- md:default [`theme.palette.primary`][primary color] -->
+
+ - [`font_family`][option.font_family]
+ – <!-- md:default [`theme.font.text`][font] -->
+
+ </div>
+
+=== "`default/variant`"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout: default/variant
+ ```
+
+ <div class="result" markdown>
+
+ ![Layout default variant]
+
+ This layout includes the [page icon] and sets the following defaults:
+
+ - [`background_color`][option.background_color]
+ – <!-- md:default [`theme.palette.primary`][primary color] -->
+
+ - [`font_family`][option.font_family]
+ – <!-- md:default [`theme.font.text`][font] -->
+
+ </div>
+
+=== "`default/accent`"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout: default/accent
+ ```
+
+ <div class="result" markdown>
+
+ ![Layout default accent]
+
+ This layout sets the following defaults:
+
+ - [`background_color`][option.background_color]
+ – <!-- md:default [`theme.palette.accent`][accent color] -->
+
+ - [`font_family`][option.font_family]
+ – <!-- md:default [`theme.font.text`][font] -->
+
+ </div>
+
+=== "`default/invert`"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout: default/invert
+ ```
+
+ <div class="result" markdown>
+
+ ![Layout default invert]
+
+ This layout sets the following defaults:
+
+ - [`color`][option.background_color]
+ – <!-- md:default [`theme.palette.primary`][primary color] -->
+
+ - [`font_family`][option.font_family]
+ – <!-- md:default [`theme.font.text`][font] -->
+
+ </div>
+
+=== "`default/only/image`"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout: default/only/image
+ cards_layout_options:
+ background_image: layouts/background.png
+
+ ```
+
+ <div class="result" markdown>
+
+ This layout only shows the given background image and scales it to cover.
+
+ </div>
+
+The [`default` layouts][default layouts] are very flexible and comfortable to
+use, as they replicate the original behavior of the plugin, sourcing default
+values for all options from other `theme` settings.
+
+The following options are available:
+
+ [Layout default]: ../assets/screenshots/social-cards.png
+ [Layout default variant]: ../assets/screenshots/social-cards-variant.png
+ [Layout default accent]: ../assets/screenshots/social-cards-accent.png
+ [Layout default invert]: ../assets/screenshots/social-cards-invert.png
+
+ [primary color]: ../setup/changing-the-colors.md#primary-color
+ [page icon]: ../reference/index.md#setting-the-page-icon
+ [accent color]: ../setup/changing-the-colors.md#accent-color
+ [font]: ../setup/changing-the-fonts.md#regular-font
+
+---
+
+#### <!-- md:setting option.background_color -->
+
+<!-- md:version 9.1.10 -->
+<!-- md:default computed -->
+
+Use this option to change the background color of the generated social card.
+The value can be set to a valid color value [supported by pillow], the imaging
+library used for card generation:
+
+=== "Hexadecimal"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ background_color: "#ff1493" # (1)!
+ ```
+
+ 1. The following notations are supported, whereas each character after the
+ `#` must be a valid hexadecimal in the range `#!css 0-F`:
+
+ - `#!css #rgb` – Color (short)
+ - `#!css #rgba` – Color + alpha (short)
+ - `#!css #rrggbb` – Color
+ - `#!css #rrggbbaa` – Color + alpha
+
+=== "Color function"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ background_color: rgb(255, 20, 147) # (1)!
+ ```
+
+ 1. The following functions are supported, listing the allowed maximum
+ values with the minimum values all being `#!css 0` or `#!css 0%`:
+
+ - `#!css rgb(255, 255, 255)` – Red, green and blue
+ - `#!css hsl(360, 100%, 100%)` – Hue, saturation and lightness
+ - `#!css hsv(360, 100%, 100%)` – Hue, saturation and value
+
+=== "Color name"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ background_color: deeppink # (1)!
+ ```
+
+ 1. See the [`<named-color>`][named-color] CSS data type for a list of
+ supported color names. Note that some might not be available.
+
+If this options is used together with [`background_image`]
+[option.background_image], the color is rendered on top of the image which
+allows for tinting images. If you want to remove the background color, use:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout_options:
+ background_color: transparent
+```
+
+ [supported by pillow]: https://pillow.readthedocs.io/en/stable/reference/ImageColor.html#color-names
+ [named-color]: https://developer.mozilla.org/en-US/docs/Web/CSS/named-color
+
+---
+
+#### <!-- md:setting option.background_image -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default none -->
+
+Use this option to define a background image for the generated social card. Note
+that the image is tinted with the [`background_color`][option.background_color],
+which can also be set to `transparent`:
+
+=== "Image"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ background_image: layouts/background.png
+ background_color: transparent
+ ```
+
+=== "Image with tint"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ background_image: layouts/background.png
+ background_color: "#ff149366"
+ ```
+
+The provided path is resolved from the root directory.
+
+---
+
+#### <!-- md:setting option.color -->
+
+<!-- md:version 9.1.10 -->
+<!-- md:default computed -->
+
+Use this option to change the foreground color of the generated social card.
+The value can be set to a valid color value [supported by pillow], the imaging
+library used for card generation:
+
+=== "Hexadecimal"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ color: "#ffffff" # (1)!
+ ```
+
+ 1. The following notations are supported, whereas each character after the
+ `#` must be a valid hexadecimal in the range `#!css 0-F`:
+
+ - `#!css #rgb` – Color (short)
+ - `#!css #rgba` – Color + alpha (short)
+ - `#!css #rrggbb` – Color
+ - `#!css #rrggbbaa` – Color + alpha
+
+=== "Color function"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ color: rgb(255, 255, 255) # (1)!
+ ```
+
+ 1. The following functions are supported, listing the allowed maximum
+ values with the minimum values all being `#!css 0` or `#!css 0%`:
+
+ - `#!css rgb(255, 255, 255)` – Red, green and blue
+ - `#!css hsl(360, 100%, 100%)` – Hue, saturation and lightness
+ - `#!css hsv(360, 100%, 100%)` – Hue, saturation and value
+
+=== "Color name"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ color: white # (1)!
+ ```
+
+ 1. See the [`<named-color>`][named-color] CSS data type for a list of
+ supported color names. Note that some might not be available.
+
+---
+
+#### <!-- md:setting option.font_family -->
+
+<!-- md:version 9.1.10 -->
+<!-- md:default computed -->
+
+Use this option to change the font family of the generated social card. The
+plugin automatically downloads the font from [Google Fonts], so the font must
+point to an existing Google Font:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout_options:
+ font_family: Ubuntu
+```
+
+When you've found a font that you like on [Google Fonts], you can just copy the
+name from the font's specimen page and use it as the value for this option –
+no further configuration needed.
+
+ [Google Fonts]: https://fonts.google.com/
+
+---
+
+#### <!-- md:setting option.font_variant -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default none -->
+
+Use this option to change the font variant used to generate the social card.
+If the downloaded font has variants like `Condensed` or `Expanded`, you can set
+them with:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout_options:
+ font_variant: Condensed
+```
+
+The variant is combined with the style as used in the custom layout, so the
+plugin is instructed to use combinations like `Condensed Regular` or
+`Expanded Bold`.
+
+---
+
+#### <!-- md:setting option.logo -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default computed -->
+
+Use this option to change the logo that is used in the generated social card.
+By default, the plugin uses the [`theme.logo`][theme.logo] or [`theme.icon.logo`]
+[theme.icon.logo] setting from `mkdocs.yml`. You can change it with:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout_options:
+ logo: layouts/logo.png
+```
+
+The provided path is resolved from the root directory.
+
+ [theme.logo]: ../setup/changing-the-logo-and-icons.md#logo-image
+ [theme.icon.logo]: ../setup/changing-the-logo-and-icons.md#logo-icon-bundled
+
+---
+
+#### <!-- md:setting option.title -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default computed -->
+
+Use this option to change the title of the generated social card. This overrides
+the computed page title as assigned by MkDocs, as well as the [`title`]
+[meta.title] metadata property:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout_options:
+ title: My custom title
+```
+
+ [meta.title]: ../reference/index.md#setting-the-page-title
+
+---
+
+#### <!-- md:setting option.description -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default computed -->
+
+Use this option to change the description of the generated social card. This
+overrides the set [`site_description`][mkdocs.site_description], if defined, as
+well as the [`description`][meta.description] metadata property:
+
+``` yaml
+plugins:
+ - social:
+ cards_layout_options:
+ description: My custom description
+```
+
+ [meta.description]: ../reference/index.md#setting-the-page-description
+
+---
+
+!!! question "Missing something?"
+
+ When setting up social cards, you might discover that you're missing
+ specific functionality – we're happy to consider adding it to the plugin!
+ You can [open a discussion] to ask a question, or create a [change request]
+ on our [issue tracker], so we can find out if it might be a good fit for
+ the plugin.
+
+ [open a discussion]: https://github.com/squidfunk/mkdocs-material/discussions
+ [change request]: ../contributing/requesting-a-change.md
+ [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
diff --git a/documents/markdown/mkdocs-material/plugins_tags.md b/documents/markdown/mkdocs-material/plugins_tags.md
new file mode 100644
index 0000000..b1ac540
--- /dev/null
+++ b/documents/markdown/mkdocs-material/plugins_tags.md
@@ -0,0 +1,928 @@
+---
+title: Built-in tags plugin
+icon: material/tag-text
+---
+
+# Built-in tags plugin
+
+The tags plugin adds first-class support for categorizing pages with the use
+of tags, adding the possibility to group related pages and make them
+discoverable via search and dedicated tags indexes. If your documentation is
+large, tags can help to discover relevant information faster.
+
+## Objective
+
+### How it works
+
+The plugin scans all pages for the [`tags`][meta.tags] metadata property and
+generates a tags index, which is an inverted list of tags and the pages they
+appear on. The tags index can be located anywhere in the [`nav`][mkdocs.nav],
+allowing for maximum flexibility when adding tags to your project.
+
+### When to use it
+
+If you want to add one or multiple tags indexes to your project, the tags
+plugin is a perfect choice as it makes this process ridiculously simple.
+Additionally, it integrates perfectly with several of the other
+[built-in plugins] that Material for MkDocs offers:
+
+<div class="grid cards" markdown>
+
+- :material-file-tree: __[Built-in meta plugin][meta]__
+
+ ---
+
+ The meta plugin makes it possible to ensure that subsections of your
+ project are annotated with [specific tags][meta.tags], so they can't be
+ forgotten when adding pages.
+
+ ---
+
+ __Simpler organization and management of tags in different subsections__
+
+- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__
+
+ ---
+
+ The tags plugin allows to categorize posts alongside with pages in your
+ project, to improve their discoverability and connect posts to your
+ documentation.
+
+ ---
+
+ __Your documentation's tag system integrates with your blog__
+
+</div>
+
+ [meta]: meta.md
+ [blog]: blog.md
+ [built-in plugins]: index.md
+
+## Configuration
+
+<!-- md:version 8.2.0 -->
+<!-- md:plugin [tags] – built-in -->
+<!-- md:flag multiple -->
+
+As with all [built-in plugins], getting started with the tags plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and start using
+[tags][meta.tags] to categorize your pages:
+
+``` yaml
+plugins:
+ - tags
+```
+
+The tags plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [tags]: tags.md
+
+### General
+
+The following settings are available:
+
+---
+
+#### <!-- md:setting config.enabled -->
+
+<!-- md:version 9.1.7 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable the plugin when [building your project].
+It's normally not necessary to specify this setting, but if you want to disable
+the plugin, use:
+
+``` yaml
+plugins:
+ - tags:
+ enabled: false
+```
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+### Tags
+
+The following settings are available for tags:
+
+---
+
+#### <!-- md:setting config.tags -->
+
+<!-- md:version 9.3.2 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable rendering of tags. The plugin still
+extracts tags from all pages, e.g., for [exporting tags] without rendering them.
+Rendering can be disabled with:
+
+``` yaml
+plugins:
+ - tags:
+ tags: false
+```
+
+This setting is automatically disabled if [`export_only`][config.export_only]
+is enabled.
+
+ [exporting tags]: #export
+
+---
+
+#### <!-- md:setting config.tags_file -->
+
+<!-- md:version 8.2.0 -->
+<!-- md:default none -->
+
+!!! warning "This setting is deprecated"
+
+ As of version <!-- md:version 9.6.0 -->, this setting is deprecated, as this
+ version ships a __ground up rewrite of the tags plugin__ which is much more
+ powerful than the previous version. Tags [listings] can be used on any page
+ now.
+
+<div style="opacity: 0.5" markdown>
+
+Use this setting to specify the location of the tags index, which is the page
+used to render a list of all tags and their associated pages. If this setting is
+specified, tags become clickable, pointing to the corresponding section in the
+tags index:
+
+``` yaml
+plugins:
+ - tags:
+ tags_file: tags.md
+```
+
+The page holding the tags index can be linked anywhere in the [`nav`][mkdocs.nav]
+section of `mkdocs.yml`. This setting is not required – you should only use it
+if you want to have a tags index.
+
+The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
+
+</div>
+
+ [listings]: ../setup/setting-up-tags.md#adding-a-tags-index
+
+---
+
+#### <!-- md:setting config.tags_slugify -->
+
+<!-- md:version 9.6.0 -->
+<!-- md:default [`pymdownx.slugs.slugify`][pymdownx.slugs.slugify] -->
+
+Use this setting to change the function for generating URL-compatible slugs
+from post titles. By default, the [`slugify`][pymdownx.slugs.slugify] function
+from [Python Markdown Extensions] is used as follows:
+
+``` yaml
+plugins:
+ - tags:
+ tags_slugify: !!python/object/apply:pymdownx.slugs.slugify
+ kwds:
+ case: lower
+```
+
+The default configuration is Unicode-aware and should produce good slugs for all
+languages. Of course, you can also provide a custom slugification function for
+more granular control.
+
+ [pymdownx.slugs.slugify]: https://github.com/facelessuser/pymdown-extensions/blob/01c91ce79c91304c22b4e3d7a9261accc931d707/pymdownx/slugs.py#L59-L65
+ [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
+
+---
+
+#### <!-- md:setting config.tags_slugify_separator -->
+
+<!-- md:version 9.6.0 -->
+<!-- md:default `-` -->
+
+Use this setting to change the separator that is passed to the slugification
+function set as part of [`tags_slugify`][config.tags_slugify]. While the default
+is a hyphen, it can be set to any string, e.g., `_`:
+
+``` yaml
+plugins:
+ - tags:
+ tags_slugify_separator: _
+```
+
+---
+
+#### <!-- md:setting config.tags_slugify_format -->
+
+<!-- md:version 9.6.0 -->
+<!-- md:default `tag:{slug}` -->
+
+Use this setting to change the format string that is used when generating tag
+slugs. It is a good idea to prefix tag slugs with a string that makes them
+unique, the default being:
+
+``` yaml
+plugins:
+ - tags:
+ tags_slugify_format: "tag:{slug}"
+```
+
+The following placeholders are available:
+
+- `slug` – Tag slug, slugified with [`tags_slugify`][config.tags_slugify]
+
+---
+
+#### <!-- md:setting config.tags_hierarchy -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `false` -->
+<!-- md:flag experimental -->
+
+Use this setting to enable support for tag hierarchies (nested tags, e.g.,
+`foo/bar`). If you intend to create hierarchical listings of tags, you can
+enable this setting in `mkdocs.yml` with:
+
+``` yaml
+plugins:
+ - tags:
+ tags_hierarchy: true
+```
+
+---
+
+#### <!-- md:setting config.tags_hierarchy_separator -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `/` -->
+<!-- md:flag experimental -->
+
+Use this setting to change the separator that is used when creating tag
+hierarchies. By default, tags are separated by a forward slash `/`, but you
+can change this to any string, e.g., `.`:
+
+``` yaml
+plugins:
+ - tags:
+ tags_hierarchy_separator: .
+```
+
+---
+
+#### <!-- md:setting config.tags_sort_by -->
+
+<!-- md:version 9.6.0 -->
+<!-- md:default `material.plugins.tags.tag_name` -->
+
+Use this setting to specify a custom function for comparing tags. By default,
+tag comparison is case-sensitive, but you can use `tag_name_casefold` for
+case-insensitive comparison:
+
+``` yaml
+plugins:
+ - tags:
+ tags_sort_by: !!python/name:material.plugins.tags.tag_name_casefold
+```
+
+You can also define your own comparison function, which must return a string
+or number representing the tag, that is used for sorting, and reference it in
+[`tags_sort_by`][config.tags_sort_by].
+
+---
+
+#### <!-- md:setting config.tags_sort_reverse -->
+
+<!-- md:version 9.6.0 -->
+<!-- md:default `false` -->
+
+Use this setting to reverse the order in which tags are sorted when comparing
+them. By default, tags are sorted in ascending order, but you can reverse
+ordering as follows:
+
+``` yaml
+plugins:
+ - tags:
+ tags_sort_reverse: true
+```
+
+---
+
+#### <!-- md:setting config.tags_name_property -->
+
+<!-- md:version 9.6.0 -->
+<!-- md:default [`tags`][meta.tags] -->
+
+Use this setting to change the name of the front matter property that is used by
+the plugin. It is normally not necessary to change this setting, but if you want
+to change it, you can use:
+
+``` yaml
+plugins:
+ - tags:
+ tags_name_property: tags
+```
+
+---
+
+#### <!-- md:setting config.tags_name_variable -->
+
+<!-- md:version 9.6.0 -->
+<!-- md:default `tags` -->
+
+Use this setting to change the name of the template variable that is used by
+the plugin. It is normally not necessary to change this setting, but if you want
+to change it, you can use:
+
+``` yaml
+plugins:
+ - tags:
+ tags_name_variable: tags
+```
+
+---
+
+#### <!-- md:setting config.tags_allowed -->
+
+<!-- md:version 9.6.0 -->
+<!-- md:default none -->
+
+The plugin allows to check tags against a predefined list, in order to catch
+typos or make sure that tags are not arbitrarily added. Specify the tags you
+want to allow with:
+
+``` yaml
+plugins:
+ - tags:
+ tags_allowed:
+ - HTML5
+ - JavaScript
+ - CSS
+```
+
+The plugin stops the build if a page references a tag that is not part of
+this list. Pages can be assigned to tags by using the [`tags`][meta.tags]
+metadata property.
+
+### Listings
+
+The following settings are available for listings:
+
+---
+
+#### <!-- md:setting config.listings -->
+
+<!-- md:version 9.6.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable listings. It is normally not necessary to
+change this setting, as listings are created entirely by inline comments, but
+you can disable them if necessary with:
+
+``` yaml
+plugins:
+ - tags:
+ listings: false
+```
+
+This setting is automatically disabled if [`export_only`][config.export_only]
+is enabled.
+
+ [exporting tags]: #export
+
+---
+
+#### <!-- md:setting config.listings_map -->
+
+<!-- md:version 9.6.0 -->
+<!-- md:default none -->
+
+Use this define listing configurations that you can then reference in listings
+with a custom identifier. Sharing configurations is a good idea, especially
+when you have many tag listings:
+
+``` yaml
+plugins:
+ - tags:
+ listings_map:
+ custom-id:
+ scope: true
+ exclude: Internal
+```
+
+Then, just reference the listing identifier:
+
+``` html
+<!-- material/tags custom-id -->
+```
+
+See the [listings section] for a list of all available settings.
+
+ [listings section]: #listing-configuration
+
+---
+
+#### <!-- md:setting config.listings_sort_by -->
+
+<!-- md:version 9.6.0 -->
+<!-- md:default `material.plugins.tags.item_title` -->
+
+Use this setting to specify a custom function for comparing listing items. By
+default, items are ordered by their titles, but you can change the sorting
+criterion with the following configuration:
+
+=== "Sort by item title"
+
+ ``` yaml
+ plugins:
+ - tags:
+ listings_sort_by: !!python/name:material.plugins.tags.item_title
+ ```
+
+=== "Sort by item URL"
+
+ ``` yaml
+ plugins:
+ - tags:
+ listings_sort_by: !!python/name:material.plugins.tags.item_url
+ ```
+
+You can also define your own comparison function, which must return a string
+or number representing the item, that is used for sorting, and reference it in
+[`listings_sort_by`][config.listings_sort_by].
+
+---
+
+#### <!-- md:setting config.listings_sort_reverse -->
+
+<!-- md:version 9.6.0 -->
+<!-- md:default `false` -->
+
+Use this setting to reverse the order in which items are sorted when comparing
+them. By default, items are sorted in ascending order, but you can reverse
+ordering as follows:
+
+``` yaml
+plugins:
+ - tags:
+ listings_sort_reverse: true
+```
+
+---
+
+#### <!-- md:setting config.listings_tags_sort_by -->
+
+<!-- md:version 9.6.0 -->
+<!-- md:default `material.plugins.tags.tag_name` -->
+
+Use this setting to specify a custom function for comparing tags in listings. By
+default, tag comparison is case-sensitive, but you can use `tag_name_casefold`
+for case-insensitivity:
+
+``` yaml
+plugins:
+ - tags:
+ tags_sort_by: !!python/name:material.plugins.tags.tag_name_casefold
+```
+
+You can also define your own comparison function, which must return a string
+or number representing the tag, that is used for sorting, and reference it in
+[`tags_sort_by`][config.tags_sort_by].
+
+---
+
+#### <!-- md:setting config.listings_tags_sort_reverse -->
+
+<!-- md:version 9.6.0 -->
+<!-- md:default `false` -->
+
+Use this setting to reverse the order in which tags are sorted when comparing
+them. By default, tags are sorted in ascending order, but you can reverse
+ordering as follows:
+
+``` yaml
+plugins:
+ - tags:
+ tags_sort_reverse: true
+```
+
+---
+
+#### <!-- md:setting config.listings_directive -->
+
+<!-- md:version 9.6.0 -->
+<!-- md:default `material/tags` -->
+
+Use this setting to change the name of the directive the plugin will look for
+when processing pages. If you want to use a shorter directive than
+`material/tags`, you could use:
+
+``` yaml
+plugins:
+ - tags:
+ listings_directive: $tags
+```
+
+Using this setting, listings must now be referenced as such:
+
+``` html
+<!-- $tags { include: [foo, bar] } -->
+```
+
+---
+
+#### <!-- md:setting config.listings_toc -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable tags showing up in the table of contents.
+If you don't want tags to show up in the table of contents, you can disable this
+behavior with:
+
+``` yaml
+plugins:
+ - tags:
+ listings_toc: false
+```
+
+### Shadow tags
+
+The following settings are available for shadow tags:
+
+---
+
+#### <!-- md:setting config.shadow -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `false` -->
+
+Use this setting to specify whether the plugin should include shadow tags on
+pages and in listings when [building your project], which might be useful for
+deploy previews:
+
+=== "Show shadow tags"
+
+ ``` yaml
+ plugins:
+ - tags:
+ shadow: true
+ ```
+
+=== "Hide shadow tags"
+
+ ``` yaml
+ plugins:
+ - tags:
+ shadow: false
+ ```
+
+---
+
+#### <!-- md:setting config.shadow_on_serve -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to control whether the plugin should include shadow tags on
+pages and in listings when [previewing your site]. If you don't wish to include
+them when previewing, use:
+
+``` yaml
+plugins:
+ - tags:
+ shadow_on_serve: false
+```
+
+ [previewing your site]: ../creating-your-site.md#previewing-as-you-write
+
+---
+
+#### <!-- md:setting config.shadow_tags -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default none -->
+
+The plugin allows to specify a predefined list of shadow tags which can be
+included and excluded from builds by using the [`shadow`][config.shadow]
+setting. Shadow tags must be specified as a list:
+
+``` yaml
+plugins:
+ - tags:
+ shadow_tags:
+ - Draft
+ - Internal
+```
+
+---
+
+#### <!-- md:setting config.shadow_tags_prefix -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default none -->
+
+Use this setting to specify a string that is checked as a prefix for each tag.
+If the tag starts with this string, the tag is marked as a shadow tag. A common
+practice is to use `_` as a prefix:
+
+``` yaml
+plugins:
+ - tags:
+ shadow_tags_prefix: _
+```
+
+---
+
+#### <!-- md:setting config.shadow_tags_suffix -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default none -->
+
+Use this setting to specify a string that is checked as a suffix for each tag.
+If the tag ends with this string, the tag is marked as a shadow tag. One option
+can be to use `Internal` as a suffix:
+
+
+``` yaml
+plugins:
+ - tags:
+ shadow_tags_suffix: Internal
+```
+
+### Export
+
+The following settings are available for exporting:
+
+---
+
+#### <!-- md:setting config.export -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to control whether the plugin creates a `tags.json` file
+inside your [`site` directory][mkdocs.site_dir], which can then be consumed by
+other plugins and projects:
+
+``` yaml
+plugins:
+ - tags:
+ export: true
+```
+
+---
+
+#### <!-- md:setting config.export_file -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `tags.json` -->
+
+Use this setting to change the path of the file where the exported tags are
+stored. It's normally not necessary to change this setting, but if you need to,
+use:
+
+``` yaml
+plugins:
+ - tags:
+ export_file: tags.json
+```
+
+The provided path is resolved from the [`site` directory][mkdocs.site_dir].
+
+---
+
+#### <!-- md:setting config.export_only -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `false` -->
+
+This setting is solely provided for convenience to disable the rendering of tags
+and listings with a single setting (e.g. by using an environment variable),
+while keeping the export functionality:
+
+``` yaml
+plugins:
+ - tags:
+ export_only: true
+```
+
+This will automatically disable the [`tags`][config.tags] and
+[`listings`][config.listings] settings.
+
+## Usage
+
+### Metadata
+
+The following properties are available:
+
+---
+
+#### <!-- md:setting meta.tags -->
+
+<!-- md:version 8.2.0 -->
+<!-- md:flag metadata -->
+<!-- md:default none -->
+
+Use this property to associate a page with one or more tags, making the page
+appear in the generated tags index. Tags are defined as a list of strings
+(whitespaces are allowed):
+
+``` yaml
+---
+tags:
+ - HTML5
+ - JavaScript
+ - CSS
+---
+
+# Page title
+...
+```
+
+If you want to prevent accidental typos when assigning tags to pages, you can
+set a predefined list of allowed tags in `mkdocs.yml` by using the
+[`tags_allowed`][config.tags_allowed] setting.
+
+### Listing configuration
+
+The listings configuration controls which tags are included in or excluded from
+a listing and whether a listing only includes pages in the current scope.
+Furthermore, listings can override some values from the global configuration.
+
+The following settings are available:
+
+---
+
+#### <!-- md:setting listing.scope -->
+
+<!-- md:version 9.6.0 -->
+<!-- md:default `false` -->
+
+This setting specifies whether the listing should only consider pages that are
+within the current subsection of the documentation of the page the listing is
+embedded in:
+
+=== "Inline usage"
+
+ ``` html
+ <!-- material/tags { scope: true } -->
+ ```
+
+=== "Usage in `mkdocs.yml`"
+
+ ``` yaml
+ plugins:
+ - tags:
+ listings_map:
+ custom-id:
+ scope: false
+ ```
+
+ Then, just reference the listing identifier:
+
+ ``` html
+ <!-- material/tags custom-id -->
+ ```
+
+---
+
+#### <!-- md:setting listing.shadow -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default computed -->
+
+This setting specifies whether the listing should include shadow tags, which
+allows to override the global [`shadow`][config.shadow] setting on a per-listing
+basis:
+
+=== "Inline usage"
+
+ ``` html
+ <!-- material/tags { shadow: true } -->
+ ```
+
+=== "Usage in `mkdocs.yml`"
+
+ ``` yaml
+ plugins:
+ - tags:
+ listings_map:
+ custom-id:
+ shadow: true
+ ```
+
+ Then, just reference the listing identifier:
+
+ ``` html
+ <!-- material/tags custom-id -->
+ ```
+
+---
+
+#### <!-- md:setting listing.toc -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default [`listings_toc`][config.listings_toc] -->
+
+This setting specifies whether the listing should render tags inside the table
+of contents, allowing to override the global [`listings_toc`][config.listings_toc]
+setting on a per-listing basis:
+
+=== "Inline usage"
+
+ ``` html
+ <!-- material/tags { toc: true } -->
+ ```
+
+=== "Usage in `mkdocs.yml`"
+
+ ``` yaml
+ plugins:
+ - tags:
+ listings_map:
+ custom-id:
+ toc: true
+ ```
+
+ Then, just reference the listing identifier:
+
+ ``` html
+ <!-- material/tags custom-id -->
+ ```
+
+---
+
+#### <!-- md:setting listing.include -->
+
+<!-- md:version 9.6.0 -->
+<!-- md:default none -->
+
+Use this setting to specify which tags should be included in the listing. Each
+page that features a tag that is part of this setting, is listed under the
+respective tag:
+
+=== "Inline usage"
+
+ ``` html
+ <!-- material/tags { include: [foo, bar] } -->
+ ```
+
+=== "Usage in `mkdocs.yml`"
+
+ ``` yaml
+ plugins:
+ - tags:
+ listings_map:
+ custom-id:
+ include:
+ - foo
+ - bar
+ ```
+
+ Then, just reference the listing identifier:
+
+ ``` html
+ <!-- material/tags custom-id -->
+ ```
+
+If this setting is left empty, all tags and pages are included.
+
+---
+
+#### <!-- md:setting listing.exclude -->
+
+<!-- md:version 9.6.0 -->
+<!-- md:default none -->
+
+Use this setting to specify which tags should be excluded from the listing. Each
+page that features a tag that is part of this setting, is excluded from the
+listing entirely:
+
+=== "Inline usage"
+
+ ``` html
+ <!-- material/tags { exclude: [foo, bar] } -->
+ ```
+
+=== "Usage in `mkdocs.yml`"
+
+ ``` yaml
+ plugins:
+ - tags:
+ listings_map:
+ custom-id:
+ exclude:
+ - foo
+ - bar
+ ```
+
+ Then, just reference the listing identifier:
+
+ ``` html
+ <!-- material/tags custom-id -->
+ ```
+
+If this setting is left empty, no tags or pages are excluded.
+
+## Limitations
+
+The implementation of the tags plugin is tricky due to MkDocs architecture.
+Notably, tag listing markers cannot appear within code blocks. For technical
+details, refer to #8114.
diff --git a/documents/markdown/mkdocs-material/plugins_typeset.md b/documents/markdown/mkdocs-material/plugins_typeset.md
new file mode 100644
index 0000000..dcde297
--- /dev/null
+++ b/documents/markdown/mkdocs-material/plugins_typeset.md
@@ -0,0 +1,96 @@
+---
+title: Built-in typeset plugin
+icon: material/format-title
+status: deprecated
+---
+
+# Built-in typeset plugin
+
+The typeset plugin allows to preserve the enriched presentation of titles and
+headlines within the navigation and table of contents. This means that code
+blocks, icons, emojis and any other inline formatting can be rendered exactly
+as defined in the page's content.
+
+!!! bug "The built-in typeset plugin is deprecated"
+
+ [Material for MkDocs is in maintenance mode]. The typeset plugin, which was
+ formely part of the [Insiders] edition, was released in <!-- md:version 9.7.0 -->, the last release that includes all features from the Insiders edition.
+ Unfortunately, the typeset plugin turned out impossible to maintain, and
+ was one of the key motivators to create [Zensical].
+
+ ---
+
+ __If you're considering the typeset plugin, please be aware that known issues will <u>not</u> be fixed.__
+
+ [Material for MkDocs is in maintenance mode]: https://github.com/squidfunk/mkdocs-material/issues/8523
+ [Zensical]: ../blog/posts/zensical.md
+ [Insiders]: ../insiders/index.md
+
+## Objective
+
+### How it works
+
+When [building your project], MkDocs extracts the plain text from headlines and
+drops the original formatting. This is generally useful and a good idea, since
+this information is made available to other plugins that might have problems
+when being passed HTML instead of plain text.
+
+However, it also means that the entire formatting is lost.
+
+The plugin hooks into the rendering process, extracts the original headlines,
+and makes them available to be used in templates and plugins. The templates of
+Material for MkDocs use this information to render an enriched version of the
+navigation and table of contents.
+
+ [building your project]: ../creating-your-site.md#building-your-site
+
+### When to use it
+
+It's generally recommended to use the plugin, because it is a drop-in solution
+that doesn't require any configuration and is designed to work out of the box.
+Since it doesn't overwrite but only adds information, it's not expected to
+interfere with other plugins.
+
+## Configuration
+
+<!-- md:version 9.7.0 -->
+<!-- md:plugin [typeset] – built-in -->
+<!-- md:flag experimental -->
+
+As with all [built-in plugins], getting started with the typeset plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and observe the
+enriched navigation and table of contents:
+
+``` yaml
+plugins:
+ - typeset
+```
+
+The typeset plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+ [typeset]: typeset.md
+ [built-in plugins]: index.md
+
+### General
+
+The following settings are available:
+
+---
+
+#### <!-- md:setting config.enabled -->
+
+<!-- md:version 9.7.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable the plugin when [building your project].
+It's normally not necessary to specify this setting, but if you want to disable
+the plugin, use:
+
+``` yaml
+plugins:
+ - typeset:
+ enabled: false
+```
+
+ [building your project]: ../creating-your-site.md#building-your-site
diff --git a/documents/markdown/mkdocs-material/publishing-your-site.md b/documents/markdown/mkdocs-material/publishing-your-site.md
new file mode 100644
index 0000000..cf690c5
--- /dev/null
+++ b/documents/markdown/mkdocs-material/publishing-your-site.md
@@ -0,0 +1,192 @@
+# Publishing your site
+
+The great thing about hosting project documentation in a `git` repository is
+the ability to deploy it automatically when new changes are pushed. MkDocs
+makes this ridiculously simple.
+
+## GitHub Pages
+
+If you're already hosting your code on GitHub, [GitHub Pages] is certainly
+the most convenient way to publish your project documentation. It's free of
+charge and pretty easy to set up.
+
+ [GitHub Pages]: https://pages.github.com/
+
+### with GitHub Actions
+
+Using [GitHub Actions] you can automate the deployment of your project
+documentation. At the root of your repository, create a new GitHub Actions
+workflow, e.g. `.github/workflows/ci.yml`, and copy and paste the following
+contents:
+
+``` yaml
+name: ci # (1)!
+on:
+ push:
+ branches:
+ - master # (2)!
+ - main
+permissions:
+ contents: write
+jobs:
+ deploy:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - name: Configure Git Credentials
+ run: |
+ git config user.name github-actions[bot]
+ git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+ - uses: actions/setup-python@v5
+ with:
+ python-version: 3.x
+ - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV # (3)!
+ - uses: actions/cache@v4
+ with:
+ key: mkdocs-material-${{ env.cache_id }}
+ path: ~/.cache # (4)!
+ restore-keys: |
+ mkdocs-material-
+ - run: pip install mkdocs-material # (5)!
+ - run: mkdocs gh-deploy --force
+```
+
+1. You can change the name to your liking.
+
+2. At some point, GitHub renamed `master` to `main`. If your default branch
+ is named `master`, you can safely remove `main`, vice versa.
+
+3. Store the `cache_id` environmental variable to access it later during cache
+ `key` creation. The name is case-sensitive, so be sure to align it with `${{ env.cache_id }}`.
+
+ - The `--utc` option makes sure that each workflow runner uses the same time zone.
+ - The `%V` format assures a cache update once a week.
+ - You can change the format to `%F` to have daily cache updates.
+
+ You can read the [manual page] to learn more about the formatting options of the `date` command.
+
+4. Some Material for MkDocs plugins use [caching] to speed up repeated
+ builds, and store the results in the `~/.cache` directory.
+
+5. This is the place to install further [MkDocs plugins] or Markdown
+ extensions with `pip` to be used during the build:
+
+ ``` sh
+ pip install \
+ mkdocs-material \
+ mkdocs-awesome-pages-plugin \
+ ...
+ ```
+
+Now, when a new commit is pushed to either the `master` or `main` branches,
+the static site is automatically built and deployed. Push your changes to see
+the workflow in action.
+
+If the GitHub Page doesn't show up after a few minutes, go to the settings of
+your repository and ensure that the [publishing source branch] for your GitHub
+Page is set to `gh-pages`.
+
+Your documentation should shortly appear at `<username>.github.io/<repository>`.
+
+To publish your site on a custom domain, please refer to the [MkDocs documentation].
+
+ [GitHub Actions]: https://github.com/features/actions
+ [MkDocs plugins]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins
+ [personal access token]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
+ [built-in optimize plugin]: plugins/optimize.md
+ [GitHub secrets]: https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets
+ [publishing source branch]: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
+ [manual page]: https://man7.org/linux/man-pages/man1/date.1.html
+ [caching]: plugins/requirements/caching.md
+ [MkDocs documentation]: https://www.mkdocs.org/user-guide/deploying-your-docs/#custom-domains
+
+### with MkDocs
+
+If you prefer to deploy your project documentation manually, you can just invoke
+the following command from the directory containing the `mkdocs.yml` file:
+
+```
+mkdocs gh-deploy --force
+```
+
+This will build your documentation and deploy it to a branch
+`gh-pages` in your repository. See [this overview in the MkDocs
+documentation] for more information. For a description of the
+arguments, see [the documentation for the command].
+
+ [this overview in the MkDocs documentation]: https://www.mkdocs.org/user-guide/deploying-your-docs/#project-pages
+ [the documentation for the command]: https://www.mkdocs.org/user-guide/cli/#mkdocs-gh-deploy
+
+## GitLab Pages
+
+If you're hosting your code on GitLab, deploying to [GitLab Pages] can be done
+by using the [GitLab CI] task runner. At the root of your repository, create a
+task definition named `.gitlab-ci.yml` and copy and paste the following
+contents:
+
+``` yaml
+pages:
+ stage: deploy
+ image: python:latest
+ script:
+ - pip install mkdocs-material
+ - mkdocs build --site-dir public
+ cache:
+ key: ${CI_COMMIT_REF_SLUG}
+ paths:
+ - ~/.cache/ # (1)!
+ pages:
+ publish: public
+ rules:
+ - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
+```
+
+1. Some Material for MkDocs plugins use [caching] to speed up repeated
+ builds, and store the results in the `~/.cache` directory.
+
+Now, when a new commit is pushed to the [default branch] (typically `master` or
+`main`), the static site is automatically built and deployed. Commit and push
+the file to your repository to see the workflow in action.
+
+Your documentation is not published under `<username>.gitlab.io/<repository>`
+by default since **GitLab 17.4** [^1]. However, if you prefer a cleaner URL
+structure, such as `<username>.gitlab.io/<repository>`, you need to adjust
+your configuration.
+
+To switch from a unique domain to the traditional URL structure, follow
+these steps:
+
+1. Locate Your Repository
+2. Go to **Settings › Pages** in the repository menu.
+3. In the **Unique domain settings** section, **uncheck** the box labeled
+4. **Use unique domain**.
+5. Click **Save changes** to apply the update.
+
+Now you can reach your documentation under `<username>.gitlab.io/<repository>`.
+
+[^1]: [Release notes for Gitlab 17.4](https://about.gitlab.com/releases/2024/09/19/gitlab-17-4-released/)
+
+## Other
+
+Since we can't cover all possible platforms, we rely on community contributed
+guides that explain how to deploy websites built with Material for MkDocs to
+other providers:
+
+<div class="mdx-columns" markdown>
+
+- [:simple-cloudflarepages: Cloudflare Pages][Cloudflare Pages]
+- [:material-airballoon-outline: Fly.io][Flyio]
+- [:simple-netlify: Netlify][Netlify]
+- [:simple-scaleway: Scaleway][Scaleway]
+
+</div>
+
+ [GitLab Pages]: https://gitlab.com/pages
+ [GitLab CI]: https://docs.gitlab.com/ee/ci/
+ [masked custom variables]: https://docs.gitlab.com/ee/ci/variables/#mask-a-cicd-variable
+ [default branch]: https://docs.gitlab.com/ee/user/project/repository/branches/default.html
+ [Cloudflare Pages]: https://deborahwrites.com/guides/deploy-host-mkdocs/deploy-mkdocs-material-cloudflare/
+ [Flyio]: https://documentation.breadnet.co.uk/cloud/fly/mkdocs-on-fly/
+ [Netlify]: https://deborahwrites.com/guides/deploy-host-mkdocs/deploy-mkdocs-material-netlify/
+ [Scaleway]: https://www.scaleway.com/en/docs/tutorials/using-bucket-website-with-mkdocs/
+
diff --git a/documents/markdown/mkdocs-material/reference_admonitions.md b/documents/markdown/mkdocs-material/reference_admonitions.md
new file mode 100644
index 0000000..d8b6568
--- /dev/null
+++ b/documents/markdown/mkdocs-material/reference_admonitions.md
@@ -0,0 +1,539 @@
+---
+icon: material/alert-outline
+---
+
+# Admonitions
+
+Admonitions, also known as _call-outs_, are an excellent choice for including
+side content without significantly interrupting the document flow. Material for
+MkDocs provides several different types of admonitions and allows for the
+inclusion and nesting of arbitrary content.
+
+## Configuration
+
+This configuration enables admonitions, allows to make them collapsible and to
+nest arbitrary content inside admonitions. Add the following lines to
+`mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - admonition
+ - pymdownx.details
+ - pymdownx.superfences
+```
+
+See additional configuration options:
+
+- [Admonition]
+- [Details]
+- [SuperFences]
+
+ [Admonition]: ../setup/extensions/python-markdown.md#admonition
+ [Details]: ../setup/extensions/python-markdown-extensions.md#details
+ [SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
+
+### Admonition icons
+
+<!-- md:version 8.3.0 -->
+
+Each of the supported admonition types has a distinct icon, which can be changed
+to any icon bundled with the theme, or even a [custom icon]. Add the following
+lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ icon:
+ admonition:
+ <type>: <icon> # (1)!
+```
+
+1. Enter a few keywords to find the perfect icon using our [icon search] and
+ click on the shortcode to copy it to your clipboard:
+
+ <div class="mdx-iconsearch" data-mdx-component="iconsearch">
+ <input class="md-input md-input--stretch mdx-iconsearch__input" placeholder="Search icon" data-mdx-component="iconsearch-query" value="alert" />
+ <div class="mdx-iconsearch-result" data-mdx-component="iconsearch-result" data-mdx-mode="file">
+ <div class="mdx-iconsearch-result__meta"></div>
+ <ol class="mdx-iconsearch-result__list"></ol>
+ </div>
+ </div>
+
+??? example "Expand to show alternate icon sets"
+
+ === ":octicons-mark-github-16: Octicons"
+
+ ``` yaml
+ theme:
+ icon:
+ admonition:
+ note: octicons/tag-16
+ abstract: octicons/checklist-16
+ info: octicons/info-16
+ tip: octicons/squirrel-16
+ success: octicons/check-16
+ question: octicons/question-16
+ warning: octicons/alert-16
+ failure: octicons/x-circle-16
+ danger: octicons/zap-16
+ bug: octicons/bug-16
+ example: octicons/beaker-16
+ quote: octicons/quote-16
+ ```
+
+
+ === ":fontawesome-brands-font-awesome: FontAwesome"
+
+ ``` yaml
+ theme:
+ icon:
+ admonition:
+ note: fontawesome/solid/note-sticky
+ abstract: fontawesome/solid/book
+ info: fontawesome/solid/circle-info
+ tip: fontawesome/solid/bullhorn
+ success: fontawesome/solid/check
+ question: fontawesome/solid/circle-question
+ warning: fontawesome/solid/triangle-exclamation
+ failure: fontawesome/solid/bomb
+ danger: fontawesome/solid/skull
+ bug: fontawesome/solid/robot
+ example: fontawesome/solid/flask
+ quote: fontawesome/solid/quote-left
+ ```
+
+ [custom icon]: ../setup/changing-the-logo-and-icons.md#additional-icons
+ [supported types]: #supported-types
+ [icon search]: icons-emojis.md#search
+
+## Usage
+
+Admonitions follow a simple syntax: a block starts with `!!!`, followed by a
+single keyword used as a [type qualifier]. The content of the block follows on
+the next line, indented by four spaces:
+
+``` markdown title="Admonition"
+!!! note
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+```
+
+<div class="result" markdown>
+
+!!! note
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+
+</div>
+
+ [type qualifier]: #supported-types
+
+### Changing the title
+
+By default, the title will equal the type qualifier in titlecase. However, it
+can be changed by adding a quoted string containing valid Markdown (including
+links, formatting, ...) after the type qualifier:
+
+``` markdown title="Admonition with custom title"
+!!! note "Phasellus posuere in sem ut cursus"
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+```
+
+<div class="result" markdown>
+
+!!! note "Phasellus posuere in sem ut cursus"
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+
+</div>
+
+### Nested admonitions
+
+You can also include nested admonitions in your documentation. To do this, you
+can use your existing admonitions and indent the desired ones:
+
+``` markdown title="Nested Admonition"
+!!! note "Outer Note"
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+
+ !!! note "Inner Note"
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+```
+
+<div class="result" markdown>
+
+!!! note "Outer Note"
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+
+ !!! note "Inner Note"
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+</div>
+
+### Removing the title
+
+Similar to [changing the title], the icon and title can be omitted entirely by
+adding an empty string directly after the type qualifier. Note that this will
+not work for [collapsible blocks]:
+
+``` markdown title="Admonition without title"
+!!! note ""
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+```
+
+<div class="result" markdown>
+
+!!! note ""
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+
+</div>
+
+ [changing the title]: #changing-the-title
+ [collapsible blocks]: #collapsible-blocks
+
+### Collapsible blocks
+
+When [Details] is enabled and an admonition block is started with `???` instead
+of `!!!`, the admonition is rendered as an expandable block with a small toggle
+on the right side:
+
+``` markdown title="Admonition, collapsible"
+??? note
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+```
+
+<div class="result" markdown>
+
+??? note
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+
+</div>
+
+Adding a `+` after the `???` token renders the block expanded:
+
+``` markdown title="Admonition, collapsible and initially expanded"
+???+ note
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+```
+
+<div class="result" markdown>
+
+???+ note
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+
+</div>
+
+### Inline blocks
+
+Admonitions can also be rendered as inline blocks (e.g., for sidebars), placing
+them to the right using the `inline` + `end` modifiers, or to the left using
+only the `inline` modifier:
+
+=== ":octicons-arrow-right-16: inline end"
+
+ !!! info inline end "Lorem ipsum"
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+ ``` markdown
+ !!! info inline end "Lorem ipsum"
+
+ Lorem ipsum dolor sit amet, consectetur
+ adipiscing elit. Nulla et euismod nulla.
+ Curabitur feugiat, tortor non consequat
+ finibus, justo purus auctor massa, nec
+ semper lorem quam in massa.
+ ```
+
+ Use `inline end` to align to the right (left for rtl languages).
+
+=== ":octicons-arrow-left-16: inline"
+
+ !!! info inline "Lorem ipsum"
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+ ``` markdown
+ !!! info inline "Lorem ipsum"
+
+ Lorem ipsum dolor sit amet, consectetur
+ adipiscing elit. Nulla et euismod nulla.
+ Curabitur feugiat, tortor non consequat
+ finibus, justo purus auctor massa, nec
+ semper lorem quam in massa.
+ ```
+
+ Use `inline` to align to the left (right for rtl languages).
+
+__Important__: admonitions that use the `inline` modifiers _must_ be declared
+prior to the content block you want to place them beside. If there's
+insufficient space to render the admonition next to the block, the admonition
+will stretch to the full width of the viewport, e.g., on mobile viewports.
+
+### Supported types
+
+Following is a list of type qualifiers provided by Material for MkDocs, whereas
+the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
+
+ [^1]:
+ Previously, some of the supported types defined more than one qualifier.
+ For example, authors could use `summary` or `tldr` as alternative qualifiers
+ to render an [`abstract`](#+type:abstract) admonition. As this increased the
+ size of the CSS that is shipped with Material for MkDocs, the additional
+ type qualifiers are now all deprecated and will be removed in the next major
+ version. This will also be mentioned in the upgrade guide.
+
+<!-- md:option type:note -->
+
+: !!! note
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+<!-- md:option type:abstract -->
+
+: !!! abstract
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+<!-- md:option type:info -->
+
+: !!! info
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+<!-- md:option type:tip -->
+
+: !!! tip
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+<!-- md:option type:success -->
+
+: !!! success
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+<!-- md:option type:question -->
+
+: !!! question
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+<!-- md:option type:warning -->
+
+: !!! warning
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+<!-- md:option type:failure -->
+
+: !!! failure
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+<!-- md:option type:danger -->
+
+: !!! danger
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+<!-- md:option type:bug -->
+
+: !!! bug
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+<!-- md:option type:example -->
+
+: !!! example
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+<!-- md:option type:quote -->
+
+: !!! quote
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+## Customization
+
+### Classic admonitions
+
+Prior to version <!-- md:version 8.5.6 -->, admonitions had a slightly
+different appearance:
+
+!!! classic "Note"
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+
+If you want to restore this appearance, add the following CSS to an
+[additional style sheet]:
+
+<style>
+ .md-typeset .admonition.classic {
+ border-width: 0;
+ border-left-width: 4px;
+ }
+</style>
+
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+ ``` css
+ .md-typeset .admonition,
+ .md-typeset details {
+ border-width: 0;
+ border-left-width: 4px;
+ }
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_css:
+ - stylesheets/extra.css
+ ```
+
+### Custom admonitions
+
+If you want to add a custom admonition type, all you need is a color and an
+`*.svg` icon. Copy the icon's code from the [`.icons`][custom icons] folder
+and add the following CSS to an [additional style sheet]:
+
+<style>
+ :root {
+ --md-admonition-icon--pied-piper: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M244 246c-3.2-2-6.3-2.9-10.1-2.9-6.6 0-12.6 3.2-19.3 3.7l1.7 4.9zm135.9 197.9c-19 0-64.1 9.5-79.9 19.8l6.9 45.1c35.7 6.1 70.1 3.6 106-9.8-4.8-10-23.5-55.1-33-55.1zM340.8 177c6.6 2.8 11.5 9.2 22.7 22.1 2-1.4 7.5-5.2 7.5-8.6 0-4.9-11.8-13.2-13.2-23 11.2-5.7 25.2-6 37.6-8.9 68.1-16.4 116.3-52.9 146.8-116.7C548.3 29.3 554 16.1 554.6 2l-2 2.6c-28.4 50-33 63.2-81.3 100-31.9 24.4-69.2 40.2-106.6 54.6l-6.3-.3v-21.8c-19.6 1.6-19.7-14.6-31.6-23-18.7 20.6-31.6 40.8-58.9 51.1-12.7 4.8-19.6 10-25.9 21.8 34.9-16.4 91.2-13.5 98.8-10zM555.5 0l-.6 1.1-.3.9.6-.6zm-59.2 382.1c-33.9-56.9-75.3-118.4-150-115.5l-.3-6c-1.1-13.5 32.8 3.2 35.1-31l-14.4 7.2c-19.8-45.7-8.6-54.3-65.5-54.3-14.7 0-26.7 1.7-41.4 4.6 2.9 18.6 2.2 36.7-10.9 50.3l19.5 5.5c-1.7 3.2-2.9 6.3-2.9 9.8 0 21 42.8 2.9 42.8 33.6 0 18.4-36.8 60.1-54.9 60.1-8 0-53.7-50-53.4-60.1l.3-4.6 52.3-11.5c13-2.6 12.3-22.7-2.9-22.7-3.7 0-43.1 9.2-49.4 10.6-2-5.2-7.5-14.1-13.8-14.1-3.2 0-6.3 3.2-9.5 4-9.2 2.6-31 2.9-21.5 20.1L15.9 298.5c-5.5 1.1-8.9 6.3-8.9 11.8 0 6 5.5 10.9 11.5 10.9 8 0 131.3-28.4 147.4-32.2 2.6 3.2 4.6 6.3 7.8 8.6 20.1 14.4 59.8 85.9 76.4 85.9 24.1 0 58-22.4 71.3-41.9 3.2-4.3 6.9-7.5 12.4-6.9.6 13.8-31.6 34.2-33 43.7-1.4 10.2-1 35.2-.3 41.1 26.7 8.1 52-3.6 77.9-2.9 4.3-21 10.6-41.9 9.8-63.5l-.3-9.5c-1.4-34.2-10.9-38.5-34.8-58.6-1.1-1.1-2.6-2.6-3.7-4 2.2-1.4 1.1-1 4.6-1.7 88.5 0 56.3 183.6 111.5 229.9 33.1-15 72.5-27.9 103.5-47.2-29-25.6-52.6-45.7-72.7-79.9zm-196.2 46.1v27.2l11.8-3.4-2.9-23.8zm-68.7-150.4l24.1 61.2 21-13.8-31.3-50.9zm84.4 154.9l2 12.4c9-1.5 58.4-6.6 58.4-14.1 0-1.4-.6-3.2-.9-4.6-26.8 0-36.9 3.8-59.5 6.3z"/></svg>')
+ }
+ .md-typeset .admonition.pied-piper,
+ .md-typeset details.pied-piper {
+ border-color: rgb(43, 155, 70);
+ }
+ .md-typeset .pied-piper > .admonition-title,
+ .md-typeset .pied-piper > summary {
+ background-color: rgba(43, 155, 70, 0.1);
+ }
+ .md-typeset .pied-piper > .admonition-title::before,
+ .md-typeset .pied-piper > summary::before {
+ background-color: rgb(43, 155, 70);
+ -webkit-mask-image: var(--md-admonition-icon--pied-piper);
+ mask-image: var(--md-admonition-icon--pied-piper);
+ }
+</style>
+
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+ ``` css
+ :root {
+ --md-admonition-icon--pied-piper: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M244 246c-3.2-2-6.3-2.9-10.1-2.9-6.6 0-12.6 3.2-19.3 3.7l1.7 4.9zm135.9 197.9c-19 0-64.1 9.5-79.9 19.8l6.9 45.1c35.7 6.1 70.1 3.6 106-9.8-4.8-10-23.5-55.1-33-55.1zM340.8 177c6.6 2.8 11.5 9.2 22.7 22.1 2-1.4 7.5-5.2 7.5-8.6 0-4.9-11.8-13.2-13.2-23 11.2-5.7 25.2-6 37.6-8.9 68.1-16.4 116.3-52.9 146.8-116.7C548.3 29.3 554 16.1 554.6 2l-2 2.6c-28.4 50-33 63.2-81.3 100-31.9 24.4-69.2 40.2-106.6 54.6l-6.3-.3v-21.8c-19.6 1.6-19.7-14.6-31.6-23-18.7 20.6-31.6 40.8-58.9 51.1-12.7 4.8-19.6 10-25.9 21.8 34.9-16.4 91.2-13.5 98.8-10zM555.5 0l-.6 1.1-.3.9.6-.6zm-59.2 382.1c-33.9-56.9-75.3-118.4-150-115.5l-.3-6c-1.1-13.5 32.8 3.2 35.1-31l-14.4 7.2c-19.8-45.7-8.6-54.3-65.5-54.3-14.7 0-26.7 1.7-41.4 4.6 2.9 18.6 2.2 36.7-10.9 50.3l19.5 5.5c-1.7 3.2-2.9 6.3-2.9 9.8 0 21 42.8 2.9 42.8 33.6 0 18.4-36.8 60.1-54.9 60.1-8 0-53.7-50-53.4-60.1l.3-4.6 52.3-11.5c13-2.6 12.3-22.7-2.9-22.7-3.7 0-43.1 9.2-49.4 10.6-2-5.2-7.5-14.1-13.8-14.1-3.2 0-6.3 3.2-9.5 4-9.2 2.6-31 2.9-21.5 20.1L15.9 298.5c-5.5 1.1-8.9 6.3-8.9 11.8 0 6 5.5 10.9 11.5 10.9 8 0 131.3-28.4 147.4-32.2 2.6 3.2 4.6 6.3 7.8 8.6 20.1 14.4 59.8 85.9 76.4 85.9 24.1 0 58-22.4 71.3-41.9 3.2-4.3 6.9-7.5 12.4-6.9.6 13.8-31.6 34.2-33 43.7-1.4 10.2-1 35.2-.3 41.1 26.7 8.1 52-3.6 77.9-2.9 4.3-21 10.6-41.9 9.8-63.5l-.3-9.5c-1.4-34.2-10.9-38.5-34.8-58.6-1.1-1.1-2.6-2.6-3.7-4 2.2-1.4 1.1-1 4.6-1.7 88.5 0 56.3 183.6 111.5 229.9 33.1-15 72.5-27.9 103.5-47.2-29-25.6-52.6-45.7-72.7-79.9zm-196.2 46.1v27.2l11.8-3.4-2.9-23.8zm-68.7-150.4l24.1 61.2 21-13.8-31.3-50.9zm84.4 154.9l2 12.4c9-1.5 58.4-6.6 58.4-14.1 0-1.4-.6-3.2-.9-4.6-26.8 0-36.9 3.8-59.5 6.3z"/></svg>')
+ }
+ .md-typeset .admonition.pied-piper,
+ .md-typeset details.pied-piper {
+ border-color: rgb(43, 155, 70);
+ }
+ .md-typeset .pied-piper > .admonition-title,
+ .md-typeset .pied-piper > summary {
+ background-color: rgba(43, 155, 70, 0.1);
+ }
+ .md-typeset .pied-piper > .admonition-title::before,
+ .md-typeset .pied-piper > summary::before {
+ background-color: rgb(43, 155, 70);
+ -webkit-mask-image: var(--md-admonition-icon--pied-piper);
+ mask-image: var(--md-admonition-icon--pied-piper);
+ }
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_css:
+ - stylesheets/extra.css
+ ```
+
+After applying the customization, you can use the custom admonition type:
+
+``` markdown title="Admonition with custom type"
+!!! pied-piper "Pied Piper"
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+```
+
+<div class="result" markdown>
+
+!!! pied-piper "Pied Piper"
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+
+</div>
+
+ [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/templates/.icons
+ [additional style sheet]: ../customization.md#additional-css
diff --git a/documents/markdown/mkdocs-material/reference_annotations.md b/documents/markdown/mkdocs-material/reference_annotations.md
new file mode 100644
index 0000000..2ee13c1
--- /dev/null
+++ b/documents/markdown/mkdocs-material/reference_annotations.md
@@ -0,0 +1,246 @@
+---
+icon: material/plus-circle
+---
+
+# Annotations
+
+One of the flagship features of Material for MkDocs is the ability to inject
+annotations – little markers that can be added almost anywhere in a document
+and expand a tooltip containing arbitrary Markdown on click or keyboard focus.
+
+## Configuration
+
+This configuration allows to add annotations to all inline- and block-level
+elements, as well as code blocks, and nest annotations inside each other. Add
+the following lines to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - attr_list
+ - md_in_html
+ - pymdownx.superfences
+```
+
+See additional configuration options:
+
+- [Attribute Lists]
+- [Markdown in HTML]
+- [SuperFences]
+
+ [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
+ [Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html
+ [SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
+
+### Annotation icons
+
+<!-- md:version 9.2.0 -->
+
+The annotation icon can be changed to any icon bundled with the theme, or even
+a [custom icon], e.g. to material/arrow-right-circle:. Simply add the following
+lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ icon:
+ annotation: material/arrow-right-circle # (1)!
+```
+
+1. Enter a few keywords to find the perfect icon using our [icon search] and
+ click on the shortcode to copy it to your clipboard:
+
+ <div class="mdx-iconsearch" data-mdx-component="iconsearch">
+ <input class="md-input md-input--stretch mdx-iconsearch__input" placeholder="Search icon" data-mdx-component="iconsearch-query" value="material circle" />
+ <div class="mdx-iconsearch-result" data-mdx-component="iconsearch-result" data-mdx-mode="file">
+ <div class="mdx-iconsearch-result__meta"></div>
+ <ol class="mdx-iconsearch-result__list"></ol>
+ </div>
+ </div>
+
+Some popular choices:
+
+- :material-plus-circle: - `material/plus-circle`
+- :material-circle-medium: - `material/circle-medium`
+- :material-record-circle: - `material/record-circle`
+- :material-arrow-right-circle: - `material/arrow-right-circle`
+- :material-arrow-right-circle-outline: - `material/arrow-right-circle-outline`
+- :material-chevron-right-circle: - `material/chevron-right-circle`
+- :material-star-four-points-circle: - `material/star-four-points-circle`
+- :material-plus-circle-outline: - `material/plus-circle-outline`
+
+ [custom icon]: ../setup/changing-the-logo-and-icons.md#additional-icons
+ [icon search]: icons-emojis.md#search
+
+## Usage
+
+### Using annotations
+
+<!-- md:version 9.2.0 -->
+<!-- md:flag experimental -->
+
+Annotations consist of two parts: a marker, which can be placed anywhere in
+a block marked with the `annotate` class, and content located in a list below
+the block containing the marker:
+
+``` markdown title="Text with annotations"
+Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+{ .annotate }
+
+1. :man_raising_hand: I'm an annotation! I can contain `code`, __formatted
+ text__, images, ... basically anything that can be expressed in Markdown.
+```
+
+<div class="result" markdown>
+
+Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+{ .annotate }
+
+1. :man_raising_hand: I'm an annotation! I can contain `code`, __formatted
+ text__, images, ... basically anything that can be written in Markdown.
+
+</div>
+
+Note that the `annotate` class must only be added to the outermost block. All
+nested elements can use the same list to define annotations, except when
+annotations are nested themselves.
+
+#### in annotations
+
+When [SuperFences] is enabled, annotations can be nested inside annotations by
+adding the `annotate` class to the list item hosting the annotation content,
+repeating the process:
+
+``` markdown title="Text with nested annotations"
+Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+{ .annotate }
+
+1. :man_raising_hand: I'm an annotation! (1)
+ { .annotate }
+
+ 1. :woman_raising_hand: I'm an annotation as well!
+```
+
+<div class="result" markdown>
+
+Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+{ .annotate }
+
+1. :man_raising_hand: I'm an annotation! (1)
+ { .annotate style="margin-bottom: 0" }
+
+ 1. :woman_raising_hand: I'm an annotation as well!
+
+</div>
+
+#### in admonitions
+
+The titles and bodies of [admonitions] can also host annotations by adding the
+`annotate` modifier after the type qualifier, which is similar to how
+[inline blocks] work:
+
+``` markdown title="Admonition with annotations"
+!!! note annotate "Phasellus posuere in sem ut cursus (1)"
+
+ Lorem ipsum dolor sit amet, (2) consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+1. :man_raising_hand: I'm an annotation!
+2. :woman_raising_hand: I'm an annotation as well!
+```
+
+<div class="result" markdown>
+
+!!! note annotate "Phasellus posuere in sem ut cursus (1)"
+
+ Lorem ipsum dolor sit amet, (2) consectetur adipiscing elit. Nulla et
+ euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
+ purus auctor massa, nec semper lorem quam in massa.
+
+1. :man_raising_hand: I'm an annotation!
+2. :woman_raising_hand: I'm an annotation as well!
+
+</div>
+
+ [admonitions]: admonitions.md
+ [inline blocks]: admonitions.md#inline-blocks
+
+#### in content tabs
+
+Content tabs can host annotations by adding the `annotate` class to the block
+of a dedicated content tab (and not to the container, which is not supported):
+
+``` markdown title="Content tabs with annotations"
+=== "Tab 1"
+
+ Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+ { .annotate }
+
+ 1. :man_raising_hand: I'm an annotation!
+
+=== "Tab 2"
+
+ Phasellus posuere in sem ut cursus (1)
+ { .annotate }
+
+ 1. :woman_raising_hand: I'm an annotation as well!
+```
+
+<div class="result" markdown>
+
+=== "Tab 1"
+
+ Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+ { .annotate }
+
+ 1. :man_raising_hand: I'm an annotation!
+
+=== "Tab 2"
+
+ Phasellus posuere in sem ut cursus (1)
+ { .annotate }
+
+ 1. :woman_raising_hand: I'm an annotation as well!
+
+</div>
+
+#### in everything else
+
+The [Attribute Lists] extension is the key ingredient for adding annotations to
+most elements, but it has some [limitations]. However, it's always possible to
+leverage the [Markdown in HTML] extension to wrap arbitrary elements with a
+`div` with the `annotate` class:
+
+```` html title="HTML with annotations"
+<div class="annotate" markdown>
+
+> Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+
+</div>
+
+1. :man_raising_hand: I'm an annotation!
+````
+
+<div class="result" markdown>
+ <div class="annotate" markdown>
+
+> Lorem ipsum dolor sit amet, (1) consectetur adipiscing elit.
+
+ </div>
+
+1. :man_raising_hand: I'm an annotation!
+
+</div>
+
+With this trick, annotations can also be added to blockquotes, lists, and many
+other elements that are not supported by the [Attribute Lists] extension.
+Furthermore, note that [code blocks follow different semantics].
+
+!!! warning "Known limitations"
+
+ Please note that annotations currently don't work in [data tables] as
+ reported in #3453, as data tables are scrollable elements and positioning
+ is very tricky to get right. This might be fixed in the future.
+
+ [limitations]: https://python-markdown.github.io/extensions/attr_list/#limitations
+ [code blocks follow different semantics]: code-blocks.md#adding-annotations
+ [data tables]: data-tables.md
diff --git a/documents/markdown/mkdocs-material/reference_buttons.md b/documents/markdown/mkdocs-material/reference_buttons.md
new file mode 100644
index 0000000..03dcb6d
--- /dev/null
+++ b/documents/markdown/mkdocs-material/reference_buttons.md
@@ -0,0 +1,84 @@
+---
+icon: material/button-cursor
+---
+
+# Buttons
+
+Material for MkDocs provides dedicated styles for primary and secondary buttons
+that can be added to any link, `label` or `button` element. This is especially
+useful for documents or landing pages with dedicated _call-to-actions_.
+
+## Configuration
+
+This configuration allows to add attributes to all inline- and block-level
+elements with a simple syntax, turning any link into a button. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - attr_list
+```
+
+See additional configuration options:
+
+- [Attribute Lists]
+
+ [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
+
+## Usage
+
+### Adding buttons
+
+In order to render a link as a button, suffix it with curly braces and add the
+`.md-button` class selector to it. The button will receive the selected
+[primary color] and [accent color] if active.
+
+``` markdown title="Button"
+[Subscribe to our newsletter](#){ .md-button }
+```
+
+<div class="result" markdown>
+
+[Subscribe to our newsletter][Demo]{ .md-button }
+
+</div>
+
+ [primary color]: ../setup/changing-the-colors.md#primary-color
+ [accent color]: ../setup/changing-the-colors.md#accent-color
+ [Demo]: javascript:alert$.next("Demo")
+
+### Adding primary buttons
+
+If you want to display a filled, primary button (like on the [landing page]
+of Material for MkDocs), add both, the `.md-button` and `.md-button--primary`
+CSS class selectors.
+
+``` markdown title="Button, primary"
+[Subscribe to our newsletter](#){ .md-button .md-button--primary }
+```
+
+<div class="result" markdown>
+
+[Subscribe to our newsletter][Demo]{ .md-button .md-button--primary }
+
+</div>
+
+ [landing page]: ../index.md
+
+### Adding icon buttons
+
+Of course, icons can be added to all types of buttons by using the [icon syntax]
+together with any valid icon shortcode, which can be easily found with a few keystrokes through our [icon search].
+
+``` markdown title="Button with icon"
+[Send :fontawesome-solid-paper-plane:](#){ .md-button }
+```
+
+<div class="result" markdown>
+
+[Send :fontawesome-solid-paper-plane:][Demo]{ .md-button }
+
+</div>
+
+ [icon syntax]: icons-emojis.md#using-icons
+ [icon search]: icons-emojis.md#search
diff --git a/documents/markdown/mkdocs-material/reference_code-blocks.md b/documents/markdown/mkdocs-material/reference_code-blocks.md
new file mode 100644
index 0000000..7342733
--- /dev/null
+++ b/documents/markdown/mkdocs-material/reference_code-blocks.md
@@ -0,0 +1,546 @@
+---
+icon: material/code-json
+---
+
+# Code blocks
+
+Code blocks and examples are an essential part of technical project
+documentation. Material for MkDocs provides different ways to set up syntax
+highlighting for code blocks, either during build time using [Pygments] or
+during runtime using a JavaScript syntax highlighter.
+
+ [Pygments]: https://pygments.org
+
+## Configuration
+
+This configuration enables syntax highlighting on code blocks and inline code
+blocks, and allows to include source code directly from other files. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.highlight:
+ anchor_linenums: true
+ line_spans: __span
+ pygments_lang_class: true
+ - pymdownx.inlinehilite
+ - pymdownx.snippets
+ - pymdownx.superfences
+```
+
+The following sections discuss how to use different syntax highlighting features
+with [Pygments], the recommended highlighter, so they don't apply when using a
+JavaScript syntax highlighter.
+
+See additional configuration options:
+
+- [Highlight]
+- [InlineHilite]
+- [SuperFences]
+- [Snippets]
+
+ [Highlight]: ../setup/extensions/python-markdown-extensions.md#highlight
+ [InlineHilite]: ../setup/extensions/python-markdown-extensions.md#inlinehilite
+ [SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
+ [Snippets]: ../setup/extensions/python-markdown-extensions.md#snippets
+
+### Code copy button
+
+<!-- md:version 9.0.0 -->
+<!-- md:feature -->
+
+Code blocks can automatically render a button on the right side to allow the
+user to copy a code block's contents to the clipboard. Add the following to
+`mkdocs.yml` to enable them globally:
+
+``` yaml
+theme:
+ features:
+ - content.code.copy
+```
+
+??? info "Enabling or disabling code copy buttons for a specific code block"
+
+ If you don't want to enable code copy buttons globally, you can enable them
+ for a specific code block by using a slightly different syntax based on the
+ [Attribute Lists] extension:
+
+ ```` yaml
+ ``` { .yaml .copy }
+ # Code block content
+ ```
+ ````
+
+ Note that there must be a language shortcode, which has to come first and
+ must also be prefixed by a `.`. Similarly, the copy button can also be
+ disabled for a specific code block:
+
+ ```` { .yaml .no-copy }
+ ``` { .yaml .no-copy }
+ # Code block content
+ ```
+ ````
+
+ To enable or disable the copy button without syntax highlighting, you can
+ use the `.text` language shortcode, which doesn't highlight anything.
+
+### Code selection button
+
+<!-- md:version 9.7.0 -->
+<!-- md:flag experimental -->
+
+Code blocks can include a button to allow for the selection of line ranges by
+the user, which is perfect for linking to a specific subsection of a code block. This allows the user to apply [line highlighting] dynamically. Add the following
+to `mkdocs.yml` to enable it globally:
+
+``` yaml
+theme:
+ features:
+ - content.code.select
+```
+
+??? info "Enabling or disabling code selection buttons for a specific code block"
+
+ If you don't want to enable code selection buttons globally, you can enable
+ them for a specific code block by using a slightly different syntax based on
+ the [Attribute Lists] extension:
+
+ ```` yaml
+ ``` { .yaml .select }
+ # Code block content
+ ```
+ ````
+
+ Note that the language shortcode which has to come first must now also be
+ prefixed by a `.`. Similarly, the selection button can also be disabled for
+ a specific code block:
+
+ ```` { .yaml .no-select }
+ ``` { .yaml .no-select }
+ # Code block content
+ ```
+ ````
+
+ [line highlighting]: #highlighting-specific-lines
+
+### Code annotations
+
+<!-- md:version 8.0.0 -->
+<!-- md:feature -->
+
+Code annotations offer a comfortable and friendly way to attach arbitrary
+content to specific sections of code blocks by adding numeric markers in block
+and inline comments in the language of the code block. Add the following to
+`mkdocs.yml` to enable them globally:
+
+``` yaml
+theme:
+ features:
+ - content.code.annotate # (1)!
+```
+
+1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
+ text__, images, ... basically anything that can be written in Markdown.
+
+??? info "Enabling code annotations for a specific code block"
+
+ If you don't want to enable code annotations globally, because you don't
+ like the automatic inlining behavior, you can enable them for a specific
+ code block by using a slightly different syntax based on the
+ [Attribute Lists] extension:
+
+ ```` yaml
+ ``` { .yaml .annotate }
+ # Code block content
+ ```
+ ````
+
+ Note that the language shortcode which has to come first must now also be
+ prefixed by a `.`.
+
+ [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
+
+#### Custom selectors
+
+<!-- md:version 9.7.0 -->
+<!-- md:flag experimental -->
+
+Normally, code annotations can only be [placed in comments], as comments can be
+considered safe for placement. However, sometimes it might be necessary to place
+annotations in parts of the code block where comments are not allowed, e.g. in
+strings.
+
+Additional selectors can be set per-language:
+
+``` yaml
+extra:
+ annotate:
+ json: [.s2] # (1)!
+```
+
+1. [`.s2`][s2] is the name of the lexeme that [Pygments] generates for double-quoted
+ strings. If you want to use a code annotation in another lexeme than a
+ comment, inspect the code block and determine which lexeme needs to be added
+ to the list of additional selectors.
+
+ __Important__: Code annotations cannot be split between lexemes.
+
+Now, code annotations can be used from within strings in JSON:
+
+``` json
+{
+ "key": "value (1)"
+}
+```
+
+1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
+ text__, images, ... basically anything that can be written in Markdown.
+
+ [placed in comments]: #adding-annotations
+ [s2]: https://github.com/squidfunk/mkdocs-material/blob/87d5ca487b9d9ab95c41ee72813149d214048693/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss#L45
+
+## Usage
+
+Code blocks must be enclosed with two separate lines containing three backticks.
+To add syntax highlighting to those blocks, add the language shortcode directly
+after the opening block. See the [list of available lexers] to find the
+shortcode for a given language:
+
+```` markdown title="Code block"
+``` py
+import tensorflow as tf
+```
+````
+
+<div class="result" markdown>
+
+``` py
+import tensorflow as tf
+```
+
+</div>
+
+ [list of available lexers]: https://pygments.org/docs/lexers/
+
+### Adding a title
+
+In order to provide additional context, a custom title can be added to a code
+block by using the `title="<custom title>"` option directly after the shortcode,
+e.g. to display the name of a file:
+
+```` markdown title="Code block with title"
+``` py title="bubble_sort.py"
+def bubble_sort(items):
+ for i in range(len(items)):
+ for j in range(len(items) - 1 - i):
+ if items[j] > items[j + 1]:
+ items[j], items[j + 1] = items[j + 1], items[j]
+```
+````
+
+<div class="result" markdown>
+
+``` py title="bubble_sort.py"
+def bubble_sort(items):
+ for i in range(len(items)):
+ for j in range(len(items) - 1 - i):
+ if items[j] > items[j + 1]:
+ items[j], items[j + 1] = items[j + 1], items[j]
+```
+
+</div>
+
+### Adding annotations
+
+Code annotations can be placed anywhere in a code block where a comment for the
+language of the block can be placed, e.g. for JavaScript in `#!js // ...` and
+`#!js /* ... */`, for YAML in `#!yaml # ...`, etc.[^1]:
+
+ [^1]:
+ Code annotations require syntax highlighting with [Pygments] – they're
+ currently not compatible with JavaScript syntax highlighters, or languages
+ that do not have comments in their grammar. However, we're actively working
+ on supporting alternate ways of defining code annotations, allowing to
+ always place code annotations at the end of lines.
+
+```` markdown title="Code block with annotation"
+``` yaml
+theme:
+ features:
+ - content.code.annotate # (1)
+```
+
+1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
+ text__, images, ... basically anything that can be written in Markdown.
+````
+
+<div class="result" markdown>
+
+``` yaml
+theme:
+ features:
+ - content.code.annotate # (1)
+```
+
+1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
+ text__, images, ... basically anything that can be written in Markdown.
+
+</div>
+
+#### Stripping comments
+
+<!-- md:version 8.5.0 -->
+<!-- md:flag experimental -->
+
+If you wish to strip the comment characters surrounding a code annotation,
+simply add an `!` after the closing parenthesis of the code annotation:
+
+```` markdown title="Code block with annotation, stripped"
+``` yaml
+# (1)!
+```
+
+1. Look ma, less line noise!
+````
+
+<div class="result" markdown>
+
+``` yaml
+# (1)!
+```
+
+1. Look ma, less line noise!
+
+</div>
+
+Note that this only allows for a single code annotation to be rendered per
+comment. If you want to add multiple code annotations, comments cannot be
+stripped for technical reasons.
+
+### Adding line numbers
+
+Line numbers can be added to a code block by using the `linenums="<start>"`
+option directly after the shortcode, whereas `<start>` represents the starting
+line number. A code block can start from a line number other than `1`, which
+allows to split large code blocks for readability:
+
+```` markdown title="Code block with line numbers"
+``` py linenums="1"
+def bubble_sort(items):
+ for i in range(len(items)):
+ for j in range(len(items) - 1 - i):
+ if items[j] > items[j + 1]:
+ items[j], items[j + 1] = items[j + 1], items[j]
+```
+````
+
+<div class="result" markdown>
+
+``` py linenums="1"
+def bubble_sort(items):
+ for i in range(len(items)):
+ for j in range(len(items) - 1 - i):
+ if items[j] > items[j + 1]:
+ items[j], items[j + 1] = items[j + 1], items[j]
+```
+
+</div>
+
+### Highlighting specific lines
+
+Specific lines can be highlighted by passing the line numbers to the `hl_lines`
+argument placed right after the language shortcode. Note that line counts start
+at `1`, regardless of the starting line number specified as part of
+[`linenums`][Adding line numbers]:
+
+=== "Lines"
+
+ ```` markdown title="Code block with highlighted lines"
+ ``` py hl_lines="2 3"
+ def bubble_sort(items):
+ for i in range(len(items)):
+ for j in range(len(items) - 1 - i):
+ if items[j] > items[j + 1]:
+ items[j], items[j + 1] = items[j + 1], items[j]
+ ```
+ ````
+
+ <div class="result" markdown>
+
+ ``` py linenums="1" hl_lines="2 3"
+ def bubble_sort(items):
+ for i in range(len(items)):
+ for j in range(len(items) - 1 - i):
+ if items[j] > items[j + 1]:
+ items[j], items[j + 1] = items[j + 1], items[j]
+ ```
+
+ </div>
+
+=== "Line ranges"
+
+ ```` markdown title="Code block with highlighted line range"
+ ``` py hl_lines="3-5"
+ def bubble_sort(items):
+ for i in range(len(items)):
+ for j in range(len(items) - 1 - i):
+ if items[j] > items[j + 1]:
+ items[j], items[j + 1] = items[j + 1], items[j]
+ ```
+ ````
+
+ <div class="result" markdown>
+
+ ``` py linenums="1" hl_lines="3-5"
+ def bubble_sort(items):
+ for i in range(len(items)):
+ for j in range(len(items) - 1 - i):
+ if items[j] > items[j + 1]:
+ items[j], items[j + 1] = items[j + 1], items[j]
+ ```
+
+ </div>
+
+ [Adding line numbers]: #adding-line-numbers
+
+### Highlighting inline code blocks
+
+When [InlineHilite] is enabled, syntax highlighting can be applied to inline
+code blocks by prefixing them with a shebang, i.e. `#!`, directly followed by
+the corresponding [language shortcode][list of available lexers].
+
+``` markdown title="Inline code block"
+The `#!python range()` function is used to generate a sequence of numbers.
+```
+
+<div class="result" markdown>
+
+The `#!python range()` function is used to generate a sequence of numbers.
+
+</div>
+
+### Embedding external files
+
+When [Snippets] is enabled, content from other files (including source files)
+can be embedded by using the [`--8<--` notation][Snippets notation] directly
+from within a code block:
+
+```` markdown title="Code block with external content"
+``` title=".browserslistrc"
+;--8<-- ".browserslistrc"
+```
+````
+
+<div class="result" markdown>
+
+``` title=".browserslistrc"
+last 4 years
+```
+
+</div>
+
+ [Snippets notation]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets-notation
+
+## Customization
+
+### Custom syntax theme
+
+If [Pygments] is used, Material for MkDocs provides the [styles for code blocks]
+[colors], which are built with a custom and well-balanced palette that works
+equally well for both [color schemes]:
+
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-number-color) " } `--md-code-hl-number-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-special-color) " } `--md-code-hl-special-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-function-color) " } `--md-code-hl-function-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-constant-color) " } `--md-code-hl-constant-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-keyword-color) " } `--md-code-hl-keyword-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-string-color) " } `--md-code-hl-string-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-name-color) " } `--md-code-hl-name-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-operator-color) " } `--md-code-hl-operator-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-punctuation-color) " } `--md-code-hl-punctuation-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-comment-color) " } `--md-code-hl-comment-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-generic-color) " } `--md-code-hl-generic-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-variable-color) " } `--md-code-hl-variable-color`
+
+Code block foreground, background and line highlight colors are defined via:
+
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-fg-color) " } `--md-code-fg-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-bg-color) " } `--md-code-bg-color`
+- :material-checkbox-blank-circle:{ style="color: var(--md-code-hl-color) " } `--md-code-hl-color`
+
+Let's say you want to change the color of `#!js "strings"`. While there are
+several [types of string tokens], they use the same color. You can assign
+a new color by using an [additional style sheet]:
+
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+ ``` css
+ :root > * {
+ --md-code-hl-string-color: #0FF1CE;
+ }
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_css:
+ - stylesheets/extra.css
+ ```
+
+If you want to tweak a specific type of string, e.g. ``#!js `backticks` ``, you
+can lookup the specific CSS class name in the [syntax theme definition], and
+override it as part of your [additional style sheet]:
+
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+ ``` css
+ .highlight .sb {
+ color: #0FF1CE;
+ }
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_css:
+ - stylesheets/extra.css
+ ```
+
+ [colors]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/assets/stylesheets/main/_colors.scss
+ [color schemes]: ../setup/changing-the-colors.md#color-scheme
+ [types of string tokens]: https://pygments.org/docs/tokens/#literals
+ [additional style sheet]: ../customization.md#additional-css
+ [syntax theme definition]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
+
+### Annotation tooltip width
+
+If you have a lot of content hosted inside your code annotations, it can be a
+good idea to increase the width of the tooltip by adding the following as part
+of an [additional style sheet]:
+
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+ ``` css
+ :root {
+ --md-tooltip-width: 600px;
+ }
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_css:
+ - stylesheets/extra.css
+ ```
+
+This will render annotations with a larger width:
+
+<div style="--md-tooltip-width: 600px;" markdown>
+
+``` yaml
+# (1)!
+```
+
+1. Muuuuuuuuuuuuuuuch more space for content
+
+</div>
diff --git a/documents/markdown/mkdocs-material/reference_content-tabs.md b/documents/markdown/mkdocs-material/reference_content-tabs.md
new file mode 100644
index 0000000..fd8f73f
--- /dev/null
+++ b/documents/markdown/mkdocs-material/reference_content-tabs.md
@@ -0,0 +1,245 @@
+---
+icon: material/tab
+---
+
+# Content tabs
+
+Sometimes, it's desirable to group alternative content under different tabs,
+e.g. when describing how to access an API from different languages or
+environments. Material for MkDocs allows for beautiful and functional tabs,
+grouping code blocks and other content.
+
+## Configuration
+
+This configuration enables content tabs, and allows to nest arbitrary content
+inside content tabs, including code blocks and ... more content tabs! Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.superfences
+ - pymdownx.tabbed:
+ alternate_style: true
+```
+
+See additional configuration options:
+
+- [SuperFences]
+- [Tabbed]
+
+ [SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
+ [Tabbed]: ../setup/extensions/python-markdown-extensions.md#tabbed
+
+### Anchor links
+
+<!-- md:version 9.5.0 -->
+<!-- md:flag experimental -->
+
+In order to link to content tabs and share them more easily, an anchor link is
+automatically added to each content tab, which you can copy via right click or
+open in a new tab:
+
+=== "Open me in a new tab ..."
+
+=== "... or me ..."
+
+=== "... or even me"
+
+You can copy the link of the tab and create a link on the same or any other
+page. For example, you can [jump to the third tab above this paragraph][tab_1].
+
+!!! tip "Readable anchor links"
+
+ [Python Markdown Extensions] 9.6 adds support for [slugification] of
+ content tabs, which produces nicer looking and more readable anchor links.
+ Enable the slugify function with the following lines:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.tabbed:
+ slugify: !!python/object/apply:pymdownx.slugs.slugify
+ kwds:
+ case: lower
+ ```
+
+ For more information, please [see the extension guide][slugification].
+
+ [tab_1]: #anchor-links--or-even-me
+ [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
+ [slugification]: ../setup/extensions/python-markdown-extensions.md#+pymdownx.tabbed.slugify
+
+### Linked content tabs
+
+<!-- md:version 8.3.0 -->
+<!-- md:feature -->
+
+When enabled, all content tabs across the whole documentation site will be
+linked and switch to the same label when the user clicks on a tab. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - content.tabs.link
+```
+
+Content tabs are linked based on their label, not offset. This means that all
+tabs with the same label will be activated when a user clicks a content tab
+regardless of order inside a container. Furthermore, this feature is fully
+integrated with [instant loading] and persisted across page loads.
+
+=== "Feature enabled"
+
+ [![Linked content tabs enabled]][Linked content tabs enabled]
+
+=== "Feature disabled"
+
+ [![Linked content tabs disabled]][Linked content tabs disabled]
+
+ [instant loading]: ../setup/setting-up-navigation.md#instant-loading
+ [Linked content tabs enabled]: ../assets/screenshots/content-tabs-link.png
+ [Linked content tabs disabled]: ../assets/screenshots/content-tabs.png
+
+## Usage
+
+### Grouping code blocks
+
+Code blocks are one of the primary targets to be grouped, and can be considered
+a special case of content tabs, as tabs with a single code block are always
+rendered without horizontal spacing:
+
+``` title="Content tabs with code blocks"
+=== "C"
+
+ ``` c
+ #include <stdio.h>
+
+ int main(void) {
+ printf("Hello world!\n");
+ return 0;
+ }
+ ```
+
+=== "C++"
+
+ ``` c++
+ #include <iostream>
+
+ int main(void) {
+ std::cout << "Hello world!" << std::endl;
+ return 0;
+ }
+ ```
+```
+
+<div class="result" markdown>
+
+=== "C"
+
+ ``` c
+ #include <stdio.h>
+
+ int main(void) {
+ printf("Hello world!\n");
+ return 0;
+ }
+ ```
+
+=== "C++"
+
+ ``` c++
+ #include <iostream>
+
+ int main(void) {
+ std::cout << "Hello world!" << std::endl;
+ return 0;
+ }
+ ```
+
+</div>
+
+### Grouping other content
+
+When a content tab contains more than one code block, it is rendered with
+horizontal spacing. Vertical spacing is never added, but can be achieved
+by nesting tabs in other blocks:
+
+``` title="Content tabs"
+=== "Unordered list"
+
+ * Sed sagittis eleifend rutrum
+ * Donec vitae suscipit est
+ * Nulla tempor lobortis orci
+
+=== "Ordered list"
+
+ 1. Sed sagittis eleifend rutrum
+ 2. Donec vitae suscipit est
+ 3. Nulla tempor lobortis orci
+```
+
+<div class="result" markdown>
+
+=== "Unordered list"
+
+ * Sed sagittis eleifend rutrum
+ * Donec vitae suscipit est
+ * Nulla tempor lobortis orci
+
+=== "Ordered list"
+
+ 1. Sed sagittis eleifend rutrum
+ 2. Donec vitae suscipit est
+ 3. Nulla tempor lobortis orci
+
+</div>
+
+### Embedded content
+
+When [SuperFences] is enabled, content tabs can contain arbitrary nested
+content, including further content tabs, and can be nested in other blocks like
+[admonitions] or blockquotes:
+
+``` title="Content tabs in admonition"
+!!! example
+
+ === "Unordered List"
+
+ ``` markdown
+ * Sed sagittis eleifend rutrum
+ * Donec vitae suscipit est
+ * Nulla tempor lobortis orci
+ ```
+
+ === "Ordered List"
+
+ ``` markdown
+ 1. Sed sagittis eleifend rutrum
+ 2. Donec vitae suscipit est
+ 3. Nulla tempor lobortis orci
+ ```
+```
+
+<div class="result" markdown>
+
+!!! example
+
+ === "Unordered List"
+
+ ``` markdown
+ * Sed sagittis eleifend rutrum
+ * Donec vitae suscipit est
+ * Nulla tempor lobortis orci
+ ```
+
+ === "Ordered List"
+
+ ``` markdown
+ 1. Sed sagittis eleifend rutrum
+ 2. Donec vitae suscipit est
+ 3. Nulla tempor lobortis orci
+ ```
+
+</div>
+
+ [admonitions]: admonitions.md
diff --git a/documents/markdown/mkdocs-material/reference_data-tables.md b/documents/markdown/mkdocs-material/reference_data-tables.md
new file mode 100644
index 0000000..fd2db1b
--- /dev/null
+++ b/documents/markdown/mkdocs-material/reference_data-tables.md
@@ -0,0 +1,191 @@
+---
+icon: material/table-edit
+---
+
+# Data tables
+
+Material for MkDocs defines default styles for data tables – an excellent way
+of rendering tabular data in project documentation. Furthermore, customizations
+like [sortable tables] can be achieved with a third-party library and some
+[additional JavaScript].
+
+ [sortable tables]: #sortable-tables
+ [additional JavaScript]: ../customization.md#additional-javascript
+
+## Configuration
+
+This configuration enables Markdown table support, which should normally be
+enabled by default, but to be sure, add the following lines to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - tables
+```
+
+See additional configuration options:
+
+- [Tables]
+
+ [Tables]: ../setup/extensions/python-markdown.md#tables
+
+## Usage
+
+Data tables can be used at any position in your project documentation and can
+contain arbitrary Markdown, including inline code blocks, as well as [icons and
+emojis]:
+
+``` markdown title="Data table"
+| Method | Description |
+| ----------- | ------------------------------------ |
+| `GET` | :material-check: Fetch resource |
+| `PUT` | :material-check-all: Update resource |
+| `DELETE` | :material-close: Delete resource |
+```
+
+<div class="result" markdown>
+
+| Method | Description |
+| ----------- | ------------------------------------ |
+| `GET` | :material-check: Fetch resource |
+| `PUT` | :material-check-all: Update resource |
+| `DELETE` | :material-close: Delete resource |
+
+</div>
+
+ [icons and emojis]: icons-emojis.md
+
+### Column alignment
+
+If you want to align a specific column to the `left`, `center` or `right`, you
+can use the [regular Markdown syntax] placing `:` characters at the beginning
+and/or end of the divider.
+
+=== "Left"
+
+ ``` markdown hl_lines="2" title="Data table, columns aligned to left"
+ | Method | Description |
+ | :---------- | :----------------------------------- |
+ | `GET` | :material-check: Fetch resource |
+ | `PUT` | :material-check-all: Update resource |
+ | `DELETE` | :material-close: Delete resource |
+ ```
+
+ <div class="result" markdown>
+
+ | Method | Description |
+ | :---------- | :----------------------------------- |
+ | `GET` | :material-check: Fetch resource |
+ | `PUT` | :material-check-all: Update resource |
+ | `DELETE` | :material-close: Delete resource |
+
+ </div>
+
+=== "Center"
+
+ ``` markdown hl_lines="2" title="Data table, columns centered"
+ | Method | Description |
+ | :---------: | :----------------------------------: |
+ | `GET` | :material-check: Fetch resource |
+ | `PUT` | :material-check-all: Update resource |
+ | `DELETE` | :material-close: Delete resource |
+ ```
+
+ <div class="result" markdown>
+
+ | Method | Description |
+ | :---------: | :----------------------------------: |
+ | `GET` | :material-check: Fetch resource |
+ | `PUT` | :material-check-all: Update resource |
+ | `DELETE` | :material-close: Delete resource |
+
+ </div>
+
+=== "Right"
+
+ ``` markdown hl_lines="2" title="Data table, columns aligned to right"
+ | Method | Description |
+ | ----------: | -----------------------------------: |
+ | `GET` | :material-check: Fetch resource |
+ | `PUT` | :material-check-all: Update resource |
+ | `DELETE` | :material-close: Delete resource |
+ ```
+
+ <div class="result" markdown>
+
+ | Method | Description |
+ | ----------: | -----------------------------------: |
+ | `GET` | :material-check: Fetch resource |
+ | `PUT` | :material-check-all: Update resource |
+ | `DELETE` | :material-close: Delete resource |
+
+ </div>
+
+ [regular Markdown syntax]: https://www.markdownguide.org/extended-syntax/#tables
+
+## Customization
+
+### Sortable tables
+
+If you want to make data tables sortable, you can add [tablesort], which is
+natively integrated with Material for MkDocs and will also work with [instant
+loading] via [additional JavaScript]:
+
+=== ":octicons-file-code-16: `docs/javascripts/tablesort.js`"
+
+ ``` js
+ document$.subscribe(function() {
+ var tables = document.querySelectorAll("article table:not([class])")
+ tables.forEach(function(table) {
+ new Tablesort(table)
+ })
+ })
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_javascript:
+ - https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js
+ - javascripts/tablesort.js
+ ```
+
+After applying the customization, data tables can be sorted by clicking on a
+column:
+
+``` markdown title="Data table, columns sortable"
+| Method | Description |
+| ----------- | ------------------------------------ |
+| `GET` | :material-check: Fetch resource |
+| `PUT` | :material-check-all: Update resource |
+| `DELETE` | :material-close: Delete resource |
+```
+
+<div class="result" markdown>
+
+| Method | Description |
+| ----------- | ------------------------------------ |
+| `GET` | :material-check: Fetch resource |
+| `PUT` | :material-check-all: Update resource |
+| `DELETE` | :material-close: Delete resource |
+
+</div>
+
+Note that [tablesort] provides alternative comparison implementations like
+numbers, filesizes, dates and month names. See the [tablesort documentation]
+[tablesort] for more information.
+
+<script src="https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js"></script>
+<script>
+ var tables = document.querySelectorAll("article table")
+ new Tablesort(tables.item(tables.length - 1));
+</script>
+
+ [tablesort]: http://tristen.ca/tablesort/demo/
+ [instant loading]: ../setup/setting-up-navigation.md#instant-loading
+
+### Import table from file
+
+The plugin [mkdocs-table-reader-plugin][table-reader-docs] allows you to
+import data from a CSV or Excel file.
+
+ [table-reader-docs]: https://timvink.github.io/mkdocs-table-reader-plugin/
diff --git a/documents/markdown/mkdocs-material/reference_diagrams.md b/documents/markdown/mkdocs-material/reference_diagrams.md
new file mode 100644
index 0000000..da8b364
--- /dev/null
+++ b/documents/markdown/mkdocs-material/reference_diagrams.md
@@ -0,0 +1,316 @@
+---
+icon: material/graph-outline
+---
+
+# Diagrams
+
+Diagrams help to communicate complex relationships and interconnections between
+different technical components, and are a great addition to project
+documentation. Material for MkDocs integrates with [Mermaid.js], a very
+popular and flexible solution for drawing diagrams.
+
+ [Mermaid.js]: https://mermaid.js.org/
+
+## Configuration
+
+<!-- md:version 8.2.0 -->
+
+This configuration enables native support for [Mermaid.js] diagrams. Material
+for MkDocs will automatically initialize the JavaScript runtime when a page
+includes a `mermaid` code block:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.superfences:
+ custom_fences:
+ - name: mermaid
+ class: mermaid
+ format: !!python/name:pymdownx.superfences.fence_code_format
+```
+
+No further configuration is necessary. Advantages over a custom integration:
+
+- [x] Works with [instant loading] without any additional effort
+- [x] Diagrams automatically use fonts and colors defined in `mkdocs.yml`[^1]
+- [x] Fonts and colors can be customized with [additional style sheets]
+- [x] Support for both, light and dark color schemes – _try it on this page!_
+
+ [^1]:
+ While all [Mermaid.js] features should work out-of-the-box, Material for
+ MkDocs will currently only adjust the fonts and colors for flowcharts,
+ sequence diagrams, class diagrams, state diagrams and entity relationship
+ diagrams. See the section on [other diagrams] for more information why this
+ is currently not implemented for all diagrams.
+
+ [instant loading]: ../setup/setting-up-navigation.md#instant-loading
+ [additional style sheets]: ../customization.md#additional-css
+ [other diagrams]: #other-diagram-types
+
+## Usage
+
+### Using flowcharts
+
+[Flowcharts] are diagrams that represent workflows or processes. The steps
+are rendered as nodes of various kinds and are connected by edges, describing
+the necessary order of steps:
+
+```` markdown title="Flow chart"
+``` mermaid
+graph LR
+ A[Start] --> B{Error?};
+ B -->|Yes| C[Hmm...];
+ C --> D[Debug];
+ D --> B;
+ B ---->|No| E[Yay!];
+```
+````
+
+<div class="result" markdown>
+
+``` mermaid
+graph LR
+ A[Start] --> B{Error?};
+ B -->|Yes| C[Hmm...];
+ C --> D[Debug];
+ D --> B;
+ B ---->|No| E[Yay!];
+```
+
+</div>
+
+ [Flowcharts]: https://mermaid.js.org/syntax/flowchart.html
+
+### Using sequence diagrams
+
+[Sequence diagrams] describe a specific scenario as sequential interactions
+between multiple objects or actors, including the messages that are exchanged
+between those actors:
+
+```` markdown title="Sequence diagram"
+``` mermaid
+sequenceDiagram
+ autonumber
+ Alice->>John: Hello John, how are you?
+ loop Healthcheck
+ John->>John: Fight against hypochondria
+ end
+ Note right of John: Rational thoughts!
+ John-->>Alice: Great!
+ John->>Bob: How about you?
+ Bob-->>John: Jolly good!
+```
+````
+
+<div class="result" markdown>
+
+``` mermaid
+sequenceDiagram
+ autonumber
+ Alice->>John: Hello John, how are you?
+ loop Healthcheck
+ John->>John: Fight against hypochondria
+ end
+ Note right of John: Rational thoughts!
+ John-->>Alice: Great!
+ John->>Bob: How about you?
+ Bob-->>John: Jolly good!
+```
+
+</div>
+
+ [Sequence diagrams]: https://mermaid.js.org/syntax/sequenceDiagram.html
+
+### Using state diagrams
+
+[State diagrams] are a great tool to describe the behavior of a system,
+decomposing it into a finite number of states, and transitions between those
+states:
+
+```` markdown title="State diagram"
+``` mermaid
+stateDiagram-v2
+ state fork_state <<fork>>
+ [*] --> fork_state
+ fork_state --> State2
+ fork_state --> State3
+
+ state join_state <<join>>
+ State2 --> join_state
+ State3 --> join_state
+ join_state --> State4
+ State4 --> [*]
+```
+````
+
+<div class="result" markdown>
+
+``` mermaid
+stateDiagram-v2
+ state fork_state <<fork>>
+ [*] --> fork_state
+ fork_state --> State2
+ fork_state --> State3
+
+ state join_state <<join>>
+ State2 --> join_state
+ State3 --> join_state
+ join_state --> State4
+ State4 --> [*]
+```
+
+</div>
+
+ [State diagrams]: https://mermaid.js.org/syntax/stateDiagram.html
+
+### Using class diagrams
+
+[Class diagrams] are central to object oriented programming, describing the
+structure of a system by modelling entities as classes and relationships between
+them:
+
+```` markdown title="Class diagram"
+``` mermaid
+classDiagram
+ Person <|-- Student
+ Person <|-- Professor
+ Person : +String name
+ Person : +String phoneNumber
+ Person : +String emailAddress
+ Person: +purchaseParkingPass()
+ Address "1" <-- "0..1" Person:lives at
+ class Student{
+ +int studentNumber
+ +int averageMark
+ +isEligibleToEnrol()
+ +getSeminarsTaken()
+ }
+ class Professor{
+ +int salary
+ }
+ class Address{
+ +String street
+ +String city
+ +String state
+ +int postalCode
+ +String country
+ -validate()
+ +outputAsLabel()
+ }
+```
+````
+
+<div class="result" markdown>
+
+``` mermaid
+classDiagram
+ Person <|-- Student
+ Person <|-- Professor
+ Person : +String name
+ Person : +String phoneNumber
+ Person : +String emailAddress
+ Person: +purchaseParkingPass()
+ Address "1" <-- "0..1" Person:lives at
+ class Student{
+ +int studentNumber
+ +int averageMark
+ +isEligibleToEnrol()
+ +getSeminarsTaken()
+ }
+ class Professor{
+ +int salary
+ }
+ class Address{
+ +String street
+ +String city
+ +String state
+ +int postalCode
+ +String country
+ -validate()
+ +outputAsLabel()
+ }
+```
+
+</div>
+
+ [Class diagrams]: https://mermaid.js.org/syntax/classDiagram.html
+
+### Using entity-relationship diagrams
+
+An [entity-relationship diagram] is composed of entity types and specifies
+relationships that exist between entities. It describes inter-related things in
+a specific domain of knowledge:
+
+```` markdown title="Entity-relationship diagram"
+``` mermaid
+erDiagram
+ CUSTOMER ||--o{ ORDER : places
+ ORDER ||--|{ LINE-ITEM : contains
+ LINE-ITEM {
+ string name
+ int pricePerUnit
+ }
+ CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
+```
+````
+
+<div class="result" markdown>
+
+``` mermaid
+erDiagram
+ CUSTOMER ||--o{ ORDER : places
+ ORDER ||--|{ LINE-ITEM : contains
+ LINE-ITEM {
+ string name
+ int pricePerUnit
+ }
+ CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
+```
+
+</div>
+
+ [entity-relationship diagram]: https://mermaid.js.org/syntax/entityRelationshipDiagram.html
+
+### Other diagram types
+
+Besides the diagram types listed above, [Mermaid.js] provides support for
+[pie charts], [gantt charts], [user journeys], [git graphs] and
+[requirement diagrams], all of which are not officially supported by Material
+for MkDocs. Those diagrams should still work as advertised by [Mermaid.js], but
+we don't consider them a good choice, mostly as they don't work well on mobile.
+
+ [pie charts]: https://mermaid.js.org/syntax/pie.html
+ [gantt charts]: https://mermaid.js.org/syntax/gantt.html
+ [user journeys]: https://mermaid.js.org/syntax/userJourney.html
+ [git graphs]: https://mermaid.js.org/syntax/gitgraph.html
+ [requirement diagrams]: https://mermaid.js.org/syntax/requirementDiagram.html
+
+## Customization
+
+If you want to customize Mermaid.js, e.g. to bring in support for [ELK layouts],
+you can do so by adding a custom JavaScript file to your `mkdocs.yml`:
+
+=== ":octicons-file-code-16: `docs/javascripts/mermaid.mjs`"
+
+ ``` js
+ import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+ import elkLayouts from 'https://cdn.jsdelivr.net/npm/@mermaid-js/layout-elk@0/dist/mermaid-layout-elk.esm.min.mjs';
+
+ mermaid.registerLayoutLoaders(elkLayouts);
+ mermaid.initialize({
+ startOnLoad: false,
+ securityLevel: "loose",
+ layout: "elk",
+ });
+
+ // Important: necessary to make it visible to Material for MkDocs
+ window.mermaid = mermaid;
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_javascript:
+ - javascripts/mermaid.mjs
+ ```
+
+ [ELK layouts]: https://www.npmjs.com/package/@mermaid-js/layout-elk
diff --git a/documents/markdown/mkdocs-material/reference_footnotes.md b/documents/markdown/mkdocs-material/reference_footnotes.md
new file mode 100644
index 0000000..7f45d0a
--- /dev/null
+++ b/documents/markdown/mkdocs-material/reference_footnotes.md
@@ -0,0 +1,109 @@
+---
+icon: material/format-align-bottom
+---
+
+# Footnotes
+
+Footnotes are a great way to add supplemental or additional information to a
+specific word, phrase or sentence without interrupting the flow of a document.
+Material for MkDocs provides the ability to define, reference and render
+footnotes.
+
+## Configuration
+
+This configuration adds the ability to define inline footnotes, which are then
+rendered below all Markdown content of a document. Add the following lines to
+`mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - footnotes
+```
+
+See additional configuration options:
+
+- [Footnotes]
+
+ [Footnotes]: ../setup/extensions/python-markdown.md#footnotes
+
+### Footnote tooltips
+
+<!-- md:version 9.7.0 -->
+<!-- md:flag experimental -->
+
+Footnotes can be rendered as inline tooltips, so the user can read the footnote
+without leaving the context of the document. Footnote tooltips can be enabled
+in `mkdocs.yml` with:
+
+``` yaml
+theme:
+ features:
+ - content.footnote.tooltips
+```
+
+__Footnote tooltips are enabled on our documentation__, so to try it out, you
+can just hover or focus any footnote on this page or any other page of our
+documentation.
+
+## Usage
+
+### Adding footnote references
+
+A footnote reference must be enclosed in square brackets and must start with a
+caret `^`, directly followed by an arbitrary identifier, which is similar to
+the standard Markdown link syntax.
+
+``` title="Text with footnote references"
+Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]
+```
+
+<div class="result" markdown>
+
+Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]
+
+</div>
+
+### Adding footnote content
+
+The footnote content must be declared with the same identifier as the reference.
+It can be inserted at an arbitrary position in the document and is always
+rendered at the bottom of the page. Furthermore, a backlink to the footnote
+reference is automatically added.
+
+#### on a single line
+
+Short footnotes can be written on the same line:
+
+``` title="Footnote"
+[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+```
+
+<div class="result" markdown>
+
+[:octicons-arrow-down-24: Jump to footnote](#fn:1)
+
+</div>
+
+ [^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+#### on multiple lines
+
+Paragraphs can be written on the next line and must be indented by four spaces:
+
+``` title="Footnote"
+[^2]:
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+```
+
+<div class="result" markdown>
+
+[:octicons-arrow-down-24: Jump to footnote](#fn:2)
+
+</div>
+
+[^2]:
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus
+ auctor massa, nec semper lorem quam in massa.
diff --git a/documents/markdown/mkdocs-material/reference_formatting.md b/documents/markdown/mkdocs-material/reference_formatting.md
new file mode 100644
index 0000000..e8148ce
--- /dev/null
+++ b/documents/markdown/mkdocs-material/reference_formatting.md
@@ -0,0 +1,140 @@
+---
+icon: material/format-font
+---
+
+# Formatting
+
+Material for MkDocs provides support for several HTML elements that can be used
+to highlight sections of a document or apply specific formatting. Additionally,
+[Critic Markup] is supported, adding the ability to display suggested changes
+for a document.
+
+ [Critic Markup]: https://github.com/CriticMarkup/CriticMarkup-toolkit
+
+## Configuration
+
+This configuration enables support for keyboard keys, tracking changes in
+documents, defining sub- and superscript and highlighting text. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.critic
+ - pymdownx.caret
+ - pymdownx.keys
+ - pymdownx.mark
+ - pymdownx.tilde
+```
+
+See additional configuration options:
+
+- [Critic]
+- [Caret, Mark & Tilde]
+- [Keys]
+
+ [Critic]: ../setup/extensions/python-markdown-extensions.md#critic
+ [Caret, Mark & Tilde]: ../setup/extensions/python-markdown-extensions.md#caret-mark-tilde
+ [Keys]: ../setup/extensions/python-markdown-extensions.md#keys
+
+## Usage
+
+### Highlighting changes
+
+When [Critic] is enabled, [Critic Markup] can be used, which adds the ability to
+highlight suggested changes, as well as add inline comments to a document:
+
+``` title="Text with suggested changes"
+Text can be {--deleted--} and replacement text {++added++}. This can also be
+combined into {~~one~>a single~~} operation. {==Highlighting==} is also
+possible {>>and comments can be added inline<<}.
+
+{==
+
+Formatting can also be applied to blocks by putting the opening and closing
+tags on separate lines and adding new lines between the tags and the content.
+
+==}
+```
+
+<div class="result" markdown>
+
+Text can be <del class="critic">deleted</del> and replacement text
+<ins class="critic">added</ins>. This can also be combined into
+<del class="critic">one</del><ins class="critic">a single</ins> operation.
+<mark class="critic">Highlighting</mark> is also possible
+<span class="critic comment">and comments can be added inline</span>.
+
+<div>
+ <mark class="critic block">
+ <p>
+ Formatting can also be applied to blocks by putting the opening and
+ closing tags on separate lines and adding new lines between the tags and
+ the content.
+ </p>
+ </mark>
+</div>
+
+</div>
+
+### Highlighting text
+
+When [Caret, Mark & Tilde] are enabled, text can be highlighted with a simple
+syntax, which is more convenient that directly using the corresponding
+[`mark`][mark], [`ins`][ins] and [`del`][del] HTML tags:
+
+``` title="Text with highlighting"
+- ==This was marked (highlight)==
+- ^^This was inserted (underline)^^
+- ~~This was deleted (strikethrough)~~
+```
+
+<div class="result" markdown>
+
+- ==This was marked (highlight)==
+- ^^This was inserted (underline)^^
+- ~~This was deleted (strikethrough)~~
+
+</div>
+
+ [mark]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark
+ [ins]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ins
+ [del]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/del
+
+### Sub- and superscripts
+
+When [Caret & Tilde][Caret, Mark & Tilde] are enabled, text can be sub- and
+superscripted with a simple syntax, which is more convenient than directly
+using the corresponding [`sub`][sub] and [`sup`][sup] HTML tags:
+
+``` markdown title="Text with sub- and superscripts"
+- H~2~O
+- A^T^A
+```
+
+<div class="result" markdown>
+
+- H~2~O
+- A^T^A
+
+</div>
+
+ [sub]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sub
+ [sup]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sup
+
+### Adding keyboard keys
+
+When [Keys] is enabled, keyboard keys can be rendered with a simple syntax.
+Consult the [Python Markdown Extensions] documentation to learn about all
+available shortcodes:
+
+``` markdown title="Keyboard keys"
+++ctrl+alt+del++
+```
+
+<div class="result" markdown>
+
+++ctrl+alt+del++
+
+</div>
+
+ [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/#extendingmodifying-key-map-index
diff --git a/documents/markdown/mkdocs-material/reference_grids.md b/documents/markdown/mkdocs-material/reference_grids.md
new file mode 100644
index 0000000..10af8d5
--- /dev/null
+++ b/documents/markdown/mkdocs-material/reference_grids.md
@@ -0,0 +1,301 @@
+---
+icon: material/view-grid-plus
+---
+
+# Grids
+
+Material for MkDocs makes it easy to arrange sections into grids, grouping
+blocks that convey similar meaning or are of equal importance. Grids are just
+perfect for building index pages that show a brief overview of a large section
+of your documentation.
+
+## Configuration
+
+This configuration enables the use of grids, allowing to bring blocks of
+identical or different types into a rectangular shape. Add the following lines
+to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions: # (1)!
+ - attr_list
+ - md_in_html
+```
+
+1. Note that some of the examples listed below use [icons and emojis], which
+ have to be [configured separately].
+
+See additional configuration options:
+
+- [Attribute Lists]
+- [Markdown in HTML]
+
+ [icons and emojis]: icons-emojis.md
+ [configured separately]: icons-emojis.md#configuration
+ [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
+ [Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html
+
+## Usage
+
+Grids come in two flavors: [card grids], which wrap each element in a card that
+levitates on hover, and [generic grids], which allow to arrange arbitrary block
+elements in a rectangular shape.
+
+ [card grids]: #using-card-grids
+ [generic grids]: #using-generic-grids
+
+### Using card grids
+
+<!-- md:version 9.5.0 -->
+<!-- md:flag experimental -->
+
+Card grids wrap each grid item with a beautiful hover card that levitates on
+hover. They come in two slightly different syntaxes: [list] and [block syntax],
+adding support for distinct use cases.
+
+ [list]: #list-syntax
+ [block syntax]: #block-syntax
+
+#### List syntax
+
+The list syntax is essentially a shortcut for [card grids], and consists of an
+unordered (or ordered) list wrapped by a `div` with both, the `grid` and `cards`
+classes:
+
+``` html title="Card grid"
+<div class="grid cards" markdown>
+
+- :fontawesome-brands-html5: __HTML__ for content and structure
+- :fontawesome-brands-js: __JavaScript__ for interactivity
+- :fontawesome-brands-css3: __CSS__ for text running out of boxes
+- :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh?
+
+</div>
+```
+
+<div class="result" markdown>
+ <div class="grid cards" markdown>
+
+- :fontawesome-brands-html5: __HTML__ for content and structure
+- :fontawesome-brands-js: __JavaScript__ for interactivity
+- :fontawesome-brands-css3: __CSS__ for text running out of boxes
+- :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh?
+
+ </div>
+</div>
+
+List elements can contain arbitrary Markdown, as long as the surrounding `div`
+defines the `markdown` attribute. Following is a more complex example, which
+includes icons and links:
+
+``` html title="Card grid, complex example"
+<div class="grid cards" markdown>
+
+- :material-clock-fast:{ .lg .middle } __Set up in 5 minutes__
+
+ ---
+
+ Install [`mkdocs-material`](#) with [`pip`](#) and get up
+ and running in minutes
+
+ [:octicons-arrow-right-24: Getting started](#)
+
+- :fontawesome-brands-markdown:{ .lg .middle } __It's just Markdown__
+
+ ---
+
+ Focus on your content and generate a responsive and searchable static site
+
+ [:octicons-arrow-right-24: Reference](#)
+
+- :material-format-font:{ .lg .middle } __Made to measure__
+
+ ---
+
+ Change the colors, fonts, language, icons, logo and more with a few lines
+
+ [:octicons-arrow-right-24: Customization](#)
+
+- :material-scale-balance:{ .lg .middle } __Open Source, MIT__
+
+ ---
+
+ Material for MkDocs is licensed under MIT and available on [GitHub]
+
+ [:octicons-arrow-right-24: License](#)
+
+</div>
+```
+
+<div class="result" markdown>
+ <div class="grid cards" markdown>
+
+- :material-clock-fast:{ .lg .middle } __Set up in 5 minutes__
+
+ ---
+
+ Install [`mkdocs-material`][mkdocs-material] with [`pip`][pip] and get up
+ and running in minutes
+
+ [:octicons-arrow-right-24: Getting started][getting started]
+
+- :fontawesome-brands-markdown:{ .lg .middle } __It's just Markdown__
+
+ ---
+
+ Focus on your content and generate a responsive and searchable static site
+
+ [:octicons-arrow-right-24: Reference][reference]
+
+- :material-format-font:{ .lg .middle } __Made to measure__
+
+ ---
+
+ Change the colors, fonts, language, icons, logo and more with a few lines
+
+ [:octicons-arrow-right-24: Customization][customization]
+
+- :material-scale-balance:{ .lg .middle } __Open Source, MIT__
+
+ ---
+
+ Material for MkDocs is licensed under MIT and available on [GitHub]
+
+ [:octicons-arrow-right-24: License][license]
+
+ </div>
+</div>
+
+If there's insufficient space to render grid items next to each other, the items
+will stretch to the full width of the viewport, e.g. on mobile viewports. If
+there's more space available, grids will render in items of 3 and more, e.g.
+when [hiding both sidebars].
+
+ [mkdocs-material]: https://pypistats.org/packages/mkdocs-material
+ [pip]: ../getting-started.md#with-pip
+ [getting started]: ../getting-started.md
+ [reference]: ../reference/index.md
+ [customization]: ../customization.md
+ [license]: ../license.md
+ [GitHub]: https://github.com/squidfunk/mkdocs-material
+ [hiding both sidebars]: ../setup/setting-up-navigation.md#hiding-the-sidebars
+
+#### Block syntax
+
+The block syntax allows for arranging cards in grids __together with other
+elements__, as explained in the section on [generic grids]. Just add the `card`
+class to any block element inside a `grid`:
+
+``` html title="Card grid, blocks"
+<div class="grid" markdown>
+
+:fontawesome-brands-html5: __HTML__ for content and structure
+{ .card }
+
+:fontawesome-brands-js: __JavaScript__ for interactivity
+{ .card }
+
+:fontawesome-brands-css3: __CSS__ for text running out of boxes
+{ .card }
+
+> :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh?
+
+</div>
+```
+
+<div class="result" markdown>
+ <div class="grid" markdown>
+
+:fontawesome-brands-html5: __HTML__ for content and structure
+{ .card }
+
+:fontawesome-brands-js: __JavaScript__ for interactivity
+{ .card }
+
+:fontawesome-brands-css3: __CSS__ for text running out of boxes
+{ .card }
+
+> :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh?
+
+ </div>
+</div>
+
+While this syntax may seem unnecessarily verbose at first, the previous example
+shows how card grids can now be mixed with other elements that will also stretch
+to the grid.
+
+### Using generic grids
+
+<!-- md:version 9.5.0 -->
+<!-- md:flag experimental -->
+
+Generic grids allow for arranging arbitrary block elements in a grid, including
+[admonitions], [code blocks], [content tabs] and more. Just wrap a set of blocks
+by using a `div` with the `grid` class:
+
+```` html title="Generic grid"
+<div class="grid" markdown>
+
+=== "Unordered list"
+
+ * Sed sagittis eleifend rutrum
+ * Donec vitae suscipit est
+ * Nulla tempor lobortis orci
+
+=== "Ordered list"
+
+ 1. Sed sagittis eleifend rutrum
+ 2. Donec vitae suscipit est
+ 3. Nulla tempor lobortis orci
+
+``` title="Content tabs"
+=== "Unordered list"
+
+ * Sed sagittis eleifend rutrum
+ * Donec vitae suscipit est
+ * Nulla tempor lobortis orci
+
+=== "Ordered list"
+
+ 1. Sed sagittis eleifend rutrum
+ 2. Donec vitae suscipit est
+ 3. Nulla tempor lobortis orci
+```
+
+</div>
+````
+
+<div class="result" markdown>
+ <div class="grid" markdown>
+
+=== "Unordered list"
+
+ * Sed sagittis eleifend rutrum
+ * Donec vitae suscipit est
+ * Nulla tempor lobortis orci
+
+=== "Ordered list"
+
+ 1. Sed sagittis eleifend rutrum
+ 2. Donec vitae suscipit est
+ 3. Nulla tempor lobortis orci
+
+``` title="Content tabs"
+=== "Unordered list"
+
+ * Sed sagittis eleifend rutrum
+ * Donec vitae suscipit est
+ * Nulla tempor lobortis orci
+
+=== "Ordered list"
+
+ 1. Sed sagittis eleifend rutrum
+ 2. Donec vitae suscipit est
+ 3. Nulla tempor lobortis orci
+```
+
+ </div>
+</div>
+
+ [admonitions]: admonitions.md
+ [code blocks]: code-blocks.md
+ [content tabs]: content-tabs.md
diff --git a/documents/markdown/mkdocs-material/reference_icons-emojis.md b/documents/markdown/mkdocs-material/reference_icons-emojis.md
new file mode 100644
index 0000000..5ac5325
--- /dev/null
+++ b/documents/markdown/mkdocs-material/reference_icons-emojis.md
@@ -0,0 +1,239 @@
+---
+icon: material/emoticon-happy-outline
+---
+
+# Icons, Emojis
+
+One of the best features of Material for MkDocs is the possibility to use [more
+than 10,000 icons][icon search] and thousands of emojis in your project
+documentation with practically zero additional effort. Moreover, [custom icons
+can be added] and used in `mkdocs.yml`, documents and templates.
+
+ [icon search]: #search
+ [custom icons can be added]: ../setup/changing-the-logo-and-icons.md#additional-icons
+
+## Search
+
+<div class="mdx-iconsearch" data-mdx-component="iconsearch">
+ <input
+ class="md-input md-input--stretch mdx-iconsearch__input"
+ placeholder="Search the icon and emoji database"
+ data-mdx-component="iconsearch-query"
+ />
+ <div class="mdx-iconsearch-result" data-mdx-component="iconsearch-result">
+ <select
+ class="mdx-iconsearch-result__select"
+ data-mdx-component="iconsearch-select"
+ >
+ <option value="all" selected>All</option>
+ <option value="icons">Icons</option>
+ <option value="emojis">Emojis</option>
+ </select>
+ <div class="mdx-iconsearch-result__meta"></div>
+ <ol class="mdx-iconsearch-result__list"></ol>
+ </div>
+</div>
+<small>
+ :octicons-light-bulb-16:
+ **Tip:** Enter some keywords to find icons and emojis and click on the
+ shortcode to copy it to your clipboard.
+</small>
+
+## Configuration
+
+This configuration enables the use of icons and emojis by using simple
+shortcodes which can be discovered through the [icon search]. Add the following
+lines to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - attr_list
+ - pymdownx.emoji:
+ emoji_index: !!python/name:material.extensions.emoji.twemoji
+ emoji_generator: !!python/name:material.extensions.emoji.to_svg
+```
+
+The following icon sets are bundled with Material for MkDocs:
+
+- :material-material-design: – [Material Design]
+- :fontawesome-brands-font-awesome: – [FontAwesome]
+- :octicons-mark-github-16: – [Octicons]
+- :simple-simpleicons: – [Simple Icons]
+
+See additional configuration options:
+
+- [Attribute Lists]
+- [Emoji]
+- [Emoji with custom icons]
+
+ [Material Design]: https://pictogrammers.com/library/mdi/
+ [FontAwesome]: https://fontawesome.com/search?m=free
+ [Octicons]: https://octicons.github.com/
+ [Simple Icons]: https://simpleicons.org/
+ [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
+ [Emoji]: ../setup/extensions/python-markdown-extensions.md#emoji
+ [Emoji with custom icons]: ../setup/extensions/python-markdown-extensions.md#+pymdownx.emoji.options.custom_icons
+
+## Usage
+
+### Using emojis
+
+Emojis can be integrated in Markdown by putting the shortcode of the emoji
+between two colons. If you're using [Twemoji] (recommended), you can look up
+the shortcodes at [Emojipedia]:
+
+``` title="Emoji"
+:smile:
+```
+
+<div class="result" markdown>
+
+:smile:
+
+</div>
+ [Twemoji]: https://github.com/jdecked/twemoji
+ [Emojipedia]: https://emojipedia.org/twitter/
+
+### Using icons
+
+When [Emoji] is enabled, icons can be used similar to emojis, by referencing
+a valid path to any icon bundled with the theme, which are located in the
+[`.icons`][custom icons] directory, and replacing `/` with `-`:
+
+``` title="Icon"
+:fontawesome-regular-face-laugh-wink:
+```
+
+<div class="result" markdown>
+
+:fontawesome-regular-face-laugh-wink:
+
+</div>
+
+ [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/templates/.icons
+
+#### with colors
+
+When [Attribute Lists] is enabled, custom CSS classes can be added to icons by
+suffixing the icon with a special syntax. While HTML allows to use [inline
+styles], it's always recommended to add an [additional style sheet] and move
+declarations into dedicated CSS classes:
+
+<style>
+ .youtube {
+ color: #EE0F0F;
+ }
+</style>
+
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+ ``` css
+ .youtube {
+ color: #EE0F0F;
+ }
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_css:
+ - stylesheets/extra.css
+ ```
+
+After applying the customization, add the CSS class to the icon shortcode:
+
+``` markdown title="Icon with color"
+:fontawesome-brands-youtube:{ .youtube }
+```
+
+<div class="result" markdown>
+
+:fontawesome-brands-youtube:{ .youtube }
+
+</div>
+
+ [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
+ [inline styles]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style
+ [additional style sheet]: ../customization.md#additional-css
+
+#### with animations
+
+Similar to adding [colors], it's just as easy to add [animations] to icons by
+using an [additional style sheet], defining a `@keyframes` rule and adding a
+dedicated CSS class to the icon:
+
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+ ``` css
+ @keyframes heart {
+ 0%, 40%, 80%, 100% {
+ transform: scale(1);
+ }
+ 20%, 60% {
+ transform: scale(1.15);
+ }
+ }
+ .heart {
+ animation: heart 1000ms infinite;
+ }
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_css:
+ - stylesheets/extra.css
+ ```
+
+After applying the customization, add the CSS class to the icon shortcode:
+
+``` markdown title="Icon with animation"
+:octicons-heart-fill-24:{ .heart }
+```
+
+<div class="result" markdown>
+
+:octicons-heart-fill-24:{ .mdx-heart }
+
+</div>
+
+ [colors]: #with-colors
+ [animations]: https://developer.mozilla.org/en-US/docs/Web/CSS/animation
+
+### Icons, emojis in sidebars :smile:
+
+With the help of the [built-in typeset plugin], you can use icons and emojis
+in headings, which will then be rendered in the sidebars. The plugin preserves
+Markdown and HTML formatting.
+
+ [built-in typeset plugin]: ../plugins/typeset.md
+
+## Customization
+
+### Using icons in templates
+
+When you're [extending the theme] with partials or blocks, you can simply
+reference any icon that's [bundled with the theme][icon search] with Jinja's
+[`include`][include] function and wrap it with the `.twemoji` CSS class:
+
+``` html
+<span class="twemoji">
+ {% include ".icons/fontawesome/brands/youtube.svg" %} <!-- (1)! -->
+</span>
+```
+
+1. Enter a few keywords to find the perfect icon using our [icon search] and
+ click on the shortcode to copy it to your clipboard:
+
+ <div class="mdx-iconsearch" data-mdx-component="iconsearch">
+ <input class="md-input md-input--stretch mdx-iconsearch__input" placeholder="Search icon" data-mdx-component="iconsearch-query" value="brands youtube" />
+ <div class="mdx-iconsearch-result" data-mdx-component="iconsearch-result" data-mdx-mode="file">
+ <div class="mdx-iconsearch-result__meta"></div>
+ <ol class="mdx-iconsearch-result__list"></ol>
+ </div>
+ </div>
+
+This is exactly what Material for MkDocs does in its templates.
+
+ [extending the theme]: ../customization.md#extending-the-theme
+ [include]: https://jinja.palletsprojects.com/en/2.11.x/templates/#include
diff --git a/documents/markdown/mkdocs-material/reference_images.md b/documents/markdown/mkdocs-material/reference_images.md
new file mode 100644
index 0000000..336bd4c
--- /dev/null
+++ b/documents/markdown/mkdocs-material/reference_images.md
@@ -0,0 +1,219 @@
+---
+icon: material/image-frame
+---
+
+# Images
+
+While images are first-class citizens of Markdown and part of the core syntax,
+it can be difficult to work with them. Material for MkDocs makes working with
+images more comfortable, providing styles for image alignment and image
+captions.
+
+## Configuration
+
+This configuration adds the ability to align images, add captions to images
+(rendering them as figures), and mark large images for lazy-loading. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - attr_list
+ - md_in_html
+ - pymdownx.blocks.caption
+```
+
+See additional configuration options:
+
+- [Attribute Lists]
+- [Markdown in HTML]
+- [Caption]
+
+ [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
+ [Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html
+ [Caption]: ../setup/extensions/python-markdown-extensions.md#caption
+
+### Lightbox
+
+<!-- md:version 0.1.0 -->
+<!-- md:plugin [glightbox] -->
+
+If you want to add image zoom functionality to your documentation, the
+[glightbox] plugin is an excellent choice, as it integrates perfectly
+with Material for MkDocs. Install it with `pip`:
+
+```
+pip install mkdocs-glightbox
+```
+
+Then, add the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - glightbox
+```
+
+We recommend checking out the available
+[configuration options][glightbox options].
+
+ [glightbox]: https://github.com/blueswen/mkdocs-glightbox
+ [glightbox options]: https://github.com/blueswen/mkdocs-glightbox#usage
+
+## Usage
+
+### Image alignment
+
+When [Attribute Lists] is enabled, images can be aligned by adding the
+respective alignment directions via the `align` attribute, i.e. `align=left` or
+`align=right`:
+
+=== "Left"
+
+ ``` markdown title="Image, aligned to left"
+ { align=left }
+ ```
+
+ <div class="result" markdown>
+
+ { align=left width=300 }
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+
+ </div>
+
+=== "Right"
+
+ ``` markdown title="Image, aligned to right"
+ { align=right }
+ ```
+
+ <div class="result" markdown>
+
+ { align=right width=300 }
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+ massa, nec semper lorem quam in massa.
+
+ </div>
+
+If there's insufficient space to render the text next to the image, the image
+will stretch to the full width of the viewport, e.g. on mobile viewports.
+
+??? question "Why is there no centered alignment?"
+
+ The [`align`][align] attribute doesn't allow for centered alignment, which
+ is why this option is not supported by Material for MkDocs.[^1] Instead,
+ the [image captions] syntax can be used, as captions are optional.
+
+ [^1]:
+ You might also realize that the [`align`][align] attribute has been
+ deprecated as of HTML5, so why use it anyways? The main reason is
+ portability – it's still supported by all browsers and clients, and is very
+ unlikely to be completely removed, as many older websites still use it. This
+ ensures a consistent appearance when a Markdown file with these attributes
+ is viewed outside of a website generated by Material for MkDocs.
+
+ [align]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#deprecated_attributes
+ [image captions]: #image-captions
+
+### Image captions
+
+Sadly, the Markdown syntax doesn't provide native support for image captions,
+but it's always possible to use the [Markdown in HTML] extension with literal
+`figure` and `figcaption` tags:
+
+``` html title="Image with caption"
+<figure markdown="span">
+ { width="300" }
+ <figcaption>Image caption</figcaption>
+</figure>
+```
+
+<div class="result">
+ <figure>
+ <img src="https://dummyimage.com/600x400/f5f5f5/aaaaaa?text=–%20Image%20–" width="300" />
+ <figcaption>Image caption</figcaption>
+ </figure>
+</div>
+
+However, [Caption] provides an alternative syntax to add captions
+to any Markdown block element, including images:
+
+``` markdown title="Image with caption"
+{ width="300" }
+/// caption
+Image caption
+///
+```
+
+### Image lazy-loading
+
+Modern browsers provide [native support for lazy-loading images][lazy-loading]
+through the `loading=lazy` directive, which degrades to eager-loading in
+browsers without support:
+
+``` markdown title="Image, lazy-loaded"
+{ loading=lazy }
+```
+
+<div class="result" markdown>
+ <img src="https://dummyimage.com/600x400/f5f5f5/aaaaaa?text=–%20Image%20–" width="300" />
+</div>
+
+ [lazy-loading]: https://caniuse.com/#feat=loading-lazy-attr
+
+### Light and dark mode
+
+<!-- md:version 8.1.1 -->
+
+If you added a [color palette toggle] and want to show different images for
+light and dark color schemes, you can append a `#only-light` or `#only-dark`
+hash fragment to the image URL:
+
+``` markdown title="Image, different for light and dark mode"
+
+
+```
+
+<div class="result" markdown>
+
+![Zelda light world]{ width="300" }
+![Zelda dark world]{ width="300" }
+
+</div>
+
+!!! warning "Requirements when using [custom color schemes]"
+
+ The built-in [color schemes] define the aforementioned hash fragments, but
+ if you're using [custom color schemes], you'll also have to add the
+ following selectors to your scheme, depending on whether it's a light or
+ dark scheme:
+
+ === "Custom light scheme"
+
+ ``` css
+ [data-md-color-scheme="custom-light"] img[src$="#only-dark"],
+ [data-md-color-scheme="custom-light"] img[src$="#gh-dark-mode-only"] {
+ display: none; /* Hide dark images in light mode */
+ }
+ ```
+
+ === "Custom dark scheme"
+
+ ``` css
+ [data-md-color-scheme="custom-dark"] img[src$="#only-light"],
+ [data-md-color-scheme="custom-dark"] img[src$="#gh-light-mode-only"] {
+ display: none; /* Hide light images in dark mode */
+ }
+ ```
+
+ Remember to change `#!css "custom-light"` and `#!css "custom-dark"` to the
+ name of your scheme.
+
+ [color palette toggle]: ../setup/changing-the-colors.md#color-palette-toggle
+ [Zelda light world]: ../assets/images/zelda-light-world.png#only-light
+ [Zelda dark world]: ../assets/images/zelda-dark-world.png#only-dark
+ [color schemes]: ../setup/changing-the-colors.md#color-scheme
+ [custom color schemes]: ../setup/changing-the-colors.md#custom-color-schemes
diff --git a/documents/markdown/mkdocs-material/reference_index.md b/documents/markdown/mkdocs-material/reference_index.md
new file mode 100644
index 0000000..a278dab
--- /dev/null
+++ b/documents/markdown/mkdocs-material/reference_index.md
@@ -0,0 +1,233 @@
+# Reference
+
+Material for MkDocs is packed with many great features that make technical
+writing a joyful activity. This section of the documentation explains how to set up
+a page, and showcases all available specimen that can be used directly from
+within Markdown files.
+
+## Configuration
+
+## Usage
+
+### Setting the page `title`
+
+Each page has a designated title, which is used in the navigation sidebar, for
+[social cards] and in other places. While MkDocs attempts to automatically
+determine the title of a page in a [four step process], the title can also be
+explicitly set with the front matter `title` property:
+
+``` yaml
+---
+title: Lorem ipsum dolor sit amet # (1)!
+---
+
+# Page title
+...
+```
+
+1. This line sets the [`title`][title] inside the HTML document's
+ [`head`][head] for the generated page to the given value. Note that the
+ site title, which is set via [`site_name`][site_name], is appended with a
+ dash.
+
+ [social cards]: ../setup/setting-up-social-cards.md
+ [four step process]: https://www.mkdocs.org/user-guide/writing-your-docs/#meta-data
+ [title]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title
+ [head]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head
+ [site_name]: https://www.mkdocs.org/user-guide/configuration/#site_name
+
+### Setting the page `description`
+
+A Markdown file can include a description that is added to the `meta` tags of
+a page, and is also used for [social cards]. It's a good idea to set a
+[`site_description`][site_description] in `mkdocs.yml` as a fallback value if
+the author does not explicitly define a description for a Markdown file:
+
+``` yaml
+---
+description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
+---
+
+# Page title
+...
+```
+
+1. This line sets the `meta` tag containing the description inside the
+ document `head` for the current page to the provided value.
+
+ [site_description]: https://www.mkdocs.org/user-guide/configuration/#site_description
+
+### Setting the page `icon`
+
+<!-- md:version 9.2.0 -->
+<!-- md:flag experimental -->
+
+An icon can be assigned to each page, which is then rendered as part of the
+navigation sidebar, as well as [navigation tabs], if enabled. Use the front
+matter `icon` property to reference an icon, adding the following lines at the
+top of a Markdown file:
+
+``` yaml
+---
+icon: material/emoticon-happy # (1)!
+---
+
+# Page title
+...
+```
+
+1. Enter a few keywords to find the perfect icon using our [icon search] and
+ click on the shortcode to copy it to your clipboard:
+
+ <div class="mdx-iconsearch" data-mdx-component="iconsearch">
+ <input class="md-input md-input--stretch mdx-iconsearch__input" placeholder="Search icon" data-mdx-component="iconsearch-query" value="emoticon happy" />
+ <div class="mdx-iconsearch-result" data-mdx-component="iconsearch-result" data-mdx-mode="file">
+ <div class="mdx-iconsearch-result__meta"></div>
+ <ol class="mdx-iconsearch-result__list"></ol>
+ </div>
+ </div>
+
+ [icon search]: icons-emojis.md#search
+ [navigation tabs]: ../setup/setting-up-navigation.md#navigation-tabs
+
+### Setting the page `status`
+
+<!-- md:version 9.2.0 -->
+<!-- md:flag experimental -->
+<!-- md:example page-status -->
+
+A status can be assigned to each page, which is then displayed as part of the
+navigation sidebar. First, associate a status identifier with a description by
+adding the following to `mkdocs.yml`:
+
+``` yaml
+extra:
+ status:
+ <identifier>: <description> # (1)!
+```
+
+1. The identifier can only include alphanumeric characters, as well as dashes
+ and underscores. For example, if you have a status `Recently added`, you can
+ set `new` as an identifier:
+
+ ``` yaml
+ extra:
+ status:
+ new: Recently added
+ ```
+
+The page status can now be set with the front matter `status` property. For
+example, you can mark a page as `new` with the following lines at the top of a
+Markdown file:
+
+``` yaml
+---
+status: new
+---
+
+# Page title
+...
+```
+
+The following status identifiers are already defined:
+
+- :material-alert-decagram: – `new`
+- :material-trash-can: – `deprecated`
+
+You can define a custom page status this way but if you want it to
+have an icon other than the default one you need to also configure
+that in your `extra.css`. We have an [example for a custom
+page status] to get you started.
+
+[example for a custom page status]: https://mkdocs-material.github.io/examples/page-status/
+
+### Setting the page `subtitle`
+
+<!-- md:version 9.6.0 -->
+<!-- md:flag experimental -->
+
+Each page can define a subtitle, which is then rendered below the title as part
+of the navigation sidebar by using the front matter `subtitle` property, and
+adding the following lines:
+
+``` yaml
+---
+subtitle: Nullam urna elit, malesuada eget finibus ut, ac tortor
+---
+
+# Page title
+...
+```
+
+### Setting the page `template`
+
+If you're using [theme extension] and created a new page template in the
+`overrides` directory, you can enable it for a specific page. Add the following
+lines at the top of a Markdown file:
+
+``` yaml
+---
+template: custom.html
+---
+
+# Page title
+...
+```
+
+??? question "How to set a page template for an entire folder?"
+
+ With the help of the [built-in meta plugin], you can set a custom template
+ for an entire section and all nested pages, by creating a `.meta.yml` file
+ in the corresponding folder with the following content:
+
+ ``` yaml
+ template: custom.html
+ ```
+
+ [theme extension]: ../customization.md#extending-the-theme
+ [built-in meta plugin]: ../plugins/meta.md
+
+## Customization
+
+### Using metadata in templates
+
+#### :material-check-all: on all pages
+
+In order to add custom `meta` tags to your document, you can [extend the theme
+][theme extension] and [override the `extrahead` block][overriding blocks],
+e.g. to add indexing policies for search engines via the `robots` property:
+
+``` html
+{% extends "base.html" %}
+
+{% block extrahead %}
+ <meta name="robots" content="noindex, nofollow" />
+{% endblock %}
+```
+
+ [overriding blocks]: ../customization.md#overriding-blocks
+
+#### :material-check: on a single page
+
+If you want to set a `meta` tag on a single page, or want to set different
+values for different pages, you can use the `page.meta` object inside your
+template override, e.g.:
+
+``` html
+{% extends "base.html" %}
+
+{% block extrahead %}
+ {% if page and page.meta and page.meta.robots %}
+ <meta name="robots" content="{{ page.meta.robots }}" />
+ {% else %}
+ <meta name="robots" content="index, follow" />
+ {% endif %}
+{% endblock %}
+```
+
+You can now use `robots` exactly like [`title`][title] and
+[`description`][description] to set values. Note that in this case, the
+template defines an `else` branch, which would set a default if none was given.
+
+ [title]: #setting-the-page-title
+ [description]: #setting-the-page-description
diff --git a/documents/markdown/mkdocs-material/reference_lists.md b/documents/markdown/mkdocs-material/reference_lists.md
new file mode 100644
index 0000000..1de7e7b
--- /dev/null
+++ b/documents/markdown/mkdocs-material/reference_lists.md
@@ -0,0 +1,168 @@
+---
+icon: material/format-list-bulleted
+---
+
+# Lists
+
+Material for MkDocs supports several flavors of lists that cater to different
+use cases, including _unordered lists_ and _ordered lists_, which are supported
+through standard Markdown, as well as _definition lists_ and _task lists_, which
+are supported through extensions.
+
+## Configuration
+
+This configuration enables the use of definition lists and tasks lists, which
+are both not part of the standard Markdown syntax. Add the following lines to
+`mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - def_list
+ - pymdownx.tasklist:
+ custom_checkbox: true
+```
+
+See additional configuration options:
+
+- [Definition Lists]
+- [Tasklist]
+
+ [Definition Lists]: ../setup/extensions/python-markdown.md#definition-lists
+ [Tasklist]: ../setup/extensions/python-markdown-extensions.md#tasklist
+
+## Usage
+
+### Using unordered lists
+
+Unordered lists can be written by prefixing a line with a `-`, `*` or `+` list
+marker, all of which can be used interchangeably. Furthermore, all flavors
+of lists can be nested inside each other:
+
+``` markdown title="List, unordered"
+- Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur
+ accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh
+ lacinia sed. Aenean in finibus diam.
+
+ * Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
+ * Nam vulputate tincidunt fringilla.
+ * Nullam dignissim ultrices urna non auctor.
+```
+
+<div class="result" markdown>
+
+- Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur
+ accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh
+ lacinia sed. Aenean in finibus diam.
+
+ * Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
+ * Nam vulputate tincidunt fringilla.
+ * Nullam dignissim ultrices urna non auctor.
+
+</div>
+
+### Using ordered lists
+
+Ordered lists must start with a number immediately followed by a dot. The
+numbers do not need to be consecutive and can be all set to `1.`, as they will
+be re-numbered when rendered:
+
+``` markdown title="List, ordered"
+1. Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis
+ sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
+ nulla. Vivamus a pharetra leo.
+
+ 1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet
+ quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a
+ ultricies libero efficitur sed.
+
+ 2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet
+ rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a.
+
+ 1. Mauris dictum mi lacus
+ 2. Ut sit amet placerat ante
+ 3. Suspendisse ac eros arcu
+```
+
+<div class="result" markdown>
+
+1. Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis
+ sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
+ nulla. Vivamus a pharetra leo.
+
+ 1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet
+ quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a
+ ultricies libero efficitur sed.
+
+ 2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet
+ rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a.
+
+ 1. Mauris dictum mi lacus
+ 2. Ut sit amet placerat ante
+ 3. Suspendisse ac eros arcu
+
+</div>
+
+### Using definition lists
+
+When [Definition Lists] is enabled, lists of arbitrary key-value pairs, e.g. the
+parameters of functions or modules, can be enumerated with a simple syntax:
+
+``` markdown title="Definition list"
+`Lorem ipsum dolor sit amet`
+
+: Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
+ tellus non sem sollicitudin, quis rutrum leo facilisis.
+
+`Cras arcu libero`
+
+: Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
+ ut eros sed sapien ullamcorper consequat. Nunc ligula ante.
+
+ Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
+ Nam vulputate tincidunt fringilla.
+ Nullam dignissim ultrices urna non auctor.
+```
+
+<div class="result" markdown>
+
+`Lorem ipsum dolor sit amet`
+
+: Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
+ tellus non sem sollicitudin, quis rutrum leo facilisis.
+
+`Cras arcu libero`
+
+: Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
+ ut eros sed sapien ullamcorper consequat. Nunc ligula ante.
+
+ Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
+ Nam vulputate tincidunt fringilla.
+ Nullam dignissim ultrices urna non auctor.
+
+</div>
+
+### Using task lists
+
+When [Tasklist] is enabled, unordered list items can be prefixed with `[ ]` to
+render an unchecked checkbox or `[x]` to render a checked checkbox, allowing
+for the definition of task lists:
+
+``` markdown title="Task list"
+- [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
+- [ ] Vestibulum convallis sit amet nisi a tincidunt
+ * [x] In hac habitasse platea dictumst
+ * [x] In scelerisque nibh non dolor mollis congue sed et metus
+ * [ ] Praesent sed risus massa
+- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
+```
+
+<div class="result" markdown>
+
+- [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
+- [ ] Vestibulum convallis sit amet nisi a tincidunt
+ * [x] In hac habitasse platea dictumst
+ * [x] In scelerisque nibh non dolor mollis congue sed et metus
+ * [ ] Praesent sed risus massa
+- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
+
+</div>
diff --git a/documents/markdown/mkdocs-material/reference_math.md b/documents/markdown/mkdocs-material/reference_math.md
new file mode 100644
index 0000000..83cc8df
--- /dev/null
+++ b/documents/markdown/mkdocs-material/reference_math.md
@@ -0,0 +1,198 @@
+---
+icon: material/alphabet-greek
+---
+
+# Math
+
+[MathJax] and [KaTeX] are two popular libraries for displaying
+mathematical content in browsers. Although both libraries offer similar
+functionality, they use different syntaxes and have different configuration
+options. This documentation site provides information on how to integrate them
+with Material for MkDocs easily.
+
+ [MathJax]: https://www.mathjax.org/
+ [LaTeX]: https://en.wikibooks.org/wiki/LaTeX/Mathematics
+ [MathML]: https://en.wikipedia.org/wiki/MathML
+ [AsciiMath]: http://asciimath.org/
+ [KaTeX]: https://katex.org/
+
+
+## Configuration
+
+The following configuration enables support for rendering block and
+inline block equations using [MathJax] and [KaTeX].
+
+### MathJax
+
+[MathJax] is a powerful and flexible library that supports multiple input formats,
+such as [LaTeX], [MathML], [AsciiMath], as well as various output formats like
+HTML, SVG, MathML. To use MathJax within your project, add the following lines
+to your `mkdocs.yml`.
+
+=== ":octicons-file-code-16: `docs/javascripts/mathjax.js`"
+
+ ``` js
+ window.MathJax = {
+ tex: {
+ inlineMath: [["\\(", "\\)"]],
+ displayMath: [["\\[", "\\]"]],
+ processEscapes: true,
+ processEnvironments: true
+ },
+ options: {
+ ignoreHtmlClass: ".*|",
+ processHtmlClass: "arithmatex"
+ }
+ };
+
+ document$.subscribe(() => { // (1)!
+ MathJax.startup.output.clearCache()
+ MathJax.typesetClear()
+ MathJax.texReset()
+ MathJax.typesetPromise()
+ })
+ ```
+
+ 1. This integrates MathJax with [instant loading].
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.arithmatex:
+ generic: true
+
+ extra_javascript:
+ - javascripts/mathjax.js
+ - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
+ ```
+
+See additional configuration options:
+
+- [Arithmatex]
+
+ [Arithmatex]: ../setup/extensions/python-markdown-extensions.md#arithmatex
+ [instant loading]: ../setup/setting-up-navigation.md#instant-loading
+
+<script id="MathJax-script" async src="https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js"></script>
+<script>
+ window.MathJax = {
+ tex: {
+ inlineMath: [["\\(", "\\)"]],
+ displayMath: [["\\[", "\\]"]],
+ processEscapes: true,
+ processEnvironments: true
+ },
+ options: {
+ ignoreHtmlClass: ".*|",
+ processHtmlClass: "arithmatex"
+ }
+ };
+</script>
+
+### KaTeX
+
+[KaTeX] is a lightweight library that focuses on speed and simplicity. It
+supports a subset of LaTeX syntax and can render math to HTML and SVG. To use
+[KaTeX] within your project, add the following lines to your `mkdocs.yml`.
+
+=== ":octicons-file-code-16: `docs/javascripts/katex.js`"
+
+ ``` js
+ document$.subscribe(({ body }) => { // (1)!
+ renderMathInElement(body, {
+ delimiters: [
+ { left: "$$", right: "$$", display: true },
+ { left: "$", right: "$", display: false },
+ { left: "\\(", right: "\\)", display: false },
+ { left: "\\[", right: "\\]", display: true }
+ ],
+ })
+ })
+ ```
+
+ 1. This integrates KaTeX with [instant loading].
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.arithmatex:
+ generic: true
+
+ extra_javascript:
+ - javascripts/katex.js
+ - https://unpkg.com/katex@0/dist/katex.min.js
+ - https://unpkg.com/katex@0/dist/contrib/auto-render.min.js
+
+ extra_css:
+ - https://unpkg.com/katex@0/dist/katex.min.css
+ ```
+
+## Usage
+
+### Using block syntax
+
+Blocks must be enclosed in `#!latex $$...$$` or `#!latex \[...\]` on separate
+lines:
+
+``` latex title="block syntax"
+$$
+\cos x=\sum_{k=0}^{\infty}\frac{(-1)^k}{(2k)!}x^{2k}
+$$
+```
+
+<div class="result" markdown>
+
+$$
+\cos x=\sum_{k=0}^{\infty}\frac{(-1)^k}{(2k)!}x^{2k}
+$$
+
+</div>
+
+### Using inline block syntax
+
+Inline blocks must be enclosed in `#!latex $...$` or `#!latex \(...\)`:
+
+``` latex title="inline syntax"
+The homomorphism $f$ is injective if and only if its kernel is only the
+singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such
+that $f(a)=f(b)$.
+```
+
+<div class="result" markdown>
+
+The homomorphism $f$ is injective if and only if its kernel is only the
+singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such
+that $f(a)=f(b)$.
+
+</div>
+
+## Comparing MathJax and KaTeX
+
+When deciding between MathJax and KaTeX, there are several key factors to
+consider:
+
+- __Speed__: KaTeX is generally faster than MathJax. If your site requires
+ rendering large quantities of complex equations quickly, KaTeX may be the
+ better choice.
+
+- __Syntax Support__: MathJax supports a wider array of LaTeX commands and can
+ process a variety of mathematical markup languages (like AsciiMath and MathML).
+ If you need advanced LaTeX features, MathJax may be more suitable.
+
+- __Output Format__: Both libraries support HTML and SVG outputs. However,
+ MathJax also offers MathML output, which can be essential for accessibility,
+ as it is readable by screen readers.
+
+- __Configurability__: MathJax provides a range of configuration options,
+ allowing for more precise control over its behavior. If you have specific
+ rendering requirements, MathJax might be a more flexible choice.
+
+- __Browser Support__: While both libraries work well in modern browsers,
+ MathJax has broader compatibility with older browsers. If your audience uses a
+ variety of browsers, including older ones, MathJax might be a safer option.
+
+In summary, KaTeX shines with its speed and simplicity, whereas MathJax offers
+more features and better compatibility at the expense of speed. The choice
+between the two will largely depend on your specific needs and constraints.
diff --git a/documents/markdown/mkdocs-material/reference_tooltips.md b/documents/markdown/mkdocs-material/reference_tooltips.md
new file mode 100644
index 0000000..55e8538
--- /dev/null
+++ b/documents/markdown/mkdocs-material/reference_tooltips.md
@@ -0,0 +1,167 @@
+---
+icon: material/tooltip-plus
+---
+
+# Tooltips
+
+Technical documentation often incurs the usage of many acronyms, which may
+need additional explanation, especially for new user of your project. For these
+matters, Material for MkDocs uses a combination of Markdown extensions to
+enable site-wide glossaries.
+
+## Configuration
+
+This configuration enables abbreviations and allows to build a simple
+project-wide glossary, sourcing definitions from a central location. Add the
+following line to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - abbr
+ - attr_list
+ - pymdownx.snippets
+```
+
+See additional configuration options:
+
+- [Abbreviations]
+- [Attribute Lists]
+- [Snippets]
+
+ [Abbreviations]: ../setup/extensions/python-markdown.md#abbreviations
+ [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
+ [Snippets]: ../setup/extensions/python-markdown-extensions.md#snippets
+
+### Improved tooltips
+
+<!-- md:version 9.5.0 -->
+<!-- md:flag experimental -->
+
+When improved tooltips are enabled, Material for MkDocs replaces the browser's
+rendering logic for `title` attribute with beautiful little tooltips.
+Add the following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - content.tooltips
+```
+
+Now, tooltips will be rendered for the following elements:
+
+- __Content__ – elements with a `title`, permalinks and code copy button
+- __Header__ – home button, header title, color palette switch and repository link
+- __Navigation__ – links that are shortened with ellipsis, i.e. `...`
+
+## Usage
+
+### Adding tooltips
+
+The [Markdown syntax] allows to specify a `title` for each link, which will
+render as a beautiful tooltip when [improved tooltips] are enabled. Add a
+tooltip to a link with the following lines:
+
+``` markdown title="Link with tooltip, inline syntax"
+[Hover me](https://example.com "I'm a tooltip!")
+```
+
+<div class="result" markdown>
+
+[Hover me](https://example.com "I'm a tooltip!")
+
+</div>
+
+Tooltips can also be added to link references:
+
+``` markdown title="Link with tooltip, reference syntax"
+[Hover me][example]
+
+ [example]: https://example.com "I'm a tooltip!"
+```
+
+<div class="result" markdown>
+
+[Hover me](https://example.com "I'm a tooltip!")
+
+</div>
+
+For all other elements, a `title` can be added by using the [Attribute Lists]
+extension:
+
+``` markdown title="Icon with tooltip"
+:material-information-outline:{ title="Important information" }
+```
+
+<div class="result" markdown>
+
+:material-information-outline:{ title="Important information" }
+
+</div>
+
+ [Markdown syntax]: https://daringfireball.net/projects/markdown/syntax#link
+ [improved tooltips]: #improved-tooltips
+
+### Adding abbreviations
+
+Abbreviations can be defined by using a special syntax similar to URLs and
+[footnotes], starting with a `*` and immediately followed by the term or
+acronym to be associated in square brackets:
+
+``` markdown title="Text with abbreviations"
+The HTML specification is maintained by the W3C.
+
+*[HTML]: Hyper Text Markup Language
+*[W3C]: World Wide Web Consortium
+```
+
+<div class="result" markdown>
+
+The HTML specification is maintained by the W3C.
+
+*[HTML]: Hyper Text Markup Language
+*[W3C]: World Wide Web Consortium
+
+</div>
+
+ [footnotes]: footnotes.md
+
+### Adding a glossary
+
+The [Snippets] extension can be used to implement a simple glossary by moving
+all abbreviations in a dedicated file[^1], and [auto-append] this file to all
+pages with the following configuration:
+
+ [^1]:
+ It's highly recommended to put the Markdown file containing the
+ abbreviations outside of the `docs` folder (here, a folder with the name
+ `includes` is used), as MkDocs might otherwise complain about an
+ unreferenced file.
+
+=== ":octicons-file-code-16: `includes/abbreviations.md`"
+
+ ```` markdown
+ *[HTML]: Hyper Text Markup Language
+ *[W3C]: World Wide Web Consortium
+ ````
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ```` yaml
+ markdown_extensions:
+ - pymdownx.snippets:
+ auto_append:
+ - includes/abbreviations.md
+ ````
+
+ [auto-append]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#auto-append-snippets
+
+!!! tip
+
+ When using a dedicated file outside of the `docs` folder, add the parent directory to the list
+ of `watch` folders so that when the glossary file is updated, the project is automatically
+ reloaded when running `mkdocs serve`.
+
+ ```` yaml
+ watch:
+ - includes
+ ````
diff --git a/documents/markdown/mkdocs-material/setup_adding-a-comment-system.md b/documents/markdown/mkdocs-material/setup_adding-a-comment-system.md
new file mode 100644
index 0000000..5238926
--- /dev/null
+++ b/documents/markdown/mkdocs-material/setup_adding-a-comment-system.md
@@ -0,0 +1,113 @@
+# Adding a comment system
+
+Material for MkDocs allows to easily add the third-party comment system of your
+choice to the footer of any page by using [theme extension]. As an example,
+we'll be integrating [Giscus], which is Open Source, free, and uses GitHub
+discussions as a backend.
+
+ [Giscus]: https://giscus.app/
+
+## Customization
+
+### Giscus integration
+
+Before you can use [Giscus], you need to complete the following steps:
+
+1. __Install the [Giscus GitHub App]__ and grant access to the repository
+ that should host comments as GitHub discussions. Note that this can be a
+ repository different from your documentation.
+2. __Visit [Giscus] and generate the snippet__ through their configuration tool
+ to load the comment system. Copy the snippet for the next step. The
+ resulting snippet should look similar to this:
+
+ ``` html
+ <script
+ src="https://giscus.app/client.js"
+ data-repo="<username>/<repository>"
+ data-repo-id="..."
+ data-category="..."
+ data-category-id="..."
+ data-mapping="pathname"
+ data-reactions-enabled="1"
+ data-emit-metadata="1"
+ data-theme="light"
+ data-lang="en"
+ crossorigin="anonymous"
+ async
+ >
+ </script>
+ ```
+
+The [`comments.html`][comments] partial (empty by default) is the best place to
+add the snippet generated by [Giscus]. Follow the guide on [theme extension]
+and [override the `comments.html` partial][overriding partials] with:
+
+``` html hl_lines="3"
+{% if page.meta.comments %}
+ <h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
+ <!-- Insert generated snippet here -->
+
+ <!-- Synchronize Giscus theme with palette -->
+ <script>
+ var giscus = document.querySelector("script[src*=giscus]")
+
+ // Set palette on initial load
+ var palette = __md_get("__palette")
+ if (palette && typeof palette.color === "object") {
+ var theme = palette.color.scheme === "slate"
+ ? "transparent_dark"
+ : "light"
+
+ // Instruct Giscus to set theme
+ giscus.setAttribute("data-theme", theme) // (1)!
+ }
+
+ // Register event handlers after documented loaded
+ document.addEventListener("DOMContentLoaded", function() {
+ var ref = document.querySelector("[data-md-component=palette]")
+ ref.addEventListener("change", function() {
+ var palette = __md_get("__palette")
+ if (palette && typeof palette.color === "object") {
+ var theme = palette.color.scheme === "slate"
+ ? "transparent_dark"
+ : "light"
+
+ // Instruct Giscus to change theme
+ var frame = document.querySelector(".giscus-frame")
+ frame.contentWindow.postMessage(
+ { giscus: { setConfig: { theme } } },
+ "https://giscus.app"
+ )
+ }
+ })
+ })
+ </script>
+{% endif %}
+```
+
+1. This code block ensures that [Giscus] renders with a dark theme when the
+ palette is set to `slate`. Note that multiple dark themes are available,
+ so you can change it to your liking.
+
+Replace the highlighted line with the snippet you generated with the [Giscus]
+configuration tool in the previous step. If you copied the snippet from above,
+you can enable comments on a page by setting the `comments` front matter
+property to `true`:
+
+``` yaml
+---
+comments: true
+---
+
+# Page title
+...
+```
+
+If you wish to enable comments for an entire folder, you can use the
+[built-in meta plugin].
+
+ [Giscus GitHub App]: https://github.com/apps/giscus
+ [theme extension]: ../customization.md#extending-the-theme
+ [comments]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/comments.html
+ [overriding partials]: ../customization.md#overriding-partials
+ [built-in meta plugin]: ../plugins/meta.md
diff --git a/documents/markdown/mkdocs-material/setup_adding-a-git-repository.md b/documents/markdown/mkdocs-material/setup_adding-a-git-repository.md
new file mode 100644
index 0000000..cf347f7
--- /dev/null
+++ b/documents/markdown/mkdocs-material/setup_adding-a-git-repository.md
@@ -0,0 +1,354 @@
+# Adding a git repository
+
+If your documentation is related to source code, Material for MkDocs provides
+the ability to display information to the project's repository as part of the
+static site, including stars and forks. Furthermore, the
+[date of last update and creation], as well as [contributors] can be shown.
+
+## Configuration
+
+### Repository
+
+<!-- md:version 0.1.0 -->
+<!-- md:default none -->
+
+In order to display a link to the repository of your project as part of your
+documentation, set [`repo_url`][repo_url] in `mkdocs.yml` to the public URL of
+your repository, e.g.:
+
+``` yaml
+repo_url: https://github.com/squidfunk/mkdocs-material
+```
+
+The link to the repository will be rendered next to the search bar on big
+screens and as part of the main navigation drawer on smaller screen sizes.
+
+Additionally, for public repositories hosted on [GitHub] or [GitLab], the
+latest release tag[^1], as well as the number of stars and forks, are
+automatically requested and rendered.
+
+ [^1]:
+ Unfortunately, GitHub only provides an API endpoint to obtain the [latest
+ release] - not the latest tag. Thus, make sure to [create a release] (not
+ pre-release) for the latest tag you want to display next to the number of
+ stars and forks. For GitLab, although it is possible to get a [list of tags
+ sorted by update time], the [equivalent API endpoint] is used. So, make sure
+ you also [create a release for GitLab repositories].
+
+ [repo_url]: https://www.mkdocs.org/user-guide/configuration/#repo_url
+ [latest release]: https://docs.github.com/en/rest/reference/releases#get-the-latest-release
+ [create a release]: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release
+ [list of tags sorted by update time]: https://docs.gitlab.com/ee/api/tags.html#list-project-repository-tags
+ [equivalent API endpoint]: https://docs.gitlab.com/ee/api/releases/#get-the-latest-release
+ [create a release for GitLab repositories]: https://docs.gitlab.com/ee/user/project/releases/#create-a-release
+
+#### Repository name
+
+<!-- md:version 0.1.0 -->
+<!-- md:default _automatically set to_ `GitHub`, `GitLab` _or_ `Bitbucket` -->
+
+MkDocs will infer the source provider by examining the URL and try to set the
+_repository name_ automatically. If you wish to customize the name, set
+[`repo_name`][repo_name] in `mkdocs.yml`:
+
+``` yaml
+repo_name: squidfunk/mkdocs-material
+```
+
+ [repo_name]: https://www.mkdocs.org/user-guide/configuration/#repo_name
+
+#### Repository icon
+
+<!-- md:version 5.0.0 -->
+<!-- md:default computed -->
+
+While the default repository icon is a generic git icon, it can be set to
+any icon bundled with the theme by referencing a valid icon path in
+`mkdocs.yml`:
+
+``` yaml
+theme:
+ icon:
+ repo: fontawesome/brands/git-alt # (1)!
+```
+
+1. Enter a few keywords to find the perfect icon using our [icon search] and
+ click on the shortcode to copy it to your clipboard:
+
+ <div class="mdx-iconsearch" data-mdx-component="iconsearch">
+ <input class="md-input md-input--stretch mdx-iconsearch__input" placeholder="Search icon" data-mdx-component="iconsearch-query" value="git" />
+ <div class="mdx-iconsearch-result" data-mdx-component="iconsearch-result" data-mdx-mode="file">
+ <div class="mdx-iconsearch-result__meta"></div>
+ <ol class="mdx-iconsearch-result__list"></ol>
+ </div>
+ </div>
+
+Some popular choices:
+
+- :fontawesome-brands-git: – `fontawesome/brands/git`
+- :fontawesome-brands-git-alt: – `fontawesome/brands/git-alt`
+- :fontawesome-brands-github: – `fontawesome/brands/github`
+- :fontawesome-brands-github-alt: – `fontawesome/brands/github-alt`
+- :fontawesome-brands-gitlab: – `fontawesome/brands/gitlab`
+- :fontawesome-brands-gitkraken: – `fontawesome/brands/gitkraken`
+- :fontawesome-brands-bitbucket: – `fontawesome/brands/bitbucket`
+- :fontawesome-solid-trash: – `fontawesome/solid/trash`
+
+ [icon search]: ../reference/icons-emojis.md#search
+
+#### Code actions
+
+<!-- md:version 9.0.0 -->
+<!-- md:feature -->
+
+If the [repository URL] points to a valid [GitHub], [GitLab] or [Bitbucket]
+repository, [MkDocs] provides a setting called [`edit_uri`][edit_uri], which
+resolves to the subfolder where your documentation is hosted.
+
+If your default branch is called `main`, change the setting to:
+
+``` yaml
+edit_uri: edit/main/docs/
+```
+
+After making sure that `edit_uri` is correctly configured, buttons for code
+actions can be added. Two types of code actions are supported: `edit` and `view`
+(GitHub only):
+
+=== ":material-file-edit-outline: Edit this page"
+
+ ``` yaml
+ theme:
+ features:
+ - content.action.edit
+ ```
+
+=== ":material-file-eye-outline: View source of this page"
+
+ ``` yaml
+ theme:
+ features:
+ - content.action.view
+ ```
+
+The icon of the edit and view buttons can be changed with the following lines:
+
+``` yaml
+theme:
+ icon:
+ edit: material/pencil # (1)!
+ view: material/eye
+```
+
+1. Enter a few keywords to find the perfect icon using our [icon search] and
+ click on the shortcode to copy it to your clipboard:
+
+ <div class="mdx-iconsearch" data-mdx-component="iconsearch">
+ <input class="md-input md-input--stretch mdx-iconsearch__input" placeholder="Search icon" data-mdx-component="iconsearch-query" value="material pencil" />
+ <div class="mdx-iconsearch-result" data-mdx-component="iconsearch-result" data-mdx-mode="file">
+ <div class="mdx-iconsearch-result__meta"></div>
+ <ol class="mdx-iconsearch-result__list"></ol>
+ </div>
+ </div>
+
+ [repository URL]: #repository
+ [GitHub]: https://github.com/
+ [GitLab]: https://about.gitlab.com/
+ [Bitbucket]: https://bitbucket.org/
+ [MkDocs]: https://www.mkdocs.org
+ [edit_uri]: https://www.mkdocs.org/user-guide/configuration/#edit_uri
+
+### Revisioning
+
+The following plugins are fully integrated with Material for MkDocs, allowing
+for showing the [date of last update and creation] of a document, as well as
+links to all [contributors] or [authors] involved.
+
+ [date of last update and creation]: #document-dates
+ [contributors]: #document-contributors
+ [authors]: #document-authors
+
+#### Document dates
+
+<!-- md:version 4.6.0 -->
+<!-- md:plugin [git-revision-date-localized] -->
+
+The [git-revision-date-localized] plugin adds support for adding the date of
+last update and creation of a document at the bottom of each page. Install it
+with `pip`:
+
+```
+pip install mkdocs-git-revision-date-localized-plugin
+```
+
+Then, add the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - git-revision-date-localized:
+ enable_creation_date: true
+```
+
+The following configuration options are supported:
+
+<!-- md:option git-revision-date-localized.enabled -->
+
+: <!-- md:default `true` --> This option specifies whether
+ the plugin is enabled when building your project. If you want to switch
+ the plugin off, e.g. for local builds, use an [environment variable]:
+
+ ``` yaml
+ plugins:
+ - git-revision-date-localized:
+ enabled: !ENV [CI, false]
+ ```
+
+<!-- md:option git-revision-date-localized.type -->
+
+: <!-- md:default `date` --> The format of the date to be
+ displayed. Valid values are `date`, `datetime`, `iso_date`, `iso_datetime`
+ and `timeago`:
+
+ ``` yaml
+ plugins:
+ - git-revision-date-localized:
+ type: date
+ ```
+
+<!-- md:option git-revision-date-localized.enable_creation_date -->
+
+: <!-- md:default `false` --> Enables the display of the
+ creation date of the file associated with the page next to the last updated
+ date at the bottom of the page:
+
+ ``` yaml
+ plugins:
+ - git-revision-date-localized:
+ enable_creation_date: true
+ ```
+
+ !!! note "When using build environments"
+
+ If you are deploying through a CI system, you might need to adjust your
+ CI settings when fetching the code. For more information, see
+ [git-revision-date-localized].
+
+<!-- md:option git-revision-date-localized.fallback_to_build_date -->
+
+: <!-- md:default `false` --> Enables falling back to
+ the time when `mkdocs build` was executed. Can be used as a fallback when
+ the build is performed outside of a git repository:
+
+ ``` yaml
+ plugins:
+ - git-revision-date-localized:
+ fallback_to_build_date: true
+ ```
+
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, which is why they may yield unexpected results. Use
+them at your own risk.
+
+ [git-revision-date-localized]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
+
+#### Document contributors
+
+<!-- md:version 9.5.0 -->
+<!-- md:plugin [git-committers] -->
+<!-- md:flag experimental -->
+
+The [git-committers][^2] plugin renders the GitHub avatars of all contributors,
+linking to their GitHub profiles at the bottom of each page. As always, it can
+be installed with `pip`:
+
+ [^2]:
+ We currently recommend using a fork of the [git-committers] plugin, as it
+ contains many improvements that have not yet been merged back into the
+ original plugin. See byrnereese/mkdocs-git-committers-plugin#12 for more
+ information.
+
+```
+pip install mkdocs-git-committers-plugin-2
+```
+
+Then, add the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - git-committers:
+ repository: squidfunk/mkdocs-material
+ branch: main
+```
+
+The following configuration options are supported:
+
+<!-- md:option git-committers.enabled -->
+
+: <!-- md:default `true` --> This option specifies whether
+ the plugin is enabled when building your project. If you want to switch
+ the plugin off, e.g. for local builds, use an [environment variable]:
+
+ ``` yaml
+ plugins:
+ - git-committers:
+ enabled: !ENV [CI, false]
+ ```
+
+<!-- md:option git-committers.repository -->
+
+: <!-- md:default none --> <!-- md:flag required -->
+ This property must be set to the slug of the repository that contains your
+ documentation. The slug must follow the pattern `<username>/<repository>`:
+
+ ``` yaml
+ plugins:
+ - git-committers:
+ repository: squidfunk/mkdocs-material
+ ```
+
+<!-- md:option git-committers.branch -->
+
+: <!-- md:default `master` --> This property should be set to
+ the branch of the repository from which to retrieve the contributors. To use the `main` branch:
+
+ ``` yaml
+ plugins:
+ - git-committers:
+ branch: main
+ ```
+
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, which is why they may yield unexpected results. Use
+them at your own risk.
+
+ [git-committers]: https://github.com/ojacques/mkdocs-git-committers-plugin-2
+ [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
+ [rate limits]: https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting
+
+#### Document authors
+
+<!-- md:version 9.5.0 -->
+<!-- md:plugin [git-authors] -->
+<!-- md:flag experimental -->
+
+The [git-authors] plugin is a lightweight alternative to the
+[git-committers] plugin and extracts the authors of a document from git to display
+them at the bottom of each page.
+
+Material for MkDocs offers deep integration for [git-authors]. This means the
+[customized overrides](https://timvink.github.io/mkdocs-git-authors-plugin/usage.html#mkdocs-material-theme)
+are not necessary, and additional styling (such as nice icons) are added.
+Simply install it with `pip`:
+
+```
+pip install mkdocs-git-authors-plugin
+```
+
+Then, add the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - git-authors
+```
+
+ [git-authors]: https://github.com/timvink/mkdocs-git-authors-plugin/
diff --git a/documents/markdown/mkdocs-material/setup_building-an-optimized-site.md b/documents/markdown/mkdocs-material/setup_building-an-optimized-site.md
new file mode 100644
index 0000000..3b133ee
--- /dev/null
+++ b/documents/markdown/mkdocs-material/setup_building-an-optimized-site.md
@@ -0,0 +1,106 @@
+# Building an optimized site
+
+Material for MkDocs, by default, allows to build optimized sites that rank great
+on search engines, load fast (even on slow networks), and work perfectly without
+JavaScript. Additionally, the [built-in optimize plugin] adds support for
+further useful automatic optimization techniques.
+
+ [built-in optimize plugin]: #built-in-optimize-plugin
+
+## Configuration
+
+### Built-in projects plugin
+
+<!-- md:version 9.7.0 -->
+<!-- md:plugin [projects] – built-in -->
+<!-- md:flag experimental -->
+
+The built-in projects plugin allows to split your documentation into multiple
+distinct MkDocs projects, __build them concurrently__ and
+__serve them together__. Add the following to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - projects
+```
+
+For a list of all settings, please consult the [plugin documentation].
+
+ [projects]: ../plugins/projects.md
+ [plugin documentation]: ../plugins/projects.md
+
+??? info "Use cases for the projects plugin"
+
+ Ideal use cases for the projects plugin are:
+
+ - Building a multi-language site
+ - Building a blog alongside your documentation
+ - Splitting large code bases for better performance
+
+ Note that the plugin is currently experimental. We're releasing it early,
+ so that we can improve it together with our users and make it even more
+ powerful as we discover new use cases.
+
+#### Scope
+
+<!-- md:version 8.0.0 -->
+<!-- md:default none -->
+
+There might be a use case, where you want to share user-level settings like
+the selected [color palette], or [cookie consent] across all projects. To do
+so, add the following lines to `mkdocs.yml`:
+
+``` yaml
+extra:
+ scope: /
+```
+
+!!! example "How it works"
+
+ Suppose you have this site structure:
+ ```
+ .
+ └── /
+ ├── subsite-a/
+ ├── subsite-b/
+ └── subsite-c/
+ ```
+ By default, each site will have its own scope (`/subsite-a/`, `/subsite-b/`,
+ `/subsite-c/`). To modify this behaviour, add the following lines to
+ `mkdocs.yml`:
+
+ ``` yaml
+ extra:
+ scope: /
+ ```
+
+ By setting it to `/`, it should allow you to share the following preferences
+ across the main site and all subsites:
+
+ - [Cookie consent][cookie consent]
+ - [Linking of content tabs, i.e. active tab]
+ - [Color palette][color palette]
+
+ [Scope support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.0.0
+ [cookie consent]: ../setup/ensuring-data-privacy.md#cookie-consent
+ [Linking of content tabs, i.e. active tab]: ../reference/content-tabs.md
+ [color palette]: ../setup/changing-the-colors.md#color-palette
+
+### Built-in optimize plugin
+
+<!-- md:version 9.7.0 -->
+<!-- md:plugin [optimize] – built-in -->
+<!-- md:flag experimental -->
+
+The built-in optimize plugin automatically identifies and optimizes all media
+files as part of the build using compression and conversion techniques. Add
+the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - optimize
+```
+
+For a list of all settings, please consult the [plugin documentation][optimize].
+
+ [optimize]: ../plugins/optimize.md
diff --git a/documents/markdown/mkdocs-material/setup_building-for-offline-usage.md b/documents/markdown/mkdocs-material/setup_building-for-offline-usage.md
new file mode 100644
index 0000000..9ceacf0
--- /dev/null
+++ b/documents/markdown/mkdocs-material/setup_building-for-offline-usage.md
@@ -0,0 +1,55 @@
+# Building for offline usage
+
+If you want to ship your documentation together with your product, MkDocs has
+you covered – with support from themes, [MkDocs] supports building
+offline-capable documentation. Notably, Material for MkDocs offers offline
+support for many of its features.
+
+ [MkDocs]: https://www.mkdocs.org
+
+## Configuration
+
+### Built-in offline plugin
+
+<!-- md:version 9.0.0 -->
+<!-- md:plugin [offline] – built-in -->
+
+The built-in offline plugin makes sure that the [site search] works when you
+distribute the contents of your [site directory] as a download. Simply add
+the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - offline
+```
+
+For a list of all settings, please consult the [plugin documentation].
+
+ [offline]: ../plugins/offline.md
+ [plugin documentation]: ../plugins/offline.md
+
+!!! tip "Automatically bundle all external assets"
+
+ The [built-in privacy plugin] makes it easy to use external assets
+ while building documentation for offline usage, as it will automatically
+ download all external assets to distribute them with your documentation.
+
+ [site search]: setting-up-site-search.md
+ [site directory]: https://www.mkdocs.org/user-guide/configuration/#site_dir
+ [built-in privacy plugin]:../plugins/privacy.md
+
+#### Limitations
+
+Material for MkDocs offers many interactive features, some of which will not
+work from the file system due to the restrictions of modern browsers: all
+features that use the `fetch` API will error.
+
+Thus, when building for offline usage, make sure to disable the following
+configuration settings: [instant loading], [site analytics], [git repository],
+[versioning] and [comment systems].
+
+ [Instant loading]: setting-up-navigation.md#instant-loading
+ [Site analytics]: setting-up-site-analytics.md
+ [Versioning]: setting-up-versioning.md
+ [Git repository]: adding-a-git-repository.md
+ [Comment systems]: adding-a-comment-system.md
diff --git a/documents/markdown/mkdocs-material/setup_changing-the-colors.md b/documents/markdown/mkdocs-material/setup_changing-the-colors.md
new file mode 100644
index 0000000..bcaffff
--- /dev/null
+++ b/documents/markdown/mkdocs-material/setup_changing-the-colors.md
@@ -0,0 +1,401 @@
+# Changing the colors
+
+As any proper Material Design implementation, Material for MkDocs supports
+Google's original [color palette], which can be easily configured through
+`mkdocs.yml`. Furthermore, colors can be customized with a few lines of CSS to
+fit your brand's identity by using [CSS variables][custom colors].
+
+ [color palette]: http://www.materialui.co/colors
+ [custom colors]: #custom-colors
+
+## Configuration
+
+### Color palette
+
+#### Color scheme
+
+<!-- md:version 5.2.0 -->
+<!-- md:default `default` -->
+
+Material for MkDocs supports two color schemes: a __light mode__, which is just
+called `default`, and a __dark mode__, which is called `slate`. The color scheme
+can be set via `mkdocs.yml`:
+
+``` yaml
+theme:
+ palette:
+ scheme: default
+```
+
+Click on a tile to change the color scheme:
+
+<div class="mdx-switch">
+ <button data-md-color-scheme="default"><code>default</code></button>
+ <button data-md-color-scheme="slate"><code>slate</code></button>
+</div>
+
+<script>
+ var buttons = document.querySelectorAll("button[data-md-color-scheme]")
+ buttons.forEach(function(button) {
+ button.addEventListener("click", function() {
+ document.body.setAttribute("data-md-color-switching", "")
+ var attr = this.getAttribute("data-md-color-scheme")
+ document.body.setAttribute("data-md-color-scheme", attr)
+ var name = document.querySelector("#__code_0 code span.l")
+ name.textContent = attr
+ setTimeout(function() {
+ document.body.removeAttribute("data-md-color-switching")
+ })
+ })
+ })
+</script>
+
+#### Primary color
+
+<!-- md:version 0.2.0 -->
+<!-- md:default `indigo` -->
+
+The primary color is used for the header, the sidebar, text links and several
+other components. In order to change the primary color, set the following value
+in `mkdocs.yml` to a valid color name:
+
+``` yaml
+theme:
+ palette:
+ primary: indigo
+```
+
+Click on a tile to change the primary color:
+
+<div class="mdx-switch">
+ <button data-md-color-primary="red"><code>red</code></button>
+ <button data-md-color-primary="pink"><code>pink</code></button>
+ <button data-md-color-primary="purple"><code>purple</code></button>
+ <button data-md-color-primary="deep-purple"><code>deep purple</code></button>
+ <button data-md-color-primary="indigo"><code>indigo</code></button>
+ <button data-md-color-primary="blue"><code>blue</code></button>
+ <button data-md-color-primary="light-blue"><code>light blue</code></button>
+ <button data-md-color-primary="cyan"><code>cyan</code></button>
+ <button data-md-color-primary="teal"><code>teal</code></button>
+ <button data-md-color-primary="green"><code>green</code></button>
+ <button data-md-color-primary="light-green"><code>light green</code></button>
+ <button data-md-color-primary="lime"><code>lime</code></button>
+ <button data-md-color-primary="yellow"><code>yellow</code></button>
+ <button data-md-color-primary="amber"><code>amber</code></button>
+ <button data-md-color-primary="orange"><code>orange</code></button>
+ <button data-md-color-primary="deep-orange"><code>deep orange</code></button>
+ <button data-md-color-primary="brown"><code>brown</code></button>
+ <button data-md-color-primary="grey"><code>grey</code></button>
+ <button data-md-color-primary="blue-grey"><code>blue grey</code></button>
+ <button data-md-color-primary="black"><code>black</code></button>
+ <button data-md-color-primary="white"><code>white</code></button>
+</div>
+
+<script>
+ var buttons = document.querySelectorAll("button[data-md-color-primary]")
+ buttons.forEach(function(button) {
+ button.addEventListener("click", function() {
+ var attr = this.getAttribute("data-md-color-primary")
+ document.body.setAttribute("data-md-color-primary", attr)
+ var name = document.querySelector("#__code_1 code span.l")
+ name.textContent = attr.replace("-", " ")
+ })
+ })
+</script>
+
+See our guide below to learn how to set [custom colors].
+
+#### Accent color
+
+<!-- md:version 0.2.0 -->
+<!-- md:default `indigo` -->
+
+The accent color is used to denote elements that can be interacted with, e.g.
+hovered links, buttons and scrollbars. It can be changed in `mkdocs.yml` by
+choosing a valid color name:
+
+``` yaml
+theme:
+ palette:
+ accent: indigo
+```
+
+Click on a tile to change the accent color:
+
+<style>
+ .md-typeset button[data-md-color-accent] > code {
+ background-color: var(--md-code-bg-color);
+ color: var(--md-accent-fg-color);
+ }
+</style>
+
+<div class="mdx-switch">
+ <button data-md-color-accent="red"><code>red</code></button>
+ <button data-md-color-accent="pink"><code>pink</code></button>
+ <button data-md-color-accent="purple"><code>purple</code></button>
+ <button data-md-color-accent="deep-purple"><code>deep purple</code></button>
+ <button data-md-color-accent="indigo"><code>indigo</code></button>
+ <button data-md-color-accent="blue"><code>blue</code></button>
+ <button data-md-color-accent="light-blue"><code>light blue</code></button>
+ <button data-md-color-accent="cyan"><code>cyan</code></button>
+ <button data-md-color-accent="teal"><code>teal</code></button>
+ <button data-md-color-accent="green"><code>green</code></button>
+ <button data-md-color-accent="light-green"><code>light green</code></button>
+ <button data-md-color-accent="lime"><code>lime</code></button>
+ <button data-md-color-accent="yellow"><code>yellow</code></button>
+ <button data-md-color-accent="amber"><code>amber</code></button>
+ <button data-md-color-accent="orange"><code>orange</code></button>
+ <button data-md-color-accent="deep-orange"><code>deep orange</code></button>
+</div>
+
+<script>
+ var buttons = document.querySelectorAll("button[data-md-color-accent]")
+ buttons.forEach(function(button) {
+ button.addEventListener("click", function() {
+ var attr = this.getAttribute("data-md-color-accent")
+ document.body.setAttribute("data-md-color-accent", attr)
+ var name = document.querySelector("#__code_2 code span.l")
+ name.textContent = attr.replace("-", " ")
+ })
+ })
+</script>
+
+See our guide below to learn how to set [custom colors].
+
+### Color palette toggle
+
+<!-- md:version 7.1.0 -->
+<!-- md:default none -->
+<!-- md:example color-palette-toggle -->
+
+Offering a light _and_ dark color palette makes your documentation pleasant to
+read at different times of the day, so the user can choose accordingly. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ palette: # (1)!
+
+ # Palette toggle for light mode
+ - scheme: default
+ toggle:
+ icon: material/brightness-7 # (2)!
+ name: Switch to dark mode
+
+ # Palette toggle for dark mode
+ - scheme: slate
+ toggle:
+ icon: material/brightness-4
+ name: Switch to light mode
+```
+
+1. Note that the `theme.palette` setting is now defined as a list.
+
+2. Enter a few keywords to find the perfect icon using our [icon search] and
+ click on the shortcode to copy it to your clipboard:
+
+ <div class="mdx-iconsearch" data-mdx-component="iconsearch">
+ <input class="md-input md-input--stretch mdx-iconsearch__input" placeholder="Search icon" data-mdx-component="iconsearch-query" value="brightness" />
+ <div class="mdx-iconsearch-result" data-mdx-component="iconsearch-result" data-mdx-mode="file">
+ <div class="mdx-iconsearch-result__meta"></div>
+ <ol class="mdx-iconsearch-result__list"></ol>
+ </div>
+ </div>
+
+This configuration will render a color palette toggle next to the search bar.
+Note that you can also define separate settings for [`primary`][palette.primary]
+and [`accent`][palette.accent] per color palette.
+
+The following properties must be set for each toggle:
+
+<!-- md:option palette.toggle.icon -->
+
+: <!-- md:default none --> <!-- md:flag required -->
+ This property must point to a valid icon path referencing any icon bundled
+ with the theme, or the build will not succeed. Some popular combinations:
+
+ * :material-brightness-7: + :material-brightness-4: – `material/brightness-7` + `material/brightness-4`
+ * :material-toggle-switch: + :material-toggle-switch-off-outline: – `material/toggle-switch` + `material/toggle-switch-off-outline`
+ * :material-weather-night: + :material-weather-sunny: – `material/weather-night` + `material/weather-sunny`
+ * :material-eye: + :material-eye-outline: – `material/eye` + `material/eye-outline`
+ * :material-lightbulb: + :material-lightbulb-outline: – `material/lightbulb` + `material/lightbulb-outline`
+
+<!-- md:option palette.toggle.name -->
+
+: <!-- md:default none --> <!-- md:flag required -->
+ This property is used as the toggle's `title` attribute and should be set to
+ a discernable name to improve accessibility. It's rendered as a [tooltip].
+
+ [palette.scheme]: #color-scheme
+ [palette.primary]: #primary-color
+ [palette.accent]: #accent-color
+ [icon search]: ../reference/icons-emojis.md#search
+ [tooltip]: ../reference/tooltips.md
+
+### System preference
+
+<!-- md:version 7.1.0 -->
+<!-- md:default none -->
+<!-- md:example color-palette-system-preference -->
+
+Each color palette can be linked to the user's system preference for light and
+dark appearance by using a media query. Simply add a `media` property next to
+the `scheme` definition in `mkdocs.yml`:
+
+``` yaml
+theme:
+ palette:
+
+ # Palette toggle for light mode
+ - media: "(prefers-color-scheme: light)"
+ scheme: default
+ toggle:
+ icon: material/brightness-7
+ name: Switch to dark mode
+
+ # Palette toggle for dark mode
+ - media: "(prefers-color-scheme: dark)"
+ scheme: slate
+ toggle:
+ icon: material/brightness-4
+ name: Switch to light mode
+```
+
+When the user first visits your site, the media queries are evaluated in the
+order of their definition. The first media query that matches selects the
+default color palette.
+
+#### Automatic light / dark mode
+
+<!-- md:version 9.5.0 -->
+<!-- md:flag experimental -->
+<!-- md:example color-palette-system-preference -->
+
+Newer operating systems allow to automatically switch between light and dark
+appearance during day and night times. Material for MkDocs adds support for
+automatic light / dark mode, delegating color palette selection to the user's
+operating system. Add the following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ palette:
+
+ # Palette toggle for automatic mode
+ - media: "(prefers-color-scheme)"
+ toggle:
+ icon: material/brightness-auto
+ name: Switch to light mode
+
+ # Palette toggle for light mode
+ - media: "(prefers-color-scheme: light)"
+ scheme: default # (1)!
+ toggle:
+ icon: material/brightness-7
+ name: Switch to dark mode
+
+ # Palette toggle for dark mode
+ - media: "(prefers-color-scheme: dark)"
+ scheme: slate
+ toggle:
+ icon: material/brightness-4
+ name: Switch to system preference
+```
+
+1. You can also define separate settings for [`primary`][palette.primary] and
+ [`accent`][palette.accent] per color palette, i.e. different colors for
+ light and dark mode.
+
+Material for MkDocs will now change the color palette each time the operating
+system switches between light and dark appearance, even when the user doesn't
+reload the site.
+
+## Customization
+
+### Custom colors
+
+<!-- md:version 5.0.0 -->
+<!-- md:example custom-colors -->
+
+Material for MkDocs implements colors using [CSS variables] (custom
+properties). If you want to customize the colors beyond the palette (e.g. to
+use your brand-specific colors), you can add an [additional style sheet] and
+tweak the values of the CSS variables.
+
+First, set the [`primary`][palette.primary] or [`accent`][palette.accent] values
+in `mkdocs.yml` to `custom`, to signal to the theme that you want to define
+custom colors, e.g., when you want to override the `primary` color:
+
+``` yaml
+theme:
+ palette:
+ primary: custom
+```
+
+Let's say you're :fontawesome-brands-youtube:{ style="color: #EE0F0F" }
+__YouTube__, and want to set the primary color to your brand's palette. Just
+add:
+
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+ ``` css
+ :root > * {
+ --md-primary-fg-color: #EE0F0F;
+ --md-primary-fg-color--light: #ECB7B7;
+ --md-primary-fg-color--dark: #90030C;
+ }
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_css:
+ - stylesheets/extra.css
+ ```
+
+See the file containing the [color definitions] for a list of all CSS variables.
+
+ [CSS variables]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
+ [color definitions]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/assets/stylesheets/main/_colors.scss
+ [additional style sheet]: ../customization.md#additional-css
+
+
+### Custom color schemes
+
+Besides overriding specific colors, you can create your own, named color scheme
+by wrapping the definitions in a `[data-md-color-scheme="..."]`
+[attribute selector], which you can then set via `mkdocs.yml` as described
+in the [color schemes][palette.scheme] section:
+
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+ ``` css
+ [data-md-color-scheme="youtube"] {
+ --md-primary-fg-color: #EE0F0F;
+ --md-primary-fg-color--light: #ECB7B7;
+ --md-primary-fg-color--dark: #90030C;
+ }
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ theme:
+ palette:
+ scheme: youtube
+ extra_css:
+ - stylesheets/extra.css
+ ```
+
+Additionally, the `slate` color scheme defines all of it's colors via `hsla`
+color functions and deduces its colors from the `--md-hue` CSS variable. You
+can tune the `slate` theme with:
+
+``` css
+[data-md-color-scheme="slate"] {
+ --md-hue: 210; /* (1)! */
+}
+```
+
+1. The `hue` value must be in the range of `[0, 360]`
+
+ [attribute selector]: https://www.w3.org/TR/selectors-4/#attribute-selectors
diff --git a/documents/markdown/mkdocs-material/setup_changing-the-fonts.md b/documents/markdown/mkdocs-material/setup_changing-the-fonts.md
new file mode 100644
index 0000000..cb7da21
--- /dev/null
+++ b/documents/markdown/mkdocs-material/setup_changing-the-fonts.md
@@ -0,0 +1,119 @@
+# Changing the fonts
+
+Material for MkDocs makes it easy to change the typeface of your project
+documentation, as it directly integrates with [Google Fonts]. Alternatively,
+fonts can be custom-loaded if self-hosting is preferred for data privacy reasons
+or another destination should be used.
+
+ [Google Fonts]: https://fonts.google.com
+
+## Configuration
+
+### Regular font
+
+<!-- md:version 0.1.2 -->
+<!-- md:default [`Roboto`][Roboto] -->
+
+The regular font is used for all body copy, headlines, and essentially
+everything that does not need to be monospaced. It can be set to any
+valid [Google Font][Google Fonts] via `mkdocs.yml`:
+
+``` yaml
+theme:
+ font:
+ text: Roboto
+```
+
+The typeface will be loaded in 300, 400, _400i_ and __700__.
+
+ [Roboto]: https://fonts.google.com/specimen/Roboto
+
+### Monospaced font
+
+<!-- md:version 0.1.2 -->
+<!-- md:default [`Roboto Mono`][Roboto Mono] -->
+
+The _monospaced font_ is used for code blocks and can be configured separately.
+Just like the regular font, it can be set to any valid [Google Font]
+[Google Fonts] via `mkdocs.yml`:
+
+``` yaml
+theme:
+ font:
+ code: Roboto Mono
+```
+
+The typeface will be loaded in 400.
+
+ [Roboto Mono]: https://fonts.google.com/specimen/Roboto+Mono
+
+### Autoloading
+
+<!-- md:version 1.0.0 -->
+<!-- md:default none -->
+
+If you want to prevent typefaces from being loaded from [Google Fonts], e.g.
+to adhere to [data privacy] regulations, and fall back to system fonts, add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ font: false
+```
+
+!!! tip "Automatically bundle Google Fonts"
+
+ The [built-in privacy plugin] makes it easy to use Google Fonts
+ while complying with the __General Data Protection Regulation__ (GDPR),
+ by automatically downloading and self-hosting the web font files.
+
+ [data privacy]: https://developers.google.com/fonts/faq/privacy
+ [built-in privacy plugin]:../plugins/privacy.md
+
+## Customization
+
+### Additional fonts
+
+If you want to load an (additional) font from another destination or override
+the system font, you can use an [additional style sheet] to add the
+corresponding `@font-face` definition:
+
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+ ``` css
+ @font-face {
+ font-family: "<font>";
+ src: "...";
+ }
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_css:
+ - stylesheets/extra.css
+ ```
+
+The font can then be applied to specific elements, e.g. only headlines, or
+globally to be used as the site-wide regular or monospaced font:
+
+=== "Regular font"
+
+ ``` css
+ :root {
+ --md-text-font: "<font>"; /* (1)! */
+ }
+ ```
+
+ 1. Always define fonts through CSS variables and not `font-family`, as
+ this would disable the system font fallback.
+
+=== "Monospaced font"
+
+ ``` css
+ :root {
+ --md-code-font: "<font>";
+ }
+ ```
+
+ [additional style sheet]: ../customization.md#additional-css
diff --git a/documents/markdown/mkdocs-material/setup_changing-the-language.md b/documents/markdown/mkdocs-material/setup_changing-the-language.md
new file mode 100644
index 0000000..e61ad4b
--- /dev/null
+++ b/documents/markdown/mkdocs-material/setup_changing-the-language.md
@@ -0,0 +1,184 @@
+# Changing the language
+
+Material for MkDocs supports internationalization (i18n) and provides
+translations for template variables and labels in 60+ languages. Additionally,
+the site search can be configured to use a language-specific stemmer, if
+available.
+
+## Configuration
+
+### Site language
+
+<!-- md:version 1.12.0 -->
+<!-- md:default `en` -->
+
+You can set the site language in `mkdocs.yml` with:
+
+``` yaml
+theme:
+ language: en # (1)!
+```
+
+1. HTML5 only allows to set a [single language per document], which is why
+ Material for MkDocs only supports setting a canonical language for the
+ entire project, i.e. one per `mkdocs.yml`.
+
+ The easiest way to build a multi-language documentation is to create one
+ project in a subfolder per language, and then use the [language selector]
+ to interlink those projects.
+
+The following languages are supported:
+
+<!-- hooks/translations.py -->
+
+Note that some languages will produce unreadable anchor links due to the way
+the default slug function works. Consider using a [Unicode-aware slug function].
+
+ [single language per document]: https://www.w3.org/International/questions/qa-html-language-declarations.en#attributes
+ [language selector]: #site-language-selector
+ [Unicode-aware slug function]: extensions/python-markdown.md#+toc.slugify
+
+### Site language selector
+
+<!-- md:version 7.0.0 -->
+<!-- md:default none -->
+
+If your documentation is available in multiple languages, a language selector
+pointing to those languages can be added to the header. Alternate languages
+can be defined via `mkdocs.yml`.
+
+``` yaml
+extra:
+ alternate:
+ - name: English
+ link: /en/ # (1)!
+ lang: en
+ - name: Deutsch
+ link: /de/
+ lang: de
+```
+
+1. Note that this must be an absolute link. If it includes a domain part, it's
+ used as defined. Otherwise the domain part of the [`site_url`][site_url] as
+ set in `mkdocs.yml` is prepended to the link.
+
+The following properties are available for each alternate language:
+
+<!-- md:option alternate.name -->
+
+: <!-- md:default none --> <!-- md:flag required -->
+ This value of this property is used inside the language selector as the
+ name of the language and must be set to a non-empty string.
+
+<!-- md:option alternate.link -->
+
+: <!-- md:default none --> <!-- md:flag required -->
+ This property must be set to an absolute link, which might also point to
+ another domain or subdomain not necessarily generated with MkDocs.
+
+<!-- md:option alternate.lang -->
+
+: <!-- md:default none --> <!-- md:flag required -->
+ This property must contain an [ISO 639-1 language code] and is used for
+ the `hreflang` attribute of the link, improving discoverability via search
+ engines.
+
+[![Language selector preview]][Language selector preview]
+
+ [site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
+ [ISO 639-1 language code]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
+ [Language selector preview]: ../assets/screenshots/language-selection.png
+
+#### Stay on page
+
+<!-- md:version 9.7.0 -->
+<!-- md:flag experimental -->
+
+When switching between languages, e.g., if language `en` and `de` contain a page
+with the same path name, the user will stay on the current page:
+
+```
+docs.example.com/en/ -> docs.example.com/de/
+docs.example.com/en/foo/ -> docs.example.com/de/foo/
+docs.example.com/en/bar/ -> docs.example.com/de/bar/
+```
+
+No configuration is necessary.
+
+### Directionality
+
+<!-- md:version 2.5.0 -->
+<!-- md:default computed -->
+
+While many languages are read `ltr` (left-to-right), Material for MkDocs also
+supports `rtl` (right-to-left) directionality which is deduced from the
+selected language, but can also be set with:
+
+``` yaml
+theme:
+ direction: ltr
+```
+
+Click on a tile to change the directionality:
+
+<div class="mdx-switch">
+ <button data-md-dir="ltr"><code>ltr</code></button>
+ <button data-md-dir="rtl"><code>rtl</code></button>
+</div>
+
+<script>
+ var buttons = document.querySelectorAll("button[data-md-dir]")
+ buttons.forEach(function(button) {
+ button.addEventListener("click", function() {
+ var attr = this.getAttribute("data-md-dir")
+ document.body.dir = attr
+ var name = document.querySelector("#__code_2 code span.l")
+ name.textContent = attr
+ })
+ })
+</script>
+
+## Customization
+
+### Custom translations
+
+If you want to customize some of the translations for a language, just follow
+the guide on [theme extension] and create a new partial in the `overrides`
+folder. Then, import the [translations] of the language as a fallback and only
+adjust the ones you want to override:
+
+=== ":octicons-file-code-16: `overrides/partials/languages/custom.html`"
+
+ ``` html
+ <!-- Import translations for language and fallback -->
+ {% import "partials/languages/de.html" as language %}
+ {% import "partials/languages/en.html" as fallback %} <!-- (1)! -->
+
+ <!-- Define custom translations -->
+ {% macro override(key) %}{{ {
+ "source.file.date.created": "Erstellt am", <!-- (2)! -->
+ "source.file.date.updated": "Aktualisiert am"
+ }[key] }}{% endmacro %}
+
+ <!-- Re-export translations -->
+ {% macro t(key) %}{{
+ override(key) or language.t(key) or fallback.t(key)
+ }}{% endmacro %}
+ ```
+
+ 1. Note that `en` must always be used as a fallback language, as it's the
+ default theme language.
+
+ 2. Check the [list of available languages], pick the translation you want
+ to override for your language and add them here.
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ theme:
+ language: custom
+ ```
+
+ [theme extension]: ../customization.md#extending-the-theme
+ [translations]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/languages/
+ [list of available languages]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/languages/
diff --git a/documents/markdown/mkdocs-material/setup_changing-the-logo-and-icons.md b/documents/markdown/mkdocs-material/setup_changing-the-logo-and-icons.md
new file mode 100644
index 0000000..c26529c
--- /dev/null
+++ b/documents/markdown/mkdocs-material/setup_changing-the-logo-and-icons.md
@@ -0,0 +1,166 @@
+# Changing the logo and icons
+
+When installing Material for MkDocs, you immediately get access to _over 8,000
+icons_ ready to be used for customization of specific parts of the theme and/or
+when writing your documentation in Markdown. Not enough? You can also add
+[additional icons] with minimal effort.
+
+ [additional icons]: #additional-icons
+
+## Configuration
+
+### Logo
+
+<!-- md:version 0.1.0 -->
+<!-- md:default `material/library` -->
+
+The logo can be changed to a user-provided image (any type, incl. `*.png` and
+`*.svg`) located in the `docs` folder, or to any icon bundled with the theme.
+Add the following lines to `mkdocs.yml`:
+
+=== ":octicons-image-16: Image"
+
+ ``` yaml
+ theme:
+ logo: assets/logo.png
+ ```
+
+=== ":octicons-package-16: Icon, bundled"
+
+ ``` yaml
+ theme:
+ icon:
+ logo: material/library # (1)!
+ ```
+
+ 1. Enter a few keywords to find the perfect icon using our [icon search] and
+ click on the shortcode to copy it to your clipboard:
+
+ <div class="mdx-iconsearch" data-mdx-component="iconsearch">
+ <input class="md-input md-input--stretch mdx-iconsearch__input" placeholder="Search icon" data-mdx-component="iconsearch-query" value="material library" />
+ <div class="mdx-iconsearch-result" data-mdx-component="iconsearch-result" data-mdx-mode="file">
+ <div class="mdx-iconsearch-result__meta"></div>
+ <ol class="mdx-iconsearch-result__list"></ol>
+ </div>
+ </div>
+
+ [icon search]: ../reference/icons-emojis.md#search
+
+Normally, the logo in the header and sidebar links to the homepage of the
+documentation, which is the same as `site_url`. This behavior can be changed
+with the following configuration:
+
+``` yaml
+extra:
+ homepage: https://example.com
+```
+
+### Favicon
+
+<!-- md:version 0.1.0 -->
+<!-- md:default [`assets/images/favicon.png`][Favicon default] -->
+
+The favicon can be changed to a path pointing to a user-provided image, which
+must be located in the `docs` folder. Add the following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ favicon: images/favicon.png
+```
+
+ [Favicon default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/templates/assets/images/favicon.png
+
+### Site icons
+
+[:octicons-tag-24: 9.2.0][Site icon support]
+
+Most icons you see on your site, such as navigation icons, can also be changed. For example,
+to change the navigation arrows in the footer, add the following lines to `mkdocs.yml`:
+
+```yaml
+theme:
+ icon:
+ previous: fontawesome/solid/angle-left
+ next: fontawesome/solid/angle-right
+```
+
+The following is a complete list of customizable icons used by the theme:
+
+| Icon name | Purpose |
+|:-------------|:------------------------------------------------------------------------------|
+| `logo` | See [Logo](#logo) |
+| `menu` | Open drawer |
+| `alternate` | Change language |
+| `search` | Search icon |
+| `share` | Share search |
+| `close` | Reset search, dismiss announcements |
+| `top` | Back-to-top button |
+| `edit` | Edit current page |
+| `view` | View page source |
+| `repo` | Repository icon |
+| `admonition` | See [Admonition icons](../reference/admonitions.md#admonition-icons) |
+| `tag` | See [Tag icons and identifiers](setting-up-tags.md#tag-icons-and-identifiers) |
+| `previous` | Previous page in footer, hide search on mobile |
+| `next` | Next page in footer |
+
+ [Site icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
+
+## Customization
+
+### Additional icons
+
+In order to use custom icons, [extend the theme] and create a new folder named
+`.icons` in the [`custom_dir`][custom_dir] you want to use for overrides.
+Next, add your `*.svg` icons into a subfolder of the `.icons` folder. Let's say
+you downloaded and unpacked the [Bootstrap] icon set, and want to add it to
+your project documentation. The structure of your project should look like this:
+
+``` { .sh .no-copy }
+.
+├─ overrides/
+│ └─ .icons/
+│ └─ bootstrap/
+│ └─ *.svg
+└─ mkdocs.yml
+```
+
+Then, add the following lines to `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.emoji:
+ emoji_index: !!python/name:material.extensions.emoji.twemoji
+ emoji_generator: !!python/name:material.extensions.emoji.to_svg
+ options:
+ custom_icons:
+ - overrides/.icons
+```
+
+You can now use all :fontawesome-brands-bootstrap: Bootstrap icons anywhere in
+Markdown files, as well as everywhere icons can be used in `mkdocs.yml`.
+However, note that the syntaxes are slightly different:
+
+- __Using icons in configuration__: take the path of the `*.svg` icon file
+ starting at the `.icons` folder and drop the file extension, e.g. for
+ `.icons/bootstrap/envelope-paper.svg`, use:
+
+ ``` yaml
+ theme:
+ icon:
+ logo: bootstrap/envelope-paper
+ ```
+
+- __Using icons in Markdown files__: additionally to taking the path from the
+ `.icons` folder as noted above, replace all `/` with `-` and enclose the icon
+ shortcode in two colons:
+
+ ```
+ :bootstrap-envelope-paper:
+ ```
+
+For further notes on icon usage, please consult the [icon reference].
+
+ [extend the theme]: ../customization.md#extending-the-theme
+ [custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
+ [Bootstrap]: https://icons.getbootstrap.com/
+ [icon reference]: ../reference/icons-emojis.md#using-icons
diff --git a/documents/markdown/mkdocs-material/setup_ensuring-data-privacy.md b/documents/markdown/mkdocs-material/setup_ensuring-data-privacy.md
new file mode 100644
index 0000000..113562c
--- /dev/null
+++ b/documents/markdown/mkdocs-material/setup_ensuring-data-privacy.md
@@ -0,0 +1,320 @@
+# Ensuring data privacy
+
+Material for MkDocs makes compliance with data privacy regulations very easy,
+as it offers a native [cookie consent] solution to seek explicit consent from
+users before setting up [analytics]. Additionally, external assets can be
+automatically downloaded for [self-hosting].
+
+ [cookie consent]: #cookie-consent
+ [analytics]: setting-up-site-analytics.md
+ [self-hosting]: #built-in-privacy-plugin
+
+## Configuration
+
+### Cookie consent
+
+<!-- md:version 8.4.0 -->
+<!-- md:default none -->
+<!-- md:flag experimental -->
+<!-- md:example cookie-consent -->
+
+Material for MkDocs ships a native and extensible cookie consent form which
+asks the user for consent prior to sending requests to third parties. Add the
+following to `mkdocs.yml`:
+
+``` yaml
+extra:
+ consent:
+ title: Cookie consent
+ description: >- # (1)!
+ We use cookies to recognize your repeated visits and preferences, as well
+ as to measure the effectiveness of our documentation and whether users
+ find what they're searching for. With your consent, you're helping us to
+ make our documentation better.
+```
+
+1. You can add arbitrary HTML tags in the `description`, e.g. to link to your
+ terms of service or other parts of the site.
+
+The following properties are available:
+
+<!-- md:option consent.title -->
+
+: <!-- md:default none --> <!-- md:flag required -->
+ This property sets the title of the cookie consent, which is rendered at the
+ top of the form and must be set to a non-empty string.
+
+<!-- md:option consent.description -->
+
+: <!-- md:default none --> <!-- md:flag required -->
+ This property sets the description of the cookie consent, is rendered below
+ the title, and may include raw HTML (e.g. a links to the terms of service).
+
+<!-- md:option consent.cookies -->
+
+: <!-- md:default none --> This property allows to add custom
+ cookies or change the initial `checked` state and name of built-in cookies.
+ Currently, the following cookies are built-in:
+
+ - __Google Analytics__ – `analytics` (enabled by default)
+ - __GitHub__ – `github` (enabled by default)
+
+ Each cookie must receive a unique identifier which is used as a key in the
+ `cookies` map, and can be either set to a string, or to a map defining
+ `name` and `checked` state:
+
+ === "Custom cookie name"
+
+ ``` yaml
+ extra:
+ consent:
+ cookies:
+ analytics: Custom name
+ ```
+
+ === "Custom initial state"
+
+ ``` yaml
+ extra:
+ consent:
+ cookies:
+ analytics:
+ name: Google Analytics
+ checked: false
+ ```
+
+ === "Custom cookie"
+
+ ``` yaml
+ extra:
+ consent:
+ cookies:
+ analytics: Google Analytics # (1)!
+ custom: Custom cookie
+ ```
+
+ 1. If you define a custom cookie as part of the `cookies` property,
+ the `analytics` cookie must be added back explicitly, or analytics
+ won't be triggered.
+
+ If Google Analytics was configured via `mkdocs.yml`, the cookie consent will
+ automatically include a setting for the user to disable it. [Custom cookies]
+ can be used from JavaScript.
+
+<!-- md:option consent.actions -->
+
+: <!-- md:default `[accept, manage]` --> This property defines
+ which buttons are shown and in which order, e.g. to allow the user to accept
+ cookies and manage settings:
+
+ ``` yaml
+ extra:
+ consent:
+ actions:
+ - accept
+ - manage # (1)!
+ ```
+
+ 1. If the `manage` settings button is omitted from the `actions` property,
+ the settings are always shown.
+
+ The cookie consent form includes three types of buttons:
+
+ - `accept` – Button to accept selected cookies
+ - `reject` – Button to reject all cookies
+ - `manage` – Button to manage settings
+
+When a user first visits your site, a cookie consent form is rendered:
+
+[![Cookie consent enabled]][Cookie consent enabled]
+
+ [Custom cookies]: #custom-cookies
+ [Cookie consent enabled]: ../assets/screenshots/consent.png
+
+#### Change cookie settings
+
+In order to comply with GDPR, users must be able to change their cookie settings
+at any time. This can be done by adding a simple link to your [copyright notice]
+in `mkdocs.yml`:
+
+``` yaml
+copyright: >
+ Copyright © 2016 - 2024 Martin Donath –
+ <a href="#__consent">Change cookie settings</a>
+```
+
+ [copyright notice]: setting-up-the-footer.md#copyright-notice
+
+### Built-in privacy plugin
+
+<!-- md:version 9.5.0 -->
+<!-- md:plugin [privacy][built-in privacy plugin] -->
+<!-- md:flag experimental -->
+
+The built-in privacy plugin automatically identifies external assets as part
+of the build process and downloads all assets for very simple self-hosting. Add
+the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - privacy
+```
+
+For a list of all settings, please consult the [plugin documentation].
+
+ [plugin documentation]: ../plugins/privacy.md
+
+!!! tip "Hosting images externally and optimizing them automatically"
+
+ This option makes the [built-in privacy plugin] an excellent choice for
+ when you want to host assets like images outside of your git repository
+ in another location to keep them fresh and your repository lean.
+
+ Additionally, as of <!-- md:version 9.7.0 -->, the
+ built-in privacy plugin was entirely rewritten and now works perfectly
+ with the [built-in optimize plugin], which means that external assets
+ can be passed through the same optimization pipeline as the rest of your
+ documentation. This means you can store and edit unoptimized files
+ outside of your repository, and let both plugins built a highly
+ optimized site for you.
+
+ If you want to implement separate pipelines, i.e., optimize some images
+ differently from others or exclude some images from downloading, you can
+ use multiple instances of the [built-in privacy plugin].
+
+!!! question "Why can't Material for MkDocs bundle all assets by design?"
+
+ The primary reason why Material for MkDocs can't just bundle all of its own
+ assets is the integration with [Google Fonts], which offers over a thousand
+ different fonts that can be used to render your documentation. Most of the
+ fonts include several weights and are split up into different character sets
+ to keep the download size small, so the browser only downloads what is
+ really needed. For Roboto, our default [regular font], this results in [42
+ `*.woff2` files in total][example].
+
+ If Material for MkDocs would bundle all font files, the download size would
+ be in the hundreds of megabytes, slowing down automated builds. Furthermore,
+ authors might add external assets like third-party scripts or style sheets
+ that would need to be remembered to be defined as further local assets.
+
+ This is the very reason the [built-in privacy plugin] exists — it automates
+ the process of downloading all external assets manually to ensure compliance
+ with GDPR with some some [technical limitations].
+
+ [Google Fonts]: changing-the-fonts.md
+ [regular font]: changing-the-fonts.md#regular-font
+ [example]: #example
+ [built-in optimize plugin]: ../plugins/optimize.md
+ [technical limitations]: ../plugins/privacy.md#limitations
+
+??? example "Expand to inspect example"
+
+ For the official documentation, the [built-in privacy plugin] downloads the
+ following resources:
+
+ ``` { .sh .no-copy #example }
+ .
+ └─ assets/external/
+ ├─ unpkg.com/tablesort@5.3.0/dist/tablesort.min.js
+ ├─ fonts.googleapis.com/css
+ └─ fonts.gstatic.com/s/
+ ├─ roboto/v29/
+ │ ├─ KFOjCnqEu92Fr1Mu51TjASc-CsTKlA.woff2
+ │ ├─ KFOjCnqEu92Fr1Mu51TjASc0CsTKlA.woff2
+ │ ├─ KFOjCnqEu92Fr1Mu51TjASc1CsTKlA.woff2
+ │ ├─ KFOjCnqEu92Fr1Mu51TjASc2CsTKlA.woff2
+ │ ├─ KFOjCnqEu92Fr1Mu51TjASc3CsTKlA.woff2
+ │ ├─ KFOjCnqEu92Fr1Mu51TjASc5CsTKlA.woff2
+ │ ├─ KFOjCnqEu92Fr1Mu51TjASc6CsQ.woff2
+ │ ├─ KFOjCnqEu92Fr1Mu51TzBic-CsTKlA.woff2
+ │ ├─ KFOjCnqEu92Fr1Mu51TzBic0CsTKlA.woff2
+ │ ├─ KFOjCnqEu92Fr1Mu51TzBic1CsTKlA.woff2
+ │ ├─ KFOjCnqEu92Fr1Mu51TzBic2CsTKlA.woff2
+ │ ├─ KFOjCnqEu92Fr1Mu51TzBic3CsTKlA.woff2
+ │ ├─ KFOjCnqEu92Fr1Mu51TzBic5CsTKlA.woff2
+ │ ├─ KFOjCnqEu92Fr1Mu51TzBic6CsQ.woff2
+ │ ├─ KFOkCnqEu92Fr1Mu51xEIzIFKw.woff2
+ │ ├─ KFOkCnqEu92Fr1Mu51xFIzIFKw.woff2
+ │ ├─ KFOkCnqEu92Fr1Mu51xGIzIFKw.woff2
+ │ ├─ KFOkCnqEu92Fr1Mu51xHIzIFKw.woff2
+ │ ├─ KFOkCnqEu92Fr1Mu51xIIzI.woff2
+ │ ├─ KFOkCnqEu92Fr1Mu51xLIzIFKw.woff2
+ │ ├─ KFOkCnqEu92Fr1Mu51xMIzIFKw.woff2
+ │ ├─ KFOlCnqEu92Fr1MmSU5fABc4EsA.woff2
+ │ ├─ KFOlCnqEu92Fr1MmSU5fBBc4.woff2
+ │ ├─ KFOlCnqEu92Fr1MmSU5fBxc4EsA.woff2
+ │ ├─ KFOlCnqEu92Fr1MmSU5fCBc4EsA.woff2
+ │ ├─ KFOlCnqEu92Fr1MmSU5fCRc4EsA.woff2
+ │ ├─ KFOlCnqEu92Fr1MmSU5fChc4EsA.woff2
+ │ ├─ KFOlCnqEu92Fr1MmSU5fCxc4EsA.woff2
+ │ ├─ KFOlCnqEu92Fr1MmWUlfABc4EsA.woff2
+ │ ├─ KFOlCnqEu92Fr1MmWUlfBBc4.woff2
+ │ ├─ KFOlCnqEu92Fr1MmWUlfBxc4EsA.woff2
+ │ ├─ KFOlCnqEu92Fr1MmWUlfCBc4EsA.woff2
+ │ ├─ KFOlCnqEu92Fr1MmWUlfCRc4EsA.woff2
+ │ ├─ KFOlCnqEu92Fr1MmWUlfChc4EsA.woff2
+ │ ├─ KFOlCnqEu92Fr1MmWUlfCxc4EsA.woff2
+ │ ├─ KFOmCnqEu92Fr1Mu4WxKOzY.woff2
+ │ ├─ KFOmCnqEu92Fr1Mu4mxK.woff2
+ │ ├─ KFOmCnqEu92Fr1Mu5mxKOzY.woff2
+ │ ├─ KFOmCnqEu92Fr1Mu72xKOzY.woff2
+ │ ├─ KFOmCnqEu92Fr1Mu7GxKOzY.woff2
+ │ ├─ KFOmCnqEu92Fr1Mu7WxKOzY.woff2
+ │ └─ KFOmCnqEu92Fr1Mu7mxKOzY.woff2
+ └─ robotomono/v13/
+ ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSV0mf0h.woff2
+ ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSZ0mf0h.woff2
+ ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSd0mf0h.woff2
+ ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSh0mQ.woff2
+ ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSt0mf0h.woff2
+ ├─ L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSx0mf0h.woff2
+ ├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtElOUlYIw.woff2
+ ├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEleUlYIw.woff2
+ ├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEluUlYIw.woff2
+ ├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEm-Ul.woff2
+ ├─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEmOUlYIw.woff2
+ └─ L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEn-UlYIw.woff2
+ ```
+
+ [built-in privacy plugin]: ../plugins/privacy.md
+ [preconnect]: https://developer.mozilla.org/en-US/docs/Web/Performance/dns-prefetch
+
+## Customization
+
+### Custom cookies
+
+<!-- md:version 8.4.0 -->
+<!-- md:example custom-cookies -->
+
+If you've customized the [cookie consent] and added a `custom` cookie, the user
+will be prompted to accept or reject your custom cookie. Once the user accepts
+or rejects the cookie consent, or [changes the settings], the page reloads[^1].
+Use [additional JavaScript] to query the result:
+
+ [^1]:
+ We reload the page to make interop with custom cookies simpler. If Material
+ for MkDocs would implement a callback-based approach, the author would need
+ to make sure to correctly update all scripts that use cookies. Additionally,
+ the cookie consent is only answered initially, which is why we consider this
+ to be a good trade-off of DX and UX.
+
+=== ":octicons-file-code-16: `docs/javascripts/consent.js`"
+
+ ``` js
+ var consent = __md_get("__consent")
+ if (consent && consent.custom) {
+ /* The user accepted the cookie */
+ } else {
+ /* The user rejected the cookie */
+ }
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_javascript:
+ - javascripts/consent.js
+ ```
+
+ [additional JavaScript]: ../customization.md#additional-javascript
+ [changes the settings]: #change-cookie-settings
diff --git a/documents/markdown/mkdocs-material/setup_extensions_index.md b/documents/markdown/mkdocs-material/setup_extensions_index.md
new file mode 100644
index 0000000..7acf2e6
--- /dev/null
+++ b/documents/markdown/mkdocs-material/setup_extensions_index.md
@@ -0,0 +1,137 @@
+---
+title: Extensions
+---
+
+# Extensions
+
+Markdown is a very small language with a kind-of reference implementation called
+[John Gruber's Markdown]. [Python Markdown] and [Python Markdown Extensions]
+are two packages that enhance the Markdown writing experience, adding useful
+syntax extensions for technical writing.
+
+ [John Gruber's Markdown]: https://daringfireball.net/projects/markdown/
+ [Python Markdown]: python-markdown.md
+ [Python Markdown Extensions]: python-markdown-extensions.md
+
+## Supported extensions
+
+The following extensions are all supported by Material for MkDocs and therefore
+strongly recommended. Click on each extension to learn about its purpose and
+configuration:
+
+<div class="mdx-columns" markdown>
+
+- [Abbreviations]
+- [Admonition]
+- [Arithmatex]
+- [Attribute Lists]
+- [BetterEm]
+- [Caret, Mark & Tilde]
+- [Critic]
+- [Definition Lists]
+- [Details]
+- [Emoji]
+- [Footnotes]
+- [Highlight]
+- [Keys]
+- [Markdown in HTML]
+- [SmartSymbols]
+- [Snippets]
+- [SuperFences]
+- [Tabbed]
+- [Table of Contents]
+- [Tables]
+- [Tasklist]
+
+</div>
+
+ [Abbreviations]: python-markdown.md#abbreviations
+ [Admonition]: python-markdown.md#admonition
+ [Arithmatex]: python-markdown-extensions.md#arithmatex
+ [Attribute Lists]: python-markdown.md#attribute-lists
+ [BetterEm]: python-markdown-extensions.md#betterem
+ [Caret, Mark & Tilde]: python-markdown-extensions.md#caret-mark-tilde
+ [Critic]: python-markdown-extensions.md#critic
+ [Definition Lists]: python-markdown.md#definition-lists
+ [Details]: python-markdown-extensions.md#details
+ [Emoji]: python-markdown-extensions.md#emoji
+ [Footnotes]: python-markdown.md#footnotes
+ [Highlight]: python-markdown-extensions.md#highlight
+ [Keys]: python-markdown-extensions.md#keys
+ [Markdown in HTML]: python-markdown.md#markdown-in-html
+ [SmartSymbols]: python-markdown-extensions.md#smartsymbols
+ [Snippets]: python-markdown-extensions.md#snippets
+ [SuperFences]: python-markdown-extensions.md#superfences
+ [Tabbed]: python-markdown-extensions.md#tabbed
+ [Table of Contents]: python-markdown.md#table-of-contents
+ [Tables]: python-markdown.md#tables
+ [Tasklist]: python-markdown-extensions.md#tasklist
+
+## Configuration
+
+Extensions are configured as part of `mkdocs.yml` – the MkDocs configuration
+file. The following sections contain two example configurations to bootstrap
+your documentation project.
+
+ [overview]: #advanced-configuration
+
+### Minimal configuration
+
+This configuration is a good starting point for when you're using Material for
+MkDocs for the first time. The best idea is to explore the [reference], and
+gradually add what you want to use:
+
+``` yaml
+markdown_extensions:
+
+ # Python Markdown
+ - toc:
+ permalink: true
+
+ # Python Markdown Extensions
+ - pymdownx.highlight
+ - pymdownx.superfences
+```
+
+ [reference]: ../../reference/index.md
+
+### Recommended configuration
+
+This configuration enables all Markdown-related features of Material for MkDocs
+and is great for experienced users bootstrapping a new documentation project:
+
+``` yaml
+markdown_extensions:
+
+ # Python Markdown
+ - abbr
+ - admonition
+ - attr_list
+ - def_list
+ - footnotes
+ - md_in_html
+ - toc:
+ permalink: true
+
+ # Python Markdown Extensions
+ - pymdownx.arithmatex:
+ generic: true
+ - pymdownx.betterem:
+ smart_enable: all
+ - pymdownx.caret
+ - pymdownx.details
+ - pymdownx.emoji:
+ emoji_index: !!python/name:material.extensions.emoji.twemoji
+ emoji_generator: !!python/name:material.extensions.emoji.to_svg
+ - pymdownx.highlight
+ - pymdownx.inlinehilite
+ - pymdownx.keys
+ - pymdownx.mark
+ - pymdownx.smartsymbols
+ - pymdownx.superfences
+ - pymdownx.tabbed:
+ alternate_style: true
+ - pymdownx.tasklist:
+ custom_checkbox: true
+ - pymdownx.tilde
+```
diff --git a/documents/markdown/mkdocs-material/setup_extensions_python-markdown-extensions.md b/documents/markdown/mkdocs-material/setup_extensions_python-markdown-extensions.md
new file mode 100644
index 0000000..97aa098
--- /dev/null
+++ b/documents/markdown/mkdocs-material/setup_extensions_python-markdown-extensions.md
@@ -0,0 +1,801 @@
+# Python Markdown Extensions
+
+The [Python Markdown Extensions] package is an excellent collection of
+additional extensions perfectly suited for advanced technical writing. Material
+for MkDocs lists this package as an explicit dependency, so it's automatically
+installed with a supported version.
+
+ [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
+
+## Supported extensions
+
+In general, all extensions that are part of [Python Markdown Extensions] should
+work with Material for MkDocs. The following list includes all extensions that
+are natively supported, meaning they work without any further adjustments.
+
+### Arithmatex
+
+<!-- md:version 1.0.0 -->
+<!-- md:extension [pymdownx.arithmatex][Arithmatex] -->
+
+The [Arithmatex] extension allows for rendering of block and inline block
+equations and integrates seamlessly with [MathJax][^1] – a library for
+mathematical typesetting. Enable it via `mkdocs.yml`:
+
+ [^1]:
+ Other libraries like [KaTeX] are also supported and can be integrated with
+ some additional effort. See the [Arithmatex documentation on KaTeX] for
+ further guidance, as this is beyond the scope of Material for MkDocs.
+
+``` yaml
+markdown_extensions:
+ - pymdownx.arithmatex:
+ generic: true
+```
+
+Besides enabling the extension in `mkdocs.yml`, a MathJax configuration and
+the JavaScript runtime need to be included, which can be done with a few lines
+of [additional JavaScript]:
+
+=== ":octicons-file-code-16: `docs/javascripts/mathjax.js`"
+
+ ``` js
+ window.MathJax = {
+ tex: {
+ inlineMath: [["\\(", "\\)"]],
+ displayMath: [["\\[", "\\]"]],
+ processEscapes: true,
+ processEnvironments: true
+ },
+ options: {
+ ignoreHtmlClass: ".*|",
+ processHtmlClass: "arithmatex"
+ }
+ };
+
+ document$.subscribe(() => { // (1)!
+ MathJax.startup.output.clearCache()
+ MathJax.typesetClear()
+ MathJax.texReset()
+ MathJax.typesetPromise()
+ })
+ ```
+
+ 1. This integrates MathJax with [instant loading]
+
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_javascript:
+ - javascripts/mathjax.js
+ - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
+ ```
+
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, which is why they may yield unexpected results. Use
+them at your own risk.
+
+See reference for usage:
+
+- [Using block syntax]
+- [Using inline block syntax]
+
+ [Arithmatex]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
+ [Arithmatex documentation on KaTeX]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/#loading-katex
+ [MathJax]: https://www.mathjax.org/
+ [KaTeX]: https://github.com/Khan/KaTeX
+ [additional JavaScript]: ../../customization.md#additional-javascript
+ [instant loading]: ../setting-up-navigation.md#instant-loading
+ [Using block syntax]: ../../reference/math.md#using-block-syntax
+ [Using inline block syntax]: ../../reference/math.md#using-inline-block-syntax
+
+### BetterEm
+
+<!-- md:version 0.1.0 -->
+<!-- md:extension [pymdownx.betterem][BetterEm] -->
+
+The [BetterEm] extension improves the detection of Markup to emphasize text
+in Markdown using special characters, i.e. for `**bold**` and `_italic_`
+formatting. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.betterem
+```
+
+The configuration options of this extension are not specific to Material for
+MkDocs, as they only impact the Markdown parsing stage. See the [BetterEm
+documentation][BetterEm] for more information.
+
+ [BetterEm]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/
+
+### Caption
+
+<!-- md:version 1.0.0 -->
+<!-- md:extension [pymdownx.blocks.caption][Caption] -->
+
+The [Caption] extension adds the ability to add captions to any Markdown block,
+including images, tables, and code blocks. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.blocks.caption
+```
+
+The configuration options of this extension are not specific to Material for
+MkDocs, as they only impact the Markdown parsing stage. See the [Caption
+documentation][Caption] for more information.
+
+ [Caption]: https://facelessuser.github.io/pymdown-extensions/extensions/blocks/plugins/caption/
+
+### Caret, Mark & Tilde
+
+<!-- md:version 1.0.0 -->
+<!-- md:extension [pymdownx.caret][Caret] -->
+
+The [Caret], [Mark] and [Tilde] extensions add the ability to highlight text
+and define sub- and superscript using a simple syntax. Enable them together
+via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.caret
+ - pymdownx.mark
+ - pymdownx.tilde
+```
+
+The configuration options of this extension are not specific to Material for
+MkDocs, as they only impact the Markdown parsing stage. See the [Caret], [Mark]
+and [Tilde documentation][Tilde] for guidance.
+
+See reference for usage:
+
+- [Highlighting text]
+- [Sub- and superscripts]
+
+ [Caret]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/
+ [Mark]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
+ [Tilde]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/
+ [Highlighting text]: ../../reference/formatting.md#highlighting-text
+ [Sub- and superscripts]: ../../reference/formatting.md#sub-and-superscripts
+
+### Critic
+
+<!-- md:version 1.0.0 -->
+<!-- md:extension [pymdownx.critic][Critic] -->
+
+The [Critic] extension allows for the usage of [Critic Markup] to highlight
+added, deleted or updated sections in a document, i.e. for tracking changes in
+Markdown syntax. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.critic
+```
+
+The following configuration options are supported:
+
+<!-- md:option pymdownx.critic.mode -->
+
+: <!-- md:default `view` --> This option defines how the markup
+ should be parsed, i.e. whether to just `view` all suggested changes, or
+ alternatively `accept` or `reject` them:
+
+ === "View changes"
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.critic:
+ mode: view
+ ```
+
+ === "Accept changes"
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.critic:
+ mode: accept
+ ```
+
+ === "Reject changes"
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.critic:
+ mode: reject
+ ```
+
+See reference for usage:
+
+- [Highlighting changes]
+
+ [Critic]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/
+ [Critic Markup]: https://github.com/CriticMarkup/CriticMarkup-toolkit
+ [Highlighting changes]: ../../reference/formatting.md#highlighting-changes
+
+### Details
+
+<!-- md:version 1.9.0 -->
+<!-- md:extension [pymdownx.details][Details] -->
+
+The [Details] extension supercharges the [Admonition] extension, making the
+resulting _call-outs_ collapsible, allowing them to be opened and closed by the
+user. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.details
+```
+
+No configuration options are available. See reference for usage:
+
+- [Collapsible blocks]
+
+ [Details]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
+ [Admonition]: python-markdown.md#admonition
+ [Collapsible blocks]: ../../reference/admonitions.md#collapsible-blocks
+
+### Emoji
+
+<!-- md:version 1.0.0 -->
+<!-- md:extension [pymdownx.emoji][Emoji] -->
+
+The [Emoji] extension automatically inlines bundled and custom icons and emojis
+in `*.svg` file format into the resulting HTML page. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.emoji:
+ emoji_index: !!python/name:material.extensions.emoji.twemoji # (1)!
+ emoji_generator: !!python/name:material.extensions.emoji.to_svg
+```
+
+1. [Python Markdown Extensions] uses the `pymdownx` namespace, but in order to
+ support the inlining of icons, the `materialx` namespace must be used, as it
+ extends the functionality of `pymdownx`.
+
+The following configuration options are supported:
+
+<!-- md:option pymdownx.emoji.emoji_index -->
+
+: <!-- md:default `emojione` --> This option defines which set
+ of emojis is used for rendering. Note that the use of `emojione` is not
+ recommended due to [restrictions in licensing][Emoji index]:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.emoji:
+ emoji_index: !!python/name:material.extensions.emoji.twemoji
+ ```
+
+<!-- md:option pymdownx.emoji.emoji_generator -->
+
+: <!-- md:default `to_png` --> This option defines how the
+ resolved emoji or icon shortcode is render. Note that icons can only be
+ used together with the `to_svg` configuration:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.emoji:
+ emoji_generator: !!python/name:material.extensions.emoji.to_svg
+ ```
+
+<!-- md:option pymdownx.emoji.options.custom_icons -->
+
+: <!-- md:default none --> This option allows to list folders
+ with additional icon sets to be used in Markdown or `mkdocs.yml`, which is
+ explained in more detail in the [icon customization guide]:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.emoji:
+ emoji_index: !!python/name:material.extensions.emoji.twemoji
+ emoji_generator: !!python/name:material.extensions.emoji.to_svg
+ options:
+ custom_icons:
+ - overrides/.icons
+ ```
+
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, which is why they may yield unexpected results. Use
+them at your own risk.
+
+See reference for usage:
+
+- [Using emojis]
+- [Using icons]
+- [Using icons in templates]
+
+ [Emoji]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
+ [Emoji index]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#default-emoji-indexes
+ [icon customization guide]: ../changing-the-logo-and-icons.md#additional-icons
+ [Using emojis]: ../../reference/icons-emojis.md#using-emojis
+ [Using icons]: ../../reference/icons-emojis.md#using-icons
+ [Using icons in templates]: ../../reference/icons-emojis.md#using-icons-in-templates
+
+### Highlight
+
+<!-- md:version 5.0.0 -->
+<!-- md:extension [pymdownx.highlight][Highlight] -->
+
+The [Highlight] extension adds support for syntax highlighting of code blocks
+(with the help of [SuperFences][pymdownx.superfences]) and inline code blocks
+(with the help of [InlineHilite][pymdownx.inlinehilite]). Enable it via
+`mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.highlight:
+ anchor_linenums: true
+ - pymdownx.superfences # (1)!
+```
+
+1. [Highlight] is used by the [SuperFences][pymdownx.superfences] extension to
+ perform syntax highlighting on code blocks, not the other way round, which
+ is why this extension also needs to be enabled.
+
+The following configuration options are supported:
+
+<!-- md:option pymdownx.highlight.use_pygments -->
+
+: <!-- md:default `true` --> This option allows to control
+ whether highlighting should be carried out during build time using
+ [Pygments] or in the browser with a JavaScript syntax highlighter:
+
+ === "Pygments"
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.highlight:
+ use_pygments: true
+ - pymdownx.superfences
+ ```
+
+ === "JavaScript"
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.highlight:
+ use_pygments: false
+ ```
+
+ As an example, [Highlight.js], a JavaScript syntax highlighter, can be
+ integrated with some [additional JavaScript] and an [additional style
+ sheet] in `mkdocs.yml`:
+
+ === ":octicons-file-code-16: `docs/javascripts/highlight.js`"
+
+ ``` js
+ document$.subscribe(() => {
+ hljs.highlightAll()
+ })
+ ```
+
+ === ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_javascript:
+ - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/highlight.min.js
+ - javascripts/highlight.js
+ extra_css:
+ - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/styles/default.min.css
+ ```
+
+ Note that [Highlight.js] has no affiliation with the
+ [Highlight][pymdownx.highlight] extension.
+
+ All following configuration options are only compatible with build-time
+ syntax highlighting using [Pygments], so they don't apply if `use_pygments`
+ is set to `false`.
+
+<!-- md:option pymdownx.highlight.pygments_lang_class -->
+
+: <!-- md:default `false` --> This option instructs [Pygments]
+ to add a CSS class to identify the language of the code block, which is
+ essential for custom annotation markers to function:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.highlight:
+ pygments_lang_class: true
+```
+
+<!-- md:option pymdownx.highlight.auto_title -->
+
+: <!-- md:default `false` --> This option will automatically
+ add a [title] to all code blocks that shows the name of the language being
+ used, e.g. `Python` is printed for a `py` block:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.highlight:
+ auto_title: true
+ ```
+
+<!-- md:option pymdownx.highlight.linenums -->
+
+: <!-- md:default `false` --> This option will add line numbers
+ to _all_ code blocks. If you wish to add line numbers to _some_, but not all
+ code blocks, consult the section on [adding line numbers][Adding line
+ numbers] in the code block reference, which also contains some tips on
+ working with line numbers:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.highlight:
+ linenums: true
+ ```
+
+<!-- md:option pymdownx.highlight.linenums_style -->
+
+: <!-- md:default `table` --> The [Highlight] extension
+ provides three ways to add line numbers, two of which are supported by
+ Material for MkDocs. While `table` wraps a code block in a `<table>`
+ element, `pymdownx-inline` renders line numbers as part of the line itself:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.highlight:
+ linenums_style: pymdownx-inline
+ ```
+
+ Note that `inline` will put line numbers next to the actual code, which
+ means that they will be included when selecting text with the cursor or
+ copying a code block to the clipboard. Thus, the usage of either `table`
+ or `pymdownx-inline` is recommended.
+
+<!-- md:option pymdownx.highlight.anchor_linenums -->
+
+: <!-- md:version 8.1.0 --> :octicons-milestone-24:
+ Default: `false` – If a code blocks contains line numbers, enabling this
+ setting will wrap them with anchor links, so they can be hyperlinked and
+ shared more easily:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.highlight:
+ anchor_linenums: true
+ ```
+
+<!-- md:option pymdownx.highlight.line_spans -->
+
+: <!-- md:default none --> When this option is set, each
+ line of a code block is wrapped in a `span`, which is essential for features
+ like line highlighting to work correctly:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.highlight:
+ line_spans: __span
+ ```
+
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, which is why they may yield unexpected results. Use
+them at your own risk.
+
+See reference for usage:
+
+- [Using code blocks]
+- [Adding a title]
+- [Adding line numbers]
+- [Highlighting specific lines]
+- [Custom syntax theme]
+
+ [Highlight]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
+ [CodeHilite]: python-markdown.md#codehilite
+ [pymdownx.superfences]: #superfences
+ [pymdownx.inlinehilite]: #inlinehilite
+ [Pygments]: https://pygments.org
+ [additional style sheet]: ../../customization.md#additional-css
+ [Highlight.js]: https://highlightjs.org/
+ [title]: ../../reference/code-blocks.md#adding-a-title
+ [Adding line numbers]: ../../reference/code-blocks.md#adding-line-numbers
+ [Using code blocks]: ../../reference/code-blocks.md#usage
+ [Adding a title]: ../../reference/code-blocks.md#adding-a-title
+ [Highlighting specific lines]: ../../reference/code-blocks.md#highlighting-specific-lines
+ [Custom syntax theme]: ../../reference/code-blocks.md#custom-syntax-theme
+
+### InlineHilite
+
+<!-- md:version 5.0.0 -->
+<!-- md:extension [pymdownx.inlinehilite][InlineHilite] -->
+
+The [InlineHilite] extension add support for syntax highlighting of inline code
+blocks. It's built on top of the [Highlight][pymdownx.highlight] extension, from
+which it sources its configuration. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.highlight
+ - pymdownx.inlinehilite
+```
+
+The configuration options of this extension are not specific to Material for
+MkDocs, as they only impact the Markdown parsing stage. The only exception is
+the [`css_class`][InlineHilite options] option, which must not be changed. See the
+[InlineHilite documentation][InlineHilite] for guidance.
+
+See reference for usage:
+
+- [Highlighting inline code blocks]
+
+ [InlineHilite]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
+ [InlineHilite options]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/#options
+ [pymdownx.highlight]: #highlight
+ [Highlighting inline code blocks]: ../../reference/code-blocks.md#highlighting-inline-code-blocks
+
+### Keys
+
+<!-- md:version 1.0.0 -->
+<!-- md:extension [pymdownx.keys][Keys] -->
+
+The [Keys] extension adds a simple syntax to allow for the rendering of keyboard
+keys and combinations, e.g. ++ctrl+alt+del++. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.keys
+```
+
+The configuration options of this extension are not specific to Material for
+MkDocs, as they only impact the Markdown parsing stage. The only exception is
+the [`class`][Keys options] option, which must not be changed. See the
+[Keys documentation][Keys] for more information.
+
+See reference for usage:
+
+- [Adding keyboard keys]
+
+ [Keys]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/
+ [Keys options]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/#options
+ [Adding keyboard keys]: ../../reference/formatting.md#adding-keyboard-keys
+
+### SmartSymbols
+
+<!-- md:version 0.1.0 -->
+<!-- md:extension [pymdownx.smartsymbols][SmartSymbols] -->
+
+The [SmartSymbols] extension converts some sequences of characters into their
+corresponding symbols, e.g. copyright symbols or fractions. Enable it via
+`mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.smartsymbols
+```
+
+The configuration options of this extension are not specific to Material for
+MkDocs, as they only impact the Markdown parsing stage. See the [SmartSymbols
+documentation][SmartSymbols] for guidance.
+
+ [SmartSymbols]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
+
+### Snippets
+
+<!-- md:version 0.1.0 -->
+<!-- md:extension [pymdownx.snippets][Snippets] -->
+
+The [Snippets] extension adds the ability to embed content from arbitrary files
+into a document, including other documents or source files, by using a simple
+syntax. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.snippets
+```
+
+The configuration options of this extension are not specific to Material for
+MkDocs, as they only impact the Markdown parsing stage. See the [Snippets
+documentation][Snippets] for more information.
+
+See reference for usage:
+
+- [Adding a glossary]
+- [Embedding external files]
+
+ [Snippets]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
+ [Adding a glossary]: ../../reference/tooltips.md#adding-a-glossary
+ [Embedding external files]: ../../reference/code-blocks.md#embedding-external-files
+
+### SuperFences
+
+<!-- md:version 0.1.0 -->
+<!-- md:extension [pymdownx.superfences][SuperFences] -->
+
+The [SuperFences] extension allows for arbitrary nesting of code and content
+blocks inside each other, including admonitions, tabs, lists and all other
+elements. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.superfences
+```
+
+The following configuration options are supported:
+
+<!-- md:option pymdownx.superfences.custom_fences -->
+
+: <!-- md:default none --> This option allows to define a
+ handler for custom fences, e.g. to preserve the definitions of [Mermaid.js]
+ diagrams to be interpreted in the browser:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.superfences:
+ custom_fences:
+ - name: mermaid
+ class: mermaid
+ format: !!python/name:pymdownx.superfences.fence_code_format
+ ```
+
+ Note that this will primarily prevent syntax highlighting from being
+ applied. See the reference on [diagrams] to learn how Mermaid.js is
+ integrated with Material for MkDocs.
+
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, which is why they may yield unexpected results. Use
+them at your own risk.
+
+See reference for usage:
+
+- [Using annotations]
+- [Using code blocks]
+- [Using content tabs]
+- [Using flowcharts]
+- [Using sequence diagrams]
+- [Using state diagrams]
+- [Using class diagrams]
+- [Using entity-relationship diagrams]
+
+ [SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
+ [Fenced Code Blocks]: python-markdown.md#fenced-code-blocks
+ [Mermaid.js]: https://mermaid-js.github.io/mermaid/
+ [diagrams]: ../../reference/diagrams.md
+ [Using annotations]: ../../reference/annotations.md#usage
+ [Using content tabs]: ../../reference/content-tabs.md#usage
+ [Using flowcharts]: ../../reference/diagrams.md#using-flowcharts
+ [Using sequence diagrams]: ../../reference/diagrams.md#using-sequence-diagrams
+ [Using state diagrams]: ../../reference/diagrams.md#using-state-diagrams
+ [Using class diagrams]: ../../reference/diagrams.md#using-class-diagrams
+ [Using entity-relationship diagrams]: ../../reference/diagrams.md#using-entity-relationship-diagrams
+
+### Tabbed
+
+<!-- md:version 5.0.0 -->
+<!-- md:extension [pymdownx.tabbed][Tabbed] -->
+
+The [Tabbed] extension allows the usage of content tabs, a simple way to group
+related content and code blocks under accessible tabs. Enable it via
+`mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.tabbed:
+ alternate_style: true
+```
+
+The following configuration options are supported:
+
+<!-- md:option pymdownx.tabbed.alternate_style -->
+
+: <!-- md:version 7.3.1 --> <!-- md:default `false` -->
+ <!-- md:flag required --> This option enables the content tabs
+ [alternate style], which has [better behavior on mobile viewports], and is
+ the only supported style:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.tabbed:
+ alternate_style: true
+ ```
+
+<!-- md:option pymdownx.tabbed.combine_header_slug -->
+
+: <!-- md:default `false` --> This option enables the content tabs'
+ [`combine_header_slug` style] flag, which prepends the id of the header to
+ the id of the tab:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.tabbed:
+ combine_header_slug: true
+ ```
+
+<!-- md:option pymdownx.tabbed.slugify -->
+
+: <!-- md:default `None` --> This option allows for
+ customization of the slug function. For some languages, the default may not
+ produce good and readable identifiers – consider using another slug function
+ like for example those from [Python Markdown Extensions][Slugs]:
+
+ === "Unicode"
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.tabbed:
+ slugify: !!python/object/apply:pymdownx.slugs.slugify
+ kwds:
+ case: lower
+ ```
+
+ === "Unicode, case-sensitive"
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.tabbed:
+ slugify: !!python/object/apply:pymdownx.slugs.slugify {}
+ ```
+
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, which is why they may yield unexpected results. Use
+them at your own risk.
+
+See reference for usage:
+
+- [Grouping code blocks]
+- [Grouping other content]
+- [Embedded content]
+
+ [Tabbed]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
+ [alternate style]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#alternate-style
+ [combine_header_slug style]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#tab-ids
+ [better behavior on mobile viewports]: https://x.com/squidfunk/status/1424740370596958214
+ [Grouping code blocks]: ../../reference/content-tabs.md#grouping-code-blocks
+ [Grouping other content]: ../../reference/content-tabs.md#grouping-other-content
+ [Embedded content]: ../../reference/content-tabs.md#embedded-content
+ [Slugs]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
+
+### Tasklist
+
+<!-- md:version 1.0.0 -->
+<!-- md:extension [pymdownx.tasklist][Tasklist] -->
+
+The [Tasklist] extension allows for the usage of [GitHub Flavored Markdown]
+inspired [task lists][Tasklist specification], following the same syntactical
+conventions. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - pymdownx.tasklist:
+ custom_checkbox: true
+```
+
+The following configuration options are supported:
+
+<!-- md:option pymdownx.tasklist.custom_checkbox -->
+
+: <!-- md:default `false` --> This option toggles the rendering
+ style of checkboxes, replacing native checkbox styles with beautiful icons,
+ and is therefore recommended:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.tasklist:
+ custom_checkbox: true
+ ```
+
+<!-- md:option pymdownx.tasklist.clickable_checkbox -->
+
+: <!-- md:default `false` --> This option toggles whether
+ checkboxes are clickable. As the state is not persisted, the use of this
+ option is _rather discouraged_ from a user experience perspective:
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.tasklist:
+ clickable_checkbox: true
+ ```
+
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, which is why they may yield unexpected results. Use
+them at your own risk.
+
+See reference for usage:
+
+- [Using task lists]
+
+ [Tasklist]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/
+ [GitHub Flavored Markdown]: https://github.github.com/gfm/
+ [Tasklist specification]: https://github.github.com/gfm/#task-list-items-extension-
+ [Using task lists]: ../../reference/lists.md#using-task-lists
diff --git a/documents/markdown/mkdocs-material/setup_extensions_python-markdown.md b/documents/markdown/mkdocs-material/setup_extensions_python-markdown.md
new file mode 100644
index 0000000..a724e2f
--- /dev/null
+++ b/documents/markdown/mkdocs-material/setup_extensions_python-markdown.md
@@ -0,0 +1,347 @@
+# Python Markdown
+
+Material for MkDocs supports a large number of [Python Markdown] extensions,
+which is part of what makes it so attractive for technical writing. Following
+is a list of all supported extensions, linking to the relevant sections of the
+reference for which features they need to be enabled.
+
+ [Python Markdown]: https://python-markdown.github.io/
+
+## Supported extensions
+
+### Abbreviations
+
+<!-- md:version 1.0.0 -->
+<!-- md:extension [abbr][Abbreviations] -->
+
+The [Abbreviations] extension adds the ability to add a small tooltip to an
+element, by wrapping it with an `abbr` tag. Only plain text (no markup) is
+supported. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - abbr
+```
+
+No configuration options are available. See reference for usage:
+
+- [Adding abbreviations]
+- [Adding a glossary]
+
+ [Abbreviations]: https://python-markdown.github.io/extensions/abbreviations/
+ [Adding abbreviations]: ../../reference/tooltips.md#adding-abbreviations
+ [Adding a glossary]: ../../reference/tooltips.md#adding-a-glossary
+
+### Admonition
+
+<!-- md:version 0.1.0 -->
+<!-- md:extension [admonition][Admonition] -->
+
+The [Admonition] extension adds support for admonitions, more commonly known as
+_call-outs_, which can be defined in Markdown by using a simple syntax. Enable
+it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - admonition
+```
+
+No configuration options are available. See reference for usage:
+
+- [Adding admonitions]
+- [Changing the title]
+- [Removing the title]
+- [Supported types]
+
+ [Admonition]: https://python-markdown.github.io/extensions/admonition/
+ [Adding admonitions]: ../../reference/admonitions.md#usage
+ [Changing the title]: ../../reference/admonitions.md#changing-the-title
+ [Removing the title]: ../../reference/admonitions.md#removing-the-title
+ [Supported types]: ../../reference/admonitions.md#supported-types
+
+### Attribute Lists
+
+<!-- md:version 0.1.0 -->
+<!-- md:extension [attr_list][Attribute Lists] -->
+
+The [Attribute Lists] extension allows to add HTML attributes and CSS classes
+to [almost every][Attribute Lists limitations] Markdown inline- and block-level
+element with a special syntax. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - attr_list
+```
+
+No configuration options are available. See reference for usage:
+
+- [Using annotations]
+- [Using grids]
+- [Adding buttons]
+- [Adding tooltips]
+- [Using icons with colors]
+- [Using icons with animations]
+- [Image alignment]
+- [Image lazy-loading]
+
+ [Attribute Lists]: https://python-markdown.github.io/extensions/attr_list/
+ [Attribute Lists limitations]: https://python-markdown.github.io/extensions/attr_list/#limitations
+ [Using grids]: ../../reference/grids.md#using-grids
+ [Adding buttons]: ../../reference/buttons.md#adding-buttons
+ [Adding tooltips]: ../../reference/tooltips.md#adding-tooltips
+ [Using icons with colors]: ../../reference/icons-emojis.md#with-colors
+ [Using icons with animations]: ../../reference/icons-emojis.md#with-animations
+ [Image alignment]: ../../reference/images.md#image-alignment
+ [Image lazy-loading]: ../../reference/images.md#image-lazy-loading
+
+### Definition Lists
+
+<!-- md:version 1.1.0 -->
+<!-- md:extension [def_list][Definition Lists] -->
+
+The [Definition Lists] extension adds the ability to add definition lists (more
+commonly known as [description lists] – `dl` in HTML) via Markdown to a
+document. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - def_list
+```
+
+No configuration options are available. See reference for usage:
+
+- [Using definition lists]
+
+ [Definition Lists]: https://python-markdown.github.io/extensions/definition_lists/
+ [description lists]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl
+ [Using definition lists]: ../../reference/lists.md#using-definition-lists
+
+### Footnotes
+
+<!-- md:version 1.0.0 -->
+<!-- md:extension [footnotes][Footnotes] -->
+
+The [Footnotes] extension allows to define inline footnotes, which are then
+rendered below all Markdown content of a document. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - footnotes
+```
+
+No configuration options are supported. See reference for usage:
+
+- [Adding footnote references]
+- [Adding footnote content]
+
+ [Footnotes]: https://python-markdown.github.io/extensions/footnotes/
+ [Adding footnote references]: ../../reference/footnotes.md#adding-footnote-references
+ [Adding footnote content]: ../../reference/footnotes.md#adding-footnote-content
+
+### Markdown in HTML
+
+<!-- md:version 0.1.0 -->
+<!-- md:extension [md_in_html][Markdown in HTML] -->
+
+The [Markdown in HTML] extension allows for writing Markdown inside of HTML,
+which is useful for wrapping Markdown content with custom elements. Enable it
+via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - md_in_html
+```
+
+> By default, Markdown ignores any content within a raw HTML block-level
+> element. With the `md_in_html` extension enabled, the content of a raw HTML
+> block-level element can be parsed as Markdown by including a `markdown`
+> attribute on the opening tag. The `markdown` attribute will be stripped from
+> the output, while all other attributes will be preserved.
+
+No configuration options are available. See reference for usage:
+
+- [Using annotations]
+- [Using grids]
+- [Image captions]
+
+ [Markdown in HTML]: https://python-markdown.github.io/extensions/md_in_html/
+ [Using annotations]: ../../reference/annotations.md#usage
+ [Using grids]: ../../reference/grids.md#usage
+ [Image captions]: ../../reference/images.md#image-captions
+
+### Table of Contents
+
+<!-- md:version 0.1.0 -->
+<!-- md:extension [toc][Table of Contents] -->
+
+The [Table of Contents] extension automatically generates a table of contents
+from a document, which Material for MkDocs will render as part of the resulting
+page. Enable it via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+ - toc:
+ permalink: true
+```
+
+The following configuration options are supported:
+
+<!-- md:option toc.title -->
+
+: <!-- md:version 7.3.5 --> <!-- md:default computed --> –
+ This option sets the title of the table of contents in the right navigation
+ sidebar, which is normally automatically sourced from the translations for
+ the [site language] as set in `mkdocs.yml`:
+
+ ``` yaml
+ markdown_extensions:
+ - toc:
+ title: On this page
+ ```
+
+<!-- md:option toc.permalink -->
+
+: <!-- md:default `false` --> This option adds an anchor link
+ containing the paragraph symbol `¶` or another custom symbol at the end of
+ each headline, exactly like on the page you're currently viewing, which
+ Material for MkDocs will make appear on hover:
+
+ === "¶"
+
+ ``` yaml
+ markdown_extensions:
+ - toc:
+ permalink: true
+ ```
+
+ === "⚓︎"
+
+ ``` yaml
+ markdown_extensions:
+ - toc:
+ permalink: ⚓︎
+ ```
+
+<!-- md:option toc.permalink_title -->
+
+: <!-- md:default `Permanent link` --> This option sets the
+ title of the anchor link which is shown on hover and read by screen readers.
+ For accessibility reasons, it might be beneficial to change it to a more
+ discernable name, stating that the anchor links to the section itself:
+
+ ``` yaml
+ markdown_extensions:
+ - toc:
+ permalink_title: Anchor link to this section for reference
+ ```
+
+<!-- md:option toc.slugify -->
+
+: <!-- md:default `toc.slugify` --> This option allows for
+ customization of the slug function. For some languages, the default may not
+ produce good and readable identifiers – consider using another slug function
+ like for example those from [Python Markdown Extensions][Slugs]:
+
+ === "Unicode"
+
+ ``` yaml
+ markdown_extensions:
+ - toc:
+ slugify: !!python/object/apply:pymdownx.slugs.slugify
+ kwds:
+ case: lower
+ ```
+
+ === "Unicode, case-sensitive"
+
+ ``` yaml
+ markdown_extensions:
+ - toc:
+ slugify: !!python/object/apply:pymdownx.slugs.slugify {}
+ ```
+
+<!-- md:option toc.toc_depth -->
+
+: <!-- md:default `6` --> Define the range of levels to be
+ included in the table of contents. This may be useful for project
+ documentation with deeply structured headings to decrease the length of the
+ table of contents, or to remove the table of contents altogether:
+
+ === "Hide levels 4-6"
+
+ ``` yaml
+ markdown_extensions:
+ - toc:
+ toc_depth: 3
+ ```
+
+ === "Hide table of contents"
+
+ ``` yaml
+ markdown_extensions:
+ - toc:
+ toc_depth: 0
+ ```
+
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, which is why they may yield unexpected results. Use
+them at your own risk.
+
+ [Table of Contents]: https://python-markdown.github.io/extensions/toc/
+ [site language]: ../changing-the-language.md#site-language
+ [Slugs]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
+
+### Tables
+
+<!-- md:version 0.1.0 -->
+<!-- md:extension [tables][Tables] -->
+
+The [Tables] extension adds the ability to create tables in Markdown by using a
+simple syntax. Enable it via `mkdocs.yml` (albeit it should be enabled by
+default):
+
+``` yaml
+markdown_extensions:
+ - tables
+```
+
+No configuration options are available. See reference for usage:
+
+- [Using data tables]
+- [Column alignment]
+
+ [Tables]: https://python-markdown.github.io/extensions/tables/
+ [Using data tables]: ../../reference/data-tables.md#usage
+ [Column alignment]: ../../reference/data-tables.md#column-alignment
+
+## Superseded extensions
+
+The following [Python Markdown] extensions are not (or might not be) supported
+anymore, and are therefore not recommended for use. Instead, the alternatives
+should be considered.
+
+### Fenced Code Blocks
+
+<!-- md:version 0.1.0 -->
+<!-- md:extension [fenced_code_blocks][Fenced Code Blocks] -->
+
+Superseded by [SuperFences]. This extension might still work, but the
+[SuperFences] extension is superior in many ways, as it allows for arbitrary
+nesting, and is therefore recommended.
+
+ [Fenced Code Blocks]: https://python-markdown.github.io/extensions/fenced_code_blocks/
+ [SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
+
+### CodeHilite
+
+<!-- md:version 0.1.0 -->
+<!-- md:extension [codehilite][CodeHilite] -->
+
+Superseded by [Highlight]. Support for CodeHilite was dropped in
+<!-- md:version 6.0.0 -->, as [Highlight] has a better integration with other
+essential extensions like [SuperFences] and [InlineHilite].
+
+ [CodeHilite]: https://python-markdown.github.io/extensions/code_hilite/
+ [CodeHilite support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
+ [Highlight]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
+ [InlineHilite]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
diff --git a/documents/markdown/mkdocs-material/setup_index.md b/documents/markdown/mkdocs-material/setup_index.md
new file mode 100644
index 0000000..c470698
--- /dev/null
+++ b/documents/markdown/mkdocs-material/setup_index.md
@@ -0,0 +1,90 @@
+# Setup
+
+Material for MkDocs offers a wide range of options for customizing your
+documentation. In this section, we will explain how you can create a meaningful
+structure for your site, change the look and feel, add a blog and comment system,
+and build a highly optimized site.
+
+## Site structure
+
+Set up and customize the structure of your documentation by configuring the
+header and footer to your taste, choosing among many modes of navigation,
+setting up site search, and more.
+
+<div class="grid cards" markdown>
+
+- :fontawesome-solid-earth-americas: __[Language]__ – Choose out of the 60+ supported languages or add a new one
+- :material-page-layout-sidebar-left: __[Navigation]__ – Create a clear, concise, and comprehensive navigation structure
+- :material-page-layout-header: __[Header]__ – Customize the behavior of the header, add an announcement bar
+- :material-page-layout-footer: __[Footer]__ – Add links to your social media profiles or websites in the footer
+- :material-tab-search: __[Search]__ – Set up and configure search, running entirely in the user's browser
+- :material-tag-plus-outline: __[Tags]__ – Categorize your pages with tags and group related pages
+
+</div>
+
+ [Language]: changing-the-language.md
+ [Navigation]: setting-up-navigation.md
+ [Header]: setting-up-the-header.md
+ [Footer]: setting-up-the-footer.md
+ [Search]: setting-up-site-search.md
+ [Tags]: setting-up-tags.md
+
+
+## Appearance
+
+Match your brand's colors, fonts, icons, logo, and more with a few lines of
+configuration – Material for MkDocs makes it easy to extend the basic
+configuration or alter the appearance.
+
+<div class="grid cards" markdown>
+
+- :material-brush-variant: __[Colors]__ – Change colors with an existing color palette or customize with CSS
+- :material-format-font: __[Fonts]__ – Choose among 1,000 Google Fonts or load self-hosted fonts
+- :material-google-downasaur: __[Logo & Icons]__ – Change the logo, use any of the 8,000+ icons, or add new ones
+- :material-cards-variant: __[Social Cards]__ – Automatically create social media previews when sharing links
+
+</div>
+
+ [Colors]: changing-the-colors.md
+ [Fonts]: changing-the-fonts.md
+ [Logo & Icons]: changing-the-logo-and-icons.md
+ [Social Cards]: setting-up-social-cards.md
+
+## Content
+
+Create a blog, integrate a comment system, connect a git repository, and set up
+versioned documentation that matches your project's versioning methodology.
+
+<div class="grid cards" markdown>
+
+- :material-book-open-outline: __[Blog]__ – Set up a standalone blog or host it alongside your documentation
+- :material-comment-text-outline: __[Comment System]__ – Add a third-party comment system on any page or footer
+- :octicons-versions-16: __[Versioning]__ – Deploy multiple versions by integrating with external utilities
+- :octicons-repo-16: __[Repository]__ – Connect your documentation to your git repository
+
+</div>
+
+ [Blog]: setting-up-a-blog.md
+ [Comment System]: adding-a-comment-system.md
+ [Versioning]: setting-up-versioning.md
+ [Repository]: adding-a-git-repository.md
+
+## Optimization
+
+Add site analytics and build an optimized site by adding automatic image
+compression, complying with GDPR data privacy regulations, and making it
+offline-capable.
+
+<div class="grid cards" markdown>
+
+- :material-google-analytics: __[Site analytics]__ – Learn how your users experience your documentation
+- :material-screwdriver: __[Optimized site]__ – Create optimized sites that rank great on search engines
+- :octicons-lock-16: __[Data Privacy]__ – Ensure compliance with data privacy regulations
+- :octicons-cloud-offline-16: __[Offline usage]__ – Build an online and offline-capable documentation
+
+</div>
+
+ [Site analytics]: setting-up-site-analytics.md
+ [Optimized site]: building-an-optimized-site.md
+ [Data Privacy]: ensuring-data-privacy.md
+ [Offline usage]: building-for-offline-usage.md
diff --git a/documents/markdown/mkdocs-material/setup_setting-up-a-blog.md b/documents/markdown/mkdocs-material/setup_setting-up-a-blog.md
new file mode 100644
index 0000000..180a21e
--- /dev/null
+++ b/documents/markdown/mkdocs-material/setup_setting-up-a-blog.md
@@ -0,0 +1,677 @@
+# Setting up a blog
+
+Material for MkDocs makes it very easy to build a blog, either as a sidecar to
+your documentation or standalone. Focus on your content while the engine does
+all the heavy lifting, automatically generating [archive] and [category]
+indexes, [post slugs], configurable [pagination] and more.
+
+---
+
+__Check out our [blog], which is created with the new [built-in blog plugin]!__
+
+ [archive]: ../plugins/blog.md#archive
+ [category]: ../plugins/blog.md#categories
+ [post slugs]: ../plugins/blog.md#config.post_url_format
+ [pagination]: ../plugins/blog.md#pagination
+ [blog]: ../blog/index.md
+
+## Configuration
+
+### Built-in blog plugin
+
+<!-- md:version 9.2.0 -->
+<!-- md:plugin -->
+<!-- md:flag experimental -->
+<!-- md:demo create-blog -->
+
+The built-in blog plugin adds support for building a blog from a folder of
+posts, which are annotated with dates and other structured data. First, add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - blog
+```
+
+If you do not have a navigation (`nav`) definition in your `mkdocs.yml` then
+there is nothing else to do there as the blog plugin will add navigation
+automatically. If you do have a navigation defined then you need to add *the
+blog index page only* to it. You need not and should not add the individual
+blog posts. For example:
+
+```yaml
+nav:
+ - index.md
+ - Blog:
+ - blog/index.md
+```
+
+For a list of all settings, please consult the [plugin documentation].
+
+ [plugin documentation]: ../plugins/blog.md
+ [built-in blog plugin]: ../plugins/blog.md
+
+### RSS
+
+<!-- md:version 9.2.0 -->
+<!-- md:plugin [rss] -->
+
+The [built-in blog plugin] integrates seamlessly with the [RSS plugin][rss],
+which provides a simple way to add an RSS feed to your blog (or to your whole
+documentation). Install it with `pip`:
+
+```
+pip install mkdocs-rss-plugin
+```
+
+Then, add the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - rss:
+ match_path: blog/posts/.* # (1)!
+ date_from_meta:
+ as_creation: date
+ categories:
+ - categories
+ - tags # (2)!
+```
+
+1. The RSS plugin allows to filter for URLs to be included in the feed. In
+ this example, only blog posts will be part of the feed.
+
+2. If you want to include a post's categories as well as its tags in the feed,
+ add both `categories` and `tags` here.
+
+The following configuration options are supported:
+
+<!-- md:option rss.enabled -->
+
+: <!-- md:default `true` --> This option specifies whether
+ the plugin is enabled when building your project. If you want to speed up
+ local builds, you can use an [environment variable][mkdocs.env]:
+
+ ``` yaml
+ plugins:
+ - rss:
+ enabled: !ENV [CI, false]
+ ```
+
+<!-- md:option rss.match_path -->
+
+: <!-- md:default `.*` --> This option specifies which
+ pages should be included in the feed. For example, to only include blog
+ posts in the feed, use the following regular expression:
+
+ ``` yaml
+ plugins:
+ - rss:
+ match_path: blog/posts/.*
+ ```
+
+<!-- md:option rss.date_from_meta -->
+
+: <!-- md:default none --> This option specifies which
+ front matter property should be used as a creation date of a page in the
+ feed. It's recommended to use the `date` property:
+
+ ``` yaml
+ plugins:
+ - rss:
+ date_from_meta:
+ as_creation: date
+ ```
+
+<!-- md:option rss.categories -->
+
+: <!-- md:default none --> This option specifies which
+ front matter properties are used as categories as part of the feed. If you
+ use [categories] and [tags], add both with the following lines:
+
+ ``` yaml
+ plugins:
+ - rss:
+ categories:
+ - categories
+ - tags
+ ```
+
+<!-- md:option rss.comments_path -->
+
+: <!-- md:default none --> This option specifies the anchor
+ at which comments for a post or page can be found. If you've integrated a
+ [comment system], add the following lines:
+
+ ``` yaml
+ plugins:
+ - rss:
+ comments_path: "#__comments"
+ ```
+
+Material for MkDocs will automatically add the [necessary metadata] to your site
+which will make the RSS feed discoverable by browsers and feed readers.
+
+The other configuration options of this extension are not officially supported
+by Material for MkDocs, which is why they may yield unexpected results. Use them
+at your own risk.
+
+ [rss]: https://guts.github.io/mkdocs-rss-plugin/
+ [categories]: ../plugins/blog.md#categories
+ [tags]: setting-up-tags.md#built-in-tags-plugin
+ [comment system]: adding-a-comment-system.md
+ [necessary metadata]: https://guts.github.io/mkdocs-rss-plugin/configuration/#integration
+ [theme extension]: ../customization.md
+
+### Blog only
+
+You might need to build a pure blog without any documentation.
+In this case, you can create a folder tree like this:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+│ ├─ posts/ # (1)!
+│ ├─ .authors.yml
+│ └─ index.md
+└─ mkdocs.yml
+```
+
+1. Notice that the `posts` directory is in the root of `docs` without
+ intermediate `blog` directory.
+
+And add the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - blog:
+ blog_dir: . # (1)!
+```
+
+1. Please see the [plugin documentation] for more information about the
+ [`blog_dir`][blog_dir] setting.
+
+With this configuration, the url of the blog post will be `/<post_slug>`
+instead of `/blog/<post_slug>`.
+
+## Usage
+
+### Writing your first post
+
+After you've successfully set up the [built-in blog plugin], it's time to write
+your first post. The plugin doesn't assume any specific directory structure, so
+you're completely free in how you organize your posts, as long as they are all
+located inside the `posts` directory:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+│ └─ blog/
+│ ├─ posts/
+│ │ └─ hello-world.md # (1)!
+│ └─ index.md
+└─ mkdocs.yml
+```
+
+1. If you'd like to arrange posts differently, you're free to do so. The URLs
+ are built from the format specified in [`post_url_format`][post slugs] and
+ the titles and dates of posts, no matter how they are organized
+ inside the `posts` directory.
+
+Create a new file called `hello-world.md` and add the following lines:
+
+``` yaml
+---
+draft: true # (1)!
+date: 2024-01-31 # (2)!
+categories:
+ - Hello
+ - World
+---
+
+# Hello world!
+...
+```
+
+1. If you mark a post as a [draft], a red marker appears next to the post date
+ on index pages. When the site is built, drafts are not included in the
+ output. [This behavior can be changed], e.g. for rendering drafts when
+ building deploy previews.
+
+2. If you wish to provide multiple dates, you can use the following syntax,
+ allowing you to define a date when you last updated the blog post +
+ further custom dates you can add to the template:
+
+ ``` yaml
+ ---
+ date:
+ created: 2022-01-31
+ updated: 2022-02-02
+ ---
+
+ # Hello world!
+ ```
+
+ Note that the creation date __must__ be set under `date.created`, as each
+ blog post must have a creation date set.
+
+When you spin up the [live preview server], you should be greeted by your first
+post! You'll also realize, that [archive] and [category] indexes have been
+automatically generated for you.
+
+ [draft]: ../plugins/blog.md#drafts
+ [This behavior can be changed]: ../plugins/blog.md#config.draft
+ [live preview server]: ../creating-your-site.md#previewing-as-you-write
+
+#### Adding an excerpt
+
+The blog index, as well as [archive] and [category] indexes can either list the
+entire content of each post, or excerpts of posts. An excerpt can be created by
+adding a `<!-- more -->` separator after the first few paragraphs of a post:
+
+``` py
+# Hello world!
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+massa, nec semper lorem quam in massa.
+
+<!-- more -->
+...
+```
+
+When the [built-in blog plugin] generates all indexes, the content before the
+[excerpt separator] is automatically extracted, allowing the user to start
+reading a post before deciding to jump in.
+
+ [excerpt separator]: ../plugins/blog.md#config.post_excerpt_separator
+
+#### Adding authors
+
+In order to add a little more personality to your posts, you can associate each
+post with one or multiple [authors]. First, create the
+[`.authors.yml`][authors_file] file in your blog directory, and add an author:
+
+``` yaml
+authors:
+ squidfunk:
+ name: Martin Donath
+ description: Creator
+ avatar: https://github.com/squidfunk.png
+```
+
+The [`.authors.yml`][authors_file] file associates each author with an
+identifier (in this example `squidfunk`), which can then be used in posts.
+Different attributes can be configured. For a list of all possible attributes,
+please consult the [`authors_file`][authors_file] documentation.
+
+Now, you can assign one or more authors to a post by referencing their
+identifiers in the front matter of the Markdown file under the `authors`
+property. For each author, a small profile is rendered in the left sidebar of
+each post, as well as in post excerpts on index pages:
+
+``` yaml
+---
+date: 2024-01-31
+authors:
+ - squidfunk
+ ...
+---
+
+# Hello world!
+...
+```
+
+ [authors]: ../plugins/blog.md#authors
+ [authors_file]: ../plugins/blog.md#config.authors_file
+
+#### Adding author profiles
+
+<!-- md:version 9.7.0 -->
+<!-- md:flag experimental -->
+
+If you wish to add a dedicated page for each author, you can enable author
+profiles by setting the [`authors_profiles`][authors_profiles] configuration
+option to `true`. Just add the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - blog:
+ authors_profiles: true
+```
+
+If you combine this with [custom index pages], you can create a dedicated page
+for each author with a short description, social media links, etc. – basically
+anything you can write in Markdown. The list of posts is then appended after
+the content of the page.
+
+ [authors_profiles]: ../plugins/blog.md#config.authors_profiles
+ [custom index pages]: #custom-index-pages
+
+#### Adding categories
+
+Categories are an excellent way for grouping your posts thematically on
+dedicated index pages. This way, a user interested in a specific topic can
+explore all of your posts on this topic. Make sure [categories] are enabled and
+add them to the front matter `categories` property:
+
+``` yaml
+---
+date: 2024-01-31
+categories:
+ - Hello
+ - World
+---
+
+# Hello world!
+...
+```
+
+If you want to save yourself from typos when typing out categories, you can
+define your desired categories in `mkdocs.yml` as part of the
+[`categories_allowed`][categories_allowed] configuration option. The
+[built-in blog plugin] will stop the build if a category is not found within
+the list.
+
+ [categories_allowed]: ../plugins/blog.md#config.categories_allowed
+
+#### Adding tags
+
+Besides [categories], the [built-in blog plugin] also integrates with the
+[built-in tags plugin]. If you add tags in the front matter `tags` property as
+part of a post, the post is linked from the [tags index]:
+
+``` yaml
+---
+date: 2024-01-31
+tags:
+ - Foo
+ - Bar
+---
+
+# Hello world!
+...
+```
+
+As usual, the tags are rendered above the main headline and posts are linked
+on the tags index page, if configured. Note that posts are, as pages, only
+linked with their titles.
+
+ [built-in tags plugin]: ../plugins/tags.md
+ [tags index]: setting-up-tags.md#adding-a-tags-index
+
+#### Changing the slug
+
+Slugs are the shortened description of your post used in the URL. They are automatically generated, but you can specify a custom slug for a page:
+
+``` yaml
+---
+slug: hello-world
+---
+
+# Hello there world!
+...
+```
+
+#### Adding related links
+
+<!-- md:version 9.6.0 -->
+<!-- md:flag experimental -->
+
+Related links offer the perfect way to prominently add a _further reading_
+section to your post that is included in the left sidebar, guiding the user to
+other destinations of your documentation. Use the front matter `links` property
+to add related links to a post:
+
+``` yaml
+---
+date: 2024-01-31
+links:
+ - plugins/search.md
+ - insiders/how-to-sponsor.md
+---
+
+# Hello world!
+...
+```
+
+You can use the exact same syntax as for the [`nav`][mkdocs.nav] section in
+`mkdocs.yml`, which means you can set explicit titles for links, add external
+links and even use nesting:
+
+``` yaml
+---
+date: 2024-01-31
+links:
+ - plugins/search.md
+ - insiders/how-to-sponsor.md
+ - Nested section:
+ - External link: https://example.com
+ - setup/setting-up-site-search.md
+---
+
+# Hello world!
+...
+```
+
+If you look closely, you'll realize that you can even use an anchor to link to
+a specific section of a document, extending the possibilities of the
+[`nav`][mkdocs.nav] syntax in `mkdocs.yml`. The [built-in blog plugin] resolves
+the anchor and sets the title of the anchor as a [subtitle] of the related link.
+
+Note that all links must be relative to [`docs_dir`][mkdocs.docs_dir], as is
+also the case for the [`nav`][mkdocs.nav] setting.
+
+ [subtitle]: ../reference/index.md#setting-the-page-subtitle
+
+#### Linking from and to posts
+
+While [post URLs][post slugs] are dynamically computed, the [built-in blog
+plugin] ensures that all links from and to posts and a post's assets are
+correct. If you want to link to a post, just use the path to the Markdown file
+as a link reference (links must be relative):
+
+``` markdown
+[Hello World!](blog/posts/hello-world.md)
+```
+
+Linking from a post to a page, e.g. the index, follows the same method:
+
+``` markdown
+[Blog](../index.md)
+```
+
+All assets inside the `posts` directory are copied to the `blog/assets` folder
+when the site is being built. Of course, you can also reference assets from
+posts outside of the `posts` directory. The [built-in blog plugin] ensures that
+all links are correct.
+
+#### Pinning a post
+
+<!-- md:version 9.7.0 -->
+<!-- md:flag experimental -->
+
+If you want to pin a post to the top of the index page, as well as the archive
+and category indexes it is part of, you can use the front matter `pin` property:
+
+``` yaml
+---
+date: 2024-01-31
+pin: true
+---
+
+# Hello world!
+...
+```
+
+If multiple posts are pinned, they are sorted by their creation date, with the
+most recent pinned post being shown first, followed by the other pinned posts in
+descending order.
+
+#### Setting the reading time
+
+When [enabled], the reading the expected reading time of each post is computed,
+which is rendered as part of the post and post excerpt. Nowadays, many blogs
+show reading times, which is why the [built-in blog plugin] offers this
+capability as well.
+
+Sometimes, however, the computed reading time might not feel accurate, or
+result in odd and unpleasant numbers. For this reason, reading time can be
+overridden and explicitly set with the front matter `readtime` property for a
+post:
+
+``` yaml
+---
+date: 2024-01-31
+readtime: 15
+---
+
+# Hello world!
+...
+```
+
+This will disable automatic reading time computation.
+
+!!! warning "Chinese, Japanese and Korean characters"
+
+ Reading time computation currently does not take segmentation of Chinese,
+ Japanese and Korean characters into account. This means that the reading
+ time for posts in these languages may be inaccurate. We're planning on
+ adding support in the future. In the meantime, please use the `readtime`
+ front matter property to set the reading time.
+
+ [enabled]: ../plugins/blog.md#config.post_readtime
+
+#### Setting defaults
+
+<!-- md:version 9.6.0 -->
+<!-- md:plugin [meta][built-in meta plugin] – built-in -->
+<!-- md:flag experimental -->
+
+If you have a lot of posts, it might feel redundant to define all of the above
+for each post. Luckily, the [built-in meta plugin] allows to set default front
+matter properties per folder. You can group your posts by categories, or
+authors, and add a `.meta.yml` file to set common properties:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+│ └─ blog/
+│ ├─ posts/
+│ ├─ .meta.yml # (1)!
+│ └─ index.md
+└─ mkdocs.yml
+```
+
+1. As already noted, you can also place a `.meta.yml` file in nested folders
+ of the `posts` directory. This file then can define all front matter
+ properties that are valid in posts, e.g.:
+
+ ``` yaml
+ authors:
+ - squidfunk
+ categories:
+ - Hello
+ - World
+ ```
+
+Note that order matters – the [built-in meta plugin] must be defined before the
+blog plugin in `mkdocs.yml`, so that all set defaults are correctly picked up
+by the [built-in blog plugin]:
+
+``` yaml
+plugins:
+ - meta
+ - blog
+```
+
+Lists and dictionaries in `.meta.yml` files are merged and deduplicated with the
+values defined for a post, which means you can define common properties in
+`.meta.yml` and then add specific properties or overrides for each post.
+
+ [built-in meta plugin]: ../plugins/meta.md
+
+### Adding pages
+
+Besides posts, it's also possible to add static pages to your blog by listing
+the pages in the [`nav`][mkdocs.nav] section of `mkdocs.yml`. All generated
+indexes are included after the last specified page. For example, to add a page
+on the authors of the blog, add the following to `mkdocs.yml`:
+
+``` yaml
+nav:
+ - Blog:
+ - blog/index.md
+ - blog/authors.md
+ ...
+```
+
+## Customization
+
+### Custom index pages
+
+<!-- md:version 9.6.0 -->
+<!-- md:flag experimental -->
+
+If you want to add custom content to automatically generated [archive] and
+[category] indexes, e.g. to add a category description prior to the list of
+posts, you can manually create the category page in the same location where
+the [built-in blog plugin] would create it:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+│ └─ blog/
+│ ├─ category/
+│ │ └─ hello.md # (1)!
+│ ├─ posts/
+│ └─ index.md
+└─ mkdocs.yml
+```
+
+1. The easiest way is to first [add the category] to the blog post, then take
+ the URL generated by the [built-in blog plugin] and create the file at the
+ corresponding location in the [`blog_dir`][blog_dir] folder.
+
+ Note that the shown directory listing is based on the default configuration.
+ If you specify different values for the following options, be sure to adjust
+ the path accordingly:
+
+ - [`blog_dir`][blog_dir]
+ - [`categories_url_format`][categories_url_format]
+ - [`categories_slugify`][categories_slugify]
+
+You can now add arbitrary content to the newly created file, or set specific
+front matter properties for this page, e.g. to change the [page description]:
+
+``` yaml
+---
+description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
+---
+
+# Hello
+...
+```
+
+All post excerpts belonging to the category are automatically appended.
+
+ [add the category]: #adding-categories
+ [page description]: ../reference/index.md#setting-the-page-description
+ [categories_url_format]: ../plugins/blog.md#config.categories_url_format
+ [categories_slugify]: ../plugins/blog.md#config.categories_slugify
+ [blog_dir]: ../plugins/blog.md#config.blog_dir
+
+### Overriding templates
+
+The [built-in blog plugin] is built on the same basis as Material for MkDocs,
+which means you can override all templates used for the blog by using
+[theme extension] as usual.
+
+The following templates are added by the [built-in blog plugin]:
+
+- [`blog.html`][blog.html] – Template for blog, archive and category index
+- [`blog-post.html`][blog-post.html] – Template for blog post
+
+ [theme extension]: ../customization.md#extending-the-theme
+
+ [blog.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/blog.html
+ [blog-post.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/blog-post.html
diff --git a/documents/markdown/mkdocs-material/setup_setting-up-navigation.md b/documents/markdown/mkdocs-material/setup_setting-up-navigation.md
new file mode 100644
index 0000000..ff8bf55
--- /dev/null
+++ b/documents/markdown/mkdocs-material/setup_setting-up-navigation.md
@@ -0,0 +1,649 @@
+# Setting up navigation
+
+A clear and concise navigation structure is an important aspect of good project
+documentation. Material for MkDocs provides a multitude of options to configure
+the behavior of navigational elements, including [tabs] and [sections], and one
+of its flagship features: [instant loading].
+
+ [tabs]: #navigation-tabs
+ [sections]: #navigation-sections
+ [instant loading]: #instant-loading
+
+Additional navigation can be configured [in the footer] as well as with the
+[tags plugin]. The [blog plugin] also sets up additional navigation.
+
+[in the footer]: setting-up-the-footer.md#navigation
+[tags plugin]: ../plugins/tags.md
+[blog plugin]: ../plugins/blog.md
+
+## Configuration
+
+### Instant loading
+
+<!-- md:version 5.0.0 -->
+<!-- md:feature -->
+
+When instant loading is enabled, clicks on all internal links will be
+intercepted and dispatched via [XHR] without fully reloading the page. Add
+the following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - navigation.instant
+```
+
+The resulting page is parsed and injected and all event handlers and components
+are rebound automatically, i.e., __Material for MkDocs now behaves like a Single
+Page Application__. Now, the search index survives navigation, which is
+especially useful for large documentation sites.
+
+!!! info "The [`site_url`][mkdocs.site_url] setting must be set"
+
+ Note that you must set [`site_url`][mkdocs.site_url] when using instant
+ navigation, as instant navigation relies on the generated `sitemap.xml`
+ which will be empty if this setting is omitted. Example:
+
+ ``` yaml
+ site_url: https://example.com
+ ```
+
+ [XHR]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
+
+#### Instant prefetching
+
+<!-- md:version 9.7.0 -->
+<!-- md:feature -->
+<!-- md:flag experimental -->
+
+Instant prefetching is a new experimental feature that will start to fetch a
+page once the user hovers over a link. This will reduce the perceived loading
+time for the user, especially on slow connections, as the page will be available
+immediately upon navigation. Enable it with:
+
+``` yaml
+theme:
+ features:
+ - navigation.instant
+ - navigation.instant.prefetch
+```
+
+#### Progress indicator
+
+<!-- md:version 9.4.3 -->
+<!-- md:feature -->
+<!-- md:flag experimental -->
+
+In order to provide a better user experience on slow connections when using
+instant navigation, a progress indicator can be enabled. It will be shown at
+the top of the page and will be hidden once the page has fully loaded. You can
+enable it in `mkdocs.yml` with:
+
+``` yaml
+theme:
+ features:
+ - navigation.instant
+ - navigation.instant.progress
+```
+
+The progress indicator will only show if the page hasn't finished loading after
+400ms, so that fast connections will never show it for a better instant
+experience.
+
+### Instant previews
+
+<!-- md:version 9.7.0 -->
+<!-- md:feature -->
+<!-- md:flag experimental -->
+
+Instant previews are a brand new feature that allow the user to preview another
+site of your documentation without navigating to it. They can be very helpful to
+keep the user in context. Instant previews can be enabled on any header link
+with the `data-preview` attribute:
+
+```` markdown title="Link with instant preview"
+``` markdown
+[Attribute Lists](#){ data-preview }
+```
+````
+
+<div class="result" markdown>
+
+[Attribute Lists](extensions/python-markdown.md#attribute-lists){ data-preview }
+
+</div>
+
+!!! info "Limitations"
+
+ Instant previews are still an experimental feature and currently limited to
+ headerlinks. This means, you can use them on any internal link that points
+ to a header on another page, but not other elements with `id` attributes.
+ After we have gathered enough feedback, we will consider extending this
+ feature to other, and possibly arbitrary elements.
+
+#### Automatic previews
+
+<!-- md:version 9.7.0 -->
+<!-- md:extension -->
+<!-- md:flag experimental -->
+
+The recommended way to work with instant previews is to use the Markdown
+extension that is included with Material for MkDocs, as it allows you to enable
+instant previews on a per-page or per-section level for your documentation:
+
+``` yaml
+markdown_extensions:
+ - material.extensions.preview:
+ configurations:
+ - targets:
+ include:
+ - changelog/index.md
+ - customization.md
+ - insiders/changelog/*
+ - setup/extensions/*
+```
+
+The above configuration is what we use for our documentation. We've enabled
+instant previews for our changelogs, customization guide, and Insiders sections,
+as well as for all Markdown extensions that we support.
+
+!!! info "Full configuration example"
+
+ ``` yaml
+ markdown_extensions:
+ - material.extensions.preview:
+ configurations:
+ - sources: # (1)!
+ include:
+ - ...
+ exclude:
+ - ...
+ targets: # (2)!
+ include:
+ - ...
+ exclude:
+ - ...
+ ```
+
+ 1. Sources specify the pages _on_ which instant previews should be enabled.
+ If this setting is omitted, instant previews will be enabled on all
+ pages. You can use patterns to include or exclude pages. Exclusion is
+ evaluated on top of inclusion, so if a page is matched by both, it will
+ be excluded.
+
+ Note that you can define multiple items under the `configurations`
+ setting, which allows to precisely control where instant previews are
+ shown.
+
+ 2. Targets specify the pages _to_ which instant previews should be enabled.
+ This is the recommended way to enable instant previews.
+---
+
+Instant previews can also be enabled globally by adding the following lines to
+`mkdocs.yml`, which will enable instant previews for all header links,
+alleviating the need to add data attributes:
+
+``` yaml
+theme:
+ features:
+ - navigation.instant.preview
+```
+
+!!! info "The [`site_url`][mkdocs.site_url] setting must be set"
+
+ Note that you must set [`site_url`][mkdocs.site_url] when using instant
+ previews, as instant previews rely on the generated `sitemap.xml`
+ which will be empty if this setting is omitted. Example:
+
+ ``` yaml
+ site_url: https://example.com
+ ```
+
+### Anchor tracking
+
+<!-- md:version 8.0.0 -->
+<!-- md:feature -->
+
+When anchor tracking is enabled, the URL in the address bar is automatically
+updated with the active anchor as highlighted in the table of contents. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - navigation.tracking
+```
+
+### Navigation tabs
+
+<!-- md:version 1.1.0 -->
+<!-- md:feature -->
+
+When tabs are enabled, top-level sections are rendered in a menu layer below
+the header for viewports above `1220px`, but remain as-is on mobile.[^1] Add
+the following lines to `mkdocs.yml`:
+
+ [^1]:
+ Prior to <!-- md:version 6.2.0 -->, navigation tabs had a slightly different
+ behavior. All top-level pages (i.e. all top-level entries directly
+ referring to a `*.md` file) defined inside the `nav` entry of `mkdocs.yml`
+ were grouped under the first tab which received the title of the first page.
+ This made it impossible to include a top-level page (or external link) as a
+ tab item, as was reported in #1884 and #2072. From <!-- md:version 6.2.0 -->
+ on, navigation tabs include all top-level pages and sections.
+
+``` yaml
+theme:
+ features:
+ - navigation.tabs
+```
+
+=== "With tabs"
+
+ [![Navigation tabs enabled]][Navigation tabs enabled]
+
+=== "Without"
+
+ [![Navigation tabs disabled]][Navigation tabs disabled]
+
+ [Navigation tabs enabled]: ../assets/screenshots/navigation-tabs.png
+ [Navigation tabs disabled]: ../assets/screenshots/navigation.png
+
+#### Sticky navigation tabs
+
+<!-- md:version 7.3.0 -->
+<!-- md:feature -->
+
+When sticky tabs are enabled, navigation tabs will lock below the header and
+always remain visible when scrolling down. Just add the following two feature
+flags to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - navigation.tabs
+ - navigation.tabs.sticky
+```
+
+=== "With sticky tabs"
+
+ [![Sticky navigation tabs enabled]][Sticky navigation tabs enabled]
+
+=== "Without"
+
+ [![Sticky navigation tabs disabled]][Sticky navigation tabs disabled]
+
+ [Sticky navigation tabs enabled]: ../assets/screenshots/navigation-tabs-sticky.png
+ [Sticky navigation tabs disabled]: ../assets/screenshots/navigation-tabs-collapsed.png
+
+### Navigation sections
+
+<!-- md:version 6.2.0 -->
+<!-- md:feature -->
+
+When sections are enabled, top-level sections are rendered as groups in the
+sidebar for viewports above `1220px`, but remain as-is on mobile. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - navigation.sections
+```
+
+=== "With sections"
+
+ [![Navigation sections enabled]][Navigation sections enabled]
+
+=== "Without"
+
+ [![Navigation sections disabled]][Navigation sections disabled]
+
+ [Navigation sections enabled]: ../assets/screenshots/navigation-sections.png
+ [Navigation sections disabled]: ../assets/screenshots/navigation.png
+
+Both feature flags, [`navigation.tabs`][tabs] and
+[`navigation.sections`][sections], can be combined with each other. If both
+feature flags are enabled, sections are rendered for level 2 navigation items.
+
+### Navigation expansion
+
+<!-- md:version 6.2.0 -->
+<!-- md:feature -->
+
+When expansion is enabled, the left sidebar will expand all collapsible
+subsections by default, so the user doesn't have to open subsections manually.
+Add the following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - navigation.expand
+```
+
+=== "With expansion"
+
+ [![Navigation expansion enabled]][Navigation expansion enabled]
+
+=== "Without"
+
+ [![Navigation expansion disabled]][Navigation expansion disabled]
+
+ [Navigation expansion enabled]: ../assets/screenshots/navigation-expand.png
+ [Navigation expansion disabled]: ../assets/screenshots/navigation.png
+
+### Navigation path <small>Breadcrumbs</small> { id=navigation-path }
+
+<!-- md:version 9.7.0 -->
+<!-- md:feature -->
+<!-- md:flag experimental -->
+
+When navigation paths are activated, a breadcrumb navigation is rendered above
+the title of each page, which might make orientation easier for users visiting your
+documentation on devices with smaller screens. Add the following lines to
+`mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - navigation.path
+```
+
+=== "With navigation path"
+
+ [![Navigation path enabled]][Navigation path enabled]
+
+=== "Without"
+
+ [![Navigation path disabled]][Navigation path disabled]
+
+ [Navigation path enabled]: ../assets/screenshots/navigation-path-on.png
+ [Navigation path disabled]: ../assets/screenshots/navigation-path-off.png
+
+### Navigation pruning
+
+<!-- md:version 9.2.0 -->
+<!-- md:feature -->
+<!-- md:flag experimental -->
+
+When pruning is enabled, only the visible navigation items are included in the
+rendered HTML, __reducing the size of the built site by 33% or more__. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - navigation.prune # (1)!
+```
+
+1. This feature flag is not compatible with
+ [`navigation.expand`][navigation.expand], as navigation expansion requires
+ the complete navigation structure.
+
+This feature flag is especially useful for documentation sites with 100+ or even
+1,000+ of pages, as the navigation makes up a significant fraction of the HTML.
+Navigation pruning will replace all expandable sections with links to the first
+page in that section (or the section index page).
+
+ [navigation.expand]: #navigation-expansion
+
+### Section index pages
+
+<!-- md:version 7.3.0 -->
+<!-- md:feature -->
+
+When section index pages are enabled, documents can be directly attached to
+sections, which is particularly useful for providing overview pages. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - navigation.indexes # (1)!
+```
+
+1. This feature flag is not compatible with [`toc.integrate`][toc.integrate],
+ as sections cannot host the table of contents due to missing space.
+
+=== "With section index pages"
+
+ [![Section index pages enabled]][Section index pages enabled]
+
+=== "Without"
+
+ [![Section index pages disabled]][Section index pages disabled]
+
+In order to link a page to a section, create a new document with the name
+`index.md` in the respective folder, and add it to the beginning of your
+navigation section:
+
+``` yaml
+nav:
+ - Section:
+ - section/index.md # (1)!
+ - Page 1: section/page-1.md
+ ...
+ - Page n: section/page-n.md
+```
+
+1. MkDocs also considers files called `README.md` as [index pages].
+
+ [Section index pages enabled]: ../assets/screenshots/navigation-index-on.png
+ [Section index pages disabled]: ../assets/screenshots/navigation-index-off.png
+ [toc.integrate]: #navigation-integration
+ [index pages]: https://www.mkdocs.org/user-guide/writing-your-docs/#index-pages
+
+### Table of contents
+
+#### Anchor following
+
+<!-- md:version 8.5.0 -->
+<!-- md:feature -->
+<!-- md:flag experimental -->
+
+When anchor following for the [table of contents] is enabled, the sidebar is
+automatically scrolled so that the active anchor is always visible. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - toc.follow
+```
+
+#### Navigation integration
+
+<!-- md:version 6.2.0 -->
+<!-- md:feature -->
+
+When navigation integration for the [table of contents] is enabled, it is always
+rendered as part of the navigation sidebar on the left. Add the following lines
+to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - toc.integrate # (1)!
+```
+
+1. This feature flag is not compatible with
+ [`navigation.indexes`][navigation.indexes], as sections cannot host the
+ table of contents due to missing space.
+
+=== "With navigation integration"
+
+ [![Navigation integration enabled]][Navigation integration enabled]
+
+=== "Without"
+
+ [![Navigation integration disabled]][Navigation integration disabled]
+
+ [table of contents]: extensions/python-markdown.md#table-of-contents
+ [Navigation integration enabled]: ../assets/screenshots/toc-integrate.png
+ [Navigation integration disabled]: ../assets/screenshots/navigation-tabs.png
+ [navigation.indexes]: #section-index-pages
+
+### Back-to-top button
+
+<!-- md:version 7.1.0 -->
+<!-- md:feature -->
+
+A back-to-top button can be shown when the user, after scrolling down, starts
+to scroll up again. It's rendered centered and just below the header. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - navigation.top
+```
+
+## Usage
+
+### Hiding the sidebars
+
+<!-- md:version 6.2.0 -->
+<!-- md:flag metadata -->
+
+The navigation and/or table of contents sidebars can be hidden for a document
+with the front matter `hide` property. Add the following lines at the top of a
+Markdown file:
+
+``` yaml
+---
+hide:
+ - navigation
+ - toc
+---
+
+# Page title
+...
+```
+
+=== "Hide navigation"
+
+ [![Hide navigation enabled]][Hide navigation enabled]
+
+=== "Hide table of contents"
+
+ [![Hide table of contents enabled]][Hide table of contents enabled]
+
+=== "Hide both"
+
+ [![Hide both enabled]][Hide both enabled]
+
+ [Hide navigation enabled]: ../assets/screenshots/hide-navigation.png
+ [Hide table of contents enabled]: ../assets/screenshots/hide-toc.png
+ [Hide both enabled]: ../assets/screenshots/hide-navigation-toc.png
+
+### Hiding the navigation path
+
+<!-- md:version 9.7.0 -->
+<!-- md:flag metadata -->
+
+While the [navigation path] is rendered above the main headline, sometimes, it
+might be desirable to hide it for a specific page, which can be achieved with
+the front matter `hide` property:
+
+``` yaml
+---
+hide:
+ - path
+---
+
+# Page title
+...
+```
+
+ [navigation path]: #navigation-path
+
+## Customization
+
+### Keyboard shortcuts
+
+Material for MkDocs includes several keyboard shortcuts that make it possible
+to navigate your project documentation via keyboard. There are two modes:
+
+<!-- md:option mode:search -->
+
+: This mode is active when the _search is focused_. It provides several key
+ bindings to make search accessible and navigable via keyboard:
+
+ * ++arrow-down++ , ++arrow-up++ : select next / previous result
+ * ++esc++ , ++tab++ : close search dialog
+ * ++enter++ : follow selected result
+
+<!-- md:option mode:global -->
+
+: This mode is active when _search is not focussed_ and when there's no other
+ focussed element that is susceptible to keyboard input. The following keys
+ are bound:
+
+ * ++f++ , ++s++ , ++slash++ : open search dialog
+ * ++p++ , ++comma++ : go to previous page
+ * ++n++ , ++period++ : go to next page
+
+Let's say you want to bind some action to the ++x++ key. By using [additional
+JavaScript], you can subscribe to the `keyboard$` observable and attach
+your custom event listener:
+
+=== ":octicons-file-code-16: `docs/javascripts/shortcuts.js`"
+
+ ``` js
+ keyboard$.subscribe(function(key) {
+ if (key.mode === "global" && key.type === "x") {
+ /* Add custom keyboard handler here */
+ key.claim() // (1)!
+ }
+ })
+ ```
+
+ 1. The call to `key.claim()` will execute `preventDefault()` on the
+ underlying event, so the keypress will not propagate further and
+ touch other event listeners.
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_javascript:
+ - javascripts/shortcuts.js
+ ```
+
+ [additional JavaScript]: ../customization.md#additional-javascript
+
+### Content area width
+
+The width of the content area is set so the length of each line doesn't exceed
+80-100 characters, depending on the width of the characters. While this
+is a reasonable default, as longer lines tend to be harder to read, it may be
+desirable to increase the overall width of the content area, or even make it
+stretch to the entire available space.
+
+This can easily be achieved with an [additional style sheet] and a few lines
+of CSS:
+
+=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
+
+ ``` css
+ .md-grid {
+ max-width: 1440px; /* (1)! */
+ }
+ ```
+
+ 1. If you want the content area to always stretch to the available screen
+ space, reset `max-width` with the following CSS:
+
+ ``` css
+ .md-grid {
+ max-width: initial;
+ }
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_css:
+ - stylesheets/extra.css
+ ```
+
+ [additional style sheet]: ../customization.md#additional-css
diff --git a/documents/markdown/mkdocs-material/setup_setting-up-site-analytics.md b/documents/markdown/mkdocs-material/setup_setting-up-site-analytics.md
new file mode 100644
index 0000000..5a8c523
--- /dev/null
+++ b/documents/markdown/mkdocs-material/setup_setting-up-site-analytics.md
@@ -0,0 +1,324 @@
+# Setting up site analytics
+
+As with any other service offered on the web, understanding how your project
+documentation is actually used can be an essential success factor. Material for
+MkDocs natively integrates with [Google Analytics] and offers a customizable
+[cookie consent] and a [feedback widget].
+
+ [Google Analytics]: https://developers.google.com/analytics
+ [cookie consent]: ensuring-data-privacy.md#cookie-consent
+ [feedback widget]: #was-this-page-helpful
+
+## Configuration
+
+### Google Analytics
+
+<!-- md:version 7.1.8 -->
+<!-- md:default none -->
+
+Material for MkDocs integrates natively with Google Analytics 4[^1]. If you
+already set up Google Analytics and have a property, enable it by adding the
+following lines to `mkdocs.yml`:
+
+ [^1]:
+ Prior to Material for MkDocs 9.2.0, Universal Analytics was supported as
+ well. However, since Universal Analytics has been sunset, this integration
+ was removed in 9.2.0.
+
+``` yaml
+extra:
+ analytics:
+ provider: google
+ property: G-XXXXXXXXXX
+```
+
+??? question "How to measure site search usage?"
+
+ Besides page views and events, [site search] can be tracked to better
+ understand how people use your documentation and what they expect to find.
+ In order to enable site search tracking, the following steps are required:
+
+ 1. Go to your Google Analytics __admin settings__
+ 2. Select the property for the respective tracking code
+ 3. Select the __data streams__ tab and click the corresponding URL
+ 4. Click the gear icon within the __enhanced measurement__ section
+ 5. Ensure that __site search__ is enabled
+
+ [site search]: setting-up-site-search.md
+
+### Was this page helpful?
+
+<!-- md:version 8.4.0 -->
+<!-- md:default none -->
+
+A simple [feedback widget] can be included at the bottom of each page,
+encouraging users to give instant feedback whether a page was helpful or not.
+Add the following lines to `mkdocs.yml`:
+
+``` yaml
+extra:
+ analytics: # (1)!
+ feedback:
+ title: Was this page helpful?
+ ratings:
+ - icon: material/emoticon-happy-outline
+ name: This page was helpful
+ data: 1
+ note: >-
+ Thanks for your feedback!
+ - icon: material/emoticon-sad-outline
+ name: This page could be improved
+ data: 0
+ note: >- # (2)!
+ Thanks for your feedback! Help us improve this page by
+ using our <a href="..." target="_blank" rel="noopener">feedback form</a>.
+```
+
+1. This feature is natively integrated with [Google Analytics][analytics],
+ which is why `provider` and `property` are also required. However, it's also
+ possible to provide a [custom feedback integration].
+
+2. You can add arbitrary HTML tags to the note which is shown after the user
+ submitted the feedback, e.g. to link to a feedback form.
+
+Both properties, `title` and `ratings`, are required. Note that it's allowed to
+define more than two ratings, e.g. to implement a 1-5 star rating. Since the
+feedback widget sends data to a third-party service, it is, of course, natively
+integrated with the [cookie consent] feature[^2].
+
+ [^2]:
+ If the user doesn't accept the `analytics` cookie, the feedback widget is
+ not shown.
+
+??? question "How to visualize the collected feedback ratings?"
+
+ To visualize feedback ratings you'll need to create a custom report with
+ [Google Analytics] that will quickly show you the worst- and best-rated
+ pages of your project documentation.
+
+ 1. Go to your Google Analytics __dashboard__
+
+ 2. Go to the __Admin__ page on the left hand menu (at the bottom), then select
+ __custom definitions__ on the __Data display__ card
+
+ 3. Click the __custom metrics__ tab and then __create custom metrics__,
+ enter the following values:
+
+ * Metric name: Page helpful
+ * Description: Was this page helpful?
+ * Event parameter: `data`
+ * Unit of measurement: Standard
+
+ 4. Go to the __explore__ page on the left hand menu, create a new
+ __blank exploration__
+
+ 5. Configure the report as follows:
+
+ * Dimensions: Add `Event name` and `Page location`
+ * Metrics: Add `Event count` and `Page helpful`
+ (the custom metric created in step 3)
+ * Rows: `Page location`
+ * Values: Drag in both `Event count` and `Page helpful`
+ * Filters: Add a new filter for
+ `Event name / exactly matches / feedback`
+
+ !!! warning "Delay in data availability"
+
+ The report may take 24 hours or longer to begin displaying data
+
+ Now, after you've saved the report and collected some feedback ratings,
+ you'll have a list of all pages with the total number of ratings, and an
+ average rating per page. This should help you identify pages that need to
+ be improved:
+
+ !!! danger "Google Analytics 4 does not support average values"
+
+ To our knowledge, Google Analytics 4 has currently no feature that
+ allows to define a custom calculated metric to compute the average
+ rating of a page. See #5740.
+
+ [![feedback report]][feedback report]
+
+The following properties are available for each rating:
+
+<!-- md:option analytics.feedback.ratings.icon -->
+
+: <!-- md:default none --> <!-- md:flag required -->
+ This property must point to a valid icon path referencing [any icon bundled
+ with the theme][custom icons], or the build will not succeed. Some popular
+ combinations:
+
+ * :material-emoticon-happy-outline: + :material-emoticon-sad-outline: – `material/emoticon-happy-outline` + `material/emoticon-sad-outline`
+ * :material-thumb-up-outline: + :material-thumb-down-outline: – `material/thumb-up-outline` + `material/thumb-down-outline`
+ * :material-heart: + :material-heart-broken: – `material/heart` + `material/heart-broken`
+
+<!-- md:option analytics.feedback.ratings.name -->
+
+: <!-- md:default none --> <!-- md:flag required -->
+ The value of this property is shown on user interaction (i.e. keyboard focus
+ or mouse hover), explaining the meaning of the rating behind the icon.
+
+<!-- md:option analytics.feedback.ratings.data -->
+
+: <!-- md:default none --> <!-- md:flag required -->
+ The value of this property is sent as a data value with the custom event
+ that is transmitted to Google Analytics[^3] (or any custom integration).
+
+ [^3]:
+ Note that for Google Analytics, the data value must be an integer.
+
+<!-- md:option analytics.feedback.ratings.note -->
+
+: <!-- md:default none --> <!-- md:flag required -->
+ The value of this property is shown after the user selected the rating.
+ It may contain arbitrary HTML tags, which is especially useful to ask the
+ user to provide more detailed feedback for the current page through a form.
+ It's also possible to pre-fill forms with the URL and title of the current
+ page by using the following placeholders:
+
+ - `{url}` – Page URL
+ - `{title}` – Page title
+
+ ```
+ https://github.com/.../issues/new/?title=[Feedback]+{title}+-+{url}
+ ```
+
+ In this example, when clicking the link, the user is redirected to the "new
+ issue" form of your repository, with a pre-filled title including the path
+ of the current document, e.g.:
+
+ ```
+ [Feedback] Setting up site analytics – /setup/setting-up-site-analytics/
+ ```
+
+ An alternative to GitHub issues is [Google Forms].
+
+ [feedback widget]: #feedback
+ [analytics]: #google-analytics
+ [feedback report]: ../assets/screenshots/feedback-report.png
+ [custom feedback integration]: #custom-site-feedback
+ [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/templates/.icons
+ [Google Forms]: https://www.google.com/forms/about/
+
+## Usage
+
+### Hiding the feedback widget
+
+The [feedback widget] can be hidden for a document with the front matter `hide`
+property. Add the following lines at the top of a Markdown file:
+
+``` yaml
+---
+hide:
+ - feedback
+---
+
+# Page title
+...
+```
+
+## Customization
+
+### Custom site analytics
+
+In order to integrate another analytics service provider offering a
+JavaScript-based tracking solution, just follow the guide on [theme extension]
+and create a new partial in the `overrides` folder. The name of the partial is
+used to configure the custom integration via `mkdocs.yml`:
+
+=== ":octicons-file-code-16: `overrides/partials/integrations/analytics/custom.html`"
+
+ ``` html
+ <script>
+ /* Add custom analytics integration here, e.g. */
+ var property = "{{ config.extra.analytics.property }}" // (1)!
+
+ /* Wait for page to load and application to mount */
+ document.addEventListener("DOMContentLoaded", function() {
+ location$.subscribe(function(url) {
+ /* Add custom page event tracking here */ // (2)!
+ })
+ })
+ </script>
+ ```
+
+ 1. As an example, this variable receives the value set in `mkdocs.yml`,
+ which is `"foobar"` for `property`.
+ 2. If you're using [instant loading], you can use the `location$`
+ observable to listen for navigation events, which always emits the
+ current `URL`.
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra:
+ analytics:
+ provider: custom
+ property: foobar # (1)!
+ ```
+
+ 1. You can add arbitrary key-value combinations to configure your
+ custom integration. This is especially useful if you're sharing the
+ custom integration across multiple repositories.
+
+ [theme extension]: ../customization.md#extending-the-theme
+ [instant loading]: setting-up-navigation.md#instant-loading
+
+### Custom site feedback
+
+A custom feedback widget integration just needs to process the events that are
+generated by users interacting with the feedback widget with the help of some
+[additional JavaScript]:
+
+=== ":octicons-file-code-16: `docs/javascripts/feedback.js`"
+
+ ``` js
+ document$.subscribe(function() {
+ var feedback = document.forms.feedback
+ if (typeof feedback === "undefined") return
+
+ feedback.hidden = false // (1)!
+
+ feedback.addEventListener("submit", function(ev) {
+ ev.preventDefault()
+
+ var page = document.location.pathname // (2)!
+ var data = ev.submitter.getAttribute("data-md-value")
+
+ console.log(page, data) // (3)!
+
+ feedback.firstElementChild.disabled = true // (4)!
+
+ var note = feedback.querySelector(
+ ".md-feedback__note [data-md-value='" + data + "']"
+ )
+ if (note)
+ note.hidden = false // (5)!
+ })
+ }
+ ```
+
+ 1. The feedback widget is hidden by default so that it does not appear when
+ people have JavaScript turned off. So, it needs to be turned on here.
+
+ 2. Retrieve page and feedback value.
+
+ 3. Replace this with the code that sends the data off to your analytics
+ provider.
+
+ 4. Disable the form after submission.
+
+ 5. Show the configured notes. Which one is shown depends on the user
+ feedback.
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ extra_javascript:
+ - javascripts/feedback.js
+ ```
+
+
+{ #feedback style="margin: 0; height: 0" }
+
+ [additional JavaScript]: ../customization.md#additional-javascript
diff --git a/documents/markdown/mkdocs-material/setup_setting-up-site-search.md b/documents/markdown/mkdocs-material/setup_setting-up-site-search.md
new file mode 100644
index 0000000..605c9c9
--- /dev/null
+++ b/documents/markdown/mkdocs-material/setup_setting-up-site-search.md
@@ -0,0 +1,229 @@
+---
+search:
+ boost: 1.05
+---
+
+# Setting up site search
+
+Material for MkDocs provides an excellent client-side search implementation,
+omitting the need for the integration of third-party services, which might
+not be compliant with privacy regulations. Moreover, search even works
+[offline], allowing users to download your documentation.
+
+ [offline]: building-for-offline-usage.md
+
+## Configuration
+
+### Built-in search plugin
+
+<!-- md:version 0.1.0 -->
+<!-- md:plugin -->
+
+The built-in search plugin integrates seamlessly with Material for MkDocs,
+adding multilingual client-side search with [lunr] and [lunr-languages]. It's
+enabled by default, but must be re-added to `mkdocs.yml` when other plugins
+are used:
+
+``` yaml
+plugins:
+ - search
+```
+
+For a list of all settings, please consult the [plugin documentation].
+
+ [plugin documentation]: ../plugins/search.md
+
+ [lunr]: https://lunrjs.com
+ [lunr-languages]: https://github.com/MihaiValentin/lunr-languages
+
+### Search suggestions
+
+<!-- md:version 7.2.0 -->
+<!-- md:feature -->
+<!-- md:flag experimental -->
+
+When search suggestions are enabled, the search will display the likeliest
+completion for the last word which can be accepted with the ++arrow-right++ key.
+Add the following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - search.suggest
+```
+
+Searching for [:octicons-search-24: search su][Search suggestions example]
+yields ^^search suggestions^^ as a suggestion.
+
+ [Search suggestions example]: ?q=search+su
+
+### Search highlighting
+
+<!-- md:version 7.2.0 -->
+<!-- md:feature -->
+<!-- md:flag experimental -->
+
+When search highlighting is enabled and a user clicks on a search result,
+Material for MkDocs will highlight all occurrences after following the link.
+Add the following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - search.highlight
+```
+
+Searching for [:octicons-search-24: code blocks][Search highlighting example]
+highlights all occurrences of both terms.
+
+ [Search highlighting example]: ../reference/code-blocks.md?h=code+blocks
+
+### Search sharing
+
+<!-- md:version 7.2.0 -->
+<!-- md:feature -->
+
+When search sharing is activated, a :material-share-variant: share button is
+rendered next to the reset button, which allows to deep link to the current
+search query and result. Add the following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - search.share
+```
+
+When a user clicks the share button, the URL is automatically copied to the
+clipboard.
+
+## Usage
+
+### Search boosting
+
+<!-- md:version 8.3.0 -->
+<!-- md:flag metadata -->
+
+Pages can be boosted in search with the front matter `search.boost` property,
+which will make them rank higher. Add the following lines at the top of a
+Markdown file:
+
+=== ":material-arrow-up-circle: Rank up"
+
+ ``` yaml
+ ---
+ search:
+ boost: 2 # (1)!
+ ---
+
+ # Page title
+ ...
+ ```
+
+ 1. :woman_in_lotus_position: When boosting pages, be gentle and start with
+ __low values__.
+
+=== ":material-arrow-down-circle: Rank down"
+
+ ``` yaml
+ ---
+ search:
+ boost: 0.5
+ ---
+
+ # Page title
+ ...
+ ```
+
+### Search exclusion
+
+<!-- md:version 9.0.0 -->
+<!-- md:flag metadata -->
+<!-- md:flag experimental -->
+
+Pages can be excluded from search with the front matter `search.exclude`
+property, removing them from the index. Add the following lines at the top of a
+Markdown file:
+
+``` yaml
+---
+search:
+ exclude: true
+---
+
+# Page title
+...
+```
+
+#### Excluding sections
+
+When [Attribute Lists] is enabled, specific sections of pages can be excluded
+from search by adding the `data-search-exclude` pragma after a Markdown
+heading:
+
+=== ":octicons-file-code-16: `docs/page.md`"
+
+ ``` markdown
+ # Page title
+
+ ## Section 1
+
+ The content of this section is included
+
+ ## Section 2 { data-search-exclude }
+
+ The content of this section is excluded
+ ```
+
+=== ":octicons-codescan-16: `search_index.json`"
+
+ ``` json
+ {
+ ...
+ "docs": [
+ {
+ "location":"page/",
+ "text":"",
+ "title":"Document title"
+ },
+ {
+ "location":"page/#section-1",
+ "text":"<p>The content of this section is included</p>",
+ "title":"Section 1"
+ }
+ ]
+ }
+ ```
+
+ [Attribute Lists]: extensions/python-markdown.md#attribute-lists
+
+#### Excluding blocks
+
+When [Attribute Lists] is enabled, specific sections of pages can be excluded
+from search by adding the `data-search-exclude` pragma after a Markdown
+inline- or block-level element:
+
+=== ":octicons-file-code-16: `docs/page.md`"
+
+ ``` markdown
+ # Page title
+
+ The content of this block is included
+
+ The content of this block is excluded
+ { data-search-exclude }
+ ```
+
+=== ":octicons-codescan-16: `search_index.json`"
+
+ ``` json
+ {
+ ...
+ "docs": [
+ {
+ "location":"page/",
+ "text":"<p>The content of this block is included</p>",
+ "title":"Document title"
+ }
+ ]
+ }
+ ```
diff --git a/documents/markdown/mkdocs-material/setup_setting-up-social-cards.md b/documents/markdown/mkdocs-material/setup_setting-up-social-cards.md
new file mode 100644
index 0000000..af270e1
--- /dev/null
+++ b/documents/markdown/mkdocs-material/setup_setting-up-social-cards.md
@@ -0,0 +1,636 @@
+# Setting up social cards
+
+Material for MkDocs can automatically create beautiful social cards for your
+documentation, which appear as link previews on social media platforms. You
+can select from several [pre-designed layouts][default layouts] or create
+[custom layouts] to match your unique style and branding.
+
+---
+
+:fontawesome-brands-youtube:{ style="color: #EE0F0F" }
+__[How to build custom social cards]__ by @james-willett – :octicons-clock-24:
+24m – Learn how to create entirely custom social cards perfectly matching your
+branding for each page automatically!
+
+ [How to build custom social cards]: https://www.youtube.com/watch?v=4OjnOc6ftJ8
+
+<figure markdown>
+
+[![Layout default variant]][Layout default variant]
+
+ <figcaption markdown>
+
+Social card of our [formatting] reference
+
+ </figcaption>
+</figure>
+
+ [default layouts]: ../plugins/social.md#layouts
+ [custom layouts]: #customization
+ [formatting]: ../reference/formatting.md
+ [Layout default variant]: ../assets/screenshots/social-cards-variant.png
+
+## Configuration
+
+### Built-in social plugin
+
+<!-- md:version 8.5.0 -->
+<!-- md:plugin -->
+<!-- md:flag experimental -->
+<!-- md:demo create-social-cards -->
+
+The built-in social plugin automatically generate a custom preview image for
+each page. Install all [dependencies for image processing] and add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - social
+```
+
+For a list of all settings, please consult the [plugin documentation].
+
+ [plugin documentation]: ../plugins/social.md
+
+!!! info "The [`site_url`][site_url] setting must be set"
+
+ Note that you must set [`site_url`][site_url] when using the social plugin,
+ or the generated cards will not be correctly linked. Social media services
+ like X and Facebook demand that social previews point to an absolute
+ URL, which the plugin can only compute when [`site_url`][site_url] is set.
+ Example:
+
+ ``` yaml
+ site_url: https://example.com
+ ```
+
+ [dependencies for image processing]: ../plugins/requirements/image-processing.md
+ [site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
+
+## Usage
+
+If you want to adjust the title or set a custom description for the social card,
+you can set the front matter [`title`][Changing the title] and
+[`description`][Changing the description] properties, which take precedence over
+the defaults, or use:
+
+- [`cards_layout_options.title`](../plugins/social.md#option.title)
+- [`cards_layout_options.description`](../plugins/social.md#option.description)
+
+ [Changing the title]: ../reference/index.md#setting-the-page-title
+ [Changing the description]: ../reference/index.md#setting-the-page-description
+
+### Choosing a font
+
+Some fonts do not contain CJK characters, like for example the
+[default font, `Roboto`][font]. In case your `site_name`, `site_description`, or
+page title contain CJK characters, choose another font from [Google Fonts] which
+comes with CJK characters, e.g. one from the `Noto Sans` font family:
+
+=== "Chinese (Simplified)"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ font_family: Noto Sans SC
+ ```
+
+=== "Chinese (Traditional)"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ font_family: Noto Sans TC
+ ```
+
+=== "Japanese"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ font_family: Noto Sans JP
+ ```
+
+=== "Korean"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_options:
+ font_family: Noto Sans KR
+ ```
+
+ [font]: changing-the-fonts.md#regular-font
+
+### Changing the layout
+
+<!-- md:version 9.7.0 -->
+<!-- md:flag metadata -->
+<!-- md:flag experimental -->
+
+If you want to use a different layout for a single page (e.g. your landing
+page), you can use the `social` front matter property together with the
+[`cards_layout`](../plugins/social.md#meta.social.cards_layout) key, exactly as
+in `mkdocs.yml`:
+
+``` yaml
+---
+social:
+ cards_layout: custom
+---
+
+# Page title
+...
+```
+
+You can apply those changes for entire subtrees of your documentation, e.g.,
+to generate different social cards for your blog and API reference, by using
+the [built-in meta plugin].
+
+ [built-in meta plugin]: ../plugins/meta.md
+
+### Parametrizing the layout
+
+<!-- md:version 9.7.0 -->
+<!-- md:flag metadata -->
+<!-- md:flag experimental -->
+
+Besides changing the entire layout, you can override all options that a layout
+exposes. This means you can parametrize social cards with custom front matter
+properties, such as `tags`, `date`, `author` or anything you can think of.
+Simply define [`cards_layout_options`](../plugins/social.md#meta.social.cards_layout_options):
+
+``` yaml
+---
+social:
+ cards_layout_options:
+ background_color: blue # Change background color
+ background_image: null # Remove background image
+---
+
+# Page title
+...
+```
+
+You can apply those changes for entire subtrees of your documentation, e.g.,
+to generate different social cards for your blog and API reference, by using
+the [built-in meta plugin].
+
+### Disabling social cards
+
+<!-- md:version 9.7.0 -->
+<!-- md:flag metadata -->
+<!-- md:flag experimental -->
+
+If you wish to disable social cards for a page, simply add the following to the
+front matter of the Markdown document:
+
+``` yaml
+---
+social:
+ cards: false
+---
+
+# Page title
+...
+```
+
+## Customization
+
+<!-- md:version 9.7.0 -->
+<!-- md:flag experimental -->
+
+<div class="mdx-social">
+ <div class="mdx-social__layer">
+ <div class="mdx-social__image">
+ <span class="mdx-social__label">Layer 0</span>
+ <img src="../../assets/screenshots/social-cards-layer-0.png" />
+ </div>
+ </div>
+ <div class="mdx-social__layer">
+ <div class="mdx-social__image">
+ <span class="mdx-social__label">Layer 1</span>
+ <img src="../../assets/screenshots/social-cards-layer-1.png" />
+ </div>
+ </div>
+ <div class="mdx-social__layer">
+ <div class="mdx-social__image">
+ <span class="mdx-social__label">Layer 2</span>
+ <img src="../../assets/screenshots/social-cards-layer-2.png" />
+ </div>
+ </div>
+ <div class="mdx-social__layer">
+ <div class="mdx-social__image">
+ <span class="mdx-social__label">Layer 3</span>
+ <img src="../../assets/screenshots/social-cards-layer-3.png" />
+ </div>
+ </div>
+ <div class="mdx-social__layer">
+ <div class="mdx-social__image">
+ <span class="mdx-social__label">Layer 4</span>
+ <img src="../../assets/screenshots/social-cards-layer-4.png" />
+ </div>
+ </div>
+ <div class="mdx-social__layer">
+ <div class="mdx-social__image">
+ <span class="mdx-social__label">Layer 5</span>
+ <img src="../../assets/screenshots/social-cards-layer-5.png" />
+ </div>
+ </div>
+</div>
+
+Social cards are composed of layers, analogous to how they are represented in
+graphic design software such as Adobe Photoshop. As many layers are common
+across the cards generated for each page (e.g., backgrounds or logos), the
+built-in social plugin can automatically deduplicate layers and render them
+just once, substantially accelerating card generation. The generated cards are
+cached to ensure they are only regenerated when their contents change.
+
+Layouts are written in YAML syntax. Before starting to create a custom layout,
+it is a good idea to [study the pre-designed layouts], in order to get a better
+understanding of how they work. Then, create a new layout and reference it in
+`mkdocs.yml`:
+
+=== ":octicons-file-code-16: `layouts/custom.yml`"
+
+ ``` yaml
+ size: { width: 1200, height: 630 }
+ layers: []
+ ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+ ``` yaml
+ plugins:
+ - social:
+ cards_layout_dir: layouts
+ cards_layout: custom
+ debug: true
+ ```
+
+Note that the `.yml` file extension should be omitted. Next, run `mkdocs serve`,
+and see how the `.cache` directory is populated with the generated cards. Open
+any card in your editor, so you can see your changes immediately. Since we
+haven't defined any layers, the cards are transparent.
+
+The following sections explain how to create custom layouts.
+
+ [built-in social plugin]: ../plugins/social.md
+ [Google Fonts]: https://fonts.google.com/
+ [Jinja templates]: https://jinja.palletsprojects.com/en/3.1.x/
+ [study the pre-designed layouts]: https://github.com/squidfunk/mkdocs-material/tree/master/src/plugins/social/layouts
+
+### Size and offset
+
+Each layer has an associated size and offset, which is defined in pixels. The
+`size` is defined by a `width` and `height` property, and the `offset` by `x`
+and `y` properties:
+
+``` yaml
+size: { width: 1200, height: 630 }
+layers:
+ - size: { width: 1200, height: 630 }
+ offset: { x: 0, y: 0 }
+```
+
+If the `size` is omitted, it defaults to the size of the layout. If the `offset`
+is omitted, it defaults to the top left corner, which is the default `origin`.
+Saving the layout and reloading renders:
+
+![Layer size]
+
+The layer outline and grid are visible because we enabled [`debug`][debug]
+mode in `mkdocs.yml`. The top left shows the layer index and offset, which is
+useful for alignment and composition.
+
+ [Layer size]: ../assets/screenshots/social-cards-layer-size.png
+ [debug]: ../plugins/social.md#debugging
+
+#### Origin
+
+<!-- md:version 9.7.0 -->
+<!-- md:flag experimental -->
+
+The `origin` for the `x` and `y` values can be changed, so that the layer is
+aligned to one of the edges or corners of the layout, e.g., to the bottom right
+corner of the layout:
+
+``` yaml hl_lines="5"
+size: { width: 1200, height: 630 }
+layers:
+ - size: { width: 1200, height: 630 }
+ offset: { x: 0, y: 0 }
+ origin: end bottom
+```
+
+The following table shows the supported values:
+
+<figure markdown>
+
+| Origin | | |
+| -------------- | --------------- | ------------ |
+| :material-arrow-top-left: `start top` | :material-arrow-up: `center top` | :material-arrow-top-right: `end top` |
+| :material-arrow-left: `start center` | :material-circle-small: `center` | :material-arrow-right: `end center` |
+| :material-arrow-bottom-left: `start bottom` | :material-arrow-down: `center bottom` | :material-arrow-bottom-right: `end bottom` |
+
+ <figcaption>
+ Supported values for origin
+ </figcaption>
+</figure>
+
+### Backgrounds
+
+Each layer can be assigned a background color and image. If both are given, the
+color is rendered on top of the image, allowing for semi-transparent, tinted
+backgrounds:
+
+=== "Background color"
+
+ ``` yaml
+ size: { width: 1200, height: 630 }
+ layers:
+ - background:
+ color: "#4051b5"
+ ```
+
+ ![Layer background color]
+
+=== "Background image"
+
+ ``` yaml
+ size: { width: 1200, height: 630 }
+ layers:
+ - background:
+ image: layouts/background.png
+ ```
+
+ ![Layer background image]
+
+=== "Background image, tinted"
+
+ ``` yaml
+ size: { width: 1200, height: 630 }
+ layers:
+ - background:
+ image: layouts/background.png
+ color: "#4051b5ee" # (1)!
+ ```
+
+ 1. The color value can be set to a [CSS color keyword], or a 3, 4, 6 or 8
+ letter HEX color code, allowing for semi-transparent layers.
+
+ ![Layer background]
+
+Background images are automatically scaled to fit the layer while preserving
+aspect-ratio. Notice how we omitted `size` and `offset`, because we want to
+fill the entire area of the social card.
+
+[Layer background color]: ../assets/screenshots/social-cards-layer-background-color.png
+[Layer background image]: ../assets/screenshots/social-cards-layer-background-image.png
+[Layer background]: ../assets/screenshots/social-cards-layer-background.png
+
+### Typography
+
+Now, we can add dynamic typography that is sourced from Markdown files - this is
+the actual raison d'être of the [built-in social plugin]. [Jinja templates] are
+used to render a text string that is then added to the image:
+
+``` yaml
+size: { width: 1200, height: 630 }
+layers:
+ - size: { width: 832, height: 310 }
+ offset: { x: 62, y: 160 }
+ typography:
+ content: "{{ page.title }}" # (1)!
+ align: start
+ color: white
+ line:
+ amount: 3
+ height: 1.25
+ font:
+ family: Roboto
+ style: Bold
+```
+
+1. The following variables can be used in [Jinja templates]:
+
+ - [`config.*`][config variable]
+ - [`page.*`][page variable]
+ - [`layout.*`][layout options]
+
+ The author is free in defining `layout.*` options, which can be used to pass
+ arbitrary data to the layout from `mkdocs.yml`.
+
+This renders a text layer with the title of the page with a line height of 1.25,
+and a maximum number of 3 lines. The plugin automatically computes the font size
+from the line height, the number of lines, and font metrics like ascender and
+descender.[^2] This renders:
+
+ [^2]:
+ If the plugin would require the author to specify the font size and line
+ height manually, it would be impossible to guarantee that the text fits
+ into the layer. For this reason we implemented a declarative approach,
+ where the author specifies the desired line height and number of lines, and
+ the plugin computes the font size automatically.
+
+![Layer typography]
+
+ [config variable]: https://www.mkdocs.org/dev-guide/themes/#config
+ [page variable]: https://www.mkdocs.org/dev-guide/themes/#page
+ [Layer typography]: ../assets/screenshots/social-cards-layer-typography.png
+
+#### Overflow
+
+If the text overflows the layer, there are two possible behaviors: either the
+text is automatically truncated and shortened with an ellipsis, or the text is
+automatically scaled down to fit the layer:
+
+``` { .markdown .no-copy }
+# If we use a very long headline, we can see how the text will be truncated
+```
+
+=== ":octicons-ellipsis-16: Ellipsis"
+
+ ![Layer typography ellipsis]
+
+=== ":material-arrow-collapse: Shrink"
+
+ ![Layer typography shrink]
+
+While truncating with an ellipsis is the default, auto-shrinking can be enabled
+by setting `overflow` to `shrink`:
+
+``` yaml hl_lines="7"
+size: { width: 1200, height: 630 }
+layers:
+ - size: { width: 832, height: 310 }
+ offset: { x: 62, y: 160 }
+ typography:
+ content: "{{ page.title }}"
+ overflow: shrink
+ align: start
+ color: white
+ line:
+ amount: 3
+ height: 1.25
+ font:
+ family: Roboto
+ style: Bold
+```
+
+ [Layer typography ellipsis]: ../assets/screenshots/social-cards-layer-typography-ellipsis.png
+ [Layer typography shrink]: ../assets/screenshots/social-cards-layer-typography-shrink.png
+
+#### Alignment
+
+Text can be aligned to all corners and edges of the layer. For example, if we
+want to align the text to the middle of the layer, we can set `align` to `start center`, which will render as:
+
+![Layer typography align]
+
+ [Layer typography align]: ../assets/screenshots/social-cards-layer-typography-align.png
+
+The following table shows the supported values:
+
+<figure markdown>
+
+| Alignment | | |
+| -------------- | --------------- | ------------ |
+| :material-arrow-top-left: `start top` | :material-arrow-up: `center top` | :material-arrow-top-right: `end top` |
+| :material-arrow-left: `start center` | :material-circle-small: `center` | :material-arrow-right: `end center` |
+| :material-arrow-bottom-left: `start bottom` | :material-arrow-down: `center bottom` | :material-arrow-bottom-right: `end bottom` |
+
+ <figcaption>
+ Supported values for text alignment
+ </figcaption>
+</figure>
+
+#### Font
+
+The [built-in social plugin] integrates with [Google Fonts] and will
+automatically download the font files for you. The `font` property accepts a
+`family` and `style` property, where the `family` must be set to the name of the
+font, and the `style` to one of the supported font styles. For example, setting
+`family` to `Roboto` will automatically download the following files:
+
+``` { .sh .no-copy #example }
+.cache/plugins/social/fonts
+└─ Roboto/
+ ├─ Black.ttf
+ ├─ Black Italic.ttf
+ ├─ Bold.ttf
+ ├─ Bold Italic.ttf
+ ├─ Italic.ttf
+ ├─ Light.ttf
+ ├─ Light Italic.ttf
+ ├─ Medium.ttf
+ ├─ Medium Italic.ttf
+ ├─ Regular.ttf
+ ├─ Thin.ttf
+ └─ Thin Italic.ttf
+```
+
+In that case, the author can use `Bold` or `Medium Italic` as the `style`. If
+the font style specified in the layer is not part of the font family, the
+font always falls back to `Regular` and prints a warning in [`debug`][debug]
+mode, as `Regular` is included with all font families.
+
+### Icons
+
+Authors can leverage the full range of icons that are shipped with Material for
+MkDocs, or even provide custom icons by using theme extension and going through
+the process described in the guide on [additional icons]. Icons can even be
+tinted by using the `color` property:
+
+``` yaml
+size: { width: 1200, height: 630 }
+layers:
+ - background:
+ color: "#4051b5"
+ - size: { width: 144, height: 144 }
+ offset: { x: 992, y: 64 }
+ icon:
+ value: material/cat
+ color: white
+```
+
+This will render the icon in the top right corner of the social card:
+
+![Layer icon]
+
+The possibilities are endless. For example, icons can be used to draw shapes
+like circles:
+
+``` yaml
+size: { width: 1200, height: 630 }
+layers:
+ - background:
+ color: "#4051b5"
+ - size: { width: 2400, height: 2400 }
+ offset: { x: -1024, y: 64 }
+ icon:
+ value: material/circle
+ color: "#5c6bc0"
+ - size: { width: 1800, height: 1800 }
+ offset: { x: 512, y: -1024 }
+ icon:
+ value: material/circle
+ color: "#3949ab"
+```
+
+This will add two circles to the background:
+
+![Layer icon circles]
+
+### Tags
+
+The new [built-in social plugin] gives full flexibility of the meta tags that
+are added to your site, which are necessary to instruct services like X
+or Discord how to display your social card. All default layouts use the following
+set of tags, which you can copy to your layout and adapt:
+
+``` yaml
+definitions:
+
+ - &page_title_with_site_name >-
+ {%- if not page.is_homepage -%}
+ {{ page.meta.get("title", page.title) }} - {{ config.site_name }}
+ {%- else -%}
+ {{ page.meta.get("title", page.title) }}
+ {%- endif -%}
+
+ - &page_description >-
+ {{ page.meta.get("description", config.site_description) or "" }}
+
+tags:
+
+ og:type: website
+ og:title: *page_title_with_site_name
+ og:description: *page_description
+ og:image: "{{ image.url }}"
+ og:image:type: "{{ image.type }}"
+ og:image:width: "{{ image.width }}"
+ og:image:height: "{{ image.height }}"
+ og:url: "{{ page.canonical_url }}"
+
+ twitter:card: summary_large_image
+ twitter:title: *page_title_with_site_name
+ twitter:description: *page_description
+ twitter:image: "{{ image.url }}"
+```
+
+Note that this example makes use of [YAML anchors] to minify repetition. The
+ `definitions` property is solely intended for the definition on aliases that
+ can then be referenced with anchors.
+
+ [YAML anchors]: https://support.atlassian.com/bitbucket-cloud/docs/yaml-anchors/
+
+__Are you missing something? Please [open a discussion] and let us know!__
+
+ [additional icons]: ./changing-the-logo-and-icons.md#additional-icons
+ [Layer icon]: ../assets/screenshots/social-cards-layer-icon.png
+ [Layer icon circles]: ../assets/screenshots/social-cards-layer-icon-circles.png
+ [open a discussion]: https://github.com/squidfunk/mkdocs-material/discussions/new
diff --git a/documents/markdown/mkdocs-material/setup_setting-up-tags.md b/documents/markdown/mkdocs-material/setup_setting-up-tags.md
new file mode 100644
index 0000000..ce28e55
--- /dev/null
+++ b/documents/markdown/mkdocs-material/setup_setting-up-tags.md
@@ -0,0 +1,310 @@
+# Setting up tags
+
+Material for MkDocs adds first-class support for categorizing pages with tags,
+which adds the possibility to group related pages and make them discoverable
+via search and a dedicated [tags index]. If your documentation is large, tags
+can help to discover relevant information faster.
+
+ [tags index]: #adding-a-tags-index
+
+## Configuration
+
+### Built-in tags plugin
+
+<!-- md:version 8.2.0 -->
+<!-- md:plugin -->
+
+The built-in tags plugin adds the ability to categorize any page with tags
+as part of the front matter of the page. In order to add support for tags, add
+the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - tags
+```
+
+For a list of all settings, please consult the [plugin documentation].
+
+ [plugin documentation]: ../plugins/tags.md
+
+### Tag icons and identifiers
+
+<!-- md:version 8.5.0 -->
+<!-- md:flag experimental -->
+<!-- md:example tags-with-icons -->
+
+Each tag can be associated with an icon, which is then rendered inside the tag.
+Before assigning icons to tags, associate each tag with a unique identifier,
+by adding the following to `mkdocs.yml`:
+
+``` yaml
+extra:
+ tags:
+ <tag>: <identifier> # (1)!
+```
+
+1. The identifier can only include alphanumeric characters, as well as dashes
+ and underscores. For example, if you have a tag `Compatibility`, you can
+ set `compat` as an identifier:
+
+ ``` yaml
+ extra:
+ tags:
+ Compatibility: compat
+ ```
+
+ Identifiers can be reused between tags. Tags which are not explicitly
+ associated will use the default tag icon which is :material-pound:
+
+Next, each identifier can be associated with an icon, even a [custom icon], by
+adding the following lines to `mkdocs.yml` under the `theme.icon` configuration
+setting:
+
+=== "Tag icon"
+
+ ``` yaml
+ theme:
+ icon:
+ tag:
+ <identifier>: <icon> # (1)!
+ ```
+
+ 1. Enter a few keywords to find the perfect icon using our [icon search] and
+ click on the shortcode to copy it to your clipboard:
+
+ <div class="mdx-iconsearch" data-mdx-component="iconsearch">
+ <input class="md-input md-input--stretch mdx-iconsearch__input" placeholder="Search icon" data-mdx-component="iconsearch-query" value="tag" />
+ <div class="mdx-iconsearch-result" data-mdx-component="iconsearch-result" data-mdx-mode="file">
+ <div class="mdx-iconsearch-result__meta"></div>
+ <ol class="mdx-iconsearch-result__list"></ol>
+ </div>
+ </div>
+
+=== "Tag default icon"
+
+ ``` yaml
+ theme:
+ icon:
+ tag:
+ default: <icon>
+ ```
+
+??? example "Expand to inspect example"
+
+ ``` yaml
+ theme:
+ icon:
+ tag:
+ html: fontawesome/brands/html5
+ js: fontawesome/brands/js
+ css: fontawesome/brands/css3
+ extra:
+ tags:
+ HTML5: html
+ JavaScript: js
+ CSS: css
+ ```
+
+ [custom icon]: changing-the-logo-and-icons.md#additional-icons
+ [icon search]: ../reference/icons-emojis.md#search
+
+## Usage
+
+### Adding tags
+
+<!-- md:version 8.2.0 -->
+<!-- md:example tags -->
+
+When the [built-in tags plugin] is enabled, tags can be added for a document
+with the front matter `tags` property. Add the following lines at the top of a
+Markdown file:
+
+``` sh
+---
+tags:
+ - HTML5
+ - JavaScript
+ - CSS
+---
+
+...
+```
+
+The page will now render with those tags above the main headline and within the
+search preview, which now allows to __find pages by tags__.
+
+??? question "How to set tags for an entire folder?"
+
+ With the help of the [built-in meta plugin], you can ensure that tags are
+ set for an entire section and all nested pages, by creating a `.meta.yml`
+ file in the corresponding folder with the following content:
+
+ ``` yaml
+ tags:
+ - HTML5
+ - JavaScript
+ - CSS
+ ```
+
+ The tags set in `.meta.yml` are merged and deduplicated with the tags
+ defined for a page, which means you can define common tags in `.meta.yml`
+ and then add specific tags for each page. The tags in `.meta.yml` are
+ appended.
+
+ [built-in tags plugin]: ../plugins/tags.md
+ [built-in meta plugin]: ../plugins/meta.md
+
+### Adding a tags index
+
+<!-- md:version 8.2.0 -->
+<!-- md:example tags -->
+
+The [built-in tags plugin] allows to define a file to render a tags index,
+which can be any page that is part of the `nav` section. To add a tags index,
+create a page, e.g. `tags.md`:
+
+``` markdown
+# Tags
+
+Following is a list of relevant tags:
+
+<!-- material/tags -->
+```
+
+The tags marker specifies the position of the tags index, i.e. it is
+replaced with the actual tags index when the page is rendered. You can include
+arbitrary content before and after the marker:
+
+[![Tags index][tags index enabled]][tags index enabled]
+
+ [tags index enabled]: ../assets/screenshots/tags-index.png
+
+### Advanced features
+
+#### Configurable listings
+
+<!-- md:version 9.6.0 -->
+<!-- md:flag experimental -->
+
+Listings can be configured in `mkdocs.yml` or directly at the location of the
+marker that you position in a Markdown document. Some examples:
+
+- __Use [scoped listings]__: limit the tags index to pages that are on the same
+ level of the subsection of the documentation the page is in:
+
+ ``` html
+ <!-- material/tags { scope: true } -->
+ ```
+
+- __List only specific tags__: limit the tags index to a single or multiple
+ selected tags, e.g., `Foo` and `Bar`, excluding all other tags:
+
+ ``` html
+ <!-- material/tags { include: [Foo, Bar] } -->
+ ```
+
+- __Exclude pages with specific tags__: don't include pages that are tagged
+ with specific tags, e.g. `Internal`. This can be any tag, including a shadow
+ tag:
+
+ ``` html
+ <!-- material/tags { exclude: [Internal] } -->
+ ```
+
+- __Enable or disable tags inside the table of contents__: specify whether the
+ table of contents lists all tags under the nearest headline:
+
+ ``` html
+ <!-- material/tags { toc: false } -->
+ ```
+
+See the [listing configuration] for all options.
+
+ [listing configuration]: ../plugins/tags.md#listing-configuration
+
+#### Scoped listings
+
+<!-- md:version 9.7.0 -->
+<!-- md:flag experimental -->
+
+If your documentation is large, you might want to consider using scoped listings
+which will only include pages that are on the same level or below the page
+containing the listing. Just use:
+
+``` html
+<!-- material/tags { scope: true } -->
+```
+
+If you plan to use multiple scoped indexes, it's a good idea to define a
+listing configuration in `mkdocs.yml`, which you can then reference by its id:
+
+``` yaml
+plugins:
+ - tags:
+ listings_map:
+ scoped:
+ scope: true
+```
+
+You can now use:
+
+``` html
+<!-- material/tags scoped -->
+```
+
+#### Shadow tags
+
+<!-- md:version 9.7.0 -->
+<!-- md:flag experimental -->
+
+Shadow tags are tags that are solely meant to organization, which can be
+included or excluded for rendering with a simple flag. They can be enumerated
+in the [`shadow_tags`][config.shadow_tags] setting:
+
+``` yaml
+plugins:
+ - tags:
+ shadow_tags:
+ - Draft
+ - Internal
+```
+
+If a document is tagged with `Draft`, the tag will only be rendered if
+[`shadow`][config.shadow] setting is enabled, and excluded when it is disabled.
+This is an excellent opportunity for using tags for structuring.
+
+ [config.shadow]: ../plugins/tags.md#config.shadow
+ [config.shadow_tags]: ../plugins/tags.md#config.shadow_tags
+
+#### Nested tags
+
+<!-- md:version 9.7.0 -->
+<!-- md:flag experimental -->
+
+The [`tags_hierarchy_separator`][config.tags_hierarchy_separator] allows to
+create hierarchies of tags, e.g., `Foo/Bar`. Nested tags will be rendered as
+children of the parent tag:
+
+``` yaml
+plugins:
+ - tags:
+ tags_hierarchy: true
+```
+
+ [config.tags_hierarchy_separator]: ../plugins/tags.md#config.tags_hierarchy_separator
+
+### Hiding tags on a page
+
+While the tags are rendered above the main headline, sometimes, it might be
+desirable to hide them for a specific page, which can be achieved with the
+front matter `hide` property:
+
+``` yaml
+---
+hide:
+ - tags
+---
+
+# Page title
+...
+```
diff --git a/documents/markdown/mkdocs-material/setup_setting-up-the-footer.md b/documents/markdown/mkdocs-material/setup_setting-up-the-footer.md
new file mode 100644
index 0000000..2d45ae4
--- /dev/null
+++ b/documents/markdown/mkdocs-material/setup_setting-up-the-footer.md
@@ -0,0 +1,182 @@
+# Setting up the footer
+
+The footer of your project documentation is a great place to add links to
+websites or platforms you or your company are using as additional marketing
+channels, e.g. :fontawesome-brands-mastodon:{ style="color: #5A4CE0" } or
+:fontawesome-brands-youtube:{ style="color: #EE0F0F" }, which you can easily
+configure via `mkdocs.yml`.
+
+## Configuration
+
+### Navigation
+
+<!-- md:version 9.0.0 -->
+<!-- md:feature -->
+
+The footer can include links to the previous and next page of the current page.
+If you wish to enable this behavior, add the following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - navigation.footer
+```
+
+### Social links
+
+<!-- md:version 1.0.0 -->
+<!-- md:default none -->
+
+Social links are rendered next to the copyright notice as part of the
+footer of your project documentation. Add a list of social links in `mkdocs.yml`
+with:
+
+``` yaml
+extra:
+ social:
+ - icon: fontawesome/brands/mastodon # (1)!
+ link: https://fosstodon.org/@squidfunk
+```
+
+1. Enter a few keywords to find the perfect icon using our [icon search] and
+ click on the shortcode to copy it to your clipboard:
+
+ <div class="mdx-iconsearch" data-mdx-component="iconsearch">
+ <input class="md-input md-input--stretch mdx-iconsearch__input" placeholder="Search icon" data-mdx-component="iconsearch-query" value="mastodon" />
+ <div class="mdx-iconsearch-result" data-mdx-component="iconsearch-result" data-mdx-mode="file">
+ <div class="mdx-iconsearch-result__meta"></div>
+ <ol class="mdx-iconsearch-result__list"></ol>
+ </div>
+ </div>
+
+The following properties are available for each link:
+
+<!-- md:option social.icon -->
+
+: <!-- md:default none --> <!-- md:flag required -->
+ This property must contain a valid path to any icon bundled with the theme,
+ or the build will not succeed. Some popular choices:
+
+ * :fontawesome-brands-github: – `fontawesome/brands/github`
+ * :fontawesome-brands-gitlab: – `fontawesome/brands/gitlab`
+ * :fontawesome-brands-x-twitter: – `fontawesome/brands/x-twitter`
+ * :fontawesome-brands-mastodon: – `fontawesome/brands/mastodon`
+ <small>automatically adds [`rel=me`][rel=me]</small>
+ * :fontawesome-brands-docker: – `fontawesome/brands/docker`
+ * :fontawesome-brands-facebook: – `fontawesome/brands/facebook`
+ * :fontawesome-brands-instagram: – `fontawesome/brands/instagram`
+ * :fontawesome-brands-linkedin: – `fontawesome/brands/linkedin`
+ * :fontawesome-brands-slack: – `fontawesome/brands/slack`
+ * :fontawesome-brands-discord: – `fontawesome/brands/discord`
+ * :fontawesome-brands-pied-piper-alt: – `fontawesome/brands/pied-piper-alt`
+
+<!-- md:option social.link -->
+
+: <!-- md:default none --> <!-- md:flag required -->
+ This property must be set to a relative or absolute URL including the URI
+ scheme. All URI schemes are supported, including `mailto` and `bitcoin`:
+
+ === ":fontawesome-brands-mastodon: Mastodon"
+
+ ``` yaml
+ extra:
+ social:
+ - icon: fontawesome/brands/mastodon
+ link: https://fosstodon.org/@squidfunk
+ ```
+
+ === ":octicons-mail-16: Email"
+
+ ``` yaml
+ extra:
+ social:
+ - icon: fontawesome/solid/paper-plane
+ link: mailto:<email-address>
+ ```
+
+<!-- md:option social.name -->
+
+: <!-- md:default _domain name from_ `link`_, if available_ -->
+ This property is used as the link's `title` attribute and can be set to a
+ discernable name to improve accessibility:
+
+ ``` yaml
+ extra:
+ social:
+ - icon: fontawesome/brands/mastodon
+ link: https://fosstodon.org/@squidfunk
+ name: squidfunk on Fosstodon
+ ```
+
+ [icon search]: ../reference/icons-emojis.md#search
+ [rel=me]: https://docs.joinmastodon.org/user/profile/#verification
+
+### Copyright notice
+
+<!-- md:version 0.1.0 -->
+<!-- md:default none -->
+
+A custom copyright banner can be rendered as part of the footer, which is
+displayed next to the social links. It can be defined as part of `mkdocs.yml`:
+
+``` yaml
+copyright: Copyright © 2016 - 2020 Martin Donath
+```
+
+### Generator notice
+
+<!-- md:version 7.3.0 -->
+<!-- md:default `true` -->
+
+The footer displays a _Made with Material for MkDocs_ notice to denote how
+the site was generated. The notice can be removed with the following option
+via `mkdocs.yml`:
+
+``` yaml
+extra:
+ generator: false
+```
+
+!!! info "Please read this before removing the generator notice"
+
+ The subtle __Made with Material for MkDocs__ hint in the footer is one of
+ the reasons why this project is so popular, as it tells the user how the
+ site is generated, helping new users to discover this project. Before
+ removing please consider that you're enjoying the benefits of @squidfunk's
+ work for free, as this project is Open Source and has a permissive license.
+ Thousands of hours went into this project, most of them
+ without any financial return.
+
+## Usage
+
+### Hiding prev/next links
+
+The footer navigation showing links to the previous and next page can be hidden
+with the front matter `hide` property. Add the following lines at the top of a
+Markdown file:
+
+``` yaml
+---
+hide:
+ - footer
+---
+
+# Page title
+...
+```
+
+## Customization
+
+### Custom copyright
+
+<!-- md:version 8.0.0 -->
+<!-- md:flag customization -->
+
+In order to customize and override the [copyright notice], [extend the theme]
+and [override the `copyright.html` partial][overriding partials], which normally
+includes the `copyright` property set in `mkdocs.yml`.
+
+ [copyright notice]: #copyright-notice
+ [generator notice]: #generator-notice
+ [extend the theme]: ../customization.md#extending-the-theme
+ [overriding partials]: ../customization.md#overriding-partials
diff --git a/documents/markdown/mkdocs-material/setup_setting-up-the-header.md b/documents/markdown/mkdocs-material/setup_setting-up-the-header.md
new file mode 100644
index 0000000..d9e7d21
--- /dev/null
+++ b/documents/markdown/mkdocs-material/setup_setting-up-the-header.md
@@ -0,0 +1,68 @@
+# Setting up the header
+
+Material for MkDocs' header can be customized to show an announcement bar that
+disappears upon scrolling, and provides some options for further configuration.
+It also includes the [search bar] and a place to display your project's
+[git repository], as explained in those dedicated guides.
+
+ [search bar]: setting-up-site-search.md
+ [git repository]: adding-a-git-repository.md
+
+## Configuration
+
+### Automatic hiding
+
+<!-- md:version 6.2.0 -->
+<!-- md:feature -->
+
+When autohiding is enabled, the header is automatically hidden when the
+user scrolls past a certain threshold, leaving more space for content. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - header.autohide
+```
+
+### Announcement bar
+
+<!-- md:version 5.0.0 -->
+<!-- md:flag customization -->
+
+Material for MkDocs includes an announcement bar, which is the perfect place to
+display project news or other important information to the user. When the user
+scrolls past the header, the bar will automatically disappear. In order to add
+an announcement bar, [extend the theme] and [override the `announce`
+block][overriding blocks], which is empty by default:
+
+``` html
+{% extends "base.html" %}
+
+{% block announce %}
+ <!-- Add announcement here, including arbitrary HTML -->
+{% endblock %}
+```
+
+ [extend the theme]: ../customization.md#extending-the-theme
+ [overriding blocks]: ../customization.md#overriding-blocks
+
+#### Mark as read
+
+<!-- md:version 8.4.0 -->
+<!-- md:feature -->
+<!-- md:flag experimental -->
+
+In order to render temporary announcements that can be marked as read by the
+user, a button to dismiss the current announcement can be included. Add the
+following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - announce.dismiss
+```
+
+When the user clicks the button, the current announcement is dismissed and not
+displayed again until the content of the announcement changes. This is handled
+automatically.
diff --git a/documents/markdown/mkdocs-material/setup_setting-up-versioning.md b/documents/markdown/mkdocs-material/setup_setting-up-versioning.md
new file mode 100644
index 0000000..7d62a3b
--- /dev/null
+++ b/documents/markdown/mkdocs-material/setup_setting-up-versioning.md
@@ -0,0 +1,189 @@
+# Setting up versioning
+
+Material for MkDocs makes it easy to deploy multiple versions of your project
+documentation by integrating with external utilities that add those capabilities
+to MkDocs, i.e. [mike]. When deploying a new version, older versions of your
+documentation remain untouched.
+
+ [mike]: https://github.com/jimporter/mike
+
+## Configuration
+
+### Versioning
+
+<!-- md:version 7.0.0 -->
+<!-- md:utility [mike] -->
+<!-- md:demo example-versioning -->
+
+[mike] makes it easy to deploy multiple versions of your project documentation.
+It integrates natively with Material for MkDocs and can be enabled via
+`mkdocs.yml`:
+
+``` yaml
+extra:
+ version:
+ provider: mike
+```
+
+This renders a version selector in the header:
+
+<figure markdown>
+
+[![Version selector preview]][Version selector preview]
+
+ <figcaption markdown>
+
+Check out the versioning example to see it in action –
+[mkdocs-material.github.io/example-versioning][version example]
+
+ </figcaption>
+</figure>
+
+!!! quote "[Why use mike?]"
+
+ mike is built around the idea that once you've generated your docs for a
+ particular version, you should never need to touch that version again. This
+ means you never have to worry about breaking changes in MkDocs, since your
+ old docs (built with an old version of MkDocs) are already generated and
+ sitting in your `gh-pages` branch.
+
+ While mike is flexible, it's optimized around putting your docs in a
+ `<major>.<minor>` directory, with optional aliases (e.g. `latest` or `dev`)
+ to particularly notable versions. This makes it easy to make permalinks to
+ whatever version of the documentation you want to direct people to.
+
+ [Version selector preview]: ../assets/screenshots/versioning.png
+ [version example]: https://mkdocs-material.github.io/example-versioning/
+ [Why use mike?]: https://github.com/jimporter/mike#why-use-mike
+
+### Stay on the same page when switching versions
+
+When the user chooses a version in the version selector, they usually want to go
+to the page corresponding to the page they were previously viewing. Material for
+MkDocs implements this behavior by default, but there are a few caveats:
+
+- the [`site_url`][mkdocs.site_url] must be set correctly in `mkdocs.yml`.
+ See the ["Publishing a new version"](#publishing-a-new-version) section for
+ an example.
+- the redirect happens via JavaScript and there is no way to know which page you
+ will be redirected to ahead of time.
+
+### Version warning
+
+<!-- md:version 8.0.0 -->
+<!-- md:flag customization -->
+
+If you're using versioning, you might want to display a warning when the user
+visits any other version than the latest version. Using [theme extension],
+you can [override the `outdated` block][overriding blocks]:
+
+``` html
+{% extends "base.html" %}
+
+{% block outdated %}
+ You're not viewing the latest version.
+ <a href="{{ '../' ~ base_url }}"> <!-- (1)! -->
+ <strong>Click here to go to latest.</strong>
+ </a>
+{% endblock %}
+```
+
+1. Given this value for the `href` attribute, the link will always redirect to
+ the root of your site, which will then redirect to the latest version. This
+ ensures that older versions of your site do not depend on a specific alias,
+ e.g. `latest`, to allow for changing the alias later on without breaking
+ earlier versions.
+
+This will render a version warning above the header:
+
+[![Version warning preview]][Version warning preview]
+
+The default version is identified by the `latest` alias. If you wish to set
+another alias as the latest version, e.g. `stable`, add the following lines
+to `mkdocs.yml`:
+
+``` yaml
+extra:
+ version:
+ default: stable # (1)!
+```
+
+1. You can also define multiple aliases as the default version, e.g. `stable`
+ and `development`.
+
+ ``` yaml
+ extra:
+ version:
+ default:
+ - stable
+ - development
+ ```
+
+ Now every version that has the `stable` and `development` aliases will not
+ display the version warning.
+
+Make sure one alias matches the [default version], as this is where users are
+redirected to.
+
+ [theme extension]: ../customization.md#extending-the-theme
+ [overriding blocks]: ../customization.md#overriding-blocks
+ [Version warning preview]: ../assets/screenshots/version-warning.png
+ [default version]: #setting-a-default-version
+
+### Version alias
+
+<!-- md:version 9.5.23 -->
+<!-- md:default `false` -->
+
+If you're using aliases for versioning, and want to show the version alias
+besides the version number, you can enable this feature by setting the `alias`
+option to `true`:
+
+``` yaml
+extra:
+ version:
+ alias: true
+```
+
+## Usage
+
+While this section outlines the basic workflow for publishing new versions,
+it's best to check out [mike's documentation][mike] to make yourself familiar
+with its mechanics.
+
+### Publishing a new version
+
+If you want to publish a new version of your project documentation, choose a
+version identifier and update the alias set as the default version with:
+
+```
+mike deploy --push --update-aliases 0.1 latest
+```
+
+Note that every version will be deployed as a subdirectory of your `site_url`,
+which you should set explicitly. For example, if your `mkdocs.yml` contains:
+
+``` yaml
+site_url: 'https://docs.example.com/' # Trailing slash is recommended
+```
+
+the documentation will be published to URLs such as:
+
+- _docs.example.com/0.1/_
+- _docs.example.com/0.2/_
+- ...
+
+### Setting a default version
+
+When starting with [mike], a good idea is to set an alias as a default version,
+e.g. `latest`, and when publishing a new version, always update the alias to
+point to the latest version:
+
+```
+mike set-default --push latest
+```
+
+When publishing a new version, [mike] will create a redirect in the root of
+your project documentation to the version associated with the alias:
+
+_docs.example.com_ :octicons-arrow-right-24: _docs.example.com/0.1_
diff --git a/documents/markdown/mkdocs-material/tutorials_blogs_basic.md b/documents/markdown/mkdocs-material/tutorials_blogs_basic.md
new file mode 100644
index 0000000..507ff75
--- /dev/null
+++ b/documents/markdown/mkdocs-material/tutorials_blogs_basic.md
@@ -0,0 +1,373 @@
+# Basic blogs
+
+Blogs are a great way to engage with your audience. Software developers can use
+a blog to announce new features, demonstrate their usage and provide background
+information. You can demonstrate competence by commenting on the state of the
+art or document your own work as best practice. Posts on current topics can help
+draw in visitors for your main website and can keep your audience engaged. Of
+course, you can blog about any topics close to your heart.
+
+The [blog plugin] makes running a blog alongside your other content easy but you
+can also configure it to run a stand-alone blog if posts are the only kind
+of content you need.
+
+After a brief overview of the basic concepts of a blog, this tutorial guides you
+through the process of configuring the [blog plugin], setting up your blog,
+creating posts, and defining post metadata.
+
+[blog plugin]: ../../plugins/blog.md
+
+__Time required:__ typically 20 minutes
+
+## Key concepts
+
+**Post, excerpt**: a blog consists of a number of self-contained _posts_ (often called
+articles) and an index page that shows the posts in reverse chronological order, with
+the most recent post at the top. The index page usually shows only a short _excerpt_ and a
+link that the user can click to navigate to the full post.
+
+**Metadata**: both the index page and the post itself list information such as
+when you published the post, when you updated it, who the author is, and what the
+expected reading time is.
+
+**Slug**: since the blog posts are primarily arranged by time and not into a hierarchy,
+their URLs do not reflect such a structure. Instead, each post's URL
+contains a shortened description, the _slug_, which is usually derived from
+the first heading in the post.
+
+**Navigation**: the main navigation structure is the timeline, which you can
+subdivide into _categories_. The main index page shows the more recent posts
+while an _archive_ section allows access to older ones, organized by year.
+In addition, posts can be _tagged_ and _tag index pages_ provide an additional
+navigation structure based on content.
+
+You can see all these elements on the [Material for MkDocs blog].
+
+[Material for MkDocs blog]: https://squidfunk.github.io/mkdocs-material/blog/
+
+## Setting up your blog
+
+The blog plugin is part of Material for MkDocs but you need to configure it
+in the `mkdocs.yml`.
+
+!!! example "Set up a blog"
+
+ If you have not done so already, create a project for your blog,
+ then edit the `mkdocs.yml` file to make sure it has the following content:
+
+ ```yaml
+ site_name: Blog Tutorial
+ site_description: an example blog set up following the tutorial
+ site_url: http://www.example.com
+
+ theme:
+ name: material
+
+ plugins:
+ - search
+ - blog
+ ```
+
+ The blog plugin will create a directory structure for your blog posts if it
+ does not exist, so simply run `mkdocs serve` to get:
+
+ ```
+ docs
+ ├── blog
+ │ ├── index.md
+ │ └── posts
+ └── index.md
+ ```
+
+Now create your first blog post in `docs/blog/posts`. You can use any
+naming convention and directory structure you like for your posts, as long as
+they are inside `docs/blog/posts`.
+
+Each post _must_ have a page header, which appears at the top of the Markdown
+code between lines with three dashes. Within this header, you need to have at
+least a `date` entry but you can add other data, as you will see below.
+Following the header comes the page content. Note that it is important
+to have a level one heading as the plugin uses it to produce the _slug_. Also,
+by adding `<!-- more -->` to the page, you can define where the excerpt will end
+that the index page shows.
+
+!!! example "Write your first post"
+
+ Create a file `docs/blog/posts/myfirst.md` with the following contents:
+
+ ```
+ ---
+ date:
+ created: 2023-12-31
+ ---
+
+ # Happy new years eve!
+
+ We hope you are all having fun and wish you all the best for the new year!
+ <!-- more -->
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+ tempor incididunt ut labore et dolore magna aliqua.
+ ```
+
+ Then, run `mkdocs serve` and point your web browser at
+ `http://localhost:8000/blog`.
+
+ The blog plugin automatically creates navigation elements for
+ the blog. The index page shows only the extract. When you select the
+ "Continue reading" link, you will get to the full blog post. Note how it
+ has a URL generated from the first-level heading.
+
+!!! tip "Navigation"
+
+ We also have a [tutorial on navigation] that shows you how to change the
+ automatically created navigation and integrate the blog into your existing
+ navigation structure. It shows how to create secondary navigation, produce
+ author pages, and control pagination.
+
+[tutorial on navigation]: navigation.md
+
+## Post metadata
+
+In addition to the date, you can provide other metadata and give the plugin
+instructions, such as to treat a post as a draft or to pin it.
+
+### Drafts
+
+You may want to produce a draft of a blog post and work with it locally but
+exclude it from the build that you publish. Simply add a field to the page
+header to indicate that a post is still in draft form.
+
+!!! example "Create a draft"
+
+ Create a second blog post in `docs/blogs/posts/draft.md` with the following
+ contents:
+
+ ```hl_lines="4"
+ ---
+ date:
+ created: 2024-01-01
+ draft: true
+ ---
+
+ # Happy new year!
+
+ Happy 2024 to everyone. Wishing you all the best!
+ <!-- more -->
+
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+ tempor incididunt ut labore et dolore magna aliqua.
+ ```
+
+ Now, note how the draft appears on the index page but with a label that
+ indicates that it is a draft. When you run `mkdocs build`, the draft will
+ _not_ appear in the output:
+
+ ```
+ $ mkdocs build
+ $ ls site/blog
+ site/blog
+ ├── 2023
+ │ └── 12
+ │ └── 31
+ │ └── happy-new-years-eve
+ │ └── index.html
+ ...
+ ```
+
+ The first blog post for 2024 is not there yet because it is still in draft
+ stage. Remember to remove the `draft` setting in the header when it is time
+ to publish it.
+
+You can also create a folder to keep your drafts in and use the [Meta plugin]
+to add the `draft` header setting to all the posts in that folder. This has the
+advantage that it is easier to see which posts are still in draft form. We will
+cover the Meta plugin later on.
+
+[Meta plugin]: ../../plugins/meta.md
+
+### Edits
+
+Sometimes, bloggers need to update a post. This might happen when you make
+a mistake or when something changes that you need to reflect in the post. To
+indicate you have edited a post, you can include an `updated` date in the page
+header.
+
+!!! example "Editing a post"
+
+ Make a change to your first blog post, then add an edit date to the header:
+
+ ```hl_lines="3 4"
+ ---
+ date:
+ created: 2023-12-31
+ updated: 2024-01-02
+ ---
+ ```
+
+The Metadata section of the blog post itself will contain the edit date,
+though the index page omits this detail by default.
+
+### Reading time
+
+To give the reader some idea of how long it might take them to read a post,
+a read time is automatically calculated. If you want to override this, you can
+do so in the page header by specifying the number of minutes you estimate
+your readers will take the read the post.
+
+!!! example "Overriding the reading time"
+
+ Add a reading time override to your first blog post:
+
+ ```hl_lines="5"
+ ---
+ date:
+ created: 2023-12-31
+ updated: 2024-01-02
+ readtime: 15
+ ---
+ ```
+
+### Pinning
+
+Sometimes, blog authors want to 'pin' a specific post so that it will always
+appear at the top of the index page, no matter what else gets published. You can
+achieve this by adding the `pin` attribute in the page header:
+
+!!! example "Pin a post"
+
+ Add the `pin` attribute to your first blog post:
+
+ ```hl_lines="6"
+ ---
+ date:
+ created: 2023-12-31
+ updated: 2024-01-02
+ readtime: 15
+ pin: true
+ ---
+ ```
+
+ Observe how this makes the post appear on top of the index page even though
+ its publication date is prior to other posts. A small pin icon shows that the
+ post has been pinned.
+
+### Related links
+
+When your blog is part of a wider site such as technical documentation, you
+will want to provide links from blog posts into your other content. One way you
+can do this is to have a related links section. The blog plugin can create one
+for you if you provide link targets in your page header:
+
+!!! example "Add a related links section"
+
+ Add the following to a blog post:
+
+ ``` hl_lines="5-7"
+ ---
+ date:
+ created: 2023-12-31
+ ...
+ links:
+ - index.md
+ - blog/index.md
+ ---
+ ```
+
+ The related links appear underneath the Metadata section.
+
+The nice thing here is that you do not need to provide a page title. The plugin
+will deduce the link text by applying the same logic that MkDocs uses for the
+main navigation. In fact, the syntax is the same as that of the `nav` section
+in the `mkdocs.yml`, so you can override the title if you want and even define
+subsections:
+
+!!! example "Override the page titles"
+
+ Change the link section to override the page titles:
+
+ ```hl_lines="6-9"
+ ---
+ date:
+ created: 2023-12-31
+ ...
+ links:
+ - Homepage: index.md
+ - Blog index: blog/index.md
+ - External links:
+ - Material documentation: https://squidfunk.github.io/mkdocs-material
+ ---
+ ```
+
+The plugin renders related links in the left sidebar on screens that are wide
+enough and at the bottom of the post on narrow screens. Change the size of your
+browser window to see this in action.
+
+## Meta plugin
+
+The Meta plugin helps simplify the management of metadata that is common to a
+group of files in the same subdirectory. Instead of having to repeat the same
+metadata in the page headers of a number of files, you can add a `.meta.yml`
+file in the directory and the Meta plugin will merge its contents into the
+headers of all the pages contained. Settings from the page header take
+precedence, so you can always override settings by adding them to a post's
+header.
+
+For example, you may want to manage drafts by keeping them in a directory
+together so that they are not only flagged as drafts but also easier to find.
+(Otherwise, you would need to inspect the page headers or trace back from the
+output to the files to figure out which posts are drafts.)
+
+!!! example "Drafts using the Meta plugin"
+
+ You first need to activate the plugin in your `mkdocs.yaml`:
+
+ ```yaml hl_lines="4"
+ plugins:
+ - search
+ - blog
+ - meta
+ ```
+
+ Now create the folder for the drafts:
+
+ === "MacOS/Linux"
+
+ ```bash
+ $ mkdir docs/blog/posts/drafts
+ ```
+
+ === "Windows"
+ ```powershell
+ $ mkdir docs\blog\posts\drafts
+ ```
+
+ Now, within this folder, crate a file `.meta.yml` that contains:
+
+ ```yaml
+ draft: true
+ ```
+
+ Add another blog post and store it in `docs/blog/posts/drafts`. When you
+ look at it locally, you will see the label that identifies it as a draft,
+ while in the version built for publication it does not appear. To move a
+ post from draft status to published, simply move it outside `drafts/`.
+
+[meta]: ../../plugins/meta.md
+
+## What's next?
+
+You should now have a working blog. However, as it accumulates content, you
+may want to make sure that people can find posts they are interested in, so
+you may want to add secondary navigation with tags and categories. You may
+have more than one author and want to attribute posts to them as well as
+generate author pages for them. We have a [tutorial on navigation, pagination,
+and authors] that covers these topics.
+
+[tutorial on navigation, pagination, and authors]: navigation.md
+
+You may want to increase engagement with your blog by allowing people to
+subscribe to an RSS feed or by setting up a comment system. The [engagement
+and dissemination tutorial] walks you through setting these up.
+
+[engagement and dissemination tutorial]: engage.md
diff --git a/documents/markdown/mkdocs-material/tutorials_blogs_engage.md b/documents/markdown/mkdocs-material/tutorials_blogs_engage.md
new file mode 100644
index 0000000..90b4248
--- /dev/null
+++ b/documents/markdown/mkdocs-material/tutorials_blogs_engage.md
@@ -0,0 +1,369 @@
+# Engagement and dissemination
+
+You can foster reader engagement and improve the dissemination of content
+on your blog by providing an RSS feed that people can subscribe to and by
+integrating a discussion system. To learn more about who is or is not reading
+your posts, you may want to integrate an analytics system. You may also want
+to post on social media when you publish a new blog post. This tutorial gives
+you a leg up on all of these topics.
+
+__Time required:__ typically 30 minutes
+
+## RSS feeds
+
+An _RSS feed_ allows users to subscribe to a blog so that they get notified when
+you publish new posts. RSS Feed readers are often used to access blogs that a
+user follows. They usually support downloading the blog content for offline
+consumption.
+
+An easy way to create an RSS feed for your blog is to use the
+[MkDocs RSS Plugin], which is well integrated with Material for MkDocs.
+Since it is a third-party plugin, you need to install it before using it.
+
+[MkDocs RSS Plugin]: https://guts.github.io/mkdocs-rss-plugin
+
+
+!!! example "Add an RSS feed"
+
+ Install the RSS plugin into your project:
+
+ ```
+ $ pip install mkdocs-rss-plugin
+ ```
+
+ It is important that have the `site_name`, `site_description` and
+ `site_url` settings configured as [instructed in the basic blog tutorial].
+ The RSS plugin makes use of this information to construct the feed, so make
+ sure you have configured them.
+
+ [instructed in the basic blog tutorial]: basic.md#setting-up-your-blog
+
+ Now, configure the plugin in the `mkdocs.yml`. The options provided restrict
+ the pages that RSS entries are created for to the blog posts, which is
+ probably what you want. Also note the configuration of the date fields to
+ match the format that Material for MkDocs uses to accommodate both a
+ creation date and a date for updates.
+
+ ```yaml hl_lines="9"
+ plugins:
+ - ...
+ - rss:
+ match_path: "blog/posts/.*"
+ date_from_meta:
+ as_creation: date.created
+ as_update: date.updated
+ ```
+
+ Have a look at http://localhost:8000/feed_rss_created.xml to see the RSS
+ feed in all its XML glory. You can use a browser like Firefox or Chrome that
+ can display the raw RSS feed or use `curl` to get the feed and `xmllint` to
+ format it. (You may need to install these tools.)
+
+ ```
+ curl -s http://localhost:8000/feed_rss_created.xml | xmllint --format -
+ ```
+
+ You may also want to try your feed with a feed reader. There are various desktop
+ and mobile apps as well as online services. Of course, to use the latter you
+ will need to deploy your project somewhere that is accessible to them.
+
+This minimal configuration should work well if you have not made any changes
+to the default configuration of the blog plugin. For more information on adapting
+the feed to your needs, see [the RSS plugin's documentation].
+
+[the RSS plugin's documentation]: https://guts.github.io/mkdocs-rss-plugin/
+
+## Social media buttons
+
+Social media buttons can serve two purposes: to allow your readers to navigate
+to your social media profiles or to share content you have published via their
+own accounts.
+
+### Profile links
+
+Links to social media profiles a usually provided in the footer of pages and
+Material for MkDocs makes this easy. All you need to do is to provide the
+necessary links and define the icons to use.
+
+!!! example "Adding social media profile links"
+
+ Add an `extra` section to your `mkdocs.yml` and, within it, a `social`
+ section to contain a list of link definitions. These consist of the logo
+ to use and the link to the profile.
+
+ ```yaml
+ extra:
+ social:
+ - icon: fontawesome/brands/mastodon
+ name: squidfunk on Mastodon
+ link: https://fosstodon.org/@squidfunk
+ ```
+
+ For the `icon`, you can choose any valid path to an icon bundled with the
+ theme. The `name` will be used as the title attribute for the icon and
+ including this improves accessibility.
+ For popular social media systems, the link needs to be absolute and
+ needs to include the scheme, most likely `https://`.
+
+ You can also use other schemes. For example, to create an icon that allows
+ people to create an email, add this:
+
+ ```yaml
+ extra:
+ social:
+ - icon: /fontawesome/regular/envelope
+ name: send me an email
+ link: mailto:<email-address>
+ ```
+
+ Finally, you can specify a URL within your site, such as to your contact
+ page. It is possible to specify only the path to the page:
+
+ ```yaml
+ extra:
+ social:
+ - icon: /material/mailbox
+ name: contact us
+ link: /contact
+ ```
+
+### Share and like buttons
+
+Adding buttons that let people share your content on social media is a bit
+more involved, which is why there are companies offering components for this.
+
+
+!!! tip "Data Protection"
+
+ "Share" and "Like" buttons that use integrations provided by social media
+ companies often leave copious data traces even when the user does not
+ interact with these buttons. If you choose to integrate such feature on
+ your site please be aware of the data protection implications and your
+ duties as a provider to ensure that processing occurs only once the user
+ has granted consent.
+
+This implementation of share buttons deliberately does not use third party code.
+It supports sharing to Twitter/X and Facebook without causing a data flow to
+these companies whenever someone views the pages. Only when someone clicks a
+share button will there be interactions with those companies' servers.
+
+!!! example "Add share buttons"
+
+ In order to add the share buttons, you can add a hook that appends buttons
+ for sharing the current page.
+
+ Create a directory `hooks` in your project root and configure it
+ in your `mkdocs.yml`:
+
+ ```yaml
+ hooks:
+ - hooks/socialmedia.py
+ ```
+
+ Add the file `hooks/socialmedia.py` with the following Python code:
+
+ ```python
+ from textwrap import dedent
+ import urllib.parse
+ import re
+
+ x_intent = "https://x.com/intent/tweet"
+ fb_sharer = "https://www.facebook.com/sharer/sharer.php"
+ include = re.compile(r"blog/[1-9].*")
+
+ def on_page_markdown(markdown, **kwargs):
+ page = kwargs['page']
+ config = kwargs['config']
+ if not include.match(page.url):
+ return markdown
+
+ page_url = config.site_url+page.url
+ page_title = urllib.parse.quote(page.title+'\n')
+
+ return markdown + dedent(f"""
+ [Share on :simple-x:]({x_intent}?text={page_title}&url={page_url}){{ .md-button }}
+ [Share on :simple-facebook:]({fb_sharer}?u={page_url}){{ .md-button }}
+ """)
+ ```
+
+ The hook first checks if the current page is a blog post and then appends
+ Markdown code for the share buttons. The buttons use icons, so you also need
+ to configure the following markdown extensions:
+
+ ```yaml
+ markdown_extensions:
+ - attr_list
+ - pymdownx.emoji:
+ emoji_index: !!python/name:material.extensions.emoji.twemoji
+ emoji_generator: !!python/name:material.extensions.emoji.to_svg
+ ```
+
+
+## Add a discussion system
+
+Allowing your readers to comment on your posts is a great way of receiving
+feedback, learning something, as well as giving readers the opportunity to
+discuss the content and the topic it is about.
+
+There are plenty of discussion system out there and you will need to consider
+your audience when choosing one appropriate for your blog. Likewise, you will
+also need to consider existing commitments to communication channels. If you
+are a heavy user Slack, for example, you may have a string preference for this
+system. Consider that when you add a communication channel, you will need to
+be prepared to use it regularly and to moderate discussions.
+
+### Giscus integration
+
+In this tutorial, we will be using [Giscus] because it is free, open source,
+and uses [GitHub Discussions] as a backend. Because a lot of users of Material
+for MkDocs use GitHub, this seems like an obvious choice.
+
+[Giscus]: https://giscus.app/
+[GitHub Discussions]: https://docs.github.com/en/discussions
+
+To add Giscus to your blog you will need to go through a number of steps:
+
+1. Create a GitHub repository if there is not already one
+2. Turn on discussions and install the [Giscus app]
+3. Configure the code needed to embed Giscus into your blog
+4. Add the code to your MkDocs project
+
+[Giscus app]: https://github.com/apps/giscus
+
+You may want to create a test repository for this tutorial that you can
+scrap later on. The instructions below assume that you are user "example"
+and that you create a repository "giscus-test." The repository will need
+to be public for people to be able to use the discussions.
+
+In the instructions given below, you will need to replace at least the username
+but also the repository name if you chose another name such as when you
+want to work directly on an existing repository.
+
+!!! example "Turn on discussions and install the Giscus app"
+
+ Once the repository is set up, go to its settings page and find
+ `Features` in the `General` section. Tick the checkbox for `Discussions`.
+ You will see that `Discussions` appears in the top navigation for the
+ repository. If you are using a live repository then you may want to add some
+ minimal content to the discussions section at this point and come back to the
+ tutorial.
+
+ Next, you need to install the [Giscus app] by following the link in this
+ sentence, and choosing `Install`, then following the instructions to choose
+ where the Giscus app is to be installed:
+
+ 1. Choose the account or organization for the repository you want to use.
+ 2. Choose to install only on select repositories and select the one you
+ want to use. Note that you can choose more than one repository here.
+ 3. Select `Install` at the end. You may need to authenticate to give
+ permission for this to happen.
+ 4. You will end up on the `Applications` page in your settings, where you
+ can control the Gicsus app and uninstall it if so desired.
+
+That is all the preparation you will need for the repository. Next, it is time
+to generate a piece of code that embeds Giscus in your site. The resulting code
+snippet will look something like this:
+
+```html
+<script src="https://giscus.app/client.js"
+ data-repo="<username>/<repository>"
+ data-repo-id="..."
+ data-category="Announcements"
+ data-category-id="..."
+ data-mapping="title"
+ data-strict="1"
+ data-reactions-enabled="1"
+ data-emit-metadata="1"
+ data-input-position="top"
+ data-theme="preferred_color_scheme"
+ data-lang="en"
+ data-loading="lazy"
+ crossorigin="anonymous"
+ async>
+</script>
+```
+
+!!! example "Configure the code needed to embed Giscus into your blog"
+
+ Go to the [Giscus homepage] and configure the embedding code. There are a
+ number of settings:
+
+ 1. Choose the language
+ 2. Enter the username / organization name and repository name
+ 3. Choose how the discussions are to be mapped to the page on your blog.
+ Because for a blog post the title is the basis of the URL, it makes
+ sense to use the `Discussion title contains page <title>` option.
+ 4. Under `Discussion Category` choose `Announcements` to limit the creation
+ of new discussions to Giscus and people with maintainer or admin
+ permissions.
+ 5. Under `Features`, select the following:
+ 1. Enable reactions for the main post
+ 2. Emit discussion metadata
+ 3. Place the comment box above the comments
+ 6. Under `Theme`, select `Preferred color scheme` so that Giscus matches
+ the color scheme selected by the user for your site.
+
+[Giscus homepage]: https://giscus.app/
+
+With these settings in place, you now need to integrate the code into your
+site. There is a partial `partials/comments.html` that exists for this purpose
+and is empty be default. It is included by the `content.html` partial, so will
+be included for every page on your site. You may or may not want this. In this
+tutorial, you will limit the Giscus integration to only blog posts but it is
+easy enough to leave out the code that achieves this if you want to have Giscus
+discussions active for every page.
+
+!!! example "Add Giscus integration code"
+
+ First, you need to create an `overrides` directory that will contain the
+ templates and partials you want to override.
+
+ ```
+ mkdir -p overrides/partials
+ ```
+
+ You need to declare it in your `mkdocs.yaml`:
+
+ ```yaml hl_lines="3"
+ theme:
+ name: material
+ custom_dir: overrides
+ ```
+
+ Now add a file `overrides/partials/comments.html` and paste in the code
+ snippet you obtained from the Giscus homepage. Look at the result locally
+ and you will see that the integration is active on all pages of the site.
+ If you want to restrict it to your blog posts, you need to add a conditional
+ around the Giscus script that tests if comments should be included. A simple
+ way of doing this is to test for a metadata flag:
+
+ ```html
+ {% if page.meta.comments %}
+ <script>...</script>
+ {% endif %}
+ ```
+
+ The disadvantage is that you now need to manually turn on comments for each
+ blog post - unless you want to turn them off on some. To get the comments
+ section on all blog posts, use code like this:
+
+ ```html
+ {% if page.file.src_uri.startswith('blog/posts') %}
+ <script>...</script>
+ {% endif %}
+ ```
+
+ You should see now that the Giscus comments are added at the bottom of your
+ blog posts but not on other pages.
+
+## What's next?
+
+This is the end of the blog tutorial. We hope you have enjoyed it and manage to
+set up your blog the way you like it. There are numerous other features and
+options that we have not been able to cover here. The [blog plugin reference]
+provides comprehensive documentation for the plugin. You may also want to
+look at the [social plugin tutorial] to generate social cards for your blog
+posts that get displayed when you post links to social media systems.
+
+[blog plugin reference]: https://squidfunk.github.io/mkdocs-material/plugins/blog/
+[social plugin tutorial]: ../social/basic.md
diff --git a/documents/markdown/mkdocs-material/tutorials_blogs_navigation.md b/documents/markdown/mkdocs-material/tutorials_blogs_navigation.md
new file mode 100644
index 0000000..9d870b8
--- /dev/null
+++ b/documents/markdown/mkdocs-material/tutorials_blogs_navigation.md
@@ -0,0 +1,524 @@
+# Navigation, authors, and pagination
+
+The Blog plugin provides blog-style navigation with a reverse-chronological
+index page and an archive organized by year by default. This tutorial shows
+how you can configure details of the default navigation, configure authors, and
+add more navigation options using categories and the [Tags plugin].
+
+[Tags plugin]: ../../plugins/tags.md
+
+__Time required:__ typically 30 minutes
+
+## Integrating navigation
+
+So far, you have let the Blog plugin and MkDocs worry about navigation. For some
+use cases, this might be enough and it is simply sufficient to not declare a
+`nav` section in the `mkdocs.yml`.
+
+However, you may want to integrate a blog with other content and a navigation
+structure that you have defined in the `nav` section of the configuration.
+In such cases, you need to provide a place where the Blog plugin should
+attach the blog navigation to the rest of the navigation structure.
+
+!!! example "Integrate with site navigation"
+
+ Add the following to your `mkdocs.yml` to see how the Blog plugin can
+ integrate the blog navigation with the overall navigation structure.
+ Note that the only thing you need to specify at this point is the
+ index page for the blog and its path must match the `blog_dir` setting,
+ which is `blog` by default:
+
+ ```yaml hl_lines="5 6"
+ nav:
+ - Home: index.md
+ - Install: install.md
+ - Usage: usage.md
+ - Blog:
+ - blog/index.md
+ ```
+
+ You will notice that "Blog" is duplicated in the navigation structure. To
+ avoid this, you can use the `navigation.indexes` feature to make the blog
+ index the section index page for the blog:
+
+ ```yaml hl_lines="3 4"
+ theme:
+ name: material
+ features:
+ - navigation.indexes
+ ```
+
+!!! tip "Stand-alone blog"
+
+ If what you need is a stand-alone blog instead of one that is integrated with
+ a larger site, this can be done by using the `blog_dir` configuration option.
+ To see how this is done, see [setting up a blog].
+ The rest of the tutorial assumes that you are integrating the blog with
+ a wider site.
+
+[Setting up a blog]: ../../setup/setting-up-a-blog.md#blog-only
+
+!!! tip "Adding pages"
+
+ You can add additional pages to the blog section by putting them into
+ `docs/blog` (and adding them to the navigation). The blog archive will be
+ added to the navigation after these pages.
+
+## Configuring the archive
+
+By default, the blog archive lists posts by year only. If you want to add
+listings by month, you can configure the date format for the archive.
+
+!!! example "Organize posts by month"
+
+ Add the following to your `mkdocs.yml` to get a listing with the month
+ name (in the language selected in the theme options):
+
+ ```yaml hl_lines="2"
+ - blog:
+ archive_date_format: MMMM yyyy
+ ```
+
+ If you do not want the full month name, you can make the date
+ configuration `MM/yyyy`, for example.
+
+ If you want to add the day, you can add a placeholder for them.
+ For example, to get an American-style output, make it `MM/dd/yyyy`.
+ For the plugin to sort the blog posts by the full date, you will
+ also need to set the `archive_url_date_format` to include the month
+ and day, so make it `MM/dd/yyyy` as well.
+
+## Using categories
+
+Categories are a way to make blog posts accessible by topic while retaining
+the navigation structure based on chronology within each category listing.
+Use them when there is a limited set of non-overlapping categories that
+you can sort your posts into.
+
+Categories appear in the main navigation, so are directly accessible from there.
+This implies that there are relatively few categories as otherwise the
+`categories` section in your main navigation will become too crowded.
+
+
+!!! example "Add a category"
+
+ Add a category to your first blog post by adding it to the page header:
+
+ ``` hl_lines="4 5""
+ ---
+ date: 2023-12-31
+ updated: 2024-01-02
+ categories:
+ - Holidays
+ ---
+ ```
+
+ Now that the blog post has been categorised, `Holidays` appears under
+ `Categories` in the main navigation and the blog post appears in the
+ index page for this category.
+
+
+!!! tip "Single or multiple categories?"
+
+ While it is traditionally the case that a blog post would belong to only
+ one category, Material for MkDocs actually allows you to assign more
+ than one. While this gives you a degree of freedom, you should
+ probably not use this too much, not least because you can use tags to
+ deal with multiple classifications. We will cover them in the next step.
+
+Material allows you to control which categories blog authors can use. You
+declare them in the `mkdocs.yml`. This way you can make sure everyone sticks
+to agreed categories and that the plugin detects typos.
+
+!!! example "Control your categories"
+
+ Add a `categories_allowed` entry to the configuration of the Blog plugin
+ with the entries "Holidays" and "News":
+
+ ```yaml hl_lines="5-7"
+ plugins:
+ - search
+ - blog:
+ archive_date_format: MMMM yyyy
+ categories_allowed:
+ - Holidays
+ - News
+ ```
+
+ Now, when you add a category to a blog post that does not match one of these
+ two, you should get a build error.
+
+## Using tags
+
+The [Tags plugin] provides another way to classify blog posts and to make
+them accessible independently of the main navigation structure. Tags are useful
+for making related content easily discoverable even if it is in different parts
+of the navigation hierarchy.
+
+[Tags plugin]: https://squidfunk.github.io/mkdocs-material/plugins/tags/
+
+You may have a tutorial like this one as well as a more comprehensive setup guide
+and reference documentation. Adding the same tag to all three shows that they
+are related. As you will see, it is possible to navigate from a tagged page to
+the tag index and, from there, to other pages that carry the same tag.
+
+!!! example "Enable the plugin and add tags"
+
+ First, you need to add the plugin to your `mkdocs.yml`:
+
+ ```yaml hl_lines="8"
+ plugins:
+ - search
+ - blog:
+ archive_date_format: MMMM yyyy
+ categories_allowed:
+ - Holidays
+ - News
+ - tags
+ ```
+
+ Once this is done, you can add tags to posts in the page header:
+
+ ``` hl_lines="9-12""
+ ---
+ date:
+ created: 2023-12-31
+ updated: 2024-01-02
+ authors:
+ - material
+ categories:
+ - Holidays
+ tags:
+ - new year
+ - hogmanay
+ - festive season
+ ---
+ ```
+
+You should see the tags that you defined at the top of the post. However, at the
+moment that is it. While the blog plugin automatically creates an index page for
+categories, the tags plugin does not do the same for tags. This is because the
+tags plugin is not specific for blogs. You can use it for any site content, so
+it is not obvious were the tag index should go.
+
+You can configure a basic tag index using the public version of Material for
+MkDocs. The Insider Edition supports this as well, of course, but also provides
+an alternative index mechanism that allows for an arbitrary number of tag
+indexes, scoped listings, shadow tags, nested tags, and much more.
+
+!!! example "Adding a tags index"
+ === "Basic tag index"
+
+ To configure a tag index using the public version, add a `tags_file` entry
+ to your configuration of the tags plugin and configure it in your `nav`
+ section. Remember to add a colon at the end of the existing `tags` entry.
+
+ ```yaml hl_lines="8-9 17"
+ plugins:
+ - search
+ - blog:
+ archive_date_format: MMMM yyyy
+ categories_allowed:
+ - Holidays
+ - News
+ - tags:
+ tags_file: blog/tags.md
+
+ nav:
+ - Home: index.md
+ - Install: install.md
+ - Usage: usage.md
+ - Blog:
+ - blog/index.md
+ - Tags: blog/tags.md
+ ```
+
+ The tag index will be appended to the configured page, which you should
+ now create at the location specified.
+
+ Note that you can put the tag index page anywhere in your primary
+ navigation, so if you are using tags elsewhere instead of just in your
+ blog then you may want to have the tag index outside the blog section
+ of the navigation.
+
+
+ === "Insider Edition"
+
+ To add a tag index, you add a placeholder in a Markdown file to tell
+ the plugin to insert an index at that point. This means that you
+ can add content before and after the index. Crucially, you can add
+ placeholders in multiple pages, each with a configuration of what
+ subset of tags should be displayed in the index.
+
+ The simplest index page looks like this. Create it under `docs/tags.md`.
+
+ ```markdown
+ # Tag index
+ <!-- material/tags -->
+ ```
+
+ Now, you may want to keep the tags for your blog separate from tags
+ you use in the rest of your page. You can achieve this by assigning
+ the tag index a scope. Put the following under `docs/blog/tags.md`:
+
+ ```markdown
+ # Tag index for the blog
+ <!-- material/tags { scope: true } -->
+ ```
+
+ You now have two index pages: one covers the whole site and one
+ covers only the blog. Add both to the navigation:
+
+ ```yaml
+ nav:
+ - Home: index.md
+ - Tags: tags.md
+ - Blog:
+ - blog/index.md
+ - blog/tags.md
+ ```
+
+ The tags plugin in the Insider Edition is an incredibly powerful tool
+ and we can only scratch the surface of what is possible with it. If you
+ want to explore more after you have worked for this part of the tutorial,
+ have a look at the [tags plugin reference].
+
+[tags plugin reference]: ../../plugins/tags.md
+
+## Defining authors
+
+If your blog has more than one author then you may want to identify the author
+for each blog post. The blog plugin allows you to create a file that contains
+the author information and to then reference the authors of a particular post in
+the page header.
+
+!!! example "Create author info"
+
+ Create a file `docs/blog/.authors.yml` with this content:
+
+ ```yaml
+ authors:
+ team:
+ name: Team
+ description: Creator
+ avatar: https://simpleicons.org/icons/materialformkdocs.svg
+ squidfunk:
+ name: Martin Donath
+ description: Creator
+ avatar: https://github.com/squidfunk.png
+ ```
+
+ and then add a line to the header of the first post:
+
+
+ ```hl_lines="5-6"
+ ---
+ date:
+ created: 2023-12-31
+ updated: 2024-01-02
+ authors:
+ - team
+ ---
+ ```
+
+ Note that `authors` is a list, so you can specify multiple authors.
+
+You can create custom author index pages that can highlight the contributions
+of an author as well as provide additional information about them.
+
+!!! example "Add author page"
+
+ First, you need to enable author profiles in the `mkdocs.yml`:
+
+ ```yaml hl_lines="8"
+ plugins:
+ - search
+ - blog:
+ archive_date_format: MMMM yyyy
+ categories_allowed:
+ - Holidays
+ - News
+ authors_profiles: true
+ ```
+
+ Check your blog to see that there is now an extra entry in the main
+ navigation next to `archive` and `categories` that lists the authors and
+ their contributions.
+
+ To customize the author page, you can create a page that overrides the one
+ generated by default. First, create the `author` directory that the profile
+ pages will live in:
+
+ ```hl_lines="3"
+ docs
+ ├── blog
+ │ ├── author
+ │ ├── index.md
+ │ └── posts
+ │ ├── draft.md
+ │ └── myfirst.md
+ └── index.md
+ ```
+
+ Then create a page `docs/blog/author/team.md`:
+
+ ```
+ # The Material Team
+
+ A small group of people dedicated to making writing documentation easy, if
+ not outright fun! Here are some of the things we have blogged about:
+ ```
+
+ As you can see, the author index gets appended to the content you have
+ written in the Markdown file.
+
+## Pagination
+
+Once your blog starts growing, you may not want to pay attention to the number
+of posts displayed per page. By default, the plugin displays up to 10 posts on
+the index pages. You can change this number separately for the main index,
+the archive index pages, and the category index pages.
+
+!!! example "Changing pagination"
+
+ Add five more blog posts, then set the pagination setting to show five per
+ page only:
+
+ ```yaml hl_lines="7"
+ - blog:
+ archive_date_format: MMMM yyyy
+ categories_allowed:
+ - Holidays
+ - News
+ authors_profiles: true
+ pagination_per_page: 5
+ ```
+
+ You will see that the pagination setting for archive and category pages
+ are inherited from the setting you added. If you want to have different
+ settings for the different index pages, you can specify each setting
+ separately:
+
+ ```yaml
+ - blog:
+ archive_date_format: MMMM yyyy
+ categories_allowed:
+ - Holidays
+ - News
+ authors_profiles: true
+ pagination_per_page: 5
+ archive_pagination_per_page: 10
+ categories_pagination_per_page: 10
+ ```
+
+## Blog table of contents
+
+Another thing you may want to do once you have a large enough number of posts
+is to turn on the function that produces a table of contents for the blog
+index pages, giving your readers the opportunity to quickly scan the content
+of each page for something that interests them without having to scroll
+(assuming that the number of post per page is not too big).
+
+!!! example "Turn on the table of contents feature"
+
+ To produce a table of contents for the blog index pages, add the following
+ to the configuration of the blog plugin:
+
+ ```yaml hl_lines="2"
+ - blog:
+ blog_toc: true
+ archive_date_format: MMMM yyyy
+ # ...
+ ```
+
+## Custom slugs
+
+If, for some reason, you are not happy with the way that Material for MkDocs
+turns headings into slugs, you can create your own slugify function or you
+can manually define a slug for a specific post.
+
+!!! example "Slugify function"
+
+ To define your own slugify function, you need to write a Python function
+ that converts text into a slug given additional arguments from the
+ configuration. You also need to write a function that returns that
+ function.
+
+ Say you want to define two slugify functions that you can switch between.
+ The first one returns a slug similar to what the default slugify function
+ produces. The second one cuts the result of that up into words and returns
+ a slug based on a maximum of five of them:
+
+ ```python
+ import re, functools, unicodedata
+
+ RE_HTML_TAGS = re.compile(r'</?[^>]*>', re.UNICODE)
+ RE_INVALID_SLUG_CHAR = re.compile(r'[^\w\- ]', re.UNICODE)
+ RE_WHITESPACE = re.compile(r'\s', re.UNICODE)
+
+ def _make_slug(text, sep, **kwargs):
+ slug = unicodedata.normalize('NFC', text)
+ slug = RE_HTML_TAGS.sub('', slug)
+ slug = RE_INVALID_SLUG_CHAR.sub('', slug)
+ slug = slug.strip().lower()
+ slug = RE_WHITESPACE.sub(sep, slug)
+ return slug
+
+ def _make_slug_short(text, sep, **kwargs):
+ words = _make_slug(text, sep, **kwargs).split(sep)
+ return sep.join(words[:5])
+
+ def slugify(**kwargs):
+ if 'short' in kwargs and kwargs['short']:
+ return functools.partial(_make_slug_short, **kwargs)
+ return functools.partial(_make_slug, **kwargs)
+ ```
+ Save this code in `ext/slugs.py` and also add an (empty) `__init__.py`
+ file to indicate that the directory is a module. Now you can configure
+ your custom slugify code like this:
+
+ ```yaml hl_lines="4-6"
+ plugins:
+ - blog:
+ # other entries omitted
+ post_slugify: !!python/object/apply:ext.slugs.slugify
+ kwds:
+ short: true
+ ```
+
+ Change the heading of a blog post to be longer than five words and observe
+ how the slugify function shortens the URL. Change the `short` attribute to
+ `false` and you can turn this off again.
+
+If you want to influence the slug only for a single blog post, you can define
+it manually by specifying it in the header of the post. Note that this is meant
+as a last resort option. Specifying a custom slug manually for every post would
+be tedious.
+
+!!! example "Manually define slug"
+
+ If, for example, you wanted the slug to be 'ny-eve' instead of the somewhat
+ lengthy 'happy-new-years-eve', you could add the following:
+
+ ```hl_lines="7"
+ ---
+ date:
+ created: 2023-12-31
+ updated: 2024-01-02
+ readtime: 15
+ pin: true
+ slug: ny-eve
+ ---
+ ```
+
+ The URL for this post should now be
+ `http://localhost:8000/blog/2023/01/31/ny-eve/`.
+
+## What's next?
+
+You may want to increase engagement with your blog by allowing people to
+subscribe to an RSS feed, by providing links to your social media profiles, by
+providing share and like buttons, or by setting up a comment system.
+The [engagement and dissemination tutorial] walks you through setting these up.
+
+[engagement and dissemination tutorial]: engage.md
diff --git a/documents/markdown/mkdocs-material/tutorials_index.md b/documents/markdown/mkdocs-material/tutorials_index.md
new file mode 100644
index 0000000..cebccc2
--- /dev/null
+++ b/documents/markdown/mkdocs-material/tutorials_index.md
@@ -0,0 +1,47 @@
+# Tutorials
+
+In addition to the basic getting started guides, we offer tutorials that aim to
+show how you can use Material for MkDocs in different use cases. In contrast to
+the getting started guides or the reference documentation, the tutorials show
+the breadth of features available in Material for MkDocs but also within
+the wider MkDocs ecosystem.
+
+The tutorials guide you through worked examples, so by following them you should
+gain not only an understanding of how to use Material for MkDocs, but also
+a template for your own projects. For convenience, these templates are also
+available as template repositories on GitHub.
+
+[public version]: ../getting-started.md
+[creating your site]: ../creating-your-site.md
+
+!!! note "Feedback wanted!"
+ The tutorials are a recent addition to our documentation and we are still
+ working out what shape they should have in the end. Please [provide any
+ feedback you might have in this discussion thread].
+
+ Note, however, that suggestions should be specific and feasible. We want to
+ focus on creating more content at the moment, instead of developing a
+ specific styling or behaviour for the tutorials. If there are worthwhile
+ improvements that we can make through simple customization then we are happy
+ to consider those.
+
+[provide any feedback you might have in this discussion thread]: https://github.com/squidfunk/mkdocs-material/discussions/7220
+
+## Blogs
+* [Basics](blogs/basic.md) (20 min) <br/>
+ covers the basics of setting up a blog, including post metadata.
+* [Navigation, pagination, multiple authors](blogs/navigation.md) (30 min)<br/>
+ describes how to make it easier for your readers to find content.
+* [Engagement and dissemination](blogs/engage.md) (30 min)<br/>
+ walks you through ways of increasing engagement with your content.
+
+[:octicons-repo-template-24: Template Repository](https://github.com/mkdocs-material/create-blog)
+
+## Social cards
+* [Basics](social/basic.md) (20 min) <br/>
+ shows you how to configure Material for MkDocs to create social cards for
+ your content.
+* [Custom cards](social/custom.md) (15 min)<br/>
+ shows you how to design your own custom social cards.
+
+[:octicons-repo-template-24: Template Repository](https://github.com/mkdocs-material/create-social-cards)
diff --git a/documents/markdown/mkdocs-material/tutorials_social_basic.md b/documents/markdown/mkdocs-material/tutorials_social_basic.md
new file mode 100644
index 0000000..3b416b9
--- /dev/null
+++ b/documents/markdown/mkdocs-material/tutorials_social_basic.md
@@ -0,0 +1,199 @@
+# Basic social cards
+
+Social cards are images that other systems such as social media can display as
+a preview for content linked to. It is easy to get started with the social
+plugin, true to the motto of Material with MkDocs: "batteries included."
+
+## Basics
+
+Before you start, there are just a couple of [dependencies to install]. These
+are libraries for image processing that the plugin needs to produce the social
+cards, as well as their Python bindings.
+
+[dependencies to install]: https://squidfunk.github.io/mkdocs-material/plugins/requirements/image-processing/
+
+With those prerequisites met, it is simply a matter of activating the plugin,
+which will:
+
+* produce the social cards as PNG images for each page in your site;
+* create meta data in the headers of your site's pages that will provide
+ social media systems with key information and tell them how to find the
+ social card image.
+
+!!! example "Add social cards"
+
+ Simply add the social plugin to your list of plugins:
+
+ ```yaml hl_lines="3"
+ plugins:
+ - search
+ - social
+ - ...
+ ```
+
+Now, when you run `mkdocs build` and look at the `site` directory, you will
+see that it contains subfolders under `assets/images/social` that reflect
+the structure of your Markdown files. Each page has a corresponding PNG file
+that contains the social card image.
+
+Have a look at the generated HTML and you will see the metadata produced in
+the `head` element, including one entry that points to the image.
+
+## Background color
+
+The social plugin has configuration options for changing aspects such as colors,
+images, fonts, logos, the title, even the description. You can configure them
+for all social cards in the `mkdocs.yml` and, they can be overridden in the page
+header for individual pages.
+
+!!! example "Change the background color"
+
+ To change the background color to an attention-grabbing hot pink,
+ you might add:
+
+ ```yaml hl_lines="4-5"
+ plugins:
+ ...
+ - social:
+ cards_layout_options:
+ background_color: "#ff1493"
+ ```
+
+## Logos
+
+By default, the plugin uses the logo that you set for the whole site, either
+through the `theme.logo` or the `theme.icon.logo` setting. The difference
+between the two is that the `theme.icon.logo` version will directly embed the
+logo's SVG code into the HTML, allowing it to inherit CSS color settings. When
+you use `theme.logo`, the Material includes the logo as an image.
+
+You can set your own logo specific for the social cards as well. The path used
+is relative to your project root and needs to point to an SVG file or a pixel
+image. It should be rectangular and have a transparent background.
+
+!!! example "Set your own logo"
+
+ ```yaml hl_lines="3-4"
+ plugins:
+ - social:
+ cards_layout_options:
+ logo: docs/assets/images/ourlogo.png
+ ```
+
+## Background images
+
+In addition to adding your own logo, the most impactful way to personalize your
+social cards is to add a background image instead of the default solid color
+background. Make sure you choose one that will contrast well with the other
+elements of the card.
+
+Also, the background color gets rendered *on top of* the background image,
+allowing you to use a transparent color to tint an image. To use just the image,
+use the color value `transparent`.
+
+!!! example "Add background image"
+
+ ```yaml hl_lines="4 5"
+ plugins:
+ - social:
+ cards_layout_options:
+ background_image: layouts/background.png
+ background_color: transparent
+ ```
+
+The path to the background image is resolved from the root of your project,
+so this is where you should make the `layouts` directory and place the
+background image. The default site of the social cards included with the plugin
+is 1200x630 pixels, so choose an image that size or one that scales well to it.
+
+## Additional layouts and styles
+
+The social plugin provides additional layouts as well as the option to configure
+different styles for different (kinds of) pages. It comes with a number of
+additional layouts for the social cards. For example, the `default/variant`
+layout adds a page icon to the card. You can use this to distinguish social
+cards visually, depending on what kind of page you are sharing.
+
+For example, imagine you have a set of pages that advertise events and you want
+to include a calendar icon as a visual indication that a card advertises an
+event. In the following, you will set up a directory for event pages and use
+the meta plugin to assign them a calendar icon.
+
+!!! example "Social cards for event pages"
+
+ First, create a directory in your `docs` directory to hold the event pages:
+
+ ```
+ $ mkdir docs/events
+ ```
+
+ Then, add a file `.meta.yml` inside this new directory with settings for
+ the page icon and a hot pink background color that will stand out on
+ social media. Note that you can override the background image by setting it
+ to `null` here since it is not visible anyway because of the opaque coloring.
+
+ ```yaml
+ ---
+ icon: material/calendar-plus
+ social:
+ cards_layout_options:
+ background_image: null
+ background_color: "#ff1493"
+ ---
+ ```
+
+ Now add a page within the `docs/events` directoy. It does not need to have
+ any special content, just a top level header.
+
+ To turn on the `default/variant` layout in `mkdocs.yml`, add the
+ `cards_layout` option and also add the meta plugin:
+
+ ```yaml
+ plugins:
+ - meta
+ - social:
+ cards_layout: default/variant
+ ```
+
+ After running `mkdocs build`, you can see that the social card at
+ `site/assets/images/social/events/index.png` features the page icon.
+
+Note that the icon will also appear next to the navigation element for the
+page. If that is not what you want then you will need to modify the social
+card template to gets its icons from another source. You can learn how to
+do this in the [custom social cards tutorial](custom.md).
+
+## Per-page settings
+
+You can customize the card layout for each page by adding settings to the page
+header. You have effectively done this in the previous exercise, but using the
+meta plugin to affect a whole set of pages.
+
+Say that in addition to regular events you also have the odd webinar and
+for this you want to set a different icon and also set the description to
+indicate that the event is part of the webinar series.
+
+!!! example "Override card style in page header"
+
+ Add the following to the top of the page in `docs/events` or create a new
+ one:
+
+ ```yaml
+ ---
+ icon: material/web
+ social:
+ cards_layout_options:
+ description: Our Webinar Series
+ ---
+ ```
+
+## What's next?
+
+You can also define custom layouts if the configuration options introduced above
+as not enough to meet your needs. Continue to the
+[custom social cards tutorial](custom.md) if you want to find out how to do this.
+
+Social cards are particularly useful for blog posts. If you have a blog,
+you need to do nothing more than to turn on both plugins to create social cards
+to advertise your latest blog posts. If you do not have one yet but would like
+to, why not check out the [blog tutorials](../index.md#blogs)?
diff --git a/documents/markdown/mkdocs-material/tutorials_social_custom.md b/documents/markdown/mkdocs-material/tutorials_social_custom.md
new file mode 100644
index 0000000..f650fb9
--- /dev/null
+++ b/documents/markdown/mkdocs-material/tutorials_social_custom.md
@@ -0,0 +1,142 @@
+# Custom cards
+
+The social plugin allows you to define custom layouts for your social cards
+to suit your specific needs if the configuration options are not enough.
+For example, you may want to define a social card to advertise a new release
+of your product. It should have an icon indicating a launch announcement as
+well as the version number of the release on the card.
+
+## Setup
+
+You can either design a custom layout from scratch or use an existing layout
+as the basis that you add to or otherwise modify. In this tutorial, you will
+use the default layout as the basis.
+
+!!! example "Copy default layout to customize"
+
+ Copy the default social card layout from your installation of Material
+ for MkDocs to a new directory `layouts`. The instructions below assume you
+ are in your project root and have a virtual environment within this. The
+ path on your machine, of course, may differ.
+
+ ```
+ $ mkdir layouts
+ $ cp venv/lib/python3.12/site-packages/material/plugins/social/templates/default/variant.yml \
+ layouts/release.yml
+ ```
+
+ Before customizing the social cards, you need to tell the plugin where to
+ find them as well as tell MkDocs to watch for any changes. Add the following
+ to the plugin configuration in your `mkdocs.yml`:
+
+ ``` yaml hl_lines="2-6"
+ plugins:
+ - social:
+ cards_layout_dir: layouts
+
+ watch:
+ - layouts
+ ```
+
+Have a look at the contents of `release.yml`. You will see that there are:
+
+* a number of definitions of content pulled from the site,
+* definitions of tags that end up in the `meta` elements in the page header
+ of each page,
+* a specification that consists of a number of layers that the social plugin
+ applies on top of each other in the order in which they are defined.
+
+## Define page metadata
+
+In the following, you will add a version number to the social card. This
+assumes you have a changelog page with information about each release.
+Add the version number of the latest version to the page header (so it does
+not need to be parsed out of the Markdown content):
+
+!!! example "Defining the release data"
+
+ Create a page `docs/changelog.md` with the following content:
+
+ ```yaml
+ ---
+ icon: material/rocket-launch-outline
+ social:
+ cards_layout: release
+ cards_layout_options:
+ title: New release!
+ latest: 1.2.3
+ ---
+
+ # Releases
+ ```
+
+## Extract page metadata
+
+With the data defined in the page header, you can now add code to the layout
+that pulls it out and makes it available to render later on. This is to separate
+the data manipulation from the actual layout instructions and so make the
+layout file easier to read.
+
+!!! example "Adding data definitions"
+
+ Add the following at the top of the layout file:
+
+ ```yaml hl_lines="2-9"
+ definitions:
+ - &latest >-
+ {%- if 'latest' in page.meta %}
+ {{ page.meta['latest']}}
+ {%- else -%}
+ No release version data defined!
+ {%- endif -%}
+ ```
+
+The code presented here checks whether the page header contains the necessary
+entries and spits out a message to the social card if not. Unfortunately, there
+is no straightforward way to raise an exception or log an error, so the messages
+merely appear in the social card produced.
+
+## Add release version layer
+
+The next step is to use these data definitions in a new layer and add it to the
+ones already present.
+
+!!! example "Render release version"
+
+ Finally, add the following to end of the custom layout:
+
+ ```yaml
+ - size: { width: 990, height: 50 }
+ offset: { x: 50, y: 360 }
+ typography:
+ content: *latest
+ align: start
+ color: *color
+ ```
+
+You should now see the social plugin use the custom layout on the changelog page
+you set up.
+
+## Adjust layout
+
+Finally, the rocket icon used for the changelog page is not quite in the right
+position. Find the please where the `page_icon` variable is used to create the
+page icon layer and adjust the horizontal position to 600 instead of 800.
+
+!!! tip "Debugging layout files"
+
+ Should you find that your layouts are causing your MkDocs build to fail,
+ there are a number of things you can do:
+
+ 1. Run Mkdocs with the `--verbose` option to get more detailed reporting.
+ 2. Comment out things you recently added or that you suspect are the cause
+ 3. Install the `jinja2` command-line tool with `pip install Jinja2` and
+ run it over your layout file, for example: `jinja2 event.yml`.
+
+## What's next?
+
+If you do not have a blog yet, why not check out the
+[blog tutorials](../index.md#blogs) and learn how to set one up? The social
+plugin will help you draw attention to your posts on social media.
+
+Check out the [other tutorials](../index.md) we have prepared for you.
diff --git a/documents/markdown/mkdocs-material/upgrade.md b/documents/markdown/mkdocs-material/upgrade.md
new file mode 100644
index 0000000..bab2d29
--- /dev/null
+++ b/documents/markdown/mkdocs-material/upgrade.md
@@ -0,0 +1,1965 @@
+# How to upgrade
+
+Upgrade to the latest version with:
+
+```
+pip install --upgrade --force-reinstall mkdocs-material
+```
+
+Show the currently installed version with:
+
+```
+pip show mkdocs-material
+```
+
+## Upgrading from 8.x to 9.x
+
+This major release includes a brand new search implementation that is faster
+and allows for rich previews, advanced tokenization and better highlighting.
+It was available as part of Insiders for over a year, and now that the funding
+goal was hit, makes its way into the community edition.
+
+### Changes to `mkdocs.yml`
+
+#### `content.code.copy`
+
+The copy-to-clipboard buttons are now opt-in and can be enabled or disabled
+per block. If you wish to enable them for all code blocks, add the following
+lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - content.code.copy
+```
+
+#### `content.action.*`
+
+A "view source" button can be shown next to the "edit this page" button, both
+of which must now be explicitly enabled. Add the following lines to
+`mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - content.action.edit
+ - content.action.view
+```
+
+#### `navigation.footer`
+
+The _previous_ and _next_ buttons in the footer are now opt-in. If you wish to
+keep them for your documentation, add the following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+ features:
+ - navigation.footer
+```
+
+#### `theme.language`
+
+The Korean and Norwegian language codes were renamed, as they were non-standard:
+
+- `kr` to `ko`
+- `no` to `nb`
+
+#### `feedback.ratings`
+
+The old, nameless placeholders were removed (after being deprecated for several
+months). Make sure to switch to the new named placeholders `{title}` and `{url}`:
+
+```
+https://github.com/.../issues/new/?title=[Feedback]+{title}+-+{url}
+```
+
+### Changes to `*.html` files
+
+The templates have undergone a series of changes. If you have customized
+Material for MkDocs with theme extension, be sure to incorporate the latest
+changes into your templates. A good starting point is to [inspect the diff].
+
+!!! warning "Built-in plugins not working after upgrade?"
+
+ If one of the built-in plugins (search or tags) doesn't work anymore without
+ any apparent error or cause, it is very likely related to custom overrides.
+ [MkDocs 1.4.1] and above allow themes to namespace built-in plugins, which
+ Material for MkDocs 9 now does in order to allow authors to use third-party
+ plugins with the same name as built-in plugins. Search your overrides for
+ [`"in config.plugins"`][in config.plugins] and add the `material/` namespace.
+ Affected partials:
+
+ - [`content.html`][content.html]
+ - [`header.html`][header.html]
+
+ [inspect the diff]: https://github.com/squidfunk/mkdocs-material/pull/4628/files#diff-3ca112736b9164701b599f34780107abf14bb79fe110c478cac410be90899828
+ [MkDocs 1.4.1]: https://github.com/mkdocs/mkdocs/releases/tag/1.4.1
+ [in config.plugins]: https://github.com/squidfunk/mkdocs-material/search?q=%22in+config.plugins%22
+ [content.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/content.html
+ [header.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/header.html
+
+## Upgrading from 7.x to 8.x
+
+### What's new?
+
+- Added support for code annotations
+- Added support for anchor tracking
+- Added support for version warning
+- Added `copyright` partial for easier override
+- Removed deprecated content tabs legacy implementation
+- Removed deprecated `seealso` admonition type
+- Removed deprecated `site_keywords` setting (unsupported by MkDocs)
+- Removed deprecated prebuilt search index support
+- Removed deprecated web app manifest – use customization
+- Removed `extracopyright` variable – use new `copyright` partial
+- Removed Disqus integration – use customization
+- Switched to `:is()` selectors for simple selector lists
+- Switched autoprefixer from `last 4 years` to `last 2 years`
+- Improved CSS overall to match modern standards
+- Improved CSS variable semantics for fonts
+- Improved extensibility by restructuring partials
+- Improved handling of `details` when printing
+- Improved keyboard navigation for footnotes
+- Fixed #3214: Search highlighting breaks site when empty
+
+### Changes to `mkdocs.yml`
+
+#### `pymdownx.tabbed`
+
+Support for the legacy style of the [Tabbed] extension was dropped in favor
+of the new, alternate implementation which has [better behavior on mobile
+viewports]:
+
+=== "8.x"
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.tabbed:
+ alternate_style: true
+ ```
+
+=== "7.x"
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.tabbed
+ ```
+
+ [Tabbed]: setup/extensions/python-markdown-extensions.md#tabbed
+ [better behavior on mobile viewports]: https://x.com/squidfunk/status/1424740370596958214
+
+#### `pymdownx.superfences`
+
+The `*-experimental` suffix must be removed from the [custom fence][SuperFences]
+class property, which is used to target code blocks to be rendered as [diagrams]
+using [Mermaid.js]:
+
+=== "8.x"
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.superfences:
+ custom_fences:
+ - name: mermaid
+ class: mermaid
+ format: !!python/name:pymdownx.superfences.fence_code_format
+ ```
+
+=== "7.x"
+
+ ``` yaml
+ markdown_extensions:
+ - pymdownx.superfences:
+ custom_fences:
+ - name: mermaid
+ class: mermaid-experimental
+ format: !!python/name:pymdownx.superfences.fence_code_format
+ ```
+
+ [SuperFences]: setup/extensions/python-markdown-extensions.md#superfences
+ [diagrams]: reference/diagrams.md
+ [Mermaid.js]: https://mermaid-js.github.io/mermaid/
+
+#### `google_analytics`
+
+This option was [deprecated in MkDocs 1.2.0], as the implementation of a
+JavaScript-based analytics integration is the responsibility of a theme.
+The following lines must be changed:
+
+=== "8.x"
+
+ ``` yaml
+ extra:
+ analytics:
+ provider: google
+ property: UA-XXXXXXXX-X
+ ```
+
+=== "7.x"
+
+ ``` yaml
+ google_analytics:
+ - UA-XXXXXXXX-X
+ - auto
+ ```
+
+ [deprecated in MkDocs 1.2.0]: https://www.mkdocs.org/about/release-notes/#backward-incompatible-changes-in-12
+
+### Changes to `*.html` files { data-search-exclude }
+
+The templates have undergone a set of changes to make them future-proof. If
+you've used theme extension to override a block or template, make sure that it
+matches the new structure:
+
+- If you've overridden a __block__, check `base.html` for potential changes
+- If you've overridden a __template__, check the respective `*.html` file for
+ potential changes
+
+=== ":octicons-file-code-16: `base.html`"
+
+ ``` diff
+ @@ -13,11 +13,6 @@
+ {% elif config.site_description %}
+ <meta name="description" content="{{ config.site_description }}">
+ {% endif %}
+ - {% if page and page.meta and page.meta.keywords %}
+ - <meta name="keywords" content="{{ page.meta.keywords }}">
+ - {% elif config.site_keywords %}
+ - <meta name="keywords" content="{{ config.site_keywords }}">
+ - {% endif %}
+ {% if page and page.meta and page.meta.author %}
+ <meta name="author" content="{{ page.meta.author }}">
+ {% elif config.site_author %}
+ @@ -61,15 +56,13 @@
+ font.text | replace(' ', '+') + ':300,400,400i,700%7C' +
+ font.code | replace(' ', '+')
+ }}&display=fallback">
+ - <style>:root{--md-text-font-family:"{{ font.text }}";--md-code-font-family:"{{ font.code }}"}</style>
+ + <style>:root{--md-text-font:"{{ font.text }}";--md-code-font:"{{ font.code }}"}</style>
+ {% endif %}
+ {% endblock %}
+ - {% if config.extra.manifest %}
+ - <link rel="manifest" href="{{ config.extra.manifest | url }}" crossorigin="use-credentials">
+ - {% endif %}
+ {% for path in config["extra_css"] %}
+ <link rel="stylesheet" href="{{ path | url }}">
+ {% endfor %}
+ + {% include "partials/javascripts/base.html" %}
+ {% block analytics %}
+ {% include "partials/integrations/analytics.html" %}
+ {% endblock %}
+ @@ -89,7 +82,6 @@
+ <body dir="{{ direction }}">
+ {% endif %}
+ {% set features = config.theme.features or [] %}
+ - {% include "partials/javascripts/base.html" %}
+ {% if not config.theme.palette is mapping %}
+ {% include "partials/javascripts/palette.html" %}
+ {% endif %}
+ @@ -106,13 +98,25 @@
+ </div>
+ <div data-md-component="announce">
+ {% if self.announce() %}
+ - <aside class="md-banner md-announce">
+ - <div class="md-banner__inner md-announce__inner md-grid md-typeset">
+ + <aside class="md-banner">
+ + <div class="md-banner__inner md-grid md-typeset">
+ {% block announce %}{% endblock %}
+ </div>
+ </aside>
+ {% endif %}
+ </div>
+ + {% if config.extra.version %}
+ + <div data-md-component="outdated" hidden>
+ + <aside class="md-banner md-banner--warning">
+ + {% if self.outdated() %}
+ + <div class="md-banner__inner md-grid md-typeset">
+ + {% block outdated %}{% endblock %}
+ + </div>
+ + {% include "partials/javascripts/outdated.html" %}
+ + {% endif %}
+ + </aside>
+ + </div>
+ + {% endif %}
+ {% block header %}
+ {% include "partials/header.html" %}
+ {% endblock %}
+ @@ -156,25 +160,7 @@
+ <div class="md-content" data-md-component="content">
+ <article class="md-content__inner md-typeset">
+ {% block content %}
+ - {% if page.edit_url %}
+ - <a href="{{ page.edit_url }}" title="{{ lang.t('edit.link.title') }}" class="md-content__button md-icon">
+ - {% include ".icons/material/pencil.svg" %}
+ - </a>
+ - {% endif %}
+ - {% if not "\x3ch1" in page.content %}
+ - <h1>{{ page.title | d(config.site_name, true)}}</h1>
+ - {% endif %}
+ - {{ page.content }}
+ - {% if page and page.meta %}
+ - {% if page.meta.git_revision_date_localized or
+ - page.meta.revision_date
+ - %}
+ - {% include "partials/source-file.html" %}
+ - {% endif %}
+ - {% endif %}
+ - {% endblock %}
+ - {% block disqus %}
+ - {% include "partials/integrations/disqus.html" %}
+ + {% include "partials/content.html" %}
+ {% endblock %}
+ </article>
+ </div>
+ ```
+
+ ``` diff
+ @@ -38,13 +38,6 @@
+ <meta name="description" content="{{ config.site_description }}" />
+ {% endif %}
+
+ - <!-- Page keywords -->
+ - {% if page and page.meta and page.meta.keywords %}
+ - <meta name="keywords" content="{{ page.meta.keywords }}" />
+ - {% elif config.site_keywords %}
+ - <meta name="keywords" content="{{ config.site_keywords }}" />
+ - {% endif %}
+ -
+ <!-- Page author -->
+ {% if page and page.meta and page.meta.author %}
+ <meta name="author" content="{{ page.meta.author }}" />
+ @@ -120,27 +113,21 @@
+ />
+ <style>
+ :root {
+ - --md-text-font-family: "{{ font.text }}";
+ - --md-code-font-family: "{{ font.code }}";
+ + --md-text-font: "{{ font.text }}";
+ + --md-code-font: "{{ font.code }}";
+ }
+ </style>
+ {% endif %}
+ {% endblock %}
+
+ - <!-- Progressive Web App Manifest -->
+ - {% if config.extra.manifest %}
+ - <link
+ - rel="manifest"
+ - href="{{ config.extra.manifest | url }}"
+ - crossorigin="use-credentials"
+ - />
+ - {% endif %}
+ -
+ <!-- Custom style sheets -->
+ {% for path in config["extra_css"] %}
+ <link rel="stylesheet" href="{{ path | url }}" />
+ {% endfor %}
+
+ + <!-- Helper functions for inline scripts -->
+ + {% include "partials/javascripts/base.html" %}
+ +
+ <!-- Analytics -->
+ {% block analytics %}
+ {% include "partials/integrations/analytics.html" %}
+ @@ -172,7 +159,6 @@
+
+ <!-- Retrieve features from configuration -->
+ {% set features = config.theme.features or [] %}
+ - {% include "partials/javascripts/base.html" %}
+
+ <!-- User preference: color palette -->
+ {% if not config.theme.palette is mapping %}
+ @@ -214,14 +200,28 @@
+ <!-- Announcement bar -->
+ <div data-md-component="announce">
+ {% if self.announce() %}
+ - <aside class="md-banner md-announce">
+ - <div class="md-banner__inner md-announce__inner md-grid md-typeset">
+ + <aside class="md-banner">
+ + <div class="md-banner__inner md-grid md-typeset">
+ {% block announce %}{% endblock %}
+ </div>
+ </aside>
+ {% endif %}
+ </div>
+
+ + <!-- Version warning -->
+ + {% if config.extra.version %}
+ + <div data-md-component="outdated" hidden>
+ + <aside class="md-banner md-banner--warning">
+ + {% if self.outdated() %}
+ + <div class="md-banner__inner md-grid md-typeset">
+ + {% block outdated %}{% endblock %}
+ + </div>
+ + {% include "partials/javascripts/outdated.html" %}
+ + {% endif %}
+ + </aside>
+ + </div>
+ + {% endif %}
+ +
+ <!-- Header -->
+ {% block header %}
+ {% include "partials/header.html" %}
+ @@ -295,49 +295,11 @@
+ {% block content %}
+ -
+ - <!-- Edit button -->
+ - {% if page.edit_url %}
+ - <a
+ - href="{{ page.edit_url }}"
+ - title="{{ lang.t('edit.link.title') }}"
+ - class="md-content__button md-icon"
+ - >
+ - {% include ".icons/material/pencil.svg" %}
+ - </a>
+ - {% endif %}
+ -
+ - <!--
+ - Hack: check whether the content contains a h1 headline. If it
+ - doesn't, the page title (or respectively site name) is used
+ - as the main headline.
+ - -->
+ - {% if not "\x3ch1" in page.content %}
+ - <h1>{{ page.title | d(config.site_name, true)}}</h1>
+ - {% endif %}
+ -
+ - <!-- Markdown content -->
+ - {{ page.content }}
+ -
+ - <!-- Last update of source file -->
+ - {% if page and page.meta %}
+ - {% if page.meta.git_revision_date_localized or
+ - page.meta.revision_date
+ - %}
+ - {% include "partials/source-file.html" %}
+ - {% endif %}
+ - {% endif %}
+ - {% endblock %}
+ -
+ - <!-- Disqus integration -->
+ - {% block disqus %}
+ - {% include "partials/integrations/disqus.html" %}
+ + {% include "partials/content.html" %}
+ {% endblock %}
+ </article>
+ </div>
+ ```
+
+=== ":octicons-file-code-16: `partials/copyright.html`"
+
+ ``` diff
+ @@ -0,0 +1,16 @@
+ +{#-
+ + This file was automatically generated - do not edit
+ +-#}
+ +<div class="md-copyright">
+ + {% if config.copyright %}
+ + <div class="md-copyright__highlight">
+ + {{ config.copyright }}
+ + </div>
+ + {% endif %}
+ + {% if not config.extra.generator == false %}
+ + Made with
+ + <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
+ + Material for MkDocs
+ + </a>
+ + {% endif %}
+ +</div>
+ ```
+
+=== ":octicons-file-code-16: `partials/footer.html`"
+
+ ``` diff
+ @@ -41,21 +40,10 @@
+ {% endif %}
+ <div class="md-footer-meta md-typeset">
+ <div class="md-footer-meta__inner md-grid">
+ - <div class="md-footer-copyright">
+ - {% if config.copyright %}
+ - <div class="md-footer-copyright__highlight">
+ - {{ config.copyright }}
+ - </div>
+ - {% endif %}
+ - {% if not config.extra.generator == false %}
+ - Made with
+ - <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
+ - Material for MkDocs
+ - </a>
+ - {% endif %}
+ - {{ extracopyright }}
+ - </div>
+ - {% include "partials/social.html" %}
+ + {% include "partials/copyright.html" %}
+ + {% if config.extra.social %}
+ + {% include "partials/social.html" %}
+ + {% endif %}
+ </div>
+ </div>
+ </footer>
+ ```
+
+=== ":octicons-file-code-16: `partials/social.html`"
+
+ ``` diff
+ @@ -4,17 +4,15 @@
+ -{% if config.extra.social %}
+ - <div class="md-footer-social">
+ - {% for social in config.extra.social %}
+ - {% set title = social.name %}
+ - {% if not title and "//" in social.link %}
+ - {% set _,url = social.link.split("//") %}
+ - {% set title = url.split("/")[0] %}
+ - {% endif %}
+ - <a href="{{ social.link }}" target="_blank" rel="noopener" title="{{ title | e }}" class="md-footer-social__link">
+ - {% include ".icons/" ~ social.icon ~ ".svg" %}
+ - </a>
+ - {% endfor %}
+ - </div>
+ -{% endif %}
+ +<div class="md-social">
+ + {% for social in config.extra.social %}
+ + {% set title = social.name %}
+ + {% if not title and "//" in social.link %}
+ + {% set _, url = social.link.split("//") %}
+ + {% set title = url.split("/")[0] %}
+ + {% endif %}
+ + <a href="{{ social.link }}" target="_blank" rel="noopener" title="{{ title | e }}" class="md-social__link">
+ + {% include ".icons/" ~ social.icon ~ ".svg" %}
+ + </a>
+ + {% endfor %}
+ +</div>
+ ```
+
+## Upgrading from 6.x to 7.x
+
+### What's new?
+
+- Added support for deploying multiple versions
+- Added support for integrating a language selector
+- Added support for rendering admonitions as inline blocks
+- Rewrite of the underlying reactive architecture
+- Removed Webpack in favor of reactive build strategy (–480 dependencies)
+- Fixed keyboard navigation for code blocks after content tabs switch
+
+### Changes to `mkdocs.yml`
+
+#### `extra.version.method`
+
+The versioning method configuration was renamed to `extra.version.provider` to
+allow for different versioning strategies in the future:
+
+=== "7.x"
+
+ ``` yaml
+ extra:
+ version:
+ provider: mike
+ ```
+
+=== "6.x"
+
+ ``` yaml
+ extra:
+ version:
+ method: mike
+ ```
+
+### Changes to `*.html` files { data-search-exclude }
+
+The templates have undergone a set of changes to make them future-proof. If
+you've used theme extension to override a block or template, make sure that it
+matches the new structure:
+
+- If you've overridden a __block__, check `base.html` for potential changes
+- If you've overridden a __template__, check the respective `*.html` file for
+ potential changes
+
+=== ":octicons-file-code-16: `base.html`"
+
+ ``` diff
+ @@ -61,7 +61,7 @@
+ font.text | replace(' ', '+') + ':300,400,400i,700%7C' +
+ font.code | replace(' ', '+')
+ }}&display=fallback">
+ - <style>body,input{font-family:"{{ font.text }}",-apple-system,BlinkMacSystemFont,Helvetica,Arial,sans-serif}code,kbd,pre{font-family:"{{ font.code }}",SFMono-Regular,Consolas,Menlo,monospace}</style>
+ + <style>:root{--md-text-font-family:"{{ font.text }}";--md-code-font-family:"{{ font.code }}"}</style>
+ {% endif %}
+ {% endblock %}
+ {% if config.extra.manifest %}
+ @@ -131,7 +131,7 @@
+ {% if page and page.meta and page.meta.hide %}
+ {% set hidden = "hidden" if "navigation" in page.meta.hide %}
+ {% endif %}
+ - <div class="md-sidebar md-sidebar--primary" data-md-component="navigation" {{ hidden }}>
+ + <div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" {{ hidden }}>
+ <div class="md-sidebar__scrollwrap">
+ <div class="md-sidebar__inner">
+ {% include "partials/nav.html" %}
+ @@ -143,7 +143,7 @@
+ {% if page and page.meta and page.meta.hide %}
+ {% set hidden = "hidden" if "toc" in page.meta.hide %}
+ {% endif %}
+ - <div class="md-sidebar md-sidebar--secondary" data-md-component="toc" {{ hidden }}>
+ + <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" {{ hidden }}>
+ <div class="md-sidebar__scrollwrap">
+ <div class="md-sidebar__inner">
+ {% include "partials/toc.html" %}
+ @@ -152,7 +152,7 @@
+ </div>
+ {% endif %}
+ {% endblock %}
+ - <div class="md-content">
+ + <div class="md-content" data-md-component="content">
+ <article class="md-content__inner md-typeset">
+ {% block content %}
+ {% if page.edit_url %}
+ @@ -183,10 +183,18 @@
+ {% include "partials/footer.html" %}
+ {% endblock %}
+ </div>
+ - {% block scripts %}
+ - <script src="{{ 'assets/javascripts/vendor.18f0862e.min.js' | url }}"></script>
+ - <script src="{{ 'assets/javascripts/bundle.994580cf.min.js' | url }}"></script>
+ - {%- set translations = {} -%}
+ + <div class="md-dialog" data-md-component="dialog">
+ + <div class="md-dialog__inner md-typeset"></div>
+ + </div>
+ + {% block config %}
+ + {%- set app = {
+ + "base": base_url,
+ + "features": features,
+ + "translations": {},
+ + "search": "assets/javascripts/workers/search.217ffd95.min.js" | url,
+ + "version": config.extra.version or None
+ + } -%}
+ + {%- set translations = app.translations -%}
+ {%- for key in [
+ "clipboard.copy",
+ "clipboard.copied",
+ @@ -204,19 +212,12 @@
+ ] -%}
+ {%- set _ = translations.update({ key: lang.t(key) }) -%}
+ {%- endfor -%}
+ - <script id="__lang" type="application/json">
+ - {{- translations | tojson -}}
+ - </script>
+ - {% block config %}{% endblock %}
+ - <script>
+ - app = initialize({
+ - base: "{{ base_url }}",
+ - features: {{ features or [] | tojson }},
+ - search: Object.assign({
+ - worker: "{{ 'assets/javascripts/worker/search.9c0e82ba.min.js' | url }}"
+ - }, typeof search !== "undefined" && search)
+ - })
+ + <script id="__config" type="application/json">
+ + {{- app | tojson -}}
+ </script>
+ + {% endblock %}
+ + {% block scripts %}
+ + <script src="{{ 'assets/javascripts/bundle.926459b3.min.js' | url }}"></script>
+ {% for path in config["extra_javascript"] %}
+ <script src="{{ path | url }}"></script>
+ {% endfor %}
+ ```
+
+=== ":octicons-file-code-16: `partials/footer.html`"
+
+ ``` diff
+ - <div class="md-footer-nav">
+ - <nav class="md-footer-nav__inner md-grid" aria-label="{{ lang.t('footer.title') }}">
+ - {% if page.previous_page %}
+ - <a href="{{ page.previous_page.url | url }}" class="md-footer-nav__link md-footer-nav__link--prev" rel="prev">
+ - <div class="md-footer-nav__button md-icon">
+ - {% include ".icons/material/arrow-left.svg" %}
+ - </div>
+ - <div class="md-footer-nav__title">
+ - <div class="md-ellipsis">
+ - <span class="md-footer-nav__direction">
+ - {{ lang.t("footer.previous") }}
+ - </span>
+ - {{ page.previous_page.title }}
+ - </div>
+ - </div>
+ - </a>
+ - {% endif %}
+ - {% if page.next_page %}
+ - <a href="{{ page.next_page.url | url }}" class="md-footer-nav__link md-footer-nav__link--next" rel="next">
+ - <div class="md-footer-nav__title">
+ - <div class="md-ellipsis">
+ - <span class="md-footer-nav__direction">
+ - {{ lang.t("footer.next") }}
+ - </span>
+ - {{ page.next_page.title }}
+ - </div>
+ + <nav class="md-footer__inner md-grid" aria-label="{{ lang.t('footer.title') }}">
+ + {% if page.previous_page %}
+ + <a href="{{ page.previous_page.url | url }}" class="md-footer__link md-footer__link--prev" rel="prev">
+ + <div class="md-footer__button md-icon">
+ + {% include ".icons/material/arrow-left.svg" %}
+ + </div>
+ + <div class="md-footer__title">
+ + <div class="md-ellipsis">
+ + <span class="md-footer__direction">
+ + {{ lang.t("footer.previous") }}
+ + </span>
+ + {{ page.previous_page.title }}
+ </div>
+ - <div class="md-footer-nav__button md-icon">
+ - {% include ".icons/material/arrow-right.svg" %}
+ + </div>
+ + </a>
+ + {% endif %}
+ + {% if page.next_page %}
+ + <a href="{{ page.next_page.url | url }}" class="md-footer__link md-footer__link--next" rel="next">
+ + <div class="md-footer__title">
+ + <div class="md-ellipsis">
+ + <span class="md-footer__direction">
+ + {{ lang.t("footer.next") }}
+ + </span>
+ + {{ page.next_page.title }}
+ </div>
+ - </a>
+ - {% endif %}
+ - </nav>
+ - </div>
+ + </div>
+ + <div class="md-footer__button md-icon">
+ + {% include ".icons/material/arrow-right.svg" %}
+ + </div>
+ + </a>
+ + {% endif %}
+ + </nav>
+ {% endif %}
+ <div class="md-footer-meta md-typeset">
+ <div class="md-footer-meta__inner md-grid">
+ ```
+
+=== ":octicons-file-code-16: `partials/header.html`"
+
+ ``` diff
+ @@ -6,21 +6,21 @@
+ {% set site_url = site_url ~ "/index.html" %}
+ {% endif %}
+ <header class="md-header" data-md-component="header">
+ - <nav class="md-header-nav md-grid" aria-label="{{ lang.t('header.title') }}">
+ - <a href="{{ site_url }}" title="{{ config.site_name | e }}" class="md-header-nav__button md-logo" aria-label="{{ config.site_name }}">
+ + <nav class="md-header__inner md-grid" aria-label="{{ lang.t('header.title') }}">
+ + <a href="{{ site_url }}" title="{{ config.site_name | e }}" class="md-header__button md-logo" aria-label="{{ config.site_name }}">
+ {% include "partials/logo.html" %}
+ </a>
+ - <label class="md-header-nav__button md-icon" for="__drawer">
+ + <label class="md-header__button md-icon" for="__drawer">
+ {% include ".icons/material/menu" ~ ".svg" %}
+ </label>
+ - <div class="md-header-nav__title" data-md-component="header-title">
+ - <div class="md-header-nav__ellipsis">
+ - <div class="md-header-nav__topic">
+ + <div class="md-header__title" data-md-component="header-title">
+ + <div class="md-header__ellipsis">
+ + <div class="md-header__topic">
+ <span class="md-ellipsis">
+ {{ config.site_name }}
+ </span>
+ </div>
+ - <div class="md-header-nav__topic">
+ + <div class="md-header__topic" data-md-component="header-topic">
+ <span class="md-ellipsis">
+ {% if page and page.meta and page.meta.title %}
+ {{ page.meta.title }}
+ @@ -31,14 +31,35 @@
+ </div>
+ </div>
+ </div>
+ + <div class="md-header__options">
+ + {% if config.extra.alternate %}
+ + <div class="md-select">
+ + {% set icon = config.theme.icon.alternate or "material/translate" %}
+ + <span class="md-header__button md-icon">
+ + {% include ".icons/" ~ icon ~ ".svg" %}
+ + </span>
+ + <div class="md-select__inner">
+ + <ul class="md-select__list">
+ + {% for alt in config.extra.alternate %}
+ + <li class="md-select__item">
+ + <a href="{{ alt.link | url }}" class="md-select__link">
+ + {{ alt.name }}
+ + </a>
+ + </li>
+ + {% endfor %}
+ + </ul>
+ + </div>
+ + </div>
+ + {% endif %}
+ + </div>
+ {% if "search" in config["plugins"] %}
+ - <label class="md-header-nav__button md-icon" for="__search">
+ + <label class="md-header__button md-icon" for="__search">
+ {% include ".icons/material/magnify.svg" %}
+ </label>
+ {% include "partials/search.html" %}
+ {% endif %}
+ {% if config.repo_url %}
+ - <div class="md-header-nav__source">
+ + <div class="md-header__source">
+ {% include "partials/source.html" %}
+ </div>
+ {% endif %}
+ ```
+
+=== ":octicons-file-code-16: `partials/source.html`"
+
+ ``` diff
+ @@ -4,5 +4,5 @@
+ {% import "partials/language.html" as lang with context %}
+ -<a href="{{ config.repo_url }}" title="{{ lang.t('source.link.title') }}" class="md-source">
+ +<a href="{{ config.repo_url }}" title="{{ lang.t('source.link.title') }}" class="md-source" data-md-component="source">
+ <div class="md-source__icon md-icon">
+ {% set icon = config.theme.icon.repo or "fontawesome/brands/git-alt" %}
+ {% include ".icons/" ~ icon ~ ".svg" %}
+ ```
+
+=== ":octicons-file-code-16: `partials/toc.html`"
+
+ ``` diff
+ @@ -12,7 +12,7 @@
+ <span class="md-nav__icon md-icon"></span>
+ {{ lang.t("toc.title") }}
+ </label>
+ - <ul class="md-nav__list" data-md-scrollfix>
+ + <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
+ {% for toc_item in toc %}
+ {% include "partials/toc-item.html" %}
+ {% endfor %}
+ ```
+
+## Upgrading from 5.x to 6.x
+
+### What's new?
+
+- Improved search result look and feel
+- Improved search result stability while typing
+- Improved search result grouping (pages + headings)
+- Improved search result relevance and scoring
+- Added display of missing query terms to search results
+- Reduced size of vendor bundle by 25% (84kb → 67kb)
+- Reduced size of the Docker image to improve CI build performance
+- Removed hero partial in favor of custom implementation
+- Removed deprecated front matter features
+
+### Changes to `mkdocs.yml`
+
+Following is a list of changes that need to be made to `mkdocs.yml`. Note that
+you only have to adjust the value if you defined it, so if your configuration
+does not contain the key, you can skip it.
+
+#### `theme.features`
+
+All feature flags that can be set from `mkdocs.yml`, like [tabs] and
+[instant loading], are now prefixed with the name of the component or
+function they apply to, e.g. `navigation.*`:
+
+=== "6.x"
+
+ ``` yaml
+ theme:
+ features:
+ - navigation.tabs
+ - navigation.instant
+ ```
+
+=== "5.x"
+
+ ``` yaml
+ theme:
+ features:
+ - tabs
+ - instant
+ ```
+
+ [tabs]: setup/setting-up-navigation.md#navigation-tabs
+ [instant loading]: setup/setting-up-navigation.md#instant-loading
+
+### Changes to `*.html` files { data-search-exclude }
+
+The templates have undergone a set of changes to make them future-proof. If
+you've used theme extension to override a block or template, make sure that it
+matches the new structure:
+
+- If you've overridden a __block__, check `base.html` for potential changes
+- If you've overridden a __template__, check the respective `*.html` file for
+ potential changes
+
+=== ":octicons-file-code-16: `base.html`"
+
+ ``` diff
+ @@ -22,13 +22,6 @@
+
+ {% import "partials/language.html" as lang with context %}
+
+ -<!-- Theme options -->
+ -{% set palette = config.theme.palette %}
+ -{% if not palette is mapping %}
+ - {% set palette = palette | first %}
+ -{% endif %}
+ -{% set font = config.theme.font %}
+ -
+ <!doctype html>
+ <html lang="{{ lang.t('language') }}" class="no-js">
+ <head>
+ @@ -45,21 +38,8 @@
+ <meta name="description" content="{{ config.site_description }}" />
+ {% endif %}
+
+ - <!-- Redirect -->
+ - {% if page and page.meta and page.meta.redirect %}
+ - <script>
+ - var anchor = window.location.hash.substr(1)
+ - location.href = '{{ page.meta.redirect }}' +
+ - (anchor ? '#' + anchor : '')
+ - </script>
+ -
+ - <!-- Fallback in case JavaScript is not available -->
+ - <meta http-equiv="refresh" content="0; url={{ page.meta.redirect }}" />
+ - <meta name="robots" content="noindex" />
+ - <link rel="canonical" href="{{ page.meta.redirect }}" />
+ -
+ <!-- Canonical -->
+ - {% elif page.canonical_url %}
+ + {% if page.canonical_url %}
+ <link rel="canonical" href="{{ page.canonical_url }}" />
+ {% endif %}
+
+ @@ -96,20 +76,21 @@
+ <link rel="stylesheet" href="{{ 'assets/stylesheets/main.css' | url }}" />
+
+ <!-- Extra color palette -->
+ - {% if palette.scheme or palette.primary or palette.accent %}
+ + {% if config.theme.palette %}
+ + {% set palette = config.theme.palette %}
+ <link
+ rel="stylesheet"
+ href="{{ 'assets/stylesheets/palette.css' | url }}"
+ />
+ - {% endif %}
+
+ - <!-- Theme-color meta tag for Android -->
+ - {% if palette.primary %}
+ - {% import "partials/palette.html" as map %}
+ - {% set primary = map.primary(
+ - palette.primary | replace(" ", "-") | lower
+ - ) %}
+ - <meta name="theme-color" content="{{ primary }}" />
+ + <!-- Theme-color meta tag for Android -->
+ + {% if palette.primary %}
+ + {% import "partials/palette.html" as map %}
+ + {% set primary = map.primary(
+ + palette.primary | replace(" ", "-") | lower
+ + ) %}
+ + <meta name="theme-color" content="{{ primary }}" />
+ + {% endif %}
+ {% endif %}
+ {% endblock %}
+
+ @@ -120,7 +101,8 @@
+ {% block fonts %}
+
+ <!-- Load fonts from Google -->
+ - {% if font != false %}
+ + {% if config.theme.font != false %}
+ + {% set font = config.theme.font %}
+ <link href="https://fonts.gstatic.com" rel="preconnect" crossorigin />
+ <link
+ rel="stylesheet"
+ @@ -169,8 +151,12 @@
+
+ <!-- Text direction and color palette, if defined -->
+ {% set direction = config.theme.direction or lang.t('direction') %}
+ - {% if palette.scheme or palette.primary or palette.accent %}
+ - {% set scheme = palette.scheme | lower %}
+ + {% if config.theme.palette %}
+ + {% set palette = config.theme.palette %}
+ + {% if not palette is mapping %}
+ + {% set palette = palette | first %}
+ + {% endif %}
+ + {% set scheme = palette.scheme | replace(" ", "-") | lower %}
+ {% set primary = palette.primary | replace(" ", "-") | lower %}
+ {% set accent = palette.accent | replace(" ", "-") | lower %}
+ <body
+ @@ -179,18 +165,19 @@
+ data-md-color-primary="{{ primary }}"
+ data-md-color-accent="{{ accent }}"
+ >
+ +
+ + <!-- Experimental: set color scheme based on preference -->
+ + {% if "preference" == scheme %}
+ + <script>
+ + if (matchMedia("(prefers-color-scheme: dark)").matches)
+ + document.body.setAttribute("data-md-color-scheme", "slate")
+ + </script>
+ + {% endif %}
+ +
+ {% else %}
+ <body dir="{{ direction }}">
+ {% endif %}
+
+ - <!-- Experimental: set color scheme based on preference -->
+ - {% if "preference" == palette.scheme %}
+ - <script>
+ - if (matchMedia("(prefers-color-scheme: dark)").matches)
+ - document.body.setAttribute("data-md-color-scheme", "slate")
+ - </script>
+ - {% endif %}
+ -
+ <!--
+ State toggles - we need to set autocomplete="off" in order to reset the
+ drawer on back button invocation in some browsers
+ @@ -243,15 +230,11 @@
+ <div class="md-container" data-md-component="container">
+
+ <!-- Hero teaser -->
+ - {% block hero %}
+ - {% if page and page.meta and page.meta.hero %}
+ - {% include "partials/hero.html" with context %}
+ - {% endif %}
+ - {% endblock %}
+ + {% block hero %}{% endblock %}
+
+ <!-- Tabs navigation -->
+ {% block tabs %}
+ - {% if "tabs" in config.theme.features %}
+ + {% if "navigation.tabs" in config.theme.features %}
+ {% include "partials/tabs.html" %}
+ {% endif %}
+ {% endblock %}
+ @@ -310,13 +293,6 @@
+ </a>
+ {% endif %}
+
+ - <!-- Link to source file -->
+ - {% block source %}
+ - {% if page and page.meta and page.meta.source %}
+ - {% include "partials/source-link.html" %}
+ - {% endif %}
+ - {% endblock %}
+ -
+ <!--
+ Hack: check whether the content contains a h1 headline. If it
+ doesn't, the page title (or respectively site name) is used
+ @@ -370,7 +346,10 @@
+ "search.result.placeholder",
+ "search.result.none",
+ "search.result.one",
+ - "search.result.other"
+ + "search.result.other",
+ + "search.result.more.one",
+ + "search.result.more.other",
+ + "search.result.term.missing"
+ ] -%}
+ {%- set _ = translations.update({ key: lang.t(key) }) -%}
+ {%- endfor -%}
+ ```
+
+=== ":octicons-file-code-16: `partials/hero.html`"
+
+ ``` diff
+ @@ -1,12 +0,0 @@
+ -{#-
+ - This file was automatically generated - do not edit
+ --#}
+ -{% set class = "md-hero" %}
+ -{% if "tabs" not in config.theme.features %}
+ - {% set class = "md-hero md-hero--expand" %}
+ -{% endif %}
+ -<div class="{{ class }}" data-md-component="hero">
+ - <div class="md-hero__inner md-grid">
+ - {{ page.meta.hero }}
+ - </div>
+ -</div>
+ ```
+
+=== ":octicons-file-code-16: `partials/source-link`"
+
+ ``` diff
+ @@ -1,14 +0,0 @@
+ -{#-
+ - This file was automatically generated - do not edit
+ --#}
+ -{% import "partials/language.html" as lang with context %}
+ -{% set repo = config.repo_url %}
+ -{% if repo | last == "/" %}
+ - {% set repo = repo[:-1] %}
+ -{% endif %}
+ -{% set path = page.meta.path | default("") %}
+ -<a href="{{ [repo, path, page.meta.source] | join('/') }}" title="{{ page.meta.source }}" class="md-content__button md-icon">
+ - {{ lang.t("meta.source") }}
+ - {% set icon = config.theme.icon.repo or "fontawesome/brands/git-alt" %}
+ - {% include ".icons/" ~ icon ~ ".svg" %}
+ -</a>
+ ```
+
+## Upgrading from 4.x to 5.x
+
+### What's new?
+
+- Reactive architecture – try `#!js app.dialog$.next("Hi!")` in the console
+- [Instant loading] – make Material behave like a Single Page Application
+- Improved CSS customization with [CSS variables] – set your brand's colors
+- Improved CSS resilience, e.g. proper sidebar locking for customized headers
+- Improved [icon integration] and configuration – now including over 5k icons
+- Added possibility to use any icon for logo, repository and social links
+- Search UI does not freeze anymore (moved to web worker)
+- Search index built only once when using instant loading
+- Improved extensible keyboard handling
+- Support for [prebuilt search indexes]
+- Support for displaying stars and forks for GitLab repositories
+- Support for scroll snapping of sidebars and search results
+- Reduced HTML and CSS footprint due to deprecation of Internet Explorer support
+- Slight facelifting of some UI elements (admonitions, tables, ...)
+
+ [CSS variables]: setup/changing-the-colors.md#custom-colors
+ [icon integration]: reference/icons-emojis.md#search
+ [prebuilt search indexes]: plugins/search.md
+
+### Changes to `mkdocs.yml`
+
+Following is a list of changes that need to be made to `mkdocs.yml`. Note that
+you only have to adjust the value if you defined it, so if your configuration
+does not contain the key, you can skip it.
+
+#### `theme.feature`
+
+Optional features like [tabs] and [instant loading] are now implemented as
+flags and can be enabled by listing them in `mkdocs.yml` under `theme.features`:
+
+=== "5.x"
+
+ ``` yaml
+ theme:
+ features:
+ - tabs
+ - instant
+ ```
+
+=== "4.x"
+
+ ``` yaml
+ theme:
+ feature:
+ tabs: true
+ ```
+
+#### `theme.logo.icon`
+
+The logo icon configuration was centralized under `theme.icon.logo` and can now
+be set to any of the [icons bundled with the theme][icon integration]:
+
+=== "5.x"
+
+ ``` yaml
+ theme:
+ icon:
+ logo: material/cloud
+ ```
+
+=== "4.x"
+
+ ``` yaml
+ theme:
+ logo:
+ icon: cloud
+ ```
+
+#### `extra.repo_icon`
+
+The repo icon configuration was centralized under `theme.icon.repo` and can now
+be set to any of the [icons bundled with the theme][icon integration]:
+
+=== "5.x"
+
+ ``` yaml
+ theme:
+ icon:
+ repo: fontawesome/brands/gitlab
+ ```
+
+=== "4.x"
+
+ ``` yaml
+ extra:
+ repo_icon: gitlab
+ ```
+
+#### `extra.search.*`
+
+Search is now configured as part of the [plugin options]. Note that the
+search languages must now be listed as an array of strings and the `tokenizer`
+was renamed to `separator`:
+
+=== "5.x"
+
+ ``` yaml
+ plugins:
+ - search:
+ separator: '[\s\-\.]+'
+ lang:
+ - en
+ - de
+ - ru
+ ```
+
+=== "4.x"
+
+ ``` yaml
+ extra:
+ search:
+ language: en, de, ru
+ tokenizer: '[\s\-\.]+'
+ ```
+
+ [plugin options]: plugins/search.md
+
+#### `extra.social.*`
+
+Social links stayed in the same place, but the `type` key was renamed to `icon`
+in order to match the new way of specifying which icon to be used:
+
+=== "5.x"
+
+ ``` yaml
+ extra:
+ social:
+ - icon: fontawesome/brands/github-alt
+ link: https://github.com/squidfunk
+ ```
+
+=== "4.x"
+
+ ``` yaml
+ extra:
+ social:
+ - type: github
+ link: https://github.com/squidfunk
+ ```
+
+### Changes to `*.html` files { data-search-exclude }
+
+The templates have undergone a set of changes to make them future-proof. If
+you've used theme extension to override a block or template, make sure that it
+matches the new structure:
+
+- If you've overridden a __block__, check `base.html` for potential changes
+- If you've overridden a __template__, check the respective `*.html` file for
+ potential changes
+
+=== ":octicons-file-code-16: `base.html`"
+
+ ``` diff
+ @@ -4,7 +4,6 @@
+ {% import "partials/language.html" as lang with context %}
+ -{% set feature = config.theme.feature %}
+ {% set palette = config.theme.palette %}
+ {% set font = config.theme.font %}
+ <!doctype html>
+ @@ -30,19 +29,6 @@
+ {% elif config.site_author %}
+ <meta name="author" content="{{ config.site_author }}">
+ {% endif %}
+ - {% for key in [
+ - "clipboard.copy",
+ - "clipboard.copied",
+ - "search.language",
+ - "search.pipeline.stopwords",
+ - "search.pipeline.trimmer",
+ - "search.result.none",
+ - "search.result.one",
+ - "search.result.other",
+ - "search.tokenizer"
+ - ] %}
+ - <meta name="lang:{{ key }}" content="{{ lang.t(key) }}">
+ - {% endfor %}
+ <link rel="shortcut icon" href="{{ config.theme.favicon | url }}">
+ <meta name="generator" content="mkdocs-{{ mkdocs_version }}, mkdocs-material-5.0.0">
+ {% endblock %}
+ @@ -56,9 +42,9 @@
+ {% endif %}
+ {% endblock %}
+ {% block styles %}
+ - <link rel="stylesheet" href="{{ 'assets/stylesheets/application.********.css' | url }}">
+ + <link rel="stylesheet" href="{{ 'assets/stylesheets/main.********.min.css' | url }}">
+ {% if palette.primary or palette.accent %}
+ - <link rel="stylesheet" href="{{ 'assets/stylesheets/application-palette.********.css' | url }}">
+ + <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.********.min.css' | url }}">
+ {% endif %}
+ {% if palette.primary %}
+ {% import "partials/palette.html" as map %}
+ @@ -69,20 +55,17 @@
+ {% endif %}
+ {% endblock %}
+ {% block libs %}
+ - <script src="{{ 'assets/javascripts/modernizr.********.js' | url }}"></script>
+ {% endblock %}
+ {% block fonts %}
+ {% if font != false %}
+ <link href="https://fonts.gstatic.com" rel="preconnect" crossorigin>
+ <link rel="stylesheet" href="https://fonts.googleapis.com/css?family={{
+ font.text | replace(' ', '+') + ':300,400,400i,700%7C' +
+ font.code | replace(' ', '+')
+ }}&display=fallback">
+ <style>body,input{font-family:"{{ font.text }}","Helvetica Neue",Helvetica,Arial,sans-serif}code,kbd,pre{font-family:"{{ font.code }}","Courier New",Courier,monospace}</style>
+ {% endif %}
+ {% endblock %}
+ - <link rel="stylesheet" href="{{ 'assets/fonts/material-icons.css' | url }}">
+ {% if config.extra.manifest %}
+ <link rel="manifest" href="{{ config.extra.manifest | url }}" crossorigin="use-credentials">
+ {% endif %}
+ @@ -95,47 +77,50 @@
+ {% endblock %}
+ {% block extrahead %}{% endblock %}
+ </head>
+ + {% set direction = config.theme.direction | default(lang.t('direction')) %}
+ {% if palette.primary or palette.accent %}
+ {% set primary = palette.primary | replace(" ", "-") | lower %}
+ {% set accent = palette.accent | replace(" ", "-") | lower %}
+ - <body dir="{{ lang.t('direction') }}" data-md-color-primary="{{ primary }}" data-md-color-accent="{{ accent }}">
+ + <body dir="{{ direction }}" data-md-color-primary="{{ primary }}" data-md-color-accent="{{ accent }}">
+ {% else %}
+ - <body dir="{{ lang.t('direction') }}">
+ + <body dir="{{ direction }}">
+ {% endif %}
+ - <svg class="md-svg">
+ - <defs>
+ - {% set platform = config.extra.repo_icon or config.repo_url %}
+ - {% if "github" in platform %}
+ - {% include "assets/images/icons/github.f0b8504a.svg" %}
+ - {% elif "gitlab" in platform %}
+ - {% include "assets/images/icons/gitlab.6dd19c00.svg" %}
+ - {% elif "bitbucket" in platform %}
+ - {% include "assets/images/icons/bitbucket.1b09e088.svg" %}
+ - {% endif %}
+ - </defs>
+ - </svg>
+ <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
+ <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
+ - <label class="md-overlay" data-md-component="overlay" for="__drawer"></label>
+ + <label class="md-overlay" for="__drawer"></label>
+ + <div data-md-component="skip">
+ + {% if page.toc | first is defined %}
+ + {% set skip = page.toc | first %}
+ + <a href="{{ skip.url | url }}" class="md-skip">
+ + {{ lang.t('skip.link.title') }}
+ + </a>
+ + {% endif %}
+ + </div>
+ + <div data-md-component="announce">
+ + {% if self.announce() %}
+ + <aside class="md-announce">
+ + <div class="md-announce__inner md-grid md-typeset">
+ + {% block announce %}{% endblock %}
+ + </div>
+ + </aside>
+ + {% endif %}
+ + </div>
+ {% block header %}
+ {% include "partials/header.html" %}
+ {% endblock %}
+ - <div class="md-container">
+ + <div class="md-container" data-md-component="container">
+ {% block hero %}
+ {% if page and page.meta and page.meta.hero %}
+ {% include "partials/hero.html" with context %}
+ {% endif %}
+ {% endblock %}
+ - {% if feature.tabs %}
+ - {% include "partials/tabs.html" %}
+ - {% endif %}
+ + {% block tabs %}
+ + {% if "tabs" in config.theme.features %}
+ + {% include "partials/tabs.html" %}
+ + {% endif %}
+ + {% endblock %}
+ - <main class="md-main" role="main">
+ - <div class="md-main__inner md-grid" data-md-component="container">
+ + <main class="md-main" data-md-component="main">
+ + <div class="md-main__inner md-grid">
+ {% block site_nav %}
+ {% if nav %}
+ <div class="md-sidebar md-sidebar--primary" data-md-component="navigation">
+ @@ -160,41 +141,25 @@
+ <article class="md-content__inner md-typeset">
+ {% block content %}
+ {% if page.edit_url %}
+ - <a href="{{ page.edit_url }}" title="{{ lang.t('edit.link.title') }}" class="md-icon md-content__icon"></a>
+ + <a href="{{ page.edit_url }}" title="{{ lang.t('edit.link.title') }}" class="md-content__button md-icon">
+ + {% include ".icons/material/pencil.svg" %}
+ + </a>
+ {% endif %}
+ + {% block source %}
+ + {% if page and page.meta and page.meta.source %}
+ + {% include "partials/source-link.html" %}
+ + {% endif %}
+ + {% endblock %}
+ {% if not "\x3ch1" in page.content %}
+ <h1>{{ page.title | default(config.site_name, true)}}</h1>
+ {% endif %}
+ {{ page.content }}
+ - {% block source %}
+ - {% if page and page.meta and page.meta.source %}
+ - <h2 id="__source">{{ lang.t("meta.source") }}</h2>
+ - {% set repo = config.repo_url %}
+ - {% if repo | last == "/" %}
+ - {% set repo = repo[:-1] %}
+ - {% endif %}
+ - {% set path = page.meta.path | default([""]) %}
+ - {% set file = page.meta.source %}
+ - <a href="{{ [repo, path, file] | join('/') }}" title="{{ file }}" class="md-source-file">
+ - {{ file }}
+ - </a>
+ - {% endif %}
+ - {% endblock %}
+ + {% if page and page.meta %}
+ + {% if page.meta.git_revision_date_localized or
+ + page.meta.revision_date
+ + %}
+ + {% include "partials/source-date.html" %}
+ - {% if page and page.meta and (
+ - page.meta.git_revision_date_localized or
+ - page.meta.revision_date
+ - ) %}
+ - {% set label = lang.t("source.revision.date") %}
+ - <hr>
+ - <div class="md-source-date">
+ - <small>
+ - {% if page.meta.git_revision_date_localized %}
+ - {{ label }}: {{ page.meta.git_revision_date_localized }}
+ - {% elif page.meta.revision_date %}
+ - {{ label }}: {{ page.meta.revision_date }}
+ - {% endif %}
+ - </small>
+ - </div>
+ {% endif %}
+ {% endblock %}
+ {% block disqus %}
+ @@ -208,29 +174,35 @@
+ {% include "partials/footer.html" %}
+ {% endblock %}
+ </div>
+ {% block scripts %}
+ - <script src="{{ 'assets/javascripts/application.********.js' | url }}"></script>
+ - {% if lang.t("search.language") != "en" %}
+ - {% set languages = lang.t("search.language").split(",") %}
+ - {% if languages | length and languages[0] != "" %}
+ - {% set path = "assets/javascripts/lunr/" %}
+ - <script src="{{ (path ~ 'lunr.stemmer.support.js') | url }}"></script>
+ - {% for language in languages | map("trim") %}
+ - {% if language != "en" %}
+ - {% if language == "ja" %}
+ - <script src="{{ (path ~ 'tinyseg.js') | url }}"></script>
+ - {% endif %}
+ - {% if language in ("ar", "da", "de", "es", "fi", "fr", "hu", "it", "ja", "nl", "no", "pt", "ro", "ru", "sv", "th", "tr", "vi") %}
+ - <script src="{{ (path ~ 'lunr.' ~ language ~ '.js') | url }}"></script>
+ - {% endif %}
+ - {% endif %}
+ - {% endfor %}
+ - {% if languages | length > 1 %}
+ - <script src="{{ (path ~ 'lunr.multi.js') | url }}"></script>
+ - {% endif %}
+ - {% endif %}
+ - {% endif %}
+ - <script>app.initialize({version:"{{ mkdocs_version }}",url:{base:"{{ base_url }}"}})</script>
+ + <script src="{{ 'assets/javascripts/vendor.********.min.js' | url }}"></script>
+ + <script src="{{ 'assets/javascripts/bundle.********.min.js' | url }}"></script>
+ + {%- set translations = {} -%}
+ + {%- for key in [
+ + "clipboard.copy",
+ + "clipboard.copied",
+ + "search.config.lang",
+ + "search.config.pipeline",
+ + "search.config.separator",
+ + "search.result.placeholder",
+ + "search.result.none",
+ + "search.result.one",
+ + "search.result.other"
+ + ] -%}
+ + {%- set _ = translations.update({ key: lang.t(key) }) -%}
+ + {%- endfor -%}
+ + <script id="__lang" type="application/json">
+ + {{- translations | tojson -}}
+ + </script>
+ + {% block config %}{% endblock %}
+ + <script>
+ + app = initialize({
+ + base: "{{ base_url }}",
+ + features: {{ config.theme.features | tojson }},
+ + search: Object.assign({
+ + worker: "{{ 'assets/javascripts/worker/search.********.min.js' | url }}"
+ + }, typeof search !== "undefined" && search)
+ + })
+ + </script>
+ {% for path in config["extra_javascript"] %}
+ <script src="{{ path | url }}"></script>
+ {% endfor %}
+ ```
+
+=== ":octicons-file-code-16: `partials/footer.html`"
+
+ ``` diff
+ @@ -5,34 +5,34 @@
+ <div class="md-footer-nav">
+ - <nav class="md-footer-nav__inner md-grid">
+ + <nav class="md-footer-nav__inner md-grid" aria-label="{{ lang.t('footer.title') }}">
+ {% if page.previous_page %}
+ - <a href="{{ page.previous_page.url | url }}" title="{{ page.previous_page.title | striptags }}" class="md-flex md-footer-nav__link md-footer-nav__link--prev" rel="prev">
+ - <div class="md-flex__cell md-flex__cell--shrink">
+ - <i class="md-icon md-icon--arrow-back md-footer-nav__button"></i>
+ + <a href="{{ page.previous_page.url | url }}" title="{{ page.previous_page.title | striptags }}" class="md-footer-nav__link md-footer-nav__link--prev" rel="prev">
+ + <div class="md-footer-nav__button md-icon">
+ + {% include ".icons/material/arrow-left.svg" %}
+ </div>
+ - <div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title">
+ - <span class="md-flex__ellipsis">
+ + <div class="md-footer-nav__title">
+ + <div class="md-ellipsis">
+ <span class="md-footer-nav__direction">
+ {{ lang.t("footer.previous") }}
+ </span>
+ {{ page.previous_page.title }}
+ - </span>
+ + </div>
+ </div>
+ </a>
+ {% endif %}
+ {% if page.next_page %}
+ - <a href="{{ page.next_page.url | url }}" title="{{ page.next_page.title | striptags }}" class="md-flex md-footer-nav__link md-footer-nav__link--next" rel="next">
+ - <div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title">
+ - <span class="md-flex__ellipsis">
+ + <a href="{{ page.next_page.url | url }}" title="{{ page.next_page.title | striptags }}" class="md-footer-nav__link md-footer-nav__link--next" rel="next">
+ + <div class="md-footer-nav__title">
+ + <div class="md-ellipsis">
+ <span class="md-footer-nav__direction">
+ {{ lang.t("footer.next") }}
+ </span>
+ {{ page.next_page.title }}
+ - </span>
+ + </div>
+ </div>
+ - <div class="md-flex__cell md-flex__cell--shrink">
+ - <i class="md-icon md-icon--arrow-forward md-footer-nav__button"></i>
+ + <div class="md-footer-nav__button md-icon">
+ + {% include ".icons/material/arrow-right.svg" %}
+ </div>
+ </a>
+ {% endif %}
+ ```
+
+=== ":octicons-file-code-16: `partials/header.html`"
+
+ ``` diff
+ @@ -4,51 +4,43 @@
+ <header class="md-header" data-md-component="header">
+ - <nav class="md-header-nav md-grid">
+ - <div class="md-flex">
+ - <div class="md-flex__cell md-flex__cell--shrink">
+ - <a href="{{ config.site_url | default(nav.homepage.url, true) | url }}" title="{{ config.site_name }}" aria-label="{{ config.site_name }}" class="md-header-nav__button md-logo">
+ - {% if config.theme.logo.icon %}
+ - <i class="md-icon">{{ config.theme.logo.icon }}</i>
+ - {% else %}
+ - <img alt="logo" src="{{ config.theme.logo | url }}" width="24" height="24">
+ - {% endif %}
+ - </a>
+ - </div>
+ - <div class="md-flex__cell md-flex__cell--shrink">
+ - <label class="md-icon md-icon--menu md-header-nav__button" for="__drawer"></label>
+ - </div>
+ - <div class="md-flex__cell md-flex__cell--stretch">
+ - <div class="md-flex__ellipsis md-header-nav__title" data-md-component="title">
+ - {% if config.site_name == page.title %}
+ - {{ config.site_name }}
+ - {% else %}
+ - <span class="md-header-nav__topic">
+ - {{ config.site_name }}
+ - </span>
+ - <span class="md-header-nav__topic">
+ - {% if page and page.meta and page.meta.title %}
+ - {{ page.meta.title }}
+ - {% else %}
+ - {{ page.title }}
+ - {% endif %}
+ - </span>
+ - {% endif %}
+ + <nav class="md-header-nav md-grid" aria-label="{{ lang.t('header.title') }}">
+ + <a href="{{ config.site_url | default(nav.homepage.url, true) | url }}" title="{{ config.site_name }}" class="md-header-nav__button md-logo" aria-label="{{ config.site_name }}">
+ + {% include "partials/logo.html" %}
+ + </a>
+ + <label class="md-header-nav__button md-icon" for="__drawer">
+ + {% include ".icons/material/menu" ~ ".svg" %}
+ + </label>
+ + <div class="md-header-nav__title" data-md-component="header-title">
+ + {% if config.site_name == page.title %}
+ + <div class="md-header-nav__ellipsis md-ellipsis">
+ + {{ config.site_name }}
+ </div>
+ - </div>
+ - <div class="md-flex__cell md-flex__cell--shrink">
+ - {% if "search" in config["plugins"] %}
+ - <label class="md-icon md-icon--search md-header-nav__button" for="__search"></label>
+ - {% include "partials/search.html" %}
+ - {% endif %}
+ - </div>
+ - {% if config.repo_url %}
+ - <div class="md-flex__cell md-flex__cell--shrink">
+ - <div class="md-header-nav__source">
+ - {% include "partials/source.html" %}
+ - </div>
+ + {% else %}
+ + <div class="md-header-nav__ellipsis">
+ + <span class="md-header-nav__topic md-ellipsis">
+ + {{ config.site_name }}
+ + </span>
+ + <span class="md-header-nav__topic md-ellipsis">
+ + {% if page and page.meta and page.meta.title %}
+ + {{ page.meta.title }}
+ + {% else %}
+ + {{ page.title }}
+ + {% endif %}
+ + </span>
+ </div>
+ {% endif %}
+ </div>
+ + {% if "search" in config["plugins"] %}
+ + <label class="md-header-nav__button md-icon" for="__search">
+ + {% include ".icons/material/magnify.svg" %}
+ + </label>
+ + {% include "partials/search.html" %}
+ + {% endif %}
+ + {% if config.repo_url %}
+ + <div class="md-header-nav__source">
+ + {% include "partials/source.html" %}
+ + </div>
+ + {% endif %}
+ </nav>
+ </header>
+ ```
+
+=== ":octicons-file-code-16: `partials/hero.html`"
+
+ ``` diff
+ @@ -4,9 +4,8 @@
+ -{% set feature = config.theme.feature %}
+ {% set class = "md-hero" %}
+ -{% if not feature.tabs %}
+ +{% if "tabs" not in config.theme.features %}
+ {% set class = "md-hero md-hero--expand" %}
+ {% endif %}
+ <div class="{{ class }}" data-md-component="hero">
+ ```
+
+=== ":octicons-file-code-16: `partials/language.html`"
+
+ ``` diff
+ @@ -4,12 +4,4 @@
+ {% import "partials/language/" + config.theme.language + ".html" as lang %}
+ {% import "partials/language/en.html" as fallback %}
+ -{% macro t(key) %}{{ {
+ - "direction": config.theme.direction,
+ - "search.language": (
+ - config.extra.search | default({})
+ - ).language,
+ - "search.tokenizer": (
+ - config.extra.search | default({})
+ - ).tokenizer | default("", true),
+ -}[key] or lang.t(key) or fallback.t(key) }}{% endmacro %}
+ +{% macro t(key) %}{{ lang.t(key) | default(fallback.t(key)) }}{% endmacro %}
+ ```
+
+=== ":octicons-file-code-16: `partials/logo.html`"
+
+ ``` diff
+ @@ -0,0 +1,9 @@
+ +{#-
+ + This file was automatically generated - do not edit
+ +-#}
+ +{% if config.theme.logo %}
+ + <img src="{{ config.theme.logo | url }}" alt="logo">
+ +{% else %}
+ + {% set icon = config.theme.icon.logo or "material/library" %}
+ + {% include ".icons/" ~ icon ~ ".svg" %}
+ +{% endif %}
+ ```
+
+=== ":octicons-file-code-16: `partials/nav-item.html`"
+
+ ``` diff
+ @@ -14,9 +14,15 @@
+ {% endif %}
+ <label class="md-nav__link" for="{{ path }}">
+ {{ nav_item.title }}
+ + <span class="md-nav__icon md-icon">
+ + {% include ".icons/material/chevron-right.svg" %}
+ + </span>
+ </label>
+ - <nav class="md-nav" data-md-component="collapsible" data-md-level="{{ level }}">
+ + <nav class="md-nav" aria-label="{{ nav_item.title }}" data-md-level="{{ level }}">
+ <label class="md-nav__title" for="{{ path }}">
+ + <span class="md-nav__icon md-icon">
+ + {% include ".icons/material/arrow-left.svg" %}
+ + </span>
+ {{ nav_item.title }}
+ </label>
+ <ul class="md-nav__list" data-md-scrollfix>
+ @@ -39,6 +45,9 @@
+ {% if toc | first is defined %}
+ <label class="md-nav__link md-nav__link--active" for="__toc">
+ {{ nav_item.title }}
+ + <span class="md-nav__icon md-icon">
+ + {% include ".icons/material/table-of-contents.svg" %}
+ + </span>
+ </label>
+ {% endif %}
+ <a href="{{ nav_item.url | url }}" title="{{ nav_item.title | striptags }}" class="md-nav__link md-nav__link--active">
+ ```
+
+=== ":octicons-file-code-16: `partials/nav.html`"
+
+ ``` diff
+ @@ -4,14 +4,10 @@
+ -<nav class="md-nav md-nav--primary" data-md-level="0">
+ - <label class="md-nav__title md-nav__title--site" for="__drawer">
+ - <a href="{{ config.site_url | default(nav.homepage.url, true) | url }}" title="{{ config.site_name }}" class="md-nav__button md-logo">
+ - {% if config.theme.logo.icon %}
+ - <i class="md-icon">{{ config.theme.logo.icon }}</i>
+ - {% else %}
+ - <img alt="logo" src="{{ config.theme.logo | url }}" width="48" height="48">
+ - {% endif %}
+ +<nav class="md-nav md-nav--primary" aria-label="{{ lang.t('nav.title') }}" data-md-level="0">
+ + <label class="md-nav__title" for="__drawer">
+ + <a href="{{ config.site_url | default(nav.homepage.url, true) | url }}" title="{{ config.site_name }}" class="md-nav__button md-logo" aria-label="{{ config.site_name }}">
+ + {% include "partials/logo.html" %}
+ </a>
+ {{ config.site_name }}
+ </label>
+ ```
+
+=== ":octicons-file-code-16: `partials/search.html`"
+
+ ``` diff
+ @@ -6,15 +6,18 @@
+ <label class="md-search__overlay" for="__search"></label>
+ <div class="md-search__inner" role="search">
+ <form class="md-search__form" name="search">
+ - <input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="{{ lang.t('search.placeholder') }}" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="query" data-md-state="active">
+ + <input type="text" class="md-search__input" name="query" aria-label="{{ lang.t('search.placeholder') }}" placeholder="{{ lang.t('search.placeholder') }}" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" data-md-state="active">
+ <label class="md-search__icon md-icon" for="__search">
+ + {% include ".icons/material/magnify.svg" %}
+ + {% include ".icons/material/arrow-left.svg" %}
+ </label>
+ - <button type="reset" class="md-icon md-search__icon" data-md-component="reset" tabindex="-1">
+ - 
+ + <button type="reset" class="md-search__icon md-icon" aria-label="{{ lang.t('search.reset') }}" data-md-component="search-reset" tabindex="-1">
+ + {% include ".icons/material/close.svg" %}
+ </button>
+ </form>
+ <div class="md-search__output">
+ <div class="md-search__scrollwrap" data-md-scrollfix>
+ - <div class="md-search-result" data-md-component="result">
+ + <div class="md-search-result" data-md-component="search-result">
+ <div class="md-search-result__meta">
+ {{ lang.t("search.result.placeholder") }}
+ </div>
+ ```
+
+=== ":octicons-file-code-16: `partials/social.html`"
+
+ ``` diff
+ @@ -4,9 +4,12 @@
+ {% if config.extra.social %}
+ <div class="md-footer-social">
+ - <link rel="stylesheet" href="{{ 'assets/fonts/font-awesome.css' | url }}">
+ {% for social in config.extra.social %}
+ - <a href="{{ social.link }}" target="_blank" rel="noopener" title="{{ social.type }}" class="md-footer-social__link fa fa-{{ social.type }}"></a>
+ + {% set _,rest = social.link.split("//") %}
+ + {% set domain = rest.split("/")[0] %}
+ + <a href="{{ social.link }}" target="_blank" rel="noopener" title="{{ domain }}" class="md-footer-social__link">
+ + {% include ".icons/" ~ social.icon ~ ".svg" %}
+ + </a>
+ {% endfor %}
+ </div>
+ {% endif %}
+ ```
+
+=== ":octicons-file-code-16: `partials/source-date.html`"
+
+ ``` diff
+ @@ -0,0 +1,15 @@
+ +{#-
+ + This file was automatically generated - do not edit
+ +-#}
+ +{% import "partials/language.html" as lang with context %}
+ +{% set label = lang.t("source.revision.date") %}
+ +<hr>
+ +<div class="md-source-date">
+ + <small>
+ + {% if page.meta.git_revision_date_localized %}
+ + {{ label }}: {{ page.meta.git_revision_date_localized }}
+ + {% elif page.meta.revision_date %}
+ + {{ label }}: {{ page.meta.revision_date }}
+ + {% endif %}
+ + </small>
+ +</div>
+ ```
+
+=== ":octicons-file-code-16: `partials/source-link.html`"
+
+ ``` diff
+ @@ -0,0 +1,13 @@
+ +{#-
+ + This file was automatically generated - do not edit
+ +-#}
+ +{% import "partials/language.html" as lang with context %}
+ +{% set repo = config.repo_url %}
+ +{% if repo | last == "/" %}
+ + {% set repo = repo[:-1] %}
+ +{% endif %}
+ +{% set path = page.meta.path | default([""]) %}
+ +<a href="{{ [repo, path, page.meta.source] | join('/') }}" title="{{ file }}" class="md-content__button md-icon">
+ + {{ lang.t("meta.source") }}
+ + {% include ".icons/" ~ config.theme.icon.repo ~ ".svg" %}
+ +</a>
+ ```
+
+=== ":octicons-file-code-16: `partials/source.html`"
+
+ ``` diff
+ @@ -4,24 +4,11 @@
+ {% import "partials/language.html" as lang with context %}
+ -{% set platform = config.extra.repo_icon or config.repo_url %}
+ -{% if "github" in platform %}
+ - {% set repo_type = "github" %}
+ -{% elif "gitlab" in platform %}
+ - {% set repo_type = "gitlab" %}
+ -{% elif "bitbucket" in platform %}
+ - {% set repo_type = "bitbucket" %}
+ -{% else %}
+ - {% set repo_type = "" %}
+ -{% endif %}
+ -<a href="{{ config.repo_url }}" title="{{ lang.t('source.link.title') }}" class="md-source" data-md-source="{{ repo_type }}">
+ - {% if repo_type %}
+ - <div class="md-source__icon">
+ - <svg viewBox="0 0 24 24" width="24" height="24">
+ - <use xlink:href="#__{{ repo_type }}" width="24" height="24"></use>
+ - </svg>
+ - </div>
+ - {% endif %}
+ +<a href="{{ config.repo_url }}" title="{{ lang.t('source.link.title') }}" class="md-source">
+ + <div class="md-source__icon md-icon">
+ + {% set icon = config.theme.icon.repo or "fontawesome/brands/git-alt" %}
+ + {% include ".icons/" ~ icon ~ ".svg" %}
+ + </div>
+ <div class="md-source__repository">
+ {{ config.repo_name }}
+ </div>
+ ```
+
+=== ":octicons-file-code-16: `partials/tabs-item.html`"
+
+ ``` diff
+ @@ -4,7 +4,7 @@
+ -{% if nav_item.is_homepage %}
+ +{% if nav_item.is_homepage or nav_item.url == "index.html" %}
+ <li class="md-tabs__item">
+ {% if not page.ancestors | length and nav | selectattr("url", page.url) %}
+ <a href="{{ nav_item.url | url }}" class="md-tabs__link md-tabs__link--active">
+ ```
+
+=== ":octicons-file-code-16: `partials/tabs.html`"
+
+ ``` diff
+ @@ -5,7 +5,7 @@
+ {% if page.ancestors | length > 0 %}
+ {% set class = "md-tabs md-tabs--active" %}
+ {% endif %}
+ -<nav class="{{ class }}" data-md-component="tabs">
+ +<nav class="{{ class }}" aria-label="{{ lang.t('tabs.title') }}" data-md-component="tabs">
+ <div class="md-tabs__inner md-grid">
+ <ul class="md-tabs__list">
+ {% for nav_item in nav %}
+ ```
+
+=== ":octicons-file-code-16: `partials/toc-item.html`"
+
+ ``` diff
+ @@ -6,7 +6,7 @@
+ {{ toc_item.title }}
+ </a>
+ {% if toc_item.children %}
+ - <nav class="md-nav">
+ + <nav class="md-nav" aria-label="{{ toc_item.title }}">
+ <ul class="md-nav__list">
+ {% for toc_item in toc_item.children %}
+ {% include "partials/toc-item.html" %}
+ ```
+
+=== ":octicons-file-code-16: `partials/toc.html`"
+
+ ``` diff
+ @@ -4,35 +4,22 @@
+ {% import "partials/language.html" as lang with context %}
+ -<nav class="md-nav md-nav--secondary">
+ +<nav class="md-nav md-nav--secondary" aria-label="{{ lang.t('toc.title') }}">
+ {% endif %}
+ {% if toc | first is defined %}
+ <label class="md-nav__title" for="__toc">
+ + <span class="md-nav__icon md-icon">
+ + {% include ".icons/material/arrow-left.svg" %}
+ + </span>
+ {{ lang.t("toc.title") }}
+ </label>
+ <ul class="md-nav__list" data-md-scrollfix>
+ {% for toc_item in toc %}
+ {% include "partials/toc-item.html" %}
+ {% endfor %}
+ - {% if page.meta.source and page.meta.source | length > 0 %}
+ - <li class="md-nav__item">
+ - <a href="#__source" class="md-nav__link md-nav__link--active">
+ - {{ lang.t("meta.source") }}
+ - </a>
+ - </li>
+ - {% endif %}
+ - {% set disqus = config.extra.disqus %}
+ - {% if page and page.meta and page.meta.disqus is string %}
+ - {% set disqus = page.meta.disqus %}
+ - {% endif %}
+ - {% if not page.is_homepage and disqus %}
+ - <li class="md-nav__item">
+ - <a href="#__comments" class="md-nav__link md-nav__link--active">
+ - {{ lang.t("meta.comments") }}
+ - </a>
+ - </li>
+ - {% endif %}
+ </ul>
+ {% endif %}
+ </nav>
+ ```
+
+## Upgrading from 3.x to 4.x
+
+### What's new?
+
+Material for MkDocs 4 fixes incorrect layout on Chinese systems. The fix
+includes a mandatory change of the base font-size from `10px` to `20px` which
+means all `rem` values needed to be updated. Within the theme, `px` to `rem`
+calculation is now encapsulated in a new function called `px2rem` which is part
+of the SASS code base.
+
+If you use Material for MkDocs with custom CSS that is based on `rem` values,
+note that those values must now be divided by 2. Now, `1.0rem` doesn't map to
+`10px`, but `20px`. To learn more about the problem and implications, please
+refer to #911 in which the problem was discovered and fixed.
+
+### Changes to `mkdocs.yml`
+
+None.
+
+### Changes to `*.html` files
+
+None.
diff --git a/documents/markdown/pandoc-md/10002.md b/documents/markdown/pandoc-md/10002.md
new file mode 100644
index 0000000..0a9d846
--- /dev/null
+++ b/documents/markdown/pandoc-md/10002.md
@@ -0,0 +1,203 @@
+````
+% pandoc -f native -t opendocument
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 3)
+ [ Plain
+ [ Str "First"
+ , Space
+ , Str "Header"
+ , Space
+ , Str "Row"
+ ]
+ ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Second" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Header" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Row" ] ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Header - Table" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Header - Body" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Header - Row" ] ]
+ ]
+ ]
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Table" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Body" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Row" ] ]
+ ]
+ ]
+ ]
+ (TableFoot
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 3)
+ [ Plain
+ [ Str "First"
+ , Space
+ , Str "Footer"
+ , Space
+ , Str "Row"
+ ]
+ ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Second" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Footer" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Row" ] ]
+ ]
+ ])
+]
+^D
+<table:table table:name="Table1" table:style-name="Table1">
+ <table:table-column table:style-name="Table1.A" />
+ <table:table-column table:style-name="Table1.B" />
+ <table:table-column table:style-name="Table1.C" />
+ <table:table-header-rows>
+ <table:table-row>
+ <table:table-cell table:style-name="TableHeaderRowCell" office:value-type="string" table:number-columns-spanned="3">
+ <text:p text:style-name="Table_20_Heading">First Header
+ Row</text:p>
+ </table:table-cell>
+ </table:table-row>
+ <table:table-row>
+ <table:table-cell table:style-name="TableHeaderRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Heading">Second</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableHeaderRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Heading">Header</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableHeaderRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Heading">Row</text:p>
+ </table:table-cell>
+ </table:table-row>
+ </table:table-header-rows>
+ <table:table-row>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Heading">Header - Table</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Heading">Header - Body</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Heading">Header - Row</text:p>
+ </table:table-cell>
+ </table:table-row>
+ <table:table-row>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">Table</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">Body</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">Row</text:p>
+ </table:table-cell>
+ </table:table-row>
+ <table:table-row>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string" table:number-columns-spanned="3">
+ <text:p text:style-name="Table_20_Contents">First Footer
+ Row</text:p>
+ </table:table-cell>
+ </table:table-row>
+ <table:table-row>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">Second</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">Footer</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">Row</text:p>
+ </table:table-cell>
+ </table:table-row>
+</table:table>
+````
diff --git a/documents/markdown/pandoc-md/10057.md b/documents/markdown/pandoc-md/10057.md
new file mode 100644
index 0000000..4e3cbde
--- /dev/null
+++ b/documents/markdown/pandoc-md/10057.md
@@ -0,0 +1,6 @@
+```
+% pandoc --natbib -t latex
+We all love the famous proof by @BenjaminHornigold [p. 42].
+^D
+We all love the famous proof by \citet[p.~42]{BenjaminHornigold}.
+```
diff --git a/documents/markdown/pandoc-md/10071.md b/documents/markdown/pandoc-md/10071.md
new file mode 100644
index 0000000..351b3ec
--- /dev/null
+++ b/documents/markdown/pandoc-md/10071.md
@@ -0,0 +1,15 @@
+Leading tabs must be preserved in org mode *src* blocks with the `-i`
+flag when pandoc is called with `-p`/`--preserve-tabs`.
+
+```
+% pandoc -f org -t native --preserve-tabs
+#+begin_src makefile -i
+%.o: %.cpp
+ $(CXX) -o $@ $<
+#+end_src
+^D
+[ CodeBlock
+ ( "" , [ "makefile" ] , [] )
+ "%.o: %.cpp\n\t$(CXX)\t-o\t$@\t$<\n"
+]
+```
diff --git a/documents/markdown/pandoc-md/10093.md b/documents/markdown/pandoc-md/10093.md
new file mode 100644
index 0000000..de9066d
--- /dev/null
+++ b/documents/markdown/pandoc-md/10093.md
@@ -0,0 +1,53 @@
+```
+% pandoc -f rst
+========== ====
+Function 1
+========== ====
+a yes
+b
+========== ====
+^D
+<table>
+<thead>
+<tr>
+<th>Function</th>
+<th>1</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>a</td>
+<td>yes</td>
+</tr>
+<tr>
+<td>b</td>
+<td></td>
+</tr>
+</tbody>
+</table>
+```
+
+```
+% pandoc -f rst
+========== ====
+Function 1
+========== ====
+a yes
+ & no
+========== ====
+^D
+<table>
+<thead>
+<tr>
+<th>Function</th>
+<th>1</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>a</td>
+<td>yes & no</td>
+</tr>
+</tbody>
+</table>
+```
diff --git a/documents/markdown/pandoc-md/10094.md b/documents/markdown/pandoc-md/10094.md
new file mode 100644
index 0000000..01504b0
--- /dev/null
+++ b/documents/markdown/pandoc-md/10094.md
@@ -0,0 +1,47 @@
+```
+% pandoc -f rst -t markdown_strict
+.. table:: Test Table
+
+ ================================== ====
+ Functions for tests 1
+ ================================== ====
+ a yes
+ b
+ c
+ d yes
+ e
+ ================================== ====
+^D
+<table>
+<caption>Test Table</caption>
+<thead>
+<tr>
+<th>Functions for tests</th>
+<th>1</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>a</td>
+<td>yes</td>
+</tr>
+<tr>
+<td>b</td>
+<td></td>
+</tr>
+<tr>
+<td>c</td>
+<td></td>
+</tr>
+<tr>
+<td>d</td>
+<td>yes</td>
+</tr>
+<tr>
+<td>e</td>
+<td></td>
+</tr>
+</tbody>
+</table>
+
+```
diff --git a/documents/markdown/pandoc-md/10105.md b/documents/markdown/pandoc-md/10105.md
new file mode 100644
index 0000000..214dd89
--- /dev/null
+++ b/documents/markdown/pandoc-md/10105.md
@@ -0,0 +1,8 @@
+```
+% pandoc -t asciidoc --wrap=preserve
+[link](https://example.com)
+[link](ftps://example.com)
+^D
+https://example.com[link]
+link:ftps://example.com[link]
+```
diff --git a/documents/markdown/pandoc-md/10127.md b/documents/markdown/pandoc-md/10127.md
new file mode 100644
index 0000000..cb7d463
--- /dev/null
+++ b/documents/markdown/pandoc-md/10127.md
@@ -0,0 +1,713 @@
+RST Reader
+
+```
+% pandoc -f rst -t native
+===== ===== ======
+ Inputs Output
+------------ ------
+ A B A or B
+===== ===== ======
+False False False
+True False True
+False True True
+True True True
+===== ===== ======
+
+Table with trailing whitespaces to ensure they don't interfere with col span parsing.
+
+=============== ============ =====================
+Full column header
+----------------------------------------------------
+Header One Header Two Header 3
+=============== ============ =====================
+Row With col span 2 on the right
+--------------- -----------------------------------
+Full column row
+----------------------------------------------------
+Row with Col spans For visual separation
+--------------- ------------ ---------------------
+Row with col span 2 On the left
+----------------------------- ---------------------
+Final row
+=============== ============ =====================
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 2)
+ [ Plain [ Str "Inputs" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Output" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "A" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "B" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "A" , Space , Str "or" , Space , Str "B" ]
+ ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "False" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "False" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "False" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "True" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "False" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "True" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "False" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "True" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "True" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "True" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "True" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "True" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+, Para
+ [ Str "Table"
+ , Space
+ , Str "with"
+ , Space
+ , Str "trailing"
+ , Space
+ , Str "whitespaces"
+ , Space
+ , Str "to"
+ , Space
+ , Str "ensure"
+ , Space
+ , Str "they"
+ , Space
+ , Str "don't"
+ , Space
+ , Str "interfere"
+ , Space
+ , Str "with"
+ , Space
+ , Str "col"
+ , Space
+ , Str "span"
+ , Space
+ , Str "parsing."
+ ]
+, Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 3)
+ [ Plain
+ [ Str "Full"
+ , Space
+ , Str "column"
+ , Space
+ , Str "header"
+ ]
+ ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Header" , Space , Str "One" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Header" , Space , Str "Two" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Header" , Space , Str "3" ] ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Row" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 2)
+ [ Plain
+ [ Str "With"
+ , Space
+ , Str "col"
+ , Space
+ , Str "span"
+ , Space
+ , Str "2"
+ , Space
+ , Str "on"
+ , Space
+ , Str "the"
+ , Space
+ , Str "right"
+ ]
+ ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 3)
+ [ Plain
+ [ Str "Full"
+ , Space
+ , Str "column"
+ , Space
+ , Str "row"
+ ]
+ ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Row" , Space , Str "with" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Col" , Space , Str "spans" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain
+ [ Str "For"
+ , Space
+ , Str "visual"
+ , Space
+ , Str "separation"
+ ]
+ ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 2)
+ [ Plain
+ [ Str "Row"
+ , Space
+ , Str "with"
+ , Space
+ , Str "col"
+ , Space
+ , Str "span"
+ , Space
+ , Str "2"
+ ]
+ ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain
+ [ Str "On"
+ , Space
+ , Str "the"
+ , Space
+ , Str "left"
+ ]
+ ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Final" , Space , Str "row" ] ]
+ , Cell
+ ( "" , [] , [] ) AlignDefault (RowSpan 1) (ColSpan 1) []
+ , Cell
+ ( "" , [] , [] ) AlignDefault (RowSpan 1) (ColSpan 1) []
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
+
+RST Writer
+```
+% pandoc -f native -t rst
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 2)
+ [ Plain [ Str "Inputs" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Output" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "A" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "B" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "A" , Space , Str "or" , Space , Str "B" ]
+ ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "False" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "False" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "False" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "True" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "False" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "True" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "False" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "True" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "True" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "True" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "True" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "True" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+, Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 3)
+ [ Plain
+ [ Str "Full"
+ , Space
+ , Str "column"
+ , Space
+ , Str "header"
+ ]
+ ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Header" , Space , Str "One" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Header" , Space , Str "Two" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Header" , Space , Str "3" ] ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Row" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 2)
+ [ Plain
+ [ Str "With"
+ , Space
+ , Str "col"
+ , Space
+ , Str "span"
+ , Space
+ , Str "2"
+ , Space
+ , Str "on"
+ , Space
+ , Str "the"
+ , Space
+ , Str "right"
+ ]
+ ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 3)
+ [ Plain
+ [ Str "Full"
+ , Space
+ , Str "column"
+ , Space
+ , Str "row"
+ ]
+ ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 2)
+ [ Plain
+ [ Str "Row"
+ , Space
+ , Str "with"
+ , Space
+ , Str "col"
+ , Space
+ , Str "span"
+ , Space
+ , Str "2"
+ ]
+ ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain
+ [ Str "On"
+ , Space
+ , Str "the"
+ , Space
+ , Str "left"
+ ]
+ ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Final" , Space , Str "row" ] ]
+ , Cell
+ ( "" , [] , [] ) AlignDefault (RowSpan 1) (ColSpan 1) []
+ , Cell
+ ( "" , [] , [] ) AlignDefault (RowSpan 1) (ColSpan 1) []
+ ]
+ ]
+ ]
+ (TableFoot
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Footer" , Space , Str "Row" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "at" , Space , Str "the" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "bottom" ] ]
+ ]
+ ])
+]
+^D
+====== ===== ======
+Inputs Output
+------------ ------
+A B A or B
+====== ===== ======
+False False False
+True False True
+False True True
+True True True
+====== ===== ======
+
+=================== ============================ ===========
+Full column header
+------------------------------------------------------------
+Header One Header Two Header 3
+=================== ============================ ===========
+Row With col span 2 on the right
+------------------- ----------------------------------------
+Full column row
+------------------------------------------------------------
+Row with col span 2 On the left
+------------------------------------------------ -----------
+Final row
+Footer Row at the bottom
+=================== ============================ ===========
+```
diff --git a/documents/markdown/pandoc-md/10145.md b/documents/markdown/pandoc-md/10145.md
new file mode 100644
index 0000000..de063aa
--- /dev/null
+++ b/documents/markdown/pandoc-md/10145.md
@@ -0,0 +1,24 @@
+```
+% pandoc -f rtf -t native
+{\rtf1\ansi\deff0{\fonttbl{\f0 \fswiss Helvetica;}{\f1 \fmodern Courier;}}
+{\colortbl;\red255\green0\blue0;\red0\green0\blue255;}
+\widowctrl\hyphauto
+
+{\pard \ql \f0 \sa0 \li0 \fi0 {\shp{\*\shpinst\shpwr2\shpwrk3\shpbypara\shpbyignore\shptop1320\shpbottom7745\shpbxcolumn\shpbxignore\shpleft0\shpright9638{\sp{\sn shapeType}{\sv 75}}{\sp{\sn wzDescription}{\sv }}{\sp{\sn wzName}{\sv }}{\sp{\sn pib}{\sv {\pict\jpegblip\picw20\pich22\picwgoal400\pichgoal440 ffd8ffe000104a46494600010101004800480000fffe0050546869732061727420697320696e20746865207075626c696320646f6d61696e2e204b6576696e204875676865732c206b6576696e68406569742e636f6d2c2053657074656d6265722031393935ffdb00430001010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101ffdb00430101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101ffc00011080016001403012200021101031101ffc4001a000100020301000000000000000000000000080905060a07ffc400231000010501000300010500000000000000060304050708020001090a11153976b7ffc400160101010100000000000000000000000000060800ffc400261101000102050109000000000000000000010200030405061121b33134365154717475b4ffda000c03010002110311003f00a90cf388f366a62aa720ed6ae07f96901f3831d973452b8cf36fe3570fc908e46d466433e5dd954f2e96992d9e498c7753faa44916e016ca91cc7d88b38fe60a5b97737defcbcc539c98d336a57f4fc2ca9a486bf07ab575ad9a3af4df221d8215e36df86c4504ff0024574551b3d687ee0575757b3ad64e311ee62bd94158d37e24198c43973099f1fc0c41614d950246513a081abf76cfe7061f6863281e6352fd1670949c148dd6dfb0d25f5b3689b1d5c965b0eacbf4e0932ad28e22ab9ae945633f4744bd3c8cee0a7fdf085b9000f449c5f7afa30b83e0b6fd7b0c8429c9467ff9715347c891e25fa24a205861aa715e6a09bd0488237dc2723414d9891381524e8ca7c0894664f835653631ab55ee7e3de433e4ff001b30949124e4c10c8b6ad0a479b3f9c937b2cf5bc0095ad600a0a41a0e9faee174a1c605e161c6c7a313539650b0113190f1a8368e60d5b24f30ff008ea7f0bf867fa6595feeb6978f1fe0f9c26177f4d63a51a9235184750e7d18811339cd000000c75f000e00380380ae390c350def826ed42ad051fa6f501c50f9b699c3b69cbeb76476d202bf3ac985b6e0e968be66572893e6a744540bd9722e5c87956848629bc2559306bd113e8653d3b6aff651dfad7a3ac8b02958cba02a93ccf525757039bae6cff090e1d90688e8aa233ee86a4c4a3e0586d6b2340522e47dcb7d0046d8a5acb05a123ee25d2b230b2ada6e2e2f9ede3c05202520ec2487b0d56562529d8b3393bca76adca4ec1bca508abb001babc007915d84fe3dd14e207e3c62f8379da2a3b861fb6629d28dba53b6ea388ebfed866bf6dfb553455e91ed547ae92e9445253a4fdf3efb4f8ebdfbe7d3c78f1ee0bb9e13e358e942a4ed49e22cff00eeb35fdd7ebfffd9}}}}}\par}
+{\pard \ql \f0 \sa0 \li0 \fi0 moon\par}
+}
+^D
+[ Para
+ [ Image
+ ( ""
+ , []
+ , [ ( "width" , "0.2777777777777778in" )
+ , ( "height" , "0.3055555555555556in" )
+ ]
+ )
+ [ Str "image" ]
+ ( "9ea9761885249909bcd8a610706eef51b54dc351.jpg" , "" )
+ ]
+, Para [ Str "moon" ]
+]
+```
diff --git a/documents/markdown/pandoc-md/10148.md b/documents/markdown/pandoc-md/10148.md
new file mode 100644
index 0000000..c90f6d0
--- /dev/null
+++ b/documents/markdown/pandoc-md/10148.md
@@ -0,0 +1,18 @@
+```
+% pandoc -t typst
+See [@MyPaper].
+
+See [@MyPaper, Equation 1] for details.
+
+See [@MyPaper, Equation 1].
+
+See [@MyPaper, Equation 1; @Other, Figure 1].
+^D
+See @MyPaper.
+
+See @MyPaper[Equation 1] for details.
+
+See @MyPaper[Equation 1].
+
+See @MyPaper[Equation 1]@Other[Figure 1].
+```
diff --git a/documents/markdown/pandoc-md/10149.md b/documents/markdown/pandoc-md/10149.md
new file mode 100644
index 0000000..9e03e8f
--- /dev/null
+++ b/documents/markdown/pandoc-md/10149.md
@@ -0,0 +1,296 @@
+Row spans
+```
+% pandoc -f html --columns 24 -t ansi
+<table>
+ <thead>
+ <tr>
+ <td rowspan="3">1</td>
+ <td>2</td>
+ <td>3</td>
+ <td>4</td>
+ <td rowspan="4">5</td>
+ <td>6</td>
+ </tr>
+ <tr>
+ <td>2</td>
+ <td colspan="2" rowspan="2">3</td>
+ <td>6</td>
+ </tr>
+ <tr>
+ <td rowspan="2">2</td>
+ <td>6</td>
+ </tr>
+ <tr>
+ <td>1</td>
+ <td>3</td>
+ <td>4</td>
+ <td>6</td>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td colspan="2">a</td>
+ <td rowspan="2">c</td>
+ <td>d</td>
+ <td>e</td>
+ <td>f</td>
+ </tr>
+ <tr>
+ <td>a</td>
+ <td>b</td>
+ <td colspan="3" rowspan="2">d</td>
+ </tr>
+ <tr>
+ <td>a</td>
+ <td>b</td>
+ <td>c</td>
+ </tr>
+ </tbody>
+ <tfoot>
+ <tr>
+ <td colspan="2" rowspan="4">A</td>
+ <td>C</td>
+ <td>D</td>
+ <td colspan="2" rowspan="3">E</td>
+ </tr>
+ <tr>
+ <td>C</td>
+ <td>D</td>
+ </tr>
+ <tr>
+ <td>C</td>
+ <td>D</td>
+ </tr>
+ <tr>
+ <td>C</td>
+ <td>D</td>
+ <td>E</td>
+ <td>F</td>
+ </tr>
+ </tfoot>
+</table>
+^D
+1 2 3 4 5 6
+ 2 3 6
+ 2 6
+1 3 4 6
+─── ─── ─── ─── ─── ───
+a c d e f
+a b d
+a b c
+─── ─── ─── ─── ─── ───
+A C D E
+ C D
+ C D
+ C D E F[0m]8;;\
+```
+
+Empty rows
+```
+% pandoc -f native --columns 12 -t ansi
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 3)
+ (ColSpan 2)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "3" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "3" ] ]
+ ]
+ , Row ( "" , [] , [] ) []
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "3" ] ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 2)
+ (ColSpan 1)
+ [ Plain [ Str "3" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 4)
+ (ColSpan 1)
+ [ Plain [ Str "2" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "3" ] ]
+ ]
+ , Row ( "" , [] , [] ) []
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "3" ] ]
+ ]
+ ]
+ ]
+ (TableFoot
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 2)
+ (ColSpan 1)
+ [ Plain [ Str "3" ] ]
+ ]
+ , Row ( "" , [] , [] ) []
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 3)
+ (ColSpan 1)
+ [ Plain [ Str "3" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "2" ] ]
+ ]
+ , Row ( "" , [] , [] ) []
+ ])
+]
+^D
+1 3
+ 3
+1 2 3
+─── ─── ───
+1 2 3
+1 2
+1 3
+1 3
+─── ─── ───
+1 2 3
+1 2 3
+1 2[0m]8;;\
+```
diff --git a/documents/markdown/pandoc-md/10152.md b/documents/markdown/pandoc-md/10152.md
new file mode 100644
index 0000000..44c5df6
--- /dev/null
+++ b/documents/markdown/pandoc-md/10152.md
@@ -0,0 +1,446 @@
+# CRediT Roles
+
+This document contains tests and examples for enabling
+export of roles to JATS. It was added for
+[Issue #10152](https://github.com/jgm/pandoc/issues/10152)
+and corresponding [Pull Request #10153](https://github.com/jgm/pandoc/pull/10153).
+
+In the first example, we show a fully qualified CRediT role.
+An explicit name isn't given, so the CRediT name is used.
+
+```
+% pandoc -s -t jats
+---
+title: CRediT Test
+author:
+ - name: Max Mustermann
+ affiliation: [ 1 ]
+ roles:
+ - credit: software
+ credit-name: Software
+ degree: Lead
+affiliation:
+- id: 1
+ name: Silverlight University
+---
+^D
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE article PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Archiving and Interchange DTD v1.2 20190208//EN"
+ "JATS-archivearticle1.dtd">
+<article xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:xlink="http://www.w3.org/1999/xlink" dtd-version="1.2" article-type="other">
+<front>
+<journal-meta>
+<journal-id></journal-id>
+<journal-title-group>
+</journal-title-group>
+<issn></issn>
+<publisher>
+<publisher-name></publisher-name>
+</publisher>
+</journal-meta>
+<article-meta>
+<title-group>
+<article-title>CRediT Test</article-title>
+</title-group>
+<contrib-group>
+<contrib contrib-type="author">
+<string-name>Max Mustermann</string-name>
+<role vocab="credit" degree-contribution="Lead"
+ vocab-identifier="https://credit.niso.org/"
+ vocab-term-identifier="https://credit.niso.org/contributor-roles/software/"
+ vocab-term="Software"
+>Software</role>
+<xref ref-type="aff" rid="aff-1"/>
+</contrib>
+<aff id="aff-1">
+<institution-wrap>
+<institution>Silverlight University</institution>
+</institution-wrap>
+</aff>
+</contrib-group>
+<permissions>
+</permissions>
+</article-meta>
+</front>
+<body>
+
+</body>
+<back>
+</back>
+</article>
+```
+
+In the second example, we show a fully qualified CRediT role.
+An explicit name is given in a different language.
+
+```
+% pandoc -s -t jats
+---
+title: CRediT Test
+author:
+ - name: Max Mustermann
+ affiliation: [ 1 ]
+ roles:
+ - credit: software
+ credit-name: Software
+ degree: Lead
+ name: Programas
+affiliation:
+- id: 1
+ name: Silverlight University
+---
+^D
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE article PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Archiving and Interchange DTD v1.2 20190208//EN"
+ "JATS-archivearticle1.dtd">
+<article xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:xlink="http://www.w3.org/1999/xlink" dtd-version="1.2" article-type="other">
+<front>
+<journal-meta>
+<journal-id></journal-id>
+<journal-title-group>
+</journal-title-group>
+<issn></issn>
+<publisher>
+<publisher-name></publisher-name>
+</publisher>
+</journal-meta>
+<article-meta>
+<title-group>
+<article-title>CRediT Test</article-title>
+</title-group>
+<contrib-group>
+<contrib contrib-type="author">
+<string-name>Max Mustermann</string-name>
+<role vocab="credit" degree-contribution="Lead"
+ vocab-identifier="https://credit.niso.org/"
+ vocab-term-identifier="https://credit.niso.org/contributor-roles/software/"
+ vocab-term="Software"
+>Programas</role>
+<xref ref-type="aff" rid="aff-1"/>
+</contrib>
+<aff id="aff-1">
+<institution-wrap>
+<institution>Silverlight University</institution>
+</institution-wrap>
+</aff>
+</contrib-group>
+<permissions>
+</permissions>
+</article-meta>
+</front>
+<body>
+
+</body>
+<back>
+</back>
+</article>
+```
+
+In this example, we show a partially qualified CRediT role
+that does not have a `degree`:
+
+```
+% pandoc -s -t jats
+---
+title: CRediT Test
+author:
+ - name: Max Mustermann
+ affiliation: [ 1 ]
+ roles:
+ - credit: software
+ credit-name: Software
+affiliation:
+- id: 1
+ name: Silverlight University
+---
+^D
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE article PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Archiving and Interchange DTD v1.2 20190208//EN"
+ "JATS-archivearticle1.dtd">
+<article xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:xlink="http://www.w3.org/1999/xlink" dtd-version="1.2" article-type="other">
+<front>
+<journal-meta>
+<journal-id></journal-id>
+<journal-title-group>
+</journal-title-group>
+<issn></issn>
+<publisher>
+<publisher-name></publisher-name>
+</publisher>
+</journal-meta>
+<article-meta>
+<title-group>
+<article-title>CRediT Test</article-title>
+</title-group>
+<contrib-group>
+<contrib contrib-type="author">
+<string-name>Max Mustermann</string-name>
+<role vocab="credit"
+ vocab-identifier="https://credit.niso.org/"
+ vocab-term-identifier="https://credit.niso.org/contributor-roles/software/"
+ vocab-term="Software"
+>Software</role>
+<xref ref-type="aff" rid="aff-1"/>
+</contrib>
+<aff id="aff-1">
+<institution-wrap>
+<institution>Silverlight University</institution>
+</institution-wrap>
+</aff>
+</contrib-group>
+<permissions>
+</permissions>
+</article-meta>
+</front>
+<body>
+
+</body>
+<back>
+</back>
+</article>
+```
+
+In this example, we show a more stripped-down data that requires automatic lookup of the
+`credit-name`.
+
+```
+% pandoc -s -t jats
+---
+title: CRediT Test
+author:
+ - name: Max Mustermann
+ affiliation: [ 1 ]
+ roles:
+ - credit: software
+affiliation:
+- id: 1
+ name: Silverlight University
+---
+^D
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE article PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Archiving and Interchange DTD v1.2 20190208//EN"
+ "JATS-archivearticle1.dtd">
+<article xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:xlink="http://www.w3.org/1999/xlink" dtd-version="1.2" article-type="other">
+<front>
+<journal-meta>
+<journal-id></journal-id>
+<journal-title-group>
+</journal-title-group>
+<issn></issn>
+<publisher>
+<publisher-name></publisher-name>
+</publisher>
+</journal-meta>
+<article-meta>
+<title-group>
+<article-title>CRediT Test</article-title>
+</title-group>
+<contrib-group>
+<contrib contrib-type="author">
+<string-name>Max Mustermann</string-name>
+<role vocab="credit"
+ vocab-identifier="https://credit.niso.org/"
+ vocab-term-identifier="https://credit.niso.org/contributor-roles/software/"
+ vocab-term="Software"
+>Software</role>
+<xref ref-type="aff" rid="aff-1"/>
+</contrib>
+<aff id="aff-1">
+<institution-wrap>
+<institution>Silverlight University</institution>
+</institution-wrap>
+</aff>
+</contrib-group>
+<permissions>
+</permissions>
+</article-meta>
+</front>
+<body>
+
+</body>
+<back>
+</back>
+</article>
+```
+
+In this example, we test the correct XML encoding of
+the CRediT role [Writing – review & editing](https://credit.niso.org/contributor-roles/writing-review-editing/),
+which annoyingly contains an ampersand in its label.
+
+```
+% pandoc -s -t jats
+---
+title: CRediT Test
+author:
+ - name: Max Mustermann
+ affiliation: [ 1 ]
+ roles:
+ - credit: writing-review-editing
+ credit-name: Writing – review & editing
+ degree: Lead
+affiliation:
+- id: 1
+ name: Silverlight University
+---
+^D
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE article PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Archiving and Interchange DTD v1.2 20190208//EN"
+ "JATS-archivearticle1.dtd">
+<article xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:xlink="http://www.w3.org/1999/xlink" dtd-version="1.2" article-type="other">
+<front>
+<journal-meta>
+<journal-id></journal-id>
+<journal-title-group>
+</journal-title-group>
+<issn></issn>
+<publisher>
+<publisher-name></publisher-name>
+</publisher>
+</journal-meta>
+<article-meta>
+<title-group>
+<article-title>CRediT Test</article-title>
+</title-group>
+<contrib-group>
+<contrib contrib-type="author">
+<string-name>Max Mustermann</string-name>
+<role vocab="credit" degree-contribution="Lead"
+ vocab-identifier="https://credit.niso.org/"
+ vocab-term-identifier="https://credit.niso.org/contributor-roles/writing-review-editing/"
+ vocab-term="Writing – review & editing"
+>Writing – review & editing</role>
+<xref ref-type="aff" rid="aff-1"/>
+</contrib>
+<aff id="aff-1">
+<institution-wrap>
+<institution>Silverlight University</institution>
+</institution-wrap>
+</aff>
+</contrib-group>
+<permissions>
+</permissions>
+</article-meta>
+</front>
+<body>
+
+</body>
+<back>
+</back>
+</article>
+```
+
+In this example, we show a role that isn't qualified with CRediT.
+
+```
+% pandoc -s -t jats
+---
+title: CRediT Test
+author:
+ - name: Max Mustermann
+ affiliation: [ 1 ]
+ roles:
+ - name: Dolphin Catcher
+affiliation:
+- id: 1
+ name: Silverlight University
+---
+^D
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE article PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Archiving and Interchange DTD v1.2 20190208//EN"
+ "JATS-archivearticle1.dtd">
+<article xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:xlink="http://www.w3.org/1999/xlink" dtd-version="1.2" article-type="other">
+<front>
+<journal-meta>
+<journal-id></journal-id>
+<journal-title-group>
+</journal-title-group>
+<issn></issn>
+<publisher>
+<publisher-name></publisher-name>
+</publisher>
+</journal-meta>
+<article-meta>
+<title-group>
+<article-title>CRediT Test</article-title>
+</title-group>
+<contrib-group>
+<contrib contrib-type="author">
+<string-name>Max Mustermann</string-name>
+<role>Dolphin Catcher</role>
+<xref ref-type="aff" rid="aff-1"/>
+</contrib>
+<aff id="aff-1">
+<institution-wrap>
+<institution>Silverlight University</institution>
+</institution-wrap>
+</aff>
+</contrib-group>
+<permissions>
+</permissions>
+</article-meta>
+</front>
+<body>
+
+</body>
+<back>
+</back>
+</article>
+```
+
+In this example, we show a role that neither has a CRediT identifer,
+nor a name, so it's ignored.
+
+```
+% pandoc -s -t jats
+---
+title: CRediT Test
+author:
+ - name: Max Mustermann
+ affiliation: [ 1 ]
+ roles:
+ - irrelevant-key: Dolphin Catcher
+affiliation:
+- id: 1
+ name: Silverlight University
+---
+^D
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE article PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Archiving and Interchange DTD v1.2 20190208//EN"
+ "JATS-archivearticle1.dtd">
+<article xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:xlink="http://www.w3.org/1999/xlink" dtd-version="1.2" article-type="other">
+<front>
+<journal-meta>
+<journal-id></journal-id>
+<journal-title-group>
+</journal-title-group>
+<issn></issn>
+<publisher>
+<publisher-name></publisher-name>
+</publisher>
+</journal-meta>
+<article-meta>
+<title-group>
+<article-title>CRediT Test</article-title>
+</title-group>
+<contrib-group>
+<contrib contrib-type="author">
+<string-name>Max Mustermann</string-name>
+<xref ref-type="aff" rid="aff-1"/>
+</contrib>
+<aff id="aff-1">
+<institution-wrap>
+<institution>Silverlight University</institution>
+</institution-wrap>
+</aff>
+</contrib-group>
+<permissions>
+</permissions>
+</article-meta>
+</front>
+<body>
+
+</body>
+<back>
+</back>
+</article>
+```
diff --git a/documents/markdown/pandoc-md/10160.md b/documents/markdown/pandoc-md/10160.md
new file mode 100644
index 0000000..52e512b
--- /dev/null
+++ b/documents/markdown/pandoc-md/10160.md
@@ -0,0 +1,15 @@
+```
+% pandoc -f latex -t native
+\begin{equation}
+ [0,1)
+\end{equation}
+
+\begin{table}[h]
+\end{table}
+^D
+[ Para
+ [ Math
+ DisplayMath "\\begin{equation}\n [0,1)\n\\end{equation}"
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/10185.md b/documents/markdown/pandoc-md/10185.md
new file mode 100644
index 0000000..9c57469
--- /dev/null
+++ b/documents/markdown/pandoc-md/10185.md
@@ -0,0 +1,46 @@
+```
+% pandoc -t latex --citeproc
+Lorem ipsum
+
+# References
+
+::: {#refs}
+:::
+^D
+Lorem ipsum
+
+\section{References}\label{references}
+
+\protect\phantomsection\label{refs}
+```
+
+```
+% pandoc -t latex --citeproc
+---
+references:
+- id: foo
+ type: book
+ title: The Title
+ author: John Doe
+...
+
+Lorem ipsum [@foo].
+
+# References
+
+::: {#refs}
+:::
+^D
+Lorem ipsum (John Doe, n.d.).
+
+\section{References}\label{references}
+
+\protect\phantomsection\label{refs}
+\begin{CSLReferences}{1}{1}
+\bibitem[\citeproctext]{ref-foo}
+John Doe. n.d. \emph{The Title}.
+
+\end{CSLReferences}
+
+```
+
diff --git a/documents/markdown/pandoc-md/10236.md b/documents/markdown/pandoc-md/10236.md
new file mode 100644
index 0000000..3ca48b8
--- /dev/null
+++ b/documents/markdown/pandoc-md/10236.md
@@ -0,0 +1,80 @@
+```
+% pandoc -t rst
+- > test
+ >
+ > para 2
+^D
+- ..
+
+ test
+
+ para 2
+```
+
+```
+% pandoc -t rst
+1. > test
+ >
+ > para 2
+^D
+1. ..
+
+ test
+
+ para 2
+```
+
+```
+% pandoc -t rst
+::: caution
+> test
+:::
+^D
+.. caution::
+
+ ..
+
+ test
+```
+
+```
+% pandoc -f native -t rst --list-tables
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidth 0.26 ) ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ BlockQuote
+ [ Para [ Emph [ Str "Level" , Space , Str "0:" ] ]
+ , Para
+ [ Emph [ Str "Incomplete" , Space , Str "process" ]
+ ]
+ ]
+ ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+^D
+.. list-table::
+ :widths: 19
+
+ * - ..
+
+ *Level 0:*
+
+ *Incomplete process*
+```
+
diff --git a/documents/markdown/pandoc-md/10271.md b/documents/markdown/pandoc-md/10271.md
new file mode 100644
index 0000000..3b529b8
--- /dev/null
+++ b/documents/markdown/pandoc-md/10271.md
@@ -0,0 +1,29 @@
+```
+% pandoc -f markdown+smart -t typst+smart
+"don't do it---"
+^D
+"don't do it---"
+
+```
+```
+% pandoc -f markdown+smart -t typst-smart
+"don't do it---"
+^D
+“don’t do it—”
+
+```
+```
+% pandoc -f markdown-smart -t typst+smart
+"don't do it---"
+^D
+\"don\'t do it-\-\-\"
+
+```
+```
+% pandoc -f markdown-smart -t typst-smart
+"don't do it---"
+^D
+"don't do it---"
+
+```
+
diff --git a/documents/markdown/pandoc-md/10279.md b/documents/markdown/pandoc-md/10279.md
new file mode 100644
index 0000000..5029c41
--- /dev/null
+++ b/documents/markdown/pandoc-md/10279.md
@@ -0,0 +1,9 @@
+```
+% pandoc -f rst
+See `the full compatibility guidelines <https://
+example.com>`_ for more information.
+^D
+<p>See <a href="https://example.com">the full compatibility
+guidelines</a> for more information.</p>
+
+```
diff --git a/documents/markdown/pandoc-md/10281.md b/documents/markdown/pandoc-md/10281.md
new file mode 100644
index 0000000..a946061
--- /dev/null
+++ b/documents/markdown/pandoc-md/10281.md
@@ -0,0 +1,68 @@
+```
+% pandoc -f rst -t native
+`Want Speed? Pass by Value`_
+
+.. note::
+ For more information about the pass-by-value idiom, read: `Want Speed? Pass by Value`_.
+
+ .. _Want Speed? Pass by Value: https://web.archive.org/web/20140205194657/http://cpp-next.com/archive/2009/08/want-speed-pass-by-value/
+^D
+[ Para
+ [ Link
+ ( "" , [] , [] )
+ [ Str "Want"
+ , Space
+ , Str "Speed?"
+ , Space
+ , Str "Pass"
+ , Space
+ , Str "by"
+ , Space
+ , Str "Value"
+ ]
+ ( "https://web.archive.org/web/20140205194657/http://cpp-next.com/archive/2009/08/want-speed-pass-by-value/"
+ , ""
+ )
+ ]
+, Div
+ ( "" , [ "note" ] , [] )
+ [ Div ( "" , [ "title" ] , [] ) [ Para [ Str "Note" ] ]
+ , Para
+ [ Str "For"
+ , Space
+ , Str "more"
+ , Space
+ , Str "information"
+ , Space
+ , Str "about"
+ , Space
+ , Str "the"
+ , Space
+ , Str "pass-by-value"
+ , Space
+ , Str "idiom,"
+ , Space
+ , Str "read:"
+ , Space
+ , Link
+ ( "" , [] , [] )
+ [ Str "Want"
+ , Space
+ , Str "Speed?"
+ , Space
+ , Str "Pass"
+ , Space
+ , Str "by"
+ , Space
+ , Str "Value"
+ ]
+ ( "https://web.archive.org/web/20140205194657/http://cpp-next.com/archive/2009/08/want-speed-pass-by-value/"
+ , ""
+ )
+ , Str "."
+ ]
+ ]
+]
+
+```
+
diff --git a/documents/markdown/pandoc-md/10318.md b/documents/markdown/pandoc-md/10318.md
new file mode 100644
index 0000000..f84dd9b
--- /dev/null
+++ b/documents/markdown/pandoc-md/10318.md
@@ -0,0 +1,84 @@
+```
+% pandoc -f rst -t html5
+-a Output all.
+-c arg Output just arg.
+--long Output all day long.
+/V A VMS/DOS-style option.
+
+-p This option has two paragraphs in the description.
+ This is the first.
+
+ This is the second.
+ Blank lines may be omitted between options
+ (as above) or left in (as here and below).
+
+--very-long-option A VMS-style option. Note the adjustment
+ for the required two spaces.
+
+--an-even-longer-option
+ The description can also start on the next line.
+
+-2, --two This option has two variants.
+
+-f FILE, --file=FILE These two options are synonyms; both have
+ arguments.
+
+-f <[path]file> Option argument placeholders must start with
+ a letter or be wrapped in angle brackets.
+
+-d <src dest> Angle brackets are also required if an option
+ expects more than one argument.
+^D
+<dl>
+<dt><code>-a</code></dt>
+<dd>
+<p>Output all.</p>
+</dd>
+<dt><code>-c arg</code></dt>
+<dd>
+<p>Output just arg.</p>
+</dd>
+<dt><code>--long</code></dt>
+<dd>
+<p>Output all day long.</p>
+</dd>
+<dt><code>/V</code></dt>
+<dd>
+<p>A VMS/DOS-style option.</p>
+</dd>
+<dt><code>-p</code></dt>
+<dd>
+<p>This option has two paragraphs in the description. This is the
+first.</p>
+<p>This is the second. Blank lines may be omitted between options (as
+above) or left in (as here and below).</p>
+</dd>
+<dt><code>--very-long-option</code></dt>
+<dd>
+<p>A VMS-style option. Note the adjustment for the required two
+spaces.</p>
+</dd>
+<dt><code>--an-even-longer-option</code></dt>
+<dd>
+<p>The description can also start on the next line.</p>
+</dd>
+<dt><code>-2, --two</code></dt>
+<dd>
+<p>This option has two variants.</p>
+</dd>
+<dt><code>-f FILE, --file=FILE</code></dt>
+<dd>
+<p>These two options are synonyms; both have arguments.</p>
+</dd>
+<dt><code>-f <[path]file></code></dt>
+<dd>
+<p>Option argument placeholders must start with a letter or be wrapped
+in angle brackets.</p>
+</dd>
+<dt><code>-d <src dest></code></dt>
+<dd>
+<p>Angle brackets are also required if an option expects more than one
+argument.</p>
+</dd>
+</dl>
+```
diff --git a/documents/markdown/pandoc-md/10328.md b/documents/markdown/pandoc-md/10328.md
new file mode 100644
index 0000000..cdd3797
--- /dev/null
+++ b/documents/markdown/pandoc-md/10328.md
@@ -0,0 +1,37 @@
+Unwrap divs if they only have the `nonincremental` or `incremental` classes.
+
+```
+% pandoc --incremental --from=markdown --to=revealjs
+## First slide
+
+::: nonincremental
+
+1. Note 1
+2. Note 2
+3. Note 3
+
+:::
+
+## Second Slide
+
+1. Note 1
+2. Note 2
+3. Note 3
+^D
+<section id="first-slide" class="slide level2">
+<h2>First slide</h2>
+<ol type="1">
+<li>Note 1</li>
+<li>Note 2</li>
+<li>Note 3</li>
+</ol>
+</section>
+<section id="second-slide" class="slide level2">
+<h2>Second Slide</h2>
+<ol type="1">
+<li class="fragment">Note 1</li>
+<li class="fragment">Note 2</li>
+<li class="fragment">Note 3</li>
+</ol>
+</section>
+```
diff --git a/documents/markdown/pandoc-md/10338-rst-multiple-header-rows.md b/documents/markdown/pandoc-md/10338-rst-multiple-header-rows.md
new file mode 100644
index 0000000..5bfd05f
--- /dev/null
+++ b/documents/markdown/pandoc-md/10338-rst-multiple-header-rows.md
@@ -0,0 +1,155 @@
+```
+% pandoc -f rst -t native
+Multiple Headers
+================
+
+========== =========
+Header A1 Header A2
+Header B1 Header B2
+========== =========
+body a1 body a1
+body b1 body b2
+========== =========
+
+Headless
+========
+
+========== =========
+body a1 body a1
+body b1 body b2
+========== =========
+
+End Section
+===========
+^D
+[ Header
+ 1
+ ( "multiple-headers" , [] , [] )
+ [ Str "Multiple" , Space , Str "Headers" ]
+, Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Header" , Space , Str "A1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Header" , Space , Str "A2" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Header" , Space , Str "B1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Header" , Space , Str "B2" ] ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "body" , Space , Str "a1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "body" , Space , Str "a1" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "body" , Space , Str "b1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "body" , Space , Str "b2" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+, Header 1 ( "headless" , [] , [] ) [ Str "Headless" ]
+, Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "body" , Space , Str "a1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "body" , Space , Str "a1" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "body" , Space , Str "b1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "body" , Space , Str "b2" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+, Header
+ 1
+ ( "end-section" , [] , [] )
+ [ Str "End" , Space , Str "Section" ]
+]
+```
diff --git a/documents/markdown/pandoc-md/10385.md b/documents/markdown/pandoc-md/10385.md
new file mode 100644
index 0000000..9897556
--- /dev/null
+++ b/documents/markdown/pandoc-md/10385.md
@@ -0,0 +1,22 @@
+````
+% pandoc -t asciidoc
+C+ C++ C+++ `++`
+
+`` ` `` \`hi\`
+
+`hi\there`` ok`
+
+```
+++`
+```
+^D
+C{plus} C{plus}{plus} C{plus}{plus}{plus} `{plus}{plus}`
+
+`++`++` ++`++hi++`++
+
+`hi++\++there++``++ ok`
+
+....
+++`
+....
+````
diff --git a/documents/markdown/pandoc-md/10390.md b/documents/markdown/pandoc-md/10390.md
new file mode 100644
index 0000000..78d12e8
--- /dev/null
+++ b/documents/markdown/pandoc-md/10390.md
@@ -0,0 +1,23 @@
+```
+% pandoc -f mediawiki
+ {| class="wikitable"
+ |+ Overview of basic table markup
+ ! Key
+ |-
+ | Value
+ |}
+^D
+<table>
+<caption>Overview of basic table markup</caption>
+<thead>
+<tr>
+<th><p>Key</p></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><p>Value</p></td>
+</tr>
+</tbody>
+</table>
+```
diff --git a/documents/markdown/pandoc-md/10414.md b/documents/markdown/pandoc-md/10414.md
new file mode 100644
index 0000000..3a69b3b
--- /dev/null
+++ b/documents/markdown/pandoc-md/10414.md
@@ -0,0 +1,6 @@
+```
+% pandoc -f textile -t html
+from 30.-100. text, inside - after dash
+^D
+<p>from 30.–100. text, inside - after dash</p>
+```
diff --git a/documents/markdown/pandoc-md/10459.md b/documents/markdown/pandoc-md/10459.md
new file mode 100644
index 0000000..b45950c
--- /dev/null
+++ b/documents/markdown/pandoc-md/10459.md
@@ -0,0 +1,11 @@
+```
+% pandoc -s --shift-heading-level-by=-1 -f djot -t native
+# hi
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList [ ( "title" , MetaInlines [ Str "hi" ] ) ]
+ }
+ [ Div ( "hi" , [ "section" ] , [] ) [] ]
+```
diff --git a/documents/markdown/pandoc-md/10484.md b/documents/markdown/pandoc-md/10484.md
new file mode 100644
index 0000000..979517e
--- /dev/null
+++ b/documents/markdown/pandoc-md/10484.md
@@ -0,0 +1,22 @@
+```
+% pandoc -frst -tmarkdown_strict
+- One issue fixed: `issue 123`_.
+
+- One change merged: `Big change <pull 234_>`_.
+
+- Improved the `home page <https://example.com/homepage>`_.
+
+- One more `small change`__.
+
+.. _issue 123: https://github.com/joe/project/issues/123
+.. _pull 234: https://github.com/joe/project/pull/234
+__ https://github.com/joe/project/issues/999
+
+^D
+- One issue fixed: [issue
+ 123](https://github.com/joe/project/issues/123).
+- One change merged: [Big
+ change](https://github.com/joe/project/pull/234).
+- Improved the [home page](https://example.com/homepage).
+- One more [small change](https://github.com/joe/project/issues/999).
+```
diff --git a/documents/markdown/pandoc-md/10490.md b/documents/markdown/pandoc-md/10490.md
new file mode 100644
index 0000000..05143ef
--- /dev/null
+++ b/documents/markdown/pandoc-md/10490.md
@@ -0,0 +1,50 @@
+```
+% pandoc -f mediawiki -t html
+{|class="wikitable" style="text-align: center;"
+|-
+!rowspan=3 style=""|Witness program version
+!colspan=4 style=""|Hash size
+|-
+!Mainnet
+!Testnet
+!Mainnet
+!Testnet
+|-
+|0||p2||QW||7Xh||T7n
+|-
+|1||p4||QY||7Xq||T7w
+|}
+^D
+<table>
+<thead>
+<tr>
+<th style=""><p>Witness program version</p></th>
+<th colspan="4" style=""><p>Hash size</p></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><p>Mainnet</p></td>
+<td><p>Testnet</p></td>
+<td><p>Mainnet</p></td>
+<td><p>Testnet</p></td>
+<td></td>
+</tr>
+<tr>
+<td><p>0</p></td>
+<td><p>p2</p></td>
+<td><p>QW</p></td>
+<td><p>7Xh</p></td>
+<td><p>T7n</p></td>
+</tr>
+<tr>
+<td><p>1</p></td>
+<td><p>p4</p></td>
+<td><p>QY</p></td>
+<td><p>7Xq</p></td>
+<td><p>T7w</p></td>
+</tr>
+</tbody>
+</table>
+
+```
diff --git a/documents/markdown/pandoc-md/10491.md b/documents/markdown/pandoc-md/10491.md
new file mode 100644
index 0000000..0647d5f
--- /dev/null
+++ b/documents/markdown/pandoc-md/10491.md
@@ -0,0 +1,35 @@
+```
+% pandoc -f mediawiki -t gfm
+{| class="wikitable"
+|-
+!
+!0
+!1
+!2
+!3
+!4
+!5
+!6
+!7
+|-
+!+0
+|q||p||z||r||y||9||x||8
+|-
+!+8
+|g||f||2||t||v||d||w||0
+|-
+!+16
+|s||3||j||n||5||4||k||h
+|-
+!+24
+|c||e||6||m||u||a||7||l
+|}
+^D
+| | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
+|-----|-----|-----|-----|-----|-----|-----|-----|-----|
+| +0 | q | p | z | r | y | 9 | x | 8 |
+| +8 | g | f | 2 | t | v | d | w | 0 |
+| +16 | s | 3 | j | n | 5 | 4 | k | h |
+| +24 | c | e | 6 | m | u | a | 7 | l |
+
+```
diff --git a/documents/markdown/pandoc-md/10537.md b/documents/markdown/pandoc-md/10537.md
new file mode 100644
index 0000000..14cf304
--- /dev/null
+++ b/documents/markdown/pandoc-md/10537.md
@@ -0,0 +1,24 @@
+```
+% pandoc -f pod -t html
+=encoding utf8
+
+=head1 NAME
+
+Test document
+^D
+<h1>NAME</h1>
+<p>Test document</p>
+```
+
+```
+% pandoc -f pod -t html
+=encoding utf8
+
+
+=head1 NAME
+
+Test document
+^D
+<h1>NAME</h1>
+<p>Test document</p>
+```
diff --git a/documents/markdown/pandoc-md/10594.md b/documents/markdown/pandoc-md/10594.md
new file mode 100644
index 0000000..b87c23e
--- /dev/null
+++ b/documents/markdown/pandoc-md/10594.md
@@ -0,0 +1,28 @@
+```
+% pandoc -f docbook -t native
+<orderedlist numeration="loweralpha">
+<title>header inside listing</title> // not rendered in any output format!
+<listitem>
+<simpara>first step</simpara>
+</listitem>
+</orderedlist>
+^D
+[ Div
+ ( "" , [] , [] )
+ [ Div
+ ( "" , [ "title" ] , [] )
+ [ Plain
+ [ Str "header"
+ , Space
+ , Str "inside"
+ , Space
+ , Str "listing"
+ ]
+ ]
+ , OrderedList
+ ( 1 , LowerAlpha , DefaultDelim )
+ [ [ Para [ Str "first" , Space , Str "step" ] ] ]
+ ]
+]
+
+```
diff --git a/documents/markdown/pandoc-md/10621.md b/documents/markdown/pandoc-md/10621.md
new file mode 100644
index 0000000..d4fc5d6
--- /dev/null
+++ b/documents/markdown/pandoc-md/10621.md
@@ -0,0 +1,7 @@
+```
+% pandoc -f markdown -t html
+[test](url
+"title")
+^D
+<p><a href="url" title="title">test</a></p>
+```
diff --git a/documents/markdown/pandoc-md/10631.md b/documents/markdown/pandoc-md/10631.md
new file mode 100644
index 0000000..7eea7a9
--- /dev/null
+++ b/documents/markdown/pandoc-md/10631.md
@@ -0,0 +1,8 @@
+GFM has funny treatment of escaped braces, requiring `\\{` instead of `\{`.
+
+```
+% pandoc -f gfm -t markdown
+$\\{x,y\\}$
+^D
+$\{x,y\}$
+```
diff --git a/documents/markdown/pandoc-md/10635.md b/documents/markdown/pandoc-md/10635.md
new file mode 100644
index 0000000..62f6375
--- /dev/null
+++ b/documents/markdown/pandoc-md/10635.md
@@ -0,0 +1,24 @@
+# Support for KOMA's `\minisec` command
+
+```
+% pandoc -f latex -t native
+\minisec{Montage}
+Zunächst suche man das Mauseloch.
+^D
+[ Header
+ 6
+ ( "montage" , [ "unnumbered" , "unlisted" ] , [] )
+ [ Str "Montage" ]
+, Para
+ [ Str "Zun\228chst"
+ , Space
+ , Str "suche"
+ , Space
+ , Str "man"
+ , Space
+ , Str "das"
+ , Space
+ , Str "Mauseloch."
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/10643.md b/documents/markdown/pandoc-md/10643.md
new file mode 100644
index 0000000..2cf41bf
--- /dev/null
+++ b/documents/markdown/pandoc-md/10643.md
@@ -0,0 +1,11 @@
+```
+% pandoc -f html -t native
+<p>A<style></style>B</p>
+^D
+[ Para
+ [ Str "A"
+ , RawInline (Format "html") "<style></style>"
+ , Str "B"
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/10650.md b/documents/markdown/pandoc-md/10650.md
new file mode 100644
index 0000000..3cd5688
--- /dev/null
+++ b/documents/markdown/pandoc-md/10650.md
@@ -0,0 +1,9 @@
+```
+% pandoc -t typst --wrap=preserve
+1\. I don't want this to be an enumerated list.
+2\. No, I don't: only a number before a paragraph.
+^D
+\1. I don't want this to be an enumerated list.
+\2. No, I don't: only a number before a paragraph.
+```
+
diff --git a/documents/markdown/pandoc-md/10659.md b/documents/markdown/pandoc-md/10659.md
new file mode 100644
index 0000000..e43236d
--- /dev/null
+++ b/documents/markdown/pandoc-md/10659.md
@@ -0,0 +1,45 @@
+```
+% pandoc -f latex -t native
+\includegraphics[
+width=5cm,
+]{abc.jpg}
+^D
+[ Para
+ [ Image
+ ( "" , [] , [ ( "width" , "5cm" ) ] )
+ [ Str "image" ]
+ ( "abc.jpg" , "" )
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\includegraphics[%
+width=5cm,%
+]{abc.jpg}
+^D
+[ Para
+ [ Image
+ ( "" , [] , [ ( "width" , "5cm" ) ] )
+ [ Str "image" ]
+ ( "abc.jpg" , "" )
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\includegraphics[width=5cm]{%
+abc.jpg%
+}
+^D
+[ Para
+ [ Image
+ ( "" , [] , [ ( "width" , "5cm" ) ] )
+ [ Str "image" ]
+ ( "abc.jpg" , "" )
+ ]
+]
+```
+
diff --git a/documents/markdown/pandoc-md/10672.md b/documents/markdown/pandoc-md/10672.md
new file mode 100644
index 0000000..5ff9285
--- /dev/null
+++ b/documents/markdown/pandoc-md/10672.md
@@ -0,0 +1,26 @@
+```
+% pandoc
+| This | Is |
+|:-----|:---|
+| With \
+| Cells
+^D
+<table>
+<thead>
+<tr>
+<th style="text-align: left;">This</th>
+<th style="text-align: left;">Is</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td style="text-align: left;">With \</td>
+<td style="text-align: left;"></td>
+</tr>
+<tr>
+<td style="text-align: left;">Cells</td>
+<td style="text-align: left;"></td>
+</tr>
+</tbody>
+</table>
+```
diff --git a/documents/markdown/pandoc-md/10708.md b/documents/markdown/pandoc-md/10708.md
new file mode 100644
index 0000000..d8296dd
--- /dev/null
+++ b/documents/markdown/pandoc-md/10708.md
@@ -0,0 +1,24 @@
+```
+% pandoc -f html -t mediawiki
+<dl>
+<dt>Case 1: Both subsets are non-empty</dt>
+<dd>
+In this case, …
+</dd>
+</dl>
+^D
+; Case 1<nowiki>:</nowiki> Both subsets are non-empty
+: In this case, …
+```
+
+```
+% pandoc -f mediawiki -t html
+; term : definition
+^D
+<dl>
+<dt>term</dt>
+<dd>
+definition
+</dd>
+</dl>
+```
diff --git a/documents/markdown/pandoc-md/10730.md b/documents/markdown/pandoc-md/10730.md
new file mode 100644
index 0000000..c9b696a
--- /dev/null
+++ b/documents/markdown/pandoc-md/10730.md
@@ -0,0 +1,7 @@
+```
+% pandoc -f org -t native
+=hi
+there=
+^D
+[ Para [ Code ( "" , [ "verbatim" ] , [] ) "hi there" ] ]
+```
diff --git a/documents/markdown/pandoc-md/10755.md b/documents/markdown/pandoc-md/10755.md
new file mode 100644
index 0000000..5a603cd
--- /dev/null
+++ b/documents/markdown/pandoc-md/10755.md
@@ -0,0 +1,71 @@
+```
+% pandoc -f native -t markdown
+[ Figure
+ ( "" , [] , [] )
+ (Caption
+ Nothing [ Para [ Str "An" , Space , Str "image." ] ])
+ [ Plain
+ [ Image
+ ( ""
+ , []
+ , []
+ )
+ [ Str "An" , Space , Str "image." ]
+ ( "media/rId20.jpg" , "" )
+ ]
+ ]
+]
+^D
+
+```
+
+```
+% pandoc -f native -t markdown -t markdown-implicit_figures
+[ Figure
+ ( "" , [] , [] )
+ (Caption
+ Nothing [ Para [ Str "An" , Space , Str "image." ] ])
+ [ Plain
+ [ Image
+ ( ""
+ , []
+ , []
+ )
+ [ Str "An" , Space , Str "image." ]
+ ( "media/rId20.jpg" , "" )
+ ]
+ ]
+]
+^D
+<figure>
+<img src="media/rId20.jpg" alt="An image." />
+<figcaption aria-hidden="true"><p>An image.</p></figcaption>
+</figure>
+```
+
+```
+% pandoc -f native -t markdown -t markdown-implicit_figures-raw_html
+[ Figure
+ ( "" , [] , [] )
+ (Caption
+ Nothing [ Para [ Str "An" , Space , Str "image." ] ])
+ [ Plain
+ [ Image
+ ( ""
+ , []
+ , []
+ )
+ [ Str "An" , Space , Str "image." ]
+ ( "media/rId20.jpg" , "" )
+ ]
+ ]
+]
+^D
+:::: figure
+
+
+::: caption
+An image.
+:::
+::::
+```
diff --git a/documents/markdown/pandoc-md/10758.md b/documents/markdown/pandoc-md/10758.md
new file mode 100644
index 0000000..885d264
--- /dev/null
+++ b/documents/markdown/pandoc-md/10758.md
@@ -0,0 +1,21 @@
+```
+% pandoc -f native -t markdown
+[ Figure
+ ( "" , [] , [] )
+ (Caption
+ Nothing
+ [ Para [ Str "Foo" , Space , Emph [ Str "emphasis" ] ] ])
+ [ Plain
+ [ Image
+ ( ""
+ , []
+ , []
+ )
+ [ Str "Foo" , Space , Str "emphasis" ]
+ ( "media/rId20.jpg" , "" )
+ ]
+ ]
+]
+^D
+
+```
diff --git a/documents/markdown/pandoc-md/10781.md b/documents/markdown/pandoc-md/10781.md
new file mode 100644
index 0000000..71860af
--- /dev/null
+++ b/documents/markdown/pandoc-md/10781.md
@@ -0,0 +1,8 @@
+```
+% pandoc -f latex -t markdown --wrap=preserve
+This is \texttt{--flag} with dashes.
+This is the same --flag without a code.
+^D
+This is `--flag` with dashes.
+This is the same --flag without a code.
+```
diff --git a/documents/markdown/pandoc-md/10791.md b/documents/markdown/pandoc-md/10791.md
new file mode 100644
index 0000000..e44878c
--- /dev/null
+++ b/documents/markdown/pandoc-md/10791.md
@@ -0,0 +1,14 @@
+```
+% pandoc -t opendocument
+Aboard **the luxury cruise ship Heart of the Ocean[^1] in the Atlantic Ocean**...
+
+[^1]: **Heart of the Ocean** (海洋之心) – The Heart of the Ocean
+^D
+<text:p text:style-name="Text_20_body">Aboard
+<text:span text:style-name="T1">the luxury cruise ship Heart of the
+Ocean</text:span><text:note text:id="ftn0" text:note-class="footnote"><text:note-citation>1</text:note-citation><text:note-body><text:p text:style-name="Footnote"><text:span text:style-name="T1">Heart
+of the Ocean</text:span> (海洋之心) – The Heart of the
+Ocean</text:p></text:note-body></text:note><text:span text:style-name="T1">
+in the Atlantic Ocean</text:span>…</text:p>
+
+```
diff --git a/documents/markdown/pandoc-md/10805.md b/documents/markdown/pandoc-md/10805.md
new file mode 100644
index 0000000..a25f695
--- /dev/null
+++ b/documents/markdown/pandoc-md/10805.md
@@ -0,0 +1,19 @@
+```
+% pandoc -t typst -f latex
+\begin{equation}
+ \label{eq:U}
+ U = A
+\end{equation}
+^D
+$ U = A $<eq:U>
+```
+
+```
+% pandoc -t typst -f latex
+\begin{equation}
+ \label{eq:U 2}
+ U = A
+\end{equation}
+^D
+$ U = A $#label("eq:U 2")
+```
diff --git a/documents/markdown/pandoc-md/10812.md b/documents/markdown/pandoc-md/10812.md
new file mode 100644
index 0000000..7609f91
--- /dev/null
+++ b/documents/markdown/pandoc-md/10812.md
@@ -0,0 +1,41 @@
+Check that the `four_space_rule` extension works for plain writer.
+
+```
+% pandoc -f markdown -t plain+four_space_rule
+This is the title
+
+Here we fix:
+
+- a
+- b
+- c
+^D
+This is the title
+
+Here we fix:
+
+- a
+- b
+- c
+```
+
+Check that the `four_space_rule` extension is off by default.
+
+```
+% pandoc -f markdown -t plain
+This is the title
+
+Here we fix:
+
+- a
+- b
+- c
+^D
+This is the title
+
+Here we fix:
+
+- a
+- b
+- c
+```
diff --git a/documents/markdown/pandoc-md/10825.md b/documents/markdown/pandoc-md/10825.md
new file mode 100644
index 0000000..90124aa
--- /dev/null
+++ b/documents/markdown/pandoc-md/10825.md
@@ -0,0 +1,39 @@
+```
+% pandoc -f docbook -t html
+<?xml version="1.0" encoding="utf-8"?>
+<book xmlns="http://docbook.org/ns/docbook" version="5.0">
+ <info><title>Literallayout test</title></info>
+ <chapter>
+ <info><title>Literallayout without class</title></info>
+ <literallayout>First line.
+Second line.
+ Third line, indented two spaces.</literallayout>
+ </chapter>
+ <chapter>
+ <info><title>Literallayout with normal class</title></info>
+ <literallayout class="normal">First line.
+Second line.
+ Third line, indented two spaces.</literallayout>
+ </chapter>
+ <chapter>
+ <info><title>Literallayout with monospaced</title></info>
+ <literallayout class="monospaced">First line.
+Second line.
+ Third line, indented two spaces.</literallayout>
+ </chapter>
+</book>
+^D
+<h1>Literallayout without class</h1>
+<div class="line-block">First line.<br />
+Second line.<br />
+ Third line, indented two spaces.</div>
+<h1>Literallayout with normal class</h1>
+<div class="line-block">First line.<br />
+Second line.<br />
+ Third line, indented two spaces.</div>
+<h1>Literallayout with monospaced</h1>
+<pre><code>First line.
+Second line.
+ Third line, indented two spaces.</code></pre>
+
+```
diff --git a/documents/markdown/pandoc-md/10836.md b/documents/markdown/pandoc-md/10836.md
new file mode 100644
index 0000000..864361b
--- /dev/null
+++ b/documents/markdown/pandoc-md/10836.md
@@ -0,0 +1,12 @@
+```
+% pandoc -f org -t latex
+Some equation here
+\begin{equation}
+x = y
+\end{equation}
+where $x$ is something important.
+^D
+Some equation here \begin{equation}
+x = y
+\end{equation} where \(x\) is something important.
+```
diff --git a/documents/markdown/pandoc-md/10848.md b/documents/markdown/pandoc-md/10848.md
new file mode 100644
index 0000000..004451c
--- /dev/null
+++ b/documents/markdown/pandoc-md/10848.md
@@ -0,0 +1,82 @@
+```
+% pandoc -f html -t markdown
+<table>
+<tr>
+<td colspan="3">A</td>
+<td rowspan="1" colspan="2">F</td>
+</tr>
+<tr>
+<td>C</td>
+<td colspan="2">B</td>
+<td colspan="2">H</td>
+</tr>
+<tr>
+<td colspan="2">D</td>
+<td colspan="2">E</td>
+<td>G</td>
+</tr>
+</table>
+^D
++---+---+---+---+---+
+| A | F |
++---+-------+-------+
+| C | B | H |
++---+---+---+---+---+
+| D | E | G |
++-------+-------+---+
+```
+
+```
+% pandoc -f html -t markdown
+<table>
+<tr>
+<td colspan="2">A</td>
+<td colspan="2">J</td>
+<td rowspan="3">F</td>
+</tr>
+<tr>
+<td rowspan="3">C</td>
+<td>B</td>
+<td rowspan="2" colspan="2">H</td>
+</tr>
+<tr>
+<td>D</td>
+</tr>
+<tr>
+<td colspan="4">K</td>
+</tr>
+</table>
+^D
++---+---+-------+---+
+| A | J | F |
++---+---+-------+ |
+| C | B | H | |
+| +---+ | |
+| | D | | |
+| +---+-------+---+
+| | K |
++---+---------------+
+```
+
+```
+% pandoc -f html -t markdown-simple_tables-multiline_tables-pipe_tables
+<table>
+ <tbody>
+ <tr>
+ <td>a</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td></td>
+ <td></td>
+ </tr>
+ </tbody>
+</table>
+^D
++---+---+
+| a | |
++---+---+
+| | |
++---+---+
+```
+
diff --git a/documents/markdown/pandoc-md/10855.md b/documents/markdown/pandoc-md/10855.md
new file mode 100644
index 0000000..6205913
--- /dev/null
+++ b/documents/markdown/pandoc-md/10855.md
@@ -0,0 +1,71 @@
+```
+% pandoc -t markdown
++----------+----+
+| h1 | h2 |
++:===:+===:+:===+
+| A | B |
++-----+----+----+
+| C | D | E |
++-----+----+----+
+^D
++-------------+----+
+| h1 | h2 |
++:====:+=====:+:===+
+| A | B |
++------+------+----+
+| C | D | E |
++------+------+----+
+
+```
+
+```
+% pandoc -t markdown
++-----+----+----+
+| h1 | h2 | h3 |
++:===:+===:+:===+
+| A | B |
++-----+----+----+
+| C | D | E |
++-----+----+----+
+^D
++------+------+----+
+| h1 | h2 | h3 |
++:====:+=====:+:===+
+| A | B |
++------+------+----+
+| C | D | E |
++------+------+----+
+
+```
+
+```
+% pandoc -t markdown
++:------:+:-----------:+
+| hello |  |
++--------+-------------+
+| hello |  |
++--------+-------------+
+^D
++:------:+:-----------:+
+| hello |  |
++--------+-------------+
+| hello |  |
++--------+-------------+
+
+```
+
+```
+% pandoc -t markdown
++:------:+:-----------:+
+| hello |  |
++--------+-------------+
+| hello |  |
++--------+-------------+
+^D
++:------:+:-----------:+
+| hello |  |
++--------+-------------+
+| hello |  |
++--------+-------------+
+
+```
diff --git a/documents/markdown/pandoc-md/10867.md b/documents/markdown/pandoc-md/10867.md
new file mode 100644
index 0000000..8852e11
--- /dev/null
+++ b/documents/markdown/pandoc-md/10867.md
@@ -0,0 +1,26 @@
+```
+% pandoc -f native -t markdown-raw_html
+[ Figure
+ ( "fig:foo" , [] , [ ( "label" , "1.1" ) ] )
+ (Caption
+ Nothing
+ [ Plain
+ [ Str "Figure" , Space , Str "1.1:" , Space , Str "Figure" ]
+ ])
+ [ Plain
+ [ Image
+ ( "" , [] , [] )
+ [ Str "Figure" , Space , Str "1.1:" , Space , Str "Figure" ]
+ ( "./image.png" , "" )
+ ]
+ ]
+]
+^D
+:::: {#fig:foo .figure label="1.1"}
+
+
+::: caption
+Figure 1.1: Figure
+:::
+::::
+```
diff --git a/documents/markdown/pandoc-md/10884.md b/documents/markdown/pandoc-md/10884.md
new file mode 100644
index 0000000..1114634
--- /dev/null
+++ b/documents/markdown/pandoc-md/10884.md
@@ -0,0 +1,17 @@
+```
+% pandoc -f markdown -t markdown
+ header1 header2
+ --------- ---------
+ r1c1 r1c2
+ r2c1 r2c2
+
+ : mycaption {#myid .myclass key="value"}
+^D
+ header1 header2
+ --------- ---------
+ r1c1 r1c2
+ r2c1 r2c2
+
+ : mycaption {#myid .myclass key="value"}
+
+```
diff --git a/documents/markdown/pandoc-md/10889.md b/documents/markdown/pandoc-md/10889.md
new file mode 100644
index 0000000..8f99685
--- /dev/null
+++ b/documents/markdown/pandoc-md/10889.md
@@ -0,0 +1,16 @@
+```
+% pandoc
+apple
+
+: pomaceous
+
+ fruit
+^D
+<dl>
+<dt>apple</dt>
+<dd>
+<p>pomaceous</p>
+<p>fruit</p>
+</dd>
+</dl>
+```
diff --git a/documents/markdown/pandoc-md/10890.md b/documents/markdown/pandoc-md/10890.md
new file mode 100644
index 0000000..508a9a3
--- /dev/null
+++ b/documents/markdown/pandoc-md/10890.md
@@ -0,0 +1,15 @@
+```
+% pandoc --tab-stop=2 --from=native --to=markdown
+[ DefinitionList
+ [ ( [ Str "apple" ]
+ , [ [ Para [ Str "pomaceous" ] , Para [ Str "fruit" ] ] ]
+ )
+ ]
+]
+^D
+apple
+
+: pomaceous
+
+ fruit
+```
diff --git a/documents/markdown/pandoc-md/10912.md b/documents/markdown/pandoc-md/10912.md
new file mode 100644
index 0000000..048f179
--- /dev/null
+++ b/documents/markdown/pandoc-md/10912.md
@@ -0,0 +1,16 @@
+```
+% pandoc -f docbook -t native
+<orderedlist numeration="arabic" startingnumber="4">
+<listitem>
+<simpara>Para1</simpara>
+</listitem>
+<listitem>
+<simpara>Para2</simpara>
+</listitem>
+</orderedlist>
+^D
+[ OrderedList
+ ( 4 , Decimal , DefaultDelim )
+ [ [ Para [ Str "Para1" ] ] , [ Para [ Str "Para2" ] ] ]
+]
+```
diff --git a/documents/markdown/pandoc-md/10915.md b/documents/markdown/pandoc-md/10915.md
new file mode 100644
index 0000000..36ba244
--- /dev/null
+++ b/documents/markdown/pandoc-md/10915.md
@@ -0,0 +1,8 @@
+```
+% pandoc -f latex
+\newcommand{\a}{\ifmmode x \else y \fi}
+$\a$ and \a
+^D
+<p><span class="math inline"><em>x</em></span> and y</p>
+```
+
diff --git a/documents/markdown/pandoc-md/10919.md b/documents/markdown/pandoc-md/10919.md
new file mode 100644
index 0000000..6f03c83
--- /dev/null
+++ b/documents/markdown/pandoc-md/10919.md
@@ -0,0 +1,21 @@
+# Org output with smart quotes turned on
+
+```
+% pandoc -t org+smart_quotes -s
+"It's nice" she said.
+^D
+#+options: ':t
+
+"It's nice" she said.
+```
+
+Same test, but with special strings turned off.
+```
+% pandoc -t org+smart_quotes-special_strings -s
+"It's nice" she said.
+^D
+#+options: ':t
+#+options: -:nil
+
+"It’s nice" she said.
+```
diff --git a/documents/markdown/pandoc-md/10926.md b/documents/markdown/pandoc-md/10926.md
new file mode 100644
index 0000000..315ffc3
--- /dev/null
+++ b/documents/markdown/pandoc-md/10926.md
@@ -0,0 +1,19 @@
+````
+% pandoc -f html -t gfm
+<div class="sourceCode" id="cb1"><pre
+class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="fu">test</span></span></code></pre></div>
+^D
+``` ruby
+test
+```
+````
+
+````
+% pandoc -f html -t gfm
+<pre
+class="border language-ruby"><code class="sourceCode ruby"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="fu">test</span></span></code></pre>
+^D
+``` ruby
+test
+```
+````
diff --git a/documents/markdown/pandoc-md/10942.md b/documents/markdown/pandoc-md/10942.md
new file mode 100644
index 0000000..3e0e70f
--- /dev/null
+++ b/documents/markdown/pandoc-md/10942.md
@@ -0,0 +1,97 @@
+Ungrouped field instruction:
+```
+% pandoc -f rtf -t native
+{\rtf1\ansi\deff0
+{\fonttbl{\f0\froman Times New Roman;}}
+{\colortbl;\red0\green0\blue0;}
+\deftab720
+
+\trowd\trleft0\cellx2000\cellx4000
+\pard\intbl
+{{\field{\*\fldinst HYPERLINK "https://example.com" }{\fldrslt {\hich\af0\loch\hich\af0\loch\cf0\f0\cf0\f0\loch
+{\*\bkmkstart _dx_frag_StartFragment}{\*\bkmkend _dx_frag_StartFragment}Problem Text}}}}\cell
+\pard\intbl Normal Text\cell
+\row
+
+\trowd\trleft0\cellx2000\cellx4000
+\pard\intbl Simple Text\cell
+\pard\intbl More Text\cell
+\row
+}
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para
+ [ Link
+ ( "" , [] , [] )
+ [ Str "Problem" , Space , Str "Text" ]
+ ( "https://example.com" , "" )
+ ]
+ ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "Normal" , Space , Str "Text" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "Simple" , Space , Str "Text" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "More" , Space , Str "Text" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
+
+Additionally, ungrouped field result:
+```
+% pandoc -f rtf -t native
+{\rtf1\ansi\ansicpg1252\cocoartf2867
+\cocoatextscaling0\cocoaplatform1{\fonttbl\f0\fnil\fcharset0 HelveticaNeue;}
+{\colortbl;\red255\green255\blue255;\red0\green0\blue0;}
+{\*\expandedcolortbl;;\cssrgb\c0\c0\c0;}
+\paperw11905\paperh16837\margl1133\margr1133\margb1133\margt1133
+\deftab720
+\pard\pardeftab720\partightenfactor0
+{\field{\*\fldinst{HYPERLINK "https://example.com"}}{\fldrslt
+\f0\fs22 \cf2 \up0 \nosupersub \ul \ulc2 link}}}
+^D
+[ Para
+ [ Underline
+ [ Link
+ ( "" , [] , [] )
+ [ Str "link" ]
+ ( "https://example.com" , "" )
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/10965.md b/documents/markdown/pandoc-md/10965.md
new file mode 100644
index 0000000..5657232
--- /dev/null
+++ b/documents/markdown/pandoc-md/10965.md
@@ -0,0 +1,47 @@
+```
+% pandoc -f markdown -t typst
+::: {lang="en"}
+This text should be in English.
+:::
+^D
+#block[
+#set text(lang: "en"); This text should be in English.
+
+]
+```
+
+```
+% pandoc -f markdown -t typst
+::: {lang="fr"}
+Ce texte devrait être en français.
+:::
+^D
+#block[
+#set text(lang: "fr"); Ce texte devrait être en français.
+
+]
+```
+
+```
+% pandoc -f markdown -t typst
+::: {lang="de-DE"}
+Dieser Text sollte auf Deutsch sein.
+:::
+^D
+#block[
+#set text(lang: "de"); Dieser Text sollte auf Deutsch sein.
+
+]
+```
+
+```
+% pandoc -f markdown -t typst
+::: {lang=""}
+This should not have lang set.
+:::
+^D
+#block[
+This should not have lang set.
+
+]
+```
diff --git a/documents/markdown/pandoc-md/10983.md b/documents/markdown/pandoc-md/10983.md
new file mode 100644
index 0000000..d31baf2
--- /dev/null
+++ b/documents/markdown/pandoc-md/10983.md
@@ -0,0 +1,22 @@
+```
+% pandoc --citeproc --csl command/chicago-fullnote-bibliography.csl -t plain
+---
+references:
+- id: test4
+ type: blog-post
+ title: "Username as author"
+ author:
+ - brtw
+ container-title: "Reddit"
+ issued:
+ year: 2004
+suppress-bibliography: true
+...
+
+[@test4]
+^D
+[1]
+
+[1] brtw, “Username as Author,” Reddit, 2004.
+
+```
diff --git a/documents/markdown/pandoc-md/10984.md b/documents/markdown/pandoc-md/10984.md
new file mode 100644
index 0000000..b718d95
--- /dev/null
+++ b/documents/markdown/pandoc-md/10984.md
@@ -0,0 +1,16 @@
+ ```
+ % pandoc -f html -t djot
+<h1 id="foo" class="a b">Hi</hi>
+^D
+{#foo .a .b}
+# Hi
+```
+
+In this one the id is suppressed by the djot writer because
+the same one would be automatically generated by the djot reader:
+```
+% pandoc -f html -t djot
+<h2 id="Introduction">Introduction</h2>
+^D
+## Introduction
+```
diff --git a/documents/markdown/pandoc-md/11006.md b/documents/markdown/pandoc-md/11006.md
new file mode 100644
index 0000000..585d355
--- /dev/null
+++ b/documents/markdown/pandoc-md/11006.md
@@ -0,0 +1,56 @@
+```
+% pandoc -f html -t asciidoc
+<ul>
+ <li>
+ <p>Paragraph one</p>
+ <p>Paragraph two to force a list continuation</p>
+ <ul>
+ <li>First nested</li>
+ <li>Second nested</li>
+ </ul>
+ </li>
+</ul>
+
+<p>How about ordered lists?</p>
+
+<ol>
+ <li>
+ <p>Paragraph one</p>
+ <p>Paragraph two to force a list continuation</p>
+ <ol><li>Nested item</li></ol>
+ </li>
+</ol>
+
+<p>With non-default attributes:</p>
+
+<ol>
+ <li>
+ <p>Paragraph one</p>
+ <p>Paragraph two to force a list continuation</p>
+ <ol start=5><li>Nested item</li></ol>
+ </li>
+</ol>
+^D
+* Paragraph one
++
+Paragraph two to force a list continuation
+
+** First nested
+** Second nested
+
+How about ordered lists?
+
+. Paragraph one
++
+Paragraph two to force a list continuation
+
+.. Nested item
+
+With non-default attributes:
+
+. Paragraph one
++
+Paragraph two to force a list continuation
+[start=5]
+.. Nested item
+```
diff --git a/documents/markdown/pandoc-md/11013.md b/documents/markdown/pandoc-md/11013.md
new file mode 100644
index 0000000..471d90e
--- /dev/null
+++ b/documents/markdown/pandoc-md/11013.md
@@ -0,0 +1,23 @@
+```
+% pandoc --csl command/chicago-fullnote-bibliography.csl -C --wrap=none -t plain
+---
+references:
+- id: test10
+ type: blog-post
+ title: "Test 10: Lowercase username in brackets, Works!"
+ author:
+ - literal: "[deleted]"
+ container-title: "Reddit"
+ issued:
+ year: 2009
+...
+
+blah [@test10].
+^D
+blah.[1]
+
+[deleted]. “Test 10: Lowercase Username in Brackets, Works!” Reddit, 2009.
+
+[1] [deleted], “Test 10: Lowercase Username in Brackets, Works!” Reddit, 2009.
+
+```
diff --git a/documents/markdown/pandoc-md/11017.md b/documents/markdown/pandoc-md/11017.md
new file mode 100644
index 0000000..07f3aca
--- /dev/null
+++ b/documents/markdown/pandoc-md/11017.md
@@ -0,0 +1,9 @@
+```
+% pandoc -t markdown -f typst
+#show heading: smallcaps
+
+= Introduction
+^D
+# [Introduction]{.smallcaps}
+
+```
diff --git a/documents/markdown/pandoc-md/11046.md b/documents/markdown/pandoc-md/11046.md
new file mode 100644
index 0000000..ee5ffcd
--- /dev/null
+++ b/documents/markdown/pandoc-md/11046.md
@@ -0,0 +1,19 @@
+```
+% pandoc --citeproc -t plain+smart --csl command/chicago-note-bibliography.csl
+---
+references:
+- id: doe
+ title: Title
+ type: book
+ date: 2006
+ author: John Doe
+...
+
+blah blah [@doe]---blah blah.
+^D
+blah blah[1]---blah blah.
+
+John Doe. Title, n.d.
+
+[1] John Doe, Title.
+```
diff --git a/documents/markdown/pandoc-md/11047.md b/documents/markdown/pandoc-md/11047.md
new file mode 100644
index 0000000..c651a1b
--- /dev/null
+++ b/documents/markdown/pandoc-md/11047.md
@@ -0,0 +1,7 @@
+```
+% pandoc -t typst --wrap=auto
+Full-time study: 2001-2003; Thesis submission: Nov 2005; Award: Jul 2006.
+^D
+Full-time study: 2001-2003; Thesis submission: Nov 2005; Award: Jul
+\2006.
+```
diff --git a/documents/markdown/pandoc-md/11048.md b/documents/markdown/pandoc-md/11048.md
new file mode 100644
index 0000000..bdcd849
--- /dev/null
+++ b/documents/markdown/pandoc-md/11048.md
@@ -0,0 +1,48 @@
+```
+% pandoc -f biblatex -t markdown -s
+@article{khatri2021spooky,
+ title = {Spooky action at a global distance: analysis of space-based
+ entanglement distribution for the quantum internet},
+ author = {Khatri, Sumeet and Brady, Anthony J and Desporte, Ren{\'e}e A and
+ Bart, Manon P and Dowling, Jonathan P},
+ journal = {{npj} Quantum Information},
+ volume = {7},
+ number = {1},
+ pages = {4},
+ doi = {10.1038/s41534-020-00327-5},
+ url = {https://doi.org/10.1038/s41534-020-00327-5},
+ year = {2021},
+ publisher = {Nature Publishing Group UK London},
+}
+^D
+---
+nocite: "[@*]"
+references:
+- author:
+ - family: Khatri
+ given: Sumeet
+ - family: Brady
+ given: Anthony J
+ - family: Desporte
+ given: Renée A
+ - family: Bart
+ given: Manon P
+ - family: Dowling
+ given: Jonathan P
+ container-title: "[npj]{.nocase} Quantum Information"
+ doi: 10.1038/s41534-020-00327-5
+ id: khatri2021spooky
+ issue: 1
+ issued: 2021
+ page: 4
+ publisher: Nature Publishing Group UK London
+ title: "Spooky action at a global distance: Analysis of space-based
+ entanglement distribution for the quantum internet"
+ title-short: Spooky action at a global distance
+ type: article-journal
+ url: "https://doi.org/10.1038/s41534-020-00327-5"
+ volume: 7
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/11090.md b/documents/markdown/pandoc-md/11090.md
new file mode 100644
index 0000000..d32c52b
--- /dev/null
+++ b/documents/markdown/pandoc-md/11090.md
@@ -0,0 +1,49 @@
+```
+% pandoc -f typst -t native
+#include "command/11090/ch1.typ"
+
+== Chapter Two
+
+#figure(
+ image("command/11090/media/image1.png"),
+ caption: [This is an image.]
+)
+^D
+[ Header
+ 2 ( "" , [] , [] ) [ Str "Chapter" , Space , Str "One" ]
+, Figure
+ ( "" , [] , [] )
+ (Caption
+ Nothing [ Para [ Str "An" , Space , Str "image." ] ])
+ [ Para
+ [ Image
+ ( "" , [] , [] )
+ []
+ ( "command/11090/media/image1.png" , "" )
+ ]
+ ]
+, Header
+ 2 ( "" , [] , [] ) [ Str "Chapter" , Space , Str "Two" ]
+, Figure
+ ( "" , [] , [] )
+ (Caption
+ Nothing
+ [ Para
+ [ Str "This"
+ , Space
+ , Str "is"
+ , Space
+ , Str "an"
+ , Space
+ , Str "image."
+ ]
+ ])
+ [ Para
+ [ Image
+ ( "" , [] , [] )
+ []
+ ( "command/11090/media/image1.png" , "" )
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/11101.md b/documents/markdown/pandoc-md/11101.md
new file mode 100644
index 0000000..77ce030
--- /dev/null
+++ b/documents/markdown/pandoc-md/11101.md
@@ -0,0 +1,15 @@
+```
+% pandoc -f typst -t native
+First paragraph.
+
+#pagebreak()
+
+Second paragraph.
+^D
+[ Para [ Str "First" , Space , Str "paragraph." ]
+, Div
+ ( "" , [ "page-break" ] , [ ( "wrapper" , "1" ) ] )
+ [ HorizontalRule ]
+, Para [ Str "Second" , Space , Str "paragraph." ]
+]
+```
\ No newline at end of file
diff --git a/documents/markdown/pandoc-md/11124.md b/documents/markdown/pandoc-md/11124.md
new file mode 100644
index 0000000..0343d26
--- /dev/null
+++ b/documents/markdown/pandoc-md/11124.md
@@ -0,0 +1,10 @@
+The heading is "unlinked" before adding it to the TOC.
+
+```
+% pandoc --to=latex
+<http://example.com/> {-}
+=========================
+^D
+\section*{\texorpdfstring{\url{http://example.com/}}{http://example.com/}}\label{httpexample.com}
+\addcontentsline{toc}{section}{{http://example.com/}}
+```
diff --git a/documents/markdown/pandoc-md/11128.md b/documents/markdown/pandoc-md/11128.md
new file mode 100644
index 0000000..ed0cbeb
--- /dev/null
+++ b/documents/markdown/pandoc-md/11128.md
@@ -0,0 +1,23 @@
+```
+% pandoc -f html -t markdown_strict+pipe_tables-raw_html
+<table>
+<tr>
+<th class="" colspan="2" rowspan="1"><b>Subject</b></th>
+<th class=""><b>Grade</b></th>
+</tr>
+<tr>
+<td class="" colspan="1" rowspan="2">Physics</td>
+<td class="">Practical</td>
+<td class="">A</td>
+</tr>
+<tr>
+<td class="">Theory</td>
+<td class="">B+</td>
+</tr>
+</table>
+^D
+| **Subject** | | **Grade** |
+|-------------|-----------|-----------|
+| Physics | Practical | A |
+| | Theory | B+ |
+```
diff --git a/documents/markdown/pandoc-md/11140.md b/documents/markdown/pandoc-md/11140.md
new file mode 100644
index 0000000..f585c48
--- /dev/null
+++ b/documents/markdown/pandoc-md/11140.md
@@ -0,0 +1,71 @@
+```
+% pandoc -f rst -t native
+.. figure:: image.png
+ :alt: my alt
+
+ Caption
+^D
+[ Figure
+ ( "" , [] , [] )
+ (Caption Nothing [ Plain [ Str "Caption" ] ])
+ [ Plain
+ [ Image
+ ( "" , [] , [] )
+ [ Str "my" , Space , Str "alt" ]
+ ( "image.png" , "" )
+ ]
+ ]
+]
+```
+
+```
+% pandoc -f rst -t native
+.. figure:: image.png
+
+ Caption
+^D
+[ Figure
+ ( "" , [] , [] )
+ (Caption Nothing [ Plain [ Str "Caption" ] ])
+ [ Plain
+ [ Image
+ ( "" , [] , [] ) [ Str "Caption" ] ( "image.png" , "" )
+ ]
+ ]
+]
+```
+
+```
+% pandoc -f native -t markdown
+[ Figure
+ ( "" , [] , [] )
+ (Caption
+ Nothing [ Plain [ Str "Caption" ] ])
+ [ Plain
+ [ Image ( "" , [] , [] ) [ Str "my", Space, Str "alt" ] ( "image.png" , "" )
+ ]
+ ]
+]
+^D
+{alt="my alt"}
+```
+
+Ignore `\pandocbounded`:
+```
+% pandoc -f latex -t native
+\begin{figure}
+\centering
+\pandocbounded{\includegraphics[keepaspectratio,alt={Caption}]{image.png}}
+\caption{Caption}
+\end{figure}
+^D
+[ Figure
+ ( "" , [] , [] )
+ (Caption Nothing [ Plain [ Str "Caption" ] ])
+ [ Para
+ [ Image
+ ( "" , [] , [] ) [ Str "Caption" ] ( "image.png" , "" )
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/11150.md b/documents/markdown/pandoc-md/11150.md
new file mode 100644
index 0000000..38898b1
--- /dev/null
+++ b/documents/markdown/pandoc-md/11150.md
@@ -0,0 +1,29 @@
+```
+% pandoc -f rst
+=== =====
+int float
+=== =====
+10 9.90
+-10 9.90
+=== =====
+^D
+<table>
+<thead>
+<tr>
+<th>int</th>
+<th>float</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>10</td>
+<td>9.90</td>
+</tr>
+<tr>
+<td>-10</td>
+<td>9.90</td>
+</tr>
+</tbody>
+</table>
+
+```
diff --git a/documents/markdown/pandoc-md/11162.md b/documents/markdown/pandoc-md/11162.md
new file mode 100644
index 0000000..f0496ef
--- /dev/null
+++ b/documents/markdown/pandoc-md/11162.md
@@ -0,0 +1,19 @@
+```
+% pandoc -f native -t rst
+[ BulletList
+ [ [ Plain [ Str "list" ]
+ , CodeBlock ( "" , [ "ruby" ] , [] ) "code = 7 # comment"
+ ]
+ , [ Plain [ Str "second" , Space , Str "item" ] ]
+ ]
+]
+^D
+- list
+
+ .. code:: ruby
+
+ code = 7 # comment
+
+- second item
+
+```
diff --git a/documents/markdown/pandoc-md/11188.md b/documents/markdown/pandoc-md/11188.md
new file mode 100644
index 0000000..a982b2d
--- /dev/null
+++ b/documents/markdown/pandoc-md/11188.md
@@ -0,0 +1,80 @@
+Parsing PARAMETERS of Org-mode blocks
+
+```
+% pandoc -f org --to=native
+#+attr_html: :width 10px
+#+BEGIN_myex :this that
+huhu
+#+END_myex
+^D
+[ Div
+ ( ""
+ , [ "myex" ]
+ , [ ( "width" , "10px" ) , ( "this" , "that" ) ]
+ )
+ [ Para [ Str "huhu" ] ]
+]
+```
+
+Python-style parameters are accepted, too.
+
+```
+% pandoc -f org --to=native
+#+BEGIN_myblock width=10px
+[[image.svg][logo]]
+#+END_myblock
+^D
+[ Div
+ ( "" , [ "myblock" ] , [ ( "width" , "10px" ) ] )
+ [ Para
+ [ Span
+ ( ""
+ , [ "spurious-link" ]
+ , [ ( "target" , "image.svg" ) ]
+ )
+ [ Emph [ Str "logo" ] ]
+ ]
+ ]
+]
+```
+
+The fallback is to put the remainder of the line into a `parameters`
+attribute.
+
+```
+% pandoc -f org --to=native
+#+BEGIN_myblock these are parameters in an unsupported format
+/OK/
+#+END_myblock
+^D
+[ Div
+ ( ""
+ , [ "myblock" ]
+ , [ ( "parameters"
+ , "these are parameters in an unsupported format"
+ )
+ ]
+ )
+ [ Para [ Emph [ Str "OK" ] ] ]
+]
+```
+
+Also works on dynamic blocks.
+
+```
+% pandoc -f org --to=markdown
+#+BEGIN: clocktable :scope subtree :maxlevel 3
+#+CAPTION: Clock summary at [2025-10-18 Sat 17:23]
+| Headline | Time |
+|--------------+--------|
+| *Total time* | *0:00* |
+#+END:
+^D
+::: {.clocktable scope="subtree" maxlevel="3"}
+ Headline Time
+ ---------------- ----------
+ **Total time** **0:00**
+
+ : Clock summary at \[2025-10-18 Sat 17:23\]
+:::
+```
diff --git a/documents/markdown/pandoc-md/11210.md b/documents/markdown/pandoc-md/11210.md
new file mode 100644
index 0000000..cfd3af7
--- /dev/null
+++ b/documents/markdown/pandoc-md/11210.md
@@ -0,0 +1,13 @@
+```
+% pandoc -t typst -f man
+.PP
+.IR login (1)
+.PP
+and a regular (paren) that should not be escaped.
+^D
+#emph[login]\(1)
+
+and a regular (paren) that should not be escaped.
+
+```
+
diff --git a/documents/markdown/pandoc-md/11211.md b/documents/markdown/pandoc-md/11211.md
new file mode 100644
index 0000000..0ecb889
--- /dev/null
+++ b/documents/markdown/pandoc-md/11211.md
@@ -0,0 +1,16 @@
+```
+% pandoc -f rtf -t native
+{\field{\*\fldinst{\rtlch\ab0\ai0\af2\alang1025\afs22\ltrch\b0\i0\fs22\lang1033\langnp1033\langfe1033\langfenp1033
+\loch\af2\dbch\af2\hich\f2\insrsid10976062\strike0\ulnone\cf1 HYPERLINK "https://example.com"}{\*\datafield 08d0c9ea79f9bace118c8200aa004ba90b0200000003000000e0c9ea79f9bace118c8200aa004ba90b28000000680074007400700073003a002f002f006500780061006d0070006c0065002e0063006f006d000000}}
+{\fldrslt{\rtlch\ab0\ai0\af2\alang1025\afs22\ltrch\b0\i0\fs22\lang1033\langnp1033\langfe1033\langfenp1033\loch\af2\dbch\af2\hich\f2\strike0\ul\cf2 link}}}
+^D
+[ Para
+ [ Underline
+ [ Link
+ ( "" , [] , [] )
+ [ Str "link" ]
+ ( "https://example.com" , "" )
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/11253.md b/documents/markdown/pandoc-md/11253.md
new file mode 100644
index 0000000..cc10d8b
--- /dev/null
+++ b/documents/markdown/pandoc-md/11253.md
@@ -0,0 +1,27 @@
+```
+% pandoc -f markdown -t native
+\ifstrequal{hello}{hello}{TRUE}{FALSE}
+\ifstrequal{hello}{world}{TRUE}{FALSE}
+^D
+[ Para
+ [ RawInline (Format "tex") "TRUE"
+ , SoftBreak
+ , RawInline (Format "tex") "FALSE"
+ ]
+]
+```
+
+```
+% pandoc -f markdown-latex_macros -t native
+\ifstrequal{hello}{hello}{TRUE}{FALSE}
+\ifstrequal{hello}{world}{TRUE}{FALSE}
+^D
+[ Para
+ [ RawInline
+ (Format "tex") "\\ifstrequal{hello}{hello}{TRUE}{FALSE}"
+ , SoftBreak
+ , RawInline
+ (Format "tex") "\\ifstrequal{hello}{world}{TRUE}{FALSE}"
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/1126.md b/documents/markdown/pandoc-md/1126.md
new file mode 100644
index 0000000..e78646f
--- /dev/null
+++ b/documents/markdown/pandoc-md/1126.md
@@ -0,0 +1,28 @@
+```
+% pandoc -f html -t latex
+\begin{eqnarray}
+A&=&B,\\
+C&=&D
+\end{eqnarray}
+^D
+\textbackslash begin\{eqnarray\} A\&=\&B,\textbackslash\textbackslash{}
+C\&=\&D \textbackslash end\{eqnarray\}
+```
+
+```
+% pandoc -f html+raw_tex -t latex
+<p>See \eqref{myeq}.</p>
+\begin{eqnarray}
+A&=&B,\\
+C&=&D
+\\label{myeq}
+\end{eqnarray}
+^D
+See \eqref{myeq}.
+
+\begin{eqnarray}
+A&=&B,\\
+C&=&D
+\\label{myeq}
+\end{eqnarray}
+```
diff --git a/documents/markdown/pandoc-md/11266.md b/documents/markdown/pandoc-md/11266.md
new file mode 100644
index 0000000..e7c5ae7
--- /dev/null
+++ b/documents/markdown/pandoc-md/11266.md
@@ -0,0 +1,19 @@
+```
+% pandoc -t latex
+$$
+\begin{eqnarray}
+S &\rightarrow& a A \nonumber \\
+A &\rightarrow& d B \ | \ b A \ | \ c A \nonumber \\
+B &\rightarrow& a c \ | \ b C \ | \ c A \nonumber \\
+C &\rightarrow& \epsilon \nonumber
+\end{eqnarray}
+$$
+^D
+
+\begin{eqnarray}
+S &\rightarrow& a A \nonumber \\
+A &\rightarrow& d B \ | \ b A \ | \ c A \nonumber \\
+B &\rightarrow& a c \ | \ b C \ | \ c A \nonumber \\
+C &\rightarrow& \epsilon \nonumber
+\end{eqnarray}
+```
diff --git a/documents/markdown/pandoc-md/11270.md b/documents/markdown/pandoc-md/11270.md
new file mode 100644
index 0000000..7cf6810
--- /dev/null
+++ b/documents/markdown/pandoc-md/11270.md
@@ -0,0 +1,25 @@
+```
+% pandoc -f markdown -t native -s
+---
+header-includes: |
+ \makeatletter
+ \beamer@ignorenonframefalse
+ \makeatother
+...
+
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "header-includes"
+ , MetaBlocks
+ [ RawBlock
+ (Format "tex")
+ "\\makeatletter\n\\beamer@ignorenonframefalse\n\\makeatother"
+ ]
+ )
+ ]
+ }
+ []
+```
diff --git a/documents/markdown/pandoc-md/11299.md b/documents/markdown/pandoc-md/11299.md
new file mode 100644
index 0000000..b8da865
--- /dev/null
+++ b/documents/markdown/pandoc-md/11299.md
@@ -0,0 +1,28 @@
+```
+% pandoc -f mediawiki -t native
+<foo>
+
+<samp>x</samp>
+
+<kbd>x</kbd>
+
+<var>x</var>
+
+<mark>This is ''highlighted''</mark>
+^D
+[ Para [ Str "<foo>" ]
+, Para [ Code ( "" , [ "sample" ] , [] ) "x" ]
+, Para [ Span ( "" , [ "kbd" ] , [] ) [ Str "x" ] ]
+, Para [ Code ( "" , [ "variable" ] , [] ) "x" ]
+, Para
+ [ Span
+ ( "" , [ "mark" ] , [] )
+ [ Str "This"
+ , Space
+ , Str "is"
+ , Space
+ , Emph [ Str "highlighted" ]
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/11300.md b/documents/markdown/pandoc-md/11300.md
new file mode 100644
index 0000000..141d462
--- /dev/null
+++ b/documents/markdown/pandoc-md/11300.md
@@ -0,0 +1,67 @@
+```
+% pandoc -f docbook -t native -s
+<?xml version="1.0"?>
+<book xmlns="http://docbook.org/ns/docbook" version="5.0" dir="ltr">
+ <info>
+ <title>Book title</title>
+ <subtitle>Book subtitle</subtitle>
+ </info>
+ <chapter>
+ <info>
+ <title>Chapter title</title>
+ </info>
+ <para>My sentence</para>
+ </chapter>
+</book>
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "subtitle"
+ , MetaInlines [ Str "Book" , Space , Str "subtitle" ]
+ )
+ , ( "title"
+ , MetaInlines [ Str "Book" , Space , Str "title" ]
+ )
+ ]
+ }
+ [ Header
+ 1 ( "" , [] , [] ) [ Str "Chapter" , Space , Str "title" ]
+ , Para [ Str "My" , Space , Str "sentence" ]
+ ]
+```
+
+```
+% pandoc -f docbook -t native -s
+<?xml version="1.0"?>
+<book xmlns="http://docbook.org/ns/docbook" version="5.0" dir="ltr">
+ <chapter>
+ <info>
+ <title>Chapter title</title>
+ </info>
+ <para>My sentence</para>
+ </chapter>
+ <info>
+ <title>Book title</title>
+ <subtitle>Book subtitle</subtitle>
+ </info>
+</book>
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "subtitle"
+ , MetaInlines [ Str "Book" , Space , Str "subtitle" ]
+ )
+ , ( "title"
+ , MetaInlines [ Str "Book" , Space , Str "title" ]
+ )
+ ]
+ }
+ [ Header
+ 1 ( "" , [] , [] ) [ Str "Chapter" , Space , Str "title" ]
+ , Para [ Str "My" , Space , Str "sentence" ]
+ ]
+```
diff --git a/documents/markdown/pandoc-md/11309.md b/documents/markdown/pandoc-md/11309.md
new file mode 100644
index 0000000..ae743ed
--- /dev/null
+++ b/documents/markdown/pandoc-md/11309.md
@@ -0,0 +1,6 @@
+```
+% pandoc -f rst -t native
+Cho\ **co**\ late
+^D
+[ Para [ Str "Cho" , Strong [ Str "co" ] , Str "late" ] ]
+```
diff --git a/documents/markdown/pandoc-md/11312.md b/documents/markdown/pandoc-md/11312.md
new file mode 100644
index 0000000..57bf287
--- /dev/null
+++ b/documents/markdown/pandoc-md/11312.md
@@ -0,0 +1,21 @@
+```
+% pandoc -f mediawiki -t texinfo
+foofoo
+
+ bar
+ baz
+
+foofoo
+^D
+@node Top
+@top Top
+
+foofoo
+
+@example
+bar
+baz
+@end example
+
+foofoo
+```
diff --git a/documents/markdown/pandoc-md/11341.md b/documents/markdown/pandoc-md/11341.md
new file mode 100644
index 0000000..c04c2f3
--- /dev/null
+++ b/documents/markdown/pandoc-md/11341.md
@@ -0,0 +1,9 @@
+```
+% pandoc -t commonmark -f html
+<h1>The Hobbit<br>or<br>There and Back Again</h1>
+^D
+The Hobbit\
+or\
+There and Back Again
+====================
+```
diff --git a/documents/markdown/pandoc-md/11342.md b/documents/markdown/pandoc-md/11342.md
new file mode 100644
index 0000000..7e6df30
--- /dev/null
+++ b/documents/markdown/pandoc-md/11342.md
@@ -0,0 +1,33 @@
+Subfigures should be converted to *fig-group* elements.
+
+```
+% pandoc -f latex -t jats
+\begin{figure}[H]
+ \begin{subfigure}
+ \centering
+ \includegraphics[height=1.5in]{assets/A.png}
+ \caption{Graph for function *A*.}
+ \label{fig:A}
+ \end{subfigure}
+ \begin{subfigure}
+ \centering
+ \includegraphics[height=1.5in]{assets/B.png}
+ \caption{Graph for function *B*.}
+ \label{fig:B}
+ \end{subfigure}
+ \label{fig:graphs}
+ \caption{Function graphs.}
+\end{figure}
+^D
+<fig-group id="figU003Agraphs">
+ <caption><p>Function graphs.</p></caption>
+ <fig id="figU003AA">
+ <caption><p>Graph for function *A*.</p></caption>
+ <graphic mimetype="image" mime-subtype="png" xlink:href="assets/A.png" />
+ </fig>
+ <fig id="figU003AB">
+ <caption><p>Graph for function *B*.</p></caption>
+ <graphic mimetype="image" mime-subtype="png" xlink:href="assets/B.png" />
+ </fig>
+</fig-group>
+```
\ No newline at end of file
diff --git a/documents/markdown/pandoc-md/11348.md b/documents/markdown/pandoc-md/11348.md
new file mode 100644
index 0000000..1871808
--- /dev/null
+++ b/documents/markdown/pandoc-md/11348.md
@@ -0,0 +1,61 @@
+```
+% pandoc -f markdown -t native
+$ invalid opening inline math$
+
+$
+invalid opening inline math$
+
+$invalid closing inline math $
+
+$invalid closing inline math
+$
+
+$valid inline math$
+^D
+[ Para
+ [ Str "$"
+ , Space
+ , Str "invalid"
+ , Space
+ , Str "opening"
+ , Space
+ , Str "inline"
+ , Space
+ , Str "math$"
+ ]
+, Para
+ [ Str "$"
+ , SoftBreak
+ , Str "invalid"
+ , Space
+ , Str "opening"
+ , Space
+ , Str "inline"
+ , Space
+ , Str "math$"
+ ]
+, Para
+ [ Str "$invalid"
+ , Space
+ , Str "closing"
+ , Space
+ , Str "inline"
+ , Space
+ , Str "math"
+ , Space
+ , Str "$"
+ ]
+, Para
+ [ Str "$invalid"
+ , Space
+ , Str "closing"
+ , Space
+ , Str "inline"
+ , Space
+ , Str "math"
+ , SoftBreak
+ , Str "$"
+ ]
+, Para [ Math InlineMath "valid inline math" ]
+]
+```
diff --git a/documents/markdown/pandoc-md/11362.md b/documents/markdown/pandoc-md/11362.md
new file mode 100644
index 0000000..9e6c221
--- /dev/null
+++ b/documents/markdown/pandoc-md/11362.md
@@ -0,0 +1,17 @@
+```
+% pandoc -f markdown -t asciidoc
+This is a _test_[^1].
+
+And yet another **one**[^1].
+
+We can also try to write #hashtags [this]{.test}.
+
+[^1]: Test footnote.
+^D
+This is a __test__footnote:[Test footnote.].
+
+And yet another **one**footnote:[Test footnote.].
+
+We can also try to write ++#++hashtags [.test]#this#.
+
+```
diff --git a/documents/markdown/pandoc-md/11364.md b/documents/markdown/pandoc-md/11364.md
new file mode 100644
index 0000000..00a8b8e
--- /dev/null
+++ b/documents/markdown/pandoc-md/11364.md
@@ -0,0 +1,75 @@
+```
+% pandoc -f rtf -t native
+{\rtf1\ansi\deff3\adeflang1025
+{\fonttbl{\f0\froman\fprq2\fcharset0 Times New Roman;}{\f1\froman\fprq2\fcharset2 Symbol;}{\f2\fswiss\fprq2\fcharset0 Arial;}{\f3\froman\fprq2\fcharset0 Liberation Serif{\*\falt Times New Roman};}{\f4\fnil\fprq0\fcharset2 OpenSymbol{\*\falt Arial Unicode MS};}{\f5\fswiss\fprq2\fcharset0 Liberation Sans{\*\falt Arial};}{\f6\fnil\fprq2\fcharset0 Noto Sans CJK SC;}{\f7\fnil\fprq2\fcharset0 Matangi Light;}{\f8\fnil\fprq0\fcharset128 Matangi Light;}{\f9\fnil\fprq0\fcharset128 OpenSymbol{\*\falt Arial Unicode MS};}}
+{\colortbl;\red0\green0\blue0;\red0\green0\blue255;\red0\green255\blue255;\red0\green255\blue0;\red255\green0\blue255;\red255\green0\blue0;\red255\green255\blue0;\red255\green255\blue255;\red0\green0\blue128;\red0\green128\blue128;\red0\green128\blue0;\red128\green0\blue128;\red128\green0\blue0;\red128\green128\blue0;\red128\green128\blue128;\red192\green192\blue192;}
+{\stylesheet{\s0\snext0\widctlpar\hyphpar0\ltrpar\kerning1\cf0\rtlch\af7\afs24\alang1081\ltrch\hich\af3\afs24\alang1033\dbch\af10\langfe2052\loch\f3\fs24\lang1033 Normal;}
+{\*\cs15\snext15\rtlch\af4\ltrch\hich\af4\dbch\af4\loch\f4 Bullets;}
+{\s16\sbasedon0\snext17\sb240\sa120\keepn\rtlch\af7\afs28\ltrch\hich\af5\afs28\dbch\af6\loch\f5\fs28 Heading;}
+{\s17\sbasedon0\snext17\sl276\slmult1\sb0\sa140 Body Text;}
+{\s18\sbasedon17\snext18\rtlch\af8\ltrch List;}
+{\s19\sbasedon0\snext19\sb120\sa120\noline\rtlch\af8\afs24\ai\ltrch\fs24\i caption;}
+{\s20\sbasedon0\snext20\noline\rtlch\af8\ltrch Index;}
+{\s21\sbasedon0\snext21\nowidctlpar\noline Table Contents;}
+}{\*\listtable{\list\listtemplateid1
+{\listlevel\levelnfc23\leveljc0\levelstartat1\levelfollow0{\leveltext \'01\u8226 ?;}{\levelnumbers;}\f9\rtlch\af4\ltrch\fi-360\li720}
+{\listlevel\levelnfc23\leveljc0\levelstartat1\levelfollow0{\leveltext \'01\u9702 ?;}{\levelnumbers;}\f9\rtlch\af4\ltrch\fi-360\li1080}
+{\listlevel\levelnfc23\leveljc0\levelstartat1\levelfollow0{\leveltext \'01\u9642 ?;}{\levelnumbers;}\f9\rtlch\af4\ltrch\fi-360\li1440}
+{\listlevel\levelnfc23\leveljc0\levelstartat1\levelfollow0{\leveltext \'01\u8226 ?;}{\levelnumbers;}\f9\rtlch\af4\ltrch\fi-360\li1800}
+{\listlevel\levelnfc23\leveljc0\levelstartat1\levelfollow0{\leveltext \'01\u9702 ?;}{\levelnumbers;}\f9\rtlch\af4\ltrch\fi-360\li2160}
+{\listlevel\levelnfc23\leveljc0\levelstartat1\levelfollow0{\leveltext \'01\u9642 ?;}{\levelnumbers;}\f9\rtlch\af4\ltrch\fi-360\li2520}
+{\listlevel\levelnfc23\leveljc0\levelstartat1\levelfollow0{\leveltext \'01\u8226 ?;}{\levelnumbers;}\f9\rtlch\af4\ltrch\fi-360\li2880}
+{\listlevel\levelnfc23\leveljc0\levelstartat1\levelfollow0{\leveltext \'01\u9702 ?;}{\levelnumbers;}\f9\rtlch\af4\ltrch\fi-360\li3240}
+{\listlevel\levelnfc23\leveljc0\levelstartat1\levelfollow0{\leveltext \'01\u9642 ?;}{\levelnumbers;}\f9\rtlch\af4\ltrch\fi-360\li3600}\listid1}
+{\list\listtemplateid2
+{\listlevel\levelnfc255\leveljc0\levelstartat1\levelfollow2{\leveltext \'00;}{\levelnumbers;}\fi0\li0}
+{\listlevel\levelnfc255\leveljc0\levelstartat1\levelfollow2{\leveltext \'00;}{\levelnumbers;}\fi0\li0}
+{\listlevel\levelnfc255\leveljc0\levelstartat1\levelfollow2{\leveltext \'00;}{\levelnumbers;}\fi0\li0}
+{\listlevel\levelnfc255\leveljc0\levelstartat1\levelfollow2{\leveltext \'00;}{\levelnumbers;}\fi0\li0}
+{\listlevel\levelnfc255\leveljc0\levelstartat1\levelfollow2{\leveltext \'00;}{\levelnumbers;}\fi0\li0}
+{\listlevel\levelnfc255\leveljc0\levelstartat1\levelfollow2{\leveltext \'00;}{\levelnumbers;}\fi0\li0}
+{\listlevel\levelnfc255\leveljc0\levelstartat1\levelfollow2{\leveltext \'00;}{\levelnumbers;}\fi0\li0}
+{\listlevel\levelnfc255\leveljc0\levelstartat1\levelfollow2{\leveltext \'00;}{\levelnumbers;}\fi0\li0}
+{\listlevel\levelnfc255\leveljc0\levelstartat1\levelfollow2{\leveltext \'00;}{\levelnumbers;}\fi0\li0}\listid2}
+}{\listoverridetable{\listoverride\listid1\listoverridecount0\ls1}{\listoverride\listid2\listoverridecount0\ls2}}{\*\generator LibreOffice/25.8.4.2$Linux_X86_64 LibreOffice_project/580$Build-2}{\info{\creatim\yr2025\mo12\dy28\hr10\min51}{\revtim\yr2025\mo12\dy28\hr10\min53}{\printim\yr0\mo0\dy0\hr0\min0}}{\*\userprops}\deftab709
+\hyphauto1\viewscale140\formshade\nobrkwrptbl\paperh15840\paperw12240\margl1134\margr1134\margt1134\margb1134\sectd\sbknone\sftnnar\saftnnrlc\sectunlocked1\pgwsxn12240\pghsxn15840\marglsxn1134\margrsxn1134\margtsxn1134\margbsxn1134\ftnbj\ftnstart1\ftnrstcont\ftnnar\fet\aftnrstcont\aftnstart1\aftnnrlc
+{\*\ftnsep\chftnsep}\pgndec\pard\plain \s0\widctlpar\hyphpar0\ltrpar\kerning1\cf0\rtlch\af7\afs24\alang1081\ltrch\hich\af3\afs24\alang1033\dbch\af10\langfe2052\loch\f3\fs24\lang1033{\listtext\pard\plain \rtlch\af4\ltrch\hich\af4\dbch\af4\loch\f4 \u8226\'95\tab}\ilvl0\ls1 \fi-360\li720\lin720\ql\ltrpar{
+List item}
+\par \trowd\trql\ltrrow\trpaddft3\trpaddt0\trpaddfl3\trpaddl0\trpaddfb3\trpaddb0\trpaddfr3\trpaddr0\clbrdrt\brdrs\brdrw10\brdrcf1\clpadfl3\clpadl55\clbrdrl\brdrs\brdrw10\brdrcf1\clpadft3\clpadt55\clbrdrb\brdrs\brdrw10\brdrcf1\clpadfb3\clpadb55\clpadfr3\clpadr55\cellx4986\clbrdrt\brdrs\brdrw10\brdrcf1\clpadfl3\clpadl55\clbrdrl\brdrs\brdrw10\brdrcf1\clpadft3\clpadt55\clbrdrb\brdrs\brdrw10\brdrcf1\clpadfb3\clpadb55\clbrdrr\brdrs\brdrw10\brdrcf1\clpadfr3\clpadr55\cellx9972\pard\plain \s21\nowidctlpar\noline\intbl\ql\ltrpar{
+A}\cell\pard\plain \s21\nowidctlpar\noline\intbl\ql\ltrpar{
+B}\cell\row\pard \pard\plain \s0\widctlpar\hyphpar0\ltrpar\kerning1\cf0\rtlch\af7\afs24\alang1081\ltrch\hich\af3\afs24\alang1033\dbch\af10\langfe2052\loch\f3\fs24\lang1033\ql\ltrpar
+\par }
+^D
+[ BulletList
+ [ [ Para [ Str "List" , Space , Str "item" ] ] ]
+, Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "A" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "B" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
diff --git a/documents/markdown/pandoc-md/11384.md b/documents/markdown/pandoc-md/11384.md
new file mode 100644
index 0000000..8530687
--- /dev/null
+++ b/documents/markdown/pandoc-md/11384.md
@@ -0,0 +1,17 @@
+```
+% pandoc -t markdown -f native
+[ Para [ Math DisplayMath "\ne = mc^2\n" ] ]
+^D
+$$
+e = mc^2
+$$
+```
+
+But we need to collapse spaces around inline math:
+
+```
+% pandoc -t markdown -f native
+[ Para [ Math InlineMath "\ne=mc\n" ]]
+^D
+$e=mc$
+```
diff --git a/documents/markdown/pandoc-md/11409.md b/documents/markdown/pandoc-md/11409.md
new file mode 100644
index 0000000..bbf12cb
--- /dev/null
+++ b/documents/markdown/pandoc-md/11409.md
@@ -0,0 +1,11 @@
+```
+% pandoc -t native
+text^[sup]{.class}^
+^D
+[ Para
+ [ Str "text"
+ , Superscript
+ [ Span ( "" , [ "class" ] , [] ) [ Str "sup" ] ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/11420.md b/documents/markdown/pandoc-md/11420.md
new file mode 100644
index 0000000..55eba02
--- /dev/null
+++ b/documents/markdown/pandoc-md/11420.md
@@ -0,0 +1,15 @@
+````
+% pandoc -t revealjs --syntax-highlighting=idiomatic
+# Slide
+
+```python
+def hello():
+ print("Hello")
+```
+^D
+<section id="slide" class="slide level1">
+<h1>Slide</h1>
+<pre><code class="language-python">def hello():
+ print("Hello")</code></pre>
+</section>
+````
diff --git a/documents/markdown/pandoc-md/11422.md b/documents/markdown/pandoc-md/11422.md
new file mode 100644
index 0000000..fa9930a
--- /dev/null
+++ b/documents/markdown/pandoc-md/11422.md
@@ -0,0 +1,12 @@
+```
+% pandoc -f docbook -t markdown
+<example>
+ <para>
+ Example without a title.
+ </para>
+</example>
+^D
+::: example
+Example without a title.
+:::
+```
diff --git a/documents/markdown/pandoc-md/11450.md b/documents/markdown/pandoc-md/11450.md
new file mode 100644
index 0000000..0a976b3
--- /dev/null
+++ b/documents/markdown/pandoc-md/11450.md
@@ -0,0 +1,62 @@
+Test for \footnotemark and \footnotetext (issue #11450)
+
+```
+% pandoc -f latex -t native
+Text\footnotemark{}.
+\footnotetext{The footnote content.}
+^D
+[ Para
+ [ Str "Text"
+ , Note
+ [ Para
+ [ Str "The"
+ , Space
+ , Str "footnote"
+ , Space
+ , Str "content."
+ ]
+ ]
+ , Str "."
+ ]
+]
+```
+
+With explicit footnote numbers:
+
+```
+% pandoc -f latex -t native
+First\footnotemark[1] and second\footnotemark[2].
+\footnotetext[1]{First note.}
+\footnotetext[2]{Second note.}
+^D
+[ Para
+ [ Str "First"
+ , Note [ Para [ Str "First" , Space , Str "note." ] ]
+ , Space
+ , Str "and"
+ , Space
+ , Str "second"
+ , Note [ Para [ Str "Second" , Space , Str "note." ] ]
+ , Str "."
+ ]
+]
+```
+
+Mixed with regular footnotes:
+
+```
+% pandoc -f latex -t native
+Text\footnotemark[1] and more\footnote{Regular footnote.}
+\footnotetext[1]{Marked footnote.}
+^D
+[ Para
+ [ Str "Text"
+ , Note [ Para [ Str "Marked" , Space , Str "footnote." ] ]
+ , Space
+ , Str "and"
+ , Space
+ , Str "more"
+ , Note [ Para [ Str "Regular" , Space , Str "footnote." ] ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/11455.md b/documents/markdown/pandoc-md/11455.md
new file mode 100644
index 0000000..70fdbec
--- /dev/null
+++ b/documents/markdown/pandoc-md/11455.md
@@ -0,0 +1,26 @@
+```
+% pandoc -f textile -t html
+| foo | bar |
+| table
+* item 1
+* item 2
+* item 3 | xxx |
+^D
+<table>
+<tbody>
+<tr>
+<td>foo</td>
+<td>bar</td>
+</tr>
+<tr>
+<td><p>table</p>
+<ul>
+<li>item 1</li>
+<li>item 2</li>
+<li>item 3</li>
+</ul></td>
+<td>xxx</td>
+</tr>
+</tbody>
+</table>
+```
diff --git a/documents/markdown/pandoc-md/11463.md b/documents/markdown/pandoc-md/11463.md
new file mode 100644
index 0000000..e29ab56
--- /dev/null
+++ b/documents/markdown/pandoc-md/11463.md
@@ -0,0 +1,13 @@
+```
+% pandoc -t typst
+'hi' and \'
+^D
+'hi' and \'
+```
+
+```
+% pandoc -f markdown -t typst | pandoc -f typst -t markdown
+"hi" \" 'hi' and \'
+^D
+"hi" \" 'hi' and \'
+```
diff --git a/documents/markdown/pandoc-md/11479.md b/documents/markdown/pandoc-md/11479.md
new file mode 100644
index 0000000..b3d43a6
--- /dev/null
+++ b/documents/markdown/pandoc-md/11479.md
@@ -0,0 +1,31 @@
+```
+% pandoc -f docbook -t gfm
+<important>
+<itemizedlist>
+<listitem>
+<simpara>Test.</simpara>
+</listitem>
+<listitem>
+<simpara>Test 2.</simpara>
+</listitem>
+</itemizedlist>
+</important>
+^D
+> [!IMPORTANT]
+> - Test.
+>
+> - Test 2.
+```
+
+```
+% pandoc -f gfm -t gfm
+> [!IMPORTANT]
+> - Test.
+>
+> - Test 2.
+^D
+> [!IMPORTANT]
+> - Test.
+>
+> - Test 2.
+```
diff --git a/documents/markdown/pandoc-md/11486.md b/documents/markdown/pandoc-md/11486.md
new file mode 100644
index 0000000..4496586
--- /dev/null
+++ b/documents/markdown/pandoc-md/11486.md
@@ -0,0 +1,82 @@
+```
+% pandoc -t revealjs --template=command/11486/scroll.revealjs
+---
+view: scroll
+---
+^D
+ scrollActivationWidth: 0,
+ scrollSnap: 'mandatory',
+ scrollProgress: 'auto',
+```
+
+```
+% pandoc -t revealjs --template=command/11486/scroll.revealjs
+---
+view: scroll
+scrollSnap: false
+---
+^D
+ scrollActivationWidth: 0,
+ scrollSnap: false,
+ scrollProgress: 'auto',
+```
+
+```
+% pandoc -t revealjs --template=command/11486/scroll.revealjs
+---
+view: scroll
+scrollSnap: proximity
+---
+^D
+ scrollActivationWidth: 0,
+ scrollSnap: 'proximity',
+ scrollProgress: 'auto',
+```
+
+```
+% pandoc -t revealjs --template=command/11486/scroll.revealjs
+---
+view: scroll
+scrollActivationWidth: 500
+---
+^D
+ scrollActivationWidth: 500,
+ scrollSnap: 'mandatory',
+ scrollProgress: 'auto',
+```
+
+```
+% pandoc -t revealjs --template=command/11486/scroll.revealjs
+---
+view: scroll
+scrollProgress: true
+---
+^D
+ scrollActivationWidth: 0,
+ scrollSnap: 'mandatory',
+ scrollProgress: true,
+```
+
+```
+% pandoc -t revealjs --template=command/11486/scroll.revealjs
+---
+view: scroll
+scrollProgress: false
+---
+^D
+ scrollActivationWidth: 0,
+ scrollSnap: 'mandatory',
+ scrollProgress: false,
+```
+
+```
+% pandoc -t revealjs --template=command/11486/scroll.revealjs
+---
+view: scroll
+scrollProgress: auto
+---
+^D
+ scrollActivationWidth: 0,
+ scrollSnap: 'mandatory',
+ scrollProgress: 'auto',
+```
diff --git a/documents/markdown/pandoc-md/11490.md b/documents/markdown/pandoc-md/11490.md
new file mode 100644
index 0000000..e2ca29e
--- /dev/null
+++ b/documents/markdown/pandoc-md/11490.md
@@ -0,0 +1,13 @@
+```
+% pandoc -t markdown
+<&lt;
+^D
+\<\<
+```
+
+```
+% pandoc -t markdown
+&#xa0;
+^D
+\ 
+```
diff --git a/documents/markdown/pandoc-md/11494.md b/documents/markdown/pandoc-md/11494.md
new file mode 100644
index 0000000..eceea05
--- /dev/null
+++ b/documents/markdown/pandoc-md/11494.md
@@ -0,0 +1,73 @@
+External images should not use [[File:...]] syntax.
+
+Inline external image:
+```
+% pandoc -f native -t mediawiki
+[Para [Image ("",[],[]) [] ("https://example.org/image.png", "")]]
+^D
+<nowiki></nowiki>https://example.org/image.png<nowiki></nowiki>
+```
+
+Inline local image (should still use [[File:]]):
+```
+% pandoc -f native -t mediawiki
+[Para [Image ("",[],[]) [] ("local.png", "")]]
+^D
+[[File:local.png]]
+```
+
+Figure with external image (from markdown):
+```
+% pandoc -f markdown -t mediawiki
+
+^D
+<nowiki></nowiki>https://example.org/figure.png<nowiki></nowiki>
+```
+
+Local image (from markdown, no caption):
+```
+% pandoc -f markdown -t mediawiki
+
+^D
+[[File:local.png]]
+```
+
+Figure with caption and external image:
+```
+% pandoc -f markdown -t mediawiki
+
+^D
+<div class="figure">
+<nowiki></nowiki>https://example.org/figure.png<nowiki></nowiki>
+</div>
+```
+
+Figure with caption and local image:
+```
+% pandoc -f markdown -t mediawiki
+
+^D
+<div class="figure">
+[[File:local.png|Caption]]
+</div>
+```
+
+SimpleFigure with external image (native format with fig: title):
+```
+% pandoc -f native -t mediawiki
+[Figure ("",[],[]) (Caption Nothing []) [Para [Image ("",[],[]) [Str "caption"] ("https://example.org/figure.png", "fig:")]]]
+^D
+<div class="figure">
+<nowiki></nowiki>https://example.org/figure.png<nowiki></nowiki>
+</div>
+```
+
+SimpleFigure with local image (native format with fig: title):
+```
+% pandoc -f native -t mediawiki
+[Figure ("",[],[]) (Caption Nothing []) [Para [Image ("",[],[]) [Str "caption"] ("local.png", "fig:")]]]
+^D
+<div class="figure">
+[[File:local.png|thumb|none|alt=caption|caption]]
+</div>
+```
diff --git a/documents/markdown/pandoc-md/11498.md b/documents/markdown/pandoc-md/11498.md
new file mode 100644
index 0000000..3de3273
--- /dev/null
+++ b/documents/markdown/pandoc-md/11498.md
@@ -0,0 +1,121 @@
+```
+% pandoc -f markdown -t icml
+{object-style="myStyle"}
+^D
+<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Paragraph">
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <Rectangle Self="uec" StrokeWeight="0" ItemTransform="1 0 0 1 32 -32" AppliedObjectStyle="ObjectStyle/myStyle">
+ <Properties>
+ <PathGeometry>
+ <GeometryPathType PathOpen="false">
+ <PathPointArray>
+ <PathPointType Anchor="-32 -32" LeftDirection="-32 -32" RightDirection="-32 -32" />
+ <PathPointType Anchor="-32 32" LeftDirection="-32 32" RightDirection="-32 32" />
+ <PathPointType Anchor="32 32" LeftDirection="32 32" RightDirection="32 32" />
+ <PathPointType Anchor="32 -32" LeftDirection="32 -32" RightDirection="32 -32" />
+ </PathPointArray>
+ </GeometryPathType>
+ </PathGeometry>
+ </Properties>
+ <Image Self="ue6" ItemTransform="1 0 0 1 -32 -32">
+ <Properties>
+ <Profile type="string">
+ $ID/Embedded
+ </Profile>
+ <GraphicBounds Left="0" Top="0" Right="64" Bottom="64" />
+ </Properties>
+ <Link Self="ueb" LinkResourceURI="file:command/11498.png" />
+ </Image>
+ </Rectangle>
+ </CharacterStyleRange>
+</ParagraphStyleRange>
+```
+```
+% pandoc -s -f markdown -t icml
+{object-style="myStyle"}
+^D
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<?aid style="50" type="snippet" readerVersion="6.0" featureSet="513" product="8.0(370)" ?>
+<?aid SnippetType="InCopyInterchange"?>
+<Document DOMVersion="8.0" Self="pandoc_doc">
+ <RootCharacterStyleGroup Self="pandoc_character_styles">
+ <CharacterStyle Self="$ID/NormalCharacterStyle" Name="Default" />
+ <CharacterStyle Self="CharacterStyle/" Name="">
+ <Properties>
+ <BasedOn type="object">$ID/NormalCharacterStyle</BasedOn>
+ </Properties>
+ </CharacterStyle>
+ </RootCharacterStyleGroup>
+ <RootParagraphStyleGroup Self="pandoc_paragraph_styles">
+ <ParagraphStyle Self="$ID/NormalParagraphStyle" Name="$ID/NormalParagraphStyle"
+ SpaceBefore="6" SpaceAfter="6"> <!-- paragraph spacing -->
+ <Properties>
+ <TabList type="list">
+ <ListItem type="record">
+ <Alignment type="enumeration">LeftAlign</Alignment>
+ <AlignmentCharacter type="string">.</AlignmentCharacter>
+ <Leader type="string"></Leader>
+ <Position type="unit">10</Position> <!-- first tab stop -->
+ </ListItem>
+ </TabList>
+ </Properties>
+ </ParagraphStyle>
+ <ParagraphStyle Self="ParagraphStyle/Paragraph" Name="Paragraph" LeftIndent="0">
+ <Properties>
+ <BasedOn type="object">$ID/NormalParagraphStyle</BasedOn>
+ </Properties>
+ </ParagraphStyle>
+ </RootParagraphStyleGroup>
+ <RootTableStyleGroup Self="pandoc_table_styles">
+ <TableStyle Self="TableStyle/Table" Name="Table" />
+ </RootTableStyleGroup>
+ <RootCellStyleGroup Self="pandoc_cell_styles">
+ <CellStyle Self="CellStyle/Cell" AppliedParagraphStyle="ParagraphStyle/$ID/[No paragraph style]" Name="Cell" />
+ </RootCellStyleGroup>
+ <RootObjectStyleGroup Self="pandoc_object_styles">
+ <ObjectStyle Self="ObjectStyle/myStyle" Name="myStyle">
+ <Properties>
+ <BasedOn type="string">$ID/None</BasedOn>
+ </Properties>
+ </ObjectStyle>
+ </RootObjectStyleGroup>
+ <Story Self="pandoc_story"
+ TrackChanges="false"
+ StoryTitle=""
+ AppliedTOCStyle="n"
+ AppliedNamedGrid="n" >
+ <StoryPreference OpticalMarginAlignment="true" OpticalMarginSize="12" />
+
+<!-- body needs to be non-indented, otherwise code blocks are indented too far -->
+<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Paragraph">
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <Rectangle Self="uec" StrokeWeight="0" ItemTransform="1 0 0 1 32 -32" AppliedObjectStyle="ObjectStyle/myStyle">
+ <Properties>
+ <PathGeometry>
+ <GeometryPathType PathOpen="false">
+ <PathPointArray>
+ <PathPointType Anchor="-32 -32" LeftDirection="-32 -32" RightDirection="-32 -32" />
+ <PathPointType Anchor="-32 32" LeftDirection="-32 32" RightDirection="-32 32" />
+ <PathPointType Anchor="32 32" LeftDirection="32 32" RightDirection="32 32" />
+ <PathPointType Anchor="32 -32" LeftDirection="32 -32" RightDirection="32 -32" />
+ </PathPointArray>
+ </GeometryPathType>
+ </PathGeometry>
+ </Properties>
+ <Image Self="ue6" ItemTransform="1 0 0 1 -32 -32">
+ <Properties>
+ <Profile type="string">
+ $ID/Embedded
+ </Profile>
+ <GraphicBounds Left="0" Top="0" Right="64" Bottom="64" />
+ </Properties>
+ <Link Self="ueb" LinkResourceURI="file:command/11498.png" />
+ </Image>
+ </Rectangle>
+ </CharacterStyleRange>
+</ParagraphStyleRange>
+
+ </Story>
+
+</Document>
+```
diff --git a/documents/markdown/pandoc-md/11511.md b/documents/markdown/pandoc-md/11511.md
new file mode 100644
index 0000000..4c4c9db
--- /dev/null
+++ b/documents/markdown/pandoc-md/11511.md
@@ -0,0 +1,6 @@
+```
+% pandoc -f html -t typst
+<p><a href="http://torch.utils.data" rel="noopener noreferrer nofollow" target="_blank">torch.utils.data</a>.Dataset</p>
+^D
+#link("http://torch.utils.data")[torch.utils.data]\.Dataset
+```
diff --git a/documents/markdown/pandoc-md/11534.md b/documents/markdown/pandoc-md/11534.md
new file mode 100644
index 0000000..4b1e4c8
--- /dev/null
+++ b/documents/markdown/pandoc-md/11534.md
@@ -0,0 +1,42 @@
+```
+% pandoc -f markdown+lists_without_preceding_blankline+alerts -t native
+:::: caution
+::: title
+Caution
+:::
+
+Foo bar, wuppie fluppie!
+::::
+^D
+[ Div
+ ( "" , [ "caution" ] , [] )
+ [ Div ( "" , [ "title" ] , [] ) [ Para [ Str "Caution" ] ]
+ , Para
+ [ Str "Foo"
+ , Space
+ , Str "bar,"
+ , Space
+ , Str "wuppie"
+ , Space
+ , Str "fluppie!"
+ ]
+ ]
+]
+```
+
+```
+% pandoc -f markdown+lists_without_preceding_blankline -t native
+hello
+- a
+- b
+c
+^D
+[ Para [ Str "hello" ]
+, BulletList
+ [ [ Plain [ Str "a" ] ]
+ , [ Plain [ Str "b" , SoftBreak , Str "c" ] ]
+ ]
+]
+
+```
+
diff --git a/documents/markdown/pandoc-md/11542.md b/documents/markdown/pandoc-md/11542.md
new file mode 100644
index 0000000..793f65e
--- /dev/null
+++ b/documents/markdown/pandoc-md/11542.md
@@ -0,0 +1,47 @@
+```
+% pandoc -f native -t markdown
+[ DefinitionList
+ [ ( [ Str "Input" ]
+ , [ [ CodeBlock ( "" , [] , [] ) "Term\n\n : Def" ] ]
+ )
+ ]
+]
+^D
+Input
+
+: Term
+
+ : Def
+```
+
+```
+% pandoc -f markdown -t native
+Input
+
+: Term
+
+ : Def
+^D
+[ DefinitionList
+ [ ( [ Str "Input" ]
+ , [ [ CodeBlock ( "" , [] , [] ) "Term\n\n : Def" ] ]
+ )
+ ]
+]
+```
+
+```
+% pandoc -f native -t markdown+four_space_rule
+[ DefinitionList
+ [ ( [ Str "Input" ]
+ , [ [ CodeBlock ( "" , [] , [] ) "Term\n\n : Def" ] ]
+ )
+ ]
+]
+^D
+Input
+
+: Term
+
+ : Def
+```
diff --git a/documents/markdown/pandoc-md/1166.md b/documents/markdown/pandoc-md/1166.md
new file mode 100644
index 0000000..b636825
--- /dev/null
+++ b/documents/markdown/pandoc-md/1166.md
@@ -0,0 +1,48 @@
+See #1166 and <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#simple-tables>.
+
+```
+% pandoc -f rst -t html5
+===== =====
+col 1 col 2
+===== =====
+1 Second column of row 1.
+2 Second column of row 2.
+ Second line of paragraph.
+3 - Second column of row 3.
+
+ - Second item in bullet
+ list (row 3, column 2).
+\ Row 4; column 1 will be empty.
+===== =====
+^D
+<table>
+<thead>
+<tr>
+<th>col 1</th>
+<th>col 2</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>1</td>
+<td>Second column of row 1.</td>
+</tr>
+<tr>
+<td>2</td>
+<td>Second column of row 2. Second line of paragraph.</td>
+</tr>
+<tr>
+<td>3</td>
+<td><ul>
+<li>Second column of row 3.</li>
+<li>Second item in bullet list (row 3, column 2).</li>
+</ul></td>
+</tr>
+<tr>
+<td></td>
+<td>Row 4; column 1 will be empty.</td>
+</tr>
+</tbody>
+</table>
+```
+
diff --git a/documents/markdown/pandoc-md/1279.md b/documents/markdown/pandoc-md/1279.md
new file mode 100644
index 0000000..522e399
--- /dev/null
+++ b/documents/markdown/pandoc-md/1279.md
@@ -0,0 +1,19 @@
+```
+% pandoc -s -t markdown
+---
+author: 'John Doe[^1]'
+date: 2014
+title: My Article
+---
+
+[^1]: Dept. of This and That
+^D
+---
+author: John Doe[^1]
+date: 2014
+title: My Article
+---
+
+[^1]: Dept. of This and That
+```
+
diff --git a/documents/markdown/pandoc-md/1390.md b/documents/markdown/pandoc-md/1390.md
new file mode 100644
index 0000000..4fea322
--- /dev/null
+++ b/documents/markdown/pandoc-md/1390.md
@@ -0,0 +1,26 @@
+```
+% pandoc -f latex -t native
+\newcommand\foo{+}
+Testing: $\mu\foo\eta$.
+^D
+[ Para
+ [ Str "Testing:"
+ , Space
+ , Math InlineMath "\\mu+\\eta"
+ , Str "."
+ ]
+]
+```
+
+<!-- It would be nice to handle this case, but I don't
+know how:
+
+```
+% pandoc -f latex -t native
+\newcommand{\vecx}{a + b}
+$\hat\vecx$
+^D
+[Para [Math InlineMath "\\hat{a+b}"]]
+```
+-->
+
diff --git a/documents/markdown/pandoc-md/1592.md b/documents/markdown/pandoc-md/1592.md
new file mode 100644
index 0000000..c3dc933
--- /dev/null
+++ b/documents/markdown/pandoc-md/1592.md
@@ -0,0 +1,98 @@
+```
+% pandoc -t native
+[hi]{.smallcaps}
+^D
+[ Para [ SmallCaps [ Str "hi" ] ] ]
+```
+
+```
+% pandoc -t native
+[hi]{style="font-variant: small-caps;"}
+^D
+[ Para [ SmallCaps [ Str "hi" ] ] ]
+```
+
+```
+% pandoc -t native
+<span class="smallcaps">hi</span>
+^D
+[ Para [ SmallCaps [ Str "hi" ] ] ]
+```
+
+```
+% pandoc -f html -t native
+<p><span class="smallcaps">hi</span></p>
+^D
+[ Para [ SmallCaps [ Str "hi" ] ] ]
+```
+
+```
+% pandoc -f html -t native
+<p><span style="font-variant:small-caps">hi</span></p>
+^D
+[ Para [ SmallCaps [ Str "hi" ] ] ]
+```
+
+```
+% pandoc -f native -t html
+[Para [SmallCaps [Str "hi"]]]
+^D
+<p><span class="smallcaps">hi</span></p>
+```
+
+```
+% pandoc -f native -t markdown
+[Para [SmallCaps [Str "hi"]]]
+^D
+[hi]{.smallcaps}
+```
+
+```
+% pandoc -f html -t native
+<bdo dir="ltr">foo</bdo>
+^D
+[ Plain
+ [ Span ( "" , [] , [ ( "dir" , "ltr" ) ] ) [ Str "foo" ] ]
+]
+```
+
+```
+% pandoc -f html -t native
+<bdo dir="rtl">foo<bdo dir="ltr">bar</bdo>baz</bdo>
+^D
+[ Plain
+ [ Span
+ ( "" , [] , [ ( "dir" , "rtl" ) ] )
+ [ Str "foo"
+ , Span ( "" , [] , [ ( "dir" , "ltr" ) ] ) [ Str "bar" ]
+ , Str "baz"
+ ]
+ ]
+]
+```
+
+```
+% pandoc -f html -t native
+<p><bdo dir="rtl">This text will go right
+to left.</bdo></p>
+^D
+[ Para
+ [ Span
+ ( "" , [] , [ ( "dir" , "rtl" ) ] )
+ [ Str "This"
+ , Space
+ , Str "text"
+ , Space
+ , Str "will"
+ , Space
+ , Str "go"
+ , Space
+ , Str "right"
+ , SoftBreak
+ , Str "to"
+ , Space
+ , Str "left."
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/1608.md b/documents/markdown/pandoc-md/1608.md
new file mode 100644
index 0000000..5c40d44
--- /dev/null
+++ b/documents/markdown/pandoc-md/1608.md
@@ -0,0 +1,205 @@
+```
+% pandoc -f latex -t native
+\newtheorem{theorem}{Theorem}
+\newtheorem{corollary}[theorem]{Corollary}
+\newtheorem{lemma}[theorem]{Lemma}
+\theoremstyle{definition}
+\newtheorem{definition}[theorem]{Definition}
+\theoremstyle{remark}
+\newtheorem{remark}{Remark}
+
+\begin{definition}[right-angled triangles] \label{def:tri}
+A \emph{right-angled triangle} is a triangle whose sides of length~\(a\), \(b\) and~\(c\), in some permutation of order, satisfies \(a^2+b^2=c^2\).
+\end{definition}
+
+\begin{lemma}
+The triangle with sides of length~\(3\), \(4\) and~\(5\) is right-angled.
+\end{lemma}
+
+\begin{proof}
+This lemma follows from \cref{def:tri} since \(3^2+4^2=9+16=25=5^2\).
+\end{proof}
+
+\begin{theorem}[Pythagorean triplets] \label{thm:py}
+Triangles with sides of length \(a=p^2-q^2\), \(b=2pq\) and \(c=p^2+q^2\) are right-angled triangles.
+\end{theorem}
+
+\begin{remark}
+These are all pretty interesting facts.
+\end{remark}
+^D
+[ Div
+ ( "def:tri" , [ "definition" ] , [] )
+ [ Para
+ [ Strong [ Str "Definition" , Space , Str "1" ]
+ , Space
+ , Str "(right-angled"
+ , Space
+ , Str "triangles)."
+ , Space
+ , Space
+ , Str "A"
+ , Space
+ , Emph [ Str "right-angled" , Space , Str "triangle" ]
+ , Space
+ , Str "is"
+ , Space
+ , Str "a"
+ , Space
+ , Str "triangle"
+ , Space
+ , Str "whose"
+ , Space
+ , Str "sides"
+ , Space
+ , Str "of"
+ , Space
+ , Str "length\160"
+ , Math InlineMath "a"
+ , Str ","
+ , Space
+ , Math InlineMath "b"
+ , Space
+ , Str "and\160"
+ , Math InlineMath "c"
+ , Str ","
+ , Space
+ , Str "in"
+ , Space
+ , Str "some"
+ , Space
+ , Str "permutation"
+ , Space
+ , Str "of"
+ , Space
+ , Str "order,"
+ , Space
+ , Str "satisfies"
+ , Space
+ , Math InlineMath "a^2+b^2=c^2"
+ , Str "."
+ ]
+ ]
+, Div
+ ( "" , [ "lemma" ] , [] )
+ [ Para
+ [ Strong [ Str "Lemma" , Space , Str "2" ]
+ , Str "."
+ , Space
+ , Space
+ , Emph
+ [ Str "The"
+ , Space
+ , Str "triangle"
+ , Space
+ , Str "with"
+ , Space
+ , Str "sides"
+ , Space
+ , Str "of"
+ , Space
+ , Str "length\160"
+ , Math InlineMath "3"
+ , Str ","
+ , Space
+ , Math InlineMath "4"
+ , Space
+ , Str "and\160"
+ , Math InlineMath "5"
+ , Space
+ , Str "is"
+ , Space
+ , Str "right-angled."
+ ]
+ ]
+ ]
+, Div
+ ( "" , [ "proof" ] , [] )
+ [ Para
+ [ Emph [ Str "Proof." ]
+ , Space
+ , Str "This"
+ , Space
+ , Str "lemma"
+ , Space
+ , Str "follows"
+ , Space
+ , Str "from"
+ , Space
+ , Link
+ ( ""
+ , []
+ , [ ( "reference-type" , "ref+label" )
+ , ( "reference" , "def:tri" )
+ ]
+ )
+ [ Str "1" ]
+ ( "#def:tri" , "" )
+ , Space
+ , Str "since"
+ , Space
+ , Math InlineMath "3^2+4^2=9+16=25=5^2"
+ , Str "."
+ , Str "\160\9723"
+ ]
+ ]
+, Div
+ ( "thm:py" , [ "theorem" ] , [] )
+ [ Para
+ [ Strong [ Str "Theorem" , Space , Str "3" ]
+ , Space
+ , Str "(Pythagorean"
+ , Space
+ , Str "triplets)."
+ , Space
+ , Space
+ , Emph
+ [ Str "Triangles"
+ , Space
+ , Str "with"
+ , Space
+ , Str "sides"
+ , Space
+ , Str "of"
+ , Space
+ , Str "length"
+ , Space
+ , Math InlineMath "a=p^2-q^2"
+ , Str ","
+ , Space
+ , Math InlineMath "b=2pq"
+ , Space
+ , Str "and"
+ , Space
+ , Math InlineMath "c=p^2+q^2"
+ , Space
+ , Str "are"
+ , Space
+ , Str "right-angled"
+ , Space
+ , Str "triangles."
+ ]
+ ]
+ ]
+, Div
+ ( "" , [ "remark" ] , [] )
+ [ Para
+ [ Emph [ Str "Remark" , Space , Str "1" ]
+ , Str "."
+ , Space
+ , Space
+ , Str "These"
+ , Space
+ , Str "are"
+ , Space
+ , Str "all"
+ , Space
+ , Str "pretty"
+ , Space
+ , Str "interesting"
+ , Space
+ , Str "facts."
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/1629.md b/documents/markdown/pandoc-md/1629.md
new file mode 100644
index 0000000..43b9b82
--- /dev/null
+++ b/documents/markdown/pandoc-md/1629.md
@@ -0,0 +1,10 @@
+```
+% pandoc -t latex --syntax-highlighting=idiomatic
+bla bla `a % b`
+
+*bla bla `a % b`*
+^D
+bla bla \passthrough{\lstinline!a \% b!}
+
+\emph{bla bla \passthrough{\lstinline!a \% b!}}
+```
diff --git a/documents/markdown/pandoc-md/168.md b/documents/markdown/pandoc-md/168.md
new file mode 100644
index 0000000..acd42b9
--- /dev/null
+++ b/documents/markdown/pandoc-md/168.md
@@ -0,0 +1,73 @@
+```
+% pandoc -t native
+:::::::::: warning ::::::::::::
+This is the warning!
+
+1. list
+2. another
+
+::: {#myid .class key=val}
+nested div
+:::
+:::::::::::::::::::::::::::::::
+^D
+[ Div
+ ( "" , [ "warning" ] , [] )
+ [ Para
+ [ Str "This"
+ , Space
+ , Str "is"
+ , Space
+ , Str "the"
+ , Space
+ , Str "warning!"
+ ]
+ , OrderedList
+ ( 1 , Decimal , Period )
+ [ [ Plain [ Str "list" ] ] , [ Plain [ Str "another" ] ] ]
+ , Div
+ ( "myid" , [ "class" ] , [ ( "key" , "val" ) ] )
+ [ Para [ Str "nested" , Space , Str "div" ] ]
+ ]
+]
+```
+
+```
+% pandoc -t native
+foo
+:::
+bar
+^D
+[ Para
+ [ Str "foo"
+ , SoftBreak
+ , Str ":::"
+ , SoftBreak
+ , Str "bar"
+ ]
+]
+```
+
+```
+% pandoc -t native
+::::: Warning
+Here is a paragraph.
+
+And another.
+:::::
+^D
+[ Div
+ ( "" , [ "Warning" ] , [] )
+ [ Para
+ [ Str "Here"
+ , Space
+ , Str "is"
+ , Space
+ , Str "a"
+ , Space
+ , Str "paragraph."
+ ]
+ , Para [ Str "And" , Space , Str "another." ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/1710.md b/documents/markdown/pandoc-md/1710.md
new file mode 100644
index 0000000..4b8cad7
--- /dev/null
+++ b/documents/markdown/pandoc-md/1710.md
@@ -0,0 +1,85 @@
+```
+% pandoc -t revealjs
+# Slide one
+
+<div class="columns">
+<div class="column" width="40%">
+- a
+- b
+</div>
+<div class="column" width="40%">
+- c
+- d
+</div>
+<div class="column" width="10%">
+ok
+</div>
+</div>
+^D
+<section id="slide-one" class="slide level1">
+<h1>Slide one</h1>
+<div class="columns">
+<div class="column" style="width:40%;">
+<ul>
+<li>a</li>
+<li>b</li>
+</ul>
+</div><div class="column" style="width:40%;">
+<ul>
+<li>c</li>
+<li>d</li>
+</ul>
+</div><div class="column" style="width:10%;">
+<p>ok</p>
+</div>
+</div>
+</section>
+```
+
+```
+% pandoc -t beamer
+# Slide one
+
+<div class="columns">
+<div class="column" width="40%">
+- a
+- b
+</div>
+<div class="column" width="40%">
+- c
+- d
+</div>
+<div class="column" width="10%">
+ok
+</div>
+</div>
+^D
+\begin{frame}{Slide one}
+\protect\phantomsection\label{slide-one}
+\begin{columns}[T]
+\begin{column}{0.4\linewidth}
+\begin{itemize}
+\tightlist
+\item
+ a
+\item
+ b
+\end{itemize}
+\end{column}
+
+\begin{column}{0.4\linewidth}
+\begin{itemize}
+\tightlist
+\item
+ c
+\item
+ d
+\end{itemize}
+\end{column}
+
+\begin{column}{0.1\linewidth}
+ok
+\end{column}
+\end{columns}
+\end{frame}
+```
diff --git a/documents/markdown/pandoc-md/1718.md b/documents/markdown/pandoc-md/1718.md
new file mode 100644
index 0000000..a6722b1
--- /dev/null
+++ b/documents/markdown/pandoc-md/1718.md
@@ -0,0 +1,19 @@
+```
+% pandoc -t native
+Note[^1].
+
+[^1]: the first note.
+
+[^2]: the second, unused, note.
+^D
+2> [WARNING] Note with key '2' defined at line 5 column 1 but not used.
+[ Para
+ [ Str "Note"
+ , Note
+ [ Para
+ [ Str "the" , Space , Str "first" , Space , Str "note." ]
+ ]
+ , Str "."
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/1745.md b/documents/markdown/pandoc-md/1745.md
new file mode 100644
index 0000000..cf987c2
--- /dev/null
+++ b/documents/markdown/pandoc-md/1745.md
@@ -0,0 +1,13 @@
+```
+% pandoc -f latex+auto_identifiers -t html
+\section{Six favourite beers}
+\subsection{Jovaru Alus}\label{jovaru-alus}
+\section{Farmhouse brewers}
+\subsection{Jovaru Alus}
+^D
+<h1 id="six-favourite-beers">Six favourite beers</h1>
+<h2 id="jovaru-alus">Jovaru Alus</h2>
+<h1 id="farmhouse-brewers">Farmhouse brewers</h1>
+<h2 id="jovaru-alus-1">Jovaru Alus</h2>
+```
+
diff --git a/documents/markdown/pandoc-md/1762.md b/documents/markdown/pandoc-md/1762.md
new file mode 100644
index 0000000..b35b209
--- /dev/null
+++ b/documents/markdown/pandoc-md/1762.md
@@ -0,0 +1,15 @@
+```
+% pandoc -t latex
+# One {.unlisted}
+
+# Two {.unnumbered}
+
+# Three {.unlisted .unnumbered}
+^D
+\section{One}\label{one}
+
+\section*{Two}\label{two}
+\addcontentsline{toc}{section}{Two}
+
+\section*{Three}\label{three}
+```
diff --git a/documents/markdown/pandoc-md/1773.md b/documents/markdown/pandoc-md/1773.md
new file mode 100644
index 0000000..c529ec9
--- /dev/null
+++ b/documents/markdown/pandoc-md/1773.md
@@ -0,0 +1,8 @@
+```
+% pandoc -f latex+raw_tex -t native
+\noindent hi
+^D
+[ Para
+ [ RawInline (Format "latex") "\\noindent " , Str "hi" ]
+]
+```
diff --git a/documents/markdown/pandoc-md/1841.md b/documents/markdown/pandoc-md/1841.md
new file mode 100644
index 0000000..408f224
--- /dev/null
+++ b/documents/markdown/pandoc-md/1841.md
@@ -0,0 +1,42 @@
+```
+% pandoc
+<table>
+<tr>
+<td> *one*</td>
+<td> [a link](http://google.com)</td>
+</tr>
+</table>
+^D
+<table>
+<tr>
+<td>
+<em>one</em>
+</td>
+<td>
+<a href="http://google.com">a link</a>
+</td>
+</tr>
+</table>
+```
+
+```
+% pandoc
+<table>
+ <tr>
+ <td>*one*</td>
+ <td>[a link](http://google.com)</td>
+ </tr>
+</table>
+^D
+<table>
+<tr>
+<td>
+<em>one</em>
+</td>
+<td>
+<a href="http://google.com">a link</a>
+</td>
+</tr>
+</table>
+```
+
diff --git a/documents/markdown/pandoc-md/1881.md b/documents/markdown/pandoc-md/1881.md
new file mode 100644
index 0000000..815f8cc
--- /dev/null
+++ b/documents/markdown/pandoc-md/1881.md
@@ -0,0 +1,167 @@
+```
+% pandoc -f html -t native
+<table>
+<caption>Demonstration of simple table syntax.</caption>
+<thead>
+<tr>
+<th align="right">Right</th>
+<th align="left">Left</th>
+<th align="center">Center</th>
+<th>Default</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td align="right">12</td>
+<td align="left">12</td>
+<td align="center">12</td>
+<td>12</td>
+</tr>
+</tbody>
+</table>
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption
+ Nothing
+ [ Plain
+ [ Str "Demonstration"
+ , Space
+ , Str "of"
+ , Space
+ , Str "simple"
+ , Space
+ , Str "table"
+ , Space
+ , Str "syntax."
+ ]
+ ])
+ [ ( AlignRight , ColWidthDefault )
+ , ( AlignLeft , ColWidthDefault )
+ , ( AlignCenter , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignRight
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Right" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignLeft
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Left" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Center" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Default" ] ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignRight
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "12" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignLeft
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "12" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "12" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "12" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
+
+```
+% pandoc -f html -t native
+<table>
+<tr>
+<td style="text-align: right;">12</td>
+<td style="text-align:left;">12</td>
+<td style="text-align: center">12</td>
+<td style="text-align: right;">12</td>
+</tr>
+</table>
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignRight , ColWidthDefault )
+ , ( AlignLeft , ColWidthDefault )
+ , ( AlignCenter , ColWidthDefault )
+ , ( AlignRight , ColWidthDefault )
+ ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignRight
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "12" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignLeft
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "12" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "12" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignRight
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "12" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
+
diff --git a/documents/markdown/pandoc-md/1905.md b/documents/markdown/pandoc-md/1905.md
new file mode 100644
index 0000000..744d1c4
--- /dev/null
+++ b/documents/markdown/pandoc-md/1905.md
@@ -0,0 +1,30 @@
+```
+% pandoc -f latex-auto_identifiers -t html
+\chapter{chapone}
+\part{partone}
+\chapter{chaptwo}
+\section{secone}
+^D
+<h2>chapone</h2>
+<h1>partone</h1>
+<h2>chaptwo</h2>
+<h3>secone</h3>
+```
+
+```
+% pandoc -f latex-auto_identifiers -t html
+\chapter{chapone}
+\chapter{chaptwo}
+\section{secone}
+^D
+<h1>chapone</h1>
+<h1>chaptwo</h1>
+<h2>secone</h2>
+```
+
+```
+% pandoc -f latex-auto_identifiers -t html
+\section{secone}
+^D
+<h1>secone</h1>
+```
diff --git a/documents/markdown/pandoc-md/2103.md b/documents/markdown/pandoc-md/2103.md
new file mode 100644
index 0000000..e5220de
--- /dev/null
+++ b/documents/markdown/pandoc-md/2103.md
@@ -0,0 +1,8 @@
+```
+% pandoc -t latex
+| A happy pandoc user said "fix this bug please
+| or I'll go crazy!"
+^D
+A happy pandoc user said ``fix this bug please\\
+or I'll go crazy!''
+```
diff --git a/documents/markdown/pandoc-md/2118.md b/documents/markdown/pandoc-md/2118.md
new file mode 100644
index 0000000..cc1c930
--- /dev/null
+++ b/documents/markdown/pandoc-md/2118.md
@@ -0,0 +1,22 @@
+```
+% pandoc -f latex -t native
+\newcommand{\inclgraph}{\includegraphics[width=0.8\textwidth]}
+\begin{figure}[ht]
+ \inclgraph{setminus.png}
+ \caption{Set subtraction}
+ \label{fig:setminus}
+\end{figure}
+^D
+[ Figure
+ ( "fig:setminus" , [] , [ ( "latex-placement" , "ht" ) ] )
+ (Caption
+ Nothing [ Plain [ Str "Set" , Space , Str "subtraction" ] ])
+ [ Plain
+ [ Image
+ ( "" , [] , [ ( "width" , "80%" ) ] )
+ []
+ ( "setminus.png" , "" )
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/2337.md b/documents/markdown/pandoc-md/2337.md
new file mode 100644
index 0000000..bcf0010
--- /dev/null
+++ b/documents/markdown/pandoc-md/2337.md
@@ -0,0 +1,6 @@
+```
+% pandoc -t asciidoc -f html
+<a href="http://example.com">][</a>
+^D
+http://example.com[++][++]
+```
diff --git a/documents/markdown/pandoc-md/2378.md b/documents/markdown/pandoc-md/2378.md
new file mode 100644
index 0000000..2944df0
--- /dev/null
+++ b/documents/markdown/pandoc-md/2378.md
@@ -0,0 +1,28 @@
+Ensure that we don't get duplicated footnotes when
+a note occurs in a header cell and `\endfirsthead`
+is used.
+
+```
+% pandoc -t latex
+| x | y[^fn] |
+|-|-|
+|1|2|
+: a table
+
+[^fn]: a footnote
+^D
+\begin{longtable}[]{@{}ll@{}}
+\caption{a table}\tabularnewline
+\toprule\noalign{}
+x & y\footnote{a footnote} \\
+\midrule\noalign{}
+\endfirsthead
+\toprule\noalign{}
+x & y{} \\
+\midrule\noalign{}
+\endhead
+\bottomrule\noalign{}
+\endlastfoot
+1 & 2 \\
+\end{longtable}
+```
diff --git a/documents/markdown/pandoc-md/2397.md b/documents/markdown/pandoc-md/2397.md
new file mode 100644
index 0000000..34d2013
--- /dev/null
+++ b/documents/markdown/pandoc-md/2397.md
@@ -0,0 +1,9 @@
+```
+% pandoc -f markdown_mmd
+# Chapter 1: A long name of chapter [Chapter 1]
+
+See [Chapter 1].
+^D
+<h1 id="chapter1">Chapter 1: A long name of chapter</h1>
+<p>See <a href="#chapter1">Chapter 1</a>.</p>
+```
diff --git a/documents/markdown/pandoc-md/2434.md b/documents/markdown/pandoc-md/2434.md
new file mode 100644
index 0000000..4f12b6f
--- /dev/null
+++ b/documents/markdown/pandoc-md/2434.md
@@ -0,0 +1,59 @@
+```
+% pandoc -t opendocument
+1. a
+2. b
+ 1. alpha
+ 2. beta
+ * gamma
+^D
+<text:list text:style-name="L1">
+ <text:list-item>
+ <text:p text:style-name="P1">a</text:p>
+ </text:list-item>
+ <text:list-item>
+ <text:p text:style-name="P1">b</text:p>
+ <text:list>
+ <text:list-item>
+ <text:p text:style-name="P1">alpha</text:p>
+ </text:list-item>
+ <text:list-item>
+ <text:p text:style-name="P1">beta</text:p>
+ </text:list-item>
+ </text:list>
+ <text:list text:style-name="L2">
+ <text:list-item>
+ <text:p text:style-name="P2">gamma</text:p>
+ </text:list-item>
+ </text:list>
+ </text:list-item>
+</text:list>
+```
+
+```
+% pandoc -t opendocument
+(@) text
+
+ some text
+
+ a) sub item 1
+ b) sub item 2
+
+ more text -- this line is missing in the odt output
+^D
+<text:list text:style-name="L1">
+ <text:list-item>
+ <text:p text:style-name="P1">text</text:p>
+ <text:p text:style-name="P1">some text</text:p>
+ <text:list>
+ <text:list-item>
+ <text:p text:style-name="P1">sub item 1</text:p>
+ </text:list-item>
+ <text:list-item>
+ <text:p text:style-name="P1">sub item 2</text:p>
+ </text:list-item>
+ </text:list>
+ <text:p text:style-name="P1">more text – this line is missing in the
+ odt output</text:p>
+ </text:list-item>
+</text:list>
+```
diff --git a/documents/markdown/pandoc-md/2465.md b/documents/markdown/pandoc-md/2465.md
new file mode 100644
index 0000000..610e351
--- /dev/null
+++ b/documents/markdown/pandoc-md/2465.md
@@ -0,0 +1,59 @@
+```
+% pandoc -f textile -t native
+This list starts:
+
+# one
+# two
+
+This list should continue at 3:
+
+#3 three
+# four
+
+This list should restart at 1:
+
+# one again
+# two again
+^D
+[ Para
+ [ Str "This" , Space , Str "list" , Space , Str "starts:" ]
+, OrderedList
+ ( 1 , DefaultStyle , DefaultDelim )
+ [ [ Plain [ Str "one" ] ] , [ Plain [ Str "two" ] ] ]
+, Para
+ [ Str "This"
+ , Space
+ , Str "list"
+ , Space
+ , Str "should"
+ , Space
+ , Str "continue"
+ , Space
+ , Str "at"
+ , Space
+ , Str "3:"
+ ]
+, OrderedList
+ ( 3 , DefaultStyle , DefaultDelim )
+ [ [ Plain [ Str "three" ] ] , [ Plain [ Str "four" ] ] ]
+, Para
+ [ Str "This"
+ , Space
+ , Str "list"
+ , Space
+ , Str "should"
+ , Space
+ , Str "restart"
+ , Space
+ , Str "at"
+ , Space
+ , Str "1:"
+ ]
+, OrderedList
+ ( 1 , DefaultStyle , DefaultDelim )
+ [ [ Plain [ Str "one" , Space , Str "again" ] ]
+ , [ Plain [ Str "two" , Space , Str "again" ] ]
+ ]
+]
+```
+
diff --git a/documents/markdown/pandoc-md/2549.md b/documents/markdown/pandoc-md/2549.md
new file mode 100644
index 0000000..12b21d0
--- /dev/null
+++ b/documents/markdown/pandoc-md/2549.md
@@ -0,0 +1,50 @@
+```
+% pandoc -f latex -t native
+\hypertarget{foo}{%
+\section{A section}\label{foo}
+}
+^D
+[ Header
+ 1 ( "foo" , [] , [] ) [ Str "A" , Space , Str "section" ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\hypertarget{bar}{%
+\section{A section}\label{foo}
+}
+^D
+[ Div
+ ( "bar" , [] , [] )
+ [ Header
+ 1 ( "foo" , [] , [] ) [ Str "A" , Space , Str "section" ]
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+Bar \hypertarget{foo}{Foo}
+^D
+[ Para
+ [ Str "Bar"
+ , Space
+ , Span ( "foo" , [] , [] ) [ Str "Foo" ]
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\hypertarget{foo}{%
+\begin{verbatim}
+bar
+\end{verbatim}
+}
+^D
+[ Div
+ ( "foo" , [] , [] ) [ CodeBlock ( "" , [] , [] ) "bar" ]
+]
+```
+
diff --git a/documents/markdown/pandoc-md/2552.md b/documents/markdown/pandoc-md/2552.md
new file mode 100644
index 0000000..90a3a38
--- /dev/null
+++ b/documents/markdown/pandoc-md/2552.md
@@ -0,0 +1,14 @@
+```
+% pandoc --strip-comments
+Foo
+
+bar
+
+<!-- comment -->
+
+baz<!-- bim -->boop
+^D
+<p>Foo</p>
+<p>bar</p>
+<p>bazboop</p>
+```
diff --git a/documents/markdown/pandoc-md/256.md b/documents/markdown/pandoc-md/256.md
new file mode 100644
index 0000000..7e3f34d
--- /dev/null
+++ b/documents/markdown/pandoc-md/256.md
@@ -0,0 +1,42 @@
+```
+% pandoc --abbreviations=command/abbrevs -t native
+Foo. bar baz h.k. and e.g. and Mr. Brown.
+^D
+[ Para
+ [ Str "Foo.\160bar"
+ , Space
+ , Str "baz"
+ , Space
+ , Str "h.k.\160and"
+ , Space
+ , Str "e.g."
+ , Space
+ , Str "and"
+ , Space
+ , Str "Mr."
+ , Space
+ , Str "Brown."
+ ]
+]
+```
+```
+% pandoc -t native
+Foo. bar baz h.k. and e.g. and Mr. Brown.
+^D
+[ Para
+ [ Str "Foo."
+ , Space
+ , Str "bar"
+ , Space
+ , Str "baz"
+ , Space
+ , Str "h.k."
+ , Space
+ , Str "and"
+ , Space
+ , Str "e.g.\160and"
+ , Space
+ , Str "Mr.\160Brown."
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/2602.md b/documents/markdown/pandoc-md/2602.md
new file mode 100644
index 0000000..5ed4b58
--- /dev/null
+++ b/documents/markdown/pandoc-md/2602.md
@@ -0,0 +1,18 @@
+```
+% pandoc
+[a] [b]
+
+[b]: url
+^D
+<p>[a] <a href="url">b</a></p>
+```
+
+```
+% pandoc -f markdown+spaced_reference_links
+[a] [b]
+
+[b]: url
+^D
+<p><a href="url">a</a></p>
+```
+
diff --git a/documents/markdown/pandoc-md/2606.md b/documents/markdown/pandoc-md/2606.md
new file mode 100644
index 0000000..cf91321
--- /dev/null
+++ b/documents/markdown/pandoc-md/2606.md
@@ -0,0 +1,58 @@
+```
+% pandoc -f mediawiki -t html5
+{|
+| * hello
+|}
+^D
+<table>
+<tbody>
+<tr>
+<td><p>* hello</p></td>
+</tr>
+</tbody>
+</table>
+```
+
+```
+% pandoc -f mediawiki -t html5
+{|
+|
+* hello
+|}
+^D
+<table>
+<tbody>
+<tr>
+<td><ul>
+<li>hello</li>
+</ul></td>
+</tr>
+</tbody>
+</table>
+```
+
+```
+% pandoc -f mediawiki -t html5
+{|
+|
+ * hello
+|}
+^D
+<table>
+<tbody>
+<tr>
+<td><p><code>* hello</code></p></td>
+</tr>
+</tbody>
+</table>
+```
+
+```
+% pandoc -f mediawiki -t html5
+* * hi
+^D
+<ul>
+<li>* hi</li>
+</ul>
+```
+
diff --git a/documents/markdown/pandoc-md/262.md b/documents/markdown/pandoc-md/262.md
new file mode 100644
index 0000000..61af20e
--- /dev/null
+++ b/documents/markdown/pandoc-md/262.md
@@ -0,0 +1,27 @@
+```
+% pandoc -f rst
+`hello`_ and `goodbye`_
+
+.. _hello:
+.. _goodbye: example.com
+^D
+<p><a href="example.com">hello</a> and <a
+href="example.com">goodbye</a></p>
+```
+
+```
+% pandoc -f rst
+`hello`_ `goodbye`_
+
+.. _hello:
+.. _goodbye:
+
+paragraph
+^D
+<p><a href="#hello">hello</a> <a href="#goodbye">goodbye</a></p>
+<div id="hello">
+<div id="goodbye">
+<p>paragraph</p>
+</div>
+</div>
+```
diff --git a/documents/markdown/pandoc-md/2649.md b/documents/markdown/pandoc-md/2649.md
new file mode 100644
index 0000000..ae825d0
--- /dev/null
+++ b/documents/markdown/pandoc-md/2649.md
@@ -0,0 +1,111 @@
+```
+% pandoc -f mediawiki -t html5
+{| class="wikitable" style="line-height: 1.0"
+
+|- bgcolor="#efefef"
+|}
+^D
+<table>
+<tbody>
+<tr>
+</tr>
+</tbody>
+</table>
+```
+
+```
+% pandoc -f mediawiki -t html5
+{| border="4" cellspacing="2" cellpadding="0" WIDTH="100%"
+|-----
+| peildatum Simbase || november 2005 || colspan=2 | '''uitslagen Flohrgambiet'''
+|-----
+| totaal aantal partijen Simbase || 7.316.773
+| wit wint || 53%
+|-----
+| percentage (en partijen) Flohrgambiet
+| 0.023 % (1.699) || zwart wint || 27%
+|-----
+| percentage Flohrgambiet in aug 2003
+| 0.035 % || remise || 20%
+|}
+^D
+<table>
+<tbody>
+<tr>
+<td><p>peildatum Simbase</p></td>
+<td><p>november 2005</p></td>
+<td colspan="2"><p><strong>uitslagen Flohrgambiet</strong></p></td>
+</tr>
+<tr>
+<td><p>totaal aantal partijen Simbase</p></td>
+<td><p>7.316.773</p></td>
+<td><p>wit wint</p></td>
+<td><p>53%</p></td>
+</tr>
+<tr>
+<td><p>percentage (en partijen) Flohrgambiet</p></td>
+<td><p>0.023 % (1.699)</p></td>
+<td><p>zwart wint</p></td>
+<td><p>27%</p></td>
+</tr>
+<tr>
+<td><p>percentage Flohrgambiet in aug 2003</p></td>
+<td><p>0.035 %</p></td>
+<td><p>remise</p></td>
+<td><p>20%</p></td>
+</tr>
+</tbody>
+</table>
+```
+
+```
+% pandoc -f mediawiki -t html5
+{| class="wikitable" style="text-align:center; font-size:95%" valign="top" |
+! Plaats
+! Rijder
+! Aantal
+|-
+| 1
+|align=left| {{FR-VLAG}} [[Sébastien Loeb]]
+| 78
+|-
+| 2
+|align=left| {{FR-VLAG}} '''[[Sébastien Ogier]]'''
+| 38
+|-
+| 10
+|align=left| {{FI-VLAG}} [[Hannu Mikkola]]
+| 18
+|}
+^D
+<table>
+<thead>
+<tr>
+<th><p>Plaats</p></th>
+<th><p>Rijder</p></th>
+<th><p>Aantal</p></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><p>1</p></td>
+<td style="text-align: left;"><p><a href="Sébastien_Loeb"
+class="wikilink" title="Sébastien Loeb">Sébastien Loeb</a></p></td>
+<td><p>78</p></td>
+</tr>
+<tr>
+<td><p>2</p></td>
+<td style="text-align: left;"><p><strong><a href="Sébastien_Ogier"
+class="wikilink" title="Sébastien Ogier">Sébastien
+Ogier</a></strong></p></td>
+<td><p>38</p></td>
+</tr>
+<tr>
+<td><p>10</p></td>
+<td style="text-align: left;"><p><a href="Hannu_Mikkola"
+class="wikilink" title="Hannu Mikkola">Hannu Mikkola</a></p></td>
+<td><p>18</p></td>
+</tr>
+</tbody>
+</table>
+```
diff --git a/documents/markdown/pandoc-md/2662.md b/documents/markdown/pandoc-md/2662.md
new file mode 100644
index 0000000..74e075c
--- /dev/null
+++ b/documents/markdown/pandoc-md/2662.md
@@ -0,0 +1,11 @@
+```
+% pandoc -t html -f rst --wrap=none
+.. image:: http://url.to.image/foo.png
+ :align: left
+ :height: 100px
+ :width: 200 px
+ :scale: 300 %
+ :alt: alternate text
+^D
+<p><img src="http://url.to.image/foo.png" class="align-left" width="600" height="300" alt="alternate text" /></p>
+```
diff --git a/documents/markdown/pandoc-md/2834.md b/documents/markdown/pandoc-md/2834.md
new file mode 100644
index 0000000..32c6d35
--- /dev/null
+++ b/documents/markdown/pandoc-md/2834.md
@@ -0,0 +1,29 @@
+Nested grid tables.
+```
+% pandoc -f html -t markdown --columns=72
+<table>
+ <tr>
+ <td>
+ <table>
+ <tr>
+ <td>
+ <table>
+ <tr>
+ <td>some text</td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+</table>
+^D
++---------------------------------------------------------------------------+
+| +-----------------------------------------------------------------------+ |
+| | ----------- | |
+| | some text | |
+| | ----------- | |
+| +-----------------------------------------------------------------------+ |
++---------------------------------------------------------------------------+
+```
diff --git a/documents/markdown/pandoc-md/2874.md b/documents/markdown/pandoc-md/2874.md
new file mode 100644
index 0000000..a82ae38
--- /dev/null
+++ b/documents/markdown/pandoc-md/2874.md
@@ -0,0 +1,14 @@
+```
+% pandoc -f html -t latex
+<a></a>
+<br/>
+^D
+{}\strut \\
+```
+
+```
+% pandoc -f html -t latex
+<a name="foo"></a><br/>
+^D
+\protect\phantomsection\label{foo}{}\strut \\
+```
diff --git a/documents/markdown/pandoc-md/2994.md b/documents/markdown/pandoc-md/2994.md
new file mode 100644
index 0000000..b6b2d1e
--- /dev/null
+++ b/documents/markdown/pandoc-md/2994.md
@@ -0,0 +1,10 @@
+```
+% pandoc -f markdown -t docx -o - | pandoc -f docx -t markdown --track-changes=all
+I want [I left a comment.]{.comment-start id="0"
+author="Jesse Rosenthal" date="2016-05-09T16:13:00Z"}some text to have a
+comment []{.comment-end id="0"}on it.
+^D
+I want [I left a comment.]{.comment-start id="0"
+author="Jesse Rosenthal" date="2016-05-09T16:13:00Z"}some text to have a
+comment []{.comment-end id="0"}on it.
+```
diff --git a/documents/markdown/pandoc-md/3113.md b/documents/markdown/pandoc-md/3113.md
new file mode 100644
index 0000000..9640390
--- /dev/null
+++ b/documents/markdown/pandoc-md/3113.md
@@ -0,0 +1,18 @@
+```
+% pandoc -f latex -t native
+\begin{eqnarray}
+A&=&B,\\
+C&=&D,\\
+%\end{eqnarray}
+%\begin{eqnarray}
+E&=&F
+\end{eqnarray}
+^D
+[ Para
+ [ Math
+ DisplayMath
+ "\\begin{eqnarray}\nA&=&B,\\\\\nC&=&D,\\\\\n%\\end{eqnarray}\n%\\begin{eqnarray}\nE&=&F\n\\end{eqnarray}"
+ ]
+]
+```
+
diff --git a/documents/markdown/pandoc-md/3123.md b/documents/markdown/pandoc-md/3123.md
new file mode 100644
index 0000000..a97165b
--- /dev/null
+++ b/documents/markdown/pandoc-md/3123.md
@@ -0,0 +1,17 @@
+```
+% pandoc -f markdown -t native
+<?php echo "1" ; ?>
+^D
+[ RawBlock (Format "html") "<?php echo \"1\" ; ?>" ]
+```
+
+```
+% pandoc -f markdown -t native
+a<?php echo "1" ; ?>
+^D
+[ Para
+ [ Str "a"
+ , RawInline (Format "html") "<?php echo \"1\" ; ?>"
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/3236.md b/documents/markdown/pandoc-md/3236.md
new file mode 100644
index 0000000..b9a98f1
--- /dev/null
+++ b/documents/markdown/pandoc-md/3236.md
@@ -0,0 +1,21 @@
+```
+% pandoc -f latex -t native
+\newcommand{\mycolor}{red}
+
+\includegraphics[width=17cm]{\mycolor /header}
+Magnificent \mycolor{} header.
+^D
+[ Para
+ [ Image
+ ( "" , [] , [ ( "width" , "17cm" ) ] )
+ [ Str "image" ]
+ ( "red/header" , "" )
+ , SoftBreak
+ , Str "Magnificent"
+ , Space
+ , Str "red"
+ , Space
+ , Str "header."
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/3257.md b/documents/markdown/pandoc-md/3257.md
new file mode 100644
index 0000000..ef24194
--- /dev/null
+++ b/documents/markdown/pandoc-md/3257.md
@@ -0,0 +1,13 @@
+```
+% pandoc -t native
+(i<j)
+^D
+[ Para [ Str "(i<j)" ] ]
+```
+
+```
+% pandoc -t native
+i<j-1, j>k
+^D
+[ Para [ Str "i<j-1," , Space , Str "j>k" ] ]
+```
diff --git a/documents/markdown/pandoc-md/3309.md b/documents/markdown/pandoc-md/3309.md
new file mode 100644
index 0000000..083ac53
--- /dev/null
+++ b/documents/markdown/pandoc-md/3309.md
@@ -0,0 +1,52 @@
+Certain environments should be treated as inline unless they
+are surrounded by blank lines:
+
+```
+% pandoc -t latex --wrap=preserve
+Lorem ipsum dolor sit amet,
+
+\begin{equation}
+E = mc^2,
+\end{equation}
+
+consectetur adipiscing elit.
+^D
+Lorem ipsum dolor sit amet,
+
+\begin{equation}
+E = mc^2,
+\end{equation}
+
+consectetur adipiscing elit.
+```
+
+```
+% pandoc -t latex --wrap=preserve
+Lorem ipsum dolor sit amet,
+\begin{equation}
+E = mc^2,
+\end{equation}
+consectetur adipiscing elit.
+^D
+Lorem ipsum dolor sit amet,
+\begin{equation}
+E = mc^2,
+\end{equation}
+consectetur adipiscing elit.
+```
+
+```
+% pandoc -t latex --wrap=preserve
+The formula
+\begin{math}
+x = y
+\end{math}
+should be inline.
+^D
+The formula
+\begin{math}
+x = y
+\end{math}
+should be inline.
+```
+
diff --git a/documents/markdown/pandoc-md/3314.md b/documents/markdown/pandoc-md/3314.md
new file mode 100644
index 0000000..6c78254
--- /dev/null
+++ b/documents/markdown/pandoc-md/3314.md
@@ -0,0 +1,34 @@
+See #3315 and <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#simple-tables>.
+
+```
+% pandoc -f org -t html5
++-----------+-------+----------+
+| First | 12.0 | Example |
+| | | row |
+| | | spanning |
+| | | lines |
++-----------+-------+----------+
+| Second | 5.0 | Another |
++-----------+-------+----------+
+^D
+<table style="width:43%;">
+<colgroup>
+<col style="width: 16%" />
+<col style="width: 11%" />
+<col style="width: 15%" />
+</colgroup>
+<tbody>
+<tr>
+<td>First</td>
+<td>12.0</td>
+<td>Example row spanning lines</td>
+</tr>
+<tr>
+<td>Second</td>
+<td>5.0</td>
+<td>Another</td>
+</tr>
+</tbody>
+</table>
+```
+
diff --git a/documents/markdown/pandoc-md/3324.md b/documents/markdown/pandoc-md/3324.md
new file mode 100644
index 0000000..45405fe
--- /dev/null
+++ b/documents/markdown/pandoc-md/3324.md
@@ -0,0 +1,18 @@
+```
+% pandoc -t latex
+Signatures
+
+\
+\
+___________________________\
+Peter Foobar\
+*The Foo Company*
+^D
+Signatures
+
+\hfill\break
+\hfill\break
+\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\\
+Peter Foobar\\
+\emph{The Foo Company}
+```
diff --git a/documents/markdown/pandoc-md/3337.md b/documents/markdown/pandoc-md/3337.md
new file mode 100644
index 0000000..7ba14dc
--- /dev/null
+++ b/documents/markdown/pandoc-md/3337.md
@@ -0,0 +1,13 @@
+```
+% pandoc -f html -t markdown
+<table>
+<tr><td>a</td></tr>
+<tr><td>1</td><td>2</td></tr>
+</table>
+^D
+ --- ---
+ a
+ 1 2
+ --- ---
+```
+
diff --git a/documents/markdown/pandoc-md/3348.md b/documents/markdown/pandoc-md/3348.md
new file mode 100644
index 0000000..9641360
--- /dev/null
+++ b/documents/markdown/pandoc-md/3348.md
@@ -0,0 +1,70 @@
+```
+% pandoc -t native --columns=72
+ ----- ------------------------------------------------
+ foo bar
+
+ foo this is a long
+ line of text
+ ----- ------------------------------------------------
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignRight , ColWidth 8.333333333333333e-2 )
+ , ( AlignLeft , ColWidth 0.6805555555555556 )
+ ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "foo" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "bar" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "foo" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain
+ [ Str "this"
+ , Space
+ , Str "is"
+ , Space
+ , Str "a"
+ , Space
+ , Str "long"
+ , SoftBreak
+ , Str "line"
+ , Space
+ , Str "of"
+ , Space
+ , Str "text"
+ ]
+ ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
diff --git a/documents/markdown/pandoc-md/3401.md b/documents/markdown/pandoc-md/3401.md
new file mode 100644
index 0000000..3b16e84
--- /dev/null
+++ b/documents/markdown/pandoc-md/3401.md
@@ -0,0 +1,19 @@
+See #3401 and <http://orgmode.org/manual/Macro-replacement.html>
+
+```
+% pandoc -f org -t native
+#+MACRO: HELLO /Hello, $1/
+{{{HELLO(World)}}}
+^D
+[ Para [ Emph [ Str "Hello," , Space , Str "World" ] ] ]
+```
+
+Inverted argument order
+
+```
+% pandoc -f org -t native
+#+MACRO: A $2,$1
+{{{A(1,2)}}}
+^D
+[ Para [ Str "2,1" ] ]
+```
diff --git a/documents/markdown/pandoc-md/3407.md b/documents/markdown/pandoc-md/3407.md
new file mode 100644
index 0000000..edc1bcb
--- /dev/null
+++ b/documents/markdown/pandoc-md/3407.md
@@ -0,0 +1,18 @@
+```
+% pandoc -f native -t rst
+[Para [Code ("",["interpreted-text"],[("role","foo")]) "text"]]
+^D
+:foo:`text`
+```
+
+```
+% pandoc -f rst -t native
+:foo:`text`
+^D
+[ Para
+ [ Code
+ ( "" , [ "interpreted-text" ] , [ ( "role" , "foo" ) ] )
+ "text"
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/3422.md b/documents/markdown/pandoc-md/3422.md
new file mode 100644
index 0000000..d0fbe20
--- /dev/null
+++ b/documents/markdown/pandoc-md/3422.md
@@ -0,0 +1,9 @@
+See #3422
+
+```
+% pandoc -t latex --syntax-highlighting=idiomatic
+`int main(int argc, const char *argv[]);`{.c}
+^D
+\passthrough{\lstinline[language=C]!int main(int argc, const char *argv[]);!}
+```
+
diff --git a/documents/markdown/pandoc-md/3432.md b/documents/markdown/pandoc-md/3432.md
new file mode 100644
index 0000000..aaa8526
--- /dev/null
+++ b/documents/markdown/pandoc-md/3432.md
@@ -0,0 +1,289 @@
+List-table with header-rows and widths options.
+
+```
+% pandoc -f rst
+.. list-table:: Frozen Delights!
+ :widths: 15 10 30
+ :header-rows: 1
+
+ * - Treat
+ - Quantity
+ - Description
+ * - Albatross
+ - 2.99
+ - On a stick!
+ * - Crunchy Frog
+ - 1.49
+ - If we took the bones out, it wouldn't be
+ crunchy, now would it?
+ * - Gannet Ripple
+ - 1.99
+ - On a stick!
+^D
+<table>
+<caption>Frozen Delights!</caption>
+<colgroup>
+<col style="width: 27%" />
+<col style="width: 18%" />
+<col style="width: 54%" />
+</colgroup>
+<thead>
+<tr>
+<th>Treat</th>
+<th>Quantity</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Albatross</td>
+<td>2.99</td>
+<td>On a stick!</td>
+</tr>
+<tr>
+<td>Crunchy Frog</td>
+<td>1.49</td>
+<td>If we took the bones out, it wouldn't be crunchy, now would it?</td>
+</tr>
+<tr>
+<td>Gannet Ripple</td>
+<td>1.99</td>
+<td>On a stick!</td>
+</tr>
+</tbody>
+</table>
+```
+
+List-table whose widths is "auto".
+
+```
+% pandoc -f rst
+.. list-table:: Frozen Delights!
+ :header-rows: 1
+ :widths: auto
+
+ * - Treat
+ - Quantity
+ - Description
+ * - Albatross
+ - 2.99
+ - On a stick!
+ * - Crunchy Frog
+ - 1.49
+ - If we took the bones out, it wouldn't be
+ crunchy, now would it?
+ * - Gannet Ripple
+ - 1.99
+ - On a stick!
+^D
+<table>
+<caption>Frozen Delights!</caption>
+<thead>
+<tr>
+<th>Treat</th>
+<th>Quantity</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Albatross</td>
+<td>2.99</td>
+<td>On a stick!</td>
+</tr>
+<tr>
+<td>Crunchy Frog</td>
+<td>1.49</td>
+<td>If we took the bones out, it wouldn't be crunchy, now would it?</td>
+</tr>
+<tr>
+<td>Gannet Ripple</td>
+<td>1.99</td>
+<td>On a stick!</td>
+</tr>
+</tbody>
+</table>
+```
+
+
+List-table with header-rows which is bigger than 1. Only the first row is treated as a header.
+
+```
+% pandoc -f rst
+.. list-table:: Frozen Delights!
+ :header-rows: 2
+
+ * - Treat
+ - Quantity
+ - Description
+ * - Albatross
+ - 2.99
+ - On a stick!
+ * - Crunchy Frog
+ - 1.49
+ - If we took the bones out, it wouldn't be
+ crunchy, now would it?
+ * - Gannet Ripple
+ - 1.99
+ - On a stick!
+^D
+<table>
+<caption>Frozen Delights!</caption>
+<thead>
+<tr>
+<th>Treat</th>
+<th>Quantity</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Albatross</td>
+<td>2.99</td>
+<td>On a stick!</td>
+</tr>
+<tr>
+<td>Crunchy Frog</td>
+<td>1.49</td>
+<td>If we took the bones out, it wouldn't be crunchy, now would it?</td>
+</tr>
+<tr>
+<td>Gannet Ripple</td>
+<td>1.99</td>
+<td>On a stick!</td>
+</tr>
+</tbody>
+</table>
+```
+
+List-table without header-rows.
+
+```
+% pandoc -f rst
+.. list-table:: Frozen Delights!
+
+ * - Albatross
+ - 2.99
+ - On a stick!
+ * - Crunchy Frog
+ - 1.49
+ - If we took the bones out, it wouldn't be
+ crunchy, now would it?
+ * - Gannet Ripple
+ - 1.99
+ - On a stick!
+^D
+<table>
+<caption>Frozen Delights!</caption>
+<tbody>
+<tr>
+<td>Albatross</td>
+<td>2.99</td>
+<td>On a stick!</td>
+</tr>
+<tr>
+<td>Crunchy Frog</td>
+<td>1.49</td>
+<td>If we took the bones out, it wouldn't be crunchy, now would it?</td>
+</tr>
+<tr>
+<td>Gannet Ripple</td>
+<td>1.99</td>
+<td>On a stick!</td>
+</tr>
+</tbody>
+</table>
+```
+
+List-table with empty cells. You need a space after '-', otherwise the row will disappear. Parser for Bulletlists causes this restriction.
+
+```
+% pandoc -f rst
+.. list-table:: Frozen Delights!
+ :header-rows: 2
+
+ * - Treat
+ - Quantity
+ - Description
+ * - Albatross
+ - 2.99
+ -
+ * - Crunchy Frog
+ -
+ - If we took the bones out, it wouldn't be
+ crunchy, now would it?
+ * - Gannet Ripple
+ - 1.99
+ - On a stick!
+^D
+<table>
+<caption>Frozen Delights!</caption>
+<thead>
+<tr>
+<th>Treat</th>
+<th>Quantity</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Albatross</td>
+<td>2.99</td>
+<td></td>
+</tr>
+<tr>
+<td>Crunchy Frog</td>
+<td></td>
+<td>If we took the bones out, it wouldn't be crunchy, now would it?</td>
+</tr>
+<tr>
+<td>Gannet Ripple</td>
+<td>1.99</td>
+<td>On a stick!</td>
+</tr>
+</tbody>
+</table>
+```
+
+List-table with a cell having a bulletlist
+
+```
+% pandoc -f rst
+.. list-table:: Frozen Delights!
+
+ * - Albatross
+ - 2.99
+ - + On a stick!
+ + In a cup!
+ * - Crunchy Frog
+ - 1.49
+ - If we took the bones out, it wouldn't be
+ crunchy, now would it?
+ * - Gannet Ripple
+ - 1.99
+ - On a stick!
+^D
+<table>
+<caption>Frozen Delights!</caption>
+<tbody>
+<tr>
+<td>Albatross</td>
+<td>2.99</td>
+<td><ul>
+<li>On a stick!</li>
+<li>In a cup!</li>
+</ul></td>
+</tr>
+<tr>
+<td>Crunchy Frog</td>
+<td>1.49</td>
+<td>If we took the bones out, it wouldn't be crunchy, now would it?</td>
+</tr>
+<tr>
+<td>Gannet Ripple</td>
+<td>1.99</td>
+<td>On a stick!</td>
+</tr>
+</tbody>
+</table>
+```
diff --git a/documents/markdown/pandoc-md/3432a.md b/documents/markdown/pandoc-md/3432a.md
new file mode 100644
index 0000000..5f25bce
--- /dev/null
+++ b/documents/markdown/pandoc-md/3432a.md
@@ -0,0 +1,19 @@
+```
+% pandoc -f rst
+* - a
+ - b
+* - c
+ - d
+^D
+<ul>
+<li><ul>
+<li>a</li>
+<li>b</li>
+</ul></li>
+<li><ul>
+<li>c</li>
+<li>d</li>
+</ul></li>
+</ul>
+```
+
diff --git a/documents/markdown/pandoc-md/3450.md b/documents/markdown/pandoc-md/3450.md
new file mode 100644
index 0000000..1feb915
--- /dev/null
+++ b/documents/markdown/pandoc-md/3450.md
@@ -0,0 +1,12 @@
+```
+% pandoc -fmarkdown-implicit_figures
+{height=2em}
+^D
+<p><img src="lalune.jpg" style="height:2em" alt="image" /></p>
+```
+```
+% pandoc -fmarkdown-implicit_figures -t latex
+{height=2em}
+^D
+\includegraphics[width=\linewidth,height=2em,keepaspectratio,alt={image}]{lalune.jpg}
+```
diff --git a/documents/markdown/pandoc-md/3475.md b/documents/markdown/pandoc-md/3475.md
new file mode 100644
index 0000000..41a738f
--- /dev/null
+++ b/documents/markdown/pandoc-md/3475.md
@@ -0,0 +1,45 @@
+RST implicit internal links to headers:
+
+```
+% pandoc -f rst
+Years
+-----
+
+Years_
+^D
+<h1 id="years">Years</h1>
+<p><a href="#years">Years</a></p>
+```
+
+```
+% pandoc -f rst
+Years_
+
+Years
+-----
+^D
+<p><a href="#years">Years</a></p>
+<h1 id="years">Years</h1>
+```
+
+```
+% pandoc -f rst
+Years and years
+---------------
+
+`Years and years`_
+^D
+<h1 id="years-and-years">Years and years</h1>
+<p><a href="#years-and-years">Years and years</a></p>
+```
+
+```
+% pandoc -f rst
+Years and *years*
+-----------------
+
+`Years and years`_
+^D
+<h1 id="years-and-years">Years and <em>years</em></h1>
+<p><a href="#years-and-years">Years and years</a></p>
+```
diff --git a/documents/markdown/pandoc-md/3494.md b/documents/markdown/pandoc-md/3494.md
new file mode 100644
index 0000000..ba52662
--- /dev/null
+++ b/documents/markdown/pandoc-md/3494.md
@@ -0,0 +1,40 @@
+```
+% pandoc -f latex --quiet
+\begin{table}[h!]
+\begin{tabular}{r|l|l}
+
+ {\large \textbf{ﺍ}} && \\
+ \textbf{ﺄﺤﺴﻨﺘـ(ﻭﺍ) IV} & \em{ʾaḥsant(ū)} & thank you \\
+ \newpage
+ \emph{blah} & \emph{blah} & \emph{blah} \\
+ blah & blah & blah \\
+
+\end{tabular}
+\end{table}
+^D
+<table>
+<tbody>
+<tr>
+<td style="text-align: right;"><span><strong>ﺍ</strong></span></td>
+<td style="text-align: left;"></td>
+<td style="text-align: left;"></td>
+</tr>
+<tr>
+<td style="text-align: right;"><strong>ﺄﺤﺴﻨﺘـ(ﻭﺍ) IV</strong></td>
+<td style="text-align: left;"><em><span>ʾaḥsant(ū)</span></em></td>
+<td style="text-align: left;">thank you</td>
+</tr>
+<tr>
+<td style="text-align: right;"><em>blah</em></td>
+<td style="text-align: left;"><em>blah</em></td>
+<td style="text-align: left;"><em>blah</em></td>
+</tr>
+<tr>
+<td style="text-align: right;">blah</td>
+<td style="text-align: left;">blah</td>
+<td style="text-align: left;">blah</td>
+</tr>
+</tbody>
+</table>
+```
+
diff --git a/documents/markdown/pandoc-md/3497.md b/documents/markdown/pandoc-md/3497.md
new file mode 100644
index 0000000..ca591cd
--- /dev/null
+++ b/documents/markdown/pandoc-md/3497.md
@@ -0,0 +1,51 @@
+Escape list markers at beginning of paragraph:
+
+```
+% pandoc -t markdown
+\* ok
+
+\+ ok
+
+\- ok
+
+1\. ok
+
+a\. ok
+^D
+\* ok
+
+\+ ok
+
+\- ok
+
+1\. ok
+
+a\. ok
+```
+
+Here we don't need to escape because there's no space:
+
+```
+% pandoc -t markdown
+\+ok
+
+\-ok
+
+1.ok
+^D
++ok
+
+-ok
+
+1.ok
+```
+
+Also escape things that might become line blocks or tables:
+
+```
+% pandoc -t markdown
+\| hi \|
+^D
+\| hi \|
+```
+
diff --git a/documents/markdown/pandoc-md/3499.md b/documents/markdown/pandoc-md/3499.md
new file mode 100644
index 0000000..4058e88
--- /dev/null
+++ b/documents/markdown/pandoc-md/3499.md
@@ -0,0 +1,18 @@
+Org-mode tables can't be on the same line as list markers:
+```
+% pandoc -f org
+- |something|
+-
+ |else|
+^D
+<ul>
+<li>|something|</li>
+<li><table>
+<tbody>
+<tr>
+<td>else</td>
+</tr>
+</tbody>
+</table></li>
+</ul>
+```
diff --git a/documents/markdown/pandoc-md/3510.md b/documents/markdown/pandoc-md/3510.md
new file mode 100644
index 0000000..48522f7
--- /dev/null
+++ b/documents/markdown/pandoc-md/3510.md
@@ -0,0 +1,22 @@
+See <http://orgmode.org/manual/Include-files.html>
+```
+% pandoc -f org -t native
+Text
+
+#+include: "command/3510-subdoc.org"
+
+#+INCLUDE: "command/3510-src.hs" src haskell
+#+INCLUDE: "command/3510-export.latex" export latex
+
+More text
+^D
+[ Para [ Str "Text" ]
+, Header 1 ( "subsection" , [] , [] ) [ Str "Subsection" ]
+, Para [ Str "Included" , Space , Str "text" ]
+, Plain [ Str "Lorem" , Space , Str "ipsum." ]
+, CodeBlock
+ ( "" , [ "haskell" ] , [] ) "putStrLn outString\n"
+, RawBlock (Format "latex") "\\emph{Hello}"
+, Para [ Str "More" , Space , Str "text" ]
+]
+```
diff --git a/documents/markdown/pandoc-md/3511.md b/documents/markdown/pandoc-md/3511.md
new file mode 100644
index 0000000..0fede7a
--- /dev/null
+++ b/documents/markdown/pandoc-md/3511.md
@@ -0,0 +1,52 @@
+```
+% pandoc -t native
+- a
+ - b
+ - c
+
+- code
+
+1000. one
+
+ not continuation
+^D
+[ BulletList
+ [ [ Plain [ Str "a" ]
+ , BulletList
+ [ [ Plain [ Str "b" ]
+ , BulletList [ [ Plain [ Str "c" ] ] ]
+ ]
+ ]
+ ]
+ , [ CodeBlock ( "" , [] , [] ) "code" ]
+ ]
+, OrderedList
+ ( 1000 , Decimal , Period ) [ [ Plain [ Str "one" ] ] ]
+, CodeBlock ( "" , [] , [] ) "not continuation"
+]
+```
+
+```
+% pandoc -t native -f markdown+four_space_rule
+- a
+ - b
+ - c
+
+- not code
+
+1000. one
+
+ continuation
+^D
+[ BulletList
+ [ [ Plain [ Str "a" ] ]
+ , [ Plain [ Str "b" ]
+ , BulletList [ [ Plain [ Str "c" ] ] ]
+ ]
+ , [ CodeBlock ( "" , [] , [] ) "not code" ]
+ ]
+, OrderedList
+ ( 1000 , Decimal , Period )
+ [ [ Para [ Str "one" ] , Para [ Str "continuation" ] ] ]
+]
+```
diff --git a/documents/markdown/pandoc-md/3512.md b/documents/markdown/pandoc-md/3512.md
new file mode 100644
index 0000000..cf8c72e
--- /dev/null
+++ b/documents/markdown/pandoc-md/3512.md
@@ -0,0 +1,13 @@
+```
+% pandoc -f markdown-auto_identifiers
+#hi
+^D
+<p>#hi</p>
+```
+
+```
+% pandoc -f markdown-auto_identifiers-space_in_atx_header
+#hi
+^D
+<h1>hi</h1>
+```
diff --git a/documents/markdown/pandoc-md/3516.md b/documents/markdown/pandoc-md/3516.md
new file mode 100644
index 0000000..116268e
--- /dev/null
+++ b/documents/markdown/pandoc-md/3516.md
@@ -0,0 +1,100 @@
+Correctly handle empty row:
+```
+% pandoc -f markdown -t rst
++---+---+
+| 1 | 2 |
++---+---+
+| | |
++---+---+
+^D
++---+---+
+| 1 | 2 |
++---+---+
+| | |
++---+---+
+```
+
+Temporarily added these to figure out what is happening
+on Windows builds.
+```
+% pandoc -f markdown -t native
++---+---+
+| 1 | 2 |
++---+---+
+| | |
++---+---+
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidth 5.555555555555555e-2 )
+ , ( AlignDefault , ColWidth 5.555555555555555e-2 )
+ ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "2" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] ) AlignDefault (RowSpan 1) (ColSpan 1) []
+ , Cell
+ ( "" , [] , [] ) AlignDefault (RowSpan 1) (ColSpan 1) []
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
+
+```
+% pandoc -f native -t rst
+[Table ("",[],[]) (Caption Nothing
+ [])
+ [(AlignDefault,ColWidth 5.555555555555555e-2)
+ ,(AlignDefault,ColWidth 5.555555555555555e-2)]
+ (TableHead ("",[],[])
+ [Row ("",[],[])
+ [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ []
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ []]])
+ [(TableBody ("",[],[]) (RowHeadColumns 0)
+ []
+ [Row ("",[],[])
+ [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Para [Str "1"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Para [Str "2"]]]
+ ,Row ("",[],[])
+ [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ []
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ []]])]
+ (TableFoot ("",[],[])
+ [])]
+^D
++---+---+
+| | |
++===+===+
+| 1 | 2 |
++---+---+
+| | |
++---+---+
+```
diff --git a/documents/markdown/pandoc-md/3518.md b/documents/markdown/pandoc-md/3518.md
new file mode 100644
index 0000000..a4ba7a3
--- /dev/null
+++ b/documents/markdown/pandoc-md/3518.md
@@ -0,0 +1,6 @@
+```
+% pandoc -f latex -t plain
+$\alpha^2 \cdot \alpha^{2+3} \equiv \alpha^7$
+^D
+α² ⋅ α² ⁺ ³ ≡ α⁷
+```
diff --git a/documents/markdown/pandoc-md/3523.md b/documents/markdown/pandoc-md/3523.md
new file mode 100644
index 0000000..c357494
--- /dev/null
+++ b/documents/markdown/pandoc-md/3523.md
@@ -0,0 +1,35 @@
+```
+% pandoc -f latex -t html
+\documentclass{article}
+\usepackage{epigraph}
+\begin{document}
+
+\epigraph{
+ Das Recht hat kein Dasein f{\"u}r sich, sein Wesen vielmehr ist das Leben des Menschen selbst, von einer besonderen Seite angesehen.
+
+ Das Recht hat kein Dasein f{\"u}r sich, sein Wesen vielmehr ist das Leben des Menschen selbst, von einer besonderen Seite angesehen.
+
+ \begin{itemize}
+ \item hey
+ \item hey
+ \item hey
+ \end{itemize}
+
+ }{ Friedrich Carl von Savigny }
+\end{document}
+^D
+<div class="epigraph">
+<p>Das Recht hat kein Dasein f<span>ü</span>r sich, sein Wesen vielmehr
+ist das Leben des Menschen selbst, von einer besonderen Seite
+angesehen.</p>
+<p>Das Recht hat kein Dasein f<span>ü</span>r sich, sein Wesen vielmehr
+ist das Leben des Menschen selbst, von einer besonderen Seite
+angesehen.</p>
+<ul>
+<li><p>hey</p></li>
+<li><p>hey</p></li>
+<li><p>hey</p></li>
+</ul>
+<p>Friedrich Carl von Savigny</p>
+</div>
+```
diff --git a/documents/markdown/pandoc-md/3526.md b/documents/markdown/pandoc-md/3526.md
new file mode 100644
index 0000000..e197bcf
--- /dev/null
+++ b/documents/markdown/pandoc-md/3526.md
@@ -0,0 +1,14 @@
+```
+% pandoc -t rst
++--+---+
+| | |
++--+---+
+| | |
++--+---+
+^D
++---+---+
+| | |
++---+---+
+| | |
++---+---+
+```
diff --git a/documents/markdown/pandoc-md/3529.md b/documents/markdown/pandoc-md/3529.md
new file mode 100644
index 0000000..fdf42f6
--- /dev/null
+++ b/documents/markdown/pandoc-md/3529.md
@@ -0,0 +1,15 @@
+```
+% pandoc -t markdown-simple_tables-pipe_tables-grid_tables+multiline_tables
+A B
+-- --
+7 8
+9 10
+^D
+ --------
+ A B
+ --- ----
+ 7 8
+
+ 9 10
+ --------
+```
diff --git a/documents/markdown/pandoc-md/3530.md b/documents/markdown/pandoc-md/3530.md
new file mode 100644
index 0000000..168cb70
--- /dev/null
+++ b/documents/markdown/pandoc-md/3530.md
@@ -0,0 +1,67 @@
+```
+% pandoc -f latex -t native
+\subfile{command/sub-file-chapter-1}
+\subfile{command/sub-file-chapter-2}
+^D
+[ Header
+ 1
+ ( "chapter-1" , [] , [] )
+ [ Str "Chapter" , Space , Str "1" ]
+, Para
+ [ Str "This"
+ , Space
+ , Str "is"
+ , Space
+ , Str "Chapter"
+ , Space
+ , Str "1,"
+ , Space
+ , Str "provided"
+ , Space
+ , Str "in"
+ , Space
+ , Str "a"
+ , Space
+ , Str "sub"
+ , Space
+ , Str "file."
+ ]
+, Header
+ 1
+ ( "chapter-2" , [] , [] )
+ [ Str "Chapter" , Space , Str "2" ]
+, Para
+ [ Str "This"
+ , Space
+ , Str "is"
+ , Space
+ , Str "Chapter"
+ , Space
+ , Str "2,"
+ , Space
+ , Str "provided"
+ , Space
+ , Str "in"
+ , Space
+ , Str "a"
+ , Space
+ , Str "second"
+ , Space
+ , Str "sub"
+ , Space
+ , Str "file."
+ ]
+]
+```
+
+```
+% pandoc -flatex+raw_tex -t native
+\subfile{command/sub-file-chapter-1}
+\subfile{command/sub-file-chapter-2}
+^D
+[ RawBlock
+ (Format "latex") "\\subfile{command/sub-file-chapter-1}"
+, RawBlock
+ (Format "latex") "\\subfile{command/sub-file-chapter-2}"
+]
+```
diff --git a/documents/markdown/pandoc-md/3531.md b/documents/markdown/pandoc-md/3531.md
new file mode 100644
index 0000000..778e93d
--- /dev/null
+++ b/documents/markdown/pandoc-md/3531.md
@@ -0,0 +1,20 @@
+```
+% pandoc -t mediawiki --wrap=preserve
+* This is a list item.
+* This is a list item in Markdown. It is
+ continued in the next line.
+ * It has a sub-item.
+* This is the next list item.
+
+A paragraph can span multiple lines
+without being broken into pieces.
+^D
+* This is a list item.
+* This is a list item in Markdown. It is continued in the next line.
+** It has a sub-item.
+* This is the next list item.
+
+A paragraph can span multiple lines
+without being broken into pieces.
+
+```
diff --git a/documents/markdown/pandoc-md/3533-rst-csv-tables.md b/documents/markdown/pandoc-md/3533-rst-csv-tables.md
new file mode 100644
index 0000000..ed69ca8
--- /dev/null
+++ b/documents/markdown/pandoc-md/3533-rst-csv-tables.md
@@ -0,0 +1,253 @@
+```
+% pandoc -f rst -t native
+.. csv-table:: Test
+ :widths: 10, 5, 10
+ :header: Flavor,Price,Slogan
+ :file: command/3533-rst-csv-tables.csv
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [ Plain [ Str "Test" ] ])
+ [ ( AlignDefault , ColWidth 0.4 )
+ , ( AlignDefault , ColWidth 0.2 )
+ , ( AlignDefault , ColWidth 0.4 )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Flavor" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Price" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Slogan" ] ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Albatross" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "2.99" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain
+ [ Str "On"
+ , Space
+ , Str "a"
+ , Space
+ , Str "stick!"
+ ]
+ ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Crunchy" , Space , Str "Frog" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1.49" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain
+ [ Str "If"
+ , Space
+ , Str "we"
+ , Space
+ , Str "took"
+ , Space
+ , Str "the"
+ , Space
+ , Str "bones"
+ , Space
+ , Str "out,"
+ , Space
+ , Str "it"
+ , Space
+ , Str "wouldn't"
+ , Space
+ , Str "be"
+ , SoftBreak
+ , Str "crunchy,"
+ , Space
+ , Str "now"
+ , Space
+ , Str "would"
+ , Space
+ , Str "it?"
+ ]
+ ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
+
+```
+% pandoc -f rst -t native
+.. csv-table:: Test
+ :header-rows: 1
+ :quote: '
+ :delim: space
+
+ '' 'a' 'b'
+ 'cat''s' 3 4
+ 'dog''s' 2 3
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [ Plain [ Str "Test" ] ])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] ) AlignDefault (RowSpan 1) (ColSpan 1) []
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "a" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "b" ] ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "cat's" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "3" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "4" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "dog's" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "3" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
+
+```
+% pandoc -f rst -t native
+.. csv-table:: Test
+ :escape: \
+
+ "1","\""
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [ Plain [ Str "Test" ] ])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "\"" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
+
diff --git a/documents/markdown/pandoc-md/3534.md b/documents/markdown/pandoc-md/3534.md
new file mode 100644
index 0000000..1ba3326
--- /dev/null
+++ b/documents/markdown/pandoc-md/3534.md
@@ -0,0 +1,85 @@
+```
+% pandoc -f latex -t html
+I want to explain the interface of \lstinline[language=Java]{public class MyClass}.
+^D
+<p>I want to explain the interface of <code
+class="sourceCode java"><span class="kw">public</span> <span class="kw">class</span> MyClass</code>.</p>
+
+```
+
+```
+% pandoc -f latex -t html
+I want to explain the interface of \lstinline{public class MyClass}.
+^D
+<p>I want to explain the interface of
+<code>public class MyClass</code>.</p>
+
+```
+
+```
+% pandoc -f latex -t native
+I want to explain the interface of \lstinline[language=Java]{public class MyClass}.
+^D
+[ Para
+ [ Str "I"
+ , Space
+ , Str "want"
+ , Space
+ , Str "to"
+ , Space
+ , Str "explain"
+ , Space
+ , Str "the"
+ , Space
+ , Str "interface"
+ , Space
+ , Str "of"
+ , Space
+ , Code ( "" , [ "java" ] , [] ) "public class MyClass"
+ , Str "."
+ ]
+]
+```
+
+```
+% pandoc -f latex -t html
+I want to explain the interface of \mintinline{java}{public class MyClass}.
+^D
+<p>I want to explain the interface of <code
+class="sourceCode java"><span class="kw">public</span> <span class="kw">class</span> MyClass</code>.</p>
+
+```
+
+```
+% pandoc -f latex -t html
+I want to explain the interface of \mintinline{java}|public class MyClass|.
+^D
+<p>I want to explain the interface of <code
+class="sourceCode java"><span class="kw">public</span> <span class="kw">class</span> MyClass</code>.</p>
+
+```
+
+```
+% pandoc -f latex -t native
+I want to explain the interface of \mintinline[linenos]{java}{public class MyClass}.
+^D
+[ Para
+ [ Str "I"
+ , Space
+ , Str "want"
+ , Space
+ , Str "to"
+ , Space
+ , Str "explain"
+ , Space
+ , Str "the"
+ , Space
+ , Str "interface"
+ , Space
+ , Str "of"
+ , Space
+ , Code ( "" , [ "java" ] , [] ) "public class MyClass"
+ , Str "."
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/3537.md b/documents/markdown/pandoc-md/3537.md
new file mode 100644
index 0000000..3f44453
--- /dev/null
+++ b/documents/markdown/pandoc-md/3537.md
@@ -0,0 +1,34 @@
+Generalized raw attributes.
+
+````
+% pandoc -t native
+```{=ms}
+.MACRO
+foo bar
+```
+^D
+[ RawBlock (Format "ms") ".MACRO\nfoo bar" ]
+````
+
+````
+% pandoc -t native
+Hi `there`{=ms}.
+^D
+[ Para
+ [ Str "Hi"
+ , Space
+ , RawInline (Format "ms") "there"
+ , Str "."
+ ]
+]
+````
+
+````
+% pandoc -t native
+~~~ {=ms}
+.MACRO
+foo bar
+~~~
+^D
+[ RawBlock (Format "ms") ".MACRO\nfoo bar" ]
+````
diff --git a/documents/markdown/pandoc-md/3539.md b/documents/markdown/pandoc-md/3539.md
new file mode 100644
index 0000000..b2ce545
--- /dev/null
+++ b/documents/markdown/pandoc-md/3539.md
@@ -0,0 +1,253 @@
+# Commands of [glossaries package](ftp://ftp.tu-chemnitz.de/pub/tex/macros/latex/contrib/glossaries/glossaries-code.pdf)
+
+```
+% pandoc -f latex -t native
+Many programming languages provide \glspl{API}. Each \gls{API} should provide a documentation.
+^D
+[ Para
+ [ Str "Many"
+ , Space
+ , Str "programming"
+ , Space
+ , Str "languages"
+ , Space
+ , Str "provide"
+ , Space
+ , Span
+ ( ""
+ , []
+ , [ ( "acronym-label" , "API" )
+ , ( "acronym-form" , "plural+short" )
+ ]
+ )
+ [ Str "APIs" ]
+ , Str "."
+ , Space
+ , Str "Each"
+ , Space
+ , Span
+ ( ""
+ , []
+ , [ ( "acronym-label" , "API" )
+ , ( "acronym-form" , "singular+short" )
+ ]
+ )
+ [ Str "API" ]
+ , Space
+ , Str "should"
+ , Space
+ , Str "provide"
+ , Space
+ , Str "a"
+ , Space
+ , Str "documentation."
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\Glsdesc{API} XYZ ist not as performant as \glsdesc{API} ZXY.
+^D
+[ Para
+ [ Span
+ ( ""
+ , []
+ , [ ( "acronym-label" , "API" )
+ , ( "acronym-form" , "singular+long" )
+ ]
+ )
+ [ Str "API" ]
+ , Space
+ , Str "XYZ"
+ , Space
+ , Str "ist"
+ , Space
+ , Str "not"
+ , Space
+ , Str "as"
+ , Space
+ , Str "performant"
+ , Space
+ , Str "as"
+ , Space
+ , Span
+ ( ""
+ , []
+ , [ ( "acronym-label" , "API" )
+ , ( "acronym-form" , "singular+long" )
+ ]
+ )
+ [ Str "API" ]
+ , Space
+ , Str "ZXY."
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\Acrlong{API} XYZ ist not as performant as \acrlong{API} ZXY.
+^D
+[ Para
+ [ Span
+ ( ""
+ , []
+ , [ ( "acronym-label" , "API" )
+ , ( "acronym-form" , "singular+long" )
+ ]
+ )
+ [ Str "API" ]
+ , Space
+ , Str "XYZ"
+ , Space
+ , Str "ist"
+ , Space
+ , Str "not"
+ , Space
+ , Str "as"
+ , Space
+ , Str "performant"
+ , Space
+ , Str "as"
+ , Space
+ , Span
+ ( ""
+ , []
+ , [ ( "acronym-label" , "API" )
+ , ( "acronym-form" , "singular+long" )
+ ]
+ )
+ [ Str "API" ]
+ , Space
+ , Str "ZXY."
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\Acrfull{API} XYZ ist not as performant as \acrfull{API} ZXY.
+^D
+[ Para
+ [ Span
+ ( ""
+ , []
+ , [ ( "acronym-label" , "API" )
+ , ( "acronym-form" , "singular+full" )
+ ]
+ )
+ [ Str "API" ]
+ , Space
+ , Str "XYZ"
+ , Space
+ , Str "ist"
+ , Space
+ , Str "not"
+ , Space
+ , Str "as"
+ , Space
+ , Str "performant"
+ , Space
+ , Str "as"
+ , Space
+ , Span
+ ( ""
+ , []
+ , [ ( "acronym-label" , "API" )
+ , ( "acronym-form" , "singular+full" )
+ ]
+ )
+ [ Str "API" ]
+ , Space
+ , Str "ZXY."
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\Acrshort{API} XYZ ist not as performant as \acrshort{API} ZXY.
+^D
+[ Para
+ [ Span
+ ( ""
+ , []
+ , [ ( "acronym-label" , "API" )
+ , ( "acronym-form" , "singular+abbrv" )
+ ]
+ )
+ [ Str "API" ]
+ , Space
+ , Str "XYZ"
+ , Space
+ , Str "ist"
+ , Space
+ , Str "not"
+ , Space
+ , Str "as"
+ , Space
+ , Str "performant"
+ , Space
+ , Str "as"
+ , Space
+ , Span
+ ( ""
+ , []
+ , [ ( "acronym-label" , "API" )
+ , ( "acronym-form" , "singular+abbrv" )
+ ]
+ )
+ [ Str "API" ]
+ , Space
+ , Str "ZXY."
+ ]
+]
+```
+
+# Commands of [acronym package](ftp://ftp.mpi-sb.mpg.de/pub/tex/mirror/ftp.dante.de/pub/tex/macros/latex/contrib/acronym/acronym.pdf)
+
+```
+% pandoc -f latex -t native
+Many programming languages provide \acp{API}. Each \ac{API} should provide a documentation.
+^D
+[ Para
+ [ Str "Many"
+ , Space
+ , Str "programming"
+ , Space
+ , Str "languages"
+ , Space
+ , Str "provide"
+ , Space
+ , Span
+ ( ""
+ , []
+ , [ ( "acronym-label" , "API" )
+ , ( "acronym-form" , "plural+short" )
+ ]
+ )
+ [ Str "APIs" ]
+ , Str "."
+ , Space
+ , Str "Each"
+ , Space
+ , Span
+ ( ""
+ , []
+ , [ ( "acronym-label" , "API" )
+ , ( "acronym-form" , "singular+short" )
+ ]
+ )
+ [ Str "API" ]
+ , Space
+ , Str "should"
+ , Space
+ , Str "provide"
+ , Space
+ , Str "a"
+ , Space
+ , Str "documentation."
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/3558.md b/documents/markdown/pandoc-md/3558.md
new file mode 100644
index 0000000..c9c782c
--- /dev/null
+++ b/documents/markdown/pandoc-md/3558.md
@@ -0,0 +1,13 @@
+```
+% pandoc -t native
+\multi
+
+hello
+
+\endmulti
+^D
+[ RawBlock (Format "tex") "\\multi"
+, Para [ Str "hello" ]
+, RawBlock (Format "tex") "\\endmulti"
+]
+```
diff --git a/documents/markdown/pandoc-md/3568.md b/documents/markdown/pandoc-md/3568.md
new file mode 100644
index 0000000..ffc1daa
--- /dev/null
+++ b/documents/markdown/pandoc-md/3568.md
@@ -0,0 +1,16 @@
+```
+% pandoc -t man
+normal *italic **bold in the middle** only italic* normal.
+
+normal **bold `code` more bold** normal.
+
+normal `code` normal.
+^D
+.PP
+normal \f[I]italic \f[BI]bold in the middle\f[I] only italic\f[R]
+normal.
+.PP
+normal \f[B]bold \f[CB]code\f[B] more bold\f[R] normal.
+.PP
+normal \f[CR]code\f[R] normal.
+```
diff --git a/documents/markdown/pandoc-md/3577.md b/documents/markdown/pandoc-md/3577.md
new file mode 100644
index 0000000..063e41c
--- /dev/null
+++ b/documents/markdown/pandoc-md/3577.md
@@ -0,0 +1,41 @@
+```
+% pandoc -f latex -t html5 --quiet
+\begin{figure}[ht]
+ \begin{subfigure}{0.45\textwidth}
+ \centering
+ \includegraphics{img1.jpg}
+ \caption{Caption 1}
+ \end{subfigure}
+
+ \begin{subfigure}{0.45\textwidth}
+ \centering
+ \includegraphics{img2.jpg}
+ \caption{Caption 2}
+ \end{subfigure}
+ \caption{Subfigure with Subfloat}
+\end{figure}
+^D
+<figure data-latex-placement="ht">
+<figure>
+<img src="img1.jpg" />
+<figcaption>Caption 1</figcaption>
+</figure>
+<figure>
+<img src="img2.jpg" />
+<figcaption>Caption 2</figcaption>
+</figure>
+<figcaption>Subfigure with Subfloat</figcaption>
+</figure>
+```
+```
+% pandoc -f latex -t html5
+\begin{figure}[ht]
+ \includegraphics{img1.jpg}
+ \caption{Caption 3}
+\end{figure}
+^D
+<figure data-latex-placement="ht">
+<img src="img1.jpg" />
+<figcaption>Caption 3</figcaption>
+</figure>
+```
diff --git a/documents/markdown/pandoc-md/3585.md b/documents/markdown/pandoc-md/3585.md
new file mode 100644
index 0000000..3f014db
--- /dev/null
+++ b/documents/markdown/pandoc-md/3585.md
@@ -0,0 +1,35 @@
+```
+% pandoc -f mediawiki+smart -t native
+"Hello"
+
+Same but bzip2 it and nice it <tt>zfs send tank/storage/data/svn@daily-2014-03-20_00.00.00--2w | nice -15 bzip2 | ssh user@hyper.somewhere.org "> /storage/c-3po/tank-storage-data-svn.dmp.bz2"</tt>
+^D
+[ Para [ Quoted DoubleQuote [ Str "Hello" ] ]
+, Para
+ [ Str "Same"
+ , Space
+ , Str "but"
+ , Space
+ , Str "bzip2"
+ , Space
+ , Str "it"
+ , Space
+ , Str "and"
+ , Space
+ , Str "nice"
+ , Space
+ , Str "it"
+ , Space
+ , Code
+ ( "" , [] , [] )
+ "zfs send tank/storage/data/svn@daily-2014-03-20_00.00.00--2w | nice -15 bzip2 | ssh user@hyper.somewhere.org \"> /storage/c-3po/tank-storage-data-svn.dmp.bz2\""
+ ]
+]
+```
+
+```
+% pandoc -f mediawiki -t native
+"Hello"
+^D
+[ Para [ Str "\"Hello\"" ] ]
+```
diff --git a/documents/markdown/pandoc-md/3587.md b/documents/markdown/pandoc-md/3587.md
new file mode 100644
index 0000000..0a3c389
--- /dev/null
+++ b/documents/markdown/pandoc-md/3587.md
@@ -0,0 +1,205 @@
+```
+% pandoc -f latex -t native
+\SI[round-precision=2]{1}{m} is equal to \SI{1000}{mm}
+^D
+[ Para
+ [ Str "1\160m"
+ , Space
+ , Str "is"
+ , Space
+ , Str "equal"
+ , Space
+ , Str "to"
+ , Space
+ , Str "1000\160mm"
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\SI[round-precision=2]{1}[\$]{} is equal to \SI{0.938094}{\euro}
+^D
+[ Para
+ [ Str "$\160\&1"
+ , Space
+ , Str "is"
+ , Space
+ , Str "equal"
+ , Space
+ , Str "to"
+ , Space
+ , Str "0.938094\160\8364"
+ ]
+]
+```
+
+
+```
+% pandoc -f latex -t native
+\SI{30}{\milli\meter}
+^D
+[ Para [ Str "30\160mm" ] ]
+```
+
+```
+% pandoc -f latex -t native
+\SI{6}{\gram}
+^D
+[ Para [ Str "6\160g" ] ]
+```
+
+```
+% pandoc -f latex -t native
+\SI{25}{\square\meter}
+^D
+[ Para [ Str "25\160m" , Superscript [ Str "2" ] ] ]
+```
+
+```
+% pandoc -f latex -t native
+\SI{18.2}{\degreeCelsius}
+^D
+[ Para [ Str "18.2\160\176C" ] ]
+```
+
+```
+% pandoc -f latex -t native
+\SI{18.2}{\celsius}
+^D
+[ Para [ Str "18.2\160\176C" ] ]
+```
+
+# SIrange tests
+
+## Integer range with simple common units
+
+```
+% pandoc -f latex -t native
+\SIrange{10}{20}{\gram}
+^D
+[ Para [ Str "10\160g\8211\&20\160g" ] ]
+```
+```
+% pandoc -f latex -t native
+\SIrange{35}{9}{\milli\meter}
+^D
+[ Para [ Str "35\160mm\8211\&9\160mm" ] ]
+```
+```
+% pandoc -f latex -t native
+\SIrange{4}{97367265}{\celsius}
+^D
+[ Para [ Str "4\160\176C\8211\&97367265\160\176C" ] ]
+```
+
+## Decimal range with simple units
+
+```
+% pandoc -f latex -t native
+\SIrange{4.5}{97367265.5}{\celsius}
+^D
+[ Para [ Str "4.5\160\176C\8211\&97367265.5\160\176C" ] ]
+```
+
+## Squared, cubed etc. units
+
+```
+% pandoc -f latex -t native
+\SIrange{10}{20}{\square\meter}
+^D
+[ Para
+ [ Str "10\160m"
+ , Superscript [ Str "2" ]
+ , Str "\8211\&20\160m"
+ , Superscript [ Str "2" ]
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\SIrange{10}{20}{\cubic\meter}
+^D
+[ Para
+ [ Str "10\160m"
+ , Superscript [ Str "3" ]
+ , Str "\8211\&20\160m"
+ , Superscript [ Str "3" ]
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\SIrange{10}{20}{\raisetothe{4}\meter}
+^D
+[ Para
+ [ Str "10\160m"
+ , Superscript [ Str "4" ]
+ , Str "\8211\&20\160m"
+ , Superscript [ Str "4" ]
+ ]
+]
+```
+
+
+```
+% pandoc -f latex -t native
+\SIrange{10}{20}{\meter\squared}
+^D
+[ Para
+ [ Str "10\160m"
+ , Superscript [ Str "2" ]
+ , Str "\8211\&20\160m"
+ , Superscript [ Str "2" ]
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\SIrange{10}{20}{\meter\cubed}
+^D
+[ Para
+ [ Str "10\160m"
+ , Superscript [ Str "3" ]
+ , Str "\8211\&20\160m"
+ , Superscript [ Str "3" ]
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\SIrange{10}{20}{\meter\tothe{4}}
+^D
+[ Para
+ [ Str "10\160m"
+ , Superscript [ Str "4" ]
+ , Str "\8211\&20\160m"
+ , Superscript [ Str "4" ]
+ ]
+]
+```
+
+
+
+## Ignore round precision
+
+`round-precision` option appears to be ignored by `\SI` as of 7c6dbd37e, so
+`\SIrange` will ignore it as well.
+
+```
+% pandoc -f latex -t native
+\SIrange[round-precision=2]{10}{20}{\gram}
+^D
+[ Para [ Str "10\160g\8211\&20\160g" ] ]
+```
+```
+% pandoc -f latex -t native
+\SIrange[round-precision=2]{10.0}{20.25}{\gram}
+^D
+[ Para [ Str "10.0\160g\8211\&20.25\160g" ] ]
+```
+
diff --git a/documents/markdown/pandoc-md/3596.md b/documents/markdown/pandoc-md/3596.md
new file mode 100644
index 0000000..972395e
--- /dev/null
+++ b/documents/markdown/pandoc-md/3596.md
@@ -0,0 +1,59 @@
+```
+% pandoc -f html -t markdown-raw_html-bracketed_spans-native_spans
+<ul>
+<li>foo</li>
+<li id="id">bar</li>
+<li>baz</li>
+</ul>
+^D
+- foo
+- bar
+- baz
+```
+
+```
+% pandoc -f html -t markdown-raw_html-bracketed_spans-native_spans
+<ul>
+<li>foo</li>
+<li id="id">bar<ul><li>subbar</li></ul></li>
+<li>baz</li>
+</ul>
+^D
+- foo
+- bar
+ - subbar
+- baz
+```
+
+
+```
+% pandoc -f html -t markdown
+<ul>
+<li>foo</li>
+<li id="id">bar</li>
+<li>baz</li>
+</ul>
+^D
+- foo
+- [bar]{#id}
+- baz
+```
+
+
+```
+% pandoc -f html -t markdown
+<ul>
+<li><p>foo</p></li>
+<li id="id"><p>bar</p></li>
+<li><p>baz</p></li>
+</ul>
+^D
+- foo
+
+- ::: {#id}
+ bar
+ :::
+
+- baz
+
+```
diff --git a/documents/markdown/pandoc-md/3615.md b/documents/markdown/pandoc-md/3615.md
new file mode 100644
index 0000000..5fbd48b
--- /dev/null
+++ b/documents/markdown/pandoc-md/3615.md
@@ -0,0 +1,18 @@
+```
+% pandoc -f html -t markdown --reference-links
+<a href="a">foo</a> <a href="b">Foo</a>
+^D
+[foo][] [Foo][1]
+
+ [foo]: a
+ [1]: b
+```
+
+```
+% pandoc -f html -t markdown --reference-links
+<a href="a">foo</a> <a href="a">Foo</a>
+^D
+[foo][] [Foo]
+
+ [foo]: a
+```
diff --git a/documents/markdown/pandoc-md/3619.md b/documents/markdown/pandoc-md/3619.md
new file mode 100644
index 0000000..62962c4
--- /dev/null
+++ b/documents/markdown/pandoc-md/3619.md
@@ -0,0 +1,28 @@
+```
+% pandoc -f html -t markdown --reference-links
+<a href="foo">bar</a>: baz
+^D
+[bar][]: baz
+
+ [bar]: foo
+```
+
+```
+% pandoc -f html -t markdown --reference-links
+<a href="foo">bar</a>(baz)
+^D
+[bar][](baz)
+
+ [bar]: foo
+```
+
+```
+% pandoc -f html -t markdown_strict --reference-links
+<a href="a">foo</a><br/><a href="b">bar</a>
+^D
+[foo][]
+[bar]
+
+ [foo]: a
+ [bar]: b
+```
diff --git a/documents/markdown/pandoc-md/3630.md b/documents/markdown/pandoc-md/3630.md
new file mode 100644
index 0000000..db3a17d
--- /dev/null
+++ b/documents/markdown/pandoc-md/3630.md
@@ -0,0 +1,8 @@
+```
+% pandoc -f markdown -t markdown --reference-links
+{#myId}
+^D
+![foo]
+
+ [foo]: bar.png {#myId}
+```
diff --git a/documents/markdown/pandoc-md/3667.md b/documents/markdown/pandoc-md/3667.md
new file mode 100644
index 0000000..07cd93c
--- /dev/null
+++ b/documents/markdown/pandoc-md/3667.md
@@ -0,0 +1,13 @@
+```
+% pandoc -f textile
+| "link text":http://example.com/ |
+^D
+<table>
+<tbody>
+<tr>
+<td><a href="http://example.com/">link text</a></td>
+</tr>
+</tbody>
+</table>
+```
+
diff --git a/documents/markdown/pandoc-md/3674.md b/documents/markdown/pandoc-md/3674.md
new file mode 100644
index 0000000..a24f6b4
--- /dev/null
+++ b/documents/markdown/pandoc-md/3674.md
@@ -0,0 +1,39 @@
+Make sure we don't get duplicate reference links, even with
+`--reference-location=section`.
+
+```
+% pandoc --reference-links -t markdown --reference-location=section
+# a
+
+
+
+# b
+
+
+
+^D
+# a
+
+![][1]
+
+ [1]: a
+
+# b
+
+![][2]
+
+ [2]: b
+```
+
+Subsidiary issue: allow line break between reference link
+url/title and attributes:
+
+```
+% pandoc
+[a]
+
+[a]: url
+{.class}
+^D
+<p><a href="url" class="class">a</a></p>
+```
diff --git a/documents/markdown/pandoc-md/3675.md b/documents/markdown/pandoc-md/3675.md
new file mode 100644
index 0000000..f75721b
--- /dev/null
+++ b/documents/markdown/pandoc-md/3675.md
@@ -0,0 +1,15 @@
+````
+% pandoc -t rst
+```python
+print("hello")
+```
+> block quote
+^D
+.. code:: python
+
+ print("hello")
+
+..
+
+ block quote
+````
diff --git a/documents/markdown/pandoc-md/3681.md b/documents/markdown/pandoc-md/3681.md
new file mode 100644
index 0000000..dc6b908
--- /dev/null
+++ b/documents/markdown/pandoc-md/3681.md
@@ -0,0 +1,69 @@
+```
+% pandoc -f latex -t native
+\newcommand{\cicd}{CI/CD\xspace}
+
+Software developers create \cicd pipelines to… Following issue can be resolved by \cicd:
+^D
+[ Para
+ [ Str "Software"
+ , Space
+ , Str "developers"
+ , Space
+ , Str "create"
+ , Space
+ , Str "CI/CD"
+ , Space
+ , Str "pipelines"
+ , Space
+ , Str "to\8230"
+ , Space
+ , Str "Following"
+ , Space
+ , Str "issue"
+ , Space
+ , Str "can"
+ , Space
+ , Str "be"
+ , Space
+ , Str "resolved"
+ , Space
+ , Str "by"
+ , Space
+ , Str "CI/CD:"
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\newcommand{\cicd}{CI/CD\xspace}
+
+\cicd\footnote{\url{https://en.wikipedia.org/wiki/CI/CD}} is awesome.
+^D
+[ Para
+ [ Str "CI/CD"
+ , Note
+ [ Para
+ [ Link
+ ( "" , [ "uri" ] , [] )
+ [ Str "https://en.wikipedia.org/wiki/CI/CD" ]
+ ( "https://en.wikipedia.org/wiki/CI/CD" , "" )
+ ]
+ ]
+ , Space
+ , Str "is"
+ , Space
+ , Str "awesome."
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\newcommand{\cicd}{CI/CD\xspace}
+\newcommand{\pipeline}{pipeline\xspace}
+
+\cicd\pipeline.
+^D
+[ Para [ Str "CI/CD" , Space , Str "pipeline." ] ]
+```
diff --git a/documents/markdown/pandoc-md/3701.md b/documents/markdown/pandoc-md/3701.md
new file mode 100644
index 0000000..bd70fae
--- /dev/null
+++ b/documents/markdown/pandoc-md/3701.md
@@ -0,0 +1,61 @@
+```
+% pandoc --reference-location=block -t markdown --reference-links --wrap=preserve
+[a](u)
+
+[a](u)
+
+[a](u2)
+[A](u)
+[a](u){.foo}
+
+[a](u3)
+^D
+[a]
+
+ [a]: u
+
+[a]
+
+ [a]: u
+
+[a][1]
+[A][]
+[a][2]
+
+ [1]: u2
+ [A]: u
+ [2]: u {.foo}
+
+[a][3]
+
+ [3]: u3
+```
+
+```
+% pandoc
+[a]
+
+ [a]: u
+
+[a]
+
+ [a]: u
+
+[a][1]
+[A][]
+[a][2]
+
+ [1]: u2
+ [A]: u
+ [2]: u {.foo}
+
+[a][3]
+
+ [3]: u3
+^D
+<p><a href="u">a</a></p>
+<p><a href="u">a</a></p>
+<p><a href="u2">a</a> <a href="u">A</a> <a href="u"
+class="foo">a</a></p>
+<p><a href="u3">a</a></p>
+```
diff --git a/documents/markdown/pandoc-md/3706.md b/documents/markdown/pandoc-md/3706.md
new file mode 100644
index 0000000..025de13
--- /dev/null
+++ b/documents/markdown/pandoc-md/3706.md
@@ -0,0 +1,112 @@
+Results marker can be hidden in block attributes (#3706)
+
+```
+% pandoc -f org -t native
+#+begin_src r :exports results :colnames yes
+ data.frame(Id = 1:3, Desc = rep("La",3))
+#+end_src
+
+#+caption: Lalelu.
+#+label: tab
+#+RESULTS:
+| Id | Desc |
+|----+------|
+| 1 | La |
+| 2 | La |
+| 3 | La |
+^D
+[ Table
+ ( "tab" , [] , [] )
+ (Caption Nothing [ Plain [ Str "Lalelu." ] ])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Id" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Desc" ] ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "La" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "La" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "3" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "La" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
+
+```
+% pandoc -f org -t native
+#+begin_src R :exports none :colnames yes
+ data.frame(Id = 1:2, Desc = rep("La",2))
+#+end_src
+
+#+caption: Lalelu.
+#+label: tab
+#+RESULTS:
+| Id | Desc |
+|----+------|
+| 1 | La |
+| 2 | La |
+^D
+[]
+```
diff --git a/documents/markdown/pandoc-md/3708.md b/documents/markdown/pandoc-md/3708.md
new file mode 100644
index 0000000..e456617
--- /dev/null
+++ b/documents/markdown/pandoc-md/3708.md
@@ -0,0 +1,53 @@
+```
+% pandoc -f latex -t native
+\begin{tabular}{cc}
+ A & B\&1 \\
+ C & D
+\end{tabular}
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignCenter , ColWidthDefault )
+ , ( AlignCenter , ColWidthDefault )
+ ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "A" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "B&1" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "C" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "D" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
diff --git a/documents/markdown/pandoc-md/3715.md b/documents/markdown/pandoc-md/3715.md
new file mode 100644
index 0000000..9d74779
--- /dev/null
+++ b/documents/markdown/pandoc-md/3715.md
@@ -0,0 +1,15 @@
+```
+% pandoc -t markdown -f html --wrap=preserve
+x<em></em>x
+y<strong></strong>y
+z<sup></sup>z
+w<sub></sub>w
+q<s></s>q
+^D
+xx
+yy
+zz
+ww
+qq
+```
+
diff --git a/documents/markdown/pandoc-md/3716.md b/documents/markdown/pandoc-md/3716.md
new file mode 100644
index 0000000..81e4a95
--- /dev/null
+++ b/documents/markdown/pandoc-md/3716.md
@@ -0,0 +1,6 @@
+```
+% pandoc
+<http://example.com>{.foo}
+^D
+<p><a href="http://example.com" class="foo">http://example.com</a></p>
+```
diff --git a/documents/markdown/pandoc-md/3730.md b/documents/markdown/pandoc-md/3730.md
new file mode 100644
index 0000000..fbc06cb
--- /dev/null
+++ b/documents/markdown/pandoc-md/3730.md
@@ -0,0 +1,21 @@
+````
+% pandoc
+nice line\
+```
+code
+```
+^D
+<p>nice line<br />
+</p>
+<pre><code>code</code></pre>
+````
+
+```
+% pandoc
+# hi\
+there
+^D
+<h1 id="hi">hi<br />
+</h1>
+<p>there</p>
+```
diff --git a/documents/markdown/pandoc-md/3733.md b/documents/markdown/pandoc-md/3733.md
new file mode 100644
index 0000000..0b24d0c
--- /dev/null
+++ b/documents/markdown/pandoc-md/3733.md
@@ -0,0 +1,13 @@
+````
+% pandoc -t native
+- Item1
+- Item2
+```yaml
+some: code
+```
+^D
+[ BulletList
+ [ [ Plain [ Str "Item1" ] ] , [ Plain [ Str "Item2" ] ] ]
+, CodeBlock ( "" , [ "yaml" ] , [] ) "some: code"
+]
+````
diff --git a/documents/markdown/pandoc-md/3734.md b/documents/markdown/pandoc-md/3734.md
new file mode 100644
index 0000000..832712c
--- /dev/null
+++ b/documents/markdown/pandoc-md/3734.md
@@ -0,0 +1,32 @@
+```
+% pandoc -t markdown_strict+pipe_tables
+| aaaaaaaaaaaa | bbbbb | ccccccccccc |
+|--------------|-------|--------------------------------------------------------------------------|
+| aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc |
+^D
+| aaaaaaaaaaaa | bbbbb | ccccccccccc |
+|------------|-------|------------------------------------------------------|
+| aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc |
+```
+
+```
+% pandoc -t markdown_strict+pipe_tables-raw_html
+| aaaaaaaaaaaa | bbbbb | ccccccccccc |
+|--------------|-------|--------------------------------------------------------------------------|
+| aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc |
+^D
+| aaaaaaaaaaaa | bbbbb | ccccccccccc |
+|------------|-------|------------------------------------------------------|
+| aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc |
+```
+
+```
+% pandoc -t gfm
+| aaaaaaaaaaaa | bbbbb | ccccccccccc |
+|--------------|-------|--------------------------------------------------------------------------|
+| aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc |
+^D
+| aaaaaaaaaaaa | bbbbb | ccccccccccc |
+|----|----|----|
+| aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc |
+```
diff --git a/documents/markdown/pandoc-md/3736.md b/documents/markdown/pandoc-md/3736.md
new file mode 100644
index 0000000..b7d75aa
--- /dev/null
+++ b/documents/markdown/pandoc-md/3736.md
@@ -0,0 +1,22 @@
+```
+% pandoc --wrap=preserve -f html -t markdown
+<h2>hi
+there</h2>
+^D
+## hi there
+```
+
+```
+% pandoc --wrap=preserve -f html -t markdown
+<h2>hi <em>there
+again</em></h2>
+^D
+## hi *there again*
+```
+
+```
+% pandoc --wrap=preserve -f html -t markdown
+<h2>hi<br>there</h2>
+^D
+## hi there
+```
diff --git a/documents/markdown/pandoc-md/3752.md b/documents/markdown/pandoc-md/3752.md
new file mode 100644
index 0000000..b7b67cc
--- /dev/null
+++ b/documents/markdown/pandoc-md/3752.md
@@ -0,0 +1,66 @@
+```
+% pandoc command/chap1/text.md command/chap2/text.md -f markdown+rebase_relative_paths --verbose -t docx -o - | pandoc -f docx -t plain
+^D
+2> [INFO] Loaded command/chap1/spider.png from command/chap1/spider.png
+2> [INFO] Loaded command/chap2/spider.png from command/chap2/spider.png
+2> [INFO] Loaded command/chap1/../../lalune.jpg from command/chap1/../../lalune.jpg
+Chapter one
+
+A spider: [spider]
+
+Another spider: [another spider]
+
+The moon: [moon]
+
+Link to spider picture.
+
+URL left alone: manual.
+
+Absolute path left alone: absolute.
+
+Link to fragment: chapter two.
+
+Empty path: empty.
+
+Chapter two
+
+A spider: [spider]
+```
+
+```
+% pandoc command/chap1/text.md command/chap2/text.md -f markdown+rebase_relative_paths -t html
+^D
+<h1 id="chapter-one">Chapter one</h1>
+<p>A spider: <img src="command/chap1/spider.png" alt="spider" /></p>
+<p>Another spider: <img src="command/chap2/spider.png"
+alt="another spider" /></p>
+<p>The moon: <img src="command/chap1/../../lalune.jpg" alt="moon" /></p>
+<p>Link to <a href="command/chap1/spider.png">spider picture</a>.</p>
+<p>URL left alone: <a
+href="https://pandoc.org/MANUAL.html">manual</a>.</p>
+<p>Absolute path left alone: <a
+href="/foo/bar/baz.png">absolute</a>.</p>
+<p>Link to fragment: <a href="#chapter-two">chapter two</a>.</p>
+<p>Empty path: <a href="">empty</a>.</p>
+<h1 id="chapter-two">Chapter two</h1>
+<p>A spider: <img src="command/chap2/spider.png" alt="spider" /></p>
+```
+
+```
+% pandoc command/chap1/text.md command/chap2/text.md -f commonmark+rebase_relative_paths -t html
+^D
+<h1>Chapter one</h1>
+<p>A spider: <img src="command/chap1/spider.png" alt="spider" /></p>
+<p>Another spider: <img src="command/chap2/spider.png"
+alt="another spider" /></p>
+<p>The moon: <img src="command/chap1/../../lalune.jpg" alt="moon" /></p>
+<p>Link to <a href="command/chap1/spider.png">spider picture</a>.</p>
+<p>URL left alone: <a
+href="https://pandoc.org/MANUAL.html">manual</a>.</p>
+<p>Absolute path left alone: <a
+href="/foo/bar/baz.png">absolute</a>.</p>
+<p>Link to fragment: <a href="#chapter-two">chapter two</a>.</p>
+<p>Empty path: <a href="">empty</a>.</p>
+<h1>Chapter two</h1>
+<p>A spider: <img src="command/chap2/spider.png" alt="spider" /></p>
+```
diff --git a/documents/markdown/pandoc-md/3755.md b/documents/markdown/pandoc-md/3755.md
new file mode 100644
index 0000000..a6e4731
--- /dev/null
+++ b/documents/markdown/pandoc-md/3755.md
@@ -0,0 +1,49 @@
+```
+% pandoc -t native -s
+---
+title: 'Titel'
+date: '22. Juni 2017'
+---
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "date"
+ , MetaInlines
+ [ Str "22." , Space , Str "Juni" , Space , Str "2017" ]
+ )
+ , ( "title" , MetaInlines [ Str "Titel" ] )
+ ]
+ }
+ []
+```
+
+```
+% pandoc -t native -s
+---
+title: "<div>foo</div>\n"
+date: |
+ 22. Juni 2017
+---
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "date"
+ , MetaBlocks
+ [ OrderedList
+ ( 22 , Decimal , Period )
+ [ [ Plain [ Str "Juni" , Space , Str "2017" ] ] ]
+ ]
+ )
+ , ( "title"
+ , MetaBlocks
+ [ Div ( "" , [] , [] ) [ Plain [ Str "foo" ] ] ]
+ )
+ ]
+ }
+ []
+```
+
diff --git a/documents/markdown/pandoc-md/3771.md b/documents/markdown/pandoc-md/3771.md
new file mode 100644
index 0000000..1d3a75a
--- /dev/null
+++ b/documents/markdown/pandoc-md/3771.md
@@ -0,0 +1,14 @@
+```
+% pandoc -f html -t org
+<div class="Section1">
+ Today is a nice day.
+</div>
+<div id="forecast">
+ Tomorrow will be rainy.
+</div>
+^D
+Today is a nice day.
+
+<<forecast>>
+Tomorrow will be rainy.
+```
diff --git a/documents/markdown/pandoc-md/3773.md b/documents/markdown/pandoc-md/3773.md
new file mode 100644
index 0000000..7ee8a39
--- /dev/null
+++ b/documents/markdown/pandoc-md/3773.md
@@ -0,0 +1,14 @@
+```
+% pandoc -t markdown
+A. \#
+B. \+
+C. \*
+D. o
+E. o or \*
+^D
+A. \#
+B. \+
+C. \*
+D. o
+E. o or \*
+```
diff --git a/documents/markdown/pandoc-md/3779.md b/documents/markdown/pandoc-md/3779.md
new file mode 100644
index 0000000..04111c2
--- /dev/null
+++ b/documents/markdown/pandoc-md/3779.md
@@ -0,0 +1,57 @@
+```
+% pandoc -f latex -t native
+\newcommand{\fakeitemize}[1]{
+ \begin{itemize}
+ #1
+ \end{itemize}
+}
+\newcommand{\testcmd}[1]{
+ #1
+}
+\fakeitemize{
+ \item Pandoc is 100\% awesome.
+}
+
+\begin{itemize}
+ \item Pandoc is 200\% awesome.
+\end{itemize}
+
+\testcmd{
+ Pandoc is 300\% awesome.
+}
+^D
+[ BulletList
+ [ [ Para
+ [ Str "Pandoc"
+ , Space
+ , Str "is"
+ , Space
+ , Str "100%"
+ , Space
+ , Str "awesome."
+ ]
+ ]
+ ]
+, BulletList
+ [ [ Para
+ [ Str "Pandoc"
+ , Space
+ , Str "is"
+ , Space
+ , Str "200%"
+ , Space
+ , Str "awesome."
+ ]
+ ]
+ ]
+, Para
+ [ Str "Pandoc"
+ , Space
+ , Str "is"
+ , Space
+ , Str "300%"
+ , Space
+ , Str "awesome."
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/3792.md b/documents/markdown/pandoc-md/3792.md
new file mode 100644
index 0000000..eb109b9
--- /dev/null
+++ b/documents/markdown/pandoc-md/3792.md
@@ -0,0 +1,13 @@
+Make sure metadata values are treated as strings,
+and properly escaped.
+
+```
+% pandoc -t markdown -s -M title="<this> *that*"
+ok
+^D
+---
+title: \<this\> \*that\*
+---
+
+ok
+```
diff --git a/documents/markdown/pandoc-md/3794.md b/documents/markdown/pandoc-md/3794.md
new file mode 100644
index 0000000..974b7db
--- /dev/null
+++ b/documents/markdown/pandoc-md/3794.md
@@ -0,0 +1,6 @@
+```
+% pandoc -f html -t native
+<div><p>hello</div>
+^D
+[ Div ( "" , [] , [] ) [ Para [ Str "hello" ] ] ]
+```
diff --git a/documents/markdown/pandoc-md/3803.md b/documents/markdown/pandoc-md/3803.md
new file mode 100644
index 0000000..a2e6035
--- /dev/null
+++ b/documents/markdown/pandoc-md/3803.md
@@ -0,0 +1,10 @@
+```
+% pandoc -f markdown+raw_tex -t latex
+\begin{blah*}
+*ok*
+\end{blah*}
+^D
+\begin{blah*}
+*ok*
+\end{blah*}
+```
diff --git a/documents/markdown/pandoc-md/3804.md b/documents/markdown/pandoc-md/3804.md
new file mode 100644
index 0000000..6637b23
--- /dev/null
+++ b/documents/markdown/pandoc-md/3804.md
@@ -0,0 +1,9 @@
+```
+% pandoc -t native
+\titleformat{\chapter}[display]{\normalfont\large\bfseries}{第\thechapter{}章}{20pt}{\Huge}
+^D
+[ RawBlock
+ (Format "tex")
+ "\\titleformat{\\chapter}[display]{\\normalfont\\large\\bfseries}{\31532\\thechapter{}\31456}{20pt}{\\Huge}"
+]
+```
diff --git a/documents/markdown/pandoc-md/3816.md b/documents/markdown/pandoc-md/3816.md
new file mode 100644
index 0000000..3979ea9
--- /dev/null
+++ b/documents/markdown/pandoc-md/3816.md
@@ -0,0 +1,32 @@
+```
+% pandoc --mathjax -t html5 --wrap=preserve
+This is an equation:
+\begin{equation}
+y+2 = 3
+\end{equation}
+
+This is a system of equations:
+\begin{align*}
+x^2+y^2 & = 2 \\
+\sin(y) & = 0.5
+\end{align*}
+
+This is Euler's formula:
+\begin{eqnarray*}
+e^{i\pi} + 1 & = & 0.
+\end{eqnarray*}
+^D
+<p>This is an equation:
+<span class="math display">\[\begin{equation}
+y+2 = 3
+\end{equation}\]</span></p>
+<p>This is a system of equations:
+<span class="math display">\[\begin{align*}
+x^2+y^2 & = 2 \\
+\sin(y) & = 0.5
+\end{align*}\]</span></p>
+<p>This is Euler’s formula:
+<span class="math display">\[\begin{eqnarray*}
+e^{i\pi} + 1 & = & 0.
+\end{eqnarray*}\]</span></p>
+```
diff --git a/documents/markdown/pandoc-md/3824.md b/documents/markdown/pandoc-md/3824.md
new file mode 100644
index 0000000..b266c89
--- /dev/null
+++ b/documents/markdown/pandoc-md/3824.md
@@ -0,0 +1,14 @@
+```
+% pandoc -f native -t dokuwiki
+[BulletList
+ [[Para [Str "hi"]
+ ,CodeBlock ("",[],[]) " there"]
+ ,[Para [Str "ok"]]]]
+^D
+ * hi<code>
+ there
+</code>
+
+ * ok
+
+```
diff --git a/documents/markdown/pandoc-md/3840.md b/documents/markdown/pandoc-md/3840.md
new file mode 100644
index 0000000..a0dd314
--- /dev/null
+++ b/documents/markdown/pandoc-md/3840.md
@@ -0,0 +1,16 @@
+```
+% pandoc
+[@Alhazen1572-qk, V.9]: "competentius est"
+^D
+<p><span class="citation" data-cites="Alhazen1572-qk">[@Alhazen1572-qk,
+V.9]</span>: “competentius est”</p>
+```
+
+```
+% pandoc -f markdown-citations
+[@Alhazen1572-qk, V.9]: "competentius est"
+
+[@Alhazen1572-qk, V.9]
+^D
+<p><a href="" title="competentius est">@Alhazen1572-qk, V.9</a></p>
+```
diff --git a/documents/markdown/pandoc-md/3853.md b/documents/markdown/pandoc-md/3853.md
new file mode 100644
index 0000000..caf21ed
--- /dev/null
+++ b/documents/markdown/pandoc-md/3853.md
@@ -0,0 +1,28 @@
+```
+% pandoc -f latex -t native
+\newtoggle{ebook}
+\toggletrue{ebook}
+\iftoggle{ebook}{
+ebook
+}%
+{
+not ebook
+}%
+more
+
+\togglefalse{ebook}
+\iftoggle{ebook}{%
+ebook
+}{
+not ebook
+}%
+more
+
+hello \iftoggle{ebook}{ebook}{noebook}
+^D
+[ Para [ Str "ebook" , SoftBreak , Str "more" ]
+, Para
+ [ Str "not" , Space , Str "ebook" , SoftBreak , Str "more" ]
+, Para [ Str "hello" , Space , Str "noebook" ]
+]
+```
diff --git a/documents/markdown/pandoc-md/3916.md b/documents/markdown/pandoc-md/3916.md
new file mode 100644
index 0000000..8775ae7
--- /dev/null
+++ b/documents/markdown/pandoc-md/3916.md
@@ -0,0 +1,15 @@
+```
+% pandoc -f textile -t native
+# text text
+<pre>blabla</pre>
+# more
+^D
+[ OrderedList
+ ( 1 , DefaultStyle , DefaultDelim )
+ [ [ Plain [ Str "text" , Space , Str "text" ]
+ , CodeBlock ( "" , [] , [] ) "blabla"
+ ]
+ , [ Plain [ Str "more" ] ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/3937.md b/documents/markdown/pandoc-md/3937.md
new file mode 100644
index 0000000..2f32cd1
--- /dev/null
+++ b/documents/markdown/pandoc-md/3937.md
@@ -0,0 +1,13 @@
+```
+% pandoc -t rst
+# My Great Section {#mysection}
+# Other section
+^D
+.. _mysection:
+
+My Great Section
+================
+
+Other section
+=============
+```
diff --git a/documents/markdown/pandoc-md/3947.md b/documents/markdown/pandoc-md/3947.md
new file mode 100644
index 0000000..68118a9
--- /dev/null
+++ b/documents/markdown/pandoc-md/3947.md
@@ -0,0 +1,13 @@
+```
+% pandoc -t native
+\newpage
+
+ Code block
+
+ Another Code block
+^D
+[ RawBlock (Format "tex") "\\newpage"
+, CodeBlock
+ ( "" , [] , [] ) "Code block\n\nAnother Code block"
+]
+```
diff --git a/documents/markdown/pandoc-md/3958.md b/documents/markdown/pandoc-md/3958.md
new file mode 100644
index 0000000..67f550f
--- /dev/null
+++ b/documents/markdown/pandoc-md/3958.md
@@ -0,0 +1,20 @@
+```
+% pandoc -f latex -t native
+\texttt{"hi"}
+^D
+[ Para [ Code ( "" , [] , [] ) "\"hi\"" ] ]
+```
+
+```
+% pandoc -f latex -t native
+\texttt{``hi''}
+^D
+[ Para [ Code ( "" , [] , [] ) "\8216\8216hi\8217\8217" ] ]
+```
+
+```
+% pandoc -f latex -t native
+\texttt{`hi'}
+^D
+[ Para [ Code ( "" , [] , [] ) "\8216hi\8217" ] ]
+```
diff --git a/documents/markdown/pandoc-md/3968.md b/documents/markdown/pandoc-md/3968.md
new file mode 100644
index 0000000..dfa0e89
--- /dev/null
+++ b/documents/markdown/pandoc-md/3968.md
@@ -0,0 +1,14 @@
+```
+% pandoc --top-level-division=chapter -t context
+# Chapter
+
+## Section
+^D
+\startchapter[title={Chapter},reference={chapter}]
+
+\startsection[title={Section},reference={section}]
+
+\stopsection
+
+\stopchapter
+```
diff --git a/documents/markdown/pandoc-md/3971.md b/documents/markdown/pandoc-md/3971.md
new file mode 100644
index 0000000..b051cae
--- /dev/null
+++ b/documents/markdown/pandoc-md/3971.md
@@ -0,0 +1,9 @@
+```
+% pandoc -f latex -t native
+\documentclass{article}
+\include{command/3971b}
+\code{f}
+\end{document}
+^D
+[ Para [ Code ( "" , [] , [] ) "f" ] ]
+```
diff --git a/documents/markdown/pandoc-md/3983.md b/documents/markdown/pandoc-md/3983.md
new file mode 100644
index 0000000..82c1dee
--- /dev/null
+++ b/documents/markdown/pandoc-md/3983.md
@@ -0,0 +1,31 @@
+```
+% pandoc -f latex+raw_tex -t native
+\def\filename@area{foo:bar:baz}
+\makeatletter
+\graphicspath\expandafter{\expandafter{\filename@area}}%
+\makeatother
+^D
+[ RawBlock (Format "latex") "\\makeatletter"
+, RawBlock (Format "latex") "\\makeatother"
+]
+```
+
+```
+% pandoc -f latex+raw_tex -t native
+\makeatletter
+ \newcommand\urlfootnote@[1]{\footnote{\url@{#1}}}
+ \DeclareRobustCommand{\urlfootnote}{\hyper@normalise\urlfootnote@}
+\makeatother
+^D
+[ RawBlock (Format "latex") "\\makeatletter"
+, RawBlock (Format "latex") "\\makeatother"
+]
+```
+
+```
+% pandoc -f latex+raw_tex -t native
+\def\foo{bar}
+\expandafter\bam\foo
+^D
+[ RawBlock (Format "latex") "\\bambar" ]
+```
diff --git a/documents/markdown/pandoc-md/3989.md b/documents/markdown/pandoc-md/3989.md
new file mode 100644
index 0000000..647aa35
--- /dev/null
+++ b/documents/markdown/pandoc-md/3989.md
@@ -0,0 +1,22 @@
+```
+% pandoc -f markdown -t native
+<span title="1st line of text <br> 2nd line of text">foo</span>
+ <span title="1st line of text <br> 2nd line of text">foo</span>
+^D
+[ Para
+ [ Span
+ ( ""
+ , []
+ , [ ( "title" , "1st line of text <br> 2nd line of text" ) ]
+ )
+ [ Str "foo" ]
+ , SoftBreak
+ , Span
+ ( ""
+ , []
+ , [ ( "title" , "1st line of text <br> 2nd line of text" ) ]
+ )
+ [ Str "foo" ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/4007.md b/documents/markdown/pandoc-md/4007.md
new file mode 100644
index 0000000..974a88a
--- /dev/null
+++ b/documents/markdown/pandoc-md/4007.md
@@ -0,0 +1,23 @@
+```
+% pandoc -f latex -t native
+\newcommand\arrow\to
+$a\arrow b$
+^D
+[ Para [ Math InlineMath "a\\to b" ] ]
+```
+
+```
+% pandoc -f latex -t native
+\newcommand\pfeil[1]{\to #1}
+$a\pfeil b$
+^D
+[ Para [ Math InlineMath "a\\to b" ] ]
+```
+
+```
+% pandoc -f latex -t native
+\newcommand\fleche{\to}
+$a\fleche b$
+^D
+[ Para [ Math InlineMath "a\\to b" ] ]
+```
diff --git a/documents/markdown/pandoc-md/4012.md b/documents/markdown/pandoc-md/4012.md
new file mode 100644
index 0000000..26e971d
--- /dev/null
+++ b/documents/markdown/pandoc-md/4012.md
@@ -0,0 +1,9 @@
+```
+% pandoc -f markdown-implicit_figures
+![image]
+
+[image]: http://example.com/image.jpg {height=35mm}
+^D
+<p><img src="http://example.com/image.jpg" style="height:35mm"
+alt="image" /></p>
+```
diff --git a/documents/markdown/pandoc-md/4016.md b/documents/markdown/pandoc-md/4016.md
new file mode 100644
index 0000000..3a7f03c
--- /dev/null
+++ b/documents/markdown/pandoc-md/4016.md
@@ -0,0 +1,42 @@
+```
+% pandoc -t beamer
+# Level 2 blocks
+
+<div class="columns">
+<div class="column" width="40%">
+## Block one
+- Item
+</div>
+<div class="column" width="60%">
+## Block two
+- Item
+</div>
+</div>
+^D
+\begin{frame}{Level 2 blocks}
+\protect\phantomsection\label{level-2-blocks}
+\begin{columns}[T]
+\begin{column}{0.4\linewidth}
+\begin{block}{Block one}
+\protect\phantomsection\label{block-one}
+\begin{itemize}
+\tightlist
+\item
+ Item
+\end{itemize}
+\end{block}
+\end{column}
+
+\begin{column}{0.6\linewidth}
+\begin{block}{Block two}
+\protect\phantomsection\label{block-two}
+\begin{itemize}
+\tightlist
+\item
+ Item
+\end{itemize}
+\end{block}
+\end{column}
+\end{columns}
+\end{frame}
+```
diff --git a/documents/markdown/pandoc-md/4019.md b/documents/markdown/pandoc-md/4019.md
new file mode 100644
index 0000000..641905b
--- /dev/null
+++ b/documents/markdown/pandoc-md/4019.md
@@ -0,0 +1,8 @@
+```
+% pandoc --wrap=preserve
+This <!-- x > 0 --> works!
+This <!-- x > 0 --> fails?
+^D
+<p>This <!-- x > 0 --> works!
+This <!-- x > 0 --> fails?</p>
+```
diff --git a/documents/markdown/pandoc-md/4054.md b/documents/markdown/pandoc-md/4054.md
new file mode 100644
index 0000000..81c6e40
--- /dev/null
+++ b/documents/markdown/pandoc-md/4054.md
@@ -0,0 +1,21 @@
+```
+% pandoc -t native -s -M title=New
+% Old
+^D
+Pandoc
+ Meta
+ { unMeta = fromList [ ( "title" , MetaString "New" ) ] }
+ []
+```
+
+```
+% pandoc -t native -s -M foo=1 -M foo=2
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "foo" , MetaList [ MetaString "1" , MetaString "2" ] ) ]
+ }
+ []
+```
diff --git a/documents/markdown/pandoc-md/4056.md b/documents/markdown/pandoc-md/4056.md
new file mode 100644
index 0000000..c270d25
--- /dev/null
+++ b/documents/markdown/pandoc-md/4056.md
@@ -0,0 +1,57 @@
+```
+% pandoc -f markdown -t native
+\parbox[t]{0.4\textwidth}{
+\begin{shaded}
+\end{shaded}
+}
+^D
+[ RawBlock
+ (Format "tex")
+ "\\parbox[t]{0.4\\textwidth}{\n\\begin{shaded}\n\\end{shaded}\n}"
+]
+```
+
+```
+% pandoc -f latex -t native
+\begin{tabular}{l*{2}{r}}
+Blah & Foo & Bar \\
+\end{tabular}
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignLeft , ColWidthDefault )
+ , ( AlignRight , ColWidthDefault )
+ , ( AlignRight , ColWidthDefault )
+ ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Blah" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Foo" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Bar" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
diff --git a/documents/markdown/pandoc-md/4061.md b/documents/markdown/pandoc-md/4061.md
new file mode 100644
index 0000000..e850c5e
--- /dev/null
+++ b/documents/markdown/pandoc-md/4061.md
@@ -0,0 +1,14 @@
+```
+% pandoc -t markdown-simple_tables-multiline_tables-pipe_tables
++-----------------------------------+
+| Text [^1] |
++-----------------------------------+
+
+[^1]: Footnote.
+^D
++-----------------------------------+
+| Text [^1] |
++-----------------------------------+
+
+[^1]: Footnote.
+```
diff --git a/documents/markdown/pandoc-md/4062.md b/documents/markdown/pandoc-md/4062.md
new file mode 100644
index 0000000..2e212f8
--- /dev/null
+++ b/documents/markdown/pandoc-md/4062.md
@@ -0,0 +1,6 @@
+```
+% pandoc -t latex
+Sentence blah.\footnote[][-.5in]{I'm a footnote}
+^D
+Sentence blah.\footnote[][-.5in]{I'm a footnote}
+```
diff --git a/documents/markdown/pandoc-md/4063.md b/documents/markdown/pandoc-md/4063.md
new file mode 100644
index 0000000..29aeae8
--- /dev/null
+++ b/documents/markdown/pandoc-md/4063.md
@@ -0,0 +1,44 @@
+```
+% pandoc -f html -t native
+<table>
+<colgroup>
+ <col width="30%" />
+ <col width="*" />
+</colgroup>
+<tr>
+ <td>1</td>
+ <td>2</td>
+</tr>
+</table>
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidth 0.3 )
+ , ( AlignDefault , ColWidth 0.7 )
+ ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "2" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
diff --git a/documents/markdown/pandoc-md/4068.md b/documents/markdown/pandoc-md/4068.md
new file mode 100644
index 0000000..83527a6
--- /dev/null
+++ b/documents/markdown/pandoc-md/4068.md
@@ -0,0 +1,33 @@
+```
+% pandoc -f mediawiki -t native
+[https://domain.com/script.php?a=1&b=2&c=&d=4 open productname bugs]
+
+[http://domain.com?a=. open productname bugs]
+^D
+[ Para
+ [ Link
+ ( "" , [] , [] )
+ [ Str "open"
+ , Space
+ , Str "productname"
+ , Space
+ , Str "bugs"
+ ]
+ ( "https://domain.com/script.php?a=1&b=2&c=&d=4" , "" )
+ ]
+, Para
+ [ Str "["
+ , Link
+ ( "" , [] , [] )
+ [ Str "http://domain.com?a=" ]
+ ( "http://domain.com?a=" , "" )
+ , Str "."
+ , Space
+ , Str "open"
+ , Space
+ , Str "productname"
+ , Space
+ , Str "bugs]"
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/4102.md b/documents/markdown/pandoc-md/4102.md
new file mode 100644
index 0000000..88e2a4d
--- /dev/null
+++ b/documents/markdown/pandoc-md/4102.md
@@ -0,0 +1,11 @@
+SmallCaps spans can have additional attributes.
+```
+% pandoc -t latex -f markdown
+[Populus]{.smallcaps lang=la}
+
+[Romanus]{.smallcaps}
+^D
+\foreignlanguage{latin}{\textsc{Populus}}
+
+\textsc{Romanus}
+```
diff --git a/documents/markdown/pandoc-md/4113.md b/documents/markdown/pandoc-md/4113.md
new file mode 100644
index 0000000..41fbcaf
--- /dev/null
+++ b/documents/markdown/pandoc-md/4113.md
@@ -0,0 +1,12 @@
+```
+% pandoc -t gfm
+::::{.bug}
+I am a [bug]{#bug}.
+::::
+^D
+<div class="bug">
+
+I am a <span id="bug">bug</span>.
+
+</div>
+```
diff --git a/documents/markdown/pandoc-md/4119.md b/documents/markdown/pandoc-md/4119.md
new file mode 100644
index 0000000..fcbf793
--- /dev/null
+++ b/documents/markdown/pandoc-md/4119.md
@@ -0,0 +1,63 @@
+```
+% pandoc -t native
+| col1 | col2 |
+| ---- | ---- |
+| 1 | 2 |
+
+::: {.notes} :::
+not a caption!
+::::::::::::::::
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "col1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "col2" ] ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "2" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+, Div
+ ( "" , [ "notes" ] , [] )
+ [ Para
+ [ Str "not" , Space , Str "a" , Space , Str "caption!" ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/4134.md b/documents/markdown/pandoc-md/4134.md
new file mode 100644
index 0000000..195d851
--- /dev/null
+++ b/documents/markdown/pandoc-md/4134.md
@@ -0,0 +1,24 @@
+```
+% pandoc -f latex -t native
+Hello.\
+world.
+^D
+[ Para [ Str "Hello.\160world." ] ]
+```
+
+```
+% pandoc -f latex -t native
+Hello.\
+ world.
+^D
+[ Para [ Str "Hello.\160world." ] ]
+```
+
+```
+% pandoc -f latex -t native
+Hello.\
+
+World.
+^D
+[ Para [ Str "Hello.\160" ] , Para [ Str "World." ] ]
+```
diff --git a/documents/markdown/pandoc-md/4159.md b/documents/markdown/pandoc-md/4159.md
new file mode 100644
index 0000000..bea4632
--- /dev/null
+++ b/documents/markdown/pandoc-md/4159.md
@@ -0,0 +1,9 @@
+```
+% pandoc -f markdown -t native
+\newcommand{\gen}{a\ Gen\ b}
+abc
+^D
+[ RawBlock (Format "tex") "\\newcommand{\\gen}{a\\ Gen\\ b}"
+, Para [ Str "abc" ]
+]
+```
diff --git a/documents/markdown/pandoc-md/4162.md b/documents/markdown/pandoc-md/4162.md
new file mode 100644
index 0000000..85b48db
--- /dev/null
+++ b/documents/markdown/pandoc-md/4162.md
@@ -0,0 +1,7 @@
+```
+% pandoc -f html -t native
+<div class="line-block">hi<br /><br>
+ there</div>
+^D
+[ LineBlock [ [ Str "hi" ] , [] , [ Str "\160there" ] ] ]
+```
diff --git a/documents/markdown/pandoc-md/4164.md b/documents/markdown/pandoc-md/4164.md
new file mode 100644
index 0000000..e5cf5d9
--- /dev/null
+++ b/documents/markdown/pandoc-md/4164.md
@@ -0,0 +1,29 @@
+```
+% pandoc -f opml -t markdown
+<?xml version="1.0"?> <opml version="1.0"> <head> <title> test </title> </head> <body> <outline text="test"> <outline text="try" _note="Here is inline html:

<div> 
<balise>
bla bla
</div>"/> </outline> </body> </opml>
+^D
+# test
+
+## try
+
+Here is inline html:
+
+::: {}
+`<balise>`{=html} bla bla
+:::
+
+```
+
+```
+% pandoc -f opml-raw_html-native_divs -t markdown
+<?xml version="1.0"?> <opml version="1.0"> <head> <title> test </title> </head> <body> <outline text="test"> <outline text="try" _note="Here is inline html:

<div> 
<balise>
bla bla
</div>"/> </outline> </body> </opml>
+^D
+# test
+
+## try
+
+Here is inline html:
+
+\<div\> \<balise\> bla bla \</div\>
+
+```
diff --git a/documents/markdown/pandoc-md/4171.md b/documents/markdown/pandoc-md/4171.md
new file mode 100644
index 0000000..42b4576
--- /dev/null
+++ b/documents/markdown/pandoc-md/4171.md
@@ -0,0 +1,34 @@
+```
+% pandoc -f org -t org
+Aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa [fn:1] a
+
+[fn:1] b
+^D
+Aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa [fn:1]
+a
+
+[fn:1] b
+```
+
+
+```
+% pandoc -f org -t org
+Aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ [fn:1] a
+
+[fn:1] b
+^D
+Aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa [fn:1]
+a
+
+[fn:1] b
+```
+
+Similar bug: "-" should not be wrapped:
+```
+% pandoc -f org -t org
+aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa - abc
+^D
+aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa -
+abc
+```
diff --git a/documents/markdown/pandoc-md/4172.md b/documents/markdown/pandoc-md/4172.md
new file mode 100644
index 0000000..6b497a8
--- /dev/null
+++ b/documents/markdown/pandoc-md/4172.md
@@ -0,0 +1,29 @@
+Test that text wrapping does not move note reference [1] to the beginning of the line,
+where it would become a note.
+```
+% pandoc -f muse -t muse
+Aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa [1] a
+
+[1] b
+^D
+Aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa [1]
+a
+
+[1] b
+
+```
+
+SoftBreak test:
+```
+% pandoc -f muse -t muse
+Aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ [1] a
+
+[1] b
+^D
+Aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa [1]
+a
+
+[1] b
+
+```
diff --git a/documents/markdown/pandoc-md/4183.md b/documents/markdown/pandoc-md/4183.md
new file mode 100644
index 0000000..e844f6a
--- /dev/null
+++ b/documents/markdown/pandoc-md/4183.md
@@ -0,0 +1,49 @@
+```
+% pandoc -f html -t native
+<figure>
+ <img src="foo" alt="bar">
+</figure>
+^D
+[ Figure
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ Plain
+ [ Image ( "" , [] , [] ) [ Str "bar" ] ( "foo" , "" ) ]
+ ]
+]
+```
+
+```
+% pandoc -f html -t native
+<figure>
+ <img src="foo" alt="bar">
+ <figcaption>
+ <div>
+ baz
+ </div>
+ </figcaption>
+</figure>
+^D
+[ Figure
+ ( "" , [] , [] )
+ (Caption
+ Nothing [ Div ( "" , [] , [] ) [ Plain [ Str "baz" ] ] ])
+ [ Plain
+ [ Image ( "" , [] , [] ) [ Str "bar" ] ( "foo" , "" ) ]
+ ]
+]
+```
+
+```
+% pandoc -f html -t native
+<figure>
+ <img src="foo">
+ <figcaption><p><em>baz</em></p></figcaption>
+</figure>
+^D
+[ Figure
+ ( "" , [] , [] )
+ (Caption Nothing [ Para [ Emph [ Str "baz" ] ] ])
+ [ Plain [ Image ( "" , [] , [] ) [] ( "foo" , "" ) ] ]
+]
+```
diff --git a/documents/markdown/pandoc-md/4186.md b/documents/markdown/pandoc-md/4186.md
new file mode 100644
index 0000000..cf7edfd
--- /dev/null
+++ b/documents/markdown/pandoc-md/4186.md
@@ -0,0 +1,64 @@
+```
+% pandoc -f org -t native
+#+begin_example -i
+ This should retain the four leading spaces
+#+end_example
+^D
+[ CodeBlock
+ ( "" , [] , [] )
+ " This should retain the four leading spaces\n"
+]
+```
+
+```
+% pandoc -f org -t html
+- depth 1
+ #+name: bob
+ #+begin_example -i
+ Vertical alignment is four spaces beyond the appearance of the word "depth".
+ #+end_example
+ - depth 2
+ #+begin_example
+ Vertically aligned with the second appearance of the word "depth".
+ #+end_example
+ #+begin_example -i
+ Vertical alignment is four spaces beyond the second
+ appearance of the word "depth".
+ The "begin" portion is a component of
+ this deeper list element, so that guarantees
+ that the entire block must be a component of the
+ inner list element.
+ #+end_example
+ Still inside the inner list element
+ #+name: carrie
+ #+begin_example
+ This belongs to the outer list element, and is aligned accordingly, since the NAME attribute is not indented deeply enough. It is not enough for the BEGIN alone to be aligned deeply if the block is meant to have a NAME.
+ #+end_example
+ Still in the shallower list element since the preceding example
+ block forced the deeper list element to terminate.
+Outside all lists.
+^D
+<ul>
+<li><p>depth 1</p>
+<pre id="bob"><code> Vertical alignment is four spaces beyond the appearance of the word "depth".
+</code></pre>
+<ul>
+<li><p>depth 2</p>
+<pre><code>Vertically aligned with the second appearance of the word "depth".
+</code></pre>
+<pre><code> Vertical alignment is four spaces beyond the second
+ appearance of the word "depth".
+ The "begin" portion is a component of
+ this deeper list element, so that guarantees
+ that the entire block must be a component of the
+ inner list element.
+</code></pre>
+<p>Still inside the inner list element</p></li>
+</ul>
+<pre id="carrie"><code>This belongs to the outer list element, and is aligned accordingly, since the NAME attribute is not indented deeply enough. It is not enough for the BEGIN alone to be aligned deeply if the block is meant to have a NAME.
+</code></pre>
+<p>Still in the shallower list element since the preceding example block
+forced the deeper list element to terminate.</p></li>
+</ul>
+<p>Outside all lists.</p>
+```
diff --git a/documents/markdown/pandoc-md/4193.md b/documents/markdown/pandoc-md/4193.md
new file mode 100644
index 0000000..67ca5a4
--- /dev/null
+++ b/documents/markdown/pandoc-md/4193.md
@@ -0,0 +1,10 @@
+```
+% pandoc -f rst -t native
+-
+ a
+- b
+^D
+[ BulletList
+ [ [ Plain [ Str "a" ] ] , [ Plain [ Str "b" ] ] ]
+]
+```
diff --git a/documents/markdown/pandoc-md/4199.md b/documents/markdown/pandoc-md/4199.md
new file mode 100644
index 0000000..36385bc
--- /dev/null
+++ b/documents/markdown/pandoc-md/4199.md
@@ -0,0 +1,9 @@
+```
+% pandoc -f latex -t native
+\foreignlanguage{ngerman}{foo}
+^D
+[ Para
+ [ Span ( "" , [] , [ ( "lang" , "de-DE" ) ] ) [ Str "foo" ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/4208.md b/documents/markdown/pandoc-md/4208.md
new file mode 100644
index 0000000..9bc519d
--- /dev/null
+++ b/documents/markdown/pandoc-md/4208.md
@@ -0,0 +1,18 @@
+```
+% pandoc -t latex
+What is a _piffle_? Mark the correct answer(s):
+
+\begin{TAB}(@)[6pt]{|l|c|}{|c|c|c|}
+(a) a subnormal woffle & $\Box$ \\
+(b) an infinite-dimensional baffle & $\Box$ \\
+(c) an inverted first-order triffle & $\Box$ \\
+\end{TAB}
+^D
+What is a \emph{piffle}? Mark the correct answer(s):
+
+\begin{TAB}(@)[6pt]{|l|c|}{|c|c|c|}
+(a) a subnormal woffle & $\Box$ \\
+(b) an infinite-dimensional baffle & $\Box$ \\
+(c) an inverted first-order triffle & $\Box$ \\
+\end{TAB}
+```
diff --git a/documents/markdown/pandoc-md/4235.md b/documents/markdown/pandoc-md/4235.md
new file mode 100644
index 0000000..6960e51
--- /dev/null
+++ b/documents/markdown/pandoc-md/4235.md
@@ -0,0 +1,15 @@
+```
+% pandoc --id-prefix=foo
+This.^[Has a footnote.]
+^D
+<p>This.<a href="#foofn1" class="footnote-ref" id="foofnref1"
+role="doc-noteref"><sup>1</sup></a></p>
+<section id="foofootnotes" class="footnotes footnotes-end-of-document"
+role="doc-endnotes">
+<hr />
+<ol>
+<li id="foofn1"><p>Has a footnote.<a href="#foofnref1"
+class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+</ol>
+</section>
+```
diff --git a/documents/markdown/pandoc-md/4240.md b/documents/markdown/pandoc-md/4240.md
new file mode 100644
index 0000000..4958543
--- /dev/null
+++ b/documents/markdown/pandoc-md/4240.md
@@ -0,0 +1,44 @@
+```
+% pandoc -f rst -s -t native
+=====
+Title
+=====
+
+--------
+Subtitle
+--------
+
+header1
+=======
+
+header2
+-------
+
+.. _id:
+
+header3
+~~~~~~~
+
+.. _id2:
+.. _id3:
+
+header4
+~~~~~~~
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "subtitle" , MetaInlines [ Str "Subtitle" ] )
+ , ( "title" , MetaInlines [ Str "Title" ] )
+ ]
+ }
+ [ Header 1 ( "header1" , [] , [] ) [ Str "header1" ]
+ , Header 2 ( "header2" , [] , [] ) [ Str "header2" ]
+ , Header 3 ( "id" , [] , [] ) [ Str "header3" ]
+ , Header
+ 3
+ ( "id3" , [] , [] )
+ [ Str "header4" , Span ( "id2" , [] , [] ) [] ]
+ ]
+```
diff --git a/documents/markdown/pandoc-md/4253.md b/documents/markdown/pandoc-md/4253.md
new file mode 100644
index 0000000..2c994a9
--- /dev/null
+++ b/documents/markdown/pandoc-md/4253.md
@@ -0,0 +1,8 @@
+```
+% pandoc -f latex -t native
+\newcommand{\noop}[1]{#1}
+\noop{\newcommand{\foo}[1]{#1}}
+\foo{hi}
+^D
+[ Para [ Str "hi" ] ]
+```
diff --git a/documents/markdown/pandoc-md/4254.md b/documents/markdown/pandoc-md/4254.md
new file mode 100644
index 0000000..e4cc5c6
--- /dev/null
+++ b/documents/markdown/pandoc-md/4254.md
@@ -0,0 +1,12 @@
+```
+% pandoc -f rst -t latex
+.. math::
+
+ x &= y\\
+ y &= z
+^D
+\[\begin{aligned}
+x &= y\\
+y &= z
+\end{aligned}\]
+```
diff --git a/documents/markdown/pandoc-md/4280.md b/documents/markdown/pandoc-md/4280.md
new file mode 100644
index 0000000..343a2ab
--- /dev/null
+++ b/documents/markdown/pandoc-md/4280.md
@@ -0,0 +1,7 @@
+```
+% pandoc -f rst -t native
+Driver
+------
+^D
+[ Header 1 ( "driver" , [] , [] ) [ Str "Driver" ] ]
+```
diff --git a/documents/markdown/pandoc-md/4281.md b/documents/markdown/pandoc-md/4281.md
new file mode 100644
index 0000000..53943e5
--- /dev/null
+++ b/documents/markdown/pandoc-md/4281.md
@@ -0,0 +1,21 @@
+```
+% pandoc -t native
+:::: {.a}
+- ::: {.b}
+ text
+ :::
+ ::: {.c}
+ text
+ :::
+::::
+^D
+[ Div
+ ( "" , [ "a" ] , [] )
+ [ BulletList
+ [ [ Div ( "" , [ "b" ] , [] ) [ Para [ Str "text" ] ]
+ , Div ( "" , [ "c" ] , [] ) [ Para [ Str "text" ] ]
+ ]
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/4284.md b/documents/markdown/pandoc-md/4284.md
new file mode 100644
index 0000000..0308f52
--- /dev/null
+++ b/documents/markdown/pandoc-md/4284.md
@@ -0,0 +1,120 @@
+```
+% pandoc -f org -t native
+#+EXCLUDE_TAGS:apple cat bye dog %
+
+* This should not appear :apple:
+* NOEXPORT should appear if not specified in EXCLUDE_TAGS :noexport:
+* This should not appear :cat:hi:laptop:
+** Children of headers with excluded tags should not appear :xylophone:
+* This should not appear :%:
+^D
+[ Header
+ 1
+ ( "noexport-should-appear-if-not-specified-in-excludetags"
+ , []
+ , []
+ )
+ [ Str "NOEXPORT"
+ , Space
+ , Str "should"
+ , Space
+ , Str "appear"
+ , Space
+ , Str "if"
+ , Space
+ , Str "not"
+ , Space
+ , Str "specified"
+ , Space
+ , Str "in"
+ , Space
+ , Str "EXCLUDE"
+ , Subscript [ Str "TAGS" ]
+ , Space
+ , Span
+ ( "" , [ "tag" ] , [ ( "tag-name" , "noexport" ) ] )
+ [ SmallCaps [ Str "noexport" ] ]
+ ]
+]
+```
+
+```
+% pandoc -f org -t native
+#+EXCLUDE_TAGS:elephant
+* This should not appear :elephant:
+* This should appear :fawn:
+^D
+[ Header
+ 1
+ ( "this-should-appear" , [] , [] )
+ [ Str "This"
+ , Space
+ , Str "should"
+ , Space
+ , Str "appear"
+ , Space
+ , Span
+ ( "" , [ "tag" ] , [ ( "tag-name" , "fawn" ) ] )
+ [ SmallCaps [ Str "fawn" ] ]
+ ]
+]
+```
+
+```
+% pandoc -f org -t native
+#+EXCLUDE_TAGS: giraffe
+#+EXCLUDE_TAGS: hippo
+* This should not appear :giraffe:
+* This should not appear :hippo:
+* This should appear :noexport:
+^D
+[ Header
+ 1
+ ( "this-should-appear" , [] , [] )
+ [ Str "This"
+ , Space
+ , Str "should"
+ , Space
+ , Str "appear"
+ , Space
+ , Span
+ ( "" , [ "tag" ] , [ ( "tag-name" , "noexport" ) ] )
+ [ SmallCaps [ Str "noexport" ] ]
+ ]
+]
+```
+
+```
+% pandoc -f org -t native
+#+EXCLUDE_TAGS:
+* NOEXPORT should appear if not specified in EXCLUDE_TAGS :noexport:
+^D
+[ Header
+ 1
+ ( "noexport-should-appear-if-not-specified-in-excludetags"
+ , []
+ , []
+ )
+ [ Str "NOEXPORT"
+ , Space
+ , Str "should"
+ , Space
+ , Str "appear"
+ , Space
+ , Str "if"
+ , Space
+ , Str "not"
+ , Space
+ , Str "specified"
+ , Space
+ , Str "in"
+ , Space
+ , Str "EXCLUDE"
+ , Subscript [ Str "TAGS" ]
+ , Space
+ , Span
+ ( "" , [ "tag" ] , [ ( "tag-name" , "noexport" ) ] )
+ [ SmallCaps [ Str "noexport" ] ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/4306.md b/documents/markdown/pandoc-md/4306.md
new file mode 100644
index 0000000..dcb90e3
--- /dev/null
+++ b/documents/markdown/pandoc-md/4306.md
@@ -0,0 +1,22 @@
+```
+% pandoc -f latex -t native
+\documentclass{article}
+\usepackage{hyperref}
+\begin{document}
+The file id is \nolinkurl{ESP_123_5235}.
+\end{document}
+^D
+[ Para
+ [ Str "The"
+ , Space
+ , Str "file"
+ , Space
+ , Str "id"
+ , Space
+ , Str "is"
+ , Space
+ , Code ( "" , [] , [] ) "ESP_123_5235"
+ , Str "."
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/4320.md b/documents/markdown/pandoc-md/4320.md
new file mode 100644
index 0000000..68c6f0e
--- /dev/null
+++ b/documents/markdown/pandoc-md/4320.md
@@ -0,0 +1,29 @@
+```
+% pandoc -f native -t rst --wrap=none
+[Table ("",[],[]) (Caption Nothing
+ [])
+ [(AlignDefault,ColWidth 0.3)
+ ,(AlignDefault,ColWidth 0.3)]
+ (TableHead ("",[],[])
+ [Row ("",[],[])
+ [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "one"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "two"]]]])
+ [(TableBody ("",[],[]) (RowHeadColumns 0)
+ []
+ [Row ("",[],[])
+ [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "ports"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [BlockQuote
+ [Para [Strong [Str "thisIsGoingToBeTooLongAnyway"]]]]]])]
+ (TableFoot ("",[],[])
+ [])]
+^D
++--------------------+-------------------------------------+
+| one | two |
++====================+=====================================+
+| ports | **thisIsGoingToBeTooLongAnyway** |
++--------------------+-------------------------------------+
+```
diff --git a/documents/markdown/pandoc-md/4374.md b/documents/markdown/pandoc-md/4374.md
new file mode 100644
index 0000000..4a0990f
--- /dev/null
+++ b/documents/markdown/pandoc-md/4374.md
@@ -0,0 +1,20 @@
+```
+% pandoc -f latex -t native
+\cite{a%
+}
+^D
+[ Para
+ [ Cite
+ [ Citation
+ { citationId = "a"
+ , citationPrefix = []
+ , citationSuffix = []
+ , citationMode = NormalCitation
+ , citationNoteNum = 0
+ , citationHash = 0
+ }
+ ]
+ [ RawInline (Format "latex") "\\cite{a%\n}" ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/4420.md b/documents/markdown/pandoc-md/4420.md
new file mode 100644
index 0000000..11eaabd
--- /dev/null
+++ b/documents/markdown/pandoc-md/4420.md
@@ -0,0 +1,9 @@
+```
+% pandoc -f native -t rst
+[Para [Image ("",["align-right"],[("width","100px")]) [Str "image"] ("foo.png","fig:test")]]
+^D
+|image|
+
+.. |image| image:: foo.png
+ :width: 100px
+```
diff --git a/documents/markdown/pandoc-md/4424.md b/documents/markdown/pandoc-md/4424.md
new file mode 100644
index 0000000..a1b3854
--- /dev/null
+++ b/documents/markdown/pandoc-md/4424.md
@@ -0,0 +1,10 @@
+```
+% pandoc -f latex -t native
+\documentclass{article}
+\usepackage[sortlocale=en_GB]{biblatex}
+\begin{document}
+Test
+\end{document}
+^D
+[ Para [ Str "Test" ] ]
+```
diff --git a/documents/markdown/pandoc-md/4442.md b/documents/markdown/pandoc-md/4442.md
new file mode 100644
index 0000000..4470734
--- /dev/null
+++ b/documents/markdown/pandoc-md/4442.md
@@ -0,0 +1,9 @@
+```
+% pandoc -f markdown -t latex
+\newcommand{\myFruit}{Mango\xspace}
+\myFruit is the king of fruits.
+^D
+\newcommand{\myFruit}{Mango\xspace}
+
+Mango is the king of fruits.
+```
diff --git a/documents/markdown/pandoc-md/4454.md b/documents/markdown/pandoc-md/4454.md
new file mode 100644
index 0000000..aeb62aa
--- /dev/null
+++ b/documents/markdown/pandoc-md/4454.md
@@ -0,0 +1,9 @@
+```
+% pandoc -f rst -t native
+• a
+• b
+^D
+[ BulletList
+ [ [ Plain [ Str "a" ] ] , [ Plain [ Str "b" ] ] ]
+]
+```
diff --git a/documents/markdown/pandoc-md/4465.md b/documents/markdown/pandoc-md/4465.md
new file mode 100644
index 0000000..eaffcf7
--- /dev/null
+++ b/documents/markdown/pandoc-md/4465.md
@@ -0,0 +1,15 @@
+```
+% pandoc -f html -t markdown
+<ol>
+ <li>An ordered list can contain block-level elements ind html, it means that divs are also allowed.</li>
+ <li>Let's see the problem! <div class="example">This is an example.</div></li>
+</ol>
+^D
+1. An ordered list can contain block-level elements ind html, it means
+ that divs are also allowed.
+2. Let\'s see the problem!
+
+ ::: example
+ This is an example.
+ :::
+```
diff --git a/documents/markdown/pandoc-md/4470.md b/documents/markdown/pandoc-md/4470.md
new file mode 100644
index 0000000..f4465fb
--- /dev/null
+++ b/documents/markdown/pandoc-md/4470.md
@@ -0,0 +1,27 @@
+```
+% pandoc -r latex -w plain
+\newcommand{\foo}{123}\renewcommand\foo{456}\foo
+^D
+456
+```
+
+```
+% pandoc -r latex -w plain
+\newcommand\foo{123}\renewcommand\foo{456}\foo
+^D
+456
+```
+
+```
+% pandoc -r latex -w plain
+\newcommand{\foo}{123}\renewcommand{\foo}{456}\foo
+^D
+456
+```
+
+```
+% pandoc -r latex -w plain
+\newcommand\foo{123}\renewcommand{\foo}{456}\foo
+^D
+456
+```
diff --git a/documents/markdown/pandoc-md/4499.md b/documents/markdown/pandoc-md/4499.md
new file mode 100644
index 0000000..5e86d6e
--- /dev/null
+++ b/documents/markdown/pandoc-md/4499.md
@@ -0,0 +1,87 @@
+```
+% pandoc -f latex -t html
+\mbox{abc def} ghi
+^D
+<p>abc def ghi</p>
+```
+
+```
+% pandoc -f latex+raw_tex -t native
+\mbox{abc def}
+^D
+[ Para [ RawInline (Format "latex") "\\mbox{abc def}" ] ]
+```
+
+```
+% pandoc -f latex -t html
+abc \mbox{\textit{def ghi} jkl} mno
+^D
+<p>abc <em>def ghi</em> jkl mno</p>
+```
+
+```
+% pandoc -f latex -t html
+abc \mbox{def \\ ghi} jkl
+^D
+<p>abc defghi jkl</p>
+```
+
+```
+% pandoc -f latex -t html
+abc \mbox{def
+ghi}
+^D
+<p>abc def ghi</p>
+```
+
+```
+% pandoc -f latex -t html
+abc \mbox{def \textit{ghi \\ jkl}
+mno} pqr
+^D
+<p>abc def <em>ghijkl</em> mno pqr</p>
+```
+
+```
+% pandoc -f latex -t html
+\hbox{abc def} ghi
+^D
+<p>abc def ghi</p>
+```
+
+```
+% pandoc -f latex+raw_tex -t native
+\hbox{abc def}
+^D
+[ Para [ RawInline (Format "latex") "\\hbox{abc def}" ] ]
+```
+
+```
+% pandoc -f latex -t html
+abc \hbox{\textit{def ghi} jkl} mno
+^D
+<p>abc <em>def ghi</em> jkl mno</p>
+```
+
+```
+% pandoc -f latex -t html
+abc \hbox{def \\ ghi} jkl
+^D
+<p>abc defghi jkl</p>
+```
+
+```
+% pandoc -f latex -t html
+abc \hbox{def
+ghi}
+^D
+<p>abc def ghi</p>
+```
+
+```
+% pandoc -f latex -t html
+abc \hbox{def \textit{ghi \\ jkl}
+mno} pqr
+^D
+<p>abc def <em>ghijkl</em> mno pqr</p>
+```
diff --git a/documents/markdown/pandoc-md/4513.md b/documents/markdown/pandoc-md/4513.md
new file mode 100644
index 0000000..1f36d19
--- /dev/null
+++ b/documents/markdown/pandoc-md/4513.md
@@ -0,0 +1,32 @@
+```
+% pandoc -f textile -t native
+|_. heading 1 |_. heading 2|
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "heading" , Space , Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "heading" , Space , Str "2" ] ]
+ ]
+ ])
+ [ TableBody ( "" , [] , [] ) (RowHeadColumns 0) [] [] ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
diff --git a/documents/markdown/pandoc-md/4527.md b/documents/markdown/pandoc-md/4527.md
new file mode 100644
index 0000000..c1e0f6a
--- /dev/null
+++ b/documents/markdown/pandoc-md/4527.md
@@ -0,0 +1,23 @@
+This command comes through as regular text:
+```
+% pandoc -f latex+raw_tex -t native
+\maketitle
+^D
+[ RawBlock (Format "latex") "\\maketitle" ]
+```
+
+
+```
+% pandoc -f latex -t native
+\maketitle
+^D
+[]
+```
+
+```
+% pandoc -f latex -t rst
+\maketitle
+Hello.
+^D
+Hello.
+```
diff --git a/documents/markdown/pandoc-md/4528.md b/documents/markdown/pandoc-md/4528.md
new file mode 100644
index 0000000..80be1df
--- /dev/null
+++ b/documents/markdown/pandoc-md/4528.md
@@ -0,0 +1,156 @@
+# Rendering small caps, superscripts and subscripts with and without `raw_html`
+
+## Small caps
+
+```
+% pandoc --wrap=none -f latex -t commonmark-raw_html
+This has \textsc{small caps} in it.
+^D
+This has SMALL CAPS in it.
+```
+
+```
+% pandoc --wrap=none -f latex -t commonmark+raw_html
+This has \textsc{small caps} in it.
+^D
+This has <span class="smallcaps">small caps</span> in it.
+```
+
+```
+% pandoc --wrap=none -f latex -t markdown_strict+raw_html
+This has \textsc{small caps} in it.
+^D
+This has <span class="smallcaps">small caps</span> in it.
+```
+
+## Strikeout
+
+```
+% pandoc --wrap=none -f html -t commonmark-raw_html-strikeout
+This has <s>strikeout</s> in it.
+^D
+This has strikeout in it.
+```
+
+```
+% pandoc --wrap=none -f html -t commonmark+raw_html-strikeout
+This has <s>strikeout</s> in it.
+^D
+This has <s>strikeout</s> in it.
+```
+
+```
+% pandoc --wrap=none -f html -t commonmark-raw_html+strikeout
+This has <s>strikeout</s> in it.
+^D
+This has ~~strikeout~~ in it.
+```
+
+```
+% pandoc --wrap=none -f html -t commonmark+raw_html+strikeout
+This has <s>strikeout</s> in it.
+^D
+This has ~~strikeout~~ in it.
+```
+
+```
+% pandoc --wrap=none -f html -t markdown_strict-raw_html-strikeout
+This has <s>strikeout</s> in it.
+^D
+This has strikeout in it.
+```
+
+```
+% pandoc --wrap=none -f html -t markdown_strict+raw_html-strikeout
+This has <s>strikeout</s> in it.
+^D
+This has <s>strikeout</s> in it.
+```
+
+```
+% pandoc --wrap=none -f html -t markdown_strict-raw_html+strikeout
+This has <s>strikeout</s> in it.
+^D
+This has ~~strikeout~~ in it.
+```
+
+```
+% pandoc --wrap=none -f html -t markdown_strict+raw_html+strikeout
+This has <s>strikeout</s> in it.
+^D
+This has ~~strikeout~~ in it.
+```
+
+## Superscript
+
+```
+% pandoc --wrap=none -f html -t commonmark-raw_html
+This has <sup>superscript</sup> in it and <sup>2 3</sup> again. With emphasis: <sup><em>2</em> 3</sup>. With letters: <sup>foo</sup>. With a span: <sup><span class=foo>2</span></sup>.
+^D
+This has ^(superscript) in it and ² ³ again. With emphasis: ^(*2* 3). With letters: ^(foo). With a span: ².
+```
+
+```
+% pandoc --wrap=none -f html -t commonmark+raw_html
+This has <sup>superscript</sup> in it and <sup>2</sup> again.
+^D
+This has <sup>superscript</sup> in it and <sup>2</sup> again.
+```
+
+```
+% pandoc --wrap=none -f html -t markdown_strict-raw_html-superscript
+This has <sup>superscript</sup> in it and <sup>2</sup> again.
+^D
+This has ^(superscript) in it and ² again.
+```
+
+```
+% pandoc --wrap=none -f html -t markdown_strict+raw_html-superscript
+This has <sup>superscript</sup> in it and <sup>2</sup> again.
+^D
+This has <sup>superscript</sup> in it and <sup>2</sup> again.
+```
+
+```
+% pandoc --wrap=none -f html -t markdown_strict+raw_html+superscript
+This has <sup>superscript</sup> in it and <sup>2</sup> again.
+^D
+This has ^superscript^ in it and ^2^ again.
+```
+
+## Subscript
+
+```
+% pandoc --wrap=none -f html -t commonmark-raw_html
+This has <sub>subscript</sub> in it and <sub>2 3</sub> again. With emphasis: <sub><em>2</em> 3</sub>. With letters: <sub>foo</sub>. With a span: <sub><span class=foo>2</span></sub>.
+^D
+This has _(subscript) in it and ₂ ₃ again. With emphasis: _(*2* 3). With letters: _(foo). With a span: ₂.
+```
+
+```
+% pandoc --wrap=none -f html -t commonmark+raw_html
+This has <sub>subscript</sub> in it and <sub>2</sub> again.
+^D
+This has <sub>subscript</sub> in it and <sub>2</sub> again.
+```
+
+```
+% pandoc --wrap=none -f html -t markdown_strict-raw_html-subscript
+This has <sub>subscript</sub> in it and <sub>2</sub> again.
+^D
+This has _(subscript) in it and ₂ again.
+```
+
+```
+% pandoc --wrap=none -f html -t markdown_strict+raw_html-subscript
+This has <sub>subscript</sub> in it and <sub>2</sub> again.
+^D
+This has <sub>subscript</sub> in it and <sub>2</sub> again.
+```
+
+```
+% pandoc --wrap=none -f html -t markdown_strict+raw_html+subscript
+This has <sub>subscript</sub> in it and <sub>2</sub> again.
+^D
+This has ~subscript~ in it and ~2~ again.
+```
diff --git a/documents/markdown/pandoc-md/4529.md b/documents/markdown/pandoc-md/4529.md
new file mode 100644
index 0000000..4242a65
--- /dev/null
+++ b/documents/markdown/pandoc-md/4529.md
@@ -0,0 +1,36 @@
+```
+% pandoc -f latex -t plain+gutenberg
+\chapter{First chapter}\label{sec:chp1}
+The next chapter is Chapter~\ref{sec:chp2}.
+\section{First section}\label{sec:chp1sec1}
+The next section is Section~\ref{sec:chp2sec1}.
+
+\chapter{Second chapter}\label{sec:chp2}
+The previous chapter is Chapter~\ref{sec:chp1}.
+\section{First section}\label{sec:chp2sec1}
+The previous section is Section~\ref{sec:chp1sec1}.
+^D
+
+
+FIRST CHAPTER
+
+
+The next chapter is Chapter 2.
+
+
+First section
+
+The next section is Section 2.1.
+
+
+
+SECOND CHAPTER
+
+
+The previous chapter is Chapter 1.
+
+
+First section
+
+The previous section is Section 1.1.
+```
diff --git a/documents/markdown/pandoc-md/4545.md b/documents/markdown/pandoc-md/4545.md
new file mode 100644
index 0000000..f017f28
--- /dev/null
+++ b/documents/markdown/pandoc-md/4545.md
@@ -0,0 +1,20 @@
+```
+% pandoc -t asciidoc
+Test 1
+
+[my text]
+
+Test 2
+^D
+Test 1
+
+++[++my text++]++
+
+Test 2
+```
+```
+% pandoc -t asciidoc
+4\. foo
+^D
+{empty}4. foo
+```
diff --git a/documents/markdown/pandoc-md/4553.md b/documents/markdown/pandoc-md/4553.md
new file mode 100644
index 0000000..0104a08
--- /dev/null
+++ b/documents/markdown/pandoc-md/4553.md
@@ -0,0 +1,21 @@
+```
+% pandoc -f latex -t native
+foo \include{command/bar}
+^D
+[ Para [ Str "foo" ]
+, Para [ Emph [ Str "hi" , Space , Str "there" ] ]
+]
+```
+
+```
+% pandoc -f latex -t native
+foo \input{command/bar}
+^D
+[ Para
+ [ Str "foo"
+ , Space
+ , Emph [ Str "hi" , Space , Str "there" ]
+ ]
+]
+```
+
diff --git a/documents/markdown/pandoc-md/4564.md b/documents/markdown/pandoc-md/4564.md
new file mode 100644
index 0000000..736570a
--- /dev/null
+++ b/documents/markdown/pandoc-md/4564.md
@@ -0,0 +1,58 @@
+```
+% pandoc -f native -t rst --list-tables
+[Table ("",[],[]) (Caption Nothing
+ [Plain [Str "Here",Space,Str "is",Space,Str "a",Space,Str "caption."]])
+ [(AlignDefault,ColWidth 0.1527777777777778)
+ ,(AlignDefault,ColWidth 0.1388888888888889)
+ ,(AlignDefault,ColWidth 0.16666666666666666)
+ ,(AlignDefault,ColWidth 0.375)]
+ (TableHead ("",[],[])
+ [Row ("",[],[])
+ [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "Centered",SoftBreak,Str "Header"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "Left",SoftBreak,Str "Aligned"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "Right",SoftBreak,Str "Aligned"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "Default",Space,Str "aligned"]]]])
+ [(TableBody ("",[],[]) (RowHeadColumns 0)
+ []
+ [Row ("",[],[])
+ [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "First"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain []]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "12.0"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "Example",Space,Str "of",Space,Str "a",Space,Str "row",Space,Str "that",SoftBreak,Str "spans",Space,Str "multiple",Space,Str "lines."]]]
+ ,Row ("",[],[])
+ [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "Second"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "row"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "5.0"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "Here\8217s",Space,Str "another",Space,Str "one.",Space,Str "Note",SoftBreak,Str "the",Space,Str "blank",Space,Str "line",Space,Str "between",SoftBreak,Str "rows."]]]])]
+ (TableFoot ("",[],[])
+ [])]
+^D
+.. list-table:: Here is a caption.
+ :widths: 11 10 12 27
+ :header-rows: 1
+
+ * - Centered Header
+ - Left Aligned
+ - Right Aligned
+ - Default aligned
+ * - First
+ -
+ - 12.0
+ - Example of a row that spans multiple lines.
+ * - Second
+ - row
+ - 5.0
+ - Here’s another one. Note the blank line between rows.
+```
diff --git a/documents/markdown/pandoc-md/4576.md b/documents/markdown/pandoc-md/4576.md
new file mode 100644
index 0000000..85322d4
--- /dev/null
+++ b/documents/markdown/pandoc-md/4576.md
@@ -0,0 +1,6 @@
+```
+% pandoc -f latex -t native
+$\rho_\text{D$_2$O}=866$
+^D
+[ Para [ Math InlineMath "\\rho_\\text{D$_2$O}=866" ] ]
+```
diff --git a/documents/markdown/pandoc-md/4578.md b/documents/markdown/pandoc-md/4578.md
new file mode 100644
index 0000000..8f12d0b
--- /dev/null
+++ b/documents/markdown/pandoc-md/4578.md
@@ -0,0 +1,14 @@
+```
+% pandoc -t markdown
+ ------ ------- --------------- ---------------------
+ One row 12.0 Example of a row that
+ spans multiple lines.
+
+ ------ ------- --------------- ---------------------
+^D
+ ------ ------- --------------- ---------------------
+ One row 12.0 Example of a row that
+ spans multiple lines.
+
+ ------ ------- --------------- ---------------------
+```
diff --git a/documents/markdown/pandoc-md/4579.md b/documents/markdown/pandoc-md/4579.md
new file mode 100644
index 0000000..353a4a5
--- /dev/null
+++ b/documents/markdown/pandoc-md/4579.md
@@ -0,0 +1,58 @@
+```
+% pandoc -f rst -t native
+.. list-table::
+ :header-rows: 1
+
+ * - Foo
+ - Bar
+ * - spam
+ - ham
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Foo" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Bar" ] ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "spam" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "ham" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
diff --git a/documents/markdown/pandoc-md/4589.md b/documents/markdown/pandoc-md/4589.md
new file mode 100644
index 0000000..ffbe6fe
--- /dev/null
+++ b/documents/markdown/pandoc-md/4589.md
@@ -0,0 +1,14 @@
+```
+% pandoc -f markdown -t latex
+\newcommand{\one}[1]{#1}
+\newcommand{\two}[1]{#1}
+
+Formatting *is* working **here**. But sticking \one{two }\two{commands}
+together *breaks* formatting.
+^D
+\newcommand{\one}[1]{#1}
+\newcommand{\two}[1]{#1}
+
+Formatting \emph{is} working \textbf{here}. But sticking two commands
+together \emph{breaks} formatting.
+```
diff --git a/documents/markdown/pandoc-md/4594.md b/documents/markdown/pandoc-md/4594.md
new file mode 100644
index 0000000..3f08b6c
--- /dev/null
+++ b/documents/markdown/pandoc-md/4594.md
@@ -0,0 +1,24 @@
+```
+% pandoc -f markdown -t latex
+Some **bold** text here.
+
+\begin{figure}[htbp]
+\centering
+\def\svgwidth{\columnwidth}
+\import{img/}{vectors.pdf_tex}
+\caption{Some caption.}
+\end{figure}
+
+Some *italic* text here.
+^D
+Some \textbf{bold} text here.
+
+\begin{figure}[htbp]
+\centering
+\def\svgwidth{\columnwidth}
+\import{img/}{vectors.pdf_tex}
+\caption{Some caption.}
+\end{figure}
+
+Some \emph{italic} text here.
+```
diff --git a/documents/markdown/pandoc-md/4598.md b/documents/markdown/pandoc-md/4598.md
new file mode 100644
index 0000000..fedfe88
--- /dev/null
+++ b/documents/markdown/pandoc-md/4598.md
@@ -0,0 +1,10 @@
+```
+% pandoc -f rst
+`x`__
+
+__ `xy`_
+
+.. _`xy`: http://xy.org
+^D
+<p><a href="http://xy.org">x</a></p>
+```
diff --git a/documents/markdown/pandoc-md/4624.md b/documents/markdown/pandoc-md/4624.md
new file mode 100644
index 0000000..abbdf61
--- /dev/null
+++ b/documents/markdown/pandoc-md/4624.md
@@ -0,0 +1,33 @@
+```
+% pandoc -f latex -t native
+\begin{Verbatim}[key1=value1]
+code1
+
+\end{Verbatim}
+
+
+\begin{lstlisting}[key2=value2]
+code2
+
+\end{lstlisting}
+
+\begin{verbatim}
+code3
+\end{verbatim}
+
+\begin{verbatim}
+code4
+ \end{verbatim}
+
+\begin{verbatim}
+code5\end{verbatim}
+^D
+[ CodeBlock
+ ( "" , [] , [ ( "key1" , "value1" ) ] ) "code1\n"
+, CodeBlock
+ ( "" , [] , [ ( "key2" , "value2" ) ] ) "code2\n "
+, CodeBlock ( "" , [] , [] ) "code3"
+, CodeBlock ( "" , [] , [] ) "code4"
+, CodeBlock ( "" , [] , [] ) "code5"
+]
+```
diff --git a/documents/markdown/pandoc-md/4635.md b/documents/markdown/pandoc-md/4635.md
new file mode 100644
index 0000000..7acb085
--- /dev/null
+++ b/documents/markdown/pandoc-md/4635.md
@@ -0,0 +1,35 @@
+```
+% pandoc -f markdown -t native
+(cf.
+foo)
+^D
+[ Para [ Str "(cf." , SoftBreak , Str "foo)" ] ]
+```
+
+```
+% pandoc -f markdown -t native
+a (cf.
+foo)
+^D
+[ Para
+ [ Str "a" , Space , Str "(cf." , SoftBreak , Str "foo)" ]
+]
+```
+
+```
+% pandoc -f markdown -t native
+cf.
+foo
+^D
+[ Para [ Str "cf." , SoftBreak , Str "foo" ] ]
+```
+
+```
+% pandoc -f markdown -t native
+a cf.
+foo
+^D
+[ Para
+ [ Str "a" , Space , Str "cf." , SoftBreak , Str "foo" ]
+]
+```
diff --git a/documents/markdown/pandoc-md/4637.md b/documents/markdown/pandoc-md/4637.md
new file mode 100644
index 0000000..892b060
--- /dev/null
+++ b/documents/markdown/pandoc-md/4637.md
@@ -0,0 +1,6 @@
+```
+% pandoc -t latex
+more \indextext{dogs}' than \indextext{cats}'
+^D
+more \indextext{dogs}' than \indextext{cats}'
+```
diff --git a/documents/markdown/pandoc-md/4639.md b/documents/markdown/pandoc-md/4639.md
new file mode 100644
index 0000000..c35df17
--- /dev/null
+++ b/documents/markdown/pandoc-md/4639.md
@@ -0,0 +1,10 @@
+```
+% pandoc -t html --mathjax
+\begin{equation}
+ E=mc^2
+\end{equation}
+^D
+<p><span class="math display">\[\begin{equation}
+ E=mc^2
+\end{equation}\]</span></p>
+```
diff --git a/documents/markdown/pandoc-md/4653.md b/documents/markdown/pandoc-md/4653.md
new file mode 100644
index 0000000..24a706e
--- /dev/null
+++ b/documents/markdown/pandoc-md/4653.md
@@ -0,0 +1,8 @@
+```
+% pandoc -t latex
+\let\tex\TeX
+\renewcommand{\TeX}{\tex\xspace}
+^D
+\let\tex\TeX
+\renewcommand{\TeX}{\tex\xspace}
+```
diff --git a/documents/markdown/pandoc-md/4667.md b/documents/markdown/pandoc-md/4667.md
new file mode 100644
index 0000000..a4ea0a5
--- /dev/null
+++ b/documents/markdown/pandoc-md/4667.md
@@ -0,0 +1,20 @@
+```
+% pandoc -t latex
+---
+header-includes:
+- \newcommand{\blandscape}{\begin{landscape}}
+- \newcommand{\elandscape}{\end{landscape}}
+...
+
+\blandscape
+
+testing
+
+\elandscape
+^D
+\begin{landscape}
+
+testing
+
+\end{landscape}
+```
diff --git a/documents/markdown/pandoc-md/4669.md b/documents/markdown/pandoc-md/4669.md
new file mode 100644
index 0000000..41f6ae3
--- /dev/null
+++ b/documents/markdown/pandoc-md/4669.md
@@ -0,0 +1,33 @@
+```
+% pandoc -f latex -t native
+{\tt <-}
+
+\begin{verbatim}
+ while (n > 0) {
+\end{verbatim}
+^D
+[ Para
+ [ Span ( "" , [] , [] ) [ Code ( "" , [] , [] ) "<-" ] ]
+, CodeBlock ( "" , [] , [] ) " while (n > 0) {"
+]
+```
+
+```
+% pandoc -f latex -t native
+\begin{itemize}
+\item<1> one
+\item<2-3,5> two
+\item<2| @alert> three
+\item<handout> four
+\item<beamer:2> five
+\end{itemize}
+^D
+[ BulletList
+ [ [ Para [ Str "one" ] ]
+ , [ Para [ Str "two" ] ]
+ , [ Para [ Str "three" ] ]
+ , [ Para [ Str "four" ] ]
+ , [ Para [ Str "five" ] ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/4677.md b/documents/markdown/pandoc-md/4677.md
new file mode 100644
index 0000000..15c8fd5
--- /dev/null
+++ b/documents/markdown/pandoc-md/4677.md
@@ -0,0 +1,9 @@
+```
+% pandoc --to "markdown-bracketed_spans-fenced_divs-link_attributes-simple_tables-multiline_tables-grid_tables-pipe_tables-fenced_code_attributes-markdown_in_html_blocks-table_captions-smart"
+{#img:1}
+^D
+<figure id="img:1">
+<img src="img.png" alt="Caption" />
+<figcaption aria-hidden="true">Caption</figcaption>
+</figure>
+```
diff --git a/documents/markdown/pandoc-md/4690.md b/documents/markdown/pandoc-md/4690.md
new file mode 100644
index 0000000..90adbd3
--- /dev/null
+++ b/documents/markdown/pandoc-md/4690.md
@@ -0,0 +1,26 @@
+```
+% pandoc -t beamer
+# title
+
+:::: {.columns}
+::: {.column width="8%"}
+content
+:::
+::: {.column width="84%"}
+content2
+:::
+::::
+^D
+\begin{frame}{title}
+\protect\phantomsection\label{title}
+\begin{columns}[T]
+\begin{column}{0.08\linewidth}
+content
+\end{column}
+
+\begin{column}{0.84\linewidth}
+content2
+\end{column}
+\end{columns}
+\end{frame}
+```
diff --git a/documents/markdown/pandoc-md/4715.md b/documents/markdown/pandoc-md/4715.md
new file mode 100644
index 0000000..f6bf873
--- /dev/null
+++ b/documents/markdown/pandoc-md/4715.md
@@ -0,0 +1,31 @@
+```
+% pandoc -f rst -t native
+.. toctree::
+ :name: tree1
+ :class: foo bar
+ :caption: Indice dei contenuti
+ :numbered:
+ :maxdepth: 3
+
+ premessa.rst
+ acquisizione-software.rst
+ riuso-software.rst
+^D
+[ Div
+ ( "tree1"
+ , [ "toctree" , "foo" , "bar" ]
+ , [ ( "caption" , "Indice dei contenuti" )
+ , ( "numbered" , "" )
+ , ( "maxdepth" , "3" )
+ ]
+ )
+ [ Para
+ [ Str "premessa.rst"
+ , SoftBreak
+ , Str "acquisizione-software.rst"
+ , SoftBreak
+ , Str "riuso-software.rst"
+ ]
+ ]
+]
+ ```
diff --git a/documents/markdown/pandoc-md/4722.md b/documents/markdown/pandoc-md/4722.md
new file mode 100644
index 0000000..2b2ceb6
--- /dev/null
+++ b/documents/markdown/pandoc-md/4722.md
@@ -0,0 +1,46 @@
+```
+% pandoc -f tikiwiki -t native
+*Level 1
+*Level 1
+**Level 2
+***Level 3
+*Level 1
+^D
+[ BulletList
+ [ [ Plain [ Str "Level" , Space , Str "1" ] ]
+ , [ Plain [ Str "Level" , Space , Str "1" ]
+ , BulletList
+ [ [ Plain [ Str "Level" , Space , Str "2" ]
+ , BulletList [ [ Plain [ Str "Level" , Space , Str "3" ] ] ]
+ ]
+ ]
+ ]
+ , [ Plain [ Str "Level" , Space , Str "1" ] ]
+ ]
+]
+```
+```
+% pandoc -f tikiwiki -t native
+#Level 1
+#Level 1
+##Level 2
+###Level 3
+#Level 1
+^D
+[ OrderedList
+ ( 1 , DefaultStyle , DefaultDelim )
+ [ [ Plain [ Str "Level" , Space , Str "1" ] ]
+ , [ Plain [ Str "Level" , Space , Str "1" ]
+ , OrderedList
+ ( 1 , DefaultStyle , DefaultDelim )
+ [ [ Plain [ Str "Level" , Space , Str "2" ]
+ , OrderedList
+ ( 1 , DefaultStyle , DefaultDelim )
+ [ [ Plain [ Str "Level" , Space , Str "3" ] ] ]
+ ]
+ ]
+ ]
+ , [ Plain [ Str "Level" , Space , Str "1" ] ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/4742.md b/documents/markdown/pandoc-md/4742.md
new file mode 100644
index 0000000..f213b88
--- /dev/null
+++ b/documents/markdown/pandoc-md/4742.md
@@ -0,0 +1,62 @@
+Check that the commonmark reader handles the `ascii_identifiers`
+extension properly.
+
+```
+% pandoc -f commonmark+gfm_auto_identifiers+ascii_identifiers -t native
+# non ascii ⚠️ räksmörgås
+^D
+[ Header
+ 1
+ ( "non-ascii-warning-raksmorgas" , [] , [] )
+ [ Str "non"
+ , Space
+ , Str "ascii"
+ , Space
+ , Str "\9888\65039"
+ , Space
+ , Str "r\228ksm\246rg\229s"
+ ]
+]
+```
+
+Note that the emoji here is actually a composite character,
+formed from \9888 and \65039. The latter is a combining mark,
+so it survives...
+
+```
+% pandoc -f commonmark+gfm_auto_identifiers-ascii_identifiers -t native
+# non ascii ⚠️ räksmörgås
+^D
+[ Header
+ 1
+ ( "non-ascii-warning-r\228ksm\246rg\229s" , [] , [] )
+ [ Str "non"
+ , Space
+ , Str "ascii"
+ , Space
+ , Str "\9888\65039"
+ , Space
+ , Str "r\228ksm\246rg\229s"
+ ]
+]
+```
+
+`gfm` should have `ascii_identifiers` disabled by default.
+
+```
+% pandoc -f gfm -t native
+# non ascii ⚠️ räksmörgås
+^D
+[ Header
+ 1
+ ( "non-ascii-warning-r\228ksm\246rg\229s" , [] , [] )
+ [ Str "non"
+ , Space
+ , Str "ascii"
+ , Space
+ , Str "\9888\65039"
+ , Space
+ , Str "r\228ksm\246rg\229s"
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/4743.md b/documents/markdown/pandoc-md/4743.md
new file mode 100644
index 0000000..a75ec10
--- /dev/null
+++ b/documents/markdown/pandoc-md/4743.md
@@ -0,0 +1,47 @@
+Test that emojis are wrapped in Span
+
+```
+% pandoc -f commonmark+emoji -t native
+My:thumbsup:emoji:heart:
+^D
+[ Para
+ [ Str "My"
+ , Span
+ ( "" , [ "emoji" ] , [ ( "data-emoji" , "thumbsup" ) ] )
+ [ Str "\128077" ]
+ , Str "emoji"
+ , Span
+ ( "" , [ "emoji" ] , [ ( "data-emoji" , "heart" ) ] )
+ [ Str "\10084\65039" ]
+ ]
+]
+```
+
+```
+% pandoc -f markdown+emoji -t native
+My:thumbsup:emoji:heart:
+^D
+[ Para
+ [ Str "My"
+ , Span
+ ( "" , [ "emoji" ] , [ ( "data-emoji" , "thumbsup" ) ] )
+ [ Str "\128077" ]
+ , Str "emoji"
+ , Span
+ ( "" , [ "emoji" ] , [ ( "data-emoji" , "heart" ) ] )
+ [ Str "\10084\65039" ]
+ ]
+]
+```
+
+```
+% pandoc -f commonmark+emoji -t html
+:zero: header
+=============
+My:thumbsup:emoji:heart:x :hearts: xyz
+^D
+<h1><span class="emoji" data-emoji="zero">0️⃣</span> header</h1>
+<p>My<span class="emoji" data-emoji="thumbsup">👍</span>emoji<span
+class="emoji" data-emoji="heart">❤️</span>x <span class="emoji"
+data-emoji="hearts">♥️</span> xyz</p>
+```
diff --git a/documents/markdown/pandoc-md/4746.md b/documents/markdown/pandoc-md/4746.md
new file mode 100644
index 0000000..6cfeef2
--- /dev/null
+++ b/documents/markdown/pandoc-md/4746.md
@@ -0,0 +1,56 @@
+```
+% pandoc -f latex -t native
+\begin{tabular}{c c}
+ \begin{tabular}{c} a \\ \end{tabular}
+ &
+ \\
+\end{tabular}
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignCenter , ColWidthDefault )
+ , ( AlignCenter , ColWidthDefault )
+ ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignCenter , ColWidthDefault ) ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "a" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+ ]
+ , Cell
+ ( "" , [] , [] ) AlignDefault (RowSpan 1) (ColSpan 1) []
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
diff --git a/documents/markdown/pandoc-md/4748.md b/documents/markdown/pandoc-md/4748.md
new file mode 100644
index 0000000..1de0fa9
--- /dev/null
+++ b/documents/markdown/pandoc-md/4748.md
@@ -0,0 +1,16 @@
+```
+% pandoc -f org -t rst
+Before example block.
+#+begin_example
+This is in an example block.
+#+end_example
+After example block.
+^D
+Before example block.
+
+::
+
+ This is in an example block.
+
+After example block.
+```
diff --git a/documents/markdown/pandoc-md/4768.md b/documents/markdown/pandoc-md/4768.md
new file mode 100644
index 0000000..60d407d
--- /dev/null
+++ b/documents/markdown/pandoc-md/4768.md
@@ -0,0 +1,7 @@
+```
+% pandoc -f latex -t plain
+\def\foo#1!#2!#3{#1 or #2 and #3}
+\foo aa!bbb bbb!{ccc}
+^D
+aa or bbb bbb and ccc
+```
diff --git a/documents/markdown/pandoc-md/4781.md b/documents/markdown/pandoc-md/4781.md
new file mode 100644
index 0000000..e240fac
--- /dev/null
+++ b/documents/markdown/pandoc-md/4781.md
@@ -0,0 +1,40 @@
+```
+% pandoc -t native
+Markdown parsed *here*
+
+\include{command/bar}
+
+*But not here*
+^D
+[ Para
+ [ Str "Markdown"
+ , Space
+ , Str "parsed"
+ , Space
+ , Emph [ Str "here" ]
+ ]
+, RawBlock (Format "tex") "\\include{command/bar}"
+, Para
+ [ Emph
+ [ Str "But" , Space , Str "not" , Space , Str "here" ]
+ ]
+]
+```
+
+```
+% pandoc -t native
+*here* \input{command/bar}
+
+*But not here*
+^D
+[ Para
+ [ Emph [ Str "here" ]
+ , Space
+ , RawInline (Format "tex") "\\input{command/bar}"
+ ]
+, Para
+ [ Emph
+ [ Str "But" , Space , Str "not" , Space , Str "here" ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/4794.md b/documents/markdown/pandoc-md/4794.md
new file mode 100644
index 0000000..06745d1
--- /dev/null
+++ b/documents/markdown/pandoc-md/4794.md
@@ -0,0 +1,18 @@
+```
+% pandoc -f markdown -t mediawiki
+| Column1 | Column2 | Column3 |
+| ------- | ------- | ------- |
+| text | | text |
+^D
+{| class="wikitable"
+|-
+! Column1
+! Column2
+! Column3
+|-
+| text
+|
+| text
+|}
+
+```
diff --git a/documents/markdown/pandoc-md/4805-beamer-columns-alignment.md b/documents/markdown/pandoc-md/4805-beamer-columns-alignment.md
new file mode 100644
index 0000000..73a3221
--- /dev/null
+++ b/documents/markdown/pandoc-md/4805-beamer-columns-alignment.md
@@ -0,0 +1,40 @@
+```
+% pandoc -t beamer
+:::: { .columns }
+::: { .column align=center }
+:::
+::: { .column align=bottom }
+:::
+::::
+
+:::: { .columns align=bottom .onlytextwidth }
+::: { .column align=top }
+:::
+::: { .column align=top-baseline }
+:::
+::::
+
+:::: { .columns totalwidth=7em }
+::::
+^D
+\begin{frame}
+\begin{columns}[T]
+\begin{column}[c]{0.48\linewidth}
+\end{column}
+
+\begin{column}[b]{0.48\linewidth}
+\end{column}
+\end{columns}
+
+\begin{columns}[b,onlytextwidth]
+\begin{column}[T]{0.48\linewidth}
+\end{column}
+
+\begin{column}[t]{0.48\linewidth}
+\end{column}
+\end{columns}
+
+\begin{columns}[T,totalwidth=7em]
+\end{columns}
+\end{frame}
+```
diff --git a/documents/markdown/pandoc-md/4811.md b/documents/markdown/pandoc-md/4811.md
new file mode 100644
index 0000000..4c0b0fa
--- /dev/null
+++ b/documents/markdown/pandoc-md/4811.md
@@ -0,0 +1,60 @@
+No blank lines in inline interpreted roles:
+
+```
+% pandoc -f rst -t native
+`no
+
+blank`:myrole:
+^D
+[ Para [ Str "`no" ] , Para [ Str "blank`:myrole:" ] ]
+```
+
+Backslash escape behaves properly in interpreted roles:
+
+```
+% pandoc -f rst -t native
+`hi\ there`:sup:
+
+`hi\ there`:code:
+^D
+[ Para [ Superscript [ Str "hithere" ] ]
+, Para [ Code ( "" , [] , [] ) "hi\\ there" ]
+]
+```
+
+Backtick followed by alphanumeric doesn't end the span:
+```
+% pandoc -f rst -t native
+`hi`there`:myrole:
+^D
+[ Para
+ [ Code
+ ( "" , [ "interpreted-text" ] , [ ( "role" , "myrole" ) ] )
+ "hi`there"
+ ]
+]
+```
+
+Newline is okay, as long as not blank:
+```
+% pandoc -f rst -t native
+`hi
+there`:myrole:
+^D
+[ Para
+ [ Code
+ ( "" , [ "interpreted-text" ] , [ ( "role" , "myrole" ) ] )
+ "hi\nthere"
+ ]
+]
+```
+
+Use span for title-reference:
+```
+% pandoc -f rst -t native
+`default`
+^D
+[ Para
+ [ Span ( "" , [ "title-ref" ] , [] ) [ Str "default" ] ]
+]
+```
diff --git a/documents/markdown/pandoc-md/4817.md b/documents/markdown/pandoc-md/4817.md
new file mode 100644
index 0000000..84db64b
--- /dev/null
+++ b/documents/markdown/pandoc-md/4817.md
@@ -0,0 +1,21 @@
+```
+% pandoc -t native -s
+---
+foo:
+- bar: bam
+...
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "foo"
+ , MetaList
+ [ MetaMap
+ (fromList [ ( "bar" , MetaInlines [ Str "bam" ] ) ])
+ ]
+ )
+ ]
+ }
+ []
+```
diff --git a/documents/markdown/pandoc-md/4819.md b/documents/markdown/pandoc-md/4819.md
new file mode 100644
index 0000000..5caa5c6
--- /dev/null
+++ b/documents/markdown/pandoc-md/4819.md
@@ -0,0 +1,55 @@
+```
+% pandoc -f markdown -t native -s
+---
+foo: 42
+...
+^D
+Pandoc
+ Meta
+ { unMeta = fromList [ ( "foo" , MetaInlines [ Str "42" ] ) ]
+ }
+ []
+```
+
+```
+% pandoc -f markdown -t native -s
+---
+foo: true
+...
+^D
+Pandoc
+ Meta { unMeta = fromList [ ( "foo" , MetaBool True ) ] } []
+```
+
+```
+% pandoc -f markdown -t native -s
+---
+foo: True
+...
+^D
+Pandoc
+ Meta { unMeta = fromList [ ( "foo" , MetaBool True ) ] } []
+```
+
+```
+% pandoc -f markdown -t native -s
+---
+foo: FALSE
+...
+^D
+Pandoc
+ Meta { unMeta = fromList [ ( "foo" , MetaBool False ) ] }
+ []
+```
+
+```
+% pandoc -f markdown -t native -s
+---
+foo: no
+...
+^D
+Pandoc
+ Meta { unMeta = fromList [ ( "foo" , MetaBool False ) ] }
+ []
+```
+
diff --git a/documents/markdown/pandoc-md/4832.md b/documents/markdown/pandoc-md/4832.md
new file mode 100644
index 0000000..ec636b2
--- /dev/null
+++ b/documents/markdown/pandoc-md/4832.md
@@ -0,0 +1,39 @@
+```
+% pandoc -f latex -t native
+\url{http://example.com/foo%20bar.htm}
+^D
+[ Para
+ [ Link
+ ( "" , [ "uri" ] , [] )
+ [ Str "http://example.com/foo%20bar.htm" ]
+ ( "http://example.com/foo%20bar.htm" , "" )
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\url{http://example.com/foo{bar}.htm}
+^D
+[ Para
+ [ Link
+ ( "" , [ "uri" ] , [] )
+ [ Str "http://example.com/foo{bar}.htm" ]
+ ( "http://example.com/foo{bar}.htm" , "" )
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\href{http://example.com/foo%20bar}{Foobar}
+^D
+[ Para
+ [ Link
+ ( "" , [] , [] )
+ [ Str "Foobar" ]
+ ( "http://example.com/foo%20bar" , "" )
+ ]
+]
+```
+
diff --git a/documents/markdown/pandoc-md/4833.md b/documents/markdown/pandoc-md/4833.md
new file mode 100644
index 0000000..838fe14
--- /dev/null
+++ b/documents/markdown/pandoc-md/4833.md
@@ -0,0 +1,20 @@
+```
+% pandoc -f native -t rst
+[Div ("",["warning"],[])
+ [Div ("",["title"],[])
+ [Para [Str "Warning"]]
+ ,Para [Str "Hi"]]]
+^D
+.. warning::
+
+ Hi
+```
+```
+% pandoc -f native -t rst
+[Div ("",["unknown"],[])
+ [Para [Str "Hi"]]]
+^D
+.. container:: unknown
+
+ Hi
+```
diff --git a/documents/markdown/pandoc-md/4845.md b/documents/markdown/pandoc-md/4845.md
new file mode 100644
index 0000000..10d1112
--- /dev/null
+++ b/documents/markdown/pandoc-md/4845.md
@@ -0,0 +1,21 @@
+```
+% pandoc -f html -t native
+x<a href="/foo"> leading trailing space </a>x
+^D
+[ Plain
+ [ Str "x"
+ , Space
+ , Link
+ ( "" , [] , [] )
+ [ Str "leading"
+ , Space
+ , Str "trailing"
+ , Space
+ , Str "space"
+ ]
+ ( "/foo" , "" )
+ , Space
+ , Str "x"
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/4848.md b/documents/markdown/pandoc-md/4848.md
new file mode 100644
index 0000000..c73699a
--- /dev/null
+++ b/documents/markdown/pandoc-md/4848.md
@@ -0,0 +1,92 @@
+```
+% pandoc -f latex -t native
+\enquote*{hi}
+^D
+[ Para [ Quoted SingleQuote [ Str "hi" ] ] ]
+```
+
+```
+% pandoc -f latex -t native
+\foreignquote{italian}{hi}
+^D
+[ Para
+ [ Quoted
+ DoubleQuote
+ [ Span ( "" , [] , [ ( "lang" , "it" ) ] ) [ Str "hi" ] ]
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\hyphenquote*{italian}{hi}
+^D
+[ Para
+ [ Quoted
+ SingleQuote
+ [ Span ( "" , [] , [ ( "lang" , "it" ) ] ) [ Str "hi" ] ]
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+Lorem ipsum
+\blockquote{dolor sit amet}
+consectetuer.
+^D
+[ Para [ Str "Lorem" , Space , Str "ipsum" ]
+, BlockQuote
+ [ Para
+ [ Str "dolor" , Space , Str "sit" , Space , Str "amet" ]
+ ]
+, Para [ Str "consectetuer." ]
+]
+```
+
+```
+% pandoc -f latex -t native
+Lorem ipsum
+\blockcquote[198]{Knu86}{dolor sit amet}
+consectetuer.
+^D
+[ Para [ Str "Lorem" , Space , Str "ipsum" ]
+, BlockQuote
+ [ Para
+ [ Str "dolor" , Space , Str "sit" , Space , Str "amet" ]
+ , Para
+ [ Cite
+ [ Citation
+ { citationId = "Knu86"
+ , citationPrefix = []
+ , citationSuffix = [ Str "198" ]
+ , citationMode = NormalCitation
+ , citationNoteNum = 0
+ , citationHash = 0
+ }
+ ]
+ []
+ ]
+ ]
+, Para [ Str "consectetuer." ]
+]
+```
+
+```
+% pandoc -f latex -t native
+Lorem ipsum
+\foreignblockquote{italian}{dolor sit amet}
+consectetuer.
+^D
+[ Para [ Str "Lorem" , Space , Str "ipsum" ]
+, BlockQuote
+ [ Div
+ ( "" , [] , [ ( "lang" , "it" ) ] )
+ [ Para
+ [ Str "dolor" , Space , Str "sit" , Space , Str "amet" ]
+ ]
+ ]
+, Para [ Str "consectetuer." ]
+]
+```
+
diff --git a/documents/markdown/pandoc-md/4860.md b/documents/markdown/pandoc-md/4860.md
new file mode 100644
index 0000000..65b6bf6
--- /dev/null
+++ b/documents/markdown/pandoc-md/4860.md
@@ -0,0 +1,20 @@
+```
+% pandoc -f rst -t native
+This is broken_.
+
+.. ***** REFERENCES FOLLOW *****
+.. _broken: http://google.com
+^D
+[ Para
+ [ Str "This"
+ , Space
+ , Str "is"
+ , Space
+ , Link
+ ( "" , [] , [] )
+ [ Str "broken" ]
+ ( "http://google.com" , "" )
+ , Str "."
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/4877.md b/documents/markdown/pandoc-md/4877.md
new file mode 100644
index 0000000..ba8acd1
--- /dev/null
+++ b/documents/markdown/pandoc-md/4877.md
@@ -0,0 +1,15 @@
+```
+% pandoc -f html -t native
+My <script type="math/tex">\mathcal{D}</script>
+^D
+[ Plain
+ [ Str "My" , Space , Math InlineMath "\\mathcal{D}" ]
+]
+```
+
+```
+% pandoc -f html -t native
+<script type="math/tex; mode=display">\mathcal{D}</script>
+^D
+[ Plain [ Math DisplayMath "\\mathcal{D}" ] ]
+```
diff --git a/documents/markdown/pandoc-md/4885.md b/documents/markdown/pandoc-md/4885.md
new file mode 100644
index 0000000..8611097
--- /dev/null
+++ b/documents/markdown/pandoc-md/4885.md
@@ -0,0 +1,8 @@
+```
+% pandoc -f org -t markdown
+This won't show the command.
+src_maxima[:exports none :results raw]{tex('integrate(sin((e^x)/pi),x,0,inf));} $$\int_{0}^{\infty }{\sin \left({{e^{x}}\over{\pi}}\right)\;dx}$$
+^D
+This won\'t show the command.
+$$\int_{0}^{\infty }{\sin \left({{e^{x}}\over{\pi}}\right)\;dx}$$
+```
diff --git a/documents/markdown/pandoc-md/4908.md b/documents/markdown/pandoc-md/4908.md
new file mode 100644
index 0000000..2ff1a46
--- /dev/null
+++ b/documents/markdown/pandoc-md/4908.md
@@ -0,0 +1,16 @@
+```
+% pandoc -f markdown_mmd+fancy_lists+example_lists -t native -t plain
+(@) Example one
+(@) Example two
+
+some text
+
+(@) Example three
+^D
+(1) Example one
+(2) Example two
+
+some text
+
+(3) Example three
+```
diff --git a/documents/markdown/pandoc-md/4913.md b/documents/markdown/pandoc-md/4913.md
new file mode 100644
index 0000000..6492b80
--- /dev/null
+++ b/documents/markdown/pandoc-md/4913.md
@@ -0,0 +1,34 @@
+```
+% pandoc -f markdown -t html
+[https://pandoc.org](https://pandoc.org)
+^D
+<p><a href="https://pandoc.org">https://pandoc.org</a></p>
+```
+
+```
+% pandoc -f markdown -t markdown
+[https://pandoc.org](https://pandoc.org)
+^D
+<https://pandoc.org>
+```
+
+```
+% pandoc -f markdown -t html
+<https://pandoc.org>
+^D
+<p><a href="https://pandoc.org" class="uri">https://pandoc.org</a></p>
+```
+
+```
+% pandoc -f markdown -t html
+<https://pandoc.org>{.foo}
+^D
+<p><a href="https://pandoc.org" class="foo">https://pandoc.org</a></p>
+```
+
+```
+% pandoc -f markdown -t html
+<me@example.com>
+^D
+<p><a href="mailto:me@example.com" class="email">me@example.com</a></p>
+```
diff --git a/documents/markdown/pandoc-md/4919.md b/documents/markdown/pandoc-md/4919.md
new file mode 100644
index 0000000..b8f1538
--- /dev/null
+++ b/documents/markdown/pandoc-md/4919.md
@@ -0,0 +1,17 @@
+```
+% pandoc -f rst -t native
+.. _`tgtmath`:
+
+ .. math::
+ :name:
+
+ V = \frac{K}{r^2}
+^D
+[ Div
+ ( "tgtmath" , [] , [] )
+ [ BlockQuote
+ [ Para [ Math DisplayMath "V = \\frac{K}{r^2}" ] ]
+ ]
+]
+```
+
diff --git a/documents/markdown/pandoc-md/4928.md b/documents/markdown/pandoc-md/4928.md
new file mode 100644
index 0000000..86699aa
--- /dev/null
+++ b/documents/markdown/pandoc-md/4928.md
@@ -0,0 +1,221 @@
+```
+% pandoc -f latex -t native
+\cites(Multiprenote)(multipostnote)[23][42]{Knu86}[65]{Nie72}
+^D
+[ Para
+ [ Cite
+ [ Citation
+ { citationId = "Knu86"
+ , citationPrefix = [ Str "Multiprenote" , Space , Str "23" ]
+ , citationSuffix = [ Str "42" ]
+ , citationMode = NormalCitation
+ , citationNoteNum = 0
+ , citationHash = 0
+ }
+ , Citation
+ { citationId = "Nie72"
+ , citationPrefix = []
+ , citationSuffix =
+ [ Str "65" , Str "," , Space , Str "multipostnote" ]
+ , citationMode = NormalCitation
+ , citationNoteNum = 0
+ , citationHash = 0
+ }
+ ]
+ [ RawInline
+ (Format "latex")
+ "\\cites(Multiprenote)(multipostnote)[23][42]{Knu86}[65]{Nie72}"
+ ]
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\cites(Multiprenote)()[23][42]{Knu86}[65]{Nie72}
+^D
+[ Para
+ [ Cite
+ [ Citation
+ { citationId = "Knu86"
+ , citationPrefix = [ Str "Multiprenote" , Space , Str "23" ]
+ , citationSuffix = [ Str "42" ]
+ , citationMode = NormalCitation
+ , citationNoteNum = 0
+ , citationHash = 0
+ }
+ , Citation
+ { citationId = "Nie72"
+ , citationPrefix = []
+ , citationSuffix = [ Str "65" ]
+ , citationMode = NormalCitation
+ , citationNoteNum = 0
+ , citationHash = 0
+ }
+ ]
+ [ RawInline
+ (Format "latex")
+ "\\cites(Multiprenote)()[23][42]{Knu86}[65]{Nie72}"
+ ]
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\cites()(multipostnote)[23][42]{Knu86}[65]{Nie72}
+^D
+[ Para
+ [ Cite
+ [ Citation
+ { citationId = "Knu86"
+ , citationPrefix = [ Str "23" ]
+ , citationSuffix = [ Str "42" ]
+ , citationMode = NormalCitation
+ , citationNoteNum = 0
+ , citationHash = 0
+ }
+ , Citation
+ { citationId = "Nie72"
+ , citationPrefix = []
+ , citationSuffix =
+ [ Str "65" , Str "," , Space , Str "multipostnote" ]
+ , citationMode = NormalCitation
+ , citationNoteNum = 0
+ , citationHash = 0
+ }
+ ]
+ [ RawInline
+ (Format "latex")
+ "\\cites()(multipostnote)[23][42]{Knu86}[65]{Nie72}"
+ ]
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\cites()()[23][42]{Knu86}[65]{Nie72}
+^D
+[ Para
+ [ Cite
+ [ Citation
+ { citationId = "Knu86"
+ , citationPrefix = [ Str "23" ]
+ , citationSuffix = [ Str "42" ]
+ , citationMode = NormalCitation
+ , citationNoteNum = 0
+ , citationHash = 0
+ }
+ , Citation
+ { citationId = "Nie72"
+ , citationPrefix = []
+ , citationSuffix = [ Str "65" ]
+ , citationMode = NormalCitation
+ , citationNoteNum = 0
+ , citationHash = 0
+ }
+ ]
+ [ RawInline
+ (Format "latex") "\\cites()()[23][42]{Knu86}[65]{Nie72}"
+ ]
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\cites(multipostnote)[23][42]{Knu86}[65]{Nie72}
+^D
+[ Para
+ [ Cite
+ [ Citation
+ { citationId = "Knu86"
+ , citationPrefix = [ Str "23" ]
+ , citationSuffix = [ Str "42" ]
+ , citationMode = NormalCitation
+ , citationNoteNum = 0
+ , citationHash = 0
+ }
+ , Citation
+ { citationId = "Nie72"
+ , citationPrefix = []
+ , citationSuffix =
+ [ Str "65" , Str "," , Space , Str "multipostnote" ]
+ , citationMode = NormalCitation
+ , citationNoteNum = 0
+ , citationHash = 0
+ }
+ ]
+ [ RawInline
+ (Format "latex")
+ "\\cites(multipostnote)[23][42]{Knu86}[65]{Nie72}"
+ ]
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\cites(Multiprenote)(multipostnote){Knu86}
+^D
+[ Para
+ [ Cite
+ [ Citation
+ { citationId = "Knu86"
+ , citationPrefix = [ Str "Multiprenote" ]
+ , citationSuffix = [ Str "," , Space , Str "multipostnote" ]
+ , citationMode = NormalCitation
+ , citationNoteNum = 0
+ , citationHash = 0
+ }
+ ]
+ [ RawInline
+ (Format "latex")
+ "\\cites(Multiprenote)(multipostnote){Knu86}"
+ ]
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\footcites(Multiprenote)(multipostnote)[23][42]{Knu86}[65]{Nie72}
+^D
+[ Para
+ [ Note
+ [ Para
+ [ Cite
+ [ Citation
+ { citationId = "Knu86"
+ , citationPrefix =
+ [ Str "Multiprenote" , Space , Str "23" ]
+ , citationSuffix = [ Str "42" ]
+ , citationMode = NormalCitation
+ , citationNoteNum = 0
+ , citationHash = 0
+ }
+ , Citation
+ { citationId = "Nie72"
+ , citationPrefix = []
+ , citationSuffix =
+ [ Str "65"
+ , Str ","
+ , Space
+ , Str "multipostnote"
+ ]
+ , citationMode = NormalCitation
+ , citationNoteNum = 0
+ , citationHash = 0
+ }
+ ]
+ [ RawInline
+ (Format "latex")
+ "\\footcites(Multiprenote)(multipostnote)[23][42]{Knu86}[65]{Nie72}"
+ ]
+ , Str "."
+ ]
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/4933.md b/documents/markdown/pandoc-md/4933.md
new file mode 100644
index 0000000..b8dedfa
--- /dev/null
+++ b/documents/markdown/pandoc-md/4933.md
@@ -0,0 +1,10 @@
+```
+% pandoc -f latex -t native
+\includegraphics{lalune}
+^D
+[ Para
+ [ Image
+ ( "" , [] , [] ) [ Str "image" ] ( "lalune.jpg" , "" )
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/4960.md b/documents/markdown/pandoc-md/4960.md
new file mode 100644
index 0000000..7253b53
--- /dev/null
+++ b/documents/markdown/pandoc-md/4960.md
@@ -0,0 +1,22 @@
+```
+% pandoc -t latex --biblatex
+[@a1;@a2;@a3]
+^D
+\autocite{a1,a2,a3}
+```
+
+```
+% pandoc -t latex --biblatex
+@a1 [@a2;@a3]
+^D
+\textcite{a1,a2,a3}
+```
+
+```
+% pandoc -t latex --biblatex
+[@a1, blah; @a2; see @a3]
+^D
+\autocites[blah]{a1}{a2}[see][]{a3}
+```
+
+
diff --git a/documents/markdown/pandoc-md/5010.md b/documents/markdown/pandoc-md/5010.md
new file mode 100644
index 0000000..b95d548
--- /dev/null
+++ b/documents/markdown/pandoc-md/5010.md
@@ -0,0 +1,21 @@
+```
+% pandoc -f latex -t latex
+\(\left\{ \begin{matrix}
+y\,\,\,\, \geqq \,\,\, f\,(\, x\,)\,\, \\
+y\,\,\, \leqq \,\,\, g\,(\, x\,)\, \\
+\end{matrix} \right.\ \)
+^D
+\(\left\{ \begin{matrix}
+y\,\,\,\, \geqq \,\,\, f\,(\, x\,)\,\, \\
+y\,\,\, \leqq \,\,\, g\,(\, x\,)\, \\
+\end{matrix} \right.\ \)
+```
+
+```
+% pandoc -f markdown -t latex
+$x\ $
+^D
+\(x\ \)
+```
+
+
diff --git a/documents/markdown/pandoc-md/5014.md b/documents/markdown/pandoc-md/5014.md
new file mode 100644
index 0000000..8acc557
--- /dev/null
+++ b/documents/markdown/pandoc-md/5014.md
@@ -0,0 +1,49 @@
+```
+% pandoc -f html -t native
+<table>
+ <thead>
+ <tr>
+ <td>Name</td>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>Accounts</td>
+ </tr>
+ </tbody>
+</table>
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault ) ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Name" ] ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Accounts" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
diff --git a/documents/markdown/pandoc-md/5039.md b/documents/markdown/pandoc-md/5039.md
new file mode 100644
index 0000000..651a023
--- /dev/null
+++ b/documents/markdown/pandoc-md/5039.md
@@ -0,0 +1,27 @@
+```
+% pandoc -f man -t plain
+.ds foo bar
+.ds bar baz
+\*[\*[foo]]
+^D
+baz
+```
+
+```
+% pandoc -f man -t plain
+.ds foo [bar]
+.ds bar baz
+\*\*[foo]
+^D
+baz
+```
+
+```
+% pandoc -f man -t html
+.ds B-Font B
+.ds I-Font I
+.ds R-Font R
+\f\*[B-Font]certtool\fP
+^D
+<p><strong>certtool</strong></p>
+```
diff --git a/documents/markdown/pandoc-md/5053.md b/documents/markdown/pandoc-md/5053.md
new file mode 100644
index 0000000..01d8b69
--- /dev/null
+++ b/documents/markdown/pandoc-md/5053.md
@@ -0,0 +1,14 @@
+```
+% pandoc
+—_legibility_—
+^D
+<p>—<em>legibility</em>—</p>
+```
+
+```
+% pandoc
+_filename_|_filetype_
+^D
+<p><em>filename</em>|<em>filetype</em></p>
+```
+
diff --git a/documents/markdown/pandoc-md/5071.md b/documents/markdown/pandoc-md/5071.md
new file mode 100644
index 0000000..0347d3c
--- /dev/null
+++ b/documents/markdown/pandoc-md/5071.md
@@ -0,0 +1,68 @@
+```
+% pandoc -f markdown -t html --number-sections
+## First section
+
+### Subhead
+
+##### Subhead with gap
+
+## Second section
+^D
+<h2 data-number="1" id="first-section"><span
+class="header-section-number">1</span> First section</h2>
+<h3 data-number="1.1" id="subhead"><span
+class="header-section-number">1.1</span> Subhead</h3>
+<h5 data-number="1.1.0.1" id="subhead-with-gap"><span
+class="header-section-number">1.1.0.1</span> Subhead with gap</h5>
+<h2 data-number="2" id="second-section"><span
+class="header-section-number">2</span> Second section</h2>
+
+```
+
+```
+% pandoc -f markdown -t html --number-sections
+## First section
+
+### Subhead
+
+# Higher-level section
+
+## Sub
+^D
+<h2 data-number="0.1" id="first-section"><span
+class="header-section-number">0.1</span> First section</h2>
+<h3 data-number="0.1.1" id="subhead"><span
+class="header-section-number">0.1.1</span> Subhead</h3>
+<h1 data-number="1" id="higher-level-section"><span
+class="header-section-number">1</span> Higher-level section</h1>
+<h2 data-number="1.1" id="sub"><span
+class="header-section-number">1.1</span> Sub</h2>
+```
+
+For backwards compatibility, we want it to work the old way,
+giving numbers like 0.1, when `--number-offset` is used:
+```
+% pandoc -f markdown -t html --number-sections --number-offset=2,2,2
+## First section
+
+### Subhead
+^D
+<h2 data-number="2.3" id="first-section"><span
+class="header-section-number">2.3</span> First section</h2>
+<h3 data-number="2.3.1" id="subhead"><span
+class="header-section-number">2.3.1</span> Subhead</h3>
+
+```
+
+```
+% pandoc -f markdown -t html --number-sections --number-offset=0,2,2
+## First section
+
+### Subhead
+^D
+<h2 data-number="0.3" id="first-section"><span
+class="header-section-number">0.3</span> First section</h2>
+<h3 data-number="0.3.1" id="subhead"><span
+class="header-section-number">0.3.1</span> Subhead</h3>
+
+```
diff --git a/documents/markdown/pandoc-md/5072.md b/documents/markdown/pandoc-md/5072.md
new file mode 100644
index 0000000..414022a
--- /dev/null
+++ b/documents/markdown/pandoc-md/5072.md
@@ -0,0 +1,14 @@
+```
+% pandoc -t latex -i
+1. one
+2. two
+^D
+\begin{enumerate}
+\def\labelenumi{\arabic{enumi}.}
+\tightlist
+\item
+ one
+\item
+ two
+\end{enumerate}
+```
diff --git a/documents/markdown/pandoc-md/5079.md b/documents/markdown/pandoc-md/5079.md
new file mode 100644
index 0000000..3eb0628
--- /dev/null
+++ b/documents/markdown/pandoc-md/5079.md
@@ -0,0 +1,35 @@
+```
+% pandoc -f html -t native
+<table>
+<tfoot>
+</tfoot>
+<tbody>
+<tr>
+<td>Cell</td>
+</tr>
+</tbody>
+</table>
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault ) ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
diff --git a/documents/markdown/pandoc-md/5080.md b/documents/markdown/pandoc-md/5080.md
new file mode 100644
index 0000000..2dfd068
--- /dev/null
+++ b/documents/markdown/pandoc-md/5080.md
@@ -0,0 +1,13 @@
+```
+% pandoc -t asciidoc
+[foo *bar*]{.small .red key=val}
+^D
+[.small .red]#foo _bar_#
+```
+
+```
+% pandoc -f html -t asciidoc
+<small>SMALL</small>
+^D
+[.small]#SMALL#
+```
diff --git a/documents/markdown/pandoc-md/5081.md b/documents/markdown/pandoc-md/5081.md
new file mode 100644
index 0000000..78b6c43
--- /dev/null
+++ b/documents/markdown/pandoc-md/5081.md
@@ -0,0 +1,8 @@
+```
+% pandoc -f rst
+Go to `g`_ `g <www.example.com>`_.
+^D
+<p>Go to <a href="www.example.com">g</a> <a
+href="www.example.com">g</a>.</p>
+
+```
diff --git a/documents/markdown/pandoc-md/5099.md b/documents/markdown/pandoc-md/5099.md
new file mode 100644
index 0000000..d464f9c
--- /dev/null
+++ b/documents/markdown/pandoc-md/5099.md
@@ -0,0 +1,29 @@
+```
+% pandoc -t native
+(@citation
+^D
+[ Para
+ [ Str "("
+ , Cite
+ [ Citation
+ { citationId = "citation"
+ , citationPrefix = []
+ , citationSuffix = []
+ , citationMode = AuthorInText
+ , citationNoteNum = 1
+ , citationHash = 0
+ }
+ ]
+ [ Str "@citation" ]
+ ]
+]
+```
+
+```
+% pandoc -t native
+('asd')
+^D
+[ Para
+ [ Str "(" , Quoted SingleQuote [ Str "asd" ] , Str ")" ]
+]
+```
diff --git a/documents/markdown/pandoc-md/5107.md b/documents/markdown/pandoc-md/5107.md
new file mode 100644
index 0000000..cdbc826
--- /dev/null
+++ b/documents/markdown/pandoc-md/5107.md
@@ -0,0 +1,23 @@
+```
+% pandoc -f muse -t dokuwiki
+ - foo
+ 1. bar
+ - baz
+^D
+ * foo
+ - bar
+ * baz
+
+```
+```
+% pandoc -f muse -t dokuwiki
+ - foo
+ 1. bar
+ 2. baz
+^D
+ * foo
+ - bar
+ - baz
+
+```
+
diff --git a/documents/markdown/pandoc-md/5116.md b/documents/markdown/pandoc-md/5116.md
new file mode 100644
index 0000000..5a57f07
--- /dev/null
+++ b/documents/markdown/pandoc-md/5116.md
@@ -0,0 +1,107 @@
+```
+% pandoc -t latex
+
+
+ Right Left Center Default
+------- ------ ---------- -------
+ 12 12 12 12
+ 123 123 123 123
+ 1 1 1 1
+
+ : Demonstration of simple table syntax.
+^D
+\begin{figure}
+\centering
+\pandocbounded{\includegraphics[keepaspectratio,alt={This is a figure.}]{img.jpg}}
+\caption{This is a figure.}
+\end{figure}
+
+\begin{longtable}[]{@{}rlcl@{}}
+\caption{Demonstration of simple table syntax.}\tabularnewline
+\toprule\noalign{}
+Right & Left & Center & Default \\
+\midrule\noalign{}
+\endfirsthead
+\toprule\noalign{}
+Right & Left & Center & Default \\
+\midrule\noalign{}
+\endhead
+\bottomrule\noalign{}
+\endlastfoot
+12 & 12 & 12 & 12 \\
+123 & 123 & 123 & 123 \\
+1 & 1 & 1 & 1 \\
+\end{longtable}
+
+```
+
+```
+% pandoc -t latex --figure-caption-position=above --table-caption-position=above
+
+
+ Right Left Center Default
+------- ------ ---------- -------
+ 12 12 12 12
+ 123 123 123 123
+ 1 1 1 1
+
+ : Demonstration of simple table syntax.
+^D
+\begin{figure}
+\centering
+\caption{This is a figure.}
+\pandocbounded{\includegraphics[keepaspectratio,alt={This is a figure.}]{img.jpg}}
+\end{figure}
+
+\begin{longtable}[]{@{}rlcl@{}}
+\caption{Demonstration of simple table syntax.}\tabularnewline
+\toprule\noalign{}
+Right & Left & Center & Default \\
+\midrule\noalign{}
+\endfirsthead
+\toprule\noalign{}
+Right & Left & Center & Default \\
+\midrule\noalign{}
+\endhead
+\bottomrule\noalign{}
+\endlastfoot
+12 & 12 & 12 & 12 \\
+123 & 123 & 123 & 123 \\
+1 & 1 & 1 & 1 \\
+\end{longtable}
+
+```
+
+```
+% pandoc -t latex --figure-caption-position=below --table-caption-position=below
+
+
+ Right Left Center Default
+------- ------ ---------- -------
+ 12 12 12 12
+ 123 123 123 123
+ 1 1 1 1
+
+ : Demonstration of simple table syntax.
+^D
+\begin{figure}
+\centering
+\pandocbounded{\includegraphics[keepaspectratio,alt={This is a figure.}]{img.jpg}}
+\caption{This is a figure.}
+\end{figure}
+
+\begin{longtable}[]{@{}rlcl@{}}
+\toprule\noalign{}
+Right & Left & Center & Default \\
+\midrule\noalign{}
+\endhead
+\bottomrule\noalign{}
+\tabularnewline
+\caption{Demonstration of simple table syntax.}
+\endlastfoot
+12 & 12 & 12 & 12 \\
+123 & 123 & 123 & 123 \\
+1 & 1 & 1 & 1 \\
+\end{longtable}
+
+```
diff --git a/documents/markdown/pandoc-md/512.md b/documents/markdown/pandoc-md/512.md
new file mode 100644
index 0000000..48f1f10
--- /dev/null
+++ b/documents/markdown/pandoc-md/512.md
@@ -0,0 +1,43 @@
+```
+% pandoc -f rst
+`click here`__ or `click here`__
+
+.. _link1: http://www.example.com/
+.. _link2: http://johnmacfarlane.net/pandoc/
+
+__ link1_
+__ link2_
+^D
+<p><a href="http://www.example.com/">click here</a> or <a
+href="http://johnmacfarlane.net/pandoc/">click here</a></p>
+```
+
+Multiple indirection:
+
+```
+% pandoc -f rst
+`click here`__
+
+.. _link1: link2_
+.. _link2: http://johnmacfarlane.net/pandoc/
+
+__ link1_
+^D
+<p><a href="http://johnmacfarlane.net/pandoc/">click here</a></p>
+```
+
+Loop detection:
+
+```
+% pandoc -f rst
+`click here`__
+
+.. _link1: link2_
+.. _link2: link1_
+
+__ link1_
+^D
+2> [WARNING] Circular reference 'link1' at line 8 column 1
+<p><a href="">click here</a></p>
+```
+
diff --git a/documents/markdown/pandoc-md/5121.md b/documents/markdown/pandoc-md/5121.md
new file mode 100644
index 0000000..f1b972f
--- /dev/null
+++ b/documents/markdown/pandoc-md/5121.md
@@ -0,0 +1,13 @@
+```
+% pandoc -f markdown -t markdown_strict
+{width=500px}
+
+## Header 2
+^D
+<figure>
+<img src="./my-figure.jpg" width="500" alt="My caption" />
+<figcaption aria-hidden="true">My caption</figcaption>
+</figure>
+
+## Header 2
+```
diff --git a/documents/markdown/pandoc-md/5128.md b/documents/markdown/pandoc-md/5128.md
new file mode 100644
index 0000000..ea62849
--- /dev/null
+++ b/documents/markdown/pandoc-md/5128.md
@@ -0,0 +1,26 @@
+```
+% pandoc -f org -t rst --columns=78
+| Option | Meaning |
+|--------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| =<= | Left alignment, additional characters are added to the right (default for string). |
+| =>= | Right alignment, additional characters are added to the left. |
+| =^= | Centered , the same amount of characters is added to the left and the right. |
+| === | Padding. If a numeric value is printed with a sign, then additional characters are added after the sign. Otherwise it behaves like "=>=". This option is only available for numbers (default for numbers). |
+^D
++--------+-------------------------------------------------------------------+
+| Option | Meaning |
++========+===================================================================+
+| ``<`` | Left alignment, additional characters are added to the right |
+| | (default for string). |
++--------+-------------------------------------------------------------------+
+| ``>`` | Right alignment, additional characters are added to the left. |
++--------+-------------------------------------------------------------------+
+| ``^`` | Centered , the same amount of characters is added to the left and |
+| | the right. |
++--------+-------------------------------------------------------------------+
+| ``=`` | Padding. If a numeric value is printed with a sign, then |
+| | additional characters are added after the sign. Otherwise it |
+| | behaves like "``>``". This option is only available for numbers |
+| | (default for numbers). |
++--------+-------------------------------------------------------------------+
+```
diff --git a/documents/markdown/pandoc-md/5177.md b/documents/markdown/pandoc-md/5177.md
new file mode 100644
index 0000000..d832780
--- /dev/null
+++ b/documents/markdown/pandoc-md/5177.md
@@ -0,0 +1,12 @@
+This should not give a "Prelude.read: no parse" error:
+
+```
+% pandoc -M foo=1e -s -t markdown
+hi
+^D
+---
+foo: 1e
+---
+
+hi
+```
diff --git a/documents/markdown/pandoc-md/5178.md b/documents/markdown/pandoc-md/5178.md
new file mode 100644
index 0000000..1c39b50
--- /dev/null
+++ b/documents/markdown/pandoc-md/5178.md
@@ -0,0 +1,52 @@
+```
+% pandoc -f rst -t org
+.. code:: haskell
+ :number-lines: 42
+
+ main = putStrLn "Hello World!"
+ unsafePerformIO main
+^D
+#+begin_src haskell -n 42
+main = putStrLn "Hello World!"
+unsafePerformIO main
+#+end_src
+```
+
+```
+% pandoc -f org -t native
+#+begin_src lisp -n 20
+ (+ 1 1)
+#+end_src
+
+#+begin_src lisp +n 10
+ (+ 2 2)
+#+end_src
+^D
+[ CodeBlock
+ ( ""
+ , [ "commonlisp" , "numberLines" ]
+ , [ ( "org-language" , "lisp" ) , ( "startFrom" , "20" ) ]
+ )
+ "(+ 1 1)\n"
+, CodeBlock
+ ( ""
+ , [ "commonlisp" , "numberLines" , "continuedSourceBlock" ]
+ , [ ( "org-language" , "lisp" ) , ( "startFrom" , "10" ) ]
+ )
+ "(+ 2 2)\n"
+]
+```
+
+```
+% pandoc -f native -t org
+[CodeBlock ("",["commonlisp","numberLines"],[("org-language","lisp"),("startFrom","20")]) "(+ 1 1)\n"
+,CodeBlock ("",["commonlisp","numberLines","continuedSourceBlock"],[("org-language","lisp"),("startFrom","10")]) "(+ 2 2)\n"]
+^D
+#+begin_src lisp -n 20
+(+ 1 1)
+#+end_src
+
+#+begin_src lisp +n 10
+(+ 2 2)
+#+end_src
+```
diff --git a/documents/markdown/pandoc-md/5182.md b/documents/markdown/pandoc-md/5182.md
new file mode 100644
index 0000000..5898f9e
--- /dev/null
+++ b/documents/markdown/pandoc-md/5182.md
@@ -0,0 +1,9 @@
+```
+% pandoc -f rst -t native
+.. include:: command/5182.txt
+^D
+[ CodeBlock
+ ( "" , [ "python" , "numberLines" ] , [] )
+ "def func(x):\n return y"
+]
+```
diff --git a/documents/markdown/pandoc-md/5241.md b/documents/markdown/pandoc-md/5241.md
new file mode 100644
index 0000000..c008b53
--- /dev/null
+++ b/documents/markdown/pandoc-md/5241.md
@@ -0,0 +1,12 @@
+```
+% pandoc -f markdown -t html5
+<textarea>
+ one
+ *two*
+</textarea>
+^D
+<textarea>
+ one
+ *two*
+</textarea>
+```
diff --git a/documents/markdown/pandoc-md/5271.md b/documents/markdown/pandoc-md/5271.md
new file mode 100644
index 0000000..5df3958
--- /dev/null
+++ b/documents/markdown/pandoc-md/5271.md
@@ -0,0 +1,41 @@
+```
+% pandoc -f markdown -t native -s
+---
+abstract: |
+ This is the abstract.
+
+ It consists of two paragraphs.
+...
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "abstract"
+ , MetaBlocks
+ [ Para
+ [ Str "This"
+ , Space
+ , Str "is"
+ , Space
+ , Str "the"
+ , Space
+ , Str "abstract."
+ ]
+ , Para
+ [ Str "It"
+ , Space
+ , Str "consists"
+ , Space
+ , Str "of"
+ , Space
+ , Str "two"
+ , Space
+ , Str "paragraphs."
+ ]
+ ]
+ )
+ ]
+ }
+ []
+```
diff --git a/documents/markdown/pandoc-md/5285.md b/documents/markdown/pandoc-md/5285.md
new file mode 100644
index 0000000..6c5b7f9
--- /dev/null
+++ b/documents/markdown/pandoc-md/5285.md
@@ -0,0 +1,32 @@
+```
+% pandoc -t native
+- a
+
+ b
+- a
+
+- b
+^D
+[ BulletList
+ [ [ Para [ Str "a" ] , Para [ Str "b" ] ]
+ , [ Para [ Str "a" ] ]
+ , [ Para [ Str "b" ] ]
+ ]
+]
+```
+
+```
+% pandoc -t native
+- foo
+
+ foo
+- foo
+
+ > foo
+^D
+[ BulletList
+ [ [ Para [ Str "foo" ] , Para [ Str "foo" ] ]
+ , [ Para [ Str "foo" ] , BlockQuote [ Para [ Str "foo" ] ] ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/5304.md b/documents/markdown/pandoc-md/5304.md
new file mode 100644
index 0000000..70f32a9
--- /dev/null
+++ b/documents/markdown/pandoc-md/5304.md
@@ -0,0 +1,24 @@
+````
+% pandoc -f markdown -t markdown
+``` {.markdown}
+`«sträng»`
+
+`` «sträng» ``
+
+``` «sträng» ```
+
+````«sträng»````
+...
+```
+^D
+``` markdown
+`«sträng»`
+
+`` «sträng» ``
+
+``` «sträng» ```
+
+````«sträng»````
+...
+```
+````
diff --git a/documents/markdown/pandoc-md/5321.md b/documents/markdown/pandoc-md/5321.md
new file mode 100644
index 0000000..8a66556
--- /dev/null
+++ b/documents/markdown/pandoc-md/5321.md
@@ -0,0 +1,41 @@
+```
+% pandoc -f jats -t native
+<fig id="fig-1">
+ <caption>
+ <p>bar</p>
+ </caption>
+ <graphic xlink:href="foo.png">
+ <alt-text>baz</alt-text>
+ </graphic>
+</fig>
+^D
+[ Figure
+ ( "fig-1" , [] , [] )
+ (Caption Nothing [ Plain [ Str "bar" ] ])
+ [ Para
+ [ Image ( "" , [] , [] ) [ Str "baz" ] ( "foo.png" , "" ) ]
+ ]
+]
+```
+
+```
+% pandoc -f jats -t native
+<fig id="fig-1">
+ <caption>
+ <title>foo</title>
+ <p>bar</p>
+ </caption>
+ <graphic xlink:href="foo.png">
+ <alt-text>baz</alt-text>
+ </graphic>
+</fig>
+^D
+[ Figure
+ ( "fig-1" , [] , [] )
+ (Caption
+ Nothing [ Plain [ Str "foo" , LineBreak , Str "bar" ] ])
+ [ Para
+ [ Image ( "" , [] , [] ) [ Str "baz" ] ( "foo.png" , "" ) ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/5340.md b/documents/markdown/pandoc-md/5340.md
new file mode 100644
index 0000000..416f0bd
--- /dev/null
+++ b/documents/markdown/pandoc-md/5340.md
@@ -0,0 +1,14 @@
+```
+% pandoc -f html -t latex --wrap=preserve
+<a href="https://example.com/foo-bar">https://example.com/foo-bar</a>
+<a href="https://example.com/foo--bar">https://example.com/foo--bar</a>
+<a href="https://example.com/foo%2Dbar">https://example.com/foo-bar</a>
+<a href="https://example.com/foo%2D%2Dbar">https://example.com/foo--bar</a>
+<a href="https://example.com/foo%2D%2Dbar">https://example.com/foo%2D%2Dbar</a>
+^D
+\url{https://example.com/foo-bar}
+\url{https://example.com/foo--bar}
+\url{https://example.com/foo\%2Dbar}
+\url{https://example.com/foo\%2D\%2Dbar}
+\url{https://example.com/foo\%2D\%2Dbar}
+```
diff --git a/documents/markdown/pandoc-md/5360.md b/documents/markdown/pandoc-md/5360.md
new file mode 100644
index 0000000..2250ba9
--- /dev/null
+++ b/documents/markdown/pandoc-md/5360.md
@@ -0,0 +1,22 @@
+```
+% pandoc -t native
+::: {.foo}
+<table>
+ <tr>
+ <td>hi</td>
+ </tr>
+</table>
+:::
+^D
+[ Div
+ ( "" , [ "foo" ] , [] )
+ [ RawBlock (Format "html") "<table>"
+ , RawBlock (Format "html") "<tr>"
+ , RawBlock (Format "html") "<td>"
+ , Plain [ Str "hi" ]
+ , RawBlock (Format "html") "</td>"
+ , RawBlock (Format "html") "</tr>"
+ , RawBlock (Format "html") "</table>"
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/5367.md b/documents/markdown/pandoc-md/5367.md
new file mode 100644
index 0000000..55c849a
--- /dev/null
+++ b/documents/markdown/pandoc-md/5367.md
@@ -0,0 +1,44 @@
+```
+% pandoc -t latex
+hello[^1]
+
+: Sample table.[^2]
+
+-----------
+ Fruit[^3]
+-----------
+ Bans[^4]
+-----------
+
+dolly[^5]
+
+[^1]: doc footnote
+[^2]: caption footnote
+[^3]: header footnote
+[^4]: table cell footnote
+[^5]: doc footnote
+^D
+hello\footnote{doc footnote}
+
+\begin{longtable}[]{@{}
+ >{\centering\arraybackslash}p{(\linewidth - 0\tabcolsep) * \real{0.1667}}@{}}
+\caption[Sample table.]{Sample table.\footnote{caption footnote}}\tabularnewline
+\toprule\noalign{}
+\begin{minipage}[b]{\linewidth}\centering
+Fruit\footnote{header footnote}
+\end{minipage} \\
+\midrule\noalign{}
+\endfirsthead
+\toprule\noalign{}
+\begin{minipage}[b]{\linewidth}\centering
+Fruit{}
+\end{minipage} \\
+\midrule\noalign{}
+\endhead
+\bottomrule\noalign{}
+\endlastfoot
+Bans\footnote{table cell footnote} \\
+\end{longtable}
+
+dolly\footnote{doc footnote}
+```
diff --git a/documents/markdown/pandoc-md/5368.md b/documents/markdown/pandoc-md/5368.md
new file mode 100644
index 0000000..9e09cee
--- /dev/null
+++ b/documents/markdown/pandoc-md/5368.md
@@ -0,0 +1,49 @@
+```
+% pandoc -t native
+1. foo
+
+ 
+2. foo2
+
+ 
+3. foo3
+
+ 
+
+Quux.
+^D
+[ OrderedList
+ ( 1 , Decimal , Period )
+ [ [ Para [ Str "foo" ]
+ , Figure
+ ( "" , [] , [] )
+ (Caption Nothing [ Plain [ Str "bar" ] ])
+ [ Plain
+ [ Image ( "" , [] , [] ) [ Str "bar" ] ( "bar.png" , "" )
+ ]
+ ]
+ ]
+ , [ Para [ Str "foo2" ]
+ , Figure
+ ( "" , [] , [] )
+ (Caption Nothing [ Plain [ Str "bar2" ] ])
+ [ Plain
+ [ Image
+ ( "" , [] , [] ) [ Str "bar2" ] ( "bar2.png" , "" )
+ ]
+ ]
+ ]
+ , [ Para [ Str "foo3" ]
+ , Figure
+ ( "" , [] , [] )
+ (Caption Nothing [ Plain [ Str "foo3" ] ])
+ [ Plain
+ [ Image
+ ( "" , [] , [] ) [ Str "foo3" ] ( "foo3.png" , "" )
+ ]
+ ]
+ ]
+ ]
+, Para [ Str "Quux." ]
+]
+```
diff --git a/documents/markdown/pandoc-md/5369.md b/documents/markdown/pandoc-md/5369.md
new file mode 100644
index 0000000..2f3305c
--- /dev/null
+++ b/documents/markdown/pandoc-md/5369.md
@@ -0,0 +1,7 @@
+```
+% pandoc -f native -t markdown
+[Div ("",[],[("tags","[\"o\\ne\",\"two\"]")]) [] ]
+^D
+::: {tags="[\"o\\ne\",\"two\"]"}
+:::
+```
diff --git a/documents/markdown/pandoc-md/5407.md b/documents/markdown/pandoc-md/5407.md
new file mode 100644
index 0000000..b8a37a8
--- /dev/null
+++ b/documents/markdown/pandoc-md/5407.md
@@ -0,0 +1,14 @@
+```
+% pandoc -t latex --wrap=preserve
+hi there?“
+hi there!“
+hi there?‘
+hi there!‘
+hi there!
+^D
+hi there?{\kern0pt}``
+hi there!{\kern0pt}``
+hi there?{\kern0pt}`
+hi there!{\kern0pt}`
+hi there!
+```
diff --git a/documents/markdown/pandoc-md/5416.md b/documents/markdown/pandoc-md/5416.md
new file mode 100644
index 0000000..d97f988
--- /dev/null
+++ b/documents/markdown/pandoc-md/5416.md
@@ -0,0 +1,13 @@
+```
+% pandoc -f dokuwiki -t native
+{
+^D
+[ Para [ Str "{" ] ]
+```
+
+```
+% pandoc -f dokuwiki -t native
+{{
+^D
+[ Para [ Str "{{" ] ]
+```
diff --git a/documents/markdown/pandoc-md/5420.md b/documents/markdown/pandoc-md/5420.md
new file mode 100644
index 0000000..17ce7e0
--- /dev/null
+++ b/documents/markdown/pandoc-md/5420.md
@@ -0,0 +1,6 @@
+```
+% pandoc --syntax-highlighting=idiomatic -t latex
+`int a = 1;`{.cpp style=cpp}
+^D
+\passthrough{\lstinline[language={C++}, style=cpp]!int a = 1;!}
+```
diff --git a/documents/markdown/pandoc-md/5474-figures.md b/documents/markdown/pandoc-md/5474-figures.md
new file mode 100644
index 0000000..915bf34
--- /dev/null
+++ b/documents/markdown/pandoc-md/5474-figures.md
@@ -0,0 +1,15 @@
+```
+% pandoc -t opendocument+native_numbering
+
+
+
+
+
+^D
+<text:p text:style-name="FigureWithCaption"><draw:frame draw:name="img1"><draw:image xlink:href="lalune.jpg" xlink:type="simple" xlink:show="embed" xlink:actuate="onLoad" /></draw:frame></text:p>
+<text:p text:style-name="FigureCaption">Figure <text:sequence text:ref-name="refIllustration0" text:name="Illustration" text:formula="ooow:Illustration+1" style:num-format="1">1</text:sequence>: First
+image</text:p>
+<text:p text:style-name="FigureWithCaption"><draw:frame draw:name="img2"><draw:image xlink:href="lalune.jpg" xlink:type="simple" xlink:show="embed" xlink:actuate="onLoad" /></draw:frame></text:p>
+<text:p text:style-name="FigureCaption">Figure <text:sequence text:ref-name="refIllustration1" text:name="Illustration" text:formula="ooow:Illustration+1" style:num-format="1">2</text:sequence>: Second
+image</text:p>
+```
diff --git a/documents/markdown/pandoc-md/5474-tables.md b/documents/markdown/pandoc-md/5474-tables.md
new file mode 100644
index 0000000..f09b0a4
--- /dev/null
+++ b/documents/markdown/pandoc-md/5474-tables.md
@@ -0,0 +1,63 @@
+```
+% pandoc -t opendocument+native_numbering
+ Right Left
+------- ------
+ 12 11
+
+: First table
+
+ Right Left
+------- ------
+ 13 14
+
+: Second Table
+^D
+<text:p text:style-name="TableCaption">Table <text:sequence text:ref-name="refTable0" text:name="Table" text:formula="ooow:Table+1" style:num-format="1">1</text:sequence>: First
+table</text:p>
+<table:table table:name="Table1" table:style-name="Table1">
+ <table:table-column table:style-name="Table1.A" />
+ <table:table-column table:style-name="Table1.B" />
+ <table:table-header-rows>
+ <table:table-row>
+ <table:table-cell table:style-name="TableHeaderRowCell" office:value-type="string">
+ <text:p text:style-name="P1">Right</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableHeaderRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Heading">Left</text:p>
+ </table:table-cell>
+ </table:table-row>
+ </table:table-header-rows>
+ <table:table-row>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="P2">12</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">11</text:p>
+ </table:table-cell>
+ </table:table-row>
+</table:table>
+<text:p text:style-name="TableCaption">Table <text:sequence text:ref-name="refTable1" text:name="Table" text:formula="ooow:Table+1" style:num-format="1">2</text:sequence>: Second
+Table</text:p>
+<table:table table:name="Table2" table:style-name="Table2">
+ <table:table-column table:style-name="Table2.A" />
+ <table:table-column table:style-name="Table2.B" />
+ <table:table-header-rows>
+ <table:table-row>
+ <table:table-cell table:style-name="TableHeaderRowCell" office:value-type="string">
+ <text:p text:style-name="P3">Right</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableHeaderRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Heading">Left</text:p>
+ </table:table-cell>
+ </table:table-row>
+ </table:table-header-rows>
+ <table:table-row>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="P4">13</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">14</text:p>
+ </table:table-cell>
+ </table:table-row>
+</table:table>
+```
diff --git a/documents/markdown/pandoc-md/5476.md b/documents/markdown/pandoc-md/5476.md
new file mode 100644
index 0000000..b7a258c
--- /dev/null
+++ b/documents/markdown/pandoc-md/5476.md
@@ -0,0 +1,12 @@
+```
+% pandoc -t latex
+![moon^[the moon]](test/lalune.jpg)
+^D
+\begin{figure}
+\centering
+\pandocbounded{\includegraphics[keepaspectratio,alt={moon}]{test/lalune.jpg}}
+\caption[moon]{moon\footnotemark{}}
+\end{figure}
+\footnotetext{the moon}
+```
+
diff --git a/documents/markdown/pandoc-md/5495.md b/documents/markdown/pandoc-md/5495.md
new file mode 100644
index 0000000..37370cc
--- /dev/null
+++ b/documents/markdown/pandoc-md/5495.md
@@ -0,0 +1,18 @@
+```
+% pandoc -t markdown --reference-links
+All because of [1](#one) link...
+
+[This](#foo) will break Pandoc.
+
+[This](#bar) will make you laugh.
+^D
+All because of [1] link...
+
+[This] will break Pandoc.
+
+[This][2] will make you laugh.
+
+ [1]: #one
+ [This]: #foo
+ [2]: #bar
+```
diff --git a/documents/markdown/pandoc-md/5519.md b/documents/markdown/pandoc-md/5519.md
new file mode 100644
index 0000000..ecde184
--- /dev/null
+++ b/documents/markdown/pandoc-md/5519.md
@@ -0,0 +1,14 @@
+~~~
+% pandoc -t markdown
+``````{.attr}
+ ```
+ code
+ ```
+``````
+^D
+```` attr
+ ```
+ code
+ ```
+````
+~~~
diff --git a/documents/markdown/pandoc-md/5529.md b/documents/markdown/pandoc-md/5529.md
new file mode 100644
index 0000000..01c6399
--- /dev/null
+++ b/documents/markdown/pandoc-md/5529.md
@@ -0,0 +1,10 @@
+```
+% pandoc -t latex
+~~`hello world`~~
+
+~~_`hello world`_~~
+^D
+\st{\mbox{\texttt{hello\ world}}}
+
+\st{\emph{\mbox{\texttt{hello\ world}}}}
+```
diff --git a/documents/markdown/pandoc-md/5540.md b/documents/markdown/pandoc-md/5540.md
new file mode 100644
index 0000000..4123902
--- /dev/null
+++ b/documents/markdown/pandoc-md/5540.md
@@ -0,0 +1,14 @@
+```
+% pandoc -f latex -t native
+\begin{lstlisting}[language=myfunnylanguage]
+Stay pure!
+\end{lstlisting}
+^D
+[ CodeBlock
+ ( ""
+ , [ "myfunnylanguage" ]
+ , [ ( "language" , "myfunnylanguage" ) ]
+ )
+ "Stay pure!"
+]
+```
diff --git a/documents/markdown/pandoc-md/5541-localLink.md b/documents/markdown/pandoc-md/5541-localLink.md
new file mode 100644
index 0000000..0770051
--- /dev/null
+++ b/documents/markdown/pandoc-md/5541-localLink.md
@@ -0,0 +1,149 @@
+```
+% pandoc -f markdown -t icml -s
+
+# Header 1
+
+this is some text
+
+## Header 2
+
+some more text that [links to](#header-1) the first header. And this links to [some text](#spanner) in 2.1.
+
+## Header 2.1
+
+if you can read this text, [and it's linked]{#spanner} - all good!
+
+^D
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<?aid style="50" type="snippet" readerVersion="6.0" featureSet="513" product="8.0(370)" ?>
+<?aid SnippetType="InCopyInterchange"?>
+<Document DOMVersion="8.0" Self="pandoc_doc">
+ <RootCharacterStyleGroup Self="pandoc_character_styles">
+ <CharacterStyle Self="$ID/NormalCharacterStyle" Name="Default" />
+ <CharacterStyle Self="CharacterStyle/Link" Name="Link">
+ <Properties>
+ <BasedOn type="object">$ID/NormalCharacterStyle</BasedOn>
+ </Properties>
+ </CharacterStyle>
+ </RootCharacterStyleGroup>
+ <RootParagraphStyleGroup Self="pandoc_paragraph_styles">
+ <ParagraphStyle Self="$ID/NormalParagraphStyle" Name="$ID/NormalParagraphStyle"
+ SpaceBefore="6" SpaceAfter="6"> <!-- paragraph spacing -->
+ <Properties>
+ <TabList type="list">
+ <ListItem type="record">
+ <Alignment type="enumeration">LeftAlign</Alignment>
+ <AlignmentCharacter type="string">.</AlignmentCharacter>
+ <Leader type="string"></Leader>
+ <Position type="unit">10</Position> <!-- first tab stop -->
+ </ListItem>
+ </TabList>
+ </Properties>
+ </ParagraphStyle>
+ <ParagraphStyle Self="ParagraphStyle/Header1" Name="Header1" LeftIndent="0" PointSize="36">
+ <Properties>
+ <BasedOn type="object">$ID/NormalParagraphStyle</BasedOn>
+ </Properties>
+ </ParagraphStyle>
+ <ParagraphStyle Self="ParagraphStyle/Header2" Name="Header2" LeftIndent="0" PointSize="30">
+ <Properties>
+ <BasedOn type="object">$ID/NormalParagraphStyle</BasedOn>
+ </Properties>
+ </ParagraphStyle>
+ <ParagraphStyle Self="ParagraphStyle/Paragraph" Name="Paragraph" LeftIndent="0">
+ <Properties>
+ <BasedOn type="object">$ID/NormalParagraphStyle</BasedOn>
+ </Properties>
+ </ParagraphStyle>
+ </RootParagraphStyleGroup>
+ <RootTableStyleGroup Self="pandoc_table_styles">
+ <TableStyle Self="TableStyle/Table" Name="Table" />
+ </RootTableStyleGroup>
+ <RootCellStyleGroup Self="pandoc_cell_styles">
+ <CellStyle Self="CellStyle/Cell" AppliedParagraphStyle="ParagraphStyle/$ID/[No paragraph style]" Name="Cell" />
+ </RootCellStyleGroup>
+ <Story Self="pandoc_story"
+ TrackChanges="false"
+ StoryTitle=""
+ AppliedTOCStyle="n"
+ AppliedNamedGrid="n" >
+ <StoryPreference OpticalMarginAlignment="true" OpticalMarginSize="12" />
+
+<!-- body needs to be non-indented, otherwise code blocks are indented too far -->
+<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Header1">
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <HyperlinkTextDestination Self="HyperlinkTextDestination/#header-1" Name="Destination" DestinationUniqueKey="1" />
+ <Content>Header 1</Content>
+ </CharacterStyleRange>
+</ParagraphStyleRange>
+<Br />
+<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Paragraph">
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <Content>this is some text</Content>
+ </CharacterStyleRange>
+</ParagraphStyleRange>
+<Br />
+<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Header2">
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <HyperlinkTextDestination Self="HyperlinkTextDestination/#header-2" Name="Destination" DestinationUniqueKey="1" />
+ <Content>Header 2</Content>
+ </CharacterStyleRange>
+</ParagraphStyleRange>
+<Br />
+<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Paragraph">
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <Content>some more text that </Content>
+ </CharacterStyleRange>
+ <HyperlinkTextSource Self="htss-1" Name="" Hidden="false">
+ <CharacterStyleRange AppliedCharacterStyle="CharacterStyle/Link">
+ <Content>links to</Content>
+ </CharacterStyleRange>
+ </HyperlinkTextSource>
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <Content> the first header. And this links to </Content>
+ </CharacterStyleRange>
+ <HyperlinkTextSource Self="htss-2" Name="" Hidden="false">
+ <CharacterStyleRange AppliedCharacterStyle="CharacterStyle/Link">
+ <Content>some text</Content>
+ </CharacterStyleRange>
+ </HyperlinkTextSource>
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <Content> in 2.1.</Content>
+ </CharacterStyleRange>
+</ParagraphStyleRange>
+<Br />
+<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Header2">
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <HyperlinkTextDestination Self="HyperlinkTextDestination/#header-2.1" Name="Destination" DestinationUniqueKey="1" />
+ <Content>Header 2.1</Content>
+ </CharacterStyleRange>
+</ParagraphStyleRange>
+<Br />
+<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Paragraph">
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <Content>if you can read this text, </Content>
+ </CharacterStyleRange>
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <HyperlinkTextDestination Self="HyperlinkTextDestination/#spanner" Name="Destination" DestinationUniqueKey="1" />
+ <Content>and it’s linked</Content>
+ </CharacterStyleRange>
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <Content> - all good!</Content>
+ </CharacterStyleRange>
+</ParagraphStyleRange>
+
+ </Story>
+ <Hyperlink Self="uf-2" Name="#spanner" Source="htss-2" Visible="false" DestinationUniqueKey="1">
+ <Properties>
+ <BorderColor type="enumeration">Black</BorderColor>
+ <Destination type="object">HyperlinkTextDestination/#spanner</Destination>
+ </Properties>
+ </Hyperlink>
+ <Hyperlink Self="uf-1" Name="#header-1" Source="htss-1" Visible="false" DestinationUniqueKey="1">
+ <Properties>
+ <BorderColor type="enumeration">Black</BorderColor>
+ <Destination type="object">HyperlinkTextDestination/#header-1</Destination>
+ </Properties>
+ </Hyperlink>
+</Document>
+```
diff --git a/documents/markdown/pandoc-md/5541-nesting.md b/documents/markdown/pandoc-md/5541-nesting.md
new file mode 100644
index 0000000..5abe41a
--- /dev/null
+++ b/documents/markdown/pandoc-md/5541-nesting.md
@@ -0,0 +1,98 @@
+```
+% pandoc -f html -t icml -s
+
+<div id="blockId">
+ <div id="blockId2">
+ <span id="inlineId">
+ <img id="inlineId2" src="lalune.jpg" />
+ </span>
+ </div>
+</div>
+
+^D
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<?aid style="50" type="snippet" readerVersion="6.0" featureSet="513" product="8.0(370)" ?>
+<?aid SnippetType="InCopyInterchange"?>
+<Document DOMVersion="8.0" Self="pandoc_doc">
+ <RootCharacterStyleGroup Self="pandoc_character_styles">
+ <CharacterStyle Self="$ID/NormalCharacterStyle" Name="Default" />
+ <CharacterStyle Self="CharacterStyle/" Name="">
+ <Properties>
+ <BasedOn type="object">$ID/NormalCharacterStyle</BasedOn>
+ </Properties>
+ </CharacterStyle>
+ </RootCharacterStyleGroup>
+ <RootParagraphStyleGroup Self="pandoc_paragraph_styles">
+ <ParagraphStyle Self="$ID/NormalParagraphStyle" Name="$ID/NormalParagraphStyle"
+ SpaceBefore="6" SpaceAfter="6"> <!-- paragraph spacing -->
+ <Properties>
+ <TabList type="list">
+ <ListItem type="record">
+ <Alignment type="enumeration">LeftAlign</Alignment>
+ <AlignmentCharacter type="string">.</AlignmentCharacter>
+ <Leader type="string"></Leader>
+ <Position type="unit">10</Position> <!-- first tab stop -->
+ </ListItem>
+ </TabList>
+ </Properties>
+ </ParagraphStyle>
+ <ParagraphStyle Self="ParagraphStyle/" Name="" LeftIndent="0">
+ <Properties>
+ <BasedOn type="object">$ID/NormalParagraphStyle</BasedOn>
+ </Properties>
+ </ParagraphStyle>
+ </RootParagraphStyleGroup>
+ <RootTableStyleGroup Self="pandoc_table_styles">
+ <TableStyle Self="TableStyle/Table" Name="Table" />
+ </RootTableStyleGroup>
+ <RootCellStyleGroup Self="pandoc_cell_styles">
+ <CellStyle Self="CellStyle/Cell" AppliedParagraphStyle="ParagraphStyle/$ID/[No paragraph style]" Name="Cell" />
+ </RootCellStyleGroup>
+ <Story Self="pandoc_story"
+ TrackChanges="false"
+ StoryTitle=""
+ AppliedTOCStyle="n"
+ AppliedNamedGrid="n" >
+ <StoryPreference OpticalMarginAlignment="true" OpticalMarginSize="12" />
+
+<!-- body needs to be non-indented, otherwise code blocks are indented too far -->
+<ParagraphStyleRange AppliedParagraphStyle="">
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <HyperlinkTextDestination Self="HyperlinkTextDestination/#inlineId" Name="Destination" DestinationUniqueKey="1" />
+ <Content> </Content>
+ </CharacterStyleRange>
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <Rectangle Self="uec" StrokeWeight="0" ItemTransform="1 0 0 1 75 -75">
+ <Properties>
+ <PathGeometry>
+ <GeometryPathType PathOpen="false">
+ <PathPointArray>
+ <PathPointType Anchor="-75 -75" LeftDirection="-75 -75" RightDirection="-75 -75" />
+ <PathPointType Anchor="-75 75" LeftDirection="-75 75" RightDirection="-75 75" />
+ <PathPointType Anchor="75 75" LeftDirection="75 75" RightDirection="75 75" />
+ <PathPointType Anchor="75 -75" LeftDirection="75 -75" RightDirection="75 -75" />
+ </PathPointArray>
+ </GeometryPathType>
+ </PathGeometry>
+ </Properties>
+ <Image Self="ue6" ItemTransform="1 0 0 1 -75 -75">
+ <Properties>
+ <Profile type="string">
+ $ID/Embedded
+ </Profile>
+ <GraphicBounds Left="0" Top="0" Right="150" Bottom="150" />
+ </Properties>
+ <Link Self="ueb" LinkResourceURI="file:lalune.jpg" />
+ </Image>
+ </Rectangle>
+ </CharacterStyleRange>
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <HyperlinkTextDestination Self="HyperlinkTextDestination/#inlineId" Name="Destination" DestinationUniqueKey="1" />
+ <Content> </Content>
+ </CharacterStyleRange>
+</ParagraphStyleRange>
+
+ </Story>
+
+</Document>
+```
diff --git a/documents/markdown/pandoc-md/5541-urlLink.md b/documents/markdown/pandoc-md/5541-urlLink.md
new file mode 100644
index 0000000..453653f
--- /dev/null
+++ b/documents/markdown/pandoc-md/5541-urlLink.md
@@ -0,0 +1,112 @@
+```
+% pandoc -f markdown -t icml -s
+
+# Header 1
+
+this is some text
+
+## Header 2
+
+some more text that [links to](https://www.pandoc.org) Pandoc.
+
+^D
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<?aid style="50" type="snippet" readerVersion="6.0" featureSet="513" product="8.0(370)" ?>
+<?aid SnippetType="InCopyInterchange"?>
+<Document DOMVersion="8.0" Self="pandoc_doc">
+ <RootCharacterStyleGroup Self="pandoc_character_styles">
+ <CharacterStyle Self="$ID/NormalCharacterStyle" Name="Default" />
+ <CharacterStyle Self="CharacterStyle/Link" Name="Link">
+ <Properties>
+ <BasedOn type="object">$ID/NormalCharacterStyle</BasedOn>
+ </Properties>
+ </CharacterStyle>
+ </RootCharacterStyleGroup>
+ <RootParagraphStyleGroup Self="pandoc_paragraph_styles">
+ <ParagraphStyle Self="$ID/NormalParagraphStyle" Name="$ID/NormalParagraphStyle"
+ SpaceBefore="6" SpaceAfter="6"> <!-- paragraph spacing -->
+ <Properties>
+ <TabList type="list">
+ <ListItem type="record">
+ <Alignment type="enumeration">LeftAlign</Alignment>
+ <AlignmentCharacter type="string">.</AlignmentCharacter>
+ <Leader type="string"></Leader>
+ <Position type="unit">10</Position> <!-- first tab stop -->
+ </ListItem>
+ </TabList>
+ </Properties>
+ </ParagraphStyle>
+ <ParagraphStyle Self="ParagraphStyle/Header1" Name="Header1" LeftIndent="0" PointSize="36">
+ <Properties>
+ <BasedOn type="object">$ID/NormalParagraphStyle</BasedOn>
+ </Properties>
+ </ParagraphStyle>
+ <ParagraphStyle Self="ParagraphStyle/Header2" Name="Header2" LeftIndent="0" PointSize="30">
+ <Properties>
+ <BasedOn type="object">$ID/NormalParagraphStyle</BasedOn>
+ </Properties>
+ </ParagraphStyle>
+ <ParagraphStyle Self="ParagraphStyle/Paragraph" Name="Paragraph" LeftIndent="0">
+ <Properties>
+ <BasedOn type="object">$ID/NormalParagraphStyle</BasedOn>
+ </Properties>
+ </ParagraphStyle>
+ </RootParagraphStyleGroup>
+ <RootTableStyleGroup Self="pandoc_table_styles">
+ <TableStyle Self="TableStyle/Table" Name="Table" />
+ </RootTableStyleGroup>
+ <RootCellStyleGroup Self="pandoc_cell_styles">
+ <CellStyle Self="CellStyle/Cell" AppliedParagraphStyle="ParagraphStyle/$ID/[No paragraph style]" Name="Cell" />
+ </RootCellStyleGroup>
+ <Story Self="pandoc_story"
+ TrackChanges="false"
+ StoryTitle=""
+ AppliedTOCStyle="n"
+ AppliedNamedGrid="n" >
+ <StoryPreference OpticalMarginAlignment="true" OpticalMarginSize="12" />
+
+<!-- body needs to be non-indented, otherwise code blocks are indented too far -->
+<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Header1">
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <HyperlinkTextDestination Self="HyperlinkTextDestination/#header-1" Name="Destination" DestinationUniqueKey="1" />
+ <Content>Header 1</Content>
+ </CharacterStyleRange>
+</ParagraphStyleRange>
+<Br />
+<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Paragraph">
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <Content>this is some text</Content>
+ </CharacterStyleRange>
+</ParagraphStyleRange>
+<Br />
+<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Header2">
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <HyperlinkTextDestination Self="HyperlinkTextDestination/#header-2" Name="Destination" DestinationUniqueKey="1" />
+ <Content>Header 2</Content>
+ </CharacterStyleRange>
+</ParagraphStyleRange>
+<Br />
+<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Paragraph">
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <Content>some more text that </Content>
+ </CharacterStyleRange>
+ <HyperlinkTextSource Self="htss-1" Name="" Hidden="false">
+ <CharacterStyleRange AppliedCharacterStyle="CharacterStyle/Link">
+ <Content>links to</Content>
+ </CharacterStyleRange>
+ </HyperlinkTextSource>
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <Content> Pandoc.</Content>
+ </CharacterStyleRange>
+</ParagraphStyleRange>
+
+ </Story>
+ <HyperlinkURLDestination Self="HyperlinkURLDestination/https%3a//www.pandoc.org" Name="link" DestinationURL="https://www.pandoc.org" DestinationUniqueKey="1" />
+ <Hyperlink Self="uf-1" Name="https://www.pandoc.org" Source="htss-1" Visible="false" DestinationUniqueKey="1">
+ <Properties>
+ <BorderColor type="enumeration">Black</BorderColor>
+ <Destination type="object">HyperlinkURLDestination/https%3a//www.pandoc.org</Destination>
+ </Properties>
+ </Hyperlink>
+</Document>
+```
diff --git a/documents/markdown/pandoc-md/5566.md b/documents/markdown/pandoc-md/5566.md
new file mode 100644
index 0000000..356a546
--- /dev/null
+++ b/documents/markdown/pandoc-md/5566.md
@@ -0,0 +1,6 @@
+```
+% pandoc -t asciidoc -f html
+fo<span class="c">o</span> f<span class="c">o</span>o <span class="c">f</span>oo <span class="c">foo</span>
+^D
+fo[.c]##o## f[.c]##o##o [.c]##f##oo [.c]#foo#
+```
diff --git a/documents/markdown/pandoc-md/5574.md b/documents/markdown/pandoc-md/5574.md
new file mode 100644
index 0000000..4d4c4ec
--- /dev/null
+++ b/documents/markdown/pandoc-md/5574.md
@@ -0,0 +1,7 @@
+No highlighting inside heading:
+```
+% pandoc -t latex
+# `foo`{.cpp}
+^D
+\section{\texorpdfstring{\texttt{foo}}{foo}}\label{foo}
+```
diff --git a/documents/markdown/pandoc-md/5619.md b/documents/markdown/pandoc-md/5619.md
new file mode 100644
index 0000000..7247ac5
--- /dev/null
+++ b/documents/markdown/pandoc-md/5619.md
@@ -0,0 +1,66 @@
+```
+% pandoc -f rst -t native
+.. figure:: img1.jpg
+ :width: 1in
+ :name: test
+
+ The caption. Here's what piggybacking on caption would look like {#fig:1}
+^D
+[ Figure
+ ( "" , [] , [] )
+ (Caption
+ Nothing
+ [ Plain
+ [ Str "The"
+ , Space
+ , Str "caption."
+ , Space
+ , Str "Here's"
+ , Space
+ , Str "what"
+ , Space
+ , Str "piggybacking"
+ , Space
+ , Str "on"
+ , Space
+ , Str "caption"
+ , Space
+ , Str "would"
+ , Space
+ , Str "look"
+ , Space
+ , Str "like"
+ , Space
+ , Str "{#fig:1}"
+ ]
+ ])
+ [ Plain
+ [ Image
+ ( "test" , [] , [ ( "width" , "1in" ) ] )
+ [ Str "The"
+ , Space
+ , Str "caption."
+ , Space
+ , Str "Here's"
+ , Space
+ , Str "what"
+ , Space
+ , Str "piggybacking"
+ , Space
+ , Str "on"
+ , Space
+ , Str "caption"
+ , Space
+ , Str "would"
+ , Space
+ , Str "look"
+ , Space
+ , Str "like"
+ , Space
+ , Str "{#fig:1}"
+ ]
+ ( "img1.jpg" , "" )
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/5620.md b/documents/markdown/pandoc-md/5620.md
new file mode 100644
index 0000000..64e931d
--- /dev/null
+++ b/documents/markdown/pandoc-md/5620.md
@@ -0,0 +1,9 @@
+```
+% pandoc -t man
+`-o`, `--output=`*OUTFILE*
+: Write output to *OUTFILE* instead of `stdout`(3)
+^D
+.TP
+\f[CR]\-o\f[R], \f[CR]\-\-output=\f[R]\f[I]OUTFILE\f[R]
+Write output to \f[I]OUTFILE\f[R] instead of \f[CR]stdout\f[R](3)
+```
diff --git a/documents/markdown/pandoc-md/5627.md b/documents/markdown/pandoc-md/5627.md
new file mode 100644
index 0000000..fde15fe
--- /dev/null
+++ b/documents/markdown/pandoc-md/5627.md
@@ -0,0 +1,87 @@
+```
+% pandoc -t html
+## Example
+
+1. One
+2. Two `-->something<!--`
+3. Three
+
+~~~html
+--><!--<script>alert('Escaped!')</script>
+~~~
+
+~~~html
+Something
+~~~
+^D
+<h2 id="example">Example</h2>
+<ol type="1">
+<li>One</li>
+<li>Two <code>-->something<!--</code></li>
+<li>Three</li>
+</ol>
+<div class="sourceCode" id="cb1"><pre
+class="sourceCode html"><code class="sourceCode html"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a>--><span class="co"><!--<script>alert('Escaped!')</script></span></span></code></pre></div>
+<div class="sourceCode" id="cb2"><pre
+class="sourceCode html"><code class="sourceCode html"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a>Something</span></code></pre></div>
+```
+
+```
+% pandoc -t html
+## Example 2
+
+- `-->something<!--`
+- `-->something<!--`
+- bye `-->something else<!--`
+
+~~~html
+--><!--<script>alert('Escaped!')</script>
+~~~
+
+~~~html
+Something
+~~~
+^D
+<h2 id="example-2">Example 2</h2>
+<ul>
+<li><code>-->something<!--</code></li>
+<li><code>-->something<!--</code></li>
+<li>bye <code>-->something else<!--</code></li>
+</ul>
+<div class="sourceCode" id="cb1"><pre
+class="sourceCode html"><code class="sourceCode html"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a>--><span class="co"><!--<script>alert('Escaped!')</script></span></span></code></pre></div>
+<div class="sourceCode" id="cb2"><pre
+class="sourceCode html"><code class="sourceCode html"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a>Something</span></code></pre></div>
+```
+
+```
+% pandoc -t html
+## Example 3
+
+1. `-->one<!--`
+5. bye `-->two <!--`
+3. ` three, not in block
+1. four, not in block `
+2. five
+5. six
+6. seven `
+- separate unordered list `
+42. forty-two, separate ordered list
+^D
+<h2 id="example-3">Example 3</h2>
+<ol type="1">
+<li><code>-->one<!--</code></li>
+<li>bye <code>-->two <!--</code></li>
+<li>` three, not in block</li>
+<li>four, not in block `</li>
+<li>five</li>
+<li>six</li>
+<li>seven `</li>
+</ol>
+<ul>
+<li>separate unordered list `</li>
+</ul>
+<ol start="42" type="1">
+<li>forty-two, separate ordered list</li>
+</ol>
+```
diff --git a/documents/markdown/pandoc-md/5635.md b/documents/markdown/pandoc-md/5635.md
new file mode 100644
index 0000000..7244061
--- /dev/null
+++ b/documents/markdown/pandoc-md/5635.md
@@ -0,0 +1,23 @@
+```
+% pandoc -f latex -t plain
+\providecommand{\test}{foo}
+\providecommand{\test}{bar}
+
+The value is: \test
+^D
+The value is: foo
+```
+
+```
+% pandoc -f latex -t plain
+\provideenvironment{test}{startfoo}{stopfoo}
+\provideenvironment{test}{startbar}{stopbar}
+
+\begin{test}
+Hi
+\end{test}
+^D
+startfoo Hi stopfoo
+```
+
+
diff --git a/documents/markdown/pandoc-md/5642.md b/documents/markdown/pandoc-md/5642.md
new file mode 100644
index 0000000..120a88a
--- /dev/null
+++ b/documents/markdown/pandoc-md/5642.md
@@ -0,0 +1,9 @@
+```
+% pandoc -t html5 -f markdown
+{aria-describedby="barbaz"}
+^D
+<figure>
+<img src="foo" aria-describedby="barbaz" alt="test" />
+<figcaption aria-hidden="true">test</figcaption>
+</figure>
+```
diff --git a/documents/markdown/pandoc-md/5650.md b/documents/markdown/pandoc-md/5650.md
new file mode 100644
index 0000000..c333d5b
--- /dev/null
+++ b/documents/markdown/pandoc-md/5650.md
@@ -0,0 +1,24 @@
+````
+% pandoc --id-prefix foo
+```haskell
+a
+b
+```
+^D
+<div class="sourceCode" id="foocb1"><pre
+class="sourceCode haskell"><code class="sourceCode haskell"><span id="foocb1-1"><a href="#foocb1-1" aria-hidden="true" tabindex="-1"></a>a</span>
+<span id="foocb1-2"><a href="#foocb1-2" aria-hidden="true" tabindex="-1"></a>b</span></code></pre></div>
+````
+
+````
+% pandoc --id-prefix foo
+``` {.haskell #bar}
+a
+b
+```
+^D
+<div class="sourceCode" id="foobar"><pre
+class="sourceCode haskell"><code class="sourceCode haskell"><span id="foobar-1"><a href="#foobar-1" aria-hidden="true" tabindex="-1"></a>a</span>
+<span id="foobar-2"><a href="#foobar-2" aria-hidden="true" tabindex="-1"></a>b</span></code></pre></div>
+````
+
diff --git a/documents/markdown/pandoc-md/5654.md b/documents/markdown/pandoc-md/5654.md
new file mode 100644
index 0000000..3905dca
--- /dev/null
+++ b/documents/markdown/pandoc-md/5654.md
@@ -0,0 +1,6 @@
+```
+% pandoc -f latex -t markdown
+This is {\tt monospaced too} done.
+^D
+This is `monospaced too` done.
+```
diff --git a/documents/markdown/pandoc-md/5655.md b/documents/markdown/pandoc-md/5655.md
new file mode 100644
index 0000000..e9fb1b6
--- /dev/null
+++ b/documents/markdown/pandoc-md/5655.md
@@ -0,0 +1,20 @@
+````
+% pandoc --webtex
+$T_n={n+1 \choose 2}$
+^D
+<p><img style="vertical-align:middle"
+src="https://latex.codecogs.com/png.latex?%5Ctextstyle%20T_n%3D%7Bn%2B1%20%5Cchoose%202%7D"
+alt="T_n={n+1 \choose 2}" title="T_n={n+1 \choose 2}"
+class="math inline" /></p>
+````
+
+````
+% pandoc --webtex
+$$T_n={n+1 \choose 2}$$
+^D
+<p><img style="vertical-align:middle"
+src="https://latex.codecogs.com/png.latex?%5Cdisplaystyle%20T_n%3D%7Bn%2B1%20%5Cchoose%202%7D"
+alt="T_n={n+1 \choose 2}" title="T_n={n+1 \choose 2}"
+class="math display" /></p>
+````
+
diff --git a/documents/markdown/pandoc-md/5682.md b/documents/markdown/pandoc-md/5682.md
new file mode 100644
index 0000000..3ce81af
--- /dev/null
+++ b/documents/markdown/pandoc-md/5682.md
@@ -0,0 +1,8 @@
+```
+% pandoc -t native -f latex
+\newcommand{\ittakestwo}[2][defaultone]{#2}
+\ittakestwo[to]{tango}
+^D
+[ Para [ Str "tango" ] ]
+```
+
diff --git a/documents/markdown/pandoc-md/5684.md b/documents/markdown/pandoc-md/5684.md
new file mode 100644
index 0000000..e723f75
--- /dev/null
+++ b/documents/markdown/pandoc-md/5684.md
@@ -0,0 +1,6 @@
+```
+% pandoc -f native -t latex
+[Str "\8222\8218Der",Space,Str "Erz\228hler.",Space,Str "Betrachtungen",Space,Str "zum",Space,Str "Werk",Space,Str "Nikolai",Space,Str "Lesskows\8216\8220."]
+^D
+„‚Der Erzähler. Betrachtungen zum Werk Nikolai Lesskows`\,``.
+```
diff --git a/documents/markdown/pandoc-md/5686.md b/documents/markdown/pandoc-md/5686.md
new file mode 100644
index 0000000..d669ae4
--- /dev/null
+++ b/documents/markdown/pandoc-md/5686.md
@@ -0,0 +1,31 @@
+```
+% pandoc -t native
+FOO\t0BAR
+
+This part does not make it to the html output.
+^D
+[ Para
+ [ Str "FOO" , RawInline (Format "tex") "\\t0" , Str "BAR" ]
+, Para
+ [ Str "This"
+ , Space
+ , Str "part"
+ , Space
+ , Str "does"
+ , Space
+ , Str "not"
+ , Space
+ , Str "make"
+ , Space
+ , Str "it"
+ , Space
+ , Str "to"
+ , Space
+ , Str "the"
+ , Space
+ , Str "html"
+ , Space
+ , Str "output."
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/5690.md b/documents/markdown/pandoc-md/5690.md
new file mode 100644
index 0000000..f51b3d1
--- /dev/null
+++ b/documents/markdown/pandoc-md/5690.md
@@ -0,0 +1,16 @@
+```
+% pandoc -f docbook -t asciidoc
+<warning>
+<title>My warning!</title>
+<para>A warning.</para>
+<para>Another paragraph.</para>
+</warning>
+^D
+[WARNING]
+.My warning!
+====
+A warning.
+
+Another paragraph.
+====
+```
diff --git a/documents/markdown/pandoc-md/5700.md b/documents/markdown/pandoc-md/5700.md
new file mode 100644
index 0000000..eae3663
--- /dev/null
+++ b/documents/markdown/pandoc-md/5700.md
@@ -0,0 +1,39 @@
+```
+% pandoc -t native -s --metadata-file command/5700-metadata-file-1.yml --metadata-file command/5700-metadata-file-2.yml
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "desc"
+ , MetaInlines
+ [ Str "Both"
+ , Space
+ , Str "of"
+ , Space
+ , Str "these"
+ , Space
+ , Str "files"
+ , Space
+ , Str "should"
+ , Space
+ , Str "be"
+ , Space
+ , Str "loaded."
+ ]
+ )
+ , ( "title"
+ , MetaInlines
+ [ Str "Multiple"
+ , Space
+ , Str "metadata"
+ , Space
+ , Str "files"
+ , Space
+ , Str "test"
+ ]
+ )
+ ]
+ }
+ []
+```
diff --git a/documents/markdown/pandoc-md/5705.md b/documents/markdown/pandoc-md/5705.md
new file mode 100644
index 0000000..a892399
--- /dev/null
+++ b/documents/markdown/pandoc-md/5705.md
@@ -0,0 +1,11 @@
+```
+% pandoc -f native -t markdown
+[OrderedList (8,UpperRoman,Period)
+ [[Plain [Str "Blah"]
+ ,BulletList
+ [[Plain [Str "Blah"]]]]]]
+^D
+VIII. Blah
+ - Blah
+```
+
diff --git a/documents/markdown/pandoc-md/5708.md b/documents/markdown/pandoc-md/5708.md
new file mode 100644
index 0000000..e97edcf
--- /dev/null
+++ b/documents/markdown/pandoc-md/5708.md
@@ -0,0 +1,37 @@
+```
+% pandoc -f rst -t native
++--------+----------------+
+| 123456 | :math:`a + b` |
++--------+----------------+
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidth 0.125 )
+ , ( AlignDefault , ColWidth 0.2361111111111111 )
+ ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "123456" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Math InlineMath "a + b" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
diff --git a/documents/markdown/pandoc-md/5711.md b/documents/markdown/pandoc-md/5711.md
new file mode 100644
index 0000000..1311730
--- /dev/null
+++ b/documents/markdown/pandoc-md/5711.md
@@ -0,0 +1,32 @@
+```
+% pandoc -t native -f latex
+\documentclass{article}
+\begin{document}
+\begin{tabular}{c}
+\parbox{2cm}{d\\e}
+\end{tabular}
+\end{document}
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignCenter , ColWidthDefault ) ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "d" , LineBreak , Str "e" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
diff --git a/documents/markdown/pandoc-md/5714.md b/documents/markdown/pandoc-md/5714.md
new file mode 100644
index 0000000..c874f1a
--- /dev/null
+++ b/documents/markdown/pandoc-md/5714.md
@@ -0,0 +1,16 @@
+```
+% pandoc -t native
+# hi _a
+b_
+
+# hi _c
+c
+^D
+[ Header
+ 1 ( "hi-_a" , [] , [] ) [ Str "hi" , Space , Str "_a" ]
+, Para [ Str "b_" ]
+, Header
+ 1 ( "hi-_c" , [] , [] ) [ Str "hi" , Space , Str "_c" ]
+, Para [ Str "c" ]
+]
+```
diff --git a/documents/markdown/pandoc-md/5740.md b/documents/markdown/pandoc-md/5740.md
new file mode 100644
index 0000000..a9fb3ad
--- /dev/null
+++ b/documents/markdown/pandoc-md/5740.md
@@ -0,0 +1,9 @@
+```
+% pandoc -t latex
+\newcommand\parenthesize[1][x]{(#1)}
+$\parenthesize$, $\parenthesize[y]$, $\parenthesize[\textsc{head}]$
+^D
+\newcommand\parenthesize[1][x]{(#1)}
+
+\((x)\), \((y)\), \((\textsc{head})\)
+```
diff --git a/documents/markdown/pandoc-md/5753.md b/documents/markdown/pandoc-md/5753.md
new file mode 100644
index 0000000..686c8f4
--- /dev/null
+++ b/documents/markdown/pandoc-md/5753.md
@@ -0,0 +1,19 @@
+```
+% pandoc -f rst -t native
+.. math::
+
+ q_3
+ + 4
+
+ - 5 +
+ q_5
+
+end
+^D
+[ Para
+ [ Math DisplayMath "q_3\n+ 4"
+ , Math DisplayMath "- 5 +\nq_5"
+ ]
+, Para [ Str "end" ]
+]
+```
diff --git a/documents/markdown/pandoc-md/5793.md b/documents/markdown/pandoc-md/5793.md
new file mode 100644
index 0000000..98e8cf8
--- /dev/null
+++ b/documents/markdown/pandoc-md/5793.md
@@ -0,0 +1,13 @@
+```
+% pandoc -f html -t djot
+You can use <abbr title="Cascading Style Sheets">CSS</abbr>
+^D
+You can use [CSS]{.abbr title="Cascading Style Sheets"}
+```
+
+```
+% pandoc -f djot -t html
+You can use [CSS]{.abbr title="Cascading Style Sheets"}
+^D
+<p>You can use <abbr title="Cascading Style Sheets">CSS</abbr></p>
+```
diff --git a/documents/markdown/pandoc-md/5795.md b/documents/markdown/pandoc-md/5795.md
new file mode 100644
index 0000000..ea0fcb6
--- /dev/null
+++ b/documents/markdown/pandoc-md/5795.md
@@ -0,0 +1,25 @@
+```
+% pandoc -f html -t html
+<dfn id="foo" title="bax"><span>foo</span></dfn>
+^D
+<dfn id="foo" title="bax"><span>foo</span></dfn>
+```
+
+```
+% pandoc -f html -t native
+<dfn id="foo" title="bax"><span>foo</span></dfn>
+^D
+[ Plain
+ [ Span
+ ( "foo" , [ "dfn" ] , [ ( "title" , "bax" ) ] )
+ [ Span ( "" , [] , [] ) [ Str "foo" ] ]
+ ]
+]
+```
+
+```
+% pandoc -f native -t html
+[Plain [Span ("foo",["dfn"],[("title","bax")]) [Span ("",[],[]) [Str "foo"]]]]
+^D
+<dfn id="foo" title="bax"><span>foo</span></dfn>
+```
diff --git a/documents/markdown/pandoc-md/5797.md b/documents/markdown/pandoc-md/5797.md
new file mode 100644
index 0000000..4be51c6
--- /dev/null
+++ b/documents/markdown/pandoc-md/5797.md
@@ -0,0 +1,20 @@
+```
+% pandoc -f html -t html
+<mark>Ctrl-C</mark>
+^D
+<mark>Ctrl-C</mark>
+```
+
+```
+% pandoc -f html -t native
+<mark>Ctrl-C</mark>
+^D
+[ Plain [ Span ( "" , [ "mark" ] , [] ) [ Str "Ctrl-C" ] ] ]
+```
+
+```
+% pandoc -f native -t html
+[Plain [Span ("",["mark"],[]) [Str "Ctrl-C"]]]
+^D
+<mark>Ctrl-C</mark>
+```
diff --git a/documents/markdown/pandoc-md/5805.md b/documents/markdown/pandoc-md/5805.md
new file mode 100644
index 0000000..03c72bd
--- /dev/null
+++ b/documents/markdown/pandoc-md/5805.md
@@ -0,0 +1,20 @@
+```
+% pandoc -f html -t html
+<kbd>Ctrl-C</kbd>
+^D
+<kbd>Ctrl-C</kbd>
+```
+
+```
+% pandoc -f html -t native
+<kbd>Ctrl-C</kbd>
+^D
+[ Plain [ Span ( "" , [ "kbd" ] , [] ) [ Str "Ctrl-C" ] ] ]
+```
+
+```
+% pandoc -f native -t html
+[Plain [Span ("",["kbd"],[]) [Str "Ctrl-C"]]]
+^D
+<kbd>Ctrl-C</kbd>
+```
diff --git a/documents/markdown/pandoc-md/5813.md b/documents/markdown/pandoc-md/5813.md
new file mode 100644
index 0000000..51f7745
--- /dev/null
+++ b/documents/markdown/pandoc-md/5813.md
@@ -0,0 +1,7 @@
+```
+% pandoc -f gfm
+### Jekyll Plugins & Gems :gem:
+^D
+<h3 id="jekyll-plugins--gems-gem">Jekyll Plugins & Gems <span
+class="emoji" data-emoji="gem">💎</span></h3>
+```
diff --git a/documents/markdown/pandoc-md/5819.md b/documents/markdown/pandoc-md/5819.md
new file mode 100644
index 0000000..235d783
--- /dev/null
+++ b/documents/markdown/pandoc-md/5819.md
@@ -0,0 +1,18 @@
+```
+% pandoc -t revealjs --slide-level=2
+# Heading
+
+one
+
+. . .
+
+two
+^D
+<section id="heading" class="title-slide slide level1">
+<h1>Heading</h1>
+<p>one</p>
+<div class="fragment">
+<p>two</p>
+</div>
+</section>
+```
diff --git a/documents/markdown/pandoc-md/5836.md b/documents/markdown/pandoc-md/5836.md
new file mode 100644
index 0000000..6fe1539
--- /dev/null
+++ b/documents/markdown/pandoc-md/5836.md
@@ -0,0 +1,27 @@
+```
+% pandoc -f markdown -t latex
+\newcommand{\vara}{\alpha}
+\newcommand{\varb}{b}
+$\vara \varb$
+^D
+\newcommand{\vara}{\alpha}
+\newcommand{\varb}{b}
+
+\(\alpha b\)
+```
+```
+% pandoc -f latex -t latex
+\newcommand{\vara}{\alpha}
+\newcommand{\varb}{b}
+$\vara \varb$
+^D
+\(\alpha b\)
+```
+```
+% pandoc -f latex -t latex
+\newcommand{\vara}{\alpha}
+\newcommand{\varb}{b}
+\[\vara \varb\]
+^D
+\[\alpha b\]
+```
diff --git a/documents/markdown/pandoc-md/5845.md b/documents/markdown/pandoc-md/5845.md
new file mode 100644
index 0000000..aac73cf
--- /dev/null
+++ b/documents/markdown/pandoc-md/5845.md
@@ -0,0 +1,25 @@
+```
+% pandoc -t native
+\parbox{1em}{#1}
+^D
+[ Para [ Str "\\parbox{1em}{#1}" ] ]
+```
+
+```
+% pandoc -t native
+\newcommand{\highlight}[1]{\colorbox{yellow}{\parbox{\dimexpr\linewidth-2\fboxsep}{#1}}
+
+Hello World
+^D
+[ Para
+ [ Str "\\newcommand{"
+ , RawInline (Format "tex") "\\highlight"
+ , Str "}[1]{\\colorbox{yellow}{\\parbox{"
+ , RawInline (Format "tex") "\\dimexpr"
+ , RawInline (Format "tex") "\\linewidth-2"
+ , RawInline (Format "tex") "\\fboxsep"
+ , Str "}{#1}}"
+ ]
+, Para [ Str "Hello" , Space , Str "World" ]
+]
+```
diff --git a/documents/markdown/pandoc-md/5846.md b/documents/markdown/pandoc-md/5846.md
new file mode 100644
index 0000000..ec00074
--- /dev/null
+++ b/documents/markdown/pandoc-md/5846.md
@@ -0,0 +1,170 @@
+```
+% pandoc --section-divs
+::: {.mydiv}
+# header 1a
+
+one
+
+# header 1b
+
+two
+:::
+^D
+<div class="mydiv">
+<section id="header-1a" class="level1">
+<h1>header 1a</h1>
+<p>one</p>
+</section>
+<section id="header-1b" class="level1">
+<h1>header 1b</h1>
+<p>two</p>
+</section>
+</div>
+```
+
+```
+% pandoc --section-divs
+::: mydiv
+# head 1
+## head 1.1
+# head 2
+:::
+
+## head 2.1
+^D
+<div class="mydiv">
+<section id="head-1" class="level1">
+<h1>head 1</h1>
+<section id="head-1.1" class="level2">
+<h2>head 1.1</h2>
+</section>
+</section>
+<section id="head-2" class="level1">
+<h1>head 2</h1>
+</section>
+</div>
+<section id="head-2.1" class="level2">
+<h2>head 2.1</h2>
+</section>
+```
+
+```
+% pandoc --section-divs
+# One
+## One A
+::: fence
+## One B
+# Two
+:::
+^D
+<section id="one" class="level1">
+<h1>One</h1>
+<section id="one-a" class="level2">
+<h2>One A</h2>
+</section>
+<div class="fence">
+<section id="one-b" class="level2">
+<h2>One B</h2>
+</section>
+<section id="two" class="level1">
+<h1>Two</h1>
+</section>
+</div>
+</section>
+```
+
+```
+% pandoc --section-divs
+# Beginning
+
+::: exterior
+
+At first...
+
+:::
+
+In the beginning...
+
+::: interior
+
+# Middle
+
+So it continued...
+
+:::
+
+# Ending
+
+::: exterior
+
+And finally...
+
+:::
+^D
+<section id="beginning" class="level1">
+<h1>Beginning</h1>
+<div class="exterior">
+<p>At first…</p>
+</div>
+<p>In the beginning…</p>
+</section>
+<section id="middle" class="level1 interior">
+<h1>Middle</h1>
+<p>So it continued…</p>
+</section>
+<section id="ending" class="level1">
+<h1>Ending</h1>
+<div class="exterior">
+<p>And finally…</p>
+</div>
+</section>
+```
+
+```
+% pandoc --section-divs
+::: part
+# One
+# Two
+:::
+::: part
+# Three
+# Four
+# Five
+:::
+::: part
+# Six
+# Seven
+# Eight
+:::
+^D
+<div class="part">
+<section id="one" class="level1">
+<h1>One</h1>
+</section>
+<section id="two" class="level1">
+<h1>Two</h1>
+</section>
+</div>
+<div class="part">
+<section id="three" class="level1">
+<h1>Three</h1>
+</section>
+<section id="four" class="level1">
+<h1>Four</h1>
+</section>
+<section id="five" class="level1">
+<h1>Five</h1>
+</section>
+</div>
+<div class="part">
+<section id="six" class="level1">
+<h1>Six</h1>
+</section>
+<section id="seven" class="level1">
+<h1>Seven</h1>
+</section>
+<section id="eight" class="level1">
+<h1>Eight</h1>
+</section>
+</div>
+```
diff --git a/documents/markdown/pandoc-md/5849-prefix.md b/documents/markdown/pandoc-md/5849-prefix.md
new file mode 100644
index 0000000..fe34820
--- /dev/null
+++ b/documents/markdown/pandoc-md/5849-prefix.md
@@ -0,0 +1,31 @@
+```
+% pandoc -t latex --biblatex
+[e.g. @a1;@a2;@a3; but also @b1;@b2;@b3]
+^D
+\autocites[e.g.][]{a1,a2,a3}[but also][]{b1,b2,b3}
+```
+```
+% pandoc -t latex --biblatex
+[e.g. @a1; e.g. @a2;@a3; but also @b1;@b2;but also @b3]
+^D
+\autocites[e.g.][]{a1}[e.g.][]{a2,a3}[but also][]{b1,b2}[but also][]{b3}
+```
+```
+% pandoc -t latex --biblatex
+[e.g. @a1, ch.3 and elsewhere;@a2;@a3; but also @a4;@a5]
+^D
+\autocites[e.g.][ch.3 and elsewhere]{a1}{a2,a3}[but also][]{a4,a5}
+```
+```
+% pandoc -t latex --biblatex
+[e.g. @a1;@a2, ch.3 and elsewhere;@a3; but also @a4;@a5]
+^D
+\autocites[e.g.][]{a1}[ch.3 and elsewhere]{a2}{a3}[but also][]{a4,a5}
+```
+```
+% pandoc -t latex --biblatex
+[e.g. @a1, blah;@a2, ch.3 and elsewhere;@a3; but also @b4;@b5]
+^D
+\autocites[e.g.][blah]{a1}[ch.3 and elsewhere]{a2}{a3}[but
+also][]{b4,b5}
+```
diff --git a/documents/markdown/pandoc-md/5857.md b/documents/markdown/pandoc-md/5857.md
new file mode 100644
index 0000000..5f15ce3
--- /dev/null
+++ b/documents/markdown/pandoc-md/5857.md
@@ -0,0 +1,11 @@
+```
+% pandoc -f native -t markdown
+[BulletList
+ [[Plain [Str "a"]]
+ ,[]
+ ,[Plain [Str "b"]]]]
+^D
+- a
+-
+- b
+```
diff --git a/documents/markdown/pandoc-md/5876.md b/documents/markdown/pandoc-md/5876.md
new file mode 100644
index 0000000..a8ede18
--- /dev/null
+++ b/documents/markdown/pandoc-md/5876.md
@@ -0,0 +1,60 @@
+```
+% pandoc -s -t native --data-dir=command/5876 --metadata-file=5876.yaml
+Hello
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "desc"
+ , MetaInlines
+ [ Str "Found"
+ , Space
+ , Str "in"
+ , Space
+ , Str "metadata"
+ , Space
+ , Str "directory."
+ ]
+ )
+ ]
+ }
+ [ Para [ Str "Hello" ] ]
+```
+```
+% pandoc -s -t native --data-dir=command/5876 --metadata-file=command/5876.yaml
+Hello
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "desc"
+ , MetaInlines
+ [ Str "Found"
+ , Space
+ , Str "in"
+ , Space
+ , Str "working"
+ , Space
+ , Str "directory."
+ ]
+ )
+ ]
+ }
+ [ Para [ Str "Hello" ] ]
+```
+```
+% pandoc -s -t native --data-dir=command/5876 --metadata-file=does-not-exist.yaml
+Hello
+^D
+2> Could not find metadata file does-not-exist.yaml
+=> 98
+```
+```
+% pandoc -s -t native --metadata-file=does-not-exist.yaml
+Hello
+^D
+2> Could not find metadata file does-not-exist.yaml
+=> 98
+```
diff --git a/documents/markdown/pandoc-md/5878.md b/documents/markdown/pandoc-md/5878.md
new file mode 100644
index 0000000..06ff29b
--- /dev/null
+++ b/documents/markdown/pandoc-md/5878.md
@@ -0,0 +1,15 @@
+```
+% pandoc -t native
+Zozime^[],
+Synésius^[]
+^D
+[ Para
+ [ Str "Zozime"
+ , Note [ Para [] ]
+ , Str ","
+ , SoftBreak
+ , Str "Syn\233sius"
+ , Note [ Para [] ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/5881.md b/documents/markdown/pandoc-md/5881.md
new file mode 100644
index 0000000..e291669
--- /dev/null
+++ b/documents/markdown/pandoc-md/5881.md
@@ -0,0 +1,14 @@
+```
+% pandoc -t markdown -s -H command/D.txt -d command/defaults1.yaml -d command/defaults2.yaml
+Ok
+^D
+here's d
+
+this is a
+
+here is b
+
+and this is c
+
+Ok
+```
diff --git a/documents/markdown/pandoc-md/5885.md b/documents/markdown/pandoc-md/5885.md
new file mode 100644
index 0000000..451929b
--- /dev/null
+++ b/documents/markdown/pandoc-md/5885.md
@@ -0,0 +1,20 @@
+```
+% pandoc -f docbook -t latex
+<equation>
+ <mathphrase>
+ J(x, y) = \left\{ \begin{array}{ll}
+ 0 & \text{if $I(x, y) < t$} \\
+ 1 & \text{if $I(x, y) \ge t$}
+ \end{array}
+ \right.
+ </mathphrase>
+</equation>
+^D
+\[
+ J(x, y) = \left\{ \begin{array}{ll}
+ 0 & \text{if $I(x, y) < t$} \\
+ 1 & \text{if $I(x, y) \ge t$}
+ \end{array}
+ \right.
+ \]
+```
diff --git a/documents/markdown/pandoc-md/5898.md b/documents/markdown/pandoc-md/5898.md
new file mode 100644
index 0000000..9d5c8ec
--- /dev/null
+++ b/documents/markdown/pandoc-md/5898.md
@@ -0,0 +1,36 @@
+```
+% pandoc -f html -t rst
+<html>
+ <body>
+ <ul>
+ <li>A list of stuff with a table inside
+ <table>
+ <thead>
+ <tr>
+ <th>First</th><th>Second</th><th>Third</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>First</td>
+ <td>Second</td>
+ <td>Third</td>
+ </tr>
+ </tbody>
+ </table>
+ </li>
+ <li>Another list item</li>
+ </ul>
+ </body>
+</html>
+^D
+- A list of stuff with a table inside
+
+ ===== ====== =====
+ First Second Third
+ ===== ====== =====
+ First Second Third
+ ===== ====== =====
+
+- Another list item
+```
diff --git a/documents/markdown/pandoc-md/5899.md b/documents/markdown/pandoc-md/5899.md
new file mode 100644
index 0000000..2382a9c
--- /dev/null
+++ b/documents/markdown/pandoc-md/5899.md
@@ -0,0 +1,51 @@
+```
+% pandoc -f html -t rst
+<html>
+ <body>
+ <ul>
+ <li>A list of stuff with a table inside
+ <table>
+ <thead>
+ <tr>
+ <th>First</th><th>Second</th><th>Third</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>First</td>
+ <td>
+ The big long table cell.
+ The big long table cell.
+ The big long table cell.
+ The big long table cell.
+ The big long table cell.
+ The big long table cell.
+ The big long table cell.
+ The big long table cell.
+ The big long table cell.
+ The big long table cell.
+ </td>
+ <td>Third</td>
+ </tr>
+ </tbody>
+ </table>
+ </li>
+ <li>Another list item</li>
+ </ul>
+ </body>
+</html>
+^D
+- A list of stuff with a table inside
+
+ +-------+------------------------------------------------------+-------+
+ | First | Second | Third |
+ +=======+======================================================+=======+
+ | First | The big long table cell. The big long table cell. | Third |
+ | | The big long table cell. The big long table cell. | |
+ | | The big long table cell. The big long table cell. | |
+ | | The big long table cell. The big long table cell. | |
+ | | The big long table cell. The big long table cell. | |
+ +-------+------------------------------------------------------+-------+
+
+- Another list item
+ ```
diff --git a/documents/markdown/pandoc-md/5904.md b/documents/markdown/pandoc-md/5904.md
new file mode 100644
index 0000000..9c94eec
--- /dev/null
+++ b/documents/markdown/pandoc-md/5904.md
@@ -0,0 +1,10 @@
+```
+% pandoc -s -t markdown -H command/B.txt --variable header-includes:foo
+Hi
+^D
+foo
+
+here is b
+
+Hi
+```
diff --git a/documents/markdown/pandoc-md/5936.md b/documents/markdown/pandoc-md/5936.md
new file mode 100644
index 0000000..6ad4e83
--- /dev/null
+++ b/documents/markdown/pandoc-md/5936.md
@@ -0,0 +1,40 @@
+```
+% pandoc -f gfm -t rst
+| Name |
+| ---- |
+| Foo |
+| Bar |
+| Baz |
+| Quux |
+^D
++------+
+| Name |
++======+
+| Foo |
++------+
+| Bar |
++------+
+| Baz |
++------+
+| Quux |
++------+
+```
+
+```
+% pandoc -f gfm -t rst
+| Name | Number |
+| ---- | ------ |
+| Foo | 3 |
+| Bar | 4 |
+| Baz | 2 |
+| Quux | 1 |
+^D
+==== ======
+Name Number
+==== ======
+Foo 3
+Bar 4
+Baz 2
+Quux 1
+==== ======
+```
diff --git a/documents/markdown/pandoc-md/5967.md b/documents/markdown/pandoc-md/5967.md
new file mode 100644
index 0000000..fb4e63e
--- /dev/null
+++ b/documents/markdown/pandoc-md/5967.md
@@ -0,0 +1,15 @@
+```
+% pandoc --toc --toc-depth=3 -s -t plain
+# One
+## Two
+#### Four
+^D
+- One
+ - Two
+
+One
+
+Two
+
+Four
+```
diff --git a/documents/markdown/pandoc-md/5986.md b/documents/markdown/pandoc-md/5986.md
new file mode 100644
index 0000000..648ae8f
--- /dev/null
+++ b/documents/markdown/pandoc-md/5986.md
@@ -0,0 +1,18 @@
+```
+% pandoc -t epub --number-sections --toc --metadata title=Foo -o - | pandoc -f epub -t html
+# Hi
+^D
+<p><span id="title_page.xhtml"></span></p>
+<p><span id="nav.xhtml"></span></p>
+<nav epub:type="landmarks" id="landmarks" hidden="hidden">
+<ol>
+<li><a href="text/title_page.xhtml" class="titlepage">Title
+Page</a></li>
+<li><a href="#nav.xhtml_toc" class="toc">Table of Contents</a></li>
+</ol>
+</nav>
+<p><span id="ch001.xhtml"></span></p>
+<section id="ch001.xhtml_hi" class="level1" data-number="1">
+<h1 data-number="1"><span class="header-section-number">1</span> Hi</h1>
+</section>
+```
diff --git a/documents/markdown/pandoc-md/6009.md b/documents/markdown/pandoc-md/6009.md
new file mode 100644
index 0000000..b2785dd
--- /dev/null
+++ b/documents/markdown/pandoc-md/6009.md
@@ -0,0 +1,19 @@
+```
+% pandoc -t native
+ <tr>
+ <td>
+ </td>
+ </tr>
+
+x
+
+ y
+^D
+[ RawBlock (Format "html") "<tr>"
+, RawBlock (Format "html") "<td>"
+, RawBlock (Format "html") "</td>"
+, RawBlock (Format "html") "</tr>"
+, Para [ Str "x" ]
+, CodeBlock ( "" , [] , [] ) "y"
+]
+```
diff --git a/documents/markdown/pandoc-md/6021.md b/documents/markdown/pandoc-md/6021.md
new file mode 100644
index 0000000..d7e7e3c
--- /dev/null
+++ b/documents/markdown/pandoc-md/6021.md
@@ -0,0 +1,54 @@
+```
+% pandoc -t native
+Oxide 石英
+------- ------
+SiO2 100
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignLeft , ColWidthDefault )
+ , ( AlignRight , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Oxide" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "\30707\33521" ] ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "SiO2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "100" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
diff --git a/documents/markdown/pandoc-md/6026.md b/documents/markdown/pandoc-md/6026.md
new file mode 100644
index 0000000..ae3bfb4
--- /dev/null
+++ b/documents/markdown/pandoc-md/6026.md
@@ -0,0 +1,45 @@
+```
+% pandoc -t native
+@{https://openreview.net/forum?id=HkwoSDPgg}
+
+@https://openreview.net/forum?id=HkwoSDPgg
+^D
+[ Para
+ [ Cite
+ [ Citation
+ { citationId = "https://openreview.net/forum?id=HkwoSDPgg"
+ , citationPrefix = []
+ , citationSuffix = []
+ , citationMode = AuthorInText
+ , citationNoteNum = 1
+ , citationHash = 0
+ }
+ ]
+ [ Str "@https://openreview.net/forum?id=HkwoSDPgg" ]
+ ]
+, Para
+ [ Cite
+ [ Citation
+ { citationId = "https://openreview.net/forum?id"
+ , citationPrefix = []
+ , citationSuffix = []
+ , citationMode = AuthorInText
+ , citationNoteNum = 2
+ , citationHash = 0
+ }
+ ]
+ [ Str "@https://openreview.net/forum?id" ]
+ , Str "=HkwoSDPgg"
+ ]
+]
+```
+```
+% pandoc -t markdown
+@{https://openreview.net/forum?id=HkwoSDPgg}
+
+@https://openreview.net/forum?id=HkwoSDPgg
+^D
+@{https://openreview.net/forum?id=HkwoSDPgg}
+
+@https://openreview.net/forum?id=HkwoSDPgg
+```
diff --git a/documents/markdown/pandoc-md/6030.md b/documents/markdown/pandoc-md/6030.md
new file mode 100644
index 0000000..2d7d217
--- /dev/null
+++ b/documents/markdown/pandoc-md/6030.md
@@ -0,0 +1,94 @@
+```
+% pandoc -t revealjs --slide-level=3
+# One
+
+One
+
+## Two
+
+Two
+
+### Three
+
+Three
+
+#### Four
+
+Four
+
+# New sec
+
+New sec
+
+## New sub
+
+New sub
+^D
+<section>
+<section id="one" class="title-slide slide level1">
+<h1>One</h1>
+<p>One</p>
+</section>
+<section id="two" class="title-slide slide level2">
+<h2>Two</h2>
+<p>Two</p>
+</section>
+<section id="three" class="slide level3">
+<h3>Three</h3>
+<p>Three</p>
+<h4 id="four">Four</h4>
+<p>Four</p>
+</section>
+</section>
+<section>
+<section id="new-sec" class="title-slide slide level1">
+<h1>New sec</h1>
+<p>New sec</p>
+</section>
+<section id="new-sub" class="title-slide slide level2">
+<h2>New sub</h2>
+<p>New sub</p>
+</section>
+</section>
+```
+
+```
+% pandoc -t beamer --slide-level=3
+# One
+
+One
+
+## Two
+
+Two
+
+### Three
+
+Three
+
+#### Four
+
+Four
+^D
+\section{One}\label{one}
+
+\begin{frame}{One}
+One
+\end{frame}
+
+\subsection{Two}\label{two}
+
+\begin{frame}{Two}
+Two
+\end{frame}
+
+\begin{frame}{Three}
+\protect\phantomsection\label{three}
+Three
+
+\begin{block}{Four}
+\protect\phantomsection\label{four}
+Four
+\end{block}
+\end{frame}
+```
diff --git a/documents/markdown/pandoc-md/6033.md b/documents/markdown/pandoc-md/6033.md
new file mode 100644
index 0000000..3748a22
--- /dev/null
+++ b/documents/markdown/pandoc-md/6033.md
@@ -0,0 +1,86 @@
+```
+% pandoc -t beamer --slide-level=4
+# One
+
+## One-A
+
+:::: columns
+
+::: column
+
+- One column.
+
+:::
+
+::: column
+
+- Another column.
+
+:::
+
+::::
+
+- Some more text.
+
+## One-B
+
+- Text.
+
+# Two
+
+## Two-A
+
+- More text.
+^D
+\section{One}\label{one}
+
+\subsection{One-A}\label{one-a}
+
+\begin{frame}{One-A}
+\begin{columns}[T]
+\begin{column}{0.48\linewidth}
+\begin{itemize}
+\tightlist
+\item
+ One column.
+\end{itemize}
+\end{column}
+
+\begin{column}{0.48\linewidth}
+\begin{itemize}
+\tightlist
+\item
+ Another column.
+\end{itemize}
+\end{column}
+\end{columns}
+
+\begin{itemize}
+\tightlist
+\item
+ Some more text.
+\end{itemize}
+\end{frame}
+
+\subsection{One-B}\label{one-b}
+
+\begin{frame}{One-B}
+\begin{itemize}
+\tightlist
+\item
+ Text.
+\end{itemize}
+\end{frame}
+
+\section{Two}\label{two}
+
+\subsection{Two-A}\label{two-a}
+
+\begin{frame}{Two-A}
+\begin{itemize}
+\tightlist
+\item
+ More text.
+\end{itemize}
+\end{frame}
+```
diff --git a/documents/markdown/pandoc-md/6034.md b/documents/markdown/pandoc-md/6034.md
new file mode 100644
index 0000000..3739fbd
--- /dev/null
+++ b/documents/markdown/pandoc-md/6034.md
@@ -0,0 +1,19 @@
+```
+% pandoc -f latex+raw_tex -t native
+\begin{figure*}
+ \centering
+ \begin{overpic}{test_pic}
+ \put (70,80) {Caption}
+ \end{overpic}
+\end{figure*}
+^D
+[ Figure
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ RawBlock (Format "latex") "\\centering"
+ , RawBlock
+ (Format "latex")
+ "\\begin{overpic}{test_pic}\n \\put (70,80) {Caption}\n \\end{overpic}"
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/6043.md b/documents/markdown/pandoc-md/6043.md
new file mode 100644
index 0000000..a3f39a4
--- /dev/null
+++ b/documents/markdown/pandoc-md/6043.md
@@ -0,0 +1,8 @@
+```
+% pandoc -t beamer
+\textbf<1>{Bold Text On Slide1}
+^D
+\begin{frame}
+\textbf<1>{Bold Text On Slide1}
+\end{frame}
+```
diff --git a/documents/markdown/pandoc-md/6062.md b/documents/markdown/pandoc-md/6062.md
new file mode 100644
index 0000000..d4f60fc
--- /dev/null
+++ b/documents/markdown/pandoc-md/6062.md
@@ -0,0 +1,6 @@
+```
+% pandoc -f native -t html
+[Header 1 ("section",["foo","unnumbered"],[("key","val")]) [Str "1"]]
+^D
+<h1 class="foo unnumbered" data-key="val" id="section">1</h1>
+```
diff --git a/documents/markdown/pandoc-md/6107.md b/documents/markdown/pandoc-md/6107.md
new file mode 100644
index 0000000..58f7164
--- /dev/null
+++ b/documents/markdown/pandoc-md/6107.md
@@ -0,0 +1,26 @@
+```
+% pandoc -t beamer
+---
+title: A silly slide
+subtitle: Look for the sequel!
+---
+
+# A circus!
+
+## Another silly title
+
+Not much to do about nothing.
+
+## Epilogue {.standout}
+^D
+\section{A circus!}\label{a-circus}
+
+\begin{frame}{Another silly title}
+\protect\phantomsection\label{another-silly-title}
+Not much to do about nothing.
+\end{frame}
+
+\begin{frame}[standout]{Epilogue}
+\protect\phantomsection\label{epilogue}
+\end{frame}
+```
diff --git a/documents/markdown/pandoc-md/6114.md b/documents/markdown/pandoc-md/6114.md
new file mode 100644
index 0000000..83d2869
--- /dev/null
+++ b/documents/markdown/pandoc-md/6114.md
@@ -0,0 +1,13 @@
+```
+% pandoc -f latex -t native
+\includegraphics[width=.85\textwidth]%
+ {pic_M87star.pdf}
+^D
+[ Para
+ [ Image
+ ( "" , [] , [ ( "width" , ".85\\textwidth" ) ] )
+ [ Str "image" ]
+ ( "pic_M87star.pdf" , "" )
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/6119.md b/documents/markdown/pandoc-md/6119.md
new file mode 100644
index 0000000..6a0085e
--- /dev/null
+++ b/documents/markdown/pandoc-md/6119.md
@@ -0,0 +1,10 @@
+```
+% pandoc -t mediawiki
+[[link](url)]
+
+[]
+^D
+[<nowiki/>[[url|link]]]
+
+[<nowiki/>[[File:url|image]]]
+```
diff --git a/documents/markdown/pandoc-md/6133.md b/documents/markdown/pandoc-md/6133.md
new file mode 100644
index 0000000..f260356
--- /dev/null
+++ b/documents/markdown/pandoc-md/6133.md
@@ -0,0 +1,12 @@
+```
+% pandoc -f markdown_mmd -t markdown_mmd -s
+author: Author
+title: Title
+
+Some text
+^D
+author: Author
+title: Title
+
+Some text
+```
diff --git a/documents/markdown/pandoc-md/6137.md b/documents/markdown/pandoc-md/6137.md
new file mode 100644
index 0000000..077044e
--- /dev/null
+++ b/documents/markdown/pandoc-md/6137.md
@@ -0,0 +1,165 @@
+```
+% pandoc -f latex -t native
+This reference to Table \ref{tbl:label} doesn't work.
+\begin{table}
+ \caption{This caption has no number.}\label{tbl:label}
+ \begin{tabular}{ l c r }
+ -------- & -------- & -------- \\
+ -------- & -------- & -------- \\
+ \end{tabular}
+\end{table}
+
+This reference to Figure \ref{fig:label} works fine.
+\begin{figure}
+ \includegraphics[width=\textwidth]{example.png}
+ \caption{A numbered caption, if I use pandoc-crossref.}\label{fig:label}
+\end{figure}
+^D
+[ Para
+ [ Str "This"
+ , Space
+ , Str "reference"
+ , Space
+ , Str "to"
+ , Space
+ , Str "Table"
+ , Space
+ , Link
+ ( ""
+ , []
+ , [ ( "reference-type" , "ref" )
+ , ( "reference" , "tbl:label" )
+ ]
+ )
+ [ Str "1" ]
+ ( "#tbl:label" , "" )
+ , Space
+ , Str "doesn\8217t"
+ , Space
+ , Str "work."
+ ]
+, Div
+ ( "tbl:label" , [] , [] )
+ [ Table
+ ( "" , [] , [] )
+ (Caption
+ Nothing
+ [ Plain
+ [ Str "This"
+ , Space
+ , Str "caption"
+ , Space
+ , Str "has"
+ , Space
+ , Str "no"
+ , Space
+ , Str "number."
+ ]
+ ])
+ [ ( AlignLeft , ColWidthDefault )
+ , ( AlignCenter , ColWidthDefault )
+ , ( AlignRight , ColWidthDefault )
+ ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "\8212\8212\8211" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "\8212\8212\8211" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "\8212\8212\8211" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "\8212\8212\8211" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "\8212\8212\8211" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "\8212\8212\8211" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+ ]
+, Para
+ [ Str "This"
+ , Space
+ , Str "reference"
+ , Space
+ , Str "to"
+ , Space
+ , Str "Figure"
+ , Space
+ , Link
+ ( ""
+ , []
+ , [ ( "reference-type" , "ref" )
+ , ( "reference" , "fig:label" )
+ ]
+ )
+ [ Str "1" ]
+ ( "#fig:label" , "" )
+ , Space
+ , Str "works"
+ , Space
+ , Str "fine."
+ ]
+, Figure
+ ( "fig:label" , [] , [] )
+ (Caption
+ Nothing
+ [ Plain
+ [ Str "A"
+ , Space
+ , Str "numbered"
+ , Space
+ , Str "caption,"
+ , Space
+ , Str "if"
+ , Space
+ , Str "I"
+ , Space
+ , Str "use"
+ , Space
+ , Str "pandoc-crossref."
+ ]
+ ])
+ [ Plain
+ [ Image
+ ( "" , [] , [ ( "width" , "\\textwidth" ) ] )
+ []
+ ( "example.png" , "" )
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/6194.md b/documents/markdown/pandoc-md/6194.md
new file mode 100644
index 0000000..43be264
--- /dev/null
+++ b/documents/markdown/pandoc-md/6194.md
@@ -0,0 +1,14 @@
+```
+% pandoc -f markdown -t rst
+image1: 
+
+image2: 
+^D
+image1: |foo|
+
+image2: |image1|
+
+.. |foo| image:: x.png
+.. |image1| image:: y.png
+```
+
diff --git a/documents/markdown/pandoc-md/6285.md b/documents/markdown/pandoc-md/6285.md
new file mode 100644
index 0000000..3eeb87d
--- /dev/null
+++ b/documents/markdown/pandoc-md/6285.md
@@ -0,0 +1,6 @@
+```
+% pandoc -t docx -f native -o - | pandoc -f docx -t native
+[ HorizontalRule ]
+^D
+[ HorizontalRule ]
+```
diff --git a/documents/markdown/pandoc-md/6288.md b/documents/markdown/pandoc-md/6288.md
new file mode 100644
index 0000000..4c1e6d5
--- /dev/null
+++ b/documents/markdown/pandoc-md/6288.md
@@ -0,0 +1,8 @@
+```
+% pandoc -f jats -t native
+<sec>
+<label>I</label><title>Introduction</title>
+</sec>
+^D
+[ Header 1 ( "" , [] , [] ) [ Str "Introduction" ] ]
+```
diff --git a/documents/markdown/pandoc-md/6296.md b/documents/markdown/pandoc-md/6296.md
new file mode 100644
index 0000000..f4ce6b6
--- /dev/null
+++ b/documents/markdown/pandoc-md/6296.md
@@ -0,0 +1,14 @@
+```
+% pandoc -f native -t markdown
+[Str "_hi_there"]
+^D
+\_hi_there
+```
+
+```
+% pandoc -f native -t markdown-intraword_underscores
+[Str "_hi_there"]
+^D
+\_hi\_there
+```
+
diff --git a/documents/markdown/pandoc-md/6308.md b/documents/markdown/pandoc-md/6308.md
new file mode 100644
index 0000000..c584bcd
--- /dev/null
+++ b/documents/markdown/pandoc-md/6308.md
@@ -0,0 +1,18 @@
+```
+% pandoc -f org -t asciidoc
+* Header
+#+begin_tip
+I'm a tip
+#+end_tip
+
+** Subheader
+^D
+== Header
+
+[TIP]
+====
+I'm a tip
+====
+
+=== Subheader
+```
diff --git a/documents/markdown/pandoc-md/6324.md b/documents/markdown/pandoc-md/6324.md
new file mode 100644
index 0000000..51a2248
--- /dev/null
+++ b/documents/markdown/pandoc-md/6324.md
@@ -0,0 +1,26 @@
+```
+% pandoc -f latex -t native -s
+\documentclass{article}
+
+\begin{document}
+ \title{Document title}
+ \author{
+
+Me
+
+}
+\maketitle
+\end{document}
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "author" , MetaList [ MetaInlines [ Str "Me" ] ] )
+ , ( "title"
+ , MetaInlines [ Str "Document" , Space , Str "title" ]
+ )
+ ]
+ }
+ []
+```
diff --git a/documents/markdown/pandoc-md/6348.md b/documents/markdown/pandoc-md/6348.md
new file mode 100644
index 0000000..7f599e5
--- /dev/null
+++ b/documents/markdown/pandoc-md/6348.md
@@ -0,0 +1,42 @@
+```
+% pandoc -f jats -t native
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE article PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Publishing DTD v1.0 20120330//EN" "http://jats.nlm.nih.gov/publishing/1.0/JATS-journalpublishing1.dtd">
+<article xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" dtd-version="1.0" article-type="research-article">
+ <front>
+ <journal-meta>
+ <journal-title-group>
+ <journal-title>Opinion Research</journal-title>
+ </journal-title-group>
+ </journal-meta>
+ <article-meta>
+ <title-group>
+ <article-title>Example article</article-title>
+ </title-group>
+ </article-meta>
+ </front>
+ <body>
+ <sec sec-type="results">
+ <title>Results</title>
+ <p>A University <xref ref-type="fn" rid="N0001">1</xref></p>
+ </sec>
+ </body>
+ <back>
+ <fn-group>
+ <fn id="N0001">
+ <p>footnote</p>
+ </fn>
+ </fn-group>
+ </back>
+</article>
+^D
+[ Header 1 ( "" , [] , [] ) [ Str "Results" ]
+, Para
+ [ Str "A"
+ , Space
+ , Str "University"
+ , Space
+ , Note [ Para [ Str "footnote" ] ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/6350.md b/documents/markdown/pandoc-md/6350.md
new file mode 100644
index 0000000..14093fc
--- /dev/null
+++ b/documents/markdown/pandoc-md/6350.md
@@ -0,0 +1,29 @@
+```
+% pandoc -f commonmark+implicit_figures -t native
+{#ident width="100%"}
+^D
+[ Para
+ [ Image
+ ( "" , [] , [] ) [ Str "caption" ] ( "image.jpg" , "" )
+ , Str "{#ident"
+ , Space
+ , Str "width=\"100%\"}"
+ ]
+]
+
+```
+
+```
+% pandoc -f commonmark -t native
+{#ident width="100%"}
+^D
+[ Para
+ [ Image
+ ( "" , [] , [] ) [ Str "caption" ] ( "image.jpg" , "" )
+ , Str "{#ident"
+ , Space
+ , Str "width=\"100%\"}"
+ ]
+]
+
+```
diff --git a/documents/markdown/pandoc-md/6360.md b/documents/markdown/pandoc-md/6360.md
new file mode 100644
index 0000000..0e14b9b
--- /dev/null
+++ b/documents/markdown/pandoc-md/6360.md
@@ -0,0 +1,6 @@
+```
+% pandoc -f native -t latex --wrap=none
+[Link ("test2",[],[]) [Str "link",Space,Str "to",Space,Str "text",Space,Str "test1"] ("#test1","")]
+^D
+\protect\phantomsection\label{test2}\hyperref[test1]{link to text test1}
+```
diff --git a/documents/markdown/pandoc-md/6367.md b/documents/markdown/pandoc-md/6367.md
new file mode 100644
index 0000000..74c56a0
--- /dev/null
+++ b/documents/markdown/pandoc-md/6367.md
@@ -0,0 +1,75 @@
+```
+% pandoc -f ipynb -t org
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "A Markdown cell"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "2"
+ ]
+ },
+ "execution_count": 1,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "# A code cell\n",
+ "1 + 1"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Another Markdown cell"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "Python 3",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.8.2"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}
+^D
+A Markdown cell
+
+#+begin_src jupyter-python
+# A code cell
+1 + 1
+#+end_src
+
+#+RESULTS:
+: 2
+
+Another Markdown cell
+```
diff --git a/documents/markdown/pandoc-md/6384.md b/documents/markdown/pandoc-md/6384.md
new file mode 100644
index 0000000..ced3106
--- /dev/null
+++ b/documents/markdown/pandoc-md/6384.md
@@ -0,0 +1,12 @@
+```
+% pandoc --wrap=preserve --file-scope command/file1.txt command/file2.txt
+^D
+<h1 id="command__file1.txt__zed">Zed</h1>
+<p><a href="bar">foo</a>
+and <a href="#command__file1.txt__zed">Zed</a>
+and <a href="#command__file2.txt__zed">other Zed</a>
+and <a href="#command__file2.txt">other file</a>
+and <a href="c.md#zed">foreign Zed</a></p>
+<h2 id="command__file2.txt__zed">Zed</h2>
+<p><a href="baz">foo</a></p>
+```
diff --git a/documents/markdown/pandoc-md/6385.md b/documents/markdown/pandoc-md/6385.md
new file mode 100644
index 0000000..f67b829
--- /dev/null
+++ b/documents/markdown/pandoc-md/6385.md
@@ -0,0 +1,18 @@
+```
+% pandoc -f markdown -t html
+<details>
+<summary>Show me:</summary>
+details para 1
+
+details para 2
+
+</details>
+^D
+<details>
+<summary>
+Show me:
+</summary>
+<p>details para 1</p>
+<p>details para 2</p>
+</details>
+```
diff --git a/documents/markdown/pandoc-md/6388.md b/documents/markdown/pandoc-md/6388.md
new file mode 100644
index 0000000..29a9156
--- /dev/null
+++ b/documents/markdown/pandoc-md/6388.md
@@ -0,0 +1,16 @@
+```
+% pandoc -t markdown -s
+---
+nvalue: false
+value: true
+---
+
+text
+^D
+---
+nvalue: false
+value: true
+---
+
+text
+```
diff --git a/documents/markdown/pandoc-md/6424.md b/documents/markdown/pandoc-md/6424.md
new file mode 100644
index 0000000..65bd580
--- /dev/null
+++ b/documents/markdown/pandoc-md/6424.md
@@ -0,0 +1,6 @@
+```
+% pandoc -t asciidoc
+test^[this is a note\]. and more]
+^D
+testfootnote:[this is a note++]++. and more]
+```
diff --git a/documents/markdown/pandoc-md/6441.md b/documents/markdown/pandoc-md/6441.md
new file mode 100644
index 0000000..621e536
--- /dev/null
+++ b/documents/markdown/pandoc-md/6441.md
@@ -0,0 +1,22 @@
+```
+% pandoc -f org -t html
+#+ATTR_HTML: :class table-dark
+| h1 | h2 |
+|----|----|
+| c1 | c2 |
+^D
+<table class="table-dark">
+<thead>
+<tr>
+<th>h1</th>
+<th>h2</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>c1</td>
+<td>c2</td>
+</tr>
+</tbody>
+</table>
+```
diff --git a/documents/markdown/pandoc-md/645.md b/documents/markdown/pandoc-md/645.md
new file mode 100644
index 0000000..90b285b
--- /dev/null
+++ b/documents/markdown/pandoc-md/645.md
@@ -0,0 +1,12 @@
+Don't use listings commands in \item[..] context:
+```
+% pandoc -t latex
+`--foo` **BAR**
+
+: Enables the foo feature with **BAR** as its flavour.
+^D
+\begin{description}
+\item[\texttt{-\/-foo} \textbf{BAR}]
+Enables the foo feature with \textbf{BAR} as its flavour.
+\end{description}
+```
diff --git a/documents/markdown/pandoc-md/6466.md b/documents/markdown/pandoc-md/6466.md
new file mode 100644
index 0000000..61a9ccd
--- /dev/null
+++ b/documents/markdown/pandoc-md/6466.md
@@ -0,0 +1,23 @@
+```
+% pandoc -f org -t native
+Stuff
+
+#+INCLUDE: "command/6466-beg.hs" src haskell :lines "-4"
+#+INCLUDE: "command/6466-mid.hs" src haskell :lines "3-6"
+#+INCLUDE: "command/6466-end.hs" src haskell :lines "3-"
+#+INCLUDE: "command/6466-whole.hs" src haskell :lines "-"
+
+More stuff
+^D
+[ Para [ Str "Stuff" ]
+, CodeBlock
+ ( "" , [ "haskell" ] , [] ) "want :: Int\nwant = 42\n\n"
+, CodeBlock
+ ( "" , [ "haskell" ] , [] ) "want :: Int\nwant = 42\n\n"
+, CodeBlock
+ ( "" , [ "haskell" ] , [] ) "want :: Int\nwant = 42\n"
+, CodeBlock
+ ( "" , [ "haskell" ] , [] ) "want :: Int\nwant = 42\n"
+, Para [ Str "More" , Space , Str "stuff" ]
+]
+```
diff --git a/documents/markdown/pandoc-md/6481.md b/documents/markdown/pandoc-md/6481.md
new file mode 100644
index 0000000..fb40114
--- /dev/null
+++ b/documents/markdown/pandoc-md/6481.md
@@ -0,0 +1,38 @@
+```
+% pandoc -t html5
+::: {.div-class}
++-------+-----+-----+-------------------------------------------------+
+| Col 1 | Col | Col | Col 4 |
+| | 2 | 3 | |
++:=====:+:===:+:===:+:================================================+
+| High | Med | Med | Some description of something. |
++-------+-----+-----+-------------------------------------------------+
+:::
+^D
+<div class="div-class">
+<table style="width:97%;">
+<colgroup>
+<col style="width: 11%" />
+<col style="width: 8%" />
+<col style="width: 8%" />
+<col style="width: 69%" />
+</colgroup>
+<thead>
+<tr>
+<th style="text-align: center;">Col 1</th>
+<th style="text-align: center;">Col 2</th>
+<th style="text-align: center;">Col 3</th>
+<th style="text-align: left;">Col 4</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td style="text-align: center;">High</td>
+<td style="text-align: center;">Med</td>
+<td style="text-align: center;">Med</td>
+<td style="text-align: left;">Some description of something.</td>
+</tr>
+</tbody>
+</table>
+</div>
+```
diff --git a/documents/markdown/pandoc-md/6541.md b/documents/markdown/pandoc-md/6541.md
new file mode 100644
index 0000000..956340d
--- /dev/null
+++ b/documents/markdown/pandoc-md/6541.md
@@ -0,0 +1,27 @@
+```
+% pandoc -f docbook -t markdown -s
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<book>
+
+<bookinfo>
+<title>Title</title>
+<author>
+<firstname>Firstname</firstname><surname>Lastname</surname>
+</author>
+<releaseinfo>1.17</releaseinfo>
+</bookinfo>
+
+<para>Text.</para>
+
+</book>
+^D
+---
+author: Firstname Lastname
+releaseinfo: 1.17
+title: Title
+---
+
+Text.
+```
diff --git a/documents/markdown/pandoc-md/6549.md b/documents/markdown/pandoc-md/6549.md
new file mode 100644
index 0000000..4ba11b4
--- /dev/null
+++ b/documents/markdown/pandoc-md/6549.md
@@ -0,0 +1,26 @@
+```
+% pandoc -f rst
+.. csv-table:: Test table
+ :file: command/01.csv
+ :delim: ;
+ :header-rows: 1
+^D
+<table>
+<caption>Test table</caption>
+<thead>
+<tr>
+<th>Column1</th>
+<th>Column2</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Data1</td>
+<td><ul>
+<li>data1</li>
+<li>data2</li>
+</ul></td>
+</tr>
+</tbody>
+</table>
+```
diff --git a/documents/markdown/pandoc-md/6588.md b/documents/markdown/pandoc-md/6588.md
new file mode 100644
index 0000000..efd3a68
--- /dev/null
+++ b/documents/markdown/pandoc-md/6588.md
@@ -0,0 +1,10 @@
+```
+% pandoc -f rst
+I recommend you try |Python|_.
+
+.. |Python| replace:: Python, *the* best language around
+.. _Python: http://www.python.org/
+^D
+<p>I recommend you try <a href="http://www.python.org/"><span>Python,
+<em>the</em> best language around</span></a>.</p>
+```
diff --git a/documents/markdown/pandoc-md/6620.md b/documents/markdown/pandoc-md/6620.md
new file mode 100644
index 0000000..e448ca6
--- /dev/null
+++ b/documents/markdown/pandoc-md/6620.md
@@ -0,0 +1,18 @@
+```
+% pandoc -f latex
+\SI{23(2)}{\m}
+
+\SI{125(12)}{\m}
+
+\SI{0.135(21)}{\m}
+
+\SI{12.3(60)}{\m}
+
+\SI{10.0 \pm 3.3}{\ms}
+^D
+<p>23 ± 2 m</p>
+<p>125 ± 12 m</p>
+<p>0.135 ± 0.021 m</p>
+<p>12.3 ± 6 m</p>
+<p>10.0 ± 3.3 ms</p>
+```
diff --git a/documents/markdown/pandoc-md/6658.md b/documents/markdown/pandoc-md/6658.md
new file mode 100644
index 0000000..c4e5dbf
--- /dev/null
+++ b/documents/markdown/pandoc-md/6658.md
@@ -0,0 +1,75 @@
+```
+% pandoc -f latex -t html
+\num{12345,67890}
+
+\num{1+-2i}
+
+\num{.3e45}
+
+\num{1.654 x 2.34 x 3.430}
+
+\si{kg.m.s^{-1}}
+
+\si{\kilogram\metre\per\second}
+
+\si[per-mode=symbol]{\kilogram\metre\per\second}
+
+\si[per-mode=symbol]{\kilogram\metre\per\ampere\per\second}
+
+\numlist{10;20;30}
+
+\SIlist{0.13;0.67;0.80}{\milli\metre}
+
+\numrange{10}{20}
+
+\SIrange{0.13}{0.67}{\milli\metre}
+
+\ang{10}
+
+\ang{1;2;3}
+
+\ang{;;1}
+
+\ang{+10;;}
+
+\ang{-0;1;}
+
+\si{kg.m/s^2}
+
+\si{g_{polymer}~mol_{cat}.s^{-1}}
+
+\si{\kilo\gram\metre\per\square\second}
+
+\si{\gram\per\cubic\centi\metre}
+
+\si{\square\volt\cubic\lumen\per\farad}
+
+\si{\metre\squared\per\gray\cubic\lux}
+
+\si{\henry\second}
+^D
+<p>12345.67890</p>
+<p>1 ± 2i</p>
+<p>0.3 × 10<sup>45</sup></p>
+<p>1.654 × 2.34 × 3.430</p>
+<p>kg m s<sup>−1</sup></p>
+<p>kg m s<sup>−1</sup></p>
+<p>kg m/s</p>
+<p>kg m/A/s</p>
+<p>10, 20, & 30</p>
+<p>0.13 mm, 0.67 mm, & 0.80 mm</p>
+<p>10–20</p>
+<p>0.13 mm–0.67 mm</p>
+<p>10°</p>
+<p>1°2′3″</p>
+<p>1″</p>
+<p>10°</p>
+<p>-0°1′</p>
+<p>kg m/s<sup>2</sup></p>
+<p>g<sub>polymer</sub> mol<sub>cat</sub> s<sup>−1</sup></p>
+<p>kg m s<sup>−2</sup></p>
+<p>g cm<sup>−3</sup></p>
+<p>V<sup>2</sup> lm<sup>3</sup> F<sup>−1</sup></p>
+<p>m<sup>2</sup> Gy<sup>−1</sup> lx<sup>3</sup></p>
+<p>H s</p>
+```
diff --git a/documents/markdown/pandoc-md/6675.md b/documents/markdown/pandoc-md/6675.md
new file mode 100644
index 0000000..d298457
--- /dev/null
+++ b/documents/markdown/pandoc-md/6675.md
@@ -0,0 +1,134 @@
+```
+% pandoc -f markdown -t icml -s
+
+# Header 1
+
+this is some text
+
+## Header 2
+
+some more text that [links to](https://www.pandoc.org) Pandoc.
+
+and some text that [links to](#header-1) the first header
+
+^D
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<?aid style="50" type="snippet" readerVersion="6.0" featureSet="513" product="8.0(370)" ?>
+<?aid SnippetType="InCopyInterchange"?>
+<Document DOMVersion="8.0" Self="pandoc_doc">
+ <RootCharacterStyleGroup Self="pandoc_character_styles">
+ <CharacterStyle Self="$ID/NormalCharacterStyle" Name="Default" />
+ <CharacterStyle Self="CharacterStyle/Link" Name="Link">
+ <Properties>
+ <BasedOn type="object">$ID/NormalCharacterStyle</BasedOn>
+ </Properties>
+ </CharacterStyle>
+ </RootCharacterStyleGroup>
+ <RootParagraphStyleGroup Self="pandoc_paragraph_styles">
+ <ParagraphStyle Self="$ID/NormalParagraphStyle" Name="$ID/NormalParagraphStyle"
+ SpaceBefore="6" SpaceAfter="6"> <!-- paragraph spacing -->
+ <Properties>
+ <TabList type="list">
+ <ListItem type="record">
+ <Alignment type="enumeration">LeftAlign</Alignment>
+ <AlignmentCharacter type="string">.</AlignmentCharacter>
+ <Leader type="string"></Leader>
+ <Position type="unit">10</Position> <!-- first tab stop -->
+ </ListItem>
+ </TabList>
+ </Properties>
+ </ParagraphStyle>
+ <ParagraphStyle Self="ParagraphStyle/Header1" Name="Header1" LeftIndent="0" PointSize="36">
+ <Properties>
+ <BasedOn type="object">$ID/NormalParagraphStyle</BasedOn>
+ </Properties>
+ </ParagraphStyle>
+ <ParagraphStyle Self="ParagraphStyle/Header2" Name="Header2" LeftIndent="0" PointSize="30">
+ <Properties>
+ <BasedOn type="object">$ID/NormalParagraphStyle</BasedOn>
+ </Properties>
+ </ParagraphStyle>
+ <ParagraphStyle Self="ParagraphStyle/Paragraph" Name="Paragraph" LeftIndent="0">
+ <Properties>
+ <BasedOn type="object">$ID/NormalParagraphStyle</BasedOn>
+ </Properties>
+ </ParagraphStyle>
+ </RootParagraphStyleGroup>
+ <RootTableStyleGroup Self="pandoc_table_styles">
+ <TableStyle Self="TableStyle/Table" Name="Table" />
+ </RootTableStyleGroup>
+ <RootCellStyleGroup Self="pandoc_cell_styles">
+ <CellStyle Self="CellStyle/Cell" AppliedParagraphStyle="ParagraphStyle/$ID/[No paragraph style]" Name="Cell" />
+ </RootCellStyleGroup>
+ <Story Self="pandoc_story"
+ TrackChanges="false"
+ StoryTitle=""
+ AppliedTOCStyle="n"
+ AppliedNamedGrid="n" >
+ <StoryPreference OpticalMarginAlignment="true" OpticalMarginSize="12" />
+
+<!-- body needs to be non-indented, otherwise code blocks are indented too far -->
+<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Header1">
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <HyperlinkTextDestination Self="HyperlinkTextDestination/#header-1" Name="Destination" DestinationUniqueKey="1" />
+ <Content>Header 1</Content>
+ </CharacterStyleRange>
+</ParagraphStyleRange>
+<Br />
+<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Paragraph">
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <Content>this is some text</Content>
+ </CharacterStyleRange>
+</ParagraphStyleRange>
+<Br />
+<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Header2">
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <HyperlinkTextDestination Self="HyperlinkTextDestination/#header-2" Name="Destination" DestinationUniqueKey="1" />
+ <Content>Header 2</Content>
+ </CharacterStyleRange>
+</ParagraphStyleRange>
+<Br />
+<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Paragraph">
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <Content>some more text that </Content>
+ </CharacterStyleRange>
+ <HyperlinkTextSource Self="htss-1" Name="" Hidden="false">
+ <CharacterStyleRange AppliedCharacterStyle="CharacterStyle/Link">
+ <Content>links to</Content>
+ </CharacterStyleRange>
+ </HyperlinkTextSource>
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <Content> Pandoc.</Content>
+ </CharacterStyleRange>
+</ParagraphStyleRange>
+<Br />
+<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Paragraph">
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <Content>and some text that </Content>
+ </CharacterStyleRange>
+ <HyperlinkTextSource Self="htss-2" Name="" Hidden="false">
+ <CharacterStyleRange AppliedCharacterStyle="CharacterStyle/Link">
+ <Content>links to</Content>
+ </CharacterStyleRange>
+ </HyperlinkTextSource>
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <Content> the first header</Content>
+ </CharacterStyleRange>
+</ParagraphStyleRange>
+
+ </Story>
+ <Hyperlink Self="uf-2" Name="#header-1" Source="htss-2" Visible="false" DestinationUniqueKey="1">
+ <Properties>
+ <BorderColor type="enumeration">Black</BorderColor>
+ <Destination type="object">HyperlinkTextDestination/#header-1</Destination>
+ </Properties>
+ </Hyperlink>
+ <HyperlinkURLDestination Self="HyperlinkURLDestination/https%3a//www.pandoc.org" Name="link" DestinationURL="https://www.pandoc.org" DestinationUniqueKey="1" />
+ <Hyperlink Self="uf-1" Name="https://www.pandoc.org" Source="htss-1" Visible="false" DestinationUniqueKey="1">
+ <Properties>
+ <BorderColor type="enumeration">Black</BorderColor>
+ <Destination type="object">HyperlinkURLDestination/https%3a//www.pandoc.org</Destination>
+ </Properties>
+ </Hyperlink>
+</Document>
+```
diff --git a/documents/markdown/pandoc-md/6699.md b/documents/markdown/pandoc-md/6699.md
new file mode 100644
index 0000000..6dfea4d
--- /dev/null
+++ b/documents/markdown/pandoc-md/6699.md
@@ -0,0 +1,15 @@
+```
+% pandoc -f rst -t native
+.. class:: allowframebreaks
+
+title
+-----
+
+text
+^D
+[ Header
+ 1 ( "title" , [ "allowframebreaks" ] , [] ) [ Str "title" ]
+, Para [ Str "text" ]
+]
+```
+
diff --git a/documents/markdown/pandoc-md/6709.md b/documents/markdown/pandoc-md/6709.md
new file mode 100644
index 0000000..4198950
--- /dev/null
+++ b/documents/markdown/pandoc-md/6709.md
@@ -0,0 +1,13 @@
+Tabs must be expanded even if --file-scope is used
+````
+% pandoc -t native --file-scope --tab-stop=2
+```
+if true; then
+ echo "yup"
+fi
+```
+^D
+[ CodeBlock
+ ( "" , [] , [] ) "if true; then\n echo \"yup\"\nfi"
+]
+````
diff --git a/documents/markdown/pandoc-md/6719.md b/documents/markdown/pandoc-md/6719.md
new file mode 100644
index 0000000..5be3bce
--- /dev/null
+++ b/documents/markdown/pandoc-md/6719.md
@@ -0,0 +1,18 @@
+```
+% pandoc -f docbook -t native
+<para>
+<emphasis>emphasized </emphasis>text
+</para>
+^D
+[ Para [ Emph [ Str "emphasized" , Space ] , Str "text" ] ]
+```
+
+```
+% pandoc -f jats -t native
+<p>
+<italic> hi </italic>there
+</p>
+^D
+[ Para [ Emph [ Space , Str "hi" , Space ] , Str "there" ] ]
+```
+
diff --git a/documents/markdown/pandoc-md/6723.md b/documents/markdown/pandoc-md/6723.md
new file mode 100644
index 0000000..4f8b78b
--- /dev/null
+++ b/documents/markdown/pandoc-md/6723.md
@@ -0,0 +1,32 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: command/chicago-fullnote-bibliography.csl
+references:
+- id: doe
+ type: article
+ author:
+ - family: Doe
+ given: John
+ DOI: 10.1109/5.771073
+ issued:
+ - year: 2020
+ title: An article
+...
+Blah [@doe].
+
+# References {-}
+
+^D
+Blah.[^1]
+
+# References {#references .unnumbered}
+
+:::: {#refs .references .csl-bib-body .hanging-indent entry-spacing="0"}
+::: {#ref-doe .csl-entry}
+Doe, John. "An Article," 2020. <https://doi.org/10.1109/5.771073>.
+:::
+::::
+
+[^1]: John Doe, "An Article," 2020, <https://doi.org/10.1109/5.771073>.
+```
diff --git a/documents/markdown/pandoc-md/6739.md b/documents/markdown/pandoc-md/6739.md
new file mode 100644
index 0000000..ff2d4bc
--- /dev/null
+++ b/documents/markdown/pandoc-md/6739.md
@@ -0,0 +1,22 @@
+```
+% pandoc -f gfm
+* `--argument` This item does not have a pipe character
+* `--argA | --argB` This item has a pipe character
+^D
+<ul>
+<li><code>--argument</code> This item does not have a pipe
+character</li>
+<li><code>--argA | --argB</code> This item has a pipe character</li>
+</ul>
+```
+
+```
+% pandoc --mathjax -f gfm+tex_math_dollars
+* $|x|$
+* $|y|$
+^D
+<ul>
+<li><span class="math inline">\(|x|\)</span></li>
+<li><span class="math inline">\(|y|\)</span></li>
+</ul>
+```
diff --git a/documents/markdown/pandoc-md/6741.md b/documents/markdown/pandoc-md/6741.md
new file mode 100644
index 0000000..7764055
--- /dev/null
+++ b/documents/markdown/pandoc-md/6741.md
@@ -0,0 +1,145 @@
+```
+% pandoc --citeproc --csl command/ieee.csl -t plain
+---
+title: 'A Simple Citations Test'
+author: 'Joanna Doe'
+references:
+- author:
+ - family: Mathôt
+ given: S
+ container-title: Annual review of vision science
+ DOI: 10.1146/annurev-vision-030320-062352
+ id: mathot2020
+ issued: 2020
+ title: "Tuning the senses: How the pupil shapes vision at the earliest
+ stage."
+ title-short: Tuning the senses
+ type: article-journal
+- author:
+ - family: Zokaei
+ given: Nahid
+ - family: Board
+ given: Alexander G.
+ - family: Manohar
+ given: Sanjay G.
+ - family: Nobre
+ given: Anna C.
+ container-title: Proceedings of the National Academy of Sciences of
+ the United States of America
+ DOI: 10.1073/pnas.1909959116
+ id: zokaei2019
+ issued: 2019
+ page: 201909959
+ title: Modulation of the pupillary response by the content of visual
+ working memory
+ type: article-journal
+- author:
+ - family: Suzuki
+ given: Y.
+ - family: Minami
+ given: T.
+ - family: Laeng
+ given: B.
+ - family: Nakauchi
+ given: S.
+ container-title: Acta Psychologica
+ DOI: 10.1016/j.actpsy.2019.102882
+ id: suzuki2019
+ issued: 2019
+ page: 102882
+ title: "Colorful glares: Effects of colors on brightness illusions
+ measured with pupillometry."
+ title-short: Colorful glares
+ type: article-journal
+ volume: 198
+- author:
+ - family: Brainard
+ given: David H.
+ - family: Hurlbert
+ given: Anya
+ container-title: Current Biology
+ DOI: 10.1016/j.cub.2015.05.020
+ id: brainard2015a
+ issue: 13
+ issued: 2015
+ page: R551-R554
+ title: "Colour vision: Understanding \\#TheDress"
+ title-short: Colour vision
+ type: article-journal
+ volume: 25
+- author:
+ - family: Cavanagh
+ given: Patrick
+ container-title: Limits of vision
+ editor:
+ - family: Crody-Dillon
+ given: John R.
+ id: cavanagh1991
+ issued: 1991
+ page: 234-250
+ publisher: CRC Press
+ title: Vision at equiluminance
+ type: chapter
+- author:
+ - family: Brainard
+ given: David H.
+ container-title: Annual Review of Vision Science
+ DOI: 10.1146/annurev-vision-082114-035341
+ id: brainard2015
+ issued: 2015
+ page: 519-546
+ title: Color and the cone mosaic
+ type: article-journal
+ volume: 1
+...
+
+# First Heading #
+Here is some **text**. And a reference [@brainard2015;@brainard2015a].
+
+# Second Heading #
+Here is some *text*[@cavanagh1991]. And a reference [@cavanagh1991;@brainard2015].
+
+# Third Heading #
+Here is some [text]{.underline}. And a reference [@mathot2020;@zokaei2019;@suzuki2019].
+
+::: {#refs}
+## Bibliography ##
+:::
+^D
+First Heading
+
+Here is some text. And a reference [1], [2].
+
+Second Heading
+
+Here is some text[3]. And a reference [1], [3].
+
+Third Heading
+
+Here is some text. And a reference [4]–[6].
+
+Bibliography
+
+[1] D. H. Brainard, “Color and the cone mosaic,” Annual Review of Vision
+Science, vol. 1, pp. 519–546, 2015.
+
+[2] D. H. Brainard and A. Hurlbert, “Colour vision: Understanding
+#TheDress,” Current Biology, vol. 25, no. 13, pp. R551–R554, 2015.
+
+[3] P. Cavanagh, “Vision at equiluminance,” in Limits of vision, J. R.
+Crody-Dillon, Ed. CRC Press, 1991, pp. 234–250.
+
+[4] S. Mathôt, “Tuning the senses: How the pupil shapes vision at the
+earliest stage.” Annual review of vision science, 2020.
+
+[5] N. Zokaei, A. G. Board, S. G. Manohar, and A. C. Nobre, “Modulation
+of the pupillary response by the content of visual working memory,”
+Proceedings of the National Academy of Sciences of the United States of
+America, p. 201909959, 2019.
+
+[6] Y. Suzuki, T. Minami, B. Laeng, and S. Nakauchi, “Colorful glares:
+Effects of colors on brightness illusions measured with pupillometry.”
+Acta Psychologica, vol. 198, p. 102882, 2019.
+
+```
+
diff --git a/documents/markdown/pandoc-md/6752.md b/documents/markdown/pandoc-md/6752.md
new file mode 100644
index 0000000..b2d51d2
--- /dev/null
+++ b/documents/markdown/pandoc-md/6752.md
@@ -0,0 +1,36 @@
+```
+% pandoc -f biblatex -t csljson
+@xdata{XDPubAlfredAKnopf,
+ publisher = {Alfred A.~Knopf},
+ address = {New York, NY}
+}
+@book{Klinkenborg2012,
+ author = {Verlyn Klinkenborg},
+ title = {Several short sentences about writing},
+ date = {2012},
+ xdata = {XDPubAlfredAKnopf},
+}
+^D
+[
+ {
+ "author": [
+ {
+ "family": "Klinkenborg",
+ "given": "Verlyn"
+ }
+ ],
+ "id": "Klinkenborg2012",
+ "issued": {
+ "date-parts": [
+ [
+ 2012
+ ]
+ ]
+ },
+ "publisher": "Alfred A. Knopf",
+ "publisher-place": "New York, NY",
+ "title": "Several short sentences about writing",
+ "type": "book"
+ }
+]
+```
diff --git a/documents/markdown/pandoc-md/6755.md b/documents/markdown/pandoc-md/6755.md
new file mode 100644
index 0000000..b6ff0fc
--- /dev/null
+++ b/documents/markdown/pandoc-md/6755.md
@@ -0,0 +1,11 @@
+```
+%pandoc -f native -t opendocument
+[Div ("divId",[],[])
+ [Para [Str "Here",Space,Str "is",Space,Str "a",Space,Str "div."]],
+Para [Span ("spanId",[],[]) [Str "And",Space,Str "here",Space,Str "is",Space,Str "a",Space,Str "span."]]]
+^D
+<text:section text:name="divId"><text:p text:style-name="Text_20_body">Here
+is a div.</text:p></text:section>
+<text:p text:style-name="Text_20_body"><text:bookmark-start text:name="spanId" />And
+here is a span.<text:bookmark-end text:name="spanId" /></text:p>
+```
diff --git a/documents/markdown/pandoc-md/6765.md b/documents/markdown/pandoc-md/6765.md
new file mode 100644
index 0000000..8836d72
--- /dev/null
+++ b/documents/markdown/pandoc-md/6765.md
@@ -0,0 +1,31 @@
+```
+% pandoc --citeproc -t plain
+@book_chapter_1 [55] says blah.
+
+---
+csl: command/chicago-fullnote-bibliography.csl
+references:
+- id: book_chapter_1
+ author:
+ - family: Author
+ given: Ann
+ container-title: A book
+ editor:
+ - family: Editor
+ given: Edward
+ issued: 2014
+ page: 48-67
+ publisher: A publisher
+ publisher-place: A place
+ title: A book chapter
+ type: chapter
+...
+^D
+Ann Author[1] says blah.
+
+Author, Ann. “A Book Chapter.” In A Book, edited by Edward Editor,
+48–67. A place: A publisher, 2014.
+
+[1] “A Book Chapter,” in A Book, ed. Edward Editor (A place: A
+publisher, 2014), 55.
+```
diff --git a/documents/markdown/pandoc-md/6768.md b/documents/markdown/pandoc-md/6768.md
new file mode 100644
index 0000000..17a3ae8
--- /dev/null
+++ b/documents/markdown/pandoc-md/6768.md
@@ -0,0 +1,21 @@
+```
+% pandoc -tcommonmark
+::: custom_div
+This is a div
+:::
+^D
+<div class="custom_div">
+
+This is a div
+
+</div>
+```
+
+```
+% pandoc -tcommonmark-raw_html
+::: custom_div
+This is a div
+:::
+^D
+This is a div
+```
diff --git a/documents/markdown/pandoc-md/6774.md b/documents/markdown/pandoc-md/6774.md
new file mode 100644
index 0000000..7e8db5b
--- /dev/null
+++ b/documents/markdown/pandoc-md/6774.md
@@ -0,0 +1,63 @@
+```
+% pandoc -f native -t opendocument --quiet
+[Header 1 ("chapter1",[],[]) [Str "The",Space,Str "Chapter"]
+,Para [Str "Chapter",Space,Str "1",Space,Str "references",Space,Link ("",[],[]) [Str "The",Space,Str "Chapter"] ("#chapter1","")]]
+^D
+<text:h text:style-name="Heading_20_1" text:outline-level="1"><text:bookmark-start text:name="chapter1" />The
+Chapter<text:bookmark-end text:name="chapter1" /></text:h>
+<text:p text:style-name="First_20_paragraph">Chapter 1 references
+<text:a xlink:type="simple" xlink:href="#chapter1" office:name=""><text:span text:style-name="Definition">The
+Chapter</text:span></text:a></text:p>
+```
+```
+% pandoc -f native -t opendocument+xrefs_name --quiet
+[Header 1 ("chapter1",[],[]) [Str "The",Space,Str "Chapter"]
+,Para [Str "Chapter",Space,Str "1",Space,Str "references",Space,Link ("",[],[]) [Str "The",Space,Str "Chapter"] ("#chapter1","")]
+,Figure ("lalune",[],[]) (Caption Nothing [Para [Str "Voyage dans la Lune"]]) [Plain [Image ("",[],[]) [Str "lalune"] ("lalune.jpg","")]]
+,Para [Str "Image",Space,Str "1",Space,Str "references",Space,Link ("",[],[]) [Str "La",Space,Str "Lune"] ("#lalune","")]]
+^D
+<text:h text:style-name="Heading_20_1" text:outline-level="1"><text:bookmark-start text:name="chapter1" />The
+Chapter<text:bookmark-end text:name="chapter1" /></text:h>
+<text:p text:style-name="First_20_paragraph">Chapter 1 references
+<text:bookmark-ref text:reference-format="text" text:ref-name="chapter1">The
+Chapter</text:bookmark-ref></text:p>
+<text:p text:style-name="FigureWithCaption"><draw:frame draw:name="img1"><draw:image xlink:href="lalune.jpg" xlink:type="simple" xlink:show="embed" xlink:actuate="onLoad" /></draw:frame></text:p>
+<text:p text:style-name="FigureCaption">Voyage dans la Lune</text:p>
+<text:p text:style-name="Text_20_body">Image 1 references
+<text:sequence-ref text:reference-format="caption" text:ref-name="lalune">La
+Lune</text:sequence-ref></text:p>
+```
+```
+% pandoc -f native -t opendocument+xrefs_number --quiet
+[Header 1 ("chapter1",[],[]) [Str "The",Space,Str "Chapter"]
+,Para [Str "Chapter",Space,Str "1",Space,Str "references",Space,Link ("",[],[]) [Str "The",Space,Str "Chapter"] ("#chapter1","")]
+,Figure ("lalune",[],[]) (Caption Nothing [Para [Str "lalune"]]) [Plain [Image ("",[],[]) [Str "lalune"] ("lalune.jpg","Voyage dans la Lune")]]
+,Para [Str "Image",Space,Str "1",Space,Str "references",Space,Link ("",[],[]) [Str "La",Space,Str "Lune"] ("#lalune","")]]
+^D
+<text:h text:style-name="Heading_20_1" text:outline-level="1"><text:bookmark-start text:name="chapter1" />The
+Chapter<text:bookmark-end text:name="chapter1" /></text:h>
+<text:p text:style-name="First_20_paragraph">Chapter 1 references
+<text:bookmark-ref text:reference-format="number" text:ref-name="chapter1"></text:bookmark-ref></text:p>
+<text:p text:style-name="FigureWithCaption"><draw:frame draw:name="img1"><draw:image xlink:href="lalune.jpg" xlink:type="simple" xlink:show="embed" xlink:actuate="onLoad" /></draw:frame></text:p>
+<text:p text:style-name="FigureCaption">lalune</text:p>
+<text:p text:style-name="Text_20_body">Image 1 references
+<text:sequence-ref text:reference-format="value" text:ref-name="lalune"></text:sequence-ref></text:p>
+```
+```
+% pandoc -f native -t opendocument+xrefs_number+xrefs_name --quiet
+[Header 1 ("chapter1",[],[]) [Str "The",Space,Str "Chapter"]
+,Para [Str "Chapter",Space,Str "1",Space,Str "references",Space,Link ("",[],[]) [Str "The",Space,Str "Chapter"] ("#chapter1","")]
+,Figure ("lalune",[],[]) (Caption Nothing [Para [Str "Voyage dans la Lune"]]) [Plain [Image ("",[],[]) [Str "lalune"] ("lalune.jpg","")]]
+,Para [Str "Image",Space,Str "1",Space,Str "references",Space,Link ("",[],[]) [Str "La",Space,Str "Lune"] ("#lalune","")]]
+^D
+<text:h text:style-name="Heading_20_1" text:outline-level="1"><text:bookmark-start text:name="chapter1" />The
+Chapter<text:bookmark-end text:name="chapter1" /></text:h>
+<text:p text:style-name="First_20_paragraph">Chapter 1 references
+<text:bookmark-ref text:reference-format="number" text:ref-name="chapter1"></text:bookmark-ref><text:s /><text:bookmark-ref text:reference-format="text" text:ref-name="chapter1">The
+Chapter</text:bookmark-ref></text:p>
+<text:p text:style-name="FigureWithCaption"><draw:frame draw:name="img1"><draw:image xlink:href="lalune.jpg" xlink:type="simple" xlink:show="embed" xlink:actuate="onLoad" /></draw:frame></text:p>
+<text:p text:style-name="FigureCaption">Voyage dans la Lune</text:p>
+<text:p text:style-name="Text_20_body">Image 1 references
+<text:sequence-ref text:reference-format="value" text:ref-name="lalune"></text:sequence-ref><text:s /><text:sequence-ref text:reference-format="caption" text:ref-name="lalune">La
+Lune</text:sequence-ref></text:p>
+```
diff --git a/documents/markdown/pandoc-md/6783.md b/documents/markdown/pandoc-md/6783.md
new file mode 100644
index 0000000..64e085d
--- /dev/null
+++ b/documents/markdown/pandoc-md/6783.md
@@ -0,0 +1,26 @@
+```
+% pandoc -f markdown -t plain -s --citeproc
+---
+references:
+- author:
+ - family: Jupyter
+ given: Project
+ container-title: Proceedings of the 17th Python in Science Conference
+ id: 'ref-1'
+ issued: 2018
+ title: 'Binder 2.0 - Reproducible, interactive, sharable environments for science at scale'
+ type: 'paper-conference'
+ volume:
+...
+
+This is a test[@ref-1].
+^D
+
+
+This is a test(Jupyter 2018).
+
+Jupyter, Project. 2018. “Binder 2.0 - Reproducible, Interactive,
+Sharable Environments for Science at Scale.” Proceedings of the 17th
+Python in Science Conference.
+```
+
diff --git a/documents/markdown/pandoc-md/6791.md b/documents/markdown/pandoc-md/6791.md
new file mode 100644
index 0000000..c35c04e
--- /dev/null
+++ b/documents/markdown/pandoc-md/6791.md
@@ -0,0 +1,47 @@
+```
+% pandoc -f docbook -t native --quiet
+<informaltable frame="all" rowsep="1" colsep="1">
+<?dbfo table-width="50%"?>
+<tgroup cols="2">
+<colspec colname="col_1" colwidth="6.25*"/>
+<colspec colname="col_2" colwidth="6.25*"/>
+<tbody>
+<row>
+<entry align="center" valign="top"><simpara>2</simpara></entry>
+<entry align="center" valign="top"><simpara>1</simpara></entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidth 0.25 )
+ , ( AlignDefault , ColWidth 0.25 )
+ ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "1" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
diff --git a/documents/markdown/pandoc-md/6792.md b/documents/markdown/pandoc-md/6792.md
new file mode 100644
index 0000000..d0d284f
--- /dev/null
+++ b/documents/markdown/pandoc-md/6792.md
@@ -0,0 +1,66 @@
+```
+% pandoc -f native -t opendocument -s --quiet
+[Table ("",[],[]) (Caption Nothing
+ [])
+ [(AlignDefault,ColWidth 0.25)
+ ,(AlignDefault,ColWidth 0.25)]
+ (TableHead ("",[],[])
+ [])
+ [(TableBody ("",[],[]) (RowHeadColumns 0)
+ []
+ [Row ("",[],[])
+ [Cell ("",[],[]) AlignCenter (RowSpan 1) (ColSpan 1)
+ [Para [Str "2"]]
+ ,Cell ("",[],[]) AlignCenter (RowSpan 1) (ColSpan 1)
+ [Para [Str "1"]]]])]
+ (TableFoot ("",[],[])
+ [])]
+^D
+<?xml version="1.0" encoding="utf-8" ?>
+<office:document-content xmlns:office="urn:oasis:names:tc:opendocument:xmlns:office:1.0" xmlns:style="urn:oasis:names:tc:opendocument:xmlns:style:1.0" xmlns:text="urn:oasis:names:tc:opendocument:xmlns:text:1.0" xmlns:table="urn:oasis:names:tc:opendocument:xmlns:table:1.0" xmlns:draw="urn:oasis:names:tc:opendocument:xmlns:drawing:1.0" xmlns:fo="urn:oasis:names:tc:opendocument:xmlns:xsl-fo-compatible:1.0" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:meta="urn:oasis:names:tc:opendocument:xmlns:meta:1.0" xmlns:number="urn:oasis:names:tc:opendocument:xmlns:datastyle:1.0" xmlns:svg="urn:oasis:names:tc:opendocument:xmlns:svg-compatible:1.0" xmlns:chart="urn:oasis:names:tc:opendocument:xmlns:chart:1.0" xmlns:dr3d="urn:oasis:names:tc:opendocument:xmlns:dr3d:1.0" xmlns:math="http://www.w3.org/1998/Math/MathML" xmlns:form="urn:oasis:names:tc:opendocument:xmlns:form:1.0" xmlns:script="urn:oasis:names:tc:opendocument:xmlns:script:1.0" xmlns:ooo="http://openoffice.org/2004/office" xmlns:ooow="http://openoffice.org/2004/writer" xmlns:oooc="http://openoffice.org/2004/calc" xmlns:dom="http://www.w3.org/2001/xml-events" xmlns:xforms="http://www.w3.org/2002/xforms" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" office:version="1.3">
+ <office:font-face-decls>
+ <style:font-face style:name="Courier New" style:font-family-generic="modern" style:font-pitch="fixed" svg:font-family="'Courier New'" />
+ </office:font-face-decls>
+ <office:automatic-styles>
+ <style:style style:name="fr2" style:family="graphic" style:parent-style-name="Formula"><style:graphic-properties style:vertical-pos="middle" style:vertical-rel="text" style:horizontal-pos="center" style:horizontal-rel="paragraph-content" style:wrap="none" /></style:style>
+ <style:style style:name="fr1" style:family="graphic" style:parent-style-name="Formula"><style:graphic-properties style:vertical-pos="middle" style:vertical-rel="text" /></style:style>
+ <style:style style:name="P1" style:family="paragraph" style:parent-style-name="Table_20_Contents">
+ <style:paragraph-properties fo:text-align="center" style:justify-single-word="false" />
+ </style:style>
+ <style:style style:name="P2" style:family="paragraph" style:parent-style-name="Table_20_Contents">
+ <style:paragraph-properties fo:text-align="center" style:justify-single-word="false" />
+ </style:style>
+ <style:style style:name="TableHeaderRowCell" style:family="table-cell">
+ <style:table-cell-properties fo:border="none" />
+ </style:style>
+ <style:style style:name="TableRowCell" style:family="table-cell">
+ <style:table-cell-properties fo:border="none" />
+ </style:style>
+ <style:style style:name="Table1" style:family="table">
+ <style:table-properties table:align="center" style:rel-width="50%" />
+ </style:style>
+ <style:style style:name="Table1.A" style:family="table-column">
+ <style:table-column-properties style:rel-column-width="16383*" />
+ </style:style>
+ <style:style style:name="Table1.B" style:family="table-column">
+ <style:table-column-properties style:rel-column-width="16383*" />
+ </style:style>
+ </office:automatic-styles>
+<office:body>
+<office:text>
+<table:table table:name="Table1" table:style-name="Table1">
+ <table:table-column table:style-name="Table1.A" />
+ <table:table-column table:style-name="Table1.B" />
+ <table:table-row>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="P1">2</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="P2">1</text:p>
+ </table:table-cell>
+ </table:table-row>
+</table:table>
+</office:text>
+</office:body>
+</office:document-content>
+```
diff --git a/documents/markdown/pandoc-md/6796.md b/documents/markdown/pandoc-md/6796.md
new file mode 100644
index 0000000..f51205a
--- /dev/null
+++ b/documents/markdown/pandoc-md/6796.md
@@ -0,0 +1,16 @@
+```
+% pandoc -f latex -t markdown
+\newcommand{\cL}{\mathcal{L}}
+\newcommand{\til}[1]{\tilde{#1}}
+
+$$\til\cL$$
+
+\newcommand{\mc}[1]{\mathcal{#1}}
+\newcommand{\dL}{\mc{L}}
+
+$$\til\dL$$
+^D
+$$\tilde{\mathcal{L}}$$
+
+$$\tilde{\mathcal{L}}$$
+```
diff --git a/documents/markdown/pandoc-md/6802.md b/documents/markdown/pandoc-md/6802.md
new file mode 100644
index 0000000..5e66c1d
--- /dev/null
+++ b/documents/markdown/pandoc-md/6802.md
@@ -0,0 +1,8 @@
+```
+% pandoc -f latex -t native
+\blockquote[test][]{quote}
+^D
+[ BlockQuote [ Para [ Str "quote" ] , Para [ Str "test" ] ]
+]
+
+```
diff --git a/documents/markdown/pandoc-md/6821.md b/documents/markdown/pandoc-md/6821.md
new file mode 100644
index 0000000..c389532
--- /dev/null
+++ b/documents/markdown/pandoc-md/6821.md
@@ -0,0 +1,80 @@
+```
+% pandoc -f native -t latex
+[ Para [ Code ( "" , [ "python" ] , [] ) "x = 5" ]
+, Figure
+ ( "" , [] , [] )
+ (Caption
+ Nothing
+ [ Plain
+ [ Str "This"
+ , Space
+ , Str "is"
+ , Space
+ , Str "a"
+ , Space
+ , Str "test"
+ , Space
+ , Code ( "" , [ "python" ] , [] ) "x = 5"
+ ]
+ ])
+ [ Plain
+ [ Image
+ ( "" , [] , [] )
+ [ Str "This"
+ , Space
+ , Str "is"
+ , Space
+ , Str "a"
+ , Space
+ , Str "test"
+ , Space
+ , Code ( "" , [ "python" ] , [] ) "x = 5"
+ ]
+ ( "test.png" , "" )
+ ]
+ ]
+, Table
+ ( "" , [] , [] )
+ (Caption
+ Nothing
+ [ Plain [ Code ( "" , [ "cpp" ] , [] ) "caption" ] ])
+ [ ( AlignDefault , ColWidthDefault ) ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody ( "" , [] , [] ) (RowHeadColumns 0) [] [] ]
+ (TableFoot
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "A" ] ]
+ ]
+ ])
+, Para [ Code ( "" , [ "cpp" ] , [] ) "caption" ]
+]
+^D
+\VERB|\NormalTok{x }\OperatorTok{=} \DecValTok{5}|
+
+\begin{figure}
+\centering
+\pandocbounded{\includegraphics[keepaspectratio,alt={This is a test x = 5}]{test.png}}
+\caption{This is a test
+\protect\VERB|\NormalTok{x }\OperatorTok{=} \DecValTok{5}|}
+\end{figure}
+
+\begin{longtable}[]{@{}l@{}}
+\caption{\protect\VERB|\NormalTok{caption}|}\tabularnewline
+\toprule\noalign{}
+\endfirsthead
+\endhead
+\midrule\noalign{}
+A \\
+\bottomrule\noalign{}
+\endlastfoot
+\end{longtable}
+
+\VERB|\NormalTok{caption}|
+```
diff --git a/documents/markdown/pandoc-md/6836.md b/documents/markdown/pandoc-md/6836.md
new file mode 100644
index 0000000..b8e668a
--- /dev/null
+++ b/documents/markdown/pandoc-md/6836.md
@@ -0,0 +1,41 @@
+```
+% pandoc -t native
+[@buchanan]
+
+(@foo)
+
+See @foo.
+
+[@buchanan]
+^D
+[ Para
+ [ Cite
+ [ Citation
+ { citationId = "buchanan"
+ , citationPrefix = []
+ , citationSuffix = []
+ , citationMode = NormalCitation
+ , citationNoteNum = 1
+ , citationHash = 0
+ }
+ ]
+ [ Str "[@buchanan]" ]
+ ]
+, OrderedList ( 1 , Example , TwoParens ) [ [] ]
+, Para [ Str "See" , Space , Str "1." ]
+, Para
+ [ Cite
+ [ Citation
+ { citationId = "buchanan"
+ , citationPrefix = []
+ , citationSuffix = []
+ , citationMode = NormalCitation
+ , citationNoteNum = 2
+ , citationHash = 0
+ }
+ ]
+ [ Str "[@buchanan]" ]
+ ]
+]
+```
+
diff --git a/documents/markdown/pandoc-md/6837.md b/documents/markdown/pandoc-md/6837.md
new file mode 100644
index 0000000..f3f800b
--- /dev/null
+++ b/documents/markdown/pandoc-md/6837.md
@@ -0,0 +1,29 @@
+```
+% pandoc -t markdown --markdown-headings=setext
+## Hi
+
+### Ok
+^D
+Hi
+--
+
+### Ok
+```
+
+```
+% pandoc -t markdown+lhs
+# Hi
+^D
+2> [WARNING] Rendering heading 'Hi' as a paragraph.
+2> ATX headings cannot be used in literate Haskell, because '#' is not
+2> allowed in column 1. Consider using --markdown-headings=setext.
+Hi
+```
+
+```
+% pandoc -t markdown --markdown-headings=atx
+Hi
+--
+^D
+## Hi
+```
diff --git a/documents/markdown/pandoc-md/6844.md b/documents/markdown/pandoc-md/6844.md
new file mode 100644
index 0000000..e7af336
--- /dev/null
+++ b/documents/markdown/pandoc-md/6844.md
@@ -0,0 +1,27 @@
+Negative numbers with siunitx
+
+```
+% pandoc -f latex -t native
+\SI{123}{\celsius}
+
+^D
+[ Para [ Str "123\160\176C" ] ]
+```
+
+```
+% pandoc -f latex -t native
+\SI{-123}{\celsius}
+
+^D
+[ Para [ Str "\8722\&123\160\176C" ] ]
+```
+
+```
+% pandoc -f latex -t native
+\SI{+123}{\celsius}
+
+^D
+[ Para [ Str "123\160\176C" ] ]
+```
+
+
diff --git a/documents/markdown/pandoc-md/6858.md b/documents/markdown/pandoc-md/6858.md
new file mode 100644
index 0000000..e59c277
--- /dev/null
+++ b/documents/markdown/pandoc-md/6858.md
@@ -0,0 +1,52 @@
+```
+% pandoc -t markdown -f man
+.TH FvwmAnimate 1 "Date" Fvwm "Fvwm Modules"
+.UC
+.SH NAME
+\fBFvwmAnimate\fP \- the fvwm animate module
+.SH SYNOPSIS
+Module FvwmAnimate [ModuleAlias]
+
+.IP "*FvwmAnimate: Color \fBcolor\fP"
+
+Tells \fBFvwmAnimate\fP what color to draw with.
+The color is "XOR'ed" (exclusive ORed) onto the background.
+
+.IP "*FvwmAnimate: Pixmap \fBpixmap\fP"
+
+Tells \fBFvwmAnimate\fP to use \fBpixmap\fP to draw with. This can be useful
+if \fB*FvwmAnimate: Color\fP gives poor results.
+^D
+# NAME
+
+**FvwmAnimate** - the fvwm animate module
+
+# SYNOPSIS
+
+Module FvwmAnimate \[ModuleAlias\]
+
+\*FvwmAnimate: Color color
+
+: Tells **FvwmAnimate** what color to draw with. The color is
+ \"XOR\'ed\" (exclusive ORed) onto the background.
+
+\*FvwmAnimate: Pixmap pixmap
+
+: Tells **FvwmAnimate** to use **pixmap** to draw with. This can be
+ useful if **\*FvwmAnimate: Color** gives poor results.
+```
+
+```
+% pandoc -t markdown -f man
+.IP "\[bu]"
+
+hi
+
+.IP "\[bu]"
+
+there
+^D
+- hi
+
+- there
+```
diff --git a/documents/markdown/pandoc-md/6869.md b/documents/markdown/pandoc-md/6869.md
new file mode 100644
index 0000000..cbef00f
--- /dev/null
+++ b/documents/markdown/pandoc-md/6869.md
@@ -0,0 +1,19 @@
+```
+% pandoc -f latex -t native
+\cite[„Aber“]{key}
+^D
+[ Para
+ [ Cite
+ [ Citation
+ { citationId = "key"
+ , citationPrefix = []
+ , citationSuffix = [ Str "\8222Aber\8220" ]
+ , citationMode = NormalCitation
+ , citationNoteNum = 0
+ , citationHash = 0
+ }
+ ]
+ [ RawInline (Format "latex") "\\cite[\8222Aber\8220]{key}" ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/6873.md b/documents/markdown/pandoc-md/6873.md
new file mode 100644
index 0000000..394b530
--- /dev/null
+++ b/documents/markdown/pandoc-md/6873.md
@@ -0,0 +1,35 @@
+```
+% pandoc -f latex -t native --citeproc
+\cite[„Etwas […{]} auslassen“]{key}
+^D
+2> [WARNING] Citeproc: citation key not found
+[ Para
+ [ Cite
+ [ Citation
+ { citationId = "key"
+ , citationPrefix = []
+ , citationSuffix =
+ [ Str "\8222Etwas"
+ , Space
+ , Str "[\8230"
+ , Span ( "" , [] , [] ) [ Str "]" ]
+ , Space
+ , Str "auslassen\8220"
+ ]
+ , citationMode = NormalCitation
+ , citationNoteNum = 0
+ , citationHash = 0
+ }
+ ]
+ [ Str "("
+ , Strong [ Str "key?" ]
+ , Str "\8222Etwas"
+ , Space
+ , Str "[\8230"
+ , Span ( "" , [] , [] ) [ Str "]" ]
+ , Space
+ , Str "auslassen\8220)"
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/6890.md b/documents/markdown/pandoc-md/6890.md
new file mode 100644
index 0000000..2676944
--- /dev/null
+++ b/documents/markdown/pandoc-md/6890.md
@@ -0,0 +1,134 @@
+```
+% pandoc -t native --citeproc
+---
+references:
+- author:
+ - family: Früchtel
+ given: Frank
+ - family: Budde
+ given: Wolfgang
+ - family: Cyprian
+ given: Gudrun
+ edition: 3
+ id: fruchtel-sozialer-2013a
+ issued: 2013
+ language: de-DE
+ publisher: Springer VS
+ publisher-place: Wiesbaden, Germany
+ title: "Sozialer Raum und Soziale Arbeit Fieldbook: Methoden und
+ Techniken"
+ title-short: Sozialer Raum und Soziale Arbeit Fieldbook
+ type: book
+---
+
+@fruchtel-sozialer-2013a
+
+Some text.[^1]
+
+[^1]: @fruchtel-sozialer-2013a
+^D
+[ Para
+ [ Cite
+ [ Citation
+ { citationId = "fruchtel-sozialer-2013a"
+ , citationPrefix = []
+ , citationSuffix = []
+ , citationMode = AuthorInText
+ , citationNoteNum = 1
+ , citationHash = 0
+ }
+ ]
+ [ Str "Fr\252chtel"
+ , Space
+ , Str "et"
+ , Space
+ , Str "al."
+ , Space
+ , Str "(2013)"
+ ]
+ ]
+, Para
+ [ Str "Some"
+ , Space
+ , Str "text."
+ , Note
+ [ Para
+ [ Cite
+ [ Citation
+ { citationId = "fruchtel-sozialer-2013a"
+ , citationPrefix = []
+ , citationSuffix = []
+ , citationMode = AuthorInText
+ , citationNoteNum = 2
+ , citationHash = 0
+ }
+ ]
+ [ Str "Fr\252chtel"
+ , Space
+ , Str "et"
+ , Space
+ , Str "al."
+ , Space
+ , Str "(2013)"
+ ]
+ ]
+ ]
+ ]
+, Div
+ ( "refs"
+ , [ "references" , "csl-bib-body" , "hanging-indent" ]
+ , []
+ )
+ [ Div
+ ( "ref-fruchtel-sozialer-2013a" , [ "csl-entry" ] , [] )
+ [ Para
+ [ Str "Fr\252chtel,"
+ , Space
+ , Str "Frank,"
+ , Space
+ , Str "Wolfgang"
+ , Space
+ , Str "Budde,"
+ , Space
+ , Str "and"
+ , Space
+ , Str "Gudrun"
+ , Space
+ , Str "Cyprian."
+ , Space
+ , Str "2013."
+ , Space
+ , Emph
+ [ Str "Sozialer"
+ , Space
+ , Str "Raum"
+ , Space
+ , Str "und"
+ , Space
+ , Str "Soziale"
+ , Space
+ , Str "Arbeit"
+ , Space
+ , Str "Fieldbook:"
+ , Space
+ , Str "Methoden"
+ , Space
+ , Str "und"
+ , Space
+ , Str "Techniken"
+ ]
+ , Str "."
+ , Space
+ , Str "3rd"
+ , Space
+ , Str "ed."
+ , Space
+ , Str "Springer"
+ , Space
+ , Str "VS."
+ ]
+ ]
+ ]
+]
+```
+
diff --git a/documents/markdown/pandoc-md/6925.md b/documents/markdown/pandoc-md/6925.md
new file mode 100644
index 0000000..3c55e23
--- /dev/null
+++ b/documents/markdown/pandoc-md/6925.md
@@ -0,0 +1,34 @@
+```
+% pandoc -f latex -t markdown
+\documentclass{amsart}
+\newtheorem{thm}{Theorem}[section]
+\theoremstyle{definition}
+\newtheorem{thm2}[section]{Theorem}
+\begin{document}
+\begin{thm}
+a
+\begin{figure}
+\includegraphics[]{1.png}
+\end{figure}
+\end{thm}
+
+\begin{thm2}
+a
+\begin{figure}
+\includegraphics[]{1.png}
+\end{figure}
+\end{thm2}
+\end{document}
+^D
+::: thm
+**Theorem 1**. *a*
+
+
+:::
+
+::: thm2
+**Theorem 1**. a
+
+
+:::
+```
diff --git a/documents/markdown/pandoc-md/6948.md b/documents/markdown/pandoc-md/6948.md
new file mode 100644
index 0000000..844ef7f
--- /dev/null
+++ b/documents/markdown/pandoc-md/6948.md
@@ -0,0 +1,31 @@
+Treat an image alone in its paragraph (but not a figure)
+as an independent image:
+```
+% pandoc -f native -t rst
+[Para [Image ("",["align-center"],[]) [Str "https://pandoc.org/diagram.jpg"] ("https://pandoc.org/diagram.jpg","")]]
+^D
+|https://pandoc.org/diagram.jpg|
+
+.. |https://pandoc.org/diagram.jpg| image:: https://pandoc.org/diagram.jpg
+```
+
+Here we just omit the center attribute as it's not valid:
+```
+% pandoc -f native -t rst
+[Para [Str "hi",Space,Image ("",["align-center"],[]) [Str "https://pandoc.org/diagram.jpg"] ("https://pandoc.org/diagram.jpg","")]]
+^D
+hi |https://pandoc.org/diagram.jpg|
+
+.. |https://pandoc.org/diagram.jpg| image:: https://pandoc.org/diagram.jpg
+```
+
+But we can use top, middle, or bottom alignment:
+```
+% pandoc -f native -t rst
+[Para [Str "hi",Space,Image ("",["align-top"],[]) [Str "https://pandoc.org/diagram.jpg"] ("https://pandoc.org/diagram.jpg","")]]
+^D
+hi |https://pandoc.org/diagram.jpg|
+
+.. |https://pandoc.org/diagram.jpg| image:: https://pandoc.org/diagram.jpg
+ :align: top
+```
diff --git a/documents/markdown/pandoc-md/6951.md b/documents/markdown/pandoc-md/6951.md
new file mode 100644
index 0000000..69815f8
--- /dev/null
+++ b/documents/markdown/pandoc-md/6951.md
@@ -0,0 +1,18 @@
+```
+% pandoc --citeproc -t plain --bibliography command/biblio.bib
+---
+references:
+- id: foo
+ title: Crazy
+ type: book
+...
+
+[@foo; @item1]
+
+^D
+(Crazy, n.d.; Doe 2005)
+
+Crazy. n.d.
+
+Doe, John. 2005. First Book. Cambridge University Press.
+```
diff --git a/documents/markdown/pandoc-md/6958.md b/documents/markdown/pandoc-md/6958.md
new file mode 100644
index 0000000..230371d
--- /dev/null
+++ b/documents/markdown/pandoc-md/6958.md
@@ -0,0 +1,10 @@
+Add thin space between single and double quotes.
+```
+% pandoc -t latex+smart
+---
+lang: en-GB
+---
+'["On the Outside"]{}: Constructing Cycling Citizenship.'
+^D
+`\,{``On the Outside''}: Constructing Cycling Citizenship.'
+```
diff --git a/documents/markdown/pandoc-md/6959.md b/documents/markdown/pandoc-md/6959.md
new file mode 100644
index 0000000..5002d33
--- /dev/null
+++ b/documents/markdown/pandoc-md/6959.md
@@ -0,0 +1,12 @@
+```
+% pandoc -t docx -o - | pandoc -f docx -t markdown --track-changes=all
+[This is the comment]{.comment-start id="1" author="Mike"
+date="2020-12-17T16:53:00Z"} [Here is my reply]{.comment-start id="2"
+author="Mike" date="2020-12-17T17:39:00Z"} This is the content being
+commented on [[]{.comment-end id="2"}]{.comment-end id="1"}
+^D
+[This is the comment]{.comment-start id="1" author="Mike"
+date="2020-12-17T16:53:00Z"} [Here is my reply]{.comment-start id="2"
+author="Mike" date="2020-12-17T17:39:00Z"} This is the content being
+commented on [[]{.comment-end id="2"}]{.comment-end id="1"}
+```
diff --git a/documents/markdown/pandoc-md/6970.md b/documents/markdown/pandoc-md/6970.md
new file mode 100644
index 0000000..45d9b76
--- /dev/null
+++ b/documents/markdown/pandoc-md/6970.md
@@ -0,0 +1,12 @@
+```
+% pandoc -f html -t native
+<a name="foo" class="bar baz" href='https://example.com' target='_blank'>https://example.com<a>
+^D
+[ Plain
+ [ Link
+ ( "foo" , [ "bar" , "baz" ] , [ ( "target" , "_blank" ) ] )
+ [ Str "https://example.com" ]
+ ( "https://example.com" , "" )
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/6992.md b/documents/markdown/pandoc-md/6992.md
new file mode 100644
index 0000000..bdfd4f3
--- /dev/null
+++ b/documents/markdown/pandoc-md/6992.md
@@ -0,0 +1,76 @@
+```
+% pandoc -f mediawiki -t native
+{| class="wikitable"
+!colspan=4 | template request
+|-
+| mode || No || String || MUST be "template" or omitted
+|}
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 4)
+ [ Para [ Str "template" , Space , Str "request" ] ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "mode" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "No" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "String" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para
+ [ Str "MUST"
+ , Space
+ , Str "be"
+ , Space
+ , Str "\"template\""
+ , Space
+ , Str "or"
+ , Space
+ , Str "omitted"
+ ]
+ ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+
+```
diff --git a/documents/markdown/pandoc-md/6993.md b/documents/markdown/pandoc-md/6993.md
new file mode 100644
index 0000000..d2baa27
--- /dev/null
+++ b/documents/markdown/pandoc-md/6993.md
@@ -0,0 +1,33 @@
+```
+% pandoc -f mediawiki -t native
+'''Should be bold '''
+^D
+[ Para
+ [ Strong
+ [ Str "Should" , Space , Str "be" , Space , Str "bold" ]
+ ]
+]
+```
+
+```
+% pandoc -f mediawiki -t native
+''' Should be bold'''
+^D
+[ Para
+ [ Strong
+ [ Str "Should" , Space , Str "be" , Space , Str "bold" ]
+ ]
+]
+```
+
+```
+% pandoc -f mediawiki -t native
+'' Should be emph ''
+^D
+[ Para
+ [ Emph
+ [ Str "Should" , Space , Str "be" , Space , Str "emph" ]
+ ]
+]
+```
+
diff --git a/documents/markdown/pandoc-md/7003.md b/documents/markdown/pandoc-md/7003.md
new file mode 100644
index 0000000..5f88a58
--- /dev/null
+++ b/documents/markdown/pandoc-md/7003.md
@@ -0,0 +1,58 @@
+```
+% pandoc -f latex -t native
+\documentclass{article}
+\usepackage{listings}
+
+\lstset{basicstyle=\ttfamily}
+
+\begin{filecontents*}[overwrite]{example.tex}
+\documentclass{article}
+\begin{document}
+\section{Bar}
+This a Bar section
+\end{document}
+\end{filecontents*}
+
+\begin{document}
+
+\section{With lstlisting environment}
+
+\begin{lstlisting}
+\documentclass{article}
+\begin{document}
+\section{Foo}
+This a Foo section
+\end{document}
+\end{lstlisting}
+
+\section{With lstinputlisting command}
+
+\lstinputlisting{example.tex}
+\end{document}
+^D
+[ Header
+ 1
+ ( "with-lstlisting-environment" , [] , [] )
+ [ Str "With"
+ , Space
+ , Str "lstlisting"
+ , Space
+ , Str "environment"
+ ]
+, CodeBlock
+ ( "" , [] , [] )
+ "\\documentclass{article}\n\\begin{document}\n\\section{Foo}\nThis a Foo section\n\\end{document}"
+, Header
+ 1
+ ( "with-lstinputlisting-command" , [] , [] )
+ [ Str "With"
+ , Space
+ , Str "lstinputlisting"
+ , Space
+ , Str "command"
+ ]
+, CodeBlock
+ ( "" , [ "latex" ] , [] )
+ "\\documentclass{article}\n\\begin{document}\n\\section{Bar}\nThis a Bar section\n\\end{document}"
+]
+```
diff --git a/documents/markdown/pandoc-md/7006.md b/documents/markdown/pandoc-md/7006.md
new file mode 100644
index 0000000..75f0fae
--- /dev/null
+++ b/documents/markdown/pandoc-md/7006.md
@@ -0,0 +1,23 @@
+```
+% pandoc -t html
+Test.[^fn]
+
+[^fn]: Foo:
+
+ 
+^D
+<p>Test.<a href="#fn1" class="footnote-ref" id="fnref1"
+role="doc-noteref"><sup>1</sup></a></p>
+<section id="footnotes" class="footnotes footnotes-end-of-document"
+role="doc-endnotes">
+<hr />
+<ol>
+<li id="fn1"><p>Foo:</p>
+<figure>
+<img src="/image.jpg" alt="Caption." />
+<figcaption aria-hidden="true">Caption.</figcaption>
+</figure>
+<a href="#fnref1" class="footnote-back" role="doc-backlink">↩︎</a></li>
+</ol>
+</section>
+```
diff --git a/documents/markdown/pandoc-md/7016.md b/documents/markdown/pandoc-md/7016.md
new file mode 100644
index 0000000..4b1e3ea
--- /dev/null
+++ b/documents/markdown/pandoc-md/7016.md
@@ -0,0 +1,51 @@
+```
+% pandoc --citeproc --to=jats_archiving --standalone
+---
+csl: command/apa.csl
+references:
+- id: doe
+ type: article
+ author:
+ - family: Doe
+ given: Jane
+ container-title: Proceedings of the Academy of Test Inputs
+ doi: 10.x/nope
+ issued: 2021
+ title: Another article
+...
+Blah [@doe].
+^D
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE article PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Archiving and Interchange DTD v1.2 20190208//EN"
+ "JATS-archivearticle1.dtd">
+<article xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:xlink="http://www.w3.org/1999/xlink" dtd-version="1.2" article-type="other">
+<front>
+<journal-meta>
+<journal-id></journal-id>
+<journal-title-group>
+</journal-title-group>
+<issn></issn>
+<publisher>
+<publisher-name></publisher-name>
+</publisher>
+</journal-meta>
+<article-meta>
+<permissions>
+</permissions>
+</article-meta>
+</front>
+<body>
+<p>Blah (Doe, 2021).</p>
+</body>
+<back>
+<ref-list>
+ <title></title>
+ <ref id="ref-doe">
+ <mixed-citation>Doe, J. (2021). Another article. <italic>Proceedings
+ of the Academy of Test Inputs</italic>.
+ doi:<ext-link ext-link-type="uri" xlink:href="https://doi.org/10.x/nope">10.x/nope</ext-link></mixed-citation>
+ </ref>
+</ref-list>
+</back>
+</article>
+```
diff --git a/documents/markdown/pandoc-md/7041.md b/documents/markdown/pandoc-md/7041.md
new file mode 100644
index 0000000..1773963
--- /dev/null
+++ b/documents/markdown/pandoc-md/7041.md
@@ -0,0 +1,23 @@
+```
+% pandoc -f html -t jats
+<table>
+ <tr><td><blockquote>Fly, you fools!</blockquote></td></tr>
+</table>
+^D
+<table-wrap>
+ <table>
+ <colgroup>
+ <col width="100%" />
+ </colgroup>
+ <tbody>
+ <tr>
+ <td><p specific-use="wrapper">
+ <disp-quote>
+ <p>Fly, you fools!</p>
+ </disp-quote>
+ </p></td>
+ </tr>
+ </tbody>
+ </table>
+</table-wrap>
+```
diff --git a/documents/markdown/pandoc-md/7042.md b/documents/markdown/pandoc-md/7042.md
new file mode 100644
index 0000000..fec3c4b
--- /dev/null
+++ b/documents/markdown/pandoc-md/7042.md
@@ -0,0 +1,149 @@
+```
+% pandoc -f markdown -t jats_publishing+element_citations --citeproc -s
+---
+nocite: "[@*]"
+references:
+- author:
+ - family: Jane
+ given: Doe
+ container-title: Public Library of Tests
+ id: year-month
+ issued: 1999-08
+ title: Year and month
+ type: article-journal
+- accessed: 1999-01-22
+ author:
+ - family: Negidius
+ given: Numerius
+ - literal: others
+ container-title: Public Library of Tests
+ id: access-date
+ issued: 1911-10-03
+ title: Entry with access date and et al.
+ type: article-journal
+- author:
+ - family: Beethoven
+ given: Ludwig
+ dropping-particle: van
+ - family: Bray
+ given: Jan
+ non-dropping-particle: de
+ container-title: Public Library of Tests
+ id: name-particles
+ issued: 1820
+ title: Name particles, dropping and non-dropping
+ type: article-journal
+- author:
+ - 宮水 三葉
+ - 立花 瀧
+ title: Big Book of Tests
+ id: book-with-japanese-authors
+ issued: 2016
+ type: book
+- author:
+ - family: Watson
+ given: J. D.
+ - family: Crick
+ given: F. H. C.
+ container-title: Nature
+ doi: '10.1038/171737a0'
+ id: full-journal-article-entry
+ issue: 4356
+ issued: '1953-04-01'
+ page: 737-738
+ pmid: 13054692
+ title: 'Molecular Structure of Nucleic Acids: A Structure for Deoxyribose Nucleic Acid'
+ type: article-journal
+ volume: 171
+...
+^D
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE article PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Publishing DTD v1.2 20190208//EN"
+ "JATS-publishing1.dtd">
+<article xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:xlink="http://www.w3.org/1999/xlink" dtd-version="1.2" article-type="other">
+<front>
+<journal-meta>
+<journal-id></journal-id>
+<journal-title-group>
+</journal-title-group>
+<issn></issn>
+<publisher>
+<publisher-name></publisher-name>
+</publisher>
+</journal-meta>
+<article-meta>
+<permissions>
+</permissions>
+</article-meta>
+</front>
+<body>
+
+</body>
+<back>
+<ref-list>
+ <title></title>
+ <ref id="ref-year-month">
+ <element-citation publication-type="article-journal">
+ <person-group person-group-type="author">
+ <name><surname>Jane</surname><given-names>Doe</given-names></name>
+ </person-group>
+ <article-title>Year and month</article-title>
+ <source>Public Library of Tests</source>
+ <year iso-8601-date="1999-08">1999</year><month>08</month>
+ </element-citation>
+ </ref>
+ <ref id="ref-access-date">
+ <element-citation publication-type="article-journal">
+ <person-group person-group-type="author">
+ <name><surname>Negidius</surname><given-names>Numerius</given-names></name>
+ <etal/>
+ </person-group>
+ <article-title>Entry with access date and et al.</article-title>
+ <source>Public Library of Tests</source>
+ <year iso-8601-date="1911-10-03">1911</year><month>10</month><day>03</day>
+ <date-in-citation content-type="access-date"><year iso-8601-date="1999-01-22">1999</year><month>01</month><day>22</day></date-in-citation>
+ </element-citation>
+ </ref>
+ <ref id="ref-name-particles">
+ <element-citation publication-type="article-journal">
+ <person-group person-group-type="author">
+ <name><surname>Beethoven</surname><given-names>Ludwig van</given-names></name>
+ <name><surname>de Bray</surname><given-names>Jan</given-names></name>
+ </person-group>
+ <article-title>Name particles, dropping and non-dropping</article-title>
+ <source>Public Library of Tests</source>
+ <year iso-8601-date="1820">1820</year>
+ </element-citation>
+ </ref>
+ <ref id="ref-book-with-japanese-authors">
+ <element-citation publication-type="book">
+ <person-group person-group-type="author">
+ <string-name>宮水 三葉</string-name>
+ <string-name>立花 瀧</string-name>
+ </person-group>
+ <source>Big Book of Tests</source>
+ <year iso-8601-date="2016">2016</year>
+ </element-citation>
+ </ref>
+ <ref id="ref-full-journal-article-entry">
+ <element-citation publication-type="article-journal">
+ <person-group person-group-type="author">
+ <name><surname>Watson</surname><given-names>J. D.</given-names></name>
+ <name><surname>Crick</surname><given-names>F. H. C.</given-names></name>
+ </person-group>
+ <article-title>Molecular Structure of Nucleic Acids: A Structure for Deoxyribose Nucleic Acid</article-title>
+ <source>Nature</source>
+ <year iso-8601-date="1953-04-01">1953</year><month>04</month><day>01</day>
+ <volume>171</volume>
+ <issue>4356</issue>
+ <pub-id pub-id-type="doi">10.1038/171737a0</pub-id>
+ <pub-id pub-id-type="pmid">13054692</pub-id>
+ <fpage>737</fpage>
+ <lpage>738</lpage>
+ </element-citation>
+ </ref>
+</ref-list>
+</back>
+</article>
+
+```
diff --git a/documents/markdown/pandoc-md/7064.md b/documents/markdown/pandoc-md/7064.md
new file mode 100644
index 0000000..2690b92
--- /dev/null
+++ b/documents/markdown/pandoc-md/7064.md
@@ -0,0 +1,32 @@
+```
+% pandoc -f rst -t html
+.. csv-table:: Changes
+ :header: "Version", "Date", "Description"
+ :widths: 15, 15, 70
+ :delim: $
+
+ 0.1.0 $ 18/02/2013 $ Initial Release
+^D
+<table>
+<caption>Changes</caption>
+<colgroup>
+<col style="width: 15%" />
+<col style="width: 15%" />
+<col style="width: 70%" />
+</colgroup>
+<thead>
+<tr>
+<th>Version</th>
+<th>Date</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>0.1.0</td>
+<td>18/02/2013</td>
+<td>Initial Release</td>
+</tr>
+</tbody>
+</table>
+```
diff --git a/documents/markdown/pandoc-md/7067.md b/documents/markdown/pandoc-md/7067.md
new file mode 100644
index 0000000..34b3bb8
--- /dev/null
+++ b/documents/markdown/pandoc-md/7067.md
@@ -0,0 +1,90 @@
+```
+% pandoc -t biblatex
+---
+references:
+- id: garaud
+ author:
+ - family: Garaud
+ given: Marcel
+ container-title: Bulletin de la Societé des antiquaires de l’Ouest
+ collection-title: 4
+ issued:
+ - year: 1967
+ language: fr-FR
+ page: 11-27
+ title: Recherches sur les défrichements dans la Gâtine poitevine aux XI^e^ et XII^e^ siècles
+ type: article-journal
+ volume: 9
+...
+^D
+@article{garaud,
+ author = {Garaud, Marcel},
+ title = {Recherches sur les défrichements dans la Gâtine poitevine aux
+ XI\textsuperscript{e} et XII\textsuperscript{e} siècles},
+ journal = {Bulletin de la Societé des antiquaires de l’Ouest},
+ series = {4},
+ volume = {9},
+ pages = {11-27},
+ date = {1967},
+ langid = {fr-FR}
+}
+```
+
+```
+% pandoc -t bibtex
+---
+references:
+- id: garaud
+ author:
+ - family: Garaud
+ given: Marcel
+ container-title: Bulletin de la Société des antiquaires de l’Ouest
+ collection-title: 4
+ issued:
+ - year: 1967
+ language: fr-FR
+ page: 11-27
+ title: Recherches sur les défrichements dans la Gâtine poitevine aux XI^e^ et XII^e^ siècles
+ type: article-journal
+ volume: 9
+...
+^D
+@article{garaud,
+ author = {Garaud, Marcel},
+ title = {{Recherches sur les défrichements dans la Gâtine poitevine
+ aux XI\textsuperscript{e} et XII\textsuperscript{e} siècles}},
+ journal = {Bulletin de la Société des antiquaires de l’Ouest},
+ series = {4},
+ volume = {9},
+ pages = {11-27},
+ year = {1967}
+}
+```
+
+This tests the titlecasing of a word with an accented second letter:
+```
+% pandoc -t bibtex
+---
+references:
+- id: garaud
+ author:
+ - family: Garaud
+ given: Marcel
+ container-title: English Journal
+ issued:
+ - year: 1967
+ language: en-US
+ title: Research on the défrichements in the Gâtine poitevine
+ type: article-journal
+ volume: 9
+...
+^D
+@article{garaud,
+ author = {Garaud, Marcel},
+ title = {Research on the Défrichements in the {Gâtine} Poitevine},
+ journal = {English Journal},
+ volume = {9},
+ year = {1967}
+}
+```
+
diff --git a/documents/markdown/pandoc-md/7080.md b/documents/markdown/pandoc-md/7080.md
new file mode 100644
index 0000000..565a654
--- /dev/null
+++ b/documents/markdown/pandoc-md/7080.md
@@ -0,0 +1,17 @@
+```
+% pandoc -f markdown_mmd -t native
+![][image]
+
+[image]: image.png width=100px height=150px
+^D
+[ Para
+ [ Image
+ ( ""
+ , []
+ , [ ( "width" , "100px" ) , ( "height" , "150px" ) ]
+ )
+ []
+ ( "image.png" , "" )
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/7092.md b/documents/markdown/pandoc-md/7092.md
new file mode 100644
index 0000000..d6a5263
--- /dev/null
+++ b/documents/markdown/pandoc-md/7092.md
@@ -0,0 +1,10 @@
+```
+% pandoc -flatex+raw_tex -t native
+\newcommand{\em}[1]{\emph{#1}}
+
+\em{\parseMe{foo}}
+^D
+[ Para
+ [ Emph [ RawInline (Format "latex") "\\parseMe{foo}" ] ]
+]
+```
diff --git a/documents/markdown/pandoc-md/7099.md b/documents/markdown/pandoc-md/7099.md
new file mode 100644
index 0000000..5dcaa64
--- /dev/null
+++ b/documents/markdown/pandoc-md/7099.md
@@ -0,0 +1,18 @@
+```
+% pandoc -f html -t native --verbose
+<iframe src=""></iframe>
+^D
+2> [INFO] Skipped '<iframe src></iframe>' at input line 1 column 16
+[]
+```
+
+```
+% pandoc -f html -t native --verbose
+<iframe src="h:invalid@url"></iframe>
+^D
+2> [INFO] Fetching h:invalid@url...
+2> [WARNING] Could not fetch resource h:invalid@url: Could not fetch h:invalid@url
+2> InvalidUrlException "h:invalid@url" "Invalid scheme"
+2> [INFO] Skipped '<iframe src="h:invalid@url"></iframe>' at input line 1 column 29
+[]
+```
diff --git a/documents/markdown/pandoc-md/7112.md b/documents/markdown/pandoc-md/7112.md
new file mode 100644
index 0000000..e225417
--- /dev/null
+++ b/documents/markdown/pandoc-md/7112.md
@@ -0,0 +1,15 @@
+```
+% pandoc -f rst
+.. csv-table::
+
+ setting, ``echo PATH="path"``
+^D
+<table>
+<tbody>
+<tr>
+<td>setting</td>
+<td><code>echo PATH="path"</code></td>
+</tr>
+</tbody>
+</table>
+```
diff --git a/documents/markdown/pandoc-md/7129.md b/documents/markdown/pandoc-md/7129.md
new file mode 100644
index 0000000..14005f0
--- /dev/null
+++ b/documents/markdown/pandoc-md/7129.md
@@ -0,0 +1,55 @@
+```
+% pandoc -f latex -t native
+\begin{tabular}{ll} \hline
+ FOO & BAR \\ \hline
+ foo & \verb|b&r| \\ \hline
+\end{tabular}
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignLeft , ColWidthDefault )
+ , ( AlignLeft , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "FOO" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "BAR" ] ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "foo" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Code ( "" , [] , [] ) "b&r" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
diff --git a/documents/markdown/pandoc-md/7132.md b/documents/markdown/pandoc-md/7132.md
new file mode 100644
index 0000000..30d4c0b
--- /dev/null
+++ b/documents/markdown/pandoc-md/7132.md
@@ -0,0 +1,10 @@
+```
+% pandoc -f markdown -t org --columns=72
+- This line has exactly the wrong number of characters before the number 5.
+- Long line ending with a number (this time it is in parentheses and a 23)
+^D
+- This line has exactly the wrong number of characters before the
+ number 5.
+- Long line ending with a number (this time it is in parentheses and
+ a 23)
+```
diff --git a/documents/markdown/pandoc-md/7134.md b/documents/markdown/pandoc-md/7134.md
new file mode 100644
index 0000000..041d7ea
--- /dev/null
+++ b/documents/markdown/pandoc-md/7134.md
@@ -0,0 +1,51 @@
+```
+% pandoc -f rst -t native
+This is a paragraph.
+
+ This is a block quote.
+
+..
+
+ This should be a second block quote.
+^D
+[ Para
+ [ Str "This"
+ , Space
+ , Str "is"
+ , Space
+ , Str "a"
+ , Space
+ , Str "paragraph."
+ ]
+, BlockQuote
+ [ Para
+ [ Str "This"
+ , Space
+ , Str "is"
+ , Space
+ , Str "a"
+ , Space
+ , Str "block"
+ , Space
+ , Str "quote."
+ ]
+ ]
+, BlockQuote
+ [ Para
+ [ Str "This"
+ , Space
+ , Str "should"
+ , Space
+ , Str "be"
+ , Space
+ , Str "a"
+ , Space
+ , Str "second"
+ , Space
+ , Str "block"
+ , Space
+ , Str "quote."
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/7145.md b/documents/markdown/pandoc-md/7145.md
new file mode 100644
index 0000000..623f408
--- /dev/null
+++ b/documents/markdown/pandoc-md/7145.md
@@ -0,0 +1,72 @@
+```
+% pandoc -f mediawiki -t native
+Maecenas at sapien tempor, pretium turpis ut, imperdiet augue.<ref>This is a multiline
+
+reference
+<i>with</i>
+empty
+
+linebreaks</ref> Nulla ut massa eget ex venenatis lobortis id in eros.
+^D
+[ Para
+ [ Str "Maecenas"
+ , Space
+ , Str "at"
+ , Space
+ , Str "sapien"
+ , Space
+ , Str "tempor,"
+ , Space
+ , Str "pretium"
+ , Space
+ , Str "turpis"
+ , Space
+ , Str "ut,"
+ , Space
+ , Str "imperdiet"
+ , Space
+ , Str "augue."
+ , Note
+ [ Para
+ [ Str "This"
+ , Space
+ , Str "is"
+ , Space
+ , Str "a"
+ , Space
+ , Str "multiline"
+ ]
+ , Para
+ [ Str "reference"
+ , SoftBreak
+ , RawInline (Format "html") "<i>"
+ , Str "with"
+ , RawInline (Format "html") "</i>"
+ , SoftBreak
+ , Str "empty"
+ ]
+ , Para [ Str "linebreaks" ]
+ ]
+ , Space
+ , Str "Nulla"
+ , Space
+ , Str "ut"
+ , Space
+ , Str "massa"
+ , Space
+ , Str "eget"
+ , Space
+ , Str "ex"
+ , Space
+ , Str "venenatis"
+ , Space
+ , Str "lobortis"
+ , Space
+ , Str "id"
+ , Space
+ , Str "in"
+ , Space
+ , Str "eros."
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/7155.md b/documents/markdown/pandoc-md/7155.md
new file mode 100644
index 0000000..454c387
--- /dev/null
+++ b/documents/markdown/pandoc-md/7155.md
@@ -0,0 +1,33 @@
+```
+% pandoc -f markdown+tex_math_single_backslash -t native
+\(x\) \[x\]
+\\(x\\) \\[x\\]
+^D
+[ Para
+ [ Math InlineMath "x"
+ , Space
+ , Math DisplayMath "x"
+ , SoftBreak
+ , Str "\\(x\\)"
+ , Space
+ , Str "\\[x\\]"
+ ]
+]
+```
+
+```
+% pandoc -f markdown+tex_math_double_backslash -t native
+\(x\) \[x\]
+\\(x\\) \\[x\\]
+^D
+[ Para
+ [ Str "(x)"
+ , Space
+ , Str "[x]"
+ , SoftBreak
+ , Math InlineMath "x"
+ , Space
+ , Math DisplayMath "x"
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/7172.md b/documents/markdown/pandoc-md/7172.md
new file mode 100644
index 0000000..a7b5a4c
--- /dev/null
+++ b/documents/markdown/pandoc-md/7172.md
@@ -0,0 +1,17 @@
+```
+% pandoc -t markdown
+- one
+ - two
+^D
+- one
+ - two
+```
+
+```
+% pandoc -t markdown+four_space_rule
+- one
+ - two
+^D
+- one
+ - two
+```
diff --git a/documents/markdown/pandoc-md/7173.md b/documents/markdown/pandoc-md/7173.md
new file mode 100644
index 0000000..2599dc1
--- /dev/null
+++ b/documents/markdown/pandoc-md/7173.md
@@ -0,0 +1,137 @@
+```
+% pandoc -f docbook -t latex
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//W3C//DTD MathML 2.0//EN" "http://www.w3.org/Math/DTD/mathml2/mathml2.dtd">
+<?xml-model href="http://www.oxygenxml.com/docbook/xml/5.0/rng/dbmathml.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
+<?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>
+<article xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ version="5.1">
+ <title>Untitled Document</title>
+ <para>Word</para>
+ <informalequation>
+ <alt role='tex'>1+2</alt>
+ <m:math xmlns:m="http://www.w3.org/1998/Math/MathML">
+ <m:mrow>
+ <m:mrow><m:mn>1</m:mn><m:mo>+</m:mo><m:mn>2</m:mn>
+ </m:mrow>
+ </m:mrow>
+ </m:math>
+ </informalequation>
+</article>
+^D
+Word
+
+\[1 + 2\]
+```
+
+```
+% pandoc -f docbook -t latex
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//W3C//DTD MathML 2.0//EN" "http://www.w3.org/Math/DTD/mathml2/mathml2.dtd">
+<?xml-model href="http://www.oxygenxml.com/docbook/xml/5.0/rng/dbmathml.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
+<?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>
+<article xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ version="5.1">
+ <title>Untitled Document</title>
+ <para>Word</para>
+ <informalequation>
+ <alt role='tex'>1+2</alt>
+ <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML">
+ <mml:mrow>
+ <mml:mrow><mml:mn>1</mml:mn><mml:mo>+</mml:mo><mml:mn>2</mml:mn>
+ </mml:mrow>
+ </mml:mrow>
+ </mml:math>
+ </informalequation>
+</article>
+^D
+Word
+
+\[1 + 2\]
+```
+
+```
+% pandoc -f docbook -t latex
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//W3C//DTD MathML 2.0//EN" "http://www.w3.org/Math/DTD/mathml2/mathml2.dtd">
+<?xml-model href="http://www.oxygenxml.com/docbook/xml/5.0/rng/dbmathml.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
+<?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>
+<article xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ version="5.1">
+ <title>Untitled Document</title>
+ <para>Word</para>
+ <informalequation>
+ <alt role='tex'>1+2</alt>
+ <math xmlns="http://www.w3.org/1998/Math/MathML">
+ <mrow>
+ <mrow><mn>1</mn><mo>+</mo><mn>2</mn>
+ </mrow>
+ </mrow>
+ </math>
+ </informalequation>
+</article>
+^D
+Word
+
+\[1 + 2\]
+```
+
+```
+% pandoc -f docbook -t latex
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//W3C//DTD MathML 2.0//EN" "http://www.w3.org/Math/DTD/mathml2/mathml2.dtd">
+<?xml-model href="http://www.oxygenxml.com/docbook/xml/5.0/rng/dbmathml.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
+<?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>
+<article xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:m="http://www.w3.org/1998/Math/MathML"
+ version="5.1">
+ <title>Untitled Document</title>
+ <para>Word</para>
+ <informalequation>
+ <alt role='tex'>1+2</alt>
+ <m:math>
+ <m:mrow>
+ <m:mrow><m:mn>1</m:mn><m:mo>+</m:mo><m:mn>2</m:mn>
+ </m:mrow>
+ </m:mrow>
+ </m:math>
+ </informalequation>
+</article>
+^D
+Word
+
+\[1 + 2\]
+```
+
+```
+% pandoc -f docbook -t latex
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//W3C//DTD MathML 2.0//EN" "http://www.w3.org/Math/DTD/mathml2/mathml2.dtd">
+<?xml-model href="http://www.oxygenxml.com/docbook/xml/5.0/rng/dbmathml.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
+<?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>
+<article xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:mml="http://www.w3.org/1998/Math/MathML"
+ version="5.1">
+ <title>Untitled Document</title>
+ <para>Word</para>
+ <informalequation>
+ <alt role='tex'>1+2</alt>
+ <mml:math>
+ <mml:mrow>
+ <mml:mrow><mml:mn>1</mml:mn><mml:mo>+</mml:mo><mml:mn>2</mml:mn>
+ </mml:mrow>
+ </mml:mrow>
+ </mml:math>
+ </informalequation>
+</article>
+^D
+Word
+
+\[1 + 2\]
+```
+
diff --git a/documents/markdown/pandoc-md/7181.md b/documents/markdown/pandoc-md/7181.md
new file mode 100644
index 0000000..6915e99
--- /dev/null
+++ b/documents/markdown/pandoc-md/7181.md
@@ -0,0 +1,11 @@
+```
+% pandoc -t latex
+{page=13,trim=1cm,clip,width=4cm}
+^D
+\begin{figure}
+\centering
+\pandocbounded{\includegraphics[keepaspectratio,page=13,trim=1cm,clip,width=4cm,alt={Global frog population.}]{slides.pdf}}
+\caption{Global frog population.}
+\end{figure}
+
+```
diff --git a/documents/markdown/pandoc-md/7201.md b/documents/markdown/pandoc-md/7201.md
new file mode 100644
index 0000000..2cc2534
--- /dev/null
+++ b/documents/markdown/pandoc-md/7201.md
@@ -0,0 +1,47 @@
+```
+% pandoc -t revealjs --slide-level=1
+# Overview
+
+:::::::::::::: {.columns}
+::: {.column width="40%"}
+
+Left column
+
+:::
+::: {.column width="60%"}
+
+* First list
+ * subitem
+
+. . .
+
+* Second list
+ * subitem
+:::
+::::::::::::::
+^D
+<section id="overview" class="slide level1">
+<h1>Overview</h1>
+<div class="columns">
+<div class="column" style="width:40%;">
+<p>Left column</p>
+</div><div class="column" style="width:60%;">
+<ul>
+<li>First list
+<ul>
+<li>subitem</li>
+</ul></li>
+</ul>
+<div class="fragment">
+<ul>
+<li>Second list
+<ul>
+<li>subitem</li>
+</ul></li>
+</ul>
+</div>
+</div>
+</div>
+</section>
+
+```
diff --git a/documents/markdown/pandoc-md/7214.md b/documents/markdown/pandoc-md/7214.md
new file mode 100644
index 0000000..1d29b04
--- /dev/null
+++ b/documents/markdown/pandoc-md/7214.md
@@ -0,0 +1,28 @@
+```
+% pandoc
++------------+----------+------------------+
+|日本語 | の文字列 | words in english |
++------------+----------+------------------+
+|abc defghij | def | xyz |
++------------+----------+------------------+
+^D
+<table style="width:60%;">
+<colgroup>
+<col style="width: 18%" />
+<col style="width: 15%" />
+<col style="width: 26%" />
+</colgroup>
+<tbody>
+<tr>
+<td>日本語</td>
+<td>の文字列</td>
+<td>words in english</td>
+</tr>
+<tr>
+<td>abc defghij</td>
+<td>def</td>
+<td>xyz</td>
+</tr>
+</tbody>
+</table>
+```
diff --git a/documents/markdown/pandoc-md/7216.md b/documents/markdown/pandoc-md/7216.md
new file mode 100644
index 0000000..2fb99c7
--- /dev/null
+++ b/documents/markdown/pandoc-md/7216.md
@@ -0,0 +1,19 @@
+```
+% pandoc -t latex
+"This is some text in quotes. Another paragraph by the same speaker follows. The first paragraph should have no close quote.
+
+"The second paragraph should have open and close quotes."
+
+| "Open quote on this line,
+| Close quote on the next line."
+| "Quotes on the same line."
+^D
+``This is some text in quotes. Another paragraph by the same speaker
+follows. The first paragraph should have no close quote.
+
+``The second paragraph should have open and close quotes.''
+
+``Open quote on this line,\\
+Close quote on the next line.''\\
+``Quotes on the same line.''
+```
diff --git a/documents/markdown/pandoc-md/7219.md b/documents/markdown/pandoc-md/7219.md
new file mode 100644
index 0000000..9f5bc30
--- /dev/null
+++ b/documents/markdown/pandoc-md/7219.md
@@ -0,0 +1,25 @@
+```
+% pandoc --citeproc -t plain
+---
+references:
+- author:
+ - family: Reese
+ given: Trevor R.
+ collection-title: 3rd series
+ container-title: William and Mary Quarterly
+ id: reese
+ issued: 1958
+ language: en-US
+ page: 168-190
+ title: Georgia in Anglo-Spanish diplomacy, 1736-1739
+ type: article-journal
+ volume: 15
+...
+and also in -@reese
+^D
+and also in (1958)
+
+Reese, Trevor R. 1958. “Georgia in Anglo-Spanish Diplomacy, 1736-1739.”
+William and Mary Quarterly, 3rd series, vol. 15: 168–90.
+
+```
diff --git a/documents/markdown/pandoc-md/7266.md b/documents/markdown/pandoc-md/7266.md
new file mode 100644
index 0000000..9db8336
--- /dev/null
+++ b/documents/markdown/pandoc-md/7266.md
@@ -0,0 +1,10 @@
+```
+% pandoc -f biblatex -t biblatex -s
+@article{id,
+ annote = "annotation"
+}
+^D
+@article{id,
+ annote = {annotation}
+}
+```
diff --git a/documents/markdown/pandoc-md/7272.md b/documents/markdown/pandoc-md/7272.md
new file mode 100644
index 0000000..a5e519b
--- /dev/null
+++ b/documents/markdown/pandoc-md/7272.md
@@ -0,0 +1,30 @@
+```
+% pandoc -t latex -f html
+<table>
+ <tbody>
+ <tr>
+ <td>
+ <span>
+ text
+ <br />
+ text2
+ </span>
+ </td>
+ </tr>
+ </tbody>
+</table>
+^D
+{\def\LTcaptype{none} % do not increment counter
+\begin{longtable}[]{@{}
+ >{\raggedright\arraybackslash}p{(\linewidth - 0\tabcolsep) * \real{1.0000}}@{}}
+\toprule\noalign{}
+\endhead
+\bottomrule\noalign{}
+\endlastfoot
+\begin{minipage}[t]{\linewidth}\raggedright
+{ text\\
+text2 }\strut
+\end{minipage} \\
+\end{longtable}
+}
+```
diff --git a/documents/markdown/pandoc-md/7278.md b/documents/markdown/pandoc-md/7278.md
new file mode 100644
index 0000000..5cd227a
--- /dev/null
+++ b/documents/markdown/pandoc-md/7278.md
@@ -0,0 +1,38 @@
+```
+% pandoc -t beamer
+# Slide
+
+Some blocks:
+
+## example block title {.example}
+
+text in block
+
+## alert block title {.alert}
+
+text in block
+
+## block title
+
+text in block
+^D
+\begin{frame}{Slide}
+\protect\phantomsection\label{slide}
+Some blocks:
+
+\begin{exampleblock}{example block title}
+\protect\phantomsection\label{example-block-title}
+text in block
+\end{exampleblock}
+
+\begin{alertblock}{alert block title}
+\protect\phantomsection\label{alert-block-title}
+text in block
+\end{alertblock}
+
+\begin{block}{block title}
+\protect\phantomsection\label{block-title}
+text in block
+\end{block}
+\end{frame}
+```
diff --git a/documents/markdown/pandoc-md/7288.md b/documents/markdown/pandoc-md/7288.md
new file mode 100644
index 0000000..e94aeee
--- /dev/null
+++ b/documents/markdown/pandoc-md/7288.md
@@ -0,0 +1,40 @@
+```
+% pandoc -f rst -t ms
+.. list-table::
+ :widths: 50 50
+ :header-rows: 1
+
+ * - Left
+ - Right
+ * - Long text that should be easy to break up into multiple lines
+ - Another long text that should be easy to break up into multiple lines
+
+ Bar
+^D
+.PP
+.na
+.nr LLold \n[LL]
+.TS
+delim(@@) tab( );
+lw(35.0n) lw(35.0n).
+T{
+Left
+T} T{
+Right
+T}
+_
+T{
+.nr LL 35.0n
+.LP
+Long text that should be easy to break up into multiple lines
+T} T{
+.nr LL 35.0n
+.PP
+Another long text that should be easy to break up into multiple lines
+.PP
+Bar
+T}
+.TE
+.nr LL \n[LLold]
+.ad
+```
diff --git a/documents/markdown/pandoc-md/7299.md b/documents/markdown/pandoc-md/7299.md
new file mode 100644
index 0000000..0847c40
--- /dev/null
+++ b/documents/markdown/pandoc-md/7299.md
@@ -0,0 +1,23 @@
+```
+% pandoc -f latex -t plain
+$1-{\ensuremath{r}\xspace}$
+^D
+1 − r
+```
+
+```
+% pandoc -f latex -t plain
+\newcommand{\foo}{Foo\xspace}
+
+$\text{\foo bar}$
+^D
+Foo bar
+```
+
+```
+% pandoc -f latex -t plain
+a\xspace b
+^D
+a b
+```
+
diff --git a/documents/markdown/pandoc-md/7321.md b/documents/markdown/pandoc-md/7321.md
new file mode 100644
index 0000000..f5e644b
--- /dev/null
+++ b/documents/markdown/pandoc-md/7321.md
@@ -0,0 +1,24 @@
+```
+% pandoc -t plain --citeproc --wrap=none
+---
+references:
+- id: fenner2012a
+ title: One-click science marketing
+ author:
+ - family: Fenner
+ given: Martin
+ container-title: Nature Materials
+ volume: 11
+ issue: 4
+ publisher: Nature Publishing Group
+ type: article-journal
+ issued:
+ year: 2012
+---
+
+[@fenner2012a, $a^2+b^2=c^2$]
+^D
+(Fenner 2012, a² + b² = c²)
+
+Fenner, Martin. 2012. “One-Click Science Marketing.” Nature Materials 11 (4).
+```
diff --git a/documents/markdown/pandoc-md/7323.md b/documents/markdown/pandoc-md/7323.md
new file mode 100644
index 0000000..7de29cf
--- /dev/null
+++ b/documents/markdown/pandoc-md/7323.md
@@ -0,0 +1,29 @@
+```
+% pandoc --citeproc -t plain
+---
+references:
+- id: smith
+ author: John Smith
+ issued: 2019
+ title: Insects
+ type: book
+...
+
+@smith [chap. 6]
+
+@smith [chapter 6]
+
+@smith [Chap. 6]
+
+@smith [Chapter 6]
+^D
+John Smith (2019, chap. 6)
+
+John Smith (2019, chap. 6)
+
+John Smith (2019, chap. 6)
+
+John Smith (2019, chap. 6)
+
+John Smith. 2019. Insects.
+```
diff --git a/documents/markdown/pandoc-md/7324.md b/documents/markdown/pandoc-md/7324.md
new file mode 100644
index 0000000..fae1b99
--- /dev/null
+++ b/documents/markdown/pandoc-md/7324.md
@@ -0,0 +1,25 @@
+```
+% pandoc --citeproc -t plain
+---
+references:
+- id: smith
+ author: John Smith
+ issued: 2019
+ title: Insects
+ type: book
+...
+
+@smith [, among others]
+
+@smith [ among others]
+
+@smith [among others]
+^D
+John Smith (2019, among others)
+
+John Smith (2019 among others)
+
+John Smith (2019, among others)
+
+John Smith. 2019. Insects.
+```
diff --git a/documents/markdown/pandoc-md/7326.md b/documents/markdown/pandoc-md/7326.md
new file mode 100644
index 0000000..7d807b1
--- /dev/null
+++ b/documents/markdown/pandoc-md/7326.md
@@ -0,0 +1,1227 @@
+Table with row and column spans
+```
+% pandoc -f html -t asciidoc
+<table>
+ <colgroup>
+ <col style="width: 17%" />
+ <col style="width: 16%" />
+ <col style="width: 15%" />
+ <col style="width: 52%" />
+ </colgroup>
+ <thead>
+ <tr>
+ <th>Header 1</th>
+ <th>Header 2</th>
+ <th>Header 3</th>
+ <th>Header 4</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>body row 1</td>
+ <td>column 2</td>
+ <td>column 3</td>
+ <td>column 4</td>
+ </tr>
+ <tr>
+ <td>body row 2</td>
+ <td colspan="2">Cells may span columns.</td>
+ <td>fff</td>
+ </tr>
+ <tr>
+ <td>body row 3</td>
+ <td rowspan="2">Cells may span rows.</td>
+ <td rowspan="2">
+ <ul>
+ <li>Cells</li>
+ <li>can</li>
+ <li>contain</li>
+ <li>blocks.</li>
+ </ul>
+ </td>
+ <td rowspan="2">
+ <ul>
+ <li>This is a very long line of text</li>
+ <li><a href="http://www.python.org/">Python</a></li>
+ <li>b</li>
+ <li>c</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>body row 4</td>
+ </tr>
+ </tbody>
+</table>
+^D
+[width="100%",cols="17%,16%,15%,52%",options="header",]
+|===
+|Header 1 |Header 2 |Header 3 |Header 4
+|body row 1 |column 2 |column 3 |column 4
+|body row 2 2+|Cells may span columns. |fff
+|body row 3 .2+|Cells may span rows. .2+a|
+* Cells
+* can
+* contain
+* blocks.
+
+.2+a|
+* This is a very long line of text
+* http://www.python.org/[Python]
+* b
+* c
+
+|body row 4
+|===
+```
+
+Header and footer.
+AsciiDoc only supports 1 header and 1 footer row.
+So for multiple header and/or footer rows all the extra rows become part of the table body.
+```
+% pandoc -f html -t asciidoc
+<table>
+ <thead>
+ <tr>
+ <th colspan="2">Inputs</th>
+ <th>Output</th>
+ </tr>
+ <tr>
+ <th>A</th>
+ <th>B</th>
+ <th>A or B</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>False</td>
+ <td>False</td>
+ <td>False</td>
+ </tr>
+ <tr>
+ <td>True</td>
+ <td>False</td>
+ <td>True</td>
+ </tr>
+ <tr>
+ <td>False</td>
+ <td>True</td>
+ <td>True</td>
+ </tr>
+ <tr>
+ <td>True</td>
+ <td>True</td>
+ <td>True</td>
+ </tr>
+ </tbody>
+ <tfoot>
+ <tr>
+ <td>A</td>
+ <td>B</td>
+ <td>A or B</td>
+ </tr>
+ <tr>
+ <td colspan="2">Inputs</td>
+ <td>Output</td>
+ </tr>
+ </tfoot>
+</table>
+<table>
+ <thead>
+ <tr>
+ <th colspan="2">Header</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>Body 1-1</td>
+ <td>Body 2-1</td>
+ </tr>
+ </tbody>
+ <tfoot>
+ <tr>
+ <td colspan="2">Footer</td>
+ </tr>
+ </tfoot>
+</table>
+^D
+[cols=",,",options="header,footer",]
+|===
+2+|Inputs |Output
+|A |B |A or B
+|False |False |False
+|True |False |True
+|False |True |True
+|True |True |True
+|A |B |A or B
+2+|Inputs |Output
+|===
+
+[cols=",",options="header,footer",]
+|===
+2+|Header
+|Body 1-1 |Body 2-1
+2+|Footer
+|===
+```
+
+Table without header but with footer rows
+```
+% pandoc -f html -t asciidoc
+<table>
+ <colgroup>
+ <col style="width: 37%" />
+ <col style="width: 37%" />
+ <col style="width: 26%" />
+ </colgroup>
+ <tbody>
+ <tr>
+ <td>False</td>
+ <td>False</td>
+ <td>False</td>
+ </tr>
+ <tr>
+ <td>True</td>
+ <td>False</td>
+ <td>True</td>
+ </tr>
+ <tr>
+ <td>False</td>
+ <td>True</td>
+ <td>True</td>
+ </tr>
+ <tr>
+ <td>True</td>
+ <td>True</td>
+ <td>True</td>
+ </tr>
+ </tbody>
+ <tfoot>
+ <tr>
+ <td>A</td>
+ <td>B</td>
+ <td>A or B</td>
+ </tr>
+ <tr>
+ <td colspan="2">Inputs</td>
+ <td>Output</td>
+ </tr>
+ </tfoot>
+</table>
+^D
+[width="100%",cols="37%,37%,26%",options="footer",]
+|===
+|False |False |False
+|True |False |True
+|False |True |True
+|True |True |True
+|A |B |A or B
+2+|Inputs |Output
+|===
+```
+
+Adjust row span for multiple header rows
+```
+% pandoc -f html -t asciidoc
+<table style="width: 63%">
+ <colgroup>
+ <col style="width: 30%" />
+ <col style="width: 11%" />
+ <col style="width: 11%" />
+ <col style="width: 11%" />
+ </colgroup>
+ <thead>
+ <tr>
+ <th rowspan="2">Location</th>
+ <th colspan="3">Temperature 1961-1990 in degree Celsius</th>
+ </tr>
+ <tr>
+ <th>min</th>
+ <th>mean</th>
+ <th>max</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>Antarctica</td>
+ <td>-89.2</td>
+ <td>N/A</td>
+ <td>19.8</td>
+ </tr>
+ <tr>
+ <td>Earth</td>
+ <td>-89.2</td>
+ <td>14</td>
+ <td>56.7</td>
+ </tr>
+ </tbody>
+</table>
+<table style="width: 63%">
+ <colgroup>
+ <col style="width: 11%" />
+ <col style="width: 11%" />
+ <col style="width: 11%" />
+ <col style="width: 30%" />
+ </colgroup>
+ <thead>
+ <tr>
+ <th colspan="3">Temperature 1961-1990 in degree Celsius</th>
+ <th rowspan="2">Location</th>
+ </tr>
+ <tr>
+ <th>min</th>
+ <th>mean</th>
+ <th>max</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>-89.2</td>
+ <td>N/A</td>
+ <td>19.8</td>
+ <td>Antarctica</td>
+ </tr>
+ <tr>
+ <td>-89.2</td>
+ <td>14</td>
+ <td>56.7</td>
+ <td>Earth</td>
+ </tr>
+ </tbody>
+</table>
+<table style="width: 65%">
+ <colgroup>
+ <col style="width: 11%" />
+ <col style="width: 11%" />
+ <col style="width: 11%" />
+ <col style="width: 18%" />
+ <col style="width: 14%" />
+ </colgroup>
+ <thead>
+ <tr>
+ <th colspan="3">Temperature 1961-1990 in degree Celsius</th>
+ <th rowspan="2">Location</th>
+ <th>Extra</th>
+ </tr>
+ <tr>
+ <th>min</th>
+ <th>mean</th>
+ <th>max</th>
+ <th>Extra 2</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>-89.2</td>
+ <td>N/A</td>
+ <td>19.8</td>
+ <td>Antarctica</td>
+ <td>Extra 3</td>
+ </tr>
+ <tr>
+ <td>-89.2</td>
+ <td>14</td>
+ <td>56.7</td>
+ <td>Earth</td>
+ <td>Extra 4</td>
+ </tr>
+ </tbody>
+</table>
+<table>
+ <thead>
+ <tr>
+ <th>Header 1-1</th>
+ <th colspan="2" rowspan="2">Header 1-2</th>
+ </tr>
+ <tr>
+ <th>Header 2-1</th>
+ </tr>
+ <tr>
+ <th>Header 3-1</th>
+ <th>Header 3-2</th>
+ <th>Header 3-3</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td rowspan="2">Body 1-1</td>
+ <td colspan="2">Body 1-2</td>
+ </tr>
+ <tr>
+ <td>Body 2-1</td>
+ <td>Body 2-2</td>
+ </tr>
+ </tbody>
+</table>
+<table>
+ <thead>
+ <tr>
+ <th rowspan="2">Header 1-1</th>
+ <th>Header 1-2</th>
+ <th rowspan="2">Header 1-3</th>
+ </tr>
+ <tr>
+ <th>Header 2-1</th>
+ </tr>
+ <tr>
+ <th>Header 3-1</th>
+ <th>Header 3-2</th>
+ <th>Header 3-3</th>
+ </tr>
+ </thead>
+ <tbody></tbody>
+</table>
+^D
+[width="63%",cols="49%,17%,17%,17%",options="header",]
+|===
+|Location 3+|Temperature 1961-1990 in degree Celsius
+| |min |mean |max
+|Antarctica |-89.2 |N/A |19.8
+|Earth |-89.2 |14 |56.7
+|===
+
+[width="63%",cols="19%,17%,17%,47%",options="header",]
+|===
+3+|Temperature 1961-1990 in degree Celsius |Location
+|min |mean |max |
+|-89.2 |N/A |19.8 |Antarctica
+|-89.2 |14 |56.7 |Earth
+|===
+
+[width="65%",cols="20%,16%,16%,27%,21%",options="header",]
+|===
+3+|Temperature 1961-1990 in degree Celsius |Location |Extra
+|min |mean |max | |Extra 2
+|-89.2 |N/A |19.8 |Antarctica |Extra 3
+|-89.2 |14 |56.7 |Earth |Extra 4
+|===
+
+[cols=",,",options="header",]
+|===
+|Header 1-1 2+|Header 1-2
+|Header 2-1 2+|
+|Header 3-1 |Header 3-2 |Header 3-3
+.2+|Body 1-1 2+|Body 1-2
+|Body 2-1 |Body 2-2
+|===
+
+[cols=",,",options="header",]
+|===
+|Header 1-1 |Header 1-2 |Header 1-3
+| |Header 2-1 |
+|Header 3-1 |Header 3-2 |Header 3-3
+|===
+```
+
+Adjust row span in multiple footer rows.
+```
+% pandoc -f html -t asciidoc
+<table>
+ <colgroup>
+ <col style="width: 40%" />
+ <col style="width: 40%" />
+ <col style="width: 20%" />
+ </colgroup>
+ <tbody>
+ <tr>
+ <td>Body 1-1</td>
+ <td>Body 1-2</td>
+ <td>Body 1-3</td>
+ </tr>
+ </tbody>
+ <tfoot>
+ <tr>
+ <td colspan="2">Footer 1-1/2</td>
+ <td>Footer 1-3</td>
+ </tr>
+ <tr>
+ <td>Footer 2-1</td>
+ <td rowspan="3">Span 3</td>
+ <td>Footer 2-3</td>
+ </tr>
+ <tr>
+ <td rowspan="2">Span 2</td>
+ <td>Footer 3-3</td>
+ </tr>
+ <tr>
+ <td>Footer 4-3</td>
+ </tr>
+ </tfoot>
+</table>
+<table>
+ <tbody>
+ <tr>
+ <td>Body 1-1</td>
+ <td>Body 1-2</td>
+ <td>Body 1-3</td>
+ <td>Body 1-4</td>
+ <td>Body 1-5</td>
+ </tr>
+ <tr>
+ <td>Body 2-1</td>
+ <td>Body 2-2</td>
+ <td>Body 2-3</td>
+ <td>Body 2-4</td>
+ <td>Body 2-5</td>
+ </tr>
+ </tbody>
+ <tfoot>
+ <tr>
+ <td colspan="3">Footer 1-1/2/3</td>
+ <td>Footer 1-4</td>
+ <td>Footer 1-5</td>
+ </tr>
+ <tr>
+ <td>Footer 2-1</td>
+ <td rowspan="3">Span 3</td>
+ <td>Footer 2-3</td>
+ <td colspan="2">Footer 2-4/5</td>
+ </tr>
+ <tr>
+ <td rowspan="2">Span 2</td>
+ <td colspan="2">Footer 3-3/4</td>
+ <td rowspan="2">Span 2</td>
+ </tr>
+ <tr>
+ <td rowspan="3">Span 3</td>
+ <td>Footer 4-4</td>
+ </tr>
+ <tr>
+ <td>Footer 5-1</td>
+ <td>Footer 5-2</td>
+ <td>Footer 5-4</td>
+ <td rowspan="2">Span 2</td>
+ </tr>
+ <tr>
+ <td colspan="2">Footer 6-1/2</td>
+ <td>Footer 6-4</td>
+ </tr>
+ </tfoot>
+</table>
+<table>
+ <tbody>
+ <tr>
+ <td>Body 1</td>
+ <td>Body 2</td>
+ <td>Body 3</td>
+ <td>Body 4</td>
+ </tr>
+ </tbody>
+ <tfoot>
+ <tr>
+ <td>Footer 1-1</td>
+ <td colspan="2" rowspan="3">Span 3</td>
+ <td rowspan="2">Span 2</td>
+ </tr>
+ <tr>
+ <td>Footer 2-1</td>
+ </tr>
+ <tr>
+ <td>Footer 3-1</td>
+ <td>Footer 3-4</td>
+ </tr>
+ </tfoot>
+</table>
+<table>
+ <tbody>
+ <tr>
+ <td>Body 1-1</td>
+ <td>Body 1-2</td>
+ <td>Body 1-3</td>
+ <td>Body 1-4</td>
+ </tr>
+ </tbody>
+ <tfoot>
+ <tr>
+ <td colspan="2">Footer 1-1/2</td>
+ <td rowspan="6">Span 6</td>
+ <td>Footer 1-4</td>
+ </tr>
+ <tr>
+ <td rowspan="3">Span 3</td>
+ <td>Footer 2-2</td>
+ <td>Footer 2-4</td>
+ </tr>
+ <tr>
+ <td>Footer 3-2</td>
+ <td>Footer 3-4</td>
+ </tr>
+ <tr>
+ <td>Footer 4-2</td>
+ <td>Footer 4-4</td>
+ </tr>
+ <tr>
+ <td>Footer 5-1</td>
+ <td>Footer 5-2</td>
+ <td rowspan="2">Span 2</td>
+ </tr>
+ <tr>
+ <td colspan="2">Footer 6-1/2</td>
+ </tr>
+ </tfoot>
+</table>
+^D
+[width="100%",cols="40%,40%,20%",options="footer",]
+|===
+|Body 1-1 |Body 1-2 |Body 1-3
+2+|Footer 1-1/2 |Footer 1-3
+|Footer 2-1 .2+|Span 3 |Footer 2-3
+|Span 2 |Footer 3-3
+| | |Footer 4-3
+|===
+
+[cols=",,,,",options="footer",]
+|===
+|Body 1-1 |Body 1-2 |Body 1-3 |Body 1-4 |Body 1-5
+|Body 2-1 |Body 2-2 |Body 2-3 |Body 2-4 |Body 2-5
+3+|Footer 1-1/2/3 |Footer 1-4 |Footer 1-5
+|Footer 2-1 .3+|Span 3 |Footer 2-3 2+|Footer 2-4/5
+.2+|Span 2 2+|Footer 3-3/4 .2+|Span 2
+.2+|Span 3 |Footer 4-4
+|Footer 5-1 |Footer 5-2 |Footer 5-4 |Span 2
+2+|Footer 6-1/2 | |Footer 6-4 |
+|===
+
+[cols=",,,",options="footer",]
+|===
+|Body 1 |Body 2 |Body 3 |Body 4
+|Footer 1-1 2.2+|Span 3 .2+|Span 2
+|Footer 2-1
+|Footer 3-1 2+| |Footer 3-4
+|===
+
+[cols=",,,",options="footer",]
+|===
+|Body 1-1 |Body 1-2 |Body 1-3 |Body 1-4
+2+|Footer 1-1/2 .5+|Span 6 |Footer 1-4
+.3+|Span 3 |Footer 2-2 |Footer 2-4
+|Footer 3-2 |Footer 3-4
+|Footer 4-2 |Footer 4-4
+|Footer 5-1 |Footer 5-2 |Span 2
+2+|Footer 6-1/2 | |
+|===
+```
+
+Individual cell alignments
+```
+% pandoc -f native -t asciidoc
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignLeft
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Left" , Space , Str "Header" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 2)
+ (ColSpan 2)
+ [ Plain [ Str "Center" , Space , Str "Headers" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignRight
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Right" , Space , Str "Header" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Center" , Space , Str "Header" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignRight
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Right" , Space , Str "Header" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignLeft
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Left" , Space , Str "Header" ] ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignRight
+ (RowSpan 2)
+ (ColSpan 1)
+ [ Plain [ Str "Right" , Space , Str "Body" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignLeft
+ (RowSpan 1)
+ (ColSpan 2)
+ [ Plain [ Str "Left" , Space , Str "Body" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Center" , Space , Str "Body" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignRight
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Right" , Space , Str "Body" ] ]
+ ]
+ ]
+ ]
+ (TableFoot
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 3)
+ [ Plain [ Str "Center" , Space , Str "Footer" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignLeft
+ (RowSpan 1)
+ (ColSpan 2)
+ [ Plain [ Str "Left" , Space , Str "Footer" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 3)
+ (ColSpan 1)
+ [ Plain [ Str "Center" , Space , Str "Footer" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignRight
+ (RowSpan 1)
+ (ColSpan 2)
+ [ Plain [ Str "Right" , Space , Str "Footer" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 2)
+ [ Plain [ Str "Center" , Space , Str "Footer" ] ]
+ ]
+ ])
+]
+^D
+[cols=",,",options="header,footer",]
+|===
+<|Left Header 2+^|Center Headers
+>|Right Header 2+|
+^|Center Header >|Right Header <|Left Header
+.2+>|Right Body 2+<|Left Body
+^|Center Body >|Right Body
+3+^|Center Footer
+2+<|Left Footer .2+^|Center Footer
+2+>|Right Footer
+2+^|Center Footer |
+|===
+```
+
+Adjust row span for empty rows and handle empty rows in general
+```
+% pandoc -f native -t asciidoc
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 2)
+ (ColSpan 1)
+ [ Plain [ Str "Header" , Space , Str "1-1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 3)
+ (ColSpan 1)
+ [ Plain [ Str "Span" , Space , Str "3" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 2)
+ (ColSpan 1)
+ [ Plain [ Str "Header" , Space , Str "1-3" ] ]
+ ]
+ , Row ( "" , [] , [] ) []
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Header" , Space , Str "2-1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Header" , Space , Str "2-3" ] ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 3)
+ (ColSpan 2)
+ [ Plain [ Str "Body" , Space , Str "1-1/2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 5)
+ (ColSpan 1)
+ [ Plain [ Str "Span" , Space , Str "5" ] ]
+ ]
+ , Row ( "" , [] , [] ) []
+ , Row ( "" , [] , [] ) []
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Body" , Space , Str "2-1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Body" , Space , Str "2-2" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Body" , Space , Str "3-1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Body" , Space , Str "3-2" ] ]
+ ]
+ , Row ( "" , [] , [] ) []
+ ]
+ ]
+ (TableFoot
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 5)
+ (ColSpan 1)
+ [ Plain
+ [ Str "Span" , Space , Str "5" ]
+ ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 2)
+ [ Plain [ Str "Footer" , Space , Str "1-2" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 2)
+ (ColSpan 2)
+ [ Plain
+ [ Str "Span" , Space , Str "2" ]
+ ]
+ ]
+ , Row ( "" , [] , [] ) []
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 2)
+ [ Plain [ Str "Footer" , Space , Str "3-2/3" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 2)
+ [ Plain [ Str "Footer" , Space , Str "4-2/3" ] ]
+ ]
+ ])
+, Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Body" , Space , Str "1-1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Body" , Space , Str "1-2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 3)
+ (ColSpan 1)
+ [ Plain [ Str "Span" , Space , Str "4" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 5)
+ (ColSpan 1)
+ [ Plain [ Str "Span" , Space , Str "5" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Body" , Space , Str "2-2" ] ]
+ ]
+ , Row
+ ( "" , [] , [] ) []
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Body" , Space , Str "3-2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Body" , Space , Str "3-3" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Body" , Space , Str "4-2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Body" , Space , Str "4-3" ] ]
+ ]
+ , Row
+ ( "" , [] , [] ) []
+ , Row
+ ( "" , [] , [] ) []
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Body" , Space , Str "6-1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Body" , Space , Str "6-2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Span" , Space , Str "6-3" ] ]
+ ]
+ ]
+ ]
+ (TableFoot
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Footer" , Space , Str "1-1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 8)
+ (ColSpan 1)
+ [ Plain [ Str "Span" , Space , Str "8" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Footer" , Space , Str "1-3" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 3)
+ (ColSpan 1)
+ [ Plain [ Str "Span" , Space , Str "3" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Footer" , Space , Str "2-3" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 2)
+ (ColSpan 1)
+ [ Plain [ Str "Span" , Space , Str "2" ] ]
+ ]
+ , Row ( "" , [] , [] ) []
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Footer" , Space , Str "4-1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Footer" , Space , Str "4-3" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Footer" , Space , Str "5-1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 3)
+ (ColSpan 1)
+ [ Plain [ Str "Span" , Space , Str "3" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 2)
+ (ColSpan 1)
+ [ Plain [ Str "Span" , Space , Str "2" ] ]
+ ]
+ , Row ( "" , [] , [] ) []
+ ])
+, Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [ "rowspan-cell" ] , [] )
+ AlignDefault
+ (RowSpan 6)
+ (ColSpan 1)
+ [ Plain [ Str "Span" , Space , Str "6" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Body" , Space , Str "1-2" ] ]
+ , Cell
+ ( "" , [ "rowspan-cell" ] , [] )
+ AlignDefault
+ (RowSpan 2)
+ (ColSpan 1)
+ [ Plain [ Str "Span" , Space , Str "2" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [ "rowspan-cell" ] , [] )
+ AlignDefault
+ (RowSpan 3)
+ (ColSpan 1)
+ [ Plain [ Str "Span" , Space , Str "3" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [ "rowspan-cell" ] , [] )
+ AlignDefault
+ (RowSpan 4)
+ (ColSpan 1)
+ [ Plain [ Str "Span" , Space , Str "4" ] ]
+ ]
+ , Row ( "" , [] , [] ) []
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Body" , Space , Str "3-2" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Body" , Space , Str "4-2" ] ]
+ ]
+ , Row ( "" , [] , [] ) []
+ , Row ( "" , [] , [] ) []
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+^D
+[cols=",,",options="header,footer",]
+|===
+|Header 1-1 |Span 3 |Header 1-3
+|Header 2-1 | |Header 2-3
+2+|Body 1-1/2 .3+|Span 5
+|Body 2-1 |Body 2-2
+|Body 3-1 |Body 3-2
+| | |
+.3+|Span 5 2+|Footer 1-2
+2+|Span 2
+2+|Footer 3-2/3
+| 2+|Footer 4-2/3
+|===
+
+[cols=",,",options="footer",]
+|===
+|Body 1-1 |Body 1-2 .2+|Span 4
+.3+|Span 5 |Body 2-2
+|Body 3-2 |Body 3-3
+|Body 4-2 |Body 4-3
+| | |
+|Body 6-1 |Body 6-2 |Span 6-3
+|Footer 1-1 .5+|Span 8 |Footer 1-3
+.2+|Span 3 |Footer 2-3
+|Span 2
+|Footer 4-1 |Footer 4-3
+|Footer 5-1 |Span 3
+|Span 2 | |
+|===
+
+[cols=",,",]
+|===
+.5+|Span 6 |Body 1-2 .2+|Span 2
+.2+|Span 3
+.3+|Span 4
+|Body 3-2
+|Body 4-2
+| | |
+| | |
+|===
+```
diff --git a/documents/markdown/pandoc-md/7329.md b/documents/markdown/pandoc-md/7329.md
new file mode 100644
index 0000000..cb34032
--- /dev/null
+++ b/documents/markdown/pandoc-md/7329.md
@@ -0,0 +1,72 @@
+```
+% pandoc -f markdown -t org
+- @item1
+- @item1 [p. 12]
+- @item1 [p.12; see also @item2]
+- [@item1]
+- [-@item1]
+- [see @item1 p. 12]
+- [see @item1, p. 12]
+- [see @item1, p. 12 and *passim*]
+- [@item1;@item2]
+- [see @item1; @item2]
+^D
+- [cite/t:@item1]
+- [cite/t:@item1 p. 12]
+- [cite/t:@item1 p.12; see also @item2]
+- [cite:@item1]
+- [cite/na:@item1]
+- [cite:see @item1 p. 12]
+- [cite:see @item1 p. 12]
+- [cite:see @item1 p. 12 and /passim/]
+- [cite:@item1; @item2]
+- [cite:see @item1; @item2]
+```
+
+```
+% pandoc -f markdown -t org -C --bibliography command/biblio.bib
+- [@item1]
+^D
+- (Doe 2005)
+
+<<refs>>
+
+<<ref-item1>>
+Doe, John. 2005. /First Book/. Cambridge University Press.
+```
+
+
+```
+% pandoc -f markdown -t org-citations -C --bibliography command/biblio.bib
+[@item1]
+^D
+(Doe 2005)
+
+<<refs>>
+
+<<ref-item1>>
+Doe, John. 2005. /First Book/. Cambridge University Press.
+```
+
+```
+% pandoc -f org -t markdown
+- [cite/t:@item1]
+- [cite/t:@item1 p. 12]
+- [cite/t:@item1 p.12; see also @item2]
+- [cite:@item1]
+- [cite/na:@item1]
+- [cite:see @item1 p. 12]
+- [cite:see @item1 p. 12 and /passim/]
+- [cite:@item1; @item2]
+- [cite:see @item1; @item2]
+^D
+- @item1
+- @item1 [p. 12]
+- @item1 [p.12; see also @item2]
+- [@item1]
+- [-@item1]
+- [see @item1 p. 12]
+- [see @item1 p. 12 and *passim*]
+- [@item1; @item2]
+- [see @item1; @item2]
+```
diff --git a/documents/markdown/pandoc-md/7339.md b/documents/markdown/pandoc-md/7339.md
new file mode 100644
index 0000000..f8d004f
--- /dev/null
+++ b/documents/markdown/pandoc-md/7339.md
@@ -0,0 +1,15 @@
+```
+% pandoc -f gfm -s -t native
+---
+title: Test
+---
+
+Hi
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList [ ( "title" , MetaInlines [ Str "Test" ] ) ]
+ }
+ [ Para [ Str "Hi" ] ]
+```
diff --git a/documents/markdown/pandoc-md/7376.md b/documents/markdown/pandoc-md/7376.md
new file mode 100644
index 0000000..229c61c
--- /dev/null
+++ b/documents/markdown/pandoc-md/7376.md
@@ -0,0 +1,16 @@
+```
+% pandoc --citeproc -t plain
+---
+references:
+- id: item1
+ type: book
+ author:
+ - family: Doe
+ given: Jane
+ issued: 2020
+ title: The title
+...
+^D
+
+
+```
diff --git a/documents/markdown/pandoc-md/7394.md b/documents/markdown/pandoc-md/7394.md
new file mode 100644
index 0000000..d6eb769
--- /dev/null
+++ b/documents/markdown/pandoc-md/7394.md
@@ -0,0 +1,85 @@
+```
+% pandoc -f markdown -t plain --citeproc
+---
+csl: command/chicago-fullnote-bibliography.csl
+references:
+- author:
+ - family: Wandt
+ given: Manfred
+ edition: 6
+ id: wandt2014ges-sv
+ issued: 2014
+ publisher: Franz Vahlen
+ publisher-place: München
+ title: Gesetzliche schuldverhältnisse
+ title-short: Gesetzl SV
+ type: book
+- author:
+ - family: Smith
+ given: Zenda
+ edition: 6
+ id: smith2015
+ issued: 2015
+ publisher: Macmillan
+ publisher-place: New York
+ title: A verb and a noun
+ type: book
+---
+
+Hi^[@wandt2014ges-sv.].
+
+Hi^[[@wandt2014ges-sv].].
+
+Hi^[[See also @wandt2014ges-sv].].
+
+Hi^[See also @wandt2014ges-sv.].
+
+Hi^[@wandt2014ges-sv [@smith2015].].
+
+Hi^[[@wandt2014ges-sv; @smith2015].].
+
+Hi [@wandt2014ges-sv].
+
+Hi [see also @wandt2014ges-sv].
+
+^D
+Hi[1].
+
+Hi[2].
+
+Hi[3].
+
+Hi[4].
+
+Hi[5].
+
+Hi[6].
+
+Hi.[7]
+
+Hi.[8]
+
+Smith, Zenda. A Verb and a Noun. 6th ed. New York: Macmillan, 2015.
+
+Wandt, Manfred. Gesetzliche Schuldverhältnisse. 6th ed. München: Franz
+Vahlen, 2014.
+
+[1] Manfred Wandt, Gesetzliche Schuldverhältnisse, 6th ed. (München:
+Franz Vahlen, 2014).
+
+[2] Wandt.
+
+[3] See also Wandt.
+
+[4] See also Wandt.
+
+[5] Wandt, Zenda Smith, A Verb and a Noun, 6th ed. (New York: Macmillan,
+2015).
+
+[6] Wandt, Gesetzl SV; Smith, A Verb and a Noun.
+
+[7] Wandt, Gesetzl SV.
+
+[8] See also Wandt.
+```
+
diff --git a/documents/markdown/pandoc-md/7397.md b/documents/markdown/pandoc-md/7397.md
new file mode 100644
index 0000000..24ce391
--- /dev/null
+++ b/documents/markdown/pandoc-md/7397.md
@@ -0,0 +1,14 @@
+````
+% pandoc -t markdown
+~~~~ { .haskell startFrom="100"}
+qsort [] = []
+qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
+ qsort (filter (>= x) xs)
+~~~~
+^D
+``` {.haskell startFrom="100"}
+qsort [] = []
+qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
+ qsort (filter (>= x) xs)
+```
+````
diff --git a/documents/markdown/pandoc-md/7416.md b/documents/markdown/pandoc-md/7416.md
new file mode 100644
index 0000000..d440725
--- /dev/null
+++ b/documents/markdown/pandoc-md/7416.md
@@ -0,0 +1,21 @@
+```
+% pandoc -f markdown -t html
+{alt="alt"}
+
+^D
+<figure>
+<img src="../media/rId25.jpg" title="title" alt="alt" />
+<figcaption>caption</figcaption>
+</figure>
+```
+
+```
+% pandoc -f markdown -t html
+
+
+^D
+<figure>
+<img src="../media/rId25.jpg" title="title" alt="caption" />
+<figcaption aria-hidden="true">caption</figcaption>
+</figure>
+```
diff --git a/documents/markdown/pandoc-md/7434.md b/documents/markdown/pandoc-md/7434.md
new file mode 100644
index 0000000..e4f2743
--- /dev/null
+++ b/documents/markdown/pandoc-md/7434.md
@@ -0,0 +1,23 @@
+```
+% pandoc -f markdown -t native
+\begin{proof}
+\newcommand{\x}{\left.\right.}
+\x
+\end{proof}
+
+1234567890abcdefghi
+
+[\*\a](x)
+^D
+[ RawBlock
+ (Format "tex")
+ "\\begin{proof}\n\\newcommand{\\x}{\\left.\\right.}\n\\left.\\right.\n\\end{proof}"
+, Para [ Str "1234567890abcdefghi" ]
+, Para
+ [ Link
+ ( "" , [] , [] )
+ [ Str "*" , RawInline (Format "tex") "\\a" ]
+ ( "x" , "" )
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/7436.md b/documents/markdown/pandoc-md/7436.md
new file mode 100644
index 0000000..c2d434d
--- /dev/null
+++ b/documents/markdown/pandoc-md/7436.md
@@ -0,0 +1,31 @@
+```
+% pandoc -f rst -t native
+.. include:: command/three.txt
+ :code:
+
+.. include:: command/three.txt
+ :literal:
+
+.. include:: command/three.txt
+^D
+[ CodeBlock
+ ( "" , [ "" ] , [ ( "code" , "" ) ] )
+ "1st line.\n2nd line.\n3rd line.\n"
+, CodeBlock
+ ( "" , [ "" ] , [ ( "literal" , "" ) ] )
+ "1st line.\n2nd line.\n3rd line.\n"
+, Para
+ [ Str "1st"
+ , Space
+ , Str "line."
+ , SoftBreak
+ , Str "2nd"
+ , Space
+ , Str "line."
+ , SoftBreak
+ , Str "3rd"
+ , Space
+ , Str "line."
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/7473.md b/documents/markdown/pandoc-md/7473.md
new file mode 100644
index 0000000..cb71a20
--- /dev/null
+++ b/documents/markdown/pandoc-md/7473.md
@@ -0,0 +1,39 @@
+```
+% pandoc -f rst -t native
+.. figure:: example.png
+ :figclass: foo bar
+ :align: right
+ :width: 1in
+
+ This is a caption.
+^D
+[ Figure
+ ( "" , [ "foo" , "bar" , "align-right" ] , [] )
+ (Caption
+ Nothing
+ [ Plain
+ [ Str "This"
+ , Space
+ , Str "is"
+ , Space
+ , Str "a"
+ , Space
+ , Str "caption."
+ ]
+ ])
+ [ Plain
+ [ Image
+ ( "" , [] , [ ( "width" , "1in" ) ] )
+ [ Str "This"
+ , Space
+ , Str "is"
+ , Space
+ , Str "a"
+ , Space
+ , Str "caption."
+ ]
+ ( "example.png" , "" )
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/7482.md b/documents/markdown/pandoc-md/7482.md
new file mode 100644
index 0000000..b4f750e
--- /dev/null
+++ b/documents/markdown/pandoc-md/7482.md
@@ -0,0 +1,47 @@
+```
+% pandoc -f html -t org
+<table border=0 cellpadding=0 cellspacing=0 width=206 style='border-collapse:
+ collapse;width:154pt'>
+<!--StartFragment-->
+ <col width=99 style='mso-width-source:userset;mso-width-alt:3157;width:74pt'>
+ <col width=107 style='mso-width-source:userset;mso-width-alt:3413;width:80pt'>
+ <tr height=23 style='height:17.0pt'>
+ <td height=23 align=left width=99 style='height:17.0pt;width:74pt'>Last N
+ credits</td>
+ <td align=left width=107 style='width:80pt'>Average grade</td>
+ </tr>
+ <tr height=21 style='height:16.0pt'>
+ <td height=21 align=right style='height:16.0pt'>140</td>
+ <td align=right>17.06571429</td>
+ </tr>
+ <tr height=21 style='height:16.0pt'>
+ <td height=21 class=xl63 align=right style='height:16.0pt'>84</td>
+ <td class=xl63 align=right>17.95595238</td>
+ </tr>
+ <tr height=21 style='height:16.0pt'>
+ <td height=21 class=xl63 align=right style='height:16.0pt'>64</td>
+ <td class=xl63 align=right>18.9734375</td>
+ </tr>
+ <tr height=21 style='height:16.0pt'>
+ <td height=21 align=right style='height:16.0pt'>36</td>
+ <td align=right>19.12777778</td>
+ </tr>
+ <tr height=27 style='mso-height-source:userset;height:20.0pt'>
+ <td height=27 align=right style='height:20.0pt'>29</td>
+ <td align=right>19.18275862</td>
+ </tr>
+ <tr height=21 style='height:16.0pt'>
+ <td height=21 align=right style='height:16.0pt'>19</td>
+ <td align=right>19.00526316</td>
+ </tr>
+<!--EndFragment-->
+</table>
+^D
+| Last N credits | Average grade |
+| 140 | 17.06571429 |
+| 84 | 17.95595238 |
+| 64 | 18.9734375 |
+| 36 | 19.12777778 |
+| 29 | 19.18275862 |
+| 19 | 19.00526316 |
+```
diff --git a/documents/markdown/pandoc-md/7494.md b/documents/markdown/pandoc-md/7494.md
new file mode 100644
index 0000000..364bcb7
--- /dev/null
+++ b/documents/markdown/pandoc-md/7494.md
@@ -0,0 +1,62 @@
+```
+% pandoc -f latex -t plain
+\def\foo{BAR}
+{\foo
+\def\foo{BAZ}
+\foo
+}
+\foo
+^D
+BAR BAZ BAR
+```
+
+```
+% pandoc -f latex -t plain
+\def\foo{BAR}
+{\foo
+\gdef\foo{BAZ}
+\foo
+}
+\foo
+^D
+BAR BAZ BAZ
+```
+
+```
+% pandoc -f latex -t plain
+\def\foo{BAR}
+{\foo
+\global\def\foo{BAZ}
+\foo
+}
+\foo
+^D
+BAR BAZ BAZ
+```
+
+```
+% pandoc -f latex -t plain
+\newcommand{\aaa}{BBB}
+{
+\renewcommand{\aaa}{AAA}
+\aaa
+}
+\aaa
+^D
+AAA BBB
+```
+
+```
+% pandoc -f latex -t markdown
+\newcommand{\aaa}{BBB}
+\begin{quote}
+\renewcommand{\aaa}{AAA}
+\aaa
+\end{quote}
+\aaa
+^D
+> AAA
+
+BBB
+```
+
diff --git a/documents/markdown/pandoc-md/7497.md b/documents/markdown/pandoc-md/7497.md
new file mode 100644
index 0000000..4b80bf2
--- /dev/null
+++ b/documents/markdown/pandoc-md/7497.md
@@ -0,0 +1,37 @@
+````
+% pandoc -f markdown-raw_tex -t latex
+```
+\end{verbatim}
+\LaTeX
+\begin{verbatim}
+```
+^D
+\begin{Shaded}
+\begin{Highlighting}[]
+\NormalTok{\textbackslash{}end\{verbatim\}}
+\NormalTok{\textbackslash{}LaTeX}
+\NormalTok{\textbackslash{}begin\{verbatim\}}
+\end{Highlighting}
+\end{Shaded}
+````
+
+````
+% pandoc -f markdown-raw_tex -t latex
+hi[^1]
+
+[^1]:
+ ```
+ \end{Verbatim}
+ \LaTeX
+ \begin{Verbatim}
+ ```
+^D
+hi\footnote{\begin{Shaded}
+\begin{Highlighting}[]
+\NormalTok{\textbackslash{}end\{Verbatim\}}
+\NormalTok{\textbackslash{}LaTeX}
+\NormalTok{\textbackslash{}begin\{Verbatim\}}
+\end{Highlighting}
+\end{Shaded}
+}
+````
diff --git a/documents/markdown/pandoc-md/7512.md b/documents/markdown/pandoc-md/7512.md
new file mode 100644
index 0000000..618739a
--- /dev/null
+++ b/documents/markdown/pandoc-md/7512.md
@@ -0,0 +1,70 @@
+```
+% pandoc -t native -f latex
+\begin{equation*}
+[d,\delta]=0.
+\end{equation*}
+^D
+[ Para
+ [ Math
+ DisplayMath
+ "\\begin{equation*}\n[d,\\delta]=0.\n\\end{equation*}"
+ ]
+]
+```
+
+```
+% pandoc -t native -f latex
+\begin{table}[htb]
+ \begin{tabular}{|c|c|}
+ $W$ & rel. err. \\[0mm]
+ [$\mu$m] & [\%]\\
+ \end{tabular}
+\end{table}
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignCenter , ColWidthDefault )
+ , ( AlignCenter , ColWidthDefault )
+ ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Math InlineMath "W" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "rel." , Space , Str "err." ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "[" , Math InlineMath "\\mu" , Str "m]" ]
+ ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "[%]" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
diff --git a/documents/markdown/pandoc-md/7520.md b/documents/markdown/pandoc-md/7520.md
new file mode 100644
index 0000000..0300a9e
--- /dev/null
+++ b/documents/markdown/pandoc-md/7520.md
@@ -0,0 +1,22 @@
+```
+% pandoc -f org -t native -s
+:PROPERTIES:
+:ID: d5b18943-98a3-4b2a-a545-41d17bf50f3e
+:END:
+#+title: Common Ground
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "id"
+ , MetaString "d5b18943-98a3-4b2a-a545-41d17bf50f3e"
+ )
+ , ( "title"
+ , MetaInlines [ Str "Common" , Space , Str "Ground" ]
+ )
+ ]
+ }
+ []
+
+```
diff --git a/documents/markdown/pandoc-md/7521.md b/documents/markdown/pandoc-md/7521.md
new file mode 100644
index 0000000..4a24f13
--- /dev/null
+++ b/documents/markdown/pandoc-md/7521.md
@@ -0,0 +1,11 @@
+```
+% pandoc --strip-comments
+- one
+ <!-- with comm -->
+- two
+^D
+<ul>
+<li>one </li>
+<li>two</li>
+</ul>
+```
diff --git a/documents/markdown/pandoc-md/7525.md b/documents/markdown/pandoc-md/7525.md
new file mode 100644
index 0000000..0283b19
--- /dev/null
+++ b/documents/markdown/pandoc-md/7525.md
@@ -0,0 +1,33 @@
+```
+% pandoc -f latex -t native
+\texttt{Normal code. \emph{Emph and code.} \textsc{\textbf{Bold small caps.}} \sout{Strikeout. \underline{Strikeout and underline.}}}
+^D
+[ Para
+ [ Code ( "" , [] , [] ) "Normal code. "
+ , Emph [ Code ( "" , [] , [] ) "Emph and code." ]
+ , Code ( "" , [] , [] ) " "
+ , SmallCaps
+ [ Strong [ Code ( "" , [] , [] ) "Bold small caps." ] ]
+ , Code ( "" , [] , [] ) " "
+ , Strikeout
+ [ Code ( "" , [] , [] ) "Strikeout. "
+ , Underline
+ [ Code ( "" , [] , [] ) "Strikeout and underline." ]
+ ]
+ ]
+]
+```
+
+```
+% pandoc -f html -t native
+<code><b>hi</b></code>
+^D
+[ Plain [ Strong [ Code ( "" , [] , [] ) "hi" ] ] ]
+```
+
+```
+% pandoc -f mediawiki -t native
+<code>''hey''</code>
+^D
+[ Para [ Emph [ Code ( "" , [] , [] ) "hey" ] ] ]
+```
diff --git a/documents/markdown/pandoc-md/7529.md b/documents/markdown/pandoc-md/7529.md
new file mode 100644
index 0000000..9515258
--- /dev/null
+++ b/documents/markdown/pandoc-md/7529.md
@@ -0,0 +1,7 @@
+```
+% pandoc -f html -t asciidoc
+<a href="https://example.com/show.cgi?id=hi--there--everyone">https://example.com/show.cgi?id=hi--there--everyone</a>
+^D
+link:++https://example.com/show.cgi?id=hi--there--everyone++[]
+```
+
diff --git a/documents/markdown/pandoc-md/7557.md b/documents/markdown/pandoc-md/7557.md
new file mode 100644
index 0000000..c837d0b
--- /dev/null
+++ b/documents/markdown/pandoc-md/7557.md
@@ -0,0 +1,20 @@
+```
+% pandoc -f org -t native
+- 11. and 12. 09. meeting
+^D
+[ BulletList
+ [ [ Plain
+ [ Str "11."
+ , Space
+ , Str "and"
+ , Space
+ , Str "12."
+ , Space
+ , Str "09."
+ , Space
+ , Str "meeting"
+ ]
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/7568.md b/documents/markdown/pandoc-md/7568.md
new file mode 100644
index 0000000..487da08
--- /dev/null
+++ b/documents/markdown/pandoc-md/7568.md
@@ -0,0 +1,16 @@
+```
+% pandoc -f rst
+While `Labyrinth Lord: Revised Edition`_ (LLRE; PDF and POD) has been
+criticized for not being a completely faithful retro-clone of the
+Moldvay/Cook/Marsh Basic/Expert D&D rules (B/X), I think it still
+holds a useful spot.
+
+.. _Labyrinth Lord\: Revised Edition: https://www.drivethrurpg.com/product/64332/Labyrinth-Lord-Revised-Edition
+^D
+<p>While <a
+href="https://www.drivethrurpg.com/product/64332/Labyrinth-Lord-Revised-Edition">Labyrinth
+Lord: Revised Edition</a> (LLRE; PDF and POD) has been criticized for
+not being a completely faithful retro-clone of the Moldvay/Cook/Marsh
+Basic/Expert D&D rules (B/X), I think it still holds a useful
+spot.</p>
+```
diff --git a/documents/markdown/pandoc-md/7582.md b/documents/markdown/pandoc-md/7582.md
new file mode 100644
index 0000000..6546871
--- /dev/null
+++ b/documents/markdown/pandoc-md/7582.md
@@ -0,0 +1,28 @@
+```
+% pandoc -t revealjs
+# Slide
+
+::: columns
+:::: column
+Left column
+::::
+
+. . .
+
+:::: column
+Right column
+::::
+:::
+^D
+<section id="slide" class="slide level1">
+<h1>Slide</h1>
+<div class="columns">
+<div class="column">
+<p>Left column</p>
+</div><div class="fragment"><div class="column">
+<p>Right column</p>
+</div></div>
+</div>
+</section>
+
+```
diff --git a/documents/markdown/pandoc-md/7589.md b/documents/markdown/pandoc-md/7589.md
new file mode 100644
index 0000000..aff21da
--- /dev/null
+++ b/documents/markdown/pandoc-md/7589.md
@@ -0,0 +1,72 @@
+```
+% pandoc -f html -t native
+<table>
+ <thead>
+ <tr>
+ <th>experience</th>
+ <th>expertise</th>
+ <th>paradigms</th>
+ <th>haskell</th>
+ <th>name</th>
+ <th>image</th>
+ </tr>
+ </thead>
+ <tbody></tbody>
+</table>
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "experience" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "expertise" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "paradigms" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "haskell" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "name" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "image" ] ]
+ ]
+ ])
+ [ TableBody ( "" , [] , [] ) (RowHeadColumns 0) [] [] ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
diff --git a/documents/markdown/pandoc-md/7623.md b/documents/markdown/pandoc-md/7623.md
new file mode 100644
index 0000000..1c4c8a0
--- /dev/null
+++ b/documents/markdown/pandoc-md/7623.md
@@ -0,0 +1,12 @@
+```
+% pandoc -t native
+[link $(0,1]$](url)
+^D
+[ Para
+ [ Link
+ ( "" , [] , [] )
+ [ Str "link" , Space , Math InlineMath "(0,1]" ]
+ ( "url" , "" )
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/7632.md b/documents/markdown/pandoc-md/7632.md
new file mode 100644
index 0000000..4256bc2
--- /dev/null
+++ b/documents/markdown/pandoc-md/7632.md
@@ -0,0 +1,66 @@
+```
+% pandoc -t native
+(@a) First case
+
+[link to (@a)](url)
+^D
+[ OrderedList
+ ( 1 , Example , TwoParens )
+ [ [ Plain [ Str "First" , Space , Str "case" ] ] ]
+, Para
+ [ Link
+ ( "" , [] , [] )
+ [ Str "link" , Space , Str "to" , Space , Str "(1)" ]
+ ( "url" , "" )
+ ]
+]
+```
+
+```
+% pandoc -t native
+[@a]{.class}
+^D
+[ Para
+ [ Span
+ ( "" , [ "class" ] , [] )
+ [ Cite
+ [ Citation
+ { citationId = "a"
+ , citationPrefix = []
+ , citationSuffix = []
+ , citationMode = AuthorInText
+ , citationNoteNum = 1
+ , citationHash = 0
+ }
+ ]
+ [ Str "@a" ]
+ ]
+ ]
+]
+
+```
+
+```
+% pandoc -t native
+[@a](url)
+^D
+[ Para
+ [ Link
+ ( "" , [] , [] )
+ [ Cite
+ [ Citation
+ { citationId = "a"
+ , citationPrefix = []
+ , citationSuffix = []
+ , citationMode = AuthorInText
+ , citationNoteNum = 1
+ , citationHash = 0
+ }
+ ]
+ [ Str "@a" ]
+ ]
+ ( "url" , "" )
+ ]
+]
+
+```
diff --git a/documents/markdown/pandoc-md/7668.md b/documents/markdown/pandoc-md/7668.md
new file mode 100644
index 0000000..6f85aa4
--- /dev/null
+++ b/documents/markdown/pandoc-md/7668.md
@@ -0,0 +1,36 @@
+```
+% pandoc -f bibtex -t csljson
+%@Book{JW82,
+ author = {Richard A. Johnson and Dean W. Wichern},
+ title = {Applied Multivariate Statistical Analysis},
+ publisher= {Prentice-Hall},
+ year = {1983}
+}
+@Book{JW83,
+ author = {Richard %A.
+ B. Johnson},
+% title = {Multivariate Analysis},
+ year = "%
+ 1983"
+}
+^D
+[
+ {
+ "author": [
+ {
+ "family": "Johnson",
+ "given": "Richard B."
+ }
+ ],
+ "id": "JW83",
+ "issued": {
+ "date-parts": [
+ [
+ 1983
+ ]
+ ]
+ },
+ "type": "book"
+ }
+]
+```
diff --git a/documents/markdown/pandoc-md/7678.md b/documents/markdown/pandoc-md/7678.md
new file mode 100644
index 0000000..df34985
--- /dev/null
+++ b/documents/markdown/pandoc-md/7678.md
@@ -0,0 +1,62 @@
+```
+% pandoc -f bibtex -t csljson
+@misc{doe,
+ author = "Jane Doe",
+ title = "Work",
+ year = "2021",
+ url = "%20and%20"
+}
+^D
+[
+ {
+ "URL": "%20and%20",
+ "author": [
+ {
+ "family": "Doe",
+ "given": "Jane"
+ }
+ ],
+ "id": "doe",
+ "issued": {
+ "date-parts": [
+ [
+ 2021
+ ]
+ ]
+ },
+ "title": "Work",
+ "type": ""
+ }
+]
+```
+```
+% pandoc -f bibtex -t csljson
+@misc{doe,
+ author = "Jane Doe",
+ title = "Work",
+ year = "2021",
+ doi = "%20and%20"
+}
+^D
+[
+ {
+ "DOI": "%20and%20",
+ "author": [
+ {
+ "family": "Doe",
+ "given": "Jane"
+ }
+ ],
+ "id": "doe",
+ "issued": {
+ "date-parts": [
+ [
+ 2021
+ ]
+ ]
+ },
+ "title": "Work",
+ "type": ""
+ }
+]
+```
diff --git a/documents/markdown/pandoc-md/7692.md b/documents/markdown/pandoc-md/7692.md
new file mode 100644
index 0000000..2a91ef3
--- /dev/null
+++ b/documents/markdown/pandoc-md/7692.md
@@ -0,0 +1,13 @@
+```
+% pandoc -t markdown
+[https://example.com](https://example.com){.clz}
+^D
+[https://example.com](https://example.com){.clz}
+```
+
+```
+% pandoc -f markdown -t html | pandoc -f html -t markdown
+<http://example.com>
+^D
+<http://example.com>
+```
diff --git a/documents/markdown/pandoc-md/7697.md b/documents/markdown/pandoc-md/7697.md
new file mode 100644
index 0000000..eb9c823
--- /dev/null
+++ b/documents/markdown/pandoc-md/7697.md
@@ -0,0 +1,27 @@
+```
+% pandoc -f rst -t mediawiki
+.. _refsubpage1:
+
+heading
+-------
+
+ref to top of this section: `refsubpage1`_.
+^D
+<span id="refsubpage1"></span>
+= heading =
+
+ref to top of this section: [[#refsubpage1|refsubpage1]].
+```
+```
+% pandoc -f markdown -t mediawiki
+# Heading {#foo}
+^D
+<span id="foo"></span>
+= Heading =
+```
+```
+% pandoc -f markdown -t mediawiki
+# My Heading {#My_Heading}
+^D
+= My Heading =
+```
diff --git a/documents/markdown/pandoc-md/7713.md b/documents/markdown/pandoc-md/7713.md
new file mode 100644
index 0000000..09aec8d
--- /dev/null
+++ b/documents/markdown/pandoc-md/7713.md
@@ -0,0 +1,29 @@
+```
+% pandoc
+| aaaaaaaaaaaa | bbbbb | ccccccccccc |
+| --- | --- | --- |
+| | | cccccccccc cccccccccc cccccccccc cccccccccc cccccccccc cccccccccc |
+^D
+<table>
+<colgroup>
+<col style="width: 33%" />
+<col style="width: 33%" />
+<col style="width: 33%" />
+</colgroup>
+<thead>
+<tr>
+<th>aaaaaaaaaaaa</th>
+<th>bbbbb</th>
+<th>ccccccccccc</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td></td>
+<td></td>
+<td>cccccccccc cccccccccc cccccccccc cccccccccc cccccccccc
+cccccccccc</td>
+</tr>
+</tbody>
+</table>
+```
diff --git a/documents/markdown/pandoc-md/7723.md b/documents/markdown/pandoc-md/7723.md
new file mode 100644
index 0000000..f3229eb
--- /dev/null
+++ b/documents/markdown/pandoc-md/7723.md
@@ -0,0 +1,8 @@
+```
+% pandoc -t native
+Bug![^1]
+
+[^1]: Note.
+^D
+[ Para [ Str "Bug!" , Note [ Para [ Str "Note." ] ] ] ]
+```
diff --git a/documents/markdown/pandoc-md/7726.md b/documents/markdown/pandoc-md/7726.md
new file mode 100644
index 0000000..bab11ca
--- /dev/null
+++ b/documents/markdown/pandoc-md/7726.md
@@ -0,0 +1,22 @@
+```
+% pandoc -t markdown
+\# Hi
+
+\## Hi
+
+\### Hi
+
+\#### hi
+
+and #hi
+^D
+\# Hi
+
+\## Hi
+
+\### Hi
+
+\#### hi
+
+and #hi
+```
diff --git a/documents/markdown/pandoc-md/7743.md b/documents/markdown/pandoc-md/7743.md
new file mode 100644
index 0000000..de70def
--- /dev/null
+++ b/documents/markdown/pandoc-md/7743.md
@@ -0,0 +1,56 @@
+```
+% pandoc -f markdown+mark -t html
+==Hi==
+^D
+<p><mark>Hi</mark></p>
+```
+
+```
+% pandoc -f markdown+mark -t latex
+==Hi==
+^D
+\hl{Hi}
+```
+
+```
+% pandoc -f markdown+mark -t rst
+==Hi==
+^D
+:mark:`Hi`
+```
+
+```
+% pandoc -f html -t markdown+mark
+<mark>Hi</mark>
+^D
+==Hi==
+```
+
+```
+% pandoc -f html -t markdown
+<mark>Hi</mark>
+^D
+[Hi]{.mark}
+```
+
+```
+% pandoc -f rst -t markdown+mark
+:mark:`Hi`
+^D
+==Hi==
+```
+
+```
+% pandoc -f markdown+mark -t docx -o - | pandoc -f docx -t markdown+mark
+==Hi==
+^D
+==Hi==
+```
+
+```
+% pandoc -f latex -t markdown+mark
+\hl{Hi}
+^D
+==Hi==
+```
+
diff --git a/documents/markdown/pandoc-md/7761.md b/documents/markdown/pandoc-md/7761.md
new file mode 100644
index 0000000..0307bca
--- /dev/null
+++ b/documents/markdown/pandoc-md/7761.md
@@ -0,0 +1,35 @@
+```
+% pandoc --citeproc --csl command/chicago-fullnote-bibliography.csl -t plain
+---
+references:
+- id: noauthor
+ issued: 2020
+ publisher: Oxford University Press
+ publisher-place: Oxford
+ title: Title
+ type: book
+- id: author
+ author:
+ - family: Jones
+ given: Jim
+ issued: 2021
+ title: Title
+ type: book
+ url: "https://duckduckgo.com/cite2021"
+---
+
+Text.[^n]
+
+[^n]: See @author. Another example of a sea level mapping tool with
+similar limitations is @noauthor.
+^D
+Text.[1]
+
+Jones, Jim. Title, 2021. https://duckduckgo.com/cite2021.
+
+Title. Oxford: Oxford University Press, 2020.
+
+[1] See Jim Jones, Title, 2021, https://duckduckgo.com/cite2021. Another
+example of a sea level mapping tool with similar limitations is Title
+(Oxford: Oxford University Press, 2020).
+```
diff --git a/documents/markdown/pandoc-md/7778.md b/documents/markdown/pandoc-md/7778.md
new file mode 100644
index 0000000..7e89141
--- /dev/null
+++ b/documents/markdown/pandoc-md/7778.md
@@ -0,0 +1,59 @@
+Here the thing to remember is that block level structure indications
+take precedence over inline level structure indications:
+
+```
+% pandoc
+Term
+: Def
+<!--
+: comment def
+-->
+^D
+<dl>
+<dt>Term</dt>
+<dd>
+Def <!–
+</dd>
+<dd>
+comment def –>
+</dd>
+</dl>
+```
+
+```
+% pandoc
+Term
+: Def
+test <!--
+: comment def
+and -->
+^D
+<dl>
+<dt>Term</dt>
+<dd>
+Def test <!–
+</dd>
+<dd>
+comment def and –>
+</dd>
+</dl>
+```
+
+```
+% pandoc
+Term
+: Def
+`code
+: comment def
+more code`
+^D
+<dl>
+<dt>Term</dt>
+<dd>
+Def `code
+</dd>
+<dd>
+comment def more code`
+</dd>
+</dl>
+```
diff --git a/documents/markdown/pandoc-md/7803.md b/documents/markdown/pandoc-md/7803.md
new file mode 100644
index 0000000..64547f4
--- /dev/null
+++ b/documents/markdown/pandoc-md/7803.md
@@ -0,0 +1,26 @@
+```
+% pandoc -f html -t asciidoc
+<ul>
+<li><a href=x.htm><i>Xx</i></a><i>,</i>
+<li><a href=x.htm><i>Xx</i></a><i>,,</i>
+<li><a href=x.htm><i>Xx</i></a><i>1</i>
+<li><a href=x.htm><i>Xx</i></a>1<i>1</i>
+<li><a href=x.htm><i>Xx</i></a><i>bcd</i>
+<li><a href=x.htm><i>Xx</i></a>a<i>bcd</i>
+<li><a href=x.htm><i>Xx</i></a>a<i>bcd</i>e
+<li><a href=x.htm><i>Xx</i></a> <i>,</i>
+<li><a href=x.htm><i>Xx</i></a>,<i>,</i>
+<li><a href=x.htm>Xx</a><i>,</i>
+</ul>
+^D
+* link:x.htm[_Xx_]_,_
+* link:x.htm[_Xx_]_,,_
+* link:x.htm[_Xx_]_1_
+* link:x.htm[_Xx_]1__1__
+* link:x.htm[_Xx_]_bcd_
+* link:x.htm[_Xx_]a__bcd__
+* link:x.htm[_Xx_]a__bcd__e
+* link:x.htm[_Xx_] _,_
+* link:x.htm[_Xx_],_,_
+* link:x.htm[Xx]_,_
+```
diff --git a/documents/markdown/pandoc-md/7808.md b/documents/markdown/pandoc-md/7808.md
new file mode 100644
index 0000000..9c7d303
--- /dev/null
+++ b/documents/markdown/pandoc-md/7808.md
@@ -0,0 +1,8 @@
+Wiki links should have no display text, if their display text matches
+their target.
+```
+% pandoc -f mediawiki -t mediawiki
+[[Help]] [[Butter|Butter]] [[Bubbles|Everyone loves bubbles]]
+^D
+[[Help]] [[Butter]] [[Bubbles|Everyone loves bubbles]]
+```
diff --git a/documents/markdown/pandoc-md/7810.md b/documents/markdown/pandoc-md/7810.md
new file mode 100644
index 0000000..389aa73
--- /dev/null
+++ b/documents/markdown/pandoc-md/7810.md
@@ -0,0 +1,43 @@
+```
+% pandoc -f org -t org
+-
+ #+begin_example
+ aa
+ #+end_example
+- test
+^D
+-
+ #+begin_example
+ aa
+ #+end_example
+
+- test
+```
+
+```
+% pandoc -f org -t org
+- a
+-
+- a
+- a
+^D
+- a
+-
+- a
+- a
+```
+
+```
+% pandoc -f org -t org
+- a
+ - b
+ - b
+- a
+- a
+^D
+- a
+ - b
+ - b
+- a
+- a
+```
diff --git a/documents/markdown/pandoc-md/7813.md b/documents/markdown/pandoc-md/7813.md
new file mode 100644
index 0000000..216a91e
--- /dev/null
+++ b/documents/markdown/pandoc-md/7813.md
@@ -0,0 +1,26 @@
+```
+% pandoc --metadata-file command/7813-meta.yaml -t native -s
+Hi
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "abstract"
+ , MetaBlocks
+ [ Para
+ [ Str "a"
+ , Space
+ , Str "footnote"
+ , Note [ Para [ Str "content" ] ]
+ , Space
+ , Str "in"
+ , Space
+ , Str "abstract."
+ ]
+ ]
+ )
+ ]
+ }
+ [ Para [ Str "Hi" ] ]
+```
diff --git a/documents/markdown/pandoc-md/7826.md b/documents/markdown/pandoc-md/7826.md
new file mode 100644
index 0000000..425a04d
--- /dev/null
+++ b/documents/markdown/pandoc-md/7826.md
@@ -0,0 +1,78 @@
+```
+% pandoc -t plain --citeproc
+---
+bibliography: command/biblio.bib
+suppress-bibliography: true
+csl: command/american-medical-association.csl
+notes-after-punctuation: true
+---
+
+In numerous recent works [@item1; @item2], statistician
+Foo and Bar have criticized XXX.
+^D
+In numerous recent works,^(1,2) statistician Foo and Bar have criticized
+XXX.
+```
+```
+% pandoc -t plain --citeproc
+---
+bibliography: command/biblio.bib
+suppress-bibliography: true
+csl: command/american-medical-association.csl
+---
+
+In numerous recent works [@item1; @item2], statistician
+Foo and Bar have criticized XXX.
+^D
+In numerous recent works^(1,2), statistician Foo and Bar have criticized
+XXX.
+```
+```
+% pandoc -t plain --citeproc
+---
+bibliography: command/biblio.bib
+suppress-bibliography: true
+csl: command/chicago-fullnote-bibliography.csl
+notes-after-punctuation: false
+---
+
+In numerous recent works [@item1; @item2], statistician
+Foo and Bar have criticized XXX.
+^D
+In numerous recent works[1], statistician Foo and Bar have criticized
+XXX.
+
+[1] John Doe, First Book (Cambridge: Cambridge University Press, 2005);
+John Doe, “Article,” Journal of Generic Studies 6 (2006): 33–34.
+```
+```
+% pandoc -t plain --citeproc
+---
+bibliography: command/biblio.bib
+suppress-bibliography: true
+csl: command/chicago-fullnote-bibliography.csl
+---
+
+In numerous recent works [@item1; @item2], statistician
+Foo and Bar have criticized XXX.
+^D
+In numerous recent works,[1] statistician Foo and Bar have criticized
+XXX.
+
+[1] John Doe, First Book (Cambridge: Cambridge University Press, 2005);
+John Doe, “Article,” Journal of Generic Studies 6 (2006): 33–34.
+```
+```
+% pandoc -t plain --citeproc
+---
+bibliography: command/biblio.bib
+suppress-bibliography: true
+notes-after-punctuation: true
+---
+
+In numerous recent works [@item1; @item2], statistician
+Foo and Bar have criticized XXX.
+^D
+In numerous recent works (Doe 2005, 2006), statistician Foo and Bar have
+criticized XXX.
+```
diff --git a/documents/markdown/pandoc-md/7847.md b/documents/markdown/pandoc-md/7847.md
new file mode 100644
index 0000000..534d974
--- /dev/null
+++ b/documents/markdown/pandoc-md/7847.md
@@ -0,0 +1,85 @@
+```
+% pandoc -f html -t markdown_strict+pipe_tables
+<table>
+<colgroup>
+<col style="width: 20%" />
+<col style="width: 60%" />
+<col style="width: 20%" />
+</colgroup>
+<thead>
+<tr>
+<th>aaa</th>
+<th>bbb</th>
+<th>ccc</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Consequat nisi sit amet nibh. Nunc mi tortor, tristique
+sit amet, rhoncus porta, malesuada elementum, nisi.</td>
+<td></td>
+<td>ccc</td>
+</tr>
+</tbody>
+</table>
+^D
+| aaa | bbb | ccc |
+|---------------|------------------------------------------|---------------|
+| Consequat nisi sit amet nibh. Nunc mi tortor, tristique sit amet, rhoncus porta, malesuada elementum, nisi. | | ccc |
+
+```
+
+```
+% pandoc -f html -t markdown_strict+pipe_tables
+<table>
+<tr>
+<th>aaa</th>
+<th>bbb</th>
+<th>ccc</th>
+</tr>
+<tr>
+<td>Consequat nisi sit amet nibh. Nunc mi tortor, tristique
+sit amet, rhoncus porta, malesuada elementum, nisi.</td>
+<td></td>
+<td>ccc</td>
+</tr>
+</table>
+^D
+| aaa | bbb | ccc |
+|----|----|----|
+| Consequat nisi sit amet nibh. Nunc mi tortor, tristique sit amet, rhoncus porta, malesuada elementum, nisi. | | ccc |
+
+```
+
+```
+% pandoc -f html -t commonmark+pipe_tables
+<table>
+<colgroup>
+<col style="width: 20%" />
+<col style="width: 60%" />
+<col style="width: 20%" />
+</colgroup>
+<thead>
+<tr>
+<th>aaa</th>
+<th>bbb</th>
+<th>ccc</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Consequat nisi sit amet nibh. Nunc mi tortor, tristique
+sit amet, rhoncus porta, malesuada elementum, nisi.</td>
+<td>bbb</td>
+<td>ccc</td>
+</tr>
+</tbody>
+</table>
+^D
+| aaa | bbb | ccc |
+|----|----|----|
+| Consequat nisi sit amet nibh. Nunc mi tortor, tristique sit amet, rhoncus porta, malesuada elementum, nisi. | bbb | ccc |
+
+```
+
+
diff --git a/documents/markdown/pandoc-md/7857.md b/documents/markdown/pandoc-md/7857.md
new file mode 100644
index 0000000..0776fdc
--- /dev/null
+++ b/documents/markdown/pandoc-md/7857.md
@@ -0,0 +1,21 @@
+```
+% pandoc --slide-level=2 -t beamer
+# section
+
+::: notes
+my note
+:::
+
+## slide
+
+ok
+^D
+\section{section}\label{section}
+
+\note{my note}
+
+\begin{frame}{slide}
+\protect\phantomsection\label{slide}
+ok
+\end{frame}
+```
diff --git a/documents/markdown/pandoc-md/7858.md b/documents/markdown/pandoc-md/7858.md
new file mode 100644
index 0000000..dc2f107
--- /dev/null
+++ b/documents/markdown/pandoc-md/7858.md
@@ -0,0 +1,6 @@
+```
+% pandoc -t html --columns=50 --wrap=auto
+`neuth asontue stheuosnt aeosunth asnoetuh asneotuh snatehou snatoehu sntahe ousntahoe unstaheou sntaheou aoeu sthoeu sntaoeusnth ansoetuhs atoeuh saonteu`
+^D
+<p><code>neuth asontue stheuosnt aeosunth asnoetuh asneotuh snatehou snatoehu sntahe ousntahoe unstaheou sntaheou aoeu sthoeu sntaoeusnth ansoetuhs atoeuh saonteu</code></p>
+```
diff --git a/documents/markdown/pandoc-md/7861.md b/documents/markdown/pandoc-md/7861.md
new file mode 100644
index 0000000..a5b68de
--- /dev/null
+++ b/documents/markdown/pandoc-md/7861.md
@@ -0,0 +1,7 @@
+```
+% pandoc -s -t native --data-dir=command/7861 --metadata-file=../../7861.yaml
+Hello
+^D
+2> Could not find metadata file ../../7861.yaml
+=> 98
+```
diff --git a/documents/markdown/pandoc-md/7863.md b/documents/markdown/pandoc-md/7863.md
new file mode 100644
index 0000000..d6a7825
--- /dev/null
+++ b/documents/markdown/pandoc-md/7863.md
@@ -0,0 +1,27 @@
+```
+% pandoc -f commonmark+yaml_metadata_block+sourcepos -t native
+---
+key:
+ |
+ value
+...
+
+
+Text
+^D
+[ Div
+ ( ""
+ , []
+ , [ ( "wrapper" , "1" ) , ( "data-pos" , "8:1-9:1" ) ]
+ )
+ [ Para
+ [ Span
+ ( ""
+ , []
+ , [ ( "wrapper" , "1" ) , ( "data-pos" , "8:1-8:5" ) ]
+ )
+ [ Str "Text" ]
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/7871.md b/documents/markdown/pandoc-md/7871.md
new file mode 100644
index 0000000..299e79c
--- /dev/null
+++ b/documents/markdown/pandoc-md/7871.md
@@ -0,0 +1,14 @@
+```
+% pandoc -f html -t html
+<table>
+<tr><td style="padding-right:4px;text-align:right">a</td></tr>
+</table>
+^D
+<table>
+<tbody>
+<tr>
+<td style="text-align: right; padding-right: 4px;">a</td>
+</tr>
+</tbody>
+</table>
+```
diff --git a/documents/markdown/pandoc-md/7884.md b/documents/markdown/pandoc-md/7884.md
new file mode 100644
index 0000000..d6006a8
--- /dev/null
+++ b/documents/markdown/pandoc-md/7884.md
@@ -0,0 +1,72 @@
+```
+% pandoc -f html+epub_html_exts -t native
+<body epub:type="bodymatter">
+<section id="chapter-1" class="level1" data-number="1">
+<h1 data-number="1">Chapter 1</h1>
+<p>Here is a footnote.<a href="#fn1" class="footnote-ref" id="fnref1" epub:type="noteref">1</a></p>
+<p>Here is a second footnote.<a href="#fn2" class="footnote-ref" id="fnref2" epub:type="noteref">2</a></p>
+</section>
+<section class="footnotes footnotes-end-of-document" epub:type="footnotes">
+<hr />
+<ol>
+<li id="fn1" epub:type="footnote"><p>This is a test<a href="#fnref1" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn2" epub:type="footnote"><p>This is another test<a href="#fnref2" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+</ol>
+</section>
+</body>
+^D
+[ Div
+ ( "chapter-1"
+ , [ "section" , "level1" ]
+ , [ ( "number" , "1" ) ]
+ )
+ [ Header
+ 1
+ ( "" , [] , [ ( "number" , "1" ) ] )
+ [ Str "Chapter" , Space , Str "1" ]
+ , Para
+ [ Str "Here"
+ , Space
+ , Str "is"
+ , Space
+ , Str "a"
+ , Space
+ , Str "footnote."
+ , Note
+ [ Para
+ [ Str "This"
+ , Space
+ , Str "is"
+ , Space
+ , Str "a"
+ , Space
+ , Str "test"
+ ]
+ ]
+ ]
+ , Para
+ [ Str "Here"
+ , Space
+ , Str "is"
+ , Space
+ , Str "a"
+ , Space
+ , Str "second"
+ , Space
+ , Str "footnote."
+ , Note
+ [ Para
+ [ Str "This"
+ , Space
+ , Str "is"
+ , Space
+ , Str "another"
+ , Space
+ , Str "test"
+ ]
+ ]
+ ]
+ ]
+]
+
+```
diff --git a/documents/markdown/pandoc-md/7894.md b/documents/markdown/pandoc-md/7894.md
new file mode 100644
index 0000000..62134ff
--- /dev/null
+++ b/documents/markdown/pandoc-md/7894.md
@@ -0,0 +1,109 @@
+```
+% pandoc -f ris -t csljson
+TY - BOOK
+ID - Chang_Keisler_Model_Theory
+AU - Chang, C. C.
+AU - Keisler, H. Jerome
+PY - 1990
+ET - 3
+TI - Model Theory
+PU - North-Holland Press
+PP - Amsterdam
+KW - model theory
+KW - logic
+ER -
+TY - JOUR
+AU - Shannon, Claude E.
+PY - 1948
+DA - July
+TI - A Mathematical Theory of Communication
+T2 - Bell System Technical Journal
+SP - 379
+EP - 423
+VL - 27
+ER -
+TY - JOUR
+T1 - On computable numbers, with an application to the Entscheidungsproblem
+A1 - Turing, Alan Mathison
+JO - Proc. of London Mathematical Society
+VL - 47
+IS - 1
+KW - decidability
+KW - computability
+SP - 230
+EP - 265
+Y1 - 1937
+ER -
+^D
+[
+ {
+ "author": [
+ {
+ "family": "Chang",
+ "given": "C. C."
+ },
+ {
+ "family": "Keisler",
+ "given": "H. Jerome"
+ }
+ ],
+ "edition": "3",
+ "id": "Chang_Keisler_Model_Theory",
+ "issued": {
+ "date-parts": [
+ [
+ 1990
+ ]
+ ]
+ },
+ "keyword": "logic, model theory",
+ "publisher-place": "Amsterdam",
+ "title": "Model Theory",
+ "type": "book"
+ },
+ {
+ "author": [
+ {
+ "family": "Shannon",
+ "given": "Claude E."
+ }
+ ],
+ "container-title": "Bell System Technical Journal",
+ "id": "Shannon_1948",
+ "issued": {
+ "date-parts": [
+ [
+ 1948
+ ]
+ ]
+ },
+ "page": "379-423",
+ "title": "A Mathematical Theory of Communication",
+ "type": "article-journal",
+ "volume": "27"
+ },
+ {
+ "author": [
+ {
+ "family": "Turing",
+ "given": "Alan Mathison"
+ }
+ ],
+ "container-title": "Proc. of London Mathematical Society",
+ "id": "Turing_1937",
+ "issue": "1",
+ "issued": {
+ "date-parts": [
+ [
+ 1937
+ ]
+ ]
+ },
+ "keyword": "computability, decidability",
+ "page": "230-265",
+ "title": "On computable numbers, with an application to the Entscheidungsproblem",
+ "type": "article-journal",
+ "volume": "47"
+ }
+]
+```
diff --git a/documents/markdown/pandoc-md/7919.md b/documents/markdown/pandoc-md/7919.md
new file mode 100644
index 0000000..2fa7f35
--- /dev/null
+++ b/documents/markdown/pandoc-md/7919.md
@@ -0,0 +1,118 @@
+```
+% pandoc -f markdown
+single column table |
+------------------- |
+item 1 |
+item 2 |
+^D
+<table>
+<thead>
+<tr>
+<th>single column table</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>item 1</td>
+</tr>
+<tr>
+<td>item 2</td>
+</tr>
+</tbody>
+</table>
+```
+
+```
+% pandoc -f markdown
+| single column table
+| -------------------
+| item 1
+| item 2
+^D
+<table>
+<thead>
+<tr>
+<th>single column table</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>item 1</td>
+</tr>
+<tr>
+<td>item 2</td>
+</tr>
+</tbody>
+</table>
+```
+
+```
+% pandoc -f markdown
+single column table
+-------------------
+item 1
+item 2
+^D
+<h2 id="single-column-table">single column table</h2>
+<p>item 1 item 2</p>
+```
+
+```
+% pandoc -f gfm
+single column table |
+------------------- |
+item 1 |
+item 2 |
+^D
+<table>
+<thead>
+<tr>
+<th>single column table</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>item 1</td>
+</tr>
+<tr>
+<td>item 2</td>
+</tr>
+</tbody>
+</table>
+```
+
+```
+% pandoc -f gfm
+| single column table
+| -------------------
+| item 1
+| item 2
+^D
+<table>
+<thead>
+<tr>
+<th>single column table</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>item 1</td>
+</tr>
+<tr>
+<td>item 2</td>
+</tr>
+</tbody>
+</table>
+```
+
+```
+% pandoc -f gfm
+single column table
+-------------------
+item 1
+item 2
+^D
+<h2 id="single-column-table">single column table</h2>
+<p>item 1 item 2</p>
+```
+
diff --git a/documents/markdown/pandoc-md/7920.md b/documents/markdown/pandoc-md/7920.md
new file mode 100644
index 0000000..6bfac3a
--- /dev/null
+++ b/documents/markdown/pandoc-md/7920.md
@@ -0,0 +1,20 @@
+```
+% pandoc -t native
+[hi]{#123}
+^D
+[ Para [ Span ( "123" , [] , [] ) [ Str "hi" ] ] ]
+```
+
+```
+% pandoc -t markdown
+[hi]{#123}
+^D
+[hi]{#123}
+```
+
+```
+% pandoc -t markdown
+# Hi {#123}
+^D
+# Hi {#123}
+```
diff --git a/documents/markdown/pandoc-md/7930.md b/documents/markdown/pandoc-md/7930.md
new file mode 100644
index 0000000..5e36254
--- /dev/null
+++ b/documents/markdown/pandoc-md/7930.md
@@ -0,0 +1,98 @@
+```
+% pandoc -f latex -t native
+We discuss foobar in notes \ref{note:X} and \ref{note:Y}.
+
+Foo.\footnote{\label{note:X}A note. See also note~\ref{note:Y}.}
+
+Bar.\footnote{\label{note:Y}Another note. See also
+note~\ref{note:X}}
+^D
+[ Para
+ [ Str "We"
+ , Space
+ , Str "discuss"
+ , Space
+ , Str "foobar"
+ , Space
+ , Str "in"
+ , Space
+ , Str "notes"
+ , Space
+ , Link
+ ( ""
+ , []
+ , [ ( "reference-type" , "ref" )
+ , ( "reference" , "note:X" )
+ ]
+ )
+ [ Str "1" ]
+ ( "#note:X" , "" )
+ , Space
+ , Str "and"
+ , Space
+ , Link
+ ( ""
+ , []
+ , [ ( "reference-type" , "ref" )
+ , ( "reference" , "note:Y" )
+ ]
+ )
+ [ Str "2" ]
+ ( "#note:Y" , "" )
+ , Str "."
+ ]
+, Para
+ [ Str "Foo."
+ , Note
+ [ Para
+ [ Span ( "note:X" , [] , [ ( "label" , "note:X" ) ] ) []
+ , Str "A"
+ , Space
+ , Str "note."
+ , Space
+ , Str "See"
+ , Space
+ , Str "also"
+ , Space
+ , Str "note\160"
+ , Link
+ ( ""
+ , []
+ , [ ( "reference-type" , "ref" )
+ , ( "reference" , "note:Y" )
+ ]
+ )
+ [ Str "2" ]
+ ( "#note:Y" , "" )
+ , Str "."
+ ]
+ ]
+ ]
+, Para
+ [ Str "Bar."
+ , Note
+ [ Para
+ [ Span ( "note:Y" , [] , [ ( "label" , "note:Y" ) ] ) []
+ , Str "Another"
+ , Space
+ , Str "note."
+ , Space
+ , Str "See"
+ , Space
+ , Str "also"
+ , SoftBreak
+ , Str "note\160"
+ , Link
+ ( ""
+ , []
+ , [ ( "reference-type" , "ref" )
+ , ( "reference" , "note:X" )
+ ]
+ )
+ [ Str "1" ]
+ ( "#note:X" , "" )
+ ]
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/7939.md b/documents/markdown/pandoc-md/7939.md
new file mode 100644
index 0000000..4b09eb4
--- /dev/null
+++ b/documents/markdown/pandoc-md/7939.md
@@ -0,0 +1,9 @@
+```
+% pandoc -f latex -t native
+\def\|{\verb|}
+\vbox{
+\hbox{\|\begin{minipage}[t]%|}
+}
+^D
+[ Para [ Code ( "" , [] , [] ) "\\begin{minipage}[t]%" ] ]
+```
diff --git a/documents/markdown/pandoc-md/7953.md b/documents/markdown/pandoc-md/7953.md
new file mode 100644
index 0000000..118aea2
--- /dev/null
+++ b/documents/markdown/pandoc-md/7953.md
@@ -0,0 +1,11 @@
+```
+% pandoc -f latex -t native
+{foo\bgroup bar\egroup }
+^D
+[ Para
+ [ Span
+ ( "" , [] , [] )
+ [ Str "foo" , Span ( "" , [] , [] ) [ Str "bar" ] ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/7965.md b/documents/markdown/pandoc-md/7965.md
new file mode 100644
index 0000000..e470a8c
--- /dev/null
+++ b/documents/markdown/pandoc-md/7965.md
@@ -0,0 +1,54 @@
+```
+% pandoc -f markdown -t gfm
+Watson and Crick (1953)
+
+<div id="refs" class="references csl-bib-body hanging-indent">
+
+<div id="ref-WatsonCrick1953" class="csl-entry">
+
+Watson, J. D., and F. H. C. Crick. 1953. “Molecular Structure of Nucleic
+Acids: A Structure for Deoxyribose Nucleic Acid.” *Nature* 171 (4356):
+737–38. <https://doi.org/10.1038/171737a0>.
+
+</div>
+
+</div>
+^D
+Watson and Crick (1953)
+
+<div id="refs" class="references csl-bib-body hanging-indent">
+
+<div id="ref-WatsonCrick1953" class="csl-entry">
+
+Watson, J. D., and F. H. C. Crick. 1953. “Molecular Structure of Nucleic
+Acids: A Structure for Deoxyribose Nucleic Acid.” *Nature* 171 (4356):
+737–38. <https://doi.org/10.1038/171737a0>.
+
+</div>
+
+</div>
+```
+
+```
+% pandoc -f markdown -t gfm-raw_html
+Watson and Crick (1953)
+
+<div id="refs" class="references csl-bib-body hanging-indent">
+
+<div id="ref-WatsonCrick1953" class="csl-entry">
+
+Watson, J. D., and F. H. C. Crick. 1953. “Molecular Structure of Nucleic
+Acids: A Structure for Deoxyribose Nucleic Acid.” *Nature* 171 (4356):
+737–38. <https://doi.org/10.1038/171737a0>.
+
+</div>
+
+</div>
+^D
+Watson and Crick (1953)
+
+Watson, J. D., and F. H. C. Crick. 1953. “Molecular Structure of Nucleic
+Acids: A Structure for Deoxyribose Nucleic Acid.” *Nature* 171 (4356):
+737–38. <https://doi.org/10.1038/171737a0>.
+```
+
diff --git a/documents/markdown/pandoc-md/8011.md b/documents/markdown/pandoc-md/8011.md
new file mode 100644
index 0000000..552ad2a
--- /dev/null
+++ b/documents/markdown/pandoc-md/8011.md
@@ -0,0 +1,15 @@
+```
+% pandoc -f docbook -t gfm
+<itemizedlist mark="none">
+<listitem>
+<simpara>❏ a</simpara>
+</listitem>
+<listitem>
+<simpara>✓ b</simpara>
+</listitem>
+</itemizedlist>
+^D
+- [ ] a
+
+- [x] b
+```
diff --git a/documents/markdown/pandoc-md/8024.md b/documents/markdown/pandoc-md/8024.md
new file mode 100644
index 0000000..e8b1fc5
--- /dev/null
+++ b/documents/markdown/pandoc-md/8024.md
@@ -0,0 +1,10 @@
+```
+% pandoc -d command/8024a.yaml -t markdown
+Hello, if this works the text should be wrapped.
+^D
+Hello, if this
+works the text
+should be
+wrapped.
+
+```
diff --git a/documents/markdown/pandoc-md/8028.md b/documents/markdown/pandoc-md/8028.md
new file mode 100644
index 0000000..325e93b
--- /dev/null
+++ b/documents/markdown/pandoc-md/8028.md
@@ -0,0 +1,10 @@
+```
+% pandoc
+foo^[a note
+
+with multiple paragraphs]
+^D
+<p>foo^[a note</p>
+<p>with multiple paragraphs]</p>
+
+```
diff --git a/documents/markdown/pandoc-md/8047.md b/documents/markdown/pandoc-md/8047.md
new file mode 100644
index 0000000..5b5efb7
--- /dev/null
+++ b/documents/markdown/pandoc-md/8047.md
@@ -0,0 +1,6 @@
+```
+% pandoc --wrap=none
+{height=10em width=10em style='border: 1px solid black'}
+^D
+<p><img src="file.jpg" style="border: 1px solid black;width:10em;height:10em" /></p>
+```
diff --git a/documents/markdown/pandoc-md/8070.md b/documents/markdown/pandoc-md/8070.md
new file mode 100644
index 0000000..538bba4
--- /dev/null
+++ b/documents/markdown/pandoc-md/8070.md
@@ -0,0 +1,13 @@
+```
+% pandoc -f html -t asciidoc
+<p><a href="https://docs.oracle.com/database/121/BRADV/rcmxplat.htm#BRADV724">12.1
+manual, Database Backup and Recovery User’s Guide:
+<span class="enumeration_chapter">Chapter 28</span> Transporting Data Across Platforms,
+Steps to Transport a Database to a Different Platform Using Backup Sets</a></p>
+^D
+https://docs.oracle.com/database/121/BRADV/rcmxplat.htm#BRADV724[12.1
+manual, Database Backup and Recovery User’s Guide:
+[.enumeration_chapter]#Chapter 28# Transporting Data Across
+Platforms, Steps to Transport a Database to a Different Platform
+Using Backup Sets]
+```
diff --git a/documents/markdown/pandoc-md/8079.md b/documents/markdown/pandoc-md/8079.md
new file mode 100644
index 0000000..a6adf49
--- /dev/null
+++ b/documents/markdown/pandoc-md/8079.md
@@ -0,0 +1,19 @@
+```
+% pandoc -f html -t icml
+<table custom-style="Foo">
+<tr><td>one</td></tr>
+</table>
+^D
+<Table AppliedTableStyle="TableStyle/Foo" HeaderRowCount="0" BodyRowCount="1" ColumnCount="1">
+ <Column Name="0" />
+ <Cell Name="0:0" AppliedCellStyle="CellStyle/Cell">
+ <ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/TablePar">
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <Content>one</Content>
+ </CharacterStyleRange>
+ </ParagraphStyleRange>
+ </Cell>
+</Table>
+<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/TableCaption">
+</ParagraphStyleRange>
+```
diff --git a/documents/markdown/pandoc-md/8088.md b/documents/markdown/pandoc-md/8088.md
new file mode 100644
index 0000000..34798ee
--- /dev/null
+++ b/documents/markdown/pandoc-md/8088.md
@@ -0,0 +1,6 @@
+```
+% pandoc -t latex --biblatex
+[@first, 1; @second; @third, 3]
+^D
+\autocites[1]{first}{second}[3]{third}
+```
diff --git a/documents/markdown/pandoc-md/8097.md b/documents/markdown/pandoc-md/8097.md
new file mode 100644
index 0000000..fa70890
--- /dev/null
+++ b/documents/markdown/pandoc-md/8097.md
@@ -0,0 +1,9 @@
+```
+% pandoc --number-sec --number-offset=2 --wrap=none
+# One
+
+# two
+^D
+<h1 data-number="3" id="one"><span class="header-section-number">3</span> One</h1>
+<h1 data-number="4" id="two"><span class="header-section-number">4</span> two</h1>
+```
diff --git a/documents/markdown/pandoc-md/8098.md b/documents/markdown/pandoc-md/8098.md
new file mode 100644
index 0000000..3196445
--- /dev/null
+++ b/documents/markdown/pandoc-md/8098.md
@@ -0,0 +1,36 @@
+```
+% pandoc -t revealjs --slide-level=2
+# Title 1
+
+## Slide 1
+
+Text.
+
+::: fragment
+### Sub Slide header
+
+Text.
+:::
+
+## Slide 2
+
+Text.
+^D
+<section>
+<section id="title-1" class="title-slide slide level1">
+<h1>Title 1</h1>
+
+</section>
+<section id="slide-1" class="slide level2">
+<h2>Slide 1</h2>
+<p>Text.</p>
+<div class="fragment">
+<h3 id="sub-slide-header">Sub Slide header</h3>
+<p>Text.</p>
+</div>
+</section>
+<section id="slide-2" class="slide level2">
+<h2>Slide 2</h2>
+<p>Text.</p>
+</section></section>
+```
diff --git a/documents/markdown/pandoc-md/8110.md b/documents/markdown/pandoc-md/8110.md
new file mode 100644
index 0000000..e4d578e
--- /dev/null
+++ b/documents/markdown/pandoc-md/8110.md
@@ -0,0 +1,41 @@
+```
+% pandoc -f mediawiki
+{| class="wikitable"
+! Header text
+! Header text
+! Header text
+
+|-
+| Example
+| Example
+| Example
+
+|- <!-- This is a comment -->
+| Example
+| Example
+| Example
+|}
+^D
+<table>
+<thead>
+<tr>
+<th><p>Header text</p></th>
+<th><p>Header text</p></th>
+<th><p>Header text</p></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><p>Example</p></td>
+<td><p>Example</p></td>
+<td><p>Example</p></td>
+</tr>
+<tr>
+<td><p>Example</p></td>
+<td><p>Example</p></td>
+<td><p>Example</p></td>
+</tr>
+</tbody>
+</table>
+
+```
diff --git a/documents/markdown/pandoc-md/8131.md b/documents/markdown/pandoc-md/8131.md
new file mode 100644
index 0000000..02f6edc
--- /dev/null
+++ b/documents/markdown/pandoc-md/8131.md
@@ -0,0 +1,41 @@
+# TOC in gfm contains no HTML by default
+```
+% pandoc --to=gfm --toc --standalone
+# Head
+
+Content
+^D
+- [Head](#head)
+
+# Head
+
+Content
+```
+
+# Same in Markdown if link_attributes extension is disabled
+```
+% pandoc --to=markdown-link_attributes --toc --standalone
+# Head
+
+Content
+^D
+- [Head](#head)
+
+# Head
+
+Content
+```
+
+# IDs are added to TOC with the "attributes" CommonMark extension
+```
+% pandoc --to=commonmark+gfm_auto_identifiers+attributes --toc -s
+# Nam a sapien
+
+Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
+^D
+- [Nam a sapien](#nam-a-sapien){#toc-nam-a-sapien}
+
+# Nam a sapien
+
+Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
+```
diff --git a/documents/markdown/pandoc-md/8150.md b/documents/markdown/pandoc-md/8150.md
new file mode 100644
index 0000000..36865db
--- /dev/null
+++ b/documents/markdown/pandoc-md/8150.md
@@ -0,0 +1,55 @@
+Nested bullet lists
+```
+% pandoc -f html -t markdown
+<ul>
+ <li>L1</li>
+ <li>L2</li>
+ <ul>
+ <li>L3.1</li>
+ <li>L3.2</li>
+ </ul>
+ <li>L4</li>
+</ul>
+^D
+- L1
+- L2
+ - L3.1
+ - L3.2
+- L4
+```
+
+Nested ordered lists
+```
+% pandoc -f html -t markdown
+<ol>
+ <li>L1</li>
+ <li>L2</li>
+ <ol>
+ <li>L3.1</li>
+ <li>L3.2</li>
+ </ol>
+</ol>
+^D
+1. L1
+2. L2
+ 1. L3.1
+ 2. L3.2
+```
+
+Ordered list nested below an unordered list
+```
+% pandoc -f html -t markdown
+<ul>
+ <li>L1</li>
+ <li>L2</li>
+ <ol>
+ <li>L3.1</li>
+ <li>L3.2</li>
+ </ol>
+</ul>
+^D
+- L1
+- L2
+ 1. L3.1
+ 2. L3.2
+```
diff --git a/documents/markdown/pandoc-md/8170.md b/documents/markdown/pandoc-md/8170.md
new file mode 100644
index 0000000..02485ac
--- /dev/null
+++ b/documents/markdown/pandoc-md/8170.md
@@ -0,0 +1,15 @@
+```
+% pandoc -f rtf -t html
+{\rtf1\ansi\ansicpg1252\cocoartf2638
+\cocoascreenfonts1\cocoatextscaling0\cocoaplatform0{\fonttbl\f0\froman\fcharset0 Times-Roman;}
+{\colortbl;\red255\green255\blue255;}
+{\*\expandedcolortbl;;}
+\margl1440\margr1440\vieww16800\viewh17280\viewkind0
+\pard\tx1080\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\li180\fi440\sa120\pardirnatural\partightenfactor0
+
+\f0\fs34 \cf0 In 5
+\fs20 \super th
+\fs34 \nosupersub grade I found a bug.}
+^D
+<p>In 5<sup>th</sup> grade I found a bug.</p>
+```
diff --git a/documents/markdown/pandoc-md/8174.md b/documents/markdown/pandoc-md/8174.md
new file mode 100644
index 0000000..61fe37b
--- /dev/null
+++ b/documents/markdown/pandoc-md/8174.md
@@ -0,0 +1,44 @@
+````
+% pandoc -t native
+```yaml {#id}
+some: code
+```
+^D
+[ CodeBlock ( "id" , [ "yaml" ] , [] ) "some: code" ]
+````
+
+````
+% pandoc -t native
+```yaml {.class #id}
+some: code
+```
+^D
+[ CodeBlock
+ ( "id" , [ "yaml" , "class" ] , [] ) "some: code"
+]
+````
+
+<!-- Inline code sections at the start of the line should not be mistaken for code blocks -->
+````
+% pandoc -t native
+```ab```
+^D
+[ Para [ Code ( "" , [] , [] ) "ab" ] ]
+````
+
+````
+% pandoc -t native
+```ab```{.class}
+^D
+[ Para [ Code ( "" , [ "class" ] , [] ) "ab" ] ]
+````
+
+<!-- Illegal language identifiers should be treated as inline code for now -->
+````
+% pandoc -t native
+``` foo}{.bar}
+test
+```
+^D
+[ Para [ Code ( "" , [] , [] ) "foo}{.bar} test" ] ]
+````
diff --git a/documents/markdown/pandoc-md/8178.md b/documents/markdown/pandoc-md/8178.md
new file mode 100644
index 0000000..da6d2d8
--- /dev/null
+++ b/documents/markdown/pandoc-md/8178.md
@@ -0,0 +1,25 @@
+```
+% pandoc -f dokuwiki -t native
+<latex>$\sum_{\substack{(i,j) \in I^2 \i \neq j}}$</latex>
+^D
+[ Para
+ [ RawInline
+ (Format "latex")
+ "$\\sum_{\\substack{(i,j) \\in I^2 \\i \\neq j}}$"
+ ]
+]
+```
+
+```
+% pandoc -f dokuwiki+tex_math_dollars -t native
+$mc^2$
+^D
+[ Para [ Math InlineMath "mc^2" ] ]
+```
+
+```
+% pandoc -f dokuwiki -t native
+$mc^2$
+^D
+[ Para [ Str "$mc^2$" ] ]
+```
diff --git a/documents/markdown/pandoc-md/8179.md b/documents/markdown/pandoc-md/8179.md
new file mode 100644
index 0000000..ef73618
--- /dev/null
+++ b/documents/markdown/pandoc-md/8179.md
@@ -0,0 +1,6 @@
+```
+% pandoc -f latex -t native
+\passthrough{\lstinline!\\textbf\{\}!}
+^D
+[ Para [ Code ( "" , [] , [] ) "\\textbf{}" ] ]
+```
diff --git a/documents/markdown/pandoc-md/8182.md b/documents/markdown/pandoc-md/8182.md
new file mode 100644
index 0000000..7e28bd1
--- /dev/null
+++ b/documents/markdown/pandoc-md/8182.md
@@ -0,0 +1,6 @@
+```
+% pandoc -f dokuwiki -t rst
+This //text and [[https://pandoc.org/|link]] are in italic//.
+^D
+This *text and* `link <https://pandoc.org/>`__ *are in italic*.
+```
diff --git a/documents/markdown/pandoc-md/8201.md b/documents/markdown/pandoc-md/8201.md
new file mode 100644
index 0000000..854e13d
--- /dev/null
+++ b/documents/markdown/pandoc-md/8201.md
@@ -0,0 +1,6 @@
+```
+% pandoc -f org -t html
+[[file:d:/Home/Documents/test.png][Link Test]]
+^D
+<p><a href="file:///d:/Home/Documents/test.png">Link Test</a></p>
+```
diff --git a/documents/markdown/pandoc-md/8204.md b/documents/markdown/pandoc-md/8204.md
new file mode 100644
index 0000000..a04b5db
--- /dev/null
+++ b/documents/markdown/pandoc-md/8204.md
@@ -0,0 +1,51 @@
+Include abstract in Org output.
+```
+% pandoc --to=org --standalone
+---
+abstract: |
+ This is an *abstract*.
+
+ It has multiple paragraphs.
+---
+^D
+#+begin_abstract
+This is an /abstract/.
+
+It has multiple paragraphs.
+
+#+end_abstract
+```
+
+Parse abstract environment as *abstract* metadata field.
+```
+% pandoc --from=org --to=markdown --standalone
+#+begin_abstract
+
+This is an /abstract/.
+
+It has multiple paragraphs.
+#+end_abstract
+
+Main text
+^D
+---
+abstract: |
+ This is an *abstract*.
+
+ It has multiple paragraphs.
+---
+
+Main text
+```
+
+Uppercase ABSTRACT environment is not moved to metadata.
+```
+% pandoc --from=org --to=markdown --standalone
+#+BEGIN_ABSTRACT
+Some text.
+#+END_ABSTRACT
+^D
+::: ABSTRACT
+Some text.
+:::
+```
diff --git a/documents/markdown/pandoc-md/8216.md b/documents/markdown/pandoc-md/8216.md
new file mode 100644
index 0000000..109342c
--- /dev/null
+++ b/documents/markdown/pandoc-md/8216.md
@@ -0,0 +1,51 @@
+Misaligned separators in grid table
+```
+% pandoc -f markdown -t html
+: Grid Table
+
++-----------------+:-:+
+|Some text |[text]{.class1 .class2 .class3}|
++-----------------+---+
+|Some text |[text]{.class1 .class2 .class3}|
++-----------------+---+
+|Some text |[text]{.class1 .class2 .class3}|
++-----------------+---+
+^D
+<table style="width:69%;">
+<caption>Grid Table</caption>
+<colgroup>
+<col style="width: 25%" />
+<col style="width: 44%" />
+</colgroup>
+<tbody>
+<tr>
+<td>Some text</td>
+<td><span class="class1 class2 class3">text</span></td>
+</tr>
+<tr>
+<td>Some text</td>
+<td><span class="class1 class2 class3">text</span></td>
+</tr>
+<tr>
+<td>Some text</td>
+<td><span class="class1 class2 class3">text</span></td>
+</tr>
+</tbody>
+</table>
+```
+
+Missing cell
+
+```
+% pandoc -f markdown -t gfm
++------+
+| text |
++------+---+
+| text | 1 |
++------+---+
+^D
+| | |
+|------|-----|
+| text | |
+| text | 1 |
+```
diff --git a/documents/markdown/pandoc-md/8219.md b/documents/markdown/pandoc-md/8219.md
new file mode 100644
index 0000000..57617e5
--- /dev/null
+++ b/documents/markdown/pandoc-md/8219.md
@@ -0,0 +1,16 @@
+```
+% pandoc -f html -t latex
+<table id="test">
+ <tr><td>one</td><td>two</td></tr>
+</table>
+^D
+\begin{longtable}[]{@{}ll@{}}
+\caption{}\label{test}\tabularnewline
+\toprule\noalign{}
+\endfirsthead
+\endhead
+\bottomrule\noalign{}
+\endlastfoot
+one & two \\
+\end{longtable}
+```
diff --git a/documents/markdown/pandoc-md/8236.md b/documents/markdown/pandoc-md/8236.md
new file mode 100644
index 0000000..f8c70a7
--- /dev/null
+++ b/documents/markdown/pandoc-md/8236.md
@@ -0,0 +1,15 @@
+```
+% pandoc -f org -t native
+ #+begin_src jupyter-python :session py :display plain
+ import pandas as pd
+ df = pd.read_csv('weight.csv', parse_dates=['Date'], index_col=0)
+ #+end_src
+^D
+[ CodeBlock
+ ( ""
+ , [ "python" , "code" ]
+ , [ ( "session" , "py" ) , ( "display" , "plain" ) ]
+ )
+ "import pandas as pd\ndf = pd.read_csv('weight.csv', parse_dates=['Date'], index_col=0)\n"
+]
+```
diff --git a/documents/markdown/pandoc-md/8243.md b/documents/markdown/pandoc-md/8243.md
new file mode 100644
index 0000000..87c8009
--- /dev/null
+++ b/documents/markdown/pandoc-md/8243.md
@@ -0,0 +1,23 @@
+```
+% pandoc -f latex
+\newenvironment{topics}{
+\newcommand{\topic}[2]{ \item{##1 / ##2} }
+Topics:
+\begin{itemize}
+}
+{
+\end{itemize}
+}
+
+\begin{topics}
+\topic{Foo}{Bar}
+\topic{Baz}{Bim}
+\end{topics}
+^D
+<p>Topics:</p>
+<ul>
+<li><p><span>Foo / Bar</span></p></li>
+<li><p><span>Baz / Bim</span></p></li>
+</ul>
+```
+
diff --git a/documents/markdown/pandoc-md/8251.md b/documents/markdown/pandoc-md/8251.md
new file mode 100644
index 0000000..cb16306
--- /dev/null
+++ b/documents/markdown/pandoc-md/8251.md
@@ -0,0 +1,13 @@
+```
+% pandoc -f native -t html
+Link ("",["", "", ""],[]) [Str "foo"] ("https://example.com","")
+^D
+<a href="https://example.com">foo</a>
+```
+
+```
+% pandoc -f native -t markdown
+Link ("",["", "", ""],[]) [Str "foo"] ("https://example.com","")
+^D
+[foo](https://example.com){}
+```
diff --git a/documents/markdown/pandoc-md/8254.md b/documents/markdown/pandoc-md/8254.md
new file mode 100644
index 0000000..f2ed6db
--- /dev/null
+++ b/documents/markdown/pandoc-md/8254.md
@@ -0,0 +1,20 @@
+```
+% pandoc -t native
+Wow![@legras_michel_2010]
+^D
+[ Para
+ [ Str "Wow!"
+ , Cite
+ [ Citation
+ { citationId = "legras_michel_2010"
+ , citationPrefix = []
+ , citationSuffix = []
+ , citationMode = NormalCitation
+ , citationNoteNum = 2
+ , citationHash = 0
+ }
+ ]
+ [ Str "[@legras_michel_2010]" ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/8256.md b/documents/markdown/pandoc-md/8256.md
new file mode 100644
index 0000000..76398f6
--- /dev/null
+++ b/documents/markdown/pandoc-md/8256.md
@@ -0,0 +1,34 @@
+```
+% pandoc -t opendocument -s
+
+---
+title: |
+ This *is* \
+ a test
+author: Someone
+---
+
+Testing.
+^D
+<?xml version="1.0" encoding="utf-8" ?>
+<office:document-content xmlns:office="urn:oasis:names:tc:opendocument:xmlns:office:1.0" xmlns:style="urn:oasis:names:tc:opendocument:xmlns:style:1.0" xmlns:text="urn:oasis:names:tc:opendocument:xmlns:text:1.0" xmlns:table="urn:oasis:names:tc:opendocument:xmlns:table:1.0" xmlns:draw="urn:oasis:names:tc:opendocument:xmlns:drawing:1.0" xmlns:fo="urn:oasis:names:tc:opendocument:xmlns:xsl-fo-compatible:1.0" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:meta="urn:oasis:names:tc:opendocument:xmlns:meta:1.0" xmlns:number="urn:oasis:names:tc:opendocument:xmlns:datastyle:1.0" xmlns:svg="urn:oasis:names:tc:opendocument:xmlns:svg-compatible:1.0" xmlns:chart="urn:oasis:names:tc:opendocument:xmlns:chart:1.0" xmlns:dr3d="urn:oasis:names:tc:opendocument:xmlns:dr3d:1.0" xmlns:math="http://www.w3.org/1998/Math/MathML" xmlns:form="urn:oasis:names:tc:opendocument:xmlns:form:1.0" xmlns:script="urn:oasis:names:tc:opendocument:xmlns:script:1.0" xmlns:ooo="http://openoffice.org/2004/office" xmlns:ooow="http://openoffice.org/2004/writer" xmlns:oooc="http://openoffice.org/2004/calc" xmlns:dom="http://www.w3.org/2001/xml-events" xmlns:xforms="http://www.w3.org/2002/xforms" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" office:version="1.3">
+ <office:font-face-decls>
+ <style:font-face style:name="Courier New" style:font-family-generic="modern" style:font-pitch="fixed" svg:font-family="'Courier New'" />
+ </office:font-face-decls>
+ <office:automatic-styles>
+ <style:style style:name="T1" style:family="text"><style:text-properties fo:font-style="italic" style:font-style-asian="italic" style:font-style-complex="italic" /></style:style>
+ <style:style style:name="fr2" style:family="graphic" style:parent-style-name="Formula"><style:graphic-properties style:vertical-pos="middle" style:vertical-rel="text" style:horizontal-pos="center" style:horizontal-rel="paragraph-content" style:wrap="none" /></style:style>
+ <style:style style:name="fr1" style:family="graphic" style:parent-style-name="Formula"><style:graphic-properties style:vertical-pos="middle" style:vertical-rel="text" /></style:style>
+ </office:automatic-styles>
+<office:body>
+<office:text>
+<text:p text:style-name="Title">This
+<text:span text:style-name="T1">is</text:span><text:line-break />a
+test</text:p>
+<text:p text:style-name="Author">Someone</text:p>
+<text:p text:style-name="Text_20_body">Testing.</text:p>
+</office:text>
+</office:body>
+</office:document-content>
+```
+
diff --git a/documents/markdown/pandoc-md/8257.md b/documents/markdown/pandoc-md/8257.md
new file mode 100644
index 0000000..d1f3b44
--- /dev/null
+++ b/documents/markdown/pandoc-md/8257.md
@@ -0,0 +1,41 @@
+```
+% pandoc -f markdown -t html5
++------+-------+
+| Item | Price |
++======+=======+
+| Eggs | 5£ |
++------+-------+
+| Spam | 3£ |
++======+=======+
+| Sum | 8£ |
++======+=======+
+^D
+<table style="width:21%;">
+<colgroup>
+<col style="width: 9%" />
+<col style="width: 11%" />
+</colgroup>
+<thead>
+<tr>
+<th>Item</th>
+<th>Price</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Eggs</td>
+<td>5£</td>
+</tr>
+<tr>
+<td>Spam</td>
+<td>3£</td>
+</tr>
+</tbody><tfoot>
+<tr>
+<td>Sum</td>
+<td>8£</td>
+</tr>
+</tfoot>
+
+</table>
+```
diff --git a/documents/markdown/pandoc-md/8281.md b/documents/markdown/pandoc-md/8281.md
new file mode 100644
index 0000000..200e74f
--- /dev/null
+++ b/documents/markdown/pandoc-md/8281.md
@@ -0,0 +1,15 @@
+```
+% pandoc -t html
+# Title
+
+test
+
+. . .
+
+test
+^D
+<h1 id="title">Title</h1>
+<p>test</p>
+<p>. . .</p>
+<p>test</p>
+```
diff --git a/documents/markdown/pandoc-md/8302.md b/documents/markdown/pandoc-md/8302.md
new file mode 100644
index 0000000..7495300
--- /dev/null
+++ b/documents/markdown/pandoc-md/8302.md
@@ -0,0 +1,6 @@
+```
+% pandoc -f org -t markdown
+some text cite:&long-2004-tecton-evolut
+^D
+some text @long-2004-tecton-evolut
+```
diff --git a/documents/markdown/pandoc-md/8307.md b/documents/markdown/pandoc-md/8307.md
new file mode 100644
index 0000000..8474051
--- /dev/null
+++ b/documents/markdown/pandoc-md/8307.md
@@ -0,0 +1,49 @@
+```
+% pandoc -t commonmark -f html
+<table>
+<tbody>
+<tr>
+<td title="this
+
+
+breaks">hello</td>
+</tr>
+</tbody>
+</table>
+^D
+<table>
+<tbody>
+<tr>
+<td title="this
+
+breaks">hello</td>
+</tr>
+</tbody>
+</table>
+```
+
+````
+% pandoc -t commonmark -f markdown
+``` {=html}
+<table>
+<tbody>
+<tr>
+<td title="this
+
+
+breaks">hello</td>
+</tr>
+</tbody>
+</table>
+```
+^D
+<table>
+<tbody>
+<tr>
+<td title="this
+
+breaks">hello</td>
+</tr>
+</tbody>
+</table>
+````
diff --git a/documents/markdown/pandoc-md/8344.md b/documents/markdown/pandoc-md/8344.md
new file mode 100644
index 0000000..c95c75a
--- /dev/null
+++ b/documents/markdown/pandoc-md/8344.md
@@ -0,0 +1,90 @@
+```
+% pandoc -t jats -s
+---
+title: |-
+ My\
+ document
+...
+
+# Section\
+with line break
+
+Paragraph\
+with line break
+
+--------
+A B
+--- ---
+1\ 3
+2 4
+
+*1\ 5\
+2* 6
+
+ 7
+--------
+
+^D
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE article PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Archiving and Interchange DTD v1.2 20190208//EN"
+ "JATS-archivearticle1.dtd">
+<article xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:xlink="http://www.w3.org/1999/xlink" dtd-version="1.2" article-type="other">
+<front>
+<journal-meta>
+<journal-id></journal-id>
+<journal-title-group>
+</journal-title-group>
+<issn></issn>
+<publisher>
+<publisher-name></publisher-name>
+</publisher>
+</journal-meta>
+<article-meta>
+<title-group>
+<article-title>My<break/>document</article-title>
+</title-group>
+<permissions>
+</permissions>
+</article-meta>
+</front>
+<body>
+<sec id="section">
+ <title>Section<break/></title>
+ <p>with line break</p>
+ <p>Paragraph
+ with line break</p>
+ <table-wrap>
+ <table>
+ <colgroup>
+ <col width="7%" />
+ <col width="7%" />
+ </colgroup>
+ <thead>
+ <tr>
+ <th align="left">A</th>
+ <th align="left">B</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td align="left">1<break/>2</td>
+ <td align="left">3 4</td>
+ </tr>
+ <tr>
+ <td align="left"><italic>1
+ 2</italic></td>
+ <td align="left">5<break/>6</td>
+ </tr>
+ <tr>
+ <td align="left"></td>
+ <td align="left">7</td>
+ </tr>
+ </tbody>
+ </table>
+ </table-wrap>
+</sec>
+</body>
+<back>
+</back>
+</article>
+```
diff --git a/documents/markdown/pandoc-md/8354.md b/documents/markdown/pandoc-md/8354.md
new file mode 100644
index 0000000..96e3d68
--- /dev/null
+++ b/documents/markdown/pandoc-md/8354.md
@@ -0,0 +1,38 @@
+```
+% pandoc -f markdown -t html --citeproc
+---
+title: test
+nocite: '[@*]'
+references:
+- author:
+ - family: Fekete
+ given: Jean-Daniel
+ - family: Freire
+ given: Juliana
+ DOI: 10.1109/MCG.2020.3006412
+ id: feketeExploringReproducibilityVisualization2020
+ ISSN: 1558-1756
+ issue: 5
+ issued: 2020-09
+ page: 108-119
+ source: IEEE Xplore
+ title: Exploring Reproducibility in Visualization
+ container-title: IEEE Computer Graphics and Applications
+ type: article-journal
+ volume: 40
+---
+
+## References
+^D
+<h2 class="unnumbered" id="references">References</h2>
+<div id="refs" class="references csl-bib-body hanging-indent"
+role="list">
+<div id="ref-feketeExploringReproducibilityVisualization2020"
+class="csl-entry" role="listitem">
+Fekete, Jean-Daniel, and Juliana Freire. 2020. <span>“Exploring
+Reproducibility in Visualization.”</span> <em>IEEE Computer Graphics and
+Applications</em> 40 (5): 108–19. <a
+href="https://doi.org/10.1109/MCG.2020.3006412">https://doi.org/10.1109/MCG.2020.3006412</a>.
+</div>
+</div>
+```
diff --git a/documents/markdown/pandoc-md/8364.md b/documents/markdown/pandoc-md/8364.md
new file mode 100644
index 0000000..95eaf29
--- /dev/null
+++ b/documents/markdown/pandoc-md/8364.md
@@ -0,0 +1,54 @@
+```
+% pandoc --citeproc -t jats -s
+---
+reference-section-title: Bibliography
+csl: command/apa.csl
+references:
+- author:
+ - family: Doe
+ given: John
+ id: test
+ issued:
+ date-parts:
+ - - 2006
+ title: Test
+ type: 'article-journal'
+ volume: 81
+---
+
+@test
+^D
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE article PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Archiving and Interchange DTD v1.2 20190208//EN"
+ "JATS-archivearticle1.dtd">
+<article xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:xlink="http://www.w3.org/1999/xlink" dtd-version="1.2" article-type="other">
+<front>
+<journal-meta>
+<journal-id></journal-id>
+<journal-title-group>
+</journal-title-group>
+<issn></issn>
+<publisher>
+<publisher-name></publisher-name>
+</publisher>
+</journal-meta>
+<article-meta>
+<permissions>
+</permissions>
+</article-meta>
+</front>
+<body>
+<p>Doe (2006)</p>
+</body>
+<back>
+<ref-list>
+ <title>Bibliography</title>
+ <ref id="ref-test">
+ <mixed-citation>Doe, J. (2006). Test,
+ <italic>81</italic>.</mixed-citation>
+ </ref>
+</ref-list>
+</back>
+</article>
+
+```
diff --git a/documents/markdown/pandoc-md/8365.md b/documents/markdown/pandoc-md/8365.md
new file mode 100644
index 0000000..0c30ba9
--- /dev/null
+++ b/documents/markdown/pandoc-md/8365.md
@@ -0,0 +1,50 @@
+```
+% pandoc -f jats -t native -s
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE article PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Archiving and Interchange DTD v1.2 20190208//EN"
+ "JATS-archivearticle1.dtd">
+<article xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:xlink="http://www.w3.org/1999/xlink" dtd-version="1.2" article-type="other">
+<front>
+<journal-meta>
+<journal-id></journal-id>
+<journal-title-group>
+</journal-title-group>
+<issn></issn>
+<publisher>
+<publisher-name></publisher-name>
+</publisher>
+</journal-meta>
+<article-meta>
+<permissions>
+</permissions>
+</article-meta>
+</front>
+<body>
+<p>Doe (2006)</p>
+</body>
+<back>
+<ref-list>
+ <title>Bibliography</title>
+ <ref id="ref-test">
+ <mixed-citation>Doe, J. (2006). Test,
+ <italic>81</italic>.</mixed-citation>
+ </ref>
+</ref-list>
+</back>
+</article>
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "references"
+ , MetaList
+ [ MetaMap (fromList [ ( "id" , MetaString "test" ) ]) ]
+ )
+ ]
+ }
+ [ Para [ Str "Doe" , Space , Str "(2006)" ]
+ , Header 1 ( "" , [] , [] ) [ Str "Bibliography" ]
+ , Div ( "refs" , [] , [] ) []
+ ]
+```
diff --git a/documents/markdown/pandoc-md/8380.md b/documents/markdown/pandoc-md/8380.md
new file mode 100644
index 0000000..116922c
--- /dev/null
+++ b/documents/markdown/pandoc-md/8380.md
@@ -0,0 +1,31 @@
+```
+% pandoc -f man -t rst
+LC_*
+^D
+LC\_\*
+```
+
+These examples of things that don't require escaping are taken
+from the RST documentation:
+
+```
+% pandoc -f native -t rst
+[Para [Str "2*x a**b O(N**2) e**(x*y) f(x)*f(y) a|b"]
+,Para [Str "a**b O(N**2) e**(x*y) f(x)*f(y)"]
+]
+^D
+2*x a**b O(N**2) e**(x*y) f(x)*f(y) a|b
+
+a**b O(N**2) e**(x*y) f(x)*f(y)
+```
+
+These examples of things that do require escaping are taken
+from the RST documentation:
+
+```
+% pandoc -f native -t rst
+Str "*4, class_, *args, **kwargs, `TeX-quoted', *ML, *.txt"
+^D
+\*4, class\_, \*args, \**kwargs, \`TeX-quoted', \*ML, \*.txt
+```
+
diff --git a/documents/markdown/pandoc-md/8402.md b/documents/markdown/pandoc-md/8402.md
new file mode 100644
index 0000000..aa5fd88
--- /dev/null
+++ b/documents/markdown/pandoc-md/8402.md
@@ -0,0 +1,52 @@
+```
+% pandoc --toc -s -t markdown
+::: {.cell .markdown id="6u8qXoeFGdqt"}
+# Summary
+> Expand to see summary
+
+## Overview and Explanation
+:::
+
+# Details
+
+## inner 1
+text
+
+## inner 2
+
+### inner inner 1
+
+## inner 3
+text
+^D
+- [Summary](#summary){#toc-summary}
+ - [Overview and
+ Explanation](#overview-and-explanation){#toc-overview-and-explanation}
+- [Details](#details){#toc-details}
+ - [inner 1](#inner-1){#toc-inner-1}
+ - [inner 2](#inner-2){#toc-inner-2}
+ - [inner inner 1](#inner-inner-1){#toc-inner-inner-1}
+ - [inner 3](#inner-3){#toc-inner-3}
+
+::: {#6u8qXoeFGdqt .cell .markdown}
+# Summary
+
+> Expand to see summary
+
+## Overview and Explanation
+:::
+
+# Details
+
+## inner 1
+
+text
+
+## inner 2
+
+### inner inner 1
+
+## inner 3
+
+text
+```
diff --git a/documents/markdown/pandoc-md/8437.md b/documents/markdown/pandoc-md/8437.md
new file mode 100644
index 0000000..ab41695
--- /dev/null
+++ b/documents/markdown/pandoc-md/8437.md
@@ -0,0 +1,44 @@
+```
+% pandoc -f markdown -t asciidoc
+[](http://www.apache.org/licenses/LICENSE-2.0)
+^D
+http://www.apache.org/licenses/LICENSE-2.0[image:https://img.shields.io/badge/License-Apache%202.0-blue.svg[alt,title="title"]]
+```
+
+```
+% pandoc -f markdown -t docbook
+[](http://www.apache.org/licenses/LICENSE-2.0)
+^D
+<para>
+ <link xlink:href="http://www.apache.org/licenses/LICENSE-2.0"><inlinemediaobject>
+ <imageobject>
+ <objectinfo>
+ <title>title</title>
+ </objectinfo>
+ <imagedata fileref="https://img.shields.io/badge/License-Apache%202.0-blue.svg" />
+ </imageobject>
+ <textobject>
+ <phrase>alt</phrase>
+ </textobject>
+ </inlinemediaobject></link>
+</para>
+```
+
+```
+% pandoc -f docbook -t markdown
+<para>
+ <link xlink:href="http://www.apache.org/licenses/LICENSE-2.0"><inlinemediaobject>
+ <imageobject>
+ <objectinfo>
+ <title>title</title>
+ </objectinfo>
+ <imagedata fileref="https://img.shields.io/badge/License-Apache%202.0-blue.svg" />
+ </imageobject>
+ <textobject>
+ <phrase>alt</phrase>
+ </textobject>
+ </inlinemediaobject></link>
+</para>
+^D
+[](http://www.apache.org/licenses/LICENSE-2.0)
+```
diff --git a/documents/markdown/pandoc-md/8486.md b/documents/markdown/pandoc-md/8486.md
new file mode 100644
index 0000000..4e0950e
--- /dev/null
+++ b/documents/markdown/pandoc-md/8486.md
@@ -0,0 +1,55 @@
+# Unnumbered and unlisted headings in ConTeXt
+
+```
+% pandoc --to=context
+# Preface {.unlisted -}
+
+Nullam rutrum.
+
+# Introduction
+
+Nullam eu ante vel est convallis dignissim.
+
+# Methods
+
+Sed diam. Nulla posuere. Praesent fermentum tempor tellus. Nam
+vestibulum accumsan nisl. Nam vestibulum accumsan nisl.
+
+# References {-}
+^D
+\startsubject[title={Preface},reference={preface},number=no,incrementnumber=no]
+
+Nullam rutrum.
+
+\stopsubject
+
+\startsectionlevel[title={Introduction},reference={introduction}]
+
+Nullam eu ante vel est convallis dignissim.
+
+\stopsectionlevel
+
+\startsectionlevel[title={Methods},reference={methods}]
+
+Sed diam. Nulla posuere. Praesent fermentum tempor tellus. Nam
+vestibulum accumsan nisl. Nam vestibulum accumsan nisl.
+
+\stopsectionlevel
+
+\startsectionlevel[title={References},reference={references},number=no,incrementnumber=no]
+
+\stopsectionlevel
+```
+
+## Semantic Headings with `--top-level-division`
+```
+% pandoc --to=context --top-level-division=chapter
+# Bibliography {-}
+None
+^D
+\startchapter[title={Bibliography},reference={bibliography},number=no,incrementnumber=no]
+
+None
+
+\stopchapter
+```
diff --git a/documents/markdown/pandoc-md/8487.md b/documents/markdown/pandoc-md/8487.md
new file mode 100644
index 0000000..7cd3e48
--- /dev/null
+++ b/documents/markdown/pandoc-md/8487.md
@@ -0,0 +1,14 @@
+```
+% pandoc -f textile -t native
+p>.
+
+p=. Links:
+^D
+[ Div
+ ( "" , [] , [ ( "style" , "text-align:right;" ) ] )
+ [ Para [] ]
+, Div
+ ( "" , [] , [ ( "style" , "text-align:center;" ) ] )
+ [ Para [ Str "Links:" ] ]
+]
+```
diff --git a/documents/markdown/pandoc-md/8504.md b/documents/markdown/pandoc-md/8504.md
new file mode 100644
index 0000000..582304f
--- /dev/null
+++ b/documents/markdown/pandoc-md/8504.md
@@ -0,0 +1,90 @@
+```
+% pandoc -f markdown -s -t biblatex
+---
+references:
+- id: Larsson_2016
+ author:
+ - family: Larsson
+ given: Johan
+ citation-key: Larsson_2016
+ issued:
+ - year: 2016
+ medium: Windows
+ title: 'qualpalr: Automatic Generation of Qualitative Color Palettes'
+ type: software
+ URL: https://cran.r-project.org/package=qualpalr
+ version: 0.3.1
+...
+^D
+@software{Larsson_2016,
+ author = {Larsson, Johan},
+ title = {Qualpalr: {Automatic} {Generation} of {Qualitative} {Color}
+ {Palettes}},
+ version = {0.3.1},
+ date = {2016},
+ url = {https://cran.r-project.org/package=qualpalr}
+}
+```
+
+```
+% pandoc -f markdown -s -t bibtex
+---
+references:
+- id: Larsson_2016
+ author:
+ - family: Larsson
+ given: Johan
+ citation-key: Larsson_2016
+ issued:
+ - year: 2016
+ medium: Windows
+ title: 'qualpalr: Automatic Generation of Qualitative Color Palettes'
+ type: software
+ URL: https://cran.r-project.org/package=qualpalr
+ version: 0.3.1
+...
+^D
+@misc{Larsson_2016,
+ author = {Larsson, Johan},
+ title = {Qualpalr: {Automatic} {Generation} of {Qualitative} {Color}
+ {Palettes}},
+ year = {2016},
+ url = {https://cran.r-project.org/package=qualpalr}
+}
+```
+
+```
+% pandoc -f biblatex -s -t csljson
+@software{Larsson_2016,
+ author = {Larsson, Johan},
+ title = {Qualpalr: {Automatic} {Generation} of {Qualitative} {Color}
+ {Palettes}},
+ version = {0.3.1},
+ date = {2016},
+ url = {https://cran.r-project.org/package=qualpalr}
+}
+^D
+[
+ {
+ "URL": "https://cran.r-project.org/package=qualpalr",
+ "author": [
+ {
+ "family": "Larsson",
+ "given": "Johan"
+ }
+ ],
+ "id": "Larsson_2016",
+ "issued": {
+ "date-parts": [
+ [
+ 2016
+ ]
+ ]
+ },
+ "title": "Qualpalr: Automatic Generation of Qualitative Color Palettes",
+ "title-short": "Qualpalr",
+ "type": "software",
+ "version": "0.3.1"
+ }
+]
+```
diff --git a/documents/markdown/pandoc-md/8508.md b/documents/markdown/pandoc-md/8508.md
new file mode 100644
index 0000000..d7a0f03
--- /dev/null
+++ b/documents/markdown/pandoc-md/8508.md
@@ -0,0 +1,20 @@
+```
+% pandoc -t man
+SEE ALSO
+========
+
+* [Milk](https://en.wikipedia.org/wiki/Milk)
+* [EBNF](https://en.wikipedia.org/wiki/Extended_Backus–Naur_form)
+^D
+.SH SEE ALSO
+.IP \(bu 2
+\c
+.UR https://en.wikipedia.org/wiki/Milk
+Milk
+.UE \c
+.IP \(bu 2
+\c
+.UR https://en.wikipedia.org/wiki/Extended_Backus–Naur_form
+EBNF
+.UE \c
+```
diff --git a/documents/markdown/pandoc-md/8511.md b/documents/markdown/pandoc-md/8511.md
new file mode 100644
index 0000000..b4f6e6e
--- /dev/null
+++ b/documents/markdown/pandoc-md/8511.md
@@ -0,0 +1,16 @@
+# Conversion of icon-like sequences followed by alphanum char
+## to Jira
+```
+% pandoc -t jira
+:P :P_ :PA :Pa :P2
+^D
+\:P \:P\_ :PA :Pa :P2
+```
+
+## from jira
+```
+% pandoc -f jira -t markdown
+\:PA
+^D
+\\:PA
+```
diff --git a/documents/markdown/pandoc-md/8513.md b/documents/markdown/pandoc-md/8513.md
new file mode 100644
index 0000000..e1ed2c3
--- /dev/null
+++ b/documents/markdown/pandoc-md/8513.md
@@ -0,0 +1,27 @@
+# Round-tripping tags in org
+```
+% pandoc --from org --to org --columns=72
+* Header with tag :tag:
+^D
+* Header with tag :tag:
+:PROPERTIES:
+:CUSTOM_ID: header-with-tag
+:END:
+```
+
+Multiple tags
+```
+% pandoc --from org-auto_identifiers --to org --columns=78
+* Header with two tags :first:second:
+^D
+* Header with two tags :first:second:
+```
+
+Check that long headings work with tags
+
+```
+% pandoc --from org-auto_identifiers --to org --columns=40
+* Header with tag and more words which are not that interesting :tag:
+^D
+* Header with tag and more words which are not that interesting :tag:
+```
diff --git a/documents/markdown/pandoc-md/853.md b/documents/markdown/pandoc-md/853.md
new file mode 100644
index 0000000..518c659
--- /dev/null
+++ b/documents/markdown/pandoc-md/853.md
@@ -0,0 +1,21 @@
+reStructuredText citations.
+
+```
+% pandoc -f rst
+Here is a citation reference: [CIT2002]_.
+
+.. [CIT2002] This is the citation. It's just like a footnote,
+ except the label is textual.
+^D
+<p>Here is a citation reference: <a href="#CIT2002"
+class="citation">[CIT2002]</a>.</p>
+<div id="citations">
+<dl>
+<dt><span id="CIT2002" class="citation-label">CIT2002</span></dt>
+<dd>
+<p>This is the citation. It's just like a footnote, except the label is
+textual.</p>
+</dd>
+</dl>
+</div>
+```
diff --git a/documents/markdown/pandoc-md/8534.md b/documents/markdown/pandoc-md/8534.md
new file mode 100644
index 0000000..caddac3
--- /dev/null
+++ b/documents/markdown/pandoc-md/8534.md
@@ -0,0 +1,11 @@
+```
+% pandoc -f html -t texinfo
+<html>
+foo <code>bar <var>baz</var> bar</code> foo
+</html>
+^D
+@node Top
+@top Top
+
+foo @code{bar }@code{@var{baz}}@code{ bar} foo
+```
diff --git a/documents/markdown/pandoc-md/8573.md b/documents/markdown/pandoc-md/8573.md
new file mode 100644
index 0000000..15eac9e
--- /dev/null
+++ b/documents/markdown/pandoc-md/8573.md
@@ -0,0 +1,7 @@
+```
+% pandoc -f latex -t plain
+\newenvironment{myenv}[1]{Open#1}{Close}
+\begin{myenv}{x}Hello\end{myenv}
+^D
+OpenxHelloClose
+```
diff --git a/documents/markdown/pandoc-md/8611.md b/documents/markdown/pandoc-md/8611.md
new file mode 100644
index 0000000..3c303b4
--- /dev/null
+++ b/documents/markdown/pandoc-md/8611.md
@@ -0,0 +1,34 @@
+```
+% pandoc -f markdown -s -t bibtex
+---
+nocite: "[@*]"
+references:
+- id: mcdowell:why
+ title: |
+ Why is Sellars's Essay Called "Empiricism and the Philosophy of Mind"?
+ author:
+ - family: McDowell
+ given: John
+ journal: Proceedings of the Aristotelian Society
+ type: chapter
+ container-title: 'Empiricism, Perceptual Knowledge, Normativity, and Realism: Essays on Wilfrid Sellars'
+ editor:
+ - family: deVries
+ given: Willem A.
+ issued: 2009
+ publisher: Oxford University Press
+ publisher-place: Oxford
+...
+^D
+@incollection{mcdowell:why,
+ author = {McDowell, John},
+ editor = {deVries, Willem A.},
+ publisher = {Oxford University Press},
+ title = {Why Is {Sellars’s} {Essay} {Called} “{Empiricism} and the
+ {Philosophy} of {Mind}”?},
+ booktitle = {Empiricism, Perceptual Knowledge, Normativity, and
+ Realism: Essays on Wilfrid Sellars},
+ year = {2009},
+ address = {Oxford}
+}
+```
diff --git a/documents/markdown/pandoc-md/8638.md b/documents/markdown/pandoc-md/8638.md
new file mode 100644
index 0000000..75c8247
--- /dev/null
+++ b/documents/markdown/pandoc-md/8638.md
@@ -0,0 +1,22 @@
+# Beamer tables must not use longtable footer
+```
+% pandoc -t beamer
+| fruit | price |
+|---------|------:|
+| apple | 2.05 |
+| oranges | 4.25 |
+^D
+\begin{frame}
+{\def\LTcaptype{none} % do not increment counter
+\begin{longtable}[]{@{}lr@{}}
+\toprule\noalign{}
+fruit & price \\
+\midrule\noalign{}
+\endhead
+apple & 2.05 \\
+oranges & 4.25 \\
+\bottomrule\noalign{}
+\end{longtable}
+}
+\end{frame}
+```
diff --git a/documents/markdown/pandoc-md/8652.md b/documents/markdown/pandoc-md/8652.md
new file mode 100644
index 0000000..e98f1cd
--- /dev/null
+++ b/documents/markdown/pandoc-md/8652.md
@@ -0,0 +1,28 @@
+```
+% pandoc -t native
+My text^[My note]isnot^[Text]
+^D
+[ Para
+ [ Str "My"
+ , Space
+ , Str "text"
+ , Note [ Para [ Str "My" , Space , Str "note" ] ]
+ , Str "isnot"
+ , Note [ Para [ Str "Text" ] ]
+ ]
+]
+
+```
+
+```
+% pandoc -t native
+^[note1]test^[note2]
+^D
+[ Para
+ [ Note [ Para [ Str "note1" ] ]
+ , Str "test"
+ , Note [ Para [ Str "note2" ] ]
+ ]
+]
+
+```
diff --git a/documents/markdown/pandoc-md/8653.md b/documents/markdown/pandoc-md/8653.md
new file mode 100644
index 0000000..e1dbefb
--- /dev/null
+++ b/documents/markdown/pandoc-md/8653.md
@@ -0,0 +1,23 @@
+```
+% pandoc -f rst -t native
+.. role:: py:class(emphasis)
+
+:py:class:`foo`
+^D
+[ Para [ Emph [ Str "foo" ] ] ]
+```
+
+```
+% pandoc -f rst -t native
+:py:class:`foo`
+^D
+[ Para
+ [ Code
+ ( ""
+ , [ "interpreted-text" ]
+ , [ ( "role" , "py:class" ) ]
+ )
+ "foo"
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/8659.md b/documents/markdown/pandoc-md/8659.md
new file mode 100644
index 0000000..5bbb6f1
--- /dev/null
+++ b/documents/markdown/pandoc-md/8659.md
@@ -0,0 +1,54 @@
+# A single pipe is parsed as an empty table
+```
+% pandoc -f org -t html
+|
+^D
+<table>
+<tbody>
+<tr>
+</tr>
+</tbody>
+</table>
+```
+# Accepts an empty org table within a grid table cell
+
+The misaligned pipe in the first row is treated as an empty table.
+
+```
+% pandoc -f org -t html
++-----+-----+-----+-----------+
+| | | | |
++:====+=====+====:+==========:+
+| a | b | c | d |
++-----+-----+-----+-----------+
+^D
+<table style="width:42%;">
+<colgroup>
+<col style="width: 8%" />
+<col style="width: 8%" />
+<col style="width: 8%" />
+<col style="width: 16%" />
+</colgroup>
+<thead>
+<tr>
+<th style="text-align: left;"></th>
+<th></th>
+<th style="text-align: right;"></th>
+<th style="text-align: right;"><table>
+<tbody>
+<tr>
+</tr>
+</tbody>
+</table></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td style="text-align: left;">a</td>
+<td>b</td>
+<td style="text-align: right;">c</td>
+<td style="text-align: right;">d</td>
+</tr>
+</tbody>
+</table>
+```
diff --git a/documents/markdown/pandoc-md/8661.md b/documents/markdown/pandoc-md/8661.md
new file mode 100644
index 0000000..609739c
--- /dev/null
+++ b/documents/markdown/pandoc-md/8661.md
@@ -0,0 +1,9 @@
+```
+% pandoc -f tsv -t gfm
+a b c
+ 6
+^D
+| a | b | c |
+|-----|-----|-----|
+| | | 6 |
+```
diff --git a/documents/markdown/pandoc-md/8665.md b/documents/markdown/pandoc-md/8665.md
new file mode 100644
index 0000000..f0e8a6f
--- /dev/null
+++ b/documents/markdown/pandoc-md/8665.md
@@ -0,0 +1,29 @@
+```
+% pandoc -f docbook -t asciidoc
+<informaltable frame="all" rowsep="1" colsep="1">
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry align="left" valign="top">h1</entry>
+ <entry align="left" valign="top">h2</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry align="left" valign="top">
+ <simpara>!@#$%^&*(){}|~?+-',."<>[]\`</simpara>
+ </entry>
+ <entry align="left" valign="top">
+ <simpara>col 2</simpara>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+^D
+[cols=",",options="header",]
+|===
+<|h1 <|h2
+<|!@++#++$%^&++*++()++{++}{vbar}~?{plus}-',."++<>[]\`++ <|col 2
+|===
+```
diff --git a/documents/markdown/pandoc-md/8666.md b/documents/markdown/pandoc-md/8666.md
new file mode 100644
index 0000000..5e08c5b
--- /dev/null
+++ b/documents/markdown/pandoc-md/8666.md
@@ -0,0 +1,40 @@
+```
+% pandoc -f docbook -t native
+<formalpara xml:id="my_code_id">
+<title>Code title</title>
+<para>
+<programlisting language="bash" linenumbering="unnumbered">echo "hello world!"</programlisting>
+</para>
+</formalpara>
+<example xml:id="my_example_id">
+<title>Example title</title>
+<simpara>example content</simpara>
+</example>
+<sidebar xml:id="my_sidebar_id">
+<title>Sidebar title</title>
+<simpara>sidebar content</simpara>
+</sidebar>
+^D
+[ Div
+ ( "my_code_id" , [ "formalpara" ] , [] )
+ [ Div
+ ( "" , [ "title" ] , [] )
+ [ Plain [ Str "Code" , Space , Str "title" ] ]
+ , CodeBlock ( "" , [ "bash" ] , [] ) "echo \"hello world!\""
+ ]
+, Div
+ ( "my_example_id" , [ "example" ] , [] )
+ [ Div
+ ( "" , [ "title" ] , [] )
+ [ Plain [ Str "Example" , Space , Str "title" ] ]
+ , Para [ Str "example" , Space , Str "content" ]
+ ]
+, Div
+ ( "my_sidebar_id" , [ "sidebar" ] , [] )
+ [ Div
+ ( "" , [ "title" ] , [] )
+ [ Plain [ Str "Sidebar" , Space , Str "title" ] ]
+ , Para [ Str "sidebar" , Space , Str "content" ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/8681.md b/documents/markdown/pandoc-md/8681.md
new file mode 100644
index 0000000..eb9a812
--- /dev/null
+++ b/documents/markdown/pandoc-md/8681.md
@@ -0,0 +1,14 @@
+# Include Jira panel title in resulting div
+```
+% pandoc -f jira -t html
+{panel:title=This is the title|titleBGColor=#cccccc|bgColor=#eeeeee}
+Panel content
+{panel}
+^D
+<div class="panel" data-titleBGColor="#cccccc" data-bgColor="#eeeeee">
+<div class="panelheader">
+<strong>This is the title</strong>
+</div>
+<p>Panel content</p>
+</div>
+```
diff --git a/documents/markdown/pandoc-md/8689.md b/documents/markdown/pandoc-md/8689.md
new file mode 100644
index 0000000..22bd8d8
--- /dev/null
+++ b/documents/markdown/pandoc-md/8689.md
@@ -0,0 +1,12 @@
+# Org figures should be rendered implicit figures
+
+```
+% pandoc -f org -t markdown+implicit_figures
+#+label: fig:bsdd-graphql-voyager-orig-detail
+#+caption: Original bSDD GraphQL Schema: Detail of Classification and ClassificationProperty
+[[./Classification-ClassificationProperty.png]]
+^D
+{#fig:bsdd-graphql-voyager-orig-detail}
+
+```
diff --git a/documents/markdown/pandoc-md/8711.md b/documents/markdown/pandoc-md/8711.md
new file mode 100644
index 0000000..1685e28
--- /dev/null
+++ b/documents/markdown/pandoc-md/8711.md
@@ -0,0 +1,118 @@
+```
+% pandoc -f html-native_spans -t native
+<table>
+<tr>
+<td>
+ <p><span class="foo">a</span> <span class="bar">b</span></p>
+</td>
+</tr>
+</table>
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault ) ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "a" , Space , Str "b" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+
+```
+
+```
+% pandoc -f html-native_spans+raw_html -t native
+<table>
+<tr>
+<td>
+ <p><span class="foo">a</span> <span class="bar">b</span></p>
+</td>
+</tr>
+</table>
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault ) ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para
+ [ RawInline (Format "html") "<span class=\"foo\">"
+ , Str "a"
+ , RawInline (Format "html") "</span>"
+ , Space
+ , RawInline (Format "html") "<span class=\"bar\">"
+ , Str "b"
+ , RawInline (Format "html") "</span>"
+ ]
+ ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+
+```
+
+```
+% pandoc -f html -t native
+<table>
+<tr>
+<td>
+ <p><span class="foo">a</span> <span class="bar">b</span></p>
+</td>
+</tr>
+</table>
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault ) ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para
+ [ Span ( "" , [ "foo" ] , [] ) [ Str "a" ]
+ , Space
+ , Span ( "" , [ "bar" ] , [] ) [ Str "b" ]
+ ]
+ ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+
+```
diff --git a/documents/markdown/pandoc-md/8738.md b/documents/markdown/pandoc-md/8738.md
new file mode 100644
index 0000000..ae128b8
--- /dev/null
+++ b/documents/markdown/pandoc-md/8738.md
@@ -0,0 +1,6 @@
+```
+% pandoc -f native -t mediawiki
+[Link ("",[],[]) [Link ("",[],[]) [Str "test"] ("https://bar.example.com",""),Str "Test"] ("https://foo.example.com","")]
+^D
+[https://foo.example.com <span>test</span>Test]
+```
diff --git a/documents/markdown/pandoc-md/8745.md b/documents/markdown/pandoc-md/8745.md
new file mode 100644
index 0000000..f422088
--- /dev/null
+++ b/documents/markdown/pandoc-md/8745.md
@@ -0,0 +1,52 @@
+# Alt text on images
+
+```
+% pandoc -f latex -t native
+\documentclass[12pt]{article}
+\usepackage{graphicx}
+\begin{document}
+Sample text
+\begin{figure}[ht]
+ \includegraphics[alt={Upside down painting},width=0.5\textwidth]{New_York_City_I.jpg}
+ \caption{New York City by Piet Mondrian (Wikipedia)}
+ \label{fig:Mondrian}
+\end{figure}
+\includegraphics[alt={Face of a mandrill}]{mandrill.jpg}
+\end{document}
+^D
+[ Para [ Str "Sample" , Space , Str "text" ]
+, Figure
+ ( "fig:Mondrian" , [] , [ ( "latex-placement" , "ht" ) ] )
+ (Caption
+ Nothing
+ [ Plain
+ [ Str "New"
+ , Space
+ , Str "York"
+ , Space
+ , Str "City"
+ , Space
+ , Str "by"
+ , Space
+ , Str "Piet"
+ , Space
+ , Str "Mondrian"
+ , Space
+ , Str "(Wikipedia)"
+ ]
+ ])
+ [ Para
+ [ Image
+ ( "" , [] , [ ( "width" , "50%" ) ] )
+ [ Str "Upside down painting" ]
+ ( "New_York_City_I.jpg" , "" )
+ ]
+ ]
+, Para
+ [ Image
+ ( "" , [] , [] )
+ [ Str "Face of a mandrill" ]
+ ( "mandrill.jpg" , "" )
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/8764.md b/documents/markdown/pandoc-md/8764.md
new file mode 100644
index 0000000..e5fe43d
--- /dev/null
+++ b/documents/markdown/pandoc-md/8764.md
@@ -0,0 +1,50 @@
+```
+% pandoc -f html -t opendocument
+<table>
+ <tbody>
+ <tr>
+ <th>Header</th>
+ <td>Normal cell (column 2)</td>
+ <td>Normal cell (column 3)</td>
+ </tr>
+ <tr>
+ <td>Normal cell (column 1)</td>
+ <td>Normal cell (column 2)</td>
+ <td>Normal cell (column 3)</td>
+ </tr>
+ </tbody>
+</table>
+^D
+<table:table table:name="Table1" table:style-name="Table1">
+ <table:table-column table:style-name="Table1.A" />
+ <table:table-column table:style-name="Table1.B" />
+ <table:table-column table:style-name="Table1.C" />
+ <table:table-row>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">Header</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">Normal cell (column
+ 2)</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">Normal cell (column
+ 3)</text:p>
+ </table:table-cell>
+ </table:table-row>
+ <table:table-row>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">Normal cell (column
+ 1)</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">Normal cell (column
+ 2)</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">Normal cell (column
+ 3)</text:p>
+ </table:table-cell>
+ </table:table-row>
+</table:table>
+```
diff --git a/documents/markdown/pandoc-md/8770-block.md b/documents/markdown/pandoc-md/8770-block.md
new file mode 100644
index 0000000..bdeede2
--- /dev/null
+++ b/documents/markdown/pandoc-md/8770-block.md
@@ -0,0 +1,75 @@
+```
+% pandoc -t html5 --reference-location=block
+# Section 1
+
+hello[^1]
+
+: Sample table.[^2]
+
+-----------
+ Fruit[^3]
+-----------
+ Bans[^4]
+-----------
+
+# Section 2
+
+dolly[^5]
+
+[^1]: doc footnote
+[^2]: caption footnote
+[^3]: header footnote
+[^4]: table cell footnote
+[^5]: doc footnote
+^D
+<h1 id="section-1">Section 1</h1>
+<p>hello<a href="#fn1" class="footnote-ref" id="fnref1"
+role="doc-noteref"><sup>1</sup></a></p>
+<aside id="footnotes" class="footnotes footnotes-end-of-block"
+role="doc-footnote">
+<ol>
+<li id="fn1"><p>doc footnote<a href="#fnref1" class="footnote-back"
+role="doc-backlink">↩︎</a></p></li>
+</ol>
+</aside>
+<table style="width:17%;">
+<caption>Sample table.<a href="#fn2" class="footnote-ref" id="fnref2"
+role="doc-noteref"><sup>2</sup></a></caption>
+<colgroup>
+<col style="width: 16%" />
+</colgroup>
+<thead>
+<tr>
+<th style="text-align: center;">Fruit<a href="#fn3" class="footnote-ref"
+id="fnref3" role="doc-noteref"><sup>3</sup></a></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td style="text-align: center;">Bans<a href="#fn4" class="footnote-ref"
+id="fnref4" role="doc-noteref"><sup>4</sup></a></td>
+</tr>
+</tbody>
+</table>
+<aside id="footnotes-2" class="footnotes footnotes-end-of-block"
+role="doc-footnote">
+<ol start="2">
+<li id="fn2"><p>caption footnote<a href="#fnref2" class="footnote-back"
+role="doc-backlink">↩︎</a></p></li>
+<li id="fn3"><p>header footnote<a href="#fnref3" class="footnote-back"
+role="doc-backlink">↩︎</a></p></li>
+<li id="fn4"><p>table cell footnote<a href="#fnref4"
+class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+</ol>
+</aside>
+<h1 id="section-2">Section 2</h1>
+<p>dolly<a href="#fn5" class="footnote-ref" id="fnref5"
+role="doc-noteref"><sup>5</sup></a></p>
+<aside id="footnotes-3" class="footnotes footnotes-end-of-block"
+role="doc-footnote">
+<ol start="5">
+<li id="fn5"><p>doc footnote<a href="#fnref5" class="footnote-back"
+role="doc-backlink">↩︎</a></p></li>
+</ol>
+</aside>
+```
diff --git a/documents/markdown/pandoc-md/8770-document.md b/documents/markdown/pandoc-md/8770-document.md
new file mode 100644
index 0000000..25443c7
--- /dev/null
+++ b/documents/markdown/pandoc-md/8770-document.md
@@ -0,0 +1,66 @@
+```
+% pandoc -t html5 --reference-location=document
+# Section 1
+
+hello[^1]
+
+: Sample table.[^2]
+
+-----------
+ Fruit[^3]
+-----------
+ Bans[^4]
+-----------
+
+# Section 2
+
+dolly[^5]
+
+[^1]: doc footnote
+[^2]: caption footnote
+[^3]: header footnote
+[^4]: table cell footnote
+[^5]: doc footnote
+^D
+<h1 id="section-1">Section 1</h1>
+<p>hello<a href="#fn1" class="footnote-ref" id="fnref1"
+role="doc-noteref"><sup>1</sup></a></p>
+<table style="width:17%;">
+<caption>Sample table.<a href="#fn2" class="footnote-ref" id="fnref2"
+role="doc-noteref"><sup>2</sup></a></caption>
+<colgroup>
+<col style="width: 16%" />
+</colgroup>
+<thead>
+<tr>
+<th style="text-align: center;">Fruit<a href="#fn3" class="footnote-ref"
+id="fnref3" role="doc-noteref"><sup>3</sup></a></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td style="text-align: center;">Bans<a href="#fn4" class="footnote-ref"
+id="fnref4" role="doc-noteref"><sup>4</sup></a></td>
+</tr>
+</tbody>
+</table>
+<h1 id="section-2">Section 2</h1>
+<p>dolly<a href="#fn5" class="footnote-ref" id="fnref5"
+role="doc-noteref"><sup>5</sup></a></p>
+<section id="footnotes" class="footnotes footnotes-end-of-document"
+role="doc-endnotes">
+<hr />
+<ol>
+<li id="fn1"><p>doc footnote<a href="#fnref1" class="footnote-back"
+role="doc-backlink">↩︎</a></p></li>
+<li id="fn2"><p>caption footnote<a href="#fnref2" class="footnote-back"
+role="doc-backlink">↩︎</a></p></li>
+<li id="fn3"><p>header footnote<a href="#fnref3" class="footnote-back"
+role="doc-backlink">↩︎</a></p></li>
+<li id="fn4"><p>table cell footnote<a href="#fnref4"
+class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+<li id="fn5"><p>doc footnote<a href="#fnref5" class="footnote-back"
+role="doc-backlink">↩︎</a></p></li>
+</ol>
+</section>
+```
diff --git a/documents/markdown/pandoc-md/8770-section.md b/documents/markdown/pandoc-md/8770-section.md
new file mode 100644
index 0000000..990e413
--- /dev/null
+++ b/documents/markdown/pandoc-md/8770-section.md
@@ -0,0 +1,72 @@
+```
+% pandoc -t html5 --reference-location=section
+# Section 1
+
+hello[^1]
+
+: Sample table.[^2]
+
+-----------
+ Fruit[^3]
+-----------
+ Bans[^4]
+-----------
+
+# Section 2
+
+dolly[^5]
+
+[^1]: doc footnote
+[^2]: caption footnote
+[^3]: header footnote
+[^4]: table cell footnote
+[^5]: doc footnote
+^D
+<h1 id="section-1">Section 1</h1>
+<p>hello<a href="#fn1" class="footnote-ref" id="fnref1"
+role="doc-noteref"><sup>1</sup></a></p>
+<table style="width:17%;">
+<caption>Sample table.<a href="#fn2" class="footnote-ref" id="fnref2"
+role="doc-noteref"><sup>2</sup></a></caption>
+<colgroup>
+<col style="width: 16%" />
+</colgroup>
+<thead>
+<tr>
+<th style="text-align: center;">Fruit<a href="#fn3" class="footnote-ref"
+id="fnref3" role="doc-noteref"><sup>3</sup></a></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td style="text-align: center;">Bans<a href="#fn4" class="footnote-ref"
+id="fnref4" role="doc-noteref"><sup>4</sup></a></td>
+</tr>
+</tbody>
+</table>
+<aside id="footnotes" class="footnotes footnotes-end-of-section"
+role="doc-footnote">
+<hr />
+<ol>
+<li id="fn1"><p>doc footnote<a href="#fnref1" class="footnote-back"
+role="doc-backlink">↩︎</a></p></li>
+<li id="fn2"><p>caption footnote<a href="#fnref2" class="footnote-back"
+role="doc-backlink">↩︎</a></p></li>
+<li id="fn3"><p>header footnote<a href="#fnref3" class="footnote-back"
+role="doc-backlink">↩︎</a></p></li>
+<li id="fn4"><p>table cell footnote<a href="#fnref4"
+class="footnote-back" role="doc-backlink">↩︎</a></p></li>
+</ol>
+</aside>
+<h1 id="section-2">Section 2</h1>
+<p>dolly<a href="#fn5" class="footnote-ref" id="fnref5"
+role="doc-noteref"><sup>5</sup></a></p>
+<aside id="footnotes-2" class="footnotes footnotes-end-of-section"
+role="doc-footnote">
+<hr />
+<ol start="5">
+<li id="fn5"><p>doc footnote<a href="#fnref5" class="footnote-back"
+role="doc-backlink">↩︎</a></p></li>
+</ol>
+</aside>
+```
diff --git a/documents/markdown/pandoc-md/8777.md b/documents/markdown/pandoc-md/8777.md
new file mode 100644
index 0000000..56f5db0
--- /dev/null
+++ b/documents/markdown/pandoc-md/8777.md
@@ -0,0 +1,8 @@
+# Backslash escapes in markdown_strict
+
+```
+% pandoc --from=markdown_strict -t html
+These are not escaped: \~ \"
+^D
+<p>These are not escaped: \~ \"</p>
+```
diff --git a/documents/markdown/pandoc-md/8783.md b/documents/markdown/pandoc-md/8783.md
new file mode 100644
index 0000000..c0538b8
--- /dev/null
+++ b/documents/markdown/pandoc-md/8783.md
@@ -0,0 +1,33 @@
+```
+% pandoc -f rtf -t native
+{\rtf1\ansi\ansicpg1252\cocoartf2867
+\cocoatextscaling0\cocoaplatform1{\fonttbl\f0\fnil\fcharset0 HelveticaNeue;}
+{\colortbl;\red255\green255\blue255;\red0\green0\blue0;}
+{\*\expandedcolortbl;;\cssrgb\c0\c0\c0;}
+{\*\listtable{\list\listtemplateid1\listhybrid{\listlevel\levelnfc0\levelnfcn0\leveljc0\leveljcn0\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{decimal\}.}{\leveltext\leveltemplateid1\'02\'00.;}{\levelnumbers\'01;}\fi-360\li720\lin720 }{\listname ;}\listid1}
+{\list\listtemplateid2\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc0\leveljcn0\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid101\'01\uc0\u8226 ;}{\levelnumbers;}\fi-360\li720\lin720 }{\listname ;}\listid2}}
+{\*\listoverridetable{\listoverride\listid1\listoverridecount0\ls1}{\listoverride\listid2\listoverridecount0\ls2}}
+\paperw11905\paperh16837\margl1133\margr1133\margb1133\margt1133
+\deftab720
+\pard\pardeftab720\partightenfactor0
+
+\f0\fs22 \cf2 \up0 \nosupersub \ulnone First paragraph\
+\pard\tx20\tx360\pardeftab720\li360\fi-360\partightenfactor0
+\ls1\ilvl0\cf2 \up0 \nosupersub \ulnone {\listtext 1. }\cf2 \up0 \nosupersub \ulnone Numbered item\
+\pard\pardeftab720\partightenfactor0
+\cf2 Second paragraph\
+\pard\tx20\tx180\pardeftab720\li180\fi-180\partightenfactor0
+\ls2\ilvl0\cf2 \up0 \nosupersub \ulnone {\listtext \uc0\u8226 }\cf2 \up0 \nosupersub \ulnone Bullet item\
+\pard\pardeftab720\partightenfactor0
+\cf2 New paragraph}
+^D
+[ Para [ Str "First" , Space , Str "paragraph" ]
+, OrderedList
+ ( 1 , Decimal , Period )
+ [ [ Para [ Str "Numbered" , Space , Str "item" ] ] ]
+, Para [ Str "Second" , Space , Str "paragraph" ]
+, BulletList
+ [ [ Para [ Str "Bullet" , Space , Str "item" ] ] ]
+, Para [ Str "New" , Space , Str "paragraph" ]
+]
+```
diff --git a/documents/markdown/pandoc-md/8789.md b/documents/markdown/pandoc-md/8789.md
new file mode 100644
index 0000000..291f508
--- /dev/null
+++ b/documents/markdown/pandoc-md/8789.md
@@ -0,0 +1,42 @@
+# `\multicolumn` with column-type `p`
+
+```
+% pandoc --from=latex --to=html
+\begin{tabular}{rrll}
+ \toprule
+ \textbf{First} & \textbf{Second} & \textbf{Third} & \textbf{Fourth} \\ \toprule
+ 160 & 1 & test & test \\\midrule
+ 160 & 2 & \multicolumn{2}{p{12cm}}{\textit{This is a test:}
+ \begin{equation*}
+ a^2+b^2 = c^2
+ \end{equation*}
+ }\\
+\bottomrule
+\end{tabular}
+^D
+<table>
+<thead>
+<tr>
+<th style="text-align: right;"><strong>First</strong></th>
+<th style="text-align: right;"><strong>Second</strong></th>
+<th style="text-align: left;"><strong>Third</strong></th>
+<th style="text-align: left;"><strong>Fourth</strong></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td style="text-align: right;">160</td>
+<td style="text-align: right;">1</td>
+<td style="text-align: left;">test</td>
+<td style="text-align: left;">test</td>
+</tr>
+<tr>
+<td style="text-align: right;">160</td>
+<td style="text-align: right;">2</td>
+<td colspan="2" style="text-align: left;"><em>This is a test:</em> <span
+class="math display"><em>a</em><sup>2</sup> + <em>b</em><sup>2</sup> = <em>c</em><sup>2</sup></span></td>
+</tr>
+</tbody>
+</table>
+
+```
diff --git a/documents/markdown/pandoc-md/8853.md b/documents/markdown/pandoc-md/8853.md
new file mode 100644
index 0000000..bf15b57
--- /dev/null
+++ b/documents/markdown/pandoc-md/8853.md
@@ -0,0 +1,6 @@
+```
+% pandoc -f markdown+wikilinks_title_after_pipe --wrap=none
+[[hi]] and ![[hi]]
+^D
+<p><a href="hi" class="wikilink">hi</a> and <img src="hi" class="wikilink" alt="hi" /></p>
+```
diff --git a/documents/markdown/pandoc-md/8863.md b/documents/markdown/pandoc-md/8863.md
new file mode 100644
index 0000000..03691e3
--- /dev/null
+++ b/documents/markdown/pandoc-md/8863.md
@@ -0,0 +1,11 @@
+```
+% pandoc -f dokuwiki -t native
+ * item 1
+ * item 1.1
+^D
+[ BulletList
+ [ [ Plain [ Str "item" , Space , Str "1" ] ]
+ , [ Plain [ Str "item" , Space , Str "1.1" ] ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/8867.md b/documents/markdown/pandoc-md/8867.md
new file mode 100644
index 0000000..f5a5a90
--- /dev/null
+++ b/documents/markdown/pandoc-md/8867.md
@@ -0,0 +1,49 @@
+```
+% pandoc -f jats -t native -s
+<article-meta>
+ <title-group>
+ <article-title></article-title>
+ </title-group>
+ <permissions>
+ <copyright-statement>© 2023, Ellerman et al</copyright-statement>
+ <copyright-year>2023</copyright-year>
+ <copyright-holder>Ellerman et al</copyright-holder>
+ <license license-type="open-access">
+ <ali:license_ref xmlns:ali="http://www.niso.org/schemas/ali/1.0/">https://creativecommons.org/licenses/by/4.0/</ali:license_ref>
+ <license-p>This document is distributed under a Creative Commons Attribution 4.0 International license.</license-p>
+ </license>
+ </permissions>
+</article-meta>
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "copyright"
+ , MetaMap
+ (fromList
+ [ ( "holder" , MetaString "Ellerman et al" )
+ , ( "statement"
+ , MetaString "\169 2023, Ellerman et al"
+ )
+ , ( "year" , MetaString "2023" )
+ ])
+ )
+ , ( "license"
+ , MetaMap
+ (fromList
+ [ ( "link"
+ , MetaString
+ "https://creativecommons.org/licenses/by/4.0/"
+ )
+ , ( "text"
+ , MetaString
+ "This document is distributed under a Creative Commons Attribution 4.0 International license."
+ )
+ , ( "type" , MetaString "open-access" )
+ ])
+ )
+ ]
+ }
+ []
+```
\ No newline at end of file
diff --git a/documents/markdown/pandoc-md/8869.md b/documents/markdown/pandoc-md/8869.md
new file mode 100644
index 0000000..eba564d
--- /dev/null
+++ b/documents/markdown/pandoc-md/8869.md
@@ -0,0 +1,20 @@
+Org arguments can either be single words, or quoted.
+
+```
+% pandoc -f org -t native
+#+begin_src jupyter-julia :exports both
+1 + 2
+#+end_src
+
+#+begin_src jupyter-julia :exports "both"
+1 + 2
+#+end_src
+^D
+[ CodeBlock
+ ( "" , [ "julia" , "code" ] , [ ( "exports" , "both" ) ] )
+ "1 + 2\n"
+, CodeBlock
+ ( "" , [ "julia" , "code" ] , [ ( "exports" , "both" ) ] )
+ "1 + 2\n"
+]
+```
diff --git a/documents/markdown/pandoc-md/8872.md b/documents/markdown/pandoc-md/8872.md
new file mode 100644
index 0000000..fddcb3c
--- /dev/null
+++ b/documents/markdown/pandoc-md/8872.md
@@ -0,0 +1,45 @@
+
+```
+% pandoc -f latex -t native
+\documentclass{amsart}
+\newtheorem{theorem}{Theorem}
+\begin{document}
+\begin{theorem}\label{thm}
+\begin{enumerate}
+\item \label{item1}text1
+\item \label{item2}text2
+\item text3
+\end{enumerate}
+\end{theorem}
+\end{document}
+^D
+[ Div
+ ( "thm" , [ "theorem" ] , [] )
+ [ Para
+ [ Strong [ Str "Theorem" , Space , Str "1" ]
+ , Str "."
+ , Space
+ , Space
+ , Emph []
+ ]
+ , OrderedList
+ ( 1 , DefaultStyle , DefaultDelim )
+ [ [ Para
+ [ Emph
+ [ Span ( "item1" , [] , [ ( "label" , "item1" ) ] ) []
+ , Str "text1"
+ ]
+ ]
+ ]
+ , [ Para
+ [ Emph
+ [ Span ( "item2" , [] , [ ( "label" , "item2" ) ] ) []
+ , Str "text2"
+ ]
+ ]
+ ]
+ , [ Para [ Emph [ Str "text3" ] ] ]
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/8948.md b/documents/markdown/pandoc-md/8948.md
new file mode 100644
index 0000000..710d866
--- /dev/null
+++ b/documents/markdown/pandoc-md/8948.md
@@ -0,0 +1,31 @@
+```
+% pandoc --embed-resources
+{.inline-svg}
+{.inline-svg}
+^D
+<p><svg role="img" aria-label="minimal" alt="minimal" viewBox="-.333 -.333 480 150" style="background-color:#ffffff00" xml:space="preserve" width="480" height="150"><use href="#svg_7868854ffb8f30209cd0" width="100%" height="100%" /></svg>
+<svg id="svg_7868854ffb8f30209cd0" role="img" aria-label="minimal" alt="minimal" viewBox="-.333 -.333 480 150" style="background-color:#ffffff00" xml:space="preserve" width="480" height="150">
+ <path d="M 0 35.5 L 6.5 22.5 L 16 37 L 23 24 L 34.8 43.7 L 42.5 30 L 50.3 47 L 59.7 27.7 L 69 47 L 85 17.7 L 98.3 39 L 113 9.7 L 127.7 42.3 L 136.3 23.7 L 147 44.3 L 158.3 20.3 L 170.3 40.3 L 177.7 25.7 L 189.7 43 L 199.7 21 L 207.7 35 L 219 11 L 233 37 L 240.3 23.7 L 251 43 L 263 18.3 L 272.7 33.3 L 283 10 L 295 32.3 L 301.3 23 L 311.7 37 L 323.7 7.7 L 339.3 39 L 346.3 25.7 L 356.3 42.3 L 369.7 15 L 376.3 25.7 L 384 9 L 393 28.3 L 400.3 19 L 411.7 38.3 L 421 21 L 434.3 43 L 445 25 L 453 36.3 L 464.3 18.3 L 476.2 40.3 L 480 33.5 L 480 215 L 0 215 L 0 35.5 Z" fill="#175720" />
+</svg></p>
+```
+
+```
+% pandoc --embed-resources
+{.inline-svg}
+{#foo .inline-svg}
+^D
+<p><svg role="img" aria-label="minimal" alt="minimal" viewBox="-.333 -.333 480 150" style="background-color:#ffffff00" xml:space="preserve" width="480" height="150"><use href="#foo" width="100%" height="100%" /></svg>
+<svg id="foo" role="img" aria-label="minimal" alt="minimal" viewBox="-.333 -.333 480 150" style="background-color:#ffffff00" xml:space="preserve" width="480" height="150">
+ <path d="M 0 35.5 L 6.5 22.5 L 16 37 L 23 24 L 34.8 43.7 L 42.5 30 L 50.3 47 L 59.7 27.7 L 69 47 L 85 17.7 L 98.3 39 L 113 9.7 L 127.7 42.3 L 136.3 23.7 L 147 44.3 L 158.3 20.3 L 170.3 40.3 L 177.7 25.7 L 189.7 43 L 199.7 21 L 207.7 35 L 219 11 L 233 37 L 240.3 23.7 L 251 43 L 263 18.3 L 272.7 33.3 L 283 10 L 295 32.3 L 301.3 23 L 311.7 37 L 323.7 7.7 L 339.3 39 L 346.3 25.7 L 356.3 42.3 L 369.7 15 L 376.3 25.7 L 384 9 L 393 28.3 L 400.3 19 L 411.7 38.3 L 421 21 L 434.3 43 L 445 25 L 453 36.3 L 464.3 18.3 L 476.2 40.3 L 480 33.5 L 480 215 L 0 215 L 0 35.5 Z" fill="#175720" />
+</svg></p>
+```
+
+```
+% pandoc --embed-resources
+
+^D
+<figure>
+<img role="img" aria-label="minimal" src="data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBzdGFuZGFsb25lPSJubyI/PgoKPHN2ZyB2aWV3Qm94PSItLjMzMyAtLjMzMyA0ODAgMTUwIiBzdHlsZT0iYmFja2dyb3VuZC1jb2xvcjojZmZmZmZmMDAiIHZlcnNpb249IjEuMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgeG1sOnNwYWNlPSJwcmVzZXJ2ZSI+CiAgICA8cGF0aCBkPSJNIDAgMzUuNSBMIDYuNSAyMi41IEwgMTYgMzcgTCAyMyAyNCBMIDM0LjggNDMuNyBMIDQyLjUgMzAgTCA1MC4zIDQ3IEwgNTkuNyAyNy43IEwgNjkgNDcgTCA4NSAxNy43IEwgOTguMyAzOSBMIDExMyA5LjcgTCAxMjcuNyA0Mi4zIEwgMTM2LjMgMjMuNyBMIDE0NyA0NC4zIEwgMTU4LjMgMjAuMyBMIDE3MC4zIDQwLjMgTCAxNzcuNyAyNS43IEwgMTg5LjcgNDMgTCAxOTkuNyAyMSBMIDIwNy43IDM1IEwgMjE5IDExIEwgMjMzIDM3IEwgMjQwLjMgMjMuNyBMIDI1MSA0MyBMIDI2MyAxOC4zIEwgMjcyLjcgMzMuMyBMIDI4MyAxMCBMIDI5NSAzMi4zIEwgMzAxLjMgMjMgTCAzMTEuNyAzNyBMIDMyMy43IDcuNyBMIDMzOS4zIDM5IEwgMzQ2LjMgMjUuNyBMIDM1Ni4zIDQyLjMgTCAzNjkuNyAxNSBMIDM3Ni4zIDI1LjcgTCAzODQgOSBMIDM5MyAyOC4zIEwgNDAwLjMgMTkgTCA0MTEuNyAzOC4zIEwgNDIxIDIxIEwgNDM0LjMgNDMgTCA0NDUgMjUgTCA0NTMgMzYuMyBMIDQ2NC4zIDE4LjMgTCA0NzYuMiA0MC4zIEwgNDgwIDMzLjUgTCA0ODAgMjE1IEwgMCAyMTUgTCAwIDM1LjUgWiIgZmlsbD0iIzE3NTcyMCIvPgo8L3N2Zz4K" alt="minimal" />
+<figcaption aria-hidden="true">minimal</figcaption>
+</figure>
+```
diff --git a/documents/markdown/pandoc-md/8956.md b/documents/markdown/pandoc-md/8956.md
new file mode 100644
index 0000000..02ab292
--- /dev/null
+++ b/documents/markdown/pandoc-md/8956.md
@@ -0,0 +1,48 @@
+```
+% pandoc -iNtslidy
+# One
+
+- one
+- two
+^D
+<div id="one" class="slide section level1" number="1">
+<h1><span class="header-section-number">1</span> One</h1>
+<ul class="incremental">
+<li>one</li>
+<li>two</li>
+</ul>
+</div>
+```
+
+````
+% pandoc -pstnative
+```
+ after tab
+```
+^D
+Pandoc
+ Meta { unMeta = fromList [] }
+ [ CodeBlock ( "" , [] , [] ) "\tafter tab" ]
+````
+
+```
+% pandoc -sfalse
+hi
+^D
+<p>hi</p>
+```
+
+```
+% pandoc --standalone=false
+hi
+^D
+<p>hi</p>
+```
+
+```
+% pandoc --standalone=FALSE
+hi
+^D
+<p>hi</p>
+```
+
diff --git a/documents/markdown/pandoc-md/8957.md b/documents/markdown/pandoc-md/8957.md
new file mode 100644
index 0000000..66840f7
--- /dev/null
+++ b/documents/markdown/pandoc-md/8957.md
@@ -0,0 +1,7 @@
+```
+% pandoc -f latex -t html --wrap=none
+{width="342pt" height="9pc"}
+^D
+<p><span>width="342pt" height="9pc"</span></p>
+
+```
diff --git a/documents/markdown/pandoc-md/8966.md b/documents/markdown/pandoc-md/8966.md
new file mode 100644
index 0000000..3c41fc8
--- /dev/null
+++ b/documents/markdown/pandoc-md/8966.md
@@ -0,0 +1,9 @@
+```
+% pandoc -t typst
+**Samsonov T.E.** Shape-Adaptive Geometric Simplification of Heterogeneous Line Datasets / T. E. Samsonov, O. P. Yakimova // International Journal of Geographical Information Science. — 2017. — Vol. 31. — № 8. — pp. 1485-1520.
+^D
+#strong[Samsonov T.E.] Shape-Adaptive Geometric Simplification of
+Heterogeneous Line Datasets / T. E. Samsonov, O. P. Yakimova /\/
+International Journal of Geographical Information Science. --- 2017. ---
+Vol. 31. --- № 8. --- pp.~1485-1520.
+```
diff --git a/documents/markdown/pandoc-md/8981.md b/documents/markdown/pandoc-md/8981.md
new file mode 100644
index 0000000..00ba6d2
--- /dev/null
+++ b/documents/markdown/pandoc-md/8981.md
@@ -0,0 +1,6 @@
+```
+% pandoc --wrap=none
+consectetur [^\[link\]^](#ref "Title")
+^D
+<p>consectetur <a href="#ref" title="Title"><sup>[link]</sup></a></p>
+```
diff --git a/documents/markdown/pandoc-md/8984.md b/documents/markdown/pandoc-md/8984.md
new file mode 100644
index 0000000..5dc9519
--- /dev/null
+++ b/documents/markdown/pandoc-md/8984.md
@@ -0,0 +1,122 @@
+```
+% pandoc -f html -t native
+<table>
+ <tr>
+ <th colspan="2">a</th>
+ <td>b</td>
+ </tr>
+ <tr>
+ <th>c</th>
+ <th>d</th>
+ <td>e</td>
+ </tr>
+</table>
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 2)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 2)
+ [ Plain [ Str "a" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "b" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "c" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "d" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "e" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+
+```
+
+```
+% pandoc -f html -t native
+<table>
+<tr>
+<th rowspan="2">Heading</th>
+<td>content</td>
+</tr>
+<tr>
+<td>content2</td>
+</tr>
+</table>
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 1)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 2)
+ (ColSpan 1)
+ [ Plain [ Str "Heading" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "content" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "content2" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+
+```
diff --git a/documents/markdown/pandoc-md/8992.md b/documents/markdown/pandoc-md/8992.md
new file mode 100644
index 0000000..0f2383d
--- /dev/null
+++ b/documents/markdown/pandoc-md/8992.md
@@ -0,0 +1,6 @@
+```
+% pandoc -t latex
+[A theorem](https://en.wikipedia.org/wiki/Rice's_theorem).
+^D
+\href{https://en.wikipedia.org/wiki/Rice's_theorem}{A theorem}.
+```
diff --git a/documents/markdown/pandoc-md/8997.md b/documents/markdown/pandoc-md/8997.md
new file mode 100644
index 0000000..d64b1d3
--- /dev/null
+++ b/documents/markdown/pandoc-md/8997.md
@@ -0,0 +1,77 @@
+```
+% pandoc -f org -t native
+* has space after second colon
+: aaa
+:
+: bbb
+
+
+* has no space after second colon
+: aaa
+:
+: bbb
+^D
+[ Header
+ 1
+ ( "has-space-after-second-colon" , [] , [] )
+ [ Str "has"
+ , Space
+ , Str "space"
+ , Space
+ , Str "after"
+ , Space
+ , Str "second"
+ , Space
+ , Str "colon"
+ ]
+, CodeBlock ( "" , [] , [] ) "aaa\n\nbbb\n"
+, Header
+ 1
+ ( "has-no-space-after-second-colon" , [] , [] )
+ [ Str "has"
+ , Space
+ , Str "no"
+ , Space
+ , Str "space"
+ , Space
+ , Str "after"
+ , Space
+ , Str "second"
+ , Space
+ , Str "colon"
+ ]
+, CodeBlock ( "" , [] , [] ) "aaa\n\nbbb\n"
+]
+```
+
+```
+% pandoc -f org -t native
+* only the colon
+:
+
+* only the colon and a space
+:
+^D
+[ Header
+ 1
+ ( "only-the-colon" , [] , [] )
+ [ Str "only" , Space , Str "the" , Space , Str "colon" ]
+, CodeBlock ( "" , [] , [] ) "\n"
+, Header
+ 1
+ ( "only-the-colon-and-a-space" , [] , [] )
+ [ Str "only"
+ , Space
+ , Str "the"
+ , Space
+ , Str "colon"
+ , Space
+ , Str "and"
+ , Space
+ , Str "a"
+ , Space
+ , Str "space"
+ ]
+, CodeBlock ( "" , [] , [] ) "\n"
+]
+```
diff --git a/documents/markdown/pandoc-md/9000.md b/documents/markdown/pandoc-md/9000.md
new file mode 100644
index 0000000..2c63363
--- /dev/null
+++ b/documents/markdown/pandoc-md/9000.md
@@ -0,0 +1,14 @@
+```
+% pandoc -t org --wrap=auto --columns=20
+[This is a link with a long description that should not
+wrap](http://example.com) and
+some regular text after it so we can see how wrapping works.
+^D
+[[http://example.com][This is a link with a long description that should not wrap]]
+and some regular
+text after it so we
+can see how wrapping
+works.
+
+```
+
diff --git a/documents/markdown/pandoc-md/9002.md b/documents/markdown/pandoc-md/9002.md
new file mode 100644
index 0000000..bac9d23
--- /dev/null
+++ b/documents/markdown/pandoc-md/9002.md
@@ -0,0 +1,20 @@
+```
+% pandoc command/9002.docx -t html
+^D
+<table style="width:40%;">
+<caption><p>This is my table!</p></caption>
+<colgroup>
+<col style="width: 20%" />
+<col style="width: 20%" />
+</colgroup>
+<thead>
+<tr>
+<th>a</th>
+<th>b</th>
+</tr>
+</thead>
+<tbody>
+</tbody>
+</table>
+<p>See <a href="#_Ref143272803">Table 1 This is my table!</a></p>
+```
diff --git a/documents/markdown/pandoc-md/9017.md b/documents/markdown/pandoc-md/9017.md
new file mode 100644
index 0000000..4faa153
--- /dev/null
+++ b/documents/markdown/pandoc-md/9017.md
@@ -0,0 +1,54 @@
+```
+% pandoc -t jats --citeproc -s
+---
+references:
+- author: DeGroot
+ id: degroot_probability
+ title: Probability
+ issued: 2002
+title: Doc example with single reference
+---
+
+# I like
+
+[@degroot_probability].
+^D
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE article PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Archiving and Interchange DTD v1.2 20190208//EN"
+ "JATS-archivearticle1.dtd">
+<article xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:xlink="http://www.w3.org/1999/xlink" dtd-version="1.2" article-type="other">
+<front>
+<journal-meta>
+<journal-id></journal-id>
+<journal-title-group>
+</journal-title-group>
+<issn></issn>
+<publisher>
+<publisher-name></publisher-name>
+</publisher>
+</journal-meta>
+<article-meta>
+<title-group>
+<article-title>Doc example with single reference</article-title>
+</title-group>
+<permissions>
+</permissions>
+</article-meta>
+</front>
+<body>
+<sec id="i-like">
+ <title>I like</title>
+ <p>(DeGroot 2002).</p>
+</sec>
+</body>
+<back>
+<ref-list>
+ <title></title>
+ <ref id="ref-degroot_probability">
+ <mixed-citation>DeGroot. 2002.
+ <italic>Probability</italic>.</mixed-citation>
+ </ref>
+</ref-list>
+</back>
+</article>
+```
diff --git a/documents/markdown/pandoc-md/9021.md b/documents/markdown/pandoc-md/9021.md
new file mode 100644
index 0000000..4bb4395
--- /dev/null
+++ b/documents/markdown/pandoc-md/9021.md
@@ -0,0 +1,61 @@
+```
+% pandoc -t jats+element_citations --citeproc -s
+---
+references:
+- author: DeGroot
+ id: degroot_probability
+ title: Probability
+ issued: 2002
+title: Doc example with single reference
+reference-section-title: Ref Title
+---
+
+# I like
+
+[@degroot_probability].
+^D
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE article PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Archiving and Interchange DTD v1.2 20190208//EN"
+ "JATS-archivearticle1.dtd">
+<article xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:xlink="http://www.w3.org/1999/xlink" dtd-version="1.2" article-type="other">
+<front>
+<journal-meta>
+<journal-id></journal-id>
+<journal-title-group>
+</journal-title-group>
+<issn></issn>
+<publisher>
+<publisher-name></publisher-name>
+</publisher>
+</journal-meta>
+<article-meta>
+<title-group>
+<article-title>Doc example with single reference</article-title>
+</title-group>
+<permissions>
+</permissions>
+</article-meta>
+</front>
+<body>
+<sec id="i-like">
+ <title>I like</title>
+ <p>(DeGroot 2002).</p>
+</sec>
+</body>
+<back>
+<ref-list>
+ <title>Ref Title</title>
+ <ref id="ref-degroot_probability">
+ <element-citation>
+ <person-group person-group-type="author">
+ <string-name>DeGroot</string-name>
+ </person-group>
+ <article-title>Probability</article-title>
+ <year iso-8601-date="2002">2002</year>
+ </element-citation>
+ </ref>
+</ref-list>
+</back>
+</article>
+
+```
diff --git a/documents/markdown/pandoc-md/9042.md b/documents/markdown/pandoc-md/9042.md
new file mode 100644
index 0000000..a27fa80
--- /dev/null
+++ b/documents/markdown/pandoc-md/9042.md
@@ -0,0 +1,30 @@
+```
+% pandoc -f org
+#+TITLE: Testing
+
+* Testing
+
+p. lower case
+
+P. Upper Case
+^D
+<h1 id="testing-1">Testing</h1>
+<p>p. lower case</p>
+<p>P. Upper Case</p>
+```
+```
+% pandoc -f org+fancy_lists
+#+TITLE: Testing
+
+* Testing
+
+p. lower case
+
+P. Upper Case
+^D
+<h1 id="testing-1">Testing</h1>
+<ol type="a">
+<li><p>lower case</p></li>
+<li><p>Upper Case</p></li>
+</ol>
+```
diff --git a/documents/markdown/pandoc-md/9043.md b/documents/markdown/pandoc-md/9043.md
new file mode 100644
index 0000000..cef7998
--- /dev/null
+++ b/documents/markdown/pandoc-md/9043.md
@@ -0,0 +1,13 @@
+```
+% pandoc -t latex
+[**TreeTagger**](https://www.cis.uni-muenchen.de/~schmid/tools/TreeTagger/)
+^D
+\href{https://www.cis.uni-muenchen.de/~schmid/tools/TreeTagger/}{\textbf{TreeTagger}}
+```
+
+```
+% pandoc -t latex
+[**TreeTagger**](https://www.cis.uni-muenchen.de/%E7schmid/tools/TreeTagger/)
+^D
+\href{https://www.cis.uni-muenchen.de/\%E7schmid/tools/TreeTagger/}{\textbf{TreeTagger}}
+```
diff --git a/documents/markdown/pandoc-md/9045.md b/documents/markdown/pandoc-md/9045.md
new file mode 100644
index 0000000..d028d4a
--- /dev/null
+++ b/documents/markdown/pandoc-md/9045.md
@@ -0,0 +1,10 @@
+```
+% pandoc -t latex
+{#foo}
+^D
+\begin{figure}
+\centering
+\pandocbounded{\includegraphics[keepaspectratio,alt={hi}]{there.jpg}}
+\caption{hi}\label{foo}
+\end{figure}
+```
diff --git a/documents/markdown/pandoc-md/9047.md b/documents/markdown/pandoc-md/9047.md
new file mode 100644
index 0000000..84c405e
--- /dev/null
+++ b/documents/markdown/pandoc-md/9047.md
@@ -0,0 +1,47 @@
+tests meant to test the fixes of bug [#9047](https://github.com/jgm/pandoc/issues/9047)
+
+```
+% pandoc -f html -t html
+<ul class="task-list">
+<li><label><input type="checkbox" />foo</label></li>
+<li><label><input type="checkbox" checked="" />bar</label></li>
+<li><label><input type="button" checked="" />foobar</label></li>
+<li><input id="hello" type="checkbox" checked/><label for="hello">hello</label></li>
+</ul>
+^D
+<ul>
+<li><label><input type="checkbox" />foo</label></li>
+<li><label><input type="checkbox" checked="" />bar</label></li>
+<li>foobar</li>
+<li><label><input type="checkbox" checked="" />hello</label></li>
+</ul>
+```
+
+w/ rawHTML extension a checkbox by itself is kept
+```
+% pandoc -f html+raw_html -t html+raw_html
+<input type="checkbox" checked="" />
+^D
+<input type="checkbox" checked>
+</input>
+```
+
+w/ rawHTML extension, a checkbox in an `li` is handled properly
+```
+% pandoc -f html+raw_html -t html+raw_html
+<ul>
+<li><input type="checkbox" checked/>foo</li>
+</ul>
+^D
+<ul class="task-list">
+<li><label><input type="checkbox" checked="" />foo</label></li>
+</ul>
+```
+
+w/o rawHTML extension, a checkbox outside of an `li` is properly ignored
+```
+% pandoc -f html -t html
+<p><input type="checkbox" checked/>foo</p>
+^D
+foo
+```
diff --git a/documents/markdown/pandoc-md/9088.md b/documents/markdown/pandoc-md/9088.md
new file mode 100644
index 0000000..fca6300
--- /dev/null
+++ b/documents/markdown/pandoc-md/9088.md
@@ -0,0 +1,10 @@
+```
+% pandoc -t latex
+| 0 - A
+| 1 - B
+| 2 - C
+^D
+~~~0 - A\\
+\strut ~~~1 - B\\
+\strut ~~~2 - C
+```
diff --git a/documents/markdown/pandoc-md/9090.md b/documents/markdown/pandoc-md/9090.md
new file mode 100644
index 0000000..a2c94b9
--- /dev/null
+++ b/documents/markdown/pandoc-md/9090.md
@@ -0,0 +1,15 @@
+```
+% pandoc -f html -t gfm
+<table>
+ <tr>
+ <th>invalid head cell</td>
+ </tr>
+ <tr>
+ <td>body cell</td>
+ </tr>
+</table>
+^D
+| invalid head cell |
+|-------------------|
+| body cell |
+```
diff --git a/documents/markdown/pandoc-md/9121.md b/documents/markdown/pandoc-md/9121.md
new file mode 100644
index 0000000..8ced6a2
--- /dev/null
+++ b/documents/markdown/pandoc-md/9121.md
@@ -0,0 +1,17 @@
+````
+% pandoc -t gfm
+a $$x=y$$ b
+^D
+a
+``` math
+x=y
+```
+b
+````
+
+````
+% pandoc -t gfm
+a $x=y$ b
+^D
+a $`x=y`$ b
+````
diff --git a/documents/markdown/pandoc-md/9150.md b/documents/markdown/pandoc-md/9150.md
new file mode 100644
index 0000000..a3c38ed
--- /dev/null
+++ b/documents/markdown/pandoc-md/9150.md
@@ -0,0 +1,51 @@
+```
+% pandoc -f latex -t native
+\hfill {\Large \textbf{Theoretische Grundlagen der Informatik}}
+^D
+[ Para
+ [ Span
+ ( "" , [] , [] )
+ [ Strong
+ [ Str "Theoretische"
+ , Space
+ , Str "Grundlagen"
+ , Space
+ , Str "der"
+ , Space
+ , Str "Informatik"
+ ]
+ ]
+ ]
+]
+```
+
+```
+% pandoc -f latex+raw_tex -t native
+\hfill {\Large \textbf{Theoretische Grundlagen der Informatik}}
+^D
+[ Para
+ [ RawInline (Format "latex") "\\hfill "
+ , Span
+ ( "" , [] , [] )
+ [ RawInline (Format "latex") "\\Large "
+ , Strong
+ [ Str "Theoretische"
+ , Space
+ , Str "Grundlagen"
+ , Space
+ , Str "der"
+ , Space
+ , Str "Informatik"
+ ]
+ ]
+ ]
+]
+```
+
+```
+% pandoc -f latex+raw_tex -t native
+\hskip 2pt plus 1pt minus 1pt
+^D
+[ RawBlock (Format "latex") "\\hskip 2pt plus 1pt minus 1pt"
+]
+```
diff --git a/documents/markdown/pandoc-md/9159.md b/documents/markdown/pandoc-md/9159.md
new file mode 100644
index 0000000..0b73f80
--- /dev/null
+++ b/documents/markdown/pandoc-md/9159.md
@@ -0,0 +1,15 @@
+```
+% pandoc -t org -f markdown
+\* See Blah
+
+\# not comment
+
+\| not table \|
+^D
+* See Blah
+
+# not comment
+
+| not table |
+
+```
diff --git a/documents/markdown/pandoc-md/9171.md b/documents/markdown/pandoc-md/9171.md
new file mode 100644
index 0000000..ede24e3
--- /dev/null
+++ b/documents/markdown/pandoc-md/9171.md
@@ -0,0 +1,65 @@
+```
+% pandoc -f markdown -t native
+[link][link contents]{target="_blank"}
+[link2](https://example.com){target="_blank"}
+
+[link contents]: https://example.com
+^D
+[ Para
+ [ Link
+ ( "" , [] , [ ( "target" , "_blank" ) ] )
+ [ Str "link" ]
+ ( "https://example.com" , "" )
+ , SoftBreak
+ , Link
+ ( "" , [] , [ ( "target" , "_blank" ) ] )
+ [ Str "link2" ]
+ ( "https://example.com" , "" )
+ ]
+]
+
+```
+
+```
+% pandoc -f markdown -t native
+[link][link contents]{#id1 target="_blank"}
+[link2](https://example.com){target="_blank"}
+
+[link contents]: https://example.com {#id2 target="_nonblank"}
+^D
+[ Para
+ [ Link
+ ( "id1" , [] , [ ( "target" , "_blank" ) ] )
+ [ Str "link" ]
+ ( "https://example.com" , "" )
+ , SoftBreak
+ , Link
+ ( "" , [] , [ ( "target" , "_blank" ) ] )
+ [ Str "link2" ]
+ ( "https://example.com" , "" )
+ ]
+]
+
+```
+
+```
+% pandoc -f markdown -t native
+[link][link contents]{target="_blank"}
+[link2](https://example.com){target="_blank"}
+
+[link contents]: https://example.com {.foo}
+^D
+[ Para
+ [ Link
+ ( "" , [ "foo" ] , [ ( "target" , "_blank" ) ] )
+ [ Str "link" ]
+ ( "https://example.com" , "" )
+ , SoftBreak
+ , Link
+ ( "" , [] , [ ( "target" , "_blank" ) ] )
+ [ Str "link2" ]
+ ( "https://example.com" , "" )
+ ]
+]
+
+```
diff --git a/documents/markdown/pandoc-md/9196.md b/documents/markdown/pandoc-md/9196.md
new file mode 100644
index 0000000..e7f8ee3
--- /dev/null
+++ b/documents/markdown/pandoc-md/9196.md
@@ -0,0 +1,6 @@
+```
+% pandoc -f rst --wrap=none
+Define _`my target`, then reference `my target`_.
+^D
+<p>Define <span id="my-target">my target</span>, then reference <a href="#my-target">my target</a>.</p>
+```
diff --git a/documents/markdown/pandoc-md/9201.md b/documents/markdown/pandoc-md/9201.md
new file mode 100644
index 0000000..333f8e3
--- /dev/null
+++ b/documents/markdown/pandoc-md/9201.md
@@ -0,0 +1,18 @@
+```
+% pandoc -f man -t markdown
+.TH "EXAMPLE" "1"
+.SH "OPTIONS"
+.TP 8n
+\fB\-\-help\fR
+This is line one.
+.sp
+This is line two.
+^D
+# OPTIONS
+
+**\--help**
+
+: This is line one.
+
+ This is line two.
+```
diff --git a/documents/markdown/pandoc-md/9202.md b/documents/markdown/pandoc-md/9202.md
new file mode 100644
index 0000000..c8096f6
--- /dev/null
+++ b/documents/markdown/pandoc-md/9202.md
@@ -0,0 +1,62 @@
+```
+% pandoc -f latex -t native
+\begin{otherlanguage}{french}
+Bonjour.
+\end{otherlanguage}
+^D
+[ Div
+ ( "" , [] , [ ( "lang" , "fr" ) ] )
+ [ Para [ Str "Bonjour." ] ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\begin{otherlanguage*}{french}
+Bonjour.
+\end{otherlanguage*}
+^D
+[ Div
+ ( "" , [ "otherlanguage*" ] , [] )
+ [ Para
+ [ Span ( "" , [] , [] ) [ Str "french" ]
+ , SoftBreak
+ , Str "Bonjour."
+ ]
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\textfrench{Bonjour}
+^D
+[ Para
+ [ Span ( "" , [] , [ ( "lang" , "fr" ) ] ) [ Str "Bonjour" ]
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\foreignlanguage{swissgerman}{Guten tag}
+^D
+[ Para
+ [ Span
+ ( "" , [] , [ ( "lang" , "de-CH-1901" ) ] )
+ [ Str "Guten" , Space , Str "tag" ]
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\begin{french}
+Bonjour.
+\end{french}
+^D
+[ Div
+ ( "" , [] , [ ( "lang" , "fr" ) ] )
+ [ Para [ Str "Bonjour." ] ]
+]
+```
diff --git a/documents/markdown/pandoc-md/9209.md b/documents/markdown/pandoc-md/9209.md
new file mode 100644
index 0000000..3cdac7f
--- /dev/null
+++ b/documents/markdown/pandoc-md/9209.md
@@ -0,0 +1,6 @@
+```
+% pandoc -t latex
+## [Section]{#Section3}
+^D
+\subsection{\texorpdfstring{\protect\hypertarget{Section3}{}{Section}}{Section}}\label{section}
+```
diff --git a/documents/markdown/pandoc-md/9218.md b/documents/markdown/pandoc-md/9218.md
new file mode 100644
index 0000000..875c172
--- /dev/null
+++ b/documents/markdown/pandoc-md/9218.md
@@ -0,0 +1,22 @@
+# Escape special lines in Org-mode code blocks
+
+````
+% pandoc -f markdown -t org
+``` org
+** Click Application
+*** Imports
+
+#+begin_src py
+from addict import Dict
+#+end_src
+```
+^D
+#+begin_src org
+,** Click Application
+,*** Imports
+
+,#+begin_src py
+from addict import Dict
+,#+end_src
+#+end_src
+````
diff --git a/documents/markdown/pandoc-md/9236.md b/documents/markdown/pandoc-md/9236.md
new file mode 100644
index 0000000..12c862f
--- /dev/null
+++ b/documents/markdown/pandoc-md/9236.md
@@ -0,0 +1,34 @@
+```
+% pandoc -t typst
+{width=3in}
+
+{width=3in height=2in}
+
+
+
+And inline: {height=2in} and
+.
+^D
+#figure(image("command/minimal.svg", width: 3in, alt: "minimal"),
+ caption: [
+ minimal
+ ]
+)
+
+#figure(image("command/minimal.svg", height: 2in, width: 3in, alt: "minimal"),
+ caption: [
+ minimal
+ ]
+)
+
+#figure(image("command/minimal.svg", alt: "minimal"),
+ caption: [
+ minimal
+ ]
+)
+
+And inline:
+#box(image("command/minimal.svg", height: 2in, alt: "minimal")) and
+#box(image("command/minimal.svg", alt: "minimal")).
+
+```
diff --git a/documents/markdown/pandoc-md/9275.md b/documents/markdown/pandoc-md/9275.md
new file mode 100644
index 0000000..c768866
--- /dev/null
+++ b/documents/markdown/pandoc-md/9275.md
@@ -0,0 +1,18 @@
+```
+% pandoc -t latex --biblatex
+[@scott2000, p. 33]
+[@scott2000, pp. 33-34 and elsewhere; @scott2001, ch. 4]
+^D
+\autocite[33]{scott2000} \autocites[33-34 and
+elsewhere]{scott2000}[ch.~4]{scott2001}
+
+```
+
+```
+% pandoc -t latex --biblatex -Mlang=de
+[@scott2000, p. 33]
+[@scott2000, S. 33]
+^D
+\autocite[p.~33]{scott2000} \autocite[33]{scott2000}
+
+```
diff --git a/documents/markdown/pandoc-md/9279.md b/documents/markdown/pandoc-md/9279.md
new file mode 100644
index 0000000..26d30af
--- /dev/null
+++ b/documents/markdown/pandoc-md/9279.md
@@ -0,0 +1,131 @@
+```
+% pandoc -f org -t native
+#+LABEL: tbl:Cosasexample
+#+CAPTION: Cosas
++-------+-------+
+| cosas | cosas |
+| cosas | cosas |
++=======+=======+
+| cosas | cosas |
+| cosas | cosas |
++-------+-------+
+^D
+[ Table
+ ( "tbl:Cosasexample" , [] , [] )
+ (Caption Nothing [ Plain [ Str "Cosas" ] ])
+ [ ( AlignDefault , ColWidth 0.1111111111111111 )
+ , ( AlignDefault , ColWidth 0.1111111111111111 )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "cosas" , SoftBreak , Str "cosas" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "cosas" , SoftBreak , Str "cosas" ] ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "cosas" , SoftBreak , Str "cosas" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "cosas" , SoftBreak , Str "cosas" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
+
+```
+% pandoc -f org -t markdown
+#+LABEL: tbl:Cosasexample
+#+CAPTION: Cosas
++-------+-------+
+| cosas | cosas |
+| cosas | cosas |
++=======+=======+
+| cosas | cosas |
+| cosas | cosas |
++-------+-------+
+^D
+ ---------------
+ cosas cosas
+ cosas cosas
+ ------- -------
+ cosas cosas
+ cosas cosas
+
+ ---------------
+
+ : Cosas {#tbl:Cosasexample}
+
+```
+
+```
+% pandoc -f org -t markdown
+#+LABEL: tbl:Cosasexample
++-------+-------+
+| cosas | cosas |
+| cosas | cosas |
++=======+=======+
+| cosas | cosas |
+| cosas | cosas |
++-------+-------+
+^D
+ ---------------
+ cosas cosas
+ cosas cosas
+ ------- -------
+ cosas cosas
+ cosas cosas
+
+ ---------------
+
+```
+
+```
+% pandoc -f org -t markdown
+#+CAPTION: Cosas
++-------+-------+
+| cosas | cosas |
+| cosas | cosas |
++=======+=======+
+| cosas | cosas |
+| cosas | cosas |
++-------+-------+
+^D
+ ---------------
+ cosas cosas
+ cosas cosas
+ ------- -------
+ cosas cosas
+ cosas cosas
+
+ ---------------
+
+ : Cosas
+
+```
diff --git a/documents/markdown/pandoc-md/9293.md b/documents/markdown/pandoc-md/9293.md
new file mode 100644
index 0000000..b9471b8
--- /dev/null
+++ b/documents/markdown/pandoc-md/9293.md
@@ -0,0 +1,29 @@
+```
+% pandoc -f mediawiki -t native
+* Linearity in the first argument:
+*:<math>\begin{align}
+\langle a \mathbf u, \mathbf v\rangle &= a \langle \mathbf u, \mathbf v\rangle. \\
+\langle \mathbf u + \mathbf v, \mathbf w\rangle &= \langle \mathbf u, \mathbf w\rangle+ \langle \mathbf v, \mathbf w\rangle.
+\end{align}</math>
+^D
+[ BulletList
+ [ [ Plain
+ [ Str "Linearity"
+ , Space
+ , Str "in"
+ , Space
+ , Str "the"
+ , Space
+ , Str "first"
+ , Space
+ , Str "argument:"
+ ]
+ , Para
+ [ Math
+ DisplayMath
+ "\\begin{align}\n\\langle a \\mathbf u, \\mathbf v\\rangle &= a \\langle \\mathbf u, \\mathbf v\\rangle. \\\\\n\\langle \\mathbf u + \\mathbf v, \\mathbf w\\rangle &= \\langle \\mathbf u, \\mathbf w\\rangle+ \\langle \\mathbf v, \\mathbf w\\rangle.\n\\end{align}"
+ ]
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/934.md b/documents/markdown/pandoc-md/934.md
new file mode 100644
index 0000000..3c86a1f
--- /dev/null
+++ b/documents/markdown/pandoc-md/934.md
@@ -0,0 +1,44 @@
+```
+% pandoc -f latex -t native
+\newcommand{\ddb}[2]{
+ \textit{``#1''}
+
+ \textbf{#2}
+}
+\ddb{This should be italic and in quotes}{And this is the attribution}
+^D
+[ Para
+ [ Emph
+ [ Quoted
+ DoubleQuote
+ [ Str "This"
+ , Space
+ , Str "should"
+ , Space
+ , Str "be"
+ , Space
+ , Str "italic"
+ , Space
+ , Str "and"
+ , Space
+ , Str "in"
+ , Space
+ , Str "quotes"
+ ]
+ ]
+ ]
+, Para
+ [ Strong
+ [ Str "And"
+ , Space
+ , Str "this"
+ , Space
+ , Str "is"
+ , Space
+ , Str "the"
+ , Space
+ , Str "attribution"
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/9346.md b/documents/markdown/pandoc-md/9346.md
new file mode 100644
index 0000000..fd62438
--- /dev/null
+++ b/documents/markdown/pandoc-md/9346.md
@@ -0,0 +1,8 @@
+```
+% pandoc -f markdown -t markdown_strict+pipe_tables
+|V1 |V2 |V3 |V4 |V5 |V6 |V7 |V8 |V9 |V10 |V11 |V12 |V13 |V14 |V15 |V16 |V17 |V18 |V19 |V20 |V21 |V22 |V23 |V24 |V25 |V26 |V27 |V28 |V29 |V30 |V31 |V32 |V33 |V34 |V35 |V36 |V37 |V38 |V39 |V40 |V41 |V42 |V43 |V44 |V45 |V46 |V47 |V48 |V49 |V50 |V51 |V52 |V53 |V54 |V55 |V56 |V57 |V58 |V59 |V60 |V61 |V62 |V63 |V64 |V65 |V66 |V67 |V68 |V69 |V70 |V71 |V72 |
+|:--|:--|:--|:--|:--|:--|:--|:--|:--|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|
+^D
+| V1 | V2 | V3 | V4 | V5 | V6 | V7 | V8 | V9 | V10 | V11 | V12 | V13 | V14 | V15 | V16 | V17 | V18 | V19 | V20 | V21 | V22 | V23 | V24 | V25 | V26 | V27 | V28 | V29 | V30 | V31 | V32 | V33 | V34 | V35 | V36 | V37 | V38 | V39 | V40 | V41 | V42 | V43 | V44 | V45 | V46 | V47 | V48 | V49 | V50 | V51 | V52 | V53 | V54 | V55 | V56 | V57 | V58 | V59 | V60 | V61 | V62 | V63 | V64 | V65 | V66 | V67 | V68 | V69 | V70 | V71 | V72 |
+|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|
+```
diff --git a/documents/markdown/pandoc-md/9350.md b/documents/markdown/pandoc-md/9350.md
new file mode 100644
index 0000000..cbb6ba9
--- /dev/null
+++ b/documents/markdown/pandoc-md/9350.md
@@ -0,0 +1,14 @@
+```
+% pandoc -f html -t latex
+<table><tbody><tr></tr></tbody></table>
+^D
+{\def\LTcaptype{none} % do not increment counter
+\begin{longtable}[]{@{}l@{}}
+\toprule\noalign{}
+\endhead
+\bottomrule\noalign{}
+\endlastfoot
+ \\
+\end{longtable}
+}
+```
diff --git a/documents/markdown/pandoc-md/9358.md b/documents/markdown/pandoc-md/9358.md
new file mode 100644
index 0000000..80f0cb9
--- /dev/null
+++ b/documents/markdown/pandoc-md/9358.md
@@ -0,0 +1,45 @@
+Caption belongs to the second table:
+```
+% pandoc -f docx -t html command/9358.docx
+^D
+<p>Lorem gipsum</p>
+<table>
+<colgroup>
+<col style="width: 50%" />
+<col style="width: 50%" />
+</colgroup>
+<thead>
+<tr>
+<th>A</th>
+<th>B</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>C</td>
+<td>D</td>
+</tr>
+</tbody>
+</table>
+<p>Lorem ipsum</p>
+<table>
+<caption><p>Table 1 Numbers from 1 to 4</p></caption>
+<colgroup>
+<col style="width: 50%" />
+<col style="width: 50%" />
+</colgroup>
+<thead>
+<tr>
+<th>1</th>
+<th>2</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>3</td>
+<td>4</td>
+</tr>
+</tbody>
+</table>
+<p>Lorem yipsum</p>
+```
diff --git a/documents/markdown/pandoc-md/9366.md b/documents/markdown/pandoc-md/9366.md
new file mode 100644
index 0000000..52d4592
--- /dev/null
+++ b/documents/markdown/pandoc-md/9366.md
@@ -0,0 +1,34 @@
+```
+% pandoc -f native -t latex
+[ Para
+ [ Strikeout
+ [ Link
+ ( "" , [] , [] )
+ [ Str "Example" ]
+ ( "https://example.com" , "" )
+ ]
+ ]
+, Para
+ [ Strikeout
+ [ Link
+ ( "" , [] , [] )
+ [ Str "https://example.com" ]
+ ( "https://example.com" , "" )
+ ]
+ ]
+, Para
+ [ Strikeout
+ [ Link
+ ( "" , [] , [] )
+ [ Str "info@example.com" ]
+ ( "mailto:info@example.com" , "" )
+ ]
+ ]
+]
+^D
+\st{\mbox{\href{https://example.com}{Example}}}
+
+\st{\mbox{\url{https://example.com}}}
+
+\st{\mbox{\href{mailto:info@example.com}{\nolinkurl{info@example.com}}}}
+```
diff --git a/documents/markdown/pandoc-md/9371.md b/documents/markdown/pandoc-md/9371.md
new file mode 100644
index 0000000..bb34f87
--- /dev/null
+++ b/documents/markdown/pandoc-md/9371.md
@@ -0,0 +1,30 @@
+```
+% pandoc -t latex
+"'In this case (A),
+
+I get a kern to separate the quotes,' he said."
+
+"'Also in this case (B), I get a kern,' he added."
+
+"'But in this case (C), there is no kern,'
+
+he continued."
+
+"He concluded,
+
+'Nor in this case (D) is there a kern.'"
+^D
+``\,'In this case (A),
+
+I get a kern to separate the quotes,' he said.''
+
+``\,`Also in this case (B), I get a kern,' he added.''
+
+``\,`But in this case (C), there is no kern,'
+
+he continued.''
+
+``He concluded,
+
+`Nor in this case (D) is there a kern.'\,''
+```
diff --git a/documents/markdown/pandoc-md/9386.md b/documents/markdown/pandoc-md/9386.md
new file mode 100644
index 0000000..043fb30
--- /dev/null
+++ b/documents/markdown/pandoc-md/9386.md
@@ -0,0 +1,17 @@
+```
+% pandoc -t typst --wrap=preserve
+A string of text that is long enough that after 73 chars that includes a
+/ slash creates a newline
+^D
+A string of text that is long enough that after 73 chars that includes a
+\/ slash creates a newline
+```
+
+```
+% pandoc -t typst --wrap=preserve
+A string of text that is long enough that after 73 chars that includes
+a / slash creates a newline
+^D
+A string of text that is long enough that after 73 chars that includes
+a / slash creates a newline
+```
diff --git a/documents/markdown/pandoc-md/9387.md b/documents/markdown/pandoc-md/9387.md
new file mode 100644
index 0000000..89b849f
--- /dev/null
+++ b/documents/markdown/pandoc-md/9387.md
@@ -0,0 +1,23 @@
+```
+% pandoc -f html -t typst
+<div id="my label">
+<p>test</p>
+</div>
+<p>See <a href="#my label">my label</a>.</p>
+^D
+#block[
+test
+
+] #label("my label")
+See #link(label("my label"))[my label].
+
+```
+
+```
+% pandoc -f latex -t typst
+\cite{10.1117/12.695309}
+\cite{foo}
+^D
+#cite(label("10.1117/12.695309")) @foo
+
+```
diff --git a/documents/markdown/pandoc-md/9388.md b/documents/markdown/pandoc-md/9388.md
new file mode 100644
index 0000000..6423b40
--- /dev/null
+++ b/documents/markdown/pandoc-md/9388.md
@@ -0,0 +1,21 @@
+```
+% pandoc -f latex -t native
+\begin{figure}
+\centering
+\includegraphics[width=0.5\linewidth,height=0.5\textheight]{figures/placeholder}
+\caption{Example figure}
+\end{figure}
+^D
+[ Figure
+ ( "" , [] , [] )
+ (Caption
+ Nothing [ Plain [ Str "Example" , Space , Str "figure" ] ])
+ [ Plain
+ [ Image
+ ( "" , [] , [ ( "width" , "50%" ) , ( "height" , "50%" ) ] )
+ []
+ ( "figures/placeholder" , "" )
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/9391.md b/documents/markdown/pandoc-md/9391.md
new file mode 100644
index 0000000..f28c9a7
--- /dev/null
+++ b/documents/markdown/pandoc-md/9391.md
@@ -0,0 +1,9 @@
+```
+% pandoc command/9391.docx -t html
+^D
+<p>Lorem ipsum.</p>
+<figure>
+<img src="media/image1.png" style="width:1.10263in;height:1.10263in" />
+<figcaption><p>Blue square.</p></figcaption>
+</figure>
+```
diff --git a/documents/markdown/pandoc-md/9420.md b/documents/markdown/pandoc-md/9420.md
new file mode 100644
index 0000000..db9a8dd
--- /dev/null
+++ b/documents/markdown/pandoc-md/9420.md
@@ -0,0 +1,13 @@
+```
+% pandoc --embed-resources
+{.inline-svg}
+^D
+<p><svg id="svg_e1815ef374a63cf552e4" role="img" width="504pt" height="360pt" viewBox="0 0 504 360">
+<defs>
+<clipPath id="svg_e1815ef374a63cf552e4_clip1-c3ce354c">
+ <path />
+</clipPath>
+</defs>
+<g clip-path="url(#svg_e1815ef374a63cf552e4_clip1-c3ce354c)" clip-rule="nonzero"></g>
+</svg></p>
+```
diff --git a/documents/markdown/pandoc-md/9452.md b/documents/markdown/pandoc-md/9452.md
new file mode 100644
index 0000000..902e468
--- /dev/null
+++ b/documents/markdown/pandoc-md/9452.md
@@ -0,0 +1,19 @@
+```
+% pandoc -t typst
+@something2024 says blah.
+
+Here is a sentence [@something2024].
+
+With supplement [@something2024, p. 3].
+
+And just the year [-@something2024].
+^D
+#cite(<something2024>, form: "prose") says blah.
+
+Here is a sentence @something2024.
+
+With supplement @something2024[p.~3].
+
+And just the year (#cite(<something2024>, form: "year")).
+
+```
diff --git a/documents/markdown/pandoc-md/9467.md b/documents/markdown/pandoc-md/9467.md
new file mode 100644
index 0000000..bfdbc74
--- /dev/null
+++ b/documents/markdown/pandoc-md/9467.md
@@ -0,0 +1,7 @@
+```
+% pandoc --embed-resources
+
+^D
+<p><img role="img" src="data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTkiIHN0YW5kYWxvbmU9Im5vIj8+CjwhLS0gQ3JlYXRlZCB3aXRoIElua3NjYXBlIChodHRwOi8vd3d3Lmlua3NjYXBlLm9yZy8pIC0tPgoKPHN2ZwogICB2ZXJzaW9uPSIxLjEiIGlkPSJzdmcyIiB3aWR0aD0iMTkxLjU2MjY3IiBoZWlnaHQ9IjE1MS43MTIwMSIgdmlld0JveD0iMCAwIDE5MS41NjI2NyAxNTEuNzEyMDEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6c3ZnPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CiAgPGRlZnMgaWQ9ImRlZnM2Ij4KICAgIDxjbGlwUGF0aCBjbGlwUGF0aFVuaXRzPSJ1c2VyU3BhY2VPblVzZSIgaWQ9ImNsaXBQYXRoMjQiPgogICAgICA8cGF0aCBkPSJNIDU2LjY5MzYyLDAgMTEzLjM4NzI0LDExMy4zODcyNCAxNzAuMDgwODYsMCBaIiBpZD0icGF0aDIyIiAvPgogICAgPC9jbGlwUGF0aD4KICAgIDxjbGlwUGF0aCBjbGlwUGF0aFVuaXRzPSJ1c2VyU3BhY2VPblVzZSIgaWQ9ImNsaXBQYXRoMzgiPgogICAgICA8cGF0aCBkPSJNIDAsMCBIIDEwMCBWIDEwMCBIIDAgWiIgaWQ9InBhdGgzNiIgLz4KICAgIDwvY2xpcFBhdGg+CiAgICA8cmFkaWFsR3JhZGllbnQgZng9IjUwLjAwMDY0MSIgZnk9IjUwLjAwMDY0MSIgY3g9IjUwLjAwMDY0MSIgY3k9IjUwLjAwMDY0MSIgcj0iNTAuMDAwNjQxIiBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSIgaWQ9InJhZGlhbEdyYWRpZW50NDYiPgogICAgICA8c3RvcCBzdHlsZT0ic3RvcC1vcGFjaXR5OjE7c3RvcC1jb2xvcjojZmZmZmZmIiBvZmZzZXQ9IjAiIGlkPSJzdG9wNDAiIC8+CiAgICAgIDxzdG9wIHN0eWxlPSJzdG9wLW9wYWNpdHk6MTtzdG9wLWNvbG9yOiM5OTk5ZmYiIG9mZnNldD0iMjUuMDAwMzIiIGlkPSJzdG9wNDIiIC8+CiAgICAgIDxzdG9wIHN0eWxlPSJzdG9wLW9wYWNpdHk6MTtzdG9wLWNvbG9yOiM5OTk5ZmYiIG9mZnNldD0iNTAuMDAwNjQiIGlkPSJzdG9wNDQiIC8+CiAgICA8L3JhZGlhbEdyYWRpZW50PgogIDwvZGVmcz4KICA8ZyBpZD0iZzgiIHRyYW5zZm9ybT0ibWF0cml4KDEuMzMzMzMzMywwLDAsLTEuMzMzMzMzMywwLDE1MS43MTIpIj4KICAgIDxnIGlkPSJnMTAiIHRyYW5zZm9ybT0idHJhbnNsYXRlKC0yNi42MDYsMC4xOTkpIj4KICAgICAgPGcgaWQ9ImcxMiI+CiAgICAgICAgPGcgaWQ9ImcxNCI+CiAgICAgICAgICA8ZyBpZD0iZzE2Ij4KICAgICAgICAgICAgPGcgaWQ9ImcxOCI+CiAgICAgICAgICAgICAgPGcgaWQ9ImcyMCIgY2xpcC1wYXRoPSJ1cmwoI2NsaXBQYXRoMjQpIj4KICAgICAgICAgICAgICAgIDxnIGlkPSJnMjYiIHRyYW5zZm9ybT0ibWF0cml4KDIuMjY4MDIsMCwwLDIuMjY4MDIsMTEzLjM4NzI0LDU2LjY5MzYyKSI+CiAgICAgICAgICAgICAgICAgIDxnIGlkPSJnMjgiPgogICAgICAgICAgICAgICAgICAgIDxnIGlkPSJnMzAiIHRyYW5zZm9ybT0idHJhbnNsYXRlKC01MCwtNTApIj4KICAgICAgICAgICAgICAgICAgICAgIDxnIGlkPSJnMzIiPgogICAgICAgICAgICAgICAgICAgICAgICA8ZyBpZD0iZzM0IiBjbGlwLXBhdGg9InVybCgjY2xpcFBhdGgzOCkiPgogICAgICAgICAgICAgICAgICAgICAgICAgIDxwYXRoIGQ9Ik0gMCwwIEggMTAwIFYgMTAwIEggMCBaIiBzdHlsZT0iZmlsbDp1cmwoI3JhZGlhbEdyYWRpZW50NDYpO3N0cm9rZTpub25lIiBpZD0icGF0aDQ4IiAvPgogICAgICAgICAgICAgICAgICAgICAgICA8L2c+CiAgICAgICAgICAgICAgICAgICAgICA8L2c+CiAgICAgICAgICAgICAgICAgICAgPC9nPgogICAgICAgICAgICAgICAgICA8L2c+CiAgICAgICAgICAgICAgICA8L2c+CiAgICAgICAgICAgICAgPC9nPgogICAgICAgICAgICA8L2c+CiAgICAgICAgICAgIDxwYXRoIGQ9Ik0gNTYuNjkzNjIsMCAxMTMuMzg3MjQsMTEzLjM4NzI0IDE3MC4wODA4NiwwIFoiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiM5OTk5ZmY7c3Ryb2tlLXdpZHRoOjAuMzk4NTtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS1saW5lam9pbjptaXRlcjtzdHJva2UtbWl0ZXJsaW1pdDoxMDtzdHJva2UtZGFzaGFycmF5Om5vbmU7c3Ryb2tlLW9wYWNpdHk6MSIgaWQ9InBhdGg1MCIgLz4KICAgICAgICAgICAgPGcgaWQ9Imc1MiI+CiAgICAgICAgICAgICAgPGcgaWQ9Imc1NCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNjMuMzM3LDUuNDU3KSI+CiAgICAgICAgICAgICAgICA8ZyBpZD0iZzU2Ij4KICAgICAgICAgICAgICAgICAgPGcgaWQ9Imc1OCIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoLTM2LjczMSwtNS42NTYpIj4KICAgICAgICAgICAgICAgICAgICA8dGV4dCB4bWw6c3BhY2U9InByZXNlcnZlIiB0cmFuc2Zvcm09Im1hdHJpeCgxLDAsMCwtMSwzNi43MzEsNS42NTYpIiBzdHlsZT0iZm9udC12YXJpYW50Om5vcm1hbDtmb250LXdlaWdodDpub3JtYWw7Zm9udC1zaXplOjkuOTYyNnB4O2ZvbnQtZmFtaWx5OkNNU1MxMDstaW5rc2NhcGUtZm9udC1zcGVjaWZpY2F0aW9uOkNNU1MxMDt3cml0aW5nLW1vZGU6bHItdGI7ZmlsbDojOTk5OWZmO2ZpbGwtb3BhY2l0eToxO2ZpbGwtcnVsZTpub256ZXJvO3N0cm9rZTpub25lIiBpZD0idGV4dDYyIj48dHNwYW4geD0iMCA0Ljk4MTI5OTkgOC4zODU1MiAxMy4xNzM1NDYgMTguMzIxMjIyIDIwLjcwMTI4NiAyNS4xMjg2NjYgMzAuMjc2MzQgMzcuMTkxMzgzIDQxLjAxMDA0OCA0Ni4xNTc3MjIgNTAuOTQ1NzQ3IDU2LjA5MzQyMiA2MC41MjA4MDIgNjguOTk1OTg3IDcyLjU5MzQ4MyA3NS45OTc3MDQgNzguMzc3NzY5IDgzLjE2NTc5NCA4OC4zMDM1MDUgOTMuMjg0ODA1IDk1LjY2NDg3MSIgeT0iMCIgaWQ9InRzcGFuNjAiPmdyYWRpZW50c2hhZGVkdHJpYW5nbGU8L3RzcGFuPjwvdGV4dD4KICAgICAgICAgICAgICAgICAgICA8ZyBpZD0iZzY0IiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgzNi43MzEsNS42NTYpIiAvPgogICAgICAgICAgICAgICAgICA8L2c+CiAgICAgICAgICAgICAgICA8L2c+CiAgICAgICAgICAgICAgICA8ZyBpZD0iZzY2IiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgtNjMuMzM3LC01LjQ1NykiIC8+CiAgICAgICAgICAgICAgPC9nPgogICAgICAgICAgICA8L2c+CiAgICAgICAgICA8L2c+CiAgICAgICAgPC9nPgogICAgICA8L2c+CiAgICA8L2c+CiAgPC9nPgo8L3N2Zz4K" /></p>
+
+```
diff --git a/documents/markdown/pandoc-md/9472.md b/documents/markdown/pandoc-md/9472.md
new file mode 100644
index 0000000..0f65ecc
--- /dev/null
+++ b/documents/markdown/pandoc-md/9472.md
@@ -0,0 +1,85 @@
+```
+% pandoc -t latex -s
+---
+lang: de-DE
+---
+
+More text in English. ['Zitat auf Deutsch.']{lang=de}
+
+[Bonjour]{lang=fr} [café]{lang="fr-FR"}
+^D
+% Options for packages loaded elsewhere
+\PassOptionsToPackage{unicode}{hyperref}
+\PassOptionsToPackage{hyphens}{url}
+\documentclass[
+ french,
+ ngerman,
+]{article}
+\usepackage{xcolor}
+\usepackage{amsmath,amssymb}
+\setcounter{secnumdepth}{-\maxdimen} % remove section numbering
+\usepackage{iftex}
+\ifPDFTeX
+ \usepackage[T1]{fontenc}
+ \usepackage[utf8]{inputenc}
+ \usepackage{textcomp} % provide euro and other symbols
+\else % if luatex or xetex
+ \usepackage{unicode-math} % this also loads fontspec
+ \defaultfontfeatures{Scale=MatchLowercase}
+ \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
+\fi
+\usepackage{lmodern}
+\ifPDFTeX\else
+ % xetex/luatex font selection
+\fi
+% Use upquote if available, for straight quotes in verbatim environments
+\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
+\IfFileExists{microtype.sty}{% use microtype if available
+ \usepackage[]{microtype}
+ \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
+}{}
+\makeatletter
+\@ifundefined{KOMAClassName}{% if non-KOMA class
+ \IfFileExists{parskip.sty}{%
+ \usepackage{parskip}
+ }{% else
+ \setlength{\parindent}{0pt}
+ \setlength{\parskip}{6pt plus 2pt minus 1pt}}
+}{% if KOMA class
+ \KOMAoptions{parskip=half}}
+\makeatother
+\ifLuaTeX
+\usepackage[bidi=basic,shorthands=off]{babel}
+\else
+\usepackage[bidi=default,shorthands=off]{babel}
+\fi
+\ifLuaTeX
+ \usepackage{selnolig} % disable illegal ligatures
+\fi
+\setlength{\emergencystretch}{3em} % prevent overfull lines
+\providecommand{\tightlist}{%
+ \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
+\usepackage{bookmark}
+\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available
+\urlstyle{same}
+% fallback for those not using the hyperref driver hyperxmp:
+\makeatletter
+\@ifundefined{xmpquote}{\newcommand{\xmpquote}[1]{#1}}{}
+\makeatother
+\hypersetup{
+ pdflang={de-DE},
+ hidelinks,
+ pdfcreator={LaTeX via pandoc}}
+
+\author{}
+\date{}
+
+\begin{document}
+
+More text in English. \foreignlanguage{ngerman}{`Zitat auf Deutsch.'}
+
+\foreignlanguage{french}{Bonjour} \foreignlanguage{french}{café}
+
+\end{document}
+
+```
diff --git a/documents/markdown/pandoc-md/9475.md b/documents/markdown/pandoc-md/9475.md
new file mode 100644
index 0000000..c3f355f
--- /dev/null
+++ b/documents/markdown/pandoc-md/9475.md
@@ -0,0 +1,102 @@
+```
+% pandoc -f org -t native
+#+begin_note
+Useful note.
+#+end_note
+
+#+begin_warning
+Be careful!
+#+end_warning
+
+#+begin_tip
+Try this...
+#+end_tip
+
+#+begin_caution
+Caution
+#+end_caution
+
+#+name: foo
+#+begin_important
+Important
+#+end_important
+^D
+[ Div
+ ( "" , [ "note" ] , [] )
+ [ Div ( "" , [ "title" ] , [] ) [ Para [ Str "Note" ] ]
+ , Para [ Str "Useful" , Space , Str "note." ]
+ ]
+, Div
+ ( "" , [ "warning" ] , [] )
+ [ Div ( "" , [ "title" ] , [] ) [ Para [ Str "Warning" ] ]
+ , Para [ Str "Be" , Space , Str "careful!" ]
+ ]
+, Div
+ ( "" , [ "tip" ] , [] )
+ [ Div ( "" , [ "title" ] , [] ) [ Para [ Str "Tip" ] ]
+ , Para [ Str "Try" , Space , Str "this\8230" ]
+ ]
+, Div
+ ( "" , [ "caution" ] , [] )
+ [ Div ( "" , [ "title" ] , [] ) [ Para [ Str "Caution" ] ]
+ , Para [ Str "Caution" ]
+ ]
+, Div
+ ( "foo" , [ "important" ] , [] )
+ [ Div ( "" , [ "title" ] , [] ) [ Para [ Str "Important" ] ]
+ , Para [ Str "Important" ]
+ ]
+]
+
+```
+
+```
+% pandoc -f native -t org
+[ Div
+ ( "" , [ "note" ] , [] )
+ [ Div ( "" , [ "title" ] , [] ) [ Para [ Str "Note" ] ]
+ , Para [ Str "Useful" , Space , Str "note." ]
+ ]
+, Div
+ ( "" , [ "warning" ] , [] )
+ [ Div ( "" , [ "title" ] , [] ) [ Para [ Str "Warning" ] ]
+ , Para [ Str "Be" , Space , Str "careful!" ]
+ ]
+, Div
+ ( "" , [ "tip" ] , [] )
+ [ Div ( "" , [ "title" ] , [] ) [ Para [ Str "Tip" ] ]
+ , Para [ Str "Try" , Space , Str "this\8230" ]
+ ]
+, Div
+ ( "" , [ "caution" ] , [] )
+ [ Div ( "" , [ "title" ] , [] ) [ Para [ Str "Caution" ] ]
+ , Para [ Str "Caution" ]
+ ]
+, Div
+ ( "foo" , [ "important" ] , [] )
+ [ Div ( "" , [ "title" ] , [] ) [ Para [ Str "Important" ] ]
+ , Para [ Str "Important" ]
+ ]
+]
+^D
+#+begin_note
+Useful note.
+#+end_note
+
+#+begin_warning
+Be careful!
+#+end_warning
+
+#+begin_tip
+Try this...
+#+end_tip
+
+#+begin_caution
+Caution
+#+end_caution
+
+#+name: foo
+#+begin_important
+Important
+#+end_important
+```
diff --git a/documents/markdown/pandoc-md/9481.md b/documents/markdown/pandoc-md/9481.md
new file mode 100644
index 0000000..552f3dd
--- /dev/null
+++ b/documents/markdown/pandoc-md/9481.md
@@ -0,0 +1,7 @@
+```
+% pandoc -f markdown+wikilinks_title_after_pipe
+[a](https://example.com)
+^D
+<p><a href="https://example.com">a</a></p>
+
+```
diff --git a/documents/markdown/pandoc-md/9516.md b/documents/markdown/pandoc-md/9516.md
new file mode 100644
index 0000000..a719e60
--- /dev/null
+++ b/documents/markdown/pandoc-md/9516.md
@@ -0,0 +1,17 @@
+```
+% pandoc --number-sections
+# One {-}
+
+# Two
+
+# Three {-}
+
+# Four
+^D
+<h1 class="unnumbered" id="one">One</h1>
+<h1 data-number="1" id="two"><span
+class="header-section-number">1</span> Two</h1>
+<h1 class="unnumbered" id="three">Three</h1>
+<h1 data-number="2" id="four"><span
+class="header-section-number">2</span> Four</h1>
+```
diff --git a/documents/markdown/pandoc-md/9517.md b/documents/markdown/pandoc-md/9517.md
new file mode 100644
index 0000000..bc2c41e
--- /dev/null
+++ b/documents/markdown/pandoc-md/9517.md
@@ -0,0 +1,34 @@
+```
+% pandoc -f latex+raw_tex -t native
+\begin{tabular}{l}
+\begin{theorem}
+Cats
+\end{theorem}
+\end{tabular}
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignLeft , ColWidthDefault ) ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ RawBlock
+ (Format "latex")
+ "\\begin{theorem}\nCats\n\\end{theorem}"
+ ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
diff --git a/documents/markdown/pandoc-md/9555.md b/documents/markdown/pandoc-md/9555.md
new file mode 100644
index 0000000..0c9b0d5
--- /dev/null
+++ b/documents/markdown/pandoc-md/9555.md
@@ -0,0 +1,13 @@
+```
+% pandoc -t native -f latex
+a\@ b\@c
+
+\makeatletter
+a\@ b\@c
+\makeatother
+a\@ b\@c
+^D
+[ Para [ Str "a" , Space , Str "bc" ]
+, Para [ Str "ab" , SoftBreak , Str "a" , Space , Str "bc" ]
+]
+```
diff --git a/documents/markdown/pandoc-md/9569.md b/documents/markdown/pandoc-md/9569.md
new file mode 100644
index 0000000..edbe2e3
--- /dev/null
+++ b/documents/markdown/pandoc-md/9569.md
@@ -0,0 +1,19 @@
+```
+% pandoc -f docbook -t gfm
+<note>
+ <para>Some content</para>
+</note>
+<para>Spacer.</para>
+<note>
+ <title>A note with a title. Works, but the title is discarded.</title>
+ <para>Some content</para>
+</note>
+^D
+> [!NOTE]
+> Some content
+
+Spacer.
+
+> [!NOTE]
+> Some content
+```
diff --git a/documents/markdown/pandoc-md/9576.md b/documents/markdown/pandoc-md/9576.md
new file mode 100644
index 0000000..e529a8f
--- /dev/null
+++ b/documents/markdown/pandoc-md/9576.md
@@ -0,0 +1,23 @@
+```
+% pandoc -t native
+::: {#something}
+Text with a footnote.[^3]
+
+[^3]: A footnote.
+:::
+^D
+[ Div
+ ( "something" , [] , [] )
+ [ Para
+ [ Str "Text"
+ , Space
+ , Str "with"
+ , Space
+ , Str "a"
+ , Space
+ , Str "footnote."
+ , Note [ Para [ Str "A" , Space , Str "footnote." ] ]
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/9579.md b/documents/markdown/pandoc-md/9579.md
new file mode 100644
index 0000000..6ebd719
--- /dev/null
+++ b/documents/markdown/pandoc-md/9579.md
@@ -0,0 +1,46 @@
+```
+% pandoc -t native
+\begin{tabular}{p{2in}}
+\end{tabular}
+
+# Test
+
+\begin{tabular}{p{2\linewidth}}
+\end{tabular}
+^D
+[ RawBlock
+ (Format "tex") "\\begin{tabular}{p{2in}}\n\\end{tabular}"
+, Header 1 ( "test" , [] , [] ) [ Str "Test" ]
+, RawBlock
+ (Format "tex")
+ "\\begin{tabular}{p{2\\linewidth}}\n\\end{tabular}"
+]
+```
+
+```
+% pandoc -f latex -t native
+\begin{tabular}{p{2in}}
+\end{tabular}
+
+Test
+
+\begin{tabular}{p{2\linewidth}}
+\end{tabular}
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignLeft , ColWidthDefault ) ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody ( "" , [] , [] ) (RowHeadColumns 0) [] [] ]
+ (TableFoot ( "" , [] , [] ) [])
+, Para [ Str "Test" ]
+, Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignLeft , ColWidth 2.0 ) ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody ( "" , [] , [] ) (RowHeadColumns 0) [] [] ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
diff --git a/documents/markdown/pandoc-md/9585.md b/documents/markdown/pandoc-md/9585.md
new file mode 100644
index 0000000..a4d26ba
--- /dev/null
+++ b/documents/markdown/pandoc-md/9585.md
@@ -0,0 +1,11 @@
+```
+% pandoc -f native -t typst
+[ Header 2 ( "" , [] , [] ) [ Str "One" ]
+, Header 2 ( "" , [ "unnumbered", "unlisted" ] , [] ) [ Str "Two" ]
+, Header 2 ( "" , [] , [] ) [ Str "Three" ]
+]
+^D
+== One
+#heading(level: 2, outlined: false, numbering: none)[Two]
+== Three
+```
diff --git a/documents/markdown/pandoc-md/9603.md b/documents/markdown/pandoc-md/9603.md
new file mode 100644
index 0000000..fda2a77
--- /dev/null
+++ b/documents/markdown/pandoc-md/9603.md
@@ -0,0 +1,23 @@
+```
+% pandoc command/9603.docx -t html -f docx+styles
+^D
+<p>A table with a contemporary style:</p>
+<table data-custom-style="TableContemporary">
+<colgroup>
+<col style="width: 50%" />
+<col style="width: 50%" />
+</colgroup>
+<thead>
+<tr>
+<th>Test</th>
+<th>Column</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>1</td>
+<td>2</td>
+</tr>
+</tbody>
+</table>
+```
diff --git a/documents/markdown/pandoc-md/9616.md b/documents/markdown/pandoc-md/9616.md
new file mode 100644
index 0000000..5b7fb76
--- /dev/null
+++ b/documents/markdown/pandoc-md/9616.md
@@ -0,0 +1,16 @@
+```
+% pandoc -f bibtex -t csljson -s
+@MISC {3252037,
+ TITLE = {Isomorphism between projective varieties $\mathbf{P}^{1}$ and a conic in $\mathbf{P}^{2}$},
+ URL = {https://math.stackexchange.com/q/3252037}
+}
+^D
+[
+ {
+ "URL": "https://math.stackexchange.com/q/3252037",
+ "id": "3252037",
+ "title": "Isomorphism between projective varieties $\\mathbf{P}^{1}$ and a conic in $\\mathbf{P}^{2}$",
+ "type": ""
+ }
+]
+```
diff --git a/documents/markdown/pandoc-md/9630.md b/documents/markdown/pandoc-md/9630.md
new file mode 100644
index 0000000..af1ea59
--- /dev/null
+++ b/documents/markdown/pandoc-md/9630.md
@@ -0,0 +1,12 @@
+```
+% pandoc -f dokuwiki
+ * [[https://example.com|https://example.com]]
+ * [[https://example.com/start#monitoring|https://example.com/start#monitoring]]
+^D
+<ul>
+<li><a href="https://example.com">https://example.com</a></li>
+<li><a
+href="https://example.com/start#monitoring">https://example.com/start#monitoring</a></li>
+</ul>
+
+```
diff --git a/documents/markdown/pandoc-md/9632.md b/documents/markdown/pandoc-md/9632.md
new file mode 100644
index 0000000..aed6f77
--- /dev/null
+++ b/documents/markdown/pandoc-md/9632.md
@@ -0,0 +1,7 @@
+```
+% pandoc -f dokuwiki
+[[.:supprimer-profil-windows|]]
+^D
+<p><a href="supprimer-profil-windows">supprimer-profil-windows</a></p>
+
+```
diff --git a/documents/markdown/pandoc-md/9635.md b/documents/markdown/pandoc-md/9635.md
new file mode 100644
index 0000000..088a5b6
--- /dev/null
+++ b/documents/markdown/pandoc-md/9635.md
@@ -0,0 +1,16 @@
+```
+% pandoc
+> ::: {.fence}
+> that is
+> not closed
+
+okay
+^D
+2> [WARNING] Div at _chunk line 1 column 1 unclosed at _chunk line 5 column 1, closing implicitly.
+<blockquote>
+<div class="fence">
+<p>that is not closed</p>
+</div>
+</blockquote>
+<p>okay</p>
+```
diff --git a/documents/markdown/pandoc-md/9639.md b/documents/markdown/pandoc-md/9639.md
new file mode 100644
index 0000000..e7107a5
--- /dev/null
+++ b/documents/markdown/pandoc-md/9639.md
@@ -0,0 +1,11 @@
+```
+% pandoc -f org -t native
+#+title: repro
+
+* heading-name
+:PROPERTIES:
+:ID: 123abc
+:END:
+^D
+[ Header 1 ( "123abc" , [] , [] ) [ Str "heading-name" ] ]
+```
diff --git a/documents/markdown/pandoc-md/9652.md b/documents/markdown/pandoc-md/9652.md
new file mode 100644
index 0000000..10c7205
--- /dev/null
+++ b/documents/markdown/pandoc-md/9652.md
@@ -0,0 +1,9 @@
+````
+% pandoc -f markdown -t html --embed-resources
+```{=html}
+<img class="something inline-svg" src="command/9652.svg" />
+```
+^D
+<svg id="svg_b627f92299158b36552b" role="img" width="504.00pt" height="360.00pt" viewBox="0 0 504.00 360.00" class="something inline-svg please-do-not-delete-me">
+</svg>
+````
diff --git a/documents/markdown/pandoc-md/9657.md b/documents/markdown/pandoc-md/9657.md
new file mode 100644
index 0000000..a3da54b
--- /dev/null
+++ b/documents/markdown/pandoc-md/9657.md
@@ -0,0 +1,7 @@
+```
+% pandoc -t opendocument
+[Text here]{custom-style="Strikethrough"}
+^D
+<text:p text:style-name="Text_20_body"><text:span text:style-name="Strikethrough">Text
+here</text:span></text:p>
+```
diff --git a/documents/markdown/pandoc-md/9676.md b/documents/markdown/pandoc-md/9676.md
new file mode 100644
index 0000000..248ab60
--- /dev/null
+++ b/documents/markdown/pandoc-md/9676.md
@@ -0,0 +1,9 @@
+```
+% pandoc -f latex
+\def\foo{BAR}
+\foo
+\ifstrequal{BAR}{BAR}{\def\foo{BAZ}}{}
+\foo
+^D
+<p>BAR BAZ</p>
+```
diff --git a/documents/markdown/pandoc-md/9700.md b/documents/markdown/pandoc-md/9700.md
new file mode 100644
index 0000000..f018164
--- /dev/null
+++ b/documents/markdown/pandoc-md/9700.md
@@ -0,0 +1,14 @@
+```
+% pandoc -t mediawiki
+This is a normal sentence with a manual text footnote\*
+
+\* The footnote explains why it couldn't just be inside parentheses
+
+\#foobar \#foobar
+^D
+This is a normal sentence with a manual text footnote*
+
+\* The footnote explains why it couldn’t just be inside parentheses
+
+\#foobar #foobar
+```
diff --git a/documents/markdown/pandoc-md/9716.md b/documents/markdown/pandoc-md/9716.md
new file mode 100644
index 0000000..4f340ae
--- /dev/null
+++ b/documents/markdown/pandoc-md/9716.md
@@ -0,0 +1,13 @@
+```
+% pandoc -f markdown+alerts -t native
+> [!TIP]
+> A suggestion.
+^D
+[ Div
+ ( "" , [ "tip" ] , [] )
+ [ Div ( "" , [ "title" ] , [] ) [ Para [ Str "Tip" ] ]
+ , Para [ Str "A" , Space , Str "suggestion." ]
+ ]
+]
+
+```
diff --git a/documents/markdown/pandoc-md/9777-b.md b/documents/markdown/pandoc-md/9777-b.md
new file mode 100644
index 0000000..3c44cf8
--- /dev/null
+++ b/documents/markdown/pandoc-md/9777-b.md
@@ -0,0 +1,62 @@
+```
+% pandoc -f native -t typst
+[ Table
+ ( "" , [] , [ ( "typst:figure:kind" , "figure" ) ] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "f" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "b" ] ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "2" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+^D
+#figure(
+ align(center)[#table(
+ columns: 2,
+ align: (auto,auto,),
+ table.header([f], [b],),
+ table.hline(),
+ [1], [2],
+ )]
+ , kind: figure
+ )
+```
+
diff --git a/documents/markdown/pandoc-md/9777.md b/documents/markdown/pandoc-md/9777.md
new file mode 100644
index 0000000..346f2b2
--- /dev/null
+++ b/documents/markdown/pandoc-md/9777.md
@@ -0,0 +1,58 @@
+```
+% pandoc -f native -t typst
+[ Table
+ ( "" , [ "typst:no-figure" ] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "f" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "b" ] ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "2" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+^D
+#table(
+ columns: 2,
+ align: (auto,auto,),
+ table.header([f], [b],),
+ table.hline(),
+ [1], [2],
+)
+```
diff --git a/documents/markdown/pandoc-md/9792.md b/documents/markdown/pandoc-md/9792.md
new file mode 100644
index 0000000..88ffeb6
--- /dev/null
+++ b/documents/markdown/pandoc-md/9792.md
@@ -0,0 +1,21 @@
+```
+% pandoc -t gfm
+- list item
+ <details>
+
+ - subitem
+ </details>
+
+ item _continue_ **with** formatting
+- next list item
+^D
+- list item
+ <details>
+
+ - subitem
+
+ </details>
+
+ item *continue* **with** formatting
+- next list item
+```
diff --git a/documents/markdown/pandoc-md/9797.md b/documents/markdown/pandoc-md/9797.md
new file mode 100644
index 0000000..b3c5622
--- /dev/null
+++ b/documents/markdown/pandoc-md/9797.md
@@ -0,0 +1,39 @@
+```
+% pandoc -t native -f csv
+"one_line_break:
+four_line_breaks:
+
+
+
+last_line"
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault ) ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain
+ [ Str "one_line_break:"
+ , LineBreak
+ , Str "four_line_breaks:"
+ , LineBreak
+ , LineBreak
+ , LineBreak
+ , LineBreak
+ , Str "last_line"
+ ]
+ ]
+ ]
+ ])
+ [ TableBody ( "" , [] , [] ) (RowHeadColumns 0) [] [] ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
diff --git a/documents/markdown/pandoc-md/9805.md b/documents/markdown/pandoc-md/9805.md
new file mode 100644
index 0000000..01b2863
--- /dev/null
+++ b/documents/markdown/pandoc-md/9805.md
@@ -0,0 +1,10 @@
+```
+% pandoc -f rst -t native
+word.*word
+------------
+* abc
+^D
+[ Header 1 ( "word.word" , [] , [] ) [ Str "word.*word" ]
+, BulletList [ [ Plain [ Str "abc" ] ] ]
+]
+```
diff --git a/documents/markdown/pandoc-md/9807.md b/documents/markdown/pandoc-md/9807.md
new file mode 100644
index 0000000..e5663fa
--- /dev/null
+++ b/documents/markdown/pandoc-md/9807.md
@@ -0,0 +1,13 @@
+```
+% pandoc -f typst -t native
+#let foo = [
+ bar baz
+]
+*#foo*
+^D
+[ Para
+ [ Strong
+ [ SoftBreak , Str "bar" , Space , Str "baz" , SoftBreak ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/9809.md b/documents/markdown/pandoc-md/9809.md
new file mode 100644
index 0000000..8879364
--- /dev/null
+++ b/documents/markdown/pandoc-md/9809.md
@@ -0,0 +1,14 @@
+```
+% pandoc -f html -t native
+<ul>
+ <li>Bullet point.</li>
+ <p>Nested line.</p>
+</ul>
+^D
+[ BulletList
+ [ [ Para [ Str "Bullet" , Space , Str "point." ]
+ , Para [ Str "Nested" , Space , Str "line." ]
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/982.md b/documents/markdown/pandoc-md/982.md
new file mode 100644
index 0000000..bc18fc1
--- /dev/null
+++ b/documents/markdown/pandoc-md/982.md
@@ -0,0 +1,15 @@
+```
+% pandoc -f latex -t native
+\newcommand{\BEQ}{\begin{equation}}
+\newcommand{\EEQ}{\end{equation}}
+
+\BEQ
+y=x^2
+\EEQ
+^D
+[ Para
+ [ Math
+ DisplayMath "\\begin{equation}\ny=x^2\n\\end{equation}"
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/9865.md b/documents/markdown/pandoc-md/9865.md
new file mode 100644
index 0000000..5641629
--- /dev/null
+++ b/documents/markdown/pandoc-md/9865.md
@@ -0,0 +1,53 @@
+````
+% pandoc
+- example 1
+- ```
+ one
+ two
+ ```
+- list item three
+^D
+<ul>
+<li>example 1</li>
+<li><pre><code>one
+two</code></pre></li>
+<li>list item three</li>
+</ul>
+````
+
+````
+% pandoc
+- example 3
+- ```
+one
+two
+```
+- list item three
+^D
+<ul>
+<li>example 3</li>
+<li><pre><code>one
+two</code></pre></li>
+<li>list item three</li>
+</ul>
+````
+
+Here is a case that we used to handle differently, but
+#9865 aligns pandoc's markdown parser with commonmark in letting
+block level structure take precedence over inline level structure.
+
+````
+% pandoc
+- a <!--
+
+- b
+
+-->
+- c
+^D
+<ul>
+<li><p>a <!–</p></li>
+<li><p>b</p></li>
+</ul>
+<p>–> - c</p>
+````
diff --git a/documents/markdown/pandoc-md/987.md b/documents/markdown/pandoc-md/987.md
new file mode 100644
index 0000000..fc75d2c
--- /dev/null
+++ b/documents/markdown/pandoc-md/987.md
@@ -0,0 +1,12 @@
+```
+% pandoc -f latex -t markdown
+\documentclass{article}
+\newenvironment{flubble}{FOO}{BAR}
+\begin{document}
+ \begin{flubble}
+ grr
+ \end{flubble}
+\end{document}
+^D
+FOO grr BAR
+```
diff --git a/documents/markdown/pandoc-md/9878.md b/documents/markdown/pandoc-md/9878.md
new file mode 100644
index 0000000..da7bf99
--- /dev/null
+++ b/documents/markdown/pandoc-md/9878.md
@@ -0,0 +1,12 @@
+```
+% pandoc -f textile -t native
+15% 50%
+^D
+[ Para [ Str "15%" , Space , Str "50%" ] ]
+```
+```
+% pandoc -f textile -t native
+15%. 70%
+^D
+[ Para [ Str "15%." , Space , Str "70%" ] ]
+```
diff --git a/documents/markdown/pandoc-md/9902.md b/documents/markdown/pandoc-md/9902.md
new file mode 100644
index 0000000..e7122b5
--- /dev/null
+++ b/documents/markdown/pandoc-md/9902.md
@@ -0,0 +1,6 @@
+```
+% pandoc -t native -f latex+raw_tex
+\kern.1pt
+^D
+[ RawBlock (Format "latex") "\\kern.1pt" ]
+```
diff --git a/documents/markdown/pandoc-md/9904.md b/documents/markdown/pandoc-md/9904.md
new file mode 100644
index 0000000..8a50486
--- /dev/null
+++ b/documents/markdown/pandoc-md/9904.md
@@ -0,0 +1,180 @@
+```
+% pandoc -f rst -t native --citeproc --bibliography command/biblio.bib
+The axioms were introduced by :cite:t:`{see}item1`.
+The axioms were introduced by :cite:t:`item1{p. 1166}`.
+The axioms were introduced by :cite:t:`{see}item1{p. 1166}`.
+Axioms were introduced :cite:`{see}item1`.
+Axioms were introduced :cite:p:`item1{p. 1166}`.
+Axioms were introduced :cite:p:`{see}item1{p. 1166}`.
+
+.. bibliography::
+^D
+[ Para
+ [ Str "The"
+ , Space
+ , Str "axioms"
+ , Space
+ , Str "were"
+ , Space
+ , Str "introduced"
+ , Space
+ , Str "by"
+ , Space
+ , Cite
+ [ Citation
+ { citationId = "item1"
+ , citationPrefix = [ Str "see" ]
+ , citationSuffix = []
+ , citationMode = AuthorInText
+ , citationNoteNum = 0
+ , citationHash = 0
+ }
+ ]
+ [ Str "(see" , Space , Str "Doe;" , Space , Str "2005)" ]
+ , Str "."
+ , SoftBreak
+ , Str "The"
+ , Space
+ , Str "axioms"
+ , Space
+ , Str "were"
+ , Space
+ , Str "introduced"
+ , Space
+ , Str "by"
+ , Space
+ , Cite
+ [ Citation
+ { citationId = "item1"
+ , citationPrefix = []
+ , citationSuffix = [ Str "p." , Space , Str "1166" ]
+ , citationMode = AuthorInText
+ , citationNoteNum = 0
+ , citationHash = 0
+ }
+ ]
+ [ Str "Doe" , Space , Str "(2005," , Space , Str "1166)" ]
+ , Str "."
+ , SoftBreak
+ , Str "The"
+ , Space
+ , Str "axioms"
+ , Space
+ , Str "were"
+ , Space
+ , Str "introduced"
+ , Space
+ , Str "by"
+ , Space
+ , Cite
+ [ Citation
+ { citationId = "item1"
+ , citationPrefix = [ Str "see" ]
+ , citationSuffix = [ Str "p." , Space , Str "1166" ]
+ , citationMode = AuthorInText
+ , citationNoteNum = 0
+ , citationHash = 0
+ }
+ ]
+ [ Str "(see"
+ , Space
+ , Str "Doe;"
+ , Space
+ , Str "2005,"
+ , Space
+ , Str "1166)"
+ ]
+ , Str "."
+ , SoftBreak
+ , Str "Axioms"
+ , Space
+ , Str "were"
+ , Space
+ , Str "introduced"
+ , Space
+ , Cite
+ [ Citation
+ { citationId = "item1"
+ , citationPrefix = [ Str "see" ]
+ , citationSuffix = []
+ , citationMode = NormalCitation
+ , citationNoteNum = 0
+ , citationHash = 0
+ }
+ ]
+ [ Str "(see" , Space , Str "Doe" , Space , Str "2005)" ]
+ , Str "."
+ , SoftBreak
+ , Str "Axioms"
+ , Space
+ , Str "were"
+ , Space
+ , Str "introduced"
+ , Space
+ , Cite
+ [ Citation
+ { citationId = "item1"
+ , citationPrefix = []
+ , citationSuffix = [ Str "p." , Space , Str "1166" ]
+ , citationMode = NormalCitation
+ , citationNoteNum = 0
+ , citationHash = 0
+ }
+ ]
+ [ Str "(Doe" , Space , Str "2005," , Space , Str "1166)" ]
+ , Str "."
+ , SoftBreak
+ , Str "Axioms"
+ , Space
+ , Str "were"
+ , Space
+ , Str "introduced"
+ , Space
+ , Cite
+ [ Citation
+ { citationId = "item1"
+ , citationPrefix = [ Str "see" ]
+ , citationSuffix = [ Str "p." , Space , Str "1166" ]
+ , citationMode = NormalCitation
+ , citationNoteNum = 0
+ , citationHash = 0
+ }
+ ]
+ [ Str "(see"
+ , Space
+ , Str "Doe"
+ , Space
+ , Str "2005,"
+ , Space
+ , Str "1166)"
+ ]
+ , Str "."
+ ]
+, Div
+ ( "refs"
+ , [ "references" , "csl-bib-body" , "hanging-indent" ]
+ , []
+ )
+ [ Div
+ ( "ref-item1" , [ "csl-entry" ] , [] )
+ [ Para
+ [ Str "Doe,"
+ , Space
+ , Str "John."
+ , Space
+ , Str "2005."
+ , Space
+ , Emph [ Str "First" , Space , Str "Book" ]
+ , Str "."
+ , Space
+ , Str "Cambridge"
+ , Space
+ , Str "University"
+ , Space
+ , Str "Press."
+ ]
+ ]
+ ]
+]
+
+```
diff --git a/documents/markdown/pandoc-md/9905.md b/documents/markdown/pandoc-md/9905.md
new file mode 100644
index 0000000..02b506c
--- /dev/null
+++ b/documents/markdown/pandoc-md/9905.md
@@ -0,0 +1,20 @@
+```
+% pandoc -t html5
+# Section Ψ {#Ψ}
+
+look at [Section Ψ](#Ψ).
+^D
+<h1 id="Ψ">Section Ψ</h1>
+<p>look at <a href="#Ψ">Section Ψ</a>.</p>
+
+```
+```
+% pandoc -t html4
+# Section Ψ {#Ψ}
+
+look at [Section Ψ](#Ψ).
+^D
+<h1 id="Ψ">Section Ψ</h1>
+<p>look at <a href="#%CE%A8">Section Ψ</a>.</p>
+
+```
diff --git a/documents/markdown/pandoc-md/9908.md b/documents/markdown/pandoc-md/9908.md
new file mode 100644
index 0000000..a4aa2cd
--- /dev/null
+++ b/documents/markdown/pandoc-md/9908.md
@@ -0,0 +1,10 @@
+```
+% pandoc -f native -t markdown
+[ BulletList
+ [ [ BlockQuote [ Para [ Str "a" ] , Para [ Str "b" ] ] ] ]
+]
+^D
+- > a
+ >
+ > b
+```
diff --git a/documents/markdown/pandoc-md/9943.md b/documents/markdown/pandoc-md/9943.md
new file mode 100644
index 0000000..f4f2f01
--- /dev/null
+++ b/documents/markdown/pandoc-md/9943.md
@@ -0,0 +1,24 @@
+```
+% pandoc -t man -s -Vpandoc-version=X.Y
+---
+title: HELLO
+section: 1
+---
+^D
+.\" Automatically generated by Pandoc X.Y
+.\"
+.TH "HELLO" "1" "" ""
+```
+
+```
+% pandoc -t man -s -Vpandoc-version=X.Y
+---
+title: HELLO
+section: 1
+header: Head
+---
+^D
+.\" Automatically generated by Pandoc X.Y
+.\"
+.TH "HELLO" "1" "" "" "Head"
+```
diff --git a/documents/markdown/pandoc-md/9945.md b/documents/markdown/pandoc-md/9945.md
new file mode 100644
index 0000000..7615434
--- /dev/null
+++ b/documents/markdown/pandoc-md/9945.md
@@ -0,0 +1,28 @@
+```
+% pandoc -t typst --dpi 300
+{width=300 height=300}
+^D
+#box(image("image.jpg", height: 1in, width: 1in))
+```
+
+```
+% pandoc -t typst --dpi 600
+{width=300px height=300px}
+^D
+#box(image("image.jpg", height: 0.5in, width: 0.5in))
+```
+
+```
+% pandoc -t typst --dpi 600
+{width=1in height=3cm}
+^D
+#box(image("image.jpg", height: 3cm, width: 1in))
+```
+
+
+```
+% pandoc -t typst --dpi 600
+{.foo .bar baz=3}
+^D
+#box(image("image.jpg"))
+```
diff --git a/documents/markdown/pandoc-md/9953.md b/documents/markdown/pandoc-md/9953.md
new file mode 100644
index 0000000..3a2100e
--- /dev/null
+++ b/documents/markdown/pandoc-md/9953.md
@@ -0,0 +1,29 @@
+```
+% pandoc -f markdown -t native -s
+---
+header-includes: |
+ \makeatletter
+ \let\old@verbatim@font=\verbatim@font
+ \def\verbatim@font{%
+ \fontsize{10}{12}%
+ \old@verbatim@font
+ }
+ \makeatother
+...
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "header-includes"
+ , MetaBlocks
+ [ RawBlock
+ (Format "tex")
+ "\\makeatletter\n\\let\\old@verbatim@font=\\verbatim@font\n\\def\\verbatim@font{%\n\\fontsize{10}{12}%\n\\old@verbatim@font\n}\n\\makeatother"
+ ]
+ )
+ ]
+ }
+ []
+
+```
diff --git a/documents/markdown/pandoc-md/9987.md b/documents/markdown/pandoc-md/9987.md
new file mode 100644
index 0000000..7919906
--- /dev/null
+++ b/documents/markdown/pandoc-md/9987.md
@@ -0,0 +1,10 @@
+```
+% pandoc -f bibtex -t bibtex
+@misc{agency,
+ author = {{European Environment Agency}},
+}
+^D
+@misc{agency,
+ author = {{European Environment Agency}}
+}
+```
diff --git a/documents/markdown/pandoc-md/adjacent_latex_blocks.md b/documents/markdown/pandoc-md/adjacent_latex_blocks.md
new file mode 100644
index 0000000..4483d6e
--- /dev/null
+++ b/documents/markdown/pandoc-md/adjacent_latex_blocks.md
@@ -0,0 +1,10 @@
+```
+% pandoc -f markdown -t native
+\listoffigures
+
+\listoftables
+^D
+[ RawBlock (Format "tex") "\\listoffigures"
+, RawBlock (Format "tex") "\\listoftables"
+]
+```
diff --git a/documents/markdown/pandoc-md/alerts.md b/documents/markdown/pandoc-md/alerts.md
new file mode 100644
index 0000000..b11b604
--- /dev/null
+++ b/documents/markdown/pandoc-md/alerts.md
@@ -0,0 +1,55 @@
+```
+% pandoc -f rst -t gfm
+.. note::
+ This is my note.
+^D
+> [!NOTE]
+> This is my note.
+```
+
+```
+% pandoc -f gfm -t rst
+> [!WARNING]
+> Be careful!
+^D
+.. warning::
+
+ Be careful!
+```
+
+```
+% pandoc -f gfm -t asciidoc
+> [!TIP]
+> A tip.
+^D
+[TIP]
+====
+A tip.
+====
+```
+
+```
+% pandoc -f gfm -t docbook
+> [!TIP]
+> A tip.
+^D
+<tip>
+ <title>Tip</title>
+ <para>
+ A tip.
+ </para>
+</tip>
+```
+
+```
+% pandoc -f docbook -t gfm
+<tip>
+ <title>Tip</title>
+ <para>
+ A tip.
+ </para>
+</tip>
+^D
+> [!TIP]
+> A tip.
+```
diff --git a/documents/markdown/pandoc-md/ascii.md b/documents/markdown/pandoc-md/ascii.md
new file mode 100644
index 0000000..447289e
--- /dev/null
+++ b/documents/markdown/pandoc-md/ascii.md
@@ -0,0 +1,89 @@
+```
+% pandoc -t html --ascii
+äéıå
+^D
+<p>äéıå</p>
+```
+
+```
+% pandoc -t latex --ascii
+äéıå
+^D
+\"{a}\'{e}\i\r{a}
+```
+
+```
+% pandoc -t man --ascii
+äéıå
+^D
+.PP
+\(:a\('e\(.i\(oa
+```
+
+```
+% pandoc -t ms --ascii
+äéıå
+^D
+.LP
+\(:a\('e\(.i\(oa
+```
+
+```
+% pandoc -t docbook --ascii
+äéıå
+^D
+<para>
+ äéıå
+</para>
+```
+
+```
+% pandoc -t jats --ascii
+äéıå
+^D
+<p>äéıå</p>
+```
+
+```
+% pandoc -t markdown-smart --ascii
+"äéıå"
+^D
+“äéıå”
+```
+
+# CommonMark tests
+
+```
+% pandoc -f commonmark -t commonmark --ascii
+hello … ok? … bye
+^D
+hello … ok? … bye
+```
+
+```
+% pandoc -f commonmark+smart -t commonmark-smart --ascii --wrap=none
+"hi"...dog's breath---cat 5--6
+^D
+“hi”…dog’s breath—cat 5–6
+```
+
+```
+% pandoc -f commonmark+smart -t commonmark+smart --ascii
+"hi"...dog's breath---cat 5--6
+^D
+"hi"...dog's breath---cat 5--6
+```
+
+```
+% pandoc -f commonmark -t commonmark --ascii
+foo Ӓ bar
+^D
+foo Ӓ bar
+```
+
+```
+% pandoc -f commonmark -t commonmark --ascii
+\[foo\](bar)
+^D
+\[foo\](bar)
+```
diff --git a/documents/markdown/pandoc-md/author-in-text-move-note.md b/documents/markdown/pandoc-md/author-in-text-move-note.md
new file mode 100644
index 0000000..5ebe85b
--- /dev/null
+++ b/documents/markdown/pandoc-md/author-in-text-move-note.md
@@ -0,0 +1,19 @@
+```
+% pandoc --citeproc --csl command/chicago-fullnote-bibliography.csl -t plain
+---
+references:
+- id: foo
+ type: book
+ author: John Doe
+ title: A Book
+...
+
+See @foo [p. 21], as well.
+^D
+See John Doe,[1] as well.
+
+John Doe. A Book, n.d.
+
+[1] A Book, n.d., 21.
+```
+
diff --git a/documents/markdown/pandoc-md/basic.md b/documents/markdown/pandoc-md/basic.md
new file mode 100644
index 0000000..b798b13
--- /dev/null
+++ b/documents/markdown/pandoc-md/basic.md
@@ -0,0 +1,33 @@
+# Top-level title
+
+## Section
+
+### Subsection
+
+This *emphasized* **strong** `verbatim` markdown.
+See this [link](http://example.com/).
+
+Ordered list:
+
+ 1. one
+ 1. two
+ 1. three
+
+> Blockquote
+> is
+> for
+> citatons.
+
+ Code
+ block
+ is
+ for
+ code.
+
+~~Strikeout~~ is Pandoc's extension.
+Superscript and subscripts too: H~2~O is a liquid[^1].
+2^10^ is 1024.
+
+Math is another Pandoc extension: $E = m c^2$.
+
+[^1]: Sometimes.
diff --git a/documents/markdown/pandoc-md/biblatex-266.md b/documents/markdown/pandoc-md/biblatex-266.md
new file mode 100644
index 0000000..1887400
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-266.md
@@ -0,0 +1,34 @@
+```
+% pandoc -f biblatex -t markdown -s
+@book{goethe2005,
+ langid = {german},
+ location = {{Frankfurt am Main}},
+ title = {Not A Real Book},
+ date = {2005},
+ author = {family=Goethe, given=Johann Wolfgang, prefix=von, useprefix=false and given=Antonie, prefix=van, family=Leeuwenhoek, useprefix=true}, editor = {Schöne, Albrecht}
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- author:
+ - dropping-particle: von
+ family: Goethe
+ given: Johann Wolfgang
+ - family: Leeuwenhoek
+ given: Antonie
+ non-dropping-particle: van
+ editor:
+ - family: Schöne
+ given: Albrecht
+ id: goethe2005
+ issued: 2005
+ language: de-DE
+ publisher-place: Frankfurt am Main
+ title: Not A Real Book
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-aksin.md b/documents/markdown/pandoc-md/biblatex-aksin.md
new file mode 100644
index 0000000..96d5c49
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-aksin.md
@@ -0,0 +1,78 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Aksin et al. 2006)
+
+Aksin, Özge, Hayati Türkmen, Levent Artok, Bekir Çetinkaya, Chaoying Ni,
+Orhan Büyükgüngör, and Erhan Özkal. 2006. “Effect of Immobilization on
+Catalytic Characteristics of Saturated Pd-N-heterocyclic Carbenes in
+Mizoroki-Heck Reactions.” *J. Organomet. Chem.* 691 (13): 3027–3036.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Aksin et al., 2006)
+
+Aksin, Ö., Türkmen, H., Artok, L., Çetinkaya, B., Ni, C., Büyükgüngör,
+O., & Özkal, E. (2006). Effect of immobilization on catalytic
+characteristics of saturated Pd-N-heterocyclic carbenes in Mizoroki-Heck
+reactions. *J. Organomet. Chem.*, *691*(13), 3027–3036.
+
+
+}
+
+@string{ jomch = {J.~Organomet. Chem.} }
+
+@Article{aksin,
+ author = {Aks{\i}n, {\"O}zge and T{\"u}rkmen, Hayati and Artok, Levent
+ and {\c{C}}etinkaya, Bekir and Ni, Chaoying and
+ B{\"u}y{\"u}kg{\"u}ng{\"o}r, Orhan and {\"O}zkal, Erhan},
+ title = {Effect of immobilization on catalytic characteristics of
+ saturated {Pd-N}-heterocyclic carbenes in {Mizoroki-Heck}
+ reactions},
+ journaltitle = jomch,
+ date = 2006,
+ volume = 691,
+ number = 13,
+ pages = {3027-3036},
+ indextitle = {Effect of immobilization on catalytic characteristics},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- author:
+ - family: Aksın
+ given: Özge
+ - family: Türkmen
+ given: Hayati
+ - family: Artok
+ given: Levent
+ - family: Çetinkaya
+ given: Bekir
+ - family: Ni
+ given: Chaoying
+ - family: Büyükgüngör
+ given: Orhan
+ - family: Özkal
+ given: Erhan
+ container-title: J. Organomet. Chem.
+ id: aksin
+ issue: 13
+ issued: 2006
+ page: 3027-3036
+ title: Effect of immobilization on catalytic characteristics of
+ saturated Pd-N-heterocyclic carbenes in Mizoroki-Heck reactions
+ type: article-journal
+ volume: 691
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-almendro.md b/documents/markdown/pandoc-md/biblatex-almendro.md
new file mode 100644
index 0000000..415b4f7
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-almendro.md
@@ -0,0 +1,71 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Almendro et al. 1998)
+
+Almendro, José L., Jacinto Martín, Alberto Sánchez, and Fernando Nozal.
+1998. “Elektromagnetisches Signalhorn.”
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Almendro, Martín, Sánchez, & Nozal, 1998)
+
+Almendro, J. L., Martín, J., Sánchez, A., & Nozal, F. (1998).
+Elektromagnetisches Signalhorn.
+
+
+NOTES:
+
+- CSL styles’ handling of patent items needs to be improved
+
+}
+
+@Patent{almendro,
+ author = {Almendro, Jos{\'e} L. and Mart{\'i}n, Jacinto and S{\'a}nchez,
+ Alberto and Nozal, Fernando},
+ title = {Elektromagnetisches Signalhorn},
+ number = {EU-29702195U},
+ date = 1998,
+ location = {countryfr and countryuk and countryde},
+ hyphenation = {german},
+ annotation = {This is a patent entry with a location
+ field. The number is given in the number field. Note
+ the format of the location field in the database
+ file. Compare laufenberg, sorace, and
+ kowalik},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: This is a patent entry with a location field. The number is
+ given in the number field. Note the format of the location field in
+ the database file. Compare laufenberg, sorace, and kowalik
+ author:
+ - family: Almendro
+ given: José L.
+ - family: Martín
+ given: Jacinto
+ - family: Sánchez
+ given: Alberto
+ - family: Nozal
+ given: Fernando
+ id: almendro
+ issued: 1998
+ jurisdiction: France; United Kingdom; Germany
+ language: de-DE
+ number: EU-29702195U
+ title: Elektromagnetisches Signalhorn
+ type: patent
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-angenendt.md b/documents/markdown/pandoc-md/biblatex-angenendt.md
new file mode 100644
index 0000000..9f0c794
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-angenendt.md
@@ -0,0 +1,66 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Angenendt 2002)
+
+Angenendt, Arnold. 2002. “In Honore Salvatoris – Vom Sinn und Unsinn der
+Patrozinienkunde.” *Revue d’Histoire Ecclésiastique* 97: 431–456,
+791–823.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Angenendt, 2002)
+
+Angenendt, A. (2002). In Honore Salvatoris – Vom Sinn und Unsinn der
+Patrozinienkunde. *Revue d’Histoire Ecclésiastique*, *97*, 431–456,
+791–823.
+
+
+}
+
+@Article{angenendt,
+ author = {Angenendt, Arnold},
+ title = {In Honore Salvatoris~-- Vom Sinn und Unsinn der
+ Patrozinienkunde},
+ journaltitle = {Revue d'Histoire Eccl{\'e}siastique},
+ date = 2002,
+ volume = 97,
+ pages = {431--456, 791--823},
+ hyphenation = {german},
+ indextitle = {In Honore Salvatoris},
+ shorttitle = {In Honore Salvatoris},
+ annotation = {A German article in a French journal. Apart from that, a
+ typical article entry. Note the indextitle
+ field},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A German article in a French journal. Apart from that, a
+ typical article entry. Note the indextitle field
+ author:
+ - family: Angenendt
+ given: Arnold
+ container-title: Revue d'Histoire Eccl[é]{.nocase}siastique
+ id: angenendt
+ issued: 2002
+ language: de-DE
+ page: 431-456, 791-823
+ title: In Honore Salvatoris -- Vom Sinn und Unsinn der
+ Patrozinienkunde
+ title-short: In Honore Salvatoris
+ type: article-journal
+ volume: 97
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-aristotle-anima.md b/documents/markdown/pandoc-md/biblatex-aristotle-anima.md
new file mode 100644
index 0000000..ef0b595
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-aristotle-anima.md
@@ -0,0 +1,62 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Aristotle 1907)
+
+Aristotle. 1907. *De Anima*. Edited by Robert Drew Hicks. Cambridge:
+Cambridge University Press.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Aristotle, 1907)
+
+Aristotle. (1907). *De anima*. (R. D. Hicks, Ed.). Cambridge: Cambridge
+University Press.
+
+
+}
+
+@string{ cup = {Cambridge University Press} }
+
+@Book{aristotle:anima,
+ author = {Aristotle},
+ title = {De Anima},
+ date = 1907,
+ editor = {Hicks, Robert Drew},
+ publisher = cup,
+ location = {Cambridge},
+ keywords = {primary},
+ hyphenation = {british},
+ annotation = {A book entry with an author and an
+ editor},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A book entry with an author and an editor
+ author:
+ - family: Aristotle
+ editor:
+ - family: Hicks
+ given: Robert Drew
+ id: "aristotle:anima"
+ issued: 1907
+ keyword: primary
+ language: en-GB
+ publisher: Cambridge University Press
+ publisher-place: Cambridge
+ title: De anima
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-aristotle-physics.md b/documents/markdown/pandoc-md/biblatex-aristotle-physics.md
new file mode 100644
index 0000000..fe60500
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-aristotle-physics.md
@@ -0,0 +1,63 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Aristotle 1929)
+
+Aristotle. 1929. *Physics*. Translated by P. H. Wicksteed and F. M.
+Cornford. New York: G. P. Putnam.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Aristotle, 1929)
+
+Aristotle. (1929). *Physics*. (P. H. Wicksteed & F. M. Cornford,
+Trans.). New York: G. P. Putnam.
+
+
+}
+
+@Book{aristotle:physics,
+ author = {Aristotle},
+ title = {Physics},
+ date = 1929,
+ translator = {Wicksteed, P. H. and Cornford, F. M.},
+ publisher = {G. P. Putnam},
+ location = {New York},
+ keywords = {primary},
+ hyphenation = {american},
+ shorttitle = {Physics},
+ annotation = {A book entry with a translator field},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A book entry with a translator field
+ author:
+ - family: Aristotle
+ id: "aristotle:physics"
+ issued: 1929
+ keyword: primary
+ language: en-US
+ publisher: G. P. Putnam
+ publisher-place: New York
+ title: Physics
+ title-short: Physics
+ translator:
+ - family: Wicksteed
+ given: P. H.
+ - family: Cornford
+ given: F. M.
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-aristotle-poetics.md b/documents/markdown/pandoc-md/biblatex-aristotle-poetics.md
new file mode 100644
index 0000000..35d559b
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-aristotle-poetics.md
@@ -0,0 +1,65 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Aristotle 1968)
+
+Aristotle. 1968. *Poetics*. Edited by D. W. Lucas. Clarendon Aristotle.
+Oxford: Clarendon Press.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Aristotle, 1968)
+
+Aristotle. (1968). *Poetics*. (D. W. Lucas, Ed.). Oxford: Clarendon
+Press.
+
+
+}
+
+@Book{aristotle:poetics,
+ author = {Aristotle},
+ title = {Poetics},
+ date = 1968,
+ editor = {Lucas, D. W.},
+ series = {Clarendon {Aristotle}},
+ publisher = {Clarendon Press},
+ location = {Oxford},
+ keywords = {primary},
+ hyphenation = {british},
+ shorttitle = {Poetics},
+ annotation = {A book entry with an author and an
+ editor as well as a series field},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A book entry with an author and an editor as well as a series
+ field
+ author:
+ - family: Aristotle
+ collection-title: Clarendon Aristotle
+ editor:
+ - family: Lucas
+ given: D. W.
+ id: "aristotle:poetics"
+ issued: 1968
+ keyword: primary
+ language: en-GB
+ publisher: Clarendon Press
+ publisher-place: Oxford
+ title: Poetics
+ title-short: Poetics
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-aristotle-rhetoric.md b/documents/markdown/pandoc-md/biblatex-aristotle-rhetoric.md
new file mode 100644
index 0000000..60ac602
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-aristotle-rhetoric.md
@@ -0,0 +1,80 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Aristotle 1877)
+
+Aristotle. 1877. *The Rhetoric of Aristotle with a Commentary by the
+Late Edward Meredith Cope*. Edited by Edward Meredith Cope. 3. Cambridge
+University Press.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Aristotle, 1877)
+
+Aristotle. (1877). *The rhetoric of Aristotle with a commentary by the
+late Edward Meredith Cope*. (E. M. Cope, Ed.) (1-3). Cambridge
+University Press.
+
+
+NOTES:
+
+- biblio2yaml
+ - commentator has no counterpart in CSL
+
+}
+
+@string{ cup = {Cambridge University Press} }
+
+@Book{aristotle:rhetoric,
+ author = {Aristotle},
+ title = {The Rhetoric of {Aristotle} with a commentary by the late {Edward
+ Meredith Cope}},
+ date = 1877,
+ editor = {Cope, Edward Meredith},
+ commentator = {Cope, Edward Meredith},
+ volumes = 3,
+ publisher = cup,
+ keywords = {primary},
+ hyphenation = {british},
+ sorttitle = {Rhetoric of Aristotle},
+ indextitle = {Rhetoric of {Aristotle}, The},
+ shorttitle = {Rhetoric},
+ annotation = {A commented edition. Note the concatenation of the
+ editor and commentator fields as well as the
+ volumes, sorttitle, and indextitle
+ fields},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A commented edition. Note the concatenation of the editor and
+ commentator fields as well as the volumes, sorttitle, and indextitle
+ fields
+ author:
+ - family: Aristotle
+ editor:
+ - family: Cope
+ given: Edward Meredith
+ id: "aristotle:rhetoric"
+ issued: 1877
+ keyword: primary
+ language: en-GB
+ number-of-volumes: 3
+ publisher: Cambridge University Press
+ title: The rhetoric of Aristotle with a commentary by the late Edward
+ Meredith Cope
+ title-short: Rhetoric
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-article.md b/documents/markdown/pandoc-md/biblatex-article.md
new file mode 100644
index 0000000..68d4675
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-article.md
@@ -0,0 +1,128 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+ - contains:
+ - an article entry with just the required fields
+ - an article entry with required and all optional fields
+ - notes:
+ - year, month to be ignored if date is present
+ - journal to be ignored if journaltitle is present
+ - editortype, editoratype, editorbtype, editorctype, pubstate,
+series contain keys which, unless corresponding CSL terms exist, require
+locale-specific expansion
+ - limitations:
+ - annotator, commentator, eid, eprint, eprintclass, eprinttype,
+issuetitle, issuesubtitle, language, origlanguage have no matching
+counterparts in CSL
+ - for editor, editora, editorb, editorc (plus editortype,
+editoratype, editorbtype, editorctype) only a subset, editor and director,
+has matching counterparts in CSL
+ - kludges:
+ - note + addendum -> CSL note
+ - number + issue -> CSL issue
+ - handling of titleaddon
+ - handling of (journal) series
+ - done properly, this should be mapped to some CSL variable
+(version? edition? collection-number?), CSL styles would have to be adapted
+ - slightly better kludge would map integer to ordinal + "ser."
+("3" -> "3rd ser."); localization keys "newseries" -> "new ser.",
+"oldseries" -> "old ser."; and print all other values as is -- but still
+wouldn't fit all styles or locales.
+ }
+
+@article{article-req,
+ Author = {Author, Ann},
+ Date = {2013-07-29},
+ Hyphenation = {english},
+ Journaltitle = {The Journaltitle},
+ Title = {An Article Entry with Just the Required Fields}}
+
+@article{article-opt,
+ Addendum = {The Addendum},
+ Annotator = {Annotator, A.},
+ Author = {Author, Jr., Ann A.},
+ Commentator = {Commentator, C.},
+ Date = {2008-12-31},
+ Doi = {10.1086/520976},
+ Editor = {Editor, Edward},
+ Editora = {Editor, A.},
+ Editorb = {Editor, B.},
+ Editorc = {Editor, C.},
+ Eid = {eid},
+ Eprint = {eprint},
+ Eprintclass = {eprintclass},
+ Eprinttype = {eprinttype},
+ Hyphenation = {english},
+ Issn = {issn},
+ Issue = {issue},
+ Issuesubtitle = {The Issuesubtitle},
+ Issuetitle = {The Issuetitle},
+ Journalsubtitle = {The Journalsubtitle},
+ Journaltitle = {The Journaltitle},
+ Journal = {The Journal},
+ Language = {language},
+ Month = {08},
+ Year = {2007},
+ Note = {The Note},
+ Number = {number},
+ Origlanguage = {origlanguage},
+ Pages = {pages},
+ Pubstate = {inpress},
+ Series = {newseries},
+ Subtitle = {The Subtitle},
+ Title = {An Article Entry with the Required and All Optional Fields},
+ Titleaddon = {The Titleaddon},
+ Translator = {Translator, Ted},
+ Url = {http://foo.bar.baz/},
+ Urldate = {2013-07-29},
+ Version = {version},
+ Volume = {volume},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- author:
+ - family: Author
+ given: Ann
+ container-title: The Journaltitle
+ id: article-req
+ issued: 2013-07-29
+ language: en-US
+ title: An article entry with just the required fields
+ type: article-journal
+- accessed: 2013-07-29
+ author:
+ - family: Author
+ given: Ann A.
+ suffix: Jr.
+ collection-title: New series
+ container-title: "The Journaltitle: The Journalsubtitle"
+ doi: 10.1086/520976
+ editor:
+ - family: Editor
+ given: Edward
+ id: article-opt
+ issn: issn
+ issue: number, issue
+ issued: 2008-12-31
+ language: en-US
+ note: The Note. The Addendum
+ page: pages
+ status: in press
+ title: "An article entry with the required and all optional fields:
+ The subtitle. The titleaddon"
+ title-short: An article entry with the required and all optional
+ fields
+ translator:
+ - family: Translator
+ given: Ted
+ type: article-journal
+ url: "http://foo.bar.baz/"
+ version: version
+ volume: volume
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-augustine.md b/documents/markdown/pandoc-md/biblatex-augustine.md
new file mode 100644
index 0000000..e512870
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-augustine.md
@@ -0,0 +1,56 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Augustine 1995)
+
+Augustine, Robert L. 1995. *Heterogeneous Catalysis for the Synthetic
+Chemist*. New York: Marcel Dekker.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Augustine, 1995)
+
+Augustine, R. L. (1995). *Heterogeneous catalysis for the synthetic
+chemist*. New York: Marcel Dekker.
+
+
+}
+
+@Book{augustine,
+ author = {Augustine, Robert L.},
+ title = {Heterogeneous catalysis for the synthetic chemist},
+ date = 1995,
+ publisher = {Marcel Dekker},
+ location = {New York},
+ hyphenation = {american},
+ shorttitle = {Heterogeneous catalysis},
+ annotation = {A plain book entry},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A plain book entry
+ author:
+ - family: Augustine
+ given: Robert L.
+ id: augustine
+ issued: 1995
+ language: en-US
+ publisher: Marcel Dekker
+ publisher-place: New York
+ title: Heterogeneous catalysis for the synthetic chemist
+ title-short: Heterogeneous catalysis
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-averroes-bland.md b/documents/markdown/pandoc-md/biblatex-averroes-bland.md
new file mode 100644
index 0000000..7182222
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-averroes-bland.md
@@ -0,0 +1,85 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Averroes 1982)
+
+Averroes. 1982. *The Epistle on the Possibility of Conjunction with the
+Active Intellect by Ibn Rushd with the Commentary of Moses Narboni*.
+Kalman P. Bland. Moreshet: Studies in Jewish History, Literature and
+Thought 7. New York: Jewish Theological Seminary of America.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Averroes, 1982)
+
+Averroes. (1982). *The epistle on the possibility of conjunction with
+the active intellect by Ibn Rushd with the commentary of Moses Narboni*.
+(K. P. Bland). New York: Jewish Theological Seminary of America.
+
+
+NOTES:
+
+- citeproc
+ - term "edited and translated by" missing
+
+}
+
+@Book{averroes-bland,
+ author = {Averroes},
+ title = {The Epistle on the Possibility of Conjunction with the Active
+ Intellect by {Ibn Rushd} with the Commentary of {Moses Narboni}},
+ date = 1982,
+ editor = {Bland, Kalman P.},
+ translator = {Bland, Kalman P.},
+ series = {Moreshet: {Studies} in {Jewish} History, Literature and Thought},
+ number = 7,
+ publisher = {Jewish Theological Seminary of America},
+ location = {New York},
+ keywords = {primary},
+ hyphenation = {american},
+ indextitle = {Epistle on the Possibility of Conjunction, The},
+ shorttitle = {Possibility of Conjunction},
+ annotation = {A book entry with a series and a
+ number. Note the concatenation of the editor
+ and translator fields as well as the
+ indextitle field},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A book entry with a series and a number. Note the
+ concatenation of the editor and translator fields as well as the
+ indextitle field
+ author:
+ - family: Averroes
+ collection-number: 7
+ collection-title: "Moreshet: Studies in Jewish history, literature and
+ thought"
+ editor:
+ - family: Bland
+ given: Kalman P.
+ id: averroes-bland
+ issued: 1982
+ keyword: primary
+ language: en-US
+ publisher: Jewish Theological Seminary of America
+ publisher-place: New York
+ title: The epistle on the possibility of conjunction with the active
+ intellect by Ibn Rushd with the commentary of Moses Narboni
+ title-short: Possibility of conjunction
+ translator:
+ - family: Bland
+ given: Kalman P.
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-averroes-hannes.md b/documents/markdown/pandoc-md/biblatex-averroes-hannes.md
new file mode 100644
index 0000000..4f7b68a
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-averroes-hannes.md
@@ -0,0 +1,84 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Averroes 1892)
+
+Averroes. 1892. *Des Averroës Abhandlung: “Über die Möglichkeit der
+Conjunktion” oder “Über den materiellen Intellekt”*. Ludwig Hannes.
+Halle an der Saale: C. A. Kaemmerer.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Averroes, 1892)
+
+Averroes. (1892). *Des Averroës Abhandlung: “Über die Möglichkeit der
+Conjunktion” oder “Über den materiellen Intellekt”*. (L. Hannes). Halle
+an der Saale: C. A. Kaemmerer.
+
+
+NOTES:
+
+- citeproc
+ - term "edited and translated by" missing
+
+}
+
+@Book{averroes-hannes,
+ author = {Averroes},
+ title = {Des Averro{\"e}s Abhandlung: \mkbibquote{{\"U}ber die
+ M{\"o}glichkeit der Conjunktion} oder \mkbibquote{{\"U}ber den
+ materiellen Intellekt}},
+ date = 1892,
+ editor = {Hannes, Ludwig},
+ translator = {Hannes, Ludwig},
+ annotator = {Hannes, Ludwig},
+ publisher = {C.~A. Kaemmerer},
+ location = {Halle an der Saale},
+ keywords = {primary},
+ hyphenation = {german},
+ sorttitle = {Uber die Moglichkeit der Conjunktion},
+ indexsorttitle= {Uber die Moglichkeit der Conjunktion},
+ indextitle = {{\"U}ber die M{\"o}glichkeit der Conjunktion},
+ shorttitle = {{\"U}ber die M{\"o}glichkeit der Conjunktion},
+ annotation = {An annotated edition. Note the concatenation of the
+ editor, translator, and annotator
+ fields. Also note the shorttitle,
+ indextitle, sorttitle, and
+ indexsorttitle fields},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: An annotated edition. Note the concatenation of the editor,
+ translator, and annotator fields. Also note the shorttitle,
+ indextitle, sorttitle, and indexsorttitle fields
+ author:
+ - family: Averroes
+ editor:
+ - family: Hannes
+ given: Ludwig
+ id: averroes-hannes
+ issued: 1892
+ keyword: primary
+ language: de-DE
+ publisher: C. A. Kaemmerer
+ publisher-place: Halle an der Saale
+ title: "Des Averroës Abhandlung: \"Über die Möglichkeit der
+ Conjunktion\" oder \"Über den materiellen Intellekt\""
+ title-short: Über die Möglichkeit der Conjunktion
+ translator:
+ - family: Hannes
+ given: Ludwig
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-averroes-hercz.md b/documents/markdown/pandoc-md/biblatex-averroes-hercz.md
new file mode 100644
index 0000000..67a788e
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-averroes-hercz.md
@@ -0,0 +1,85 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Averroes 1869)
+
+Averroes. 1869. *Drei Abhandlungen über die Conjunction des separaten
+Intellects mit dem Menschen: Von Averroes (Vater und Sohn), aus dem
+Arabischen übersetzt von Samuel Ibn Tibbon*. J. Hercz. Berlin:
+S. Hermann.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Averroes, 1869)
+
+Averroes. (1869). *Drei Abhandlungen über die Conjunction des separaten
+Intellects mit dem Menschen: Von Averroes (Vater und Sohn), aus dem
+Arabischen übersetzt von Samuel Ibn Tibbon*. (J. Hercz). Berlin:
+S. Hermann.
+
+
+NOTES:
+
+- citeproc
+ - term "edited and translated by" missing
+
+}
+
+@Book{averroes-hercz,
+ author = {Averroes},
+ title = {Drei Abhandlungen {\"u}ber die Conjunction des separaten
+ Intellects mit dem Menschen},
+ date = 1869,
+ editor = {Hercz, J.},
+ translator = {Hercz, J.},
+ publisher = {S.~Hermann},
+ location = {Berlin},
+ keywords = {primary},
+ hyphenation = {german},
+ indexsorttitle= {Drei Abhandlungen uber die Conjunction},
+ indextitle = {Drei Abhandlungen {\"u}ber die Conjunction},
+ subtitle = {Von Averroes (Vater und Sohn), aus dem Arabischen
+ {\"u}bersetzt von Samuel Ibn Tibbon},
+ shorttitle = {Drei Abhandlungen},
+ annotation = {A book entry. Note the concatenation of the
+ editor and translator fields as well as the
+ indextitle and indexsorttitle fields},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A book entry. Note the concatenation of the editor and
+ translator fields as well as the indextitle and indexsorttitle
+ fields
+ author:
+ - family: Averroes
+ editor:
+ - family: Hercz
+ given: J.
+ id: averroes-hercz
+ issued: 1869
+ keyword: primary
+ language: de-DE
+ publisher: S. Hermann
+ publisher-place: Berlin
+ title: "Drei Abhandlungen über die Conjunction des separaten
+ Intellects mit dem Menschen: Von Averroes (Vater und Sohn), aus dem
+ Arabischen übersetzt von Samuel Ibn Tibbon"
+ title-short: Drei Abhandlungen
+ translator:
+ - family: Hercz
+ given: J.
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-baez-article.md b/documents/markdown/pandoc-md/biblatex-baez-article.md
new file mode 100644
index 0000000..ed3f830
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-baez-article.md
@@ -0,0 +1,76 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Baez and Lauda 2004)
+
+Baez, John C., and Aaron D. Lauda. 2004. “Higher-dimensional Algebra V:
+2-groups” (version 3). *Theory and Applications of Categories* 12:
+423–491.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Baez & Lauda, 2004)
+
+Baez, J. C., & Lauda, A. D. (2004). Higher-dimensional algebra V:
+2-groups. *Theory and Applications of Categories*, *12*, 423–491.
+
+
+NOTES:
+
+- biblio2yaml
+ - eprint: see baez-online
+
+}
+
+@Article{baez-article,
+ author = {Baez, John C. and Lauda, Aaron D.},
+ title = {Higher-Dimensional Algebra {V}: 2-Groups},
+ journaltitle = {Theory and Applications of Categories},
+ date = 2004,
+ volume = 12,
+ pages = {423-491},
+ version = 3,
+ eprint = {math/0307200v3},
+ eprinttype = {arxiv},
+ hyphenation = {american},
+ annotation = {An article with eprint and
+ eprinttype fields. Note that the arXiv reference is
+ transformed into a clickable link if hyperref support
+ has been enabled. Compare baez\slash online, which
+ is the same item given as an online entry},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: An article with eprint and eprinttype fields. Note that the
+ arXiv reference is transformed into a clickable link if hyperref
+ support has been enabled. Compare baez/online, which is the same
+ item given as an online entry
+ author:
+ - family: Baez
+ given: John C.
+ - family: Lauda
+ given: Aaron D.
+ container-title: Theory and Applications of Categories
+ id: baez-article
+ issued: 2004
+ language: en-US
+ page: 423-491
+ title: "Higher-dimensional algebra V: 2-groups"
+ title-short: Higher-dimensional algebra V
+ type: article-journal
+ url: "https://arxiv.org/abs/math/0307200v3"
+ version: 3
+ volume: 12
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-baez-online.md b/documents/markdown/pandoc-md/biblatex-baez-online.md
new file mode 100644
index 0000000..9b73b70
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-baez-online.md
@@ -0,0 +1,69 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Baez and Lauda 2004)
+
+Baez, John C., and Aaron D. Lauda. 2004. “Higher-dimensional Algebra V:
+2-groups” (version 3). October 27.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Baez & Lauda, 2004)
+
+Baez, J. C., & Lauda, A. D. (2004, October 27). Higher-dimensional
+algebra V: 2-groups.
+
+
+NOTES:
+
+- biblio2yaml:
+ - eprinttype = {arxiv}, eprint = {math/0307200v3},
+ should be converted to a url: http://arxiv.org/abs/math/0307200v3
+ (prefix http://arxiv.org/abs/ seems to work for all arxiv material)
+
+}
+
+@Online{baez-online,
+ author = {Baez, John C. and Lauda, Aaron D.},
+ title = {Higher-Dimensional Algebra {V}: 2-Groups},
+ date = {2004-10-27},
+ version = 3,
+ hyphenation = {american},
+ eprinttype = {arxiv},
+ eprint = {math/0307200v3},
+ annotation = {An online reference from arXiv. Note the
+ eprint and eprinttype fields. Compare
+ baez\slash article which is the same item given as an
+ article entry with eprint information},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: An online reference from arXiv. Note the eprint and eprinttype
+ fields. Compare baez/article which is the same item given as an
+ article entry with eprint information
+ author:
+ - family: Baez
+ given: John C.
+ - family: Lauda
+ given: Aaron D.
+ id: baez-online
+ issued: 2004-10-27
+ language: en-US
+ title: "Higher-dimensional algebra V: 2-groups"
+ title-short: Higher-dimensional algebra V
+ type: webpage
+ url: "https://arxiv.org/abs/math/0307200v3"
+ version: 3
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-basic.md b/documents/markdown/pandoc-md/biblatex-basic.md
new file mode 100644
index 0000000..8a11769
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-basic.md
@@ -0,0 +1,71 @@
+```
+% pandoc -f biblatex -t markdown -s
+@Book{item1,
+author="John Doe",
+title="First Book",
+year="2005",
+address="Cambridge",
+publisher="Cambridge University Press"
+}
+
+@Article{item2,
+author="John Doe",
+title="Article",
+year="2006",
+journal="Journal of Generic Studies",
+volume="6",
+pages="33-34"
+}
+
+@InCollection{пункт3,
+author="John Doe and Jenny Roe",
+title="Why Water Is Wet",
+booktitle="Third Book",
+editor="Sam Smith",
+publisher="Oxford University Press",
+address="Oxford",
+year="2007"
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- author:
+ - family: Doe
+ given: John
+ id: item1
+ issued: 2005
+ publisher: Cambridge University Press
+ publisher-place: Cambridge
+ title: First book
+ type: book
+- author:
+ - family: Doe
+ given: John
+ container-title: Journal of Generic Studies
+ id: item2
+ issued: 2006
+ page: 33-34
+ title: Article
+ type: article-journal
+ volume: 6
+- author:
+ - family: Doe
+ given: John
+ - family: Roe
+ given: Jenny
+ container-title: Third book
+ editor:
+ - family: Smith
+ given: Sam
+ id: пункт3
+ issued: 2007
+ publisher: Oxford University Press
+ publisher-place: Oxford
+ title: Why water is wet
+ type: chapter
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-bertram.md b/documents/markdown/pandoc-md/biblatex-bertram.md
new file mode 100644
index 0000000..bcf661e
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-bertram.md
@@ -0,0 +1,66 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Bertram and Wentworth 1996)
+
+Bertram, Aaron, and Richard Wentworth. 1996. “Gromov Invariants for
+Holomorphic Maps on Riemann Surfaces.” *J. Amer. Math. Soc.* 9 (2):
+529–571.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Bertram & Wentworth, 1996)
+
+Bertram, A., & Wentworth, R. (1996). Gromov invariants for holomorphic
+maps on Riemann surfaces. *J. Amer. Math. Soc.*, *9*(2), 529–571.
+
+
+}
+
+@string{ jams = {J.~Amer. Math. Soc.} }
+
+@Article{bertram,
+ author = {Bertram, Aaron and Wentworth, Richard},
+ title = {Gromov invariants for holomorphic maps on {Riemann} surfaces},
+ journaltitle = jams,
+ date = 1996,
+ volume = 9,
+ number = 2,
+ pages = {529-571},
+ hyphenation = {american},
+ shorttitle = {Gromov invariants},
+ annotation = {An article entry with a volume and a
+ number field},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: An article entry with a volume and a number field
+ author:
+ - family: Bertram
+ given: Aaron
+ - family: Wentworth
+ given: Richard
+ container-title: J. Amer. Math. Soc.
+ id: bertram
+ issue: 2
+ issued: 1996
+ language: en-US
+ page: 529-571
+ title: Gromov invariants for holomorphic maps on Riemann surfaces
+ title-short: Gromov invariants
+ type: article-journal
+ volume: 9
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-bibstring-resolution.md b/documents/markdown/pandoc-md/biblatex-bibstring-resolution.md
new file mode 100644
index 0000000..6f94898
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-bibstring-resolution.md
@@ -0,0 +1,20 @@
+```
+% pandoc -f biblatex -t markdown -s
+@book{item1,
+ Title = {The Title: \bibstring{newseries}},
+ Hyphenation = {english}
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- id: item1
+ language: en-US
+ title: "The title: New series"
+ title-short: The title
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-book-averroes.md b/documents/markdown/pandoc-md/biblatex-book-averroes.md
new file mode 100644
index 0000000..32e3c82
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-book-averroes.md
@@ -0,0 +1,129 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+adapted from
+http://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/examples/biblatex-examples.bib}
+
+@book{averroes/bland,
+ Annotation = {A book entry with a series and a number. Note the concatenation of the editor and translator fields as well as the indextitle field},
+ Author = {Averroes},
+ Date = 1982,
+ Editor = {Bland, Kalman P.},
+ Hyphenation = {american},
+ Indextitle = {Epistle on the Possibility of Conjunction, The},
+ Keywords = {primary},
+ Location = {New York},
+ Number = 7,
+ Publisher = {Jewish Theological Seminary of America},
+ Series = {{Moreshet: Studies in Jewish History, Literature and Thought}},
+ Shorttitle = {Possibility of Conjunction},
+ Title = {The Epistle on the Possibility of Conjunction with the Active Intellect by {Ibn Rushd} with the Commentary of {Moses Narboni}},
+ Translator = {Bland, Kalman P.}}
+
+@book{averroes/hannes,
+ Annotation = {An annotated edition. Note the concatenation of the editor, translator, and annotator fields. Also note the shorttitle, indextitle, sorttitle, and indexsorttitle fields},
+ Annotator = {Hannes, Ludwig},
+ Author = {Averroes},
+ Date = 1892,
+ Editor = {Hannes, Ludwig},
+ Hyphenation = {german},
+ Indexsorttitle = {Uber die Moglichkeit der Conjunktion},
+ Indextitle = {Über die Möglichkeit der Conjunktion},
+ Keywords = {primary},
+ Location = {Halle an der Saale},
+ Publisher = {C.~A. Kaemmerer},
+ Shorttitle = {Über die Möglichkeit der Conjunktion},
+ Sorttitle = {Uber die Moglichkeit der Conjunktion},
+ Title = {Des Averroës Abhandlung: \mkbibquote{Über die Möglichkeit der Conjunktion} oder \mkbibquote{Über den materiellen Intellekt}},
+ Translator = {Hannes, Ludwig}}
+
+@book{averroes/hercz,
+ Annotation = {A book entry. Note the concatenation of the editor and translator fields as well as the indextitle and indexsorttitle fields},
+ Author = {Averroes},
+ Date = 1869,
+ Editor = {Hercz, J.},
+ Hyphenation = {german},
+ Indexsorttitle = {Drei Abhandlungen uber die Conjunction},
+ Indextitle = {Drei Abhandlungen über die Conjunction},
+ Keywords = {primary},
+ Location = {Berlin},
+ Publisher = {S.~Hermann},
+ Shorttitle = {Drei Abhandlungen},
+ Subtitle = {Von Averroes (Vater und Sohn), aus dem Arabischen übersetzt von Samuel Ibn Tibbon},
+ Title = {Drei Abhandlungen über die Conjunction des separaten Intellects mit dem Menschen},
+ Translator = {Hercz, J.}}
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A book entry with a series and a number. Note the
+ concatenation of the editor and translator fields as well as the
+ indextitle field
+ author:
+ - family: Averroes
+ collection-number: 7
+ collection-title: "[Moreshet: Studies in Jewish History, Literature
+ and Thought]{.nocase}"
+ editor:
+ - family: Bland
+ given: Kalman P.
+ id: averroes/bland
+ issued: 1982
+ keyword: primary
+ language: en-US
+ publisher: Jewish Theological Seminary of America
+ publisher-place: New York
+ title: The epistle on the possibility of conjunction with the active
+ intellect by Ibn Rushd with the commentary of Moses Narboni
+ title-short: Possibility of conjunction
+ translator:
+ - family: Bland
+ given: Kalman P.
+ type: book
+- annote: An annotated edition. Note the concatenation of the editor,
+ translator, and annotator fields. Also note the shorttitle,
+ indextitle, sorttitle, and indexsorttitle fields
+ author:
+ - family: Averroes
+ editor:
+ - family: Hannes
+ given: Ludwig
+ id: averroes/hannes
+ issued: 1892
+ keyword: primary
+ language: de-DE
+ publisher: C. A. Kaemmerer
+ publisher-place: Halle an der Saale
+ title: "Des Averroës Abhandlung: \"Über die Möglichkeit der
+ Conjunktion\" oder \"Über den materiellen Intellekt\""
+ title-short: Über die Möglichkeit der Conjunktion
+ translator:
+ - family: Hannes
+ given: Ludwig
+ type: book
+- annote: A book entry. Note the concatenation of the editor and
+ translator fields as well as the indextitle and indexsorttitle
+ fields
+ author:
+ - family: Averroes
+ editor:
+ - family: Hercz
+ given: J.
+ id: averroes/hercz
+ issued: 1869
+ keyword: primary
+ language: de-DE
+ publisher: S. Hermann
+ publisher-place: Berlin
+ title: "Drei Abhandlungen über die Conjunction des separaten
+ Intellects mit dem Menschen: Von Averroes (Vater und Sohn), aus dem
+ Arabischen übersetzt von Samuel Ibn Tibbon"
+ title-short: Drei Abhandlungen
+ translator:
+ - family: Hercz
+ given: J.
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-book-coleridge.md b/documents/markdown/pandoc-md/biblatex-book-coleridge.md
new file mode 100644
index 0000000..855771f
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-book-coleridge.md
@@ -0,0 +1,59 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{adapted from http://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/examples/biblatex-examples.bib
+
+TODO (as a stopgap):
+Combine biblatex “volume = 7” and “part = 2” to CSL “volume: 7.2”
+
+}
+
+@book{coleridge,
+ Annotation = {One (partial) volume of a multivolume book. This is a book entry with a volume and a part field which explicitly refers to the second (physical) part of the seventh (logical) volume. Also note the series and number fields},
+ Author = {Coleridge, Samuel Taylor},
+ Date = 1983,
+ Editor = {Coburn, Kathleen and Engell, James and Bate, W. Jackson},
+ Hyphenation = {british},
+ Indextitle = {Biographia literaria},
+ Location = {London},
+ Maintitle = {The collected works of {Samuel Taylor Coleridge}},
+ Number = 75,
+ Part = 2,
+ Publisher = {Routledge {and} Kegan Paul},
+ Series = {Bollingen Series},
+ Shorttitle = {Biographia literaria},
+ Title = {Biographia literaria, or {Biographical} sketches of my literary life and opinions},
+ Volume = 7}
+^D
+---
+nocite: "[@*]"
+references:
+- annote: One (partial) volume of a multivolume book. This is a book
+ entry with a volume and a part field which explicitly refers to the
+ second (physical) part of the seventh (logical) volume. Also note
+ the series and number fields
+ author:
+ - family: Coleridge
+ given: Samuel Taylor
+ collection-number: 75
+ collection-title: Bollingen series
+ editor:
+ - family: Coburn
+ given: Kathleen
+ - family: Engell
+ given: James
+ - family: Bate
+ given: W. Jackson
+ id: coleridge
+ issued: 1983
+ language: en-GB
+ publisher: Routledge and Kegan Paul
+ publisher-place: London
+ title: The collected works of Samuel Taylor Coleridge
+ type: book
+ volume: 7.2
+ volume-title: Biographia literaria, or Biographical sketches of my
+ literary life and opinions
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-book-title-maintitle-series.md b/documents/markdown/pandoc-md/biblatex-book-title-maintitle-series.md
new file mode 100644
index 0000000..64a31f4
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-book-title-maintitle-series.md
@@ -0,0 +1,39 @@
+```
+% pandoc -f biblatex -t markdown -s
+@book{item1,
+ Author = {Author, Al},
+ Date = {2013},
+ Hyphenation = {french},
+ Location = {Location},
+ Mainsubtitle = {Mainsubtitle},
+ Maintitle = {Maintitle},
+ Maintitleaddon = {Maintitleaddon},
+ Number = {3},
+ Publisher = {Publisher},
+ Series = {Series},
+ Subtitle = {Subtitle},
+ Title = {Title of the Book},
+ Titleaddon = {Titleaddon},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- author:
+ - family: Author
+ given: Al
+ collection-number: 3
+ collection-title: Series
+ id: item1
+ issued: 2013
+ language: fr-FR
+ publisher: Publisher
+ publisher-place: Location
+ title: "Maintitle: Mainsubtitle. Maintitleaddon"
+ type: book
+ volume-title: "Title of the Book: Subtitle. Titleaddon"
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-book-vazques-de-parga.md b/documents/markdown/pandoc-md/biblatex-book-vazques-de-parga.md
new file mode 100644
index 0000000..ceb8a9e
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-book-vazques-de-parga.md
@@ -0,0 +1,48 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{excerpted from http://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/examples/biblatex-examples.bib
+
+Note handling of Author = {Vázques{ de }Parga, Luis}
+
+}
+
+@book{vazques-de-parga,
+ Annotation = {A multivolume book cited as a whole. This is a book entry with volumes, note, sorttitle, and indextitle fields},
+ Author = {Vázques{ de }Parga, Luis and Lacarra, José María and Uría Ríu, Juan},
+ Date = 1993,
+ Hyphenation = {spanish},
+ Indextitle = {Peregrinaciones a Santiago de Compostela, Las},
+ Location = {Pamplona},
+ Note = {Ed. facs. de la realizada en 1948--49},
+ Publisher = {Iberdrola},
+ Shorttitle = {Peregrinaciones},
+ Sorttitle = {Peregrinaciones a Santiago de Compostela},
+ Title = {Las Peregrinaciones a Santiago de Compostela},
+ Volumes = 3}
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A multivolume book cited as a whole. This is a book entry with
+ volumes, note, sorttitle, and indextitle fields
+ author:
+ - family: Vázques de Parga
+ given: Luis
+ - family: Lacarra
+ given: José María
+ - family: Uría Ríu
+ given: Juan
+ id: vazques-de-parga
+ issued: 1993
+ language: es-ES
+ note: Ed. facs. de la realizada en 1948--49
+ number-of-volumes: 3
+ publisher: Iberdrola
+ publisher-place: Pamplona
+ title: Las Peregrinaciones a Santiago de Compostela
+ title-short: Peregrinaciones
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-brandt.md b/documents/markdown/pandoc-md/biblatex-brandt.md
new file mode 100644
index 0000000..2c542d8
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-brandt.md
@@ -0,0 +1,88 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Brandt and Hoffmann 1987)
+
+Brandt, Ahasver von, and Erich Hoffmann. 1987. “Die nordischen Länder
+von der Mitte des 11. Jahrhunderts bis 1448.” In *Europa im Hoch- und
+Spätmittelalter*, edited by Ferdinand Seibt, 884–917. Handbuch der
+europäischen Geschichte 2. Stuttgart: Klett-Cotta.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Brandt & Hoffmann, 1987)
+
+Brandt, A. von, & Hoffmann, E. (1987). Die nordischen Länder von der
+Mitte des 11. Jahrhunderts bis 1448. In F. Seibt (ed.), *Europa im Hoch-
+und Spätmittelalter* (pp. 884–917). Stuttgart: Klett-Cotta.
+
+
+}
+
+@InCollection{brandt,
+ author = {von Brandt, Ahasver and Erich Hoffmann},
+ editor = {Ferdinand Seibt},
+ title = {Die nordischen L{\"a}nder von der Mitte des 11.~Jahrhunderts
+ bis 1448},
+ date = 1987,
+ booktitle = {Europa im Hoch- und Sp{\"a}tmittelalter},
+ series = {Handbuch der europ{\"a}ischen Geschichte},
+ number = 2,
+ publisher = {Klett-Cotta},
+ location = {Stuttgart},
+ pages = {884-917},
+ options = {useprefix=false},
+ hyphenation = {german},
+ indexsorttitle= {Nordischen Lander von der Mitte des 11. Jahrhunderts bis
+ 1448},
+ indextitle = {Nordischen L{\"a}nder von der Mitte des 11.~Jahrhunderts bis
+ 1448, Die},
+ shorttitle = {Die nordischen L{\"a}nder},
+ annotation = {An incollection entry with a series and a
+ number. Note the format of the printed name and
+ compare the useprefix option in the options
+ field as well as vangennep. Also note the
+ indextitle, and indexsorttitle fields},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: An incollection entry with a series and a number. Note the
+ format of the printed name and compare the useprefix option in the
+ options field as well as vangennep. Also note the indextitle, and
+ indexsorttitle fields
+ author:
+ - dropping-particle: von
+ family: Brandt
+ given: Ahasver
+ - family: Hoffmann
+ given: Erich
+ collection-number: 2
+ collection-title: Handbuch der europäischen Geschichte
+ container-title: Europa im Hoch- und Spätmittelalter
+ editor:
+ - family: Seibt
+ given: Ferdinand
+ id: brandt
+ issued: 1987
+ language: de-DE
+ page: 884-917
+ publisher: Klett-Cotta
+ publisher-place: Stuttgart
+ title: Die nordischen Länder von der Mitte des 11. Jahrhunderts bis
+ 1448
+ title-short: Die nordischen Länder
+ type: chapter
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-britannica.md b/documents/markdown/pandoc-md/biblatex-britannica.md
new file mode 100644
index 0000000..37a3a07
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-britannica.md
@@ -0,0 +1,85 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Preece 2003)
+
+Preece, Warren E., ed. 2003. *The New EncyclopæDia Britannica*. 15th ed.
+32. Chicago, Ill.: Encyclopædia Britannica.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Preece, 2003)
+
+Preece, W. E. (Ed.). (2003). *The new encyclopædia Britannica* (15th
+ed., 1-32). Chicago, Ill.: Encyclopædia Britannica.
+
+
+NOTES:
+
+- biblio2yaml
+ - spurious <span> in Encyclopædia
+ - options = {useeditor=false} has no equivalent in CSL, so citing and alphabetizing by title even though there is an editor does not seem to be possible
+
+- citeproc
+ - incorrect camel case: "EncyclopæDia"
+ - term "vols." missing
+
+}
+
+@Collection{britannica,
+ editor = {Preece, Warren E.},
+ title = {The New Encyclop{\ae}dia {Britannica}},
+ date = 2003,
+ edition = 15,
+ volumes = 32,
+ publisher = {Encyclop{\ae}dia Britannica},
+ location = {Chicago, Ill.},
+ options = {useeditor=false},
+ label = {EB},
+ hyphenation = {british},
+ sorttitle = {Encyclop{\ae}dia Britannica},
+ indextitle = {Encyclop{\ae}dia Britannica, The New},
+ shorttitle = {Encyclop{\ae}dia {Britannica}},
+ annotation = {This is a collection entry for an encyclopedia. Note
+ the useeditor option in the options field as
+ well as the sorttitle field. We want this entry to be
+ cited and alphabetized by title even though there is an
+ editor. In addition to that, we want the title to be
+ alphabetized under \enquote*{E} rather than \enquote*{T}. Also
+ note the label field which is provided for
+ author-year citation styles},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: This is a collection entry for an encyclopedia. Note the
+ useeditor option in the options field as well as the sorttitle
+ field. We want this entry to be cited and alphabetized by title even
+ though there is an editor. In addition to that, we want the title to
+ be alphabetized under 'E' rather than 'T'. Also note the label field
+ which is provided for author-year citation styles
+ edition: 15
+ editor:
+ - family: Preece
+ given: Warren E.
+ id: britannica
+ issued: 2003
+ language: en-GB
+ number-of-volumes: 32
+ publisher: Encyclopædia Britannica
+ publisher-place: Chicago, Ill.
+ title: The new encyclopædia Britannica
+ title-short: Encyclopædia Britannica
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-chiu.md b/documents/markdown/pandoc-md/biblatex-chiu.md
new file mode 100644
index 0000000..cd21a06
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-chiu.md
@@ -0,0 +1,77 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Chiu and Chow 1978)
+
+Chiu, Willy W., and We Min Chow. 1978. “A Hybrid Hierarchical Model of a
+Multiple Virtual Storage (MVS) Operating System.” Research report
+RC-6947. IBM.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Chiu & Chow, 1978)
+
+Chiu, W. W., & Chow, W. M. (1978). *A hybrid hierarchical model of a
+multiple virtual storage (MVS) operating system* (research report No.
+RC-6947). IBM.
+
+
+NOTES:
+
+- biblio2yaml
+ - "MVS", when not wrapped in {}, gives "mVS", which is probably never intended, or useful (latex converts the whole word to lowercase if unprotected ("MVS" -> "mvs"))
+
+}
+
+@Report{chiu,
+ author = {Chiu, Willy W. and Chow, We Min},
+ title = {A Hybrid Hierarchical Model of a Multiple Virtual Storage
+ ({MVS}) Operating System},
+ type = {resreport},
+ institution = {IBM},
+ date = 1978,
+ number = {RC-6947},
+ hyphenation = {american},
+ sorttitle = {Hybrid Hierarchical Model of a Multiple Virtual Storage (MVS)
+ Operating System},
+ indextitle = {Hybrid Hierarchical Model, A},
+ annotation = {This is a report entry for a research report. Note
+ the format of the type field in the database file
+ which uses a localization key. The number of the report is
+ given in the number field. Also note the
+ sorttitle and indextitle fields},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: This is a report entry for a research report. Note the format
+ of the type field in the database file which uses a localization
+ key. The number of the report is given in the number field. Also
+ note the sorttitle and indextitle fields
+ author:
+ - family: Chiu
+ given: Willy W.
+ - family: Chow
+ given: We Min
+ genre: research report
+ id: chiu
+ issued: 1978
+ language: en-US
+ number: RC-6947
+ publisher: IBM
+ title: A hybrid hierarchical model of a multiple virtual storage (MVS)
+ operating system
+ type: report
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-cicero.md b/documents/markdown/pandoc-md/biblatex-cicero.md
new file mode 100644
index 0000000..57916a4
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-cicero.md
@@ -0,0 +1,82 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Cicero 1995)
+
+Cicero, Marcus Tullius. 1995. *De natura deorum. Über das Wesen der
+Götter*. Ursula Blank-Sangmeister. Stuttgart: Reclam.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Cicero, 1995)
+
+Cicero, M. T. (1995). *De natura deorum. Über das Wesen der Götter*. (U.
+Blank-Sangmeister). Stuttgart: Reclam.
+
+
+NOTES:
+
+- biblio2yaml
+ - afterword, language: no CSL variables available
+
+- citeproc:
+ - term such as "edited and translated by" should appear
+
+}
+
+@Book{cicero,
+ author = {Cicero, Marcus Tullius},
+ title = {De natura deorum. {\"U}ber das Wesen der G{\"o}tter},
+ date = 1995,
+ editor = {Blank-Sangmeister, Ursula},
+ translator = {Blank-Sangmeister, Ursula},
+ afterword = {Thraede, Klaus},
+ language = {langlatin and langgerman},
+ publisher = {Reclam},
+ location = {Stuttgart},
+ hyphenation = {german},
+ indextitle = {De natura deorum},
+ shorttitle = {De natura deorum},
+ annotation = {A bilingual edition of Cicero's \emph{De natura deorum}, with
+ a German translation. Note the format of the language
+ field in the database file, the concatenation of the
+ editor and translator fields, and the
+ afterword field},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A bilingual edition of Cicero's *De natura deorum*, with a
+ German translation. Note the format of the language field in the
+ database file, the concatenation of the editor and translator
+ fields, and the afterword field
+ author:
+ - family: Cicero
+ given: Marcus Tullius
+ editor:
+ - family: Blank-Sangmeister
+ given: Ursula
+ id: cicero
+ issued: 1995
+ language: de-DE
+ publisher: Reclam
+ publisher-place: Stuttgart
+ title: De natura deorum. Über das Wesen der Götter
+ title-short: De natura deorum
+ translator:
+ - family: Blank-Sangmeister
+ given: Ursula
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-cms.md b/documents/markdown/pandoc-md/biblatex-cms.md
new file mode 100644
index 0000000..7a6d861
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-cms.md
@@ -0,0 +1,81 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(*The Chicago Manual of Style: The Essential Guide for Writers, Editors,
+and Publishers* 2003)
+
+*The Chicago Manual of Style: The Essential Guide for Writers, Editors,
+and Publishers*. 2003. 15th ed. Chicago, Ill.: University of Chicago
+Press.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(*Chicago manual of style*, 2003)
+
+*The Chicago manual of style: The essential guide for writers, editors,
+and publishers*. (2003) (15th ed.). Chicago, Ill.: University of Chicago
+Press.
+
+
+NOTES:
+
+- chicago-author-date.csl should have as in-text citation:
+ (*Chicago Manual of Style* 2003)
+ Same behaviour in Zotero; most probably a style file issue.
+
+}
+
+@Manual{cms,
+ title = {The {Chicago} Manual of Style},
+ date = 2003,
+ subtitle = {The Essential Guide for Writers, Editors, and Publishers},
+ edition = 15,
+ publisher = {University of Chicago Press},
+ location = {Chicago, Ill.},
+ isbn = {0-226-10403-6},
+ label = {CMS},
+ hyphenation = {american},
+ sorttitle = {Chicago Manual of Style},
+ indextitle = {Chicago Manual of Style, The},
+ shorttitle = {Chicago Manual of Style},
+ annotation = {This is a manual entry without an author or
+ editor. Note the label field in the database
+ file which is provided for author-year citation styles. Also
+ note the sorttitle and indextitle fields. By
+ default, all entries without an author or
+ editor are alphabetized by title but we want
+ this entry to be alphabetized under \enquote*{C} rather than
+ \enquote*{T}. There's also an isbn field},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: This is a manual entry without an author or editor. Note the
+ label field in the database file which is provided for author-year
+ citation styles. Also note the sorttitle and indextitle fields. By
+ default, all entries without an author or editor are alphabetized by
+ title but we want this entry to be alphabetized under 'C' rather
+ than 'T'. There's also an isbn field
+ edition: 15
+ id: cms
+ isbn: 0-226-10403-6
+ issued: 2003
+ language: en-US
+ publisher: University of Chicago Press
+ publisher-place: Chicago, Ill.
+ title: "The Chicago manual of style: The essential guide for writers,
+ editors, and publishers"
+ title-short: Chicago manual of style
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-coleridge.md b/documents/markdown/pandoc-md/biblatex-coleridge.md
new file mode 100644
index 0000000..22258a6
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-coleridge.md
@@ -0,0 +1,86 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2015-03-08:
+
+(Coleridge 1983)
+
+Coleridge, Samuel Taylor. 1983. *The Collected Works of Samuel Taylor
+Coleridge*. Edited by Kathleen Coburn, James Engell, and W. Jackson
+Bate. Vol. 7.2. Bollingen Series 75. London: Routledge and Kegan Paul.
+
+Formatted with pandoc and apa.csl, 2015-03-08:
+
+(Coleridge, 1983)
+
+Coleridge, S. T. (1983). *The collected works of Samuel Taylor
+Coleridge*. (K. Coburn, J. Engell, & W. J. Bate, Eds.) (Vol. 7.2).
+London: Routledge and Kegan Paul.
+
+NOTES:
+
+- volume-title currently not implemented by chicago-author-date.csl and apa.csl.
+
+}
+
+@Book{coleridge,
+ author = {Coleridge, Samuel Taylor},
+ title = {Biographia literaria, or {Biographical} sketches of my literary
+ life and opinions},
+ date = 1983,
+ editor = {Coburn, Kathleen and Engell, James and Bate, W. Jackson},
+ maintitle = {The collected works of {Samuel Taylor Coleridge}},
+ volume = 7,
+ part = 2,
+ series = {Bollingen Series},
+ number = 75,
+ publisher = {Routledge {and} Kegan Paul},
+ location = {London},
+ hyphenation = {british},
+ indextitle = {Biographia literaria},
+ shorttitle = {Biographia literaria},
+ annotation = {One (partial) volume of a multivolume book. This is a
+ book entry with a volume and a part
+ field which explicitly refers to the second (physical) part of
+ the seventh (logical) volume. Also note the series
+ and number fields},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: One (partial) volume of a multivolume book. This is a book
+ entry with a volume and a part field which explicitly refers to the
+ second (physical) part of the seventh (logical) volume. Also note
+ the series and number fields
+ author:
+ - family: Coleridge
+ given: Samuel Taylor
+ collection-number: 75
+ collection-title: Bollingen series
+ editor:
+ - family: Coburn
+ given: Kathleen
+ - family: Engell
+ given: James
+ - family: Bate
+ given: W. Jackson
+ id: coleridge
+ issued: 1983
+ language: en-GB
+ publisher: Routledge and Kegan Paul
+ publisher-place: London
+ title: The collected works of Samuel Taylor Coleridge
+ type: book
+ volume: 7.2
+ volume-title: Biographia literaria, or Biographical sketches of my
+ literary life and opinions
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-companion.md b/documents/markdown/pandoc-md/biblatex-companion.md
new file mode 100644
index 0000000..fe3dcac
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-companion.md
@@ -0,0 +1,70 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Goossens, Mittelbach, and Samarin 1994)
+
+Goossens, Michel, Frank Mittelbach, and Alexander Samarin. 1994. *The
+LaTeX Companion*. 1st ed. Reading, Mass.: Addison-Wesley.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Goossens, Mittelbach, & Samarin, 1994)
+
+Goossens, M., Mittelbach, F., & Samarin, A. (1994). *The LaTeX
+companion* (1st ed.). Reading, Mass.: Addison-Wesley.
+
+
+}
+
+@Book{companion,
+ author = {Goossens, Michel and Mittelbach, Frank and Samarin, Alexander},
+ title = {The {LaTeX} Companion},
+ date = 1994,
+ edition = 1,
+ publisher = {Addison-Wesley},
+ location = {Reading, Mass.},
+ pagetotal = 528,
+ hyphenation = {american},
+ sorttitle = {LaTeX Companion},
+ indextitle = {LaTeX Companion, The},
+ shorttitle = {LaTeX Companion},
+ annotation = {A book with three authors. Note the formatting of the author
+ list. By default, only the first name is reversed in the
+ bibliography},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A book with three authors. Note the formatting of the author
+ list. By default, only the first name is reversed in the
+ bibliography
+ author:
+ - family: Goossens
+ given: Michel
+ - family: Mittelbach
+ given: Frank
+ - family: Samarin
+ given: Alexander
+ edition: 1
+ id: companion
+ issued: 1994
+ language: en-US
+ number-of-pages: 528
+ publisher: Addison-Wesley
+ publisher-place: Reading, Mass.
+ title: The LaTeX companion
+ title-short: LaTeX companion
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-cotton.md b/documents/markdown/pandoc-md/biblatex-cotton.md
new file mode 100644
index 0000000..7a7a2e2
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-cotton.md
@@ -0,0 +1,69 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Cotton et al. 1999)
+
+Cotton, Frank Albert, Geoffrey Wilkinson, Carlos A. Murillio, and
+Manfred Bochmann. 1999. *Advanced Inorganic Chemistry*. 6th ed.
+Chichester: Wiley.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Cotton, Wilkinson, Murillio, & Bochmann, 1999)
+
+Cotton, F. A., Wilkinson, G., Murillio, C. A., & Bochmann, M. (1999).
+*Advanced inorganic chemistry* (6th ed.). Chichester: Wiley.
+
+
+}
+
+@Book{cotton,
+ author = {Cotton, Frank Albert and Wilkinson, Geoffrey and Murillio,
+ Carlos A. and Bochmann, Manfred},
+ title = {Advanced inorganic chemistry},
+ date = 1999,
+ edition = 6,
+ publisher = {Wiley},
+ location = {Chichester},
+ hyphenation = {british},
+ annotation = {A book entry with \arabic{author} authors and an
+ edition field. By default, long author and
+ editor lists are automatically truncated. This is
+ configurable},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A book entry with `\arabic{author}`{=latex} authors and an
+ edition field. By default, long author and editor lists are
+ automatically truncated. This is configurable
+ author:
+ - family: Cotton
+ given: Frank Albert
+ - family: Wilkinson
+ given: Geoffrey
+ - family: Murillio
+ given: Carlos A.
+ - family: Bochmann
+ given: Manfred
+ edition: 6
+ id: cotton
+ issued: 1999
+ language: en-GB
+ publisher: Wiley
+ publisher-place: Chichester
+ title: Advanced inorganic chemistry
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-crossref-inbook-mvbook.md b/documents/markdown/pandoc-md/biblatex-crossref-inbook-mvbook.md
new file mode 100644
index 0000000..be7b5ff
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-crossref-inbook-mvbook.md
@@ -0,0 +1,58 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+crossref, directly from inbook to mvbook
+
+}
+
+@inbook{inbook-1,
+ Crossref = {mvbook-1},
+ Title = {Macbeth [title field of inbook-1]},
+ Date = {1975},
+ Volume = {3},
+ Chapter = {7},
+ Pages = {100-200},
+}
+
+@mvbook{mvbook-1,
+ Author = {Shakespeare},
+ Date = {1970/1980},
+ Title = {Collected Works [title field of mvbook-1]},
+ Location = {Location},
+ Publisher = {Publisher},
+ Volumes = {4},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- author:
+ - family: Shakespeare
+ chapter-number: 7
+ container-author:
+ - family: Shakespeare
+ container-title: Collected works \[title field of mvbook-1\]
+ id: inbook-1
+ issued: 1975
+ number-of-volumes: 4
+ page: 100-200
+ publisher: Publisher
+ publisher-place: Location
+ title: Macbeth \[title field of inbook-1\]
+ type: chapter
+ volume: 3
+- author:
+ - family: Shakespeare
+ id: mvbook-1
+ issued: 1970/1980
+ number-of-volumes: 4
+ publisher: Publisher
+ publisher-place: Location
+ title: Collected works \[title field of mvbook-1\]
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-crossref-nested.md b/documents/markdown/pandoc-md/biblatex-crossref-nested.md
new file mode 100644
index 0000000..3b5b5ac
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-crossref-nested.md
@@ -0,0 +1,100 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Nested cross-references (see biber manual v 1.7)
+
+}
+
+@bookinbook{bookinbook-1,
+ Crossref = {book-1},
+ Title = {Macbeth [title field of bookinbook-1]},
+ Chapter = {7},
+ Pages = {100-200},
+}
+
+@inbook{inbook-1,
+ Crossref = {book-1},
+ Title = {Macbeth [title field of inbook-1]},
+ Chapter = {7},
+ Pages = {100-200},
+}
+
+@book{book-1,
+ Crossref = {mvbook-1},
+ Date = {1975},
+ Title = {Tragedies [title field of book-1]},
+ Volume = {3}
+}
+
+@mvbook{mvbook-1,
+ Author = {Shakespeare},
+ Date = {1970/1980},
+ Title = {Collected Works [title field of mvbook-1]},
+ Location = {Location},
+ Publisher = {Publisher},
+ Volumes = {4}
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- author:
+ - family: Shakespeare
+ chapter-number: 7
+ container-author:
+ - family: Shakespeare
+ container-title: Collected works \[title field of mvbook-1\]
+ id: bookinbook-1
+ issued: 1975
+ number-of-volumes: 4
+ page: 100-200
+ publisher: Publisher
+ publisher-place: Location
+ title: Macbeth \[title field of bookinbook-1\]
+ type: book
+ volume: 3
+ volume-title: Tragedies \[title field of book-1\]
+- author:
+ - family: Shakespeare
+ chapter-number: 7
+ container-author:
+ - family: Shakespeare
+ container-title: Collected works \[title field of mvbook-1\]
+ id: inbook-1
+ issued: 1975
+ number-of-volumes: 4
+ page: 100-200
+ publisher: Publisher
+ publisher-place: Location
+ title: Macbeth \[title field of inbook-1\]
+ type: chapter
+ volume: 3
+ volume-title: Tragedies \[title field of book-1\]
+- author:
+ - family: Shakespeare
+ container-author:
+ - family: Shakespeare
+ id: book-1
+ issued: 1975
+ number-of-volumes: 4
+ publisher: Publisher
+ publisher-place: Location
+ title: Collected works \[title field of mvbook-1\]
+ type: book
+ volume: 3
+ volume-title: Tragedies \[title field of book-1\]
+- author:
+ - family: Shakespeare
+ id: mvbook-1
+ issued: 1970/1980
+ number-of-volumes: 4
+ publisher: Publisher
+ publisher-place: Location
+ title: Collected works \[title field of mvbook-1\]
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-ctan.md b/documents/markdown/pandoc-md/biblatex-ctan.md
new file mode 100644
index 0000000..12a126c
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-ctan.md
@@ -0,0 +1,73 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(“CTAN: The Comprehensive TeX Archive Network” 2006)
+
+“CTAN: The Comprehensive TeX Archive Network.” 2006.
+<http://www.ctan.org>.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(“CTAN: The Comprehensive TeX Archive Network,” 2006)
+
+CTAN: The Comprehensive TeX Archive Network. (2006). Retrieved October
+01, 2006, from <http://www.ctan.org>
+
+
+NOTES:
+
+- biblio2yaml
+ - if there is no shorttitle, but title and subtitle, the title alone should also be mapped to title-short
+
+- citeproc
+ - citeproc should use title-short (if available) instead of title for in-text citations when there is no author
+
+}
+
+@Online{ctan,
+ title = {{CTAN}},
+ date = 2006,
+ url = {http://www.ctan.org},
+ subtitle = {{The Comprehensive TeX Archive Network}},
+ urldate = {2006-10-01},
+ label = {CTAN},
+ hyphenation = {american},
+ annotation = {This is an online entry. The \textsc{url}, which is
+ given in the url field, is transformed into a
+ clickable link if hyperref support has been
+ enabled. Note the format of the urldate field
+ (yyyy-mm-dd) in the database file. Also note the
+ label field which may be used as a fallback by
+ citation styles which need an author and\slash or a
+ year},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- accessed: 2006-10-01
+ annote: This is an online entry. The [url]{.smallcaps}, which is given
+ in the url field, is transformed into a clickable link if hyperref
+ support has been enabled. Note the format of the urldate field
+ (yyyy-mm-dd) in the database file. Also note the label field which
+ may be used as a fallback by citation styles which need an author
+ and/or a year
+ id: ctan
+ issued: 2006
+ language: en-US
+ title: "CTAN: The Comprehensive TeX Archive Network"
+ title-short: CTAN
+ type: webpage
+ url: "http://www.ctan.org"
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-dates.md b/documents/markdown/pandoc-md/biblatex-dates.md
new file mode 100644
index 0000000..85d424d
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-dates.md
@@ -0,0 +1,162 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+ - Dates
+ - Not included in tests:
+ - malformed dates and date ranges
+ - literal dates ("13th century"; not supported by biblatex)
+ - seasons (would have to come from parsing the issue field)
+ - uncertain dates (use "doubtfuldate" from biblatex-apa?)
+ - dates with single-digit day or month (not supported by biblatex)
+ - negative dates (not supported by biblatex)
+ - Note: biblatex supports years < 1000 but only if padded with leading zeros
+ - TODO:
+ - either biblio2yaml or, probably better, citeproc should strip leading zeros
+ from days and months (CSL can add leading zeros to its output, but not remove
+ them when they are in its input data)
+}
+
+@article{year-month-old,
+ Author = {Author, Al},
+ Journal = {Journal},
+ Month = aug,
+ Title = {Year and Month, bibtex style, supported by biblatex for backwards compatibility},
+ Year = {1999}}
+
+@article{year-month-new,
+ Author = {Author, Al},
+ Journal = {Journal},
+ Month = {08},
+ Title = {Year and Month, biblatex style; note that biblatex does not have a ``day'' field},
+ Year = {1999}}
+
+@article{dates,
+ Author = {Author, Al},
+ Date = {2012-12-13},
+ Eventdate = {2011-10-03},
+ Journal = {Journal},
+ Month = may,
+ Origdate = {1888-10-01},
+ Title = {Dates, default biblatex style; year, month to be ignored if date exists},
+ Urldate = {1999-05-23},
+ Year = {9999}}
+
+@article{date-ranges-different-years,
+ Author = {Author, Al},
+ Date = {1999-10-14/2010-01-23},
+ Eventdate = {1999-12/2000-01},
+ Journal = {Journal},
+ Origdate = {1888-01-02/1913-12-13},
+ Title = {Date ranges; different years},
+ Urldate = {2012-10-12/2013-01-31}}
+
+@article{date-ranges-same-year,
+ Author = {Author, Al},
+ Date = {1999-10-14/1999-10-15},
+ Eventdate = {1999-10/1999-11},
+ Journal = {Journal},
+ Origdate = {1888-01-02/1888-12-13},
+ Title = {Date ranges; same year},
+ Urldate = {2012-10-31/2012-11-01}}
+
+@article{date-ranges-open,
+ Author = {Author, Al},
+ Date = {1999-10-14/},
+ Eventdate = {1999-10/},
+ Journal = {Journal},
+ Origdate = {1888-01-02/},
+ Title = {Date ranges, open-ended},
+ Urldate = {2012-10-31/}}
+
+@article{dates-very-old,
+ Author = {Author, Al},
+ Date = {0712-12-13},
+ Eventdate = {0311-10-03},
+ Journal = {Journal},
+ Month = may,
+ Origdate = {0088-10-01},
+ Title = {Dates, year less than 1000},
+ Urldate = {0999-12-14}}
+
+^D
+---
+nocite: "[@*]"
+references:
+- author:
+ - family: Author
+ given: Al
+ container-title: Journal
+ id: year-month-old
+ issued: 1999-08
+ title: Year and month, bibtex style, supported by biblatex for
+ backwards compatibility
+ type: article-journal
+- author:
+ - family: Author
+ given: Al
+ container-title: Journal
+ id: year-month-new
+ issued: 1999-08
+ title: Year and month, biblatex style; note that biblatex does not
+ have a "day" field
+ type: article-journal
+- accessed: 1999-05-23
+ author:
+ - family: Author
+ given: Al
+ container-title: Journal
+ event-date: 2011-10-03
+ id: dates
+ issued: 2012-12-13
+ original-date: 1888-10-01
+ title: Dates, default biblatex style; year, month to be ignored if
+ date exists
+ type: article-journal
+- accessed: 2012-10-12/2013-01-31
+ author:
+ - family: Author
+ given: Al
+ container-title: Journal
+ event-date: 1999-12/2000-01
+ id: date-ranges-different-years
+ issued: 1999-10-14/2010-01-23
+ original-date: 1888-01-02/1913-12-13
+ title: Date ranges; different years
+ type: article-journal
+- accessed: 2012-10-31/2012-11-01
+ author:
+ - family: Author
+ given: Al
+ container-title: Journal
+ event-date: 1999-10/1999-11
+ id: date-ranges-same-year
+ issued: 1999-10-14/1999-10-15
+ original-date: 1888-01-02/1888-12-13
+ title: Date ranges; same year
+ type: article-journal
+- accessed: 2012-10-31/
+ author:
+ - family: Author
+ given: Al
+ container-title: Journal
+ event-date: 1999-10/
+ id: date-ranges-open
+ issued: 1999-10-14/
+ original-date: 1888-01-02/
+ title: Date ranges, open-ended
+ type: article-journal
+- accessed: 0999-12-14
+ author:
+ - family: Author
+ given: Al
+ container-title: Journal
+ event-date: 0311-10-03
+ id: dates-very-old
+ issued: 0712-12-13
+ original-date: 0088-10-01
+ title: Dates, year less than 1000
+ type: article-journal
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-doody.md b/documents/markdown/pandoc-md/biblatex-doody.md
new file mode 100644
index 0000000..78f496a
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-doody.md
@@ -0,0 +1,101 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Doody 1974) (Matuz 1990)
+
+Doody, Terrence. 1974. “Hemingway’s Style and Jake’s Narration.” *The
+Journal of Narrative Technique* 4 (3): 212–225.
+
+Matuz, Roger, ed. 1990. *Contemporary Literary Criticism*. Vol. 61.
+Detroit: Gale.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Doody, 1974) (Matuz, 1990)
+
+Doody, T. (1974). Hemingway’s style and Jake’s narration. *The Journal
+of Narrative Technique*, *4*(3), 212–225.
+
+Matuz, R. (Ed.). (1990). *Contemporary literary criticism* (Vol. 61, pp.
+204–208). Detroit: Gale.
+
+
+NOTES
+
+- biblio2yaml
+ - contains fields “related” and “relatedstring”. In principle, these could be appended to CSL "note", if citeproc can handle citations in the bibliography ...
+
+}
+
+@Article{doody,
+ author = {Doody, Terrence},
+ title = {Hemingway's Style and {Jake}'s Narration},
+ year = 1974,
+ volume = 4,
+ number = 3,
+ pages = {212-225},
+ hyphenation = {american},
+ related = {matuz:doody},
+ relatedstring= {\autocap{e}xcerpt in},
+ journal = {The Journal of Narrative Technique},
+ annotation = {An article entry cited as an excerpt from a
+ collection entry. Note the format of the
+ related and relatedstring fields},
+}
+
+@Collection{matuz:doody,
+ editor = {Matuz, Roger},
+ title = {Contemporary Literary Criticism},
+ year = 1990,
+ volume = 61,
+ publisher = {Gale},
+ location = {Detroit},
+ pages = {204-208},
+ hyphenation = {american},
+ annotation = {A collection entry providing the excerpt information
+ for the doody entry. Note the format of the
+ pages field},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: An article entry cited as an excerpt from a collection entry.
+ Note the format of the related and relatedstring fields
+ author:
+ - family: Doody
+ given: Terrence
+ container-title: The Journal of Narrative Technique
+ id: doody
+ issue: 3
+ issued: 1974
+ language: en-US
+ page: 212-225
+ title: Hemingway's style and Jake's narration
+ type: article-journal
+ volume: 4
+- annote: A collection entry providing the excerpt information for the
+ doody entry. Note the format of the pages field
+ editor:
+ - family: Matuz
+ given: Roger
+ id: "matuz:doody"
+ issued: 1990
+ language: en-US
+ page: 204-208
+ publisher: Gale
+ publisher-place: Detroit
+ title: Contemporary literary criticism
+ type: book
+ volume: 61
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-edtf-date.md b/documents/markdown/pandoc-md/biblatex-edtf-date.md
new file mode 100644
index 0000000..a168d75
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-edtf-date.md
@@ -0,0 +1,72 @@
+```
+% pandoc -f biblatex -t markdown -s
+Note that current CSL doesn't give us a way
+to distinguish between /open and /unknown,
+so item3-3 and item3-4 get parsed similarly.
+That should change in CSL 1.1, and then this
+test should be revised.
+
+@article{item3-3, date={1998/unknown}}
+@article{item3-4, date={1999/open}}
+@article{item3-10, date={2004-04-05T14:34:00}}
+@article{item5-1, date={0000}}
+@article{item5-2, date={-0876}}
+@article{item5-3, date={-0877/-0866}}
+@article{item5-5, date={-0343-02}}
+@article{item5-8, date={1723~}}
+@article{item5-9, date={1723?}}
+@article{item5-10, date={1723?~}}
+@article{item5-11, date={2004-22}}
+@article{item5-12, date={2004-24}}
+@article{item5-13, date={20uu}}
+@article{item5-14, date={y-123456789}}
+
+^D
+---
+nocite: "[@*]"
+references:
+- id: item3-3
+ issued: 1998/
+ type: article-journal
+- id: item3-4
+ issued: 1999/
+ type: article-journal
+- id: item3-10
+ issued: 2004-04-05
+ type: article-journal
+- id: item5-1
+ type: article-journal
+- id: item5-2
+ issued: "-0876"
+ type: article-journal
+- id: item5-3
+ issued: "-0877/-0866"
+ type: article-journal
+- id: item5-5
+ issued: "-0343-02"
+ type: article-journal
+- id: item5-8
+ issued: 1723\~
+ type: article-journal
+- id: item5-9
+ issued: 1723
+ type: article-journal
+- id: item5-10
+ issued: 1723\~
+ type: article-journal
+- id: item5-11
+ issued: 2004-22
+ type: article-journal
+- id: item5-12
+ issued: 2004-24
+ type: article-journal
+- id: item5-13
+ issued: 2000/2099
+ type: article-journal
+- id: item5-14
+ issued: y-123456789
+ type: article-journal
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-escapedquotes.md b/documents/markdown/pandoc-md/biblatex-escapedquotes.md
new file mode 100644
index 0000000..9e260f7
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-escapedquotes.md
@@ -0,0 +1,51 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{From jgm/pandoc#1568. Double quotes escaped using {"}.}
+
+@ARTICLE{Koff2009-gn,
+ title = "Pan-Canadian evaluation of irreversible compression ratios
+ ({"}lossy{"} compression) for development of national
+ guidelines",
+ author = "Koff, David and Bak, Peter and Brownrigg, Paul and
+ Hosseinzadeh, Danoush and Khademi, April and Kiss, Alex and
+ Lepanto, Luigi and Michalak, Tracy and Shulman, Harry and
+ Volkening, Andrew",
+ affiliation = "Sunnybrook Health Sciences Centre, 2075 Bayview Ave., Toronto,
+ ON, M4N 3M5, Canada. dkoffmcmaster.ca",
+ journal = "Journal of digital imaging",
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- author:
+ - family: Koff
+ given: David
+ - family: Bak
+ given: Peter
+ - family: Brownrigg
+ given: Paul
+ - family: Hosseinzadeh
+ given: Danoush
+ - family: Khademi
+ given: April
+ - family: Kiss
+ given: Alex
+ - family: Lepanto
+ given: Luigi
+ - family: Michalak
+ given: Tracy
+ - family: Shulman
+ given: Harry
+ - family: Volkening
+ given: Andrew
+ container-title: Journal of digital imaging
+ id: Koff2009-gn
+ title: Pan-canadian evaluation of irreversible compression ratios
+ (\"lossy\" compression) for development of national guidelines
+ type: article-journal
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-formatting.md b/documents/markdown/pandoc-md/biblatex-formatting.md
new file mode 100644
index 0000000..c12f05d
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-formatting.md
@@ -0,0 +1,23 @@
+```
+% pandoc -f biblatex -t markdown -s
+@article{item1,
+ Title = {The Title:
+ \textit{italics},
+ \textbf{bold},
+ \textsubscript{subscript},
+ \textsuperscript{superscript},
+ \textsc{small-caps}}
+}
+^D
+---
+nocite: "[@*]"
+references:
+- id: item1
+ title: "The title: *Italics*, **bold**, ~subscript~, ^superscript^,
+ [small-caps]{.smallcaps}"
+ title-short: The title
+ type: article-journal
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-gaonkar-in.md b/documents/markdown/pandoc-md/biblatex-gaonkar-in.md
new file mode 100644
index 0000000..8c8765c
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-gaonkar-in.md
@@ -0,0 +1,62 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Gaonkar 2001)
+
+Gaonkar, Dilip Parameshwar. 2001. “On Alternative Modernities.” In
+*Alternative Modernities*, edited by Dilip Parameshwar Gaonkar, 1–23.
+Durham; London: Duke University Press.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Gaonkar, 2001)
+
+Gaonkar, D. P. (2001). On alternative modernities. In D. P. Gaonkar
+(Ed.), *Alternative modernities* (pp. 1–23). Durham; London: Duke
+University Press.
+
+
+}
+
+@InCollection{gaonkar:in,
+ author = {Gaonkar, Dilip Parameshwar},
+ editor = {Gaonkar, Dilip Parameshwar},
+ title = {On Alternative Modernities},
+ date = 2001,
+ booktitle = {Alternative Modernities},
+ publisher = {Duke University Press},
+ location = {Durham and London},
+ isbn = {0-822-32714-7},
+ pages = {1-23},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- author:
+ - family: Gaonkar
+ given: Dilip Parameshwar
+ container-title: Alternative modernities
+ editor:
+ - family: Gaonkar
+ given: Dilip Parameshwar
+ id: "gaonkar:in"
+ isbn: 0-822-32714-7
+ issued: 2001
+ page: 1-23
+ publisher: Duke University Press
+ publisher-place: Durham; London
+ title: On alternative modernities
+ type: chapter
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-gaonkar.md b/documents/markdown/pandoc-md/biblatex-gaonkar.md
new file mode 100644
index 0000000..61e87bf
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-gaonkar.md
@@ -0,0 +1,59 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Gaonkar 2001)
+
+Gaonkar, Dilip Parameshwar, ed. 2001. *Alternative Modernities*. Durham;
+London: Duke University Press.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Gaonkar, 2001)
+
+Gaonkar, D. P. (Ed.). (2001). *Alternative modernities*. Durham; London:
+Duke University Press.
+
+
+}
+
+@Collection{gaonkar,
+ editor = {Gaonkar, Dilip Parameshwar},
+ title = {Alternative Modernities},
+ date = 2001,
+ publisher = {Duke University Press},
+ location = {Durham and London},
+ isbn = {0-822-32714-7},
+ hyphenation = {american},
+ annotation = {This is a collection entry. Note the format of the
+ location field in the database file as well as the
+ isbn field},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: This is a collection entry. Note the format of the location
+ field in the database file as well as the isbn field
+ editor:
+ - family: Gaonkar
+ given: Dilip Parameshwar
+ id: gaonkar
+ isbn: 0-822-32714-7
+ issued: 2001
+ language: en-US
+ publisher: Duke University Press
+ publisher-place: Durham; London
+ title: Alternative modernities
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-geer.md b/documents/markdown/pandoc-md/biblatex-geer.md
new file mode 100644
index 0000000..e85913d
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-geer.md
@@ -0,0 +1,70 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Geer 1985)
+
+Geer, Ingrid de. 1985. “Earl, Saint, Bishop, Skald – and Music: The
+Orkney Earldom of the Twelfth Century. A Musicological Study.” PhD
+thesis, Uppsala: Uppsala Universitet.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Geer, 1985)
+
+Geer, I. de. (1985). *Earl, saint, bishop, skald – and music: The Orkney
+earldom of the twelfth century. A musicological study* (PhD thesis).
+Uppsala Universitet, Uppsala.
+
+
+}
+
+@Thesis{geer,
+ author = {de Geer, Ingrid},
+ title = {Earl, Saint, Bishop, Skald~-- and Music},
+ type = {phdthesis},
+ institution = {Uppsala Universitet},
+ date = 1985,
+ subtitle = {The {Orkney} Earldom of the Twelfth Century. {A} Musicological
+ Study},
+ location = {Uppsala},
+ options = {useprefix=false},
+ hyphenation = {british},
+ annotation = {This is a typical thesis entry for a PhD thesis. Note
+ the type field in the database file which uses a
+ localization key. Also note the format of the printed name and
+ compare the useprefix option in the options
+ field as well as vangennep},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: This is a typical thesis entry for a PhD thesis. Note the type
+ field in the database file which uses a localization key. Also note
+ the format of the printed name and compare the useprefix option in
+ the options field as well as vangennep
+ author:
+ - dropping-particle: de
+ family: Geer
+ given: Ingrid
+ genre: PhD thesis
+ id: geer
+ issued: 1985
+ language: en-GB
+ publisher: Uppsala Universitet
+ publisher-place: Uppsala
+ title: "Earl, saint, bishop, skald -- and music: The Orkney earldom of
+ the twelfth century. A musicological study"
+ title-short: Earl, saint, bishop, skald -- and music
+ type: thesis
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-gerhardt.md b/documents/markdown/pandoc-md/biblatex-gerhardt.md
new file mode 100644
index 0000000..86c6a59
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-gerhardt.md
@@ -0,0 +1,64 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Gerhardt 2000)
+
+Gerhardt, Michael J. 2000. *The Federal Appointments Process: A
+Constitutional and Historical Analysis*. Durham; London: Duke University
+Press.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Gerhardt, 2000)
+
+Gerhardt, M. J. (2000). *The federal appointments process: A
+constitutional and historical analysis*. Durham; London: Duke University
+Press.
+
+
+}
+
+@Book{gerhardt,
+ author = {Gerhardt, Michael J.},
+ title = {The Federal Appointments Process},
+ date = 2000,
+ publisher = {Duke University Press},
+ location = {Durham and London},
+ hyphenation = {american},
+ sorttitle = {Federal Appointments Process},
+ indextitle = {Federal Appointments Process, The},
+ subtitle = {A Constitutional and Historical Analysis},
+ shorttitle = {Federal Appointments Process},
+ annotation = {This is a book entry. Note the format of the
+ location field as well as the sorttitle and
+ indextitle fields},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: This is a book entry. Note the format of the location field as
+ well as the sorttitle and indextitle fields
+ author:
+ - family: Gerhardt
+ given: Michael J.
+ id: gerhardt
+ issued: 2000
+ language: en-US
+ publisher: Duke University Press
+ publisher-place: Durham; London
+ title: "The federal appointments process: A constitutional and
+ historical analysis"
+ title-short: Federal appointments process
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-gillies.md b/documents/markdown/pandoc-md/biblatex-gillies.md
new file mode 100644
index 0000000..a63c131
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-gillies.md
@@ -0,0 +1,69 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Gillies 1933)
+
+Gillies, Alexander. 1933. “Herder and the Preparation of Goethe’s Idea
+of World Literature.” *Publications of the English Goethe Society, New
+Series* 9: 46–67.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Gillies, 1933)
+
+Gillies, A. (1933). Herder and the preparation of Goethe’s idea of world
+literature. *Publications of the English Goethe Society, new series*,
+*9*, 46–67.
+
+
+NOTES:
+
+- biblio2yaml
+ - "new series" is not pretty, but it’s the best we can do at the moment, given the limitations of CSL.
+
+}
+
+@Article{gillies,
+ author = {Gillies, Alexander},
+ title = {Herder and the Preparation of {Goethe}'s Idea of World
+ Literature},
+ journaltitle = {Publications of the English Goethe Society},
+ date = 1933,
+ series = {newseries},
+ volume = 9,
+ pages = {46-67},
+ hyphenation = {british},
+ annotation = {An article entry with a series and a
+ volume field. Note that format of the series
+ field in the database file},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: An article entry with a series and a volume field. Note that
+ format of the series field in the database file
+ author:
+ - family: Gillies
+ given: Alexander
+ collection-title: New series
+ container-title: Publications of the English Goethe Society
+ id: gillies
+ issued: 1933
+ language: en-GB
+ page: 46-67
+ title: Herder and the preparation of Goethe's idea of world literature
+ type: article-journal
+ volume: 9
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-glashow.md b/documents/markdown/pandoc-md/biblatex-glashow.md
new file mode 100644
index 0000000..40d5713
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-glashow.md
@@ -0,0 +1,51 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Glashow 1961)
+
+Glashow, Sheldon. 1961. “Partial Symmetries of Weak Interactions.”
+*Nucl. Phys.* 22: 579–588.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Glashow, 1961)
+
+Glashow, S. (1961). Partial symmetries of weak interactions.
+*Nucl. Phys.*, *22*, 579–588.
+
+
+}
+
+@Article{glashow,
+ author = {Glashow, Sheldon},
+ title = {Partial Symmetries of Weak Interactions},
+ journaltitle = {Nucl.~Phys.},
+ date = 1961,
+ volume = 22,
+ pages = {579-588},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- author:
+ - family: Glashow
+ given: Sheldon
+ container-title: Nucl. Phys.
+ id: glashow
+ issued: 1961
+ page: 579-588
+ title: Partial symmetries of weak interactions
+ type: article-journal
+ volume: 22
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-gonzalez.md b/documents/markdown/pandoc-md/biblatex-gonzalez.md
new file mode 100644
index 0000000..8826b1c
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-gonzalez.md
@@ -0,0 +1,62 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Gonzalez 2001)
+
+Gonzalez, Ray. 2001. *The Ghost of John Wayne and Other Stories*.
+Tucson: The University of Arizona Press.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Gonzalez, 2001)
+
+Gonzalez, R. (2001). *The ghost of John Wayne and other stories*.
+Tucson: The University of Arizona Press.
+
+}
+
+@Book{gonzalez,
+ author = {Gonzalez, Ray},
+ title = {The Ghost of {John Wayne} and Other Stories},
+ date = 2001,
+ publisher = {The University of Arizona Press},
+ location = {Tucson},
+ isbn = {0-816-52066-6},
+ hyphenation = {american},
+ sorttitle = {Ghost of John Wayne and Other Stories},
+ indextitle = {Ghost of {John Wayne} and Other Stories, The},
+ shorttitle = {Ghost of {John Wayne}},
+ annotation = {A collection of short stories. This is a book entry.
+ Note the sorttitle and indextitle fields in
+ the database file. There's also an isbn field},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A collection of short stories. This is a book entry. Note the
+ sorttitle and indextitle fields in the database file. There's also
+ an isbn field
+ author:
+ - family: Gonzalez
+ given: Ray
+ id: gonzalez
+ isbn: 0-816-52066-6
+ issued: 2001
+ language: en-US
+ publisher: The University of Arizona Press
+ publisher-place: Tucson
+ title: The ghost of John Wayne and other stories
+ title-short: Ghost of John Wayne
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-hammond.md b/documents/markdown/pandoc-md/biblatex-hammond.md
new file mode 100644
index 0000000..d3a8c77
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-hammond.md
@@ -0,0 +1,63 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Hammond 1997)
+
+Hammond, Christopher. 1997. *The Basics of Crystallography and
+Diffraction*. Oxford: International Union of Crystallography; Oxford
+University Press.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Hammond, 1997)
+
+Hammond, C. (1997). *The basics of crystallography and diffraction*.
+Oxford: International Union of Crystallography; Oxford University Press.
+
+
+}
+
+@Book{hammond,
+ author = {Hammond, Christopher},
+ title = {The basics of crystallography and diffraction},
+ date = 1997,
+ publisher = {International Union of Crystallography and Oxford University
+ Press},
+ location = {Oxford},
+ hyphenation = {british},
+ sorttitle = {Basics of crystallography and diffraction},
+ indextitle = {Basics of crystallography and diffraction, The},
+ shorttitle = {Crystallography and diffraction},
+ annotation = {A book entry. Note the sorttitle and
+ indextitle fields as well as the format of the
+ publisher field},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A book entry. Note the sorttitle and indextitle fields as well
+ as the format of the publisher field
+ author:
+ - family: Hammond
+ given: Christopher
+ id: hammond
+ issued: 1997
+ language: en-GB
+ publisher: International Union of Crystallography; Oxford University
+ Press
+ publisher-place: Oxford
+ title: The basics of crystallography and diffraction
+ title-short: Crystallography and diffraction
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-herrmann.md b/documents/markdown/pandoc-md/biblatex-herrmann.md
new file mode 100644
index 0000000..29d1cc8
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-herrmann.md
@@ -0,0 +1,70 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Herrmann et al. 2006)
+
+Herrmann, Wolfgang A., Karl Öfele, Sabine K. Schneider, Eberhardt
+Herdtweck, and Stephan D. Hoffmann. 2006. “A Carbocyclic Carbene as an
+Efficient Catalyst Ligand for C–C Coupling Reactions.” *Angew. Chem.
+Int. Ed.* 45 (23): 3859–3862.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Herrmann, Öfele, Schneider, Herdtweck, & Hoffmann, 2006)
+
+Herrmann, W. A., Öfele, K., Schneider, S. K., Herdtweck, E., & Hoffmann,
+S. D. (2006). A carbocyclic carbene as an efficient catalyst ligand for
+C–C coupling reactions. *Angew. Chem. Int. Ed.*, *45*(23), 3859–3862.
+
+
+}
+
+@string{ anch-ie = {Angew.~Chem. Int.~Ed.} }
+
+@Article{herrmann,
+ author = {Herrmann, Wolfgang A. and {\"O}fele, Karl and Schneider,
+ Sabine K. and Herdtweck, Eberhardt and Hoffmann, Stephan D.},
+ title = {A carbocyclic carbene as an efficient catalyst ligand for {C--C}
+ coupling reactions},
+ journaltitle = anch-ie,
+ date = 2006,
+ volume = 45,
+ number = 23,
+ pages = {3859-3862},
+ indextitle = {Carbocyclic carbene as an efficient catalyst, A},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- author:
+ - family: Herrmann
+ given: Wolfgang A.
+ - family: Öfele
+ given: Karl
+ - family: Schneider
+ given: Sabine K.
+ - family: Herdtweck
+ given: Eberhardt
+ - family: Hoffmann
+ given: Stephan D.
+ container-title: Angew. Chem. Int. Ed.
+ id: herrmann
+ issue: 23
+ issued: 2006
+ page: 3859-3862
+ title: A carbocyclic carbene as an efficient catalyst ligand for C--C
+ coupling reactions
+ type: article-journal
+ volume: 45
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-hyman.md b/documents/markdown/pandoc-md/biblatex-hyman.md
new file mode 100644
index 0000000..4c76590
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-hyman.md
@@ -0,0 +1,79 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Hyman 1981)
+
+Hyman, Arthur. 1981. “Aristotle’s Theory of the Intellect and Its
+Interpretation by Averroes.” In *Studies in Aristotle*, edited by
+Dominic J. O’Meara, 161–191. Studies in Philosophy and the History of
+Philosophy 9. Washington, D.C.: The Catholic University of America
+Press.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Hyman, 1981)
+
+Hyman, A. (1981). Aristotle’s theory of the intellect and its
+interpretation by Averroes. In D. J. O’Meara (Ed.), *Studies in
+Aristotle* (pp. 161–191). Washington, D.C.: The Catholic University of
+America Press.
+
+
+}
+
+@InCollection{hyman,
+ author = {Arthur Hyman},
+ editor = {O'Meara, Dominic J.},
+ title = {Aristotle's Theory of the Intellect and its Interpretation by
+ {Averroes}},
+ date = 1981,
+ booktitle = {Studies in {Aristotle}},
+ series = {Studies in Philosophy and the History of Philosophy},
+ number = 9,
+ publisher = {The Catholic University of America Press},
+ location = {Washington, D.C.},
+ pages = {161-191},
+ keywords = {secondary},
+ hyphenation = {american},
+ indextitle = {Aristotle's Theory of the Intellect},
+ shorttitle = {Aristotle's Theory of the Intellect},
+ annotation = {An incollection entry with a series and
+ number field},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: An incollection entry with a series and number field
+ author:
+ - family: Hyman
+ given: Arthur
+ collection-number: 9
+ collection-title: Studies in philosophy and the history of philosophy
+ container-title: Studies in Aristotle
+ editor:
+ - family: O'Meara
+ given: Dominic J.
+ id: hyman
+ issued: 1981
+ keyword: secondary
+ language: en-US
+ page: 161-191
+ publisher: The Catholic University of America Press
+ publisher-place: Washington, D.C.
+ title: Aristotle's theory of the intellect and its interpretation by
+ Averroes
+ title-short: Aristotle's theory of the intellect
+ type: chapter
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-iliad.md b/documents/markdown/pandoc-md/biblatex-iliad.md
new file mode 100644
index 0000000..215e911
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-iliad.md
@@ -0,0 +1,68 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Homer 2004)
+
+Homer. 2004. *Die Ilias*. Translated by Wolfgang Schadewaldt. 3rd ed.
+Düsseldorf; Zürich: Artemis & Winkler.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Homer, 2004)
+
+Homer. (2004). *Die Ilias*. (W. Schadewaldt, trans.) (3rd ed.).
+Düsseldorf; Zürich: Artemis & Winkler.
+
+}
+
+@Book{iliad,
+ author = {Homer},
+ title = {Die Ilias},
+ date = 2004,
+ translator = {Schadewaldt, Wolfgang},
+ introduction = {Latacz, Joachim},
+ edition = 3,
+ publisher = {Artemis \& Winkler},
+ location = {D{\"u}sseldorf and Z{\"u}rich},
+ hyphenation = {german},
+ sorttitle = {Ilias},
+ indextitle = {Ilias, Die},
+ shorttitle = {Ilias},
+ annotation = {A German translation of the \emph{Iliad}. Note the
+ translator and introduction fields and the
+ format of the location field in the database
+ file. Also note the sorttitle and indextitle
+ fields},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A German translation of the *Iliad*. Note the translator and
+ introduction fields and the format of the location field in the
+ database file. Also note the sorttitle and indextitle fields
+ author:
+ - family: Homer
+ edition: 3
+ id: iliad
+ issued: 2004
+ language: de-DE
+ publisher: Artemis & Winkler
+ publisher-place: Düsseldorf; Zürich
+ title: Die Ilias
+ title-short: Ilias
+ translator:
+ - family: Schadewaldt
+ given: Wolfgang
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-inbook-title-booktitle-maintitle-series-2.md b/documents/markdown/pandoc-md/biblatex-inbook-title-booktitle-maintitle-series-2.md
new file mode 100644
index 0000000..83e4294
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-inbook-title-booktitle-maintitle-series-2.md
@@ -0,0 +1,48 @@
+```
+% pandoc -f biblatex -t markdown -s
+@inbook{item1,
+ Author = {Author, Al},
+ Bookauthor = {Bookauthor, Bob},
+ Booksubtitle = {Booksubtitle},
+ Booktitle = {Booktitle},
+ Booktitleaddon = {Booktitleaddon},
+ Date = {2011},
+ Hyphenation = {french},
+ Location = {Location},
+ Mainsubtitle = {Mainsubtitle},
+ Maintitle = {Maintitle},
+ Maintitleaddon = {Maintitleaddon},
+ Number = {3},
+ Publisher = {Publisher},
+ Series = {Series},
+ Subtitle = {Subtitle},
+ Title = {Title of the ``inbook'' Entry},
+ Titleaddon = {Titleaddon},
+ Volume = {4}}
+
+^D
+---
+nocite: "[@*]"
+references:
+- author:
+ - family: Author
+ given: Al
+ collection-number: 3
+ collection-title: Series
+ container-author:
+ - family: Bookauthor
+ given: Bob
+ container-title: "Maintitle: Mainsubtitle. Maintitleaddon"
+ id: item1
+ issued: 2011
+ language: fr-FR
+ publisher: Publisher
+ publisher-place: Location
+ title: "Title of the \"inbook\" Entry: Subtitle. Titleaddon"
+ type: chapter
+ volume: 4
+ volume-title: "Booktitle: Booksubtitle. Booktitleaddon"
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-inbook-title-booktitle-maintitle-series.md b/documents/markdown/pandoc-md/biblatex-inbook-title-booktitle-maintitle-series.md
new file mode 100644
index 0000000..feaf075
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-inbook-title-booktitle-maintitle-series.md
@@ -0,0 +1,44 @@
+```
+% pandoc -f biblatex -t markdown -s
+@inbook{item1,
+ Author = {Author, Al},
+ Booksubtitle = {Booksubtitle},
+ Booktitle = {Booktitle},
+ Booktitleaddon = {Booktitleaddon},
+ Date = {2011},
+ Hyphenation = {french},
+ Location = {Location},
+ Mainsubtitle = {Mainsubtitle},
+ Maintitle = {Maintitle},
+ Maintitleaddon = {Maintitleaddon},
+ Number = {3},
+ Publisher = {Publisher},
+ Series = {Series},
+ Subtitle = {Subtitle},
+ Title = {Title of the ``inbook'' Entry},
+ Titleaddon = {Titleaddon},
+ Volume = {4}}
+
+^D
+---
+nocite: "[@*]"
+references:
+- author:
+ - family: Author
+ given: Al
+ collection-number: 3
+ collection-title: Series
+ container-title: "Maintitle: Mainsubtitle. Maintitleaddon"
+ id: item1
+ issued: 2011
+ language: fr-FR
+ publisher: Publisher
+ publisher-place: Location
+ title: "Title of the \"inbook\" Entry: Subtitle. Titleaddon"
+ type: chapter
+ volume: 4
+ volume-title: "Booktitle: Booksubtitle. Booktitleaddon"
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-inbook.md b/documents/markdown/pandoc-md/biblatex-inbook.md
new file mode 100644
index 0000000..e95f4aa
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-inbook.md
@@ -0,0 +1,147 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+adapted from http://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/examples/biblatex-examples.bib
+
+TODO / citeproc: in biblatex "inbook" entries, citeproc should suppress bookauthor = CSL container-author if identical with author. -- See annotation in kant:kpv.
+}
+
+@string{dtv = {Deutscher Taschenbuch-Verlag}}
+
+@inbook{kant:kpv,
+ Annotation = {An edition of Kant's \emph{Collected Works}, volume five. This is an inbook entry which explicitly refers to the \emph{Critique of Practical Reason} only, not to the entire fifth volume. Note the author and bookauthor fields in the database file. By default, the bookauthor is omitted if the values of the author and bookauthor fields are identical},
+ Author = {Kant, Immanuel},
+ Bookauthor = {Kant, Immanuel},
+ Booktitle = {Kritik der praktischen Vernunft. Kritik der Urtheilskraft},
+ Date = 1968,
+ Hyphenation = {german},
+ Location = {Berlin},
+ Maintitle = {Kants Werke. Akademie Textausgabe},
+ Pages = {1-163},
+ Publisher = {Walter de Gruyter},
+ Shorthand = {KpV},
+ Shorttitle = {Kritik der praktischen Vernunft},
+ Title = {Kritik der praktischen Vernunft},
+ Volume = 5}
+
+@inbook{kant:ku,
+ Annotation = {An edition of Kant's \emph{Collected Works}, volume five. This is an inbook entry which explicitly refers to the \emph{Critique of Judgment} only, not to the entire fifth volume},
+ Author = {Kant, Immanuel},
+ Bookauthor = {Kant, Immanuel},
+ Booktitle = {Kritik der praktischen Vernunft. Kritik der Urtheilskraft},
+ Date = 1968,
+ Hyphenation = {german},
+ Location = {Berlin},
+ Maintitle = {Kants Werke. Akademie Textausgabe},
+ Pages = {165-485},
+ Publisher = {Walter de Gruyter},
+ Shorthand = {KU},
+ Title = {Kritik der Urtheilskraft},
+ Volume = 5}
+
+@inbook{nietzsche:historie,
+ Annotation = {A single essay from the critical edition of Nietzsche's works. This inbook entry explicitly refers to an essay found in the first volume. Note the title, booktitle, and maintitle fields. Also note the sorttitle and sortyear fields. We want this entry to be listed after the entry referring to the entire first volume},
+ Author = {Nietzsche, Friedrich},
+ Bookauthor = {Nietzsche, Friedrich},
+ Booktitle = {Die Geburt der Tragödie. Unzeitgemäße Betrachtungen I--IV. Nachgelassene Schriften 1870--1973},
+ Date = 1988,
+ Editor = {Colli, Giorgio and Montinari, Mazzino},
+ Hyphenation = {german},
+ Indexsorttitle = {Vom Nutzen und Nachtheil der Historie fur das Leben},
+ Indextitle = {Vom Nutzen und Nachtheil der Historie für das Leben},
+ Location = {München and Berlin and New York},
+ Mainsubtitle = {Kritische Studienausgabe},
+ Maintitle = {Sämtliche Werke},
+ Pages = {243-334},
+ Publisher = dtv # { and Walter de Gruyter},
+ Shorttitle = {Vom Nutzen und Nachtheil der Historie},
+ Sorttitle = {Werke-01-243},
+ Sortyear = {1988-2},
+ Subtitle = {Vom Nutzen und Nachtheil der Historie für das Leben},
+ Title = {Unzeitgemässe Betrachtungen. Zweites Stück},
+ Volume = 1}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: An edition of Kant's *Collected Works*, volume five. This is
+ an inbook entry which explicitly refers to the *Critique of
+ Practical Reason* only, not to the entire fifth volume. Note the
+ author and bookauthor fields in the database file. By default, the
+ bookauthor is omitted if the values of the author and bookauthor
+ fields are identical
+ author:
+ - family: Kant
+ given: Immanuel
+ container-author:
+ - family: Kant
+ given: Immanuel
+ container-title: Kants Werke. Akademie Textausgabe
+ id: "kant:kpv"
+ issued: 1968
+ language: de-DE
+ page: 1-163
+ publisher: Walter de Gruyter
+ publisher-place: Berlin
+ title: Kritik der praktischen Vernunft
+ title-short: Kritik der praktischen Vernunft
+ type: chapter
+ volume: 5
+ volume-title: Kritik der praktischen Vernunft. Kritik der
+ Urtheilskraft
+- annote: An edition of Kant's *Collected Works*, volume five. This is
+ an inbook entry which explicitly refers to the *Critique of
+ Judgment* only, not to the entire fifth volume
+ author:
+ - family: Kant
+ given: Immanuel
+ container-author:
+ - family: Kant
+ given: Immanuel
+ container-title: Kants Werke. Akademie Textausgabe
+ id: "kant:ku"
+ issued: 1968
+ language: de-DE
+ page: 165-485
+ publisher: Walter de Gruyter
+ publisher-place: Berlin
+ title: Kritik der Urtheilskraft
+ type: chapter
+ volume: 5
+ volume-title: Kritik der praktischen Vernunft. Kritik der
+ Urtheilskraft
+- annote: A single essay from the critical edition of Nietzsche's works.
+ This inbook entry explicitly refers to an essay found in the first
+ volume. Note the title, booktitle, and maintitle fields. Also note
+ the sorttitle and sortyear fields. We want this entry to be listed
+ after the entry referring to the entire first volume
+ author:
+ - family: Nietzsche
+ given: Friedrich
+ container-author:
+ - family: Nietzsche
+ given: Friedrich
+ container-title: "Sämtliche Werke: Kritische Studienausgabe"
+ editor:
+ - family: Colli
+ given: Giorgio
+ - family: Montinari
+ given: Mazzino
+ id: "nietzsche:historie"
+ issued: 1988
+ language: de-DE
+ page: 243-334
+ publisher: Deutscher Taschenbuch-Verlag; Walter de Gruyter
+ publisher-place: München; Berlin; New York
+ title: "Unzeitgemässe Betrachtungen. Zweites Stück: Vom Nutzen und
+ Nachtheil der Historie für das Leben"
+ title-short: Vom Nutzen und Nachtheil der Historie
+ type: chapter
+ volume: 1
+ volume-title: Die Geburt der Tragödie. Unzeitgemäße Betrachtungen
+ I--IV. Nachgelassene Schriften 1870--1973
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-incollection-2.md b/documents/markdown/pandoc-md/biblatex-incollection-2.md
new file mode 100644
index 0000000..dcb3047
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-incollection-2.md
@@ -0,0 +1,98 @@
+```
+% pandoc -f biblatex -t markdown -s
+
+@comment{adapted from http://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/examples/biblatex-examples.bib}
+
+
+@string{hup = {Harvard University Press}}
+
+
+@incollection{westfahl:space,
+ Annotation = {A cross-referenced article from a collection. This is an incollection entry with a crossref field. Note the subtitle and indextitle fields},
+ Author = {Westfahl, Gary},
+ Crossref = {westfahl:frontier},
+ Hyphenation = {american},
+ Indextitle = {True Frontier, The},
+ Pages = {55-65},
+ Subtitle = {Confronting and Avoiding the Realities of Space in {American} Science Fiction Films},
+ Title = {The True Frontier}}
+
+@incollection{gaonkar:in,
+ Author = {Gaonkar, Dilip Parameshwar},
+ Booktitle = {Alternative Modernities},
+ Date = 2001,
+ Editor = {Gaonkar, Dilip Parameshwar},
+ Isbn = {0-822-32714-7},
+ Location = {Durham and London},
+ Pages = {1-23},
+ Publisher = {Duke University Press},
+ Title = {On Alternative Modernities}}
+
+@collection{westfahl:frontier,
+ Annotation = {This is a collection entry. Note the format of the location field as well as the subtitle and booksubtitle fields},
+ Booksubtitle = {The Frontier Theme in Science Fiction},
+ Booktitle = {Space and Beyond},
+ Date = 2000,
+ Editor = {Westfahl, Gary},
+ Hyphenation = {american},
+ Location = {Westport, Conn. and London},
+ Publisher = {Greenwood},
+ Subtitle = {The Frontier Theme in Science Fiction},
+ Title = {Space and Beyond}}
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A cross-referenced article from a collection. This is an
+ incollection entry with a crossref field. Note the subtitle and
+ indextitle fields
+ author:
+ - family: Westfahl
+ given: Gary
+ container-title: "Space and beyond: The frontier theme in science
+ fiction"
+ editor:
+ - family: Westfahl
+ given: Gary
+ id: "westfahl:space"
+ issued: 2000
+ language: en-US
+ page: 55-65
+ publisher: Greenwood
+ publisher-place: Westport, Conn.; London
+ title: "The true frontier: Confronting and avoiding the realities of
+ space in American science fiction films"
+ title-short: The true frontier
+ type: chapter
+- author:
+ - family: Gaonkar
+ given: Dilip Parameshwar
+ container-title: Alternative modernities
+ editor:
+ - family: Gaonkar
+ given: Dilip Parameshwar
+ id: "gaonkar:in"
+ isbn: 0-822-32714-7
+ issued: 2001
+ page: 1-23
+ publisher: Duke University Press
+ publisher-place: Durham; London
+ title: On alternative modernities
+ type: chapter
+- annote: This is a collection entry. Note the format of the location
+ field as well as the subtitle and booksubtitle fields
+ editor:
+ - family: Westfahl
+ given: Gary
+ id: "westfahl:frontier"
+ issued: 2000
+ language: en-US
+ publisher: Greenwood
+ publisher-place: Westport, Conn.; London
+ title: "Space and beyond: The frontier theme in science fiction"
+ title-short: Space and beyond
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-incollection.md b/documents/markdown/pandoc-md/biblatex-incollection.md
new file mode 100644
index 0000000..0890693
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-incollection.md
@@ -0,0 +1,130 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{adapted from http://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/examples/biblatex-examples.bib}
+
+@string{hup = {Harvard University Press}}
+
+@incollection{brandt,
+ Annotation = {An incollection entry with a series and a number. Note the format of the printed name and compare the useprefix option in the options field as well as vangennep. Also note the indextitle, and indexsorttitle fields},
+ Author = {von Brandt, Ahasver and Hoffmann, Erich},
+ Booktitle = {Europa im Hoch- und Spätmittelalter},
+ Date = 1987,
+ Editor = {Seibt, Ferdinand},
+ Hyphenation = {german},
+ Indexsorttitle = {Nordischen Lander von der Mitte des 11. Jahrhunderts bis 1448},
+ Indextitle = {Nordischen Länder von der Mitte des 11.~Jahrhunderts bis 1448, Die},
+ Location = {Stuttgart},
+ Number = 2,
+ Options = {useprefix=false},
+ Pages = {884-917},
+ Publisher = {Klett-Cotta},
+ Series = {Handbuch der europäischen Geschichte},
+ Shorttitle = {Die nordischen Länder},
+ Title = {Die nordischen Länder von der Mitte des 11.~Jahrhunderts bis 1448}}
+
+@incollection{hyman,
+ Annotation = {An incollection entry with a series and number field},
+ Author = {Hyman, Arthur},
+ Booktitle = {Studies in {Aristotle}},
+ Date = 1981,
+ Editor = {O'Meara, Dominic J.},
+ Hyphenation = {american},
+ Indextitle = {Aristotle's Theory of the Intellect},
+ Keywords = {secondary},
+ Location = {Washington, D.C.},
+ Number = 9,
+ Pages = {161-191},
+ Publisher = {The Catholic University of America Press},
+ Series = {Studies in Philosophy and the History of Philosophy},
+ Shorttitle = {Aristotle's Theory of the Intellect},
+ Title = {Aristotle's Theory of the Intellect and its Interpretation by {Averroes}}}
+
+@incollection{pines,
+ Annotation = {A typical incollection entry. Note the indextitle field},
+ Author = {Pines, Shlomo},
+ Booktitle = {Studies in Medieval {Jewish} History and Literature},
+ Date = 1979,
+ Editor = {Twersky, Isadore},
+ Hyphenation = {american},
+ Indextitle = {Limitations of Human Knowledge According to Al-Farabi, ibn Bajja, and Maimonides, The},
+ Keywords = {secondary},
+ Location = {Cambridge, Mass.},
+ Pages = {82-109},
+ Publisher = hup,
+ Shorttitle = {Limitations of Human Knowledge},
+ Title = {The Limitations of Human Knowledge According to {Al-Farabi}, {ibn Bajja}, and {Maimonides}}}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: An incollection entry with a series and a number. Note the
+ format of the printed name and compare the useprefix option in the
+ options field as well as vangennep. Also note the indextitle, and
+ indexsorttitle fields
+ author:
+ - dropping-particle: von
+ family: Brandt
+ given: Ahasver
+ - family: Hoffmann
+ given: Erich
+ collection-number: 2
+ collection-title: Handbuch der europäischen Geschichte
+ container-title: Europa im Hoch- und Spätmittelalter
+ editor:
+ - family: Seibt
+ given: Ferdinand
+ id: brandt
+ issued: 1987
+ language: de-DE
+ page: 884-917
+ publisher: Klett-Cotta
+ publisher-place: Stuttgart
+ title: Die nordischen Länder von der Mitte des 11. Jahrhunderts bis
+ 1448
+ title-short: Die nordischen Länder
+ type: chapter
+- annote: An incollection entry with a series and number field
+ author:
+ - family: Hyman
+ given: Arthur
+ collection-number: 9
+ collection-title: Studies in philosophy and the history of philosophy
+ container-title: Studies in Aristotle
+ editor:
+ - family: O'Meara
+ given: Dominic J.
+ id: hyman
+ issued: 1981
+ keyword: secondary
+ language: en-US
+ page: 161-191
+ publisher: The Catholic University of America Press
+ publisher-place: Washington, D.C.
+ title: Aristotle's theory of the intellect and its interpretation by
+ Averroes
+ title-short: Aristotle's theory of the intellect
+ type: chapter
+- annote: A typical incollection entry. Note the indextitle field
+ author:
+ - family: Pines
+ given: Shlomo
+ container-title: Studies in medieval Jewish history and literature
+ editor:
+ - family: Twersky
+ given: Isadore
+ id: pines
+ issued: 1979
+ keyword: secondary
+ language: en-US
+ page: 82-109
+ publisher: Harvard University Press
+ publisher-place: Cambridge, Mass.
+ title: The limitations of human knowledge according to Al-Farabi, [ibn
+ Bajja]{.nocase}, and Maimonides
+ title-short: Limitations of human knowledge
+ type: chapter
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-inproceedings.md b/documents/markdown/pandoc-md/biblatex-inproceedings.md
new file mode 100644
index 0000000..76b5848
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-inproceedings.md
@@ -0,0 +1,88 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{adapted from http://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/examples/biblatex-examples.bib}
+
+@string{cup = {Cambridge University Press}}
+
+@inproceedings{moraux,
+ Annotation = {This is a typical inproceedings entry. Note the booksubtitle, shorttitle, indextitle, and indexsorttitle fields. Also note the eventdate field.},
+ Author = {Moraux, Paul},
+ Booktitle = {Aristotle on Mind and the Senses},
+ Booktitleaddon = {Proceedings of the Seventh Symposium Aristotelicum},
+ Date = 1979,
+ Editor = {Lloyd, G. E. R. and Owen, G. E. L.},
+ Eventdate = 1975,
+ Hyphenation = {french},
+ Indexsorttitle = {De Anima dans la tradition grecque},
+ Indextitle = {\emph{De Anima} dans la tradition grècque, Le},
+ Keywords = {secondary},
+ Location = {Cambridge},
+ Pages = {281-324},
+ Publisher = cup,
+ Shorttitle = {\emph{De Anima} dans la tradition grècque},
+ Subtitle = {Quelques aspects de l'interpretation du traité, de Theophraste à Themistius},
+ Title = {Le \emph{De Anima} dans la tradition grècque}}
+
+@inproceedings{salam,
+ Author = {Salam, Abdus},
+ Booksubtitle = {Relativistic groups and analyticity},
+ Booktitle = {Elementary particle theory},
+ Booktitleaddon = {Proceedings of the Eighth {Nobel} Symposium},
+ Date = 1968,
+ Editor = {Svartholm, Nils},
+ Eventdate = {1968-05-19/1968-05-25},
+ Location = {Stockholm},
+ Pages = {367-377},
+ Publisher = {Almquist \& Wiksell},
+ Title = {Weak and Electromagnetic Interactions},
+ Venue = {Aspenäsgarden, Lerum}}
+^D
+---
+nocite: "[@*]"
+references:
+- annote: This is a typical inproceedings entry. Note the booksubtitle,
+ shorttitle, indextitle, and indexsorttitle fields. Also note the
+ eventdate field.
+ author:
+ - family: Moraux
+ given: Paul
+ container-title: Aristotle on Mind and the Senses. Proceedings of the
+ Seventh Symposium Aristotelicum
+ editor:
+ - family: Lloyd
+ given: G. E. R.
+ - family: Owen
+ given: G. E. L.
+ event-date: 1975
+ id: moraux
+ issued: 1979
+ keyword: secondary
+ language: fr-FR
+ page: 281-324
+ publisher: Cambridge University Press
+ publisher-place: Cambridge
+ title: "Le *De Anima* dans la tradition grècque: Quelques aspects de
+ l'interpretation du traité, de Theophraste à Themistius"
+ title-short: "*De Anima* dans la tradition grècque"
+ type: paper-conference
+- author:
+ - family: Salam
+ given: Abdus
+ container-title: "Elementary particle theory: Relativistic groups and
+ analyticity. Proceedings of the eighth Nobel symposium"
+ editor:
+ - family: Svartholm
+ given: Nils
+ event-date: 1968-05-19/1968-05-25
+ event-place: Aspenäsgarden, Lerum
+ id: salam
+ issued: 1968
+ page: 367-377
+ publisher: Almquist & Wiksell
+ publisher-place: Stockholm
+ title: Weak and electromagnetic interactions
+ type: paper-conference
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-issue288.md b/documents/markdown/pandoc-md/biblatex-issue288.md
new file mode 100644
index 0000000..dd9d6a7
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-issue288.md
@@ -0,0 +1,35 @@
+```
+% pandoc -f biblatex -t markdown -s
+@thesis{Leavitt_2016,
+location = {{Los Angeles, CA}},
+title = {Upvoting the News: {{Breaking}} News Aggregation, Crowd Collaboration,
+and Algorithm-Driven Attention on Reddit.Com},
+timestamp = {2017-04-06T14:13:22Z},
+langid = {english},
+institution = {{University of Southern California}},
+type = {Dissertation},
+author = {Leavitt, Alex},
+date = {2016-08},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- author:
+ - family: Leavitt
+ given: Alex
+ genre: Dissertation
+ id: Leavitt_2016
+ issued: 2016-08
+ language: en-US
+ publisher: University of Southern California
+ publisher-place: Los Angeles, CA
+ title: "Upvoting the news: Breaking news aggregation, crowd
+ collaboration, and algorithm-driven attention on reddit.com"
+ title-short: Upvoting the news
+ type: thesis
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-itzhaki.md b/documents/markdown/pandoc-md/biblatex-itzhaki.md
new file mode 100644
index 0000000..568e262
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-itzhaki.md
@@ -0,0 +1,82 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Itzhaki 1996)
+
+Itzhaki, Nissan. 1996. “Some Remarks on ’t Hooft’s S-matrix for Black
+Holes” (version 1). March 11.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Itzhaki, 1996)
+
+Itzhaki, N. (1996, March 11). Some remarks on ’t Hooft’s S-matrix for
+black holes.
+
+
+NOTES:
+
+- biblio2yaml:
+ - eprinttype = {arxiv}, eprint = {hep-th/9603067},
+ should be converted to a url: http://arxiv.org/abs/hep-th/9603067
+ (prefix http://arxiv.org/abs/ seems to work for all arxiv material)
+
+- citeproc:
+ - obtaining correct case of "'t Hooft's" in title is possible but awkward:
+ '{t Hooft's} works; {'t Hooft}'s or '{t Hooft}'s do not
+
+}
+
+@Online{itzhaki,
+ author = {Itzhaki, Nissan},
+ title = {Some remarks on '{t Hooft's} {S}-matrix for black holes},
+ date = {1996-03-11},
+ version = 1,
+ hyphenation = {american},
+ eprinttype = {arxiv},
+ eprint = {hep-th/9603067},
+ annotation = {An online reference from arXiv. Note the
+ eprint and eprinttype fields. Also note that
+ the arXiv reference is transformed into a clickable link if
+ hyperref support has been enabled},
+ abstract = {We discuss the limitations of 't Hooft's proposal for the
+ black hole S-matrix. We find that the validity of the S-matrix
+ implies violation of the semi-classical approximation at
+ scales large compared to the Planck scale. We also show that
+ the effect of the centrifugal barrier on the S-matrix is
+ crucial even for large transverse distances.},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- abstract: We discuss the limitations of 't Hooft's proposal for the
+ black hole S-matrix. We find that the validity of the S-matrix
+ implies violation of the semi-classical approximation at scales
+ large compared to the Planck scale. We also show that the effect of
+ the centrifugal barrier on the S-matrix is crucial even for large
+ transverse distances.
+ annote: An online reference from arXiv. Note the eprint and eprinttype
+ fields. Also note that the arXiv reference is transformed into a
+ clickable link if hyperref support has been enabled
+ author:
+ - family: Itzhaki
+ given: Nissan
+ id: itzhaki
+ issued: 1996-03-11
+ language: en-US
+ title: Some remarks on '[t Hooft's]{.nocase} S-matrix for black holes
+ type: webpage
+ url: "https://arxiv.org/abs/hep-th/9603067"
+ version: 1
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-jaffe.md b/documents/markdown/pandoc-md/biblatex-jaffe.md
new file mode 100644
index 0000000..e038177
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-jaffe.md
@@ -0,0 +1,82 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Jaffé 1885–1888)
+
+Jaffé, Philipp, ed. 1885–1888. *Regesta Pontificum Romanorum ab condita
+ecclesia ad annum post Christum natum \<span
+Style="font-variant:small-caps;"\>mcxcviii\</span\>*. 2nd ed. 2.
+Leipzig.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Jaffé, 1885–1888)
+
+Jaffé, P. (Ed.). (1885–1888). *Regesta Pontificum Romanorum ab condita
+ecclesia ad annum post Christum natum \<span
+style="font-variant:small-caps;"\>mcxcviii\</span\>* (2nd ed., 1-2).
+Leipzig.
+
+
+NOTES:
+
+- biblatex conversion:
+ - hyphenation = {latin}
+- citeproc:
+ - "vols." is missing
+ - works in Zotero
+ - This does not show up in the tests from the citeproc test suite that currently fail.
+ - "\<span ...\> needs to be fixed.
+ - maybe add markdown syntax ^^small caps^^ ?
+ - in pandoc "plain" output, small caps could be converted to uppercase chars: "MCXCVIII" would definitely look better here.
+
+}
+
+@Collection{jaffe,
+ editor = {Jaff{\'e}, Philipp},
+ title = {Regesta Pontificum Romanorum ab condita ecclesia ad annum post
+ Christum natum \textsc{mcxcviii}},
+ date = {1885/1888},
+ editora = {Loewenfeld, Samuel and Kaltenbrunner, Ferdinand and Ewald,
+ Paul},
+ edition = 2,
+ volumes = 2,
+ location = {Leipzig},
+ editoratype = {redactor},
+ indextitle = {Regesta Pontificum Romanorum},
+ shorttitle = {Regesta Pontificum Romanorum},
+ annotation = {A collection entry with edition and
+ volumes fields. Note the editora and
+ editoratype fields},
+ hyphenation = {latin},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A collection entry with edition and volumes fields. Note the
+ editora and editoratype fields
+ edition: 2
+ editor:
+ - family: Jaffé
+ given: Philipp
+ id: jaffe
+ issued: 1885/1888
+ language: la
+ number-of-volumes: 2
+ publisher-place: Leipzig
+ title: Regesta Pontificum Romanorum ab condita ecclesia ad annum post
+ Christum natum [mcxcviii]{.smallcaps}
+ title-short: Regesta Pontificum Romanorum
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-jcg.md b/documents/markdown/pandoc-md/biblatex-jcg.md
new file mode 100644
index 0000000..b2cca56
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-jcg.md
@@ -0,0 +1,54 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(“Semantic 3D Media and Content” 2011)
+
+“Semantic 3D Media and Content.” 2011. *Computers and Graphics* 35 (4).
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(“Semantic 3D media and content,” 2011)
+
+Semantic 3D media and content. (2011). *Computers and Graphics*,
+*35*(4).
+
+
+NOTES:
+ - output looks OK even if indistinguishable from article without page numbers
+
+}
+
+@Periodical{jcg,
+ title = {Computers and Graphics},
+ year = 2011,
+ issuetitle = {Semantic {3D} Media and Content},
+ volume = 35,
+ number = 4,
+ issn = {0097-8493},
+ annotation = {This is a periodical entry with an issn
+ field.},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: This is a periodical entry with an issn field.
+ container-title: Computers and Graphics
+ id: jcg
+ issn: 0097-8493
+ issue: 4
+ issued: 2011
+ title: Semantic 3D media and content
+ type: article-journal
+ volume: 35
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-kant-kpv.md b/documents/markdown/pandoc-md/biblatex-kant-kpv.md
new file mode 100644
index 0000000..6504d9c
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-kant-kpv.md
@@ -0,0 +1,90 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Kant 1968)
+
+Kant, Immanuel. 1968. “Kritik der praktischen Vernunft.” In *Kants
+Werke. Akademie Textausgabe*, by Immanuel Kant, 5:1–163. Berlin: Walter
+de Gruyter.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Kant, 1968)
+
+Kant, I. (1968). Kritik der praktischen Vernunft. In *Kants Werke.
+Akademie Textausgabe* (Vol. 5, pp. 1–163). Berlin: Walter de Gruyter.
+
+
+NOTES:
+
+- citeproc
+ - support for the not yet official "volume-title" is missing
+
+- csl style file
+ - if author and container-author are identical, container-author should be suppressed (apparently csl style file issue; zotero shows same behaviour)
+
+}
+
+@InBook{kant:kpv,
+ title = {Kritik der praktischen Vernunft},
+ date = 1968,
+ author = {Kant, Immanuel},
+ booktitle = {Kritik der praktischen Vernunft. Kritik der Urtheilskraft},
+ bookauthor = {Kant, Immanuel},
+ maintitle = {Kants Werke. Akademie Textausgabe},
+ volume = 5,
+ publisher = {Walter de Gruyter},
+ location = {Berlin},
+ pages = {1-163},
+ shorthand = {KpV},
+ hyphenation = {german},
+ shorttitle = {Kritik der praktischen Vernunft},
+ annotation = {An edition of Kant's \emph{Collected Works}, volume five. This
+ is an inbook entry which explicitly refers to the
+ \emph{Critique of Practical Reason} only, not to the entire
+ fifth volume. Note the author and bookauthor
+ fields in the database file. By default, the
+ bookauthor is omitted if the values of the
+ author and bookauthor fields are identical},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: An edition of Kant's *Collected Works*, volume five. This is
+ an inbook entry which explicitly refers to the *Critique of
+ Practical Reason* only, not to the entire fifth volume. Note the
+ author and bookauthor fields in the database file. By default, the
+ bookauthor is omitted if the values of the author and bookauthor
+ fields are identical
+ author:
+ - family: Kant
+ given: Immanuel
+ container-author:
+ - family: Kant
+ given: Immanuel
+ container-title: Kants Werke. Akademie Textausgabe
+ id: "kant:kpv"
+ issued: 1968
+ language: de-DE
+ page: 1-163
+ publisher: Walter de Gruyter
+ publisher-place: Berlin
+ title: Kritik der praktischen Vernunft
+ title-short: Kritik der praktischen Vernunft
+ type: chapter
+ volume: 5
+ volume-title: Kritik der praktischen Vernunft. Kritik der
+ Urtheilskraft
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-kant-ku.md b/documents/markdown/pandoc-md/biblatex-kant-ku.md
new file mode 100644
index 0000000..bfc256e
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-kant-ku.md
@@ -0,0 +1,82 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Kant 1968)
+
+Kant, Immanuel. 1968. “Kritik der Urtheilskraft.” In *Kants Werke.
+Akademie Textausgabe*, by Immanuel Kant, 5:165–485. Berlin: Walter de
+Gruyter.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Kant, 1968)
+
+Kant, I. (1968). Kritik der Urtheilskraft. In *Kants Werke. Akademie
+Textausgabe* (Vol. 5, pp. 165–485). Berlin: Walter de Gruyter.
+
+
+NOTES:
+
+- citeproc
+ - support for the not yet official "volume-title" is missing
+
+- CSL style file
+ - if author and container-author are identical, container-author should be suppressed (apparently csl style file issue; zotero shows same behaviour)
+
+}
+
+@InBook{kant:ku,
+ title = {Kritik der Urtheilskraft},
+ date = 1968,
+ author = {Kant, Immanuel},
+ booktitle = {Kritik der praktischen Vernunft. Kritik der Urtheilskraft},
+ bookauthor = {Kant, Immanuel},
+ maintitle = {Kants Werke. Akademie Textausgabe},
+ volume = 5,
+ publisher = {Walter de Gruyter},
+ location = {Berlin},
+ pages = {165-485},
+ shorthand = {KU},
+ hyphenation = {german},
+ annotation = {An edition of Kant's \emph{Collected Works}, volume five. This
+ is an inbook entry which explicitly refers to the
+ \emph{Critique of Judgment} only, not to the entire fifth
+ volume},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: An edition of Kant's *Collected Works*, volume five. This is
+ an inbook entry which explicitly refers to the *Critique of
+ Judgment* only, not to the entire fifth volume
+ author:
+ - family: Kant
+ given: Immanuel
+ container-author:
+ - family: Kant
+ given: Immanuel
+ container-title: Kants Werke. Akademie Textausgabe
+ id: "kant:ku"
+ issued: 1968
+ language: de-DE
+ page: 165-485
+ publisher: Walter de Gruyter
+ publisher-place: Berlin
+ title: Kritik der Urtheilskraft
+ type: chapter
+ volume: 5
+ volume-title: Kritik der praktischen Vernunft. Kritik der
+ Urtheilskraft
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-kastenholz.md b/documents/markdown/pandoc-md/biblatex-kastenholz.md
new file mode 100644
index 0000000..78fd4b9
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-kastenholz.md
@@ -0,0 +1,126 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Kastenholz and Hünenberger 2006)
+
+Kastenholz, M. A., and Philippe H. Hünenberger. 2006. “Computation of
+Methodologyindependent Ionic Solvation Free Energies from Molecular
+Simulations: I. the Electrostatic Potential in Molecular Liquids.”
+*J. Chem. Phys.* 124.
+doi:[10.1063/1.2172593](https://doi.org/10.1063/1.2172593 "10.1063/1.2172593").
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Kastenholz & Hünenberger, 2006)
+
+Kastenholz, M. A., & Hünenberger, P. H. (2006). Computation of
+methodologyindependent ionic solvation free energies from molecular
+simulations: I. the electrostatic potential in molecular liquids.
+*J. Chem. Phys.*, *124*.
+doi:[10.1063/1.2172593](https://doi.org/10.1063/1.2172593 "10.1063/1.2172593")
+
+
+NOTES:
+
+- biblio2xaml
+ - fix conversion of "\hyphen”
+ - the string "doi:" should not appear as part of the content of the "doi" field
+
+}
+
+@string{ jchph = {J.~Chem. Phys.} }
+
+@Article{kastenholz,
+ author = {Kastenholz, M. A. and H{\"u}nenberger, Philippe H.},
+ title = {Computation of methodology\hyphen independent ionic solvation
+ free energies from molecular simulations},
+ journaltitle = jchph,
+ date = 2006,
+ subtitle = {I. {The} electrostatic potential in molecular liquids},
+ volume = 124,
+ eid = 124106,
+ doi = {10.1063/1.2172593},
+ hyphenation = {american},
+ indextitle = {Computation of ionic solvation free energies},
+ annotation = {An article entry with an eid and a
+ doi field. Note that the \textsc{doi} is transformed
+ into a clickable link if hyperref support has been
+ enabled},
+ abstract = {The computation of ionic solvation free energies from
+ atomistic simulations is a surprisingly difficult problem that
+ has found no satisfactory solution for more than 15 years. The
+ reason is that the charging free energies evaluated from such
+ simulations are affected by very large errors. One of these is
+ related to the choice of a specific convention for summing up
+ the contributions of solvent charges to the electrostatic
+ potential in the ionic cavity, namely, on the basis of point
+ charges within entire solvent molecules (M scheme) or on the
+ basis of individual point charges (P scheme). The use of an
+ inappropriate convention may lead to a charge-independent
+ offset in the calculated potential, which depends on the
+ details of the summation scheme, on the quadrupole-moment
+ trace of the solvent molecule, and on the approximate form
+ used to represent electrostatic interactions in the
+ system. However, whether the M or P scheme (if any) represents
+ the appropriate convention is still a matter of on-going
+ debate. The goal of the present article is to settle this
+ long-standing controversy by carefully analyzing (both
+ analytically and numerically) the properties of the
+ electrostatic potential in molecular liquids (and inside
+ cavities within them).},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- abstract: The computation of ionic solvation free energies from
+ atomistic simulations is a surprisingly difficult problem that has
+ found no satisfactory solution for more than 15 years. The reason is
+ that the charging free energies evaluated from such simulations are
+ affected by very large errors. One of these is related to the choice
+ of a specific convention for summing up the contributions of solvent
+ charges to the electrostatic potential in the ionic cavity, namely,
+ on the basis of point charges within entire solvent molecules (M
+ scheme) or on the basis of individual point charges (P scheme). The
+ use of an inappropriate convention may lead to a charge-independent
+ offset in the calculated potential, which depends on the details of
+ the summation scheme, on the quadrupole-moment trace of the solvent
+ molecule, and on the approximate form used to represent
+ electrostatic interactions in the system. However, whether the M or
+ P scheme (if any) represents the appropriate convention is still a
+ matter of on-going debate. The goal of the present article is to
+ settle this long-standing controversy by carefully analyzing (both
+ analytically and numerically) the properties of the electrostatic
+ potential in molecular liquids (and inside cavities within them).
+ annote: An article entry with an eid and a doi field. Note that the
+ [doi]{.smallcaps} is transformed into a clickable link if hyperref
+ support has been enabled
+ author:
+ - family: Kastenholz
+ given: M. A.
+ - family: Hünenberger
+ given: Philippe H.
+ container-title: J. Chem. Phys.
+ doi: 10.1063/1.2172593
+ id: kastenholz
+ issued: 2006
+ language: en-US
+ title: "Computation of methodology-independent ionic solvation free
+ energies from molecular simulations: I. The electrostatic potential
+ in molecular liquids"
+ title-short: Computation of methodology-independent ionic solvation
+ free energies from molecular simulations
+ type: article-journal
+ volume: 124
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-knuth-ct-a.md b/documents/markdown/pandoc-md/biblatex-knuth-ct-a.md
new file mode 100644
index 0000000..69bc27a
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-knuth-ct-a.md
@@ -0,0 +1,78 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Knuth 1984)
+
+Knuth, Donald E. 1984. *Computers & Typesetting*. Vol. A. Reading,
+Mass.: Addison-Wesley.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Knuth, 1984)
+
+Knuth, D. E. (1984). *Computers & typesetting* (Vol. A). Reading, Mass.:
+Addison-Wesley.
+
+
+NOTES:
+
+- volume-title currently not implemented by chicago-author-date.csl and apa.csl.
+
+}
+
+@Book{knuth:ct:a,
+ author = {Knuth, Donald E.},
+ title = {The {\TeX} book},
+ date = 1984,
+ maintitle = {Computers \& Typesetting},
+ volume = {A},
+ publisher = {Addison-Wesley},
+ location = {Reading, Mass.},
+ hyphenation = {american},
+ sortyear = {1984-1},
+ sorttitle = {Computers & Typesetting A},
+ indexsorttitle= {The TeXbook},
+ indextitle = {\protect\TeX book, The},
+ shorttitle = {\TeX book},
+ annotation = {The first volume of a five-volume book. Note the
+ sorttitle and sortyear fields. We want this
+ volume to be listed after the entry referring to the entire
+ five-volume set. Also note the indextitle and
+ indexsorttitle fields. Indexing packages that don't
+ generate robust index entries require some control sequences
+ to be protected from expansion},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: The first volume of a five-volume book. Note the sorttitle and
+ sortyear fields. We want this volume to be listed after the entry
+ referring to the entire five-volume set. Also note the indextitle
+ and indexsorttitle fields. Indexing packages that don't generate
+ robust index entries require some control sequences to be protected
+ from expansion
+ author:
+ - family: Knuth
+ given: Donald E.
+ id: "knuth:ct:a"
+ issued: 1984
+ language: en-US
+ publisher: Addison-Wesley
+ publisher-place: Reading, Mass.
+ title: Computers & typesetting
+ type: book
+ volume: A
+ volume-title: The TeX book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-knuth-ct-b.md b/documents/markdown/pandoc-md/biblatex-knuth-ct-b.md
new file mode 100644
index 0000000..bff5e54
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-knuth-ct-b.md
@@ -0,0 +1,70 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2015-03-08:
+
+(Knuth 1986)
+
+Knuth, Donald E. 1986. *Computers & Typesetting*. Vol. B. Reading,
+Mass.: Addison-Wesley.
+
+
+Formatted with pandoc and apa.csl, 2015-03-08:
+
+(Knuth, 1986)
+
+Knuth, D. E. (1986). *Computers & typesetting* (Vol. B). Reading, Mass.:
+Addison-Wesley.
+
+
+NOTES:
+
+- volume-title currently not implemented by chicago-author-date.csl and apa.csl.
+
+}
+
+@Book{knuth:ct:b,
+ author = {Knuth, Donald E.},
+ title = {\TeX: {T}he Program},
+ date = 1986,
+ maintitle = {Computers \& Typesetting},
+ volume = {B},
+ publisher = {Addison-Wesley},
+ location = {Reading, Mass.},
+ hyphenation = {american},
+ sortyear = {1986-1},
+ sorttitle = {Computers & Typesetting B},
+ indexsorttitle= {TeX: The Program},
+ shorttitle = {\TeX},
+ annotation = {The second volume of a five-volume book. Note the
+ sorttitle and sortyear fields. Also note the
+ indexsorttitle field},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: The second volume of a five-volume book. Note the sorttitle
+ and sortyear fields. Also note the indexsorttitle field
+ author:
+ - family: Knuth
+ given: Donald E.
+ id: "knuth:ct:b"
+ issued: 1986
+ language: en-US
+ publisher: Addison-Wesley
+ publisher-place: Reading, Mass.
+ title: Computers & typesetting
+ title-short: TeX
+ type: book
+ volume: B
+ volume-title: "TeX: The program"
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-knuth-ct-c.md b/documents/markdown/pandoc-md/biblatex-knuth-ct-c.md
new file mode 100644
index 0000000..2137d6b
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-knuth-ct-c.md
@@ -0,0 +1,69 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2015-03-08:
+
+(Knuth 1986)
+
+Knuth, Donald E. 1986. *Computers & Typesetting*. Vol. C. Reading,
+Mass.: Addison-Wesley.
+
+
+Formatted with pandoc and apa.csl, 2015-03-08:
+
+(Knuth, 1986)
+
+Knuth, D. E. (1986). *Computers & typesetting* (Vol. C). Reading, Mass.:
+Addison-Wesley.
+
+
+NOTES:
+
+- volume-title currently not implemented by chicago-author-date.csl and apa.csl.
+
+}
+
+@Book{knuth:ct:c,
+ author = {Knuth, Donald E.},
+ title = {The {METAFONTbook}},
+ date = 1986,
+ maintitle = {Computers \& Typesetting},
+ volume = {C},
+ publisher = {Addison-Wesley},
+ location = {Reading, Mass.},
+ hyphenation = {american},
+ sortyear = {1986-2},
+ sorttitle = {Computers & Typesetting C},
+ indextitle = {METAFONTbook, The},
+ shorttitle = {{METAFONTbook}},
+ annotation = {The third volume of a five-volume book. Note the
+ sorttitle and sortyear fields as well as the
+ indextitle field},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: The third volume of a five-volume book. Note the sorttitle and
+ sortyear fields as well as the indextitle field
+ author:
+ - family: Knuth
+ given: Donald E.
+ id: "knuth:ct:c"
+ issued: 1986
+ language: en-US
+ publisher: Addison-Wesley
+ publisher-place: Reading, Mass.
+ title: Computers & typesetting
+ type: book
+ volume: C
+ volume-title: The METAFONTbook
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-knuth-ct-d.md b/documents/markdown/pandoc-md/biblatex-knuth-ct-d.md
new file mode 100644
index 0000000..71190f5
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-knuth-ct-d.md
@@ -0,0 +1,71 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2015-03-08:
+
+(Knuth 1986)
+
+Knuth, Donald E. 1986. *Computers & Typesetting*. Vol. D. Reading,
+Mass.: Addison-Wesley.
+
+
+Formatted with pandoc and apa.csl, 2015-03-08:
+
+(Knuth, 1986)
+
+Knuth, D. E. (1986). *Computers & typesetting* (Vol. D). Reading, Mass.:
+Addison-Wesley.
+
+
+NOTES:
+
+- biblio2yaml
+ - Should letters following a colon, such as the "T" in "{{METAFONT}: {T}he Program}" be protected by default? -- I'm not sure ...
+
+- volume-title currently not implemented by chicago-author-date.csl and apa.csl.
+
+}
+
+@Book{knuth:ct:d,
+ author = {Knuth, Donald E.},
+ title = {{METAFONT}: {T}he Program},
+ date = 1986,
+ maintitle = {Computers \& Typesetting},
+ volume = {D},
+ publisher = {Addison-Wesley},
+ location = {Reading, Mass.},
+ hyphenation = {american},
+ sortyear = {1986-3},
+ sorttitle = {Computers & Typesetting D},
+ shorttitle = {{METAFONT}},
+ annotation = {The fourth volume of a five-volume book. Note the
+ sorttitle and sortyear fields},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: The fourth volume of a five-volume book. Note the sorttitle
+ and sortyear fields
+ author:
+ - family: Knuth
+ given: Donald E.
+ id: "knuth:ct:d"
+ issued: 1986
+ language: en-US
+ publisher: Addison-Wesley
+ publisher-place: Reading, Mass.
+ title: Computers & typesetting
+ title-short: METAFONT
+ type: book
+ volume: D
+ volume-title: "METAFONT: The program"
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-knuth-ct-e.md b/documents/markdown/pandoc-md/biblatex-knuth-ct-e.md
new file mode 100644
index 0000000..68b48c1
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-knuth-ct-e.md
@@ -0,0 +1,66 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2015-03-08:
+
+(Knuth 1986)
+
+Knuth, Donald E. 1986. *Computers & Typesetting*. Vol. E. Reading,
+Mass.: Addison-Wesley.
+
+
+Formatted with pandoc and apa.csl, 2015-03-08:
+
+(Knuth, 1986)
+
+Knuth, D. E. (1986). *Computers & typesetting* (Vol. E). Reading, Mass.:
+Addison-Wesley.
+
+
+NOTES:
+
+- volume-title currently not implemented by chicago-author-date.csl and apa.csl.
+
+}
+
+@Book{knuth:ct:e,
+ author = {Knuth, Donald E.},
+ title = {Computer Modern Typefaces},
+ date = 1986,
+ maintitle = {Computers \& Typesetting},
+ volume = {E},
+ publisher = {Addison-Wesley},
+ location = {Reading, Mass.},
+ hyphenation = {american},
+ sortyear = {1986-4},
+ sorttitle = {Computers & Typesetting E},
+ annotation = {The fifth volume of a five-volume book. Note the
+ sorttitle and sortyear fields},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: The fifth volume of a five-volume book. Note the sorttitle and
+ sortyear fields
+ author:
+ - family: Knuth
+ given: Donald E.
+ id: "knuth:ct:e"
+ issued: 1986
+ language: en-US
+ publisher: Addison-Wesley
+ publisher-place: Reading, Mass.
+ title: Computers & typesetting
+ type: book
+ volume: E
+ volume-title: Computer modern typefaces
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-knuth-ct-related.md b/documents/markdown/pandoc-md/biblatex-knuth-ct-related.md
new file mode 100644
index 0000000..ce9dfa9
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-knuth-ct-related.md
@@ -0,0 +1,72 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Knuth 1984–1986)
+
+Knuth, Donald E. 1984–1986. *Computers & Typesetting*. 5. Reading,
+Mass.: Addison-Wesley.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Knuth, 1984–1986)
+
+Knuth, D. E. (1984–1986). *Computers & typesetting* (1-5). Reading,
+Mass.: Addison-Wesley.
+
+
+NOTES:
+
+- biblio2yaml
+ - related = {...}, relatedtype = {multivolume}, -- no counterpart in CSL
+
+- citeproc
+ - term "vols." missing
+
+}
+
+@Book{knuth:ct:related,
+ author = {Knuth, Donald E.},
+ title = {Computers \& Typesetting},
+ date = {1984/1986},
+ volumes = 5,
+ publisher = {Addison-Wesley},
+ location = {Reading, Mass.},
+ hyphenation = {american},
+ sortyear = {1984-0},
+ sorttitle = {Computers & Typesetting},
+ indexsorttitle= {Computers & Typesetting},
+ related = {knuth:ct:a,knuth:ct:b,knuth:ct:c,knuth:ct:d,knuth:ct:e},
+ relatedtype = {multivolume},
+ annotation = {A five-volume book cited as a whole and related to its
+ individual volumes. Note the related and
+ relatedtype fields},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A five-volume book cited as a whole and related to its
+ individual volumes. Note the related and relatedtype fields
+ author:
+ - family: Knuth
+ given: Donald E.
+ id: "knuth:ct:related"
+ issued: 1984/1986
+ language: en-US
+ number-of-volumes: 5
+ publisher: Addison-Wesley
+ publisher-place: Reading, Mass.
+ title: Computers & typesetting
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-knuth-ct.md b/documents/markdown/pandoc-md/biblatex-knuth-ct.md
new file mode 100644
index 0000000..d543d59
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-knuth-ct.md
@@ -0,0 +1,66 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Knuth 1984–1986)
+
+Knuth, Donald E. 1984–1986. *Computers & Typesetting*. 5. Reading,
+Mass.: Addison-Wesley.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Knuth, 1984–1986)
+
+Knuth, D. E. (1984–1986). *Computers & typesetting* (1-5). Reading,
+Mass.: Addison-Wesley.
+
+
+NOTES:
+
+- citeproc
+ - term "vols." is missing
+
+}
+
+@Book{knuth:ct,
+ author = {Knuth, Donald E.},
+ title = {Computers \& Typesetting},
+ date = {1984/1986},
+ volumes = 5,
+ publisher = {Addison-Wesley},
+ location = {Reading, Mass.},
+ hyphenation = {american},
+ sortyear = {1984-0},
+ sorttitle = {Computers & Typesetting},
+ indexsorttitle= {Computers & Typesetting},
+ annotation = {A five-volume book cited as a whole. This is a book
+ entry, note the volumes field},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A five-volume book cited as a whole. This is a book entry,
+ note the volumes field
+ author:
+ - family: Knuth
+ given: Donald E.
+ id: "knuth:ct"
+ issued: 1984/1986
+ language: en-US
+ number-of-volumes: 5
+ publisher: Addison-Wesley
+ publisher-place: Reading, Mass.
+ title: Computers & typesetting
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-kowalik.md b/documents/markdown/pandoc-md/biblatex-kowalik.md
new file mode 100644
index 0000000..431f337
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-kowalik.md
@@ -0,0 +1,68 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Kowalik and Isard 1995)
+
+Kowalik, F., and M. Isard. 1995. “Estimateur d’un défaut de
+fonctionnement d’un modulateur en quadrature et étage de modulation
+l’utilisant.” French patent request.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Kowalik & Isard, 1995)
+
+Kowalik, F., & Isard, M. (1995, January 11). Estimateur d’un défaut de
+fonctionnement d’un modulateur en quadrature et étage de modulation
+l’utilisant. French patent request.
+
+
+}
+
+@Patent{kowalik,
+ author = {Kowalik, F. and Isard, M.},
+ title = {Estimateur d'un d{\'e}faut de fonctionnement d'un modulateur
+ en quadrature et {\'e}tage de modulation l'utilisant},
+ number = 9500261,
+ date = {1995-01-11},
+ type = {patreqfr},
+ hyphenation = {french},
+ indextitle = {Estimateur d'un d{\'e}faut de fonctionnement},
+ annotation = {This is a patent entry for a French patent request
+ with a full date. The number is given in the number
+ field. Note the format of the type and date
+ fields in the database file. Compare almendro,
+ laufenberg, and sorace},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: This is a patent entry for a French patent request with a full
+ date. The number is given in the number field. Note the format of
+ the type and date fields in the database file. Compare almendro,
+ laufenberg, and sorace
+ author:
+ - family: Kowalik
+ given: F.
+ - family: Isard
+ given: M.
+ genre: French patent request
+ id: kowalik
+ issued: 1995-01-11
+ language: fr-FR
+ number: 9500261
+ title: Estimateur d'un défaut de fonctionnement d'un modulateur en
+ quadrature et étage de modulation l'utilisant
+ type: patent
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-kullback-related.md b/documents/markdown/pandoc-md/biblatex-kullback-related.md
new file mode 100644
index 0000000..e0edcc9
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-kullback-related.md
@@ -0,0 +1,62 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Kullback 1997)
+
+Kullback, Solomon. 1997. *Information Theory and Statistics*. New York:
+Dover Publications.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Kullback, 1997)
+
+Kullback, S. (1997). *Information theory and statistics*. New York:
+Dover Publications.
+
+
+NOTES:
+
+- related = {kullback}, relatedtype = {origpubin}, -- not possible in CSL
+
+}
+
+@Book{kullback:related,
+ author = {Kullback, Solomon},
+ title = {Information Theory and Statistics},
+ year = 1997,
+ publisher = {Dover Publications},
+ location = {New York},
+ hyphenation = {american},
+ related = {kullback},
+ relatedtype = {origpubin},
+ annotation = {A reprint of the kullback entry. Note the format of
+ the related and relatedtype fields},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A reprint of the kullback entry. Note the format of the
+ related and relatedtype fields
+ author:
+ - family: Kullback
+ given: Solomon
+ id: "kullback:related"
+ issued: 1997
+ language: en-US
+ publisher: Dover Publications
+ publisher-place: New York
+ title: Information theory and statistics
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-kullback-reprint.md b/documents/markdown/pandoc-md/biblatex-kullback-reprint.md
new file mode 100644
index 0000000..c584309
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-kullback-reprint.md
@@ -0,0 +1,71 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Kullback 1997)
+
+Kullback, Solomon. 1997. *Information Theory and Statistics*. New York:
+Dover Publications.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Kullback, 1997)
+
+Kullback, S. (1997). *Information theory and statistics*. New York:
+Dover Publications.
+
+
+NOTES:
+
+Formatted with chicago-author-date-TEST-20131018.csl
+
+(Kullback [1959] 1997)
+
+Kullback, Solomon. (1959) 1997. *Information Theory and Statistics*. New
+York: Dover Publications.
+
+}
+
+@Book{kullback:reprint,
+ author = {Kullback, Solomon},
+ title = {Information Theory and Statistics},
+ year = 1997,
+ publisher = {Dover Publications},
+ location = {New York},
+ origyear = 1959,
+ origpublisher= {John Wiley \& Sons},
+ hyphenation = {american},
+ annotation = {A reprint of the kullback entry. Note the format of
+ origyear and origpublisher. These fields are
+ not used by the standard bibliography styles},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A reprint of the kullback entry. Note the format of origyear
+ and origpublisher. These fields are not used by the standard
+ bibliography styles
+ author:
+ - family: Kullback
+ given: Solomon
+ id: "kullback:reprint"
+ issued: 1997
+ language: en-US
+ original-date: 1959
+ original-publisher: John Wiley & Sons
+ publisher: Dover Publications
+ publisher-place: New York
+ title: Information theory and statistics
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-kullback.md b/documents/markdown/pandoc-md/biblatex-kullback.md
new file mode 100644
index 0000000..50482df
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-kullback.md
@@ -0,0 +1,52 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Kullback 1959)
+
+Kullback, Solomon. 1959. *Information Theory and Statistics*. New York:
+John Wiley & Sons.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Kullback, 1959)
+
+Kullback, S. (1959). *Information theory and statistics*. New York: John
+Wiley & Sons.
+
+
+}
+
+@Book{kullback,
+ author = {Kullback, Solomon},
+ title = {Information Theory and Statistics},
+ year = 1959,
+ publisher = {John Wiley \& Sons},
+ location = {New York},
+ hyphenation = {american},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- author:
+ - family: Kullback
+ given: Solomon
+ id: kullback
+ issued: 1959
+ language: en-US
+ publisher: John Wiley & Sons
+ publisher-place: New York
+ title: Information theory and statistics
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-laufenberg.md b/documents/markdown/pandoc-md/biblatex-laufenberg.md
new file mode 100644
index 0000000..25a4080
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-laufenberg.md
@@ -0,0 +1,109 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Laufenberg et al. 2006)
+
+Laufenberg, Xaver, Dominique Eynius, Helmut Suelzle, Stephan Usbeck,
+Matthias Spaeth, Miriam Neuser-Hoffmann, Christian Myrzik, et al. 2006.
+“Elektrische Einrichtung und Betriebsverfahren.” European patent.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Laufenberg et al., 2006)
+
+Laufenberg, X., Eynius, D., Suelzle, H., Usbeck, S., Spaeth, M.,
+Neuser-Hoffmann, M., … Ebner, N. (2006, September 13). Elektrische
+Einrichtung und Betriebsverfahren. European patent.
+
+
+NOTES:
+
+- biblio2yaml
+ - Is there any equivalent of "holder" in CSL?
+
+}
+
+@Patent{laufenberg,
+ author = {Laufenberg, Xaver and Eynius, Dominique and Suelzle, Helmut
+ and Usbeck, Stephan and Spaeth, Matthias and Neuser-Hoffmann,
+ Miriam and Myrzik, Christian and Schmid, Manfred and Nietfeld,
+ Franz and Thiel, Alexander and Braun, Harald and Ebner,
+ Norbert},
+ title = {Elektrische Einrichtung und Betriebsverfahren},
+ number = 1700367,
+ date = {2006-09-13},
+ holder = {{Robert Bosch GmbH} and {Daimler Chrysler AG} and {Bayerische
+ Motoren Werke AG}},
+ type = {patenteu},
+ hyphenation = {german},
+ annotation = {This is a patent entry with a holder field.
+ Note the format of the type and location
+ fields in the database file. Compare almendro,
+ sorace, and kowalik},
+ abstract = {The invention relates to an electric device comprising a
+ generator, in particular for use in the vehicle electric
+ system of a motor vehicle and a controller for controlling the
+ generator voltage. The device is equipped with a control zone,
+ in which the voltage is controlled and zones, in which the
+ torque is controlled. The invention also relates to methods
+ for operating a device of this type.},
+ file = {http://v3.espacenet.com/textdoc?IDX=EP1700367},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- abstract: The invention relates to an electric device comprising a
+ generator, in particular for use in the vehicle electric system of a
+ motor vehicle and a controller for controlling the generator
+ voltage. The device is equipped with a control zone, in which the
+ voltage is controlled and zones, in which the torque is controlled.
+ The invention also relates to methods for operating a device of this
+ type.
+ annote: This is a patent entry with a holder field. Note the format of
+ the type and location fields in the database file. Compare almendro,
+ sorace, and kowalik
+ author:
+ - family: Laufenberg
+ given: Xaver
+ - family: Eynius
+ given: Dominique
+ - family: Suelzle
+ given: Helmut
+ - family: Usbeck
+ given: Stephan
+ - family: Spaeth
+ given: Matthias
+ - family: Neuser-Hoffmann
+ given: Miriam
+ - family: Myrzik
+ given: Christian
+ - family: Schmid
+ given: Manfred
+ - family: Nietfeld
+ given: Franz
+ - family: Thiel
+ given: Alexander
+ - family: Braun
+ given: Harald
+ - family: Ebner
+ given: Norbert
+ genre: European patent
+ id: laufenberg
+ issued: 2006-09-13
+ language: de-DE
+ number: 1700367
+ title: Elektrische Einrichtung und Betriebsverfahren
+ type: patent
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-loh.md b/documents/markdown/pandoc-md/biblatex-loh.md
new file mode 100644
index 0000000..3dd9bc8
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-loh.md
@@ -0,0 +1,65 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Loh 1992)
+
+Loh, Nin C. 1992. “High-resolution Micromachined Interferometric
+Accelerometer.” Master’s thesis, Cambridge, Mass.: Massachusetts
+Institute of Technology.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Loh, 1992)
+
+Loh, N. C. (1992). *High-resolution micromachined interferometric
+accelerometer* (Master’s thesis). Massachusetts Institute of Technology,
+Cambridge, Mass.
+
+
+NOTES:
+
+- biblio2yaml
+ - At some point, actual localization of "localization keys" will have to be implemented
+
+}
+
+@Thesis{loh,
+ author = {Loh, Nin C.},
+ title = {High-Resolution Micromachined Interferometric Accelerometer},
+ type = {mathesis},
+ institution = {Massachusetts Institute of Technology},
+ date = 1992,
+ location = {Cambridge, Mass.},
+ hyphenation = {american},
+ annotation = {This is a typical thesis entry for an MA thesis. Note
+ the type field in the database file which uses a
+ localization key},
+}
+^D
+---
+nocite: "[@*]"
+references:
+- annote: This is a typical thesis entry for an MA thesis. Note the type
+ field in the database file which uses a localization key
+ author:
+ - family: Loh
+ given: Nin C.
+ genre: Master's thesis
+ id: loh
+ issued: 1992
+ language: en-US
+ publisher: Massachusetts Institute of Technology
+ publisher-place: Cambridge, Mass.
+ title: High-resolution micromachined interferometric accelerometer
+ type: thesis
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-malinowski.md b/documents/markdown/pandoc-md/biblatex-malinowski.md
new file mode 100644
index 0000000..6e06492
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-malinowski.md
@@ -0,0 +1,67 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Malinowski 1972)
+
+Malinowski, Bronisław. 1972. *Argonauts of the Western Pacific: An
+Account of Native Enterprise and Adventure in the Archipelagoes of
+Melanesian New Guinea*. 8th ed. London: Routledge and Kegan Paul.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Malinowski, 1972)
+
+Malinowski, B. (1972). *Argonauts of the Western Pacific: An account of
+native enterprise and adventure in the Archipelagoes of Melanesian New
+Guinea* (8th ed.). London: Routledge and Kegan Paul.
+
+
+}
+
+@Book{malinowski,
+ author = {Malinowski, Bronis{\l}aw},
+ title = {Argonauts of the {Western Pacific}},
+ date = 1972,
+ edition = 8,
+ publisher = {Routledge {and} Kegan Paul},
+ location = {London},
+ hyphenation = {british},
+ subtitle = {An account of native enterprise and adventure in the
+ {Archipelagoes of Melanesian New Guinea}},
+ shorttitle = {Argonauts},
+ annotation = {This is a book entry. Note the format of the
+ publisher and edition fields as well as the
+ subtitle field},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: This is a book entry. Note the format of the publisher and
+ edition fields as well as the subtitle field
+ author:
+ - family: Malinowski
+ given: Bronisław
+ edition: 8
+ id: malinowski
+ issued: 1972
+ language: en-GB
+ publisher: Routledge and Kegan Paul
+ publisher-place: London
+ title: "Argonauts of the Western Pacific: An account of native
+ enterprise and adventure in the [Archipelagoes of Melanesian New
+ Guinea]{.nocase}"
+ title-short: Argonauts
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-manual.md b/documents/markdown/pandoc-md/biblatex-manual.md
new file mode 100644
index 0000000..83a1b5b
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-manual.md
@@ -0,0 +1,51 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{adapted from http://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/examples/biblatex-examples.bib}
+
+@Manual{cms,
+ title = {The {Chicago} Manual of Style},
+ date = 2003,
+ subtitle = {The Essential Guide for Writers, Editors, and Publishers},
+ edition = 15,
+ publisher = {University of Chicago Press},
+ location = {Chicago, Ill.},
+ isbn = {0-226-10403-6},
+ label = {CMS},
+ hyphenation = {american},
+ sorttitle = {Chicago Manual of Style},
+ indextitle = {Chicago Manual of Style, The},
+ shorttitle = {Chicago Manual of Style},
+ annotation = {This is a manual entry without an author or
+ editor. Note the label field in the database
+ file which is provided for author-year citation styles. Also
+ note the sorttitle and indextitle fields. By
+ default, all entries without an author or
+ editor are alphabetized by title but we want
+ this entry to be alphabetized under \enquote*{C} rather than
+ \enquote*{T}. There's also an isbn field},
+}
+^D
+---
+nocite: "[@*]"
+references:
+- annote: This is a manual entry without an author or editor. Note the
+ label field in the database file which is provided for author-year
+ citation styles. Also note the sorttitle and indextitle fields. By
+ default, all entries without an author or editor are alphabetized by
+ title but we want this entry to be alphabetized under 'C' rather
+ than 'T'. There's also an isbn field
+ edition: 15
+ id: cms
+ isbn: 0-226-10403-6
+ issued: 2003
+ language: en-US
+ publisher: University of Chicago Press
+ publisher-place: Chicago, Ill.
+ title: "The Chicago manual of style: The essential guide for writers,
+ editors, and publishers"
+ title-short: Chicago manual of style
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-markey.md b/documents/markdown/pandoc-md/biblatex-markey.md
new file mode 100644
index 0000000..1343909
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-markey.md
@@ -0,0 +1,65 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Markey 2005)
+
+Markey, Nicolas. 2005. “Tame the BeaST: The B to X of BibTeX” (version
+1.3). October 16.
+<http://tug.ctan.org/tex-archive/info/bibtex/tamethebeast/ttb_en.pdf>.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Markey, 2005)
+
+Markey, N. (2005, October 16). Tame the BeaST: The B to X of BibTeX.
+Retrieved October 01, 2006, from
+<http://tug.ctan.org/tex-archive/info/bibtex/tamethebeast/ttb_en.pdf>
+
+
+}
+
+@Online{markey,
+ author = {Markey, Nicolas},
+ title = {Tame the {BeaST}},
+ date = {2005-10-16},
+ url =
+ {http://tug.ctan.org/tex-archive/info/bibtex/tamethebeast/ttb_en.pdf},
+ subtitle = {The {B} to {X} of {BibTeX}},
+ version = {1.3},
+ urldate = {2006-10-01},
+ hyphenation = {american},
+ sorttitle = {Tame the Beast},
+ annotation = {An online entry for a tutorial. Note the format of
+ the date field (yyyy-mm-dd) in the database
+ file.},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- accessed: 2006-10-01
+ annote: An online entry for a tutorial. Note the format of the date
+ field (yyyy-mm-dd) in the database file.
+ author:
+ - family: Markey
+ given: Nicolas
+ id: markey
+ issued: 2005-10-16
+ language: en-US
+ title: "Tame the BeaST: The B to X of BibTeX"
+ title-short: Tame the BeaST
+ type: webpage
+ url: "http://tug.ctan.org/tex-archive/info/bibtex/tamethebeast/ttb_en.pdf"
+ version: 1.3
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-maron.md b/documents/markdown/pandoc-md/biblatex-maron.md
new file mode 100644
index 0000000..ffa100e
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-maron.md
@@ -0,0 +1,70 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Maron 2000)
+
+Maron, Monika. 2000. *Animal Triste*. Translated by Brigitte Goldstein.
+Lincoln: University of Nebraska Press.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Maron, 2000)
+
+Maron, M. (2000). *Animal triste*. (B. Goldstein, Trans.). Lincoln:
+University of Nebraska Press.
+
+
+NOTES:
+
+- origlanguage concatenated with translator, e.g. “translated from the German by …” not possible in CSL
+
+}
+
+@Book{maron,
+ author = {Maron, Monika},
+ title = {Animal Triste},
+ date = 2000,
+ translator = {Brigitte Goldstein},
+ origlanguage = {german},
+ publisher = {University of Nebraska Press},
+ location = {Lincoln},
+ hyphenation = {american},
+ shorttitle = {Animal Triste},
+ annotation = {An English translation of a German novel with a French title.
+ In other words: a book entry with a
+ translator field. Note the origlanguage
+ field which is concatenated with the translator},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: "An English translation of a German novel with a French title.
+ In other words: a book entry with a translator field. Note the
+ origlanguage field which is concatenated with the translator"
+ author:
+ - family: Maron
+ given: Monika
+ id: maron
+ issued: 2000
+ language: en-US
+ publisher: University of Nebraska Press
+ publisher-place: Lincoln
+ title: Animal triste
+ title-short: Animal triste
+ translator:
+ - family: Goldstein
+ given: Brigitte
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-massa.md b/documents/markdown/pandoc-md/biblatex-massa.md
new file mode 100644
index 0000000..9d8e202
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-massa.md
@@ -0,0 +1,56 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Massa 2004)
+
+Massa, Werner. 2004. *Crystal Structure Determination*. 2nd ed. Berlin:
+Spinger.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Massa, 2004)
+
+Massa, W. (2004). *Crystal structure determination* (2nd ed.). Berlin:
+Spinger.
+
+
+}
+
+@Book{massa,
+ author = {Werner Massa},
+ title = {Crystal structure determination},
+ date = 2004,
+ edition = 2,
+ publisher = {Spinger},
+ location = {Berlin},
+ hyphenation = {british},
+ annotation = {A book entry with an edition field},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A book entry with an edition field
+ author:
+ - family: Massa
+ given: Werner
+ edition: 2
+ id: massa
+ issued: 2004
+ language: en-GB
+ publisher: Spinger
+ publisher-place: Berlin
+ title: Crystal structure determination
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-moore-related.md b/documents/markdown/pandoc-md/biblatex-moore-related.md
new file mode 100644
index 0000000..58270e0
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-moore-related.md
@@ -0,0 +1,66 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Moore 1998)
+
+Moore, Gordon E. 1998. “Cramming More Components onto Integrated
+Circuits.” *Proceedings of the IEEE* 86 (1): 82–85.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Moore, 1998)
+
+Moore, G. E. (1998). Cramming more components onto integrated circuits.
+*Proceedings of the IEEE*, *86*(1), 82–85.
+
+
+NOTES:
+
+- "related = {moore}, relatedtype = {reprintfrom}," – no equivalent implemented in CSL
+
+}
+
+@Article{moore:related,
+ author = {Moore, Gordon E.},
+ title = {Cramming more components onto integrated circuits},
+ journaltitle = {Proceedings of the {IEEE}},
+ year = 1998,
+ volume = 86,
+ number = 1,
+ pages = {82-85},
+ hyphenation = {american},
+ related = {moore},
+ relatedtype = {reprintfrom},
+ annotation = {A reprint of Moore's law. Note the related and
+ relatedtype fields},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A reprint of Moore's law. Note the related and relatedtype
+ fields
+ author:
+ - family: Moore
+ given: Gordon E.
+ container-title: Proceedings of the IEEE
+ id: "moore:related"
+ issue: 1
+ issued: 1998
+ language: en-US
+ page: 82-85
+ title: Cramming more components onto integrated circuits
+ type: article-journal
+ volume: 86
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-moore.md b/documents/markdown/pandoc-md/biblatex-moore.md
new file mode 100644
index 0000000..d4ea5bc
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-moore.md
@@ -0,0 +1,56 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Moore 1965)
+
+Moore, Gordon E. 1965. “Cramming More Components onto Integrated
+Circuits.” *Electronics* 38 (8): 114–117.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Moore, 1965)
+
+Moore, G. E. (1965). Cramming more components onto integrated circuits.
+*Electronics*, *38*(8), 114–117.
+
+
+}
+
+@Article{moore,
+ author = {Moore, Gordon E.},
+ title = {Cramming more components onto integrated circuits},
+ journaltitle = {Electronics},
+ year = 1965,
+ volume = 38,
+ number = 8,
+ pages = {114-117},
+ hyphenation = {american},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- author:
+ - family: Moore
+ given: Gordon E.
+ container-title: Electronics
+ id: moore
+ issue: 8
+ issued: 1965
+ language: en-US
+ page: 114-117
+ title: Cramming more components onto integrated circuits
+ type: article-journal
+ volume: 38
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-moraux.md b/documents/markdown/pandoc-md/biblatex-moraux.md
new file mode 100644
index 0000000..1624ad9
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-moraux.md
@@ -0,0 +1,94 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Moraux 1979)
+
+Moraux, Paul. 1979. “Le *De Anima* dans la tradition grècque: Quelques
+aspects de l’interpretation du traité, de Theophraste à Themistius.” In
+*Aristotle on Mind and the Senses. Proceedings of the Seventh Symposium
+Aristotelicum*, edited by G. E. R. Lloyd and G. E. L. Owen, 281–324.
+Cambridge: Cambridge University Press.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Moraux, 1979)
+
+Moraux, P. (1979). Le *De Anima* dans la tradition grècque: Quelques
+aspects de l’interpretation du traité, de Theophraste à Themistius. In
+G. E. R. Lloyd & G. E. L. Owen (eds.), *Aristotle on Mind and the
+Senses. Proceedings of the Seventh Symposium Aristotelicum* (pp.
+281–324). Cambridge: Cambridge University Press.
+
+
+NOTES:
+
+- Since case (conversion) can only be specified per entry, not per field, for apa.csl the case of container-title would have to be adjusted manually.
+
+}
+
+@string{ cup = {Cambridge University Press} }
+
+@InProceedings{moraux,
+ author = {Moraux, Paul},
+ editor = {Lloyd, G. E. R. and Owen, G. E. L.},
+ title = {Le \emph{De Anima} dans la tradition gr{\`e}cque},
+ date = 1979,
+ booktitle = {Aristotle on Mind and the Senses},
+ subtitle = {Quelques aspects de l'interpretation du trait{\'e}, de
+ Theophraste {\`a} Themistius},
+ booktitleaddon= {Proceedings of the Seventh Symposium Aristotelicum},
+ eventdate = 1975,
+ publisher = cup,
+ location = {Cambridge},
+ pages = {281-324},
+ keywords = {secondary},
+ hyphenation = {french},
+ indexsorttitle= {De Anima dans la tradition grecque},
+ indextitle = {\emph{De Anima} dans la tradition gr{\`e}cque, Le},
+ shorttitle = {\emph{De Anima} dans la tradition gr{\`e}cque},
+ annotation = {This is a typical inproceedings entry. Note the
+ booksubtitle, shorttitle,
+ indextitle, and indexsorttitle fields. Also
+ note the eventdate field.},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: This is a typical inproceedings entry. Note the booksubtitle,
+ shorttitle, indextitle, and indexsorttitle fields. Also note the
+ eventdate field.
+ author:
+ - family: Moraux
+ given: Paul
+ container-title: Aristotle on Mind and the Senses. Proceedings of the
+ Seventh Symposium Aristotelicum
+ editor:
+ - family: Lloyd
+ given: G. E. R.
+ - family: Owen
+ given: G. E. L.
+ event-date: 1975
+ id: moraux
+ issued: 1979
+ keyword: secondary
+ language: fr-FR
+ page: 281-324
+ publisher: Cambridge University Press
+ publisher-place: Cambridge
+ title: "Le *De Anima* dans la tradition grècque: Quelques aspects de
+ l'interpretation du traité, de Theophraste à Themistius"
+ title-short: "*De Anima* dans la tradition grècque"
+ type: paper-conference
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-murray.md b/documents/markdown/pandoc-md/biblatex-murray.md
new file mode 100644
index 0000000..8242e48
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-murray.md
@@ -0,0 +1,105 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Hostetler et al. 1998)
+
+Hostetler, Michael J., Julia E. Wingate, Chuan-Jian Zhong, Jay E.
+Harris, Richard W. Vachet, Michael R. Clark, J. David Londono, et al.
+1998. “Alkanethiolate Gold Cluster Molecules with Core Diameters from
+1.5 to 5.2 nm: Core and Monolayer Properties as a Function of Core
+Size.” *Langmuir* 14 (1): 17–30.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Hostetler et al., 1998)
+
+Hostetler, M. J., Wingate, J. E., Zhong, C.-J., Harris, J. E., Vachet,
+R. W., Clark, M. R., … Murray, R. W. (1998). Alkanethiolate gold cluster
+molecules with core diameters from 1.5 to 5.2 nm: Core and monolayer
+properties as a function of core size. *Langmuir*, *14*(1), 17–30.
+
+
+}
+
+@Article{murray,
+ author = {Hostetler, Michael J. and Wingate, Julia E. and Zhong,
+ Chuan-Jian and Harris, Jay E. and Vachet, Richard W. and
+ Clark, Michael R. and Londono, J. David and Green, Stephen
+ J. and Stokes, Jennifer J. and Wignall, George D. and Glish,
+ Gary L. and Porter, Marc D. and Evans, Neal D. and Murray,
+ Royce W.},
+ title = {Alkanethiolate gold cluster molecules with core diameters from
+ 1.5 to 5.2~{nm}},
+ journaltitle = {Langmuir},
+ date = 1998,
+ subtitle = {Core and monolayer properties as a function of core size},
+ volume = 14,
+ number = 1,
+ pages = {17-30},
+ hyphenation = {american},
+ indextitle = {Alkanethiolate gold cluster molecules},
+ shorttitle = {Alkanethiolate gold cluster molecules},
+ annotation = {An article entry with \arabic{author} authors. By
+ default, long author and editor lists are automatically
+ truncated. This is configurable},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: An article entry with `\arabic{author}`{=latex} authors. By
+ default, long author and editor lists are automatically truncated.
+ This is configurable
+ author:
+ - family: Hostetler
+ given: Michael J.
+ - family: Wingate
+ given: Julia E.
+ - family: Zhong
+ given: Chuan-Jian
+ - family: Harris
+ given: Jay E.
+ - family: Vachet
+ given: Richard W.
+ - family: Clark
+ given: Michael R.
+ - family: Londono
+ given: J. David
+ - family: Green
+ given: Stephen J.
+ - family: Stokes
+ given: Jennifer J.
+ - family: Wignall
+ given: George D.
+ - family: Glish
+ given: Gary L.
+ - family: Porter
+ given: Marc D.
+ - family: Evans
+ given: Neal D.
+ - family: Murray
+ given: Royce W.
+ container-title: Langmuir
+ id: murray
+ issue: 1
+ issued: 1998
+ language: en-US
+ page: 17-30
+ title: "Alkanethiolate gold cluster molecules with core diameters from
+ 1.5 to 5.2 [nm]{.nocase}: Core and monolayer properties as a
+ function of core size"
+ title-short: Alkanethiolate gold cluster molecules
+ type: article-journal
+ volume: 14
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-nietzsche-historie.md b/documents/markdown/pandoc-md/biblatex-nietzsche-historie.md
new file mode 100644
index 0000000..f7eed79
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-nietzsche-historie.md
@@ -0,0 +1,100 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Nietzsche 1988)
+
+Nietzsche, Friedrich. 1988. “Unzeitgemässe Betrachtungen. Zweites Stück:
+Vom Nutzen und Nachtheil der Historie für das Leben.” In *Sämtliche
+Werke: Kritische Studienausgabe*, by Friedrich Nietzsche, edited by
+Giorgio Colli and Mazzino Montinari, 1:243–334. München; Berlin; New
+York: Deutscher Taschenbuch-Verlag; Walter de Gruyter.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Nietzsche, 1988)
+
+Nietzsche, F. (1988). Unzeitgemässe Betrachtungen. Zweites Stück: Vom
+Nutzen und Nachtheil der Historie für das Leben. In G. Colli & M.
+Montinari (eds.), *Sämtliche Werke: Kritische Studienausgabe* (Vol. 1,
+pp. 243–334). München; Berlin; New York: Deutscher Taschenbuch-Verlag;
+Walter de Gruyter.
+
+
+}
+
+@string{ dtv = {Deutscher Taschenbuch-Verlag} }
+
+@InBook{nietzsche:historie,
+ title = {Unzeitgem{\"a}sse Betrachtungen. Zweites St{\"u}ck},
+ date = 1988,
+ author = {Nietzsche, Friedrich},
+ booktitle = {Die Geburt der Trag{\"o}die. Unzeitgem{\"a}{\ss}e
+ Betrachtungen I--IV. Nachgelassene Schriften 1870--1973},
+ bookauthor = {Nietzsche, Friedrich},
+ editor = {Colli, Giorgio and Montinari, Mazzino},
+ subtitle = {Vom Nutzen und Nachtheil der Historie f{\"u}r das Leben},
+ maintitle = {S{\"a}mtliche Werke},
+ mainsubtitle = {Kritische Studienausgabe},
+ volume = 1,
+ publisher = dtv # { and Walter de Gruyter},
+ location = {M{\"u}nchen and Berlin and New York},
+ pages = {243-334},
+ hyphenation = {german},
+ sortyear = {1988-2},
+ sorttitle = {Werke-01-243},
+ indexsorttitle= {Vom Nutzen und Nachtheil der Historie fur das Leben},
+ indextitle = {Vom Nutzen und Nachtheil der Historie f{\"u}r das Leben},
+ shorttitle = {Vom Nutzen und Nachtheil der Historie},
+ annotation = {A single essay from the critical edition of Nietzsche's works.
+ This inbook entry explicitly refers to an essay found
+ in the first volume. Note the title,
+ booktitle, and maintitle fields. Also note
+ the sorttitle and sortyear fields. We want
+ this entry to be listed after the entry referring to the
+ entire first volume},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A single essay from the critical edition of Nietzsche's works.
+ This inbook entry explicitly refers to an essay found in the first
+ volume. Note the title, booktitle, and maintitle fields. Also note
+ the sorttitle and sortyear fields. We want this entry to be listed
+ after the entry referring to the entire first volume
+ author:
+ - family: Nietzsche
+ given: Friedrich
+ container-author:
+ - family: Nietzsche
+ given: Friedrich
+ container-title: "Sämtliche Werke: Kritische Studienausgabe"
+ editor:
+ - family: Colli
+ given: Giorgio
+ - family: Montinari
+ given: Mazzino
+ id: "nietzsche:historie"
+ issued: 1988
+ language: de-DE
+ page: 243-334
+ publisher: Deutscher Taschenbuch-Verlag; Walter de Gruyter
+ publisher-place: München; Berlin; New York
+ title: "Unzeitgemässe Betrachtungen. Zweites Stück: Vom Nutzen und
+ Nachtheil der Historie für das Leben"
+ title-short: Vom Nutzen und Nachtheil der Historie
+ type: chapter
+ volume: 1
+ volume-title: Die Geburt der Tragödie. Unzeitgemäße Betrachtungen
+ I--IV. Nachgelassene Schriften 1870--1973
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-nietzsche-ksa.md b/documents/markdown/pandoc-md/biblatex-nietzsche-ksa.md
new file mode 100644
index 0000000..09e1890
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-nietzsche-ksa.md
@@ -0,0 +1,89 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Nietzsche 1988)
+
+Nietzsche, Friedrich. 1988. *Sämtliche Werke: Kritische Studienausgabe*.
+Edited by Giorgio Colli and Mazzino Montinari. 2nd ed. 15. München;
+Berlin; New York: Deutscher Taschenbuch-Verlag; Walter de Gruyter.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Nietzsche, 1988)
+
+Nietzsche, F. (1988). *Sämtliche Werke: Kritische Studienausgabe*. (G.
+Colli & M. Montinari, eds.) (2nd ed., 1-15). München; Berlin; New York:
+Deutscher Taschenbuch-Verlag; Walter de Gruyter.
+
+
+NOTES:
+
+- biblio2yaml
+ - term "vols." missing
+
+}
+
+@string{ dtv = {Deutscher Taschenbuch-Verlag} }
+
+@Book{nietzsche:ksa,
+ author = {Nietzsche, Friedrich},
+ title = {S{\"a}mtliche Werke},
+ date = 1988,
+ editor = {Colli, Giorgio and Montinari, Mazzino},
+ edition = 2,
+ volumes = 15,
+ publisher = dtv # { and Walter de Gruyter},
+ location = {M{\"u}nchen and Berlin and New York},
+ hyphenation = {german},
+ sortyear = {1988-0},
+ sorttitle = {Werke-00-000},
+ indexsorttitle= {Samtliche Werke},
+ subtitle = {Kritische Studienausgabe},
+ annotation = {The critical edition of Nietzsche's works. This is a
+ book entry referring to a 15-volume work as a
+ whole. Note the volumes field and the format of the
+ publisher and location fields in the
+ database file. Also note the sorttitle and
+ sortyear fields which are used to fine-tune the
+ sorting order of the bibliography. We want this item listed
+ first in the bibliography},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: The critical edition of Nietzsche's works. This is a book
+ entry referring to a 15-volume work as a whole. Note the volumes
+ field and the format of the publisher and location fields in the
+ database file. Also note the sorttitle and sortyear fields which are
+ used to fine-tune the sorting order of the bibliography. We want
+ this item listed first in the bibliography
+ author:
+ - family: Nietzsche
+ given: Friedrich
+ edition: 2
+ editor:
+ - family: Colli
+ given: Giorgio
+ - family: Montinari
+ given: Mazzino
+ id: "nietzsche:ksa"
+ issued: 1988
+ language: de-DE
+ number-of-volumes: 15
+ publisher: Deutscher Taschenbuch-Verlag; Walter de Gruyter
+ publisher-place: München; Berlin; New York
+ title: "Sämtliche Werke: Kritische Studienausgabe"
+ title-short: Sämtliche Werke
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-nietzsche-ksa1.md b/documents/markdown/pandoc-md/biblatex-nietzsche-ksa1.md
new file mode 100644
index 0000000..176ac74
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-nietzsche-ksa1.md
@@ -0,0 +1,95 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2015-03-08:
+
+(Nietzsche 1988)
+
+Nietzsche, Friedrich. 1988. *Sämtliche Werke: Kritische Studienausgabe*.
+Edited by Giorgio Colli and Mazzino Montinari. 2nd ed. Vol. 1. München;
+Berlin; New York: Deutscher Taschenbuch-Verlag; Walter de Gruyter.
+
+
+Formatted with pandoc and apa.csl, 2015-03-08:
+
+(Nietzsche, 1988)
+
+Nietzsche, F. (1988). *Sämtliche Werke: Kritische Studienausgabe*. (G.
+Colli & M. Montinari, eds., F. Nietzsche) (2nd ed., Vol. 1). München;
+Berlin; New York: Deutscher Taschenbuch-Verlag; Walter de Gruyter.
+
+
+NOTES:
+
+- volume-title currently not implemented by chicago-author-date.csl and apa.csl.
+
+}
+
+@string{ dtv = {Deutscher Taschenbuch-Verlag} }
+
+@Book{nietzsche:ksa1,
+ author = {Nietzsche, Friedrich},
+ title = {Die Geburt der Trag{\"o}die. Unzeitgem{\"a}{\ss}e
+ Betrachtungen I--IV. Nachgelassene Schriften 1870--1973},
+ date = 1988,
+ editor = {Colli, Giorgio and Montinari, Mazzino},
+ maintitle = {S{\"a}mtliche Werke},
+ mainsubtitle = {Kritische Studienausgabe},
+ volume = 1,
+ edition = 2,
+ publisher = dtv # { and Walter de Gruyter},
+ location = {M{\"u}nchen and Berlin and New York},
+ hyphenation = {german},
+ sortyear = {1988-1},
+ sorttitle = {Werke-01-000},
+ indexsorttitle= {Samtliche Werke I},
+ bookauthor = {Nietzsche, Friedrich},
+ indextitle = {S{\"a}mtliche Werke I},
+ shorttitle = {S{\"a}mtliche Werke I},
+ annotation = {A single volume from the critical edition of Nietzsche's
+ works. This book entry explicitly refers to the first
+ volume only. Note the title and maintitle
+ fields. Also note the sorttitle and sortyear
+ fields. We want this entry to be listed after the entry
+ referring to the entire edition},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A single volume from the critical edition of Nietzsche's
+ works. This book entry explicitly refers to the first volume only.
+ Note the title and maintitle fields. Also note the sorttitle and
+ sortyear fields. We want this entry to be listed after the entry
+ referring to the entire edition
+ author:
+ - family: Nietzsche
+ given: Friedrich
+ container-author:
+ - family: Nietzsche
+ given: Friedrich
+ edition: 2
+ editor:
+ - family: Colli
+ given: Giorgio
+ - family: Montinari
+ given: Mazzino
+ id: "nietzsche:ksa1"
+ issued: 1988
+ language: de-DE
+ publisher: Deutscher Taschenbuch-Verlag; Walter de Gruyter
+ publisher-place: München; Berlin; New York
+ title: "Sämtliche Werke: Kritische Studienausgabe"
+ type: book
+ volume: 1
+ volume-title: Die Geburt der Tragödie. Unzeitgemäße Betrachtungen
+ I--IV. Nachgelassene Schriften 1870--1973
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-online.md b/documents/markdown/pandoc-md/biblatex-online.md
new file mode 100644
index 0000000..f2e87f5
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-online.md
@@ -0,0 +1,64 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{adapted from http://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/examples/biblatex-examples.bib}
+
+@online{markey,
+ Annotation = {An online entry for a tutorial. Note the format of the date field (yyyy-mm-dd) in the database file.},
+ Author = {Markey, Nicolas},
+ Date = {2005-10-16},
+ Hyphenation = {american},
+ Sorttitle = {Tame the Beast},
+ Subtitle = {The {B} to {X} of {BibTeX}},
+ Title = {Tame the {BeaST}},
+ Url = {http://tug.ctan.org/tex-archive/info/bibtex/tamethebeast/ttb_en.pdf},
+ Urldate = {2006-10-01},
+ Version = {1.3},
+}
+
+@online{CTAN,
+ Annotation = {This is an online entry. The \textsc{url}, which is given in the url field, is transformed into a clickable link if hyperref support has been enabled. Note the format of the urldate field (yyyy-mm-dd) in the database file. Also note the label field which may be used as a fallback by citation styles which need an author and\slash or a year},
+ Date = 2006,
+ Hyphenation = {american},
+ Label = {CTAN},
+ Subtitle = {The {Comprehensive TeX Archive Network}},
+ Title = {{CTAN}},
+ Url = {http://www.ctan.org},
+ Urldate = {2006-10-01},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- accessed: 2006-10-01
+ annote: An online entry for a tutorial. Note the format of the date
+ field (yyyy-mm-dd) in the database file.
+ author:
+ - family: Markey
+ given: Nicolas
+ id: markey
+ issued: 2005-10-16
+ language: en-US
+ title: "Tame the BeaST: The B to X of BibTeX"
+ title-short: Tame the BeaST
+ type: webpage
+ url: "http://tug.ctan.org/tex-archive/info/bibtex/tamethebeast/ttb_en.pdf"
+ version: 1.3
+- accessed: 2006-10-01
+ annote: This is an online entry. The [url]{.smallcaps}, which is given
+ in the url field, is transformed into a clickable link if hyperref
+ support has been enabled. Note the format of the urldate field
+ (yyyy-mm-dd) in the database file. Also note the label field which
+ may be used as a fallback by citation styles which need an author
+ and/or a year
+ id: CTAN
+ issued: 2006
+ language: en-US
+ title: "CTAN: The Comprehensive TeX Archive Network"
+ title-short: CTAN
+ type: webpage
+ url: "http://www.ctan.org"
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-options-url-false-doi-false.md b/documents/markdown/pandoc-md/biblatex-options-url-false-doi-false.md
new file mode 100644
index 0000000..abba65e
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-options-url-false-doi-false.md
@@ -0,0 +1,57 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Entry contains url and doi fields; these should be discarded since the
+options field specifies url=false, doi=false.
+
+Exception: As in standard biblatex, in online entries url should never be
+discarded, even if options contains url=false.
+
+}
+
+@article{item1,
+ Author = {Author, Andy},
+ Date = {2012},
+ Doi = {1234/5678.90},
+ Journal = {Journal},
+ Options = {url=false, doi=false},
+ Title = {Title, Any Entry Type Except online},
+ Url = {http://foo.bar}
+}
+
+@online{item2,
+ Author = {Author, Andy},
+ Date = {2012},
+ Doi = {1234/5678.90},
+ Journal = {Journal},
+ Options = {url=false, doi=false},
+ Title = {Title, Entry Type online},
+ Url = {http://foo.bar}
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- author:
+ - family: Author
+ given: Andy
+ container-title: Journal
+ id: item1
+ issued: 2012
+ title: Title, any entry type except online
+ type: article-journal
+- author:
+ - family: Author
+ given: Andy
+ container-title: Journal
+ id: item2
+ issued: 2012
+ title: Title, entry type online
+ type: webpage
+ url: "http://foo.bar"
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-padhye.md b/documents/markdown/pandoc-md/biblatex-padhye.md
new file mode 100644
index 0000000..9f3af15
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-padhye.md
@@ -0,0 +1,117 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Padhye, Firoiu, and Towsley 1999)
+
+Padhye, Jitendra, Victor Firoiu, and Don Towsley. 1999. “A Stochastic
+Model of TCP Reno Congestion Avoidance and Control.” Technical report
+99-02. Amherst, Mass.: University of Massachusetts.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Padhye, Firoiu, & Towsley, 1999)
+
+Padhye, J., Firoiu, V., & Towsley, D. (1999). *A stochastic model of TCP
+Reno congestion avoidance and control* (technical report No. 99-02).
+Amherst, Mass.: University of Massachusetts.
+
+}
+
+@Report{padhye,
+ author = {Padhye, Jitendra and Firoiu, Victor and Towsley, Don},
+ title = {A Stochastic Model of {TCP Reno} Congestion Avoidance and
+ Control},
+ type = {techreport},
+ institution = {University of Massachusetts},
+ date = 1999,
+ number = {99-02},
+ location = {Amherst, Mass.},
+ hyphenation = {american},
+ sorttitle = {A Stochastic Model of TCP Reno Congestion Avoidance and
+ Control},
+ indextitle = {Stochastic Model of {TCP Reno} Congestion Avoidance and Control,
+ A},
+ annotation = {This is a report entry for a technical report. Note
+ the format of the type field in the database file
+ which uses a localization key. The number of the report is
+ given in the number field. Also note the
+ sorttitle and indextitle fields},
+ abstract = {The steady state performance of a bulk transfer TCP flow
+ (i.e., a flow with a large amount of data to send, such as FTP
+ transfers) may be characterized by three quantities. The first
+ is the send rate, which is the amount of data sent by the
+ sender in unit time. The second is the throughput, which is
+ the amount of data received by the receiver in unit time. Note
+ that the throughput will always be less than or equal to the
+ send rate due to losses. Finally, the number of non-duplicate
+ packets received by the receiver in unit time gives us the
+ goodput of the connection. The goodput is always less than or
+ equal to the throughput, since the receiver may receive two
+ copies of the same packet due to retransmissions by the
+ sender. In a previous paper, we presented a simple model for
+ predicting the steady state send rate of a bulk transfer TCP
+ flow as a function of loss rate and round trip time. In this
+ paper, we extend that work in two ways. First, we analyze the
+ performance of bulk transfer TCP flows using more precise,
+ stochastic analysis. Second, we build upon the previous
+ analysis to provide both an approximate formula as well as a
+ more accurate stochastic model for the steady state throughput
+ of a bulk transfer TCP flow.},
+ file = {ftp://gaia.cs.umass.edu/pub/Padhey99-markov.ps},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- abstract: The steady state performance of a bulk transfer TCP flow
+ (i.e., a flow with a large amount of data to send, such as FTP
+ transfers) may be characterized by three quantities. The first is
+ the send rate, which is the amount of data sent by the sender in
+ unit time. The second is the throughput, which is the amount of data
+ received by the receiver in unit time. Note that the throughput will
+ always be less than or equal to the send rate due to losses.
+ Finally, the number of non-duplicate packets received by the
+ receiver in unit time gives us the goodput of the connection. The
+ goodput is always less than or equal to the throughput, since the
+ receiver may receive two copies of the same packet due to
+ retransmissions by the sender. In a previous paper, we presented a
+ simple model for predicting the steady state send rate of a bulk
+ transfer TCP flow as a function of loss rate and round trip time. In
+ this paper, we extend that work in two ways. First, we analyze the
+ performance of bulk transfer TCP flows using more precise,
+ stochastic analysis. Second, we build upon the previous analysis to
+ provide both an approximate formula as well as a more accurate
+ stochastic model for the steady state throughput of a bulk transfer
+ TCP flow.
+ annote: This is a report entry for a technical report. Note the format
+ of the type field in the database file which uses a localization
+ key. The number of the report is given in the number field. Also
+ note the sorttitle and indextitle fields
+ author:
+ - family: Padhye
+ given: Jitendra
+ - family: Firoiu
+ given: Victor
+ - family: Towsley
+ given: Don
+ genre: technical report
+ id: padhye
+ issued: 1999
+ language: en-US
+ number: 99-02
+ publisher: University of Massachusetts
+ publisher-place: Amherst, Mass.
+ title: A stochastic model of TCP Reno congestion avoidance and control
+ type: report
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-patent.md b/documents/markdown/pandoc-md/biblatex-patent.md
new file mode 100644
index 0000000..14be455
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-patent.md
@@ -0,0 +1,158 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{adapted from http://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/examples/biblatex-examples.bib
+
+TODO: Is there a CSL counterpart for the biblatex field "holder"?}
+
+
+@patent{almendro,
+ Annotation = {This is a patent entry with a location field. The number is given in the number field. Note the format of the location field in the database file. Compare laufenberg, sorace, and kowalik},
+ Author = {Almendro, José L. and Martín, Jacinto and Sánchez, Alberto and Nozal, Fernando},
+ Date = 1998,
+ Hyphenation = {german},
+ Location = {countryfr and countryuk and countryde},
+ Number = {EU-29702195U},
+ Title = {Elektromagnetisches Signalhorn}}
+
+@patent{kowalik,
+ Annotation = {This is a patent entry for a French patent request with a full date. The number is given in the number field. Note the format of the type and date fields in the database file. Compare almendro, laufenberg, and sorace},
+ Author = {Kowalik, F. and Isard, M.},
+ Date = {1995-01-11},
+ Hyphenation = {french},
+ Indextitle = {Estimateur d'un défaut de fonctionnement},
+ Number = 9500261,
+ Title = {Estimateur d'un défaut de fonctionnement d'un modulateur en quadrature et étage de modulation l'utilisant},
+ Type = {patreqfr}}
+
+@patent{laufenberg,
+ Annotation = {This is a patent entry with a holder field. Note the format of the type and location fields in the database file. Compare almendro, sorace, and kowalik},
+ Author = {Laufenberg, Xaver and Eynius, Dominique and Suelzle, Helmut and Usbeck, Stephan and Spaeth, Matthias and Neuser-Hoffmann, Miriam and Myrzik, Christian and Schmid, Manfred and Nietfeld, Franz and Thiel, Alexander and Braun, Harald and Ebner, Norbert},
+ Date = {2006-09-13},
+ File = {http://v3.espacenet.com/textdoc?IDX=EP1700367},
+ Holder = {{Robert Bosch GmbH} and {Daimler Chrysler AG} and {Bayerische Motoren Werke AG}},
+ Hyphenation = {german},
+ Number = 1700367,
+ Title = {Elektrische Einrichtung und Betriebsverfahren},
+ Type = {patenteu},
+ Abstract = {The invention relates to an electric device comprising a
+ generator, in particular for use in the vehicle electric
+ system of a motor vehicle and a controller for controlling the
+ generator voltage. The device is equipped with a control zone,
+ in which the voltage is controlled and zones, in which the
+ torque is controlled. The invention also relates to methods
+ for operating a device of this type.}}
+
+@patent{sorace,
+ Annotation = {This is a patent entry with a holder field. Note the format of the type and date fields in the database file. Compare almendro, laufenberg, and kowalik},
+ Author = {Sorace, Ronald E. and Reinhardt, Victor S. and Vaughn, Steven A.},
+ Date = {1997-09-16},
+ Date-Modified = {2013-10-16 13:44:15 +0000},
+ Holder = {{Hughes Aircraft Company}},
+ Hyphenation = {american},
+ Number = 5668842,
+ Title = {High-Speed Digital-to-{RF} Converter},
+ Type = {patentus}}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: This is a patent entry with a location field. The number is
+ given in the number field. Note the format of the location field in
+ the database file. Compare laufenberg, sorace, and kowalik
+ author:
+ - family: Almendro
+ given: José L.
+ - family: Martín
+ given: Jacinto
+ - family: Sánchez
+ given: Alberto
+ - family: Nozal
+ given: Fernando
+ id: almendro
+ issued: 1998
+ jurisdiction: France; United Kingdom; Germany
+ language: de-DE
+ number: EU-29702195U
+ title: Elektromagnetisches Signalhorn
+ type: patent
+- annote: This is a patent entry for a French patent request with a full
+ date. The number is given in the number field. Note the format of
+ the type and date fields in the database file. Compare almendro,
+ laufenberg, and sorace
+ author:
+ - family: Kowalik
+ given: F.
+ - family: Isard
+ given: M.
+ genre: French patent request
+ id: kowalik
+ issued: 1995-01-11
+ language: fr-FR
+ number: 9500261
+ title: Estimateur d'un défaut de fonctionnement d'un modulateur en
+ quadrature et étage de modulation l'utilisant
+ type: patent
+- abstract: The invention relates to an electric device comprising a
+ generator, in particular for use in the vehicle electric system of a
+ motor vehicle and a controller for controlling the generator
+ voltage. The device is equipped with a control zone, in which the
+ voltage is controlled and zones, in which the torque is controlled.
+ The invention also relates to methods for operating a device of this
+ type.
+ annote: This is a patent entry with a holder field. Note the format of
+ the type and location fields in the database file. Compare almendro,
+ sorace, and kowalik
+ author:
+ - family: Laufenberg
+ given: Xaver
+ - family: Eynius
+ given: Dominique
+ - family: Suelzle
+ given: Helmut
+ - family: Usbeck
+ given: Stephan
+ - family: Spaeth
+ given: Matthias
+ - family: Neuser-Hoffmann
+ given: Miriam
+ - family: Myrzik
+ given: Christian
+ - family: Schmid
+ given: Manfred
+ - family: Nietfeld
+ given: Franz
+ - family: Thiel
+ given: Alexander
+ - family: Braun
+ given: Harald
+ - family: Ebner
+ given: Norbert
+ genre: European patent
+ id: laufenberg
+ issued: 2006-09-13
+ language: de-DE
+ number: 1700367
+ title: Elektrische Einrichtung und Betriebsverfahren
+ type: patent
+- annote: This is a patent entry with a holder field. Note the format of
+ the type and date fields in the database file. Compare almendro,
+ laufenberg, and kowalik
+ author:
+ - family: Sorace
+ given: Ronald E.
+ - family: Reinhardt
+ given: Victor S.
+ - family: Vaughn
+ given: Steven A.
+ genre: U.S. patent
+ id: sorace
+ issued: 1997-09-16
+ language: en-US
+ number: 5668842
+ title: High-speed digital-to-RF converter
+ type: patent
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-periodical.md b/documents/markdown/pandoc-md/biblatex-periodical.md
new file mode 100644
index 0000000..87b8055
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-periodical.md
@@ -0,0 +1,31 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{excerpt from
+http://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/examples/biblatex-examples.bib}
+
+@periodical{jcg,
+ Annotation = {This is a periodical entry with an issn field.},
+ Issn = {0097-8493},
+ Issuetitle = {Semantic {3D} Media and Content},
+ Number = 4,
+ Title = {Computers and Graphics},
+ Volume = 35,
+ Year = 2011}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: This is a periodical entry with an issn field.
+ container-title: Computers and Graphics
+ id: jcg
+ issn: 0097-8493
+ issue: 4
+ issued: 2011
+ title: Semantic 3D media and content
+ type: article-journal
+ volume: 35
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-piccato.md b/documents/markdown/pandoc-md/biblatex-piccato.md
new file mode 100644
index 0000000..1f81da3
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-piccato.md
@@ -0,0 +1,59 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Piccato 2001)
+
+Piccato, Pablo. 2001. *City of Suspects: Crime in Mexico City,
+1900–1931*. Durham; London: Duke University Press.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Piccato, 2001)
+
+Piccato, P. (2001). *City of suspects: Crime in Mexico City, 1900–1931*.
+Durham; London: Duke University Press.
+
+
+}
+
+@Book{piccato,
+ author = {Piccato, Pablo},
+ title = {City of Suspects},
+ date = 2001,
+ publisher = {Duke University Press},
+ location = {Durham and London},
+ hyphenation = {american},
+ subtitle = {Crime in {Mexico City}, 1900--1931},
+ shorttitle = {City of Suspects},
+ annotation = {This is a book entry. Note the format of the
+ location field in the database file},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: This is a book entry. Note the format of the location field in
+ the database file
+ author:
+ - family: Piccato
+ given: Pablo
+ id: piccato
+ issued: 2001
+ language: en-US
+ publisher: Duke University Press
+ publisher-place: Durham; London
+ title: "City of suspects: Crime in Mexico City, 1900--1931"
+ title-short: City of suspects
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-pines.md b/documents/markdown/pandoc-md/biblatex-pines.md
new file mode 100644
index 0000000..f19ece8
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-pines.md
@@ -0,0 +1,77 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Pines 1979)
+
+Pines, Shlomo. 1979. “The Limitations of Human Knowledge According to
+Al-Farabi, ibn Bajja, and Maimonides.” In *Studies in Medieval Jewish
+History and Literature*, edited by Isadore Twersky, 82–109. Cambridge,
+Mass.: Harvard University Press.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Pines, 1979)
+
+Pines, S. (1979). The limitations of human knowledge according to
+Al-Farabi, ibn Bajja, and Maimonides. In I. Twersky (Ed.), *Studies in
+medieval Jewish history and literature* (pp. 82–109). Cambridge, Mass.:
+Harvard University Press.
+
+
+}
+
+@string{ hup = {Harvard University Press} }
+
+@InCollection{pines,
+ author = {Pines, Shlomo},
+ editor = {Twersky, Isadore},
+ title = {The Limitations of Human Knowledge According to {Al-Farabi}, {ibn
+ Bajja}, and {Maimonides}},
+ date = 1979,
+ booktitle = {Studies in Medieval {Jewish} History and Literature},
+ publisher = hup,
+ location = {Cambridge, Mass.},
+ pages = {82-109},
+ keywords = {secondary},
+ hyphenation = {american},
+ indextitle = {Limitations of Human Knowledge According to {Al-Farabi}, {ibn
+ Bajja}, and {Maimonides}, The},
+ shorttitle = {Limitations of Human Knowledge},
+ annotation = {A typical incollection entry. Note the
+ indextitle field},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A typical incollection entry. Note the indextitle field
+ author:
+ - family: Pines
+ given: Shlomo
+ container-title: Studies in medieval Jewish history and literature
+ editor:
+ - family: Twersky
+ given: Isadore
+ id: pines
+ issued: 1979
+ keyword: secondary
+ language: en-US
+ page: 82-109
+ publisher: Harvard University Press
+ publisher-place: Cambridge, Mass.
+ title: The limitations of human knowledge according to Al-Farabi, [ibn
+ Bajja]{.nocase}, and Maimonides
+ title-short: Limitations of human knowledge
+ type: chapter
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-quotes.md b/documents/markdown/pandoc-md/biblatex-quotes.md
new file mode 100644
index 0000000..5005531
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-quotes.md
@@ -0,0 +1,44 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{excerpt from http://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/examples/biblatex-examples.bib
+
+\mkbibquote{} should be replaced by a matching set of quotation marks that can be used by citeproc for quote substitution and flipflopping. English smart double quotation marks seem best, as they cannot be confused with apostrophes.
+
+\enquote{}, \enquote*{} should be replaced by a matching set of quotation marks, too: “foo”, ‘bar’.
+}
+
+@string{pup = {Princeton University Press}}
+
+@book{nussbaum,
+ Annotation = {A book entry. Note the sorttitle and indexsorttitle fields and the markup of the quotes in the database file},
+ Author = {Nussbaum, Martha},
+ Date = 1978,
+ Hyphenation = {american},
+ Indexsorttitle = {Aristotle's De Motu Animalium},
+ Keywords = {secondary},
+ Location = {Princeton},
+ Publisher = pup,
+ Sorttitle = {Aristotle's De Motu Animalium},
+ Title = {Aristotle's \mkbibquote{De Motu Animalium}}}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A book entry. Note the sorttitle and indexsorttitle fields and
+ the markup of the quotes in the database file
+ author:
+ - family: Nussbaum
+ given: Martha
+ id: nussbaum
+ issued: 1978
+ keyword: secondary
+ language: en-US
+ publisher: Princeton University Press
+ publisher-place: Princeton
+ title: Aristotle's "De Motu Animalium"
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-reese.md b/documents/markdown/pandoc-md/biblatex-reese.md
new file mode 100644
index 0000000..af02c2b
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-reese.md
@@ -0,0 +1,71 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Reese 1958)
+
+Reese, Trevor R. 1958. “Georgia in Anglo-Spanish Diplomacy, 1736-1739.”
+*William and Mary Quarterly, 3* 15: 168–190.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Reese, 1958)
+
+Reese, T. R. (1958). Georgia in Anglo-Spanish diplomacy, 1736-1739.
+*William and Mary Quarterly, 3*, *15*, 168–190.
+
+
+NOTES:
+
+- biblio2yaml
+ - series field: still not entirely satisfactory.
+ Could we map this to some existing CSL variable, and have the CSL styles handle this? "edition", maybe ??
+
+}
+
+@Article{reese,
+ author = {Reese, Trevor R.},
+ title = {Georgia in {Anglo-Spanish} Diplomacy, 1736-1739},
+ journaltitle = {William and Mary Quarterly},
+ date = 1958,
+ series = 3,
+ volume = 15,
+ pages = {168-190},
+ hyphenation = {american},
+ annotation = {An article entry with a series and a
+ volume field. Note the format of the series. If the
+ value of the series field is an integer, this number
+ is printed as an ordinal and the string \enquote*{series} is
+ appended automatically},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: An article entry with a series and a volume field. Note the
+ format of the series. If the value of the series field is an
+ integer, this number is printed as an ordinal and the string
+ 'series' is appended automatically
+ author:
+ - family: Reese
+ given: Trevor R.
+ collection-title: 3rd series
+ container-title: William and Mary Quarterly
+ id: reese
+ issued: 1958
+ language: en-US
+ page: 168-190
+ title: Georgia in Anglo-Spanish diplomacy, 1736-1739
+ type: article-journal
+ volume: 15
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-report.md b/documents/markdown/pandoc-md/biblatex-report.md
new file mode 100644
index 0000000..06ad140
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-report.md
@@ -0,0 +1,119 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{excerpt from http://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/examples/biblatex-examples.bib
+
+TODO: Where to map "file" field?
+}
+
+@report{chiu,
+ Annotation = {This is a report entry for a research report. Note the format of the type field in the database file which uses a localization key. The number of the report is given in the number field. Also note the sorttitle and indextitle fields},
+ Author = {Chiu, Willy W. and Chow, We Min},
+ Date = 1978,
+ Hyphenation = {american},
+ Indextitle = {Hybrid Hierarchical Model, A},
+ Institution = {IBM},
+ Number = {RC-6947},
+ Sorttitle = {Hybrid Hierarchical Model of a Multiple Virtual Storage (MVS) Operating System},
+ Title = {A Hybrid Hierarchical Model of a {Multiple Virtual Storage} ({MVS}) Operating System},
+ Type = {resreport}}
+
+@report{padhye,
+ Annotation = {This is a report entry for a technical report. Note the format of the type field in the database file which uses a localization key. The number of the report is given in the number field. Also note the sorttitle and indextitle fields},
+ Author = {Padhye, Jitendra and Firoiu, Victor and Towsley, Don},
+ Date = 1999,
+ File = {ftp://gaia.cs.umass.edu/pub/Padhey99-markov.ps},
+ Hyphenation = {american},
+ Indextitle = {Stochastic Model of TCP Reno Congestion Avoidance and Control, A},
+ Institution = {University of Massachusetts},
+ Location = {Amherst, Mass.},
+ Number = {99-02},
+ Sorttitle = {A Stochastic Model of TCP Reno Congestion Avoidance and Control},
+ Title = {A Stochastic Model of {TCP Reno} Congestion Avoidance and Control},
+ Type = {techreport},
+ Abstract = {The steady state performance of a bulk transfer TCP flow
+ (i.e., a flow with a large amount of data to send, such as FTP
+ transfers) may be characterized by three quantities. The first
+ is the send rate, which is the amount of data sent by the
+ sender in unit time. The second is the throughput, which is
+ the amount of data received by the receiver in unit time. Note
+ that the throughput will always be less than or equal to the
+ send rate due to losses. Finally, the number of non-duplicate
+ packets received by the receiver in unit time gives us the
+ goodput of the connection. The goodput is always less than or
+ equal to the throughput, since the receiver may receive two
+ copies of the same packet due to retransmissions by the
+ sender. In a previous paper, we presented a simple model for
+ predicting the steady state send rate of a bulk transfer TCP
+ flow as a function of loss rate and round trip time. In this
+ paper, we extend that work in two ways. First, we analyze the
+ performance of bulk transfer TCP flows using more precise,
+ stochastic analysis. Second, we build upon the previous
+ analysis to provide both an approximate formula as well as a
+ more accurate stochastic model for the steady state throughput
+ of a bulk transfer TCP flow.}}
+^D
+---
+nocite: "[@*]"
+references:
+- annote: This is a report entry for a research report. Note the format
+ of the type field in the database file which uses a localization
+ key. The number of the report is given in the number field. Also
+ note the sorttitle and indextitle fields
+ author:
+ - family: Chiu
+ given: Willy W.
+ - family: Chow
+ given: We Min
+ genre: research report
+ id: chiu
+ issued: 1978
+ language: en-US
+ number: RC-6947
+ publisher: IBM
+ title: A hybrid hierarchical model of a Multiple Virtual Storage (MVS)
+ operating system
+ type: report
+- abstract: The steady state performance of a bulk transfer TCP flow
+ (i.e., a flow with a large amount of data to send, such as FTP
+ transfers) may be characterized by three quantities. The first is
+ the send rate, which is the amount of data sent by the sender in
+ unit time. The second is the throughput, which is the amount of data
+ received by the receiver in unit time. Note that the throughput will
+ always be less than or equal to the send rate due to losses.
+ Finally, the number of non-duplicate packets received by the
+ receiver in unit time gives us the goodput of the connection. The
+ goodput is always less than or equal to the throughput, since the
+ receiver may receive two copies of the same packet due to
+ retransmissions by the sender. In a previous paper, we presented a
+ simple model for predicting the steady state send rate of a bulk
+ transfer TCP flow as a function of loss rate and round trip time. In
+ this paper, we extend that work in two ways. First, we analyze the
+ performance of bulk transfer TCP flows using more precise,
+ stochastic analysis. Second, we build upon the previous analysis to
+ provide both an approximate formula as well as a more accurate
+ stochastic model for the steady state throughput of a bulk transfer
+ TCP flow.
+ annote: This is a report entry for a technical report. Note the format
+ of the type field in the database file which uses a localization
+ key. The number of the report is given in the number field. Also
+ note the sorttitle and indextitle fields
+ author:
+ - family: Padhye
+ given: Jitendra
+ - family: Firoiu
+ given: Victor
+ - family: Towsley
+ given: Don
+ genre: technical report
+ id: padhye
+ issued: 1999
+ language: en-US
+ number: 99-02
+ publisher: University of Massachusetts
+ publisher-place: Amherst, Mass.
+ title: A stochastic model of TCP Reno congestion avoidance and control
+ type: report
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-salam.md b/documents/markdown/pandoc-md/biblatex-salam.md
new file mode 100644
index 0000000..98eeffc
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-salam.md
@@ -0,0 +1,69 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Salam 1968)
+
+Salam, Abdus. 1968. “Weak and Electromagnetic Interactions.” In
+*Elementary Particle Theory: Relativistic Groups and Analyticity.
+Proceedings of the Eighth Nobel Symposium*, edited by Nils Svartholm,
+367–377. Stockholm: Almquist & Wiksell.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Salam, 1968)
+
+Salam, A. (1968). Weak and electromagnetic interactions. In N. Svartholm
+(Ed.), *Elementary particle theory: Relativistic groups and analyticity.
+Proceedings of the eighth Nobel symposium* (pp. 367–377). Stockholm:
+Almquist & Wiksell.
+
+
+}
+
+@InProceedings{salam,
+ author = {Salam, Abdus},
+ editor = {Svartholm, Nils},
+ title = {Weak and Electromagnetic Interactions},
+ date = 1968,
+ booktitle = {Elementary particle theory},
+ booksubtitle = {Relativistic groups and analyticity},
+ booktitleaddon= {Proceedings of the Eighth {Nobel} Symposium},
+ eventdate = {1968-05-19/1968-05-25},
+ venue = {Aspen{\"a}sgarden, Lerum},
+ publisher = {Almquist \& Wiksell},
+ location = {Stockholm},
+ pages = {367-377},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- author:
+ - family: Salam
+ given: Abdus
+ container-title: "Elementary particle theory: Relativistic groups and
+ analyticity. Proceedings of the eighth Nobel symposium"
+ editor:
+ - family: Svartholm
+ given: Nils
+ event-date: 1968-05-19/1968-05-25
+ event-place: Aspenäsgarden, Lerum
+ id: salam
+ issued: 1968
+ page: 367-377
+ publisher: Almquist & Wiksell
+ publisher-place: Stockholm
+ title: Weak and electromagnetic interactions
+ type: paper-conference
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-sarfraz.md b/documents/markdown/pandoc-md/biblatex-sarfraz.md
new file mode 100644
index 0000000..6461006
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-sarfraz.md
@@ -0,0 +1,65 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Sarfraz and Razzak 2002)
+
+Sarfraz, M., and M. F. A. Razzak. 2002. “Technical Section: An Algorithm
+for Automatic Capturing of the Font Outlines.” *Computers and Graphics*
+26 (5): 795–804.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Sarfraz & Razzak, 2002)
+
+Sarfraz, M., & Razzak, M. F. A. (2002). Technical section: An algorithm
+for automatic capturing of the font outlines. *Computers and Graphics*,
+*26*(5), 795–804.
+
+
+}
+
+@Article{sarfraz,
+ author = {M. Sarfraz and M. F. A. Razzak},
+ title = {Technical section: {An} algorithm for automatic capturing of
+ the font outlines},
+ year = 2002,
+ volume = 26,
+ number = 5,
+ pages = {795-804},
+ issn = {0097-8493},
+ journal = {Computers and Graphics},
+ annotation = {An article entry with an issn field},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: An article entry with an issn field
+ author:
+ - family: Sarfraz
+ given: M.
+ - family: Razzak
+ given: M. F. A.
+ container-title: Computers and Graphics
+ id: sarfraz
+ issn: 0097-8493
+ issue: 5
+ issued: 2002
+ page: 795-804
+ title: "Technical section: An algorithm for automatic capturing of the
+ font outlines"
+ title-short: Technical section
+ type: article-journal
+ volume: 26
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-shore.md b/documents/markdown/pandoc-md/biblatex-shore.md
new file mode 100644
index 0000000..efe97ef
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-shore.md
@@ -0,0 +1,66 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Shore 1991)
+
+Shore, Bradd. 1991. “Twice-born, Once Conceived: Meaning Construction
+and Cultural Cognition.” *American Anthropologist, New Series* 93 (1)
+(March): 9–27.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Shore, 1991)
+
+Shore, B. (1991). Twice-born, once conceived: Meaning construction and
+cultural cognition. *American Anthropologist, new series*, *93*(1),
+9–27.
+
+
+}
+
+@Article{shore,
+ author = {Shore, Bradd},
+ title = {Twice-Born, Once Conceived},
+ journaltitle = {American Anthropologist},
+ date = {1991-03},
+ subtitle = {Meaning Construction and Cultural Cognition},
+ series = {newseries},
+ volume = 93,
+ number = 1,
+ pages = {9-27},
+ annotation = {An article entry with series,
+ volume, and number fields. Note the format
+ of the series which is a localization key},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: An article entry with series, volume, and number fields. Note
+ the format of the series which is a localization key
+ author:
+ - family: Shore
+ given: Bradd
+ collection-title: New series
+ container-title: American Anthropologist
+ id: shore
+ issue: 1
+ issued: 1991-03
+ page: 9-27
+ title: "Twice-born, once conceived: Meaning construction and cultural
+ cognition"
+ title-short: Twice-born, once conceived
+ type: article-journal
+ volume: 93
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-sigfridsson.md b/documents/markdown/pandoc-md/biblatex-sigfridsson.md
new file mode 100644
index 0000000..f83c356
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-sigfridsson.md
@@ -0,0 +1,106 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Sigfridsson and Ryde 1998)
+
+Sigfridsson, Emma, and Ulf Ryde. 1998. “Comparison of Methods for
+Deriving Atomic Charges from the Electrostatic Potential and Moments.”
+*Journal of Computational Chemistry* 19 (4): 377–395.
+doi:[10.1002/(SICI)1096-987X(199803)19:4\<377::AID-JCC1\>3.0.CO;2-P](https://doi.org/10.1002/(SICI)1096-987X(199803)19:4<377::AID-JCC1>3.0.CO;2-P "10.1002/(SICI)1096-987X(199803)19:4<377::AID-JCC1>3.0.CO;2-P").
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Sigfridsson & Ryde, 1998)
+
+Sigfridsson, E., & Ryde, U. (1998). Comparison of methods for deriving
+atomic charges from the electrostatic potential and moments. *Journal of
+Computational Chemistry*, *19*(4), 377–395.
+doi:[10.1002/(SICI)1096-987X(199803)19:4\<377::AID-JCC1\>3.0.CO;2-P](https://doi.org/10.1002/(SICI)1096-987X(199803)19:4<377::AID-JCC1>3.0.CO;2-P "10.1002/(SICI)1096-987X(199803)19:4<377::AID-JCC1>3.0.CO;2-P")
+
+
+NOTES:
+
+- biblio2xaml
+ - the string "doi:" should not appear as part of the content of the "doi" field
+
+}
+
+@Article{sigfridsson,
+ author = {Sigfridsson, Emma and Ryde, Ulf},
+ title = {Comparison of methods for deriving atomic charges from the
+ electrostatic potential and moments},
+ journaltitle = {Journal of Computational Chemistry},
+ date = 1998,
+ volume = 19,
+ number = 4,
+ pages = {377-395},
+ doi = {10.1002/(SICI)1096-987X(199803)19:4<377::AID-JCC1>3.0.CO;2-P},
+ hyphenation = {american},
+ indextitle = {Methods for deriving atomic charges},
+ annotation = {An article entry with volume,
+ number, and doi fields. Note that the
+ \textsc{doi} is transformed into a clickable link if
+ hyperref support has been enabled},
+ abstract = {Four methods for deriving partial atomic charges from the
+ quantum chemical electrostatic potential (CHELP, CHELPG,
+ Merz-Kollman, and RESP) have been compared and critically
+ evaluated. It is shown that charges strongly depend on how and
+ where the potential points are selected. Two alternative
+ methods are suggested to avoid the arbitrariness in the
+ point-selection schemes and van der Waals exclusion radii:
+ CHELP-BOW, which also estimates the charges from the
+ electrostatic potential, but with potential points that are
+ Boltzmann-weighted after their occurrence in actual
+ simulations using the energy function of the program in which
+ the charges will be used, and CHELMO, which estimates the
+ charges directly from the electrostatic multipole
+ moments. Different criteria for the quality of the charges are
+ discussed.},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- abstract: "Four methods for deriving partial atomic charges from the
+ quantum chemical electrostatic potential (CHELP, CHELPG,
+ Merz-Kollman, and RESP) have been compared and critically evaluated.
+ It is shown that charges strongly depend on how and where the
+ potential points are selected. Two alternative methods are suggested
+ to avoid the arbitrariness in the point-selection schemes and van
+ der Waals exclusion radii: CHELP-BOW, which also estimates the
+ charges from the electrostatic potential, but with potential points
+ that are Boltzmann-weighted after their occurrence in actual
+ simulations using the energy function of the program in which the
+ charges will be used, and CHELMO, which estimates the charges
+ directly from the electrostatic multipole moments. Different
+ criteria for the quality of the charges are discussed."
+ annote: An article entry with volume, number, and doi fields. Note
+ that the [doi]{.smallcaps} is transformed into a clickable link if
+ hyperref support has been enabled
+ author:
+ - family: Sigfridsson
+ given: Emma
+ - family: Ryde
+ given: Ulf
+ container-title: Journal of Computational Chemistry
+ doi: "10.1002/(SICI)1096-987X(199803)19:4\\<377::AID-JCC1\\>3.0.CO;2-P"
+ id: sigfridsson
+ issue: 4
+ issued: 1998
+ language: en-US
+ page: 377-395
+ title: Comparison of methods for deriving atomic charges from the
+ electrostatic potential and moments
+ type: article-journal
+ volume: 19
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-sorace.md b/documents/markdown/pandoc-md/biblatex-sorace.md
new file mode 100644
index 0000000..8276931
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-sorace.md
@@ -0,0 +1,65 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Sorace, Reinhardt, and Vaughn 1997)
+
+Sorace, Ronald E., Victor S. Reinhardt, and Steven A. Vaughn. 1997.
+“High-speed Digital-to-RF Converter.” U.S. patent.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Sorace, Reinhardt, & Vaughn, 1997)
+
+Sorace, R. E., Reinhardt, V. S., & Vaughn, S. A. (1997, September 16).
+High-speed digital-to-RF converter. U.S. patent.
+
+
+}
+
+@Patent{sorace,
+ author = {Sorace, Ronald E. and Reinhardt, Victor S. and Vaughn, Steven
+ A.},
+ title = {High-Speed Digital-to-{RF} Converter},
+ number = 5668842,
+ date = {1997-09-16},
+ holder = {{Hughes Aircraft Company}},
+ type = {patentus},
+ hyphenation = {american},
+ annotation = {This is a patent entry with a holder field.
+ Note the format of the type and date fields
+ in the database file. Compare almendro,
+ laufenberg, and kowalik},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: This is a patent entry with a holder field. Note the format of
+ the type and date fields in the database file. Compare almendro,
+ laufenberg, and kowalik
+ author:
+ - family: Sorace
+ given: Ronald E.
+ - family: Reinhardt
+ given: Victor S.
+ - family: Vaughn
+ given: Steven A.
+ genre: U.S. patent
+ id: sorace
+ issued: 1997-09-16
+ language: en-US
+ number: 5668842
+ title: High-speed digital-to-RF converter
+ type: patent
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-spiegelberg.md b/documents/markdown/pandoc-md/biblatex-spiegelberg.md
new file mode 100644
index 0000000..59338ae
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-spiegelberg.md
@@ -0,0 +1,74 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Spiegelberg 1969)
+
+Spiegelberg, Herbert. 1969. ““Intention” und “Intentionalität” in der
+Scholastik, bei Brentano und Husserl.” *Studia Philosophica* 29:
+189–216.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Spiegelberg, 1969)
+
+Spiegelberg, H. (1969). “Intention” und “Intentionalität” in der
+Scholastik, bei Brentano und Husserl. *Studia Philosophica*, *29*,
+189–216.
+
+
+NOTES:
+
+- citeproc
+ - flipflopping of quotes incorrect
+
+}
+
+@Article{spiegelberg,
+ author = {Spiegelberg, Herbert},
+ title = {\mkbibquote{Intention} und \mkbibquote{Intentionalit{\"a}t} in
+ der Scholastik, bei Brentano und Husserl},
+ journaltitle = {Studia Philosophica},
+ date = 1969,
+ volume = 29,
+ pages = {189-216},
+ hyphenation = {german},
+ sorttitle = {Intention und Intentionalitat in der Scholastik, bei Brentano
+ und Husserl},
+ indexsorttitle= {Intention und Intentionalitat in der Scholastik, bei Brentano
+ und Husserl},
+ shorttitle = {Intention und Intentionalit{\"a}t},
+ annotation = {An article entry. Note the sorttitle and
+ indexsorttitle fields and the markup of the quotes in
+ the database file},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: An article entry. Note the sorttitle and indexsorttitle fields
+ and the markup of the quotes in the database file
+ author:
+ - family: Spiegelberg
+ given: Herbert
+ container-title: Studia Philosophica
+ id: spiegelberg
+ issued: 1969
+ language: de-DE
+ page: 189-216
+ title: "\"Intention\" und \"Intentionalität\" in der Scholastik, bei
+ Brentano und Husserl"
+ title-short: Intention und Intentionalität
+ type: article-journal
+ volume: 29
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-springer.md b/documents/markdown/pandoc-md/biblatex-springer.md
new file mode 100644
index 0000000..8e19a75
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-springer.md
@@ -0,0 +1,58 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Springer 1950)
+
+Springer, Otto. 1950. “Mediaeval Pilgrim Routes from Scandinavia to
+Rome.” *Mediaeval Studies* 12: 92–122.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Springer, 1950)
+
+Springer, O. (1950). Mediaeval pilgrim routes from Scandinavia to Rome.
+*Mediaeval Studies*, *12*, 92–122.
+
+
+}
+
+@Article{springer,
+ author = {Springer, Otto},
+ title = {Mediaeval Pilgrim Routes from {Scandinavia} to {Rome}},
+ journaltitle = {Mediaeval Studies},
+ date = 1950,
+ volume = 12,
+ pages = {92-122},
+ hyphenation = {british},
+ shorttitle = {Mediaeval Pilgrim Routes},
+ annotation = {A plain article entry},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A plain article entry
+ author:
+ - family: Springer
+ given: Otto
+ container-title: Mediaeval Studies
+ id: springer
+ issued: 1950
+ language: en-GB
+ page: 92-122
+ title: Mediaeval pilgrim routes from Scandinavia to Rome
+ title-short: Mediaeval pilgrim routes
+ type: article-journal
+ volume: 12
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-strings.md b/documents/markdown/pandoc-md/biblatex-strings.md
new file mode 100644
index 0000000..79edec4
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-strings.md
@@ -0,0 +1,46 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{excerpt from http://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/examples/biblatex-examples.bib}
+
+@string{anch-ie = {Angew.~Chem. Int.~Ed.}}
+
+@article{herrmann,
+ Author = {Herrmann, Wolfgang A. and Öfele, Karl and Schneider, Sabine K. and Herdtweck, Eberhardt and Hoffmann, Stephan D.},
+ Date = 2006,
+ Hyphenation = {english},
+ Indextitle = {Carbocyclic carbene as an efficient catalyst, A},
+ Journaltitle = anch-ie,
+ Number = 23,
+ Pages = {3859-3862},
+ Title = {A Carbocyclic Carbene as an Efficient Catalyst Ligand for {C--C} Coupling Reactions},
+ Volume = 45}
+
+^D
+---
+nocite: "[@*]"
+references:
+- author:
+ - family: Herrmann
+ given: Wolfgang A.
+ - family: Öfele
+ given: Karl
+ - family: Schneider
+ given: Sabine K.
+ - family: Herdtweck
+ given: Eberhardt
+ - family: Hoffmann
+ given: Stephan D.
+ container-title: Angew. Chem. Int. Ed.
+ id: herrmann
+ issue: 23
+ issued: 2006
+ language: en-US
+ page: 3859-3862
+ title: A carbocyclic carbene as an efficient catalyst ligand for C--C
+ coupling reactions
+ type: article-journal
+ volume: 45
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-test-case-conversion.md b/documents/markdown/pandoc-md/biblatex-test-case-conversion.md
new file mode 100644
index 0000000..e69cb93
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-test-case-conversion.md
@@ -0,0 +1,73 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+ - bibtex and biblatex
+ - expect titles in title case
+ - styles use titles as is, or convert them to sentence case
+ - strings wrapped {} are not converted
+ - all CSL styles at <http://github.com/citation-style-language/styles>
+ and <https://www.zotero.org/styles/>
+ - expect titles in sentence case
+ - styles use titles as is, or convert them to title case
+ - except for (hardcoded) list of stop words, see
+ <http://citationstyles.org/downloads/specification.html#title-case-conversion>
+ - citeproc-js (MLZ only?) also recognizes a markup syntax for
+ suppressing title-case changes on a range of text (see
+ <https://forums.zotero.org/discussion/21991/excessive-capitalization-of-citation-titles/#Item_22>):
+ - `<span class="nocase"/>lowercase</span>`
+ - Proposal:
+ - When converting to yaml, convert English titles to sentence case,
+ - for all strings wrapped in {} where {} is not part of a latex
+ command, ...
+ - ... when starting with an uppercase letter: suppress
+conversion, remove the {}
+ - ... when starting with a lowercase letter ("nm", "iPod"):
+ suppress conversion, replace the {} with
+ <span class="nocase"/></span>
+ - Note: Camel case ("iPod") needs to be protected in
+ bibtex/biblatex anyway; the only "extension" (wrt bibtex/biblatex
+ specs) we'd be introducing is wrapping lowercase-only strings in
+ {}, something that is never necessary on the latex side but
+ won't break anything there either.
+ - citeproc-hs/pandoc-citeproc should be modified to honour this new
+ syntax and suppress conversion to title case for strings wrapped
+ in `<span class="nocase"/></span>`.
+ - Expected output, using one of the title-case CSL styles, here
+ chicago-author-date.csl:
+
+ Author, Ann. 2013. “A Title, in English, with a Proper Name and
+an
+ ACRONYM and a camelCase Word and Some Units, 400 nm, 3 cm, and
+a Quote,
+ *Alea iacta est*.” *Journal*.
+ }
+
+@article{item1,
+ Author = {Author, Ann},
+ Date = {2013},
+ Hyphenation = {english},
+ Journaltitle = {Journal},
+ Title = {A Title, in {English}, with a {Proper Name} and an {ACRONYM}
+and a {camelCase} Word and Some Units, 400~{nm}, 3~{cm}, and a Quote,
+\textit{{Alea} {iacta est}}}
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- author:
+ - family: Author
+ given: Ann
+ container-title: Journal
+ id: item1
+ issued: 2013
+ language: en-US
+ title: A title, in English, with a Proper Name and an ACRONYM and a
+ [camelCase]{.nocase} word and some units, 400 [nm]{.nocase},
+ 3 [cm]{.nocase}, and a quote, *Alea [iacta est]{.nocase}*
+ type: article-journal
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-textnormal.md b/documents/markdown/pandoc-md/biblatex-textnormal.md
new file mode 100644
index 0000000..a4e6107
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-textnormal.md
@@ -0,0 +1,17 @@
+```
+% pandoc -f biblatex -t markdown -s
+@book{item1,
+ Title = {The Title \textnormal{of this book}},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- id: item1
+ title: The title [of this book]{.nodecor}
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-thesis.md b/documents/markdown/pandoc-md/biblatex-thesis.md
new file mode 100644
index 0000000..aba8b56
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-thesis.md
@@ -0,0 +1,68 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{excerpted from http://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/examples/biblatex-examples.bib
+
+TODO: Uppercase letters following hyphens need to be converted to lowercase, too (e.g., "r" in "High-Resolution". -- Same for citeproc when doing title-case conversion!)
+}
+
+@thesis{geer,
+ Annotation = {This is a typical thesis entry for a PhD thesis. Note the type field in the database file which uses a localization key. Also note the format of the printed name and compare the useprefix option in the options field as well as vangennep},
+ Author = {de Geer, Ingrid},
+ Date = 1985,
+ Hyphenation = {british},
+ Institution = {Uppsala Universitet},
+ Location = {Uppsala},
+ Options = {useprefix=false},
+ Subtitle = {The {Orkney} Earldom of the Twelfth Century. {A} Musicological Study},
+ Title = {Earl, Saint, Bishop, Skald~-- and Music},
+ Type = {phdthesis}}
+
+@thesis{loh,
+ Annotation = {This is a typical thesis entry for an MA thesis. Note the type field in the database file which uses a localization key},
+ Author = {Loh, Nin C.},
+ Date = 1992,
+ Hyphenation = {american},
+ Institution = {Massachusetts Institute of Technology},
+ Location = {Cambridge, Mass.},
+ Title = {High-Resolution Micromachined Interferometric Accelerometer},
+ Type = {mathesis}}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: This is a typical thesis entry for a PhD thesis. Note the type
+ field in the database file which uses a localization key. Also note
+ the format of the printed name and compare the useprefix option in
+ the options field as well as vangennep
+ author:
+ - dropping-particle: de
+ family: Geer
+ given: Ingrid
+ genre: PhD thesis
+ id: geer
+ issued: 1985
+ language: en-GB
+ publisher: Uppsala Universitet
+ publisher-place: Uppsala
+ title: "Earl, saint, bishop, skald -- and music: The Orkney earldom of
+ the twelfth century. A musicological study"
+ title-short: Earl, saint, bishop, skald -- and music
+ type: thesis
+- annote: This is a typical thesis entry for an MA thesis. Note the type
+ field in the database file which uses a localization key
+ author:
+ - family: Loh
+ given: Nin C.
+ genre: Master's thesis
+ id: loh
+ issued: 1992
+ language: en-US
+ publisher: Massachusetts Institute of Technology
+ publisher-place: Cambridge, Mass.
+ title: High-resolution micromachined interferometric accelerometer
+ type: thesis
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-title-and-shorttitle.md b/documents/markdown/pandoc-md/biblatex-title-and-shorttitle.md
new file mode 100644
index 0000000..90e1275
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-title-and-shorttitle.md
@@ -0,0 +1,76 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+TODO:
+Slight inconsistency:
+When a biblatex “title” field contains a colon, the part before the colon is mapped to CSL “title-short”.
+When there’s a biblatex “title” and a “subtitle” field, CSL “title-short” is not set, though it would make at least as much sense to map “title” (without “subtitle”) to CSL “title-short” in this case.
+
+CSL “container-title-short” could also be set
+- from biblatex “shortjournal”
+- for inbook, incollection etc. from the “shorttitle” field of the cross-referenced book, collection etc. entry (see item5, item6)
+... but it might not really be worth it, “container-title-short” not being used once in my sample of 70+ CSL styles.
+
+}
+
+@book{item4,
+ Shorttitle = {The Shorttitle},
+ Subtitle = {And a Subtitle, in Two Separate Fields; plus a Separate “Shorttitle” Field},
+ Title = {The Title: With a Colon in the “Title” Field}}
+
+@book{item3,
+ Subtitle = {And a Subtitle, in two separate fields},
+ Title = {The Title: With a Colon in the “title” field}}
+
+@book{item2,
+ Subtitle = {The Subtitle, In Two Separate fields},
+ Title = {The Title}}
+
+@book{item1,
+ Title = {The Title: And the Subtitle, all in the “title” Field}}
+
+@inbook{item5,
+ Title = {The inbook Title: And the Subtitle, all in the “title” Field},
+ Crossref = {item6}}
+
+@book{item6,
+ Title = {The Title: And the Subtitle, all in the “title” Field},
+ Shorttitle = {The Shorttitle},
+}
+^D
+---
+nocite: "[@*]"
+references:
+- id: item4
+ title: "The title: With a colon in the \"title\" field: And a subtitle,
+ in two separate fields; plus a separate \"shorttitle\" field"
+ title-short: The shorttitle
+ type: book
+- id: item3
+ title: "The title: With a colon in the \"title\" field: And a subtitle,
+ in two separate fields"
+ title-short: The title
+ type: book
+- id: item2
+ title: "The title: The subtitle, in two separate fields"
+ title-short: The title
+ type: book
+- id: item1
+ title: "The title: And the subtitle, all in the \"title\" field"
+ title-short: The title
+ type: book
+- container-title: "The title: And the subtitle, all in the \"title\"
+ field"
+ id: item5
+ title: "The inbook title: And the subtitle, all in the \"title\" field"
+ title-short: The inbook title
+ type: chapter
+- id: item6
+ title: "The title: And the subtitle, all in the \"title\" field"
+ title-short: The shorttitle
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-vangennep-related.md b/documents/markdown/pandoc-md/biblatex-vangennep-related.md
new file mode 100644
index 0000000..0bf3c7d
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-vangennep-related.md
@@ -0,0 +1,69 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(van Gennep 1909)
+
+van Gennep, Arnold. 1909. *Les rites de passage*. Paris: Nourry.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(van Gennep, 1909)
+
+van Gennep, A. (1909). *Les rites de passage*. Paris: Nourry.
+
+NOTES:
+
+- biblio2yaml
+ - "related = {vizedom:related}, relatedtype = {bytranslator}": no equivalent implemented in CSL
+ - "options = {useprefix}," is shorthand for "options = {useprefix=true},"
+
+
+}
+
+@Book{vangennep:related,
+ author = {van Gennep, Arnold},
+ title = {Les rites de passage},
+ date = 1909,
+ publisher = {Nourry},
+ location = {Paris},
+ options = {useprefix},
+ hyphenation = {french},
+ related = {vizedom:related},
+ relatedtype = {bytranslator},
+ sorttitle = {Rites de passage},
+ indextitle = {Rites de passage, Les},
+ shorttitle = {Rites de passage},
+ annotation = {A variant of the vangennep entry related to its
+ translation. Note the format of the related and
+ relatedtype fields},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A variant of the vangennep entry related to its translation.
+ Note the format of the related and relatedtype fields
+ author:
+ - family: Gennep
+ given: Arnold
+ non-dropping-particle: van
+ id: "vangennep:related"
+ issued: 1909
+ language: fr-FR
+ publisher: Nourry
+ publisher-place: Paris
+ title: Les rites de passage
+ title-short: Rites de passage
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-vangennep-trans.md b/documents/markdown/pandoc-md/biblatex-vangennep-trans.md
new file mode 100644
index 0000000..f086d85
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-vangennep-trans.md
@@ -0,0 +1,69 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(van Gennep 1960)
+
+van Gennep, Arnold. 1960. *The Rites of Passage*. Translated by Monika
+B. Vizedom and Gabrielle L. Caffee. University of Chicago Press.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(van Gennep, 1960)
+
+van Gennep, A. (1960). *The rites of passage*. (M. B. Vizedom & G. L.
+Caffee, Trans.). University of Chicago Press.
+
+
+}
+
+@Book{vangennep:trans,
+ author = {van Gennep, Arnold},
+ title = {The Rites of Passage},
+ year = 1960,
+ translator = {Vizedom, Monika B. and Caffee, Gabrielle L.},
+ language = {english},
+ origlanguage = {french},
+ publisher = {University of Chicago Press},
+ options = {useprefix},
+ indextitle = {Rites of Passage, The},
+ sorttitle = {Rites of Passage},
+ shorttitle = {Rites of Passage},
+ hyphenation = {american},
+ annotation = {A translation of the vangennep entry. Note the
+ translator and origlanguage fields. Compare
+ with the vangennep:related entry.},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: "A translation of the vangennep entry. Note the translator and
+ origlanguage fields. Compare with the vangennep:related entry."
+ author:
+ - family: Gennep
+ given: Arnold
+ non-dropping-particle: van
+ id: "vangennep:trans"
+ issued: 1960
+ language: en-US
+ publisher: University of Chicago Press
+ title: The rites of passage
+ title-short: Rites of passage
+ translator:
+ - family: Vizedom
+ given: Monika B.
+ - family: Caffee
+ given: Gabrielle L.
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-vangennep.md b/documents/markdown/pandoc-md/biblatex-vangennep.md
new file mode 100644
index 0000000..196e621
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-vangennep.md
@@ -0,0 +1,61 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(van Gennep 1909)
+
+van Gennep, Arnold. 1909. *Les rites de passage*. Paris: Nourry.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(van Gennep, 1909)
+
+van Gennep, A. (1909). *Les rites de passage*. Paris: Nourry.
+
+
+}
+
+@Book{vangennep,
+ author = {van Gennep, Arnold},
+ title = {Les rites de passage},
+ date = 1909,
+ publisher = {Nourry},
+ location = {Paris},
+ options = {useprefix},
+ hyphenation = {french},
+ sorttitle = {Rites de passage},
+ indextitle = {Rites de passage, Les},
+ shorttitle = {Rites de passage},
+ annotation = {A book entry. Note the format of the printed name and
+ compare the useprefix option in the options
+ field as well as brandt and geer},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A book entry. Note the format of the printed name and compare
+ the useprefix option in the options field as well as brandt and geer
+ author:
+ - family: Gennep
+ given: Arnold
+ non-dropping-particle: van
+ id: vangennep
+ issued: 1909
+ language: fr-FR
+ publisher: Nourry
+ publisher-place: Paris
+ title: Les rites de passage
+ title-short: Rites de passage
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-vazques-de-parga-mvbook.md b/documents/markdown/pandoc-md/biblatex-vazques-de-parga-mvbook.md
new file mode 100644
index 0000000..4e545ae
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-vazques-de-parga-mvbook.md
@@ -0,0 +1,75 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Vázques de Parga, Lacarra, and Uría Ríu 1993)
+
+Vázques de Parga, Luis, José María Lacarra, and Juan Uría Ríu. 1993.
+*Las Peregrinaciones a Santiago de Compostela*. 3. Pamplona: Iberdrola.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Vázques de Parga, Lacarra, & Uría Ríu, 1993)
+
+Vázques de Parga, L., Lacarra, J. M., & Uría Ríu, J. (1993). *Las
+Peregrinaciones a Santiago de Compostela* (1-3). Pamplona: Iberdrola.
+
+
+NOTES:
+
+- citeproc
+ - term "vols." missing
+
+}
+
+@mvbook{vazques-de-parga,
+ author = {V{\'a}zques{ de }Parga, Luis and Lacarra, Jos{\'e} Mar{\'i}a
+ and Ur{\'i}a R{\'i}u, Juan},
+ title = {Las Peregrinaciones a Santiago de Compostela},
+ date = 1993,
+ volumes = 3,
+ note = {Ed. facs. de la realizada en 1948--49},
+ publisher = {Iberdrola},
+ location = {Pamplona},
+ hyphenation = {spanish},
+ sorttitle = {Peregrinaciones a Santiago de Compostela},
+ indextitle = {Peregrinaciones a Santiago de Compostela, Las},
+ shorttitle = {Peregrinaciones},
+ annotation = {A multivolume book cited as a whole. This is a book
+ entry with volumes, note,
+ sorttitle, and indextitle fields},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A multivolume book cited as a whole. This is a book entry with
+ volumes, note, sorttitle, and indextitle fields
+ author:
+ - family: Vázques de Parga
+ given: Luis
+ - family: Lacarra
+ given: José María
+ - family: Uría Ríu
+ given: Juan
+ id: vazques-de-parga
+ issued: 1993
+ language: es-ES
+ note: Ed. facs. de la realizada en 1948--49
+ number-of-volumes: 3
+ publisher: Iberdrola
+ publisher-place: Pamplona
+ title: Las Peregrinaciones a Santiago de Compostela
+ title-short: Peregrinaciones
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-vazques-de-parga.md b/documents/markdown/pandoc-md/biblatex-vazques-de-parga.md
new file mode 100644
index 0000000..7b283aa
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-vazques-de-parga.md
@@ -0,0 +1,74 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Vázques de Parga, Lacarra, and Uría Ríu 1993)
+
+Vázques de Parga, Luis, José María Lacarra, and Juan Uría Ríu. 1993.
+*Las Peregrinaciones a Santiago de Compostela*. 3. Pamplona: Iberdrola.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Vázques de Parga, Lacarra, & Uría Ríu, 1993)
+
+Vázques de Parga, L., Lacarra, J. M., & Uría Ríu, J. (1993). *Las
+Peregrinaciones a Santiago de Compostela* (1-3). Pamplona: Iberdrola.
+
+
+NOTES:
+
+- citeproc
+ - term "vols." missing
+
+}
+
+@Book{vazques-de-parga,
+ author = {V{\'a}zques{ de }Parga, Luis and Lacarra, Jos{\'e} Mar{\'i}a
+ and Ur{\'i}a R{\'i}u, Juan},
+ title = {Las Peregrinaciones a Santiago de Compostela},
+ date = 1993,
+ volumes = 3,
+ note = {Ed. facs. de la realizada en 1948--49},
+ publisher = {Iberdrola},
+ location = {Pamplona},
+ hyphenation = {spanish},
+ sorttitle = {Peregrinaciones a Santiago de Compostela},
+ indextitle = {Peregrinaciones a Santiago de Compostela, Las},
+ shorttitle = {Peregrinaciones},
+ annotation = {A multivolume book cited as a whole. This is a book
+ entry with volumes, note,
+ sorttitle, and indextitle fields},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A multivolume book cited as a whole. This is a book entry with
+ volumes, note, sorttitle, and indextitle fields
+ author:
+ - family: Vázques de Parga
+ given: Luis
+ - family: Lacarra
+ given: José María
+ - family: Uría Ríu
+ given: Juan
+ id: vazques-de-parga
+ issued: 1993
+ language: es-ES
+ note: Ed. facs. de la realizada en 1948--49
+ number-of-volumes: 3
+ publisher: Iberdrola
+ publisher-place: Pamplona
+ title: Las Peregrinaciones a Santiago de Compostela
+ title-short: Peregrinaciones
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-video.md b/documents/markdown/pandoc-md/biblatex-video.md
new file mode 100644
index 0000000..3eb239c
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-video.md
@@ -0,0 +1,19 @@
+```
+% pandoc -f biblatex -t markdown -s
+@video{x1,title={blah}}
+@movie{x2,title={blah}}
+
+^D
+---
+nocite: "[@*]"
+references:
+- id: x1
+ title: Blah
+ type: motion_picture
+- id: x2
+ title: Blah
+ type: motion_picture
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-vizedom-related.md b/documents/markdown/pandoc-md/biblatex-vizedom-related.md
new file mode 100644
index 0000000..26c66d7
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-vizedom-related.md
@@ -0,0 +1,68 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Vizedom and Caffee 1960)
+
+Vizedom, Monika B., and Gabrielle L. Caffee, trans. 1960. *The Rites of
+Passage*. University of Chicago Press.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Vizedom & Caffee, 1960)
+
+Vizedom, M. B., & Caffee, G. L. (Trans.). (1960). *The rites of
+passage*. University of Chicago Press.
+
+
+NOTES:
+
+- biblio2yaml
+ - "related = {vangennep}, relatedtype = {translationof}": no equivalent implemented in CSL
+
+}
+
+@Book{vizedom:related,
+ title = {The Rites of Passage},
+ year = 1960,
+ translator = {Vizedom, Monika B. and Caffee, Gabrielle L.},
+ language = {english},
+ publisher = {University of Chicago Press},
+ hyphenation = {american},
+ options = {usetranslator},
+ related = {vangennep},
+ relatedtype = {translationof},
+ indextitle = {Rites of Passage, The},
+ sorttitle = {Rites of Passage},
+ shorttitle = {Rites of Passage},
+ annotation = {A translated work from vangennep. Note the format of
+ the related and relatedtype fields},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A translated work from vangennep. Note the format of the
+ related and relatedtype fields
+ id: "vizedom:related"
+ issued: 1960
+ language: en-US
+ publisher: University of Chicago Press
+ title: The rites of passage
+ title-short: Rites of passage
+ translator:
+ - family: Vizedom
+ given: Monika B.
+ - family: Caffee
+ given: Gabrielle L.
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-wassenberg.md b/documents/markdown/pandoc-md/biblatex-wassenberg.md
new file mode 100644
index 0000000..0ae9e10
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-wassenberg.md
@@ -0,0 +1,83 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Wassenberg and Sanders 2010)
+
+Wassenberg, Jan, and Peter Sanders. 2010. “Faster Radix Sort via Virtual
+Memory and Write-combining” (version 1). August 17.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Wassenberg & Sanders, 2010)
+
+Wassenberg, J., & Sanders, P. (2010, August 17). Faster radix sort via
+virtual memory and write-combining.
+
+
+NOTES:
+
+- biblio2yaml
+ - "eprinttype = {arxiv}, eprintclass = {cs.DS}, eprint = {1008.2849v1}" should be used to reconstruct a Url: http://arxiv.org/abs/1008.2849v1 ("cs.DS" does not seem to be essential)
+
+}
+
+@Online{wassenberg,
+ author = {Wassenberg, Jan and Sanders, Peter},
+ title = {Faster Radix Sort via Virtual Memory and Write-Combining},
+ date = {2010-08-17},
+ version = 1,
+ hyphenation = {american},
+ eprinttype = {arxiv},
+ eprintclass = {cs.DS},
+ eprint = {1008.2849v1},
+ annotation = {A recent online reference from arXiv using the new
+ (April 2007 onward) identifier format. Note the
+ eprint, eprinttype, and eprintclass
+ fields. Also note that the arXiv reference is transformed into
+ a clickable link if hyperref support has been
+ enabled},
+ abstract = {Sorting algorithms are the deciding factor for the performance
+ of common operations such as removal of duplicates or database
+ sort-merge joins. This work focuses on 32-bit integer keys,
+ optionally paired with a 32-bit value. We present a fast radix
+ sorting algorithm that builds upon a microarchitecture-aware
+ variant of counting sort},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- abstract: Sorting algorithms are the deciding factor for the
+ performance of common operations such as removal of duplicates or
+ database sort-merge joins. This work focuses on 32-bit integer keys,
+ optionally paired with a 32-bit value. We present a fast radix
+ sorting algorithm that builds upon a microarchitecture-aware variant
+ of counting sort
+ annote: A recent online reference from arXiv using the new (April 2007
+ onward) identifier format. Note the eprint, eprinttype, and
+ eprintclass fields. Also note that the arXiv reference is
+ transformed into a clickable link if hyperref support has been
+ enabled
+ author:
+ - family: Wassenberg
+ given: Jan
+ - family: Sanders
+ given: Peter
+ id: wassenberg
+ issued: 2010-08-17
+ language: en-US
+ title: Faster radix sort via virtual memory and write-combining
+ type: webpage
+ url: "https://arxiv.org/abs/1008.2849v1"
+ version: 1
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-weinberg.md b/documents/markdown/pandoc-md/biblatex-weinberg.md
new file mode 100644
index 0000000..5ccafa0
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-weinberg.md
@@ -0,0 +1,52 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Weinberg 1967)
+
+Weinberg, Steven. 1967. “A Model of Leptons.” *Phys. Rev. Lett.* 19:
+1264–1266.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Weinberg, 1967)
+
+Weinberg, S. (1967). A model of leptons. *Phys. Rev. Lett.*, *19*,
+1264–1266.
+
+
+}
+
+@Article{weinberg,
+ author = {Weinberg, Steven},
+ title = {A Model of Leptons},
+ journaltitle = {Phys.~Rev.~Lett.},
+ date = 1967,
+ volume = 19,
+ pages = {1264-1266},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- author:
+ - family: Weinberg
+ given: Steven
+ container-title: Phys. Rev. Lett.
+ id: weinberg
+ issued: 1967
+ page: 1264-1266
+ title: A model of leptons
+ type: article-journal
+ volume: 19
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-westfahl-frontier.md b/documents/markdown/pandoc-md/biblatex-westfahl-frontier.md
new file mode 100644
index 0000000..dff096b
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-westfahl-frontier.md
@@ -0,0 +1,60 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Westfahl 2000)
+
+Westfahl, Gary, ed. 2000. *Space and Beyond: The Frontier Theme in
+Science Fiction*. Westport, Conn.; London: Greenwood.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Westfahl, 2000)
+
+Westfahl, G. (Ed.). (2000). *Space and beyond: The frontier theme in
+science fiction*. Westport, Conn.; London: Greenwood.
+
+
+}
+
+@Collection{westfahl:frontier,
+ editor = {Westfahl, Gary},
+ title = {Space and Beyond},
+ date = 2000,
+ subtitle = {The Frontier Theme in Science Fiction},
+ publisher = {Greenwood},
+ location = {Westport, Conn. and London},
+ hyphenation = {american},
+ booktitle = {Space and Beyond},
+ booksubtitle = {The Frontier Theme in Science Fiction},
+ annotation = {This is a collection entry. Note the format of the
+ location field as well as the subtitle and
+ booksubtitle fields},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: This is a collection entry. Note the format of the location
+ field as well as the subtitle and booksubtitle fields
+ editor:
+ - family: Westfahl
+ given: Gary
+ id: "westfahl:frontier"
+ issued: 2000
+ language: en-US
+ publisher: Greenwood
+ publisher-place: Westport, Conn.; London
+ title: "Space and beyond: The frontier theme in science fiction"
+ title-short: Space and beyond
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-westfahl-space.md b/documents/markdown/pandoc-md/biblatex-westfahl-space.md
new file mode 100644
index 0000000..d0c16e7
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-westfahl-space.md
@@ -0,0 +1,106 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Westfahl 2000a) (Westfahl 2000b)
+
+Westfahl, Gary. 2000a. “The True Frontier: Confronting and Avoiding the
+Realities of Space in American Science Fiction Films.” In *Space and
+Beyond: The Frontier Theme in Science Fiction*, edited by Gary Westfahl,
+55–65. Westport, Conn.; London: Greenwood.
+
+———, ed. 2000b. *Space and Beyond: The Frontier Theme in Science
+Fiction*. Westport, Conn.; London: Greenwood.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Westfahl, 2000) (Westfahl, 2000)
+
+Westfahl, G. (2000). The true frontier: Confronting and avoiding the
+realities of space in American science fiction films. In G. Westfahl
+(Ed.), *Space and beyond: The frontier theme in science fiction* (pp.
+55–65). Westport, Conn.; London: Greenwood.
+
+Westfahl, G. (Ed.). (2000). *Space and beyond: The frontier theme in
+science fiction*. Westport, Conn.; London: Greenwood.
+
+
+}
+
+@InCollection{westfahl:space,
+ author = {Westfahl, Gary},
+ title = {The True Frontier},
+ subtitle = {Confronting and Avoiding the Realities of Space in {American}
+ Science Fiction Films},
+ pages = {55-65},
+ crossref = {westfahl:frontier},
+ hyphenation = {american},
+ indextitle = {True Frontier, The},
+ annotation = {A cross-referenced article from a collection. This is
+ an incollection entry with a crossref
+ field. Note the subtitle and indextitle
+ fields},
+}
+
+@Collection{westfahl:frontier,
+ editor = {Westfahl, Gary},
+ title = {Space and Beyond},
+ date = 2000,
+ subtitle = {The Frontier Theme in Science Fiction},
+ publisher = {Greenwood},
+ location = {Westport, Conn. and London},
+ hyphenation = {american},
+ booktitle = {Space and Beyond},
+ booksubtitle = {The Frontier Theme in Science Fiction},
+ annotation = {This is a collection entry. Note the format of the
+ location field as well as the subtitle and
+ booksubtitle fields},
+}
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A cross-referenced article from a collection. This is an
+ incollection entry with a crossref field. Note the subtitle and
+ indextitle fields
+ author:
+ - family: Westfahl
+ given: Gary
+ container-title: "Space and beyond: The frontier theme in science
+ fiction"
+ editor:
+ - family: Westfahl
+ given: Gary
+ id: "westfahl:space"
+ issued: 2000
+ language: en-US
+ page: 55-65
+ publisher: Greenwood
+ publisher-place: Westport, Conn.; London
+ title: "The true frontier: Confronting and avoiding the realities of
+ space in American science fiction films"
+ title-short: The true frontier
+ type: chapter
+- annote: This is a collection entry. Note the format of the location
+ field as well as the subtitle and booksubtitle fields
+ editor:
+ - family: Westfahl
+ given: Gary
+ id: "westfahl:frontier"
+ issued: 2000
+ language: en-US
+ publisher: Greenwood
+ publisher-place: Westport, Conn.; London
+ title: "Space and beyond: The frontier theme in science fiction"
+ title-short: Space and beyond
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-wilde.md b/documents/markdown/pandoc-md/biblatex-wilde.md
new file mode 100644
index 0000000..d471041
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-wilde.md
@@ -0,0 +1,65 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Wilde 1899)
+
+Wilde, Oscar. 1899. *The Importance of Being Earnest: A Trivial Comedy
+for Serious People*. English and American Drama of the Nineteenth
+Century. Leonard Smithers and Company.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Wilde, 1899)
+
+Wilde, O. (1899). *The importance of being earnest: A trivial comedy for
+serious people*. Leonard Smithers and Company.
+
+
+NOTES:
+
+- biblio2yaml
+ - From "eprint = {4HIWAAAAYAAJ}, eprinttype = {googlebooks}", a url could be reconstructed, shortest form: http://books.google.com?id=4HIWAAAAYAAJ
+
+}
+
+@Book{wilde,
+ author = {Wilde, Oscar},
+ title = {The Importance of Being Earnest: {A} Trivial Comedy for Serious
+ People},
+ year = 1899,
+ series = {English and American drama of the Nineteenth Century},
+ publisher = {Leonard Smithers {and} Company},
+ eprint = {4HIWAAAAYAAJ},
+ eprinttype = {googlebooks},
+ annotation = {A book with eprint and eprinttype
+ fields.},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A book with eprint and eprinttype fields.
+ author:
+ - family: Wilde
+ given: Oscar
+ collection-title: English and american drama of the nineteenth century
+ id: wilde
+ issued: 1899
+ publisher: Leonard Smithers and Company
+ title: "The importance of being earnest: A trivial comedy for serious
+ people"
+ title-short: The importance of being earnest
+ type: book
+ url: "https://books.google.com?id=4HIWAAAAYAAJ"
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-worman.md b/documents/markdown/pandoc-md/biblatex-worman.md
new file mode 100644
index 0000000..8015903
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-worman.md
@@ -0,0 +1,60 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Worman 2002)
+
+Worman, Nancy. 2002. *The Cast of Character: Style in Greek Literature*.
+Austin: University of Texas Press.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Worman, 2002)
+
+Worman, N. (2002). *The cast of character: Style in Greek literature*.
+Austin: University of Texas Press.
+
+
+}
+
+@Book{worman,
+ author = {Worman, Nancy},
+ title = {The Cast of Character},
+ date = 2002,
+ publisher = {University of Texas Press},
+ location = {Austin},
+ hyphenation = {american},
+ sorttitle = {Cast of Character},
+ indextitle = {Cast of Character, The},
+ subtitle = {Style in {Greek} Literature},
+ shorttitle = {Cast of Character},
+ annotation = {A book entry. Note the sorttitle and
+ indextitle fields},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- annote: A book entry. Note the sorttitle and indextitle fields
+ author:
+ - family: Worman
+ given: Nancy
+ id: worman
+ issued: 2002
+ language: en-US
+ publisher: University of Texas Press
+ publisher-place: Austin
+ title: "The cast of character: Style in Greek literature"
+ title-short: Cast of character
+ type: book
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/biblatex-yoon.md b/documents/markdown/pandoc-md/biblatex-yoon.md
new file mode 100644
index 0000000..19f8737
--- /dev/null
+++ b/documents/markdown/pandoc-md/biblatex-yoon.md
@@ -0,0 +1,67 @@
+```
+% pandoc -f biblatex -t markdown -s
+@comment{
+
+Adapted from biblatex-example.bib
+
+
+Formatted with pandoc and chicago-author-date.csl, 2013-10-23:
+
+(Yoon et al. 2006)
+
+Yoon, Myeong S., Dowook Ryu, Jeongryul Kim, and Kyo Han Ahn. 2006.
+“Palladium Pincer Complexes with Reduced Bond Angle Strain: Efficient
+Catalysts for the Heck Reaction.” *Organometallics* 25 (10): 2409–2411.
+
+
+Formatted with pandoc and apa.csl, 2013-10-23:
+
+(Yoon, Ryu, Kim, & Ahn, 2006)
+
+Yoon, M. S., Ryu, D., Kim, J., & Ahn, K. H. (2006). Palladium pincer
+complexes with reduced bond angle strain: Efficient catalysts for the
+Heck reaction. *Organometallics*, *25*(10), 2409–2411.
+
+
+}
+
+@Article{yoon,
+ author = {Yoon, Myeong S. and Ryu, Dowook and Kim, Jeongryul and Ahn,
+ Kyo Han},
+ title = {Palladium pincer complexes with reduced bond angle strain:
+ efficient catalysts for the {Heck} reaction},
+ journaltitle = {Organometallics},
+ date = 2006,
+ volume = 25,
+ number = 10,
+ pages = {2409-2411},
+ indextitle = {Palladium pincer complexes},
+}
+
+^D
+---
+nocite: "[@*]"
+references:
+- author:
+ - family: Yoon
+ given: Myeong S.
+ - family: Ryu
+ given: Dowook
+ - family: Kim
+ given: Jeongryul
+ - family: Ahn
+ given: Kyo Han
+ container-title: Organometallics
+ id: yoon
+ issue: 10
+ issued: 2006
+ page: 2409-2411
+ title: "Palladium pincer complexes with reduced bond angle strain:
+ Efficient catalysts for the Heck reaction"
+ title-short: Palladium pincer complexes with reduced bond angle strain
+ type: article-journal
+ volume: 25
+---
+
+
+```
diff --git a/documents/markdown/pandoc-md/bits-book-meta.md b/documents/markdown/pandoc-md/bits-book-meta.md
new file mode 100644
index 0000000..53a64c7
--- /dev/null
+++ b/documents/markdown/pandoc-md/bits-book-meta.md
@@ -0,0 +1,104 @@
+```
+% pandoc -f jats -t native -s
+<book>
+ <book-meta>
+ <book-id book-id-type="publisher">handbook-648</book-id>
+ <book-title-group>
+ <book-title>The NCBI Handbook</book-title>
+ </book-title-group>
+ <contrib-group>
+ <contrib contrib-type="author">
+ <name><surname>McEntyre</surname>
+ <given-names>Jo</given-names></name>
+ <xref ref-type="aff" rid="bid.m.1"/>
+ </contrib>
+ <contrib contrib-type="editor">
+ <name><surname>Ostell</surname>
+ <given-names>Jim</given-names></name>
+ <xref ref-type="aff" rid="bid.m.1"/>
+ </contrib>
+ </contrib-group>
+ <aff id="bid.m.1">
+ <institution>National Center for Biotechnology Information (NCBI), National Library of Medicine, National Institutes of Health</institution>, <addr-line>Bethesda, MD 20892-6510</addr-line>
+ </aff>
+ <pub-date iso-8601-date="2002-11">
+ <month>11</month>
+ <year>2002</year>
+ </pub-date>
+ <publisher>
+ <publisher-name>National Center for Biotechnology Information (NCBI), National Library of Medicine, National Institutes of Health</publisher-name>
+ <publisher-loc>Bethesda, MD</publisher-loc>
+ </publisher>
+ <edition>1</edition>
+ <counts>
+ <book-fig-count count="98"/>
+ <book-table-count count="40"/>
+ <book-equation-count count="0"/>
+ <book-ref-count count="115"/>
+ <book-page-count count="532"/>
+ <book-word-count count="149852"/>
+ </counts>
+ </book-meta>
+</book>
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "author"
+ , MetaList
+ [ MetaInlines [ Str "Jo" , Space , Str "McEntyre" ] ]
+ )
+ , ( "date" , MetaInlines [ Str "2002-11" ] )
+ , ( "institute"
+ , MetaList
+ [ MetaInlines
+ [ Str "National"
+ , Space
+ , Str "Center"
+ , Space
+ , Str "for"
+ , Space
+ , Str "Biotechnology"
+ , Space
+ , Str "Information"
+ , Space
+ , Str "(NCBI),"
+ , Space
+ , Str "National"
+ , Space
+ , Str "Library"
+ , Space
+ , Str "of"
+ , Space
+ , Str "Medicine,"
+ , Space
+ , Str "National"
+ , Space
+ , Str "Institutes"
+ , Space
+ , Str "of"
+ , Space
+ , Str "Health,"
+ , Space
+ , Str "Bethesda,"
+ , Space
+ , Str "MD"
+ , Space
+ , Str "20892-6510"
+ ]
+ ]
+ )
+ , ( "title"
+ , MetaInlines
+ [ Str "The"
+ , Space
+ , Str "NCBI"
+ , Space
+ , Str "Handbook"
+ ]
+ )
+ ]
+ }
+ []
+```
\ No newline at end of file
diff --git a/documents/markdown/pandoc-md/bits-book-part-wrapper-meta.md b/documents/markdown/pandoc-md/bits-book-part-wrapper-meta.md
new file mode 100644
index 0000000..33f9320
--- /dev/null
+++ b/documents/markdown/pandoc-md/bits-book-part-wrapper-meta.md
@@ -0,0 +1,95 @@
+```
+% pandoc -f jats -t native -s
+<book-part-wrapper
+ dtd-version="2.1"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:mml="http://www.w3.org/1998/Math/MathML"
+ xmlns:xlink="http://www.w3.org/1999/xlink">
+
+ <collection-meta>
+ <title-group>
+ <title>Balisage Series on Markup Technologies</title>
+ </title-group>
+
+ <abstract>
+ <p>The <italic>Balisage Series on Markup Technologies</italic>
+ is an occasional series...</p>
+ </abstract>
+ </collection-meta>
+
+ <book-meta>
+ <book-title-group>
+ <book-title>Proceedings of Balisage: The Markup Conference
+ 2013</book-title>
+ </book-title-group>
+
+ <abstract>
+ <p>Balisage is a peer-reviewed conference...</p></abstract>
+
+ </book-meta>
+</book-part-wrapper>
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "abstract"
+ , MetaBlocks
+ [ Para
+ [ Str "Balisage"
+ , Space
+ , Str "is"
+ , Space
+ , Str "a"
+ , Space
+ , Str "peer-reviewed"
+ , Space
+ , Str "conference..."
+ ]
+ ]
+ )
+ , ( "title"
+ , MetaInlines
+ [ Str "Proceedings"
+ , Space
+ , Str "of"
+ , Space
+ , Str "Balisage:"
+ , Space
+ , Str "The"
+ , Space
+ , Str "Markup"
+ , Space
+ , Str "Conference"
+ , SoftBreak
+ , Str "2013"
+ ]
+ )
+ ]
+ }
+ [ Para
+ [ Str "The"
+ , Space
+ , Emph
+ [ Str "Balisage"
+ , Space
+ , Str "Series"
+ , Space
+ , Str "on"
+ , Space
+ , Str "Markup"
+ , Space
+ , Str "Technologies"
+ ]
+ , SoftBreak
+ , Str "is"
+ , Space
+ , Str "an"
+ , Space
+ , Str "occasional"
+ , Space
+ , Str "series..."
+ ]
+ ]
+```
\ No newline at end of file
diff --git a/documents/markdown/pandoc-md/bits-book-part-wrapper.md b/documents/markdown/pandoc-md/bits-book-part-wrapper.md
new file mode 100644
index 0000000..206ad95
--- /dev/null
+++ b/documents/markdown/pandoc-md/bits-book-part-wrapper.md
@@ -0,0 +1,149 @@
+```
+% pandoc -f jats -t native
+<book-part-wrapper
+ dtd-version="2.1"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:mml="http://www.w3.org/1998/Math/MathML"
+ xmlns:xlink="http://www.w3.org/1999/xlink">
+
+ <collection-meta>
+ <title-group>
+ <title>Balisage Series on Markup Technologies</title>
+ </title-group>
+
+ <abstract>
+ <p>The <italic>Balisage Series on Markup Technologies</italic>
+ is an occasional series...</p>
+ </abstract>
+ </collection-meta>
+
+ <book-meta>
+ <book-title-group>
+ <book-title>Proceedings of Balisage: The Markup Conference
+ 2013</book-title>
+ </book-title-group>
+
+ <abstract>
+ <p>Balisage is a peer-reviewed conference...</p></abstract>
+
+ </book-meta>
+
+ <book-part id="bid.1" book-part-type="part">
+ <book-part-meta>
+ <title-group>
+ <label>Part 1</label>
+ <title>The Databases</title>
+ </title-group>
+ </book-part-meta>
+ <body>
+ <sec id="bid.3">
+ <title>History</title>
+ <p>Initially, GenBank was built and maintained at Los Alamos
+ National Laboratory.</p>
+ </sec>
+ </body>
+ <back>
+ <title>Back matter of book part</title>
+ <ref-list>
+ <title>References</title>
+ <ref id="bid.41">
+ <label>1</label>
+ <element-citation>
+ <person-group>
+ <string-name>
+ <surname>Olson</surname>
+ <given-names>M</given-names>
+ </string-name>
+ <string-name>
+ <surname>Hood</surname>
+ <given-names>L</given-names>
+ </string-name>
+ <string-name>
+ <surname>Cantor</surname>
+ <given-names>C</given-names>
+ </string-name>
+ <string-name>
+ <surname>Botstein</surname>
+ <given-names>D</given-names>
+ </string-name>
+ </person-group>
+ <article-title>A common language for physical mapping of the human genome</article-title>
+ <source>Science</source>
+ <year iso-8601-date="1989">1989</year>
+ <volume>245</volume>
+ <issue>4925</issue>
+ <fpage>1434</fpage>
+ <lpage>1435</lpage>
+ <pub-id pub-id-type="pmid">2781285</pub-id>
+ </element-citation>
+ </ref>
+ </ref-list>
+ </back>
+ </book-part>
+</book-part-wrapper>
+^D
+[ Para
+ [ Str "The"
+ , Space
+ , Emph
+ [ Str "Balisage"
+ , Space
+ , Str "Series"
+ , Space
+ , Str "on"
+ , Space
+ , Str "Markup"
+ , Space
+ , Str "Technologies"
+ ]
+ , SoftBreak
+ , Str "is"
+ , Space
+ , Str "an"
+ , Space
+ , Str "occasional"
+ , Space
+ , Str "series..."
+ ]
+, Header 2 ( "bid.3" , [] , [] ) [ Str "History" ]
+, Para
+ [ Str "Initially,"
+ , Space
+ , Str "GenBank"
+ , Space
+ , Str "was"
+ , Space
+ , Str "built"
+ , Space
+ , Str "and"
+ , Space
+ , Str "maintained"
+ , Space
+ , Str "at"
+ , Space
+ , Str "Los"
+ , Space
+ , Str "Alamos"
+ , SoftBreak
+ , Str "National"
+ , Space
+ , Str "Laboratory."
+ ]
+, Header
+ 2
+ ( "" , [] , [] )
+ [ Str "Back"
+ , Space
+ , Str "matter"
+ , Space
+ , Str "of"
+ , Space
+ , Str "book"
+ , Space
+ , Str "part"
+ ]
+, Header 1 ( "" , [] , [] ) [ Str "References" ]
+, Div ( "refs" , [] , [] ) []
+]
+```
\ No newline at end of file
diff --git a/documents/markdown/pandoc-md/bits-book.md b/documents/markdown/pandoc-md/bits-book.md
new file mode 100644
index 0000000..6515d35
--- /dev/null
+++ b/documents/markdown/pandoc-md/bits-book.md
@@ -0,0 +1,186 @@
+```
+% pandoc -f jats -t native
+<book dtd-version="2.1" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:mml="http://www.w3.org/1998/Math/MathML">
+ <front-matter>
+ <front-matter-part>
+ <book-part-meta>
+ <title-group>
+ <title>About this book</title>
+ </title-group>
+ </book-part-meta>
+ <named-book-part-body>
+ <sec sec-type="miscinfo">
+ <title>The NCBI Handbook</title>
+ <p>Bioinformatics consists of a computational approach
+ to biomedical information management and analysis.</p>
+ </sec>
+ </named-book-part-body>
+ </front-matter-part>
+ </front-matter>
+ <book-body>
+ <book-part id="bid.1" book-part-type="part">
+ <book-part-meta>
+ <title-group>
+ <label>Part 1</label>
+ <title>The Databases</title>
+ </title-group>
+ </book-part-meta>
+ <body>
+ <sec id="bid.3">
+ <title>History</title>
+ <p>Initially, GenBank was built and maintained at Los Alamos
+ National Laboratory.</p>
+ </sec>
+ </body>
+ <back>
+ <title>Back matter of book part</title>
+ <ref-list>
+ <title>References</title>
+ <ref id="bid.41">
+ <label>1</label>
+ <element-citation>
+ <person-group>
+ <string-name>
+ <surname>Olson</surname>
+ <given-names>M</given-names>
+ </string-name>
+ <string-name>
+ <surname>Hood</surname>
+ <given-names>L</given-names>
+ </string-name>
+ <string-name>
+ <surname>Cantor</surname>
+ <given-names>C</given-names>
+ </string-name>
+ <string-name>
+ <surname>Botstein</surname>
+ <given-names>D</given-names>
+ </string-name>
+ </person-group>
+ <article-title>A common language for physical mapping of the human genome</article-title>
+ <source>Science</source>
+ <year iso-8601-date="1989">1989</year>
+ <volume>245</volume>
+ <issue>4925</issue>
+ <fpage>1434</fpage>
+ <lpage>1435</lpage>
+ <pub-id pub-id-type="pmid">2781285</pub-id>
+ </element-citation>
+ </ref>
+ </ref-list>
+ </back>
+ </book-part>
+ </book-body>
+ <book-back>
+ <ack id="bid.394">
+ <title>Acknowledgments</title>
+ <p>We gratefully acknowledge the work of Vladimir Soussov,
+ as well as the entire NCBI Entrez team...</p>
+ </ack>
+ </book-back>
+</book>
+^D
+[ Header
+ 2
+ ( "" , [] , [] )
+ [ Str "The" , Space , Str "NCBI" , Space , Str "Handbook" ]
+, Para
+ [ Str "Bioinformatics"
+ , Space
+ , Str "consists"
+ , Space
+ , Str "of"
+ , Space
+ , Str "a"
+ , Space
+ , Str "computational"
+ , Space
+ , Str "approach"
+ , SoftBreak
+ , Str "to"
+ , Space
+ , Str "biomedical"
+ , Space
+ , Str "information"
+ , Space
+ , Str "management"
+ , Space
+ , Str "and"
+ , Space
+ , Str "analysis."
+ ]
+, Header 2 ( "bid.3" , [] , [] ) [ Str "History" ]
+, Para
+ [ Str "Initially,"
+ , Space
+ , Str "GenBank"
+ , Space
+ , Str "was"
+ , Space
+ , Str "built"
+ , Space
+ , Str "and"
+ , Space
+ , Str "maintained"
+ , Space
+ , Str "at"
+ , Space
+ , Str "Los"
+ , Space
+ , Str "Alamos"
+ , SoftBreak
+ , Str "National"
+ , Space
+ , Str "Laboratory."
+ ]
+, Header
+ 2
+ ( "" , [] , [] )
+ [ Str "Back"
+ , Space
+ , Str "matter"
+ , Space
+ , Str "of"
+ , Space
+ , Str "book"
+ , Space
+ , Str "part"
+ ]
+, Header 1 ( "" , [] , [] ) [ Str "References" ]
+, Div ( "refs" , [] , [] ) []
+, Header 2 ( "bid.394" , [] , [] ) [ Str "Acknowledgments" ]
+, Para
+ [ Str "We"
+ , Space
+ , Str "gratefully"
+ , Space
+ , Str "acknowledge"
+ , Space
+ , Str "the"
+ , Space
+ , Str "work"
+ , Space
+ , Str "of"
+ , Space
+ , Str "Vladimir"
+ , Space
+ , Str "Soussov,"
+ , SoftBreak
+ , Str "as"
+ , Space
+ , Str "well"
+ , Space
+ , Str "as"
+ , Space
+ , Str "the"
+ , Space
+ , Str "entire"
+ , Space
+ , Str "NCBI"
+ , Space
+ , Str "Entrez"
+ , Space
+ , Str "team..."
+ ]
+]
+```
\ No newline at end of file
diff --git a/documents/markdown/pandoc-md/bits-index-elements.md b/documents/markdown/pandoc-md/bits-index-elements.md
new file mode 100644
index 0000000..6ba03cc
--- /dev/null
+++ b/documents/markdown/pandoc-md/bits-index-elements.md
@@ -0,0 +1,83 @@
+```
+% pandoc -f jats -t native
+<index-group>
+ <index-title-group>
+ <title>Index group</title>
+ </index-title-group>
+ <p>Content of index group</p>
+ <index>
+ <index-title-group>
+ <title>Index</title>
+ </index-title-group>
+ <p>Content of index</p>
+ <index-div>
+ <index-title-group>
+ <title>N</title>
+ </index-title-group>
+ <p>Content of index div</p>
+ <index-entry>
+ <term>Navy</term>
+ <x>.</x>
+ <see-entry>Armed forces</see-entry>
+ <x>.</x>
+ </index-entry>
+ <index-entry>
+ <term>Necessary and proper clause, congressional power</term>
+ </index-entry>
+ <index-entry>
+ <term>Newsgathering as commerce</term>
+ </index-entry>
+ </index-div>
+ </index>
+</index-group>
+^D
+[ Header
+ 1 ( "" , [] , [] ) [ Str "Index" , Space , Str "group" ]
+, Para
+ [ Str "Content"
+ , Space
+ , Str "of"
+ , Space
+ , Str "index"
+ , Space
+ , Str "group"
+ ]
+, Header 2 ( "" , [] , [] ) [ Str "Index" ]
+, Para
+ [ Str "Content" , Space , Str "of" , Space , Str "index" ]
+, Header 3 ( "" , [] , [] ) [ Str "N" ]
+, Para
+ [ Str "Content"
+ , Space
+ , Str "of"
+ , Space
+ , Str "index"
+ , Space
+ , Str "div"
+ ]
+, Plain [ Str "Navy" ]
+, Plain [ Str "." ]
+, Plain [ Str "Armed" , Space , Str "forces" ]
+, Plain [ Str "." ]
+, Plain
+ [ Str "Necessary"
+ , Space
+ , Str "and"
+ , Space
+ , Str "proper"
+ , Space
+ , Str "clause,"
+ , Space
+ , Str "congressional"
+ , Space
+ , Str "power"
+ ]
+, Plain
+ [ Str "Newsgathering"
+ , Space
+ , Str "as"
+ , Space
+ , Str "commerce"
+ ]
+]
+```
\ No newline at end of file
diff --git a/documents/markdown/pandoc-md/bits-legend.md b/documents/markdown/pandoc-md/bits-legend.md
new file mode 100644
index 0000000..0217e68
--- /dev/null
+++ b/documents/markdown/pandoc-md/bits-legend.md
@@ -0,0 +1,45 @@
+```
+% pandoc -f jats -t native
+<fig id="fig_A.1" orientation="portrait">
+ <label>Figure A.1</label>
+ <caption>
+ <title>Field of Application</title>
+ </caption>
+ <legend>
+ <title>Key</title>
+ <def-list>
+ <def-item>
+ <term>I</term>
+ <def><p>input</p></def>
+ </def-item>
+ <def-item>
+ <term>O</term>
+ <def><p>output</p></def>
+ </def-item>
+ ...
+ </def-list>
+ </legend>
+ <graphic xlink:href="1234"/>
+</fig>
+^D
+[ Figure
+ ( "fig_A.1" , [] , [] )
+ (Caption
+ Nothing
+ [ Plain
+ [ Str "Field"
+ , Space
+ , Str "of"
+ , Space
+ , Str "Application"
+ ]
+ ])
+ [ Header 1 ( "" , [] , [] ) [ Str "Key" ]
+ , DefinitionList
+ [ ( [ Str "I" ] , [ [ Para [ Str "input" ] ] ] )
+ , ( [ Str "O" ] , [ [ Para [ Str "output" ] ] ] )
+ ]
+ , Para [ Image ( "" , [] , [] ) [] ( "1234" , "" ) ]
+ ]
+]
+```
\ No newline at end of file
diff --git a/documents/markdown/pandoc-md/bits-named-boook-parts.md b/documents/markdown/pandoc-md/bits-named-boook-parts.md
new file mode 100644
index 0000000..8a87942
--- /dev/null
+++ b/documents/markdown/pandoc-md/bits-named-boook-parts.md
@@ -0,0 +1,68 @@
+```
+% pandoc -f jats -t native
+<dedication>
+ <named-book-part-body>
+ <p>This is the dedication text.</p>
+ </named-book-part-body>
+</dedication>
+^D
+[ Header 1 ( "" , [] , [] ) [ Str "Dedication" ]
+, Para
+ [ Str "This"
+ , Space
+ , Str "is"
+ , Space
+ , Str "the"
+ , Space
+ , Str "dedication"
+ , Space
+ , Str "text."
+ ]
+]
+```
+
+```
+% pandoc -f jats -t native
+<foreword>
+ <named-book-part-body>
+ <p>This is the foreword text.</p>
+ </named-book-part-body>
+</foreword>
+^D
+[ Header 1 ( "" , [] , [] ) [ Str "Foreword" ]
+, Para
+ [ Str "This"
+ , Space
+ , Str "is"
+ , Space
+ , Str "the"
+ , Space
+ , Str "foreword"
+ , Space
+ , Str "text."
+ ]
+]
+```
+
+```
+% pandoc -f jats -t native
+<preface>
+ <named-book-part-body>
+ <p>This is the preface text.</p>
+ </named-book-part-body>
+</preface>
+^D
+[ Header 1 ( "" , [] , [] ) [ Str "Preface" ]
+, Para
+ [ Str "This"
+ , Space
+ , Str "is"
+ , Space
+ , Str "the"
+ , Space
+ , Str "preface"
+ , Space
+ , Str "text."
+ ]
+]
+```
\ No newline at end of file
diff --git a/documents/markdown/pandoc-md/bits-title-display-as.md b/documents/markdown/pandoc-md/bits-title-display-as.md
new file mode 100644
index 0000000..88bec9b
--- /dev/null
+++ b/documents/markdown/pandoc-md/bits-title-display-as.md
@@ -0,0 +1,175 @@
+```
+% pandoc -f jats -t native
+<sec>
+ <title>THE EUROPEAN UNION EXPLAINED</title>
+</sec>
+^D
+[ Header
+ 1
+ ( "" , [] , [] )
+ [ Str "THE"
+ , Space
+ , Str "EUROPEAN"
+ , Space
+ , Str "UNION"
+ , Space
+ , Str "EXPLAINED"
+ ]
+]
+```
+
+```
+% pandoc -f jats -t native
+<sec>
+ <title display-as="3">THE EUROPEAN UNION EXPLAINED</title>
+</sec>
+^D
+[ Header
+ 3
+ ( "" , [] , [] )
+ [ Str "THE"
+ , Space
+ , Str "EUROPEAN"
+ , Space
+ , Str "UNION"
+ , Space
+ , Str "EXPLAINED"
+ ]
+]
+```
+
+```
+% pandoc -f jats -t native
+<body>
+ <sec>
+ <title>The European Parliament</title>
+ <p>Members of the European Parliament (MEPs) are directly elected by EU citizens.</p>
+ <sec>
+ <title display-as="3">Composition of the European Parliament</title>
+ <p>The seats in the European Parliament are allocated among the Member States.</p>
+ </sec>
+ <sec>
+ <title>Composition of the European Parliament - II </title>
+ <p>Most MEPs are associated with a national political party in their home country.</p>
+ </sec>
+ </sec>
+</body>
+^D
+[ Header
+ 1
+ ( "" , [] , [] )
+ [ Str "The"
+ , Space
+ , Str "European"
+ , Space
+ , Str "Parliament"
+ ]
+, Para
+ [ Str "Members"
+ , Space
+ , Str "of"
+ , Space
+ , Str "the"
+ , Space
+ , Str "European"
+ , Space
+ , Str "Parliament"
+ , Space
+ , Str "(MEPs)"
+ , Space
+ , Str "are"
+ , Space
+ , Str "directly"
+ , Space
+ , Str "elected"
+ , Space
+ , Str "by"
+ , Space
+ , Str "EU"
+ , Space
+ , Str "citizens."
+ ]
+, Header
+ 3
+ ( "" , [] , [] )
+ [ Str "Composition"
+ , Space
+ , Str "of"
+ , Space
+ , Str "the"
+ , Space
+ , Str "European"
+ , Space
+ , Str "Parliament"
+ ]
+, Para
+ [ Str "The"
+ , Space
+ , Str "seats"
+ , Space
+ , Str "in"
+ , Space
+ , Str "the"
+ , Space
+ , Str "European"
+ , Space
+ , Str "Parliament"
+ , Space
+ , Str "are"
+ , Space
+ , Str "allocated"
+ , Space
+ , Str "among"
+ , Space
+ , Str "the"
+ , Space
+ , Str "Member"
+ , Space
+ , Str "States."
+ ]
+, Header
+ 2
+ ( "" , [] , [] )
+ [ Str "Composition"
+ , Space
+ , Str "of"
+ , Space
+ , Str "the"
+ , Space
+ , Str "European"
+ , Space
+ , Str "Parliament"
+ , Space
+ , Str "-"
+ , Space
+ , Str "II"
+ ]
+, Para
+ [ Str "Most"
+ , Space
+ , Str "MEPs"
+ , Space
+ , Str "are"
+ , Space
+ , Str "associated"
+ , Space
+ , Str "with"
+ , Space
+ , Str "a"
+ , Space
+ , Str "national"
+ , Space
+ , Str "political"
+ , Space
+ , Str "party"
+ , Space
+ , Str "in"
+ , Space
+ , Str "their"
+ , Space
+ , Str "home"
+ , Space
+ , Str "country."
+ ]
+]
+```
\ No newline at end of file
diff --git a/documents/markdown/pandoc-md/bits-title-supress.md b/documents/markdown/pandoc-md/bits-title-supress.md
new file mode 100644
index 0000000..e66c6ed
--- /dev/null
+++ b/documents/markdown/pandoc-md/bits-title-supress.md
@@ -0,0 +1,122 @@
+```
+% pandoc -f jats -t native
+<sec>
+ <title>The European Parliament</title>
+ <p>Members of the European Parliament (MEPs) are directly elected by EU citizens.</p>
+</sec>
+^D
+[ Header
+ 1
+ ( "" , [] , [] )
+ [ Str "The"
+ , Space
+ , Str "European"
+ , Space
+ , Str "Parliament"
+ ]
+, Para
+ [ Str "Members"
+ , Space
+ , Str "of"
+ , Space
+ , Str "the"
+ , Space
+ , Str "European"
+ , Space
+ , Str "Parliament"
+ , Space
+ , Str "(MEPs)"
+ , Space
+ , Str "are"
+ , Space
+ , Str "directly"
+ , Space
+ , Str "elected"
+ , Space
+ , Str "by"
+ , Space
+ , Str "EU"
+ , Space
+ , Str "citizens."
+ ]
+]
+```
+
+```
+% pandoc -f jats -t native
+<sec>
+ <title suppress="no">The European Parliament</title>
+ <p>Members of the European Parliament (MEPs) are directly elected by EU citizens.</p>
+</sec>
+^D
+[ Header
+ 1
+ ( "" , [] , [] )
+ [ Str "The"
+ , Space
+ , Str "European"
+ , Space
+ , Str "Parliament"
+ ]
+, Para
+ [ Str "Members"
+ , Space
+ , Str "of"
+ , Space
+ , Str "the"
+ , Space
+ , Str "European"
+ , Space
+ , Str "Parliament"
+ , Space
+ , Str "(MEPs)"
+ , Space
+ , Str "are"
+ , Space
+ , Str "directly"
+ , Space
+ , Str "elected"
+ , Space
+ , Str "by"
+ , Space
+ , Str "EU"
+ , Space
+ , Str "citizens."
+ ]
+]
+```
+
+```
+% pandoc -f jats -t native
+<sec>
+ <title suppress="yes">The European Parliament</title>
+ <p>Members of the European Parliament (MEPs) are directly elected by EU citizens.</p>
+</sec>
+^D
+[ Para
+ [ Str "Members"
+ , Space
+ , Str "of"
+ , Space
+ , Str "the"
+ , Space
+ , Str "European"
+ , Space
+ , Str "Parliament"
+ , Space
+ , Str "(MEPs)"
+ , Space
+ , Str "are"
+ , Space
+ , Str "directly"
+ , Space
+ , Str "elected"
+ , Space
+ , Str "by"
+ , Space
+ , Str "EU"
+ , Space
+ , Str "citizens."
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/bits-toc-elements.md b/documents/markdown/pandoc-md/bits-toc-elements.md
new file mode 100644
index 0000000..415a255
--- /dev/null
+++ b/documents/markdown/pandoc-md/bits-toc-elements.md
@@ -0,0 +1,69 @@
+```
+% pandoc -f jats -t native
+<toc-group>
+ <toc-title-group>
+ <title>TOC group</title>
+ </toc-title-group>
+ <p>Content of toc group</p>
+ <toc>
+ <toc-title-group>
+ <title>TOC</title>
+ </toc-title-group>
+ <p>Content of TOC</p>
+ <toc-div content-type="sections">
+ <toc-title-group>
+ <title>Mental Health Services</title>
+ </toc-title-group>
+ <toc-entry>
+ <label>Section 1</label>
+ <title>Introduction</title>
+ <nav-pointer rid="tc3"/>
+ </toc-entry>
+ <toc-entry>
+ <label>Section 2</label>
+ <title>Mental Health of the Population</title>
+ <nav-pointer rid="tc4"/>
+ </toc-entry>
+ </toc-div>
+ </toc>
+</toc-group>
+^D
+[ Header
+ 1 ( "" , [] , [] ) [ Str "TOC" , Space , Str "group" ]
+, Para
+ [ Str "Content"
+ , Space
+ , Str "of"
+ , Space
+ , Str "toc"
+ , Space
+ , Str "group"
+ ]
+, Header 2 ( "" , [] , [] ) [ Str "TOC" ]
+, Para
+ [ Str "Content" , Space , Str "of" , Space , Str "TOC" ]
+, Header
+ 3
+ ( "" , [] , [] )
+ [ Str "Mental"
+ , Space
+ , Str "Health"
+ , Space
+ , Str "Services"
+ ]
+, Header 4 ( "" , [] , [] ) [ Str "Introduction" ]
+, Header
+ 4
+ ( "" , [] , [] )
+ [ Str "Mental"
+ , Space
+ , Str "Health"
+ , Space
+ , Str "of"
+ , Space
+ , Str "the"
+ , Space
+ , Str "Population"
+ ]
+]
+```
\ No newline at end of file
diff --git a/documents/markdown/pandoc-md/cite-in-inline-note.md b/documents/markdown/pandoc-md/cite-in-inline-note.md
new file mode 100644
index 0000000..aa61b93
--- /dev/null
+++ b/documents/markdown/pandoc-md/cite-in-inline-note.md
@@ -0,0 +1,26 @@
+```
+% pandoc -t native
+foo^[bar [@doe]]
+^D
+[ Para
+ [ Str "foo"
+ , Note
+ [ Para
+ [ Str "bar"
+ , Space
+ , Cite
+ [ Citation
+ { citationId = "doe"
+ , citationPrefix = []
+ , citationSuffix = []
+ , citationMode = NormalCitation
+ , citationNoteNum = 1
+ , citationHash = 0
+ }
+ ]
+ [ Str "[@doe]" ]
+ ]
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/citeproc-17.md b/documents/markdown/pandoc-md/citeproc-17.md
new file mode 100644
index 0000000..d80550f
--- /dev/null
+++ b/documents/markdown/pandoc-md/citeproc-17.md
@@ -0,0 +1,17 @@
+```
+% pandoc -t csljson
+---
+references:
+- id: foo
+ type: book
+ title: "Hi & Low"
+...
+^D
+[
+ {
+ "id": "foo",
+ "title": "Hi & Low",
+ "type": "book"
+ }
+]
+```
diff --git a/documents/markdown/pandoc-md/citeproc-20.md b/documents/markdown/pandoc-md/citeproc-20.md
new file mode 100644
index 0000000..0c4f7ab
--- /dev/null
+++ b/documents/markdown/pandoc-md/citeproc-20.md
@@ -0,0 +1,25 @@
+```
+% pandoc --citeproc -t plain
+Lorem ipsum dolor sit amet^[Consectetur adipisicing elit: «sed do eiusmod tempor incididunt» [@doe_1989, 15].].
+
+---
+csl: command/chicago-fullnote-bibliography.csl
+suppress-bibliography: true
+references:
+- id: doe_1989
+ author:
+ - family: Doe
+ given: John
+ issued:
+ - year: 1989
+ publisher: ABC
+ publisher-place: New York
+ title: Tempor
+ type: book
+...
+^D
+Lorem ipsum dolor sit amet[1].
+
+[1] Consectetur adipisicing elit: «sed do eiusmod tempor incididunt»
+(John Doe, Tempor (New York: ABC, 1989), 15).
+```
diff --git a/documents/markdown/pandoc-md/citeproc-7a.md b/documents/markdown/pandoc-md/citeproc-7a.md
new file mode 100644
index 0000000..9ea9017
--- /dev/null
+++ b/documents/markdown/pandoc-md/citeproc-7a.md
@@ -0,0 +1,42 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: command/chicago-fullnote-bibliography.csl
+references:
+ - id: test
+ title: Test
+ author:
+ family: Doe
+ given: John
+---
+
+Test [@test, 12].
+
+Test [@test, 12].
+
+Test.^[asdfasdf]
+
+Test [@test, 12].
+^D
+Test.[^1]
+
+Test.[^2]
+
+Test.[^3]
+
+Test.[^4]
+
+:::: {#refs .references .csl-bib-body .hanging-indent entry-spacing="0"}
+::: {#ref-test .csl-entry}
+Doe, John. "Test," n.d.
+:::
+::::
+
+[^1]: John Doe, "Test," n.d., 12.
+
+[^2]: Doe, 12.
+
+[^3]: asdfasdf
+
+[^4]: Doe, "Test," 12.
+```
diff --git a/documents/markdown/pandoc-md/citeproc-7b.md b/documents/markdown/pandoc-md/citeproc-7b.md
new file mode 100644
index 0000000..a8768f5
--- /dev/null
+++ b/documents/markdown/pandoc-md/citeproc-7b.md
@@ -0,0 +1,36 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: command/bioethics.csl
+references:
+ - id: test
+ title: Test
+ author:
+ family: Doe
+ given: John
+---
+
+Irrelevant.^[note]
+
+Test [@test, 12].
+
+Test.^[asdfasdf]
+
+Test [@test, 12].
+^D
+Irrelevant.[^1]
+
+Test.[^2]
+
+Test.[^3]
+
+Test.[^4]
+
+[^1]: note
+
+[^2]: J. Doe. ***Test***: 12.
+
+[^3]: asdfasdf
+
+[^4]: Doe (cited n. 2) : 12.
+```
diff --git a/documents/markdown/pandoc-md/citeproc-87.md b/documents/markdown/pandoc-md/citeproc-87.md
new file mode 100644
index 0000000..2c6f7a7
--- /dev/null
+++ b/documents/markdown/pandoc-md/citeproc-87.md
@@ -0,0 +1,59 @@
+```
+% pandoc --citeproc -Mlang=it-IT -t markdown-citations
+Foo [@a 50: «Disse: "bar"»]. «Disse: "baz"»
+
+---
+suppress-bibliography: true
+references:
+- id: a
+ author:
+ - literal: Aristotele
+ title: Metafisica
+ type: book
+...
+^D
+Foo (Aristotele, s.d., 50: «Disse: "bar"»). «Disse: "baz"»
+```
+
+The Quoted is passed to citeproc as a Span ("",["csl-quoted"],[])
+so that flipflopping and localization occur.
+```
+% pandoc -C -t plain -Mlang=en --csl command/le-tapuscrit-note.csl
+---
+references:
+- id: a
+ author:
+ - literal: Aristotele
+ title: Metafisica et "Physica"
+ type: article-journal
+...
+
+Foo [@a 50].
+^D
+Foo.[1]
+
+ARISTOTELE, “Metafisica et ‘Physica’.”
+
+[1] Aristotele, “Metafisica et ‘Physica’,” p. 50.
+```
+
+```
+% pandoc -C -t plain -Mlang=it --csl command/le-tapuscrit-note.csl
+---
+references:
+- id: a
+ author:
+ - literal: Aristotele
+ title: Metafisica et "Physica"
+ type: article-journal
+...
+
+Foo [@a 50].
+^D
+Foo.[1]
+
+ARISTOTELE, «Metafisica et “Physica”».
+
+[1] Aristotele, «Metafisica et “Physica”», p. 50.
+```
+
diff --git a/documents/markdown/pandoc-md/citeproc-author-in-text-suffix.md b/documents/markdown/pandoc-md/citeproc-author-in-text-suffix.md
new file mode 100644
index 0000000..df3184a
--- /dev/null
+++ b/documents/markdown/pandoc-md/citeproc-author-in-text-suffix.md
@@ -0,0 +1,34 @@
+```
+% pandoc -t native
+@a [p. 33; @b]
+^D
+[ Para
+ [ Cite
+ [ Citation
+ { citationId = "a"
+ , citationPrefix = []
+ , citationSuffix = [ Str "p.\160\&33" ]
+ , citationMode = AuthorInText
+ , citationNoteNum = 1
+ , citationHash = 0
+ }
+ , Citation
+ { citationId = "b"
+ , citationPrefix = []
+ , citationSuffix = []
+ , citationMode = NormalCitation
+ , citationNoteNum = 1
+ , citationHash = 0
+ }
+ ]
+ [ Str "@a"
+ , Space
+ , Str "[p."
+ , Space
+ , Str "33;"
+ , Space
+ , Str "@b]"
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/csv.md b/documents/markdown/pandoc-md/csv.md
new file mode 100644
index 0000000..3535125
--- /dev/null
+++ b/documents/markdown/pandoc-md/csv.md
@@ -0,0 +1,102 @@
+```
+% pandoc -f csv -t native
+Fruit,Price,Quantity
+Apple,25 cents,33
+"""Navel"" Orange","35 cents",22
+,,45
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Fruit" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Price" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Quantity" ] ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Apple" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "25" , Space , Str "cents" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "33" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "\"Navel\"" , Space , Str "Orange" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "35" , Space , Str "cents" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "22" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] ) AlignDefault (RowSpan 1) (ColSpan 1) []
+ , Cell
+ ( "" , [] , [] ) AlignDefault (RowSpan 1) (ColSpan 1) []
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "45" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
diff --git a/documents/markdown/pandoc-md/defaults-inheritance-2.md b/documents/markdown/pandoc-md/defaults-inheritance-2.md
new file mode 100644
index 0000000..e50332c
--- /dev/null
+++ b/documents/markdown/pandoc-md/defaults-inheritance-2.md
@@ -0,0 +1,6 @@
+```
+% pandoc -d command/defaults6 2>&1
+^D
+Error: Circular defaults file reference in 'command/defaults7.yaml'
+=> 63
+```
diff --git a/documents/markdown/pandoc-md/definition-lists.md b/documents/markdown/pandoc-md/definition-lists.md
new file mode 100644
index 0000000..a075d51
--- /dev/null
+++ b/documents/markdown/pandoc-md/definition-lists.md
@@ -0,0 +1,70 @@
+---
+vimdoc-prefix: pandoc
+abstract: "A short description"
+filename: "definition-lists.txt"
+author: Author
+title: Title
+---
+
+## Basic
+
+Term 1
+: Definition I
+
+Term 2
+: Definition II
+
+Term 3
+: Definition III
+
+## Code
+
+<!-- Source: <https://github.com/ggandor/leap.nvim/blob/c4a215acef90749851d85ddba08bc282867b50eb/doc/leap.txt#L283-L294> -->
+
+`leap.opts.keys.next_target`
+: Jump to the next available target (use the previous search pattern if no input
+ has been given). `:h leap-repeat`
+
+`leap.opts.keys.prev_target`
+: Jump to the previous target (revert `next_target`).
+
+`leap.opts.keys.next_group`
+: Shift to the next group of labeled targets.
+
+`leap.opts.keys.prev_group`
+: Shift to the previous group of labeled targets (revert `next_group`).
+
+## Span
+
+[Important concept]{#important-concept}
+: Definition
+
+[I am too long to fit on the same line as a reference, so reference is put above me!]{#i-am-too-long}
+: Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
+ tempor incididunt ut labore et dolore magna aliqua.
+
+## Commands
+
+In markdown vim commands are represented as inline code starting with colon (ie.
+`:MyCommand`), but writer strips the backticks
+
+`:FnlCompileBuffer`{#:FnlCompileBuffer}
+
+: Compiles current active fennel buffer
+
+`:FnlCompile[!]`{#:FnlCompile}
+
+: Diff compiles all indexed fennel files
+ If bang! is present then forcefully compiles all `source` files
+
+`:[range]Fnl {expr}`{#:Fnl}
+
+: Evaluates {expr} or range
+
+ ```
+ :'<,'>Fnl
+
+ :Fnl (print "Hello World")
+
+ :Fnl (values some_var)
+ ```
diff --git a/documents/markdown/pandoc-md/doc_custom-readers.md b/documents/markdown/pandoc-md/doc_custom-readers.md
new file mode 100644
index 0000000..4b1ec21
--- /dev/null
+++ b/documents/markdown/pandoc-md/doc_custom-readers.md
@@ -0,0 +1,613 @@
+---
+author:
+- John MacFarlane
+date: 'November 18, 2021'
+title: Creating Custom Pandoc Readers in Lua
+---
+
+# Introduction
+
+If you need to parse a format not already handled by pandoc,
+you can create a custom reader using the [Lua] language.
+Pandoc has a built-in Lua interpreter, so you needn't
+install any additional software to do this.
+
+[Lua]: https://www.lua.org
+
+A custom reader is a Lua file that defines a function
+called `Reader`, which takes two arguments:
+
+- the raw input to be parsed, as a list of sources
+- optionally, a table of reader options, e.g.
+ `{ columns = 62, standalone = true }`.
+
+The `Reader` function should return a `Pandoc` AST.
+This can be created using functions in the [`pandoc` module],
+which is automatically in scope. (Indeed, all of the utility
+functions that are available for [Lua filters] are available
+in custom readers, too.)
+
+Each source item corresponds to a file or stream passed to pandoc
+containing its text and name. E.g., if a single file `input.txt`
+is passed to pandoc, then the list of sources will contain just a
+single element `s`, where `s.name == 'input.txt'` and `s.text`
+contains the file contents as a string.
+
+The sources list, as well as each of its elements, can be
+converted to a string via the Lua standard library function
+`tostring`.
+
+[Lua filters]: https://pandoc.org/lua-filters.html
+[`pandoc` module]: https://pandoc.org/lua-filters.html#module-pandoc
+
+A minimal example would be
+
+```lua
+function Reader(input)
+ return pandoc.Pandoc({ pandoc.CodeBlock(tostring(input)) })
+end
+```
+
+This just returns a document containing a big code block with all
+of the input. Or, to create a separate code block for each input
+file, one might write
+
+``` lua
+function Reader(input)
+ return pandoc.Pandoc(input:map(
+ function (s) return pandoc.CodeBlock(s.text) end))
+end
+```
+
+In a nontrivial reader, you'll want to parse the input.
+You can do this using standard Lua library functions
+(for example, the [patterns] library), or with the powerful
+and fast [lpeg] parsing library, which is automatically in scope.
+You can also use external Lua libraries (for example,
+an XML parser).
+
+A previous pandoc version passed a raw string instead of a list
+of sources to the Reader function. Reader functions that rely on
+this are obsolete, but still supported: Pandoc analyzes any
+script error, detecting when code assumed the old behavior. The
+code is rerun with raw string input in this case, thereby
+ensuring backwards compatibility.
+
+[patterns]: http://lua-users.org/wiki/PatternsTutorial
+[lpeg]: http://www.inf.puc-rio.br/~roberto/lpeg/
+
+# Bytestring readers
+
+In order to read binary formats, including docx, odt, and epub,
+pandoc supports the `ByteStringReader` function. A
+`ByteStringReader` function is similar to the `Reader` function
+that processes text input. Instead of a list of sources, the
+ByteStringReader function is passed a bytestring, i.e., a string
+that contains the binary input.
+
+``` lua
+-- read input as epub
+function ByteStringReader (input)
+ return pandoc.read(input, 'epub')
+end
+```
+
+# Format extensions
+
+Custom readers can be built such that their behavior is
+controllable through format extensions, such as `smart`,
+`citations`, or `hard-line-breaks`. Supported extensions are those
+that are present as a key in the global `Extensions` table. Fields
+of extensions that are enabled default have the value `true` or
+`enable`, while those that are supported but disabled have value
+`false` or `disable`.
+
+Example: A reader with the following global table supports the
+extensions `smart`, `citations`, and `foobar`, with `smart` enabled and
+the other two disabled by default:
+
+``` lua
+Extensions = {
+ smart = 'enable',
+ citations = 'disable',
+ foobar = true
+}
+```
+
+The users control extensions as usual, e.g., `pandoc -f
+my-reader.lua+citations`. The extensions are accessible through
+the reader options' `extensions` field, e.g.:
+
+``` lua
+function Reader (input, opts)
+ print(
+ 'The citations extension is',
+ opts.extensions:includes 'citations' and 'enabled' or 'disabled'
+ )
+ -- ...
+end
+```
+
+Extensions that are neither enabled nor disabled in the
+`Extensions` field are treated as unsupported by the
+reader. Trying to modify such an extension via the command line
+will lead to an error.
+
+
+# Example: plain text reader
+
+This is a simple example using [lpeg] to parse the input
+into space-separated strings and blankline-separated paragraphs.
+
+```lua
+-- A sample custom reader that just parses text into blankline-separated
+-- paragraphs with space-separated words.
+
+-- For better performance we put these functions in local variables:
+local P, S, R, Cf, Cc, Ct, V, Cs, Cg, Cb, B, C, Cmt =
+ lpeg.P, lpeg.S, lpeg.R, lpeg.Cf, lpeg.Cc, lpeg.Ct, lpeg.V,
+ lpeg.Cs, lpeg.Cg, lpeg.Cb, lpeg.B, lpeg.C, lpeg.Cmt
+
+local whitespacechar = S(" \t\r\n")
+local wordchar = (1 - whitespacechar)
+local spacechar = S(" \t")
+local newline = P"\r"^-1 * P"\n"
+local blanklines = newline * (spacechar^0 * newline)^1
+local endline = newline - blanklines
+
+-- Grammar
+G = P{ "Pandoc",
+ Pandoc = Ct(V"Block"^0) / pandoc.Pandoc;
+ Block = blanklines^0 * V"Para" ;
+ Para = Ct(V"Inline"^1) / pandoc.Para;
+ Inline = V"Str" + V"Space" + V"SoftBreak" ;
+ Str = wordchar^1 / pandoc.Str;
+ Space = spacechar^1 / pandoc.Space;
+ SoftBreak = endline / pandoc.SoftBreak;
+}
+
+function Reader(input)
+ return lpeg.match(G, tostring(input))
+end
+```
+
+Example of use:
+
+```
+% pandoc -f plain.lua -t native
+*Hello there*, this is plain text with no formatting
+except paragraph breaks.
+
+- Like this one.
+^D
+[ Para
+ [ Str "*Hello"
+ , Space
+ , Str "there*,"
+ , Space
+ , Str "this"
+ , Space
+ , Str "is"
+ , Space
+ , Str "plain"
+ , Space
+ , Str "text"
+ , Space
+ , Str "with"
+ , Space
+ , Str "no"
+ , Space
+ , Str "formatting"
+ , SoftBreak
+ , Str "except"
+ , Space
+ , Str "paragraph"
+ , Space
+ , Str "breaks."
+ ]
+, Para
+ [ Str "-"
+ , Space
+ , Str "Like"
+ , Space
+ , Str "this"
+ , Space
+ , Str "one."
+ ]
+]
+```
+
+# Example: a wiki Creole reader
+
+This is a parser for [Creole common wiki markup].
+It uses an [lpeg] grammar. Fun fact: this custom reader is faster than
+pandoc's built-in creole reader! This shows that high-performance
+readers can be designed in this way.
+
+[Creole common wiki markup]: http://www.wikicreole.org/wiki/CheatSheet
+
+
+```lua
+-- A sample custom reader for Creole 1.0 (common wiki markup)
+-- http://www.wikicreole.org/wiki/CheatSheet
+
+-- For better performance we put these functions in local variables:
+local P, S, R, Cf, Cc, Ct, V, Cs, Cg, Cb, B, C, Cmt =
+ lpeg.P, lpeg.S, lpeg.R, lpeg.Cf, lpeg.Cc, lpeg.Ct, lpeg.V,
+ lpeg.Cs, lpeg.Cg, lpeg.Cb, lpeg.B, lpeg.C, lpeg.Cmt
+
+local whitespacechar = S(" \t\r\n")
+local specialchar = S("/*~[]\\{}|")
+local wordchar = (1 - (whitespacechar + specialchar))
+local spacechar = S(" \t")
+local newline = P"\r"^-1 * P"\n"
+local blankline = spacechar^0 * newline
+local endline = newline * #-blankline
+local endequals = spacechar^0 * P"="^0 * spacechar^0 * newline
+local cellsep = spacechar^0 * P"|"
+
+local function trim(s)
+ return (s:gsub("^%s*(.-)%s*$", "%1"))
+end
+
+local function ListItem(lev, ch)
+ local start
+ if ch == nil then
+ start = S"*#"
+ else
+ start = P(ch)
+ end
+ local subitem = function(c)
+ if lev < 6 then
+ return ListItem(lev + 1, c)
+ else
+ return (1 - 1) -- fails
+ end
+ end
+ local parser = spacechar^0
+ * start^lev
+ * #(- start)
+ * spacechar^0
+ * Ct((V"Inline" - (newline * spacechar^0 * S"*#"))^0)
+ * newline
+ * (Ct(subitem("*")^1) / pandoc.BulletList
+ +
+ Ct(subitem("#")^1) / pandoc.OrderedList
+ +
+ Cc(nil))
+ / function (ils, sublist)
+ return { pandoc.Plain(ils), sublist }
+ end
+ return parser
+end
+
+-- Grammar
+G = P{ "Doc",
+ Doc = Ct(V"Block"^0)
+ / pandoc.Pandoc ;
+ Block = blankline^0
+ * ( V"Header"
+ + V"HorizontalRule"
+ + V"CodeBlock"
+ + V"List"
+ + V"Table"
+ + V"Para") ;
+ Para = Ct(V"Inline"^1)
+ * newline
+ / pandoc.Para ;
+ HorizontalRule = spacechar^0
+ * P"----"
+ * spacechar^0
+ * newline
+ / pandoc.HorizontalRule;
+ Header = (P("=")^1 / string.len)
+ * spacechar^1
+ * Ct((V"Inline" - endequals)^1)
+ * endequals
+ / pandoc.Header;
+ CodeBlock = P"{{{"
+ * blankline
+ * C((1 - (newline * P"}}}"))^0)
+ * newline
+ * P"}}}"
+ / pandoc.CodeBlock;
+ Placeholder = P"<<<"
+ * C(P(1) - P">>>")^0
+ * P">>>"
+ / function() return pandoc.Div({}) end;
+ List = V"BulletList"
+ + V"OrderedList" ;
+ BulletList = Ct(ListItem(1,'*')^1)
+ / pandoc.BulletList ;
+ OrderedList = Ct(ListItem(1,'#')^1)
+ / pandoc.OrderedList ;
+ Table = (V"TableHeader" + Cc{})
+ * Ct(V"TableRow"^1)
+ / function(headrow, bodyrows)
+ local numcolumns = #(bodyrows[1])
+ local aligns = {}
+ local widths = {}
+ for i = 1,numcolumns do
+ aligns[i] = pandoc.AlignDefault
+ widths[i] = 0
+ end
+ return pandoc.utils.from_simple_table(
+ pandoc.SimpleTable({}, aligns, widths, headrow, bodyrows))
+ end ;
+ TableHeader = Ct(V"HeaderCell"^1)
+ * cellsep^-1
+ * spacechar^0
+ * newline ;
+ TableRow = Ct(V"BodyCell"^1)
+ * cellsep^-1
+ * spacechar^0
+ * newline ;
+ HeaderCell = cellsep
+ * P"="
+ * spacechar^0
+ * Ct((V"Inline" - (newline + cellsep))^0)
+ / function(ils) return { pandoc.Plain(ils) } end ;
+ BodyCell = cellsep
+ * spacechar^0
+ * Ct((V"Inline" - (newline + cellsep))^0)
+ / function(ils) return { pandoc.Plain(ils) } end ;
+ Inline = V"Emph"
+ + V"Strong"
+ + V"LineBreak"
+ + V"Link"
+ + V"URL"
+ + V"Image"
+ + V"Str"
+ + V"Space"
+ + V"SoftBreak"
+ + V"Escaped"
+ + V"Placeholder"
+ + V"Code"
+ + V"Special" ;
+ Str = wordchar^1
+ / pandoc.Str;
+ Escaped = P"~"
+ * C(P(1))
+ / pandoc.Str ;
+ Special = specialchar
+ / pandoc.Str;
+ Space = spacechar^1
+ / pandoc.Space ;
+ SoftBreak = endline
+ * # -(V"HorizontalRule" + V"CodeBlock")
+ / pandoc.SoftBreak ;
+ LineBreak = P"\\\\"
+ / pandoc.LineBreak ;
+ Code = P"{{{"
+ * C((1 - P"}}}")^0)
+ * P"}}}"
+ / trim / pandoc.Code ;
+ Link = P"[["
+ * C((1 - (P"]]" + P"|"))^0)
+ * (P"|" * Ct((V"Inline" - P"]]")^1))^-1 * P"]]"
+ / function(url, desc)
+ local txt = desc or {pandoc.Str(url)}
+ return pandoc.Link(txt, url)
+ end ;
+ Image = P"{{"
+ * #-P"{"
+ * C((1 - (S"}"))^0)
+ * (P"|" * Ct((V"Inline" - P"}}")^1))^-1
+ * P"}}"
+ / function(url, desc)
+ local txt = desc or ""
+ return pandoc.Image(txt, url)
+ end ;
+ URL = P"http"
+ * P"s"^-1
+ * P":"
+ * (1 - (whitespacechar + (S",.?!:;\"'" * #whitespacechar)))^1
+ / function(url)
+ return pandoc.Link(pandoc.Str(url), url)
+ end ;
+ Emph = P"//"
+ * Ct((V"Inline" - P"//")^1)
+ * P"//"
+ / pandoc.Emph ;
+ Strong = P"**"
+ * Ct((V"Inline" -P"**")^1)
+ * P"**"
+ / pandoc.Strong ;
+}
+
+function Reader(input, reader_options)
+ return lpeg.match(G, tostring(input))
+end
+```
+
+Example of use:
+
+```
+% pandoc -f creole.lua -t markdown
+== Wiki Creole
+
+You can make things **bold** or //italic// or **//both//** or //**both**//.
+
+Character formatting extends across line breaks: **bold,
+this is still bold. This line deliberately does not end in star-star.
+
+Not bold. Character formatting does not cross paragraph boundaries.
+
+You can use [[internal links]] or [[http://www.wikicreole.org|external links]],
+give the link a [[internal links|different]] name.
+^D
+## Wiki Creole
+
+You can make things **bold** or *italic* or ***both*** or ***both***.
+
+Character formatting extends across line breaks: \*\*bold, this is still
+bold. This line deliberately does not end in star-star.
+
+Not bold. Character formatting does not cross paragraph boundaries.
+
+You can use [internal links](internal links) or [external
+links](http://www.wikicreole.org), give the link a
+[different](internal links) name.
+```
+
+# Example: parsing JSON from an API
+
+This custom reader consumes the JSON output of
+<https://www.reddit.com/r/haskell.json> and produces
+a document containing the current top articles on the
+Haskell subreddit.
+
+It assumes that the `pandoc.json` library is available, which
+ships with pandoc versions after (not including) 3.1. It's still
+possible to use this with older pandoc version by using a
+different JSON library. E.g., `luajson` can be installed using
+`luarocks install luajson`---but be sure you are installing it for
+Lua 5.4, which is the version packaged with pandoc.
+
+
+```lua
+-- consumes the output of https://www.reddit.com/r/haskell.json
+
+local json = require 'pandoc.json'
+
+local function read_inlines(raw)
+ local doc = pandoc.read(raw, "commonmark")
+ return pandoc.utils.blocks_to_inlines(doc.blocks)
+end
+
+local function read_blocks(raw)
+ local doc = pandoc.read(raw, "commonmark")
+ return doc.blocks
+end
+
+function Reader(input)
+
+ local parsed = json.decode(tostring(input))
+ local blocks = {}
+
+ for _,entry in ipairs(parsed.data.children) do
+ local d = entry.data
+ table.insert(blocks, pandoc.Header(2,
+ pandoc.Link(read_inlines(d.title), d.url)))
+ for _,block in ipairs(read_blocks(d.selftext)) do
+ table.insert(blocks, block)
+ end
+ end
+
+ return pandoc.Pandoc(blocks)
+
+end
+```
+
+Similar code can be used to consume JSON output from other APIs.
+
+Note that the content of the text fields is markdown, so we
+convert it using `pandoc.read()`.
+
+
+# Example: syntax-highlighted code files
+
+This is a reader that puts the content of each input file into a
+code block, sets the file's extension as the block's class to
+enable code highlighting, and places the filename as a header
+above each code block.
+
+``` lua
+function to_code_block (source)
+ local _, lang = pandoc.path.split_extension(source.name)
+ return pandoc.Div{
+ pandoc.Header(1, source.name == '' and '<stdin>' or source.name),
+ pandoc.CodeBlock(source.text, {class=lang}),
+ }
+end
+
+function Reader (input, opts)
+ return pandoc.Pandoc(input:map(to_code_block))
+end
+```
+
+# Example: extracting the content from web pages
+
+This reader uses the command-line program `readable`
+(install via `npm install -g readability-cli`)
+to clean out parts of HTML input that have to do with
+navigation, leaving only the content.
+
+``` lua
+-- Custom reader that extracts the content from HTML documents,
+-- ignoring navigation and layout elements. This preprocesses input
+-- through the 'readable' program (which can be installed using
+-- 'npm install -g readability-cli') and then calls the HTML reader.
+-- In addition, Divs that seem to have only a layout function are removed
+-- to avoid clutter.
+
+function make_readable(source)
+ local result
+ if not pcall(function ()
+ local name = source.name
+ if not name:match("http") then
+ name = "file:///" .. name
+ end
+ result = pandoc.pipe("readable",
+ {"--keep-classes","--base",name},
+ source.text)
+ end) then
+ io.stderr:write("Error running 'readable': do you have it installed?\n")
+ io.stderr:write("npm install -g readability-cli\n")
+ os.exit(1)
+ end
+ return result
+end
+
+local boring_classes =
+ { row = true,
+ page = true,
+ container = true
+ }
+
+local boring_attributes = { "role" }
+
+local function is_boring_class(cl)
+ return boring_classes[cl] or cl:match("col%-") or cl:match("pull%-")
+end
+
+local function handle_div(el)
+ for i,class in ipairs(el.classes) do
+ if is_boring_class(class) then
+ el.classes[i] = nil
+ end
+ end
+ for i,k in ipairs(boring_attributes) do
+ el.attributes[k] = nil
+ end
+ if el.identifier:match("readability%-") then
+ el.identifier = ""
+ end
+ if #el.classes == 0 and #el.attributes == 0 and #el.identifier == 0 then
+ return el.content
+ else
+ return el
+ end
+end
+
+function Reader(sources)
+ local readable = ''
+ for _,source in ipairs(sources) do
+ readable = readable .. make_readable(source)
+ end
+ local doc = pandoc.read(readable, "html", PANDOC_READER_OPTIONS)
+ -- Now remove Divs used only for layout
+ return doc:walk{ Div = handle_div }
+end
+```
+
+Example of use:
+
+```
+pandoc -f readable.lua -t markdown https://pandoc.org
+```
+and compare the output to
+```
+pandoc -f html -t markdown https://pandoc.org
+```
+
diff --git a/documents/markdown/pandoc-md/doc_custom-writers.md b/documents/markdown/pandoc-md/doc_custom-writers.md
new file mode 100644
index 0000000..72a014a
--- /dev/null
+++ b/documents/markdown/pandoc-md/doc_custom-writers.md
@@ -0,0 +1,232 @@
+---
+author:
+- John MacFarlane
+date: 'November 21, 2021'
+title: Creating Custom Pandoc Writers in Lua
+---
+
+# Introduction
+
+If you need to render a format not already handled by pandoc,
+or you want to change how pandoc renders a format,
+you can create a custom writer using the [Lua] language.
+Pandoc has a built-in Lua interpreter, so you needn't
+install any additional software to do this.
+
+[Lua]: https://www.lua.org
+
+A custom writer is a Lua file that defines how to render the
+document. Writers must define just a single function, named either
+`Writer` or `ByteStringWriter`, which gets passed the document and
+writer options, and then handles the conversion of the document,
+rendering it into a string. This interface was introduced in
+pandoc 2.17.2, with ByteString writers becoming available in
+pandoc 3.0.
+
+Pandoc also supports "classic" custom writers, where a Lua
+function must be defined for each AST element type. Classic style
+writers are *deprecated* and should be replaced with new-style
+writers if possible.
+
+# Writers
+
+Custom writers using the new style must contain a global function
+named `Writer` or `ByteStringWriter`. Pandoc calls this function
+with the document and writer options as arguments, and expects the
+function to return a UTF-8 encoded string.
+
+``` lua
+function Writer (doc, opts)
+ -- ...
+end
+```
+
+Writers that do not return text but binary data should define a
+function with name `ByteStringWriter` instead. The function must
+still return a string, but it does not have to be UTF-8 encoded
+and can contain arbitrary binary data.
+
+If both `Writer` and `ByteStringWriter` functions are defined,
+then only the `Writer` function will be used.
+
+## Format extensions
+
+Writers can be customized through format extensions, such as
+`smart`, `citations`, or `hard_line_breaks`. The global
+`Extensions` table indicates supported extensions with a
+key. Extensions enabled by default are assigned a true value,
+while those that are supported but disabled are assigned a false
+value.
+
+Example: A writer with the following global table supports the
+extensions `smart`, `citations`, and `foobar`, with `smart` enabled and
+the others disabled by default:
+
+``` lua
+Extensions = {
+ smart = true,
+ citations = false,
+ foobar = false
+}
+```
+
+The users control extensions as usual, e.g., `pandoc -t
+my-writer.lua+citations`. The extensions are accessible through
+the writer options' `extensions` field, e.g.:
+
+``` lua
+function Writer (doc, opts)
+ print(
+ 'The citations extension is',
+ opts.extensions:includes 'citations' and 'enabled' or 'disabled'
+ )
+ -- ...
+end
+```
+
+## Default template
+
+The default template of a custom writer is defined by the return
+value of the global function `Template`. Pandoc uses the default
+template for rendering when the user has not specified a template,
+but invoked with the `-s`/`--standalone` flag.
+
+The `Template` global can be left undefined, in which case pandoc
+will throw an error when it would otherwise use the default
+template.
+
+## Example: modified Markdown writer
+
+Writers have access to all modules described in the [Lua filters
+documentation][]. This includes `pandoc.write`, which can be used
+to render a document in a format already supported by pandoc. The
+document can be modified before this conversion, as demonstrated
+in the following short example. It renders a document as GitHub
+Flavored Markdown, but always uses fenced code blocks, never
+indented code.
+
+``` lua
+function Writer (doc, opts)
+ local filter = {
+ CodeBlock = function (cb)
+ -- only modify if code block has no attributes
+ if cb.attr == pandoc.Attr() then
+ local delimited = '```\n' .. cb.text .. '\n```'
+ return pandoc.RawBlock('markdown', delimited)
+ end
+ end
+ }
+ return pandoc.write(doc:walk(filter), 'gfm', opts)
+end
+
+Template = pandoc.template.default 'gfm'
+```
+
+[Lua filters documentation]: https://pandoc.org/lua-filters.html
+
+## Reducing boilerplate with `pandoc.scaffolding.Writer`
+
+The `pandoc.scaffolding.Writer` structure is a custom writer scaffold
+that serves to avoid common boilerplate code when defining a custom
+writer. The object can be used as a function and allows to skip details
+like metadata and template handling, requiring only the render functions
+for each AST element type.
+
+The value of `pandoc.scaffolding.Writer` is a function that should
+usually be assigned to the global `Writer`:
+
+``` lua
+Writer = pandoc.scaffolding.Writer
+```
+
+The render functions for Block and Inline values can then be added
+to `Writer.Block` and `Writer.Inline`, respectively. The functions
+are passed the element and the WriterOptions.
+
+``` lua
+Writer.Inline.Str = function (str)
+ return str.text
+end
+Writer.Inline.SoftBreak = function (_, opts)
+ return opts.wrap_text == "wrap-preserve"
+ and cr
+ or space
+end
+Writer.Inline.LineBreak = cr
+
+Writer.Block.Para = function (para)
+ return {Writer.Inlines(para.content), pandoc.layout.blankline}
+end
+```
+
+The render functions must return a string, a pandoc.layout *Doc*
+element, or a list of such elements. In the latter case, the
+values are concatenated as if they were passed to
+`pandoc.layout.concat`. If the value does not depend on the input,
+a constant can be used as well.
+
+The tables `Writer.Block` and `Writer.Inline` can be used as
+functions; they apply the right render function for an element of
+the respective type. E.g., `Writer.Block(pandoc.Para 'x')` will
+delegate to the `Writer.Para` render function and will return the
+result of that call.
+
+Similarly, the functions `Writer.Blocks` and `Writer.Inlines` can
+be used to render lists of elements, and `Writer.Pandoc` renders
+the document's blocks. The function `Writer.Blocks` can take a
+separator as an optional second argument, e.g.,
+`Writer.Blocks(blks, pandoc.layout.cr)`; the default block
+separator is `pandoc.layout.blankline`.
+
+All predefined functions can be overwritten when needed.
+
+The resulting Writer uses the render functions to handle metadata
+values and converts them to template variables. The template is
+applied automatically if one is given.
+
+# Classic style
+
+A writer using the classic style defines rendering functions for
+each element of the pandoc AST. Note that this style is
+*deprecated* and may be removed in later versions.
+
+For example,
+
+``` lua
+function Para(s)
+ return "<paragraph>" .. s .. "</paragraph>"
+end
+```
+
+## Template variables
+
+New template variables can be added, or existing ones
+modified, by returning a second value from function `Doc`.
+
+For example, the following will add the current date in
+variable `date`, unless `date` is already defined as either a
+metadata value or a variable:
+
+``` lua
+function Doc (body, meta, vars)
+ vars.date = vars.date or meta.date or os.date '%B %e, %Y'
+ return body, vars
+end
+```
+
+## Changes in pandoc 3.0
+
+Custom writers were reworked in pandoc 3.0. For technical reasons,
+the global variables `PANDOC_DOCUMENT` and `PANDOC_WRITER_OPTIONS`
+are set to the empty document and default values, respectively.
+The old behavior can be restored by adding the following snippet,
+which turns a classic into a new style writer.
+
+``` lua
+function Writer (doc, opts)
+ PANDOC_DOCUMENT = doc
+ PANDOC_WRITER_OPTIONS = opts
+ loadfile(PANDOC_SCRIPT_FILE)()
+ return pandoc.write_classic(doc, opts)
+end
+```
diff --git a/documents/markdown/pandoc-md/doc_customizing-pandoc.md b/documents/markdown/pandoc-md/doc_customizing-pandoc.md
new file mode 100644
index 0000000..9bcc963
--- /dev/null
+++ b/documents/markdown/pandoc-md/doc_customizing-pandoc.md
@@ -0,0 +1,168 @@
+---
+author:
+- Mauro Bieg
+- John MacFarlane
+title: Customizing Pandoc
+---
+
+This document provides a quick overview over the various ways to
+customize pandoc's output, with links to fuller documentation
+and some examples.
+
+## Templates
+
+When the `-s`/`--standalone` option is used, pandoc will
+generate a standalone document rather than a fragment.
+For example, in HTML output this will include the
+`<head>` element; in LaTeX output, it will include the
+preamble.
+
+Pandoc comes with a default template for (almost) every output
+format. A template is a plain text file containing variables
+that are replaced by text generated by pandoc. For example,
+the variable `$body$` will be replaced by the document body,
+and `$title$` by the title from metadata.
+
+To look at the default template for an output format, you can do
+`pandoc -D FORMAT`, where `FORMAT` is replaced by the name of
+the format. For example `pandoc -D latex`. You can also use your
+own template instead, either by using the `--template` option
+or by putting the custom template in your user data directory
+(on Linux and macOS, `~/.pandoc/templates/`).
+
+Note that in many cases you can avoid the need for a custom
+template by including a file with the `--include-in-header`,
+`--include-before-body`, or `--include-after-body` option.
+Or you can set the corresponding template variable directly.
+
+### Template variables
+
+There are several ways to set template variables:
+
+| | [`--variable`] | [`--metadata`] | [YAML metadata] and [`--metadata-file`] |
+|:---------------|:------------------|:------------------|:----------------------------|
+| values can be… | strings and bools | strings and bools | also YAML objects and lists |
+| strings are… | inserted verbatim | escaped | interpreted as markdown |
+| accessible by filters: | no | yes | yes |
+
+
+[`--variable`]: https://pandoc.org/MANUAL.html#option--variable
+[`--metadata`]: https://pandoc.org/MANUAL.html#option--metadata
+[YAML metadata]: https://pandoc.org/MANUAL.html#extension-yaml_metadata_block
+[`--metadata-file`]: https://pandoc.org/MANUAL.html#option--metadata-file
+
+
+
+For more information, see [Templates](https://pandoc.org/MANUAL.html#templates) in
+the pandoc manual.
+
+### Example: adding structured author data to HTML
+
+TODO
+
+### Example: generating documents from YAML metadata
+
+TODO <!-- Example of generating a structured document,
+say, a table, from structured YAML metadata using
+just the control structures in pandoc's template
+language. -->
+
+## Reference docx/pptx/odt
+
+For `docx`, `pptx` or `odt` documents, things are a bit more
+complicated. Instead of a single template file, you need to
+provide a customized `reference.docx/pptx/odt`.
+See the manual for the
+[`--reference-doc`](https://pandoc.org/MANUAL.html#option--reference-doc) option.
+
+### Example: changing the font and line spacing in a Word docx
+
+TODO
+
+## Filters
+
+Templates are very powerful, but they are only a sort of scaffold to
+place your document's body text in. You cannot directly change the
+body text using the template.
+
+If you need to affect the output of the actual body text, you
+can use a pandoc filter. A filter is a small program that
+transforms the document, between the parsing and the writing phase,
+while it is still in pandoc's native format. For example,
+a filter might find all the Header elements of a document
+and capitalize their text.
+
+Pandoc's native representation of a document is an
+abstract syntax tree (AST), not unlike the HTML DOM. It is
+documented
+[here](https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html). A `Pandoc` document is a chunk of
+metadata (`Meta`) and a list of `Block`s. The `Block`s, in
+turn, are composed of other `Block`s and `Inline` elements.
+(`Block` elements are things like paragraphs, lists, headers,
+and code blocks. `Inline` elements are individual words,
+links, emphasis, and so on.) Filters operate on these
+elements. You can use `pandoc -t native` to learn about the
+AST's structure.
+
+There are two kinds of filters: JSON filters (which transform a
+JSON serialization of the pandoc AST, and may be written in any
+language that can parse and emit JSON), and Lua filters (which
+use an interface built directly into pandoc, and must be written
+in the Lua language). If you are writing your own filters, it
+is best to use Lua filters, which are more portable (they
+require only pandoc itself) and more efficient. See [Lua
+filters](https://pandoc.org/lua-filters.html) for documentation and examples. If
+you would prefer to write your filter in another language, see
+[Filters](https://pandoc.org/filters.html) for a gentle introduction to JSON
+filters.
+
+There's a repository of lua filters at
+[pandoc/lua-filters](https://github.com/pandoc/lua-filters)
+on GitHub. A number of pandoc filters, written in
+Haskell, are available on
+[Hackage](https://hackage.haskell.org/packages/search?terms=pandoc+filter)
+and can be installed using the `stack` or `cabal` tools.
+The wiki also lists [third party
+filters](https://github.com/jgm/pandoc/wiki/Pandoc-Filters).
+
+### Example: capitalizing headers
+
+TODO
+
+### Example: code extractor
+
+TODO
+
+## Generic Divs and Spans
+
+TODO
+[Divs and Spans](https://pandoc.org/MANUAL.html#divs-and-spans): generic blocks
+that can be transformed with filters
+
+### Example: colored text
+
+
+### Example: custom styles in docx
+
+[Custom Styles in Docx](https://pandoc.org/MANUAL.html#custom-styles-in-docx)
+
+## Raw attributes
+
+TODO
+[Generic raw attributes](https://pandoc.org/MANUAL.html#generic-raw-attribute):
+to include raw snippets
+
+## Custom writers
+
+TODO
+[Custom writers](https://pandoc.org/MANUAL.html#custom-writers)
+
+## Custom syntax highlighting
+
+TODO
+[Custom syntax highlighting](https://pandoc.org/MANUAL.html#syntax-highlighting),
+provided by the [skylighting
+library](https://github.com/jgm/skylighting)
+
+including highlighting styles
+
diff --git a/documents/markdown/pandoc-md/doc_epub.md b/documents/markdown/pandoc-md/doc_epub.md
new file mode 100644
index 0000000..b370b46
--- /dev/null
+++ b/documents/markdown/pandoc-md/doc_epub.md
@@ -0,0 +1,171 @@
+---
+title: Creating an ebook with pandoc
+author: John MacFarlane
+---
+
+Starting with version 1.6, pandoc can produce output in the [EPUB]
+electronic book format. EPUB books can be viewed on iPads, Nooks, and
+other electronic book readers, including many smart phones. (They can
+also be converted to Kindle books using the GUI only [KindlePreviewer]
+on Windows and Mac OSX. [KindleGen] – which offers a command line
+interface and supports [Linux][KindleGenLinux], [Mac OSX][KindleGenMacOSX]
+and [Windows][KindleGenWindows] – has been deprecated, but binaries can still
+be found on the internet.)
+
+This means that it's now very easy to produce an electronic book!
+Let's try it.
+
+# A toy example
+
+Use your text editor to create a file `mybook.txt`, with the following
+contents:
+
+ % My Book
+ % Sam Smith
+
+ This is my book!
+
+ # Chapter One
+
+ Chapter one is over.
+
+ # Chapter Two
+
+ Chapter two has just begun.
+
+To make this into an ebook takes only one command:
+
+ pandoc mybook.txt -o mybook.epub
+
+You can upload `mybook.epub` to your ebook reader and try it out.
+
+Note that if your markdown file contains links to local images, for
+example
+
+ 
+
+pandoc will automatically include the images in the generated
+epub.
+
+# A real book
+
+To see what this would look like for a real book, let's convert Scott
+Chacon's book [Pro Git], which he wrote using pandoc's markdown variant
+and released under a [Creative Commons] license. (If you use the book,
+please consider [buying a copy] to help support his excellent work.)
+
+You can find the markdown source for the book on its
+[github site]. Let's get a copy of the whole repository:[^1]
+
+ git clone https://github.com/progit/progit.git
+
+[^1]: If you don't have [git], you can browse to the [github site] and
+click "Download Source" to get the same files in a zip or tar archive.
+
+This command will create a working directory called `progit` on
+your machine. The actual markdown sources for the English version
+of the book are in the `en` subdirectory, so start by changing
+to that directory:
+
+ cd progit/en
+
+As you can see, each chapter is a single text file in its own directory.
+Chacon does some postprocessing on these files, for example, to insert images.
+This is a placeholder for Figure 1-1, for example:
+
+ Insert 18333fig0101.png
+ Figure 1-1. Local version control diagram.
+
+The actual image file is called `18333fig0101-tn.png` and lives in
+the `figures` subdirectory of the repository, as you can verify.
+
+For demonstration purposes, we want pure markdown files, so let's
+change this placeholder into a markdown image link. Pandoc will
+treat a paragraph containing a single image as a figure with
+a caption, which is what we want:
+
+ 
+
+We can make this change in all the files with a perl one-liner:
+
+ perl -i -0pe \
+ 's/^Insert\s*(.*)\.png\s*\n([^\n]*)$/!\[\2](..\/figures\/\1-tn.png)/mg' \
+ */*.markdown
+
+This will modify the files in place. (We won't worry about backing
+them up; if we mess up, we can get the original files back with
+`git reset --hard`.)
+
+OK! Now we're almost ready to make an ebook. We have the chapters,
+each in its own file, but we still need a title. Create a file,
+`title.txt`, with a pandoc YAML metadata block:
+
+```
+---
+title: Pro Git
+author: Scott Chacon
+rights: Creative Commons Non-Commercial Share Alike 3.0
+language: en-US
+...
+```
+
+See the [User's Guide](https://pandoc.org/MANUAL.html#epub-metadata) for more information
+about these fields.
+
+Now run pandoc to make the ebook, using our title page and modified
+chapter files as sources:
+
+ pandoc -o progit.epub title.txt \
+ 01-introduction/01-chapter1.markdown \
+ 02-git-basics/01-chapter2.markdown \
+ 03-git-branching/01-chapter3.markdown \
+ 04-git-server/01-chapter4.markdown \
+ 05-distributed-git/01-chapter5.markdown \
+ 06-git-tools/01-chapter6.markdown \
+ 07-customizing-git/01-chapter7.markdown \
+ 08-git-and-other-scms/01-chapter8.markdown \
+ 09-git-internals/01-chapter9.markdown
+
+That's it! The ebook, `progit.epub`, is ready to be uploaded to your reader.
+
+## Changing the format
+
+You can use the `--css` option to specify a CSS file
+for the book. The default CSS is minimal and can be found
+[on GitHub](https://github.com/jgm/pandoc/blob/main/data/epub.css)
+or in the `epub.css` file in your data directory
+(see `--data-dir` in the [User's Guide]).
+
+You can even embed fonts in the EPUB if you want; see the [User's Guide]
+under `--epub-embed-font` for instructions.
+
+## Math
+
+Pandoc has an EPUB3 writer. It renders LaTeX math into MathML, which
+EPUB3 readers are supposed to support (but unfortunately few do).
+
+Of course, this isn't much help if you want EPUB2 output (`pandoc -t epub2`)
+or target readers that don't support MathML. Then you have two options:
+
+1. Use the [`--webtex`](https://pandoc.org/MANUAL.html#option--webtex) option,
+ which will use a web service to convert the TeX to an image.
+2. Use the [`--gladtex`](https://pandoc.org/MANUAL.html#option--gladtex) option
+ to convert maths into SVG images on your local machine.
+
+Both GladTeX and WebTeX add the LaTeX source of the formula as alternative text
+of the image, increasing accessibility for blind users.
+
+[KindlePreviewer]: https://www.amazon.com/Kindle-Previewer/b?node=21381691011
+[KindleGen]: https://www.amazon.com/gp/feature.html?docId=1000765211
+[KindleGenLinux]: https://archive.org/details/kindlegen2.9
+[KindleGenMacOSX]: https://web.archive.org/web/20190905040839/https://www.amazon.com/gp/feature.html?ie=UTF8&docId=1000765211
+[KindleGenWindows]: https://archive.org/details/kindlegen_win32_v2_9
+[EPUB]: https://en.wikipedia.org/wiki/EPUB
+[Pro Git]: https://git-scm.com/book/en/v2
+[Creative Commons]: https://creativecommons.org/
+[buying a copy]: https://git-scm.com/book/en/v2
+[github site]: https://github.com/progit/progit
+[git]: https://git-scm.com
+[Dublin Core metadata elements]: https://dublincore.org/documents/dces/
+[User's Guide]: https://pandoc.org/MANUAL.html
+
diff --git a/documents/markdown/pandoc-md/doc_extras.md b/documents/markdown/pandoc-md/doc_extras.md
new file mode 100644
index 0000000..5c1df77
--- /dev/null
+++ b/documents/markdown/pandoc-md/doc_extras.md
@@ -0,0 +1,115 @@
+---
+title: Pandoc Extras
+author: John MacFarlane
+---
+
+This is a curated list of some of the most useful third-party
+software that extends pandoc's capabilities. For a more
+complete list, see the [Pandoc Extras wiki page](https://github.com/jgm/pandoc/wiki/Pandoc-Extras).
+
+
+### GUI
+
+ - [PanWriter](https://github.com/mb21/panwriter/#panwriter) is
+ a Markdown editor with live preview that can import and export
+ using pandoc.
+ - [Pandoc Mac OS X
+ Services](https://github.com/mb21/Pandoc-Mac-OS-X-Services)
+ allows you to invoke pandoc from any text editor with the
+ opened file as input.
+
+### Editor support
+
+ - [pandoc-mode](http://joostkremers.github.io/pandoc-mode) for Emacs
+ - [vim-pandoc](https://github.com/vim-pandoc) for Vim
+ - [Panache](https://panache.bz/) is a language server, formatter, and linter
+ for Pandoc markdown.
+
+### CLI wrappers
+
+ - [panzer](https://github.com/msprev/panzer) allows you to
+ specify command-line options and styles in the Markdown file's YAML
+ metadata.
+ - [pandocomatic](https://heerdebeer.org/Software/markdown/pandocomatic/)
+ is similar to panzer but also provides support for
+ converting directory trees.
+ - [panrun](https://github.com/mb21/panrun) is a more
+ minimalistic alternative to panzer and pandocomatic.
+
+### Editing/document changes
+
+ - [pandiff](https://github.com/davidar/pandiff) creates prose
+ diffs for any document format supported by pandoc.
+ - [pancritic](https://github.com/ickc/pancritic) allows using
+ [CriticMarkup](http://criticmarkup.com/spec.php#caveats) with pandoc.
+
+### Charts and data
+
+ - [R Markdown](https://rmarkdown.rstudio.com) allows you to
+ process Markdown documents with integrated data and charts
+ (integrates pandoc).
+ - [pandoc-plot](https://github.com/LaurentRDC/pandoc-plot)
+ allows you to integrate programmatically generated plots
+ generated by various tools.
+
+### Citations
+
+ - [zotxt](https://github.com/egh/zotxt) is Zotero extension
+ for working with pandoc
+
+### Numbering and cross-references
+
+ - [pandoc-crossref](https://github.com/lierdakil/pandoc-crossref)
+ is a filter that adds support for figure, table, and
+ equation numbers and cross-references.
+ - [pandoc-xnos](https://github.com/tomduck/pandoc-xnos) is
+ a suite of filters supporting numbering and
+ cross-referencing figures, equations, tables, and sections.
+
+### Academic publishing workflows
+
+ - [Quarto](https://quarto.org/) is an open-source scientific and technical publishing system
+ to make reproducible, production quality
+ articles, presentations, websites, blogs, and books.
+ It supports equations, citations, crossrefs, figure panels, callouts, advanced layout, etc.
+ - [Manubot](https://manubot.org) is a workflow and set of tools for the next
+ generation of scholarly publishing, including citation support and
+ support for multiple output formats.
+ It's especially suited for papers with a very large set of authors.
+ - [pandoc-ext](https://github.com/pandoc-ext) includes goodies such as
+ putting the Abstract into a section,
+ multiple bibliographies,
+ support the Citation Typing Ontology (CiTO), etc.
+ - [Baseprinter](https://try.perm.pub/baseprinter/) is an open-source pandoc wrapper to
+ generate Baseprint document snapshots and HTML/PDF previews.
+ These snapshots can be self-published/archived as editions of a
+ [Baseprint document succession](https://try.perm.pub/document_succession/).
+ - [Pandoc Scholar](https://github.com/pandoc-scholar/pandoc-scholar) is a
+ set of utilities to make publishing of scientific articles as simple and
+ pleasant as possible. It simplifies setting authors' metadata in
+ YAML blocks, allows to add semantic annotation to citations, and
+ only requires the programs `pandoc` and `make`.
+ Please note that it is no longer maintained and refers to `Quarto` and `pandoc-ext`
+
+### Containers
+
+ - [pandoc docker images](https://github.com/pandoc/dockerfiles)
+
+### Lua filters
+
+(For a fuller list, see [the lua-filters
+repository](https://github.com/pandoc/lua-filters).)
+
+ - [Spell
+ checking](https://github.com/pandoc/lua-filters/tree/master/spellcheck).
+ - [Word count](https://github.com/pandoc/lua-filters/tree/master/wordcount).
+ - [Embed textually-specified
+ diagrams](https://github.com/pandoc-ext/diagram) in Mermaid, Dot/GraphViz,
+ PlantUML, Asymptote, CeTZ, and TikZ.
+ - [Create subfigures in pandoc's Markdown](https://github.com/rnwst/pandoc-subfigs).
+ - [Handle scholarly
+ metadata](https://github.com/pandoc/lua-filters/tree/master/scholarly-metadata).
+ - [Panda](http://christophe.delord.free.fr/panda/) provides
+ conditionals, code file inclusion, string expansion,
+ and diagrams from code blocks.
+
diff --git a/documents/markdown/pandoc-md/doc_faqs.md b/documents/markdown/pandoc-md/doc_faqs.md
new file mode 100644
index 0000000..f756f2a
--- /dev/null
+++ b/documents/markdown/pandoc-md/doc_faqs.md
@@ -0,0 +1,230 @@
+% FAQs
+
+::: faqs
+
+## How can I convert a whole directory of files from Markdown to RTF?
+
+On linux or OSX:
+
+ for f in *.txt; do pandoc "$f" -s -o "${f%.txt}.rtf"; done
+
+
+In Windows Powershell:
+
+ gci -r -i *.txt
+ |foreach{$rtf=$_.directoryname+"\"+$_.basename+".rtf";pandoc -f markdown -s $_.fullname -o $rtf}
+
+## I used pandoc to convert a document to ICML (or OPML or RTF), and when I try to open it I'm told it's invalid. What have I done wrong?
+
+Be sure to use the `-s` or `--standalone` flag, or you just get a
+fragment, not a full document with the required header:
+
+ pandoc -s -f markdown -t icml -o my.icml my.md
+
+## I get a blank document when I try to convert a markdown document in Chinese to PDF.
+
+By default, pandoc uses pdflatex to generate the PDF, and pdflatex
+doesn't handle Chinese characters. But you can change the default to
+use xelatex instead. You should also make sure you're using a font
+with Chinese glyphs. For example:
+
+ pandoc -o c.pdf --pdf-engine=xelatex -V mainfont='Adobe Ming Std'
+
+## The Windows installer does a single user install, rather than installing pandoc for all users. How can I install pandoc for all users?
+
+Run the following command as admin:
+
+ msiexec /i pandoc-VERSION.msi ALLUSERS=1
+
+This will put pandoc in `C:\Program Files\Pandoc`.
+You can install Pandoc to a different directory by setting APPLICATIONFOLDER parameter,
+for example:
+
+ msiexec /i pandoc-1.11.1.msi ALLUSERS=1 APPLICATIONFOLDER="C:\Pandoc"
+
+## How do I change the margins in PDF output?
+
+The option
+
+ -V geometry:margin=1in
+
+will set the margins to one inch on each side. If you don't want uniform
+margins, you can do something like
+
+ -V geometry:"top=2cm, bottom=1.5cm, left=1cm, right=1cm"
+
+Or
+
+ -V geometry:"left=3cm, width=10cm"
+
+For more options, see the documentation for the LaTeX [geometry
+package](https://www.ctan.org/pkg/geometry).
+
+## How does pandoc compare to multimarkdown?
+
+Here is a [wiki
+page](https://github.com/jgm/pandoc/wiki/Pandoc-vs-Multimarkdown)
+comparing the two.
+
+## When I specify an image width of 50% and convert to LaTeX, pandoc sets the height to textheight and the aspect ratio isn't preserved. How can I prevent this?
+
+For example, if you convert an image with `{width="50%"}`, the LaTeX produced
+will be `\includegraphics[width=0.5\textwidth,height=\textheight]`.
+
+This output presupposes the following code in pandoc's default latex
+template:
+
+```
+% Scale images if necessary, so that they will not overflow the page
+% margins by default, and it is still possible to overwrite the defaults
+% using explicit options in \includegraphics[width, height, ...]{}
+\setkeys{Gin}{width=\maxwidth,height=\maxheight,keepaspectratio}
+```
+
+If you don't have this in your custom template, you should
+add it. If we didn't set the `height` explicitly in this way,
+the image would not be resized correctly unless it was
+being resized to smaller than its original size.
+
+## Pandoc sometimes uses too much memory. How can I limit the memory used by pandoc?
+
+`pandoc +RTS -M30m -RTS` will limit heap memory to 30MB.
+When converting a document requires more than this, an out of
+memory error will be issued.
+
+## When using `--include-in-header` with PDF or LaTeX output, how do I reference tex declarations coming after `$header-includes$` in the default template?
+
+For various reasons, the `$header-includes$` are not at the very
+end of the LaTeX preamble. This poses a problem when the code
+you are inserting depends on declarations in the preamble coming
+after the `$header-includes$` location. For example, you might
+want to reference the `\author` and `\title` metadata values
+(set at the very bottom of the preamble) and present them in
+margins. In that case you can wrap your code in `etoolbox`'s
+`\AtEndPreamble`. The technique is demonstrated in [this
+gist](https://gist.github.com/JohnLukeBentley/9dda6166b9ee5c4127afd2b8cd16b70a).
+When using `\AtEndPreamble`, keep any `makeatletter` or
+`makeatother` outside of the `\AtEndPreamble`, as shown in the
+example.
+
+## How can I convert PDFs to other formats using pandoc?
+
+You can't. You can try opening the PDF in Word or Google Docs
+and saving in a format from which pandoc can convert directly.
+
+## Do I really need to install a 1 GB TeX installation to produce a PDF using pandoc?
+
+No. You can get by with a relatively small TeX installation,
+for example, by starting with MacTeX's Basic TeX distribution
+and using the `tlmgr` tool to install a few packages required by pandoc
+(see [the manual](https://pandoc.org/MANUAL.html#creating-a-pdf)).
+
+Or, you can produce PDFs via HTML and `wkhtmltopdf`,
+or via groff ms and `pdfroff`. (These don't produce as nice
+typography as TeX, particularly when it comes to math, but they
+may be fine for many purposes.)
+
+
+## Converting to PDF on an M1 Mac, I get a "Cannot allocate memory" error.
+
+We are not sure why this happens, but we have found that
+fully specifying the `pdflatex` path avoids the error. For
+example,
+
+ pandoc -o my.pdf --pdf-engine=/Library/TeX/texbin/pdflatex
+
+## When I convert from ipynb, some visualizations aren't showing up.
+
+First, unless your target is a binary format (docx, odt, epub),
+you must use either `--extract-media` or (for HTML only)
+`--embed-resources` to make the images in the ipynb container
+available to your output file.
+
+Second, some Jupyter extensions, especially those that use JavaScript
+for visualizations, assume the presence of
+[`require.js`](https://github.com/requirejs/requirejs).
+To ensure that this script is available in your HTML output, you
+can use:
+
+```
+pandoc -s -o output.html input.ipynb \
+-V header-includes='<script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js"></script>'
+```
+
+## How can I get BibTeX references to work when converting from LaTeX?
+
+Use the `--citeproc` option.
+If it still doesn't work, you may need to tell pandoc where
+your bibliography file is using `--bibliography`.
+Your references may not be formatted the same as they are
+when you use `latex` and `bibtex`; you can change the format
+of the citations by specifying an appropriate CSL bibliography
+style using `--csl`
+(see [the manual](https://pandoc.org/MANUAL.html#specifying-a-citation-style)).
+
+### How can I produce PDF/A with pandoc?
+
+The simplest approach is via ConTeXt:
+
+```
+pandoc --pdf-engine=context -V pdfa
+```
+
+Alternatively, `--pdf-engine=pdflatex` can be used with
+the following in `header-includes` in metadata (or included from
+a file using `--include-in-header`):
+
+```
+\usepackage[a-2u,mathxmp]{pdfx}
+\usepackage[pdfa]{hyperref}
+```
+
+Or `--pdf-engine=lualatex` can be used with the following:
+
+```
+\usepackage{hyperxmp}
+\hypersetup{pdfapart=3,pdfaconformance=B}
+\immediate\pdfobj stream attr{/N 3} file{sRGB.icc}
+\pdfcatalog{/OutputIntents [<<
+/Type /OutputIntent /S /GTS_PDFA1
+/DestOutputProfile \the\pdflastobj\space 0 R
+/OutputConditionIdentifier (sRGB) /Info (sRGB)
+>>]}
+```
+
+
+### Pandoc adds column widths to pipe tables when any line is wider than the setting for `--columns`. How can I prevent this?
+
+Save this filter as `nowidths.lua` and then pass `--lua-filter
+nowidths.lua` as an additional option to pandoc.
+(See [issue 8139](https://github.com/jgm/pandoc/issues/8139).)
+
+``` lua
+-- Unset the width attribute of HTML colspecs in tables
+-- See https://github.com/jgm/pandoc/issues/8139
+function Table (tbl)
+ if PANDOC_VERSION[1] >= 2 and PANDOC_VERSION[2] >= 10 then
+ tbl.colspecs = tbl.colspecs:map(function (colspec)
+ local align = colspec[1]
+ local width = nil -- default width
+ return {align, width}
+ end)
+ else
+ for i, w in ipairs(tbl.widths) do
+ tbl.widths[i] = 0
+ end
+ end
+ return tbl
+end
+```
+
+### How can I use pandoc to read Word files in the old .DOC format?
+
+Install `antiword` and use it to convert the doc to DocBook,
+which can be read by pandoc.
+
+```
+antiword -x db input.doc | pandoc -f docbook
+```
+
+:::
diff --git a/documents/markdown/pandoc-md/doc_filters.md b/documents/markdown/pandoc-md/doc_filters.md
new file mode 100644
index 0000000..4da5bb8
--- /dev/null
+++ b/documents/markdown/pandoc-md/doc_filters.md
@@ -0,0 +1,512 @@
+% Pandoc filters
+% John MacFarlane
+
+# Summary
+
+Pandoc provides an interface for users to write programs (known
+as filters) which act on pandoc’s AST.
+
+Pandoc consists of a set of readers and writers. When converting
+a document from one format to another, text is parsed by a
+reader into pandoc’s intermediate representation of the
+document---an "abstract syntax tree" or AST---which is then
+converted by the writer into the target format.
+The pandoc AST format is defined in the module
+[`Text.Pandoc.Definition` in the `pandoc-types` package
+](https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html).
+
+A "filter" is a program that modifies the AST, between the
+reader and the writer.
+
+ INPUT --reader--> AST --filter--> AST --writer--> OUTPUT
+
+Pandoc supports two kinds of filters:
+
+- **Lua filters** use the Lua language to
+ define transformations on the pandoc AST. They are
+ described in a [separate document](lua-filters.html).
+
+- **JSON filters**, described here, are pipes that read from
+ standard input and write to standard output, consuming and
+ producing a JSON representation of the pandoc AST:
+
+ source format
+ ↓
+ (pandoc)
+ ↓
+ JSON-formatted AST
+ ↓
+ (JSON filter)
+ ↓
+ JSON-formatted AST
+ ↓
+ (pandoc)
+ ↓
+ target format
+
+Lua filters have a couple of advantages. They use a Lua
+interpreter that is embedded in pandoc, so you don't need
+to have any external software installed. And they are
+usually faster than JSON filters. But if you wish to
+write your filter in a language other than Lua, you may
+prefer to use a JSON filter. JSON filters may be written
+in any programming language.
+
+You can use a JSON filter directly in a pipeline:
+
+ pandoc -s input.txt -t json | \
+ pandoc-citeproc | \
+ pandoc -s -f json -o output.html
+
+But it is more convenient to use the `--filter` option,
+which handles the plumbing automatically:
+
+ pandoc -s input.txt --filter pandoc-citeproc -o output.html
+
+For a gentle introduction into writing your own filters,
+continue this guide. There’s also a [list of third party filters
+on the wiki](https://github.com/jgm/pandoc/wiki/Pandoc-Filters).
+
+
+# A simple example
+
+Suppose you wanted to replace all level 2+ headings in a markdown
+document with regular paragraphs, with text in italics. How would you go
+about doing this?
+
+A first thought would be to use regular expressions. Something
+like this:
+
+ perl -pe 's/^##+ (.*)$/\*\1\*/' source.txt
+
+This should work most of the time. But don't forget
+that ATX style headings can end with a sequence of `#`s
+that is not part of the heading text:
+
+ ## My heading ##
+
+And what if your document contains a line starting with `##` in an HTML
+comment or delimited code block?
+
+ <!--
+ ## This is just a comment
+ -->
+
+ ~~~~
+ ### A third level heading in standard markdown
+ ~~~~
+
+We don't want to touch *these* lines. Moreover, what about Setext
+style second-level heading?
+
+ A heading
+ ---------
+
+We need to handle those too. Finally, can we be sure that adding
+asterisks to each side of our string will put it in italics?
+What if the string already contains asterisks around it? Then we'll
+end up with bold text, which is not what we want. And what if it contains
+a regular unescaped asterisk?
+
+How would you modify your regular expression to handle these cases? It
+would be hairy, to say the least.
+
+A better approach is to let pandoc handle the parsing, and
+then modify the AST before the document is written. For this,
+we can use a filter.
+
+To see what sort of AST is produced when pandoc parses our text,
+we can use pandoc's `native` output format:
+
+~~~~
+% cat test.txt
+## my heading
+
+text with *italics*
+% pandoc -s -t native test.txt
+Pandoc (Meta {unMeta = fromList []})
+[Header 2 ("my-heading",[],[]) [Str "My",Space,Str "heading"]
+, Para [Str "text",Space,Str "with",Space,Emph [Str "italics"]] ]
+~~~~
+
+A `Pandoc` document consists of a `Meta` block (containing
+metadata like title, authors, and date) and a list of `Block`
+ elements. In this case, we have two `Block`s, a `Header` and a `Para`.
+Each has as its content a list of `Inline` elements. For more details on
+the pandoc AST, see the [haddock documentation for `Text.Pandoc.Definition`].
+
+[haddock documentation for `Text.Pandoc.Definition`]: https://hackage.haskell.org/package/pandoc-types
+
+We can use Haskell to create a JSON filter that transforms this
+AST, replacing each `Header` block with level >= 2 with a `Para`
+with its contents wrapped inside an `Emph` inline:
+
+~~~~ {.haskell}
+#!/usr/bin/env runhaskell
+-- behead.hs
+import Text.Pandoc.JSON
+
+main :: IO ()
+main = toJSONFilter behead
+
+behead :: Block -> Block
+behead (Header n _ xs) | n >= 2 = Para [Emph xs]
+behead x = x
+~~~~
+
+The `toJSONFilter` function does two things. First, it lifts
+the `behead` function (which maps `Block -> Block`) onto a
+transformation of the entire `Pandoc` AST, walking the AST
+and transforming each block. Second, it wraps this `Pandoc ->
+Pandoc` transformation with the necessary JSON serialization
+and deserialization, producing an executable that consumes
+JSON from stdin and produces JSON to stdout.
+
+To use the filter, make it executable:
+
+ chmod +x behead.hs
+
+and then
+
+ pandoc -f SOURCEFORMAT -t TARGETFORMAT --filter ./behead.hs
+
+(It is also necessary that `pandoc-types` be installed in the
+local package repository. To do this using cabal-install,
+`cabal v2-update && cabal v2-install --lib pandoc-types --package-env .`.)
+
+Alternatively, we could compile the filter:
+
+ ghc -package-env=default --make behead.hs
+ pandoc -f SOURCEFORMAT -t TARGETFORMAT --filter ./behead
+
+Note that if the filter is placed in the system PATH, then the initial
+`./` is not needed. Note also that the command line can include
+multiple instances of `--filter`: the filters will be applied in
+sequence.
+
+
+# LaTeX for WordPress
+
+Another easy example. WordPress blogs require a special format for
+LaTeX math. Instead of `$e=mc^2$`, you need: `$LaTeX e=mc^2$`.
+How can we convert a markdown document accordingly?
+
+Again, it's difficult to do the job reliably with regexes.
+A `$` might be a regular currency indicator, or it might occur in
+a comment or code block or inline code span. We just want to find
+the `$`s that begin LaTeX math. If only we had a parser...
+
+We do. Pandoc already extracts LaTeX math, so:
+
+~~~~ {.haskell}
+#!/usr/bin/env runhaskell
+-- wordpressify.hs
+import Text.Pandoc.JSON
+
+main = toJSONFilter wordpressify
+ where wordpressify (Math x y) = Math x ("LaTeX " ++ y)
+ wordpressify x = x
+~~~~
+
+Mission accomplished. (I've omitted type signatures here,
+just to show it can be done.)
+
+
+# But I don't want to learn Haskell!
+
+While it's easiest to write pandoc filters in Haskell, it is fairly
+easy to write them in python using the `pandocfilters` package.
+The package is in PyPI and can be installed using `pip install
+pandocfilters` or `easy_install pandocfilters`.
+
+Here's our "beheading" filter in python:
+
+~~~ {.python}
+#!/usr/bin/env python
+
+"""
+Pandoc filter to convert all level 2+ headings to paragraphs with
+emphasized text.
+"""
+
+from pandocfilters import toJSONFilter, Emph, Para
+
+def behead(key, value, format, meta):
+ if key == 'Header' and value[0] >= 2:
+ return Para([Emph(value[2])])
+
+if __name__ == "__main__":
+ toJSONFilter(behead)
+~~~
+
+`toJSONFilter(behead)` walks the AST and applies the `behead` action
+to each element. If `behead` returns nothing, the node is unchanged;
+if it returns an object, the node is replaced; if it returns a list,
+the new list is spliced in.
+
+Note that, although these parameters are not used in this example,
+`format` provides access to the target format, and `meta` provides access to
+the document's metadata.
+
+There are many examples of python filters in [the pandocfilters
+repository](https://github.com/jgm/pandocfilters).
+
+For a more Pythonic alternative to pandocfilters, see
+the [panflute](https://pypi.org/project/panflute) library.
+Don't like Python? There are also ports of pandocfilters in
+
+- [PHP](https://github.com/vinai/pandocfilters-php),
+- [perl](https://metacpan.org/pod/Pandoc::Filter),
+- TypeScript/JavaScript via Node.js
+ - [pandoc-filter](https://github.com/mvhenderson/pandoc-filter-node),
+ - [node-pandoc-filter](https://github.com/mu-io/node-pandoc-filter),
+- [Groovy](https://github.com/dfrommi/groovy-pandoc), and
+- [Ruby](https://heerdebeer.org/Software/markdown/paru/).
+
+Starting with pandoc 2.0, pandoc includes built-in support for
+writing filters in lua. The lua interpreter is built in to
+pandoc, so a lua filter does not require any additional software
+to run. See the [documentation on lua
+filters](https://pandoc.org/lua-filters.html).
+
+# Include files
+
+So none of our transforms have involved IO. How about a script that
+reads a markdown document, finds all the inline code blocks with
+attribute `include`, and replaces their contents with the contents of
+the file given?
+
+~~~~ {.haskell}
+#!/usr/bin/env runhaskell
+-- includes.hs
+import Text.Pandoc.JSON
+import qualified Data.Text.IO as TIO
+import qualified Data.Text as T
+
+doInclude :: Block -> IO Block
+doInclude cb@(CodeBlock (id, classes, namevals) contents) =
+ case lookup (T.pack "include") namevals of
+ Just f -> CodeBlock (id, classes, namevals) <$>
+ TIO.readFile (T.unpack f)
+ Nothing -> return cb
+doInclude x = return x
+
+main :: IO ()
+main = toJSONFilter doInclude
+~~~~
+
+Try this on the following:
+
+ Here's the pandoc README:
+
+ ~~~~ {include="README"}
+ this will be replaced by contents of README
+ ~~~~
+
+# Removing links
+
+What if we want to remove every link from a document, retaining
+the link's text?
+
+~~~~ {.haskell}
+#!/usr/bin/env runhaskell
+-- delink.hs
+import Text.Pandoc.JSON
+
+main = toJSONFilter delink
+
+delink :: Inline -> [Inline]
+delink (Link _ txt _) = txt
+delink x = [x]
+~~~~
+
+Note that `delink` can't be a function of type `Inline -> Inline`,
+because the thing we want to replace the link with is not a single
+`Inline` element, but a list of them. So we make `delink` a function
+from an `Inline` element to a list of `Inline` elements.
+`toJSONFilter` can still lift this function to a transformation of type
+`Pandoc -> Pandoc`.
+
+# A filter for ruby text
+
+Finally, here's a nice real-world example, developed on the
+[pandoc-discuss](https://groups.google.com/group/pandoc-discuss/browse_thread/thread/7baea325565878c8) list. Qubyte wrote:
+
+> I'm interested in using pandoc to turn my markdown notes on Japanese
+> into nicely set HTML and (Xe)LaTeX. With HTML5, ruby (typically used to
+> phonetically read chinese characters by placing text above or to the
+> side) is standard, and support from browsers is emerging (Webkit based
+> browsers appear to fully support it). For those browsers that don't
+> support it yet (notably Firefox) the feature falls back in a nice way
+> by placing the phonetic reading inside brackets to the side of each
+> Chinese character, which is suitable for other output formats too. As
+> for (Xe)LaTeX, ruby is not an issue.
+>
+> At the moment, I use inline HTML to achieve the result when the
+> conversion is to HTML, but it's ugly and uses a lot of keystrokes, for
+> example
+>
+> ~~~ {.xml}
+> <ruby>ご<rt></rt>飯<rp>（</rp><rt>はん</rt><rp>）</rp></ruby>
+> ~~~
+>
+> sets ご飯 "gohan" with "han" spelt phonetically above the second
+> character, or to the right of it in brackets if the browser does not
+> support ruby. I'd like to have something more like
+>
+> r[はん](飯)
+>
+> or any keystroke saving convention would be welcome.
+
+We came up with the following script, which uses the convention that a
+markdown link with a URL beginning with a hyphen is interpreted as ruby:
+
+ [はん](-飯)
+
+~~~ {.haskell}
+{-# LANGUAGE OverloadedStrings #-}
+-- handleruby.hs
+import Text.Pandoc.JSON
+import System.Environment (getArgs)
+import qualified Data.Text as T
+
+handleRuby :: Maybe Format -> Inline -> Inline
+handleRuby (Just format) x@(Link attr [Str ruby] (src,_)) =
+ case T.uncons src of
+ Just ('-',kanji)
+ | format == Format "html" -> RawInline format $
+ "<ruby>" <> kanji <> "<rp>(</rp><rt>" <> ruby <>
+ "</rt><rp>)</rp></ruby>"
+ | format == Format "latex" -> RawInline format $
+ "\\ruby{" <> kanji <> "}{" <> ruby <> "}"
+ | otherwise -> Str ruby
+ _ -> x
+handleRuby _ x = x
+
+main :: IO ()
+main = toJSONFilter handleRuby
+~~~
+
+Note that, when a script is called using `--filter`, pandoc passes
+it the target format as the first argument. When a function's
+first argument is of type `Maybe Format`, `toJSONFilter` will
+automatically assign it `Just` the target format or `Nothing`.
+
+We compile our script:
+
+ # first, make sure pandoc-types is installed:
+ cabal install --lib pandoc-types --package-env .
+ ghc --make handleRuby
+
+Then run it:
+
+ % pandoc -F ./handleRuby -t html
+ [はん](-飯)
+ ^D
+ <p><ruby>飯<rp>(</rp><rt>はん</rt><rp>)</rp></ruby></p>
+ % pandoc -F ./handleRuby -t latex
+ [はん](-飯)
+ ^D
+ \ruby{飯}{はん}
+
+Note: to use this to generate PDFs via LaTeX, you'll need
+to use `--pdf-engine=xelatex`, specify a `mainfont` that has
+the Japanese characters (e.g. "[Noto Sans CJK JP](https://fonts.google.com/noto/specimen/Noto+Sans+JP)"), and add
+`\usepackage{ruby}` to your template or header-includes.
+
+# Exercises
+
+1. Put all the regular text in a markdown document in ALL CAPS
+ (without touching text in URLs or link titles).
+
+2. Remove all horizontal rules from a document.
+
+3. Renumber all enumerated lists with roman numerals.
+
+4. Replace each delimited code block with class `dot` with an
+ image generated by running `dot -Tpng` (from graphviz) on the
+ contents of the code block.
+
+5. Find all code blocks with class `python` and run them
+ using the python interpreter, printing the results to the console.
+
+# Technical details of JSON filters
+
+A JSON filter is any program which can consume and produce a
+valid pandoc JSON document representation. This section describes
+the technical details surrounding the invocation of filters.
+
+## Arguments
+
+The program will always be called with the target format as the
+only argument. A pandoc invocation like
+
+ pandoc --filter demo --to=html
+
+will cause pandoc to call the program `demo` with argument `html`.
+
+## Environment variables
+
+Pandoc sets additional environment variables before calling a
+filter.
+
+`PANDOC_VERSION`
+: The version of the pandoc binary used to process the document.
+ Example: `2.11.1`.
+
+`PANDOC_READER_OPTIONS`
+: JSON object representation of the options passed to the input
+ parser.
+
+ Object fields:
+
+ `abbreviations`
+ : set of known abbreviations (array of strings).
+
+ `columns`
+ : number of columns in terminal; an integer.
+
+ `default-image-extension`
+ : default extension for images; a string.
+
+ `extensions`
+ : integer representation of the syntax extensions bit
+ field.
+
+ `indented-code-classes`
+ : default classes for indented code blocks; array of
+ strings.
+
+ `standalone`
+ : whether the input was a standalone document with header;
+ either `true` or `false`.
+
+ `strip-comments`
+ : HTML comments are stripped instead of parsed as raw HTML;
+ either `true` or `false`.
+
+ `tab-stop`
+ : width (i.e. equivalent number of spaces) of tab stops;
+ integer.
+
+ `track-changes`
+ : track changes setting for docx; one of
+ `"accept-changes"`, `"reject-changes"`, and
+ `"all-changes"`.
+
+## Supported interpreters
+
+Files passed to the `--filter`/`-F` parameter are expected to be
+executable. However, if the executable bit is not set, then
+pandoc tries to guess a suitable interpreter from the file
+extension.
+
+ file extension interpreter
+ ---------------- --------------
+ .py `python`
+ .hs `runhaskell`
+ .pl `perl`
+ .rb `ruby`
+ .php `php`
+ .js `node`
+ .r `Rscript`
diff --git a/documents/markdown/pandoc-md/doc_getting-started.md b/documents/markdown/pandoc-md/doc_getting-started.md
new file mode 100644
index 0000000..6c21721
--- /dev/null
+++ b/documents/markdown/pandoc-md/doc_getting-started.md
@@ -0,0 +1,319 @@
+---
+title: Getting started with pandoc
+author: John MacFarlane
+---
+
+This document is for people who are unfamiliar with command line
+tools. Command-line experts can go straight to the [User's
+Guide](https://pandoc.org/MANUAL.html) or the pandoc man page.
+
+# Step 1: Install pandoc
+
+First, install pandoc, following the [instructions for
+your platform](https://pandoc.org/installing.html).
+
+# Step 2: Open a terminal
+
+Pandoc is a command-line tool. There is no graphic user interface.
+So, to use it, you'll need to open a terminal window:
+
+- On OS X, the Terminal application can be found in
+ `/Applications/Utilities`. Open a Finder window and go to
+ `Applications`, then `Utilities`. Then double click on
+ `Terminal`. (Or, click the spotlight icon in the upper right
+ hand corner of your screen and type `Terminal` -- you should
+ see `Terminal` under `Applications`.)
+
+- On Windows, you can use either the classic command prompt or the
+ more modern PowerShell terminal. If you use Windows in desktop
+ mode, run the `cmd` or `powershell` command from the Start menu.
+ If you use the Windows 8 start screen instead, simply type
+ `cmd` or `powershell`, and then run either the "Command
+ Prompt" or "Windows Powershell" application. If you are using
+ `cmd`, type `chcp 65001` before using pandoc, to set the
+ encoding to UTF-8.
+
+- On Linux, there are many possible configurations, depending on
+ what desktop environment you're using:
+
+ * In Unity, use the search function on the `Dash`, and search
+ for `Terminal`. Or, use the keyboard shortcut `Ctrl-Alt-T`.
+ * In Gnome, go to `Applications`, then `Accessories`, and
+ select `Terminal`, or use `Ctrl-Alt-T`.
+ * In XFCE, go to `Applications`, then `System`, then `Terminal`,
+ or use `Super-T`.
+ * In KDE, go to `KMenu`, then `System`, then `Terminal Program (Konsole)`.
+
+You should now see a rectangle with a "prompt" (possibly just a symbol
+like `%`, but probably including more information, such as your
+username and directory), and a blinking cursor.
+
+Let's verify that pandoc is installed. Type
+
+ pandoc --version
+
+and hit enter. You should see a message telling you which version
+of pandoc is installed, and giving you some additional information.
+
+# Step 3: Changing directories
+
+First, let's see where we are. Type
+
+ pwd
+
+on Linux or OSX, or
+
+ echo %cd%
+
+on Windows, and hit enter. Your terminal should print your current
+working directory. (Guess what `pwd` stands for?) This should be your
+home directory.
+
+Let's navigate now to our `Documents` directory: type
+
+ cd Documents
+
+and hit enter. Now type
+
+ pwd
+
+(or `echo %cd%` on Windows)
+again. You should be in the `Documents` subdirectory of your home
+directory. To go back to your home directory, you could type
+
+ cd ..
+
+The `..` means "one level up."
+
+Go back to your `Documents` directory if you're not there already.
+Let's try creating a subdirectory called `pandoc-test`:
+
+ mkdir pandoc-test
+
+Now change to the `pandoc-test` directory:
+
+ cd pandoc-test
+
+If the prompt doesn't tell you what directory you're in, you can
+confirm that you're there by doing
+
+ pwd
+
+(or `echo %cd%`) again.
+
+OK, that's all you need to know for now about using the terminal.
+But here's a secret that will save you a lot of typing. You can
+always type the up-arrow key to go back through your history
+of commands. So if you want to use a command you typed earlier,
+you don't need to type it again: just use up-arrow until it comes
+up. Try this. (You can use down-arrow as well, to go the other
+direction.) Once you have the command, you can also use the
+left and right arrows and the backspace/delete key to edit it.
+
+Most terminals also support tab completion of directories and
+filenames. To try this, let's first go back up to our `Documents`
+directory:
+
+ cd ..
+
+Now, type
+
+ cd pandoc-
+
+and hit the tab key instead of enter. Your terminal should fill
+in the rest (`test`), and then you can hit enter.
+
+To review:
+
+ - `pwd` (or `echo %cd%` on Windows)
+ to see what the current working directory is.
+ - `cd foo` to change to the `foo` subdirectory of your working
+ directory.
+ - `cd ..` to move up to the parent of the working directory.
+ - `mkdir foo` to create a subdirectory called `foo` in the
+ working directory.
+ - up-arrow to go back through your command history.
+ - tab to complete directories and file names.
+
+# Step 4: Using pandoc as a filter
+
+Type
+
+ pandoc
+
+and hit enter. You should see the cursor just sitting there, waiting
+for you to type something. Type this:
+
+ Hello *pandoc*!
+
+ - one
+ - two
+
+When you're finished (the cursor should be at the beginning of the line),
+type `Ctrl-D` on OS X or Linux, or `Ctrl-Z` followed
+by `Enter` on Windows. You should now see your text converted to HTML!
+
+ <p>Hello <em>pandoc</em>!</p>
+ <ul>
+ <li>one</li>
+ <li>two</li>
+ </ul>
+
+What just happened? When pandoc is invoked without specifying any
+input files, it operates as a "filter," taking input from the
+terminal and sending its output back to the terminal. You can use
+this feature to play around with pandoc.
+
+By default, input is interpreted as pandoc markdown, and output is
+HTML. But we can change that. Let's try converting *from* HTML
+*to* markdown:
+
+ pandoc -f html -t markdown
+
+Now type:
+
+ <p>Hello <em>pandoc</em>!</p>
+
+and hit `Ctrl-D` (or `Ctrl-Z` followed by `Enter` on Windows).
+You should see:
+
+ Hello *pandoc*!
+
+Now try converting something from markdown to LaTeX. What command
+do you think you should use?
+
+# Step 5: Text editor basics
+
+You'll probably want to use pandoc to convert a file, not to read
+text from the terminal. That's easy, but first we need to create
+a text file in our `pandoc-test` subdirectory.
+
+**Important:** To create a text file, you'll need to use a text
+editor, *not* a word processor like Microsoft Word. On Windows, you
+can use Notepad (in `Accessories`). On OS X, you can use
+`TextEdit` (in `Applications`). On Linux, different platforms come
+with different text editors: Gnome has `GEdit`, and KDE has `Kate`.
+
+Start up your text editor. Type the following:
+
+ ---
+ title: Test
+ ...
+
+ # Test!
+
+ This is a test of *pandoc*.
+
+ - list one
+ - list two
+
+Now save your file as `test1.md` in the directory
+`Documents/pandoc-test`.
+
+Note: If you use plain text a lot, you'll want a better editor than
+`Notepad` or `TextEdit`. You might want to look at
+[Visual Studio Code](https://code.visualstudio.com/) or
+[Sublime Text](https://www.sublimetext.com/) or (if you're willing
+to put in some time learning an unfamiliar interface)
+[Vim](https://www.vim.org) or [Emacs](https://www.gnu.org/software/emacs).
+
+# Step 6: Converting a file
+
+Go back to your terminal. We should still be in the
+`Documents/pandoc-test` directory. Verify that with `pwd`.
+
+Now type
+
+ ls
+
+(or `dir` if you're on Windows).
+This will list the files in the current directory. You should see
+the file you created, `test1.md`.
+
+To convert it to HTML, use this command:
+
+ pandoc test1.md -f markdown -t html -s -o test1.html
+
+The filename `test1.md` tells pandoc which file to convert.
+The `-s` option says to create a "standalone" file, with a header
+and footer, not just a fragment. And the `-o test1.html` says
+to put the output in the file `test1.html`. Note that we could
+have omitted `-f markdown` and `-t html`, since the default
+is to convert from markdown to HTML, but it doesn't hurt to
+include them.
+
+Check that the file was created by typing `ls` again. You
+should see `test1.html`. Now open this in a browser. On OS X,
+you can type
+
+ open test1.html
+
+On Windows, type
+
+ .\test1.html
+
+You should see a browser window with your document.
+
+To create a LaTeX document, you just need to change the command
+slightly:
+
+ pandoc test1.md -f markdown -t latex -s -o test1.tex
+
+Try opening `test1.tex` in your text editor.
+
+Pandoc can often figure out the input and output formats from
+the filename extensions. So, you could have just used:
+
+ pandoc test1.md -s -o test1.tex
+
+Pandoc knows you're trying to create a LaTeX document, because of the
+`.tex` extension.
+
+Now try creating a Word document (with extension `docx`).
+
+If you want to create a PDF, you'll need to have LaTeX installed.
+(See [MacTeX](https://tug.org/mactex/) on OS X,
+[MiKTeX](https://miktex.org) on Windows, or install the texlive
+package on Linux.) Then do
+
+ pandoc test1.md -s -o test1.pdf
+
+# Step 7: Command-line options
+
+You now know the basics. Pandoc has a lot of options. At this point
+you can start to learn more about them by reading the
+[User's Guide](https://pandoc.org/MANUAL.html).
+
+Here's an example. The `--mathml` option causes pandoc to
+convert TeX math into MathML. Type
+
+ pandoc --mathml
+
+then enter this text, followed by `Ctrl-D` (`Ctrl-Z` followed by
+`Enter` on Windows):
+
+ $x = y^2$
+
+Now try the same thing without `--mathml`. See the difference
+in output?
+
+If you forget an option, or forget which formats are supported, you
+can always do
+
+ pandoc --help
+
+to get a list of all the supported options.
+
+On OS X or Linux systems, you can also do
+
+ man pandoc
+
+to get the pandoc manual page. All of this information is also
+in the User's Guide.
+
+If you get stuck, you can always ask questions on the
+[discussion forum](https://github.com/jgm/pandoc/discussions).
+But be sure to check the [FAQs](https://pandoc.org/faqs.html) first,
+and search through the forum to see if your question has
+been answered before.
+
diff --git a/documents/markdown/pandoc-md/doc_jats.md b/documents/markdown/pandoc-md/doc_jats.md
new file mode 100644
index 0000000..a723ccc
--- /dev/null
+++ b/documents/markdown/pandoc-md/doc_jats.md
@@ -0,0 +1,566 @@
+---
+title: JATS
+author: Albert Krewinkel
+---
+
+This document describes pandoc's handling of [JATS].
+
+Metadata Values
+===============
+
+`abstract`
+: Article summary. Added via the document's front matter via the
+ [`<abstract>`][elem:abstract] element.
+
+`author`
+: list of article contributors. Each author should have a surname
+ and a given name listed in the entry; if the author has no
+ `surname` value, then the item will be used as the contributors
+ [`string-name`][elem:string-name].
+
+ `orcid`
+ : the contributor's ORCID identifier.
+
+ `surname`
+ : surname of the contributor. Usually the family name in
+ western names.
+
+ See [`<surname>`][elem:surname].
+
+ `given-names`
+ : personal names of the contributor; this includes middle
+ names (if any) in western-style names.
+
+ See [`<given-names>`][elem:given-names].
+
+ `name`
+ : full name of the author; included only as a fallback if
+ `author.surname` is not available. Tagged with
+ [`<string-name>`][elem:string-name].
+
+ `email`
+ : the contributor's email address.
+
+ Used as the contents of the [`<email>`][elem:given-names]
+ element.
+
+ `affiliation`
+ : either full affiliation entries as described in field
+ `affiliation`, or a list of affiliation identifiers.
+
+ The identifiers link to the organizations with which an
+ author is affiliated. Each identifier in this list must
+ also occur as the `id` of an affiliation listed in the
+ top-level `affiliation` list.
+
+ If the top-level `affiliation` field is set, then this
+ entry assumed to be a list of identifiers, and a list of
+ full entries if that field is unset.
+
+ Full entries must be given if the articleauthoring tag
+ set it used, as affiliation links are not allowed in that
+ schema.
+
+ `roles`
+ : a list of dictionaries describing the author's role(s).
+ Each role is added as an [`<role>`] element to
+ the author's [`<contrib>`] element. The following examples
+ illustrate:
+
+ An ad-hoc role:
+
+ ```yaml
+ roles:
+ - name: Dolphin Catcher
+ ```
+
+ A role specified with CRediT.
+
+ ```yaml
+ roles:
+ - credit: writing-review-editing
+ ```
+
+ The `credit-name` is automatically looked up from
+ the CRediT taxonomy, but you can also specify it
+ yourself:
+
+ ```yaml
+ roles:
+ - credit: writing-review-editing
+ credit-name: Writing – review & editing
+ ```
+
+ A role specified with CRediT, including an
+ optional degree of contribution. Note that
+ specifying the degree only is allowed when
+ using CRediT roles and not ad-hoc roles.
+
+ ```yaml
+ roles:
+ - credit: writing-review-editing
+ degree: Lead
+ ```
+
+ A role specified with CRediT with a label override,
+ useful for internationalization:
+
+ ```yaml
+ roles:
+ - credit: writing-review-editing
+ name: Escrita – revisão e edição
+ ```
+
+ The value for `credit` and `credit-name`
+ must be from one of the 14 terms from the
+ Contribution Role Taxonomy (CRediT):
+
+ | `credit` | `credit-name` |
+ |--------------------------|----------------------------|
+ | `conceptualization` | Conceptualization |
+ | `data-curation` | Data curation |
+ | `formal-analysis` | Formal analysis |
+ | `funding-acquisition` | Funding acquisition |
+ | `investigation` | Investigation |
+ | `methodology` | Methodology |
+ | `project-administration` | Project administration |
+ | `resources` | Resources |
+ | `software` | Software |
+ | `supervision` | Supervision |
+ | `validation` | Validation |
+ | `visualization` | Visualization |
+ | `writing-original-draft` | Writing – original draft |
+ | `writing-review-editing` | Writing – review & editing |
+
+ JATS suggests in [`<degree-contribution>`] to use one of
+ the following three values when specifying the degree of
+ contribution:
+
+ 1. `Lead`
+ 2. `Equal`
+ 3. `Supporting`
+
+ `equal-contrib`
+ : boolean attribute used to mark authors who contributed
+ equally to the work. The
+ [`equal-contrib`][attr:equal-contrib] attribute, set to
+ `yes`, is added to the author's [`<contrib>`] element if
+ this is set to a truthy value.
+
+ `cor-id`
+ : identifier linking to the contributor's correspondence
+ information. The info itself must be stored as an item in
+ `article.author-notes.corresp`. If the `cor-id` value is
+ set, then an [`<xref>`][elem:xref] link of
+ [`ref-type`][attr:ref-type] `corresp` is added. The
+ [`rid`][attr:rid] attribute is set to `cor-<ID>`, where
+ `<ID>` is the stringified value of this attribute.
+
+ Furthermore, the [`corresp`][attr:corresp] attribute on
+ the author's [`<contrib>`] element is set to `yes` if
+ this attribute is set to a truthy.
+
+`affiliation`
+: the list of organizations with which contributors are
+ affiliated. Each institution is added as an [`<aff>`] element to
+ the author's contrib-group.
+
+ The fields are given in the order in which they are included in
+ the output.
+
+ `id`
+ : internal identifier; used as the [`<aff>`] element's `id`
+ value, prefixed with `aff-`.
+
+ `group`
+ : name of the research group or other low-level organizational
+ structure; used as value of an [`<institution>`] element with
+ [`content-type`][attr:content-type] set to `group`.
+
+ `department`
+ : name of the department or other mid-level organizational
+ structure; used as value of an [`<institution>`] element with
+ [`content-type`][attr:content-type] set to `dept`.
+
+ `organization`
+ : name of the company, university, or other top-level
+ organizational structure; used as value of an
+ [`<institution>`] element. The institution element is wrapped
+ in an [`<institution-wrap>`] element; any identifiers, like
+ `ringgold` or `ror`, are added to the wrapper and must hence
+ belong to this organization (not the department or group).
+
+ `isni`
+ : International Standard Name Identifier of the organization.
+ Added via an [`<institution-id>`] element with
+ [`institution-id-type`](attr:institution-id-type) set to
+ `ISNI`.
+
+ `ringgold`
+ : [Ringgold] identifier of the organization. Added via an
+ [`<institution-id>`] element with
+ [`institution-id-type`](attr:institution-id-type) set to
+ `Ringgold`.
+
+ `ror`
+ : Research Organization Registry identifier of the
+ organization. Added via an [`<institution-id>`] element with
+ [`institution-id-type`](attr:institution-id-type) set to
+ `ROR`.
+
+ `pid`
+ : Array of persistent identifiers which are added as
+ [`<institution-id>`] elements. Each item must contain a map
+ with keys `type`, used as
+ [`institution-id-type`](attr:institution-id-type), and `id`,
+ used as element content.
+
+ `street-address`
+ : The organization's street address; each list item is wrapped
+ in an [`<addr-line>`] element, separated by a comma and
+ space (`, `).
+
+ `city`
+ : City in which the organization is located; used only if
+ `street-address` is not given, in which case the value is
+ wrapped in a [`<city>`] element.
+
+ `country`
+ : Country in which the organization is located; used as the
+ value of a [`<country>`] element.
+
+ `country-code`
+ : Two letter ISO-3166-1 country identifier; used as the
+ [`country`][attr:country] attribute in element [`<country>`]
+ (if the latter is present).
+
+`copyright`
+: Copyright and licensing information. This information is
+ rendered via the [`<permissions>`][elem:permissions] element.
+
+ It is recommended to use the `license` field (described below)
+ for licensing information. If licensing information is
+ included below `copyright`, then the variables `type`, `link`,
+ and `text` should always be used together.
+
+ `statement`
+ : copyright notice or statement; used as content of the
+ [`<copyright-statement>`][elem:copyright-statement]. Use a
+ list for multiple statements.
+
+ `year`
+ : the year of copyright; used as content of the
+ [`<copyright-year>`][elem:copyright-year]. Use a list to
+ for multiple copyright years. The JATS documentation
+ states that this field need not to be used if the year is
+ included in the copyright statement.
+
+ `holder`
+ : the copyright holder; included via the
+ [`<copyright-holder>`][elem:copyright-holder] element. Use
+ a list for multiple copyright holders.
+
+ `text`
+ : inline text setting the license under which the text is
+ published; included via the
+ [`<license-p>`][elem:copyright-holder] element.
+
+ `type`
+ : type of the license; used as value of the
+ [`license-type`][attr:license-type] attribute.
+
+ `link`
+ : external link describing the license; used as value of a
+ `xlink:href` attribute in the `<license>` element.
+
+`date`
+: publication date. This value should usually be a string
+ representation of a date. Pandoc will parse and deconstruct the
+ date into the components given below. It is also possible to
+ pass these components directly.
+
+ The publication date is recorded in the document via the
+ [`<pub-date>`] element and its sub-elements. The
+ [`publication-format`][attr:publication-format] attribute is
+ always set to `electronic`.
+
+ `iso-8601`
+ : ISO-8601 representation of the publication date. Used as the
+ value of the [`<pub-date>`] element's
+ [`iso-8601-date`][attr:iso-8601-date] attribute.
+
+ This value is set automatically if pandoc can parse the
+ `date` value as a date.
+
+ `day`, `month`, `year`
+ : Day, month, and year of the publication date. Only the
+ publication year is required. The values are used as the
+ contents of the elements with the respective names.
+
+ The values are set automatically if pandoc can parse the
+ `date` value as a date.
+
+ `type`
+ : The type of event marked by this date. The value is set as
+ the [`date-type`][attr:date-type] attribute on the
+ [`<pub-date>`] element and defaults to "pub" if not
+ specified.
+
+`article`
+: information concerning the article that identifies or describes
+ it. The key-value pairs within this map are typically used
+ within the [`<article-meta>`][elem:article-meta] element.
+
+ `publisher-id`
+ : external article identifier assigned by the publisher. Used
+ as the content of the [`<article-id>`][elem:article-id]
+ element with attribute [`pub-id-type`][attr:pub-id-type] set
+ to `publisher-id`.
+
+ `doi`
+ : Digital Object Identifier (DOI) assigned to the article.
+ Used as the content of the [`<article-id>`][elem:article-id]
+ element with attribute [`pub-id-type`][attr:pub-id-type] set
+ to `doi`.
+
+ `pmid`
+ : PubMed Identifier (PubMed ID) assigned to the article. Used
+ as the content of the [`<article-id>`][elem:article-id]
+ element with attribute [`pub-id-type`][attr:pub-id-type] set
+ to `pmid`.
+
+ `pmcid`
+ : PubMed Central Identifier assigned to the article. Used as
+ the content of the [`<article-id>`][elem:article-id] element
+ with attribute [`pub-id-type`][attr:pub-id-type] set to
+ `pmcid`.
+
+ `art-access-id`
+ : generic article accession identifier. Used as the content of
+ the [`<article-id>`][elem:article-id] element with attribute
+ [`pub-id-type`][attr:pub-id-type] set to `art-access-id`.
+
+ `heading`
+ : name of a subject or topic describing the article. Used as
+ the content of the [`<subject>`][elem:subject] element,
+ nested in a [`<subj-group>`][elem:subj-group] element which
+ has `heading` as its
+ [`subj-group-type`][attr:subj-group-type] attribute.
+
+ `categories`
+ : list a subject or topic describing the article. Items are
+ each used as the content a the [`<subject>`][elem:subject]
+ element, grouped in a single
+ [`<subj-group>`][elem:subj-group] element with its
+ [`subj-group-type`][attr:subj-group-type] attribute set to
+ `categories`.
+
+ `author-notes`
+ : Additional information about authors, like conflict of
+ interest statements and corresponding author contact info.
+ Wrapped in an [`<author-notes>`][elem:author-notes] element.
+
+ `conflict`
+ : Conflict of interest statement. Rendered as a footnote
+ ([`<fn>`][elem:fn]) of [`fn-type`](attr:fn-type)
+ `conflict`.
+
+ `con`
+ : Contributed-by information. Rendered as a footnote
+ ([`<fn>`][elem:fn]) of [`fn-type`](attr:fn-type) `con`.
+
+ `corresp`
+ : Correspondence information. This must be a list of
+ contributor correspondence items, where each item must
+ have the properties `id` and `email`. The info is then
+ rendered via a [`<corresp>`][elem:corresp] element.
+
+ `funding-statement`
+ : Prose describing the funding. Added to the article's
+ frontmatter via the
+ [`funding-statement`][elem:funding-statement] element.
+
+`journal`
+: information on the journal in which the article is published.
+ This must be a map; the following key/value pairs are
+ recognized.
+
+ `publisher-id`
+ : journal identifier assigned by the publisher. Used as
+ content of element [`<journal-id>`][elem:journal-id] with
+ attribute [`journal-id-type`][attr:journal-id-type] set to
+ `publisher-id`.
+
+ `nlm-ta`
+ : journal identifier assigned by PubMed. Used as content of
+ element [`<journal-id>`][elem:journal-id] with attribute
+ [`journal-id-type`][attr:journal-id-type] set to `nlm-ta`.
+
+ `pmc`
+ : journal identifier assigned by PubMed Central. Used as
+ content of element [`<journal-id>`][elem:journal-id] with
+ attribute [`journal-id-type`][attr:journal-id-type] set to
+ `pmc`.
+
+ `title`
+ : full title of the journal in which the article is published.
+ Used as content of the
+ [`<journal-title>`][elem:journal-title] element.
+
+ `abbrev-title`
+ : short form of the journal title. Used as content of the
+ [`<abbrev-journal-title>`][elem:abbrev-journal-title]
+ element.
+
+ `pissn`
+ : ISSN identifier of the publication's print version. Used as
+ content of the [`<issn>`][elem:issn] element with the
+ [`publication-format`][attr:publication-format] attribute
+ set to `print`.
+
+ `eissn`
+ : ISSN identifier of the publication's electronic version.
+ Used as content of the [`<issn>`][elem:issn] element with
+ the [`publication-format`][attr:publication-format]
+ attribute set to `electronic`.
+
+ `publisher-name`
+ : name of the publishing entity (person, company, or other).
+ Used as the content of the
+ [`<publisher-name>`][elem:publisher-name] element.
+
+ `publisher-loc`
+ : place of publication. Used as the content of the
+ [`<publisher-loc>`][elem:publisher-loc] element.
+
+`license`
+: Article licensing information. Each item of this field is
+ rendered as a `<license>` element within the
+ [`<permissions>`][elem:permissions] element.
+
+ Item content should be either a single paragraph, or a map
+ with the fields listed below.
+
+ `text`
+ : inline text describing a license under which the text is
+ published; included via the
+ [`<license-p>`][elem:copyright-holder] element.
+
+ `type`
+ : type of the license; used as value of the
+ [`license-type`][attr:license-type] attribute.
+
+ `link`
+ : external link describing the license; used as value of a
+ `xlink:href` attribute in the `<license>` element.
+
+`notes`
+: Additional notes concerning the whole article. Added to the
+ article's frontmatter via the [`<notes>`][elem:notes] element.
+
+`subtitle`
+: Subordinate part of the document title. Added to the
+ document's front matter as a
+ [`<subtitle>`][elem:article-title] element.
+
+`tags`
+: list of keywords. Items are used as contents of the
+ [`<kwd>`][elem:kwd] element; the elements are grouped in a
+ [`<kwd-group>`][elem:kwd-group] with the
+ [`kwd-group-type`][attr:kwd-group-type] value `author`.
+
+`title`
+: The article title. Added to the document's front matter via the
+ [`<article-title>`][elem:article-title] element.
+
+`supplementary-material`
+: Supplementary metadata. Added to the document's front matter
+ via the [`<supplementary-material>`][elem:supplementary-material]
+ element. Only available with `jats_articlepublishing`.
+
+`floats-group`
+: List of floating objects, such as figures, tables, text boxes,
+ etc., that are not part of the main text. The value is
+ rendered by nesting it below a
+ [`<floats-group>`][elem:floats-group] element. Only available
+ with `jats_publishing` and `jats_archiving`.
+
+
+Required Metadata
+-----------------
+
+Pandoc will try to generate a valid JATS document even when
+information is missing, filling in placeholders or using empty
+values. This circumvents the intend to ensure a minimum set of
+information being present in documents of a certain tag set. It is
+hence recommended to always provide the information listed below.
+
+### Publishing Tag Set
+
+Required metadata values:
+
+- One or more of `journal.publisher-id`, `journal.nlm-ta`,
+ `journal.pmc`.
+- One or more of `journal.pissn`, `journal.eissn`.
+
+[JATS]: https://jats.nlm.nih.gov/
+[Ringgold]: https://ringgold.com/
+[attr:content-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/content-type.html
+[attr:corresp]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/corresp.html
+[attr:date-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/date-type.html
+[attr:equal-contrib]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/equal-contrib.html
+[attr:fn-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/fn-type.html
+[attr:institution-id-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/institution-id-type.html
+[attr:iso-8601-date]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/iso-8601-date.html
+[attr:journal-id-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/journal-id-type.html
+[attr:kwd-group-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/kwd-group-type.html
+[attr:license-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/license-type.html
+[attr:pub-id-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/pub-id-type.html
+[attr:publication-format]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/publication-format.html
+[attr:ref-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/ref-type.html
+[attr:rid]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/rid.html
+[attr:subj-group-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/subj-group-type.html
+[elem:abbrev-journal-title]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/abbrev-journal-title.html
+[elem:abstract]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/abstract.html
+[elem:article-id]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/article-id.html
+[elem:article-meta]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/article-meta.html
+[elem:article-title]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/article-title.html
+[elem:supplementary-material]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/supplementary-material.html
+[elem:copyright-holder]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/copyright-holder.html
+[elem:copyright-statement]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/copyright-statement.html
+[elem:copyright-year]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/copyright-year.html
+[elem:corresp]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/corresp.html
+[elem:email]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/email.html
+[elem:floats-group]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/floats-group.html
+[elem:fn]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/fn.html
+[elem:funding-statement]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/funding-statement.html
+[elem:given-names]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/given-names.html
+[elem:issn]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/issn.html
+[elem:journal-id]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/journal-id.html
+[elem:journal-title]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/journal-title.html
+[elem:kwd-group]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/kwd-group.html
+[elem:kwd]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/kwd.html
+[elem:license-p]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/license-p.html
+[elem:license]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/license.html
+[elem:notes]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/notes.html
+[elem:permissions]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/permissions.html
+[elem:publisher-loc]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/publisher-loc.html
+[elem:publisher-name]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/publisher-name.html
+[elem:string-name]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/string-name.html
+[elem:subj-group]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/subj-group.html
+[elem:subject]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/subject.html
+[elem:subtitle]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/subtitle.html
+[elem:surname]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/surname.html
+[elem:xref]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/xref.html
+
+[`<addr-line>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/addr-line.html
+[`<aff>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/aff.html
+[`<city>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/city.html
+[`<contrib>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/contrib.html
+[`<country>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/country.html
+[`<institution-id>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/institution-id.html
+[`<institution-wrap>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/institution-wrap.html
+[`<institution>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/institution.html
+[`<pub-date>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/pub-date.html
+[`<role>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/role.html
+[`<degree-contribution>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/degree-contribution.html
diff --git a/documents/markdown/pandoc-md/doc_libraries.md b/documents/markdown/pandoc-md/doc_libraries.md
new file mode 100644
index 0000000..6e0abdd
--- /dev/null
+++ b/documents/markdown/pandoc-md/doc_libraries.md
@@ -0,0 +1,105 @@
+---
+title: The pandoc family of libraries
+author: John MacFarlane
+---
+
+The following Haskell libraries have been developed to support
+pandoc:
+
+
+[citeproc]
+: Citation processing using CSL stylesheets.
+
+[commonmark], [commonmark-extensions], and [commonmark-pandoc]
+: Efficient, standards-compliant parser for commonmark and extensions.
+
+[djot]
+: Parser and renderer for djot light markup syntax.
+
+[doclayout]
+: Combinators for laying out a textual document, with support
+ for line wrapping, tabular layout, and more.
+
+[doctemplates]
+: Supports pandoc's templates.
+
+[emojis]
+: Conversion between emoji characters and aliases.
+
+[gridtables]
+: Support for parsing grid style textual tables.
+
+[hslua-aeson]
+: Converter from aeson data types to Lua objects.
+
+[hslua-cli]
+: Command-line interface mimicking the default `lua` executable.
+
+[hslua-module-doclayout]
+: Lua bindings to the doclayout library mentioned above.
+
+[hslua-module-path], [-system], [-text], and [-version]
+: Lua modules that expose functionality of basic Haskell
+ libraries to Lua.
+
+[hslua-objectorientation], [hslua-packaging]
+: Bindings, wrappers, and helper functions to access Haskell data
+ types from Lua via an object-oriented interface.
+
+[ipynb]
+: Representation of Jupyter notebooks and conversion to and
+ from JSON.
+
+[jira-wiki-markup]
+: Support for parsing Jira wiki syntax.
+
+[rfc5051]
+: Simple unicode collation (used for citation sorting).
+
+[skylighting-core] and [skylighting]
+: Syntax highlighting engine supporting over 140 languages.
+
+[texmath]
+: Conversion of math between tex, Word equation, MathML, and GNU eqn.
+
+[typst]
+: Parsing and evaluating typst syntax.
+
+[typst-symbol]
+: Symbol and emoji lookup for typst language.
+
+[unicode-collation]
+: Proper Unicode collation (sorting).
+
+[zip-archive]
+: A pure zip file creator and extractor, used by pandoc for
+ docx, ODT, and EPUB.
+
+[citeproc]: https://hackage.haskell.org/package/citeproc
+[commonmark-extensions]: https://hackage.haskell.org/package/commonmark-extensions
+[commonmark-pandoc]: https://hackage.haskell.org/package/commonmark-pandoc
+[commonmark]: https://hackage.haskell.org/package/commonmark
+[djot]: https://hackage.haskell.org/package/djot
+[doclayout]: https://hackage.haskell.org/package/doclayout
+[doctemplates]: https://hackage.haskell.org/package/doctemplates
+[emojis]: https://hackage.haskell.org/package/emojis
+[gridtables]: https://hackage.haskell.org/package/gridtables
+[hslua-aeson]: https://hackage.haskell.org/package/hslua-aeson
+[hslua-cli]: https://hackage.haskell.org/package/hslua-cli
+[hslua-module-doclayout]: https://hackage.haskell.org/package/hslua-module-doclayout
+[hslua-module-path]: https://hackage.haskell.org/package/hslua-module-path
+[-system]: https://hackage.haskell.org/package/hslua-module-system
+[-text]: https://hackage.haskell.org/package/hslua-module-text
+[-version]: https://hackage.haskell.org/package/hslua-module-version
+[hslua-objectorientation]: https://hackage.haskell.org/package/hslua-objectorientation
+[hslua-packaging]: https://hackage.haskell.org/package/hslua-packaging
+[ipynb]: https://hackage.haskell.org/package/ipynb
+[jira-wiki-markup]: https://hackage.haskell.org/package/jira-wiki-markup
+[rfc5051]: https://hackage.haskell.org/package/rfc5051
+[skylighting-core]: https://hackage.haskell.org/package/skylighting-core
+[skylighting]: https://hackage.haskell.org/package/skylighting
+[texmath]: https://hackage.haskell.org/package/texmath
+[typst-symbol]: https://hackage.haskell.org/package/typst-symbol
+[typst]: https://hackage.haskell.org/package/typst
+[unicode-collation]: https://hackage.haskell.org/package/unicode-collation
+[zip-archive]: https://hackage.haskell.org/package/zip-archive
diff --git a/documents/markdown/pandoc-md/doc_lua-filters.md b/documents/markdown/pandoc-md/doc_lua-filters.md
new file mode 100644
index 0000000..ae864e8
--- /dev/null
+++ b/documents/markdown/pandoc-md/doc_lua-filters.md
@@ -0,0 +1,7536 @@
+---
+author:
+- Albert Krewinkel
+- John MacFarlane
+date: 'January 10, 2020'
+title: Pandoc Lua Filters
+---
+
+# Introduction
+
+Pandoc has long supported filters, which allow the pandoc
+abstract syntax tree (AST) to be manipulated between the parsing
+and the writing phase. [Traditional pandoc
+filters](https://pandoc.org/filters.html) accept a JSON
+representation of the pandoc AST and produce an altered JSON
+representation of the AST. They may be written in any
+programming language, and invoked from pandoc using the
+`--filter` option.
+
+Although traditional filters are very flexible, they have a
+couple of disadvantages. First, there is some overhead in
+writing JSON to stdout and reading it from stdin (twice, once on
+each side of the filter). Second, whether a filter will work
+will depend on details of the user's environment. A filter may
+require an interpreter for a certain programming language to be
+available, as well as a library for manipulating the pandoc AST
+in JSON form. One cannot simply provide a filter that can be
+used by anyone who has a certain version of the pandoc
+executable.
+
+Starting with version 2.0, pandoc makes it possible to write
+filters in Lua without any external dependencies at all. A Lua
+interpreter (version 5.4) and a Lua library for creating pandoc
+filters is built into the pandoc executable. Pandoc data types
+are marshaled to Lua directly, avoiding the overhead of writing
+JSON to stdout and reading it from stdin.
+
+Here is an example of a Lua filter that converts strong emphasis
+to small caps:
+
+``` lua
+return {
+ Strong = function (elem)
+ return pandoc.SmallCaps(elem.content)
+ end,
+}
+```
+
+or equivalently,
+
+``` lua
+function Strong(elem)
+ return pandoc.SmallCaps(elem.content)
+end
+```
+
+This says: walk the AST, and when you find a Strong element,
+replace it with a SmallCaps element with the same content.
+
+To run it, save it in a file, say `smallcaps.lua`, and invoke
+pandoc with `--lua-filter=smallcaps.lua`.
+
+Here's a quick performance comparison, converting the pandoc
+manual (MANUAL.txt) to HTML, with versions of the same JSON
+filter written in compiled Haskell (`smallcaps`) and interpreted
+Python (`smallcaps.py`):
+
+ Command Time
+ --------------------------------------- -------
+ `pandoc` 1.01s
+ `pandoc --filter ./smallcaps` 1.36s
+ `pandoc --filter ./smallcaps.py` 1.40s
+ `pandoc --lua-filter ./smallcaps.lua` 1.03s
+
+As you can see, the Lua filter avoids the substantial overhead
+associated with marshaling to and from JSON over a pipe.
+
+# Lua filter structure
+
+Lua filters are tables with element names as keys and values
+consisting of functions acting on those elements.
+
+Filters are expected to be put into separate files and are
+passed via the `--lua-filter` command-line argument. For
+example, if a filter is defined in a file `current-date.lua`,
+then it would be applied like this:
+
+ pandoc --lua-filter=current-date.lua -f markdown MANUAL.txt
+
+The `--lua-filter` option may be supplied multiple times. Pandoc
+applies all filters (including JSON filters specified via
+`--filter` and Lua filters specified via `--lua-filter`) in the
+order they appear on the command line.
+
+Pandoc expects each Lua file to return a filter. If there is
+no value returned by the filter script, then pandoc will try to
+generate a single filter by collecting all top-level functions
+whose names correspond to those of pandoc elements (e.g., `Str`,
+`Para`, `Meta`, or `Pandoc`). (That is why the two examples above
+are equivalent.)
+
+It is currently also possible to return a list of filters
+from a Lua file which are called sequentially. Before the
+[walk](#type-pandoc:walk) method was made available, this was
+the only way to run multiple filters from one Lua file. However,
+returning a list of filters is now discouraged in favor of using
+the [walk](#type-pandoc:walk) method, and this functionality may
+be removed at some point.
+
+For each filter, the document is traversed and each element
+subjected to the filter. Elements for which the filter contains
+an entry (i.e. a function of the same name) are passed to Lua
+element filtering function. In other words, filter entries will
+be called for each corresponding element in the document,
+getting the respective element as input.
+
+The return value of a filter function must be one of the
+following:
+
+- nil: this means that the object should remain unchanged.
+- a pandoc object: this must be of the same type as the input
+ and will replace the original object.
+- a list of pandoc objects: these will replace the original
+ object; the list is merged with the neighbors of the
+ original objects (spliced into the list the original object
+ belongs to); returning an empty list deletes the object.
+
+The function's output must result in an element of the same type
+as the input. This means a filter function acting on an inline
+element must return either nil, an inline, or a list of inlines,
+and a function filtering a block element must return one of nil,
+a block, or a list of block elements. Pandoc will throw an error
+if this condition is violated.
+
+If there is no function matching the element's node type, then
+the filtering system will look for a more general fallback
+function. Two fallback functions are supported, `Inline` and
+`Block`. Each matches elements of the respective type.
+
+Elements without matching functions are left untouched.
+
+See [module documentation](#module-pandoc) for a list of pandoc
+elements.
+
+## Filters on element sequences
+
+For some filtering tasks, it is necessary to know the order
+in which elements occur in the document. It is not enough then to
+inspect a single element at a time.
+
+There are two special function names, which can be used to define
+filters on lists of blocks or lists of inlines.
+
+[`Inlines (inlines)`]{#inlines-filter}
+: If present in a filter, this function will be called on all
+ lists of inline elements, like the content of a [Para]
+ (paragraph) block, or the description of an [Image]. The
+ `inlines` argument passed to the function will be a [List] of
+ [Inline] elements for each call.
+
+[`Blocks (blocks)`]{#blocks-filter}
+: If present in a filter, this function will be called on all
+ lists of block elements, like the content of a [MetaBlocks]
+ meta element block, on each item of a list, and the main
+ content of the [Pandoc] document. The `blocks` argument
+ passed to the function will be a [List] of [Block] elements
+ for each call.
+
+These filter functions are special in that the result must either
+be nil, in which case the list is left unchanged, or must be a
+list of the correct type, i.e., the same type as the input
+argument. Single elements are **not** allowed as return values,
+as a single element in this context usually hints at a bug.
+
+See ["Remove spaces before normal citations"][Inlines filter
+example] for an example.
+
+This functionality has been added in pandoc 2.9.2.
+
+[Inlines filter example]: #remove-spaces-before-citations
+
+## Traversal order
+
+The traversal order of filters can be selected by setting the key
+`traverse` to either `'topdown'` or `'typewise'`; the default is
+`'typewise'`.
+
+Example:
+
+``` lua
+local filter = {
+ traverse = 'topdown',
+ -- ... filter functions ...
+}
+return filter
+```
+
+Support for this was added in pandoc 2.17; previous versions
+ignore the `traverse` setting.
+
+### Typewise traversal
+
+Element filter functions within a filter set are called in a
+fixed order, skipping any which are not present:
+
+ 1. functions for [*Inline* elements](#type-inline),
+ 2. the [`Inlines`](#inlines-filter) filter function,
+ 2. functions for [*Block* elements](#type-block) ,
+ 2. the [`Blocks`](#inlines-filter) filter function,
+ 3. the [`Meta`](#type-meta) filter function, and last
+ 4. the [`Pandoc`](#type-pandoc) filter function.
+
+It is still possible to force a different order by manually
+running the filters using the [walk](#type-pandoc:walk) method.
+For example, if the filter for *Meta* is to be run before that
+for *Str*, one can write
+
+``` lua
+function Pandoc(doc)
+ doc = doc:walk { Meta = Meta } -- (1)
+ return doc:walk { Str = Str } -- (2)
+end
+```
+
+### Topdown traversal
+
+It is sometimes more natural to traverse the document tree
+depth-first from the root towards the leaves, and all in a single
+run.
+
+For example, a block list `[Plain [Str "a"], Para [Str
+"b"]]`{.haskell} will try the following filter functions, in
+order: `Blocks`, `Plain`, `Inlines`, `Str`, `Para`, `Inlines`,
+`Str`.
+
+Topdown traversals can be cut short by returning `false` as a
+second value from the filter function. No child-element of
+the returned element is processed in that case.
+
+For example, to exclude the contents of a footnote from being
+processed, one might write
+
+``` lua
+traverse = 'topdown'
+function Note (n)
+ return n, false
+end
+```
+
+## Global variables
+
+Pandoc passes additional data to Lua filters by setting global
+variables.
+
+`FORMAT`
+: The global `FORMAT` is set to the format of the pandoc
+ writer being used (`html5`, `latex`, etc.), so the behavior
+ of a filter can be made conditional on the eventual output
+ format.
+
+`PANDOC_READER_OPTIONS`
+: Table of the options which were provided to the parser.
+ ([ReaderOptions](#type-readeroptions))
+
+`PANDOC_WRITER_OPTIONS`
+: Table of the options that will be passed to the writer.
+ While the object can be modified, the changes will **not**
+ be picked up by pandoc.
+ ([WriterOptions](#type-writeroptions))
+
+ Accessing this variable in **custom writers** is
+ **deprecated**. Starting with pandoc 3.0, it is set to a
+ placeholder value (the default options) in custom writers.
+ Access to the actual writer options is provided via the
+ `Writer` or `ByteStringWriter` function, to which the options
+ are passed as the second function argument.
+
+ *Since: pandoc 2.17*
+
+`PANDOC_VERSION`
+: Contains the pandoc version as a [Version] object which
+ behaves like a numerically indexed table, most significant
+ number first. E.g., for pandoc 2.7.3, the value of the
+ variable is equivalent to a table `{2, 7, 3}`. Use
+ `tostring(PANDOC_VERSION)` to produce a version string. This
+ variable is also set in custom writers.
+
+`PANDOC_API_VERSION`
+: Contains the version of the pandoc-types API against which
+ pandoc was compiled. It is given as a numerically indexed
+ table, most significant number first. E.g., if pandoc was
+ compiled against pandoc-types 1.17.3, then the value of the
+ variable will behave like the table `{1, 17, 3}`. Use
+ `tostring(PANDOC_API_VERSION)` to produce a version string.
+ This variable is also set in custom writers.
+
+`PANDOC_SCRIPT_FILE`
+: The name used to involve the filter. This value can be used
+ to find files relative to the script file. This variable is
+ also set in custom writers.
+
+`PANDOC_STATE`
+: The state shared by all readers and writers. It is used by
+ pandoc to collect and pass information. The value of this
+ variable is of type [CommonState] and
+ is read-only.
+
+`pandoc`
+: The *pandoc* module, described in the next section, is
+ available through the global `pandoc`. The other modules
+ described herein are loaded as subfields under their
+ respective name.
+
+`lpeg`
+: This variable holds the `lpeg` module, a package based on
+ Parsing Expression Grammars (PEG). It provides excellent
+ parsing utilities and is documented on the official [LPeg
+ homepage]. Pandoc uses a built-in version of the library,
+ unless it has been configured by the package maintainer to
+ rely on a system-wide installation.
+
+`re`
+: Contains the LPeg.re module, which is built on top of LPeg
+ and offers an implementation of a [regex engine]. Pandoc
+ uses a built-in version of the library, unless it has been
+ configured by the package maintainer to rely on a system-wide
+ installation.
+
+[LPeg homepage]: http://www.inf.puc-rio.br/~roberto/lpeg/
+[regex engine]: http://www.inf.puc-rio.br/~roberto/lpeg/re.html
+
+# Pandoc Module
+
+The `pandoc` Lua module is loaded into the filter's Lua
+environment and provides a set of functions and constants to
+make creation and manipulation of elements easier. The global
+variable `pandoc` is bound to the module and should generally
+not be overwritten for this reason.
+
+Two major functionalities are provided by the module: element
+creator functions and access to some of pandoc's main
+functionalities.
+
+## Element creation
+
+Element creator functions like `Str`, `Para`, and `Pandoc` are
+designed to allow easy creation of new elements that are simple
+to use and can be read back from the Lua environment.
+Internally, pandoc uses these functions to create the Lua
+objects which are passed to element filter functions. This means
+that elements created via this module will behave exactly as
+those elements accessible through the filter function parameter.
+
+## Exposed pandoc functionality
+
+Some pandoc functions have been made available in Lua:
+
+- [`walk_block`](#pandoc.walk_block) and
+ [`walk_inline`](#pandoc.walk_inline) allow filters to be applied
+ inside specific block or inline elements;
+- [`read`](#pandoc.read) allows filters to parse strings into pandoc
+ documents;
+- [`pipe`](#pandoc.pipe) runs an external command with input from and
+ output to strings;
+- the [`pandoc.mediabag`](#module-pandoc.mediabag) module
+ allows access to the "mediabag," which stores binary content
+ such as images that may be included in the final document;
+- the [`pandoc.utils`](#module-pandoc.utils) module contains
+ various utility functions.
+
+# Lua interpreter initialization
+
+Initialization of pandoc's Lua interpreter can be controlled by
+placing a file `init.lua` in pandoc's data directory. A common
+use-case would be to load additional modules, or even to alter
+default modules.
+
+The following snippet is an example of code that might be useful
+when added to `init.lua`. The snippet adds all Unicode-aware
+functions defined in the [`text` module](#module-pandoc.text) to the
+default `string` module, prefixed with the string `uc_`.
+
+``` lua
+for name, fn in pairs(require 'text') do
+ string['uc_' .. name] = fn
+end
+```
+
+This makes it possible to apply these functions on strings using
+colon syntax (`mystring:uc_upper()`).
+
+# Debugging Lua filters
+
+Many errors can be avoided by performing static analysis.
+[`luacheck`](https://github.com/lunarmodules/luacheck) may be used
+for this purpose. A Luacheck configuration file for pandoc filters
+is available at <https://github.com/rnwst/pandoc-luacheckrc>.
+
+William Lupton has written a Lua module with some handy
+functions for debugging Lua filters, including functions
+that can pretty-print the Pandoc AST elements manipulated
+by the filters: it is available at
+<https://github.com/wlupton/pandoc-lua-logging>.
+
+It is possible to use a debugging interface to halt execution and
+step through a Lua filter line by line as it is run inside Pandoc.
+This is accomplished using the remote-debugging interface of the
+package [`mobdebug`](https://github.com/pkulchenko/MobDebug).
+Although mobdebug can be run from the terminal, it is more useful
+run within the donation-ware Lua editor and IDE, [ZeroBrane
+Studio](https://studio.zerobrane.com/). ZeroBrane offers a REPL
+console and UI to step-through and view all variables and state.
+
+ZeroBrane doesn't come with Lua 5.4 bundled, but it can debug it, so
+you should install Lua 5.4, and then add
+[`mobdebug`](https://luarocks.org/modules/paulclinger/mobdebug) and
+its dependency
+[`luasocket`](https://luarocks.org/modules/luasocket/luasocket) using
+[`luarocks`](https://luarocks.org). ZeroBrane can use your Lua 5.4
+install by adding `path.lua = "/path/to/your/lua"` in your ZeroBrane
+settings file. Next, open your Lua filter in ZeroBrane, and add
+`require('mobdebug').start()` at the line where you want your
+breakpoint. Then make sure the Project > Lua Interpreter is set to the
+"Lua" you added in settings and enable "Start Debugger Server" [see
+detailed instructions
+here](https://studio.zerobrane.com/doc-remote-debugging). Run Pandoc
+as you normally would, and ZeroBrane should break at the correct line.
+
+## Common pitfalls
+
+AST elements not updated
+: A filtered element will only be updated if the filter
+ function returns a new element to replace it. A function like
+ the below has no effect, as the function returns no value:
+
+ ``` lua
+ function Str (str)
+ str.text = string.upper(str.text)
+ end
+ ```
+
+ The correct version would be
+
+ ``` lua
+ function Str (str)
+ str.text = string.upper(str.text)
+ return str
+ end
+ ```
+
+Pattern behavior is locale dependent
+: The character classes in Lua's pattern library depend on the
+ current locale: E.g., the character `©` will be treated as
+ punctuation, and matched by the pattern `%p`, on CP-1252
+ locales, but not on systems using a UTF-8 locale.
+
+ A reliable way to ensure unified handling of patterns and
+ character classes is to use the "C" locale by adding
+ `os.setlocale 'C'` to the top of the Lua script.
+
+String library is not Unicode aware
+: Lua's `string` library treats each byte as a single
+ character. A function like `string.upper` will not have the
+ intended effect when applied to words with non-ASCII
+ characters. Similarly, a pattern like `[☃]` will match *any*
+ of the bytes `\240`, `\159`, `\154`, and `\178`, but
+ **won't** match the "snowman" Unicode character.
+
+ Use the [pandoc.text](#module-pandoc.text) module for Unicode-aware
+ transformation, and consider using using the lpeg or re
+ library for pattern matching.
+
+# Examples
+
+The following filters are presented as examples. A repository of
+useful Lua filters (which may also serve as good examples) is
+available at <https://github.com/pandoc/lua-filters>.
+
+## Macro substitution
+
+The following filter converts the string `{{helloworld}}` into
+emphasized text "Hello, World".
+
+``` lua
+return {
+ Str = function (elem)
+ if elem.text == "{{helloworld}}" then
+ return pandoc.Emph {pandoc.Str "Hello, World"}
+ else
+ return elem
+ end
+ end,
+}
+```
+
+## Center images in LaTeX and HTML output
+
+For LaTeX, wrap an image in LaTeX snippets which cause the image
+to be centered horizontally. In HTML, the image element's style
+attribute is used to achieve centering.
+
+``` lua
+-- Filter images with this function if the target format is LaTeX.
+if FORMAT:match 'latex' then
+ function Image (elem)
+ -- Surround all images with image-centering raw LaTeX.
+ return {
+ pandoc.RawInline('latex', '\\hfill\\break{\\centering'),
+ elem,
+ pandoc.RawInline('latex', '\\par}')
+ }
+ end
+end
+
+-- Filter images with this function if the target format is HTML
+if FORMAT:match 'html' then
+ function Image (elem)
+ -- Use CSS style to center image
+ elem.attributes.style = 'margin:auto; display: block;'
+ return elem
+ end
+end
+```
+
+## Setting the date in the metadata
+
+This filter sets the date in the document's metadata to the
+current date, if a date isn't already set:
+
+``` lua
+function Meta(m)
+ if m.date == nil then
+ m.date = os.date("%B %e, %Y")
+ return m
+ end
+end
+```
+
+## Remove spaces before citations
+
+This filter removes all spaces preceding an "author-in-text"
+citation. In Markdown, author-in-text citations (e.g.,
+`@citekey`), must be preceded by a space. If these spaces are
+undesired, they must be removed with a filter.
+
+``` lua
+local function is_space_before_author_in_text(spc, cite)
+ return spc and spc.t == 'Space'
+ and cite and cite.t == 'Cite'
+ -- there must be only a single citation, and it must have
+ -- mode 'AuthorInText'
+ and #cite.citations == 1
+ and cite.citations[1].mode == 'AuthorInText'
+end
+
+function Inlines (inlines)
+ -- Go from end to start to avoid problems with shifting indices.
+ for i = #inlines-1, 1, -1 do
+ if is_space_before_author_in_text(inlines[i], inlines[i+1]) then
+ inlines:remove(i)
+ end
+ end
+ return inlines
+end
+```
+
+## Replacing placeholders with their metadata value
+
+Lua filter functions are run in the order
+
+> *Inlines → Blocks → Meta → Pandoc*.
+
+Passing information from a higher level (e.g., metadata) to a
+lower level (e.g., inlines) is still possible by using two
+filters living in the same file:
+
+``` lua
+local vars = {}
+
+local function get_vars (meta)
+ for k, v in pairs(meta) do
+ if pandoc.utils.type(v) == 'Inlines' then
+ vars["%" .. k .. "%"] = {table.unpack(v)}
+ end
+ end
+end
+
+local function replace (el)
+ if vars[el.text] then
+ return pandoc.Span(vars[el.text])
+ else
+ return el
+ end
+end
+
+function Pandoc(doc)
+ return doc:walk { Meta = get_vars }:walk { Str = replace }
+end
+```
+
+If the contents of file `occupations.md` are
+
+``` markdown
+---
+name: Samuel Q. Smith
+occupation: Professor of Oenology
+---
+
+Name
+
+: %name%
+
+Occupation
+
+: %occupation%
+```
+
+then running `pandoc --lua-filter=meta-vars.lua occupations.md`
+will output:
+
+``` html
+<dl>
+<dt>Name</dt>
+<dd><p><span>Samuel Q. Smith</span></p>
+</dd>
+<dt>Occupation</dt>
+<dd><p><span>Professor of Oenology</span></p>
+</dd>
+</dl>
+```
+Note that the placeholders must not contain any spaces, otherwise
+they will turn into two separate Str elements and the filter
+won't work.
+
+## Modifying pandoc's `MANUAL.txt` for man pages
+
+This is the filter we use when converting `MANUAL.txt` to man
+pages. It converts level-1 headers to uppercase (using
+[`walk`](#type-block:walk) to transform inline elements inside
+headers), removes footnotes, and replaces links with regular
+text.
+
+``` lua
+-- we use pandoc.text to get a UTF-8 aware 'upper' function
+local text = pandoc.text
+
+function Header(el)
+ if el.level == 1 then
+ return el:walk {
+ Str = function(el)
+ return pandoc.Str(text.upper(el.text))
+ end
+ }
+ end
+end
+
+function Link(el)
+ return el.content
+end
+
+function Note(el)
+ return {}
+end
+```
+
+## Creating a handout from a paper
+
+This filter extracts all the numbered examples, section headers,
+block quotes, and figures from a document, in addition to any
+divs with class `handout`. (Note that only blocks at the "outer
+level" are included; this ignores blocks inside nested
+constructs, like list items.)
+
+``` lua
+-- creates a handout from an article, using its headings,
+-- blockquotes, numbered examples, figures, and any
+-- Divs with class "handout"
+
+function Pandoc(doc)
+ local hblocks = {}
+ for i,el in pairs(doc.blocks) do
+ if (el.t == "Div" and el.classes[1] == "handout") or
+ (el.t == "BlockQuote") or
+ (el.t == "OrderedList" and el.style == "Example") or
+ (el.t == "Para" and #el.c == 1 and el.c[1].t == "Image") or
+ (el.t == "Header") then
+ table.insert(hblocks, el)
+ end
+ end
+ return pandoc.Pandoc(hblocks, doc.meta)
+end
+```
+
+## Counting words in a document
+
+This filter counts the words in the body of a document (omitting
+metadata like titles and abstracts), including words in code. It
+should be more accurate than `wc -w` run directly on a Markdown
+document, since the latter will count markup characters, like
+the `#` in front of an ATX header, or tags in HTML documents, as
+words. To run it, `pandoc --lua-filter wordcount.lua myfile.md`.
+
+``` lua
+-- counts words in a document
+
+words = 0
+
+wordcount = {
+ Str = function(el)
+ -- we don't count a word if it's entirely punctuation:
+ if el.text:match("%P") then
+ words = words + 1
+ end
+ end,
+
+ Code = function(el)
+ _,n = el.text:gsub("%S+","")
+ words = words + n
+ end,
+
+ CodeBlock = function(el)
+ _,n = el.text:gsub("%S+","")
+ words = words + n
+ end
+}
+
+function Pandoc(el)
+ -- skip metadata, just count body:
+ el.blocks:walk(wordcount)
+ print(words .. " words in body")
+ os.exit(0)
+end
+```
+
+## Creating a table
+
+This filter creates a document that contains the following
+table with 5 columns. It serves as a working example of how
+to use the [`pandoc.Table`](#pandoc.Table) constructor.
+
++--------+--------+--------+--------+---+
+| This | is my | table | header | |
++========+:=======+:======:+=======:+===+
+| Cell 1 | Cell 2 | Cell 3 | | |
++--------+--------+--------+--------+---+
+| Cell 4 | Cell 5 | Cell 6 | | |
++========+========+========+========+===+
+| This is my table footer. | |
++===================================+===+
+
+: This is my table caption.
+
+Note that:
+
+- The number of columns in the resulting Table element is
+ equal to the number of entries in the `colspecs` parameter.
+
+- A [ColSpec] object must contain the cell alignment, but the
+ column width is optional.
+
+- A [TableBody] object is specified using a Lua table in the
+ `bodies` parameter because there is no `pandoc.TableBody`
+ constructor.
+
+```lua
+function Pandoc ()
+ local caption = pandoc.Caption( "This is my table caption." )
+ local colspecs = {
+ { pandoc.AlignLeft },
+ { pandoc.AlignDefault },
+ { pandoc.AlignCenter },
+ { pandoc.AlignRight },
+ { pandoc.AlignDefault }
+ }
+ local head = pandoc.TableHead{
+ pandoc.Row{
+ pandoc.Cell( "This" ),
+ pandoc.Cell( "is my" ),
+ pandoc.Cell( "table" ),
+ pandoc.Cell( "header" )
+ }
+ }
+ local bodies = {
+ {
+ attr={},
+ body={
+ pandoc.Row{
+ pandoc.Cell( "Cell 1" ),
+ pandoc.Cell( "Cell 2" ),
+ pandoc.Cell( "Cell 3" )
+ },
+ pandoc.Row{
+ pandoc.Cell( "Cell 4" ),
+ pandoc.Cell( "Cell 5" ),
+ pandoc.Cell( "Cell 6" )
+ }
+ },
+ head={},
+ row_head_columns=0
+ }
+ }
+ local foot = pandoc.TableFoot{
+ pandoc.Row{
+ pandoc.Cell( "This is my table footer.", pandoc.AlignDefault, 1, 4 )
+ }
+ }
+ return pandoc.Pandoc {
+ pandoc.Table(caption, colspecs, head, bodies, foot)
+ }
+end
+```
+
+## Extracting links from a document
+
+This filter creates a document containing a table that lists
+the URLs the input document links to, together with the
+number of links to each URL.
+
+```lua
+links = {}
+
+function Link (el)
+ if links[el.target] then
+ links[el.target] = links[el.target] + 1
+ else
+ links[el.target] = 1
+ end
+ return el
+end
+
+function Pandoc ()
+ local caption = pandoc.Caption("Link count.")
+ local colspecs = {
+ { pandoc.AlignDefault, 0.8 },
+ { pandoc.AlignLeft, 0.2 }
+ }
+ local head = pandoc.TableHead{
+ pandoc.Row{ pandoc.Cell("Target"), pandoc.Cell("Count") }
+ }
+ local foot = pandoc.TableFoot()
+ local rows = {}
+ for link, count in pairs(links) do
+ rows[#rows + 1] = pandoc.Row{
+ pandoc.Cell( link ),
+ pandoc.Cell( pandoc.utils.stringify(count) )
+ }
+ end
+ local bodies = {
+ {
+ attr={},
+ body=rows,
+ head={},
+ row_head_columns=0
+ }
+ }
+ return pandoc.Pandoc {
+ pandoc.Table(caption, colspecs, head, bodies, foot)
+ }
+end
+```
+
+## Converting ABC code to music notation
+
+This filter replaces code blocks with class `abc` with images
+created by running their contents through `abcm2ps` and
+ImageMagick's `convert`. (For more on ABC notation, see
+<https://abcnotation.com>.)
+
+Images are added to the mediabag. For output to binary formats,
+pandoc will use images in the mediabag. For textual formats, use
+`--extract-media` to specify a directory where the files in the
+mediabag will be written, or (for HTML only) use
+`--embed-resources`.
+
+``` lua
+-- Pandoc filter to process code blocks with class "abc" containing
+-- ABC notation into images.
+--
+-- * Assumes that abcm2ps and ImageMagick's convert are in the path.
+-- * For textual output formats, use --extract-media=abc-images
+-- * For HTML formats, you may alternatively use --embed-resources
+
+local filetypes = { html = {"png", "image/png"}
+ , latex = {"pdf", "application/pdf"}
+ }
+local filetype = filetypes[FORMAT][1] or "png"
+local mimetype = filetypes[FORMAT][2] or "image/png"
+
+local function abc2eps(abc, filetype)
+ local eps = pandoc.pipe("abcm2ps", {"-q", "-O", "-", "-"}, abc)
+ local final = pandoc.pipe("convert", {"-", filetype .. ":-"}, eps)
+ return final
+end
+
+function CodeBlock(block)
+ if block.classes[1] == "abc" then
+ local img = abc2eps(block.text, filetype)
+ local fname = pandoc.sha1(img) .. "." .. filetype
+ pandoc.mediabag.insert(fname, mimetype, img)
+ return pandoc.Para{ pandoc.Image({pandoc.Str("abc tune")}, fname) }
+ end
+end
+```
+
+## Building images with Ti*k*Z
+
+This filter converts raw LaTeX Ti*k*Z environments into images. It
+works with both PDF and HTML output. The Ti*k*Z code is compiled
+to an image using `pdflatex`, and the image is converted from
+pdf to svg format using
+[`pdf2svg`](https://github.com/dawbarton/pdf2svg), so both of
+these must be in the system path. Converted images are cached in
+the working directory and given filenames based on a hash of the
+source, so that they need not be regenerated each time the
+document is built. (A more sophisticated version of this might
+put these in a special cache directory.)
+
+``` lua
+local system = require 'pandoc.system'
+
+local tikz_doc_template = [[
+\documentclass{standalone}
+\usepackage{xcolor}
+\usepackage{tikz}
+\begin{document}
+\nopagecolor
+%s
+\end{document}
+]]
+
+local function tikz2image(src, filetype, outfile)
+ system.with_temporary_directory('tikz2image', function (tmpdir)
+ system.with_working_directory(tmpdir, function()
+ local f = io.open('tikz.tex', 'w')
+ f:write(tikz_doc_template:format(src))
+ f:close()
+ os.execute('pdflatex tikz.tex')
+ if filetype == 'pdf' then
+ os.rename('tikz.pdf', outfile)
+ else
+ os.execute('pdf2svg tikz.pdf ' .. outfile)
+ end
+ end)
+ end)
+end
+
+extension_for = {
+ html = 'svg',
+ html4 = 'svg',
+ html5 = 'svg',
+ latex = 'pdf',
+ beamer = 'pdf' }
+
+local function file_exists(name)
+ local f = io.open(name, 'r')
+ if f ~= nil then
+ io.close(f)
+ return true
+ else
+ return false
+ end
+end
+
+local function starts_with(start, str)
+ return str:sub(1, #start) == start
+end
+
+
+function RawBlock(el)
+ if starts_with('\\begin{tikzpicture}', el.text) then
+ local filetype = extension_for[FORMAT] or 'svg'
+ local fbasename = pandoc.sha1(el.text) .. '.' .. filetype
+ local fname = system.get_working_directory() .. '/' .. fbasename
+ if not file_exists(fname) then
+ tikz2image(el.text, filetype, fname)
+ end
+ return pandoc.Para({pandoc.Image({}, fbasename)})
+ else
+ return el
+ end
+end
+```
+
+Example of use:
+
+ pandoc --lua-filter tikz.lua -s -o cycle.html <<EOF
+ Here is a diagram of the cycle:
+
+ \begin{tikzpicture}
+
+ \def \n {5}
+ \def \radius {3cm}
+ \def \margin {8} % margin in angles, depends on the radius
+
+ \foreach \s in {1,...,\n}
+ {
+ \node[draw, circle] at ({360/\n * (\s - 1)}:\radius) {$\s$};
+ \draw[->, >=latex] ({360/\n * (\s - 1)+\margin}:\radius)
+ arc ({360/\n * (\s - 1)+\margin}:{360/\n * (\s)-\margin}:\radius);
+ }
+ \end{tikzpicture}
+ EOF
+
+# Lua type reference
+
+This section describes the types of objects available to Lua
+filters. See the [pandoc module](#module-pandoc) for
+functions to create these objects.
+
+## Shared Properties
+
+### `clone`
+
+`clone ()`
+
+All instances of the types listed here, with the exception of
+read-only objects, can be cloned via the `clone()` method.
+
+Usage:
+
+ local emph = pandoc.Emph {pandoc.Str 'important'}
+ local cloned_emph = emph:clone() -- note the colon
+
+## Pandoc {#type-pandoc}
+
+Pandoc document
+
+Values of this type can be created with the
+[`pandoc.Pandoc`](#pandoc.Pandoc) constructor. Pandoc values are
+equal in Lua if and only if they are equal in Haskell.
+
+`blocks`
+: document content ([Blocks][])
+
+`meta`
+: document meta information ([Meta] object)
+
+### Methods {#type-pandoc-methods}
+
+#### normalize
+
+`normalize(self)`
+
+Perform a normalization of Pandoc documents. E.g., multiple
+successive spaces are collapsed, and tables are normalized, so
+that all rows and columns contain the same number of cells.
+
+Parameters:
+
+`self`
+: the element ([Pandoc][])
+
+Results:
+
+- cloned and normalized document. ([Pandoc][])
+
+### walk {#type-pandoc:walk}
+
+`walk(self, lua_filter)`
+
+Applies a Lua filter to the Pandoc element. Just as for
+full-document filters, the order in which elements are traversed
+can be controlled by setting the `traverse` field of the filter;
+see the section on [traversal order][Traversal order]. Returns a
+(deep) copy on which the filter has been applied: the original
+element is left untouched.
+
+Parameters:
+
+`self`
+: the element ([Pandoc](#type-pandoc))
+
+`lua_filter`
+: map of filter functions (table)
+
+Result:
+
+- filtered document ([Pandoc][])
+
+Usage:
+
+ -- returns `pandoc.Pandoc{pandoc.Para{pandoc.Str 'Bye'}}`
+ return pandoc.Pandoc{pandoc.Para('Hi')}:walk {
+ Str = function (_) return 'Bye' end,
+ }
+
+
+## Meta {#type-meta}
+
+Meta information on a document; string-indexed collection of
+[MetaValues].
+
+Values of this type can be created with the
+[`pandoc.Meta`](#pandoc.meta) constructor. Meta values are equal
+in Lua if and only if they are equal in Haskell.
+
+## MetaValue {#type-metavalue}
+
+Document meta information items. This is not a separate type, but
+describes a set of types that can be used in places were a
+MetaValue is expected. The types correspond to the following
+Haskell type constructors:
+
+- boolean → MetaBool
+- string or number → MetaString
+- Inlines → MetaInlines
+- Blocks → MetaBlocks
+- List/integer indexed table → MetaList
+- string-indexed table → MetaMap
+
+The corresponding constructors
+[`pandoc.MetaBool`](#pandoc.metabool),
+[`pandoc.MetaString`](#pandoc.metastring),
+[`pandoc.MetaInlines`](#pandoc.metainlines),
+[`pandoc.MetaBlocks`](#pandoc.metablocks),
+[`pandoc.MetaList`](#pandoc.metalist), and
+[`pandoc.MetaMap`](#pandoc.metamap)
+can be used to ensure that a value is treated in the intended
+way. E.g., an empty table is normally treated as a `MetaMap`, but
+can be made into an empty `MetaList` by calling
+`pandoc.MetaList{}`. However, the same can be accomplished by
+using the generic functions like `pandoc.List`, `pandoc.Inlines`,
+or `pandoc.Blocks`.
+
+Use the function [`pandoc.utils.type`](#pandoc.utils.type) to
+get the type of a metadata value.
+
+## Block {#type-block}
+
+Block values are equal in Lua if and only if they are equal in
+Haskell.
+
+### Common methods
+
+#### walk {#type-block:walk}
+
+`walk(self, lua_filter)`
+
+Applies a Lua filter to the block element. Just as for
+full-document filters, the order in which elements are traversed
+can be controlled by setting the `traverse` field of the filter;
+see the section on [traversal order][Traversal order]. Returns a
+(deep) copy on which the filter has been applied: the original
+element is left untouched.
+
+Note that the filter is applied to the subtree, but not to the
+`self` block element. The rationale is that otherwise the element
+could be deleted by the filter, or replaced with multiple block
+elements, which might lead to possibly unexpected results.
+
+Parameters:
+
+`self`
+: the element ([Block](#type-block))
+
+`lua_filter`
+: map of filter functions (table)
+
+Result:
+
+- filtered block ([Block][])
+
+Usage:
+
+ -- returns `pandoc.Para{pandoc.Str 'Bye'}`
+ return pandoc.Para('Hi'):walk {
+ Str = function (_) return 'Bye' end,
+ }
+
+
+### BlockQuote {#type-blockquote}
+
+A block quote element.
+
+Values of this type can be created with the
+[`pandoc.BlockQuote`](#pandoc.BlockQuote) constructor.
+
+Fields:
+
+`content`
+: block content ([Blocks][])
+
+`tag`, `t`
+: the literal `BlockQuote` (string)
+
+### BulletList {#type-bulletlist}
+
+A bullet list.
+
+Values of this type can be created with the
+[`pandoc.BulletList`](#pandoc.BulletList) constructor.
+
+Fields:
+
+`content`
+: list items ([List] of items, i.e., [List] of [Blocks][])
+
+`tag`, `t`
+: the literal `BulletList` (string)
+
+### CodeBlock {#type-codeblock}
+
+Block of code.
+
+Values of this type can be created with the
+[`pandoc.CodeBlock`](#pandoc.CodeBlock) constructor.
+
+Fields:
+
+`text`
+: code string (string)
+
+`attr`
+: element attributes ([Attr])
+
+`identifier`
+: alias for `attr.identifier` (string)
+
+`classes`
+: alias for `attr.classes` ([List] of strings)
+
+`attributes`
+: alias for `attr.attributes` ([Attributes])
+
+`tag`, `t`
+: the literal `CodeBlock` (string)
+
+### DefinitionList {#type-definitionlist}
+
+Definition list, containing terms and their explanation.
+
+Values of this type can be created with the
+[`pandoc.DefinitionList`](#pandoc.DefinitionList) constructor.
+
+Fields:
+
+`content`
+: list of items
+
+`tag`, `t`
+: the literal `DefinitionList` (string)
+
+### Div {#type-div}
+
+Generic block container with attributes.
+
+Values of this type can be created with the
+[`pandoc.Div`](#pandoc.Div) constructor.
+
+Fields:
+
+`content`
+: block content ([Blocks][])
+
+`attr`
+: element attributes ([Attr])
+
+`identifier`
+: alias for `attr.identifier` (string)
+
+`classes`
+: alias for `attr.classes` ([List] of
+ strings)
+
+`attributes`
+: alias for `attr.attributes` ([Attributes])
+
+`tag`, `t`
+: the literal `Div` (string)
+
+### Figure {#type-figure}
+
+Figure with caption and arbitrary block contents.
+
+Values of this type can be created with the
+[`pandoc.Figure`](#pandoc.Figure) constructor.
+
+Fields:
+
+`content`
+: block content ([Blocks][])
+
+`caption`
+: figure caption ([Caption][])
+
+`attr`
+: element attributes ([Attr][])
+
+`identifier`
+: alias for `attr.identifier` (string)
+
+`classes`
+: alias for `attr.classes` ([List][] of strings)
+
+`attributes`
+: alias for `attr.attributes` ([Attributes][])
+
+`tag`, `t`
+: the literal `Figure` (string)
+
+### Header {#type-header}
+
+Creates a header element.
+
+Values of this type can be created with the
+[`pandoc.Header`](#pandoc.Header) constructor.
+
+Fields:
+
+`level`
+: header level (integer)
+
+`content`
+: inline content ([Inlines][])
+
+`attr`
+: element attributes ([Attr])
+
+`identifier`
+: alias for `attr.identifier` (string)
+
+`classes`
+: alias for `attr.classes` ([List] of strings)
+
+`attributes`
+: alias for `attr.attributes`
+ ([Attributes])
+
+`tag`, `t`
+: the literal `Header` (string)
+
+### HorizontalRule {#type-horizontalrule}
+
+A horizontal rule.
+
+Values of this type can be created with the
+[`pandoc.HorizontalRule`](#pandoc.HorizontalRule) constructor.
+
+Fields:
+
+`tag`, `t`
+: the literal `HorizontalRule` (string)
+
+### LineBlock {#type-lineblock}
+
+A line block, i.e. a list of lines, each separated from the next
+by a newline.
+
+Values of this type can be created with the
+[`pandoc.LineBlock`](#pandoc.LineBlock) constructor.
+
+Fields:
+
+`content`
+: inline content ([List] of lines, i.e. [List] of [Inlines][])
+
+`tag`, `t`
+: the literal `LineBlock` (string)
+
+### OrderedList {#type-orderedlist}
+
+An ordered list.
+
+Values of this type can be created with the
+[`pandoc.OrderedList`](#pandoc.OrderedList) constructor.
+
+Fields:
+
+`content`
+: list items ([List] of items, i.e., [List] of [Blocks][])
+
+`listAttributes`
+: list parameters ([ListAttributes])
+
+`start`
+: alias for `listAttributes.start` (integer)
+
+`style`
+: alias for `listAttributes.style` (string)
+
+`delimiter`
+: alias for `listAttributes.delimiter` (string)
+
+`tag`, `t`
+: the literal `OrderedList` (string)
+
+### Para {#type-para}
+
+A paragraph.
+
+Values of this type can be created with the
+[`pandoc.Para`](#pandoc.Para) constructor.
+
+Fields:
+
+`content`
+: inline content ([Inlines][])
+
+`tag`, `t`
+: the literal `Para` (string)
+
+### Plain {#type-plain}
+
+Plain text, not a paragraph.
+
+Values of this type can be created with the
+[`pandoc.Plain`](#pandoc.Plain) constructor.
+
+Fields:
+
+`content`
+: inline content ([Inlines][])
+
+`tag`, `t`
+: the literal `Plain` (string)
+
+### RawBlock {#type-rawblock}
+
+Raw content of a specified format.
+
+Values of this type can be created with the
+[`pandoc.RawBlock`](#pandoc.RawBlock) constructor.
+
+Fields:
+
+`format`
+: format of content (string)
+
+`text`
+: raw content (string)
+
+`tag`, `t`
+: the literal `RawBlock` (string)
+
+### Table {#type-table}
+
+A table.
+
+Values of this type can be created with the
+[`pandoc.Table`](#pandoc.Table) constructor.
+
+Fields:
+
+`attr`
+: table attributes ([Attr])
+
+`caption`
+: table caption ([Caption])
+
+`colspecs`
+: column specifications, i.e., alignments and widths ([List] of
+ [ColSpec]s)
+
+`head`
+: table head ([TableHead])
+
+`bodies`
+: table bodies ([List] of [TableBody]s)
+
+`foot`
+: table foot ([TableFoot])
+
+`identifier`
+: alias for `attr.identifier` (string)
+
+`classes`
+: alias for `attr.classes` ([List] of strings)
+
+`attributes`
+: alias for `attr.attributes` ([Attributes])
+
+`tag`, `t`
+: the literal `Table` (string)
+
+A [table cell]{#type-table-cell} is a list of blocks.
+
+*[Alignment]{#type-alignment}* is a string value indicating the
+horizontal alignment of a table column. `AlignLeft`,
+`AlignRight`, and `AlignCenter` leads cell content to be
+left-aligned, right-aligned, and centered, respectively. The
+default alignment is `AlignDefault` (often equivalent to
+centered).
+
+## Blocks {#type-blocks}
+
+List of [Block] elements, with the same methods as a generic
+[List](#type-list). It is usually not necessary to create values
+of this type in user scripts, as pandoc can convert other types
+into Blocks wherever a value of this type is expected:
+
+- a list of [Block] (or Block-like) values is used directly;
+- a single [Inlines][] value is wrapped into a [Plain] element;
+- string values are turned into an [Inlines][] value by splitting
+ the string into words (see [Inlines](#type-inlines)), and
+ then wrapping the result into a Plain singleton.
+
+### Methods
+
+Lists of type `Blocks` share all methods available in generic
+lists, see the [`pandoc.List` module](#module-pandoc.list).
+
+Additionally, the following methods are available on Blocks
+values:
+
+#### walk {#type-blocks:walk}
+
+`walk(self, lua_filter)`
+
+Applies a Lua filter to the Blocks list. Just as for
+full-document filters, the order in which elements are traversed
+can be controlled by setting the `traverse` field of the filter;
+see the section on [traversal order][Traversal order]. Returns a
+(deep) copy on which the filter has been applied: the original
+list is left untouched.
+
+Parameters:
+
+`self`
+: the list ([Blocks][])
+
+`lua_filter`
+: map of filter functions (table)
+
+Result:
+
+- filtered list ([Blocks][])
+
+Usage:
+
+ -- returns `pandoc.Blocks{pandoc.Para('Salve!')}`
+ return pandoc.Blocks{pandoc.Plain('Salve!)}:walk {
+ Plain = function (p) return pandoc.Para(p.content) end,
+ }
+
+## Inline {#type-inline}
+
+Inline values are equal in Lua if and only if they are equal in
+Haskell.
+
+### Common methods
+
+#### walk {#type-inline:walk}
+
+`walk(self, lua_filter)`
+
+Applies a Lua filter to the Inline element. Just as for
+full-document filters, the order in which elements are traversed
+can be controlled by setting the `traverse` field of the filter;
+see the section on [traversal order][Traversal order]. Returns a
+(deep) copy on which the filter has been applied: the original
+element is left untouched.
+
+Note that the filter is applied to the subtree, but not to the
+`self` inline element. The rationale is that otherwise the
+element could be deleted by the filter, or replaced with multiple
+inline elements, which might lead to possibly unexpected results.
+
+Parameters:
+
+`self`
+: the element ([Inline](#type-inline))
+
+`lua_filter`
+: map of filter functions (table)
+
+Result:
+
+- filtered inline element ([Inline][])
+
+Usage:
+
+ -- returns `pandoc.SmallCaps('SPQR)`
+ return pandoc.SmallCaps('spqr'):walk {
+ Str = function (s) return string.upper(s.text) end,
+ }
+
+### Cite {#type-cite}
+
+Citation.
+
+Values of this type can be created with the
+[`pandoc.Cite`](#pandoc.Cite) constructor.
+
+Fields:
+
+`content`
+: ([Inlines][])
+
+`citations`
+: citation entries ([List] of [Citations])
+
+`tag`, `t`
+: the literal `Cite` (string)
+
+### Code {#type-code}
+
+Inline code
+
+Values of this type can be created with the
+[`pandoc.Code`](#pandoc.Code) constructor.
+
+Fields:
+
+`text`
+: code string (string)
+
+`attr`
+: attributes ([Attr])
+
+`identifier`
+: alias for `attr.identifier` (string)
+
+`classes`
+: alias for `attr.classes` ([List] of strings)
+
+`attributes`
+: alias for `attr.attributes` ([Attributes])
+
+`tag`, `t`
+: the literal `Code` (string)
+
+### Emph {#type-emph}
+
+Emphasized text
+
+Values of this type can be created with the
+[`pandoc.Emph`](#pandoc.Emph) constructor.
+
+Fields:
+
+`content`
+: inline content ([Inlines][])
+
+`tag`, `t`
+: the literal `Emph` (string)
+
+### Image {#type-image}
+
+Image: alt text (list of inlines), target
+
+Values of this type can be created with the
+[`pandoc.Image`](#pandoc.Image) constructor.
+
+Fields:
+
+`caption`
+: text used to describe the image ([Inlines][])
+
+`src`
+: path to the image file (string)
+
+`title`
+: brief image description (string)
+
+`attr`
+: attributes ([Attr])
+
+`identifier`
+: alias for `attr.identifier` (string)
+
+`classes`
+: alias for `attr.classes` ([List] of strings)
+
+`attributes`
+: alias for `attr.attributes` ([Attributes])
+
+`tag`, `t`
+: the literal `Image` (string)
+
+### LineBreak {#type-linebreak}
+
+Hard line break
+
+Values of this type can be created with the
+[`pandoc.LineBreak`](#pandoc.LineBreak) constructor.
+
+Fields:
+
+`tag`, `t`
+: the literal `LineBreak` (string)
+
+### Link {#type-link}
+
+Hyperlink: alt text (list of inlines), target
+
+Values of this type can be created with the
+[`pandoc.Link`](#pandoc.Link) constructor.
+
+Fields:
+
+`attr`
+: attributes ([Attr])
+
+`content`
+: text for this link ([Inlines][])
+
+`target`
+: the link target (string)
+
+`title`
+: brief link description
+
+`identifier`
+: alias for `attr.identifier` (string)
+
+`classes`
+: alias for `attr.classes` ([List] of strings)
+
+`attributes`
+: alias for `attr.attributes` ([Attributes])
+
+`tag`, `t`
+: the literal `Link` (string)
+
+### Math {#type-math}
+
+TeX math (literal)
+
+Values of this type can be created with the
+[`pandoc.Math`](#pandoc.Math) constructor.
+
+Fields:
+
+`mathtype`
+: specifier determining whether the math content should be
+ shown inline (`InlineMath`) or on a separate line
+ (`DisplayMath`) (string)
+
+`text`
+: math content (string)
+
+`tag`, `t`
+: the literal `Math` (string)
+
+### Note {#type-note}
+
+Footnote or endnote
+
+Values of this type can be created with the
+[`pandoc.Note`](#pandoc.Note) constructor.
+
+Fields:
+
+`content`
+: ([Blocks][])
+
+`tag`, `t`
+: the literal `Note` (string)
+
+### Quoted {#type-quoted}
+
+Quoted text
+
+Values of this type can be created with the
+[`pandoc.Quoted`](#pandoc.Quoted) constructor.
+
+Fields:
+
+`quotetype`
+: type of quotes to be used; one of `SingleQuote` or
+ `DoubleQuote` (string)
+
+`content`
+: quoted text ([Inlines][])
+
+`tag`, `t`
+: the literal `Quoted` (string)
+
+### RawInline {#type-rawinline}
+
+Raw inline
+
+Values of this type can be created with the
+[`pandoc.RawInline`](#pandoc.RawInline) constructor.
+
+Fields:
+
+`format`
+: the format of the content (string)
+
+`text`
+: raw content (string)
+
+`tag`, `t`
+: the literal `RawInline` (string)
+
+### SmallCaps {#type-smallcaps}
+
+Small caps text
+
+Values of this type can be created with the
+[`pandoc.SmallCaps`](#pandoc.Smallcaps) constructor.
+
+Fields:
+
+`content`
+: ([Inlines][])
+
+`tag`, `t`
+: the literal `SmallCaps` (string)
+
+### SoftBreak {#type-softbreak}
+
+Soft line break
+
+Values of this type can be created with the
+[`pandoc.SoftBreak`](#pandoc.Softbreak) constructor.
+
+Fields:
+
+`tag`, `t`
+: the literal `SoftBreak` (string)
+
+### Space {#type-space}
+
+Inter-word space
+
+Values of this type can be created with the
+[`pandoc.Space`](#pandoc.Space) constructor.
+
+Fields:
+
+`tag`, `t`
+: the literal `Space` (string)
+
+### Span {#type-span}
+
+Generic inline container with attributes
+
+Values of this type can be created with the
+[`pandoc.Span`](#pandoc.Span) constructor.
+
+Fields:
+
+`attr`
+: attributes ([Attr])
+
+`content`
+: wrapped content ([Inlines][])
+
+`identifier`
+: alias for `attr.identifier` (string)
+
+`classes`
+: alias for `attr.classes` ([List] of strings)
+
+`attributes`
+: alias for `attr.attributes` ([Attributes])
+
+`tag`, `t`
+: the literal `Span` (string)
+
+### Str {#type-str}
+
+Text
+
+Values of this type can be created with the
+[`pandoc.Str`](#pandoc.Str) constructor.
+
+Fields:
+
+`text`
+: content (string)
+
+`tag`, `t`
+: the literal `Str` (string)
+
+### Strikeout {#type-strikeout}
+
+Strikeout text
+
+Values of this type can be created with the
+[`pandoc.Strikeout`](#pandoc.Strikeout) constructor.
+
+Fields:
+
+`content`
+: inline content ([Inlines][])
+
+`tag`, `t`
+: the literal `Strikeout` (string)
+
+### Strong {#type-strong}
+
+Strongly emphasized text
+
+Values of this type can be created with the
+[`pandoc.Strong`](#pandoc.Strong) constructor.
+
+Fields:
+
+`content`
+: inline content ([Inlines][])
+
+`tag`, `t`
+: the literal `Strong` (string)
+
+### Subscript {#type-subscript}
+
+Subscripted text
+
+Values of this type can be created with the
+[`pandoc.Subscript`](#pandoc.Subscript) constructor.
+
+Fields:
+
+`content`
+: inline content ([Inlines][])
+
+`tag`, `t`
+: the literal `Subscript` (string)
+
+### Superscript {#type-superscript}
+
+Superscripted text
+
+Values of this type can be created with the
+[`pandoc.Superscript`](#pandoc.Superscript) constructor.
+
+Fields:
+
+`content`
+: inline content ([Inlines][])
+
+`tag`, `t`
+: the literal `Superscript` (string)
+
+### Underline {#type-underline}
+
+Underlined text
+
+Values of this type can be created with the
+[`pandoc.Underline`](#pandoc.Underline) constructor.
+
+Fields:
+
+`content`
+: inline content ([Inlines][])
+
+`tag`, `t`
+: the literal `Underline` (string)
+
+## Inlines {#type-inlines}
+
+List of [Inline] elements, with the same methods as a generic
+[List](#type-list). It is usually not necessary to create values
+of this type in user scripts, as pandoc can convert other types
+into Inlines wherever a value of this type is expected:
+
+- lists of [Inline] (or Inline-like) values are used directly;
+- single [Inline] values are converted into a list containing
+ just that element;
+- String values are split into words, converting line breaks
+ into [SoftBreak](#type-softbreak) elements, and other
+ whitespace characters into [Spaces](#type-space).
+
+### Methods
+
+Lists of type `Inlines` share all methods available in generic
+lists, see the [`pandoc.List` module](#module-pandoc.list).
+
+Additionally, the following methods are available on *Inlines*
+values:
+
+#### walk {#type-inlines:walk}
+
+`walk(self, lua_filter)`
+
+Applies a Lua filter to the Inlines list. Just as for
+full-document filters, the order in which elements are handled
+are Inline → Inlines → Block → Blocks. The filter is applied
+to all list items *and* to the list itself. Returns a (deep)
+copy on which the filter has been applied: the original list is
+left untouched.
+
+Parameters:
+
+`self`
+: the list ([Inlines](#type-inlines))
+
+`lua_filter`
+: map of filter functions (table)
+
+Result:
+
+- filtered list ([Inlines](#type-inlines))
+
+Usage:
+
+ -- returns `pandoc.Inlines{pandoc.SmallCaps('SPQR')}`
+ return pandoc.Inlines{pandoc.Emph('spqr')}:walk {
+ Str = function (s) return string.upper(s.text) end,
+ Emph = function (e) return pandoc.SmallCaps(e.content) end,
+ }
+
+
+## Element components
+
+### Attr {#type-attr}
+
+A set of element attributes. Values of this type can be created
+with the [`pandoc.Attr`](#pandoc.Attr) constructor. For
+convenience, it is usually not necessary to construct the value
+directly if it is part of an element, and it is sufficient to
+pass an HTML-like table. E.g., to create a span with identifier
+"text" and classes "a" and "b", one can write:
+
+ local span = pandoc.Span('text', {id = 'text', class = 'a b'})
+
+This also works when using the `attr` setter:
+
+ local span = pandoc.Span 'text'
+ span.attr = {id = 'text', class = 'a b', other_attribute = '1'}
+
+Attr values are equal in Lua if and only if they are equal in
+Haskell.
+
+Fields:
+
+`identifier`
+: element identifier (string)
+
+`classes`
+: element classes ([List] of strings)
+
+`attributes`
+: collection of key/value pairs ([Attributes])
+
+### Attributes {#type-attributes}
+
+List of key/value pairs. Values can be accessed by using keys as
+indices to the list table.
+
+Attributes values are equal in Lua if and only if they are equal
+in Haskell.
+
+### Caption {#type-caption}
+
+The caption of a table, with an optional short caption.
+
+Fields:
+
+`long`
+: long caption ([Blocks][])
+
+`short`
+: short caption ([Inlines][])
+
+### Cell {#type-cell}
+
+A table cell.
+
+Fields:
+
+`attr`
+: cell attributes
+
+`alignment`
+: individual cell alignment ([Alignment]).
+
+`contents`
+: cell contents ([Blocks][]).
+
+`col_span`
+: number of columns spanned by the cell; the width of the cell
+ in columns (integer).
+
+`row_span`
+: number of rows spanned by the cell; the height of the cell in
+ rows (integer).
+
+`identifier`
+: alias for `attr.identifier` (string)
+
+`classes`
+: alias for `attr.classes` ([List] of strings)
+
+`attributes`
+: alias for `attr.attributes` ([Attributes])
+
+### Citation {#type-citation}
+
+Single citation entry
+
+Values of this type can be created with the
+[`pandoc.Citation`](#pandoc.citation) constructor.
+
+Citation values are equal in Lua if and only if they are equal in
+Haskell.
+
+Fields:
+
+`id`
+: citation identifier, e.g., a bibtex key (string)
+
+`mode`
+: citation mode, one of `AuthorInText`, `SuppressAuthor`, or
+ `NormalCitation` (string)
+
+`prefix`
+: citation prefix ([Inlines][])
+
+`suffix`
+: citation suffix ([Inlines][])
+
+`note_num`
+: note number (integer)
+
+`hash`
+: hash (integer)
+
+### ColSpec {#type-colspec}
+
+Column alignment and width specification for a single table
+column.
+
+This is a pair, i.e., a plain table, with the following
+components:
+
+1. cell alignment ([Alignment]).
+2. table column width, as a fraction of the page width (number).
+
+### ListAttributes {#type-listattributes}
+
+List attributes
+
+Values of this type can be created with the
+[`pandoc.ListAttributes`](#pandoc.ListAttributes) constructor.
+
+Fields:
+
+`start`
+: number of the first list item (integer)
+
+`style`
+: style used for list numbers; possible values are
+ `DefaultStyle`, `Example`, `Decimal`, `LowerRoman`,
+ `UpperRoman`, `LowerAlpha`, and `UpperAlpha` (string)
+
+`delimiter`
+: delimiter of list numbers; one of `DefaultDelim`, `Period`,
+ `OneParen`, and `TwoParens` (string)
+
+### Row {#type-row}
+
+A table row.
+
+Fields:
+
+`attr`
+: element attributes ([Attr][])
+
+`cells`
+: list of table cells ([List][] of [Cell][]s)
+
+### TableBody {#type-tablebody}
+
+A body of a table, with an intermediate head and the specified
+number of row header columns.
+
+Fields:
+
+`attr`
+: table body attributes ([Attr][])
+
+`body`
+: table body rows ([List][] of [Row][]s)
+
+`head`
+: intermediate head ([List][] of [Row][]s)
+
+`row_head_columns`
+: number of columns taken up by the row head of each row of a
+ [TableBody][]. The row body takes up the remaining columns.
+
+### TableFoot {#type-tablefoot}
+
+The foot of a table.
+
+Fields:
+
+`attr`
+: element attributes ([Attr][])
+
+`rows`
+: list of rows ([List][] of [Row][]s)
+
+`identifier`
+: alias for `attr.identifier` (string)
+
+`classes`
+: alias for `attr.classes` ([List][] of strings)
+
+`attributes`
+: alias for `attr.attributes` ([Attributes][])
+
+### TableHead {#type-tablehead}
+
+The head of a table.
+
+Fields:
+
+`attr`
+: element attributes ([Attr][])
+
+`rows`
+: list of rows ([List][] of [Row][]s)
+
+`identifier`
+: alias for `attr.identifier` (string)
+
+`classes`
+: alias for `attr.classes` ([List][] of strings)
+
+`attributes`
+: alias for `attr.attributes` ([Attributes][])
+
+## ReaderOptions {#type-readeroptions}
+
+Pandoc reader options
+
+Fields:
+
+`abbreviations`
+: set of known abbreviations (set of strings)
+
+`columns`
+: number of columns in terminal (integer)
+
+`default_image_extension`
+: default extension for images (string)
+
+`extensions`
+: string representation of the syntax extensions bit field
+ (sequence of strings)
+
+`indented_code_classes`
+: default classes for indented code blocks (list of strings)
+
+`standalone`
+: whether the input was a standalone document with header
+ (boolean)
+
+`strip_comments`
+: HTML comments are stripped instead of parsed as raw HTML
+ (boolean)
+
+`tab_stop`
+: width (i.e. equivalent number of spaces) of tab stops
+ (integer)
+
+`track_changes`
+: track changes setting for docx; one of `accept-changes`,
+ `reject-changes`, and `all-changes` (string)
+
+## WriterOptions {#type-writeroptions}
+
+Pandoc writer options
+
+Fields:
+
+`chunk_template`
+: Template used to generate chunked HTML filenames (string)
+
+`cite_method`
+: How to print cites -- one of 'citeproc', 'natbib', or
+ 'biblatex' (string)
+
+`columns`
+: Characters in a line (for text wrapping) (integer)
+
+`dpi`
+: DPI for pixel to/from inch/cm conversions (integer)
+
+`email_obfuscation`
+: How to obfuscate emails -- one of 'none', 'references', or
+ 'javascript' (string)
+
+`epub_chapter_level`
+: Header level for chapters, i.e., how the document is split
+ into separate files (integer)
+
+`epub_fonts`
+: Paths to fonts to embed (sequence of strings)
+
+`epub_metadata`
+: Metadata to include in EPUB (string|nil)
+
+`epub_subdirectory`
+: Subdir for epub in OCF (string)
+
+`extensions`
+: Markdown extensions that can be used (sequence of strings)
+
+`highlight_style`
+: Style to use for highlighting; see the output of `pandoc
+ --print-highlight-style=...` for an example structure. The
+ value `nil` means that no highlighting is used. (table|nil)
+
+`html_math_method`
+: How to print math in HTML; one of 'plain', 'mathjax',
+ 'mathml', 'webtex', 'katex', 'gladtex', or a table with keys
+ `method` and `url`. (string|table)
+
+`html_q_tags`
+: Use `<q>` tags for quotes in HTML (boolean)
+
+`identifier_prefix`
+: Prefix for section & note ids in HTML and for footnote marks
+ in markdown (string)
+
+`incremental`
+: True if lists should be incremental (boolean)
+
+`listings`
+: Use listings package for code (boolean)
+
+`number_offset`
+: Starting number for section, subsection, ... (sequence of
+ integers)
+
+`number_sections`
+: Number sections in LaTeX (boolean)
+
+`prefer_ascii`
+: Prefer ASCII representations of characters when possible
+ (boolean)
+
+`reference_doc`
+: Path to reference document if specified (string|nil)
+
+`reference_links`
+: Use reference links in writing markdown, rst (boolean)
+
+`reference_location`
+: Location of footnotes and references for writing markdown;
+ one of 'end-of-block', 'end-of-section', 'end-of-document'.
+ The common prefix may be omitted when setting this value.
+ (string)
+
+`section_divs`
+: Put sections in div tags in HTML (boolean)
+
+`setext_headers`
+: Use setext headers for levels 1-2 in markdown (boolean)
+
+`slide_level`
+: Force header level of slides (integer\|nil)
+
+`tab_stop`
+: Tabstop for conversion btw spaces and tabs (integer)
+
+`table_of_contents`
+: Include table of contents (boolean)
+
+`template`
+: Template to use ([Template](#type-template)|nil)
+
+`toc_depth`
+: Number of levels to include in TOC (integer)
+
+`top_level_division`
+: Type of top-level divisions; one of 'top-level-part',
+ 'top-level-chapter', 'top-level-section', or
+ 'top-level-default'. The prefix `top-level` may be omitted
+ when setting this value. (string)
+
+`variables`
+: Variables to set in template; string-indexed table (table)
+
+`wrap_text`
+: Option for wrapping text; one of 'wrap-auto', 'wrap-none',
+ or 'wrap-preserve'. The `wrap-` prefix may be omitted when
+ setting this value. (string)
+
+
+## CommonState {#type-commonstate}
+
+The state used by pandoc to collect information and make it
+available to readers and writers.
+
+Fields:
+
+`input_files`
+: List of input files from command line
+ ([List] of strings)
+
+`output_file`
+: Output file from command line (string or nil)
+
+`log`
+: A list of log messages ([List] of [LogMessage]s)
+
+`request_headers`
+: Headers to add for HTTP requests; table with header names as
+ keys and header contents as value (table)
+
+`resource_path`
+: Path to search for resources like included images
+ ([List] of strings)
+
+`source_url`
+: Absolute URL or directory of first source file (string or
+ nil)
+
+`user_data_dir`
+: Directory to search for data files (string or nil)
+
+`trace`
+: Whether tracing messages are issued (boolean)
+
+`verbosity`
+: Verbosity level; one of `INFO`, `WARNING`, `ERROR` (string)
+
+## Doc {#type-doc}
+
+Reflowable plain-text document. A Doc value can be rendered and
+reflown to fit a given column width.
+
+The [`pandoc.layout`](#module-pandoc.layout) module can be used to
+create and modify Doc values. All functions in that module that
+take a Doc value as their first argument are also available as Doc
+methods. E.g., `(pandoc.layout.literal 'text'):render()`.
+
+If a string is passed to a function expecting a Doc, then the
+string is treated as a literal value. I.e., the following two
+lines are equivalent:
+
+``` lua
+test = pandoc.layout.quotes(pandoc.layout.literal 'this')
+test = pandoc.layout.quotes('this')
+```
+### Operators {#type-doc-operators}
+
+#### `..` {#type-doc.__concat}
+
+Concatenate two `Doc` elements.
+
+#### `+` {#type-doc.__add}
+
+Concatenate two `Doc`s, inserting a reflowable space between them.
+
+#### `/` {#type-doc.__div}
+
+If `a` and `b` are `Doc` elements, then `a / b` puts `a` above `b`.
+
+#### `//` {#type-doc.__idiv}
+
+If `a` and `b` are `Doc` elements, then `a // b` puts `a` above
+`b`, inserting a blank line between them.
+
+
+## List {#type-list}
+
+A list is any Lua table with integer indices. Indices start at
+one, so if `alist = {'value'}` then `alist[1] == 'value'`.
+
+Lists, when part of an element, or when generated during
+marshaling, are made instances of the `pandoc.List` type for
+convenience. The `pandoc.List` type is defined in the
+[*pandoc.List*](#module-pandoc.list) module. See there for
+available methods.
+
+Values of this type can be created with the
+[`pandoc.List`](#pandoc.list) constructor, turning a normal Lua
+table into a List.
+
+## LogMessage {#type-logmessage}
+
+A pandoc log message. Objects have no fields, but can be
+converted to a string via `tostring`.
+
+## SimpleTable {#type-simpletable}
+
+A simple table is a table structure which resembles the old (pre
+pandoc 2.10) Table type. Bi-directional conversion from and to
+[Tables](#type-table) is possible with the
+[`pandoc.utils.to_simple_table`](#pandoc.utils.to_simple_table)
+and
+[`pandoc.utils.from_simple_table`](#pandoc.utils.from_simple_table)
+function, respectively. Instances of this type can also be created
+directly with the [`pandoc.SimpleTable`](#pandoc.simpletable)
+constructor.
+
+Fields:
+
+`caption`
+: [Inlines][]
+
+`aligns`
+: column alignments ([List] of [Alignments](#type-alignment))
+
+`widths`
+: column widths; a ([List] of numbers)
+
+`headers`
+: table header row ([List] of simple cells, i.e., [List] of
+ [Blocks][])
+
+`rows`
+: table rows ([List] of rows, where a row is a list of simple
+ cells, i.e., [List] of [Blocks][])
+
+## Template {#type-template}
+
+Opaque type holding a compiled template.
+
+## Version {#type-version}
+
+A version object. This represents a software version like
+"2.7.3". The object behaves like a numerically indexed table,
+i.e., if `version` represents the version `2.7.3`, then
+
+ version[1] == 2
+ version[2] == 7
+ version[3] == 3
+ #version == 3 -- length
+
+Comparisons are performed element-wise, i.e.
+
+ Version '1.12' > Version '1.9'
+
+Values of this type can be created with the
+[`pandoc.types.Version`](#pandoc.types.Version) constructor.
+
+### `must_be_at_least`
+
+`must_be_at_least(actual, expected [, error_message])`
+
+Raise an error message if the actual version is older than the
+expected version; does nothing if `actual` is equal to or newer
+than the expected version.
+
+Parameters:
+
+`actual`
+: actual version specifier ([Version])
+
+`expected`
+: minimum expected version ([Version])
+
+`error_message`
+: optional error message template. The string is used as
+ format string, with the expected and actual versions as
+ arguments. Defaults to
+ `"expected version %s or newer, got %s"`.
+
+Usage:
+
+ PANDOC_VERSION:must_be_at_least '2.7.3'
+ PANDOC_API_VERSION:must_be_at_least(
+ '1.17.4',
+ 'pandoc-types is too old: expected version %s, got %s'
+ )
+
+[Attributes]: #type-attributes
+[Cells]: #type-cell
+[Citation]: #type-citation
+[Citations]: #type-citation
+[ColSpec]: #type-colspec
+[CommonState]: #type-commonstate
+[Div]: #type-div
+[Image]: #type-image
+[List]: #type-list
+[ListAttributes]: #type-listattributes
+[Meta]: #type-meta
+[MetaBlocks]: #type-metablocks
+[MetaValue]: #type-metavalue
+[MetaValues]: #type-metavalue
+[LogMessage]: #type-logmessage
+[Pandoc]: #type-pandoc
+[Para]: #type-para
+[Plain]: #type-plain
+[Rows]: #type-row
+[SimpleTable]: #type-simpletable
+[Version]: #type-version
+
+## Chunk {#type-chunk}
+
+Part of a document; usually chunks are each written to a separate
+file.
+
+Fields:
+
+`heading`
+: heading text ([Inlines][])
+
+`id`
+: identifier (string)
+
+`level`
+: level of topmost heading in chunk (integer)
+
+`number`
+: chunk number (integer)
+
+`section_number`
+: hierarchical section number (string)
+
+`path`
+: target filepath for this chunk (string)
+
+`up`
+: link to the enclosing section, if any ([Chunk][]|nil)
+
+`prev`
+: link to the previous section, if any ([Chunk][]|nil)
+
+`next`
+: link to the next section, if any ([Chunk][]|nil)
+
+`unlisted`
+: whether the section in this chunk should be listed in the TOC
+ even if the chunk has no section number. (boolean)
+
+`contents`
+: the chunk's block contents ([Blocks][])
+
+## ChunkedDoc {#type-chunkeddoc}
+
+A Pandoc document divided into [Chunks]{#type-chunk}.
+
+The table of contents info in field `toc` is rose-tree structure
+represented as a list. The node item is always placed at index
+`0`; subentries make up the rest of the list. Each node item
+contains the fields `title` ([Inlines][]), `number` (string|nil),
+`id` (string), `path` (string), and `level` (integer).
+
+Fields:
+
+`chunks`
+: list of chunks that make up the document (list of
+ [Chunks](#type-chunk)).
+
+`meta`
+: the document's metadata ([Meta][])
+
+`toc`
+: table of contents information (table)
+
+<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc -->
+
+# Module pandoc
+
+Fields and functions for pandoc scripts; includes constructors for
+document tree elements, functions to parse text in a given format,
+and functions to filter and modify a subtree.
+
+## Fields {#pandoc-fields}
+
+### readers {#pandoc.readers}
+
+Set of formats that pandoc can parse. All keys in this table can
+be used as the `format` value in `pandoc.read`. (table)
+
+### writers {#pandoc.writers}
+
+Set of formats that pandoc can generate. All keys in this table
+can be used as the `format` value in `pandoc.write`. (table)
+
+## Functions {#pandoc-functions}
+
+### Pandoc {#pandoc.Pandoc}
+
+`Pandoc (blocks[, meta])`
+
+Parameters:
+
+`blocks`
+: document contents ([Blocks])
+
+`meta`
+: document metadata ([Meta])
+
+Returns:
+
+- new Pandoc document ([Pandoc])
+
+### Meta {#pandoc.Meta}
+
+`Meta (meta)`
+
+Parameters:
+
+`meta`
+: table containing meta information (table)
+
+Returns:
+
+- new Meta table (table)
+
+### MetaBlocks {#pandoc.MetaBlocks}
+
+`MetaBlocks (content)`
+
+Creates a value to be used as a MetaBlocks value in meta data;
+creates a copy of the input list via `pandoc.Blocks`, discarding
+all non-list keys.
+
+Parameters:
+
+`content`
+: block content ([Blocks])
+
+Returns:
+
+- list of Block elements ([Blocks])
+
+### MetaBool {#pandoc.MetaBool}
+
+`MetaBool (bool)`
+
+Parameters:
+
+`bool`
+: true or false (boolean)
+
+Returns:
+
+- input, unchanged (boolean)
+
+### MetaInlines {#pandoc.MetaInlines}
+
+`MetaInlines (inlines)`
+
+Creates a value to be used as a MetaInlines value in meta data;
+creates a copy of the input list via `pandoc.Inlines`, discarding
+all non-list keys.
+
+Parameters:
+
+`inlines`
+: inline elements ([Inlines])
+
+Returns:
+
+- list of Inline elements ([Inlines])
+
+### MetaList {#pandoc.MetaList}
+
+`MetaList (values)`
+
+Creates a value to be used as a MetaList in meta data; creates a
+copy of the input list via `pandoc.List`, discarding all non-list
+keys.
+
+Parameters:
+
+`values`
+: value, or list of values ([MetaValue]\|{[MetaValue],\...})
+
+Returns:
+
+- list of meta values ([List]{unknown-type="List"})
+
+### MetaMap {#pandoc.MetaMap}
+
+`MetaMap (key_value_map)`
+
+Creates a value to be used as a MetaMap in meta data; creates a
+copy of the input table, keeping only pairs with string keys and
+discards all other keys.
+
+Parameters:
+
+`key_value_map`
+: a string-indexed map of meta values (table)
+
+Returns:
+
+- map of meta values (table)
+
+### MetaString {#pandoc.MetaString}
+
+`MetaString (s)`
+
+Creates a value to be used as a MetaString in meta data; this is
+the identity function for boolean values and exists only for
+completeness.
+
+Parameters:
+
+`s`
+: string value (string)
+
+Returns:
+
+- unchanged input (string)
+
+### BlockQuote {#pandoc.BlockQuote}
+
+`BlockQuote (content)`
+
+Creates a block quote element
+
+Parameters:
+
+`content`
+: block content ([Blocks])
+
+Returns:
+
+- BlockQuote element ([Block])
+
+### BulletList {#pandoc.BulletList}
+
+`BulletList (items)`
+
+Creates a bullet list.
+
+Parameters:
+
+`items`
+: list items ({[Blocks],\...})
+
+Returns:
+
+- BulletList element ([Block])
+
+### CodeBlock {#pandoc.CodeBlock}
+
+`CodeBlock (text[, attr])`
+
+Creates a code block element.
+
+Parameters:
+
+`text`
+: code string (string)
+
+`attr`
+: element attributes ([Attr])
+
+Returns:
+
+- CodeBlock element ([Block])
+
+### DefinitionList {#pandoc.DefinitionList}
+
+`DefinitionList (content)`
+
+Creates a definition list, containing terms and their explanation.
+
+Parameters:
+
+`content`
+: definition items ([{{Inlines,
+ {Blocks,\...}},\...}]{unknown-type="{{Inlines, {Blocks,...}},...}"})
+
+Returns:
+
+- DefinitionList element ([Block])
+
+### Div {#pandoc.Div}
+
+`Div (content[, attr])`
+
+Creates a div element
+
+Parameters:
+
+`content`
+: block content ([Blocks])
+
+`attr`
+: element attributes ([Attr])
+
+Returns:
+
+- Div element ([Block])
+
+### Figure {#pandoc.Figure}
+
+`Figure (content[, caption[, attr]])`
+
+Creates a [Figure] element.
+
+Parameters:
+
+`content`
+: figure block content ([Blocks])
+
+`caption`
+: figure caption ([Caption])
+
+`attr`
+: element attributes ([Attr])
+
+Returns:
+
+- Figure object ([Block])
+
+### Header {#pandoc.Header}
+
+`Header (level, content[, attr])`
+
+Creates a header element.
+
+Parameters:
+
+`level`
+: heading level ([integer]{unknown-type="integer"})
+
+`content`
+: inline content ([Inlines])
+
+`attr`
+: element attributes ([Attr])
+
+Returns:
+
+- Header element ([Block])
+
+### HorizontalRule {#pandoc.HorizontalRule}
+
+`HorizontalRule ()`
+
+Creates a horizontal rule.
+
+Returns:
+
+- HorizontalRule element ([Block])
+
+### LineBlock {#pandoc.LineBlock}
+
+`LineBlock (content)`
+
+Creates a line block element.
+
+Parameters:
+
+`content`
+: lines ({[Inlines],\...})
+
+Returns:
+
+- LineBlock element ([Block])
+
+### OrderedList {#pandoc.OrderedList}
+
+`OrderedList (items[, listAttributes])`
+
+Creates an ordered list.
+
+Parameters:
+
+`items`
+: list items ({[Blocks],\...})
+
+`listAttributes`
+: list parameters ([ListAttributes])
+
+Returns:
+
+- OrderedList element ([Block])
+
+### Para {#pandoc.Para}
+
+`Para (content)`
+
+Creates a para element.
+
+Parameters:
+
+`content`
+: inline content ([Inlines])
+
+Returns:
+
+- Para element ([Block])
+
+### Plain {#pandoc.Plain}
+
+`Plain (content)`
+
+Creates a plain element.
+
+Parameters:
+
+`content`
+: inline content ([Inlines])
+
+Returns:
+
+- Plain element ([Block])
+
+### RawBlock {#pandoc.RawBlock}
+
+`RawBlock (format, text)`
+
+Creates a raw content block of the specified format.
+
+Parameters:
+
+`format`
+: format of content (string)
+
+`text`
+: raw content (string)
+
+Returns:
+
+- RawBlock element ([Block])
+
+### Table {#pandoc.Table}
+
+`Table (caption, colspecs, head, bodies, foot[, attr])`
+
+Creates a table element.
+
+Parameters:
+
+`caption`
+: table caption ([Caption])
+
+`colspecs`
+: column alignments and widths ({[ColSpec],\...})
+
+`head`
+: table head ([TableHead])
+
+`bodies`
+: table bodies ({[TableBody],\...})
+
+`foot`
+: table foot ([TableFoot])
+
+`attr`
+: element attributes ([Attr])
+
+Returns:
+
+- Table element ([Block])
+
+### Blocks {#pandoc.Blocks}
+
+`Blocks (block_like_elements)`
+
+Creates a [Blocks] list.
+
+Parameters:
+
+`block_like_elements`
+: List where each element can be treated as a [Block] value, or
+ a single such value. ([Blocks])
+
+Returns:
+
+- list of block elements ([Blocks])
+
+### Cite {#pandoc.Cite}
+
+`Cite (content, citations)`
+
+Creates a Cite inline element
+
+Parameters:
+
+`content`
+: placeholder content ([Inlines])
+
+`citations`
+: List of Citations ({[Citation]{unknown-type="Citation"},\...})
+
+Returns:
+
+- cite element ([Inline])
+
+### Code {#pandoc.Code}
+
+`Code (code[, attr])`
+
+Creates a Code inline element
+
+Parameters:
+
+`code`
+: code string (string)
+
+`attr`
+: additional attributes ([Attr])
+
+Returns:
+
+- code element ([Inline])
+
+### Emph {#pandoc.Emph}
+
+`Emph (content)`
+
+Creates an inline element representing emphasized text.
+
+Parameters:
+
+`content`
+: inline content ([Inlines])
+
+Returns:
+
+- new object ([Inline])
+
+### Image {#pandoc.Image}
+
+`Image (caption, src[, title[, attr]])`
+
+Creates an Image element
+
+Parameters:
+
+`caption`
+: text used to describe the image ([Inlines])
+
+`src`
+: path to the image file (string)
+
+`title`
+: brief image description (string)
+
+`attr`
+: image attributes ([Attr])
+
+Returns:
+
+- Image element ([Inline])
+
+### LineBreak {#pandoc.LineBreak}
+
+`LineBreak ()`
+
+Create a LineBreak inline element
+
+Returns:
+
+- line break ([Inline])
+
+### Link {#pandoc.Link}
+
+`Link (content, target[, title[, attr]])`
+
+Creates a link inline element, usually a hyperlink.
+
+Parameters:
+
+`content`
+: text for this link ([Inlines])
+
+`target`
+: the link target (string)
+
+`title`
+: brief link description (string)
+
+`attr`
+: link attributes ([Attr])
+
+Returns:
+
+- link element ([Inline])
+
+### Math {#pandoc.Math}
+
+`Math (mathtype, text)`
+
+Creates a Math element, either inline or displayed.
+
+Parameters:
+
+`mathtype`
+: rendering specifier ([MathType]{unknown-type="MathType"})
+
+`text`
+: math content (string)
+
+Returns:
+
+- math element ([Inline])
+
+### Note {#pandoc.Note}
+
+`Note (content)`
+
+Creates a Note inline element
+
+Parameters:
+
+`content`
+: footnote block content ([Blocks])
+
+Returns:
+
+- note ([Inline])
+
+### Quoted {#pandoc.Quoted}
+
+`Quoted (quotetype, content)`
+
+Creates a Quoted inline element given the quote type and quoted
+content.
+
+Parameters:
+
+`quotetype`
+: type of quotes ([QuoteType]{unknown-type="QuoteType"})
+
+`content`
+: inlines in quotes ([Inlines])
+
+Returns:
+
+- quoted element ([Inline])
+
+### RawInline {#pandoc.RawInline}
+
+`RawInline (format, text)`
+
+Creates a raw inline element
+
+Parameters:
+
+`format`
+: format of content (string)
+
+`text`
+: string content (string)
+
+Returns:
+
+- raw inline element ([Inline])
+
+### SmallCaps {#pandoc.SmallCaps}
+
+`SmallCaps (content)`
+
+Creates text rendered in small caps
+
+Parameters:
+
+`content`
+: inline content ([Inlines])
+
+Returns:
+
+- new object ([Inline])
+
+### SoftBreak {#pandoc.SoftBreak}
+
+`SoftBreak ()`
+
+Creates a SoftBreak inline element.
+
+Returns:
+
+- soft break ([Inline])
+
+### Space {#pandoc.Space}
+
+`Space ()`
+
+Create a Space inline element
+
+Returns:
+
+- new space ([Inline])
+
+### Span {#pandoc.Span}
+
+`Span (content[, attr])`
+
+Creates a Span inline element
+
+Parameters:
+
+`content`
+: inline content ([Inlines])
+
+`attr`
+: additional attributes ([Attr])
+
+Returns:
+
+- [Span] object ([Inline])
+
+### Str {#pandoc.Str}
+
+`Str (text)`
+
+Creates a Str inline element
+
+Parameters:
+
+`text`
+: (string)
+
+Returns:
+
+- [Str] object ([Inline])
+
+### Strikeout {#pandoc.Strikeout}
+
+`Strikeout (content)`
+
+Creates text which is struck out.
+
+Parameters:
+
+`content`
+: inline content ([Inlines])
+
+Returns:
+
+- new object ([Inline])
+
+### Strong {#pandoc.Strong}
+
+`Strong (content)`
+
+Creates a Strong element, whose text is usually displayed in a
+bold font.
+
+Parameters:
+
+`content`
+: inline content ([Inlines])
+
+Returns:
+
+- new object ([Inline])
+
+### Subscript {#pandoc.Subscript}
+
+`Subscript (content)`
+
+Creates a Subscript inline element
+
+Parameters:
+
+`content`
+: inline content ([Inlines])
+
+Returns:
+
+- new object ([Inline])
+
+### Superscript {#pandoc.Superscript}
+
+`Superscript (content)`
+
+Creates a Superscript inline element
+
+Parameters:
+
+`content`
+: inline content ([Inlines])
+
+Returns:
+
+- new object ([Inline])
+
+### Underline {#pandoc.Underline}
+
+`Underline (content)`
+
+Creates an Underline inline element
+
+Parameters:
+
+`content`
+: inline content ([Inlines])
+
+Returns:
+
+- new object ([Inline])
+
+### Inlines {#pandoc.Inlines}
+
+`Inlines (inline_like_elements)`
+
+Converts its argument into an [Inlines] list:
+
+- copies a list of [Inline] elements into a fresh list; any string
+ `s` within the list is treated as `pandoc.Str(s)`;
+- turns a single [Inline] into a singleton list;
+- splits a string into `Str`-wrapped words, treating interword
+ spaces as `Space`s or `SoftBreak`s.
+
+Parameters:
+
+`inline_like_elements`
+: List where each element can be treated as an [Inline] value,
+ or just a single such value. ([Inlines])
+
+Returns:
+
+- list of inline elements ([Inlines])
+
+### Attr {#pandoc.Attr}
+
+`Attr ([identifier[, classes[, attributes]]])`
+
+Create a new set of attributes
+
+Parameters:
+
+`identifier`
+: element identifier (string\|table\|[Attr])
+
+`classes`
+: element classes ({string,\...})
+
+`attributes`
+: table containing string keys and values
+ (table\|[AttributeList])
+
+Returns:
+
+- new Attr object ([Attr])
+
+### Caption {#pandoc.Caption}
+
+`Caption ([long[, short]])`
+
+Creates a new Caption object.
+
+Parameters:
+
+`long`
+: full caption ([Blocks])
+
+`short`
+: short summary caption ([Inlines])
+
+Returns:
+
+- new Caption object ([Caption])
+
+*Since: 3.6.1*
+
+### Cell {#pandoc.Cell}
+
+`Cell (blocks[, align[, rowspan[, colspan[, attr]]]])`
+
+Create a new table cell.
+
+Parameters:
+
+`blocks`
+: cell contents ([Blocks])
+
+`align`
+: text alignment; defaults to `AlignDefault` ([Alignment])
+
+`rowspan`
+: number of rows occupied by the cell; defaults to `1`
+ ([integer]{unknown-type="integer"})
+
+`colspan`
+: number of columns occupied by the cell; defaults to `1`
+ ([integer]{unknown-type="integer"})
+
+`attr`
+: cell attributes ([Attr])
+
+Returns:
+
+- new Cell object ([Cell])
+
+### AttributeList {#pandoc.AttributeList}
+
+`AttributeList (attribs)`
+
+Parameters:
+
+`attribs`
+: an attribute list (table\|[AttributeList])
+
+Returns:
+
+- new AttributeList object ([AttributeList])
+
+### Citation {#pandoc.Citation}
+
+`Citation (id, mode[, prefix[, suffix[, note_num[, hash]]]])`
+
+Creates a single citation.
+
+Parameters:
+
+`id`
+: citation ID (e.g. BibTeX key) (string)
+
+`mode`
+: citation rendering mode
+ ([CitationMode]{unknown-type="CitationMode"})
+
+`prefix`
+: ([Inlines])
+
+`suffix`
+: ([Inlines])
+
+`note_num`
+: note number ([integer]{unknown-type="integer"})
+
+`hash`
+: hash number ([integer]{unknown-type="integer"})
+
+Returns:
+
+- new citation object ([Citation]{unknown-type="Citation"})
+
+### ListAttributes {#pandoc.ListAttributes}
+
+`ListAttributes ([start[, style[, delimiter]]])`
+
+Creates a new ListAttributes object.
+
+Parameters:
+
+`start`
+: number of the first list item
+ ([integer]{unknown-type="integer"})
+
+`style`
+: style used for list numbering (string)
+
+`delimiter`
+: delimiter of list numbers (string)
+
+Returns:
+
+- new ListAttributes object ([ListAttributes])
+
+### Row {#pandoc.Row}
+
+`Row ([cells[, attr]])`
+
+Creates a table row.
+
+Parameters:
+
+`cells`
+: list of table cells in this row ({[Cell],\...})
+
+`attr`
+: row attributes ([Attr])
+
+Returns:
+
+- new Row object ([Row])
+
+### TableFoot {#pandoc.TableFoot}
+
+`TableFoot ([rows[, attr]])`
+
+Creates a table foot.
+
+Parameters:
+
+`rows`
+: list of table rows ({[Row],\...})
+
+`attr`
+: table foot attributes ([Attr])
+
+Returns:
+
+- new TableFoot object ([TableFoot])
+
+### TableHead {#pandoc.TableHead}
+
+`TableHead ([rows[, attr]])`
+
+Creates a table head.
+
+Parameters:
+
+`rows`
+: list of table rows ({[Row],\...})
+
+`attr`
+: table head attributes ([Attr])
+
+Returns:
+
+- new TableHead object ([TableHead])
+
+### SimpleTable {#pandoc.SimpleTable}
+
+`SimpleTable (caption, align, widths, header, rows)`
+
+Usage:
+
+ local caption = "Overview"
+ local aligns = {pandoc.AlignDefault, pandoc.AlignDefault}
+ local widths = {0, 0} -- let pandoc determine col widths
+ local headers = {{pandoc.Plain({pandoc.Str "Language"})},
+ {pandoc.Plain({pandoc.Str "Typing"})}}
+ local rows = {
+ {{pandoc.Plain "Haskell"}, {pandoc.Plain "static"}},
+ {{pandoc.Plain "Lua"}, {pandoc.Plain "Dynamic"}},
+ }
+ simple_table = pandoc.SimpleTable(
+ caption,
+ aligns,
+ widths,
+ headers,
+ rows
+ )
+
+Parameters:
+
+`caption`
+: table caption ([Inlines])
+
+`align`
+: column alignments ({[Alignment],\...})
+
+`widths`
+: relative column widths ({number,\...})
+
+`header`
+: table header row ({[Blocks],\...})
+
+`rows`
+: table rows ({{[Blocks],\...},\...})
+
+Returns:
+
+- new SimpleTable object ([SimpleTable])
+
+<!-- END: AUTOGENERATED CONTENT -->
+
+## Constants
+
+[`AuthorInText`]{#pandoc.authorintext}
+
+: Author name is mentioned in the text.
+
+ See also: [Citation](#type-citation)
+
+[`SuppressAuthor`]{#pandoc.suppressauthor}
+
+: Author name is suppressed.
+
+ See also: [Citation](#type-citation)
+
+[`NormalCitation`]{#pandoc.normalcitation}
+
+: Default citation style is used.
+
+ See also: [Citation](#type-citation)
+
+[`DisplayMath`]{#pandoc.displaymath}
+
+: Math style identifier, marking that the formula should be show
+ in "display" style, i.e., on a separate line.
+
+ See also: [Math](#type-math)
+
+[`InlineMath`]{#pandoc.inlinemath}
+
+: Math style identifier, marking that the formula should be show
+ inline.
+
+ See also: [Math](#type-math)
+
+[`SingleQuote`]{#pandoc.singlequote}
+
+: Quote type used with [Quoted](#type-quoted), indicating
+ that the string is enclosed in *single* quotes.
+
+ See also: [Quoted](#type-quoted)
+
+[`DoubleQuote`]{#pandoc.doublequote}
+
+: Quote type used with [Quoted](#type-quoted), indicating
+ that the string is enclosed in *double* quotes.
+
+ See also: [Quoted](#type-quoted)
+
+[`AlignLeft`]{#pandoc.alignleft}
+
+: Table cells aligned left.
+
+ See also: [Table](#type-alignment)
+
+[`AlignRight`]{#pandoc.alignright}
+
+: Table cells right-aligned.
+
+ See also: [Table](#type-alignment)
+
+[`AlignCenter`]{#pandoc.aligncenter}
+
+: Table cell content is centered.
+
+ See also: [Table](#type-alignment)
+
+[`AlignDefault`]{#pandoc.aligndefault}
+
+: Table cells are alignment is unaltered.
+
+ See also: [Table](#type-alignment)
+
+[`DefaultDelim`]{#pandoc.defaultdelim}
+
+: Default list number delimiters are used.
+
+ See also: [ListAttributes](#type-listattributes)
+
+[`Period`]{#pandoc.period}
+
+: List numbers are delimited by a period.
+
+ See also: [ListAttributes](#type-listattributes)
+
+[`OneParen`]{#pandoc.oneparen}
+
+: List numbers are delimited by a single parenthesis.
+
+ See also: [ListAttributes](#type-listattributes)
+
+[`TwoParens`]{#pandoc.twoparens}
+
+: List numbers are delimited by a double parentheses.
+
+ See also: [ListAttributes](#type-listattributes)
+
+[`DefaultStyle`]{#pandoc.defaultstyle}
+
+: List are numbered in the default style
+
+ See also: [ListAttributes](#type-listattributes)
+
+[`Example`]{#pandoc.example}
+
+: List items are numbered as examples.
+
+ See also: [ListAttributes](#type-listattributes)
+
+[`Decimal`]{#pandoc.decimal}
+
+: List are numbered using decimal integers.
+
+ See also: [ListAttributes](#type-listattributes)
+
+[`LowerRoman`]{#pandoc.lowerroman}
+
+: List are numbered using lower-case roman numerals.
+
+ See also: [ListAttributes](#type-listattributes)
+
+[`UpperRoman`]{#pandoc.upperroman}
+
+: List are numbered using upper-case roman numerals
+
+ See also: [ListAttributes](#type-listattributes)
+
+[`LowerAlpha`]{#pandoc.loweralpha}
+
+: List are numbered using lower-case alphabetic characters.
+
+ See also: [ListAttributes](#type-listattributes)
+
+[`UpperAlpha`]{#pandoc.upperalpha}
+
+: List are numbered using upper-case alphabetic characters.
+
+ See also: [ListAttributes](#type-listattributes)
+
+[`sha1`]{#pandoc.sha1}
+
+: Alias for [`pandoc.utils.sha1`](#pandoc.utils.sha1)
+ (DEPRECATED, use `pandoc.utils.sha1` instead).
+
+## Other constructors
+
+### `ReaderOptions (opts)` {#pandoc.readeroptions}
+
+Creates a new [ReaderOptions] value.
+
+Parameters
+
+`opts`
+: Either a table with a subset of the properties of a
+ [ReaderOptions] object, or another ReaderOptions object.
+ Uses the defaults specified in the manual for all
+ properties that are not explicitly specified. Throws an
+ error if a table contains properties which are not present
+ in a ReaderOptions object. ([ReaderOptions]|table)
+
+Returns: new [ReaderOptions] object
+
+Usage:
+
+ -- copy of the reader options that were defined on the command line.
+ local cli_opts = pandoc.ReaderOptions(PANDOC_READER_OPTIONS)
+
+ -- default reader options, but columns set to 66.
+ local short_colums_opts = pandoc.ReaderOptions {columns = 66}
+
+### `WriterOptions (opts)` {#pandoc.writeroptions}
+
+Creates a new [WriterOptions][] value.
+
+Parameters
+
+`opts`
+: Either a table with a subset of the properties of a
+ [WriterOptions] object, or another WriterOptions object.
+ Uses the defaults specified in the manual for all
+ properties that are not explicitly specified. Throws an
+ error if a table contains properties which are not present
+ in a WriterOptions object. ([WriterOptions]|table)
+
+Returns: new [WriterOptions] object
+
+Usage:
+
+ -- copy of the writer options that were defined on the command line.
+ local cli_opts = pandoc.WriterOptions(PANDOC_WRITER_OPTIONS)
+
+ -- default writer options, but DPI set to 300.
+ local short_colums_opts = pandoc.WriterOptions {dpi = 300}
+
+## Helper functions
+
+### `pipe (command, args, input)` {#pandoc.pipe}
+
+Runs command with arguments, passing it some input, and returns
+the output.
+
+Parameters:
+
+`command`
+: program to run; the executable will be resolved using default
+ system methods (string).
+
+`args`
+: list of arguments to pass to the program (list of strings).
+
+`input`
+: data which is piped into the program via stdin (string).
+
+Returns:
+
+- Output of command, i.e. data printed to stdout (string)
+
+Raises:
+
+- A table containing the keys `command`, `error_code`, and
+ `output` is thrown if the command exits with a non-zero
+ error code.
+
+Usage:
+
+ local output = pandoc.pipe("sed", {"-e","s/a/b/"}, "abc")
+
+### `walk_block (element, filter)` {#pandoc.walk_block}
+
+Apply a filter inside a block element, walking its contents.
+Returns a (deep) copy on which the filter has been applied:
+the original element is left untouched.
+
+Parameters:
+
+`element`
+: the block element
+
+`filter`
+: a Lua filter (table of functions) to be applied within the
+ block element
+
+Returns: the transformed block element
+
+### `walk_inline (element, filter)` {#pandoc.walk_inline}
+
+Apply a filter inside an inline element, walking its contents.
+Returns a (deep) copy on which the filter has been applied:
+the original element is left untouched.
+
+Parameters:
+
+`element`
+: the inline element
+
+`filter`
+: a Lua filter (table of functions) to be applied within the
+ inline element
+
+Returns: the transformed inline element
+
+### `with_state (options, callback)` {#pandoc.with_state}
+
+Runs a function with a modified pandoc state.
+
+The given callback is invoked after setting the pandoc state to the
+given values. The modifiable options are restored to their original
+values once the callback has returned.
+
+The following state variables can be controlled:
+
+ - `request_headers` (list of key-value tuples)
+ - `resource_path` (list of filepaths)
+ - `user_data_dir` (string)
+
+Other options are ignored, and the rest of the state is not modified.
+
+Usage:
+
+ local opts = {
+ request_headers = {
+ {'Authorization', 'Basic my-secret'}
+ }
+ }
+ pandoc.with_state(opts, function ()
+ local mime, contents = pandoc.mediabag.fetch(image_url)
+ )
+
+### `read (markup[, format[, reader_options[, read_env]]])` {#pandoc.read}
+
+Parse the given string into a Pandoc document.
+
+The parser is run in the same environment that was used to read
+the main input files; it has full access to the file-system and
+the mediabag. This means that if the document specifies files to
+be included, as is possible in formats like LaTeX,
+reStructuredText, and Org, then these will be included in the
+resulting document. Any media elements are added to those
+retrieved from the other parsed input files. Use the `read_env`
+parameter to modify this behavior.
+
+The `format` parameter defines the format flavor that will be
+parsed. This can be either a string, using `+` and `-` to enable
+and disable extensions, or a table with fields `format` (string)
+and `extensions` (table). The `extensions` table can be a list of
+all enabled extensions, or a table with extensions as keys and
+their activation status as values (`true` or `'enable'` to enable
+an extension, `false` or `'disable'` to disable it).
+
+Note: The extensions field in `reader_options` is ignored, as the
+function will always use the format extensions specified via the
+`format` parameter.
+
+Parameters:
+
+`markup`
+: the markup to be parsed (string|Sources)
+
+`format`
+: format specification; defaults to `"markdown"`. See the
+ description above for a complete description of this
+ parameter. (string|table)
+
+`reader_options`
+: options passed to the reader; may be a ReaderOptions object or
+ a table with a subset of the keys and values of a
+ ReaderOptions object; defaults to the default values
+ documented in the manual. ([ReaderOptions]|table)
+
+`read_env`
+: If the value is not given or `nil`, then the global
+ environment is used. Passing a list of filenames causes the
+ reader to be run in a sandbox. The given files are read from
+ the file system and provided to the sandbox via an ersatz file
+ system. The table can also contain mappings from filenames to
+ contents, which will be used to populate the ersatz file
+ system.
+
+Returns: pandoc document ([Pandoc](#type-pandoc))
+
+Usage:
+
+ local org_markup = "/emphasis/" -- Input to be read
+ local document = pandoc.read(org_markup, "org")
+ -- Get the first block of the document
+ local block = document.blocks[1]
+ -- The inline element in that block is an `Emph`
+ assert(block.content[1].t == "Emph")
+
+[ReaderOptions]: #type-readeroptions
+
+### `write (doc[, format[, writer_options]])` {#pandoc.write}
+
+Converts a document to the given target format.
+
+Note: The extensions field in `writer_options` is ignored, as the
+function will always use the format extensions specified via the
+`format` parameter.
+
+Parameters:
+
+`doc`
+: document to convert ([Pandoc](#type-pandoc))
+
+`format`
+: format specification; defaults to `"html"`. See the
+ documentation of [`pandoc.read`](#pandoc.read) for a complete
+ description of this parameter. (string|table)
+
+`writer_options`
+: options passed to the writer; may be a WriterOptions object
+ or a table with a subset of the keys and values of a
+ WriterOptions object; defaults to the default values
+ documented in the manual. ([WriterOptions]|table)
+
+Returns:
+- converted document (string)
+
+Usage:
+
+ local doc = pandoc.Pandoc(
+ {pandoc.Para {pandoc.Strong 'Tea'}}
+ )
+ local html = pandoc.write(doc, 'html')
+ assert(html == "<p><strong>Tea</strong></p>")
+
+### `write_classic (doc[, writer_options])` {#pandoc.write_custom}
+
+Runs a classic custom Lua writer, using the functions defined
+in the current environment.
+
+Parameters:
+
+`doc`
+: document to convert ([Pandoc](#type-pandoc))
+
+`writer_options`
+: options passed to the writer; may be a [WriterOptions] object
+ or a table with a subset of the keys and values of a
+ WriterOptions object; defaults to the default values
+ documented in the manual. ([WriterOptions]|table)
+
+Returns:
+- converted document (string)
+
+Usage:
+
+ -- Adding this function converts a classic writer into a
+ -- new-style custom writer.
+ function Writer (doc, opts)
+ PANDOC_DOCUMENT = doc
+ PANDOC_WRITER_OPTIONS = opts
+ loadfile(PANDOC_SCRIPT_FILE)()
+ return pandoc.write_classic(doc, opts)
+ end
+
+[WriterOptions]: #type-writeroptions
+
+<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.cli -->
+
+# Module pandoc.cli
+
+Command line options and argument parsing.
+
+## Fields {#pandoc.cli-fields}
+
+### default_options {#pandoc.cli.default_options}
+
+Default CLI options, using a JSON-like representation. (table)
+
+## Functions {#pandoc.cli-functions}
+
+### parse_options {#pandoc.cli.parse_options}
+
+`parse_options (args)`
+
+Parses command line arguments into pandoc options. Typically this
+function will be used in stand-alone pandoc Lua scripts, taking
+the list of arguments from the global `arg`.
+
+Parameters:
+
+`args`
+: list of command line arguments ({string,\...})
+
+Returns:
+
+- parsed options, using their JSON-like representation. (table)
+
+*Since: 3.0*
+
+### repl {#pandoc.cli.repl}
+
+`repl ([env])`
+
+Starts a read-eval-print loop (REPL). The function returns all
+values of the last evaluated input. Exit the REPL by pressing
+`ctrl-d` or `ctrl-c`; press `F1` to get a list of all key
+bindings.
+
+The REPL is started in the global namespace, unless the `env`
+parameter is specified. In that case, the global namespace is
+merged into the given table and the result is used as `_ENV` value
+for the repl.
+
+Specifically, local variables *cannot* be accessed, unless they
+are explicitly passed via the `env` parameter; e.g.
+
+ function Pandoc (doc)
+ -- start repl, allow to access the `doc` parameter
+ -- in the repl
+ return pandoc.cli.repl{ doc = doc }
+ end
+
+**Note**: it seems that the function exits immediately on Windows,
+without prompting for user input.
+
+Parameters:
+
+`env`
+: Extra environment; the global environment is merged into this
+ table. (table)
+
+Returns:
+
+The result(s) of the last evaluated input, or nothing if the last
+input resulted in an error.
+
+*Since: 3.1.2*
+
+<!-- END: AUTOGENERATED CONTENT -->
+
+<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.utils -->
+
+# Module pandoc.utils
+
+This module exposes internal pandoc functions and utility
+functions.
+
+## Functions {#pandoc.utils-functions}
+
+### blocks_to_inlines {#pandoc.utils.blocks_to_inlines}
+
+`blocks_to_inlines (blocks[, sep])`
+
+Squash a list of blocks into a list of inlines.
+
+Usage
+
+ local blocks = {
+ pandoc.Para{ pandoc.Str 'Paragraph1' },
+ pandoc.Para{ pandoc.Emph 'Paragraph2' }
+ }
+ local inlines = pandoc.utils.blocks_to_inlines(blocks)
+ assert(
+ inlines == pandoc.Inlines {
+ pandoc.Str 'Paragraph1',
+ pandoc.Linebreak(),
+ pandoc.Emph{ pandoc.Str 'Paragraph2' }
+ }
+ )
+
+Parameters:
+
+`blocks`
+: List of [Block] elements to be flattened. ([Blocks])
+
+`sep`
+: List of [Inline] elements inserted as separator between two
+ consecutive blocks; defaults to `{pandoc.LineBreak()}`.
+ ([Inlines])
+
+Returns:
+
+- ([Inlines])
+
+*Since: 2.2.3*
+
+### citeproc {#pandoc.utils.citeproc}
+
+`citeproc (doc)`
+
+Process the citations in the file, replacing them with rendered
+citations and adding a bibliography. See the manual section on
+citation rendering for details.
+
+Usage:
+
+ -- Lua filter that behaves like `--citeproc`
+ function Pandoc (doc)
+ return pandoc.utils.citeproc(doc)
+ end
+
+Parameters:
+
+`doc`
+: document ([Pandoc])
+
+Returns:
+
+- processed document ([Pandoc])
+
+*Since: 2.19.1*
+
+### documentation {#pandoc.utils.documentation}
+
+`documentation (object[, format])`
+
+Return the documentation for a function or module defined by
+pandoc. Throws an error if there is no documentation for the given
+object.
+
+The result format can be any textual format accepted by
+`pandoc.write`, and the documentation will be returned in that
+format. Additionally, the special format `blocks` is accepted, in
+which case the documentation is returned as [Blocks].
+
+Parameters:
+
+`object`
+: Retrieve documentation for this object (any)
+
+`format`
+: result format; defaults to `'ansi'` (string\|table)
+
+Returns:
+
+- rendered documentation (string\|[Blocks])
+
+*Since: 3.8.4*
+
+### equals {#pandoc.utils.equals}
+
+`equals (element1, element2)`
+
+Test equality of AST elements. Elements in Lua are considered
+equal if and only if the objects obtained by unmarshaling are
+equal.
+
+**This function is deprecated.** Use the normal Lua `==` equality
+operator instead.
+
+Parameters:
+
+`element1`
+: (any)
+
+`element2`
+: (any)
+
+Returns:
+
+- Whether the two objects represent the same element (boolean)
+
+*Since: 2.5*
+
+### from_simple_table {#pandoc.utils.from_simple_table}
+
+`from_simple_table (simple_tbl)`
+
+Creates a [Table] block element from a [SimpleTable]. This is
+useful for dealing with legacy code which was written for pandoc
+versions older than 2.10.
+
+Usage:
+
+ local simple = pandoc.SimpleTable(table)
+ -- modify, using pre pandoc 2.10 methods
+ simple.caption = pandoc.SmallCaps(simple.caption)
+ -- create normal table block again
+ table = pandoc.utils.from_simple_table(simple)
+
+Parameters:
+
+`simple_tbl`
+: ([SimpleTable])
+
+Returns:
+
+- table block element ([Block])
+
+*Since: 2.11*
+
+### make_sections {#pandoc.utils.make_sections}
+
+`make_sections (number_sections, baselevel, blocks)`
+
+Converts a list of [Block] elements into sections. `Div`s will be
+created beginning at each `Header` and containing following
+content until the next `Header` of comparable level. If
+`number_sections` is true, a `number` attribute will be added to
+each `Header` containing the section number. If `base_level` is
+non-null, `Header` levels will be reorganized so that there are no
+gaps, and so that the base level is the level specified.
+
+Parameters:
+
+`number_sections`
+: whether section divs should get an additional `number`
+ attribute containing the section number. (boolean)
+
+`baselevel`
+: shift top-level headings to this level (integer\|nil)
+
+`blocks`
+: list of blocks to process ([Blocks])
+
+Returns:
+
+- blocks with sections ([Blocks])
+
+*Since: 2.8*
+
+### normalize_date {#pandoc.utils.normalize_date}
+
+`normalize_date (date)`
+
+Parse a date and convert (if possible) to "YYYY-MM-DD" format. We
+limit years to the range 1601-9999 (ISO 8601 accepts greater than
+or equal to 1583, but MS Word only accepts dates starting 1601).
+Returns nil instead of a string if the conversion failed.
+
+Parameters:
+
+`date`
+: the date string (string)
+
+Returns:
+
+- normalized date, or nil if normalization failed. (string\|nil)
+
+*Since: 2.0.6*
+
+### references {#pandoc.utils.references}
+
+`references (doc)`
+
+Get references defined inline in the metadata and via an external
+bibliography. Only references that are actually cited in the
+document (either with a genuine citation or with `nocite`) are
+returned. URL variables are converted to links.
+
+The structure used represent reference values corresponds to that
+used in CSL JSON; the return value can be use as `references`
+metadata, which is one of the values used by pandoc and citeproc
+when generating bibliographies.
+
+Usage:
+
+ -- Include all cited references in document
+ function Pandoc (doc)
+ doc.meta.references = pandoc.utils.references(doc)
+ doc.meta.bibliography = nil
+ return doc
+ end
+
+Parameters:
+
+`doc`
+: document ([Pandoc])
+
+Returns:
+
+- lift of references. (table)
+
+*Since: 2.17*
+
+### run_json_filter {#pandoc.utils.run_json_filter}
+
+`run_json_filter (doc, filter[, args])`
+
+Filter the given doc by passing it through a JSON filter.
+
+Parameters:
+
+`doc`
+: the Pandoc document to filter ([Pandoc])
+
+`filter`
+: filter to run (string)
+
+`args`
+: list of arguments passed to the filter. Defaults to
+ `{FORMAT}`. ({string,\...})
+
+Returns:
+
+- filtered document ([Pandoc])
+
+*Since: 2.1.1*
+
+### run_lua_filter {#pandoc.utils.run_lua_filter}
+
+`run_lua_filter (doc, filter[, env])`
+
+Filter the given doc by passing it through a Lua filter.
+
+The filter will be run in the current Lua process.
+
+Parameters:
+
+`doc`
+: the Pandoc document to filter ([Pandoc])
+
+`filter`
+: filepath of the filter to run (string)
+
+`env`
+: environment to load and run the filter in (table)
+
+Returns:
+
+- filtered document ([Pandoc])
+
+*Since: 3.2.1*
+
+### sha1 {#pandoc.utils.sha1}
+
+`sha1 (input)`
+
+Computes the SHA1 hash of the given string input.
+
+Parameters:
+
+`input`
+: (string)
+
+Returns:
+
+- hexadecimal hash value (string)
+
+*Since: 2.0.6*
+
+### stringify {#pandoc.utils.stringify}
+
+`stringify (element)`
+
+Converts the given element (Pandoc, Meta, Block, or Inline) into a
+string with all formatting removed.
+
+Parameters:
+
+`element`
+: some pandoc AST element
+ ([Pandoc]\|[Block]\|[Inline]\|[Caption]\|[Cell]\|[MetaValue])
+
+Returns:
+
+- A plain string representation of the given element. (string)
+
+*Since: 2.0.6*
+
+### to_roman_numeral {#pandoc.utils.to_roman_numeral}
+
+`to_roman_numeral (n)`
+
+Converts an integer \< 4000 to uppercase roman numeral.
+
+Usage:
+
+ local to_roman_numeral = pandoc.utils.to_roman_numeral
+ local pandoc_birth_year = to_roman_numeral(2006)
+ -- pandoc_birth_year == 'MMVI'
+
+Parameters:
+
+`n`
+: positive integer below 4000 (integer)
+
+Returns:
+
+- A roman numeral. (string)
+
+*Since: 2.0.6*
+
+### to_simple_table {#pandoc.utils.to_simple_table}
+
+`to_simple_table (tbl)`
+
+Converts a table into an old/simple table.
+
+Usage:
+
+ local simple = pandoc.utils.to_simple_table(table)
+ -- modify, using pre pandoc 2.10 methods
+ simple.caption = pandoc.SmallCaps(simple.caption)
+ -- create normal table block again
+ table = pandoc.utils.from_simple_table(simple)
+
+Parameters:
+
+`tbl`
+: a table ([Block])
+
+Returns:
+
+- SimpleTable object ([SimpleTable])
+
+*Since: 2.11*
+
+### type {#pandoc.utils.type}
+
+`type (value)`
+
+Pandoc-friendly version of Lua's default `type` function,
+returning type information similar to what is presented in the
+manual.
+
+The function works by checking the metafield `__name`. If the
+argument has a string-valued metafield `__name`, then it returns
+that string. Otherwise it behaves just like the normal `type`
+function.
+
+Usage:
+
+ -- Prints one of 'string', 'boolean', 'Inlines', 'Blocks',
+ -- 'table', and 'nil', corresponding to the Haskell constructors
+ -- MetaString, MetaBool, MetaInlines, MetaBlocks, MetaMap,
+ -- and an unset value, respectively.
+
+ function Meta (meta)
+ print('type of metavalue `author`:', pandoc.utils.type(meta.author))
+ end
+
+Parameters:
+
+`value`
+: any Lua value (any)
+
+Returns:
+
+- type of the given value (string)
+
+*Since: 2.17*
+
+### Version {#pandoc.utils.Version}
+
+`Version (v)`
+
+Creates a Version object.
+
+Parameters:
+
+`v`
+: version description
+ ([Version]\|string\|{integer,\...}\|number)
+
+Returns:
+
+- new Version object ([Version])
+
+<!-- END: AUTOGENERATED CONTENT -->
+
+<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.mediabag -->
+
+# Module pandoc.mediabag
+
+The `pandoc.mediabag` module allows accessing pandoc's media
+storage. The "media bag" is used when pandoc is called with the
+`--extract-media` or (for HTML only) `--embed-resources` option.
+
+The module is loaded as part of module `pandoc` and can either be
+accessed via the `pandoc.mediabag` field, or explicitly required,
+e.g.:
+
+ local mb = require 'pandoc.mediabag'
+
+## Functions {#pandoc.mediabag-functions}
+
+### delete {#pandoc.mediabag.delete}
+
+`delete (filepath)`
+
+Removes a single entry from the media bag.
+
+Parameters:
+
+`filepath`
+: Filename of the item to deleted. The media bag will be left
+ unchanged if no entry with the given filename exists. (string)
+
+*Since: 2.7.3*
+
+### empty {#pandoc.mediabag.empty}
+
+`empty ()`
+
+Clear-out the media bag, deleting all items.
+
+*Since: 2.7.3*
+
+### fetch {#pandoc.mediabag.fetch}
+
+`fetch (source)`
+
+Fetches the given source from a URL or local file. Returns two
+values: the contents of the file and the MIME type (or an empty
+string).
+
+The function will first try to retrieve `source` from the
+mediabag; if that fails, it will try to download it or read it
+from the local file system while respecting pandoc's "resource
+path" setting.
+
+Usage:
+
+ local diagram_url = 'https://pandoc.org/diagram.jpg'
+ local mt, contents = pandoc.mediabag.fetch(diagram_url)
+
+Parameters:
+
+`source`
+: path to a resource; either a local file path or URI (string)
+
+Returns:
+
+- The entry's MIME type, or `nil` if the file was not found.
+ (string)
+
+- Contents of the file, or `nil` if the file was not found.
+ (string)
+
+*Since: 2.0*
+
+### fill {#pandoc.mediabag.fill}
+
+`fill (doc)`
+
+Fills the mediabag with the images in the given document. An image
+that cannot be retrieved will be replaced with a Span of class
+"image" that contains the image description.
+
+Images for which the mediabag already contains an item will not be
+processed again.
+
+Parameters:
+
+`doc`
+: document from which to fill the mediabag ([Pandoc])
+
+Returns:
+
+- modified document ([Pandoc])
+
+*Since: 2.19*
+
+### insert {#pandoc.mediabag.insert}
+
+`insert (filepath, mimetype, contents)`
+
+Adds a new entry to pandoc's media bag. Replaces any existing
+media bag entry the same `filepath`.
+
+Usage:
+
+ local fp = 'media/hello.txt'
+ local mt = 'text/plain'
+ local contents = 'Hello, World!'
+ pandoc.mediabag.insert(fp, mt, contents)
+
+Parameters:
+
+`filepath`
+: filename and path relative to the output folder. (string)
+
+`mimetype`
+: the item's MIME type; use `nil` if the MIME type is unknown or
+ unavailable. (string\|nil)
+
+`contents`
+: the binary contents of the file. (string)
+
+*Since: 2.0*
+
+### items {#pandoc.mediabag.items}
+
+`items ()`
+
+Returns an iterator triple to be used with Lua's generic `for`
+statement. The iterator returns the filepath, MIME type, and
+content of a media bag item on each invocation. Items are
+processed one-by-one to avoid excessive memory use.
+
+This function should be used only when full access to all items,
+including their contents, is required. For all other cases,
+[`list`] should be preferred.
+
+Usage:
+
+ for fp, mt, contents in pandoc.mediabag.items() do
+ -- print(fp, mt, contents)
+ end
+
+Returns:
+
+Iterator triple:
+
+- The iterator function; must be called with the iterator state
+ and the current iterator value.
+- Iterator state -- an opaque value to be passed to the iterator
+ function.
+- Initial iterator value.
+
+*Since: 2.7.3*
+
+### list {#pandoc.mediabag.list}
+
+`list ()`
+
+Get a summary of the current media bag contents.
+
+Usage:
+
+ -- calculate the size of the media bag.
+ local mb_items = pandoc.mediabag.list()
+ local sum = 0
+ for i = 1, #mb_items do
+ sum = sum + mb_items[i].length
+ end
+ print(sum)
+
+Returns:
+
+- A list of elements summarizing each entry in the media bag. The
+ summary item contains the keys `path`, `type`, and `length`,
+ giving the filepath, MIME type, and length of contents in bytes,
+ respectively. (table)
+
+*Since: 2.0*
+
+### lookup {#pandoc.mediabag.lookup}
+
+`lookup (filepath)`
+
+Lookup a media item in the media bag, and return its MIME type and
+contents.
+
+Usage:
+
+ local filename = 'media/diagram.png'
+ local mt, contents = pandoc.mediabag.lookup(filename)
+
+Parameters:
+
+`filepath`
+: name of the file to look up. (string)
+
+Returns:
+
+- The entry's MIME type, or nil if the file was not found.
+ (string)
+
+- Contents of the file, or nil if the file was not found. (string)
+
+*Since: 2.0*
+
+### make_data_uri {#pandoc.mediabag.make_data_uri}
+
+`make_data_uri (mime_type, raw_data)`
+
+Convert the input data into a data URI as defined by RFC 2397.
+
+Example:
+
+ -- Embed an unofficial pandoc logo
+ local pandoc_logo_url = 'https://raw.githubusercontent.com/'
+ .. 'tarleb/pandoc-logo/main/pandoc.svg'
+
+ local datauri = pandoc.mediabag.make_data_uri(
+ pandoc.mediabag.fetch(pandoc_logo_url)
+ )
+
+ local image = pandoc.Image('Logo', datauri)
+
+Parameters:
+
+`mime_type`
+: MIME type of the data (string)
+
+`raw_data`
+: data to encode (string)
+
+Returns:
+
+- data uri (string)
+
+*Since: 3.7.1*
+
+### write {#pandoc.mediabag.write}
+
+`write (dir[, fp])`
+
+Writes the contents of mediabag to the given target directory. If
+`fp` is given, then only the resource with the given name will be
+extracted. Omitting that parameter means that the whole mediabag
+gets extracted. An error is thrown if `fp` is given but cannot be
+found in the mediabag.
+
+Parameters:
+
+`dir`
+: path of the target directory (string)
+
+`fp`
+: canonical name (relative path) of resource (string)
+
+*Since: 3.0*
+
+<!-- END: AUTOGENERATED CONTENT -->
+
+# Module pandoc.List
+
+This module defines pandoc's list type. It comes with useful
+methods and convenience functions.
+
+## Constructor
+
+[`pandoc.List([table])`]{#pandoc.list}
+
+: Create a new List. If the optional argument `table` is given,
+ set the metatable of that value to `pandoc.List`. This is an
+ alias for [`pandoc.List:new([table])`](#pandoc.list:new).
+
+## Metamethods
+
+### `pandoc.List:__concat (list)` {#pandoc.list:__concat}
+
+Concatenates two lists.
+
+Parameters:
+
+`list`
+: second list concatenated to the first
+
+Returns: a new list containing all elements from list1 and
+list2
+
+### `pandoc.List:__eq (a, b)` {#pandoc.list:__eq}
+
+Compares two lists for equality. The lists are taken as equal
+if and only if they are of the same type (i.e., have the same
+non-nil metatable), have the same length, and if all elements
+are equal.
+
+Parameters:
+
+`a`, `b`
+: any Lua object
+
+Returns:
+
+- `true` if the two lists are equal, `false` otherwise.
+
+## Methods
+
+### `pandoc.List:at` {#pandoc.list:at}
+
+`:at (index[, default])`
+
+Returns the element at the given index, or `default` if the list
+contains no item at the given position.
+
+Negative integers count back from the last item in the list.
+
+Parameters:
+
+`index`
+: element position (integer)
+
+`default`
+: the default value that is returned if the index is out of
+ range (any)
+
+Returns:
+
+- the list item at `index`, or `default`.
+
+### `pandoc.List:clone ()` {#pandoc.list:clone}
+
+Returns a (shallow) copy of the list. (To get a deep copy
+of the list, use `walk` with an empty filter.)
+
+### `pandoc.List:extend (list)` {#pandoc.list:extend}
+
+Adds the given list to the end of this list.
+
+Parameters:
+
+`list`
+: list to appended
+
+### `pandoc.List:find (needle, init)` {#pandoc.list:find}
+
+Returns the value and index of the first occurrence of the
+given item.
+
+Parameters:
+
+`needle`
+: item to search for
+
+`init`
+: index at which the search is started
+
+Returns: first item equal to the needle, or nil if no such
+item exists.
+
+### `pandoc.List:find_if (pred, init)` {#pandoc.list:find_if}
+
+Returns the value and index of the first element for which
+the predicate holds true.
+
+Parameters:
+
+`pred`
+: the predicate function
+
+`init`
+: index at which the search is started
+
+Returns: first item for which \`test\` succeeds, or nil if
+no such item exists.
+
+### `pandoc.List:filter (pred)` {#pandoc.list:filter}
+
+Returns a new list containing all items satisfying a given
+condition.
+
+Parameters:
+
+`pred`
+: condition items must satisfy.
+
+Returns: a new list containing all items for which \`test\`
+was true.
+
+### `pandoc.List:includes (needle, init)` {#pandoc.list:includes}
+
+Checks if the list has an item equal to the given needle.
+
+Parameters:
+
+`needle`
+: item to search for
+
+`init`
+: index at which the search is started
+
+Returns: true if a list item is equal to the needle, false
+otherwise
+
+### `pandoc.List:insert ([pos], value)` {#pandoc.list:insert}
+
+Inserts element `value` at position `pos` in list, shifting
+elements to the next-greater index if necessary.
+
+This function is identical to
+[`table.insert`](https://www.lua.org/manual/5.4/manual.html#6.6).
+
+Parameters:
+
+`pos`
+: index of the new value; defaults to length of the list + 1
+
+`value`
+: value to insert into the list
+
+### `pandoc.List:iter ([step])` {#pandoc.list:iter}
+
+Create an iterator over the list. The resulting function returns the
+next value each time it is called.
+
+Usage:
+
+ for item in List{1, 1, 2, 3, 5, 8}:iter() do
+ -- process item
+ end
+
+Parameters:
+
+`step`
+: step width with which to step through the list. Negative step sizes
+ will cause the iterator to start from the end of the list. Defaults
+ to 1. (integer)
+
+Returns:
+
+- iterator (function)
+
+### `pandoc.List:map (fn)` {#pandoc.list:map}
+
+Returns a copy of the current list by applying the given
+function to all elements.
+
+Parameters:
+
+`fn`
+: function which is applied to all list items.
+
+### `pandoc.List:new([table])` {#pandoc.list:new}
+
+Create a new List. If the optional argument `table` is given,
+set the metatable of that value to `pandoc.List`.
+
+The function also accepts an iterator, in which case it creates a
+new list from the return values of the iterator function.
+
+Parameters:
+
+`table`
+: table which should be treatable as a list; defaults to an
+ empty table
+
+Returns: the updated input value
+
+### `pandoc.List:remove ([pos])` {#pandoc.list:remove}
+
+Removes the element at position `pos`, returning the value
+of the removed element.
+
+This function is identical to
+[`table.remove`](https://www.lua.org/manual/5.4/manual.html#6.6).
+
+Parameters:
+
+`pos`
+: position of the list value that will be removed; defaults
+ to the index of the last element
+
+Returns: the removed element
+
+### `pandoc.List:sort ([comp])` {#pandoc.list:sort}
+
+Sorts list elements in a given order, in-place. If `comp` is
+given, then it must be a function that receives two list
+elements and returns true when the first element must come
+before the second in the final order (so that, after the
+sort, `i < j` implies `not comp(list[j],list[i]))`. If comp
+is not given, then the standard Lua operator `<` is used
+instead.
+
+Note that the comp function must define a strict partial
+order over the elements in the list; that is, it must be
+asymmetric and transitive. Otherwise, no valid sort may be
+possible.
+
+The sort algorithm is not stable: elements considered equal
+by the given order may have their relative positions changed
+by the sort.
+
+This function is identical to
+[`table.sort`](https://www.lua.org/manual/5.4/manual.html#6.6).
+
+Parameters:
+
+`comp`
+: Comparison function as described above.
+
+<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.format -->
+
+# Module pandoc.format
+
+Information about the formats supported by pandoc.
+
+## Functions {#pandoc.format-functions}
+
+### all_extensions {#pandoc.format.all_extensions}
+
+`all_extensions (format)`
+
+Returns the list of all valid extensions for a format. No
+distinction is made between input and output; an extension can
+have an effect when reading a format but not when writing it, or
+*vice versa*.
+
+Parameters:
+
+`format`
+: format name (string)
+
+Returns:
+
+- all extensions supported for `format` ([FormatExtensions])
+
+*Since: 3.0*
+
+### default_extensions {#pandoc.format.default_extensions}
+
+`default_extensions (format)`
+
+Returns the list of default extensions of the given format; this
+function does not check if the format is supported, it will return
+a fallback list of extensions even for unknown formats.
+
+Parameters:
+
+`format`
+: format name (string)
+
+Returns:
+
+- default extensions enabled for `format` ([FormatExtensions])
+
+*Since: 3.0*
+
+### extensions {#pandoc.format.extensions}
+
+`extensions (format)`
+
+Returns the extension configuration for the given format. The
+configuration is represented as a table with all supported
+extensions as keys and their default status as value, with `true`
+indicating that the extension is enabled by default, while `false`
+marks a supported extension that's disabled.
+
+This function can be used to assign a value to the `Extensions`
+global in custom readers and writers.
+
+Parameters:
+
+`format`
+: format identifier (string)
+
+Returns:
+
+- extensions config (table)
+
+*Since: 3.0*
+
+### from_path {#pandoc.format.from_path}
+
+`from_path (path)`
+
+Parameters:
+
+`path`
+: file path, or list of paths (string\|{string,\...})
+
+Returns:
+
+- format determined by heuristic (string\|nil)
+
+*Since: 3.1.2*
+
+<!-- END: AUTOGENERATED CONTENT -->
+
+<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.image -->
+
+# Module pandoc.image
+
+Basic image querying functions.
+
+## Functions {#pandoc.image-functions}
+
+### size {#pandoc.image.size}
+
+`size (image[, opts])`
+
+Returns a table containing the size and resolution of an image;
+throws an error if the given string is not an image, or if the
+size of the image cannot be determined.
+
+The resulting table has four entries: *width*, *height*,
+*dpi_horz*, and *dpi_vert*.
+
+The `opts` parameter, when given, should be either a WriterOptions
+object such as `PANDOC_WRITER_OPTIONS`, or a table with a `dpi`
+entry. It affects the calculation for vector image formats such as
+SVG.
+
+Parameters:
+
+`image`
+: image data (string)
+
+`opts`
+: writer options ([WriterOptions]\|table)
+
+Returns:
+
+- image size information or error message (table)
+
+*Since: 3.1.13*
+
+### format {#pandoc.image.format}
+
+`format (image)`
+
+Returns the format of an image as a lowercase string.
+
+Formats recognized by pandoc include *png*, *gif*, *tiff*, *jpeg*,
+*pdf*, *svg*, *eps*, and *emf*.
+
+Parameters:
+
+`image`
+: binary image data (string)
+
+Returns:
+
+- image format, or nil if the format cannot be determined
+ (string\|nil)
+
+*Since: 3.1.13*
+
+<!-- END: AUTOGENERATED CONTENT -->
+
+<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.json -->
+
+# Module pandoc.json
+
+JSON module to work with JSON; based on the Aeson Haskell package.
+
+## Fields {#pandoc.json-fields}
+
+### null {#pandoc.json.null}
+
+Value used to represent the `null` JSON value. (light userdata)
+
+## Functions {#pandoc.json-functions}
+
+### decode {#pandoc.json.decode}
+
+`decode (str[, pandoc_types])`
+
+Creates a Lua object from a JSON string. If the input can be
+decoded as representing an [Inline], [Block], [Pandoc], [Inlines],
+or [Blocks] element the function will return an object of the
+appropriate type. Otherwise, if the input does not represent any
+of the AST types, the default decoding is applied: Objects and
+arrays are represented as tables, the JSON `null` value becomes
+[null], and JSON booleans, strings, and numbers are converted
+using the Lua types of the same name.
+
+The special handling of AST elements can be disabled by setting
+`pandoc_types` to `false`.
+
+Parameters:
+
+`str`
+: JSON string (string)
+
+`pandoc_types`
+: whether to use pandoc types when possible. (boolean)
+
+Returns:
+
+- decoded object (any)
+
+*Since: 3.1.1*
+
+### encode {#pandoc.json.encode}
+
+`encode (object)`
+
+Encodes a Lua object as JSON string.
+
+If the object has a metamethod with name `__tojson`, then the
+result is that of a call to that method with `object` passed as
+the sole argument. The result of that call is expected to be a
+valid JSON string, but this is not checked.
+
+Parameters:
+
+`object`
+: object to convert (any)
+
+Returns:
+
+- JSON encoding of the given `object` (string)
+
+*Since: 3.1.1*
+
+<!-- END: AUTOGENERATED CONTENT -->
+
+<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.log -->
+
+# Module pandoc.log
+
+Access to pandoc's logging system.
+
+## Functions {#pandoc.log-functions}
+
+### info {#pandoc.log.info}
+
+`info (message)`
+
+Reports a ScriptingInfo message to pandoc's logging system.
+
+Parameters:
+
+`message`
+: the info message (string)
+
+*Since: 3.2*
+
+### silence {#pandoc.log.silence}
+
+`silence (fn)`
+
+Applies the function to the given arguments while preventing log
+messages from being added to the log. The warnings and info
+messages reported during the function call are returned as the
+first return value, with the results of the function call
+following thereafter.
+
+Parameters:
+
+`fn`
+: function to be silenced (function)
+
+Returns:
+
+List of log messages triggered during the function call, and any
+value returned by the function.
+
+*Since: 3.2*
+
+### warn {#pandoc.log.warn}
+
+`warn (message)`
+
+Reports a ScriptingWarning to pandoc's logging system. The warning
+will be printed to stderr unless logging verbosity has been set to
+*ERROR*.
+
+Parameters:
+
+`message`
+: the warning message (string)
+
+*Since: 3.2*
+
+<!-- END: AUTOGENERATED CONTENT -->
+
+<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.path -->
+
+# Module pandoc.path
+
+Module for file path manipulations.
+
+## Fields {#pandoc.path-fields}
+
+### separator {#pandoc.path.separator}
+
+The character that separates directories. (string)
+
+### search_path_separator {#pandoc.path.search_path_separator}
+
+The character that is used to separate the entries in the `PATH`
+environment variable. (string)
+
+## Functions {#pandoc.path-functions}
+
+### directory {#pandoc.path.directory}
+
+`directory (filepath)`
+
+Gets the directory name, i.e., removes the last directory
+separator and everything after from the given path.
+
+Parameters:
+
+`filepath`
+: path (string)
+
+Returns:
+
+- The filepath up to the last directory separator. (string)
+
+*Since: 2.12*
+
+### exists {#pandoc.path.exists}
+
+`exists (path[, type])`
+
+Check whether there exists a filesystem object at the given path.
+If `type` is given and either *directory* or *file*, then the
+function returns `true` if and only if the file system object has
+the given type, or if it's a symlink pointing to an object of that
+type. Passing *symlink* as type requires the path itself to be a
+symlink. Types other than those will cause an error.
+
+Parameters:
+
+`path`
+: file path to check (string)
+
+`type`
+: the required type of the filesystem object (string)
+
+Returns:
+
+- whether a filesystem object of type `type` exists at `path`.
+ (boolean)
+
+*Since: 3.7.1*
+
+### filename {#pandoc.path.filename}
+
+`filename (filepath)`
+
+Get the file name.
+
+Parameters:
+
+`filepath`
+: path (string)
+
+Returns:
+
+- File name part of the input path. (string)
+
+*Since: 2.12*
+
+### is_absolute {#pandoc.path.is_absolute}
+
+`is_absolute (filepath)`
+
+Checks whether a path is absolute, i.e. not fixed to a root.
+
+Parameters:
+
+`filepath`
+: path (string)
+
+Returns:
+
+- `true` iff `filepath` is an absolute path, `false` otherwise.
+ (boolean)
+
+*Since: 2.12*
+
+### is_relative {#pandoc.path.is_relative}
+
+`is_relative (filepath)`
+
+Checks whether a path is relative or fixed to a root.
+
+Parameters:
+
+`filepath`
+: path (string)
+
+Returns:
+
+- `true` iff `filepath` is a relative path, `false` otherwise.
+ (boolean)
+
+*Since: 2.12*
+
+### join {#pandoc.path.join}
+
+`join (filepaths)`
+
+Join path elements back together by the directory separator.
+
+Parameters:
+
+`filepaths`
+: path components ({string,\...})
+
+Returns:
+
+- The joined path. (string)
+
+*Since: 2.12*
+
+### make_relative {#pandoc.path.make_relative}
+
+`make_relative (path, root[, unsafe])`
+
+Contract a filename, based on a relative path. Note that the
+resulting path will never introduce `..` paths, as the presence of
+symlinks means `../b` may not reach `a/b` if it starts from `a/c`.
+For a worked example see [this blog post].
+
+Parameters:
+
+`path`
+: path to be made relative (string)
+
+`root`
+: root path (string)
+
+`unsafe`
+: whether to allow `..` in the result. (boolean)
+
+Returns:
+
+- contracted filename (string)
+
+*Since: 2.12*
+
+### normalize {#pandoc.path.normalize}
+
+`normalize (filepath)`
+
+Normalizes a path.
+
+- `//` makes sense only as part of a (Windows) network drive;
+ elsewhere, multiple slashes are reduced to a single
+ `path.separator` (platform dependent).
+- `/` becomes `path.separator` (platform dependent).
+- `./` is removed.
+- an empty path becomes `.`
+
+Parameters:
+
+`filepath`
+: path (string)
+
+Returns:
+
+- The normalized path. (string)
+
+*Since: 2.12*
+
+### split {#pandoc.path.split}
+
+`split (filepath)`
+
+Splits a path by the directory separator.
+
+Parameters:
+
+`filepath`
+: path (string)
+
+Returns:
+
+- List of all path components. ({string,\...})
+
+*Since: 2.12*
+
+### split_extension {#pandoc.path.split_extension}
+
+`split_extension (filepath)`
+
+Splits the last extension from a file path and returns the parts.
+The extension, if present, includes the leading separator; if the
+path has no extension, then the empty string is returned as the
+extension.
+
+Parameters:
+
+`filepath`
+: path (string)
+
+Returns:
+
+- filepath without extension (string)
+
+- extension or empty string (string)
+
+*Since: 2.12*
+
+### split_search_path {#pandoc.path.split_search_path}
+
+`split_search_path (search_path)`
+
+Takes a string and splits it on the `search_path_separator`
+character. Blank items are ignored on Windows, and converted to
+`.` on Posix. On Windows path elements are stripped of quotes.
+
+Parameters:
+
+`search_path`
+: platform-specific search path (string)
+
+Returns:
+
+- list of directories in search path ({string,\...})
+
+*Since: 2.12*
+
+### treat_strings_as_paths {#pandoc.path.treat_strings_as_paths}
+
+`treat_strings_as_paths ()`
+
+Augment the string module such that strings can be used as path
+objects.
+
+*Since: 2.12*
+
+<!-- END: AUTOGENERATED CONTENT -->
+
+<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.structure -->
+
+# Module pandoc.structure
+
+Access to the higher-level document structure, including
+hierarchical sections and the table of contents.
+
+## Functions {#pandoc.structure-functions}
+
+### make_sections {#pandoc.structure.make_sections}
+
+`make_sections (blocks[, opts])`
+
+Puts [Blocks] into a hierarchical structure: a list of sections
+(each a Div with class "section" and first element a Header).
+
+The optional `opts` argument can be a table; two settings are
+recognized: If `number_sections` is true, a `number` attribute
+containing the section number will be added to each `Header`. If
+`base_level` is an integer, then `Header` levels will be
+reorganized so that there are no gaps, with numbering levels
+shifted by the given value. Finally, an integer `slide_level`
+value triggers the creation of slides at that heading level.
+
+Note that a [WriterOptions] object can be passed as the opts
+table; this will set the `number_section` and `slide_level` values
+to those defined on the command line.
+
+Usage:
+
+ local blocks = {
+ pandoc.Header(2, pandoc.Str 'first'),
+ pandoc.Header(2, pandoc.Str 'second'),
+ }
+ local opts = PANDOC_WRITER_OPTIONS
+ local newblocks = pandoc.structure.make_sections(blocks, opts)
+
+Parameters:
+
+`blocks`
+: document blocks to process ([Blocks]\|[Pandoc])
+
+`opts`
+: options (table)
+
+Returns:
+
+- processed blocks ([Blocks])
+
+*Since: 3.0*
+
+### slide_level {#pandoc.structure.slide_level}
+
+`slide_level (blocks)`
+
+Find level of header that starts slides (defined as the least
+header level that occurs before a non-header/non-hrule in the
+blocks).
+
+Parameters:
+
+`blocks`
+: document body ([Blocks]\|[Pandoc])
+
+Returns:
+
+- slide level (integer)
+
+*Since: 3.0*
+
+### split_into_chunks {#pandoc.structure.split_into_chunks}
+
+`split_into_chunks (doc[, opts])`
+
+Converts a [Pandoc] document into a [ChunkedDoc].
+
+Parameters:
+
+`doc`
+: document to split ([Pandoc])
+
+`opts`
+
+: Splitting options.
+
+ The following options are supported:
+
+ `path_template`
+ : template used to generate the chunks' filepaths
+ `%n` will be replaced with the chunk number (padded with
+ leading 0s to 3 digits), `%s` with the section number of
+ the heading, `%h` with the (stringified) heading text,
+ `%i` with the section identifier. For example,
+ `"section-%s-%i.html"` might be resolved to
+ `"section-1.2-introduction.html"`.
+
+ Default is `"chunk-%n"` (string)
+
+ `number_sections`
+ : whether sections should be numbered; default is `false`
+ (boolean)
+
+ `chunk_level`
+ : The heading level the document should be split into
+ chunks. The default is to split at the top-level, i.e.,
+ `1`. (integer)
+
+ `base_heading_level`
+ : The base level to be used for numbering. Default is `nil`
+ (integer|nil)
+
+ (table)
+
+Returns:
+
+- ([ChunkedDoc])
+
+*Since: 3.0*
+
+### table_of_contents {#pandoc.structure.table_of_contents}
+
+`table_of_contents (toc_source[, opts])`
+
+Generates a table of contents for the given object.
+
+Parameters:
+
+`toc_source`
+: list of command line arguments
+ ([Blocks]\|[Pandoc]\|[ChunkedDoc])
+
+`opts`
+: options ([WriterOptions])
+
+Returns:
+
+- Table of contents as a BulletList object ([Block])
+
+*Since: 3.0*
+
+### unique_identifier {#pandoc.structure.unique_identifier}
+
+`unique_identifier (inlines[, used[, exts]])`
+
+Generates a unique identifier from a list of inlines, similar to
+what's generated by the `auto_identifiers` extension.
+
+The method used to generated identifiers can be modified through
+`ext`, which is a list of format extensions.
+
+It can be used to generate IDs similar to what the
+`auto_identifiers` extension provides.
+
+Example:
+
+ local used_ids = {}
+ function Header (h)
+ local id =
+ pandoc.structure.unique_identifier(h.content, used_ids)
+ used_ids[id] = true
+ h.identifier = id
+ return h
+ end
+
+Parameters:
+
+`inlines`
+: base for identifier ([Inlines])
+
+`used`
+: set of identifiers (string keys, boolean values) that have
+ already been used. (table)
+
+`exts`
+: list of format extensions ({string,\...})
+
+Returns:
+
+- unique identifier (string)
+
+*Since: 3.8*
+
+<!-- END: AUTOGENERATED CONTENT -->
+
+<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.system -->
+
+# Module pandoc.system
+
+Access to the system's information and file functionality.
+
+## Fields {#pandoc.system-fields}
+
+### arch {#pandoc.system.arch}
+
+The machine architecture on which the program is running. (string)
+
+### os {#pandoc.system.os}
+
+The operating system on which the program is running. The most
+common values are `darwin` (macOS), `freebsd`, `linux`,
+`linux-android`, `mingw32` (Windows), `netbsd`, `openbsd`.
+(string)
+
+## Functions {#pandoc.system-functions}
+
+### cputime {#pandoc.system.cputime}
+
+`cputime ()`
+
+Returns the number of picoseconds CPU time used by the current
+program. The precision of this result may vary in different
+versions and on different platforms.
+
+Returns:
+
+- CPU time in picoseconds (integer)
+
+*Since: 3.1.1*
+
+### command {#pandoc.system.command}
+
+`command (command, args[, input[, opts]])`
+
+Executes a system command with the given arguments and `input` on
+*stdin*.
+
+Parameters:
+
+`command`
+: command to execute (string)
+
+`args`
+: command arguments ({string,\...})
+
+`input`
+: input on stdin (string)
+
+`opts`
+: process options (table)
+
+Returns:
+
+- exit code -- `false` on success, an integer otherwise
+ (integer\|boolean)
+
+- stdout (string)
+
+- stderr (string)
+
+*Since: 3.7.1*
+
+### copy {#pandoc.system.copy}
+
+`copy (source, target)`
+
+Copy a file with its permissions. If the destination file already
+exists, it is overwritten.
+
+Parameters:
+
+`source`
+: source file (string)
+
+`target`
+: target destination (string)
+
+*Since: 3.7.1*
+
+### environment {#pandoc.system.environment}
+
+`environment ()`
+
+Retrieves the entire environment as a string-indexed table.
+
+Returns:
+
+- A table mapping environment variable names to their value.
+ (table)
+
+*Since: 2.7.3*
+
+### get_working_directory {#pandoc.system.get_working_directory}
+
+`get_working_directory ()`
+
+Obtain the current working directory as an absolute path.
+
+Returns:
+
+- The current working directory. (string)
+
+*Since: 2.8*
+
+### list_directory {#pandoc.system.list_directory}
+
+`list_directory ([directory])`
+
+List the contents of a directory.
+
+Parameters:
+
+`directory`
+: Path of the directory whose contents should be listed.
+ Defaults to `.`. (string)
+
+Returns:
+
+- A table of all entries in `directory`, except for the special
+ entries (`.` and `..`). (table)
+
+*Since: 2.19*
+
+### make_directory {#pandoc.system.make_directory}
+
+`make_directory (dirname[, create_parent])`
+
+Create a new directory which is initially empty, or as near to
+empty as the operating system allows. The function throws an error
+if the directory cannot be created, e.g., if the parent directory
+does not exist or if a directory of the same name is already
+present.
+
+If the optional second parameter is provided and truthy, then all
+directories, including parent directories, are created as
+necessary.
+
+Parameters:
+
+`dirname`
+: name of the new directory (string)
+
+`create_parent`
+: create parent directory if necessary (boolean)
+
+*Since: 2.19*
+
+### read_file {#pandoc.system.read_file}
+
+`read_file (filepath)`
+
+Parameters:
+
+`filepath`
+: File to read (string)
+
+Returns:
+
+- file contents (string)
+
+*Since: 3.7.1*
+
+### rename {#pandoc.system.rename}
+
+`rename (old, new)`
+
+Change the name of an existing path from `old` to `new`.
+
+If `old` is a directory and `new` is a directory that already
+exists, then `new` is atomically replaced by the `old` directory.
+On Win32 platforms, this function fails if `new` is an existing
+directory.
+
+If `old` does not refer to a directory, then neither may `new`.
+
+Renaming may not work across file system boundaries or due to
+other system-specific reasons. It's generally more robust to copy
+the source path to its destination before deleting the source.
+
+Parameters:
+
+`old`
+: original path (string)
+
+`new`
+: new path (string)
+
+*Since: 3.7.1*
+
+### remove {#pandoc.system.remove}
+
+`remove (filename)`
+
+Removes the directory entry for an existing file.
+
+Parameters:
+
+`filename`
+: file to remove (string)
+
+*Since: 3.7.1*
+
+### remove_directory {#pandoc.system.remove_directory}
+
+`remove_directory (dirname[, recursive])`
+
+Remove an existing, empty directory. If `recursive` is given, then
+delete the directory and its contents recursively.
+
+Parameters:
+
+`dirname`
+: name of the directory to delete (string)
+
+`recursive`
+: delete content recursively (boolean)
+
+*Since: 2.19*
+
+### times {#pandoc.system.times}
+
+`times (filepath)`
+
+Obtain the modification and access time of a file or directory.
+The times are returned as strings using the ISO 8601 format.
+
+Parameters:
+
+`filepath`
+: file or directory path (string)
+
+Returns:
+
+- time at which the file or directory was last modified (table)
+
+- time at which the file or directory was last accessed (table)
+
+*Since: 3.7.1*
+
+### with_environment {#pandoc.system.with_environment}
+
+`with_environment (environment, callback)`
+
+Run an action within a custom environment. Only the environment
+variables given by `environment` will be set, when `callback` is
+called. The original environment is restored after this function
+finishes, even if an error occurs while running the callback
+action.
+
+Parameters:
+
+`environment`
+: Environment variables and their values to be set before
+ running `callback` (table)
+
+`callback`
+: Action to execute in the custom environment (function)
+
+Returns:
+
+The results of the call to `callback`.
+
+*Since: 2.7.3*
+
+### with_temporary_directory {#pandoc.system.with_temporary_directory}
+
+`with_temporary_directory (parent_dir, templ, callback)`
+
+Create and use a temporary directory inside the given directory.
+The directory is deleted after the callback returns.
+
+Parameters:
+
+`parent_dir`
+: Parent directory to create the directory in. If this parameter
+ is omitted, the system's canonical temporary directory is
+ used. (string)
+
+`templ`
+: Directory name template. (string)
+
+`callback`
+: Function which takes the name of the temporary directory as
+ its first argument. (function)
+
+Returns:
+
+The results of the call to `callback`.
+
+*Since: 2.8*
+
+### with_working_directory {#pandoc.system.with_working_directory}
+
+`with_working_directory (directory, callback)`
+
+Run an action within a different directory. This function will
+change the working directory to `directory`, execute `callback`,
+then switch back to the original working directory, even if an
+error occurs while running the callback action.
+
+Parameters:
+
+`directory`
+: Directory in which the given `callback` should be executed
+ (string)
+
+`callback`
+: Action to execute in the given directory (function)
+
+Returns:
+
+The results of the call to `callback`.
+
+*Since: 2.7.3*
+
+### write_file {#pandoc.system.write_file}
+
+`write_file (filepath, contents)`
+
+Writes a string to a file.
+
+Parameters:
+
+`filepath`
+: path to target file (string)
+
+`contents`
+: file contents (string)
+
+*Since: 3.7.1*
+
+### xdg {#pandoc.system.xdg}
+
+`xdg (xdg_directory_type[, filepath])`
+
+Access special directories and directory search paths.
+
+Special directories for storing user-specific application data,
+configuration, and cache files, as specified by the [XDG Base
+Directory Specification].
+
+Parameters:
+
+`xdg_directory_type`
+
+: The type of the XDG directory or search path. Must be one of
+ `config`, `data`, `cache`, `state`, `datadirs`, or
+ `configdirs`.
+
+ Matching is case-insensitive, and underscores and `XDG`
+ prefixes are ignored, so a value like `XDG_DATA_DIRS` is also
+ acceptable.
+
+ The `state` directory might not be available, depending on the
+ version of the underlying Haskell library. (string)
+
+`filepath`
+: relative path that is appended to the path; ignored if the
+ result is a list of search paths. (string)
+
+Returns:
+
+- Either a single file path, or a list of search paths.
+ (string\|{string,\...})
+
+*Since: 3.7.1*
+
+<!-- END: AUTOGENERATED CONTENT -->
+
+
+<!-- Auto-generation temporarily disabled; needs updates in the documenation
+renderer and in `hslua-packaging`. -->
+
+<!-- BEGIN DISABLED: AUTOGENERATED CONTENT for module pandoc.layout -->
+
+# Module pandoc.layout
+
+Plain-text document layouting.
+
+## Fields {#pandoc.layout-fields}
+
+### blankline {#pandoc.layout.blankline}
+
+Inserts a blank line unless one exists already. ([Doc])
+
+### cr {#pandoc.layout.cr}
+
+A carriage return. Does nothing if we're at the beginning of a
+line; otherwise inserts a newline. ([Doc])
+
+### empty {#pandoc.layout.empty}
+
+The empty document. ([Doc])
+
+### space {#pandoc.layout.space}
+
+A breaking (reflowable) space. ([Doc])
+
+## Functions {#pandoc.layout-functions}
+
+### after_break {#pandoc.layout.after_break}
+
+`after_break (text)`
+
+Creates a [Doc] which is conditionally included only if it comes
+at the beginning of a line.
+
+An example where this is useful is for escaping line-initial `.`
+in roff man.
+
+Parameters:
+
+`text`
+: content to include when placed after a break (string)
+
+Returns:
+
+- new doc ([Doc])
+
+*Since: 2.18*
+
+### before_non_blank {#pandoc.layout.before_non_blank}
+
+`before_non_blank (doc)`
+
+Conditionally includes the given `doc` unless it is followed by a
+blank space.
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+Returns:
+
+- conditional doc ([Doc])
+
+*Since: 2.18*
+
+### blanklines {#pandoc.layout.blanklines}
+
+`blanklines (n)`
+
+Inserts blank lines unless they exist already.
+
+Parameters:
+
+`n`
+: number of blank lines ([integer]{unknown-type="integer"})
+
+Returns:
+
+- conditional blank lines ([Doc])
+
+*Since: 2.18*
+
+### braces {#pandoc.layout.braces}
+
+`braces (doc)`
+
+Puts the `doc` in curly braces.
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+Returns:
+
+- `doc` enclosed by {}. ([Doc])
+
+*Since: 2.18*
+
+### brackets {#pandoc.layout.brackets}
+
+`brackets (doc)`
+
+Puts the `doc` in square brackets
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+Returns:
+
+- doc enclosed by \[\]. ([Doc])
+
+*Since: 2.18*
+
+### cblock {#pandoc.layout.cblock}
+
+`cblock (doc, width)`
+
+Creates a block with the given width and content, aligned
+centered.
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+`width`
+: block width in chars ([integer]{unknown-type="integer"})
+
+Returns:
+
+- doc, aligned centered in a block with max `width` chars per
+ line. ([Doc])
+
+*Since: 2.18*
+
+### chomp {#pandoc.layout.chomp}
+
+`chomp (doc)`
+
+Chomps trailing blank space off of the `doc`.
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+Returns:
+
+- `doc` without trailing blanks ([Doc])
+
+*Since: 2.18*
+
+### concat {#pandoc.layout.concat}
+
+`concat (docs[, sep])`
+
+Concatenates a list of `Doc`s.
+
+Parameters:
+
+`docs`
+: list of Docs ([\`{Doc,\...}\`]{unknown-type="`{Doc,...}`"})
+
+`sep`
+: separator (default: none) ([Doc])
+
+Returns:
+
+- concatenated doc ([Doc])
+
+*Since: 2.18*
+
+### double_quotes {#pandoc.layout.double_quotes}
+
+`double_quotes (doc)`
+
+Wraps a `Doc` in double quotes.
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+Returns:
+
+- `doc` enclosed by `"` chars ([Doc])
+
+*Since: 2.18*
+
+### flush {#pandoc.layout.flush}
+
+`flush (doc)`
+
+Makes a `Doc` flush against the left margin.
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+Returns:
+
+- flushed `doc` ([Doc])
+
+*Since: 2.18*
+
+### hang {#pandoc.layout.hang}
+
+`hang (doc, ind, start)`
+
+Creates a hanging indent.
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+`ind`
+: indentation width ([integer]{unknown-type="integer"})
+
+`start`
+: document ([Doc])
+
+Returns:
+
+- `doc` prefixed by `start` on the first line, subsequent lines
+ indented by `ind` spaces. ([Doc])
+
+*Since: 2.18*
+
+### inside {#pandoc.layout.inside}
+
+`inside (contents, start, end)`
+
+Encloses a [Doc] inside a start and end [Doc].
+
+Parameters:
+
+`contents`
+: document ([Doc])
+
+`start`
+: document ([Doc])
+
+`end`
+: document ([Doc])
+
+Returns:
+
+- enclosed contents ([Doc])
+
+*Since: 2.18*
+
+### lblock {#pandoc.layout.lblock}
+
+`lblock (doc, width)`
+
+Creates a block with the given width and content, aligned to the
+left.
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+`width`
+: block width in chars ([integer]{unknown-type="integer"})
+
+Returns:
+
+- doc put into block with max `width` chars per line. ([Doc])
+
+*Since: 2.18*
+
+### literal {#pandoc.layout.literal}
+
+`literal (text)`
+
+Creates a `Doc` from a string.
+
+Parameters:
+
+`text`
+: literal value (string)
+
+Returns:
+
+- doc contatining just the literal string ([Doc])
+
+*Since: 2.18*
+
+### nest {#pandoc.layout.nest}
+
+`nest (doc, ind)`
+
+Indents a `Doc` by the specified number of spaces.
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+`ind`
+: indentation size ([integer]{unknown-type="integer"})
+
+Returns:
+
+- `doc` indented by `ind` spaces ([Doc])
+
+*Since: 2.18*
+
+### nestle {#pandoc.layout.nestle}
+
+`nestle (doc)`
+
+Removes leading blank lines from a `Doc`.
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+Returns:
+
+- `doc` with leading blanks removed ([Doc])
+
+*Since: 2.18*
+
+### nowrap {#pandoc.layout.nowrap}
+
+`nowrap (doc)`
+
+Makes a `Doc` non-reflowable.
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+Returns:
+
+- same as input, but non-reflowable ([Doc])
+
+*Since: 2.18*
+
+### parens {#pandoc.layout.parens}
+
+`parens (doc)`
+
+Puts the `doc` in parentheses.
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+Returns:
+
+- doc enclosed by (). ([Doc])
+
+*Since: 2.18*
+
+### prefixed {#pandoc.layout.prefixed}
+
+`prefixed (doc, prefix)`
+
+Uses the specified string as a prefix for every line of the inside
+document (except the first, if not at the beginning of the line).
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+`prefix`
+: prefix for each line (string)
+
+Returns:
+
+- prefixed `doc` ([Doc])
+
+*Since: 2.18*
+
+### quotes {#pandoc.layout.quotes}
+
+`quotes (doc)`
+
+Wraps a `Doc` in single quotes.
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+Returns:
+
+- doc enclosed in `'`. ([Doc])
+
+*Since: 2.18*
+
+### rblock {#pandoc.layout.rblock}
+
+`rblock (doc, width)`
+
+Creates a block with the given width and content, aligned to the
+right.
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+`width`
+: block width in chars ([integer]{unknown-type="integer"})
+
+Returns:
+
+- doc, right aligned in a block with max `width` chars per line.
+ ([Doc])
+
+*Since: 2.18*
+
+### vfill {#pandoc.layout.vfill}
+
+`vfill (border)`
+
+An expandable border that, when placed next to a box, expands to
+the height of the box. Strings cycle through the list provided.
+
+Parameters:
+
+`border`
+: vertically expanded characters (string)
+
+Returns:
+
+- automatically expanding border Doc ([Doc])
+
+*Since: 2.18*
+
+### render {#pandoc.layout.render}
+
+`render (doc[, colwidth[, style]])`
+
+Render a [Doc]. The text is reflowed on breakable spaces to match
+the given line length. Text is not reflowed if the line
+length parameter is omitted or nil.
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+`colwidth`
+: Maximum number of characters per line. A value of `nil`, the
+ default, means that the text is not reflown.
+ ([integer]{unknown-type="integer"})
+
+`style`
+: Whether to generate plain text or ANSI terminal output. Must
+ be either `'plain'` or `'ansi'`. Defaults to `'plain'`.
+ (string)
+
+Returns:
+
+- rendered doc (string)
+
+*Since: 2.18*
+
+### is_empty {#pandoc.layout.is_empty}
+
+`is_empty (doc)`
+
+Checks whether a doc is empty.
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+Returns:
+
+- `true` iff `doc` is the empty document, `false` otherwise.
+ (boolean)
+
+*Since: 2.18*
+
+### height {#pandoc.layout.height}
+
+`height (doc)`
+
+Returns the height of a block or other Doc.
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+Returns:
+
+- doc height ([integer]{unknown-type="integer"}\|string)
+
+*Since: 2.18*
+
+### min_offset {#pandoc.layout.min_offset}
+
+`min_offset (doc)`
+
+Returns the minimal width of a [Doc] when reflowed at breakable
+spaces.
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+Returns:
+
+- minimal possible width
+ ([integer]{unknown-type="integer"}\|string)
+
+*Since: 2.18*
+
+### offset {#pandoc.layout.offset}
+
+`offset (doc)`
+
+Returns the width of a [Doc] as number of characters.
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+Returns:
+
+- doc width ([integer]{unknown-type="integer"}\|string)
+
+*Since: 2.18*
+
+### real_length {#pandoc.layout.real_length}
+
+`real_length (str)`
+
+Returns the real length of a string in a monospace font: 0 for a
+combining character, 1 for a regular character, 2 for an East
+Asian wide character.
+
+Parameters:
+
+`str`
+: UTF-8 string to measure (string)
+
+Returns:
+
+- text length ([integer]{unknown-type="integer"}\|string)
+
+*Since: 2.18*
+
+### update_column {#pandoc.layout.update_column}
+
+`update_column (doc, i)`
+
+Returns the column that would be occupied by the last laid out
+character.
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+`i`
+: start column ([integer]{unknown-type="integer"})
+
+Returns:
+
+- column number ([integer]{unknown-type="integer"}\|string)
+
+*Since: 2.18*
+
+### bold {#pandoc.layout.bold}
+
+`bold (doc)`
+
+Puts a [Doc] in boldface.
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+Returns:
+
+- bolded Doc ([Doc])
+
+*Since: 3.4.1*
+
+### italic {#pandoc.layout.italic}
+
+`italic (doc)`
+
+Puts a [Doc] in italics.
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+Returns:
+
+- styled Doc ([Doc])
+
+*Since: 3.4.1*
+
+### underlined {#pandoc.layout.underlined}
+
+`underlined (doc)`
+
+Underlines a [Doc].
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+Returns:
+
+- styled Doc ([Doc])
+
+*Since: 3.4.1*
+
+### strikeout {#pandoc.layout.strikeout}
+
+`strikeout (doc)`
+
+Puts a line through the [Doc].
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+Returns:
+
+- styled Doc ([Doc])
+
+*Since: 3.4.1*
+
+### fg {#pandoc.layout.fg}
+
+`fg (doc, color)`
+
+Set the foreground color.
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+`color`
+: One of 'black', 'red', 'green', 'yellow', 'blue', 'magenta'
+ 'cyan', or 'white'. (string)
+
+Returns:
+
+- styled Doc ([Doc])
+
+*Since: 3.4.1*
+
+### bg {#pandoc.layout.bg}
+
+`bg (doc, color)`
+
+Set the background color.
+
+Parameters:
+
+`doc`
+: document ([Doc])
+
+`color`
+: One of 'black', 'red', 'green', 'yellow', 'blue', 'magenta'
+ 'cyan', or 'white'. (string)
+
+Returns:
+
+- styled Doc ([Doc])
+
+*Since: 3.4.1*
+
+## Types {#pandoc.layout-types}
+
+### Doc {#type-pandoc.Doc}
+
+See the description [above][Doc].
+
+<!-- END: AUTOGENERATED CONTENT -->
+
+
+<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.scaffolding -->
+
+# Module pandoc.scaffolding
+
+Scaffolding for custom writers.
+
+## Fields {#pandoc.scaffolding-fields}
+
+### Writer {#pandoc.scaffolding.Writer}
+
+An object to be used as a `Writer` function; the construct handles
+most of the boilerplate, expecting only render functions for all
+AST elements (table)
+
+<!-- END: AUTOGENERATED CONTENT -->
+
+<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.text -->
+
+# Module pandoc.text
+
+UTF-8 aware text manipulation functions, implemented in Haskell.
+
+The text module can also be loaded under the name `text`, although
+this is discouraged and deprecated.
+
+``` lua
+-- uppercase all regular text in a document:
+function Str (s)
+ s.text = pandoc.text.upper(s.text)
+ return s
+end
+```
+
+## Functions {#pandoc.text-functions}
+
+### fromencoding {#pandoc.text.fromencoding}
+
+`fromencoding (s[, encoding])`
+
+Converts a string to UTF-8. The `encoding` parameter specifies the
+encoding of the input string. On Windows, that parameter defaults
+to the current ANSI code page; on other platforms the function
+will try to use the file system's encoding.
+
+The set of known encodings is system dependent, but includes at
+least `UTF-8`, `UTF-16BE`, `UTF-16LE`, `UTF-32BE`, and `UTF-32LE`.
+Note that the default code page on Windows is available through
+`CP0`.
+
+Parameters:
+
+`s`
+: string to be converted (string)
+
+`encoding`
+: target encoding (string)
+
+Returns:
+
+- UTF-8 string (string)
+
+*Since: 3.0*
+
+### len {#pandoc.text.len}
+
+`len (s)`
+
+Returns the length of a UTF-8 string, i.e., the number of
+characters.
+
+Parameters:
+
+`s`
+: UTF-8 encoded string (string)
+
+Returns:
+
+- length (integer\|string)
+
+*Since: 2.0.3*
+
+### lower {#pandoc.text.lower}
+
+`lower (s)`
+
+Returns a copy of a UTF-8 string, converted to lowercase.
+
+Parameters:
+
+`s`
+: UTF-8 string to convert to lowercase (string)
+
+Returns:
+
+- Lowercase copy of `s` (string)
+
+*Since: 2.0.3*
+
+### reverse {#pandoc.text.reverse}
+
+`reverse (s)`
+
+Returns a copy of a UTF-8 string, with characters reversed.
+
+Parameters:
+
+`s`
+: UTF-8 string to revert (string)
+
+Returns:
+
+- Reversed `s` (string)
+
+*Since: 2.0.3*
+
+### sub {#pandoc.text.sub}
+
+`sub (s, i[, j])`
+
+Returns a substring of a UTF-8 string, using Lua's string indexing
+rules.
+
+Parameters:
+
+`s`
+: UTF-8 string (string)
+
+`i`
+: substring start position (integer)
+
+`j`
+: substring end position (integer)
+
+Returns:
+
+- text substring (string)
+
+*Since: 2.0.3*
+
+### subscript {#pandoc.text.subscript}
+
+`subscript (input)`
+
+Tries to convert the string into a Unicode subscript version of
+the string. Returns `nil` if not all characters of the input can
+be mapped to a subscript Unicode character. Supported characters
+include numbers, parentheses, and plus/minus.
+
+Parameters:
+
+`input`
+: string to convert to subscript characters (string)
+
+Returns:
+
+- Subscript version of the input, or `nil` if not all characters
+ could be converted. (string\|nil)
+
+*Since: 3.8*
+
+### superscript {#pandoc.text.superscript}
+
+`superscript (input)`
+
+Tries to convert the string into a Unicode superscript version of
+the string. Returns `nil` if not all characters of the input can
+be mapped to a superscript Unicode character. Supported characters
+include numbers, parentheses, and plus/minus.
+
+Parameters:
+
+`input`
+: string to convert to superscript characters (string)
+
+Returns:
+
+- Superscript version of the input, or `nil` if not all characters
+ could be converted. (string\|nil)
+
+*Since: 3.8*
+
+### toencoding {#pandoc.text.toencoding}
+
+`toencoding (s[, enc])`
+
+Converts a UTF-8 string to a different encoding. The `encoding`
+parameter defaults to the current ANSI code page on Windows; on
+other platforms it will try to guess the file system's encoding.
+
+The set of known encodings is system dependent, but includes at
+least `UTF-8`, `UTF-16BE`, `UTF-16LE`, `UTF-32BE`, and `UTF-32LE`.
+Note that the default code page on Windows is available through
+`CP0`.
+
+Parameters:
+
+`s`
+: UTF-8 string (string)
+
+`enc`
+: target encoding (string)
+
+Returns:
+
+- re-encoded string (string)
+
+*Since: 3.0*
+
+### upper {#pandoc.text.upper}
+
+`upper (s)`
+
+Returns a copy of a UTF-8 string, converted to uppercase.
+
+Parameters:
+
+`s`
+: UTF-8 string to convert to uppercase (string)
+
+Returns:
+
+- Uppercase copy of `s` (string)
+
+*Since: 2.0.3*
+
+<!-- END: AUTOGENERATED CONTENT -->
+
+<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.template -->
+
+# Module pandoc.template
+
+Handle pandoc templates.
+
+## Functions {#pandoc.template-functions}
+
+### apply {#pandoc.template.apply}
+
+`apply (template, context)`
+
+Applies a context with variable assignments to a template,
+returning the rendered template. The `context` parameter must be a
+table with variable names as keys and [Doc], string, boolean, or
+table as values, where the table can be either be a list of the
+aforementioned types, or a nested context.
+
+Parameters:
+
+`template`
+: template to apply ([Template])
+
+`context`
+: variable values (table)
+
+Returns:
+
+- rendered template ([Doc])
+
+*Since: 3.0*
+
+### compile {#pandoc.template.compile}
+
+`compile (template[, templates_path])`
+
+Compiles a template string into a [Template] object usable by
+pandoc.
+
+If the `templates_path` parameter is specified, then it should be
+the file path associated with the template. It is used when
+checking for partials. Partials will be taken only from the
+default data files if this parameter is omitted.
+
+An error is raised if compilation fails.
+
+Parameters:
+
+`template`
+: template string (string)
+
+`templates_path`
+: parameter to determine a default path and extension for
+ partials; uses the data files templates path by default.
+ (string)
+
+Returns:
+
+- compiled template ([Template])
+
+*Since: 2.17*
+
+### default {#pandoc.template.default}
+
+`default ([writer])`
+
+Returns the default template for a given writer as a string. An
+error is thrown if no such template can be found.
+
+Parameters:
+
+`writer`
+: name of the writer for which the template should be retrieved;
+ defaults to the global `FORMAT`. (string)
+
+Returns:
+
+- raw template (string)
+
+*Since: 2.17*
+
+### get {#pandoc.template.get}
+
+`get (filename)`
+
+Retrieve text for a template.
+
+This function first checks the resource paths for a file of this
+name; if none is found, the `templates` directory in the user data
+directory is checked. Returns the content of the file, or throws
+an error if no file is found.
+
+Parameters:
+
+`filename`
+: name of the template (string)
+
+Returns:
+
+- content of template file (string)
+
+*Since: 3.2.1*
+
+### meta_to_context {#pandoc.template.meta_to_context}
+
+`meta_to_context (meta, blocks_writer, inlines_writer)`
+
+Creates template context from the document's [Meta] data, using
+the given functions to convert [Blocks] and [Inlines] to [Doc]
+values.
+
+Parameters:
+
+`meta`
+: document metadata ([Meta])
+
+`blocks_writer`
+: converter from [Blocks] to [Doc] values (function)
+
+`inlines_writer`
+: converter from [Inlines] to [Doc] values (function)
+
+Returns:
+
+- template context (table)
+
+*Since: 3.0*
+
+## Types {#pandoc.template-types}
+
+### Template {#type-pandoc.template.Template}
+
+<!-- END: AUTOGENERATED CONTENT -->
+
+<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.types -->
+
+# Module pandoc.types
+
+Constructors for types that are not part of the pandoc AST.
+
+## Functions {#pandoc.types-functions}
+
+### Version {#pandoc.types.Version}
+
+`Version (version_specifier)`
+
+Parameters:
+
+`version_specifier`
+: A version string like `'2.7.3'`, a Lua number like `2.0`, a
+ list of integers like `{2,7,3}`, or a Version object.
+ (string\|number\|{integer,\...}\|[Version])
+
+Returns:
+
+- New Version object. ([Version])
+
+*Since: 2.7.3*
+
+### Sources {#pandoc.types.Sources}
+
+`Sources (srcs)`
+
+Creates a new Sources element, i.e., a list of [Source] items.
+
+Pandoc's text readers expect the input text to be paired with
+information on where the text originated, e.g., a file name. This
+abstraction is provided via the `Sources` type.
+
+Pandoc accepts a range of objects wherever a *Sources* list is
+expected:
+
+- a list of [Source] items;
+- a simple string, which becomes an unnamed source;
+- a list of table objects, where each table contains the fields
+ `name` (the filepath) and `text` (the file contents)
+
+A Sources list can be converted to a string via the default
+`tostring` Lua function. This will concatenate all source items.
+
+Parameters:
+
+`srcs`
+: sources (string\|{string,\...}\|table)
+
+Returns:
+
+- new Sources object ({[Source],\...})
+
+*Since: 3.9.1*
+
+## Types {#pandoc.types-types}
+
+### Source {#type-pandoc.types.Source}
+
+### Version {#type-pandoc.types.Version}
+
+#### Methods
+
+##### Version.must_be_at_least {#Version.must_be_at_least}
+
+`Version.must_be_at_least (self, reference[, msg])`
+
+Parameters:
+
+`self`
+: version to check ([Version])
+
+`reference`
+: minimum version ([Version])
+
+`msg`
+: alternative message (string)
+
+Returns:
+
+Returns no result, and throws an error if this version is older
+than `reference`.
+
+<!-- END: AUTOGENERATED CONTENT -->
+
+<!-- Disabled due to limitations in the current documentation
+ renderer. -->
+<!-- BEGIN DISABLED: AUTOGENERATED CONTENT for module pandoc.zip -->
+
+# Module pandoc.zip
+
+Functions to create, modify, and extract files from zip archives.
+
+The module can be called as a function, in which case it behaves
+like the `zip` function described below.
+
+Zip options are optional; when defined, they must be a table with
+any of the following keys:
+
+- `recursive`: recurse directories when set to `true`;
+- `verbose`: print info messages to stdout;
+- `destination`: the value specifies the directory in which to
+ extract;
+- `location`: value is used as path name, defining where files are
+ placed.
+- `preserve_symlinks`: Boolean value, controlling whether symbolic
+ links are preserved as such. This option is ignored on Windows.
+
+## Functions {#pandoc.zip-functions}
+
+### Archive {#pandoc.zip.Archive}
+
+`Archive ([bytestring_or_entries])`
+
+Reads an *Archive* structure from a raw zip archive or a list of
+Entry items; throws an error if the given string cannot be decoded
+into an archive.
+
+Parameters:
+
+`bytestring_or_entries`
+: binary archive data or list of entries; defaults to an empty
+ list (string\|{[zip.Entry],\...})
+
+Returns:
+
+- new Archive ([zip.Archive])
+
+*Since: 3.0*
+
+### Entry {#pandoc.zip.Entry}
+
+`Entry (path, contents[, modtime])`
+
+Generates a ZipEntry from a filepath, uncompressed content, and
+the file's modification time.
+
+Parameters:
+
+`path`
+: file path in archive (string)
+
+`contents`
+: uncompressed contents (string)
+
+`modtime`
+: modification time (integer)
+
+Returns:
+
+- a new zip archive entry ([zip.Entry])
+
+*Since: 3.0*
+
+### read_entry {#pandoc.zip.read_entry}
+
+`read_entry (filepath[, opts])`
+
+Generates a ZipEntry from a file or directory.
+
+Parameters:
+
+`filepath`
+: (string)
+
+`opts`
+: zip options (table)
+
+Returns:
+
+- a new zip archive entry ([zip.Entry])
+
+*Since: 3.0*
+
+### zip {#pandoc.zip.zip}
+
+`zip (filepaths[, opts])`
+
+Package and compress the given files into a new Archive.
+
+Parameters:
+
+`filepaths`
+: list of files from which the archive is created.
+ ({string,\...})
+
+`opts`
+: zip options (table)
+
+Returns:
+
+- a new archive ([zip.Archive])
+
+*Since: 3.0*
+
+## Types {#pandoc.zip-types}
+
+### zip.Archive {#type-pandoc.zip.Archive}
+
+#### Properties {#type-pandoc.zip.Archive-properties}
+
+##### entries {#type-pandoc.zip.Archive.entries}
+
+Files in this zip archive ({[zip.Entry],\...})
+
+#### Methods {#type-pandoc.zip.Archive-methods}
+
+##### bytestring {#pandoc.zip.Archive.bytestring}
+
+`bytestring (self)`
+
+Returns the raw binary string representation of the archive.
+
+Parameters:
+
+`self`
+: ([zip.Archive])
+
+Returns:
+
+- bytes of the archive (string)
+
+##### extract {#pandoc.zip.Archive.extract}
+
+`extract (self[, opts])`
+
+Extract all files from this archive, creating directories as
+needed. Note that the last-modified time is set correctly only in
+POSIX, not in Windows. This function fails if encrypted entries
+are present.
+
+Parameters:
+
+`self`
+: ([zip.Archive])
+
+`opts`
+: zip options (table)
+
+### zip.Entry {#type-pandoc.zip.Entry}
+
+#### Properties {#type-pandoc.zip.Entry-properties}
+
+##### modtime {#type-pandoc.zip.Entry.modtime}
+
+Modification time (seconds since unix epoch)
+([integer]{unknown-type="integer"})
+
+##### path {#type-pandoc.zip.Entry.path}
+
+Relative path, using `/` as separator ([zip.Entry])
+
+#### Methods {#type-pandoc.zip.Entry-methods}
+
+##### contents {#pandoc.zip.Entry.contents}
+
+`contents (self[, password])`
+
+Get the uncompressed contents of a zip entry. If `password` is
+given, then that password is used to decrypt the contents. An
+error is throws if decrypting fails.
+
+Parameters:
+
+`self`
+: ([zip.Entry])
+
+`password`
+: password for entry (string)
+
+Returns:
+
+- binary contents (string)
+
+##### symlink {#pandoc.zip.Entry.symlink}
+
+`symlink (self)`
+
+Returns the target if the Entry represents a symbolic link, and
+`nil` otherwise. Always returns `nil` on Windows.
+
+Parameters:
+
+`self`
+: ([zip.Entry])
+
+Returns:
+
+- link target if entry represents a symbolic link (string\|nil)
+
+[zip.Entry]: #type-pandoc.zip.Entry
+[zip.Archive]: #type-pandoc.zip.Archive
+<!-- END DISABLED: AUTOGENERATED CONTENT -->
+
+<!-- BEGIN: GENERATED REFERENCE LINKS -->
+
+ [Blocks]: #type-blocks
+ [Meta]: #type-meta
+ [Pandoc]: #type-pandoc
+ [Inlines]: #type-inlines
+ [MetaValue]: #type-metavalue
+ [Block]: #type-block
+ [Attr]: #type-attr
+ [Figure]: #type-figure
+ [Caption]: #type-caption
+ [ListAttributes]: #type-listattributes
+ [ColSpec]: #type-colspec
+ [TableHead]: #type-tablehead
+ [TableBody]: #type-tablebody
+ [TableFoot]: #type-tablefoot
+ [Inline]: #type-inline
+ [Span]: #type-span
+ [Str]: #type-str
+ [AttributeList]: #type-attributes
+ [Alignment]: #type-alignment
+ [Cell]: #type-cell
+ [Row]: #type-row
+ [SimpleTable]: #type-simpletable
+ [Table]: #type-table
+ [Version]: #type-version
+ [`list`]: #pandoc.mediabag.list
+ [FormatExtensions]: #FormatExtensions
+ [WriterOptions]: #type-writeroptions
+ [null]: #pandoc.json.null
+ [this blog post]: http://neilmitchell.blogspot.co.uk/2015/10/filepaths-are-subtle-symlinks-are-hard.html
+ [ChunkedDoc]: #type-chunkeddoc
+ [XDG Base Directory Specification]: https://specifications.freedesktop.org/basedir-spec/latest/
+ [Doc]: #type-doc
+ [Template]: #type-template
+ [Source]: #type-pandoc.types.Source
diff --git a/documents/markdown/pandoc-md/doc_nix.md b/documents/markdown/pandoc-md/doc_nix.md
new file mode 100644
index 0000000..ce25b2f
--- /dev/null
+++ b/documents/markdown/pandoc-md/doc_nix.md
@@ -0,0 +1,26 @@
+---
+title: Using NiX to develop pandoc
+author: John MacFarlane
+---
+
+The source directory contains `shell.nix` and `flake.nix`,
+so if you have NiX installed, you can use either `nix shell`
+or `nix develop` can be used to obtain a shell with pandoc
+dependencies installed.
+
+To set up `direnv` so that the NiX shell is automatically
+activated whenever the directory is entered, add the following
+`.envrc` in the pandoc source directory:
+
+```
+if ! has nix_direnv_version || ! nix_direnv_version 2.2.1; then
+ source_url "https://raw.githubusercontent.com/nix-community/nix-direnv/2.2.1/direnvrc" "sha256-zelF0vLbEl5uaqrfIzbgNzJWGmLzCmYAkInj/LNxvKs="
+fi
+use flake
+```
+
+This uses [nix-direnv] for caching. See its web page for
+further help.
+
+[nix-direnv]: https://github.com/nix-community/nix-direnv
+
diff --git a/documents/markdown/pandoc-md/doc_org.md b/documents/markdown/pandoc-md/doc_org.md
new file mode 100644
index 0000000..31aecff
--- /dev/null
+++ b/documents/markdown/pandoc-md/doc_org.md
@@ -0,0 +1,290 @@
+---
+title: Org-mode features and differences
+author: Albert Krewinkel
+---
+
+Pandoc's handling of org files is similar to that of Emacs
+org-mode. This document aims to highlight the cases where this is
+not possible or just not the case yet.
+
+Export options
+==============
+
+The following export keywords are supported. (Because they
+populate metadata fields, they will not generally affect the
+output unless you use the `-s/--standalone` option to generate
+a standalone document with metadata.)
+
+- AUTHOR: comma-separated list of author(s); fully supported.
+
+- CREATOR: output generator; passed as plain-text metadata entry
+ `creator`, but not used by any default templates.
+
+- DATE: creation or publication date; well supported by pandoc.
+
+- EMAIL: author email address; passed as plain-text metadata
+ field `email`, but not used by any default templates.
+
+- LANGUAGE: document language; included as plain-text metadata
+ field `lang`. The value should be a [BCP47 language tag].
+
+- SELECT_TAGS: tags which select a tree for export.
+
+- EXCLUDE\_TAGS: tags which prevent a subtree from being
+ exported. Fully supported.
+
+- TITLE: document title; fully supported.
+
+- EXPORT\_FILE\_NAME: target filename; *unsupported*, the output
+ defaults to stdout unless a target has to be given as a command
+ line option.
+
+::: {.alert .alert-info}
+Pandoc tries to be compatible with org-mode when exporting an org document. If
+you find some behavior confusing, please do refer to org-mode
+[Export-Settings](https://orgmode.org/manual/Export-Settings.html)
+documentation. For example, a common confusion
+([#3214](https://github.com/jgm/pandoc/issues/3214 "Problem with headers lower
+then 3 in org-mode reader"), [#5169](https://github.com/jgm/pandoc/issues/5169
+"org mode headings past level three converted to numbered outline list"),
+[#6145](https://github.com/jgm/pandoc/issues/6145 "Headers 4 levels deep render
+differently"), [#7236](https://github.com/jgm/pandoc/issues/7236 "In Org mode,
+Header with level > 3 are not recognized as headers")) is treatment of headers
+with level > 3 differently because org-mode sets `org-export-headline-levels`
+(configurable with `#+OPTIONS: H:3`) to 3 by default.
+:::
+
+[BCP47 language tag]: https://tools.ietf.org/html/bcp47
+
+Format-specific options
+-----------------------
+
+Emacs Org-mode supports additional export options which work for
+specific export formats. Some of these options' behavior differs
+in Org-mode depending on the output format, while pandoc is
+format-agnostic when parsing; differences are noted where they
+occur.
+
+- DESCRIPTION: the document's description; pandoc parses this
+ option as text with markup into the `description` metadata
+ field. The field is not used in default templates.
+
+ Pandoc follows the LaTeX exporter in that it allows markup in
+ the description. In contrast, the Org-mode HTML exporter treats
+ the description as plain text.
+
+- LATEX\_HEADER and LATEX_HEADER_EXTRA: arbitrary lines to add to
+ the document's preamble. Contrary to Org-mode, these lines are
+ not inserted before the hyperref settings, but close to the end
+ of the preamble.
+
+ The contents of this option are stored as a list of raw LaTeX
+ lines in the `header-includes` metadata field.
+
+- LATEX\_CLASS: the LaTeX document class; like Org-mode, pandoc
+ uses `article` as the default class.
+
+ The contents of this option are stored as plain text in the
+ `documentclass` metadata field.
+
+- LATEX\_CLASS\_OPTIONS: Options for the LaTeX document class;
+ fully supported.
+
+ The contents of this option are stored as plain text in the
+ `classoption` metadata field.
+
+- SUBTITLE: the document's subtitle; fully supported.
+
+ The content of this option is stored as inlines in the
+ `subtitle` metadata field.
+
+- HTML\_HEAD and HTML\_HEAD\_EXTRA: arbitrary lines to add to the
+ HTML document's head; fully supported.
+
+ The contents of these options are stored as a list of raw HTML
+ lines in the `header-includes` metadata field.
+
+Pandoc-specific options
+-----------------------
+
+Pandoc recognizes some export options not used by Emacs Org.
+
+- NOCITE: this field adds the listed citations to the
+ bibliography, without the need to mention them to the text. The
+ special value `@*` causes all available references to be added
+ the bibliography.
+
+- HEADER-INCLUDES: like HTML_HEAD and, LATEX_HEADER, but treats
+ the option's value as normal text with markup.
+
+- INSTITUTE: Affiliation of the author; the value is read as text
+ with markup and is stored in the `institute` metadata field. The
+ field is included by default on the title slide of beamer
+ presentations.
+
+Other options
+-------------
+
+Any export option or directive not listed above has no effect when
+parsing with pandoc. However, the information is retained as a
+*raw block*. It can be accessed through a
+[filter](https://pandoc.org/filters.html) and will be included in
+org output.
+
+### Directives as metadata
+
+As an example, we will restore an old behavior of pandoc versions
+prior to 2.10. Unknown keywords were treated as variable
+definitions, and were added the document's metadata. Typing
+`#+key: value` in the org-file used to have the same effect as
+running pandoc with the `--metadata key=value` option.
+
+Since pandoc 2.10, each unhandled line starting with `#+` is kept
+internally as a raw block with format `org`. This block can be
+inspected and processed by a filter. Below is a [Lua
+filter](https://pandoc.org/lua-filters.html) which converts these
+unhandled lines into metadata key-value pairs.
+
+``` lua
+-- intermediate store for variables and their values
+local variables = {}
+
+--- Function called for each raw block element.
+function RawBlock (raw)
+ -- Don't do anything unless the block contains *org* markup.
+ if raw.format ~= 'org' then return nil end
+
+ -- extract variable name and value
+ local name, value = raw.text:match '#%+(%w+):%s*(.+)$'
+ if name and value then
+ variables[name] = value
+ end
+end
+
+-- Add the extracted variables to the document's metadata.
+function Meta (meta)
+ for name, value in pairs(variables) do
+ meta[name] = value
+ end
+ return meta
+end
+```
+
+Tables
+======
+
+Pandoc supports normal org tables (sometimes called "pipe tables")
+and grid tables (tables created by [table.el]).
+
+Column widths
+-------------
+
+Org mode tables don't allow line-breaks within cells, and lines
+which contain text can get very long. This often leads to tables
+which run off the page when exporting, especially when exporting
+to PDF via LaTeX. Overlong lines in the source text are this is
+usually hidden by setting a [column width], but the default Emacs
+exporters ignore that setting. Pandoc deviates from Emacs's
+behavior and uses this information to resize the table columns
+when exporting.
+
+Limitations
+-----------
+
+There is no support yet for cells spanning multiple columns or
+rows. The table.el grid tables allows rowspans and colspans and so
+does pandoc's internal structure since 2.10, but the parser has
+not been updated yet.
+
+[table.el]: http://table.sourceforge.net/
+[column width]: https://orgmode.org/manual/Column-Width-and-Alignment.html
+
+Emphasis rules
+==============
+
+Org-mode uses complex rules to decide whether a string
+represents emphasized text. In Emacs, this can be customized via
+the variable `org-emphasis-regexp-components`. A variable like
+this doesn't fit well with pandoc's model. Instead, it is
+possible to use special lines to change these values:
+
+ #+pandoc-emphasis-pre: "-\t ('\"{\x200B"
+ #+pandoc-emphasis-post: "-\t\n .,:!?;'\")}[\x200B"
+
+The above describes the default values of these variables. The
+arguments must be valid (Haskell) strings. If interpretation of
+the argument as string fails, the default is restored.
+
+Changing emphasis rules only affect the part of the document
+following the special lines. They must be some of the first
+lines to alter parsing behavior for the whole document. It is
+also possible to change the values temporarily for selected
+sections only. The string `test` in the following snippet will
+be read as emphasized text, while the rest of the document will
+be parsed using default emphasis rules:
+
+ #+pandoc-emphasis-pre: "["
+ #+pandoc-emphasis-post: "]"
+ [/test/]
+ #+pandoc-emphasis-pre:
+ #+pandoc-emphasis-post:
+
+`smart` extension
+=================
+
+Org-mode allows to insert certain characters via special character
+sequences. For example, instead of typing the Unicode /HORIZONTAL
+ELLISPIS/ character `…` by hand, one can instead type tree dots
+`...`. En dashes and em dashes can be written as `--` and `---`
+respectively. Furthermore, quotation marks (`"`) and
+apostrophe-quotes (`'`) can be treated in a "smart" way,
+potentially replacing them with proper, language specific unicode
+quotation characters.
+
+Like in Markdown, these behaviors can be turned on all-at-once by
+enabling the `smart` extension. However, disabling `smart` (the
+default) will *not* necessarily disable smart quotes and special
+strings. Instead, it will just result in the default Org mode
+behavior.
+
+The special string feature can be turned off via the `#+OPTIONS:
+-:nil` [export setting]. There are currently no command line flags
+which control these features. As a workaround, one can use process
+substitution, a feature supported by most shells. It allows to
+provide the options line on the command line:
+
+ pandoc -f org <(printf "#+OPTIONS: -:nil\n") …
+
+[export setting]: https://orgmode.org/manual/Export-Settings.html
+
+`fancy_lists` extension
+=======================
+
+Org-mode has a variable `org-list-allow-alphabetical` that when
+set to `t`, allows ordered lists with single-character
+alphabetical markers. Since this variable is `nil` by default,
+alphabetical markers can be optionally enabled in Pandoc by
+enabling the `fancy_lists` extension.
+
+When `fancy_lists` is enabled, Pandoc will also parse list
+markers starting with one lowercase or uppercase alphabetical
+character, like `a.` and `D)`. Contrary to the use of this
+extension in markdown, roman numerals or the `#` placeholder
+can't be used as markers as they are not allowed in Org-mode.
+
+One additional behavior that is enabled by the `fancy_lists`
+extension is that the `.` and `)` delimiters for list markers
+will be distinguished by Pandoc. In essence, this means that when
+converting Org into formats like LaTeX, Pandoc will respect the
+type of delimiter that you used in your Org file, instead of
+always using the default delimiter for the exported format.
+
+Currently unsupported features
+==============================
+
+Library of babel
+----------------
+
+The library of babel translates between various programming
+languages. This is out-of-scope for pandoc. Use Emacs to run
+code, then feed the resulting org file to pandoc.
diff --git a/documents/markdown/pandoc-md/doc_pandoc-lua.md b/documents/markdown/pandoc-md/doc_pandoc-lua.md
new file mode 100644
index 0000000..aa01b48
--- /dev/null
+++ b/documents/markdown/pandoc-md/doc_pandoc-lua.md
@@ -0,0 +1,80 @@
+---
+title: pandoc-lua
+section: 1
+date: September 22, 2022
+---
+
+# SYNOPSIS
+
+`pandoc-lua` [*options*] [*script* [*args*]]
+
+# DESCRIPTION
+
+`pandoc-lua` is a standalone Lua interpreter with behavior similar
+to that of the standard `lua` executable, but exposing all of
+pandoc's Lua libraries. All `pandoc.*` packages, as well as the
+packages `re` and `lpeg`, are available via global variables.
+Furthermore, the globals `PANDOC_VERSION`, `PANDOC_STATE`, and
+`PANDOC_API_VERSION` are set at startup.
+
+If no script argument is given, then the script is assumed to be
+passed in via *stdin*. When called without arguments, `pandoc-lua`
+behaves as `pandoc-lua -v -i` when the standard input (`stdin`) is
+a terminal, and as `pandoc-lua -` otherwise. On Windows the
+program will always behave as if it was connected to a terminal.
+
+When called without the option `-E`, the interpreter checks for an
+environment variable `LUA_INIT` before running any argument. If
+the variable content has the format *`@filename`*, then
+`pandoc-lua` executes the file. Otherwise, `pandoc-lua` executes
+the string itself.
+
+# OPTIONS
+
+`-e stat`
+: Execute statement `stat`.
+
+`-l mod`
+: If mod has the pattern `g=m`, then require library `m` into
+ global `g`; otherwise require library `mod` into global
+ `mod`.
+
+`-v`
+: Show version information.
+
+`-i`
+: Enter interactive mode after running *script*.
+
+`-E`
+: Ignore environment variables. This is not fully implemented
+ yet and only ignores the `LUA_INIT` variable. Other variables
+ like `LUA_PATH` and `LUA_CPATH` are **not** ignored.
+
+`-W`
+: Turn warnings on.
+
+# INTERACTIVE MODE
+
+In interactive mode, the Lua interpreter repeatedly prompts and
+waits for a line. After reading a line, Lua first tries to
+interpret the line as an expression. If it succeeds, it prints its
+value. Otherwise, it interprets the line as a statement. If you
+write an incomplete statement, the interpreter waits for its
+completion by issuing a different prompt.
+
+Exit the interactive mode by pressing `Ctrl-D` or `Ctrl-C`, or by
+typing `os.exit()`. The *Isocline* library is used for line
+editing. Press `F1` to get a list of available keybindings; the
+`ctrl` key is abbreviated as `^` in that list.
+
+# AUTHORS
+
+Copyright 2023 John MacFarlane (jgm@berkeley.edu) and
+contributors. Released under the [GPL], version 2 or later. This
+software carries no warranty of any kind. (See COPYRIGHT for full
+copyright and warranty notices.)
+
+Lua: Copyright 1994-2023 Lua.org, PUC-Rio.
+
+[GPL]: https://www.gnu.org/copyleft/gpl.html "GNU General Public License"
+
diff --git a/documents/markdown/pandoc-md/doc_pandoc-server.md b/documents/markdown/pandoc-md/doc_pandoc-server.md
new file mode 100644
index 0000000..8289314
--- /dev/null
+++ b/documents/markdown/pandoc-md/doc_pandoc-server.md
@@ -0,0 +1,422 @@
+---
+title: pandoc-server
+section: 1
+date: August 15, 2022
+---
+
+# SYNOPSIS
+
+`pandoc-server` [*options*]
+
+# DESCRIPTION
+
+`pandoc-server` is a web server that can perform pandoc
+conversions. It can be used either as a running server
+or as a CGI program.
+
+To use `pandoc-server` as a CGI program, rename it (or symlink
+it) as `pandoc-server.cgi`. (Note: if you symlink it, you may
+need to adjust your webserver's configuration in order to allow
+it to follow symlinks for the CGI script.)
+
+All pandoc functions are run in the PandocPure monad, which
+ensures that they can do no I/O operations on the server.
+This should provide a high degree of security. This security
+does, however, impose certain limitations:
+
+- PDFs cannot be produced.
+
+- Filters are not supported.
+
+- Resources cannot be fetched via HTTP.
+
+- Any images, include files, or other resources needed for
+ the document conversion must be explicitly included in
+ the request, via the `files` field (see below under API).
+
+# OPTIONS
+
+`--port NUM`
+: HTTP port on which to run the server. Default: 3030.
+
+`--timeout SECONDS`
+: Timeout in seconds, after which a conversion is killed. Default: 2.
+
+ When `pandoc-server` is run as a CGI program, this option
+ can be set via the `PANDOC_SERVER_TIMEOUT` environment variable.
+
+`--help`
+: Print this help.
+
+`--version`
+: Print version.
+
+# API
+
+## Root endpoint
+
+The root (`/`) endpoint accepts only POST requests.
+
+### Response
+
+It returns a converted document in one of the following
+formats (in order of preference), depending on the `Accept` header:
+
+- `application/octet-stream`
+- `text/plain`
+- `application/json`
+
+If the result is a binary format (e.g., `epub` or `docx`)
+and the content is returned as plain text or JSON, the
+binary will be base64 encoded.
+
+If a JSON response is given, it will have one of the
+following formats. If the conversion is not successful:
+
+```
+{ "error": string with the error message }
+```
+
+If the conversion is successful:
+
+```
+{ "output": string with textual or base64-encoded binary output,
+ "base64": boolean (true means the "output" is base64-encoded),
+ "messages": array of message objects (see below) }
+```
+
+Each element of the "messages" array will have the format
+
+```
+{ "message": string,
+ "verbosity": string (either "WARNING" or "INFO") }
+```
+
+### Request
+
+The body of the POST request should be a JSON object,
+with the following fields. Only the `text` field is
+required; all of the others can be omitted for default
+values. When there are several string alternatives,
+the first one given is the default.
+
+`text` (string)
+
+: The document to be converted. Note:
+ if the `from` format is binary (e.g., `epub` or `docx`), then
+ `text` should be a base64 encoding of the document.
+
+`from` (string, default `"markdown"`)
+
+: The input format, possibly with extensions, just as it is
+ specified on the pandoc command line.
+
+`to` (string, default `"html"`)
+
+: The output format, possibly with extensions, just as it is
+ specified on the pandoc command line.
+
+`shift-heading-level-by` (integer, default 0)
+
+: Increase or decrease the level of all headings.
+
+`indented-code-classes` (array of strings)
+
+: List of classes to be applied to indented Markdown code blocks.
+
+`default-image-extension` (string)
+
+: Extension to be applied to image sources that lack extensions
+ (e.g. `".jpg"`).
+
+`metadata` (JSON map)
+
+: String-valued metadata.
+
+`tab-stop` (integer, default 4)
+
+: Tab stop (spaces per tab).
+
+`track-changes` (`"accept"|"reject"|"all"`)
+
+: Specifies what to do with insertions, deletions, and
+ comments produced by the MS Word "Track Changes" feature. Only
+ affects docx input.
+
+`abbreviations` (file path)
+
+: List of strings to be regarded as abbreviations when
+ parsing Markdown. See `--abbreviations` in `pandoc(1)` for
+ details.
+
+`standalone` (boolean, default false)
+
+: If true, causes a standalone document to be produced, using
+ the default template or the custom template specified using
+ `template`. If false, a fragment will be produced.
+
+`template` (string)
+
+: String contents of a document template (see Templates in
+ `pandoc(1)` for the format).
+
+`variables` (JSON map)
+
+: Variables to be interpolated in the template. (See Templates
+ in `pandoc(1)`.)
+
+`dpi` (integer, default 96)
+
+: Dots-per-inch to use for conversions between pixels and
+ other measurements (for image sizes).
+
+`wrap` (`"auto"|"preserve"|"none"`)
+
+: Text wrapping option: either `"auto"` (automatic
+ hard-wrapping to fit within a column width), `"preserve"`
+ (insert newlines where they are present in the source),
+ or `"none"` (don't insert any unnecessary newlines at all).
+
+`columns` (integer, default 72)
+
+: Column width (affects text wrapping and calculation of
+ table column widths in plain text formats)
+
+`table-of-contents` (boolean, default false)
+
+: Include a table of contents (in supported formats).
+
+`toc-depth` (integer, default 3)
+
+: Depth of sections to include in the table of contents.
+
+`list-of-figures` (boolean, default false)
+
+: Include a list of figures (in supported formats).
+
+`list-of-tables` (boolean, default false)
+
+: Include a list of tables (in supported formats).
+
+`strip-comments` (boolean, default false)
+
+: Causes HTML comments to be stripped in Markdown or Textile
+ source, instead of being passed through to the output format.
+
+`syntax-highlighting` (`"default"|"none"|"idiomatic"|style`)
+
+: The method used for code syntax highlighting. Setting a
+ specific *style* causes highlighting to be performed with the
+ internal highlighting engine, using KDE syntax definitions and
+ styles. The `"idiomatic"` method uses a format-specific
+ highlighter if one is available, or the default style if the
+ target format has no idiomatic highlighting method. Setting
+ this option to `none` disables all syntax highlighting. The
+ `"default"` method uses a format-specific default.
+
+ Standard styles are `"pygments"` (the default), `"kate"`,
+ `"monochrome"`, `"breezeDark"`, `"espresso"`, `"zenburn"`,
+ `"haddock"`, and `"tango"`. Alternatively, the path of a
+ `.theme` with a KDE syntax theme may be used (in this case,
+ the relevant file contents must also be included in `files`,
+ see below).
+
+ The default for HTML, EPUB, Docx, Ms, Man, and LaTeX output is
+ to use the internal highlighter with the default style; Typst
+ output relies on Typst's own syntax highlighting system by
+ default.
+
+`embed-resources`
+
+: Embed images, scripts, styles and other resources in an HTML
+ document using `data` URIs. Note that this will not work
+ unless the contents of all external resources are included
+ under `files`.
+
+`html-q-tags` (boolean, default false)
+
+: Use `<q>` elements in HTML instead of literal quotation marks.
+
+`ascii` (boolean, default false)
+
+: Use entities and escapes when possible to avoid non-ASCII
+ characters in the output.
+
+`reference-links` (boolean, default false)
+
+: Create reference links rather than inline links in Markdown output.
+
+`reference-location` (`"document"|"section"|"block"`)
+
+: Determines whether link references and footnotes are placed
+ at the end of the document, the end of the section, or the
+ end of the block (e.g. paragraph), in
+ certain formats. (See `pandoc(1)` under `--reference-location`.)
+
+`setext-headers` (boolean, default false)
+
+: Use Setext (underlined) headings instead of ATX (`#`-prefixed)
+ in Markdown output.
+
+`top-level-division` (`"default"|"part"|"chapter"|"section"`)
+
+: Determines how top-level headings are interpreted in
+ LaTeX, ConTeXt, DocBook, and TEI. The `"default"` value
+ tries to choose the best interpretation based on heuristics.
+
+`number-sections` (boolean, default false)
+
+: Automatically number sections (in supported formats).
+
+
+`number-offset` (array of integers)
+
+: Offsets to be added to each component of the section number.
+ For example, `[1]` will cause the first section to be
+ numbered "2" and the first subsection "2.1"; `[0,1]` will
+ cause the first section to be numbered "1" and the first
+ subsection "1.2."
+
+`html-math-method` (`"plain"|"webtex"|"gladtex"|"mathml"|"mathjax"|"katex"`)
+
+: Determines how math is represented in HTML.
+
+`listings` (boolean, default false)
+
+: Use the `listings` package to format code in LaTeX output.
+
+`incremental` (boolean, default false)
+
+: If true, lists appear incrementally by default in slide shows.
+
+`slide-level` (integer)
+
+: Heading level that deterimes slide divisions in slide shows.
+ The default is to pick the highest heading level under which
+ there is body text.
+
+`section-divs` (boolean, default false)
+
+: Arrange the document into a hierarchy of nested sections
+ based on the headings.
+
+`email-obfuscation` (`"none"|"references"|"javascript"`)
+
+: Determines how email addresses are obfuscated in HTML.
+
+`identifier-prefix` (string)
+
+: Prefix to be added to all automatically-generated identifiers.
+
+`title-prefix` (string)
+
+: Prefix to be added to the title in the HTML header.
+
+`reference-doc` (file path)
+
+: Reference doc to use in creating `docx` or `odt` or `pptx`.
+ See `pandoc(1)` under `--reference-doc` for details.
+ The contents of the file must be included under `files`.
+
+`split-level` (integer, default 1)
+
+: Heading level at which documents are split in EPUB or
+ chunked HTML.
+
+`epub-cover-image` (file path)
+
+: Cover image for EPUB.
+ The contents of the file must be included under `files`.
+
+`epub-metadata` (file path)
+
+: Path of file containing Dublin core XML elements to be used for
+ EPUB metadata. The contents of the file must be included
+ under `files`.
+
+`epub-subdirectory` (string, default "EPUB")
+
+: Name of content subdirectory in the EPUB container.
+
+`epub-fonts` (array of file paths)
+
+: Fonts to include in the EPUB. The fonts themselves must be
+ included in `files` (see below).
+
+`ipynb-output` (`"best"|"all"|"none"`)
+
+: Determines how ipynb output cells are treated. `all` means
+ that all of the data formats included in the original are
+ preserved. `none` means that the contents of data cells
+ are omitted. `best` causes pandoc to try to pick the
+ richest data block in each output cell that is compatible
+ with the output format.
+
+`citeproc` (boolean, default false)
+
+: Causes citations to be processed using citeproc. See
+ Citations in `pandoc(1)` for details.
+
+`bibliography` (array of file paths)
+
+: Files containing bibliographic data. The contents of the
+ files must be included in `files`.
+
+`csl` (file path)
+
+: CSL style file. The contents of the file must be included
+ in `files`.
+
+`cite-method` (`"citeproc"|"natbib"|"biblatex"`)
+
+: Determines how citations are formatted in LaTeX output.
+
+`files` (JSON mapping of file paths to base64-encoded strings)
+
+: Any files needed for the conversion, including images
+ referred to in the document source, should be included here.
+ Binary data must be base64-encoded. Textual data may be
+ left as it is, unless it is *also* valid base 64 data,
+ in which case it will be interpreted that way.
+
+## `/batch` endpoint
+
+The `/batch` endpoint behaves like the root endpoint,
+except for these two points:
+
+- It accepts a JSON array, each element of which is a JSON
+ object like the one expected by the root endpoint.
+- It returns a JSON array of JSON results.
+
+This endpoint can be used to convert a sequence of small
+snippets in one request.
+
+## `/version` endpoint
+
+The `/version` endpoint accepts a GET request and returns
+the pandoc version as a plain or JSON-encoded string,
+depending on Accept headers.
+
+## `/babelmark` endpoint
+
+The `/babelmark` endpoint accepts a GET request with
+the following query parameters:
+
+- `text` (required string)
+- `from` (optional string, default is `"markdown"`)
+- `to` (optional string, default is `"html"`)
+- `standalone` (optional boolean, default is `false`)
+
+It returns a JSON object with fields `html` and `version`.
+This endpoint is designed to support the
+[Babelmark](https://babelmark.github.io) website.
+
+# AUTHORS
+
+Copyright 2022 John MacFarlane (jgm@berkeley.edu). Released
+under the [GPL], version 2 or greater. This software carries no
+warranty of any kind. (See COPYRIGHT for full copyright and
+warranty notices.)
+
+[GPL]: https://www.gnu.org/copyleft/gpl.html "GNU General Public License"
+
diff --git a/documents/markdown/pandoc-md/doc_press.md b/documents/markdown/pandoc-md/doc_press.md
new file mode 100644
index 0000000..98b8d83
--- /dev/null
+++ b/documents/markdown/pandoc-md/doc_press.md
@@ -0,0 +1,156 @@
+% Press
+
+Here are some books, articles, and blogs that discuss pandoc:
+
+# Articles
+
+- [Pandoc](http://en.wikipedia.org/wiki/Pandoc) on Wikipedia.
+
+- Egon Willighagen, [Two years of explicit CiTO
+ annotations](https://doi.org/10.1186/s13321-023-00683-2).
+ Journal of Cheminformatics 15, 14 (2023). doi:
+ 10.1186/s13321-023-00683-2.
+
+- Albert Krewinkel, Juanjo Bazán, and Afron M. Smith,
+ ["JATS from Markdown: Developer friendly single-source
+ scholarly
+ publishing"](https://www.ncbi.nlm.nih.gov/books/NBK579698/),
+ *JATS-Con Proceedings 2022*.
+
+- A. Ohri and T. Schmah, ["Machine Translation of Mathematical
+ Text,"](https://doi.org/10.1109/ACCESS.2021.3063715) in
+ *IEEE Access*, vol. 9, pp. 38078-38086, 2021,
+ doi: 10.1109/ACCESS.2021.3063715.
+
+- Julien Dehut, ["En finir avec Word ! Pour une analyse des
+ enjeux relatifs aux traitements de texte et à leur
+ utilisation"](https://eriac.hypotheses.org/80),
+ *L'Atelier des Savoirs*, January 23, 2018.
+
+- Phillips, Lee. ["Technical Writing with Pandoc and
+ Panflute"](https://lee-phillips.org/panflute-gnuplot/).
+ Reproduced with permission from *Linux Journal*, September, 2017.
+
+- Krewinkel, Albert and Robert Winkler. ["Formatting Open
+ Science: agile creation of multiple document types by writing
+ academic manuscripts in pandoc
+ markdown."](https://peerj.com/preprints/2648/).
+ *PeerJ Preprints*.
+
+- Krijnen, Jacco, Doaitse Swierstra, and Marcos O. Viera. ["Expand:
+ Towards an Extensible Pandoc
+ System."](http://dx.doi.org/10.1007/978-3-319-04132-2_14)
+ *Practical Aspects of Declarative Languages* (Springer International
+ Publishing, 2014), 200--215.
+
+- Kielhorn, Axel. ["Multi-target publishing-Generating ePub, PDF, and
+ more, from Markdown using
+ pandoc."](https://www.tug.org/TUGboat/tb32-3/tb102kielhorn.pdf)
+ *TUGboat-TeX Users Group* 32, no. 3 (2011): 272.
+
+- Massimiliano Dominici. ["An Overview of Pandoc."](http://www.dw.tug.org/TUGboat/tb35-1/tb109dominici.pdf),
+ *TUGboat* 32 (2014), n. 1: 44-50.
+
+- Gieben, R. ["Writing I-Ds and RFCs Using Pandoc and a Bit of
+ XML."](https://tools.ietf.org/html/rfc7328.html) (RFC 7328, 2014).
+
+- Ovadia, Steven (2014). ["Markdown for Librarians and
+ Academics".](http://www.tandfonline.com/doi/pdf/10.1080/01639269.2014.904696)
+ *Behavioral & Social Sciences Librarian* 33 (2): 120–124.
+ doi:10.1080/01639269.2014.904696
+
+- Daniel Burgos and Alberto Corbí, "Semi-Automated Correction Tools for
+ Mathematics-Based Exercises in MOOC Environments,"
+ [*International Journal of Artificial Intelligence and Interactive Multimedia*,
+ 3](http://www.ijimai.org/journal/sites/default/files/journals/IJIMAI20153_3.pdf), 89-95.
+
+- Garnett A, Alperin JP, Willinsky J. "The Public Knowledge Project XML
+ Publishing Service and meTypeset: Don't call it 'Yet Another
+ Word-to-JATS Conversion Kit'." *Journal Article Tag Suite
+ Conference (JATS-Con) Proceedings* 2015 [Internet]. Bethesda (MD):
+ National Center for Biotechnology Information (US); 2015. Available
+ from: <http://www.ncbi.nlm.nih.gov/books/NBK279666/>
+
+# Books
+
+- Digital Publishing Toolkit Collective,
+ [*From Print to EBooks: A Hybrid Publishing Toolkit for the Arts*](http://networkcultures.org/blog/publication/from-print-to-ebooks-a-hybrid-publishing-toolkit-for-the-arts/)
+ (Institute of Network Cultures), ch. 6.
+
+- Hasecke, Jan Ulrich. [*Das ZEN von Pandoc: Bücher und E-Books einfach
+und professionell
+produzieren*](http://www.amazon.com/Das-ZEN-von-Pandoc-professionell-ebook/dp/B00TQ55D34).
+
+- Michael Kofler,
+ [*Markdown und
+ Pandoc*](http://www.amazon.com/Markdown-Pandoc-German-Michael-Kofler-ebook/dp/B00CX7HIOO/ref=sr_1_1?ie=UTF8&qid=1424543894&sr=8-1&keywords=pandoc).
+
+# Blog posts
+
+- Grec, Dan (2021), ["How I self-published a professional paperback and
+ eBook using LaTeX and
+ Pandoc"](http://theroadchoseme.com/how-i-self-published-a-professional-paperback-and-ebook-using-latex-and-pandoc),
+ The Road Chose Me.
+
+- Grandesso, Piero (2018-03-23). ["A pandoc-based layout workflow for
+ scholarly journals"](http://pierog.it/en/2018/03/markdown-workflow/).
+ Piero G: Notes on Open Access, Scholarly Publishing etc.
+
+- Krewinkel, Albert (2017-12-23). ["Extending pandoc with
+ Lua"](http://lua.space/general/extending-pandoc-with-lua).
+ Lua.Space.
+
+- Pullum, Geoffrey (2017-03-13). ["Word-Processing
+ Misery"](http://www.chronicle.com/blogs/linguafranca/2017/03/13/word-processing-hell/).
+ The Chronicle of Higher Education Blogs: Lingua Franca.
+
+- Curiositry (2017-02-28). ["Pandoc for
+ Writers"](http://www.autodidacts.io/convert-markdown-to-standard-manuscript-format-odts-docs-and-pdfs-with-pandoc/).
+ The Autodidacts.
+
+- Tenen, Dennis and Grant Wythoff (2014-03-19). ["Sustainable Authorship
+ in Plain Text using Pandoc and Markdown"](http://programminghistorian.org/lessons/sustainable-authorship-in-plain-text-using-pandoc-and-markdown). The Programming
+ Historian.
+
+- Mullen, Lincoln (2012-02-23). ["Pandoc Converts All Your (Text)
+ Documents"](http://chronicle.com/blogs/profhacker/pandoc-converts-all-your-text-documents/38700), The Chronicle of Higher Education Blogs: ProfHacker.
+
+- Mullen, Lincoln (2012-03-20). ["Make Your Own E-Books with
+ Pandoc"](http://chronicle.com/blogs/profhacker/make-your-own-e-books-with-pandoc/39067). The Chronicle of Higher Education Blogs: ProfHacker.
+
+- Fenner, Martin (2013-12-12). ["From Markdown to JATS XML in one
+ Step"](http://blog.martinfenner.org/2013/12/12/from-markdown-to-jats-xml-in-one-step/). Gobbledygook.
+
+- McDaniel, W. Caleb (2012-09-28). ["Why (and How) I Wrote My Academic
+ Book in Plain Text"](http://wcm1.web.rice.edu/my-academic-book-in-plain-text.html).
+
+- Healy, Kieran (2014-01-23). ["Plain Text, Papers, Pandoc"](http://kieranhealy.org/blog/archives/2014/01/23/plain-text/).
+
+- Till, Kaitlyn, Shed Simas, and Velma Larkai (2014-04-14). ["The Flying
+ Narwhal: Small mag workflow"](http://tkbr.ccsp.sfu.ca/mpub/2014/04/14/the-flying-narwhal-small-mag-workflow/#more-639). Publishing @ SFU.
+
+- Maxwell, John (2013-11-01). ["Building Publishing Workflows with
+ Pandoc and Git"](http://www.ccsp.sfu.ca/2013/11/building-publishing-workflows-with-pandoc-and-git/). Publishing @ SFU.
+
+- Maxwell, John (2014-02-26). ["On Pandoc"](http://tkbr.ccsp.sfu.ca:5001/Slides/On%20Pandoc). eBound Canada: Digital Production Workshop, Vancouver, BC.
+
+- Puppet labs (2013-11-28).
+ ["How We Automated our Ebook Builds with Pandoc and KindleGen."](http://puppetlabs.com/blog/automated-ebook-generation-convert-markdown-epub-mobi-pandoc-kindlegen).
+
+- Fenner, Martin (2014-08-25).
+ ["Using Microsoft Word with
+ git."](http://blog.martinfenner.org/2014/08/25/using-microsoft-word-with-git/).
+
+- Wouter Soudan (2015-12-02). ["From Word to Markdown to InDesign:
+ Fully automated typesetting."](http://rhythmus.be/md2indd/)
+
+- Mattia Tezzele (2015-11-24), ["Typesetting automation: A Plain-text workflow for painless
+ production of personal documents & offline
+ correspondence---featuring Pandoc, LaTeX, and a simple
+ makefile](http://mrzool.cc/writing/typesetting-automation/)
+
+# Talks
+
+- MacFarlane, John (2014-05-17). ["Pandoc for Haskell Hackers"](http://johnmacfarlane.net/BayHac2014/#/). BayHac 2014, Mountain View, CA.
+
+
diff --git a/documents/markdown/pandoc-md/doc_short-guide-to-pandocs-sources.md b/documents/markdown/pandoc-md/doc_short-guide-to-pandocs-sources.md
new file mode 100644
index 0000000..18fa9d2
--- /dev/null
+++ b/documents/markdown/pandoc-md/doc_short-guide-to-pandocs-sources.md
@@ -0,0 +1,259 @@
+---
+title: Short guide to pandoc's sources
+subtitle: Laying a path for code wanderers
+author: Albert Krewinkel
+date: 2021-06-07
+---
+
+Pandoc, the universal document converter, can serve as a nice intro
+into functional programming with Haskell. For many contributors,
+including the author of this guide, pandoc was their first real
+exposure to this language. Despite its impressive size of more than
+60.000 lines of Haskell code (excluding the test suite), pandoc is
+still very approachable due to its modular architecture. It can
+serve as an interesting subject for learning.
+
+This guide exists to navigate the large amount of sources, to
+lay-out a path that can be followed for learning, and to explain the
+underlying concepts.
+
+A basic understanding of Haskell and of pandoc's functionality is
+assumed.
+
+# Getting the code
+
+Pandoc has a publicly accessible git repository on GitHub:
+<https://github.com/jgm/pandoc>. To get a local copy of the source:
+
+ git clone https://github.com/jgm/pandoc
+
+The source for the main pandoc program is `app/pandoc.hs`. The
+source for the pandoc library is in `src/`, the source for the tests
+is in `test/`, and the source for the benchmarks is in `benchmark/`.
+
+Core type definitions are in the separate [*pandoc-types* repo].
+Get it with
+
+ git clone https://github.com/jgm/pandoc-types
+
+The organization of library and test sources is identical to the
+main repo.
+
+[*pandoc-types* repo]: https://github.com/jgm/pandoc-types
+
+# Document representation
+
+The way documents are represented in pandoc is part of its success.
+Every document is read into one central data structure, the
+so-called *abstract syntax tree* (AST).
+
+The AST is defined in module `Text.Pandoc.Definition` in package
+[*pandoc-types*].
+
+It is not necessary to understand the AST in detail, just check-out
+the following points:
+
+ * The [`Pandoc`][def-Pandoc] type serves as the central structure.
+
+ * A document has metadata and a list of "block" elements.
+
+ * There are various types of [blocks][def-Block]; some contain raw
+ text, others contain "Inline" elements.
+
+ * [Inlines][def-Inline] are "running text", with many different
+ types. The most important constructors are `Str` (a word),
+ `Space` (a space char), `Emph` (emphasized text), and `Strong`
+ (strongly emphasized text). It's worth checking their
+ definitions.
+
+ * Element attributes are captured as [`Attr`][def-Attr], which is a
+ triple of the element identifier, its classes, and the key-value
+ pairs.^[For plans to change this see [jgm/pandoc-types#88].]
+
+[*pandoc-types*]: https://hackage.haskell.org/package/pandoc-types
+[jgm/pandoc-types#88]: https://github.com/jgm/pandoc-types/issues/88
+[def-Pandoc]: https://hackage.haskell.org/package/pandoc-types/docs/src/Text.Pandoc.Definition.html#Pandoc
+[def-Block]: https://hackage.haskell.org/package/pandoc-types/docs/src/Text.Pandoc.Definition.html#Block
+[def-Inline]: https://hackage.haskell.org/package/pandoc-types/docs/src/Text.Pandoc.Definition.html#Inline
+[def-Attr]: https://hackage.haskell.org/package/pandoc-types/docs/src/Text.Pandoc.Definition.html#Attr
+
+# Basic architecture
+
+Take a look at pandoc's source files. The code is below the `src`
+directory, in the `Text.Pandoc` module. The basic flow is:
+
+ 1. Document is parsed into the internal representation by a
+ *reader*;
+
+ 2. the document AST is modified (optional);
+
+ 3. then the internal representation is converted into the target
+ format by a *writer*.
+
+The [*readers*] can be found in `Text.Pandoc.Readers`, while the
+[*writers*] are submodules of `Text.Pandoc.Writers`. The document
+modification step is powerful and used in different ways, e.g., in
+[*filters*].
+
+These parts are the "muscles" of pandoc, which do the heavy lifting.
+Everything else can be thought of as the bones and fibers to which
+these parts are attached and which make them usable.
+
+# Writers
+
+Writers are usually simpler than readers and therefore easier to
+grasp.
+
+Broadly speaking, there are three kind of writers:
+
+ 1. Text writers: these are used for lightweight markup languages
+ and generate plain text output. Examples: Markdown, Org,
+ reStructuredText.
+ 2. XML writers, which convert the AST into structured XML.
+ Examples: HTML, JATS.
+ 3. Binary writers, which are like XML writers, but combine the
+ output with other data and zip it into a single file. Examples:
+ docx, epub.
+
+ Most writers follow a common pattern and have three main functions:
+ docTo*Format*, blockTo*Format* and inlineTo*Format*. Each converts
+ the `Pandoc`, `Block`, and `Inline` elements, respectively. The
+ *XWiki* and *TEI* writers are comparatively simple and suitable
+ samples when taking a first look.
+
+ Most writers are self-contained in that most of the conversion code
+ is within a single module. However, newer writers often use a
+ different setup: those are built around modules from an external
+ package. The details of how to serialize the document are not in
+ the writer module itself, but in an external module. The writer
+ only has to convert pandoc's AST into the document representation
+ used by the module. Good examples: commonmark, jira.
+
+## DocLayout
+
+All writers build on the `doclayout` package. It can be thought of
+as a pretty printer with extra features suitable for lightweight
+markup languages. E.g., multiple blank lines are collapsed into a
+single blank line, unless multiple blank lines are specifically
+requested. This simplifies the code significantly.
+
+See the repo at https://github.com/jgm/doclayout, and the [hackage
+documentation](https://hackage.haskell.org/package/doclayout)
+
+# Readers
+
+The same distinction that applies to writers also applies to
+readers. Readers for XML formats use XML parsing libraries, while
+plain text formats are parsed with [parsec].
+
+## Builders
+
+The plain type constructors from the [`Text.Pandoc.Definition`]
+module can be difficult to use, which is why the module
+[`Text.Pandoc.Builder`] exists. It offers functions to conveniently
+build and combine AST elements.
+
+The most interesting and important types in `Builder` are
+[`Blocks`][def-Blocks] and [`Inlines`][def-Inlines]. All type
+constructors use simple lists for sequences of AST elements.
+Building lists can be awkward and often comes with bad performance
+characteristics, esp. when appending. The `Blocks` and `Inlines`
+types are better suited for these operations and are therefore used
+extensively in builder functions.
+
+The builder functions are named with the convention that the suffix
+`With` is added if the first argument is an `Attr`; there is usually
+another function without that suffix, creating an element with no
+attributes.
+
+[def-Blocks]: https://hackage.haskell.org/package/pandoc-types/docs/src/Text.Pandoc.Builder.html#Blocks
+[def-Inlines]: https://hackage.haskell.org/package/pandoc-types/docs/src/Text.Pandoc.Builder.html#Inlines
+[parsec]: https://hackage.haskell.org/package/parsec
+
+# PandocMonad
+
+Looking at the readers and writers, one will notice that they all
+operate within the `PandocMonad` type class. This class gives access
+to options, file operations, and other shared information. The
+typeclass has two main implementations: one operates in IO, so on
+the "real world", while the other provides a pure functional
+interface, suitable to "mock" an environment for testing.
+
+# Document modifications
+
+One of the big advantages of a central document structure is that it
+allows document modifications via a unified interface. This section
+describes the multiple ways in which the document can be altered.
+
+## Walkable
+
+Document traversal happens through the `Walkable` class in module
+`Text.Pandoc.Walk` ([*pandoc-types* package]).
+
+## Transformations
+
+Transformations are simple modifications controllable through
+command-line options.
+
+## Filters
+
+Filters allow to use Lua or any external language to perform
+document transformations.
+
+
+[`Text.Pandoc.Builder`]: https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Builder.html
+[`Text.Pandoc.Definition`]: https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html
+
+# Module overview
+
+The library is structured as follows:
+
+ - `Text.Pandoc` is a top-level module that exports what is needed
+ by most users of the library. Any patches that add new readers
+ or writers will need to make changes here, too.
+ - `Text.Pandoc.Definition` (in `pandoc-types`) defines the types
+ used for representing a pandoc document.
+ - `Text.Pandoc.Builder` (in `pandoc-types`) provides functions for
+ building pandoc documents programmatically.
+ - `Text.Pandoc.Generics` (in `pandoc-types`) provides functions allowing
+ you to promote functions that operate on parts of pandoc documents
+ to functions that operate on whole pandoc documents, walking the
+ tree automatically.
+ - `Text.Pandoc.Readers.*` are the readers, and `Text.Pandoc.Writers.*`
+ are the writers.
+ - `Text.Pandoc.Citeproc.*` contain the code for citation handling,
+ including an interface to the [citeproc] library.
+ - `Text.Pandoc.Data` is used to embed data files when the `embed_data_files`
+ cabal flag is used.
+ - `Text.Pandoc.Emoji` is a thin wrapper around [emojis].
+ - `Text.Pandoc.Highlighting` contains the interface to the
+ skylighting library, which is used for code syntax highlighting.
+ - `Text.Pandoc.ImageSize` is a utility module containing functions for
+ calculating image sizes from the contents of image files.
+ - `Text.Pandoc.MIME` contains functions for associating MIME types
+ with extensions.
+ - `Text.Pandoc.Lua.*` implement Lua filters.
+ - `Text.Pandoc.Options` defines reader and writer options.
+ - `Text.Pandoc.PDF` contains functions for producing PDFs.
+ - `Text.Pandoc.Parsing` contains parsing functions used in multiple readers.
+ the needs of pandoc.
+ - `Text.Pandoc.SelfContained` contains functions for making an HTML
+ file "self-contained," by importing remotely linked images, CSS,
+ and JavaScript and turning them into `data:` URLs.
+ - `Text.Pandoc.Shared` is a grab-bag of shared utility functions.
+ - `Text.Pandoc.Writers.Shared` contains utilities used in writers only.
+ - `Text.Pandoc.Slides` contains functions for splitting a markdown document
+ into slides, using the conventions described in the MANUAL.
+ - `Text.Pandoc.Templates` defines pandoc's templating system.
+ - `Text.Pandoc.UTF8` contains functions for converting text to and from
+ UTF8 bytestrings (strict and lazy).
+ - `Text.Pandoc.Asciify` contains functions to derive ascii versions of
+ identifiers that use accented characters.
+ - `Text.Pandoc.UUID` contains functions for generating UUIDs.
+ - `Text.Pandoc.XML` contains functions for formatting XML.
+
+
+<!--
+# Templating
+## DocTemplates
+-->
diff --git a/documents/markdown/pandoc-md/doc_typst-property-output.md b/documents/markdown/pandoc-md/doc_typst-property-output.md
new file mode 100644
index 0000000..8a1907b
--- /dev/null
+++ b/documents/markdown/pandoc-md/doc_typst-property-output.md
@@ -0,0 +1,162 @@
+---
+title: Typst property output
+author: Gordon Woodhull
+---
+
+Pandoc Typst property output
+============================
+
+In addition to the output of structural properties built into Pandoc's Typst Writer, the Writer can also output non-structural Typst properties. This is enabled by setting attributes with keys of the form `typst:prop` or `typst:text:prop` on supported elements.
+
+
+Typst properties
+----------------
+
+[Typst](https://typst.app/) allows specification of visual and layout properties as parameters to elements
+
+```typst
+#block(fill=orange)[Hello]
+```
+
+and set-rules
+
+```typst
+#set text(fill=blue); Hello
+```
+
+The parameter values are [Typst code](https://typst.app/docs/reference/syntax/#modes) that can use any features of the Typst language.
+
+Pandoc Typst property output
+----------------------------
+
+For the set of supported Pandoc elements, the Pandoc Typst Writer will output attributes as parameters to corresponding Typst elements or set-text rules.
+
+The Typst Writer looks for attributes with keys of the form `typst:prop` or `typst:text:prop` and assumes the values are raw Typst code.
+
+`prop` is the name of the property to set.
+
+For example, `pandoc -f html -t typst` with HTML input
+
+```html
+<div typst:inset="10pt">foo</div>
+```
+
+produces Typst output
+
+```typst
+#block(inset: 10pt)[
+foo
+]
+```
+
+and with HTML input
+
+```html
+<div typst:text:fill="purple">foo</div>
+```
+
+it produces Typst output
+
+```typst
+#block[
+#set text(fill: purple); foo
+]
+```
+
+The Typst Writer does not check the validity of `prop` or the value. Since Typst is a statically typed language, improper property names or values usually result in compilation failure.
+
+Supported elements
+------------------
+
+The following Pandoc AST elements are currently supported. More may be supported in the future.
+
+- [Span](https://pandoc.org/lua-filters.html#type-span)
+
+ `typst:text:prop`
+
+ : The content is wrapped in a Typst [text element](https://typst.app/docs/reference/text/text/) with the specified properties set.
+
+- [Div](https://pandoc.org/lua-filters.html#type-div)
+
+ `typst:prop`
+
+ : The `prop` is output as a parameter to the Typst [block element](https://typst.app/docs/reference/layout/block/).
+
+ `typst:text:prop`
+
+ : The `prop` is output as a parameter to a set-text rule at the start of the block content.
+
+- [Table](https://pandoc.org/lua-filters.html#type-table)
+
+ `typst:prop`
+
+ : The `prop` is output as a parameter to the Typst [table element](https://typst.app/docs/reference/model/table/).
+
+ `typst:text:prop`
+
+ : The table is wrapped in a Typst [text element](https://typst.app/docs/reference/text/text/) with `prop` as one of its parameters.
+
+ `typst:no-figure` (class)
+
+ : By default, Pandoc will wrap the table in a Typst [figure element](https://typst.app/docs/reference/model/figure/). If the table has this class, only the table element itself will be emitted. This avoids Typst's crossreference counter of kind `table` from being incremented.
+
+ `typst:figure:kind`
+
+ : If this attribute is set, Pandoc will wrap the table in a Typst [figure element](https://typst.app/docs/reference/model/figure/) with the specified `kind` attribute. This is useful for tables that should be cross-referenced as something other than `Table ...` in the document. Typst will use the `kind` attribute to increment the corresponding counter: `raw` and `image`.
+
+- Table [Cell](https://pandoc.org/lua-filters.html#type-cell)
+
+ `typst:prop`
+
+ : The `prop` is output as a parameter to the Typst table [cell element](https://typst.app/docs/reference/model/table/#definitions-cell).
+
+ `typst:text:prop`
+
+ : The `prop` is output as a parameter to a set-text rule at the start of the cell content.
+
+
+Lua filter example
+------------------
+
+Here is a minimal example of a Lua filter which translates the CSS [color property](https://developer.mozilla.org/en-US/docs/Web/CSS/color) on a span element to the equivalent [fill parameter](https://typst.app/docs/reference/text/text/#parameters-fill) on a Typst text element.
+
+```lua
+function styleToTable(style)
+ if not style then return nil end
+ local ret = {}
+ for clause in style:gmatch('([^;]+)') do
+ k,v = clause:match("([%w-]+)%s*:%s*(.*)$")
+ ret[k] = v
+ end
+ return ret
+end
+
+function Span(span)
+ local style = styleToTable(span.attributes['style'])
+ if not style then return end
+ if style['color'] then
+ span.attributes['typst:text:fill'] = style['color']
+ end
+ return span
+end
+```
+
+Given the HTML input
+
+```html
+<p>Here is some <span style="color:orange">orange text</span>.</p>
+```
+
+the command
+
+```sh
+pandoc -f html -t typst --lua-filter ./typst-property-example.lua
+```
+
+will produce the Typst output
+
+```typst
+Here is some #text(fill: orange)[orange text].
+```
+
+Of course, this simple filter will only work for Typst's [predefined colors](https://typst.app/docs/reference/visualize/color/#predefined-colors). A more complete filter would need to translate the value as well.
diff --git a/documents/markdown/pandoc-md/doc_using-the-pandoc-api.md b/documents/markdown/pandoc-md/doc_using-the-pandoc-api.md
new file mode 100644
index 0000000..70075fd
--- /dev/null
+++ b/documents/markdown/pandoc-md/doc_using-the-pandoc-api.md
@@ -0,0 +1,486 @@
+% Using the pandoc API
+% John MacFarlane
+
+Pandoc can be used as a Haskell library, to write your own
+conversion tools or power a web application. This document
+offers an introduction to using the pandoc API.
+
+Detailed API documentation at the level of individual functions
+and types is available at
+<https://hackage.haskell.org/package/pandoc>.
+
+# Pandoc's architecture
+
+Pandoc is structured as a set of *readers*, which translate
+various input formats into an abstract syntax tree (the
+Pandoc AST) representing a structured document, and a set of
+*writers*, which render this AST into various output formats.
+Pictorially:
+
+```
+[input format] ==reader==> [Pandoc AST] ==writer==> [output format]
+```
+
+This architecture allows pandoc to perform $M \times N$
+conversions with $M$ readers and $N$ writers.
+
+The Pandoc AST is defined in the
+[pandoc-types](https://hackage.haskell.org/package/pandoc-types)
+package. You should start by looking at the Haddock
+documentation for [Text.Pandoc.Definition]. As you'll see, a
+`Pandoc` is composed of some metadata and a list of `Block`s.
+There are various kinds of `Block`, including `Para`
+(paragraph), `Header` (section heading), and `BlockQuote`. Some
+of the `Block`s (like `BlockQuote`) contain lists of `Block`s,
+while others (like `Para`) contain lists of `Inline`s, and still
+others (like `CodeBlock`) contain plain text or nothing.
+`Inline`s are the basic elements of paragraphs. The distinction
+between `Block` and `Inline` in the type system makes it
+impossible to represent, for example, a link (`Inline`) whose
+link text is a block quote (`Block`). This expressive
+limitation is mostly a help rather than a hindrance, since many
+of the formats pandoc supports have similar limitations.
+
+The best way to explore the pandoc AST is to use `pandoc -t
+native`, which will display the AST corresponding to some
+Markdown input:
+
+```
+% echo -e "1. *foo*\n2. bar" | pandoc -t native
+[OrderedList (1,Decimal,Period)
+ [[Plain [Emph [Str "foo"]]]
+ ,[Plain [Str "bar"]]]]
+```
+
+# A simple example
+
+Here is a simple example of the use of a pandoc reader and
+writer to perform a conversion:
+
+```haskell
+import Text.Pandoc
+import qualified Data.Text as T
+import qualified Data.Text.IO as TIO
+
+main :: IO ()
+main = do
+ result <- runIO $ do
+ doc <- readMarkdown def (T.pack "[testing](url)")
+ writeRST def doc
+ rst <- handleError result
+ TIO.putStrLn rst
+```
+
+Some notes:
+
+1. The first part constructs a conversion pipeline: the input
+ string is passed to `readMarkdown`, and the resulting Pandoc
+ AST (`doc`) is then rendered by `writeRST`. The conversion
+ pipeline is "run" by `runIO`---more on that below.
+
+2. `result` has the type `Either PandocError Text`. We could
+ pattern-match on this manually, but it's simpler in this
+ context to use the `handleError` function from
+ Text.Pandoc.Error. This exits with an appropriate error
+ code and message if the value is a `Left`, and returns the
+ `Text` if the value is a `Right`.
+
+# The PandocMonad class
+
+Let's look at the types of `readMarkdown` and `writeRST`:
+
+```haskell
+readMarkdown :: (PandocMonad m, ToSources a)
+ => ReaderOptions
+ -> a
+ -> m Pandoc
+writeRST :: PandocMonad m
+ => WriterOptions
+ -> Pandoc
+ -> m Text
+```
+
+The `PandocMonad m =>` part is a typeclass constraint.
+It says that `readMarkdown` and `writeRST` define computations
+that can be used in any instance of the `PandocMonad`
+type class. `PandocMonad` is defined in the module
+[Text.Pandoc.Class].
+
+Two instances of `PandocMonad` are provided: `PandocIO` and
+`PandocPure`. The difference is that computations run in
+`PandocIO` are allowed to do IO (for example, read a file),
+while computations in `PandocPure` are free of any side effects.
+`PandocPure` is useful for sandboxed environments, when you want
+to prevent users from doing anything malicious. To run the
+conversion in `PandocIO`, use `runIO` (as above). To run it in
+`PandocPure`, use `runPure`.
+
+As you can see from the Haddocks, [Text.Pandoc.Class]
+exports many auxiliary functions that can be used in any
+instance of `PandocMonad`. For example:
+
+```haskell
+-- | Get the verbosity level.
+getVerbosity :: PandocMonad m => m Verbosity
+
+-- | Set the verbosity level.
+setVerbosity :: PandocMonad m => Verbosity -> m ()
+
+-- Get the accumulated log messages (in temporal order).
+getLog :: PandocMonad m => m [LogMessage]
+getLog = reverse <$> getsCommonState stLog
+
+-- | Log a message using 'logOutput'. Note that 'logOutput' is
+-- called only if the verbosity level exceeds the level of the
+-- message, but the message is added to the list of log messages
+-- that will be retrieved by 'getLog' regardless of its verbosity level.
+report :: PandocMonad m => LogMessage -> m ()
+
+-- | Fetch an image or other item from the local filesystem or the net.
+-- Returns raw content and maybe mime type.
+fetchItem :: PandocMonad m
+ => Text
+ -> m (B.ByteString, Maybe MimeType)
+
+-- Set the resource path searched by 'fetchItem'.
+setResourcePath :: PandocMonad m => [FilePath] -> m ()
+```
+
+If we wanted more verbose informational messages
+during the conversion we defined in the previous
+section, we could do this:
+
+```haskell
+ result <- runIO $ do
+ setVerbosity INFO
+ doc <- readMarkdown def (T.pack "[testing](url)")
+ writeRST def doc
+```
+
+Note that `PandocIO` is an instance of `MonadIO`, so you can
+use `liftIO` to perform arbitrary IO operations inside a pandoc
+conversion chain.
+
+`readMarkdown` is polymorphic in its second argument, which
+can be any type that is an instance of the `ToSources`
+typeclass. You can use `Text`, as in the example above.
+But you can also use `[(FilePath, Text)]`, if the input comes
+from multiple files and you want to track source positions
+accurately.
+
+# Options
+
+The first argument of each reader or writer is for
+options controlling the behavior of the reader or writer:
+`ReaderOptions` for readers and `WriterOptions`
+for writers. These are defined in [Text.Pandoc.Options]. It is
+a good idea to study these options to see what can be adjusted.
+
+`def` (from Data.Default) denotes a default value for
+each kind of option. (You can also use `defaultWriterOptions`
+and `defaultReaderOptions`.) Generally you'll want to use
+the defaults and modify them only when needed, for example:
+
+```haskell
+ writeRST def{ writerReferenceLinks = True }
+```
+
+Some particularly important options to know about:
+
+1. `writerTemplate`: By default, this is `Nothing`, which
+ means that a document fragment will be produced. If you
+ want a full document, you need to specify `Just template`,
+ where `template` is a `Template Text` from
+ [Text.Pandoc.Templates] containing the template's
+ contents (not the path).
+
+2. `readerExtensions` and `writerExtensions`: These specify
+ the extensions to be used in parsing and rendering.
+ Extensions are defined in [Text.Pandoc.Extensions].
+
+# Builder
+
+Sometimes it's useful to construct a Pandoc document
+programmatically. To make this easier we provide the
+module [Text.Pandoc.Builder] `pandoc-types`.
+
+Because concatenating lists is slow, we use special
+types `Inlines` and `Blocks` that wrap a `Sequence` of
+`Inline` and `Block` elements. These are instances
+of the Monoid typeclass and can easily be concatenated:
+
+```haskell
+import Text.Pandoc.Builder
+
+mydoc :: Pandoc
+mydoc = doc $ header 1 (text (T.pack "Hello!"))
+ <> para (emph (text (T.pack "hello world")) <> text (T.pack "."))
+
+main :: IO ()
+main = print mydoc
+```
+
+If you use the `OverloadedStrings` pragma, you can
+simplify this further:
+
+```haskell
+mydoc = doc $ header 1 "Hello!"
+ <> para (emph "hello world" <> ".")
+```
+
+Here's a more realistic example. Suppose your boss says: write
+me a letter in Word listing all the filling stations in Chicago
+that take the Voyager card. You find some JSON data in this
+format (`fuel.json`):
+
+```json
+[ {
+ "state" : "IL",
+ "city" : "Chicago",
+ "fuel_type_code" : "CNG",
+ "zip" : "60607",
+ "station_name" : "Clean Energy - Yellow Cab",
+ "cards_accepted" : "A D M V Voyager Wright_Exp CleanEnergy",
+ "street_address" : "540 W Grenshaw"
+}, ...
+```
+
+And then use aeson and pandoc to parse the JSON and create
+the Word document:
+
+```haskell
+{-# LANGUAGE OverloadedStrings #-}
+import Text.Pandoc.Builder
+import Text.Pandoc
+import Data.Monoid ((<>), mempty, mconcat)
+import Data.Aeson
+import Control.Applicative
+import Control.Monad (mzero)
+import qualified Data.ByteString.Lazy as BL
+import qualified Data.Text as T
+import Data.List (intersperse)
+
+data Station = Station{
+ address :: T.Text
+ , name :: T.Text
+ , cardsAccepted :: [T.Text]
+ } deriving Show
+
+instance FromJSON Station where
+ parseJSON (Object v) = Station <$>
+ v .: "street_address" <*>
+ v .: "station_name" <*>
+ (T.words <$> (v .:? "cards_accepted" .!= ""))
+ parseJSON _ = mzero
+
+createLetter :: [Station] -> Pandoc
+createLetter stations = doc $
+ para "Dear Boss:" <>
+ para "Here are the CNG stations that accept Voyager cards:" <>
+ simpleTable [plain "Station", plain "Address", plain "Cards accepted"]
+ (map stationToRow stations) <>
+ para "Your loyal servant," <>
+ plain (image "JohnHancock.png" "" mempty)
+ where
+ stationToRow station =
+ [ plain (text $ name station)
+ , plain (text $ address station)
+ , plain (mconcat $ intersperse linebreak
+ $ map text $ cardsAccepted station)
+ ]
+
+main :: IO ()
+main = do
+ json <- BL.readFile "fuel.json"
+ let letter = case decode json of
+ Just stations -> createLetter [s | s <- stations,
+ "Voyager" `elem` cardsAccepted s]
+ Nothing -> error "Could not decode JSON"
+ docx <- runIO (writeDocx def letter) >>= handleError
+ BL.writeFile "letter.docx" docx
+ putStrLn "Created letter.docx"
+```
+
+Voila! You've written the letter without using Word and
+without looking at the data.
+
+# Data files
+
+Pandoc has a number of data files, which can be found in the
+`data/` subdirectory of the repository. These are installed
+with pandoc (or, if pandoc was compiled with the
+`embed_data_files` flag, they are embedded in the binary).
+You can retrieve data files using `readDataFile` from
+Text.Pandoc.Class. `readDataFile` will first look for the
+file in the "user data directory" (`setUserDataDir`,
+`getUserDataDir`), and if it is not found there, it will
+return the default installed with the system.
+To force the use of the default, `setUserDataDir Nothing`.
+
+# Metadata files
+
+Pandoc can add metadata to documents, as described in the
+User's Guide. Similar to data files, metadata YAML files can
+be retrieved using `readMetadataFile` from Text.Pandoc.Class.
+`readMetadataFile` will first look for the file in the working
+directory, and if it is not found there, it will look for it
+in the `metadata` subdirectory of the user data directory
+(`setUserDataDir`, `getUserDataDir`).
+
+# Templates
+
+Pandoc has its own template system, described in the User's
+Guide. To retrieve the default template for a system,
+use `getDefaultTemplate` from [Text.Pandoc.Templates].
+Note that this looks first in the
+`templates` subdirectory of the user data directory, allowing
+users to override the system defaults. If you want to disable
+this behavior, use `setUserDataDir Nothing`.
+
+To render a template, use `renderTemplate'`, which takes two
+arguments, a template (Text) and a context (any instance
+of ToJSON). If you want to create a context from the metadata
+part of a Pandoc document, use `metaToJSON'` from
+[Text.Pandoc.Writers.Shared]. If you also want to incorporate
+values from variables, use `metaToJSON` instead, and make sure
+`writerVariables` is set in `WriterOptions`.
+
+
+# Handling errors and warnings
+
+`runIO` and `runPure` return an `Either PandocError a`. All errors
+raised in running a `PandocMonad` computation will be trapped
+and returned as a `Left` value, so they can be handled by
+the calling program. To see the constructors for `PandocError`,
+see the documentation for [Text.Pandoc.Error].
+
+To raise a `PandocError` from inside a `PandocMonad` computation,
+use `throwError`.
+
+In addition to errors, which stop execution of the conversion
+pipeline, one can generate informational messages.
+Use `report` from [Text.Pandoc.Class] to issue a `LogMessage`.
+For a list of constructors for `LogMessage`, see
+[Text.Pandoc.Logging]. Note that each type of log message
+is associated with a verbosity level. The verbosity level
+(`setVerbosity`/`getVerbosity`) determines whether the report
+will be printed to stderr (when running in `PandocIO`), but
+regardless of verbosity level, all reported messages are stored
+internally and may be retrieved using `getLog`.
+
+# Walking the AST
+
+It is often useful to walk the Pandoc AST either to extract
+information (e.g., what are all the URLs linked to in this
+document?, do all the code samples compile?) or to transform a
+document (e.g., increase the level of every section header,
+remove emphasis, or replace specially marked code blocks with
+images). To make this easier and more efficient, `pandoc-types`
+includes a module [Text.Pandoc.Walk].
+
+Here's the essential documentation:
+
+```haskell
+class Walkable a b where
+ -- | @walk f x@ walks the structure @x@ (bottom up) and replaces every
+ -- occurrence of an @a@ with the result of applying @f@ to it.
+ walk :: (a -> a) -> b -> b
+ walk f = runIdentity . walkM (return . f)
+ -- | A monadic version of 'walk'.
+ walkM :: (Monad m, Functor m) => (a -> m a) -> b -> m b
+ -- | @query f x@ walks the structure @x@ (bottom up) and applies @f@
+ -- to every @a@, appending the results.
+ query :: Monoid c => (a -> c) -> b -> c
+```
+
+`Walkable` instances are defined for most combinations of
+Pandoc types. For example, the `Walkable Inline Block`
+instance allows you to take a function `Inline -> Inline`
+and apply it over every inline in a `Block`. And
+`Walkable [Inline] Pandoc` allows you to take a function
+`[Inline] -> [Inline]` and apply it over every maximal
+list of `Inline`s in a `Pandoc`.
+
+Here's a simple example of a function that promotes
+the levels of headers:
+
+```haskell
+promoteHeaderLevels :: Pandoc -> Pandoc
+promoteHeaderLevels = walk promote
+ where promote :: Block -> Block
+ promote (Header lev attr ils) = Header (lev + 1) attr ils
+ promote x = x
+```
+
+`walkM` is a monadic version of `walk`; it can be used, for
+example, when you need your transformations to perform IO
+operations, use PandocMonad operations, or update internal
+state. Here's an example using the State monad to add unique
+identifiers to each code block:
+
+```haskell
+addCodeIdentifiers :: Pandoc -> Pandoc
+addCodeIdentifiers doc = evalState (walkM addCodeId doc) 1
+ where addCodeId :: Block -> State Int Block
+ addCodeId (CodeBlock (_,classes,kvs) code) = do
+ curId <- get
+ put (curId + 1)
+ return $ CodeBlock (show curId,classes,kvs) code
+ addCodeId x = return x
+```
+
+`query` is used to collect information from the AST.
+Its argument is a query function that produces a result
+in some monoidal type (e.g. a list). The results are
+concatenated together. Here's an example that returns a
+list of the URLs linked to in a document:
+
+```haskell
+listURLs :: Pandoc -> [Text]
+listURLs = query urls
+ where urls (Link _ _ (src, _)) = [src]
+ urls _ = []
+```
+
+# Creating a front-end
+
+All of the functionality of the command-line program `pandoc`
+has been abstracted out in `convertWithOpts` in
+the module [Text.Pandoc.App]. Creating a GUI front-end for
+pandoc is thus just a matter of populating the `Opts`
+structure and calling this function.
+
+# Notes on using pandoc in web applications
+
+1. Pandoc's parsers can exhibit pathological behavior on some
+ inputs. So it is always a good idea to wrap uses of pandoc
+ in a timeout function (e.g. `System.Timeout.timeout` from `base`)
+ to prevent DoS attacks.
+
+2. If pandoc generates HTML from untrusted user input, it is
+ always a good idea to filter the generated HTML through
+ a sanitizer (such as `xss-sanitize`) to avoid security
+ problems.
+
+3. Using `runPure` rather than `runIO` will ensure that
+ pandoc's functions perform no IO operations (e.g. writing
+ files). If some resources need to be made available, a
+ "fake environment" is provided inside the state available
+ to `runPure` (see `PureState` and its associated functions
+ in [Text.Pandoc.Class]). It is also possible to write
+ a custom instance of `PandocMonad` that, for example,
+ makes wiki resources available as files in the fake environment,
+ while isolating pandoc from the rest of the system.
+
+
+[Text.Pandoc.Definition]: https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Definition.html
+[Text.Pandoc.Walk]: https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Walk.html
+[Text.Pandoc.Class]: https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Class.html
+[Text.Pandoc.Options]: https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Options.html
+[Text.Pandoc.Extensions]: https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Extensions.html
+[Text.Pandoc.Builder]: https://hackage.haskell.org/package/pandoc-types/docs/Text-Pandoc-Builder.html
+[Text.Pandoc.Templates]: https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Templates.html
+[Text.Pandoc.Logging]: https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Logging.html
+[Text.Pandoc.App]: https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-App.html
+[Text.Pandoc.Error]: https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Error.html
+[Text.Pandoc.Writers.Shared]: https://hackage.haskell.org/package/pandoc/docs/Text-Pandoc-Writers-Shared.html
diff --git a/documents/markdown/pandoc-md/doc_xml.md b/documents/markdown/pandoc-md/doc_xml.md
new file mode 100644
index 0000000..df90b7e
--- /dev/null
+++ b/documents/markdown/pandoc-md/doc_xml.md
@@ -0,0 +1,376 @@
+---
+title: XML
+author: massifrg@gmail.com
+---
+
+# Pandoc XML format
+
+This document describes Pandoc's `xml` format, a 1:1 equivalent
+of the `native` and `json` formats.
+
+Here's the xml version of the beginning of this document,
+to give you a glimpse of the format:
+
+```xml
+<?xml version='1.0' ?>
+<Pandoc api-version="1,23,1">
+<meta>
+ <entry key="author">
+ <MetaInlines>massifrg@gmail.com</MetaInlines>
+ </entry>
+ <entry key="title">
+ <MetaInlines>XML</MetaInlines>
+ </entry>
+</meta>
+<blocks>
+ <Header id="pandoc-xml-format" level="1">Pandoc XML format</Header>
+ <Para>This document describes Pandoc’s <Code>xml</Code> format, a 1:1 equivalent<SoftBreak />of the <Code>native</Code> and <Code>json</Code> formats.</Para>
+ ...
+</blocks>
+</Pandoc>
+```
+
+## The tags
+
+If you know [Pandoc types](https://hackage.haskell.org/package/pandoc-types-1.23.1/docs/Text-Pandoc-Definition.html), the XML conversion is fairly straightforward.
+
+These are the main rules:
+
+- `Str` inlines are usually converted to plain, UTF-8 text (see below for exceptions)
+
+- `Space` inlines are usually converted to " " chars (see below for exceptions)
+
+- every `Block` and `Inline` becomes an element with the same name and the same capitalization:
+ a `Para` Block becomes a `<Para>` element, an `Emph` Inline becomes an `<Emph>` element,
+ and so on;
+
+- the root element is `<Pandoc>` and it has a `api-version` attribute, whose value
+ is a string of comma-separated integer numbers; it matches the `pandoc-api-version`
+ field of the `json` format;
+
+- the root `<Pandoc>` element has only two children: `<meta>` and `<blocks>`
+ (lowercase, as in `json` format);
+
+- blocks and inlines with an `Attr` are HTM-like, and they have:
+
+ - the `id` attribute for the identifier
+
+ - the `class` attribute, a string of space-separated classes
+
+ - the other attributes of `Attr`, without any prefix (so no `data-` prefix, instead of HTML)
+
+- attributes are in lower (kebab) case:
+
+ - `level` in Header
+
+ - `start`, `number-style`, `number-delim` in OrderedList;
+ style and delimiter values are capitalized exactly as in `Text.Pandoc.Definition`;
+
+ - `format` in `RawBlock` and RawInline
+
+ - `quote-type` in Quoted (values are `SingleQuote` and `DoubleQuote`)
+
+ - `math-type` in Math (values are `InlineMath` and `DisplayMath`)
+
+ - `title` and `src` in Image target
+
+ - `title` and `href` in Link target
+
+ - `alignment` and `col-width` in ColSpec (about `col-width` values, see below);
+ (alignment values are capitalized as in `Text.Pandoc.Definition`)
+
+ - `alignment`, `row-span` and `col-span` in Cell
+
+ - `row-head-columns` in TableBody
+
+ - `id`, `mode`, `note-num` and `hash` for Citation (about Cite elements, see below);
+ (`mode` values are capitalized as in `Text.Pandoc.Definition`)
+
+The classes of items with an `Attr` are put in a `class` attribute,
+so that you can style the XML with CSS.
+
+## Str and Space elements
+
+`Str` and `Space` usually result in text and normal " " spaces, but there are exceptions:
+
+- `Str ""`, an empty string, is not suppressed; instead it is converted into a `<Str />` element;
+
+- `Str "foo bar"`, a string containing a space, is converted as `<Str content="foo bar" />`;
+
+- consecutive `Str` inlines, as in `[ ..., Str "foo", Str "bar", ... ]`,
+ are encoded as `foo<Str content="bar" />` to keep their individuality;
+
+- consecutive `Space` inlines, as in `[ ..., Space, Space, ... ]`,
+ are encoded as `<Space count="2" />`
+
+- `Space` inlines at the start or at the end of their container element
+ are always encoded with a `<Space />` element, instead of just a " "
+
+These encodings are necessary to ensure 1:1 equivalence of the `xml` format with the AST,
+or the `native` and `json` formats.
+
+Since the ones above are corner cases, usually you should not see those `<Str />` and `<Space />`
+elements in your documents.
+
+## Added tags
+
+Some other elements have been introduced to better structure the resulting XML.
+
+Since they are not Pandoc Blocks or Inlines, or they have no constructor or type
+in Pandoc's haskell code, they are kept lowercased.
+
+### BulletList and OrderedList items
+
+Items of those lists are embedded in `<item>` elements.
+
+These snippets are from the `xml` version of `test/testsuite.native`:
+
+```xml
+<BulletList>
+ <item>
+ <Plain>asterisk 1</Plain>
+ </item>
+ <item>
+ <Plain>asterisk 2</Plain>
+ </item>
+ <item>
+ <Plain>asterisk 3</Plain>
+ </item>
+</BulletList>
+...
+<OrderedList start="1" number-style="Decimal" number-delim="Period">
+ <item>
+ <Plain>First</Plain>
+ </item>
+ <item>
+ <Plain>Second</Plain>
+ </item>
+ <item>
+ <Plain>Third</Plain>
+ </item>
+</OrderedList>
+```
+
+### DefinitionList items
+
+Definition lists have `<item>` elements.
+
+Each `<item>` term has only one `<term>` child element,
+and one or more `<def>` children elements.
+
+This snippet is from the `xml` version of `test/testsuite.native`:
+
+```xml
+<DefinitionList>
+ <item>
+ <term>apple</term>
+ <def>
+ <Plain>red fruit</Plain>
+ </def>
+ </item>
+ <item>
+ <term>orange</term>
+ <def>
+ <Plain>orange fruit</Plain>
+ </def>
+ </item>
+ <item>
+ <term>banana</term>
+ <def>
+ <Plain>yellow fruit</Plain>
+ </def>
+ </item>
+</DefinitionList>
+```
+
+### Figure and Table captions
+
+Figures and tables have a `<Caption>` child element,
+which in turn may optionally have a `<ShortCaption>` child element.
+
+This snippet is from the `xml` version of `test/testsuite.native`:
+
+```xml
+<Figure>
+ <Caption>
+ <Plain>lalune</Plain>
+ </Caption>
+ <Plain><Image src="lalune.jpg" title="Voyage dans la Lune">lalune</Image></Plain>
+</Figure>
+```
+
+### Tables
+
+A `<Table>` element has:
+
+- a `<Caption>` child element;
+
+- a `<colspecs>` child element, whose children are empty
+ `<ColSpec alignment="..." col-width="..." />` elements;
+
+- a `<TableHead>` child element;
+
+- one or more `<TableBody>` children elements, that in turn
+ have two children: `<header>` and `<body>`, whose children
+ are `<Row>` elements;
+
+- a `<TableFoot>` child element.
+
+This specification is debatable; I have these doubts:
+
+- is it necessary to enclose the `<ColSpec>` elements in a `<colspecs>` element?
+
+- to discriminate between header and data cells in table bodies,
+ there are the `row-head-columns` attribute, and the `<header>` and `<body>` children
+ of the `<TableBody>` element, but there's only one type of cell:
+ every cell is a `<Cell>` element
+
+- the specs are a tradeoff between consistency with pandoc types and CSS compatibility;
+ this way bodies' header rows are easily stylable with CSS, while header columns are not
+
+The `ColWidthDefault` value becomes a "0" value for the attribute `col-width`;
+this way it's type-consistent with non-zero values, but I'm still doubtful whether to
+leave its value as a "ColWidthDefault" string.
+
+Here's an example from the `xml` version of `test/tables/planets.native`:
+
+```xml
+<Table>
+ <Caption>
+ <Para>Data about the planets of our solar system.</Para>
+ </Caption>
+ <colspecs>
+ <ColSpec col-width="0" alignment="AlignCenter" />
+ <ColSpec col-width="0" alignment="AlignCenter" />
+ <ColSpec col-width="0" alignment="AlignDefault" />
+ <ColSpec col-width="0" alignment="AlignRight" />
+ <ColSpec col-width="0" alignment="AlignRight" />
+ <ColSpec col-width="0" alignment="AlignRight" />
+ <ColSpec col-width="0" alignment="AlignRight" />
+ <ColSpec col-width="0" alignment="AlignRight" />
+ <ColSpec col-width="0" alignment="AlignRight" />
+ <ColSpec col-width="0" alignment="AlignRight" />
+ <ColSpec col-width="0" alignment="AlignRight" />
+ <ColSpec col-width="0" alignment="AlignDefault" />
+ </colspecs>
+ <TableHead>
+ <Row>
+ <Cell col-span="2" row-span="1" alignment="AlignDefault" />
+ <Cell col-span="1" row-span="1" alignment="AlignDefault">
+ <Plain>Name</Plain>
+ </Cell>
+ <Cell col-span="1" row-span="1" alignment="AlignDefault">
+ <Plain>Mass (10^24kg)</Plain>
+ </Cell>
+ ...
+ </Row>
+ </TableHead>
+ <TableBody row-head-columns="3">
+ <header />
+ <body>
+ <Row>
+ <Cell col-span="2" row-span="4" alignment="AlignDefault">
+ <Plain>Terrestrial planets</Plain>
+ </Cell>
+ <Cell alignment="AlignDefault">
+ <Plain>Mercury</Plain>
+ </Cell>
+ <Cell alignment="AlignDefault">
+ <Plain>0.330</Plain>
+ </Cell>
+ <Cell alignment="AlignDefault">
+ <Plain>4,879</Plain>
+ </Cell>
+ <Cell alignment="AlignDefault">
+ <Plain>5427</Plain>
+ </Cell>
+ <Cell alignment="AlignDefault">
+ <Plain>3.7</Plain>
+ </Cell>
+ <Cell alignment="AlignDefault">
+ <Plain>4222.6</Plain>
+ </Cell>
+ <Cell alignment="AlignDefault">
+ <Plain>57.9</Plain>
+ </Cell>
+ <Cell alignment="AlignDefault">
+ <Plain>167</Plain>
+ </Cell>
+ <Cell alignment="AlignDefault">
+ <Plain>0</Plain>
+ </Cell>
+ <Cell alignment="AlignDefault">
+ <Plain>Closest to the Sun</Plain>
+ </Cell>
+ </Row>
+ ...
+ </body>
+ </TableBody>
+ <TableFoot />
+</Table>
+```
+
+### Metadata and MetaMap entries
+
+Metadata entries are meta values (`MetaBool`, `MetaString`, `MetaInlines`, `MetaBlocks`,
+`MetaList` and `MetaMap` elements) inside `<entry>` elements.
+
+The `<meta>` and the `<MetaMap>` elements have the same children elements (`<entry>`),
+which have a `key` attribute.
+
+`<MetaInlines>`, `<MetaBlocks>`, `<MetaList>` and `<MetaMap>` elements
+all have children elements.
+
+`<MetaString>` elements have only text.
+
+`<MetaBool>` elements are empty, they can be either `<MetaBool value="true" />`
+or `<MetaBool value="false" />`.
+
+This snippet is from the `xml` version of `test/testsuite.native`:
+
+```xml
+<meta>
+ <entry key="author">
+ <MetaList>
+ <MetaInlines>John MacFarlane</MetaInlines>
+ <MetaInlines>Anonymous</MetaInlines>
+ </MetaList>
+ </entry>
+ <entry key="date">
+ <MetaInlines>July 17, 2006</MetaInlines>
+ </entry>
+ <entry key="title">
+ <MetaInlines>Pandoc Test Suite</MetaInlines>
+ </entry>
+</meta>
+```
+
+### Cite elements
+
+`Cite` inlines are modeled with `<Cite>` elements, whose first child
+is a `<citations>` element, that have only `<Citation>` children elements.
+
+`<Citation>` elements are empty, unless they have a prefix and/or a suffix.
+
+Here's an example from the `xml` version of `test/markdown-citations.native`:
+
+```xml
+<Para><Cite><citations>
+ <Citation note-num="3" mode="AuthorInText" id="item1" hash="0" />
+</citations>@item1</Cite> says blah.</Para>
+<Para><Cite><citations>
+ <Citation note-num="4" mode="AuthorInText" id="item1" hash="0">
+ <suffix>p. 30</suffix>
+ </Citation>
+</citations>@item1 [p. 30]</Cite> says blah.</Para>
+<Para>A citation group <Cite><citations>
+ <Citation note-num="8" mode="NormalCitation" id="item1" hash="0">
+ <prefix>see</prefix>
+ <suffix> chap. 3</suffix>
+ </Citation>
+ <Citation note-num="8" mode="NormalCitation" id="пункт3" hash="0">
+ <prefix>also</prefix>
+ <suffix> p. 34-35</suffix>
+ </Citation>
+</citations>[see @item1 chap. 3; also @пункт3 p. 34-35]</Cite>.</Para>
+```
diff --git a/documents/markdown/pandoc-md/docbook-bibliography.md b/documents/markdown/pandoc-md/docbook-bibliography.md
new file mode 100644
index 0000000..6e42732
--- /dev/null
+++ b/documents/markdown/pandoc-md/docbook-bibliography.md
@@ -0,0 +1,45 @@
+```
+% pandoc -f docbook -t native --quiet
+<bibliodiv>
+<title>Document References</title>
+<bibliomixed>
+<bibliomisc><anchor xml:id="refTheFirst" xreflabel="[1]"/>[1] First reference</bibliomisc>
+</bibliomixed>
+<bibliomixed>
+<bibliomisc><anchor xml:id="refTheSecond" xreflabel="[2]"/>[2] Second reference</bibliomisc>
+</bibliomixed>
+<bibliomixed>
+<bibliomisc><anchor xml:id="refTheThird" xreflabel="[3]"/>[3] Third reference</bibliomisc>
+</bibliomixed>
+</bibliodiv>
+^D
+[ Header
+ 1
+ ( "" , [] , [] )
+ [ Str "Document" , Space , Str "References" ]
+, Para
+ [ Span ( "refTheFirst" , [] , [] ) []
+ , Str "[1]"
+ , Space
+ , Str "First"
+ , Space
+ , Str "reference"
+ ]
+, Para
+ [ Span ( "refTheSecond" , [] , [] ) []
+ , Str "[2]"
+ , Space
+ , Str "Second"
+ , Space
+ , Str "reference"
+ ]
+, Para
+ [ Span ( "refTheThird" , [] , [] ) []
+ , Str "[3]"
+ , Space
+ , Str "Third"
+ , Space
+ , Str "reference"
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/dokuwiki-quote.md b/documents/markdown/pandoc-md/dokuwiki-quote.md
new file mode 100644
index 0000000..2ae4aa4
--- /dev/null
+++ b/documents/markdown/pandoc-md/dokuwiki-quote.md
@@ -0,0 +1,16 @@
+```
+% pandoc -f dokuwiki -t native
+> <code>some
+code
+</code>
+>> ok
+> then
+> more
+^D
+[ BlockQuote
+ [ CodeBlock ( "" , [] , [] ) "some\ncode\n"
+ , BlockQuote [ Plain [ Str "ok" ] ]
+ , Plain [ Str "then" , LineBreak , Str "more" ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/dots.md b/documents/markdown/pandoc-md/dots.md
new file mode 100644
index 0000000..cd9a978
--- /dev/null
+++ b/documents/markdown/pandoc-md/dots.md
@@ -0,0 +1,13 @@
+```
+% pandoc -f latex -t native
+\dots
+
+\ldots
+
+\vdots
+^D
+[ Para [ Str "\8230" ]
+, Para [ Str "\8230" ]
+, Para [ Str "\8942" ]
+]
+```
diff --git a/documents/markdown/pandoc-md/duplicate_attributes.md b/documents/markdown/pandoc-md/duplicate_attributes.md
new file mode 100644
index 0000000..4eec0be
--- /dev/null
+++ b/documents/markdown/pandoc-md/duplicate_attributes.md
@@ -0,0 +1,7 @@
+```
+% pandoc
+[span]{.foobar style="color:blue" class="zip" style="color:red"}
+^D
+2> [WARNING] Ignoring duplicate attribute style="color:red".
+<p><span class="foobar zip" style="color:blue">span</span></p>
+```
diff --git a/documents/markdown/pandoc-md/emoji.md b/documents/markdown/pandoc-md/emoji.md
new file mode 100644
index 0000000..b5c573b
--- /dev/null
+++ b/documents/markdown/pandoc-md/emoji.md
@@ -0,0 +1,27 @@
+```
+% pandoc -t markdown+emoji -f markdown+emoji
+:smile:
+^D
+:smile:
+```
+
+```
+% pandoc -t markdown-emoji -f markdown+emoji
+:smile:
+^D
+😄
+```
+
+```
+% pandoc -t gfm -f markdown+emoji
+:smile:
+^D
+:smile:
+```
+
+```
+% pandoc -t gfm-emoji -f markdown+emoji
+:smile:
+^D
+😄
+```
diff --git a/documents/markdown/pandoc-md/empty_paragraphs.md b/documents/markdown/pandoc-md/empty_paragraphs.md
new file mode 100644
index 0000000..6efbab9
--- /dev/null
+++ b/documents/markdown/pandoc-md/empty_paragraphs.md
@@ -0,0 +1,91 @@
+```
+% pandoc -f native -t docx -o - | pandoc -f docx -t native
+[Para [Str "hi"], Para [], Para [], Para [Str "lo"]]
+^D
+[ Para [ Str "hi" ] , Para [ Str "lo" ] ]
+```
+
+```
+% pandoc -f native -t docx+empty_paragraphs -o - | pandoc -f docx -t native
+[Para [Str "hi"], Para [], Para [], Para [Str "lo"]]
+^D
+[ Para [ Str "hi" ] , Para [ Str "lo" ] ]
+```
+
+```
+% pandoc -f native -t docx -o - | pandoc -f docx+empty_paragraphs -t native
+[Para [Str "hi"], Para [], Para [], Para [Str "lo"]]
+^D
+[ Para [ Str "hi" ] , Para [ Str "lo" ] ]
+```
+
+```
+% pandoc -f native -t docx+empty_paragraphs -o - | pandoc -f docx+empty_paragraphs -t native
+[Para [Str "hi"], Para [], Para [], Para [Str "lo"]]
+^D
+[ Para [ Str "hi" ]
+, Para []
+, Para []
+, Para [ Str "lo" ]
+]
+```
+
+```
+% pandoc -f native -t html5
+[Para [Str "hi"], Para [], Para [], Para [Str "lo"]]
+^D
+<p>hi</p>
+<p>lo</p>
+```
+
+```
+% pandoc -f native -t html5+empty_paragraphs
+[Para [Str "hi"], Para [], Para [], Para [Str "lo"]]
+^D
+<p>hi</p>
+<p></p>
+<p></p>
+<p>lo</p>
+```
+
+```
+% pandoc -f html+empty_paragraphs -t native
+<p>hi</p>
+<p></p>
+<p></p>
+<p>lo</p>
+^D
+[ Para [ Str "hi" ]
+, Para []
+, Para []
+, Para [ Str "lo" ]
+]
+```
+
+```
+% pandoc -f html -t native
+<p>hi</p>
+<p></p>
+<p></p>
+<p>lo</p>
+^D
+[ Para [ Str "hi" ] , Para [ Str "lo" ] ]
+```
+
+```
+% pandoc -f native -t opendocument+empty_paragraphs
+[Para [Str "hi"], Para [], Para [], Para [Str "lo"]]
+^D
+<text:p text:style-name="Text_20_body">hi</text:p>
+<text:p text:style-name="Text_20_body"></text:p>
+<text:p text:style-name="Text_20_body"></text:p>
+<text:p text:style-name="Text_20_body">lo</text:p>
+```
+
+```
+% pandoc -f native -t opendocument
+[Para [Str "hi"], Para [], Para [], Para [Str "lo"]]
+^D
+<text:p text:style-name="Text_20_body">hi</text:p>
+<text:p text:style-name="Text_20_body">lo</text:p>
+```
diff --git a/documents/markdown/pandoc-md/figures-context.md b/documents/markdown/pandoc-md/figures-context.md
new file mode 100644
index 0000000..1f93d63
--- /dev/null
+++ b/documents/markdown/pandoc-md/figures-context.md
@@ -0,0 +1,48 @@
+# Figure with one image, caption and label
+
+```
+% pandoc -t context -f html
+<figure>
+ <img src="mandrill.jpg" />
+ <figcaption><q>The Mandrill</q>, a photo used in
+ image processing tests.</figcaption>
+</figure>
+^D
+\startplacefigure[title={\quotation{The Mandrill}, a photo used in image
+processing tests.}]
+{\externalfigure[mandrill.jpg]}
+\stopplacefigure
+```
+
+# Nested figures
+
+```
+% pandoc -t context -f html
+<figure id="test-images">
+ <figure id="mandrill">
+ <img src="../testing/mandrill.jpg">
+ <figcaption><q>The Mandrill</q> is a commonly used test image.</figcaption>
+ </figure>
+ <figure id="peppers">
+ <img src="../testing/peppers.webp" >
+ <figcaption>Another test image. This one is called <q>peppers</q>.</figcaption>
+ </figure>
+ <figcaption>Signal processing test images.</figcaption>
+</figure>
+^D
+\startplacefigure[reference=test-images,title={Signal processing test
+images.}]
+\startfloatcombination
+\startplacefigure[reference=mandrill,title={\quotation{The Mandrill} is
+a commonly used test image.}]
+{\externalfigure[../testing/mandrill.jpg]}
+\stopplacefigure
+
+\startplacefigure[reference=peppers,title={Another test image. This one
+is called \quotation{peppers}.}]
+{\externalfigure[../testing/peppers.webp]}
+\stopplacefigure
+
+\stopfloatcombination
+\stopplacefigure
+```
diff --git a/documents/markdown/pandoc-md/figures-fb2.md b/documents/markdown/pandoc-md/figures-fb2.md
new file mode 100644
index 0000000..63aa86d
--- /dev/null
+++ b/documents/markdown/pandoc-md/figures-fb2.md
@@ -0,0 +1,8 @@
+```
+% pandoc -f native -t fb2
+[Figure ("fig-id",[],[]) (Caption Nothing []) [Para [Str "content"]]]
+
+^D
+<?xml version="1.0" encoding="UTF-8"?>
+<FictionBook xmlns="http://www.gribuser.ru/xml/fictionbook/2.0" xmlns:l="http://www.w3.org/1999/xlink"><description><title-info><genre>unrecognised</genre></title-info><document-info><program-used>pandoc</program-used></document-info></description><body><title><p /></title><section><p>content</p></section></body></FictionBook>
+```
diff --git a/documents/markdown/pandoc-md/figures-haddock.md b/documents/markdown/pandoc-md/figures-haddock.md
new file mode 100644
index 0000000..9a63861
--- /dev/null
+++ b/documents/markdown/pandoc-md/figures-haddock.md
@@ -0,0 +1,7 @@
+```
+% pandoc -f native -t haddock
+[Figure ("fig-id",[],[]) (Caption Nothing []) [Para [Str "content"]]]
+
+^D
+content
+```
diff --git a/documents/markdown/pandoc-md/figures-html.md b/documents/markdown/pandoc-md/figures-html.md
new file mode 100644
index 0000000..3718246
--- /dev/null
+++ b/documents/markdown/pandoc-md/figures-html.md
@@ -0,0 +1,92 @@
+# Writer
+
+HTML5 figure with caption and content.
+
+```
+% pandoc -f native -t html5
+[Figure ("fig-id",[],[]) (Caption Nothing [Plain [Str "caption"]]) [Para [Str "content"]]]
+
+^D
+<figure id="fig-id">
+<p>content</p>
+<figcaption>caption</figcaption>
+</figure>
+```
+
+HTML5 figure with NO caption and content.
+
+```
+% pandoc -f native -t html5
+[Figure ("fig-id",[],[]) (Caption Nothing []) [Para [Str "content"]]]
+
+^D
+<figure id="fig-id">
+<p>content</p>
+</figure>
+```
+
+HTML4 figure with caption and content.
+
+```
+% pandoc -f native -t html4
+[Figure ("fig-id",[],[]) (Caption Nothing [Plain [Str "caption"]]) [Para [Str "content"]]]
+
+^D
+<div class="float" id="fig-id">
+<p>content</p>
+<div class="figcaption">caption</div>
+</div>
+```
+
+HTML4 figure with NO caption and content.
+
+```
+% pandoc -f native -t html4
+[Figure ("fig-id",[],[]) (Caption Nothing []) [Para [Str "content"]]]
+
+^D
+<div class="float" id="fig-id">
+<p>content</p>
+</div>
+```
+
+# Reader
+
+Figure with caption and multiple elements.
+
+```
+% pandoc -f html -t native
+<figure class="important">
+ <img src="../media/rId25.jpg" />
+ <ul> <li> ITEM </li> </ul>
+ <figcaption> CAP2 </figcaption>
+</figure>
+^D
+[ Figure
+ ( "" , [ "important" ] , [] )
+ (Caption Nothing [ Plain [ Str "CAP2" ] ])
+ [ Plain
+ [ Image ( "" , [] , [] ) [] ( "../media/rId25.jpg" , "" ) ]
+ , BulletList [ [ Plain [ Str "ITEM" ] ] ]
+ ]
+]
+```
+
+Figure without caption.
+
+```
+% pandoc -f html -t native
+<figure class="important">
+ <img src="../media/rId25.jpg" />
+ <ul> <li> ITEM </li> </ul>
+</figure>
+^D
+[ Figure
+ ( "" , [ "important" ] , [] )
+ (Caption Nothing [])
+ [ Plain
+ [ Image ( "" , [] , [] ) [] ( "../media/rId25.jpg" , "" ) ]
+ , BulletList [ [ Plain [ Str "ITEM" ] ] ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/figures-jats.md b/documents/markdown/pandoc-md/figures-jats.md
new file mode 100644
index 0000000..bc13bcb
--- /dev/null
+++ b/documents/markdown/pandoc-md/figures-jats.md
@@ -0,0 +1,31 @@
+Figure float with caption at the figure level.
+
+```
+% pandoc -f native -t jats
+[Figure ("fig-id",[],[]) (Caption Nothing [Para [Str "Caption"]]) [Para [Str "Text"],
+Para [Image ("fig-id-2",[],[]) [] ("foo.png", "fig:")]]]
+
+^D
+<fig id="fig-id">
+ <caption><p>Caption</p></caption>
+ <p>Text</p>
+ <graphic id="fig-id-2" mimetype="image" mime-subtype="png" xlink:href="foo.png" xlink:title="fig:" />
+</fig>
+```
+
+Figure float with caption and alt text.
+
+```
+% pandoc -f native -t jats
+[Figure ("fig-id",[],[]) (Caption Nothing [Para [Str "Caption"]]) [Para [Str "Text"],
+Para [Image ("fig-id-2",[],[]) [Str "alt"] ("foo.png", "fig:")]]]
+
+^D
+<fig id="fig-id">
+ <caption><p>Caption</p></caption>
+ <p>Text</p>
+ <graphic id="fig-id-2" mimetype="image" mime-subtype="png" xlink:href="foo.png" xlink:title="fig:">
+ <alt-text>alt</alt-text>
+ </graphic>
+</fig>
+```
diff --git a/documents/markdown/pandoc-md/figures-jira.md b/documents/markdown/pandoc-md/figures-jira.md
new file mode 100644
index 0000000..7517b7e
--- /dev/null
+++ b/documents/markdown/pandoc-md/figures-jira.md
@@ -0,0 +1,9 @@
+A figure with title
+```
+% pandoc -f native -t jira
+[Figure ("fig-id",[],[("title","This is the title")]) (Caption Nothing []) []]
+^D
+{panel:title=This is the title}
+{anchor:fig-id}
+{panel}
+```
diff --git a/documents/markdown/pandoc-md/figures-latex.md b/documents/markdown/pandoc-md/figures-latex.md
new file mode 100644
index 0000000..cebce97
--- /dev/null
+++ b/documents/markdown/pandoc-md/figures-latex.md
@@ -0,0 +1,83 @@
+# Figure with one image, caption and label
+
+```
+% pandoc -f latex -t native
+\begin{document}
+ \begin{figure}
+ \includegraphics{../../media/rId25.jpg}
+ \caption{CAP}
+ \label{LAB}
+ \end{figure}
+\end{document}
+^D
+[ Figure
+ ( "LAB" , [] , [] )
+ (Caption Nothing [ Plain [ Str "CAP" ] ])
+ [ Plain
+ [ Image ( "" , [] , [] ) [] ( "../../media/rId25.jpg" , "" )
+ ]
+ ]
+]
+```
+
+# Nested figures
+
+```
+% pandoc -f latex -t native
+\begin{figure}
+ \begin{subfigure}[b]{0.5\textwidth}
+ \begin{subfigure}[b]{0.5\textwidth}
+ \centering
+ \includegraphics{test/media/rId25.jpg}
+ \caption{CAP1.1}
+ \end{subfigure}
+ \begin{subfigure}[b]{0.5\textwidth}
+ \centering
+ \includegraphics{test/media/rId25.jpg}
+ \caption{CAP1.2}
+ \end{subfigure}
+ \caption{CAP1}
+ \label{fig:inner1}
+ \end{subfigure}
+ \begin{subfigure}[b]{0.5\textwidth}
+ \includegraphics{test/media/rId25.jpg}
+ \caption{CAP2}
+ \label{fig:inner2}
+ \end{subfigure}
+ \caption{CAP}
+ \label{fig:outer}
+\end{figure}
+^D
+[ Figure
+ ( "fig:outer" , [] , [] )
+ (Caption Nothing [ Plain [ Str "CAP" ] ])
+ [ Figure
+ ( "fig:inner1" , [] , [] )
+ (Caption Nothing [ Plain [ Str "CAP1" ] ])
+ [ Figure
+ ( "" , [] , [] )
+ (Caption Nothing [ Plain [ Str "CAP1.1" ] ])
+ [ Plain
+ [ Image
+ ( "" , [] , [] ) [] ( "test/media/rId25.jpg" , "" )
+ ]
+ ]
+ , Figure
+ ( "" , [] , [] )
+ (Caption Nothing [ Plain [ Str "CAP1.2" ] ])
+ [ Plain
+ [ Image
+ ( "" , [] , [] ) [] ( "test/media/rId25.jpg" , "" )
+ ]
+ ]
+ ]
+ , Figure
+ ( "fig:inner2" , [] , [] )
+ (Caption Nothing [ Plain [ Str "CAP2" ] ])
+ [ Plain
+ [ Image ( "" , [] , [] ) [] ( "test/media/rId25.jpg" , "" )
+ ]
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/figures-markdown.md b/documents/markdown/pandoc-md/figures-markdown.md
new file mode 100644
index 0000000..4d3ea41
--- /dev/null
+++ b/documents/markdown/pandoc-md/figures-markdown.md
@@ -0,0 +1,12 @@
+Figure float with caption at the figure level.
+
+```
+% pandoc -f native -t markdown
+[Figure ("fig-id",[],[]) (Caption Nothing [Para [Str "Caption"]]) [Para [Image ("",[],[]) [] ("foo.png", "fig:")]]]
+
+^D
+<figure id="fig-id">
+<p><img src="foo.png" title="fig:" /></p>
+<figcaption><p>Caption</p></figcaption>
+</figure>
+```
diff --git a/documents/markdown/pandoc-md/figures-mediawiki.md b/documents/markdown/pandoc-md/figures-mediawiki.md
new file mode 100644
index 0000000..8b38269
--- /dev/null
+++ b/documents/markdown/pandoc-md/figures-mediawiki.md
@@ -0,0 +1,11 @@
+Figure float with caption at the figure level.
+
+```
+% pandoc -f native -t mediawiki
+[Figure ("fig-id",[],[]) (Caption Nothing [Para [Str "Caption"]]) [Para [Image ("",[],[]) [] ("foo.png", "fig:")]]]
+
+^D
+<div id="fig-id" class="figure">
+[[File:foo.png|thumb|none]]
+</div>
+```
diff --git a/documents/markdown/pandoc-md/figures-org.md b/documents/markdown/pandoc-md/figures-org.md
new file mode 100644
index 0000000..bfa5c6d
--- /dev/null
+++ b/documents/markdown/pandoc-md/figures-org.md
@@ -0,0 +1,16 @@
+```
+% pandoc -f native -t org
+[Figure ("fig-id",[],[]) (Caption Nothing []) [Para [Str "content"]]]
+
+^D
+<<fig-id>>
+content
+```
+
+```
+% pandoc -f native -t org
+[Figure ("",[],[]) (Caption Nothing []) [Para [Str "content"]]]
+
+^D
+content
+```
diff --git a/documents/markdown/pandoc-md/figures-rst.md b/documents/markdown/pandoc-md/figures-rst.md
new file mode 100644
index 0000000..a5f22da
--- /dev/null
+++ b/documents/markdown/pandoc-md/figures-rst.md
@@ -0,0 +1,13 @@
+Figure float with caption at the figure level.
+
+```
+% pandoc -f native -t rst
+[Figure ("fig-id",[],[]) (Caption Nothing [Para [Str "Caption"]]) [Para [Image ("",[],[]) [] ("foo.png", "fig:")]]]
+
+^D
+.. figure:: foo.png
+ name: fig-id
+ :alt: fig:
+
+ Caption
+```
diff --git a/documents/markdown/pandoc-md/figures-texinfo.md b/documents/markdown/pandoc-md/figures-texinfo.md
new file mode 100644
index 0000000..f50c6b5
--- /dev/null
+++ b/documents/markdown/pandoc-md/figures-texinfo.md
@@ -0,0 +1,115 @@
+Figure float with caption at the figure level.
+
+```
+% pandoc -f native -t texinfo
+[Figure ("fig-id",[],[]) (Caption Nothing [Para [Str "Caption"]]) [Para [Image ("",[],[]) [] ("foo.png", "fig:")]]]
+
+^D
+@node Top
+@top Top
+
+@float Figure
+@image{foo,,,,png}
+@caption{Caption}
+@end float
+```
+
+Float that has no caption and doesn't contain a `SimpleFigure`
+
+```
+% pandoc -f native -t texinfo
+[Figure ("fig-id",[],[]) (Caption Nothing []) [Para [Image ("",[],[]) [] ("foo.png", "")]]]
+
+^D
+@node Top
+@top Top
+
+@float
+@image{foo,,,,png}
+@end float
+```
+
+Table float with caption at the figure level.
+
+```
+% pandoc -f native -t texinfo
+[Figure ("fig-id",[],[]) (Caption Nothing [Para [Str "Caption"]])
+[Table ("",[],[]) (Caption Nothing
+ [])
+ [(AlignDefault,ColWidthDefault)
+ ,(AlignDefault,ColWidthDefault)
+ ,(AlignDefault,ColWidthDefault)]
+ (TableHead ("",[],[])
+ [Row ("",[],[])
+ [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "Fruit"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "Price"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "Quantity"]]]])
+ [(TableBody ("",[],[]) (RowHeadColumns 0)
+ []
+ [Row ("",[],[])
+ [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "Apple"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "25",Space,Str "cents"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "33"]]]
+ ,Row ("",[],[])
+ [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "\"Navel\"",Space,Str "Orange"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "35",Space,Str "cents"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "22"]]]
+ ,Row ("",[],[])
+ [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ []
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ []
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "45"]]]])]
+ (TableFoot ("",[],[])
+ [])]]
+
+^D
+@node Top
+@top Top
+
+@float Table
+@multitable {"Navel" Orange} {35 cents} {Quantity}
+@headitem
+Fruit
+ @tab Price
+ @tab Quantity
+@item
+Apple
+ @tab 25 cents
+ @tab 33
+@item
+"Navel" Orange
+ @tab 35 cents
+ @tab 22
+@item
+45
+@end multitable
+@caption{Caption}
+@end float
+```
+
+Float the isn't a table nor a figure.
+
+```
+% pandoc -f native -t texinfo
+[Figure ("fig-id",[],[]) (Caption Nothing [Para[ Str "Caption"]]) [Para [Str "Content"]]]
+
+^D
+@node Top
+@top Top
+
+@float
+Content
+@caption{Caption}
+@end float
+```
diff --git a/documents/markdown/pandoc-md/figures-textile.md b/documents/markdown/pandoc-md/figures-textile.md
new file mode 100644
index 0000000..27c60cb
--- /dev/null
+++ b/documents/markdown/pandoc-md/figures-textile.md
@@ -0,0 +1,31 @@
+```
+% pandoc -f native -t textile
+[Figure ("fig-id",[],[]) (Caption Nothing [Para [Str "Caption"]]) [Para [Image ("",[],[]) [] ("foo.png", "")]]]
+
+^D
+<figure id="fig-id">
+
+<figcaption>
+
+Caption
+
+</figcaption>
+
+!foo.png!
+
+
+</figure>
+```
+
+```
+% pandoc -f native -t textile
+[Figure ("fig-id",[],[]) (Caption Nothing []) [Para [Image ("",[],[]) [] ("foo.png", "")]]]
+
+^D
+<figure id="fig-id">
+
+!foo.png!
+
+
+</figure>
+```
diff --git a/documents/markdown/pandoc-md/figures-xwiki.md b/documents/markdown/pandoc-md/figures-xwiki.md
new file mode 100644
index 0000000..0b4e84d
--- /dev/null
+++ b/documents/markdown/pandoc-md/figures-xwiki.md
@@ -0,0 +1,10 @@
+```
+% pandoc -f native -t xwiki
+[Figure ("fig-id",[],[]) (Caption Nothing []) [Para [Str "content"]]]
+
+^D
+(((
+{{id name="fig-id" /}}content
+
+)))
+```
diff --git a/documents/markdown/pandoc-md/figures-zimwiki.md b/documents/markdown/pandoc-md/figures-zimwiki.md
new file mode 100644
index 0000000..a2d4bcd
--- /dev/null
+++ b/documents/markdown/pandoc-md/figures-zimwiki.md
@@ -0,0 +1,9 @@
+```
+% pandoc -f native -t zimwiki
+[Figure ("fig-id",[],[]) (Caption Nothing []) [Para [Str "content"]]]
+
+^D
+content
+
+
+```
diff --git a/documents/markdown/pandoc-md/gfm.md b/documents/markdown/pandoc-md/gfm.md
new file mode 100644
index 0000000..12bd090
--- /dev/null
+++ b/documents/markdown/pandoc-md/gfm.md
@@ -0,0 +1,222 @@
+gfm tests:
+
+```
+% pandoc -f gfm -t native
+| Fruit | Price |
+| ----- | ----: |
+| apple | 0.13 |
+| orange|1.12|
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignRight , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Fruit" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Price" ] ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "apple" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "0.13" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "orange" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1.12" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
+
+```
+% pandoc -f gfm -t native
+~~stricken out~~
+^D
+[ Para [ Strikeout [ Str "stricken" , Space , Str "out" ] ]
+]
+```
+
+```
+% pandoc -f gfm -t native
+# Header
+## Header
+# -foo-bar_baz
+^D
+[ Header 1 ( "header" , [] , [] ) [ Str "Header" ]
+, Header 2 ( "header-1" , [] , [] ) [ Str "Header" ]
+, Header
+ 1 ( "-foo-bar_baz" , [] , [] ) [ Str "-foo-bar_baz" ]
+]
+```
+
+```
+% pandoc -f gfm -t native
+My:thumbsup:emoji:heart:
+^D
+[ Para
+ [ Str "My"
+ , Span
+ ( "" , [ "emoji" ] , [ ( "data-emoji" , "thumbsup" ) ] )
+ [ Str "\128077" ]
+ , Str "emoji"
+ , Span
+ ( "" , [ "emoji" ] , [ ( "data-emoji" , "heart" ) ] )
+ [ Str "\10084\65039" ]
+ ]
+]
+```
+
+```
+% pandoc -f gfm -t native
+"hi"
+^D
+[ Para [ Str "\"hi\"" ] ]
+```
+
+```
+% pandoc -f gfm+smart -t native
+"hi"
+^D
+[ Para [ Quoted DoubleQuote [ Str "hi" ] ] ]
+```
+
+```
+% pandoc -t gfm -f native
+[Table ("",[],[]) (Caption Nothing
+ [Plain [Str "The",Space,Str "caption."]])
+ [(AlignDefault,ColWidthDefault)
+ ,(AlignRight,ColWidthDefault)]
+ (TableHead ("",[],[])
+ [Row ("",[],[])
+ [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "Fruit"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "Price"]]]])
+ [(TableBody ("",[],[]) (RowHeadColumns 0)
+ []
+ [Row ("",[],[])
+ [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "apple"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "0.13"]]]
+ ,Row ("",[],[])
+ [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "orange"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Plain [Str "1.12"]]]])]
+ (TableFoot ("",[],[])
+ [])]
+^D
+| Fruit | Price |
+|--------|------:|
+| apple | 0.13 |
+| orange | 1.12 |
+
+The caption.
+```
+
+```
+% pandoc -f gfm-smart -t gfm+smart
+“hi”
+^D
+"hi"
+```
+
+```
+% pandoc -f gfm+smart -t gfm-smart
+"hi"
+^D
+“hi”
+```
+
+```
+% pandoc -f gfm+smart -t gfm+smart
+"hi"
+^D
+"hi"
+```
+
+```
+% pandoc -f gfm+hard_line_breaks -t native
+hi
+hi
+^D
+[ Para [ Str "hi" , LineBreak , Str "hi" ] ]
+```
+
+```
+% pandoc -f gfm -t native
+- [ ] foo
+- [x] bar
+^D
+[ BulletList
+ [ [ Plain [ Str "\9744" , Space , Str "foo" ] ]
+ , [ Plain [ Str "\9746" , Space , Str "bar" ] ]
+ ]
+]
+```
+
+```
+% pandoc -f gfm-task_lists -t native
+- [ ] foo
+- [x] bar
+^D
+[ BulletList
+ [ [ Plain [ Str "[" , Space , Str "]" , Space , Str "foo" ]
+ ]
+ , [ Plain [ Str "[x]" , Space , Str "bar" ] ]
+ ]
+]
+```
+
+```
+% pandoc -f gfm -t gfm
+- [ ] foo
+- [x] bar
+^D
+- [ ] foo
+- [x] bar
+```
diff --git a/documents/markdown/pandoc-md/headers.md b/documents/markdown/pandoc-md/headers.md
new file mode 100644
index 0000000..fa285c8
--- /dev/null
+++ b/documents/markdown/pandoc-md/headers.md
@@ -0,0 +1,45 @@
+Headers with a short title and implicit ref. Last 3 headers are unnumbered.
+
+# unremarkable header 1
+## unremarkable header 2
+### unremarkable header 3
+### unremarkable header 3
+## unremarkable header 2 {.unnumbered}
+### unremarkable header 3 {.unnumbered}
+### unremarkable header 3 {.unnumbered}
+
+---
+
+Headers with various inline elements
+
+# **bold** *italic* [underline]{.underline} ~strikethrough~ {#short11}
+## superscript^2^ subscript~3~ {#short21}
+### [smallcaps]{.smallcaps} `code` $inline math$ $$display math$$ {#short31}
+### [link](example.com)  {#short32}
+
+---
+
+Headers with a long name and explicit short ref
+
+# Long header 1 long header 1 long header 1 long header 1 long header 1 long header 1 long header 1 {#long1}
+## Long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 {#long21}
+### Long header 3 long header 3 long header 3 long header 3 long header 3 long header 3 long header 3 {#long31}
+### Long header 3 long header 3 long header 3 long header 3 long header 3 long header 3 long header 3 {#long32}
+## Long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 {#long22}
+### Long header 3 long header 3 long header 3 long header 3 long header 3 long header 3 long header 3 {#long33}
+### Long header 3 long header 3 long header 3 long header 3 long header 3 long header 3 long header 3 {#long34}
+
+---
+
+Headers with a long name and implicit ref.
+
+Since implicit ref is very lengthy, there is no way to fit it. Therefore title
+is not rendered and the references exceed the columns (textwidth) limit
+
+# Long header 1 long header 1 long header 1 long header 1 long header 1 long header 1 long header 1
+## Long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 long header 2
+### Long header 3 long header 3 long header 3 long header 3 long header 3 long header 3 long header 3
+### Long header 3 long header 3 long header 3 long header 3 long header 3 long header 3 long header 3
+## Long header 2 long header 2 long header 2 long header 2 long header 2 long header 2 long header 2
+### Long header 3 long header 3 long header 3 long header 3 long header 3 long header 3 long header 3
+### Long header 3 long header 3 long header 3 long header 3 long header 3 long header 3 long header 3
diff --git a/documents/markdown/pandoc-md/hspace.md b/documents/markdown/pandoc-md/hspace.md
new file mode 100644
index 0000000..c011f17
--- /dev/null
+++ b/documents/markdown/pandoc-md/hspace.md
@@ -0,0 +1,68 @@
+`\hspace` and `\vspace` should count as both block and inline.
+
+Here they need to be inline:
+```
+% pandoc -f markdown+raw_tex -t native
+\begin{figure}
+\includegraphics{lalune.jpg}
+\caption{lalune \hspace{2em} \vspace{1em} bloo}
+\end{figure}
+^D
+[ RawBlock
+ (Format "tex")
+ "\\begin{figure}\n\\includegraphics{lalune.jpg}\n\\caption{lalune \\hspace{2em} \\vspace{1em} bloo}\n\\end{figure}"
+]
+```
+
+Here block:
+```
+% pandoc -f markdown+raw_tex -t native
+\begin{tabular}[t]{cc|c}
+\(P\) & \(Q\) & \(P\wedge Q\)\\
+\hline
+T & T &\\
+T & F &\\
+F & T &\\
+F & F &\\
+\end{tabular}
+\hspace{1em}
+\begin{tabular}[t]{cc|c}
+\(P\) & \(Q\) & \(P\vee Q\)\\
+\hline
+T & T &\\
+T & F &\\
+F & T &\\
+F & F &\\
+\end{tabular}
+^D
+[ RawBlock
+ (Format "tex")
+ "\\begin{tabular}[t]{cc|c}\n\\(P\\) & \\(Q\\) & \\(P\\wedge Q\\)\\\\\n\\hline\nT & T &\\\\\nT & F &\\\\\nF & T &\\\\\nF & F &\\\\\n\\end{tabular}\n\\hspace{1em}\n\\begin{tabular}[t]{cc|c}\n\\(P\\) & \\(Q\\) & \\(P\\vee Q\\)\\\\\n\\hline\nT & T &\\\\\nT & F &\\\\\nF & T &\\\\\nF & F &\\\\\n\\end{tabular}"
+]
+```
+
+```
+% pandoc -f markdown+raw_tex -t native
+hi\hspace{1em}there
+^D
+[ Para
+ [ Str "hi"
+ , RawInline (Format "tex") "\\hspace{1em}"
+ , Str "there"
+ ]
+]
+```
+
+```
+% pandoc -f markdown+raw_tex -t native
+hi
+
+\hspace{1em}
+
+there
+^D
+[ Para [ Str "hi" ]
+, RawBlock (Format "tex") "\\hspace{1em}"
+, Para [ Str "there" ]
+]
+```
diff --git a/documents/markdown/pandoc-md/html-read-figure.md b/documents/markdown/pandoc-md/html-read-figure.md
new file mode 100644
index 0000000..9d7cc16
--- /dev/null
+++ b/documents/markdown/pandoc-md/html-read-figure.md
@@ -0,0 +1,81 @@
+```
+% pandoc -f html -t native
+<figure>
+ <img src="foo.png" title="voyage">
+ <figcaption>bar</figcaption>
+</figure>
+^D
+[ Figure
+ ( "" , [] , [] )
+ (Caption Nothing [ Plain [ Str "bar" ] ])
+ [ Plain
+ [ Image ( "" , [] , [] ) [] ( "foo.png" , "voyage" ) ]
+ ]
+]
+```
+
+```
+% pandoc -f html -t native
+<figure>
+ <figcaption>bar</figcaption>
+ <img src="foo.png" title="voyage">
+</figure>
+^D
+[ Figure
+ ( "" , [] , [] )
+ (Caption Nothing [ Plain [ Str "bar" ] ])
+ [ Plain
+ [ Image ( "" , [] , [] ) [] ( "foo.png" , "voyage" ) ]
+ ]
+]
+```
+
+```
+% pandoc -f html -t native
+<figure>
+ <img src="foo.png" title="voyage">
+</figure>
+^D
+[ Figure
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ Plain
+ [ Image ( "" , [] , [] ) [] ( "foo.png" , "voyage" ) ]
+ ]
+]
+```
+
+```
+% pandoc -f html -t native
+<figure>
+ <p><img src="foo.png" title="voyage"></p>
+ <figcaption>bar</figcaption>
+</figure>
+^D
+[ Figure
+ ( "" , [] , [] )
+ (Caption Nothing [ Plain [ Str "bar" ] ])
+ [ Para
+ [ Image ( "" , [] , [] ) [] ( "foo.png" , "voyage" ) ]
+ ]
+]
+```
+
+```
+% pandoc -f html -t native
+<figure><img src="foo.png" title="voyage" alt="this is ignored"><figcaption>bar <strong>baz</strong></figcaption></figure>
+^D
+[ Figure
+ ( "" , [] , [] )
+ (Caption
+ Nothing
+ [ Plain [ Str "bar" , Space , Strong [ Str "baz" ] ] ])
+ [ Plain
+ [ Image
+ ( "" , [] , [] )
+ [ Str "this" , Space , Str "is" , Space , Str "ignored" ]
+ ( "foo.png" , "voyage" )
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/html-trim-definition-list-terms.md b/documents/markdown/pandoc-md/html-trim-definition-list-terms.md
new file mode 100644
index 0000000..d2b0199
--- /dev/null
+++ b/documents/markdown/pandoc-md/html-trim-definition-list-terms.md
@@ -0,0 +1,25 @@
+```
+% pandoc -f html -t native
+<dl>
+ <dt>
+ foo
+ bar
+ </dt>
+ <dt>
+ baz
+ </dt>
+ <dd>test</dd>
+</dl>
+^D
+[ DefinitionList
+ [ ( [ Str "foo"
+ , SoftBreak
+ , Str "bar"
+ , LineBreak
+ , Str "baz"
+ ]
+ , [ [ Plain [ Str "test" ] ] ]
+ )
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/html-writer-a-in-a.md b/documents/markdown/pandoc-md/html-writer-a-in-a.md
new file mode 100644
index 0000000..219496d
--- /dev/null
+++ b/documents/markdown/pandoc-md/html-writer-a-in-a.md
@@ -0,0 +1,7 @@
+a is not allowed inside a in HTML, so we remove links in link text:
+```
+% pandoc -f native -t html
+[ Link ("",[],[]) [Link ("",[],[]) [Str "Lo"] ("url2","") ] ("url","") ]
+^D
+<a href="url"><span>Lo</span></a>
+```
diff --git a/documents/markdown/pandoc-md/hyphenat.md b/documents/markdown/pandoc-md/hyphenat.md
new file mode 100644
index 0000000..ca418c1
--- /dev/null
+++ b/documents/markdown/pandoc-md/hyphenat.md
@@ -0,0 +1,61 @@
+```
+% pandoc -f latex -t native
+electromagnetic\hyp{}endioscopy
+^D
+[ Para [ Str "electromagnetic-endioscopy" ] ]
+```
+
+```
+% pandoc -f latex -t native
+C\colonhyp\bshyp{}Windows\bshyp
+^D
+[ Para [ Str "C:\173\\\173Windows\\\173" ] ]
+```
+
+```
+% pandoc -f latex -t native
+\fshyp{}usr\fshyp{}share\fshyp
+^D
+[ Para [ Str "/\173usr/\173share/\173" ] ]
+```
+
+```
+% pandoc -f latex -t native
+\fshyp{}home\fshyp{}schrieveslaach\fshyp\dothyp{}m2
+^D
+[ Para [ Str "/\173home/\173schrieveslaach/\173.\173m2" ] ]
+```
+
+```
+% pandoc -f latex -t native
+\nohyphens{Pneumonoultramicroscopicsilicovolcanoconiosis}
+^D
+[ Para
+ [ Str "Pneumonoultramicroscopicsilicovolcanoconiosis" ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\textnhtt{Pneumonoultramicroscopicsilicovolcanoconiosis}
+^D
+[ Para
+ [ Code
+ ( "" , [] , [] )
+ "Pneumonoultramicroscopicsilicovolcanoconiosis"
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\nhttfamily{Pneumonoultramicroscopicsilicovolcanoconiosis}
+^D
+[ Para
+ [ Code
+ ( "" , [] , [] )
+ "Pneumonoultramicroscopicsilicovolcanoconiosis"
+ ]
+]
+```
+
diff --git a/documents/markdown/pandoc-md/ifstrequal.md b/documents/markdown/pandoc-md/ifstrequal.md
new file mode 100644
index 0000000..92fe6bf
--- /dev/null
+++ b/documents/markdown/pandoc-md/ifstrequal.md
@@ -0,0 +1,16 @@
+```
+% pandoc -f latex -t native
+\ifstrequal{a}{b}{yes}{\emph{no}}
+\newcommand{\h}[1]{\ifstrequal{#1}{a}{\'a}{#1}}
+\h{a}
+\h{b}
+^D
+[ Para
+ [ Emph [ Str "no" ]
+ , SoftBreak
+ , Str "\225"
+ , SoftBreak
+ , Str "b"
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/imageIndex.md b/documents/markdown/pandoc-md/imageIndex.md
new file mode 100644
index 0000000..6719ab8
--- /dev/null
+++ b/documents/markdown/pandoc-md/imageIndex.md
@@ -0,0 +1,6 @@
+# Abbildungsverzeichnis
+
+Abbildung 1: Image caption
+
+
+
diff --git a/documents/markdown/pandoc-md/images.md b/documents/markdown/pandoc-md/images.md
new file mode 100644
index 0000000..e7d3cc1
--- /dev/null
+++ b/documents/markdown/pandoc-md/images.md
@@ -0,0 +1,13 @@
+This example test if Pandoc correctly embeds images into FictionBook.
+
+Small inline image: ![alt text a small PNG image][inline-image].
+
+Paragraph image:
+
+
+
+
+
+A missing image inline: .
+
+[inline-image]: fb2/test-small.png
diff --git a/documents/markdown/pandoc-md/indented-fences.md b/documents/markdown/pandoc-md/indented-fences.md
new file mode 100644
index 0000000..12aade1
--- /dev/null
+++ b/documents/markdown/pandoc-md/indented-fences.md
@@ -0,0 +1,22 @@
+`````
+% pandoc -t native
+ ```haskell
+ let x = y
+in y
+ ```
+^D
+[ CodeBlock ( "" , [ "haskell" ] , [] ) "let x = y\nin y" ]
+`````
+`````
+% pandoc -t native
+ ~~~ {.haskell}
+ let x = y
+ in y +
+y +
+ y
+~~~
+^D
+[ CodeBlock
+ ( "" , [ "haskell" ] , [] ) " let x = y\nin y +\ny +\ny"
+]
+`````
diff --git a/documents/markdown/pandoc-md/input-with-endinput.md b/documents/markdown/pandoc-md/input-with-endinput.md
new file mode 100644
index 0000000..55d298b
--- /dev/null
+++ b/documents/markdown/pandoc-md/input-with-endinput.md
@@ -0,0 +1,15 @@
+```
+% pandoc --from=latex -t native
+\begin{document}
+Visible
+
+\include{command/bar-endinput}
+
+Visible
+\end{document}
+^D
+[ Para [ Str "Visible" ]
+, Para [ Emph [ Str "hi" , Space , Str "there" ] ]
+, Para [ Str "Visible" ]
+]
+```
diff --git a/documents/markdown/pandoc-md/jabberwocky.md b/documents/markdown/pandoc-md/jabberwocky.md
new file mode 100644
index 0000000..442534f
--- /dev/null
+++ b/documents/markdown/pandoc-md/jabberwocky.md
@@ -0,0 +1,22 @@
+```
+% pandoc -t plain -f markdown
+| 'Twas brillig, and the slithy toves
+| Did gyre and gimble in the wabe:
+| All mimsy were the borogoves,
+| And the mome raths outgrabe.
+|
+| "Beware the Jabberwock, my son!
+| The jaws that bite, the claws that catch!
+| Beware the Jubjub bird, and shun
+| The frumious Bandersnatch!"
+^D
+’Twas brillig, and the slithy toves
+ Did gyre and gimble in the wabe:
+All mimsy were the borogoves,
+ And the mome raths outgrabe.
+
+“Beware the Jabberwock, my son!
+ The jaws that bite, the claws that catch!
+Beware the Jubjub bird, and shun
+ The frumious Bandersnatch!”
+```
diff --git a/documents/markdown/pandoc-md/jats-figure-alt-text.md b/documents/markdown/pandoc-md/jats-figure-alt-text.md
new file mode 100644
index 0000000..999e7b9
--- /dev/null
+++ b/documents/markdown/pandoc-md/jats-figure-alt-text.md
@@ -0,0 +1,22 @@
+```
+% pandoc -f jats -t native
+<fig id="fig-1">
+ <caption>
+ <p>bar</p>
+ </caption>
+ <alt-text>alternative-decription</alt-text>
+ <graphic xlink:href="foo.png">
+ <alt-text>baz</alt-text>
+ </graphic>
+</fig>
+
+^D
+[ Figure
+ ( "fig-1" , [] , [] )
+ (Caption Nothing [ Plain [ Str "bar" ] ])
+ [ Plain [ Str "alternative-decription" ]
+ , Para
+ [ Image ( "" , [] , [] ) [ Str "baz" ] ( "foo.png" , "" ) ]
+ ]
+]
+```
\ No newline at end of file
diff --git a/documents/markdown/pandoc-md/latex-center.md b/documents/markdown/pandoc-md/latex-center.md
new file mode 100644
index 0000000..078a580
--- /dev/null
+++ b/documents/markdown/pandoc-md/latex-center.md
@@ -0,0 +1,12 @@
+# `\begin{center}`
+
+```
+% pandoc -f latex -t native
+\begin{center}
+Hello
+\end{center}
+
+^D
+[ Div ( "" , [ "center" ] , [] ) [ Para [ Str "Hello" ] ] ]
+```
+
diff --git a/documents/markdown/pandoc-md/latex-color.md b/documents/markdown/pandoc-md/latex-color.md
new file mode 100644
index 0000000..39837f7
--- /dev/null
+++ b/documents/markdown/pandoc-md/latex-color.md
@@ -0,0 +1,207 @@
+# `\textcolor{}{}`
+
+```
+% pandoc -f latex -t native
+Hello \textcolor{red}{World}
+^D
+[ Para
+ [ Str "Hello"
+ , Space
+ , Span
+ ( "" , [] , [ ( "style" , "color: red" ) ] ) [ Str "World" ]
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\textcolor{red}{Hello} World
+^D
+[ Para
+ [ Span
+ ( "" , [] , [ ( "style" , "color: red" ) ] ) [ Str "Hello" ]
+ , Space
+ , Str "World"
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+Hello \textcolor{blue}{\textbf{World}}
+^D
+[ Para
+ [ Str "Hello"
+ , Space
+ , Span
+ ( "" , [] , [ ( "style" , "color: blue" ) ] )
+ [ Strong [ Str "World" ] ]
+ ]
+]
+```
+
+
+```
+% pandoc -f latex -t native
+Hello \textcolor{blue}{\textbf{World}}.
+^D
+[ Para
+ [ Str "Hello"
+ , Space
+ , Span
+ ( "" , [] , [ ( "style" , "color: blue" ) ] )
+ [ Strong [ Str "World" ] ]
+ , Str "."
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\textcolor{orange}{
+\begin{itemize}
+ \item Item 1
+ \item Item 2
+\end{itemize}
+}
+^D
+[ Div
+ ( "" , [] , [ ( "style" , "color: orange" ) ] )
+ [ BulletList
+ [ [ Para [ Str "Item" , Space , Str "1" ] ]
+ , [ Para [ Str "Item" , Space , Str "2" ] ]
+ ]
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\textcolor{blue}{
+\begin{itemize}
+ \item Item 1
+ \item Item 2
+\end{itemize}
+} some more text
+^D
+[ Div
+ ( "" , [] , [ ( "style" , "color: blue" ) ] )
+ [ BulletList
+ [ [ Para [ Str "Item" , Space , Str "1" ] ]
+ , [ Para [ Str "Item" , Space , Str "2" ] ]
+ ]
+ ]
+, Para
+ [ Str "some" , Space , Str "more" , Space , Str "text" ]
+]
+```
+
+# `\colorbox{}{}`
+
+
+```
+% pandoc -f latex -t native
+Hello \colorbox{red}{World}
+^D
+[ Para
+ [ Str "Hello"
+ , Space
+ , Span
+ ( "" , [] , [ ( "style" , "background-color: red" ) ] )
+ [ Str "World" ]
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\colorbox{red}{Hello} World
+^D
+[ Para
+ [ Span
+ ( "" , [] , [ ( "style" , "background-color: red" ) ] )
+ [ Str "Hello" ]
+ , Space
+ , Str "World"
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+Hello \colorbox{blue}{\textbf{World}}
+^D
+[ Para
+ [ Str "Hello"
+ , Space
+ , Span
+ ( "" , [] , [ ( "style" , "background-color: blue" ) ] )
+ [ Strong [ Str "World" ] ]
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+Hello \colorbox{blue}{\textbf{World}}.
+^D
+[ Para
+ [ Str "Hello"
+ , Space
+ , Span
+ ( "" , [] , [ ( "style" , "background-color: blue" ) ] )
+ [ Strong [ Str "World" ] ]
+ , Str "."
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\colorbox{orange}{
+\begin{minipage}{\textwidth}
+\begin{itemize}
+ \item Item 1
+ \item Item 2
+\end{itemize}
+\end{minipage}
+}
+^D
+[ Div
+ ( "" , [] , [ ( "style" , "background-color: orange" ) ] )
+ [ Div
+ ( "" , [ "minipage" ] , [] )
+ [ BulletList
+ [ [ Para [ Str "Item" , Space , Str "1" ] ]
+ , [ Para [ Str "Item" , Space , Str "2" ] ]
+ ]
+ ]
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\colorbox{blue}{
+\begin{minipage}{\textwidth}
+\begin{itemize}
+ \item Item 1
+ \item Item 2
+\end{itemize}
+\end{minipage}
+} some more text
+^D
+[ Div
+ ( "" , [] , [ ( "style" , "background-color: blue" ) ] )
+ [ Div
+ ( "" , [ "minipage" ] , [] )
+ [ BulletList
+ [ [ Para [ Str "Item" , Space , Str "1" ] ]
+ , [ Para [ Str "Item" , Space , Str "2" ] ]
+ ]
+ ]
+ ]
+, Para
+ [ Str "some" , Space , Str "more" , Space , Str "text" ]
+]
+```
diff --git a/documents/markdown/pandoc-md/latex-fontawesome.md b/documents/markdown/pandoc-md/latex-fontawesome.md
new file mode 100644
index 0000000..18512ac
--- /dev/null
+++ b/documents/markdown/pandoc-md/latex-fontawesome.md
@@ -0,0 +1,13 @@
+```
+% pandoc -f latex -t native
+Check: \faCheck
+^D
+[ Para [ Str "Check:" , Space , Str "\10003" ] ]
+```
+
+```
+% pandoc -f latex -t native
+Close: \faClose
+^D
+[ Para [ Str "Close:" , Space , Str "\10007" ] ]
+```
diff --git a/documents/markdown/pandoc-md/latex-math-trailing-space.md b/documents/markdown/pandoc-md/latex-math-trailing-space.md
new file mode 100644
index 0000000..6502b12
--- /dev/null
+++ b/documents/markdown/pandoc-md/latex-math-trailing-space.md
@@ -0,0 +1,38 @@
+Test that trailing spaces before \end{equation} don't create spurious paragraph breaks:
+
+```
+% pandoc -f latex -t latex
+\begin{equation}
+ a
+ \end{equation}
+^D
+\begin{equation}
+ a
+\end{equation}
+```
+
+Same for align environment:
+
+```
+% pandoc -f latex -t latex
+\begin{align}
+ x &= y \\
+ \end{align}
+^D
+\begin{align}
+ x &= y \\
+\end{align}
+```
+
+Test with multiple trailing spaces:
+
+```
+% pandoc -f latex -t latex
+\begin{equation}
+ a + b
+ \end{equation}
+^D
+\begin{equation}
+ a + b
+\end{equation}
+```
diff --git a/documents/markdown/pandoc-md/latex-tabular-column-specs.md b/documents/markdown/pandoc-md/latex-tabular-column-specs.md
new file mode 100644
index 0000000..586fed3
--- /dev/null
+++ b/documents/markdown/pandoc-md/latex-tabular-column-specs.md
@@ -0,0 +1,95 @@
+See https://groups.google.com/forum/#!topic/pandoc-discuss/_VXtqihCyDU.
+
+```
+% pandoc -f latex -t native
+\begin{tabular}{>{$}l<{$}>{$}l<{$} >{$}l<{$}}
+\toprule
+& f1 & f2 \\
+\midrule
+e & 0.5 & 4 \\
+f & 0.5 & 5,5 \\
+\bottomrule
+\end{tabular}
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignLeft , ColWidthDefault )
+ , ( AlignLeft , ColWidthDefault )
+ , ( AlignLeft , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Math InlineMath "" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Math InlineMath "f1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Math InlineMath "f2" ] ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Math InlineMath "e" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Math InlineMath "0.5" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Math InlineMath "4" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Math InlineMath "f" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Math InlineMath "0.5" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Math InlineMath "5,5" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
diff --git a/documents/markdown/pandoc-md/lettrine.md b/documents/markdown/pandoc-md/lettrine.md
new file mode 100644
index 0000000..b4a2794
--- /dev/null
+++ b/documents/markdown/pandoc-md/lettrine.md
@@ -0,0 +1,20 @@
+```
+% pandoc -f latex -t native
+\lettrine{A}{category} is
+
+\lettrine[lhang=0.17]{A}{category} is
+^D
+[ Para
+ [ Span ( "" , [ "lettrine" ] , [] ) [ Str "A" ]
+ , SmallCaps [ Str "category" ]
+ , Space
+ , Str "is"
+ ]
+, Para
+ [ Span ( "" , [ "lettrine" ] , [] ) [ Str "A" ]
+ , SmallCaps [ Str "category" ]
+ , Space
+ , Str "is"
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/lhs-test.md b/documents/markdown/pandoc-md/lhs-test.md
new file mode 100644
index 0000000..0ddf24a
--- /dev/null
+++ b/documents/markdown/pandoc-md/lhs-test.md
@@ -0,0 +1,21 @@
+lhs test
+========
+
+`unsplit` is an arrow that takes a pair of values and combines them to
+return a single value:
+
+``` {.haskell .literate}
+unsplit :: (Arrow a) => (b -> c -> d) -> a (b, c) d
+unsplit = arr . uncurry
+ -- arr (\op (x,y) -> x `op` y)
+```
+
+`(***)` combines two arrows into a new arrow by running the two arrows on a
+pair of values (one arrow on the first item of the pair and one arrow on the
+second item of the pair).
+
+ f *** g = first f >>> second g
+
+Block quote:
+
+> foo bar
diff --git a/documents/markdown/pandoc-md/listBlocks.md b/documents/markdown/pandoc-md/listBlocks.md
new file mode 100644
index 0000000..22c77bb
--- /dev/null
+++ b/documents/markdown/pandoc-md/listBlocks.md
@@ -0,0 +1,6 @@
+<text:list xml:id="list2666723676250588421" text:style-name="L6">
+<text:list-header>
+<text:p text:style-name="P1">Indented text in a list.</text:p>
+</text:list-header>
+<text:list-item>
+<text:p text:style-name="P1">This is a numbered block.<text:line-break/>It contains several paragraphs of text.<text:line-break/>Like this.</text:p></text:list-item><text:list-item><text:p text:style-name="P1">Next item.</text:p></text:list-item></text:list></office:text></office:body></office:document-content>
\ No newline at end of file
diff --git a/documents/markdown/pandoc-md/lists-inside-definition.md b/documents/markdown/pandoc-md/lists-inside-definition.md
new file mode 100644
index 0000000..de2c72c
--- /dev/null
+++ b/documents/markdown/pandoc-md/lists-inside-definition.md
@@ -0,0 +1,70 @@
+This inserts an empty `\item[]` when a list occurs at the
+beginning of a definition list definition; otherwise the list
+may start on the line with the label, which looks terrible.
+See https://tex.stackexchange.com/questions/192480/force-itemize-inside-description-onto-a-new-line
+
+```
+% pandoc -t latex
+Definition
+: 1. list
+ 2. list
+^D
+\begin{description}
+\tightlist
+\item[Definition]
+\hfill
+\begin{enumerate}
+\def\labelenumi{\arabic{enumi}.}
+\tightlist
+\item
+ list
+\item
+ list
+\end{enumerate}
+\end{description}
+```
+
+```
+% pandoc -t latex
+Definition
+: Foo
+
+ 1. list
+ 2. list
+^D
+\begin{description}
+\tightlist
+\item[Definition]
+Foo
+
+\begin{enumerate}
+\def\labelenumi{\arabic{enumi}.}
+\tightlist
+\item
+ list
+\item
+ list
+\end{enumerate}
+\end{description}
+```
+
+```
+% pandoc -t latex
+Definition
+: - list
+ - list
+^D
+\begin{description}
+\tightlist
+\item[Definition]
+\hfill
+\begin{itemize}
+\tightlist
+\item
+ list
+\item
+ list
+\end{itemize}
+\end{description}
+```
+
diff --git a/documents/markdown/pandoc-md/lstlisting.md b/documents/markdown/pandoc-md/lstlisting.md
new file mode 100644
index 0000000..2ea8b4b
--- /dev/null
+++ b/documents/markdown/pandoc-md/lstlisting.md
@@ -0,0 +1,44 @@
+```
+% pandoc -f latex -t native
+\begin{lstlisting}[language=Java, caption={Java Example}, label=lst:Hello-World]
+public class World {
+ public static void main(String[] args) {
+ System.out.println("Hello World");
+ }
+}
+\end{lstlisting}
+^D
+[ CodeBlock
+ ( "lst:Hello-World"
+ , [ "java" ]
+ , [ ( "language" , "Java" )
+ , ( "caption" , "Java Example" )
+ , ( "label" , "lst:Hello-World" )
+ ]
+ )
+ "public class World {\n public static void main(String[] args) {\n System.out.println(\"Hello World\");\n }\n}"
+]
+```
+
+```
+% pandoc -f latex -t native
+\begin{lstlisting}[language=Java, escapechar=|, caption={Java Example}, label=lst:Hello-World]
+public class World {
+ public static void main(String[] args) {
+ System.out.println("Hello World");
+ }
+}
+\end{lstlisting}
+^D
+[ CodeBlock
+ ( "lst:Hello-World"
+ , [ "java" ]
+ , [ ( "language" , "Java" )
+ , ( "escapechar" , "|" )
+ , ( "caption" , "Java Example" )
+ , ( "label" , "lst:Hello-World" )
+ ]
+ )
+ "public class World {\n public static void main(String[] args) {\n System.out.println(\"Hello World\");\n }\n}"
+]
+```
diff --git a/documents/markdown/pandoc-md/macro-defs-in-preamble.md b/documents/markdown/pandoc-md/macro-defs-in-preamble.md
new file mode 100644
index 0000000..7bd72d1
--- /dev/null
+++ b/documents/markdown/pandoc-md/macro-defs-in-preamble.md
@@ -0,0 +1,18 @@
+```
+% pandoc -s -f latex-latex_macros -t native
+\documentclass[11pt]{article}
+
+\newcommand{\vara}{\alpha}
+\newcommand{\varb}{b}
+
+\begin{document}
+$\vara \varb$
+\end{document}
+^D
+Pandoc
+ Meta { unMeta = fromList [] }
+ [ RawBlock (Format "latex") "\\newcommand{\\vara}{\\alpha}"
+ , RawBlock (Format "latex") "\\newcommand{\\varb}{b}"
+ , Para [ Math InlineMath "\\vara \\varb" ]
+ ]
+```
diff --git a/documents/markdown/pandoc-md/macros.md b/documents/markdown/pandoc-md/macros.md
new file mode 100644
index 0000000..d90498e
--- /dev/null
+++ b/documents/markdown/pandoc-md/macros.md
@@ -0,0 +1,162 @@
+```
+% pandoc -f markdown+latex_macros -t markdown+raw_tex-raw_attribute
+\newcommand{\my}{\phi}
+$\my+\my$
+^D
+\newcommand{\my}{\phi}
+
+$\phi+\phi$
+```
+
+```
+% pandoc -f markdown-latex_macros -t markdown+raw_tex-raw_attribute
+\newcommand{\my}{\phi}
+$\my+\my$
+^D
+\newcommand{\my}{\phi}
+
+$\my+\my$
+```
+
+`\let` macros should be expanded at point of
+definition, while `\newcommand` macros should be
+expanded at point of use:
+
+```
+% pandoc -f latex -t latex
+\let\a\b
+\def\b{\emph{ouk}}
+\a a
+^D
+a̱
+```
+
+```
+% pandoc -f latex -t latex
+\newcommand{\a}{\b}
+\newcommand{\b}{\emph{ouk}}
+\a a
+^D
+\emph{ouk}a
+```
+
+```
+% pandoc -f latex -t latex
+\def\BDpos{}
+\def\BDneg{-}
+\def\beq{\begin{align}}
+\def\eeq{\end{align}}
+\def\e#1{\emph{#1}}
+\def\f#1#2{\emph{#1--#2}}
+
+$5\BDneg 6\BDpos 7$
+
+\beq
+x &= y\\
+\eeq
+
+\e{hi}
+
+\f{hi}{ok}
+^D
+\(5-67\)
+
+\begin{align}
+x &= y\\
+\end{align}
+
+\emph{hi}
+
+\emph{hi--ok}
+```
+
+```
+% pandoc -f markdown+latex_macros -t markdown+raw_tex-raw_attribute
+\newcommand{\my}{\phi}
+\begin{equation}
+\my+\my
+\end{equation}
+^D
+\newcommand{\my}{\phi}
+
+\begin{equation}
+\phi+\phi
+\end{equation}
+```
+
+```
+% pandoc -f markdown-latex_macros -t markdown+raw_tex-raw_attribute
+\newcommand{\my}{\phi}
+\begin{equation}
+\my+\my
+\end{equation}
+^D
+\newcommand{\my}{\phi}
+
+\begin{equation}
+\my+\my
+\end{equation}
+```
+
+```
+% pandoc -f markdown+latex_macros -t markdown+raw_tex-raw_attribute
+\newcommand{\my}{\emph{a}}
+\my
+^D
+\newcommand{\my}{\emph{a}}
+\emph{a}
+```
+
+<https://tex.stackexchange.com/questions/258/what-is-the-difference-between-let-and-def>
+
+```
+% pandoc -f latex -t plain
+\def\bar{hello}
+\let\fooi\bar
+\def\fooii{\bar}
+\fooi +\fooii
+
+\def\bar{goodbye}
+\fooi +\fooii
+^D
+hello+hello
+
+hello+goodbye
+```
+
+```
+% pandoc -f latex -t plain
+\def\txt{a}
+\def\foo{\txt}
+\let\bar\foo
+\bar % -> a
+\def\txt{b}
+\bar % -> b
+\def\foo{OH}
+\bar % -> b
+^D
+a b b
+```
+
+```
+% pandoc -f latex -t plain
+\def\aaa{aaa}
+\def\bbb{x\aaa}
+\edef\ccc{y\aaa}
+\def\aaa{AAA}
+\bbb \ccc
+^D
+xAAAyaaa
+```
+
+```
+% pandoc -f latex -t plain
+\gdef\aaa{aaa}
+\gdef\bbb{x\aaa}
+\xdef\ccc{y\aaa}
+\gdef\aaa{AAA}
+\bbb \ccc
+^D
+xAAAyaaa
+```
+
diff --git a/documents/markdown/pandoc-md/make-section-column-divs.md b/documents/markdown/pandoc-md/make-section-column-divs.md
new file mode 100644
index 0000000..0e85482
--- /dev/null
+++ b/documents/markdown/pandoc-md/make-section-column-divs.md
@@ -0,0 +1,28 @@
+For reference see
+https://groups.google.com/d/msgid/pandoc-discuss/cef24253-7731-417c-a1ee-48153c4344bf%40googlegroups.com
+
+```
+% pandoc
+::: columns
+::: column
+# A
+
+a
+:::
+::: column
+# B
+
+b
+:::
+:::
+^D
+<div class="columns">
+<div class="column">
+<h1 id="a">A</h1>
+<p>a</p>
+</div><div class="column">
+<h1 id="b">B</h1>
+<p>b</p>
+</div>
+</div>
+```
diff --git a/documents/markdown/pandoc-md/math.md b/documents/markdown/pandoc-md/math.md
new file mode 100644
index 0000000..a88fb6c
--- /dev/null
+++ b/documents/markdown/pandoc-md/math.md
@@ -0,0 +1,10 @@
+List math:
+
+- $E = m c^2$
+- $A = \pi r^2$
+
+Inline math: $x=\frac{-b \pm \sqrt {b^2-4ac}}{2a}$.
+
+Display math:
+
+$$\int_a^b \! f(x)\,dx = F(b) - F(a).$$
diff --git a/documents/markdown/pandoc-md/md-abbrevs.md b/documents/markdown/pandoc-md/md-abbrevs.md
new file mode 100644
index 0000000..a3ee6af
--- /dev/null
+++ b/documents/markdown/pandoc-md/md-abbrevs.md
@@ -0,0 +1,21 @@
+Pandoc recognizes an abbreviation and inserts a nonbreaking
+space (among other things, this prevents a sentence-ending
+space from being inserted in LaTeX output).
+
+```
+% pandoc -t native
+Mr. Bob
+^D
+[ Para [ Str "Mr.\160Bob" ] ]
+```
+
+If you don't want this to happen you can escape the period:
+
+```
+% pandoc -t native
+Hi Mr\. Bob
+^D
+[ Para [ Str "Hi" , Space , Str "Mr." , Space , Str "Bob" ]
+]
+```
+
diff --git a/documents/markdown/pandoc-md/mdoc-An.md b/documents/markdown/pandoc-md/mdoc-An.md
new file mode 100644
index 0000000..c219cdb
--- /dev/null
+++ b/documents/markdown/pandoc-md/mdoc-An.md
@@ -0,0 +1,17 @@
+```
+% pandoc -f mdoc -t plain
+.Sh DESCRIPTION
+.An Emily Brontë ,
+.An Anne Brontë
+.Pp
+.An -split
+.An Charlotte Brontë
+.An Bramwell Brontë
+^D
+DESCRIPTION
+
+Emily Brontë, Anne Brontë
+
+Charlotte Brontë
+Bramwell Brontë
+```
diff --git a/documents/markdown/pandoc-md/mdoc-Bd-unfilled.md b/documents/markdown/pandoc-md/mdoc-Bd-unfilled.md
new file mode 100644
index 0000000..10a39cc
--- /dev/null
+++ b/documents/markdown/pandoc-md/mdoc-Bd-unfilled.md
@@ -0,0 +1,24 @@
+```
+% pandoc -f mdoc -t plain
+.Bd -unfilled
+’Twas brillig, and the slithy toves
+ Did gyre and gimble in the wabe:
+All mimsy were the borogoves,
+ And the mome raths outgrabe.
+
+“Beware the Jabberwock, my son!
+ The jaws that bite, the claws that catch!
+Beware the Jubjub bird, and shun
+ The frumious Bandersnatch!”
+.Ed
+^D
+’Twas brillig, and the slithy toves
+ Did gyre and gimble in the wabe:
+All mimsy were the borogoves,
+ And the mome raths outgrabe.
+
+“Beware the Jabberwock, my son!
+ The jaws that bite, the claws that catch!
+Beware the Jubjub bird, and shun
+ The frumious Bandersnatch!”
+```
diff --git a/documents/markdown/pandoc-md/mdoc-Bl-column.md b/documents/markdown/pandoc-md/mdoc-Bl-column.md
new file mode 100644
index 0000000..c460b03
--- /dev/null
+++ b/documents/markdown/pandoc-md/mdoc-Bl-column.md
@@ -0,0 +1,22 @@
+```
+% pandoc -f mdoc -t djot
+.Bl -column a b
+.It a Ta
+.Sy b
+b
+.Ta c
+.Pp
+.It c Ta d Ta \&
+.It Em e
+.Ta f
+.Ta g
+.It h Ta Ta j
+.It Pq a Ta b Ta c
+.El
+^D
+| a | *b* b | c |
+| c | d | |
+| _e_ | f | g |
+| h | | j |
+| (a) | b | c |
+```
diff --git a/documents/markdown/pandoc-md/mdoc-Bl-tag.md b/documents/markdown/pandoc-md/mdoc-Bl-tag.md
new file mode 100644
index 0000000..5f5bd94
--- /dev/null
+++ b/documents/markdown/pandoc-md/mdoc-Bl-tag.md
@@ -0,0 +1,36 @@
+```
+% pandoc -f mdoc -t native
+.Bl -tag
+.It one
+one
+.It Xo
+two
+.Xc
+two
+.It Em three Xo
+three
+.Xc
+three
+.It Po one two
+.Bq three
+.Pc
+four
+.El
+^D
+[ DefinitionList
+ [ ( [ Str "one" ] , [ [ Para [ Str "one" ] ] ] )
+ , ( [ Str "two" ] , [ [ Para [ Str "two" ] ] ] )
+ , ( [ Emph [ Str "three" ] , Space , Str "three" ]
+ , [ [ Para [ Str "three" ] ] ]
+ )
+ , ( [ Str "(one"
+ , Space
+ , Str "two"
+ , Space
+ , Str "[three])"
+ ]
+ , [ [ Para [ Str "four" ] ] ]
+ )
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/mediawiki_behavior_switches.md b/documents/markdown/pandoc-md/mediawiki_behavior_switches.md
new file mode 100644
index 0000000..3798df4
--- /dev/null
+++ b/documents/markdown/pandoc-md/mediawiki_behavior_switches.md
@@ -0,0 +1,16 @@
+```
+% pandoc -f mediawiki -t native
+____INDEX____
+__NOINDEX__
+__noindex__
+__FOOBAR__
+^D
+[ Para
+ [ Str "____"
+ , SoftBreak
+ , Str "__noindex__"
+ , SoftBreak
+ , Str "__FOOBAR__"
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/mmd-metadata.md b/documents/markdown/pandoc-md/mmd-metadata.md
new file mode 100644
index 0000000..3cda348
--- /dev/null
+++ b/documents/markdown/pandoc-md/mmd-metadata.md
@@ -0,0 +1,20 @@
+```
+% pandoc -f markdown_mmd -t markdown -s
+Title: Blah blah blah
+Author: Doo de Doo
+Base Header Level: 1
+Bibliography: Pubs.bib
+Lang: en-GB
+
+body
+^D
+---
+author: Doo de Doo
+baseheaderlevel: 1
+bibliography: Pubs.bib
+lang: en-GB
+title: Blah blah blah
+---
+
+body
+```
diff --git a/documents/markdown/pandoc-md/multiple-metadata-blocks.md b/documents/markdown/pandoc-md/multiple-metadata-blocks.md
new file mode 100644
index 0000000..e117f37
--- /dev/null
+++ b/documents/markdown/pandoc-md/multiple-metadata-blocks.md
@@ -0,0 +1,19 @@
+If multiple blocks define a field, the first is used.
+
+```
+% pandoc -s -t native
+---
+foo: bar
+...
+
+---
+foo: bim
+...
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList [ ( "foo" , MetaInlines [ Str "bim" ] ) ]
+ }
+ []
+```
diff --git a/documents/markdown/pandoc-md/nested-spanlike.md b/documents/markdown/pandoc-md/nested-spanlike.md
new file mode 100644
index 0000000..f3e1cd3
--- /dev/null
+++ b/documents/markdown/pandoc-md/nested-spanlike.md
@@ -0,0 +1,6 @@
+```
+% pandoc -f markdown -t html
+[test]{.foo .underline #bar .smallcaps .kbd}
+^D
+<p><kbd id="bar"><u><span class="smallcaps">test</span></u></kbd></p>
+```
diff --git a/documents/markdown/pandoc-md/nested-table-to-asciidoc-6942.md b/documents/markdown/pandoc-md/nested-table-to-asciidoc-6942.md
new file mode 100644
index 0000000..c305801
--- /dev/null
+++ b/documents/markdown/pandoc-md/nested-table-to-asciidoc-6942.md
@@ -0,0 +1,82 @@
+A table within a table should be converted into a table within table
+
+```
+% pandoc -f html -t asciidoc
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<title> NestedTables </title>
+</head>
+<body>
+<table>
+ <tr>
+ <td >
+ <table> <tr> <td> a1 </td> <td> a2 </td> </tr> </table>
+ </td>
+ <td>b</td>
+ </tr>
+ <tr>
+ <td>c</td> <td>d </td>
+ </tr>
+</table>
+</body>
+</html>
+^D
+[width="100%",cols="50%,50%",]
+|===
+a|
+[cols=",",]
+!===
+!a1 !a2
+!===
+
+|b
+|c |d
+|===
+```
+
+A table within a table within a table cannot be converted because asciidoc only
+supports two levels of tables.
+The table on level 3 is thus converted to level 2 and a warning is produced
+```
+% pandoc -f html -t asciidoc --verbose
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<title> NestedTables </title>
+</head>
+<body>
+<table>
+ <tr>
+ <td>
+ <table> <tr>
+ <td> a1 </td>
+ <td>
+ <table> <tr> <td> 1 </td> <td> 2 </td> </tr> </table>
+ </td>
+ </tr> </table>
+ </td>
+ <td>b</td>
+ </tr>
+ <tr>
+ <td>c</td> <td>d </td>
+ </tr>
+</table>
+</body>
+</html>
+^D
+2> [INFO] Not rendering Table ("",[],[]) (Caption Nothing []) [(AlignDefault,ColWidth 0.5),(AlignDefault,ColWidth 0.5)] (TableHead ("",[],[]) []) [TableBody ("",[],[]) (RowHeadColumns 0) [] [Row ("",[],[]) [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1) [Plain [Str "a1"]],Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1) [Table ("",[],[]) (Caption Nothing []) [(AlignDefault,ColWidthDefault),(AlignDefault,ColWidthDefault)] (TableHead ("",[],[]) []) [TableBody ("",[],[]) (RowHeadColumns 0) [] [Row ("",[],[]) [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1) [Plain [Str "1"]],Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1) [Plain [Str "2"]]]]] (TableFoot ("",[],[]) [])]]]] (TableFoot ("",[],[]) [])
+[width="100%",cols="50%,50%",]
+|===
+a|
+[width="100%",cols="50%,50%",]
+!===
+!a1 !
+!===
+
+|b
+|c |d
+|===
+```
diff --git a/documents/markdown/pandoc-md/newif.md b/documents/markdown/pandoc-md/newif.md
new file mode 100644
index 0000000..730f969
--- /dev/null
+++ b/documents/markdown/pandoc-md/newif.md
@@ -0,0 +1,55 @@
+```
+% pandoc -f latex -t plain
+\iftrue
+should print
+\iftrue
+should print
+\else
+should not print A
+\fi
+\else
+should not print B
+\fi
+
+\iffalse
+should not print C
+\else
+\iftrue
+should print
+\else
+should not print D
+\fi
+\fi
+
+\newif\ifepub
+
+\ifepub
+should not print E
+\fi
+
+\epubtrue
+
+\ifepub
+should print
+\else
+should not print F
+\fi
+
+\epubfalse
+
+\ifepub
+should not print G
+\else
+should print
+\fi
+^D
+should print
+
+should print
+
+should print
+
+should print
+
+should print
+```
diff --git a/documents/markdown/pandoc-md/nordics.md b/documents/markdown/pandoc-md/nordics.md
new file mode 100644
index 0000000..16e3bb3
--- /dev/null
+++ b/documents/markdown/pandoc-md/nordics.md
@@ -0,0 +1,18 @@
++-----------------------+-----------------------+---------------+---------------+
+| Name | Capital | Population\ | Area\ |
+| | | (in 2018) | (in km^2^) |
++:=====================:+:======================+:==============+:==============+
+| Denmark | Copenhagen | 5,809,502 | 43,094 |
++-----------------------+-----------------------+---------------+---------------+
+| Finland | Helsinki | 5,537,364 | 338,145 |
++-----------------------+-----------------------+---------------+---------------+
+| Iceland | Reykjavik | 343,518 | 103,000 |
++-----------------------+-----------------------+---------------+---------------+
+| Norway | Oslo | 5,372,191 | 323,802 |
++-----------------------+-----------------------+---------------+---------------+
+| Sweden | Stockholm | 10,313,447 | 450,295 |
++=======================+=======================+===============+===============+
+| Total | | 27,376,022 | 1,258,336 |
++=======================+=======================+===============+===============+
+
+: States belonging to the *Nordics.* {#nordics source="wikipedia"}
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-118.md b/documents/markdown/pandoc-md/pandoc-citeproc-118.md
new file mode 100644
index 0000000..5aa727e
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-118.md
@@ -0,0 +1,27 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+references:
+- director:
+ family: Hitchcock
+ given: Alfred
+ id: nbn
+ issued:
+ year: 1959
+ language: 'en-US'
+ publisher: 'Metro-Goldwyn-Mayer'
+ publisher-place: USA
+ title: North by Northwest
+ type: motion_picture
+---
+
+[@nbn] is a spy thriller film.
+^D
+(Hitchcock 1959) is a spy thriller film.
+
+:::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-nbn .csl-entry}
+Hitchcock, Alfred, dir. 1959. *North by Northwest*. Metro-Goldwyn-Mayer.
+:::
+::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-119.md b/documents/markdown/pandoc-md/pandoc-citeproc-119.md
new file mode 100644
index 0000000..59ed35d
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-119.md
@@ -0,0 +1,38 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+bibliography: 'command/averroes.bib'
+csl: command/apa.csl
+---
+
+@averroes/bland; @averroes/hannes; @averroes/hercz
+
+References {#references .unnumbered}
+==========
+^D
+Averroes (1982); Averroes (1892); Averroes (1869)
+
+# References {#references .unnumbered}
+
+:::::: {#refs .references .csl-bib-body .hanging-indent entry-spacing="0" line-spacing="2"}
+::: {#ref-averroes/hercz .csl-entry}
+Averroes. (1869). *Drei Abhandlungen über die Conjunction des separaten
+Intellects mit dem Menschen: Von Averroes (Vater und Sohn), aus dem
+Arabischen übersetzt von Samuel Ibn Tibbon*. (J. Hercz, Ed. & Trans.).
+Berlin: S. Hermann.
+:::
+
+::: {#ref-averroes/hannes .csl-entry}
+Averroes. (1892). *Des Averroës Abhandlung: "Über die Möglichkeit der
+Conjunktion" oder "Über den materiellen Intellekt"*. (L. Hannes, Ed. &
+Trans.). Halle an der Saale: C. A. Kaemmerer.
+:::
+
+::: {#ref-averroes/bland .csl-entry}
+Averroes. (1982). *The epistle on the possibility of conjunction with
+the active intellect by Ibn Rushd with the commentary of Moses Narboni*.
+(K. P. Bland, Ed. & Trans.). New York: Jewish Theological Seminary of
+America.
+:::
+::::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-13.md b/documents/markdown/pandoc-md/pandoc-citeproc-13.md
new file mode 100644
index 0000000..24f7375
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-13.md
@@ -0,0 +1,29 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: 'command/chicago-note-bibliography.csl'
+references:
+- author:
+ family: Author
+ given:
+ - Ann
+ container-title: Journal
+ id: item1
+ issued:
+ - year: 2011
+ title: Title
+ type: 'article-newspaper'
+---
+
+Foo [@item1].
+^D
+Foo.[^1]
+
+:::: {#refs .references .csl-bib-body .hanging-indent entry-spacing="0"}
+::: {#ref-item1 .csl-entry}
+Author, Ann. "Title." *Journal*, 2011.
+:::
+::::
+
+[^1]: Author, "Title."
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-136.md b/documents/markdown/pandoc-md/pandoc-citeproc-136.md
new file mode 100644
index 0000000..3657900
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-136.md
@@ -0,0 +1,23 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+references:
+- id: stanze
+ type: book
+ issued:
+ - year: 1547
+ title: Stanze in lode della donna brutta
+ publisher-place: Florence
+ language: it-IT
+...
+
+@stanze is an anoynymous work.
+^D
+*Stanze in lode della donna brutta* (1547) is an anoynymous work.
+
+:::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-stanze .csl-entry}
+*Stanze in lode della donna brutta*. 1547. Florence.
+:::
+::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-14.md b/documents/markdown/pandoc-md/pandoc-citeproc-14.md
new file mode 100644
index 0000000..4137080
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-14.md
@@ -0,0 +1,77 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+references:
+- author:
+ family: Pelikan
+ given: Jaroslav
+ container-title: 'The Christian tradition: A history of the
+ development of doctrine'
+ id: CTv1c2
+ issued:
+ - year: 1971
+ language: 'en-US'
+ page: '34-56'
+ publisher: University of Chicago Press
+ publisher-place: Chicago
+ title: Chapter two
+ type: chapter
+ volume: 1
+ volume-title: 'The emergence of the Catholic tradition (100--600)'
+- author:
+ family: Pelikan
+ given: Jaroslav
+ container-title: 'The Christian tradition: A history of the
+ development of doctrine'
+ id: CTv1
+ issued:
+ - year: 1971
+ language: 'en-US'
+ publisher: University of Chicago Press
+ publisher-place: Chicago
+ title: 'The emergence of the Catholic tradition (100--600)'
+ type: book
+ volume: 1
+- author:
+ family: Pelikan
+ given: Jaroslav
+ id: CT
+ issued:
+ - year: 1971
+ language: 'en-US'
+ publisher: University of Chicago Press
+ publisher-place: Chicago
+ title: 'The Christian tradition: A history of the development of
+ doctrine'
+ type: book
+---
+
+Foo [@CT, 1:12]. Bar [@CTv1, 12]. Baz [@CTv1c2, 12].
+
+References {#references .unnumbered}
+==========
+^D
+Foo (Pelikan 1971b, 1:12). Bar (Pelikan 1971c, 12). Baz (Pelikan 1971a,
+12).
+
+# References {#references .unnumbered}
+
+:::::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-CTv1c2 .csl-entry}
+Pelikan, Jaroslav. 1971a. "Chapter Two." In *The Emergence of the
+Catholic Tradition (100--600)*, vol. 1 of *The Christian Tradition: A
+History of the Development of Doctrine*. University of Chicago Press.
+:::
+
+::: {#ref-CT .csl-entry}
+Pelikan, Jaroslav. 1971b. *The Christian Tradition: A History of the
+Development of Doctrine*. University of Chicago Press.
+:::
+
+::: {#ref-CTv1 .csl-entry}
+Pelikan, Jaroslav. 1971c. *The Emergence of the Catholic Tradition
+(100--600)*. In *The Christian Tradition: A History of the Development
+of Doctrine*, vol. 1. University of Chicago Press.
+:::
+::::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-152.md b/documents/markdown/pandoc-md/pandoc-citeproc-152.md
new file mode 100644
index 0000000..c4b1a1b
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-152.md
@@ -0,0 +1,63 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: command/apa.csl
+references:
+- URL: 'http://geekfeminism.wikia.com/wiki/Geek_Feminism'
+ accessed:
+ day: 10
+ month: 4
+ year: 2013
+ container-title: Geek Feminism
+ custom2: ok.mm
+ id: Feminism2013gf
+ issued:
+ day: 10
+ month: 4
+ year: 2013
+ keyword: gender
+ title: Geek Feminism
+ type: webpage
+- URL: 'http://geekfeminism.wikia.com/wiki/Category:Communities'
+ accessed:
+ day: 19
+ month: 10
+ year: 2011
+ container-title: Geek Feminism
+ custom2: gender.mm
+ id: Feminism2011ces
+ issued:
+ day: 14
+ month: 8
+ year: 2011
+ keyword: gender
+ title: Communities
+ type: 'entry-encyclopedia'
+---
+
+Test
+====
+
+I have two citations [@Feminism2013gf; @Feminism2011ces].
+
+References
+==========
+^D
+# Test
+
+I have two citations ("Communities," 2011; "Geek Feminism," 2013).
+
+# References {#references .unnumbered}
+
+::::: {#refs .references .csl-bib-body .hanging-indent entry-spacing="0" line-spacing="2"}
+::: {#ref-Feminism2011ces .csl-entry}
+Communities. (2011, August 14). In *Geek Feminism*. Retrieved from
+<http://geekfeminism.wikia.com/wiki/Category:Communities>
+:::
+
+::: {#ref-Feminism2013gf .csl-entry}
+Geek Feminism. (2013, April 10). *Geek Feminism*. Retrieved April 10,
+2013, from <http://geekfeminism.wikia.com/wiki/Geek_Feminism>
+:::
+:::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-160.md b/documents/markdown/pandoc-md/pandoc-citeproc-160.md
new file mode 100644
index 0000000..56e2f96
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-160.md
@@ -0,0 +1,44 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: command/issue160.csl
+references:
+- author:
+ - family: Doe
+ given: Jane
+ citation-label: Jane11
+ id: item1
+ issued:
+ year: 2011
+ title: A book
+ type: book
+---
+
+No citation-label
+-----------------
+
+Foo [@item1].
+
+Expected
+--------
+
+> Foo \[Jane11\].
+>
+> \[Jane11\] Jane Doe. A book. 2011.
+^D
+## No citation-label
+
+Foo \[Jane11\].
+
+## Expected
+
+> Foo \[Jane11\].
+>
+> \[Jane11\] Jane Doe. A book. 2011.
+
+:::: {#refs .references .csl-bib-body}
+::: {#ref-item1 .csl-entry}
+\[Jane11\] Jane Doe. A book. 2011.
+:::
+::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-175.md b/documents/markdown/pandoc-md/pandoc-citeproc-175.md
new file mode 100644
index 0000000..552d24c
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-175.md
@@ -0,0 +1,43 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+references:
+- author:
+ - family: Doe
+ given: Jane
+ container-title: A magazine
+ id: item1
+ issued:
+ - month: 1
+ year: 2011
+ - month: 2
+ year: 2011
+ page: '33-44'
+ title: A title
+ type: 'article-magazine'
+---
+
+Missing en-dash between months
+------------------------------
+
+Foo [@item1].
+
+Expected
+--------
+
+> Doe, Jane. 2011. "A Title." *A Magazine*, January--February.
+^D
+## Missing en-dash between months
+
+Foo (Doe 2011).
+
+## Expected
+
+> Doe, Jane. 2011. "A Title." *A Magazine*, January--February.
+
+:::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-item1 .csl-entry}
+Doe, Jane. 2011. "A Title." *A Magazine*, January--February, 33--44.
+:::
+::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-197.md b/documents/markdown/pandoc-md/pandoc-citeproc-197.md
new file mode 100644
index 0000000..6461c26
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-197.md
@@ -0,0 +1,31 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: 'command/chicago-fullnote-bibliography.csl'
+nocite: '@test'
+references:
+- editor:
+ - family: Abelard
+ given: Peter
+ id: test
+ issued:
+ date-parts:
+ - - 1989
+ publisher: Clarendon Press
+ publisher-place: Oxford
+ title: Test
+ type: book
+---
+
+This is a test [@test].
+^D
+This is a test.[^1]
+
+:::: {#refs .references .csl-bib-body .hanging-indent entry-spacing="0"}
+::: {#ref-test .csl-entry}
+Abelard, Peter, ed. *Test*. Oxford: Clarendon Press, 1989.
+:::
+::::
+
+[^1]: Peter Abelard, ed., *Test* (Oxford: Clarendon Press, 1989).
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-213.md b/documents/markdown/pandoc-md/pandoc-citeproc-213.md
new file mode 100644
index 0000000..53fd0bb
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-213.md
@@ -0,0 +1,33 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: 'command/harvard-university-of-kent.csl'
+references:
+- author:
+ - family: Doe
+ given: Ann
+ collection-title: The collection title
+ dimensions: 789 pp.
+ id: doe1
+ issued:
+ - year: 1999
+ publisher: The publisher
+ title: Title
+ type: book
+---
+
+Foo [@doe1].
+
+References {#references .unnumbered}
+==========
+^D
+Foo (Doe 1999).
+
+# References {#references .unnumbered}
+
+:::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-doe1 .csl-entry}
+Doe, A. (1999). *Title*. The collection title. The publisher. 789 pp.
+:::
+::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-25.md b/documents/markdown/pandoc-md/pandoc-citeproc-25.md
new file mode 100644
index 0000000..1e49f4f
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-25.md
@@ -0,0 +1,30 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+references:
+- author:
+ - family: Author
+ given: Al
+ id: item1
+ issued:
+ date-parts:
+ - - 1998
+ title: 'foo bar baz: bazbaz foo'
+ type: 'article-journal'
+---
+
+Foo [@item1].
+
+References {#references .unnumbered}
+==========
+^D
+Foo (Author 1998).
+
+# References {#references .unnumbered}
+
+:::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-item1 .csl-entry}
+Author, Al. 1998. *Foo Bar Baz: Bazbaz Foo*.
+:::
+::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-250.md b/documents/markdown/pandoc-md/pandoc-citeproc-250.md
new file mode 100644
index 0000000..77dc335
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-250.md
@@ -0,0 +1,21 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+link-citations: true
+references:
+- author:
+ family: Doe
+ id: doe
+ title: Title
+---
+
+[@doe]
+^D
+([Doe, n.d.](#ref-doe))
+
+:::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-doe .csl-entry}
+Doe. n.d. *Title*.
+:::
+::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-27.md b/documents/markdown/pandoc-md/pandoc-citeproc-27.md
new file mode 100644
index 0000000..f7cdde0
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-27.md
@@ -0,0 +1,38 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: command/science.csl
+references:
+- author:
+ - family: AuthorOne
+ given: Joe
+ - family: AuthorTwo
+ given: Jill
+ container-title: Some Journal
+ id: AuthorOne2014
+ issue: X
+ issued:
+ date-parts:
+ - - 2014
+ page: 'XXXX-YYYY'
+ title: Sample Title
+ type: 'article-journal'
+ volume: XX
+---
+
+Minimal example
+===============
+
+Here is some text that needs a citation [@AuthorOne2014].
+^D
+# Minimal example
+
+Here is some text that needs a citation (*1*).
+
+:::: {#refs .references .csl-bib-body}
+::: {#ref-AuthorOne2014 .csl-entry}
+[1. ]{.csl-left-margin}[J. AuthorOne, J. AuthorTwo, *Some Journal*, in
+press.]{.csl-right-inline}
+:::
+::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-292.md b/documents/markdown/pandoc-md/pandoc-citeproc-292.md
new file mode 100644
index 0000000..eab63db
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-292.md
@@ -0,0 +1,43 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: 'command/sage-harvard.csl'
+references:
+- author:
+ family: Doe
+ id: doe
+ issued:
+ year: 2007
+ type: article
+- author:
+ family: Zoe
+ id: zoe
+ issued:
+ - year: 2009
+ type: article
+- author:
+ family: Roe
+ id: roe
+ issued:
+ - year: 2007
+ type: article
+---
+
+[@zoe; @roe; see for comparison @doe, p. 3]
+^D
+(Roe, 2007; Zoe, 2009; see for comparison Doe, 2007: 3)
+
+:::::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-doe .csl-entry}
+Doe (2007).
+:::
+
+::: {#ref-roe .csl-entry}
+Roe (2007).
+:::
+
+::: {#ref-zoe .csl-entry}
+Zoe (2009).
+:::
+::::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-301.md b/documents/markdown/pandoc-md/pandoc-citeproc-301.md
new file mode 100644
index 0000000..128431f
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-301.md
@@ -0,0 +1,25 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+references:
+- id: test
+ title: Essays presented to N.R. Ker (On Art)
+- id: test2
+ title: '*Test:* An experiment: An abridgement'
+---
+
+@test; @test2
+^D
+*Essays Presented to N.R. Ker (On Art)* (n.d.); **Test:* An Experiment:
+An Abridgement* (n.d.)
+
+::::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-test .csl-entry}
+*Essays Presented to N.R. Ker (On Art)*. n.d.
+:::
+
+::: {#ref-test2 .csl-entry}
+**Test:* An Experiment: An Abridgement*. n.d.
+:::
+:::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-307.md b/documents/markdown/pandoc-md/pandoc-citeproc-307.md
new file mode 100644
index 0000000..de595a2
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-307.md
@@ -0,0 +1,31 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+lang: 'fr-FR'
+references:
+- author:
+ - family: Bazin
+ given: André
+ container-title: Cahiers du cinéma
+ id: bazin_cybernetique_1954
+ issue: 36
+ issued:
+ date-parts:
+ - - 1954
+ - 6
+ page: '22-27'
+ title: 'La Cybernétique d''André Cayatte'
+ type: 'article-journal'
+---
+
+Bonjour[@bazin_cybernetique_1954] !
+^D
+Bonjour(Bazin 1954) !
+
+:::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-bazin_cybernetique_1954 .csl-entry}
+Bazin, André. 1954. « La Cybernétique d'André Cayatte ». *Cahiers du
+cinéma*, nᵒ 36 (juin): 22‑27.
+:::
+::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-31.md b/documents/markdown/pandoc-md/pandoc-citeproc-31.md
new file mode 100644
index 0000000..28ca474
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-31.md
@@ -0,0 +1,49 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: command/oscola.csl
+references:
+- DOI: 10.1086/504343
+ author:
+ - family: Olson
+ given: Hope A.
+ container-title: Library Quarterly
+ id: item1
+ issue: 1
+ issued:
+ date-parts:
+ - - 2006
+ page: '19-35'
+ title: 'Codes, costs, and critiques: The organization of information
+ in *Library Quarterly*, 1931--2004'
+ title-short: 'Codes, costs, and critiques'
+ type: 'article-magazine'
+ volume: 76
+- id: item2
+ title: Second title
+---
+
+Foo [@item1]. Bar [@item2]. Baz [@item1].
+^D
+Foo.[^1] Bar.[^2] Baz.[^3]
+
+::::: {#refs .references .csl-bib-body}
+::: {#ref-item1 .csl-entry}
+Olson HA, '[Codes, Costs, and Critiques: The Organization of Information
+in *Library Quarterly*, 1931--2004](https://doi.org/10.1086/504343)'
+(2006) 76 *Library Quarterly* 19
+:::
+
+::: {#ref-item2 .csl-entry}
+'Second Title'
+:::
+:::::
+
+[^1]: Hope A Olson, 'Codes, Costs, and Critiques: The Organization of
+ Information in *Library Quarterly*, 1931--2004' (2006) 76 *Library
+ Quarterly* 19.
+
+[^2]: 'Second Title'.
+
+[^3]: Olson (n 1).
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-312.md b/documents/markdown/pandoc-md/pandoc-citeproc-312.md
new file mode 100644
index 0000000..fdd2f20
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-312.md
@@ -0,0 +1,171 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: command/apa.csl
+nocite: '@*'
+references:
+- author:
+ - literal: NN
+ id: 'Y'
+ issued:
+ - year: 1950
+ title: 'Date: Year'
+ title-short: Date
+ type: webpage
+- author:
+ - literal: NN
+ id: Y/Y
+ issued:
+ - year: 1951
+ - year: 1952
+ title: 'Date range: Year'
+ title-short: Date range
+ type: webpage
+- author:
+ - literal: NN
+ id: YM
+ issued:
+ - month: 1
+ year: 1953
+ title: 'Date: Year+month'
+ title-short: Date
+ type: webpage
+- author:
+ - literal: NN
+ id: YM/YM
+ issued:
+ - month: 1
+ year: 1954
+ - month: 2
+ year: 1955
+ title: 'Date range: Year+month'
+ title-short: Date range
+ type: webpage
+- author:
+ - literal: NN
+ id: YM/YM_same
+ issued:
+ - month: 1
+ year: 1956
+ - month: 2
+ year: 1956
+ title: 'Date range: Year+month, same year'
+ title-short: Date range
+ type: webpage
+- author:
+ - literal: NN
+ id: YMD
+ issued:
+ - day: 15
+ month: 1
+ year: 1958
+ title: 'Date: Year+month+day'
+ title-short: Date
+ type: webpage
+- author:
+ - literal: NN
+ id: YMD/YMD
+ issued:
+ - day: 15
+ month: 1
+ year: 1959
+ - day: 16
+ month: 2
+ year: 1960
+ title: 'Date range: Year+month+day'
+ title-short: Date range
+ type: webpage
+- author:
+ - literal: NN
+ id: YMD/YMD_same
+ issued:
+ - day: 15
+ month: 1
+ year: 1961
+ - day: 16
+ month: 1
+ year: 1962
+ title: 'Date range: Year+month+day, same month'
+ title-short: Date range
+ type: webpage
+- author:
+ - literal: NN
+ id: YS
+ issued:
+ - season: 3
+ year: 1963
+ title: 'Date: Year+season'
+ title-short: Date
+ type: webpage
+- author:
+ - literal: NN
+ id: YS/YS
+ issued:
+ - season: 1
+ year: 1964
+ - season: 4
+ year: 1965
+ title: 'Date range: Year+season'
+ title-short: Date range
+ type: webpage
+- author:
+ - literal: NN
+ id: YS/YS_same
+ issued:
+ - season: 2
+ year: 1966
+ - season: 4
+ year: 1966
+ title: 'Date range: Year+season, same year'
+ title-short: Date range
+ type: webpage
+---
+
+^D
+:::::::::::::: {#refs .references .csl-bib-body .hanging-indent entry-spacing="0" line-spacing="2"}
+::: {#ref-Y .csl-entry}
+NN. (1950). Date: Year.
+:::
+
+::: {#ref-Y/Y .csl-entry}
+NN. (1951--1952). Date range: Year.
+:::
+
+::: {#ref-YM .csl-entry}
+NN. (1953, January). Date: Year+month.
+:::
+
+::: {#ref-YM/YM .csl-entry}
+NN. (1954--1955, January--February). Date range: Year+month.
+:::
+
+::: {#ref-YM/YM_same .csl-entry}
+NN. (1956, January--February). Date range: Year+month, same year.
+:::
+
+::: {#ref-YMD .csl-entry}
+NN. (1958, January 15). Date: Year+month+day.
+:::
+
+::: {#ref-YMD/YMD .csl-entry}
+NN. (1959--1960, January 15--February 16). Date range: Year+month+day.
+:::
+
+::: {#ref-YMD/YMD_same .csl-entry}
+NN. (1961--1962, January 15--16). Date range: Year+month+day, same
+month.
+:::
+
+::: {#ref-YS .csl-entry}
+NN. (1963, Autumn). Date: Year+season.
+:::
+
+::: {#ref-YS/YS .csl-entry}
+NN. (1964--1965, Spring--Winter). Date range: Year+season.
+:::
+
+::: {#ref-YS/YS_same .csl-entry}
+NN. (1966, Summer--Winter). Date range: Year+season, same year.
+:::
+::::::::::::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-320.md b/documents/markdown/pandoc-md/pandoc-citeproc-320.md
new file mode 100644
index 0000000..66dbcea
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-320.md
@@ -0,0 +1,254 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: command/apa.csl
+references:
+- author:
+ - family: Benjamin
+ given: A. S.
+ id: itemA1
+- author:
+ - family: Yaakov
+ given: D.
+ non-dropping-particle: ben
+ id: itemA2
+- author:
+ - family: Brown
+ given: J. R.
+ id: itemA3
+- author:
+ - family: Browning
+ given: A. R.
+ id: itemA4
+- author:
+ - family: Girard
+ given: 'J.-B.'
+ id: itemA5
+- author:
+ - family: 'Girard-Perregaux'
+ given: A. S.
+ id: itemA6
+- author:
+ - family: Ibn Abdulaziz
+ given: T.
+ id: itemA7
+- author:
+ - family: Ibn Nidal
+ given: A. K. M.
+ id: itemA8
+- author:
+ - family: López
+ given: M. E.
+ id: itemA9
+- author:
+ - family: López de Molina
+ given: G.
+ id: itemA10
+- author:
+ - family: Singh
+ given: Y.
+ id: itemA11
+- author:
+ - family: Singh Siddhu
+ given: N.
+ id: itemA12
+- author:
+ - family: Villafuerte
+ given: S. A.
+ id: itemA13
+- author:
+ - family: 'Villa-Lobos'
+ given: J.
+ id: itemA14
+- author:
+ - family: Macalister
+ given: Donald
+ id: itemB1
+- author:
+ - family: MacAlister
+ given: Paul
+ id: itemB2
+- author:
+ - family: Macauley
+ given: Catharine
+ id: itemB3
+- author:
+ - family: Macmillan
+ given: Harold
+ id: itemB4
+- author:
+ - family: Madison
+ given: James
+ id: itemB5
+- author:
+ - family: McAllister
+ given: Ward
+ id: itemB6
+- author:
+ - family: McAuley
+ given: Catherine
+ id: itemB7
+- author:
+ - family: McMillan
+ given: Edwin M.
+ id: itemB8
+- author:
+ - family: 'Sainte-Beuve'
+ given: 'Charles-Augustin'
+ id: itemC1
+- author:
+ - family: 'Saint-Gaudens'
+ given: Augustus
+ id: itemC2
+- author:
+ - family: 'Saint-Saëns'
+ given: Camille
+ id: itemC3
+- author:
+ - dropping-particle: de
+ family: San Martin
+ given: José
+ id: itemC4
+- author:
+ - family: St. Denis
+ given: Ruth
+ id: itemC5
+- author:
+ - family: St. Laurent
+ given: Louis Stephen
+ id: itemC6
+---
+
+Foo
+[@itemA1; @itemA2; @itemA3; @itemA4; @itemA5; @itemA6; @itemA7; @itemA8; @itemA9; @itemA10; @itemA11; @itemA12; @itemA13; @itemA14].
+
+Foo
+[@itemB1; @itemB2; @itemB3; @itemB4; @itemB5; @itemB6; @itemB7; @itemB8].
+
+Foo [@itemC1; @itemC2; @itemC3; @itemC4; @itemC5; @itemC6].
+^D
+Foo (ben Yaakov, n.d.; Benjamin, n.d.; Brown, n.d.; Browning, n.d.;
+Girard, n.d.; Girard-Perregaux, n.d.; Ibn Abdulaziz, n.d.; Ibn Nidal,
+n.d.; López de Molina, n.d.; López, n.d.; Singh Siddhu, n.d.; Singh,
+n.d.; Villafuerte, n.d.; Villa-Lobos, n.d.).
+
+Foo (Macalister, n.d.; MacAlister, n.d.; Macauley, n.d.; Macmillan,
+n.d.; Madison, n.d.; McAllister, n.d.; McAuley, n.d.; McMillan, n.d.).
+
+Foo (Sainte-Beuve, n.d.; Saint-Gaudens, n.d.; Saint-Saëns, n.d.; San
+Martin, n.d.; St. Denis, n.d.; St. Laurent, n.d.).
+
+::::::::::::::::::::::::::::::: {#refs .references .csl-bib-body .hanging-indent entry-spacing="0" line-spacing="2"}
+::: {#ref-itemA2 .csl-entry}
+ben Yaakov, D. (n.d.).
+:::
+
+::: {#ref-itemA1 .csl-entry}
+Benjamin, A. S. (n.d.).
+:::
+
+::: {#ref-itemA3 .csl-entry}
+Brown, J. R. (n.d.).
+:::
+
+::: {#ref-itemA4 .csl-entry}
+Browning, A. R. (n.d.).
+:::
+
+::: {#ref-itemA5 .csl-entry}
+Girard, J.-B. (n.d.).
+:::
+
+::: {#ref-itemA6 .csl-entry}
+Girard-Perregaux, A. S. (n.d.).
+:::
+
+::: {#ref-itemA7 .csl-entry}
+Ibn Abdulaziz, T. (n.d.).
+:::
+
+::: {#ref-itemA8 .csl-entry}
+Ibn Nidal, A. K. M. (n.d.).
+:::
+
+::: {#ref-itemA10 .csl-entry}
+López de Molina, G. (n.d.).
+:::
+
+::: {#ref-itemA9 .csl-entry}
+López, M. E. (n.d.).
+:::
+
+::: {#ref-itemB1 .csl-entry}
+Macalister, D. (n.d.).
+:::
+
+::: {#ref-itemB2 .csl-entry}
+MacAlister, P. (n.d.).
+:::
+
+::: {#ref-itemB3 .csl-entry}
+Macauley, C. (n.d.).
+:::
+
+::: {#ref-itemB4 .csl-entry}
+Macmillan, H. (n.d.).
+:::
+
+::: {#ref-itemB5 .csl-entry}
+Madison, J. (n.d.).
+:::
+
+::: {#ref-itemB6 .csl-entry}
+McAllister, W. (n.d.).
+:::
+
+::: {#ref-itemB7 .csl-entry}
+McAuley, C. (n.d.).
+:::
+
+::: {#ref-itemB8 .csl-entry}
+McMillan, E. M. (n.d.).
+:::
+
+::: {#ref-itemC1 .csl-entry}
+Sainte-Beuve, C.-A. (n.d.).
+:::
+
+::: {#ref-itemC2 .csl-entry}
+Saint-Gaudens, A. (n.d.).
+:::
+
+::: {#ref-itemC3 .csl-entry}
+Saint-Saëns, C. (n.d.).
+:::
+
+::: {#ref-itemC4 .csl-entry}
+San Martin, J. de. (n.d.).
+:::
+
+::: {#ref-itemA12 .csl-entry}
+Singh Siddhu, N. (n.d.).
+:::
+
+::: {#ref-itemA11 .csl-entry}
+Singh, Y. (n.d.).
+:::
+
+::: {#ref-itemC5 .csl-entry}
+St. Denis, R. (n.d.).
+:::
+
+::: {#ref-itemC6 .csl-entry}
+St. Laurent, L. S. (n.d.).
+:::
+
+::: {#ref-itemA13 .csl-entry}
+Villafuerte, S. A. (n.d.).
+:::
+
+::: {#ref-itemA14 .csl-entry}
+Villa-Lobos, J. (n.d.).
+:::
+:::::::::::::::::::::::::::::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-320a.md b/documents/markdown/pandoc-md/pandoc-citeproc-320a.md
new file mode 100644
index 0000000..95378ea
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-320a.md
@@ -0,0 +1,80 @@
+```
+% pandoc --citeproc -t plain
+---
+references:
+- author:
+ - family: ʾUdhrī
+ given: Jamīl
+ non-dropping-particle: 'al-'
+ issued: 2000
+ title: hamza
+ id: item1
+- author:
+ - family: ʿUdhrī
+ given: Jamīl
+ non-dropping-particle: 'al-'
+ issued: 2000
+ title: ayn
+ id: item2
+- author:
+ - family: "'Udhrī"
+ given: Jamīl
+ non-dropping-particle: 'al-'
+ issued: 2000
+ title: straight apostrophe
+ id: item3
+- author:
+ - family: '‘Udhrī'
+ given: Jamīl
+ non-dropping-particle: 'al-'
+ issued: 2000
+ title: inverted curly apostrophe = opening single curly quote (for ayn)
+ id: item4
+- author:
+ - family: '’Udhrī'
+ given: Jamīl
+ non-dropping-particle: 'al-'
+ issued: 2000
+ title: curly apostrophe = closing single curly quote (for hamza)
+ id: item5
+- author:
+ - family: Uch
+ given: Ann
+ id: item6
+ issued: 2000
+- author:
+ - family: Uebel
+ given: Joe
+ id: item7
+ issued: 2000
+- author:
+ - family: Zzz
+ given: Zoe
+ id: item8
+ issued: 2000
+---
+
+Foo [@item1; @item2; @item3; @item4; @item5; @item6; @item7; @item8].
+^D
+Foo (al-ʾUdhrī 2000; al-ʿUdhrī 2000; al-’Udhrī 2000b, 2000a; al-‘Udhrī
+2000; Uch 2000; Uebel 2000; Zzz 2000).
+
+Uch, Ann. 2000.
+
+‘Udhrī, Jamīl al-. 2000. Inverted Curly Apostrophe = Opening Single
+Curly Quote (for Ayn).
+
+ʿUdhrī, Jamīl al-. 2000. Ayn.
+
+’Udhrī, Jamīl al-. 2000a. Curly Apostrophe = Closing Single Curly Quote
+(for Hamza).
+
+ʾUdhrī, Jamīl al-. 2000. Hamza.
+
+’Udhrī, Jamīl al-. 2000b. Straight Apostrophe.
+
+Uebel, Joe. 2000.
+
+Zzz, Zoe. 2000.
+
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-322.md b/documents/markdown/pandoc-md/pandoc-citeproc-322.md
new file mode 100644
index 0000000..8c02450
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-322.md
@@ -0,0 +1,35 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: command/annales.csl
+references:
+- author:
+ - family: Timmory
+ given: François
+ container-title: 'L''Écran français'
+ id: timmory\_\_justice_1950
+ issue: 272
+ issued:
+ - day: 25
+ month: 9
+ year: 1950
+ language: 'fr-FR'
+ page: 12
+ title: '*Justice est faite* : soyons justes'
+ type: 'article-journal'
+---
+
+Foo [@timmory__justice_1950].
+^D
+Foo.[^1]
+
+:::: {#refs .references .csl-bib-body}
+::: {#ref-timmory__justice_1950 .csl-entry}
+François [Timmory]{.smallcaps}, « *Justice est faite* : soyons justes »,
+*L'Écran français*, 1950, nᵒ 272, p. 12.
+:::
+::::
+
+[^1]: François [Timmory]{.smallcaps}, « *Justice est faite* : soyons
+ justes », *L'Écran français*, 1950, nᵒ 272, p. 12.
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-325.md b/documents/markdown/pandoc-md/pandoc-citeproc-325.md
new file mode 100644
index 0000000..1516298
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-325.md
@@ -0,0 +1,30 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+references:
+- author:
+ - family: Smith
+ given: John
+ id: item1
+ type: book
+- author:
+ - family: Smith
+ given: John
+ id: item2
+ type: book
+---
+
+[@item1; @item2]
+^D
+(Smith, n.d.-a, n.d.-b)
+
+::::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-item1 .csl-entry}
+Smith, John. n.d.-a.
+:::
+
+::: {#ref-item2 .csl-entry}
+Smith, John. n.d.-b.
+:::
+:::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-327.md b/documents/markdown/pandoc-md/pandoc-citeproc-327.md
new file mode 100644
index 0000000..6678a16
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-327.md
@@ -0,0 +1,51 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: 'command/chinese-gb7714-2005-numeric.csl'
+references:
+- ISSN: '1003-1111'
+ URL: 'http://kns.cnki.net/kns/detail/detail.aspx?QueryID=4&CurRec=4&recid=&FileName=CHAN201706006&DbName=CJFDLAST2018&DbCode=CJFQ&yx=Y&pr=&URLID=21.1110.S.20171129.1725.006'
+ abstract: '为了解辽东湾海域底栖动物次级生产力水平和时空分布特点,根据2007年的4月和10月辽东湾海域大型底栖动物调查数据,运用Brey经验公式计算大型底栖动物次级生产力和P/B值,并结合海洋生物指数方法对辽东湾海域进行生境适宜性评价。分析结果表明,该海域大型底栖动物年平均次级生产力为5.59g/(m\~2·年),年平均P/B值为3.16,辽东湾大型底栖动物次级生产力空间分布呈现出自沿岸向中部递增的趋势,P/B值空间分布与底栖动物次级生产力相反,呈现出自沿岸向中部递减的趋势,群落组成中以个体小、生活史短、代谢快的底栖动物为主。'
+ accessed:
+ - day: 27
+ month: 3
+ year: 2018
+ author:
+ - family: 李
+ given: 轶平
+ - family: 于
+ given: 旭光
+ - family: 孙
+ given: 明
+ - family: 郭
+ given: 栋
+ - family: 段
+ given: 妍
+ - family: 董
+ given: 婧
+ container-title: 水产科学
+ id: LiLiaoDongWanHaiYuDiQiDongWuCiJiShengChanLiYanJiuJiShengJingGuaYiXingPingJie2017
+ issue: 06
+ issued:
+ - year: 2017
+ keyword: '次级生产力,大型底栖动物,海洋生物指数方法,AMBI,macrozoobenthos,P/B
+ value,P/B值,secondary productivity'
+ language: 中文;
+ page: '728-734'
+ title: 辽东湾海域底栖动物次级生产力研究及生境适宜性评价
+ type: 'article-journal'
+---
+
+I referenced something here
+[@LiLiaoDongWanHaiYuDiQiDongWuCiJiShengChanLiYanJiuJiShengJingGuaYiXingPingJie2017]
+^D
+I referenced something here^\[1\]^
+
+:::: {#refs .references .csl-bib-body entry-spacing="0"}
+::: {#ref-LiLiaoDongWanHaiYuDiQiDongWuCiJiShengChanLiYanJiuJiShengJingGuaYiXingPingJie2017 .csl-entry}
+[\[1\] ]{.csl-left-margin}[李轶平, 于旭光, 孙明, 等.
+[辽东湾海域底栖动物次级生产力研究及生境适宜性评价](http://kns.cnki.net/kns/detail/detail.aspx?QueryID=4&CurRec=4&recid=&FileName=CHAN201706006&DbName=CJFDLAST2018&DbCode=CJFQ&yx=Y&pr=&URLID=21.1110.S.20171129.1725.006)\[J\].
+水产科学, 2017(6): 728～734.]{.csl-right-inline}
+:::
+::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-338.md b/documents/markdown/pandoc-md/pandoc-citeproc-338.md
new file mode 100644
index 0000000..e153493
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-338.md
@@ -0,0 +1,34 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: 'command/din-1505-2.csl'
+lang: de
+nocite: '@*'
+pagetitle: Citation
+references:
+- ISBN: '978-3-642-32078-1'
+ author:
+ - family: Wolfinger
+ given: Christine
+ edition: '11., vollst. überarb. Aufl.'
+ id: 'item-1'
+ issued:
+ - year: 2013
+ keyword: UNIX; LINUX
+ number-of-pages: 'XVIII, 529 S. : Ill., graph. Darst.'
+ publisher: Springer Vieweg
+ publisher-place: 'Berlin \[u.a.\]'
+ title: 'Keine Angst vor Linux, Unix: ein Lehrbuch für Linux- und
+ Unix-Anwender'
+ type: book
+---
+
+^D
+:::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-item-1 .csl-entry}
+[Wolfinger, Christine]{.smallcaps}: *Keine Angst vor Linux, Unix: ein
+Lehrbuch für Linux- und Unix-Anwender*. 11., vollst. überarb. Aufl.
+Aufl. Berlin \[u.a.\] : Springer Vieweg, 2013 --- ISBN 978-3-642-32078-1
+:::
+::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-351.md b/documents/markdown/pandoc-md/pandoc-citeproc-351.md
new file mode 100644
index 0000000..7458273
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-351.md
@@ -0,0 +1,27 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: 'command/zeitschrift-fur-kunstgeschichte.csl'
+references:
+- editor:
+ - family: Nietzsche
+ given: Friedrich
+ id: Nie72
+ issued:
+ - year: 1872
+ title: Die geburt
+ type: book
+---
+
+@Nie72
+^D
+Friedrich Nietzsche (ed.)[^1]
+
+:::: {#refs .references .csl-bib-body .hanging-indent entry-spacing="0"}
+::: {#ref-Nie72 .csl-entry}
+Nietzsche, Friedrich (ed.), *Die geburt*, 1872.
+:::
+::::
+
+[^1]: *Die geburt*, 1872.
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-356.md b/documents/markdown/pandoc-md/pandoc-citeproc-356.md
new file mode 100644
index 0000000..112564f
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-356.md
@@ -0,0 +1,20 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+references:
+- author:
+ - family: Alice
+ id: foo
+ issued:
+ - year: 2042
+ other-ids:
+ - bar
+ - doz
+ type: book
+---
+
+[@bar]
+^D
+2> [WARNING] Citeproc: citation bar not found
+(**bar?**)
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-360.md b/documents/markdown/pandoc-md/pandoc-citeproc-360.md
new file mode 100644
index 0000000..a16a819
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-360.md
@@ -0,0 +1,35 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: 'command/chicago-fullnote-bibliography.csl'
+references:
+- author:
+ - family: 'L''Estrange'
+ given: Michael
+ - family: Merchant
+ given: Stephen
+ id: lestrange2017
+ issued:
+ - day: 18
+ month: 7
+ year: 2017
+ language: 'en-US'
+ title: 2017 Independent Intelligence Review
+ title-short: Independent Intelligence Review
+ type: report
+---
+
+[@lestrange2017]
+^D
+[^1]
+
+:::: {#refs .references .csl-bib-body .hanging-indent entry-spacing="0"}
+::: {#ref-lestrange2017 .csl-entry}
+L'Estrange, Michael, and Stephen Merchant. "2017 Independent
+Intelligence Review," July 18, 2017.
+:::
+::::
+
+[^1]: Michael L'Estrange and Stephen Merchant, "2017 Independent
+ Intelligence Review," July 18, 2017.
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-361.md b/documents/markdown/pandoc-md/pandoc-citeproc-361.md
new file mode 100644
index 0000000..d187ffc
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-361.md
@@ -0,0 +1,80 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: command/locators.csl
+references:
+- id: citekey
+ title: Title
+ type: 'article-journal'
+- id: other
+ title: Other
+ type: 'article-journal'
+suppress-bibliography: true
+---
+
+Content[@citekey]
+
+Content[@citekey, 1]
+
+Content[@citekey, 2]
+
+Content[@citekey, 2]
+
+Content[@citekey 2]
+
+Content[@citekey, p. 2]
+
+Content[@citekey p. 2]
+
+Content[@citekey]
+
+Content[@other]
+
+Content[@citekey, 3]
+
+Content[@citekey, 3]
+^D
+Content[^1]
+
+Content[^2]
+
+Content[^3]
+
+Content[^4]
+
+Content[^5]
+
+Content[^6]
+
+Content[^7]
+
+Content[^8]
+
+Content[^9]
+
+Content[^10]
+
+Content[^11]
+
+[^1]: Title.
+
+[^2]: Ibid-with-locator {1}.
+
+[^3]: Ibid-with-locator {2}.
+
+[^4]: Ibid.
+
+[^5]: Ibid.
+
+[^6]: Ibid.
+
+[^7]: Ibid.
+
+[^8]: Subsequent.
+
+[^9]: Other.
+
+[^10]: Subsequent {3}.
+
+[^11]: Ibid.
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-365.md b/documents/markdown/pandoc-md/pandoc-citeproc-365.md
new file mode 100644
index 0000000..12c3a60
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-365.md
@@ -0,0 +1,39 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: 'command/le-tapuscrit-note.csl'
+references:
+- ISBN: '978-2-912573-52-0'
+ author:
+ - family: Le Gras
+ given: Gwénaëlle
+ call-number: 'Tolbiac - Rez de Jardin - Littérature et art - Magasin -
+ 2010-82178'
+ collection-title: 'Jeux d''acteurs'
+ id: legras_michel_2010
+ issued:
+ - year: 2010
+ language: fre
+ number-of-pages: 128
+ publisher: Scope
+ publisher-place: Paris
+ source: 'BnF Catalogue général (http://catalogue.bnf.fr)'
+ title: 'Michel Simon : l''art de la disgrâce'
+ title-short: Michel Simon
+ type: book
+---
+
+Foo [@legras_michel_2010].
+^D
+Foo.[^1]
+
+:::: {#refs .references .csl-bib-body}
+::: {#ref-legras_michel_2010 .csl-entry}
+[Le Gras]{.smallcaps} Gwénaëlle, *Michel Simon : l'art de la disgrâce*,
+Paris, Scope (coll. « Jeux d'acteurs »), 2010, 128 p.
+:::
+::::
+
+[^1]: Gwénaëlle Le Gras, *Michel Simon : l'art de la disgrâce*, Paris,
+ Scope, 2010, 128 p.
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-371.md b/documents/markdown/pandoc-md/pandoc-citeproc-371.md
new file mode 100644
index 0000000..0c8a282
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-371.md
@@ -0,0 +1,40 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+references:
+- author:
+ - family: Doe
+ given: Jane
+ id: item1
+ status: in press
+ title: Title one
+ type: book
+- author:
+ - family: Doe
+ given: Jane
+ id: item2
+ issued:
+ - year: 2018
+ title: Title two
+ type: book
+---
+
+Foo [@item2; @item1].
+
+References {#references .unnumbered}
+==========
+^D
+Foo (Doe 2018, in press).
+
+# References {#references .unnumbered}
+
+::::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-item2 .csl-entry}
+Doe, Jane. 2018. *Title Two*.
+:::
+
+::: {#ref-item1 .csl-entry}
+Doe, Jane. In press. *Title One*.
+:::
+:::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-38.md b/documents/markdown/pandoc-md/pandoc-citeproc-38.md
new file mode 100644
index 0000000..1c5a773
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-38.md
@@ -0,0 +1,29 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+references:
+- author:
+ - family: Doe
+ given: Ann
+ - family: Doe
+ given: Ben
+ - family: Roe
+ given: Ron
+ id: a
+ issued:
+ date-parts:
+ - - 2007
+ title: Title
+ type: 'article-journal'
+---
+
+@a
+^D
+Doe et al. (2007)
+
+:::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-a .csl-entry}
+Doe, Ann, Ben Doe, and Ron Roe. 2007. *Title*.
+:::
+::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-386.md b/documents/markdown/pandoc-md/pandoc-citeproc-386.md
new file mode 100644
index 0000000..bac7fa6
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-386.md
@@ -0,0 +1,36 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: 'command/advanced-optical-materials.csl'
+references:
+- DOI: 10.1038/lsa.2012.20
+ ISSN: '2047-7538'
+ author:
+ - family: Ding
+ given: K.
+ - family: Ning
+ given: C. Z.
+ container-title: Light Sci. Appl.
+ id: ding_metallic_2012
+ issue: 7
+ issued:
+ - month: 7
+ year: 2012
+ page: 'e20-e20'
+ title: 'Metallic subwavelength-cavity semiconductor nanolasers'
+ type: 'article-journal'
+ volume: 1
+---
+
+@ding_metallic_2012
+^D
+^\[1\]^
+
+:::: {#refs .references .csl-bib-body entry-spacing="0" line-spacing="2"}
+::: {#ref-ding_metallic_2012 .csl-entry}
+[\[1\] ]{.csl-left-margin}[[K. Ding, C. Z. Ning, *Light Sci. Appl.*
+**2012**, *1*,
+e20](https://doi.org/10.1038/lsa.2012.20).]{.csl-right-inline}
+:::
+::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-392.md b/documents/markdown/pandoc-md/pandoc-citeproc-392.md
new file mode 100644
index 0000000..0c77e76
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-392.md
@@ -0,0 +1,29 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: command/vancouver.csl
+references:
+- author:
+ - family: James
+ given: M.R.C.E.L.
+ id: james
+- author:
+ - family: MacFarlane
+ given: J. G.
+ id: macfarlane
+---
+
+@james; @macfarlane
+^D
+(1); (2)
+
+::::: {#refs .references .csl-bib-body}
+::: {#ref-james .csl-entry}
+[1. ]{.csl-left-margin}[James MRCEL. ]{.csl-right-inline}
+:::
+
+::: {#ref-macfarlane .csl-entry}
+[2. ]{.csl-left-margin}[MacFarlane JG. ]{.csl-right-inline}
+:::
+:::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-399.md b/documents/markdown/pandoc-md/pandoc-citeproc-399.md
new file mode 100644
index 0000000..0c0840c
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-399.md
@@ -0,0 +1,45 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: command/style399.csl
+references:
+- author:
+ - family: One
+ id: one
+- author:
+ - family: Two
+ id: two
+- author:
+ - family: Three
+ id: three
+- author:
+ - family: Four
+ id: four
+- author:
+ - family: Five
+ id: five
+- author:
+ - family: Six
+ id: six
+- author:
+ - family: Seven
+ id: seven
+- author:
+ - family: Eight
+ id: eight
+- author:
+ - family: Nine
+ id: nine
+- author:
+ - family: Ten
+ id: ten
+- author:
+ - family: Eleven
+ id: eleven
+---
+
+Inline citation
+[@one; @two; @three; @four; @five; @six; @seven; @eight; @nine; @ten; @eleven].
+^D
+Inline citation \[1,2,3,4,5,6,7,8,9,10,11\].
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-401.md b/documents/markdown/pandoc-md/pandoc-citeproc-401.md
new file mode 100644
index 0000000..256aaaa
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-401.md
@@ -0,0 +1,59 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+references:
+- id: haslanger2012SocialConstructionDebunking
+ type: chapter
+ author:
+ - family: Haslanger
+ given: Sally
+ issued:
+ - year: 2012
+ original-date:
+ - year: 2003
+ title: 'Social Construction: The ‘Debunking’ Project'
+ title-short: Social Construction
+ container-title: 'Resisting Reality: Social Construction and Social Critique'
+ publisher: Oxford University Press
+ publisher-place: Oxford
+ event-place: Oxford
+ page: 113–138
+ ISBN: 978-0-19-989262-4
+
+- id: haslanger2012FeminismMetaphysicsNegotiating
+ type: chapter
+ author:
+ - family: Haslanger
+ given: Sally
+ issued:
+ - year: 2012
+ original-date:
+ - year: 2000
+ title: 'Feminism in Metaphysics: Negotiating the Natural'
+ container-title: 'Resisting Reality: Social Construction and Social Critique'
+ publisher: Oxford University Press
+ publisher-place: Oxford
+ event-place: Oxford
+ page: 139–157
+ ISBN: 978-0-19-989262-4
+ language: en
+...
+
+Haslanger [-@haslanger2012SocialConstructionDebunking; @haslanger2012FeminismMetaphysicsNegotiating] says...
+^D
+Haslanger (\[2003\] 2012, \[2000\] 2012) says...
+
+::::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-haslanger2012FeminismMetaphysicsNegotiating .csl-entry}
+Haslanger, Sally. (2000) 2012. "Feminism in Metaphysics: Negotiating the
+Natural." In *Resisting Reality: Social Construction and Social
+Critique*. Oxford University Press.
+:::
+
+::: {#ref-haslanger2012SocialConstructionDebunking .csl-entry}
+Haslanger, Sally. (2003) 2012. "Social Construction: The 'Debunking'
+Project." In *Resisting Reality: Social Construction and Social
+Critique*. Oxford University Press.
+:::
+:::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-408.md b/documents/markdown/pandoc-md/pandoc-citeproc-408.md
new file mode 100644
index 0000000..bdf1e1c
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-408.md
@@ -0,0 +1,39 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+references:
+- id: smith1
+ type: article-journal
+ author:
+ - family: Smith
+ given: Mary
+ issued:
+ - year: 2019
+ title: Foo
+
+- id: smithsmith
+ type: article-journal
+ author:
+ - family: Smith
+ given: Mary
+ - family: Smith
+ given: John
+ issued:
+ - year: 2019
+ title: Foo bar
+...
+
+[@smithsmith; @smith1]
+^D
+(Smith and Smith 2019; Smith 2019)
+
+::::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-smith1 .csl-entry}
+Smith, Mary. 2019. *Foo*.
+:::
+
+::: {#ref-smithsmith .csl-entry}
+Smith, Mary, and John Smith. 2019. *Foo Bar*.
+:::
+:::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-416.md b/documents/markdown/pandoc-md/pandoc-citeproc-416.md
new file mode 100644
index 0000000..9cbf755
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-416.md
@@ -0,0 +1,60 @@
+```
+% pandoc --citeproc -t markdown-citations
+Blah blah [@item1; @item2; @item3].
+
+# References {-}
+
+---
+title: The Title
+references:
+- id: item1
+ type: article-newspaper
+ author:
+ - family: Doe
+ given: J.
+ issued:
+ - year: 2010
+ month: 12
+ day: 13
+ title: The title
+- id: item2
+ type: article-newspaper
+ author:
+ - family: Doe
+ given: J.
+ issued:
+ - year: 2007
+ month: 12
+ day: 12
+ - year: 2007
+ month: 12
+ day: 13
+ title: The title
+- id: item3
+ type: article-newspaper
+ author:
+ - family: Doe
+ given: J.
+ issued:
+ - year: 2008
+ title: The title
+...
+^D
+Blah blah (Doe 2010, 2007, 2008).
+
+# References {#references .unnumbered}
+
+:::::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-item2 .csl-entry}
+Doe, J. 2007. *The Title*. December 12--13.
+:::
+
+::: {#ref-item3 .csl-entry}
+Doe, J. 2008. *The Title*.
+:::
+
+::: {#ref-item1 .csl-entry}
+Doe, J. 2010. *The Title*. December 13.
+:::
+::::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-437.md b/documents/markdown/pandoc-md/pandoc-citeproc-437.md
new file mode 100644
index 0000000..91b3cbb
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-437.md
@@ -0,0 +1,23 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: command/issue437.csl
+references:
+- author:
+ - family: Smith
+ given: John
+ id: hirt2009
+ issued:
+ - year: 2009
+ publisher: Publishing House
+ publisher-place: Lausanne
+ title: Some Book
+ type: book
+---
+
+> Here is a quote. [@hirt2009]
+^D
+> Here is a quote.[^1]
+
+[^1]: John Smith, Some Book, Lausanne, 2009
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-47.md b/documents/markdown/pandoc-md/pandoc-citeproc-47.md
new file mode 100644
index 0000000..f5d9eb1
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-47.md
@@ -0,0 +1,112 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+references:
+- author:
+ - family: Doe
+ given: A.
+ id: doe
+ issued:
+ date-parts:
+ - - 2000
+ title: Title
+ type: book
+- author:
+ - family: Doe
+ given: A.
+ - family: Poe
+ given: A.
+ id: doepoe
+ issued:
+ date-parts:
+ - - 2000
+ title: Title
+ type: book
+- editor:
+ - family: Doe
+ given: A.
+ id: 'doe-ed'
+ issued:
+ date-parts:
+ - - 2000
+ title: Title
+ type: book
+- author:
+ - family: Doe
+ given: A.
+ - family: Loe
+ given: A.
+ - family: Toe
+ given: A.
+ id: doeloetoe
+ issued:
+ date-parts:
+ - - 2000
+ title: Title
+ type: book
+---
+
+Foo [@doe]. Bar [@doepoe]. Foo [@doe-ed]. Bar [@doeloetoe].
+
+Expected output:
+
+> Doe, A. 2000a. Title.
+>
+> ---------, ed. 2000b. Title.
+>
+> Doe, A., A. Loe, and A. Toe. 2000. Title.
+>
+> Doe, A., and A. Poe. 2000. Title.
+
+(See CMoS, 16e, 15.16, "Single author versus several authors---reference
+list order": "Successive entries by two or more authors in which only
+the first author's name is the same are alphabetized according to the
+coauthors' last names (regardless of how many coauthors there are)." and
+15.18, "The 3-em dash with edited, translated, or compiled works": "The
+chronological order is maintained, regardless of the added abbreviation.
+\[ed., trans., comp., or whatever\]"
+
+References {#references .unnumbered}
+==========
+^D
+Foo (Doe 2000a). Bar (Doe and Poe 2000). Foo (Doe 2000b). Bar (Doe et
+al. 2000).
+
+Expected output:
+
+> Doe, A. 2000a. Title.
+>
+> ---------, ed. 2000b. Title.
+>
+> Doe, A., A. Loe, and A. Toe. 2000. Title.
+>
+> Doe, A., and A. Poe. 2000. Title.
+
+(See CMoS, 16e, 15.16, "Single author versus several authors---reference
+list order": "Successive entries by two or more authors in which only
+the first author's name is the same are alphabetized according to the
+coauthors' last names (regardless of how many coauthors there are)." and
+15.18, "The 3-em dash with edited, translated, or compiled works": "The
+chronological order is maintained, regardless of the added abbreviation.
+\[ed., trans., comp., or whatever\]"
+
+# References {#references .unnumbered}
+
+::::::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-doe .csl-entry}
+Doe, A. 2000a. *Title*.
+:::
+
+::: {#ref-doe-ed .csl-entry}
+Doe, A., ed. 2000b. *Title*.
+:::
+
+::: {#ref-doeloetoe .csl-entry}
+Doe, A., A. Loe, and A. Toe. 2000. *Title*.
+:::
+
+::: {#ref-doepoe .csl-entry}
+Doe, A., and A. Poe. 2000. *Title*.
+:::
+:::::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-51.md b/documents/markdown/pandoc-md/pandoc-citeproc-51.md
new file mode 100644
index 0000000..61cff71
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-51.md
@@ -0,0 +1,45 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+references:
+- author:
+ - family: Doe
+ given: John
+ container-title: Journal of Something
+ id: item1
+ issued:
+ date-parts:
+ - - 1987
+ - - 1988
+ page: '12-34'
+ title: The title
+ type: 'article-journal'
+ volume: 3
+- author:
+ - family: Roe
+ given: Ron
+ container-title: Journal of Something
+ id: item2
+ issued:
+ date-parts:
+ - - 1987
+ page: '12-34'
+ title: The title
+ type: 'article-journal'
+ volume: 4
+---
+
+@item1; @item2
+^D
+Doe (1987--1988); Roe (1987)
+
+::::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-item1 .csl-entry}
+Doe, John. 1987--1988. "The Title." *Journal of Something* 3: 12--34.
+:::
+
+::: {#ref-item2 .csl-entry}
+Roe, Ron. 1987. "The Title." *Journal of Something* 4: 12--34.
+:::
+:::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-53.md b/documents/markdown/pandoc-md/pandoc-citeproc-53.md
new file mode 100644
index 0000000..41f210c
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-53.md
@@ -0,0 +1,56 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: command/archeologie-medievale.csl
+references:
+- title: Work A
+ id: a
+ issued:
+ date-parts:
+ - - 2000
+ author:
+ - given: John
+ family: Doe
+ type: book
+- title: Work B
+ id: b
+ issued:
+ date-parts:
+ - - 1990
+ author:
+ - given: Jane
+ family: Roe
+ type: book
+---
+@a @a @b @b @a @a @b @b
+^D
+Doe[^1] Doe[^2] Roe[^3] Roe[^4] Doe[^5] Doe[^6] Roe[^7] Roe[^8]
+
+::::: {#refs .references .csl-bib-body}
+::: {#ref-a .csl-entry}
+[[Doe J.]{.smallcaps} ]{.csl-block}
+[2000, *Work A*,.]{.csl-left-margin}
+:::
+
+::: {#ref-b .csl-entry}
+[[Roe J.]{.smallcaps} ]{.csl-block}
+[1990, *Work B*,.]{.csl-left-margin}
+:::
+:::::
+
+[^1]: 2000
+
+[^2]: *Ibid.*
+
+[^3]: 1990
+
+[^4]: *Ibid.*
+
+[^5]: 2000
+
+[^6]: *Ibid.*
+
+[^7]: 1990
+
+[^8]: *Ibid.*
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-57.md b/documents/markdown/pandoc-md/pandoc-citeproc-57.md
new file mode 100644
index 0000000..51cb7ff
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-57.md
@@ -0,0 +1,37 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: 'command/chicago-author-date-with-original-date-and-status.csl'
+references:
+- author:
+ - family: Faraday
+ given: Carry
+ container-title: Seven Trips beyond the Asteroid Belt
+ editor:
+ - family: Oring
+ given: James
+ id: 'Faraday-forthcoming'
+ publisher: Launch Press
+ publisher-place: 'Cape Canaveral, FL'
+ status: forthcoming
+ title: Protean photography
+ type: chapter
+---
+
+[@Faraday-forthcoming]
+
+References
+==========
+^D
+(Faraday, forthcoming)
+
+# References {#references .unnumbered}
+
+:::: {#refs .references .csl-bib-body .hanging-indent entry-spacing="0"}
+::: {#ref-Faraday-forthcoming .csl-entry}
+Faraday, Carry. Forthcoming. "Protean Photography." In *Seven Trips
+Beyond the Asteroid Belt*, edited by James Oring. Cape Canaveral, FL:
+Launch Press.
+:::
+::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-58.md b/documents/markdown/pandoc-md/pandoc-citeproc-58.md
new file mode 100644
index 0000000..f42fb7f
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-58.md
@@ -0,0 +1,32 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: command/issue58.csl
+references:
+- id: stanze
+ issued:
+ date-parts:
+ - - 1547
+ language: 'it-IT'
+ publisher-place: Florence
+ title: Stanze in lode della donna brutta
+ type: book
+---
+
+In this item, the title replaces the (unknown) author (see 14.79)
+[@stanze, p. 12].
+
+References
+==========
+^D
+In this item, the title replaces the (unknown) author (see 14.79)
+(*Stanze in lode della donna brutta* 1547, 12).
+
+# References {#references .unnumbered}
+
+:::: {#refs .references .csl-bib-body .hanging-indent entry-spacing="0"}
+::: {#ref-stanze .csl-entry}
+*Stanze in lode della donna brutta*. 1547. Florence.
+:::
+::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-61.md b/documents/markdown/pandoc-md/pandoc-citeproc-61.md
new file mode 100644
index 0000000..da17f31
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-61.md
@@ -0,0 +1,77 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: 'command/modern-humanities-research-association.csl'
+references:
+- author:
+ - family: Doe
+ given: John
+ id: doe
+ issued:
+ date-parts:
+ - - 1985
+ publisher: Publisher
+ title: Title
+ type: book
+- author:
+ - family: Roe
+ given: Rob
+ id: roe
+ issued:
+ date-parts:
+ - - 1985
+ publisher: Publisher
+ title: Title
+ type: book
+---
+
+Text
+====
+
+Foo [@doe, VIII, 89]
+
+Foo [@roe, III, 89]
+
+Foo [@doe, LVIII, 89]
+
+Foo [@roe, MVIII, 89]
+
+Foo [@doe, CL, 89]
+
+References
+==========
+^D
+# Text
+
+Foo[^1]
+
+Foo[^2]
+
+Foo[^3]
+
+Foo[^4]
+
+Foo[^5]
+
+# References {#references .unnumbered}
+
+::::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-doe .csl-entry}
+Doe, John, *Title* (Publisher, 1985)
+:::
+
+::: {#ref-roe .csl-entry}
+Roe, Rob, *Title* (Publisher, 1985)
+:::
+:::::
+
+[^1]: John Doe, *Title* (Publisher, 1985), VIII, 89.
+
+[^2]: Rob Roe, *Title* (Publisher, 1985), III, 89.
+
+[^3]: Doe, LVIII, 89.
+
+[^4]: Roe, MVIII, 89.
+
+[^5]: Doe, CL, 89.
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-64.md b/documents/markdown/pandoc-md/pandoc-citeproc-64.md
new file mode 100644
index 0000000..199679a
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-64.md
@@ -0,0 +1,24 @@
+```
+% pandoc --citeproc -t markdown-citations --csl command/chicago-fullnote-bibliography.csl
+---
+bibliography:
+- command/biblio.bib
+nocite: '[@*]'
+---
+
+^D
+:::::: {#refs .references .csl-bib-body .hanging-indent entry-spacing="0"}
+::: {#ref-item2 .csl-entry}
+Doe, John. "Article." *Journal of Generic Studies* 6 (2006): 33--34.
+:::
+
+::: {#ref-item1 .csl-entry}
+---------. *First Book*. Cambridge: Cambridge University Press, 2005.
+:::
+
+::: {#ref-пункт3 .csl-entry}
+Doe, John, and Jenny Roe. "Why Water Is Wet." In *Third Book*, edited by
+Sam Smith. Oxford: Oxford University Press, 2007.
+:::
+::::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-65.md b/documents/markdown/pandoc-md/pandoc-citeproc-65.md
new file mode 100644
index 0000000..e54eea4
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-65.md
@@ -0,0 +1,37 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+references:
+- ISBN: 3406493556
+ author:
+ - family: Stotz
+ given: Peter
+ call-number: 'PA25 PA2616 .H24 Abt. 2, T. 5, Bd. 2, etc'
+ collection-number: 2.5
+ collection-title: Handbuch der Altertumswissenschaft
+ event-place: Munich
+ first-reference-note-number: 1
+ id: 'stotz:1996handbuch'
+ issued:
+ literal: 1996_2004
+ language: de
+ number-of-volumes: 5
+ publisher: Beck
+ publisher-place: Munich
+ source: Library of Congress ISBN
+ title: Handbuch zur lateinischen Sprache des Mittelalters
+ title-short: Handbuch
+ type: book
+---
+
+[@stotz:1996handbuch]
+^D
+(Stotz 1996--2004)
+
+:::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-stotz:1996handbuch .csl-entry}
+Stotz, Peter. 1996--2004. *Handbuch zur lateinischen Sprache des
+Mittelalters*. 5 vols. Handbuch der Altertumswissenschaft, 2.5. Beck.
+:::
+::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-68.md b/documents/markdown/pandoc-md/pandoc-citeproc-68.md
new file mode 100644
index 0000000..d0b188e
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-68.md
@@ -0,0 +1,56 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: 'command/chicago-fullnote-bibliography.csl'
+references:
+- ISBN: 0888441088
+ author:
+ - family: Goering
+ given: Joseph
+ call-number: BV4009 .W55 1992
+ collection-number: 108
+ collection-title: Studies and Texts
+ event-place: Toronto
+ first-reference-note-number: 1
+ id: 'goering:1992william'
+ issued:
+ date-parts:
+ - - 1992
+ publisher: Pontifical Institute of Mediaeval Studies
+ publisher-place: Toronto
+ source: toroprod.library.utoronto.ca Library Catalog
+ title: 'William de Montibus (c. 1140--1213): The Schools and the
+ Literature of Pastoral Care'
+ title-short: William de Montibus
+ type: book
+---
+
+\... a prose commentary [the text of fol. 9r is printed in
+@goering:1992william, pp. 501--3]. \... a collection of verses with a
+formal prose commentary [excerpts from this text were previously printed
+in @goering:1992william, p. 508--14; it was also briefly described in
+@goering:1992william, pp. 141--42] \... and finally a note starting with
+a citation [@goering:1992william, pp. 141-42].
+^D
+\... a prose commentary.[^1] \... a collection of verses with a formal
+prose commentary[^2] \... and finally a note starting with a
+citation.[^3]
+
+:::: {#refs .references .csl-bib-body .hanging-indent entry-spacing="0"}
+::: {#ref-goering:1992william .csl-entry}
+Goering, Joseph. *William de Montibus (c. 1140--1213): The Schools and
+the Literature of Pastoral Care*. Studies and Texts 108. Toronto:
+Pontifical Institute of Mediaeval Studies, 1992.
+:::
+::::
+
+[^1]: The text of fol. 9r is printed in Joseph Goering, *William de
+ Montibus (c. 1140--1213): The Schools and the Literature of Pastoral
+ Care*, Studies and Texts 108 (Toronto: Pontifical Institute of
+ Mediaeval Studies, 1992), 501--3.
+
+[^2]: Excerpts from this text were previously printed in Goering,
+ 508--14; it was also briefly described in Goering, 141--42.
+
+[^3]: Goering, *William de Montibus*, 141--42.
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-7.md b/documents/markdown/pandoc-md/pandoc-citeproc-7.md
new file mode 100644
index 0000000..bf1e39e
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-7.md
@@ -0,0 +1,31 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+references:
+- author:
+ family: Author
+ given:
+ - Ann
+ container-title: Journal
+ id: item1
+ issued:
+ - day: 24
+ month: 9
+ year: 2011
+ - day: 26
+ month: 9
+ year: 2011
+ title: Title
+ type: 'article-magazine'
+---
+
+@item1
+^D
+Author (2011)
+
+:::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-item1 .csl-entry}
+Author, Ann. 2011. "Title." *Journal*, September 24--26.
+:::
+::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-70.md b/documents/markdown/pandoc-md/pandoc-citeproc-70.md
new file mode 100644
index 0000000..f08b620
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-70.md
@@ -0,0 +1,73 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+references:
+- ISBN: 9782503531465
+ author:
+ - family: 'Dinkova-Bruun'
+ given: Greti
+ call-number: CB351 .F564 2009
+ collection-number: 50
+ collection-title: Textes et études du moyen âge
+ container-title: 'Florilegium mediaevale: Études offertes à Jacqueline
+ Hamesse à l''occasion de son éméritat'
+ editor:
+ - family: Meirinhos
+ given: José Francisco
+ - family: Weijers
+ given: Olga
+ event-place: 'Louvain-la-Neuve'
+ first-reference-note-number: 1
+ id: 'bruun:2009samuel'
+ issued:
+ date-parts:
+ - - 2009
+ language: fr
+ page: '155--174'
+ publisher: 'Fédération Internationale des Instituts d''Études
+ Médiévales'
+ publisher-place: 'Louvain-la-Neuve'
+ source: Library of Congress ISBN
+ title: 'Samuel Presbyter and the Glosses to His Versification of Psalm
+ 1: An Anti-Church Invective?'
+ title-short: Samuel Presbyter
+ type: chapter
+- ISSN: '0362-1529'
+ author:
+ - family: Thorndike
+ given: Lynn
+ container-title: Traditio
+ first-reference-note-number: 1
+ id: 'thorndike:1955unde'
+ issued:
+ date-parts:
+ - - 1955
+ language: la
+ note: 'ArticleType: research-article / Full publication date: 1955 /
+ Copyright © 1955 Fordham University'
+ page: '163--193'
+ source: JSTOR
+ title: Unde versus
+ type: 'article-journal'
+ volume: 11
+---
+
+[@thorndike:1955unde; @bruun:2009samuel]
+^D
+(Thorndike 1955; Dinkova-Bruun 2009)
+
+::::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-bruun:2009samuel .csl-entry}
+Dinkova-Bruun, Greti. 2009. "Samuel Presbyter and the Glosses to His
+Versification of Psalm 1: An Anti-Church Invective?" In *Florilegium
+mediaevale: Études offertes à Jacqueline Hamesse à l'occasion de son
+éméritat*, edited by José Francisco Meirinhos and Olga Weijers. Textes
+et études du moyen âge 50. Fédération Internationale des Instituts
+d'Études Médiévales.
+:::
+
+::: {#ref-thorndike:1955unde .csl-entry}
+Thorndike, Lynn. 1955. "Unde versus." *Traditio* 11: 163--93.
+:::
+:::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-75.md b/documents/markdown/pandoc-md/pandoc-citeproc-75.md
new file mode 100644
index 0000000..d70c699
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-75.md
@@ -0,0 +1,67 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: command/apa.csl
+references:
+- author:
+ - family: Doe
+ given: John
+ id: test
+ issued:
+ date-parts:
+ - - 2006
+ title: Test
+ type: 'article-journal'
+ volume: 81
+---
+
+[@test, p. 6]
+
+[@test, chap. 6]
+
+[@test, n. 6]
+
+[@test, pp. 34-36, 38-39]
+
+[@test, sec. 3]
+
+[@test, p.3]
+
+[@test, 33-35, 38-39]
+
+[@test, 14]
+
+[@test bk. VI]
+
+[@test, no. 6]
+
+[@test, nos. 6 and 7]
+^D
+(Doe, 2006, p. 6)
+
+(Doe, 2006, Chapter 6)
+
+(Doe, 2006, n. 6)
+
+(Doe, 2006, pp. 34--36, 38--39)
+
+(Doe, 2006, sec. 3)
+
+(Doe, 2006, p. 3)
+
+(Doe, 2006, pp. 33--35, 38--39)
+
+(Doe, 2006, p. 14)
+
+(Doe, 2006, bk. VI)
+
+(Doe, 2006, no. 6)
+
+(Doe, 2006, no. 6 and 7)
+
+:::: {#refs .references .csl-bib-body .hanging-indent entry-spacing="0" line-spacing="2"}
+::: {#ref-test .csl-entry}
+Doe, J. (2006). Test, *81*.
+:::
+::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-76.md b/documents/markdown/pandoc-md/pandoc-citeproc-76.md
new file mode 100644
index 0000000..5240c09
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-76.md
@@ -0,0 +1,64 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+references:
+- author:
+ - family: Author
+ given: Al
+ id: item1
+ issued:
+ date-parts:
+ - - 1998
+ title: 'foo bar baz: bazbaz bar foo'
+ type: 'article-journal'
+- author:
+ - family: Author
+ given: Al
+ id: item2
+ issued:
+ date-parts:
+ - - 1998
+ title: 'foo bar baz: the bazbaz bar foo'
+ type: 'article-journal'
+- author:
+ - family: Author
+ given: Al
+ id: item3
+ issued:
+ date-parts:
+ - - 1998
+ title: 'foo bar baz: a bazbaz bar foo'
+ type: 'article-journal'
+- author:
+ - family: Author
+ given: Al
+ id: item4
+ issued:
+ date-parts:
+ - - 1998
+ title: 'foo bar baz: an abazbaz bar foo'
+ type: 'article-journal'
+---
+
+@item1, @item2, @item3, @item4
+^D
+Author (1998c), Author (1998d), Author (1998a), Author (1998b)
+
+::::::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-item3 .csl-entry}
+Author, Al. 1998a. *Foo Bar Baz: A Bazbaz Bar Foo*.
+:::
+
+::: {#ref-item4 .csl-entry}
+Author, Al. 1998b. *Foo Bar Baz: An Abazbaz Bar Foo*.
+:::
+
+::: {#ref-item1 .csl-entry}
+Author, Al. 1998c. *Foo Bar Baz: Bazbaz Bar Foo*.
+:::
+
+::: {#ref-item2 .csl-entry}
+Author, Al. 1998d. *Foo Bar Baz: The Bazbaz Bar Foo*.
+:::
+:::::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-77.md b/documents/markdown/pandoc-md/pandoc-citeproc-77.md
new file mode 100644
index 0000000..34c29bd
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-77.md
@@ -0,0 +1,67 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: 'command/chicago-fullnote-bibliography.csl'
+references:
+- author:
+ - family: Doe
+ given: 'John, III'
+ parse-names: true
+ id: item1
+ type: book
+- author:
+ - family: van Gogh
+ given: Vincent
+ parse-names: true
+ id: item2
+ type: book
+- author:
+ - family: Humboldt
+ given: Alexander von
+ parse-names: true
+ id: item3
+ type: book
+- author:
+ - family: Bennett
+ given: 'Frank G.,! Jr.'
+ parse-names: true
+ id: item4
+ type: book
+- author:
+ - family: Dumboldt
+ given: 'Ezekiel, III'
+ parse-names: true
+ id: item5
+ type: book
+---
+
+[@item1; @item2; @item3; @item4; @item5]
+^D
+[^1]
+
+:::::::: {#refs .references .csl-bib-body .hanging-indent entry-spacing="0"}
+::: {#ref-item4 .csl-entry}
+Bennett, Frank G., Jr., n.d.
+:::
+
+::: {#ref-item1 .csl-entry}
+Doe, John, III, n.d.
+:::
+
+::: {#ref-item5 .csl-entry}
+Dumboldt, Ezekiel, III, n.d.
+:::
+
+::: {#ref-item2 .csl-entry}
+Gogh, Vincent van, n.d.
+:::
+
+::: {#ref-item3 .csl-entry}
+Humboldt, Alexander von, n.d.
+:::
+::::::::
+
+[^1]: John Doe III, n.d.; Vincent van Gogh, n.d.; Alexander von
+ Humboldt, n.d.; Frank G. Bennett, Jr., n.d.; Ezekiel Dumboldt III,
+ n.d.
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-82.md b/documents/markdown/pandoc-md/pandoc-citeproc-82.md
new file mode 100644
index 0000000..380fe29
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-82.md
@@ -0,0 +1,39 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: 'command/chicago-annotated-bibliography.csl'
+references:
+- URL: 'https://www.worldcat.org/'
+ accessed:
+ date-parts:
+ - - 2014
+ - 9
+ - 19
+ author:
+ - literal: OCLC
+ first-reference-note-number: 1
+ id: OCLC_i1099
+ title: WorldCat
+ type: webpage
+---
+
+Title
+=====
+
+Some text.[^1]
+
+[^1]: Comment regarding text, supported by citation [@OCLC_i1099].
+^D
+# Title
+
+Some text.[^1]
+
+:::: {#refs .references .csl-bib-body .hanging-indent entry-spacing="0"}
+::: {#ref-OCLC_i1099 .csl-entry}
+OCLC. "WorldCat." Accessed September 19, 2014.
+<https://www.worldcat.org/>.
+:::
+::::
+
+[^1]: Comment regarding text, supported by citation (OCLC, "WorldCat").
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-87.md b/documents/markdown/pandoc-md/pandoc-citeproc-87.md
new file mode 100644
index 0000000..67f67c9
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-87.md
@@ -0,0 +1,156 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+references:
+- URL: 'http://www.example.com'
+ author:
+ - family: Doe
+ given: John
+ container-title: The Web Site
+ id: item1
+ issued:
+ date-parts:
+ - - 2006
+ - 10
+ - 26
+ title: Title
+ type: webpage
+- URL: 'http://www.example.com'
+ author:
+ - family: Doe
+ given: John
+ container-title: The Web Site
+ id: item2
+ issued:
+ date-parts:
+ - - 2006
+ - 10
+ - 26
+ - - 2006
+ - 11
+ - 27
+ title: Title
+ type: webpage
+- URL: 'http://www.example.com'
+ author:
+ - family: Doe
+ given: John
+ container-title: The Web Site
+ id: item2a
+ issued:
+ date-parts:
+ - - 2006
+ - 10
+ - - 2006
+ - 11
+ title: Title
+ type: webpage
+- URL: 'http://www.example.com'
+ author:
+ - family: Doe
+ given: John
+ container-title: The Web Site
+ id: item2b
+ issued:
+ date-parts:
+ - - 2006
+ - 12
+ - 31
+ - - 2007
+ - 1
+ - 1
+ title: Title
+ type: webpage
+- URL: 'http://www.example.com'
+ author:
+ - family: Doe
+ given: John
+ container-title: The Newspaper
+ id: item3
+ issued:
+ date-parts:
+ - - 2006
+ - 10
+ - 26
+ - - 2006
+ - 11
+ - 27
+ title: Title
+ type: 'article-newspaper'
+- URL: 'http://www.example.com'
+ author:
+ - family: Doe
+ given: John
+ container-title: The Newspaper
+ id: item3b
+ issued:
+ date-parts:
+ - - 2006
+ - 10
+ - - 2006
+ - 11
+ title: Title
+ type: 'article-newspaper'
+---
+
+@item1 -- webpage, date
+
+@item2 -- webpage, date range
+
+@item2a -- webpage, date range YM
+
+@item2b -- webpage, date range across years
+
+@item3 -- article-newspaper
+
+@item3b -- article-newspaper YM
+
+References
+==========
+^D
+Doe (2006a) -- webpage, date
+
+Doe (2006c) -- webpage, date range
+
+Doe (2006b) -- webpage, date range YM
+
+Doe (2006--2007) -- webpage, date range across years
+
+Doe (2006e) -- article-newspaper
+
+Doe (2006d) -- article-newspaper YM
+
+# References {#references .unnumbered}
+
+::::::::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-item1 .csl-entry}
+Doe, John. 2006a. "Title." The Web Site, October 26.
+<http://www.example.com>.
+:::
+
+::: {#ref-item2a .csl-entry}
+Doe, John. 2006b. "Title." The Web Site, October--November.
+<http://www.example.com>.
+:::
+
+::: {#ref-item2 .csl-entry}
+Doe, John. 2006c. "Title." The Web Site, October 26--November 27.
+<http://www.example.com>.
+:::
+
+::: {#ref-item3b .csl-entry}
+Doe, John. 2006d. "Title." *The Newspaper*, October--November.
+<http://www.example.com>.
+:::
+
+::: {#ref-item3 .csl-entry}
+Doe, John. 2006e. "Title." *The Newspaper*, October 26--November 27.
+<http://www.example.com>.
+:::
+
+::: {#ref-item2b .csl-entry}
+Doe, John. 2006--2007. "Title." The Web Site, December 31--January 1.
+<http://www.example.com>.
+:::
+:::::::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-chicago-author-date.md b/documents/markdown/pandoc-md/pandoc-citeproc-chicago-author-date.md
new file mode 100644
index 0000000..f88578d
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-chicago-author-date.md
@@ -0,0 +1,109 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+bibliography: command/biblio.bib
+link-citations: true
+---
+
+Pandoc with citeproc-hs
+=======================
+
+[@nonexistent]
+
+@nonexistent
+
+@item1 says blah.
+
+@item1 [p. 30] says blah.
+
+@item1 [p. 30, with suffix] says blah.
+
+@item1 [-@item2 p. 30; see also @пункт3] says blah.
+
+In a note.[^1]
+
+A citation group [see @item1 chap. 3; also @пункт3 p. 34-35].
+
+Another one [see @item1 p. 34-35].
+
+And another one in a note.[^2]
+
+Citation with a suffix and locator [@item1 pp. 33, 35-37, and nowhere
+else].
+
+Citation with suffix only [@item1 and nowhere else].
+
+Now some modifiers.[^3]
+
+With some markup [*see* @item1 p. **32**].
+
+References {#references .unnumbered}
+==========
+
+[^1]: @пункт3 [p. 12] and a citation without locators [@пункт3].
+
+[^2]: Some citations [see @item1 chap. 3; @пункт3; @item2].
+
+[^3]: Like a citation without author: [-@item1], and now Doe with a
+ locator [-@item2 p. 44].
+^D
+2> [WARNING] Citeproc: citation nonexistent not found
+# Pandoc with citeproc-hs
+
+([**nonexistent?**](#ref-nonexistent))
+
+([**nonexistent?**](#ref-nonexistent))
+
+Doe ([2005](#ref-item1)) says blah.
+
+Doe ([2005, 30](#ref-item1)) says blah.
+
+Doe ([2005, 30](#ref-item1), with suffix) says blah.
+
+Doe ([2005](#ref-item1); [2006, 30](#ref-item2); see also [Doe and Roe
+2007](#ref-пункт3)) says blah.
+
+In a note.[^1]
+
+A citation group (see [Doe 2005, chap. 3](#ref-item1); also [Doe and Roe
+2007, 34--35](#ref-пункт3)).
+
+Another one (see [Doe 2005, 34--35](#ref-item1)).
+
+And another one in a note.[^2]
+
+Citation with a suffix and locator ([Doe 2005, 33, 35--37](#ref-item1),
+and nowhere else).
+
+Citation with suffix only ([Doe 2005](#ref-item1) and nowhere else).
+
+Now some modifiers.[^3]
+
+With some markup (*see* [Doe 2005, 32](#ref-item1)).
+
+# References {#references .unnumbered}
+
+:::::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-item1 .csl-entry}
+Doe, John. 2005. *First Book*. Cambridge University Press.
+:::
+
+::: {#ref-item2 .csl-entry}
+Doe, John. 2006. "Article." *Journal of Generic Studies* 6: 33--34.
+:::
+
+::: {#ref-пункт3 .csl-entry}
+Doe, John, and Jenny Roe. 2007. "Why Water Is Wet." In *Third Book*,
+edited by Sam Smith. Oxford University Press.
+:::
+::::::
+
+[^1]: Doe and Roe ([2007, 12](#ref-пункт3)) and a citation without
+ locators ([Doe and Roe 2007](#ref-пункт3)).
+
+[^2]: Some citations (see [Doe 2005, chap. 3](#ref-item1);
+ [2006](#ref-item2); [Doe and Roe 2007](#ref-пункт3)).
+
+[^3]: Like a citation without author: ([2005](#ref-item1)), and now Doe
+ with a locator ([2006, 44](#ref-item2)).
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-chicago-fullnote-bibliography.md b/documents/markdown/pandoc-md/pandoc-citeproc-chicago-fullnote-bibliography.md
new file mode 100644
index 0000000..c9c5d0a
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-chicago-fullnote-bibliography.md
@@ -0,0 +1,134 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+bibliography: command/biblio.bib
+csl: 'command/chicago-fullnote-bibliography.csl'
+link-citations: true
+---
+
+Pandoc with citeproc-hs
+=======================
+
+[@nonexistent]
+
+@nonexistent
+
+@item1 says blah.
+
+@item1 [p. 30] says blah.
+
+@item1 [p. 30, with suffix] says blah.
+
+@item1 [-@item2 p. 30; see also @пункт3] says blah.
+
+In a note.[^1]
+
+A citation group [see @item1 chap. 3; also @пункт3 p. 34-35].
+
+Another one [see @item1 p. 34-35].
+
+And another one in a note.[^2]
+
+Citation with a suffix and locator [@item1 pp. 33, 35-37, and nowhere
+else].
+
+Citation with suffix only [@item1 and nowhere else].
+
+Now some modifiers.[^3]
+
+With some markup [*see* @item1 p. **32**].
+
+References {#references .unnumbered}
+==========
+
+[^1]: @пункт3 [p. 12] and a citation without locators [@пункт3].
+
+[^2]: Some citations [see @item1 chap. 3; @пункт3; @item2].
+
+[^3]: Like a citation without author: [-@item1], and again
+ [-@item1], and now Doe with a locator [-@item2 p. 44].
+^D
+2> [WARNING] Citeproc: citation nonexistent not found
+# Pandoc with citeproc-hs
+
+[^1]
+
+[^2]
+
+John Doe[^3] says blah.
+
+Doe[^4] says blah.
+
+Doe[^5] says blah.
+
+Doe[^6] says blah.
+
+In a note.[^7]
+
+A citation group.[^8]
+
+Another one.[^9]
+
+And another one in a note.[^10]
+
+Citation with a suffix and locator.[^11]
+
+Citation with suffix only.[^12]
+
+Now some modifiers.[^13]
+
+With some markup.[^14]
+
+# References {#references .unnumbered}
+
+:::::: {#refs .references .csl-bib-body .hanging-indent entry-spacing="0"}
+::: {#ref-item2 .csl-entry}
+Doe, John. "Article." *Journal of Generic Studies* 6 (2006): 33--34.
+:::
+
+::: {#ref-item1 .csl-entry}
+---------. *First Book*. Cambridge: Cambridge University Press, 2005.
+:::
+
+::: {#ref-пункт3 .csl-entry}
+Doe, John, and Jenny Roe. "Why Water Is Wet." In *Third Book*, edited by
+Sam Smith. Oxford: Oxford University Press, 2007.
+:::
+::::::
+
+[^1]: [**Nonexistent?**](#ref-nonexistent)
+
+[^2]: [**Nonexistent?**](#ref-nonexistent)
+
+[^3]: [*First Book* (Cambridge: Cambridge University Press,
+ 2005)](#ref-item1).
+
+[^4]: [30](#ref-item1).
+
+[^5]: [30](#ref-item1), with suffix.
+
+[^6]: [*First Book*](#ref-item1); ["Article," *Journal of Generic
+ Studies* 6 (2006): 30](#ref-item2); see also [John Doe and Jenny
+ Roe, "Why Water Is Wet," in *Third Book*, ed. Sam Smith (Oxford:
+ Oxford University Press, 2007)](#ref-пункт3).
+
+[^7]: Doe and Roe, ["Why Water Is Wet," 12](#ref-пункт3) and a citation
+ without locators ([Doe and Roe, "Why Water Is Wet"](#ref-пункт3)).
+
+[^8]: See [Doe, *First Book*, chap. 3](#ref-item1); also [Doe and Roe,
+ "Why Water Is Wet," 34--35](#ref-пункт3).
+
+[^9]: See [Doe, *First Book*, 34--35](#ref-item1).
+
+[^10]: Some citations (see [Doe, chap. 3](#ref-item1); [Doe and Roe,
+ "Why Water Is Wet"](#ref-пункт3); [Doe, "Article"](#ref-item2)).
+
+[^11]: [Doe, *First Book*, 33, 35--37](#ref-item1), and nowhere else.
+
+[^12]: [Doe, *First Book*](#ref-item1) and nowhere else.
+
+[^13]: Like a citation without author: (), and again (), and now Doe
+ with a locator (["Article," 44](#ref-item2)).
+
+[^14]: *See* [Doe, *First Book*, 32](#ref-item1).
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-ieee.md b/documents/markdown/pandoc-md/pandoc-citeproc-ieee.md
new file mode 100644
index 0000000..dbe5d23
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-ieee.md
@@ -0,0 +1,113 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+bibliography: command/biblio.bib
+csl: command/ieee.csl
+link-citations: true
+---
+
+Pandoc with citeproc-hs
+=======================
+
+[@nonexistent]
+
+@nonexistent
+
+@item1 says blah.
+
+@item1 [p. 30] says blah.
+
+@item1 [p. 30, with suffix] says blah.
+
+@item1 [-@item2 p. 30; see also @пункт3] says blah.
+
+In a note.[^1]
+
+A citation group [see @item1 chap. 3; also @пункт3 p. 34-35].
+
+Another one [see @item1 p. 34-35].
+
+And another one in a note.[^2]
+
+Citation with a suffix and locator [@item1 pp. 33, 35-37, and nowhere
+else].
+
+Citation with suffix only [@item1 and nowhere else].
+
+Now some modifiers.[^3]
+
+With some markup [*see* @item1 p. **32**].
+
+References {#references .unnumbered}
+==========
+
+[^1]: @пункт3 [p. 12] and a citation without locators [@пункт3].
+
+[^2]: Some citations [see @item1 chap. 3; @пункт3; @item2].
+
+[^3]: Like a citation without author: [-@item1], and now Doe with a
+ locator [-@item2 p. 44].
+^D
+2> [WARNING] Citeproc: citation nonexistent not found
+# Pandoc with citeproc-hs
+
+[**nonexistent?**](#ref-nonexistent)
+
+[**nonexistent?**](#ref-nonexistent)
+
+[\[1\]](#ref-item1) says blah.
+
+[\[1, p. 30\]](#ref-item1) says blah.
+
+[\[1, p. 30\]](#ref-item1), with suffix says blah.
+
+[\[1\]](#ref-item1), [\[2, p. 30\]](#ref-item2), see also
+[\[3\]](#ref-пункт3) says blah.
+
+In a note.[^1]
+
+A citation group see [\[1, Ch. 3\]](#ref-item1), also [\[3, pp.
+34--35\]](#ref-пункт3).
+
+Another one see [\[1, pp. 34--35\]](#ref-item1).
+
+And another one in a note.[^2]
+
+Citation with a suffix and locator [\[1, pp. 33, 35--37\]](#ref-item1),
+and nowhere else.
+
+Citation with suffix only [\[1\]](#ref-item1) and nowhere else.
+
+Now some modifiers.[^3]
+
+With some markup *see* [\[1, p. 32\]](#ref-item1).
+
+# References {#references .unnumbered}
+
+:::::: {#refs .references .csl-bib-body entry-spacing="0"}
+::: {#ref-item1 .csl-entry}
+[\[1\] ]{.csl-left-margin}[J. Doe, *First book*. Cambridge: Cambridge
+University Press, 2005.]{.csl-right-inline}
+:::
+
+::: {#ref-item2 .csl-entry}
+[\[2\] ]{.csl-left-margin}[J. Doe, "Article," *Journal of Generic
+Studies*, vol. 6, pp. 33--34, 2006.]{.csl-right-inline}
+:::
+
+::: {#ref-пункт3 .csl-entry}
+[\[3\] ]{.csl-left-margin}[J. Doe and J. Roe, "Why water is wet," in
+*Third book*, S. Smith, Ed. Oxford: Oxford University Press,
+2007.]{.csl-right-inline}
+:::
+::::::
+
+[^1]: [\[3, p. 12\]](#ref-пункт3) and a citation without locators
+ [\[3\]](#ref-пункт3).
+
+[^2]: Some citations see [\[1, Ch. 3\]](#ref-item1),
+ [\[2\]](#ref-item2), [\[3\]](#ref-пункт3).
+
+[^3]: Like a citation without author: [\[1\]](#ref-item1), and now Doe
+ with a locator [\[2, p. 44\]](#ref-item2).
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-locators-delimited.md b/documents/markdown/pandoc-md/pandoc-citeproc-locators-delimited.md
new file mode 100644
index 0000000..08c58c0
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-locators-delimited.md
@@ -0,0 +1,127 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: command/locators.csl
+references:
+- id: citekey
+ title: Title
+ type: 'article-journal'
+suppress-bibliography: true
+---
+
+See <https://github.com/jgm/pandoc-citeproc/pull/362>.
+
+Standard page range[@citekey {35-89, 102}]
+
+Alphanumeric[@citekey {abcdefg1234}]
+
+Kitchen sink[@citekey, {123(4)a-8(\[a\]12.398{8})}]
+
+Empty braces inside[@citekey, {{}}]
+
+Label specified[@citekey {p. a}]
+
+Should it work outside? No. [@citekey, p. {(a)}]
+
+Empty locator [@citekey, {}]
+
+Empty locator to force suffix[@citekey {} 123-35 numbers are suffix]
+
+Suffix generally [@citekey {123-35} numbers not, but text is suffix]
+
+With preceding comma[@citekey, {p. VI}]
+
+No commas before label[@citekey, {, p. (p. is not recognised)}]
+
+Trim white space[@citekey, { p. 9 }]
+
+Without delimiters[@citekey, suffix]
+
+With rendering label[@citekey {ss IV div 4 s 128L(7)(a)(i)-(iv), 129(5),
+130(b)}]
+
+The text is apparently NOT verbatim; it is lightly processed as page
+numbers. [@citekey {no comma, no label, no nothing}]
+
+AGLC-style page \[para\] [@citekey {584 \[78\]}]
+
+Unbalanced curly { breaks the parse[@citekey {p. suffix{suffix}suffix]
+
+Unbalanced curly } ends early[@citekey {green}suffix}suffix]
+^D
+See <https://github.com/jgm/pandoc-citeproc/pull/362>.
+
+Standard page range[^1]
+
+Alphanumeric[^2]
+
+Kitchen sink[^3]
+
+Empty braces inside[^4]
+
+Label specified[^5]
+
+Should it work outside? No.[^6]
+
+Empty locator[^7]
+
+Empty locator to force suffix[^8]
+
+Suffix generally[^9]
+
+With preceding comma[^10]
+
+No commas before label[^11]
+
+Trim white space[^12]
+
+Without delimiters[^13]
+
+With rendering label[^14]
+
+The text is apparently NOT verbatim; it is lightly processed as page
+numbers.[^15]
+
+AGLC-style page \[para\][^16]
+
+Unbalanced curly { breaks the parse[^17]
+
+Unbalanced curly } ends early[^18]
+
+[^1]: Title {35--89, 102}.
+
+[^2]: Ibid-with-locator {abcdefg1234}.
+
+[^3]: Ibid-with-locator {123(4)a--8(\[a\]12.398{8})}.
+
+[^4]: Ibid-with-locator {{}}.
+
+[^5]: Ibid-with-locator {a}.
+
+[^6]: Subsequent, p. {(a)}.
+
+[^7]: Ibid.
+
+[^8]: Ibid 123-35 numbers are suffix.
+
+[^9]: Ibid-with-locator {123--35} numbers not, but text is suffix.
+
+[^10]: Ibid-with-locator {VI}.
+
+[^11]: Ibid-with-locator {, p. (p. is not recognised)}.
+
+[^12]: Ibid-with-locator {9}.
+
+[^13]: Subsequent, suffix.
+
+[^14]: Ibid-with-locator ss {IV div 4 s 128L(7)(a)(i)--(iv), 129(5),
+ 130(b)}.
+
+[^15]: Ibid-with-locator {no comma, no label, no nothing}.
+
+[^16]: Ibid-with-locator {584 \[78\]}.
+
+[^17]: Subsequent {p. suffix{suffix}suffix.
+
+[^18]: Ibid-with-locator {green}suffix}suffix.
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-locators-integrated.md b/documents/markdown/pandoc-md/pandoc-citeproc-locators-integrated.md
new file mode 100644
index 0000000..de37cf8
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-locators-integrated.md
@@ -0,0 +1,159 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: command/locators.csl
+references:
+- id: citekey
+ title: Title
+ type: 'article-journal'
+suppress-bibliography: true
+---
+
+See <https://github.com/jgm/pandoc-citeproc/pull/362>.
+
+[@citekey, 89, and suffix]
+
+[@citekey, 89, perfect Ibid with suffix]
+
+[@citekey, 123-79, and suffix]
+
+[@citekey, xi, will be entirely suffix]
+
+[@citekey, p. xi, gives you a (page) locator xi]
+
+[@citekey, pp. VII, 89, gives you a (pages) locator VII, 89]
+
+[@citekey, p. VI, VII, VIII-IX, explicit romans]
+
+[@citekey \[89\]]
+
+[@citekey, p. \[89\]]
+
+[@citekey and nothing else]
+
+[@citekey, 123(4)\[5\]6, and suffix]
+
+[@citekey, 3(a), 4.4.8, \[7.6\], 7A(2)(a)(i)-(iv)]
+
+[@citekey, 4B.2a.i(3.4), and suffix]
+
+[@citekey, IV.2A, and suffix]
+
+[@citekey, \[28\], and suffix]
+
+[@citekey, \[39-52\], and suffix]
+
+[@citekey, \[39\]-\[52\], and suffix]
+
+[@citekey, s 123(4)(a)(iv), and suffix]
+
+[@citekey, ss 123(4)-(6), and suffix]
+
+[@citekey, \[13\], and suffix]
+
+[@citekey, p.3, and suffix]
+
+[@citekey, (13 entirely suffix]
+
+[@citekey, p.a entirely suffix]
+
+[@citekey, s (a) entirely suffix]
+^D
+See <https://github.com/jgm/pandoc-citeproc/pull/362>.
+
+[^1]
+
+[^2]
+
+[^3]
+
+[^4]
+
+[^5]
+
+[^6]
+
+[^7]
+
+[^8]
+
+[^9]
+
+[^10]
+
+[^11]
+
+[^12]
+
+[^13]
+
+[^14]
+
+[^15]
+
+[^16]
+
+[^17]
+
+[^18]
+
+[^19]
+
+[^20]
+
+[^21]
+
+[^22]
+
+[^23]
+
+[^24]
+
+[^1]: Title {89}, and suffix.
+
+[^2]: Ibid, perfect Ibid with suffix.
+
+[^3]: Ibid-with-locator {123--79}, and suffix.
+
+[^4]: Subsequent, xi, will be entirely suffix.
+
+[^5]: Ibid-with-locator {xi}, gives you a (page) locator xi.
+
+[^6]: Ibid-with-locator {VII, 89}, gives you a (pages) locator VII, 89.
+
+[^7]: Ibid-with-locator {VI, VII, VIII--IX}, explicit romans.
+
+[^8]: Ibid-with-locator {\[89\]}.
+
+[^9]: Ibid.
+
+[^10]: Subsequent and nothing else.
+
+[^11]: Ibid-with-locator {123(4)\[5\]6}, and suffix.
+
+[^12]: Ibid-with-locator {3(a), 4.4.8, \[7.6\], 7A(2)(a)(i)--(iv)}.
+
+[^13]: Ibid-with-locator {4B.2a.i(3.4)}, and suffix.
+
+[^14]: Ibid-with-locator {IV.2A}, and suffix.
+
+[^15]: Ibid-with-locator {\[28\]}, and suffix.
+
+[^16]: Ibid-with-locator {\[39--52\]}, and suffix.
+
+[^17]: Ibid-with-locator {\[39\]--\[52\]}, and suffix.
+
+[^18]: Ibid-with-locator s {123(4)(a)(iv)}, and suffix.
+
+[^19]: Ibid-with-locator ss {123(4)--(6)}, and suffix.
+
+[^20]: Ibid-with-locator {\[13\]}, and suffix.
+
+[^21]: Ibid-with-locator {3}, and suffix.
+
+[^22]: Subsequent, (13 entirely suffix.
+
+[^23]: Ibid, p.a entirely suffix.
+
+[^24]: Ibid, s (a) entirely suffix.
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-move-period-inside-quote.md b/documents/markdown/pandoc-md/pandoc-citeproc-move-period-inside-quote.md
new file mode 100644
index 0000000..86c330d
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-move-period-inside-quote.md
@@ -0,0 +1,52 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: 'command/chicago-fullnote-bibliography.csl'
+references:
+- DOI: 10.1038/171737a0
+ URL: 'http://www.nature.com/nature/journal/v171/n4356/abs/171737a0.html'
+ accessed:
+ day: 17
+ month: 6
+ year: 2008
+ author:
+ - family: Watson
+ given: J. D.
+ - family: Crick
+ given: F. H. C.
+ container-title: Nature
+ custom4: custom4
+ id: WatsonCrick1953
+ issue: 4356
+ issued:
+ date-parts:
+ - - 1953
+ - 4
+ - 25
+ language: 'en-US'
+ note: this is a note
+ original-date:
+ year: 1951
+ page: '737-738'
+ title: 'Molecular structure of nucleic acids: a structure for
+ deoxyribose nucleic acid'
+ title-short: Molecular structure of nucleic acids
+ type: 'article-journal'
+ volume: 171
+suppress-bibliography: true
+---
+
+Here is a "test citation" [@WatsonCrick1953].
+
+Here is a test citation [@WatsonCrick1953].
+^D
+Here is a "test citation."[^1]
+
+Here is a test citation.[^2]
+
+[^1]: J. D. Watson and F. H. C. Crick, "Molecular Structure of Nucleic
+ Acids: A Structure for Deoxyribose Nucleic Acid," *Nature* 171, no.
+ 4356 (April 25, 1953): 737--38, <https://doi.org/10.1038/171737a0>.
+
+[^2]: Watson and Crick.
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-no-author.md b/documents/markdown/pandoc-md/pandoc-citeproc-no-author.md
new file mode 100644
index 0000000..ae1ce98
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-no-author.md
@@ -0,0 +1,73 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+references:
+- container-title: Magazine
+ id: item1
+ issued:
+ year: 2012
+ title: Title A
+ type: 'article-magazine'
+- container-title: Magazine
+ id: item2
+ issued:
+ year: 2012
+ title: Title B
+ type: 'article-magazine'
+- container-title: Magazine
+ id: item3
+ issued:
+ year: 2012
+ title: Title C
+ type: 'article-magazine'
+- container-title: Magazine
+ id: item4
+ issued:
+ year: 2012
+ title: Title D
+ type: 'article-magazine'
+- container-title: Newspaper
+ id: item5
+ issued:
+ year: 2012
+ title: Title E
+ type: 'article-magazine'
+- container-title: Newspaper
+ id: item6
+ issued:
+ year: 2012
+ title: Title F
+ type: 'article-magazine'
+---
+
+@item1 [p. 3], @item2, @item3, @item4, @item5, @item6
+^D
+*Magazine* (2012a, 3), *Magazine* (2012b), *Magazine* (2012c),
+*Magazine* (2012d), *Newspaper* (2012a), *Newspaper* (2012b)
+
+::::::::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-item1 .csl-entry}
+*Magazine*. 2012a. "Title A."
+:::
+
+::: {#ref-item2 .csl-entry}
+*Magazine*. 2012b. "Title B."
+:::
+
+::: {#ref-item3 .csl-entry}
+*Magazine*. 2012c. "Title C."
+:::
+
+::: {#ref-item4 .csl-entry}
+*Magazine*. 2012d. "Title D."
+:::
+
+::: {#ref-item5 .csl-entry}
+*Newspaper*. 2012a. "Title E."
+:::
+
+::: {#ref-item6 .csl-entry}
+*Newspaper*. 2012b. "Title F."
+:::
+:::::::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-number-of-volumes.md b/documents/markdown/pandoc-md/pandoc-citeproc-number-of-volumes.md
new file mode 100644
index 0000000..b098b46
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-number-of-volumes.md
@@ -0,0 +1,29 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+references:
+- author:
+ family: Author
+ given:
+ - Al
+ id: item1
+ issued:
+ year: 2013
+ language: 'en-US'
+ number-of-volumes: 2
+ publisher: Publisher
+ publisher-place: Location
+ title: Title
+ type: book
+---
+
+@item1
+^D
+Author (2013)
+
+:::: {#refs .references .csl-bib-body .hanging-indent}
+::: {#ref-item1 .csl-entry}
+Author, Al. 2013. *Title*. 2 vols. Publisher.
+:::
+::::
+```
diff --git a/documents/markdown/pandoc-md/pandoc-citeproc-page-range.md b/documents/markdown/pandoc-md/pandoc-citeproc-page-range.md
new file mode 100644
index 0000000..20d6fa5
--- /dev/null
+++ b/documents/markdown/pandoc-md/pandoc-citeproc-page-range.md
@@ -0,0 +1,32 @@
+```
+% pandoc --citeproc -t markdown-citations
+---
+csl: 'command/chicago-fullnote-bibliography.csl'
+references:
+- URL: 'https://johnmacfarlane.net/vagueness.pdf'
+ id: test1
+- URL: 'https://pandoc.org'
+ id: test2
+- URL: 'https://johnmacfarlane.net'
+ id: test3
+suppress-bibliography: true
+---
+
+Test 1 [@test1, pp. 93--101].
+
+Test 2 [@test2, pp. 93--101].
+
+Test 3 [@test3, pp. 93-101].
+^D
+Test 1.[^1]
+
+Test 2.[^2]
+
+Test 3.[^3]
+
+[^1]: N.d., 93--101, <https://johnmacfarlane.net/vagueness.pdf>.
+
+[^2]: N.d., 93--101, <https://pandoc.org>.
+
+[^3]: N.d., 93--101, <https://johnmacfarlane.net>.
+```
diff --git a/documents/markdown/pandoc-md/parse-raw.md b/documents/markdown/pandoc-md/parse-raw.md
new file mode 100644
index 0000000..a1a41b5
--- /dev/null
+++ b/documents/markdown/pandoc-md/parse-raw.md
@@ -0,0 +1,27 @@
+```
+% pandoc -f latex+raw_tex -t markdown
+\emph{Hi \foo{there}}
+^D
+*Hi `\foo{there}`{=latex}*
+```
+
+```
+% pandoc -f latex -t markdown
+\emph{Hi \foo{there}}
+^D
+*Hi*
+```
+
+```
+% pandoc -f html+raw_html -t markdown
+<em>Hi <blink>there</blink></em>
+^D
+*Hi `<blink>`{=html}there`</blink>`{=html}*
+```
+
+```
+% pandoc -f html -t markdown
+<em>Hi <blink>there</blink></em>
+^D
+*Hi there*
+```
diff --git a/documents/markdown/pandoc-md/pdfstandard.md b/documents/markdown/pandoc-md/pdfstandard.md
new file mode 100644
index 0000000..587ec24
--- /dev/null
+++ b/documents/markdown/pandoc-md/pdfstandard.md
@@ -0,0 +1,616 @@
+PDF standard support: basic PDF/A-2b test (infers version 1.7)
+```
+% pandoc -t latex -s
+---
+pdfstandard: a-2b
+lang: en-US
+---
+
+Test document.
+^D
+\DocumentMetadata{
+ pdfversion=1.7,
+ pdfstandard={a-2b},
+ lang=en-US,
+ xmp=true}
+% Options for packages loaded elsewhere
+\PassOptionsToPackage{unicode}{hyperref}
+\PassOptionsToPackage{hyphens}{url}
+\documentclass[
+ american,
+]{article}
+\usepackage{xcolor}
+\usepackage{amsmath,amssymb}
+\setcounter{secnumdepth}{-\maxdimen} % remove section numbering
+\usepackage{iftex}
+\ifPDFTeX
+ \usepackage[T1]{fontenc}
+ \usepackage[utf8]{inputenc}
+ \usepackage{textcomp} % provide euro and other symbols
+\else % if luatex or xetex
+ \usepackage{unicode-math} % this also loads fontspec
+ \defaultfontfeatures{Scale=MatchLowercase}
+ \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
+\fi
+\usepackage{lmodern}
+\ifPDFTeX\else
+ % xetex/luatex font selection
+\fi
+% Use upquote if available, for straight quotes in verbatim environments
+\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
+\IfFileExists{microtype.sty}{% use microtype if available
+ \usepackage[]{microtype}
+ \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
+}{}
+\makeatletter
+\@ifundefined{KOMAClassName}{% if non-KOMA class
+ \IfFileExists{parskip.sty}{%
+ \usepackage{parskip}
+ }{% else
+ \setlength{\parindent}{0pt}
+ \setlength{\parskip}{6pt plus 2pt minus 1pt}}
+}{% if KOMA class
+ \KOMAoptions{parskip=half}}
+\makeatother
+\ifLuaTeX
+\usepackage[bidi=basic,shorthands=off]{babel}
+\else
+\usepackage[bidi=default,shorthands=off]{babel}
+\fi
+\ifLuaTeX
+ \usepackage{selnolig} % disable illegal ligatures
+\fi
+\setlength{\emergencystretch}{3em} % prevent overfull lines
+\providecommand{\tightlist}{%
+ \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
+\usepackage{bookmark}
+\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available
+\urlstyle{same}
+% fallback for those not using the hyperref driver hyperxmp:
+\makeatletter
+\@ifundefined{xmpquote}{\newcommand{\xmpquote}[1]{#1}}{}
+\makeatother
+\hypersetup{
+ pdflang={en-US},
+ hidelinks,
+ pdfcreator={LaTeX via pandoc}}
+
+\author{}
+\date{}
+
+\begin{document}
+
+Test document.
+
+\end{document}
+```
+
+PDF standard support: PDF/UA-1 with tagging
+```
+% pandoc -t latex -s
+---
+pdfstandard: ua-1
+lang: en-US
+---
+
+Accessible document.
+^D
+\DocumentMetadata{
+ pdfstandard={ua-1},
+ tagging=on,
+ lang=en-US,
+ xmp=true}
+% Options for packages loaded elsewhere
+\PassOptionsToPackage{unicode}{hyperref}
+\PassOptionsToPackage{hyphens}{url}
+\documentclass[
+ american,
+]{article}
+\usepackage{xcolor}
+\usepackage{amsmath,amssymb}
+\setcounter{secnumdepth}{-\maxdimen} % remove section numbering
+\usepackage{iftex}
+\ifPDFTeX
+ \usepackage[T1]{fontenc}
+ \usepackage[utf8]{inputenc}
+ \usepackage{textcomp} % provide euro and other symbols
+\else % if luatex or xetex
+ \usepackage{unicode-math} % this also loads fontspec
+ \defaultfontfeatures{Scale=MatchLowercase}
+ \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
+\fi
+\usepackage{lmodern}
+\ifPDFTeX\else
+ % xetex/luatex font selection
+\fi
+% Use upquote if available, for straight quotes in verbatim environments
+\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
+\IfFileExists{microtype.sty}{% use microtype if available
+ \usepackage[]{microtype}
+ \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
+}{}
+\makeatletter
+\@ifundefined{KOMAClassName}{% if non-KOMA class
+ \IfFileExists{parskip.sty}{%
+ \usepackage{parskip}
+ }{% else
+ \setlength{\parindent}{0pt}
+ \setlength{\parskip}{6pt plus 2pt minus 1pt}}
+}{% if KOMA class
+ \KOMAoptions{parskip=half}}
+\makeatother
+\ifLuaTeX
+\usepackage[bidi=basic,shorthands=off]{babel}
+\else
+\usepackage[bidi=default,shorthands=off]{babel}
+\fi
+\ifLuaTeX
+ \usepackage{selnolig} % disable illegal ligatures
+\fi
+\setlength{\emergencystretch}{3em} % prevent overfull lines
+\providecommand{\tightlist}{%
+ \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
+\usepackage{bookmark}
+\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available
+\urlstyle{same}
+% fallback for those not using the hyperref driver hyperxmp:
+\makeatletter
+\@ifundefined{xmpquote}{\newcommand{\xmpquote}[1]{#1}}{}
+\makeatother
+\hypersetup{
+ pdflang={en-US},
+ hidelinks,
+ pdfcreator={LaTeX via pandoc}}
+
+\author{}
+\date{}
+
+\begin{document}
+
+Accessible document.
+
+\end{document}
+```
+
+PDF standard support: multiple standards with version
+```
+% pandoc -t latex -s
+---
+pdfstandard:
+ - a-2b
+ - ua-1
+ - "1.7"
+lang: de-DE
+---
+
+Multi-standard document.
+^D
+\DocumentMetadata{
+ pdfversion=1.7,
+ pdfstandard={a-2b,ua-1},
+ tagging=on,
+ lang=de-DE,
+ xmp=true}
+% Options for packages loaded elsewhere
+\PassOptionsToPackage{unicode}{hyperref}
+\PassOptionsToPackage{hyphens}{url}
+\documentclass[
+ ngerman,
+]{article}
+\usepackage{xcolor}
+\usepackage{amsmath,amssymb}
+\setcounter{secnumdepth}{-\maxdimen} % remove section numbering
+\usepackage{iftex}
+\ifPDFTeX
+ \usepackage[T1]{fontenc}
+ \usepackage[utf8]{inputenc}
+ \usepackage{textcomp} % provide euro and other symbols
+\else % if luatex or xetex
+ \usepackage{unicode-math} % this also loads fontspec
+ \defaultfontfeatures{Scale=MatchLowercase}
+ \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
+\fi
+\usepackage{lmodern}
+\ifPDFTeX\else
+ % xetex/luatex font selection
+\fi
+% Use upquote if available, for straight quotes in verbatim environments
+\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
+\IfFileExists{microtype.sty}{% use microtype if available
+ \usepackage[]{microtype}
+ \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
+}{}
+\makeatletter
+\@ifundefined{KOMAClassName}{% if non-KOMA class
+ \IfFileExists{parskip.sty}{%
+ \usepackage{parskip}
+ }{% else
+ \setlength{\parindent}{0pt}
+ \setlength{\parskip}{6pt plus 2pt minus 1pt}}
+}{% if KOMA class
+ \KOMAoptions{parskip=half}}
+\makeatother
+\ifLuaTeX
+\usepackage[bidi=basic,shorthands=off]{babel}
+\else
+\usepackage[bidi=default,shorthands=off]{babel}
+\fi
+\ifLuaTeX
+ \usepackage{selnolig} % disable illegal ligatures
+\fi
+\setlength{\emergencystretch}{3em} % prevent overfull lines
+\providecommand{\tightlist}{%
+ \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
+\usepackage{bookmark}
+\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available
+\urlstyle{same}
+% fallback for those not using the hyperref driver hyperxmp:
+\makeatletter
+\@ifundefined{xmpquote}{\newcommand{\xmpquote}[1]{#1}}{}
+\makeatother
+\hypersetup{
+ pdflang={de-DE},
+ hidelinks,
+ pdfcreator={LaTeX via pandoc}}
+
+\author{}
+\date{}
+
+\begin{document}
+
+Multi-standard document.
+
+\end{document}
+```
+
+PDF standard support: PDF/A-1b infers version 1.4
+```
+% pandoc -t latex -s
+---
+pdfstandard: a-1b
+lang: en-US
+---
+
+PDF/A-1 document.
+^D
+\DocumentMetadata{
+ pdfversion=1.4,
+ pdfstandard={a-1b},
+ lang=en-US,
+ xmp=true}
+% Options for packages loaded elsewhere
+\PassOptionsToPackage{unicode}{hyperref}
+\PassOptionsToPackage{hyphens}{url}
+\documentclass[
+ american,
+]{article}
+\usepackage{xcolor}
+\usepackage{amsmath,amssymb}
+\setcounter{secnumdepth}{-\maxdimen} % remove section numbering
+\usepackage{iftex}
+\ifPDFTeX
+ \usepackage[T1]{fontenc}
+ \usepackage[utf8]{inputenc}
+ \usepackage{textcomp} % provide euro and other symbols
+\else % if luatex or xetex
+ \usepackage{unicode-math} % this also loads fontspec
+ \defaultfontfeatures{Scale=MatchLowercase}
+ \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
+\fi
+\usepackage{lmodern}
+\ifPDFTeX\else
+ % xetex/luatex font selection
+\fi
+% Use upquote if available, for straight quotes in verbatim environments
+\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
+\IfFileExists{microtype.sty}{% use microtype if available
+ \usepackage[]{microtype}
+ \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
+}{}
+\makeatletter
+\@ifundefined{KOMAClassName}{% if non-KOMA class
+ \IfFileExists{parskip.sty}{%
+ \usepackage{parskip}
+ }{% else
+ \setlength{\parindent}{0pt}
+ \setlength{\parskip}{6pt plus 2pt minus 1pt}}
+}{% if KOMA class
+ \KOMAoptions{parskip=half}}
+\makeatother
+\ifLuaTeX
+\usepackage[bidi=basic,shorthands=off]{babel}
+\else
+\usepackage[bidi=default,shorthands=off]{babel}
+\fi
+\ifLuaTeX
+ \usepackage{selnolig} % disable illegal ligatures
+\fi
+\setlength{\emergencystretch}{3em} % prevent overfull lines
+\providecommand{\tightlist}{%
+ \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
+\usepackage{bookmark}
+\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available
+\urlstyle{same}
+% fallback for those not using the hyperref driver hyperxmp:
+\makeatletter
+\@ifundefined{xmpquote}{\newcommand{\xmpquote}[1]{#1}}{}
+\makeatother
+\hypersetup{
+ pdflang={en-US},
+ hidelinks,
+ pdfcreator={LaTeX via pandoc}}
+
+\author{}
+\date{}
+
+\begin{document}
+
+PDF/A-1 document.
+
+\end{document}
+```
+
+PDF standard support: PDF/A-4 with no version inference (uses default 2.0)
+```
+% pandoc -t latex -s
+---
+pdfstandard: a-4
+lang: en-US
+---
+
+PDF/A-4 document.
+^D
+\DocumentMetadata{
+ pdfstandard={a-4},
+ lang=en-US,
+ xmp=true}
+% Options for packages loaded elsewhere
+\PassOptionsToPackage{unicode}{hyperref}
+\PassOptionsToPackage{hyphens}{url}
+\documentclass[
+ american,
+]{article}
+\usepackage{xcolor}
+\usepackage{amsmath,amssymb}
+\setcounter{secnumdepth}{-\maxdimen} % remove section numbering
+\usepackage{iftex}
+\ifPDFTeX
+ \usepackage[T1]{fontenc}
+ \usepackage[utf8]{inputenc}
+ \usepackage{textcomp} % provide euro and other symbols
+\else % if luatex or xetex
+ \usepackage{unicode-math} % this also loads fontspec
+ \defaultfontfeatures{Scale=MatchLowercase}
+ \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
+\fi
+\usepackage{lmodern}
+\ifPDFTeX\else
+ % xetex/luatex font selection
+\fi
+% Use upquote if available, for straight quotes in verbatim environments
+\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
+\IfFileExists{microtype.sty}{% use microtype if available
+ \usepackage[]{microtype}
+ \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
+}{}
+\makeatletter
+\@ifundefined{KOMAClassName}{% if non-KOMA class
+ \IfFileExists{parskip.sty}{%
+ \usepackage{parskip}
+ }{% else
+ \setlength{\parindent}{0pt}
+ \setlength{\parskip}{6pt plus 2pt minus 1pt}}
+}{% if KOMA class
+ \KOMAoptions{parskip=half}}
+\makeatother
+\ifLuaTeX
+\usepackage[bidi=basic,shorthands=off]{babel}
+\else
+\usepackage[bidi=default,shorthands=off]{babel}
+\fi
+\ifLuaTeX
+ \usepackage{selnolig} % disable illegal ligatures
+\fi
+\setlength{\emergencystretch}{3em} % prevent overfull lines
+\providecommand{\tightlist}{%
+ \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
+\usepackage{bookmark}
+\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available
+\urlstyle{same}
+% fallback for those not using the hyperref driver hyperxmp:
+\makeatletter
+\@ifundefined{xmpquote}{\newcommand{\xmpquote}[1]{#1}}{}
+\makeatother
+\hypersetup{
+ pdflang={en-US},
+ hidelinks,
+ pdfcreator={LaTeX via pandoc}}
+
+\author{}
+\date{}
+
+\begin{document}
+
+PDF/A-4 document.
+
+\end{document}
+```
+
+PDF standard support: numeric YAML version (2 becomes 2.0)
+```
+% pandoc -t latex -s
+---
+pdfstandard:
+ - ua-1
+ - 2
+lang: en-US
+---
+
+PDF 2.0 document.
+^D
+\DocumentMetadata{
+ pdfversion=2.0,
+ pdfstandard={ua-1},
+ tagging=on,
+ lang=en-US,
+ xmp=true}
+% Options for packages loaded elsewhere
+\PassOptionsToPackage{unicode}{hyperref}
+\PassOptionsToPackage{hyphens}{url}
+\documentclass[
+ american,
+]{article}
+\usepackage{xcolor}
+\usepackage{amsmath,amssymb}
+\setcounter{secnumdepth}{-\maxdimen} % remove section numbering
+\usepackage{iftex}
+\ifPDFTeX
+ \usepackage[T1]{fontenc}
+ \usepackage[utf8]{inputenc}
+ \usepackage{textcomp} % provide euro and other symbols
+\else % if luatex or xetex
+ \usepackage{unicode-math} % this also loads fontspec
+ \defaultfontfeatures{Scale=MatchLowercase}
+ \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
+\fi
+\usepackage{lmodern}
+\ifPDFTeX\else
+ % xetex/luatex font selection
+\fi
+% Use upquote if available, for straight quotes in verbatim environments
+\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
+\IfFileExists{microtype.sty}{% use microtype if available
+ \usepackage[]{microtype}
+ \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
+}{}
+\makeatletter
+\@ifundefined{KOMAClassName}{% if non-KOMA class
+ \IfFileExists{parskip.sty}{%
+ \usepackage{parskip}
+ }{% else
+ \setlength{\parindent}{0pt}
+ \setlength{\parskip}{6pt plus 2pt minus 1pt}}
+}{% if KOMA class
+ \KOMAoptions{parskip=half}}
+\makeatother
+\ifLuaTeX
+\usepackage[bidi=basic,shorthands=off]{babel}
+\else
+\usepackage[bidi=default,shorthands=off]{babel}
+\fi
+\ifLuaTeX
+ \usepackage{selnolig} % disable illegal ligatures
+\fi
+\setlength{\emergencystretch}{3em} % prevent overfull lines
+\providecommand{\tightlist}{%
+ \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
+\usepackage{bookmark}
+\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available
+\urlstyle{same}
+% fallback for those not using the hyperref driver hyperxmp:
+\makeatletter
+\@ifundefined{xmpquote}{\newcommand{\xmpquote}[1]{#1}}{}
+\makeatother
+\hypersetup{
+ pdflang={en-US},
+ hidelinks,
+ pdfcreator={LaTeX via pandoc}}
+
+\author{}
+\date{}
+
+\begin{document}
+
+PDF 2.0 document.
+
+\end{document}
+```
+
+PDF standard support: explicit version overrides inferred version
+```
+% pandoc -t latex -s
+---
+pdfstandard:
+ - a-2b
+ - "1.5"
+lang: en-US
+---
+
+Explicit version document.
+^D
+\DocumentMetadata{
+ pdfversion=1.5,
+ pdfstandard={a-2b},
+ lang=en-US,
+ xmp=true}
+% Options for packages loaded elsewhere
+\PassOptionsToPackage{unicode}{hyperref}
+\PassOptionsToPackage{hyphens}{url}
+\documentclass[
+ american,
+]{article}
+\usepackage{xcolor}
+\usepackage{amsmath,amssymb}
+\setcounter{secnumdepth}{-\maxdimen} % remove section numbering
+\usepackage{iftex}
+\ifPDFTeX
+ \usepackage[T1]{fontenc}
+ \usepackage[utf8]{inputenc}
+ \usepackage{textcomp} % provide euro and other symbols
+\else % if luatex or xetex
+ \usepackage{unicode-math} % this also loads fontspec
+ \defaultfontfeatures{Scale=MatchLowercase}
+ \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
+\fi
+\usepackage{lmodern}
+\ifPDFTeX\else
+ % xetex/luatex font selection
+\fi
+% Use upquote if available, for straight quotes in verbatim environments
+\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
+\IfFileExists{microtype.sty}{% use microtype if available
+ \usepackage[]{microtype}
+ \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
+}{}
+\makeatletter
+\@ifundefined{KOMAClassName}{% if non-KOMA class
+ \IfFileExists{parskip.sty}{%
+ \usepackage{parskip}
+ }{% else
+ \setlength{\parindent}{0pt}
+ \setlength{\parskip}{6pt plus 2pt minus 1pt}}
+}{% if KOMA class
+ \KOMAoptions{parskip=half}}
+\makeatother
+\ifLuaTeX
+\usepackage[bidi=basic,shorthands=off]{babel}
+\else
+\usepackage[bidi=default,shorthands=off]{babel}
+\fi
+\ifLuaTeX
+ \usepackage{selnolig} % disable illegal ligatures
+\fi
+\setlength{\emergencystretch}{3em} % prevent overfull lines
+\providecommand{\tightlist}{%
+ \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
+\usepackage{bookmark}
+\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available
+\urlstyle{same}
+% fallback for those not using the hyperref driver hyperxmp:
+\makeatletter
+\@ifundefined{xmpquote}{\newcommand{\xmpquote}[1]{#1}}{}
+\makeatother
+\hypersetup{
+ pdflang={en-US},
+ hidelinks,
+ pdfcreator={LaTeX via pandoc}}
+
+\author{}
+\date{}
+
+\begin{document}
+
+Explicit version document.
+
+\end{document}
+```
diff --git a/documents/markdown/pandoc-md/planets.md b/documents/markdown/pandoc-md/planets.md
new file mode 100644
index 0000000..a6cd6d2
--- /dev/null
+++ b/documents/markdown/pandoc-md/planets.md
@@ -0,0 +1,31 @@
++------------------+---------+------------+----------+-----------+----------+---------+-----------+-------------+--------+--------------+
+| | Name | Mass | Diameter | Density | Gravity | Length | Distance | Mean | Number | Notes |
+| | | (10\^24kg) | (km) | (kg/m\^3) | (m/s\^2) | of day | from Sun | temperature | of | |
+| | | | | | | (hours) | (10\^6km) | (C) | moons | |
++:=======:+:======:+=========+===========:+=========:+==========:+=========:+========:+==========:+============:+=======:+==============+
+| Terrestrial | Mercury | 0.330 | 4,879 | 5427 | 3.7 | 4222.6 | 57.9 | 167 | 0 | Closest to |
+| planets | | | | | | | | | | the Sun |
+| +---------+------------+----------+-----------+----------+---------+-----------+-------------+--------+--------------+
+| | Venus | 4.87 | 12,104 | 5243 | 8.9 | 2802.0 | 108.2 | 464 | 0 | |
+| +---------+------------+----------+-----------+----------+---------+-----------+-------------+--------+--------------+
+| | Earth | 5.97 | 12,756 | 5514 | 9.8 | 24.0 | 149.6 | 15 | 1 | Our world |
+| +---------+------------+----------+-----------+----------+---------+-----------+-------------+--------+--------------+
+| | Mars | 0.642 | 6,792 | 3933 | 3.7 | 24.7 | 227.9 | -65 | 2 | The red |
+| | | | | | | | | | | planet |
++---------+--------+---------+------------+----------+-----------+----------+---------+-----------+-------------+--------+--------------+
+| Jovian | Gas | Jupiter | 1898 | 142,984 | 1326 | 23.1 | 9.9 | 778.6 | -110 | 67 | The largest |
+| planets | giants | | | | | | | | | | planet |
+| | +---------+------------+----------+-----------+----------+---------+-----------+-------------+--------+--------------+
+| | | Saturn | 568 | 120,536 | 687 | 9.0 | 10.7 | 1433.5 | -140 | 62 | |
+| +--------+---------+------------+----------+-----------+----------+---------+-----------+-------------+--------+--------------+
+| | Ice | Uranus | 86.8 | 51,118 | 1271 | 8.7 | 17.2 | 2872.5 | -195 | 27 | |
+| | giants | | | | | | | | | | |
+| | +---------+------------+----------+-----------+----------+---------+-----------+-------------+--------+--------------+
+| | | Neptune | 102 | 49,528 | 1638 | 11.0 | 16.1 | 4495.1 | -200 | 14 | |
++---------+--------+---------+------------+----------+-----------+----------+---------+-----------+-------------+--------+--------------+
+| Dwarf planets | Pluto | 0.0146 | 2,370 | 2095 | 0.7 | 153.3 | 5906.4 | -225 | 5 | Declassified |
+| | | | | | | | | | | as a planet |
+| | | | | | | | | | | in 2006. |
++------------------+---------+------------+----------+-----------+----------+---------+-----------+-------------+--------+--------------+
+
+: Data about the planets of our solar system.
diff --git a/documents/markdown/pandoc-md/refs.md b/documents/markdown/pandoc-md/refs.md
new file mode 100644
index 0000000..63daf81
--- /dev/null
+++ b/documents/markdown/pandoc-md/refs.md
@@ -0,0 +1,309 @@
+```
+% pandoc -f latex -t native
+Figure \ref{fig:1}
+^D
+[ Para
+ [ Str "Figure"
+ , Space
+ , Link
+ ( ""
+ , []
+ , [ ( "reference-type" , "ref" )
+ , ( "reference" , "fig:1" )
+ ]
+ )
+ [ Str "[fig:1]" ]
+ ( "#fig:1" , "" )
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+Figure \cref{fig:1}
+^D
+[ Para
+ [ Str "Figure"
+ , Space
+ , Link
+ ( ""
+ , []
+ , [ ( "reference-type" , "ref+label" )
+ , ( "reference" , "fig:1" )
+ ]
+ )
+ [ Str "[fig:1]" ]
+ ( "#fig:1" , "" )
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+Figure \vref{fig:1}
+^D
+[ Para
+ [ Str "Figure"
+ , Space
+ , Link
+ ( ""
+ , []
+ , [ ( "reference-type" , "ref" )
+ , ( "reference" , "fig:1" )
+ ]
+ )
+ [ Str "[fig:1]" ]
+ ( "#fig:1" , "" )
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\autoref{fig:flowchart}
+^D
+[ Para
+ [ Link
+ ( ""
+ , []
+ , [ ( "reference-type" , "ref+label" )
+ , ( "reference" , "fig:flowchart" )
+ ]
+ )
+ [ Str "[fig:flowchart]" ]
+ ( "#fig:flowchart" , "" )
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+Accuracy~\eqref{eq:Accuracy} is the proportion, measuring true results among all results.
+
+\begin{equation}
+ \label{eq:Accuracy}
+ Accuracy = \frac{t_p + t_n}{t_p + f_p + f_n + t_n}
+\end{equation}
+^D
+[ Para
+ [ Str "Accuracy\160"
+ , Link
+ ( ""
+ , []
+ , [ ( "reference-type" , "eqref" )
+ , ( "reference" , "eq:Accuracy" )
+ ]
+ )
+ [ Str "[eq:Accuracy]" ]
+ ( "#eq:Accuracy" , "" )
+ , Space
+ , Str "is"
+ , Space
+ , Str "the"
+ , Space
+ , Str "proportion,"
+ , Space
+ , Str "measuring"
+ , Space
+ , Str "true"
+ , Space
+ , Str "results"
+ , Space
+ , Str "among"
+ , Space
+ , Str "all"
+ , Space
+ , Str "results."
+ ]
+, Para
+ [ Math
+ DisplayMath
+ "\\begin{equation}\n \\label{eq:Accuracy}\n Accuracy = \\frac{t_p + t_n}{t_p + f_p + f_n + t_n}\n\\end{equation}"
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\begin{figure}
+ \includegraphics{command/SVG_logo.svg}
+ \caption{Logo}
+ \label{fig:Logo}
+\end{figure}
+
+Figure \ref{fig:Logo} illustrated the SVG logo
+^D
+[ Figure
+ ( "fig:Logo" , [] , [] )
+ (Caption Nothing [ Plain [ Str "Logo" ] ])
+ [ Plain
+ [ Image ( "" , [] , [] ) [] ( "command/SVG_logo.svg" , "" )
+ ]
+ ]
+, Para
+ [ Str "Figure"
+ , Space
+ , Link
+ ( ""
+ , []
+ , [ ( "reference-type" , "ref" )
+ , ( "reference" , "fig:Logo" )
+ ]
+ )
+ [ Str "1" ]
+ ( "#fig:Logo" , "" )
+ , Space
+ , Str "illustrated"
+ , Space
+ , Str "the"
+ , Space
+ , Str "SVG"
+ , Space
+ , Str "logo"
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\chapter{One}
+\begin{figure}
+ \includegraphics{command/SVG_logo.svg}
+ \caption{Logo}
+ \label{fig:Logo}
+\end{figure}
+
+\begin{figure}
+ \includegraphics{command/SVG_logo2.svg}
+ \caption{Logo2}
+ \label{fig:Logo2}
+\end{figure}
+
+\chapter{Two}
+
+\section{Subone}
+
+\begin{figure}
+ \includegraphics{command/SVG_logo3.svg}
+ \caption{Logo3}
+ \label{fig:Logo3}
+\end{figure}
+
+Figure \ref{fig:Logo} illustrated the SVG logo
+
+Figure \ref{fig:Logo2} illustrated the SVG logo
+
+Figure \ref{fig:Logo3} illustrated the SVG logo
+^D
+[ Header 1 ( "one" , [] , [] ) [ Str "One" ]
+, Figure
+ ( "fig:Logo" , [] , [] )
+ (Caption Nothing [ Plain [ Str "Logo" ] ])
+ [ Plain
+ [ Image ( "" , [] , [] ) [] ( "command/SVG_logo.svg" , "" )
+ ]
+ ]
+, Figure
+ ( "fig:Logo2" , [] , [] )
+ (Caption Nothing [ Plain [ Str "Logo2" ] ])
+ [ Plain
+ [ Image ( "" , [] , [] ) [] ( "command/SVG_logo2.svg" , "" )
+ ]
+ ]
+, Header 1 ( "two" , [] , [] ) [ Str "Two" ]
+, Header 2 ( "subone" , [] , [] ) [ Str "Subone" ]
+, Figure
+ ( "fig:Logo3" , [] , [] )
+ (Caption Nothing [ Plain [ Str "Logo3" ] ])
+ [ Plain
+ [ Image ( "" , [] , [] ) [] ( "command/SVG_logo3.svg" , "" )
+ ]
+ ]
+, Para
+ [ Str "Figure"
+ , Space
+ , Link
+ ( ""
+ , []
+ , [ ( "reference-type" , "ref" )
+ , ( "reference" , "fig:Logo" )
+ ]
+ )
+ [ Str "1.1" ]
+ ( "#fig:Logo" , "" )
+ , Space
+ , Str "illustrated"
+ , Space
+ , Str "the"
+ , Space
+ , Str "SVG"
+ , Space
+ , Str "logo"
+ ]
+, Para
+ [ Str "Figure"
+ , Space
+ , Link
+ ( ""
+ , []
+ , [ ( "reference-type" , "ref" )
+ , ( "reference" , "fig:Logo2" )
+ ]
+ )
+ [ Str "1.2" ]
+ ( "#fig:Logo2" , "" )
+ , Space
+ , Str "illustrated"
+ , Space
+ , Str "the"
+ , Space
+ , Str "SVG"
+ , Space
+ , Str "logo"
+ ]
+, Para
+ [ Str "Figure"
+ , Space
+ , Link
+ ( ""
+ , []
+ , [ ( "reference-type" , "ref" )
+ , ( "reference" , "fig:Logo3" )
+ ]
+ )
+ [ Str "2.1" ]
+ ( "#fig:Logo3" , "" )
+ , Space
+ , Str "illustrated"
+ , Space
+ , Str "the"
+ , Space
+ , Str "SVG"
+ , Space
+ , Str "logo"
+ ]
+]
+```
+
+
+```
+% pandoc -f latex -t native
+\label{section} Section \ref{section}
+^D
+[ Para
+ [ Span ( "section" , [] , [ ( "label" , "section" ) ] ) []
+ , Space
+ , Str "Section"
+ , Space
+ , Link
+ ( ""
+ , []
+ , [ ( "reference-type" , "ref" )
+ , ( "reference" , "section" )
+ ]
+ )
+ [ Str "[section]" ]
+ ( "#section" , "" )
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/reset-citation-positions.md b/documents/markdown/pandoc-md/reset-citation-positions.md
new file mode 100644
index 0000000..e6ed125
--- /dev/null
+++ b/documents/markdown/pandoc-md/reset-citation-positions.md
@@ -0,0 +1,41 @@
+```
+% pandoc --citeproc -t plain --csl command/chicago-fullnote-bibliography.csl
+---
+suppress-bibliography: true
+references:
+- id: foo
+ name: John doe
+ title: A Book
+ type: book
+ publisher: Oxford University Press
+ issued: 2010
+...
+
+# Chapter one
+
+Blah [@foo, p. 7].
+
+Blah [@foo, p. 8].
+
+# Chapter two {.reset-citation-positions}
+
+Blah [@foo, p. 57].
+^D
+Chapter one
+
+Blah.[1]
+
+Blah.[2]
+
+Chapter two
+
+Blah.[3]
+
+[1] A Book (Oxford University Press, 2010), 7.
+
+[2] A Book, 8.
+
+[3] A Book (Oxford University Press, 2010), 57.
+
+```
+
diff --git a/documents/markdown/pandoc-md/rst-links.md b/documents/markdown/pandoc-md/rst-links.md
new file mode 100644
index 0000000..496bebc
--- /dev/null
+++ b/documents/markdown/pandoc-md/rst-links.md
@@ -0,0 +1,18 @@
+```
+% pandoc -f rst
+`*ab*`_
+
+.. _`*ab*`: foo
+^D
+<p><a href="foo">*ab*</a></p>
+```
+
+```
+% pandoc -f rst
+`A B
+c`_
+
+.. _A B C: foo
+^D
+<p><a href="foo">A B c</a></p>
+```
diff --git a/documents/markdown/pandoc-md/rst-writer-gridtable-if-rowspans.md b/documents/markdown/pandoc-md/rst-writer-gridtable-if-rowspans.md
new file mode 100644
index 0000000..e94cf31
--- /dev/null
+++ b/documents/markdown/pandoc-md/rst-writer-gridtable-if-rowspans.md
@@ -0,0 +1,246 @@
+```
+% pandoc -f native -t rst
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 2)
+ (ColSpan 1)
+ [ Plain [ Str "2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "3" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "3" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "3" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+, Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 2)
+ (ColSpan 1)
+ [ Plain [ Str "2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "3" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "3" ] ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "3" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+, Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ [] []
+ ]
+ (TableFoot ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 2)
+ (ColSpan 1)
+ [ Plain [ Str "2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "3" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "3" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "3" ] ]
+ ]
+ ])
+]
+^D
++---+---+---+
+| 1 | 2 | 3 |
++---+ +---+
+| 1 | | 3 |
++---+---+---+
+| 1 | 2 | 3 |
++---+---+---+
+
++---+---+---+
+| 1 | 2 | 3 |
++---+ +---+
+| 1 | | 3 |
++===+===+===+
+| 1 | 2 | 3 |
++---+---+---+
+
++===+===+===+
+| 1 | 2 | 3 |
++---+ +---+
+| 1 | | 3 |
++---+---+---+
+| 1 | 2 | 3 |
++===+===+===+
+```
diff --git a/documents/markdown/pandoc-md/rst_block_subst.md b/documents/markdown/pandoc-md/rst_block_subst.md
new file mode 100644
index 0000000..c279b1c
--- /dev/null
+++ b/documents/markdown/pandoc-md/rst_block_subst.md
@@ -0,0 +1,18 @@
+```
+% pandoc -f rst -t native
+|figure05|
+
+.. |figure05| figure:: img/dummy.png
+
+ capt
+^D
+[ Figure
+ ( "" , [] , [] )
+ (Caption Nothing [ Plain [ Str "capt" ] ])
+ [ Plain
+ [ Image
+ ( "" , [] , [] ) [ Str "capt" ] ( "img/dummy.png" , "" )
+ ]
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/section-divs.md b/documents/markdown/pandoc-md/section-divs.md
new file mode 100644
index 0000000..5ee28bb
--- /dev/null
+++ b/documents/markdown/pandoc-md/section-divs.md
@@ -0,0 +1,25 @@
+```
+% pandoc --section-divs
+::: {#hi .section .level1}
+# Hi
+
+::: {#there .section .level2}
+## there
+:::
+:::
+
+::: {#ok .section .level1}
+Ok
+==
+:::
+^D
+<section id="hi" class="level1">
+<h1>Hi</h1>
+<section id="there" class="level2">
+<h2>there</h2>
+</section>
+</section>
+<section id="ok" class="level1">
+<h1>Ok</h1>
+</section>
+```
diff --git a/documents/markdown/pandoc-md/setext-fenced-div.md b/documents/markdown/pandoc-md/setext-fenced-div.md
new file mode 100644
index 0000000..3494cbf
--- /dev/null
+++ b/documents/markdown/pandoc-md/setext-fenced-div.md
@@ -0,0 +1,8 @@
+```
+% pandoc -t native
+::: {.cell}
+---
+:::
+^D
+[ Div ( "" , [ "cell" ] , [] ) [ HorizontalRule ] ]
+```
diff --git a/documents/markdown/pandoc-md/shift-heading-level-by.md b/documents/markdown/pandoc-md/shift-heading-level-by.md
new file mode 100644
index 0000000..1ce9669
--- /dev/null
+++ b/documents/markdown/pandoc-md/shift-heading-level-by.md
@@ -0,0 +1,59 @@
+```
+% pandoc --shift-heading-level-by 1 -t native -s
+---
+title: My title
+...
+
+# First heading
+
+## Second
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "title"
+ , MetaInlines [ Str "My" , Space , Str "title" ]
+ )
+ ]
+ }
+ [ Header
+ 2
+ ( "first-heading" , [] , [] )
+ [ Str "First" , Space , Str "heading" ]
+ , Header 3 ( "second" , [] , [] ) [ Str "Second" ]
+ ]
+```
+
+```
+% pandoc --shift-heading-level-by -1 -t native -s
+---
+title: Old title
+...
+
+# First heading
+
+## Second
+
+# Another top-level heading
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "title"
+ , MetaInlines [ Str "First" , Space , Str "heading" ]
+ )
+ ]
+ }
+ [ Header 1 ( "second" , [] , [] ) [ Str "Second" ]
+ , Para
+ [ Str "Another"
+ , Space
+ , Str "top-level"
+ , Space
+ , Str "heading"
+ ]
+ ]
+```
+
diff --git a/documents/markdown/pandoc-md/short-caption.md b/documents/markdown/pandoc-md/short-caption.md
new file mode 100644
index 0000000..0fb7129
--- /dev/null
+++ b/documents/markdown/pandoc-md/short-caption.md
@@ -0,0 +1,42 @@
+```
+% pandoc -f latex -t native
+\begin{table}
+\caption[short caption]{long caption}
+\begin{tabular}{ll}
+hi & hi \\
+\end{tabular}
+\end{table}
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption
+ (Just [ Str "short" , Space , Str "caption" ])
+ [ Plain [ Str "long" , Space , Str "caption" ] ])
+ [ ( AlignLeft , ColWidthDefault )
+ , ( AlignLeft , ColWidthDefault )
+ ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "hi" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "hi" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
diff --git a/documents/markdown/pandoc-md/sloppypar.md b/documents/markdown/pandoc-md/sloppypar.md
new file mode 100644
index 0000000..44ec93a
--- /dev/null
+++ b/documents/markdown/pandoc-md/sloppypar.md
@@ -0,0 +1,229 @@
+```
+% pandoc -f latex+raw_tex -t native
+\begin{sloppypar}
+Sequi id qui facere et incidunt ut. Et fuga ut voluptate enim qui. Odit unde magni ipsam dicta modi. Modi soluta velit est aut aut possimus.
+
+Qui et temporibus explicabo. Esse ab ut quidem. Vel qui perspiciatis quae odio consectetur alias non sed. Quo consectetur libero omnis quos eius ad vel.
+\end{sloppypar}
+^D
+[ Para
+ [ Str "Sequi"
+ , Space
+ , Str "id"
+ , Space
+ , Str "qui"
+ , Space
+ , Str "facere"
+ , Space
+ , Str "et"
+ , Space
+ , Str "incidunt"
+ , Space
+ , Str "ut."
+ , Space
+ , Str "Et"
+ , Space
+ , Str "fuga"
+ , Space
+ , Str "ut"
+ , Space
+ , Str "voluptate"
+ , Space
+ , Str "enim"
+ , Space
+ , Str "qui."
+ , Space
+ , Str "Odit"
+ , Space
+ , Str "unde"
+ , Space
+ , Str "magni"
+ , Space
+ , Str "ipsam"
+ , Space
+ , Str "dicta"
+ , Space
+ , Str "modi."
+ , Space
+ , Str "Modi"
+ , Space
+ , Str "soluta"
+ , Space
+ , Str "velit"
+ , Space
+ , Str "est"
+ , Space
+ , Str "aut"
+ , Space
+ , Str "aut"
+ , Space
+ , Str "possimus."
+ ]
+, Para
+ [ Str "Qui"
+ , Space
+ , Str "et"
+ , Space
+ , Str "temporibus"
+ , Space
+ , Str "explicabo."
+ , Space
+ , Str "Esse"
+ , Space
+ , Str "ab"
+ , Space
+ , Str "ut"
+ , Space
+ , Str "quidem."
+ , Space
+ , Str "Vel"
+ , Space
+ , Str "qui"
+ , Space
+ , Str "perspiciatis"
+ , Space
+ , Str "quae"
+ , Space
+ , Str "odio"
+ , Space
+ , Str "consectetur"
+ , Space
+ , Str "alias"
+ , Space
+ , Str "non"
+ , Space
+ , Str "sed."
+ , Space
+ , Str "Quo"
+ , Space
+ , Str "consectetur"
+ , Space
+ , Str "libero"
+ , Space
+ , Str "omnis"
+ , Space
+ , Str "quos"
+ , Space
+ , Str "eius"
+ , Space
+ , Str "ad"
+ , Space
+ , Str "vel."
+ ]
+]
+```
+
+```
+% pandoc -f latex -t native
+\begin{sloppypar}
+Sequi id qui facere et incidunt ut. Et fuga ut voluptate enim qui. Odit unde magni ipsam dicta modi. Modi soluta velit est aut aut possimus.
+
+Qui et temporibus explicabo. Esse ab ut quidem. Vel qui perspiciatis quae odio consectetur alias non sed. Quo consectetur libero omnis quos eius ad vel.
+\end{sloppypar}
+^D
+[ Para
+ [ Str "Sequi"
+ , Space
+ , Str "id"
+ , Space
+ , Str "qui"
+ , Space
+ , Str "facere"
+ , Space
+ , Str "et"
+ , Space
+ , Str "incidunt"
+ , Space
+ , Str "ut."
+ , Space
+ , Str "Et"
+ , Space
+ , Str "fuga"
+ , Space
+ , Str "ut"
+ , Space
+ , Str "voluptate"
+ , Space
+ , Str "enim"
+ , Space
+ , Str "qui."
+ , Space
+ , Str "Odit"
+ , Space
+ , Str "unde"
+ , Space
+ , Str "magni"
+ , Space
+ , Str "ipsam"
+ , Space
+ , Str "dicta"
+ , Space
+ , Str "modi."
+ , Space
+ , Str "Modi"
+ , Space
+ , Str "soluta"
+ , Space
+ , Str "velit"
+ , Space
+ , Str "est"
+ , Space
+ , Str "aut"
+ , Space
+ , Str "aut"
+ , Space
+ , Str "possimus."
+ ]
+, Para
+ [ Str "Qui"
+ , Space
+ , Str "et"
+ , Space
+ , Str "temporibus"
+ , Space
+ , Str "explicabo."
+ , Space
+ , Str "Esse"
+ , Space
+ , Str "ab"
+ , Space
+ , Str "ut"
+ , Space
+ , Str "quidem."
+ , Space
+ , Str "Vel"
+ , Space
+ , Str "qui"
+ , Space
+ , Str "perspiciatis"
+ , Space
+ , Str "quae"
+ , Space
+ , Str "odio"
+ , Space
+ , Str "consectetur"
+ , Space
+ , Str "alias"
+ , Space
+ , Str "non"
+ , Space
+ , Str "sed."
+ , Space
+ , Str "Quo"
+ , Space
+ , Str "consectetur"
+ , Space
+ , Str "libero"
+ , Space
+ , Str "omnis"
+ , Space
+ , Str "quos"
+ , Space
+ , Str "eius"
+ , Space
+ , Str "ad"
+ , Space
+ , Str "vel."
+ ]
+]
+```
diff --git a/documents/markdown/pandoc-md/smart.md b/documents/markdown/pandoc-md/smart.md
new file mode 100644
index 0000000..e64d67d
--- /dev/null
+++ b/documents/markdown/pandoc-md/smart.md
@@ -0,0 +1,45 @@
+```
+% pandoc -f markdown+smart -t markdown-smart
+"hi"...dog's breath---cat 5--6
+^D
+“hi”…dog’s breath—cat 5–6
+```
+
+```
+% pandoc -f markdown+smart -t markdown+smart
+"hi"...dog's breath---cat 5--6
+^D
+"hi"...dog's breath---cat 5--6
+```
+
+When we render literal quotes without smart, we need to escape:
+
+```
+% pandoc -f markdown-smart \
+ -t markdown+smart
+"hi"...dog's breath---cat 5--6
+^D
+\"hi\"\...dog\'s breath\-\--cat 5\--6
+```
+
+```
+% pandoc -f markdown+smart -t rst-smart
+"hi"...dog's breath---cat 5--6
+^D
+“hi”…dog’s breath—cat 5–6
+```
+
+```
+% pandoc -f markdown+smart -t rst+smart
+"hi"...dog's breath---cat 5--6
+^D
+"hi"...dog's breath---cat 5--6
+```
+
+```
+% pandoc -f markdown-smart -t rst+smart
+"hi"...dog's breath---cat 5--6
+^D
+\"hi\"\...dog\'s breath\-\--cat 5\--6
+```
+
diff --git a/documents/markdown/pandoc-md/students.md b/documents/markdown/pandoc-md/students.md
new file mode 100644
index 0000000..fac8653
--- /dev/null
+++ b/documents/markdown/pandoc-md/students.md
@@ -0,0 +1,23 @@
++-----------------------------------------+-----------------------------------------+
+| Student ID | Name |
++:========================================+:========================================+
+| Computer Science |
++-----------------------------------------+-----------------------------------------+
+| 3741255 | Jones, Martha |
++-----------------------------------------+-----------------------------------------+
+| 4077830 | Pierce, Benjamin |
++-----------------------------------------+-----------------------------------------+
+| 5151701 | Kirk, James |
++-----------------------------------------+-----------------------------------------+
+| Russian Literature |
++-----------------------------------------+-----------------------------------------+
+| 3971244 | Nim, Victor |
++-----------------------------------------+-----------------------------------------+
+| Astrophysics |
++-----------------------------------------+-----------------------------------------+
+| 4100332 | Petrov, Alexandra |
++-----------------------------------------+-----------------------------------------+
+| 4100332 | Toyota, Hiroko |
++-----------------------------------------+-----------------------------------------+
+
+: List of Students {#students source="mdn"}
diff --git a/documents/markdown/pandoc-md/svg.md b/documents/markdown/pandoc-md/svg.md
new file mode 100644
index 0000000..74a2a1e
--- /dev/null
+++ b/documents/markdown/pandoc-md/svg.md
@@ -0,0 +1,134 @@
+```
+% pandoc -f latex -t icml
+\includegraphics{command/corrupt.svg}
+^D
+2> [WARNING] Could not determine image size for command/corrupt.svg: could not determine image type
+<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Paragraph">
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <Rectangle Self="uec" StrokeWeight="0" ItemTransform="1 0 0 1 150 -100">
+ <Properties>
+ <PathGeometry>
+ <GeometryPathType PathOpen="false">
+ <PathPointArray>
+ <PathPointType Anchor="-150 -100" LeftDirection="-150 -100" RightDirection="-150 -100" />
+ <PathPointType Anchor="-150 100" LeftDirection="-150 100" RightDirection="-150 100" />
+ <PathPointType Anchor="150 100" LeftDirection="150 100" RightDirection="150 100" />
+ <PathPointType Anchor="150 -100" LeftDirection="150 -100" RightDirection="150 -100" />
+ </PathPointArray>
+ </GeometryPathType>
+ </PathGeometry>
+ </Properties>
+ <Image Self="ue6" ItemTransform="1 0 0 1 -150 -100">
+ <Properties>
+ <Profile type="string">
+ $ID/Embedded
+ </Profile>
+ <GraphicBounds Left="0" Top="0" Right="300" Bottom="200" />
+ </Properties>
+ <Link Self="ueb" LinkResourceURI="file:command/corrupt.svg" />
+ </Image>
+ </Rectangle>
+ </CharacterStyleRange>
+</ParagraphStyleRange>
+```
+
+```
+% pandoc -f latex -t icml
+\includegraphics{command/SVG_logo.svg}
+^D
+<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Paragraph">
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <Rectangle Self="uec" StrokeWeight="0" ItemTransform="1 0 0 1 37.5 -37.5">
+ <Properties>
+ <PathGeometry>
+ <GeometryPathType PathOpen="false">
+ <PathPointArray>
+ <PathPointType Anchor="-37.5 -37.5" LeftDirection="-37.5 -37.5" RightDirection="-37.5 -37.5" />
+ <PathPointType Anchor="-37.5 37.5" LeftDirection="-37.5 37.5" RightDirection="-37.5 37.5" />
+ <PathPointType Anchor="37.5 37.5" LeftDirection="37.5 37.5" RightDirection="37.5 37.5" />
+ <PathPointType Anchor="37.5 -37.5" LeftDirection="37.5 -37.5" RightDirection="37.5 -37.5" />
+ </PathPointArray>
+ </GeometryPathType>
+ </PathGeometry>
+ </Properties>
+ <Image Self="ue6" ItemTransform="1 0 0 1 -37.5 -37.5">
+ <Properties>
+ <Profile type="string">
+ $ID/Embedded
+ </Profile>
+ <GraphicBounds Left="0" Top="0" Right="75" Bottom="75" />
+ </Properties>
+ <Link Self="ueb" LinkResourceURI="file:command/SVG_logo.svg" />
+ </Image>
+ </Rectangle>
+ </CharacterStyleRange>
+</ParagraphStyleRange>
+```
+
+```
+% pandoc -f latex -t icml
+\includegraphics{command/SVG_logo-without-xml-declaration.svg}
+^D
+<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Paragraph">
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <Rectangle Self="uec" StrokeWeight="0" ItemTransform="1 0 0 1 37.5 -37.5">
+ <Properties>
+ <PathGeometry>
+ <GeometryPathType PathOpen="false">
+ <PathPointArray>
+ <PathPointType Anchor="-37.5 -37.5" LeftDirection="-37.5 -37.5" RightDirection="-37.5 -37.5" />
+ <PathPointType Anchor="-37.5 37.5" LeftDirection="-37.5 37.5" RightDirection="-37.5 37.5" />
+ <PathPointType Anchor="37.5 37.5" LeftDirection="37.5 37.5" RightDirection="37.5 37.5" />
+ <PathPointType Anchor="37.5 -37.5" LeftDirection="37.5 -37.5" RightDirection="37.5 -37.5" />
+ </PathPointArray>
+ </GeometryPathType>
+ </PathGeometry>
+ </Properties>
+ <Image Self="ue6" ItemTransform="1 0 0 1 -37.5 -37.5">
+ <Properties>
+ <Profile type="string">
+ $ID/Embedded
+ </Profile>
+ <GraphicBounds Left="0" Top="0" Right="75" Bottom="75" />
+ </Properties>
+ <Link Self="ueb" LinkResourceURI="file:command/SVG_logo-without-xml-declaration.svg" />
+ </Image>
+ </Rectangle>
+ </CharacterStyleRange>
+</ParagraphStyleRange>
+```
+
+
+```
+% pandoc -f latex -t icml
+\includegraphics{command/inkscape-cube.svg}
+^D
+<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Paragraph">
+ <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
+ <Rectangle Self="uec" StrokeWeight="0" ItemTransform="1 0 0 1 54.75 -65.25">
+ <Properties>
+ <PathGeometry>
+ <GeometryPathType PathOpen="false">
+ <PathPointArray>
+ <PathPointType Anchor="-54.75 -65.25" LeftDirection="-54.75 -65.25" RightDirection="-54.75 -65.25" />
+ <PathPointType Anchor="-54.75 65.25" LeftDirection="-54.75 65.25" RightDirection="-54.75 65.25" />
+ <PathPointType Anchor="54.75 65.25" LeftDirection="54.75 65.25" RightDirection="54.75 65.25" />
+ <PathPointType Anchor="54.75 -65.25" LeftDirection="54.75 -65.25" RightDirection="54.75 -65.25" />
+ </PathPointArray>
+ </GeometryPathType>
+ </PathGeometry>
+ </Properties>
+ <Image Self="ue6" ItemTransform="1 0 0 1 -54.75 -65.25">
+ <Properties>
+ <Profile type="string">
+ $ID/Embedded
+ </Profile>
+ <GraphicBounds Left="0" Top="0" Right="109.5" Bottom="130.5" />
+ </Properties>
+ <Link Self="ueb" LinkResourceURI="file:command/inkscape-cube.svg" />
+ </Image>
+ </Rectangle>
+ </CharacterStyleRange>
+</ParagraphStyleRange>
+```
+
diff --git a/documents/markdown/pandoc-md/table-with-cell-align.md b/documents/markdown/pandoc-md/table-with-cell-align.md
new file mode 100644
index 0000000..ccf119c
--- /dev/null
+++ b/documents/markdown/pandoc-md/table-with-cell-align.md
@@ -0,0 +1,105 @@
+```
+% pandoc -f docbook -t native --quiet
+<informaltable frame="all" rowsep="1" colsep="1">
+<tgroup cols="16">
+<tbody>
+<row>
+<entry align="center" valign="top"><simpara>1</simpara></entry>
+<entry align="left" valign="top"><simpara>2</simpara></entry>
+<entry align="right" valign="top"><simpara>3</simpara></entry>
+<entry align="justify" valign="top"><simpara>4</simpara></entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ , ( AlignDefault , ColWidthDefault )
+ ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignLeft
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignRight
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "3" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "4" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
+```
+% pandoc -f native -t opendocument --quiet
+[Table ("",[],[]) (Caption Nothing
+ [])
+ [(AlignDefault,ColWidthDefault)
+ ,(AlignDefault,ColWidthDefault)
+ ,(AlignDefault,ColWidthDefault)
+ ,(AlignDefault,ColWidthDefault)]
+ (TableHead ("",[],[])
+ [])
+ [(TableBody ("",[],[]) (RowHeadColumns 0)
+ []
+ [Row ("",[],[])
+ [Cell ("",[],[]) AlignCenter (RowSpan 1) (ColSpan 1)
+ [Para [Str "1"]]
+ ,Cell ("",[],[]) AlignLeft (RowSpan 1) (ColSpan 1)
+ [Para [Str "2"]]
+ ,Cell ("",[],[]) AlignRight (RowSpan 1) (ColSpan 1)
+ [Para [Str "3"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Para [Str "4"]]]])]
+ (TableFoot ("",[],[])
+ [])]
+^D
+<table:table table:name="Table1" table:style-name="Table1">
+ <table:table-column table:style-name="Table1.A" />
+ <table:table-column table:style-name="Table1.B" />
+ <table:table-column table:style-name="Table1.C" />
+ <table:table-column table:style-name="Table1.D" />
+ <table:table-row>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="P1">1</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">2</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="P2">3</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">4</text:p>
+ </table:table-cell>
+ </table:table-row>
+</table:table>
+```
diff --git a/documents/markdown/pandoc-md/table-with-column-span.md b/documents/markdown/pandoc-md/table-with-column-span.md
new file mode 100644
index 0000000..d4e8beb
--- /dev/null
+++ b/documents/markdown/pandoc-md/table-with-column-span.md
@@ -0,0 +1,385 @@
+```
+% pandoc -f docbook -t native --quiet
+<informaltable frame="all" rowsep="1" colsep="1">
+<tgroup cols="16">
+<colspec colname="col_1" colwidth="6.25*"/>
+<colspec colname="col_2" colwidth="6.25*"/>
+<colspec colname="col_3" colwidth="6.25*"/>
+<colspec colname="col_4" colwidth="6.25*"/>
+<colspec colname="col_5" colwidth="6.25*"/>
+<colspec colname="col_6" colwidth="6.25*"/>
+<colspec colname="col_7" colwidth="6.25*"/>
+<colspec colname="col_8" colwidth="6.25*"/>
+<colspec colname="col_9" colwidth="6.25*"/>
+<colspec colname="col_10" colwidth="6.25*"/>
+<colspec colname="col_11" colwidth="6.25*"/>
+<colspec colname="col_12" colwidth="6.25*"/>
+<colspec colname="col_13" colwidth="6.25*"/>
+<colspec colname="col_14" colwidth="6.25*"/>
+<colspec colname="col_15" colwidth="6.25*"/>
+<colspec colname="col_16" colwidth="6.25*"/>
+<tbody>
+<row>
+<entry align="center" valign="top" namest="col_1" nameend="col_8"><simpara><emphasis role="strong">Octet no. 1</emphasis></simpara></entry>
+<entry align="center" valign="top" namest="col_2" nameend="col_9"><simpara><emphasis role="strong">Octet no. 2</emphasis></simpara></entry>
+</row>
+<row>
+<entry align="center" valign="top"><simpara>16</simpara></entry>
+<entry align="center" valign="top"><simpara>15</simpara></entry>
+<entry align="center" valign="top"><simpara>14</simpara></entry>
+<entry align="center" valign="top"><simpara>13</simpara></entry>
+<entry align="center" valign="top"><simpara>12</simpara></entry>
+<entry align="center" valign="top"><simpara>11</simpara></entry>
+<entry align="center" valign="top"><simpara>10</simpara></entry>
+<entry align="center" valign="top"><simpara>9</simpara></entry>
+<entry align="center" valign="top"><simpara>8</simpara></entry>
+<entry align="center" valign="top"><simpara>7</simpara></entry>
+<entry align="center" valign="top"><simpara>6</simpara></entry>
+<entry align="center" valign="top"><simpara>5</simpara></entry>
+<entry align="center" valign="top"><simpara>4</simpara></entry>
+<entry align="center" valign="top"><simpara>3</simpara></entry>
+<entry align="center" valign="top"><simpara>2</simpara></entry>
+<entry align="center" valign="top"><simpara>1</simpara></entry>
+</row>
+<row>
+<entry align="center" valign="top" namest="col_1" nameend="col_8"><simpara>Code A</simpara></entry>
+<entry align="center" valign="top" namest="col_2" nameend="col_9"><simpara>Code B</simpara></entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignDefault , ColWidth 6.25e-2 )
+ , ( AlignDefault , ColWidth 6.25e-2 )
+ , ( AlignDefault , ColWidth 6.25e-2 )
+ , ( AlignDefault , ColWidth 6.25e-2 )
+ , ( AlignDefault , ColWidth 6.25e-2 )
+ , ( AlignDefault , ColWidth 6.25e-2 )
+ , ( AlignDefault , ColWidth 6.25e-2 )
+ , ( AlignDefault , ColWidth 6.25e-2 )
+ , ( AlignDefault , ColWidth 6.25e-2 )
+ , ( AlignDefault , ColWidth 6.25e-2 )
+ , ( AlignDefault , ColWidth 6.25e-2 )
+ , ( AlignDefault , ColWidth 6.25e-2 )
+ , ( AlignDefault , ColWidth 6.25e-2 )
+ , ( AlignDefault , ColWidth 6.25e-2 )
+ , ( AlignDefault , ColWidth 6.25e-2 )
+ , ( AlignDefault , ColWidth 6.25e-2 )
+ ]
+ (TableHead ( "" , [] , [] ) [])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 8)
+ [ Para
+ [ Strong
+ [ Str "Octet"
+ , Space
+ , Str "no."
+ , Space
+ , Str "1"
+ ]
+ ]
+ ]
+ , Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 8)
+ [ Para
+ [ Strong
+ [ Str "Octet"
+ , Space
+ , Str "no."
+ , Space
+ , Str "2"
+ ]
+ ]
+ ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "16" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "15" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "14" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "13" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "12" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "11" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "10" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "9" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "8" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "7" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "6" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "5" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "4" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "3" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Para [ Str "1" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 8)
+ [ Para [ Str "Code" , Space , Str "A" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignCenter
+ (RowSpan 1)
+ (ColSpan 8)
+ [ Para [ Str "Code" , Space , Str "B" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
+```
+% pandoc -f native -t opendocument --quiet
+[Table ("",[],[]) (Caption Nothing
+ [])
+ [(AlignDefault,ColWidth 6.25e-2)
+ ,(AlignDefault,ColWidth 6.25e-2)
+ ,(AlignDefault,ColWidth 6.25e-2)
+ ,(AlignDefault,ColWidth 6.25e-2)
+ ,(AlignDefault,ColWidth 6.25e-2)
+ ,(AlignDefault,ColWidth 6.25e-2)
+ ,(AlignDefault,ColWidth 6.25e-2)
+ ,(AlignDefault,ColWidth 6.25e-2)
+ ,(AlignDefault,ColWidth 6.25e-2)
+ ,(AlignDefault,ColWidth 6.25e-2)
+ ,(AlignDefault,ColWidth 6.25e-2)
+ ,(AlignDefault,ColWidth 6.25e-2)
+ ,(AlignDefault,ColWidth 6.25e-2)
+ ,(AlignDefault,ColWidth 6.25e-2)
+ ,(AlignDefault,ColWidth 6.25e-2)
+ ,(AlignDefault,ColWidth 6.25e-2)]
+ (TableHead ("",[],[])
+ [])
+ [(TableBody ("",[],[]) (RowHeadColumns 0)
+ []
+ [Row ("",[],[])
+ [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 8)
+ [Para [Strong [Str "Octet",Space,Str "no.",Space,Str "1"]]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 8)
+ [Para [Strong [Str "Octet",Space,Str "no.",Space,Str "2"]]]]
+ ,Row ("",[],[])
+ [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Para [Str "16"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Para [Str "15"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Para [Str "14"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Para [Str "13"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Para [Str "12"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Para [Str "11"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Para [Str "10"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Para [Str "9"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Para [Str "8"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Para [Str "7"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Para [Str "6"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Para [Str "5"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Para [Str "4"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Para [Str "3"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Para [Str "2"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 1)
+ [Para [Str "1"]]]
+ ,Row ("",[],[])
+ [Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 8)
+ [Para [Str "Code",Space,Str "A"]]
+ ,Cell ("",[],[]) AlignDefault (RowSpan 1) (ColSpan 8)
+ [Para [Str "Code",Space,Str "B"]]]])]
+ (TableFoot ("",[],[])
+ [])]
+^D
+<table:table table:name="Table1" table:style-name="Table1">
+ <table:table-column table:style-name="Table1.A" />
+ <table:table-column table:style-name="Table1.B" />
+ <table:table-column table:style-name="Table1.C" />
+ <table:table-column table:style-name="Table1.D" />
+ <table:table-column table:style-name="Table1.E" />
+ <table:table-column table:style-name="Table1.F" />
+ <table:table-column table:style-name="Table1.G" />
+ <table:table-column table:style-name="Table1.H" />
+ <table:table-column table:style-name="Table1.I" />
+ <table:table-column table:style-name="Table1.J" />
+ <table:table-column table:style-name="Table1.K" />
+ <table:table-column table:style-name="Table1.L" />
+ <table:table-column table:style-name="Table1.M" />
+ <table:table-column table:style-name="Table1.N" />
+ <table:table-column table:style-name="Table1.O" />
+ <table:table-column table:style-name="Table1.P" />
+ <table:table-row>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string" table:number-columns-spanned="8">
+ <text:p text:style-name="Table_20_Contents"><text:span text:style-name="T1">Octet
+ no. 1</text:span></text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string" table:number-columns-spanned="8">
+ <text:p text:style-name="Table_20_Contents"><text:span text:style-name="T1">Octet
+ no. 2</text:span></text:p>
+ </table:table-cell>
+ </table:table-row>
+ <table:table-row>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">16</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">15</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">14</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">13</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">12</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">11</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">10</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">9</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">8</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">7</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">6</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">5</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">4</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">3</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">2</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string">
+ <text:p text:style-name="Table_20_Contents">1</text:p>
+ </table:table-cell>
+ </table:table-row>
+ <table:table-row>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string" table:number-columns-spanned="8">
+ <text:p text:style-name="Table_20_Contents">Code A</text:p>
+ </table:table-cell>
+ <table:table-cell table:style-name="TableRowCell" office:value-type="string" table:number-columns-spanned="8">
+ <text:p text:style-name="Table_20_Contents">Code B</text:p>
+ </table:table-cell>
+ </table:table-row>
+</table:table>
+```
diff --git a/documents/markdown/pandoc-md/tables.md b/documents/markdown/pandoc-md/tables.md
new file mode 100644
index 0000000..97ffd82
--- /dev/null
+++ b/documents/markdown/pandoc-md/tables.md
@@ -0,0 +1,76 @@
+Simple table with caption:
+
+ Right Left Center Default
+ ------- ------ -------- ---------
+ 12 12 12 12
+ 123 123 123 123
+ 1 1 1 1
+
+ : Demonstration of simple table syntax.
+
+Simple table without caption:
+
+ Right Left Center Default
+ ------- ------ -------- ---------
+ 12 12 12 12
+ 123 123 123 123
+ 1 1 1 1
+
+Simple table indented two spaces:
+
+ Right Left Center Default
+ ------- ------ -------- ---------
+ 12 12 12 12
+ 123 123 123 123
+ 1 1 1 1
+
+ : Demonstration of simple table syntax.
+
+Multiline table with caption:
+
+ ---------------------------------------------------------------
+ Centered Left Right Default aligned
+ Header Aligned Aligned
+ ----------- ---------- ------------ ---------------------------
+ First row 12.0 Example of a row that spans
+ multiple lines.
+
+ Second row 5.0 Here's another one. Note
+ the blank line between
+ rows.
+ ---------------------------------------------------------------
+
+ : Here's the caption. It may span multiple lines.
+
+Multiline table without caption:
+
+ ---------------------------------------------------------------
+ Centered Left Right Default aligned
+ Header Aligned Aligned
+ ----------- ---------- ------------ ---------------------------
+ First row 12.0 Example of a row that spans
+ multiple lines.
+
+ Second row 5.0 Here's another one. Note
+ the blank line between
+ rows.
+ ---------------------------------------------------------------
+
+Table without column headers:
+
+ ----- ----- ----- -----
+ 12 12 12 12
+ 123 123 123 123
+ 1 1 1 1
+ ----- ----- ----- -----
+
+Multiline table without column headers:
+
+ ----------- ---------- ------------ ---------------------------
+ First row 12.0 Example of a row that spans
+ multiple lines.
+
+ Second row 5.0 Here's another one. Note
+ the blank line between
+ rows.
+ ----------- ---------- ------------ ---------------------------
diff --git a/documents/markdown/pandoc-md/tabularx.md b/documents/markdown/pandoc-md/tabularx.md
new file mode 100644
index 0000000..3997417
--- /dev/null
+++ b/documents/markdown/pandoc-md/tabularx.md
@@ -0,0 +1,440 @@
+```
+% pandoc -f latex -t native --quiet
+\begin{tabularx}{\linewidth}{|c|c|c|}
+\hline
+ Column Heading 1
+ & Column Heading 2
+ & Column Heading 3 \\
+\hline
+ Cell 1.1
+ & Cell 1.2
+ & Cell 1.3 \\
+\hline
+ Cell 2.1
+ & Cell 2.2
+ & Cell 2.3 \\
+\hline
+ Cell 3.1
+ & Cell 3.2
+ & Cell 3.3 \\
+\hline
+\end{tabularx}
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignCenter , ColWidthDefault )
+ , ( AlignCenter , ColWidthDefault )
+ , ( AlignCenter , ColWidthDefault )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain
+ [ Str "Column"
+ , Space
+ , Str "Heading"
+ , Space
+ , Str "1"
+ ]
+ ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain
+ [ Str "Column"
+ , Space
+ , Str "Heading"
+ , Space
+ , Str "2"
+ ]
+ ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain
+ [ Str "Column"
+ , Space
+ , Str "Heading"
+ , Space
+ , Str "3"
+ ]
+ ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "1.1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "1.2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "1.3" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "2.1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "2.2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "2.3" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "3.1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "3.2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "3.3" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
+
+```
+% pandoc -f latex -t native --quiet
+\begin{tabularx}{\linewidth}{|X|c|p{0.25\linewidth}|}
+\hline
+ Column Heading 1
+ & Column Heading 2
+ & Column Heading 3 \\
+\hline
+ Cell 1.1
+ & Cell 1.2
+ & Cell 1.3 \\
+\hline
+ Cell 2.1
+ & Cell 2.2
+ & Cell 2.3 \\
+\hline
+ Cell 3.1
+ & Cell 3.2
+ & Cell 3.3 \\
+\hline
+\end{tabularx}
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignLeft , ColWidthDefault )
+ , ( AlignCenter , ColWidthDefault )
+ , ( AlignLeft , ColWidth 0.25 )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain
+ [ Str "Column"
+ , Space
+ , Str "Heading"
+ , Space
+ , Str "1"
+ ]
+ ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain
+ [ Str "Column"
+ , Space
+ , Str "Heading"
+ , Space
+ , Str "2"
+ ]
+ ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain
+ [ Str "Column"
+ , Space
+ , Str "Heading"
+ , Space
+ , Str "3"
+ ]
+ ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "1.1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "1.2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "1.3" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "2.1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "2.2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "2.3" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "3.1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "3.2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "3.3" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
+
+```
+% pandoc -f latex -t native --quiet
+\begin{tabularx}{\linewidth}{|b{0.25\linewidth}|c|m{0.25\linewidth}|}
+\hline
+ Column Heading 1
+ & Column Heading 2
+ & Column Heading 3 \\
+\hline
+ Cell 1.1
+ & Cell 1.2
+ & Cell 1.3 \\
+\hline
+ Cell 2.1
+ & Cell 2.2
+ & Cell 2.3 \\
+\hline
+ Cell 3.1
+ & Cell 3.2
+ & Cell 3.3 \\
+\hline
+\end{tabularx}
+^D
+[ Table
+ ( "" , [] , [] )
+ (Caption Nothing [])
+ [ ( AlignLeft , ColWidth 0.25 )
+ , ( AlignCenter , ColWidthDefault )
+ , ( AlignLeft , ColWidth 0.25 )
+ ]
+ (TableHead
+ ( "" , [] , [] )
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain
+ [ Str "Column"
+ , Space
+ , Str "Heading"
+ , Space
+ , Str "1"
+ ]
+ ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain
+ [ Str "Column"
+ , Space
+ , Str "Heading"
+ , Space
+ , Str "2"
+ ]
+ ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain
+ [ Str "Column"
+ , Space
+ , Str "Heading"
+ , Space
+ , Str "3"
+ ]
+ ]
+ ]
+ ])
+ [ TableBody
+ ( "" , [] , [] )
+ (RowHeadColumns 0)
+ []
+ [ Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "1.1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "1.2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "1.3" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "2.1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "2.2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "2.3" ] ]
+ ]
+ , Row
+ ( "" , [] , [] )
+ [ Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "3.1" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "3.2" ] ]
+ , Cell
+ ( "" , [] , [] )
+ AlignDefault
+ (RowSpan 1)
+ (ColSpan 1)
+ [ Plain [ Str "Cell" , Space , Str "3.3" ] ]
+ ]
+ ]
+ ]
+ (TableFoot ( "" , [] , [] ) [])
+]
+```
diff --git a/documents/markdown/pandoc-md/tasklist.md b/documents/markdown/pandoc-md/tasklist.md
new file mode 100644
index 0000000..177845a
--- /dev/null
+++ b/documents/markdown/pandoc-md/tasklist.md
@@ -0,0 +1,105 @@
+tests adapted from <https://github.github.com/gfm/#task-list-items-extension->
+
+```
+% pandoc
+- [ ] foo
+- [x] bar
+^D
+<ul class="task-list">
+<li><label><input type="checkbox" />foo</label></li>
+<li><label><input type="checkbox" checked="" />bar</label></li>
+</ul>
+```
+
+
+```
+% pandoc
+- [x] foo
+ - [ ] bar
+ - [x] baz
+- [ ] bim
+^D
+<ul class="task-list">
+<li><label><input type="checkbox" checked="" />foo</label>
+<ul class="task-list">
+<li><label><input type="checkbox" />bar</label></li>
+<li><label><input type="checkbox" checked="" />baz</label></li>
+</ul></li>
+<li><label><input type="checkbox" />bim</label></li>
+</ul>
+```
+
+
+custom html task list test:
+
+```
+% pandoc
+- [ ] unchecked
+- plain item
+- [x] checked
+
+paragraph
+
+1. [ ] ordered unchecked
+2. [] plain item
+3. [x] ordered checked
+
+paragraph
+
+- [ ] list item with a
+
+ second paragraph
+
+- [x] checked
+^D
+<ul>
+<li><label><input type="checkbox" />unchecked</label></li>
+<li>plain item</li>
+<li><label><input type="checkbox" checked="" />checked</label></li>
+</ul>
+<p>paragraph</p>
+<ol type="1">
+<li><label><input type="checkbox" />ordered unchecked</label></li>
+<li>[] plain item</li>
+<li><label><input type="checkbox" checked="" />ordered
+checked</label></li>
+</ol>
+<p>paragraph</p>
+<ul class="task-list">
+<li><p><label><input type="checkbox" />list item with a</label></p>
+<p>second paragraph</p></li>
+<li><p><label><input type="checkbox"
+checked="" />checked</label></p></li>
+</ul>
+```
+
+latex task list test:
+
+```
+% pandoc -t latex
+- [ ] foo bar
+
+ baz
+
+- [x] ok
+^D
+\begin{itemize}
+\item[$\square$]
+ foo bar
+
+ baz
+\item[$\boxtimes$]
+ ok
+\end{itemize}
+```
+
+round trip:
+
+```
+% pandoc -f markdown -t markdown
+- [ ] foo
+- [x] bar
+^D
+- [ ] foo
+- [x] bar
+```
\ No newline at end of file
diff --git a/documents/markdown/pandoc-md/tex-group.md b/documents/markdown/pandoc-md/tex-group.md
new file mode 100644
index 0000000..cc0ed21
--- /dev/null
+++ b/documents/markdown/pandoc-md/tex-group.md
@@ -0,0 +1,12 @@
+```
+% pandoc -f latex -t html
+\newenvironment{foo}%
+{\emph\bgroup}%
+{\egroup}
+
+\begin{foo}
+hi
+\end{foo}
+^D
+<p><span> <em>hi</em> </span></p>
+```
diff --git a/documents/markdown/pandoc-md/text.md b/documents/markdown/pandoc-md/text.md
new file mode 100644
index 0000000..54f0104
--- /dev/null
+++ b/documents/markdown/pandoc-md/text.md
@@ -0,0 +1,17 @@
+# Chapter one
+
+A spider: 
+
+Another spider: ![another spider][refspider]
+
+The moon: 
+
+Link to [spider picture](spider.png).
+
+URL left alone: [manual](https://pandoc.org/MANUAL.html).
+
+Absolute path left alone: [absolute](/foo/bar/baz.png).
+
+Link to fragment: [chapter two](#chapter-two).
+
+Empty path: [empty]().
diff --git a/documents/markdown/pandoc-md/toc.md b/documents/markdown/pandoc-md/toc.md
new file mode 100644
index 0000000..e681e93
--- /dev/null
+++ b/documents/markdown/pandoc-md/toc.md
@@ -0,0 +1,47 @@
+```
+% pandoc -s --toc -t markdown
+# A
+## b
+# B
+## b
+
+::: interior
+# C
+## cc
+# D
+:::
+
+::: blue
+# E
+## e
+:::
+^D
+- [A](#a){#toc-a}
+ - [b](#b){#toc-b}
+- [B](#b-1){#toc-b-1}
+ - [b](#b-2){#toc-b-2}
+- [E](#e){#toc-e}
+ - [e](#e-1){#toc-e-1}
+
+# A
+
+## b
+
+# B
+
+## b
+
+::: interior
+# C
+
+## cc
+
+# D
+:::
+
+::: blue
+# E
+
+## e
+:::
+```
diff --git a/documents/markdown/pandoc-md/translations.md b/documents/markdown/pandoc-md/translations.md
new file mode 100644
index 0000000..613c29a
--- /dev/null
+++ b/documents/markdown/pandoc-md/translations.md
@@ -0,0 +1,29 @@
+```
+% pandoc -f latex -t native -M lang=en
+\figurename\ 2
+^D
+[ Para [ Str "Figure\160\&2" ] ]
+```
+
+```
+% pandoc -f latex -t native -M lang=de-DE
+\figurename\ 2
+^D
+[ Para [ Str "Abbildung\160\&2" ] ]
+```
+
+```
+% pandoc -f latex -t native -M lang=en
+\setmainlanguage{german}
+\figurename 2
+^D
+[ Para [ Str "Abbildung2" ] ]
+```
+
+```
+% pandoc -f latex -t native -M lang=sr-Latn
+\figurename~2
+\figurename.
+^D
+[ Para [ Str "Slika\160\&2" , SoftBreak , Str "Slika." ] ]
+```
diff --git a/documents/markdown/pandoc-md/typst-hs-80.md b/documents/markdown/pandoc-md/typst-hs-80.md
new file mode 100644
index 0000000..ed0e922
--- /dev/null
+++ b/documents/markdown/pandoc-md/typst-hs-80.md
@@ -0,0 +1,55 @@
+```
+% pandoc -f typst -t native -s
+#set document(
+ title: [My Title],
+)
+
+#title()
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "title"
+ , MetaInlines [ Str "My" , Space , Str "Title" ]
+ )
+ ]
+ }
+ []
+```
+
+```
+% pandoc -f typst -t native -s
+#set document(
+ title: [ignored],
+)
+
+#title[My Title]
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "title"
+ , MetaInlines [ Str "My" , Space , Str "Title" ]
+ )
+ ]
+ }
+ []
+```
+
+```
+% pandoc -f typst -t native -s
+#title[My Title]
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "title"
+ , MetaInlines [ Str "My" , Space , Str "Title" ]
+ )
+ ]
+ }
+ []
+```
diff --git a/documents/markdown/pandoc-md/typst-image-alt.md b/documents/markdown/pandoc-md/typst-image-alt.md
new file mode 100644
index 0000000..615c100
--- /dev/null
+++ b/documents/markdown/pandoc-md/typst-image-alt.md
@@ -0,0 +1,78 @@
+```
+% pandoc -f markdown-implicit_figures -t typst
+
+^D
+#box(image("image.png", alt: "Alt text from inlines"))
+```
+
+```
+% pandoc -f markdown-implicit_figures -t typst
+{alt="Explicit alt attribute"}
+^D
+#box(image("image.png", alt: "Explicit alt attribute"))
+```
+
+```
+% pandoc -f markdown-implicit_figures -t typst
+{alt="Explicit wins"}
+^D
+#box(image("image.png", alt: "Explicit wins"))
+```
+
+```
+% pandoc -f markdown-implicit_figures -t typst
+
+^D
+#box(image("image.png"))
+```
+
+```
+% pandoc -f markdown-implicit_figures -t typst
+{alt=""}
+^D
+#box(image("image.png"))
+```
+
+```
+% pandoc -t typst
+{alt="Alt text describing the image"}
+
+^D
+#figure(image("image.png", alt: "Alt text describing the image"),
+ caption: [
+ Caption text
+ ]
+)
+```
+
+```
+% pandoc -t typst
+
+
+^D
+#figure(image("image.png", alt: "Caption only"),
+ caption: [
+ Caption only
+ ]
+)
+```
+
+```
+% pandoc -f markdown -t typst
+{alt="A \"quoted\" phrase and C:\\path\\file"}
+^D
+#figure(image("test.png", alt: "A \"quoted\" phrase and C:\\path\\file"),
+ caption: [
+ Caption
+ ]
+)
+
+```
+
+```
+% pandoc -f html -t typst
+<img src="data:image/png;base64,iVBORw0KGgo=" alt="A small red dot">
+^D
+#box(image(bytes((137,80,78,71,13,10,26,10)), alt: "A small red dot"))
+
+```
diff --git a/documents/markdown/pandoc-md/typst-images.md b/documents/markdown/pandoc-md/typst-images.md
new file mode 100644
index 0000000..4541087
--- /dev/null
+++ b/documents/markdown/pandoc-md/typst-images.md
@@ -0,0 +1,32 @@
+```
+% pandoc -t typst
+{width=1in}
+^D
+#figure(image(bytes((137,80,78,71,13,10,26,10,0,0,0,13,73,72,68,82,0,0,0,10,0,0,0,10,8,6,0,0,0,141,50,207,189,0,0,0,9,112,72,89,115,0,0,46,35,0,0,46,35,1,120,165,63,118,0,0,0,73,73,68,65,84,24,25,173,206,91,10,0,32,8,4,64,215,251,223,217,52,18,53,66,127,18,130,30,211,42,136,72,116,141,197,163,56,160,64,145,8,207,123,179,5,118,233,255,33,180,93,12,214,244,230,123,232,151,53,179,19,29,3,118,140,202,247,165,181,63,56,205,31,23,32,166,25,1,179,208,168,31,0,0,0,0,73,69,78,68,174,66,96,130)), width: 1in, alt: "dot"),
+ caption: [
+ dot
+ ]
+)
+```
+
+```
+% pandoc -t typst
+{width="1in"}
+^D
+#figure(image("dot.png", width: 1in, alt: "dot"),
+ caption: [
+ dot
+ ]
+)
+```
+
+```
+% pandoc -t typst
+
+^D
+#figure(image(bytes("<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 100 100\" aria-label=\"Chicken\"> <path d=\"M76.5 33.3l-8.3-6.6 4-5c-1.3-2-1.3-4.7.1-6.6 3.4-3.8 8.7-2 10.2 2.2 4.5.7 7.5 5.4 4.4 9.4a5.7 5.7 0 01-6.4 1.6zM73 26.2l3 2.4 3.8-4.7c1.3 1 3.5 2 4.5.7 2.1-2.9-1.5-5.4-4.7-3.5 1.2-4.6-2.7-6.2-4.5-3.9-.7 2.2.2 3 1.7 4.2z\"/> <path d=\"M54 72.3a19.1 19.1 0 01-19.2-17.8 21.4 21.4 0 014.7-15.2c3.5-4.3 8.4-7.1 13.7-8l3.1-.1c8.2-.9 12.9-5.5 13-5.6l1-1 8.2 6.5-1 1.3c-3.3 4-2.8 11.3-2.5 14.2a21.5 21.5 0 01-4.4 17.5 21.2 21.2 0 01-16.5 8.2zM70.6 29a27 27 0 01-14 5.5l-3 .2a18 18 0 00-11.3 6.7 18 18 0 00-4 12.8 16 16 0 0015.9 14.7c5.4 0 10.4-2.5 14-6.9A18 18 0 0072 49.4c0-.8-.2-1.6-.3-2.2-.5-4-.7-10.7 2.1-15.5z\"/> <path d=\"M46 87C22.6 87 .5 87 .5 66.8c0-19 20.4-34.6 45.5-34.6 1.2 0 2.5 0 3.7.2 10.1.6 9.7-.1.5 3.2a18.3 18.3 0 00-12 18.6 16 16 0 0015.9 14.7c5.4 0 10.4-2.5 14-6.9A18 18 0 0072 49.4c-.6-4-.4-7.4-.2-11.3a35.8 35.8 0 0119.5 26A11.7 11.7 0 0187.8 87H46zm-2.8-51.3c-22 1-39.4 14.6-39.4 31 0 15.8 16 16.9 42.2 16.9h41.8c4.6 0 8.4-3.8 8.4-8.4-.4-4.8-3.2-7.7-8.1-8.4-.3-10.4-7.4-18.4-13.3-22.7.1 2 .5 4.3.7 6.1 0 5-1.6 10-4.8 14A21.2 21.2 0 0154 72.3a19.1 19.1 0 01-19.3-17.8 21.4 21.4 0 018.4-18.8z\"/> </svg>"), alt: "chicken"),
+ caption: [
+ chicken
+ ]
+)
+```
diff --git a/documents/markdown/pandoc-md/typst-property-output.md b/documents/markdown/pandoc-md/typst-property-output.md
new file mode 100644
index 0000000..e809e19
--- /dev/null
+++ b/documents/markdown/pandoc-md/typst-property-output.md
@@ -0,0 +1,232 @@
+```
+% pandoc -f html -t typst
+<span typst:text:fill="orange">foo</span>
+^D
+#text(fill: orange)[foo]
+```
+
+```
+% pandoc -f html -t typst
+<span>foo</span>
+^D
+foo
+```
+
+```
+% pandoc -f html -t typst
+<div typst:inset="10pt">foo</div>
+^D
+#block(inset: 10pt)[
+foo
+]
+```
+
+```
+% pandoc -f html -t typst
+<div typst:text:fill="purple">foo</div>
+^D
+#block[
+#set text(fill: purple); foo
+]
+```
+
+```
+% pandoc -f html -t typst
+<div>foo</div>
+^D
+#block[
+foo
+]
+```
+
+```
+% pandoc -f html -t typst
+<table typst:fill="blue">
+ <tr><td>A</td><td>B</td></tr>
+</table>
+^D
+#figure(
+ align(center)[#table(
+ columns: 2,
+ align: (auto,auto,),
+ fill: blue,
+ [A], [B],
+ )]
+ , kind: table
+ )
+```
+
+```
+% pandoc -f html -t typst
+<table typst:text:fill="orange">
+ <tr><td>A</td><td>B</td></tr>
+</table>
+^D
+#figure(
+ align(center)[#set text(fill: orange); #table(
+ columns: 2,
+ align: (auto,auto,),
+ [A], [B],
+ )]
+ , kind: table
+ )
+```
+
+```
+% pandoc -f html -t typst
+<table>
+ <tr><td>A</td><td typst:fill="green">B</td></tr>
+</table>
+^D
+#figure(
+ align(center)[#table(
+ columns: 2,
+ align: (auto,auto,),
+ [A], table.cell(fill: green)[B],
+ )]
+ , kind: table
+ )
+```
+
+```
+% pandoc -f html -t typst
+<table>
+ <tr><td>A</td><td typst:text:fill="fuchsia">B</td></tr>
+</table>
+^D
+#figure(
+ align(center)[#table(
+ columns: 2,
+ align: (auto,auto,),
+ [A], [#set text(fill: fuchsia); B],
+ )]
+ , kind: table
+ )
+```
+
+```
+% pandoc -f html -t typst
+<table>
+ <tr><td>A</td><td typst:text:fill="maroon" align="center">B</td></tr>
+</table>
+^D
+#figure(
+ align(center)[#table(
+ columns: 2,
+ align: (auto,center,),
+ [A], table.cell(align: center)[#set text(fill: maroon); B],
+ )]
+ , kind: table
+ )
+```
+
+```
+% pandoc -f html -t typst
+<table>
+ <tr><td>A</td><td typst:align="horizon" align="center">B</td></tr>
+</table>
+^D
+#figure(
+ align(center)[#table(
+ columns: 2,
+ align: (auto,center,),
+ [A], table.cell(align: horizon + center)[B],
+ )]
+ , kind: table
+ )
+```
+
+
+```
+% pandoc -f html -t typst
+<table>
+ <tr><td>A</td><td>B</td></tr>
+</table>
+^D
+#figure(
+ align(center)[#table(
+ columns: 2,
+ align: (auto,auto,),
+ [A], [B],
+ )]
+ , kind: table
+ )
+```
+
+```
+% pandoc -f html -t typst
+<p>Paragraph before.</p>
+
+<table class="typst:no-figure" typst:text:size="3em">
+ <tr>
+ <td>A</td>
+ <td>B</td>
+ <td>C</td>
+ </tr>
+</table>
+
+<p>Paragraph after.</p>
+^D
+Paragraph before.
+
+#{set text(size: 3em); table(
+ columns: 3,
+ align: (auto,auto,auto,),
+ [A], [B], [C],
+)}
+Paragraph after.
+```
+
+
+```
+% pandoc -f html -t typst
+<p>Paragraph before.</p>
+
+<table typst:text:size="3em">
+ <tr>
+ <td>A</td>
+ <td>B</td>
+ <td>C</td>
+ </tr>
+</table>
+
+<p>Paragraph after.</p>
+^D
+Paragraph before.
+
+#figure(
+ align(center)[#set text(size: 3em); #table(
+ columns: 3,
+ align: (auto,auto,auto,),
+ [A], [B], [C],
+ )]
+ , kind: table
+ )
+
+Paragraph after.
+```
+
+
+```
+% pandoc -f html -t typst
+<p>Paragraph before.</p>
+
+<table class="typst:no-figure">
+ <tr>
+ <td>A</td>
+ <td>B</td>
+ <td>C</td>
+ </tr>
+</table>
+
+<p>Paragraph after.</p>
+^D
+Paragraph before.
+
+#table(
+ columns: 3,
+ align: (auto,auto,auto,),
+ [A], [B], [C],
+)
+Paragraph after.
+```
\ No newline at end of file
diff --git a/documents/markdown/pandoc-md/unicode-collation.md b/documents/markdown/pandoc-md/unicode-collation.md
new file mode 100644
index 0000000..190e383
--- /dev/null
+++ b/documents/markdown/pandoc-md/unicode-collation.md
@@ -0,0 +1,130 @@
+```
+% pandoc --citeproc -t plain
+---
+lang: en-US
+csl: command/apa.csl
+references:
+- id: a1
+ type: book
+ author:
+ - family: Ubina
+ given: A. John
+ issued: 1985
+- id: a2
+ type: book
+ author:
+ - family: Über
+ given: Aglaia
+ issued: 1996
+- id: a3
+ type: book
+ author:
+ - family: Oñate
+ given: José
+ issued: 1985
+- id: a4
+ type: book
+ author:
+ - family: Onush
+ given: Frank
+ issued: 2002
+- id: a5
+ type: book
+ author:
+ - family: O'Neil
+ given: Timothy
+ issued: 2010
+---
+
+[@a1;@a2;@a3;@a4;@a5]
+^D
+(O’Neil, 2010; Oñate, 1985; Onush, 2002; Über, 1996; Ubina, 1985)
+
+O’Neil, T. (2010).
+
+Oñate, J. (1985).
+
+Onush, F. (2002).
+
+Über, A. (1996).
+
+Ubina, A. J. (1985).
+```
+
+```
+% pandoc --citeproc -t plain
+---
+lang: es
+csl: command/apa.csl
+references:
+- id: a1
+ type: book
+ author:
+ - family: Ubina
+ given: A. John
+ issued: 1985
+- id: a2
+ type: book
+ author:
+ - family: Über
+ given: Aglaia
+ issued: 1996
+- id: a3
+ type: book
+ author:
+ - family: Oñate
+ given: José
+ issued: 1985
+- id: a4
+ type: book
+ author:
+ - family: Onush
+ given: Frank
+ issued: 2002
+- id: a5
+ type: book
+ author:
+ - family: O'Neil
+ given: Timothy
+ issued: 2010
+---
+
+[@a1;@a2;@a3;@a4;@a5]
+^D
+(O’Neil, 2010; Onush, 2002; Oñate, 1985; Über, 1996; Ubina, 1985)
+
+O’Neil, T. (2010).
+
+Onush, F. (2002).
+
+Oñate, J. (1985).
+
+Über, A. (1996).
+
+Ubina, A. J. (1985).
+```
+
+```
+% pandoc -C -t plain
+---
+nocite: '@*'
+lang: fr-FR-u-kb-true
+references:
+- id: cote
+ author: cote
+- id: côte
+ author: côte
+- id: coté
+ author: coté
+- id: côté
+ author: côté
+...
+^D
+cote. s. d.
+
+côte. s. d.
+
+coté. s. d.
+
+côté. s. d.
+```
diff --git a/documents/markdown/pandoc-md/vars-and-metadata.md b/documents/markdown/pandoc-md/vars-and-metadata.md
new file mode 100644
index 0000000..c3dc895
--- /dev/null
+++ b/documents/markdown/pandoc-md/vars-and-metadata.md
@@ -0,0 +1,15 @@
+Variables should not leak into metadata in the Markdown writer:
+
+```
+% pandoc -t markdown -Vfoo=1 -Vbar=2 -s
+---
+foo: x
+...
+zib
+^D
+---
+foo: x
+---
+
+zib
+```
diff --git a/documents/markdown/pandoc-md/video-audio.md b/documents/markdown/pandoc-md/video-audio.md
new file mode 100644
index 0000000..4fbd58d
--- /dev/null
+++ b/documents/markdown/pandoc-md/video-audio.md
@@ -0,0 +1,23 @@
+```
+% pandoc -f markdown-implicit_figures -t html
+
+
+{width=300}
+
+
+
+
+
+
+^D
+<p><video src="./test.mp4" controls=""><a
+href="./test.mp4">Video</a></video></p>
+<p><video src="foo/test.webm" width="300" controls=""><a
+href="foo/test.webm">Your browser does not support
+video.</a></video></p>
+<p><audio src="test.mp3" controls=""><a
+href="test.mp3">Audio</a></audio></p>
+<p><embed src="./test.pdf" /></p>
+<p><img src="./test.jpg" /></p>
+```
+
diff --git a/documents/markdown/pandoc-md/vim-online-doc.md b/documents/markdown/pandoc-md/vim-online-doc.md
new file mode 100644
index 0000000..ecc80b4
--- /dev/null
+++ b/documents/markdown/pandoc-md/vim-online-doc.md
@@ -0,0 +1,42 @@
+# Online vim documentation
+
+While vim documentation can be accessed with `:help`, it may be beneficial to
+link to the websites inside readme/markdown docs. Two most common websites are:
+
+- <https://vimhelp.org/> and
+- <https://neovim.io/doc/user>
+
+Also it is not uncommon to reference documentation as `:h <topic>`
+
+## Links to vimhelp.org {#vimhelp-links}
+
+For introduction to writing help files see
+<https://vimhelp.org/helphelp.txt.html#help-writing>
+
+Named link: [vimhelp link](https://vimhelp.org/helphelp.txt.html#help-writing)
+
+## Links to neo.vimhelp.org {#neo-vimhelp-links}
+
+For introduction to writing help files see
+<https://neo.vimhelp.org/helphelp.txt.html#help-writing>
+
+Named link: [vimhelp link](https://neo.vimhelp.org/helphelp.txt.html#help-writing)
+
+## Links to neovim.io {#neovim-io-links}
+
+For introduction to writing help files see
+<https://neovim.io/doc/user/helphelp.html#help-writing>
+
+Named link: [neovim.io link](https://neovim.io/doc/user/helphelp.html#help-writing)
+
+You can also reference whole files with topic omitted:
+<https://neovim.io/doc/user/vim_diff.html>
+
+## :h-style documentation {#colon-h-docs}
+
+For introduction to writing help files see
+`:h help-writing`
+
+Long name for `:help` is also supported: `:help help-writing`
+
+This is malformed: `:help help-writing `, but this is not: `:help help-writing`
diff --git a/documents/markdown/pandoc-md/wikilinks_title_after_pipe.md b/documents/markdown/pandoc-md/wikilinks_title_after_pipe.md
new file mode 100644
index 0000000..43c2745
--- /dev/null
+++ b/documents/markdown/pandoc-md/wikilinks_title_after_pipe.md
@@ -0,0 +1,73 @@
+# CommonMark
+
+## Reader
+```
+% pandoc --from commonmark_x+wikilinks_title_after_pipe -t html --columns 90
+[[https://example.org]]
+
+[[https://example.org|title]]
+
+[[name of page]]
+
+[[name of page|title]]
+^D
+<p><a href="https://example.org" class="wikilink">https://example.org</a></p>
+<p><a href="https://example.org" class="wikilink">title</a></p>
+<p><a href="name of page" class="wikilink">name of page</a></p>
+<p><a href="name of page" class="wikilink">title</a></p>
+```
+
+## Writer
+
+```
+% pandoc -t commonmark_x+wikilinks_title_after_pipe -f html
+<p><a href="https://example.org" class="wikilink">https://example.org</a></p>
+<p><a href="https://example.org" class="wikilink">title</a></p>
+<p><a href="Home" class="wikilink">Home</a></p>
+<p><a href="Name of page" class="wikilink">Title</a></p>
+^D
+[[https://example.org]]
+
+[[https://example.org|title]]
+
+[[Home]]
+
+[[Name%20of%20page|Title]]
+```
+
+# Markdown
+## Reader
+
+```
+% pandoc --from markdown+wikilinks_title_after_pipe -t html --columns 90
+[[https://example.org]]
+
+[[https://example.org|title]]
+
+[[name of page]]
+
+[[name of page|title]]
+^D
+<p><a href="https://example.org" class="wikilink">https://example.org</a></p>
+<p><a href="https://example.org" class="wikilink">title</a></p>
+<p><a href="name of page" class="wikilink">name of page</a></p>
+<p><a href="name of page" class="wikilink">title</a></p>
+```
+
+## Writer
+
+```
+% pandoc -t markdown+wikilinks_title_after_pipe -f html
+<p><a href="https://example.org" class="wikilink">https://example.org</a></p>
+<p><a href="https://example.org" class="wikilink">title</a></p>
+<p><a href="Home" class="wikilink">Home</a></p>
+<p><a href="Name of page" class="wikilink">Title</a></p>
+^D
+[[https://example.org]]
+
+[[https://example.org|title]]
+
+[[Home]]
+
+[[Name%20of%20page|Title]]
+```
diff --git a/documents/markdown/pandoc-md/wikilinks_title_before_pipe.md b/documents/markdown/pandoc-md/wikilinks_title_before_pipe.md
new file mode 100644
index 0000000..86680a3
--- /dev/null
+++ b/documents/markdown/pandoc-md/wikilinks_title_before_pipe.md
@@ -0,0 +1,84 @@
+# CommonMark
+
+## Reader
+
+```
+% pandoc -f commonmark+wikilinks_title_before_pipe -t html --columns 90
+[[https://example.org]]
+
+[[title|https://example.org]]
+
+[[Name of page]]
+
+[[Title|Name of page]]
+^D
+<p><a href="https://example.org" class="wikilink">https://example.org</a></p>
+<p><a href="https://example.org" class="wikilink">title</a></p>
+<p><a href="Name of page" class="wikilink">Name of page</a></p>
+<p><a href="Name of page" class="wikilink">Title</a></p>
+```
+
+## Writer
+
+```
+% pandoc -t commonmark_x+wikilinks_title_before_pipe -f html
+<p><a href="https://example.org" class="wikilink">https://example.org</a></p>
+<p><a href="https://example.org" class="wikilink">title</a></p>
+<p><a href="Home" class="wikilink">Home</a></p>
+<p><a href="Name of page" class="wikilink">Title</a></p>
+^D
+[[https://example.org]]
+
+[[title|https://example.org]]
+
+[[Home]]
+
+[[Title|Name%20of%20page]]
+```
+
+## Regular links should still work
+
+```
+% pandoc -f commonmark+wikilinks_title_before_pipe -t html
+[Title](Name%20of%20page)
+^D
+<p><a href="Name%20of%20page">Title</a></p>
+```
+
+# Markdown
+
+## Reader
+
+```
+% pandoc -f markdown+wikilinks_title_before_pipe -t html --columns 90
+[[https://example.org]]
+
+[[title|https://example.org]]
+
+[[Name of page]]
+
+[[Title|Name of page]]
+^D
+<p><a href="https://example.org" class="wikilink">https://example.org</a></p>
+<p><a href="https://example.org" class="wikilink">title</a></p>
+<p><a href="Name of page" class="wikilink">Name of page</a></p>
+<p><a href="Name of page" class="wikilink">Title</a></p>
+```
+
+## Writer
+
+```
+% pandoc -t markdown+wikilinks_title_before_pipe -f html
+<p><a href="https://example.org" class="wikilink">https://example.org</a></p>
+<p><a href="https://example.org" class="wikilink">title</a></p>
+<p><a href="Home" class="wikilink">Home</a></p>
+<p><a href="Name of page" class="wikilink">Title</a></p>
+^D
+[[https://example.org]]
+
+[[title|https://example.org]]
+
+[[Home]]
+
+[[Title|Name%20of%20page]]
+```
diff --git a/documents/markdown/pandoc-md/write18.md b/documents/markdown/pandoc-md/write18.md
new file mode 100644
index 0000000..4a3f10b
--- /dev/null
+++ b/documents/markdown/pandoc-md/write18.md
@@ -0,0 +1,14 @@
+Handle \write18{..} as raw tex:
+```
+% pandoc -t native
+\write18{git --version}
+^D
+[ RawBlock (Format "tex") "\\write18{git --version}" ]
+```
+
+```
+% pandoc -f latex+raw_tex -t native
+\write18{git --version}
+^D
+[ RawBlock (Format "latex") "\\write18{git --version}" ]
+```
diff --git a/documents/markdown/pandoc-md/writer.md b/documents/markdown/pandoc-md/writer.md
new file mode 100644
index 0000000..ebcff08
--- /dev/null
+++ b/documents/markdown/pandoc-md/writer.md
@@ -0,0 +1,701 @@
+---
+author:
+- John MacFarlane
+- Anonymous
+date: July 17, 2006
+title: Pandoc Test Suite
+---
+
+This is a set of tests for pandoc. Most of them are adapted from John Gruber's
+markdown test suite.
+
+--------------------------------------------------------------------------------
+
+# Headers
+
+## Level 2 with an [embedded link](/url)
+
+### Level 3 with *emphasis*
+
+#### Level 4
+
+##### Level 5
+
+# Level 1
+
+## Level 2 with *emphasis*
+
+### Level 3
+
+with no blank line
+
+## Level 2
+
+with no blank line
+
+--------------------------------------------------------------------------------
+
+# Paragraphs
+
+Here's a regular paragraph.
+
+In Markdown 1.0.0 and earlier. Version 8. This line turns into a list item.
+Because a hard-wrapped line in the middle of a paragraph looked like a list
+item.
+
+Here's one with a bullet. \* criminey.
+
+There should be a hard line break\
+here.
+
+--------------------------------------------------------------------------------
+
+# Block Quotes
+
+E-mail style:
+
+> This is a block quote. It is pretty short.
+
+> Code in a block quote:
+>
+> sub status {
+> print "working";
+> }
+>
+> A list:
+>
+> 1. item one
+> 2. item two
+>
+> Nested block quotes:
+>
+> > nested
+>
+> > nested
+
+This should not be a block quote: 2 \> 1.
+
+And a following paragraph.
+
+--------------------------------------------------------------------------------
+
+# Code Blocks
+
+Code:
+
+ ---- (should be four hyphens)
+
+ sub status {
+ print "working";
+ }
+
+ this code block is indented by one tab
+
+And:
+
+ this code block is indented by two tabs
+
+ These should not be escaped: \$ \\ \> \[ \{
+
+--------------------------------------------------------------------------------
+
+# Lists
+
+## Unordered
+
+Asterisks tight:
+
+- asterisk 1
+- asterisk 2
+- asterisk 3
+
+Asterisks loose:
+
+- asterisk 1
+
+- asterisk 2
+
+- asterisk 3
+
+Pluses tight:
+
+- Plus 1
+- Plus 2
+- Plus 3
+
+Pluses loose:
+
+- Plus 1
+
+- Plus 2
+
+- Plus 3
+
+Minuses tight:
+
+- Minus 1
+- Minus 2
+- Minus 3
+
+Minuses loose:
+
+- Minus 1
+
+- Minus 2
+
+- Minus 3
+
+## Ordered
+
+Tight:
+
+1. First
+2. Second
+3. Third
+
+and:
+
+1. One
+2. Two
+3. Three
+
+Loose using tabs:
+
+1. First
+
+2. Second
+
+3. Third
+
+and using spaces:
+
+1. One
+
+2. Two
+
+3. Three
+
+Multiple paragraphs:
+
+1. Item 1, graf one.
+
+ Item 1. graf two. The quick brown fox jumped over the lazy dog's back.
+
+2. Item 2.
+
+3. Item 3.
+
+## Nested
+
+- Tab
+ - Tab
+ - Tab
+
+Here's another:
+
+1. First
+2. Second:
+ - Fee
+ - Fie
+ - Foe
+3. Third
+
+Same thing but with paragraphs:
+
+1. First
+
+2. Second:
+
+ - Fee
+ - Fie
+ - Foe
+
+3. Third
+
+## Tabs and spaces
+
+- this is a list item indented with tabs
+
+- this is a list item indented with spaces
+
+ - this is an example list item indented with tabs
+
+ - this is an example list item indented with spaces
+
+## Fancy list markers
+
+(2) begins with 2
+
+(3) and now 3
+
+ with a continuation
+
+ iv. sublist with roman numerals, starting with 4
+ v. more items
+ (A) a subsublist
+ (B) a subsublist
+
+Nesting:
+
+A. Upper Alpha
+ I. Upper Roman.
+ (6) Decimal start with 6
+ c) Lower alpha with paren
+
+Autonumbering:
+
+1. Autonumber.
+2. More.
+ 1. Nested.
+
+Should not be a list item:
+
+M.A. 2007
+
+B. Williams
+
+--------------------------------------------------------------------------------
+
+# Definition Lists
+
+Tight using spaces:
+
+apple
+: red fruit
+
+orange
+: orange fruit
+
+banana
+: yellow fruit
+
+Tight using tabs:
+
+apple
+: red fruit
+
+orange
+: orange fruit
+
+banana
+: yellow fruit
+
+Loose:
+
+apple
+
+: red fruit
+
+orange
+
+: orange fruit
+
+banana
+
+: yellow fruit
+
+Multiple blocks with italics:
+
+*apple*
+
+: red fruit
+
+ contains seeds, crisp, pleasant to taste
+
+*orange*
+
+: orange fruit
+
+ { orange code block }
+
+ > orange block quote
+
+Multiple definitions, tight:
+
+apple
+: red fruit
+: computer
+
+orange
+: orange fruit
+: bank
+
+Multiple definitions, loose:
+
+apple
+
+: red fruit
+
+: computer
+
+orange
+
+: orange fruit
+
+: bank
+
+Blank line after term, indented marker, alternate markers:
+
+apple
+
+: red fruit
+
+: computer
+
+orange
+
+: orange fruit
+
+ 1. sublist
+ 2. sublist
+
+# HTML Blocks
+
+Simple block on one line:
+
+::: {}
+foo
+:::
+
+And nested without indentation:
+
+:::::: {}
+:::: {}
+::: {}
+foo
+:::
+::::
+
+::: {}
+bar
+:::
+::::::
+
+Interpreted markdown in a table:
+
+<table>
+<tr>
+<td>
+This is *emphasized*
+</td>
+<td>
+And this is **strong**
+</td>
+</tr>
+</table>
+<script type="text/javascript">document.write('This *should not* be interpreted as markdown');</script>
+
+Here's a simple block:
+
+::: {}
+foo
+:::
+
+This should be a code block, though:
+
+ <div>
+ foo
+ </div>
+
+As should this:
+
+ <div>foo</div>
+
+Now, nested:
+
+::::: {}
+:::: {}
+::: {}
+foo
+:::
+::::
+:::::
+
+This should just be an HTML comment:
+
+<!-- Comment -->
+
+Multiline:
+
+<!--
+Blah
+Blah
+-->
+<!--
+ This is another comment.
+-->
+
+Code block:
+
+ <!-- Comment -->
+
+Just plain comment, with trailing spaces on the line:
+
+<!-- foo -->
+
+Code:
+
+ <hr />
+
+Hr's:
+
+<hr>
+<hr />
+<hr />
+<hr>
+<hr />
+<hr />
+<hr class="foo" id="bar" />
+<hr class="foo" id="bar" />
+<hr class="foo" id="bar">
+
+--------------------------------------------------------------------------------
+
+# Inline Markup
+
+This is *emphasized*, and so *is this*.
+
+This is **strong**, and so **is this**.
+
+An *[emphasized link](/url)*.
+
+***This is strong and em.***
+
+So is ***this*** word.
+
+***This is strong and em.***
+
+So is ***this*** word.
+
+This is code: `>`, `$`, `\`, `\$`, `<html>`.
+
+~~This is *strikeout*.~~
+
+Superscripts: a^bc^d a^*hello*^ a^hello there^.
+
+Subscripts: H~2~O, H~23~O, H~many of them~O.
+
+These should not be superscripts or subscripts, because of the unescaped spaces:
+a\^b c\^d, a\~b c\~d.
+
+--------------------------------------------------------------------------------
+
+# Smart quotes, ellipses, dashes
+
+"Hello," said the spider. "'Shelob' is my name."
+
+'A', 'B', and 'C' are letters.
+
+'Oak,' 'elm,' and 'beech' are names of trees. So is 'pine.'
+
+'He said, "I want to go."' Were you alive in the 70's?
+
+Here is some quoted '`code`' and a "[quoted
+link](http://example.com/?foo=1&bar=2)".
+
+Some dashes: one---two --- three---four --- five.
+
+Dashes between numbers: 5--7, 255--66, 1987--1999.
+
+Ellipses...and...and....
+
+--------------------------------------------------------------------------------
+
+# LaTeX
+
+- `\cite[22-23]{smith.1899}`{=tex}
+- $2+2=4$
+- $x \in y$
+- $\alpha \wedge \omega$
+- $223$
+- $p$-Tree
+- Here's some display math:
+ $$\frac{d}{dx}f(x)=\lim_{h\to 0}\frac{f(x+h)-f(x)}{h}$$
+- Here's one that has a line break in it: $\alpha + \omega \times x^2$.
+
+These shouldn't be math:
+
+- To get the famous equation, write `$e = mc^2$`.
+- \$22,000 is a *lot* of money. So is \$34,000. (It worked if "lot" is
+ emphasized.)
+- Shoes (\$20) and socks (\$5).
+- Escaped `$`: \$73 *this should be emphasized* 23\$.
+
+Here's a LaTeX table:
+
+\begin{tabular}{|l|l|}\hline
+Animal & Number \\ \hline
+Dog & 2 \\
+Cat & 1 \\ \hline
+\end{tabular}
+
+--------------------------------------------------------------------------------
+
+# Special Characters
+
+Here is some unicode:
+
+- I hat: Î
+- o umlaut: ö
+- section: §
+- set membership: ∈
+- copyright: ©
+
+AT&T has an ampersand in their name.
+
+AT&T is another way to write it.
+
+This & that.
+
+4 \< 5.
+
+6 \> 5.
+
+Backslash: \\
+
+Backtick: \`
+
+Asterisk: \*
+
+Underscore: \_
+
+Left brace: {
+
+Right brace: }
+
+Left bracket: \[
+
+Right bracket: \]
+
+Left paren: (
+
+Right paren: )
+
+Greater-than: \>
+
+Hash: \#
+
+Period: .
+
+Bang: !
+
+Plus: +
+
+Minus: -
+
+--------------------------------------------------------------------------------
+
+# Links
+
+## Explicit
+
+Just a [URL](/url/).
+
+[URL and title](/url/ "title").
+
+[URL and title](/url/ "title preceded by two spaces").
+
+[URL and title](/url/ "title preceded by a tab").
+
+[URL and title](/url/ "title with "quotes" in it")
+
+[URL and title](/url/ "title with single quotes")
+
+[with_underscore](/url/with_underscore)
+
+[Email link](mailto:nobody@nowhere.net)
+
+[Empty]().
+
+## Reference
+
+Foo [bar](/url/).
+
+With [embedded \[brackets\]](/url/).
+
+[b](/url/) by itself should be a link.
+
+Indented [once](/url).
+
+Indented [twice](/url).
+
+Indented [thrice](/url).
+
+This should \[not\]\[\] be a link.
+
+ [not]: /url
+
+Foo [bar](/url/ "Title with "quotes" inside").
+
+Foo [biz](/url/ "Title with "quote" inside").
+
+## With ampersands
+
+Here's a [link with an ampersand in the URL](http://example.com/?foo=1&bar=2).
+
+Here's a link with an amersand in the link text: [AT&T](http://att.com/ "AT&T").
+
+Here's an [inline link](/script?foo=1&bar=2).
+
+Here's an [inline link in pointy braces](/script?foo=1&bar=2).
+
+## Autolinks
+
+With an ampersand: <http://example.com/?foo=1&bar=2>
+
+- In a list?
+- <http://example.com/>
+- It should.
+
+An e-mail address: <nobody@nowhere.net>
+
+> Blockquoted: <http://example.com/>
+
+Auto-links should not occur here: `<http://example.com/>`
+
+ or here: <http://example.com/>
+
+--------------------------------------------------------------------------------
+
+# Images
+
+From "Voyage dans la Lune" by Georges Melies (1902):
+
+
+
+Here is a movie  icon.
+
+--------------------------------------------------------------------------------
+
+# Footnotes
+
+Here is a footnote reference,[^1] and another.[^2] This should *not* be a
+footnote reference, because it contains a space.\[\^my note\] Here is an inline
+note.[^3]
+
+> Notes can go in quotes.[^4]
+
+1. And in list items.[^5]
+
+This paragraph should not be part of the note, as it is not indented.
+
+[^1]: Here is the footnote. It can go anywhere after the footnote reference. It
+ need not be placed at the end of the document.
+
+[^2]: Here's the long note. This one contains multiple blocks.
+
+ Subsequent blocks are indented to show that they belong to the footnote (as
+ with list items).
+
+ { <code> }
+
+ If you want, you can indent every line, but you can also be lazy and just
+ indent the first line of each block.
+
+[^3]: This is *easier* to type. Inline notes may contain
+ [links](http://google.com) and `]` verbatim characters, as well as
+ \[bracketed text\].
+
+[^4]: In quote.
+
+[^5]: In list.
diff --git a/documents/markdown/pandoc-md/yaml-metadata-blocks.md b/documents/markdown/pandoc-md/yaml-metadata-blocks.md
new file mode 100644
index 0000000..d92994b
--- /dev/null
+++ b/documents/markdown/pandoc-md/yaml-metadata-blocks.md
@@ -0,0 +1,121 @@
+```
+% pandoc -s -t native
+---
+foobar_: this should be ignored
+foo:
+ bar_: as should this
+---
+^D
+Pandoc
+ Meta
+ { unMeta = fromList [ ( "foo" , MetaMap (fromList []) ) ] }
+ []
+```
+```
+% pandoc -s -t native
+---
+# For precedence, see multiple-metadata-blocks.md and vars-and-metadata.md
+# For Bools, see also 4819.md
+# For Multiline strings, see yaml-with-chomp.md
+int: 7
+float: 1.5
+scientific: 3.7e-5
+bool: true
+more: False
+nothing: null
+empty: []
+nested:
+ int: 8
+ float: 2.5
+ bool: true
+ more: False
+ nothing: null
+ empty: []
+ scientific: 3.7e-5
+---
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "bool" , MetaBool True )
+ , ( "empty" , MetaList [] )
+ , ( "float" , MetaInlines [ Str "1.5" ] )
+ , ( "int" , MetaInlines [ Str "7" ] )
+ , ( "more" , MetaBool False )
+ , ( "nested"
+ , MetaMap
+ (fromList
+ [ ( "bool" , MetaBool True )
+ , ( "empty" , MetaList [] )
+ , ( "float" , MetaInlines [ Str "2.5" ] )
+ , ( "int" , MetaInlines [ Str "8" ] )
+ , ( "more" , MetaBool False )
+ , ( "nothing" , MetaString "" )
+ , ( "scientific" , MetaInlines [ Str "3.7e-5" ] )
+ ])
+ )
+ , ( "nothing" , MetaString "" )
+ , ( "scientific" , MetaInlines [ Str "3.7e-5" ] )
+ ]
+ }
+ []
+```
+```
+% pandoc -s -t native
+---
+array:
+ - foo: bar
+ - bool: True
+---
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "array"
+ , MetaList
+ [ MetaMap
+ (fromList [ ( "foo" , MetaInlines [ Str "bar" ] ) ])
+ , MetaMap (fromList [ ( "bool" , MetaBool True ) ])
+ ]
+ )
+ ]
+ }
+ []
+```
+```
+% pandoc -s -t native --metadata-file command/yaml-metadata.yaml
+---
+title: document
+---
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "other"
+ , MetaInlines
+ [ Emph [ Str "markdown" ] , Space , Str "value" ]
+ )
+ , ( "title" , MetaInlines [ Str "document" ] )
+ ]
+ }
+ []
+```
+```
+% pandoc -s -t native --metadata-file command/yaml-metadata.yaml -M title=cmdline
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "other"
+ , MetaInlines
+ [ Emph [ Str "markdown" ] , Space , Str "value" ]
+ )
+ , ( "title" , MetaString "cmdline" )
+ ]
+ }
+ []
+```
diff --git a/documents/markdown/pandoc-md/yaml-with-chomp.md b/documents/markdown/pandoc-md/yaml-with-chomp.md
new file mode 100644
index 0000000..6dc75fc
--- /dev/null
+++ b/documents/markdown/pandoc-md/yaml-with-chomp.md
@@ -0,0 +1,20 @@
+```
+% pandoc -s -t native
+---
+ml: |-
+ TEST
+
+ BLOCK
+...
+^D
+Pandoc
+ Meta
+ { unMeta =
+ fromList
+ [ ( "ml"
+ , MetaInlines [ Str "TEST" , LineBreak , Str "BLOCK" ]
+ )
+ ]
+ }
+ []
+```
diff --git a/documents/markdown/remark/changelog.md b/documents/markdown/remark/changelog.md
new file mode 100644
index 0000000..0a9a9f3
--- /dev/null
+++ b/documents/markdown/remark/changelog.md
@@ -0,0 +1,5 @@
+# Changelog
+
+See [GitHub Releases][releases] for the changelog.
+
+[releases]: https://github.com/remarkjs/remark/releases
diff --git a/documents/markdown/remark/doc_getting-started.md b/documents/markdown/remark/doc_getting-started.md
new file mode 100644
index 0000000..ec9a925
--- /dev/null
+++ b/documents/markdown/remark/doc_getting-started.md
@@ -0,0 +1,6 @@
+# Getting started
+
+See [the monorepo readme][remark] for what the remark ecosystem is and examples
+of how to get started.
+
+[remark]: https://github.com/remarkjs/remark
diff --git a/documents/markdown/remark/doc_plugins.md b/documents/markdown/remark/doc_plugins.md
new file mode 100644
index 0000000..ec25bdf
--- /dev/null
+++ b/documents/markdown/remark/doc_plugins.md
@@ -0,0 +1,449 @@
+![remark][file-logo]
+
+# Plugins
+
+**remark** is a tool that transforms markdown with plugins.
+See [the monorepo readme][github-remark] for info on what the remark ecosystem
+is.
+This page lists existing plugins.
+
+## Contents
+
+* [List of plugins](#list-of-plugins)
+* [List of utilities](#list-of-utilities)
+* [Use plugins](#use-plugins)
+* [Create plugins](#create-plugins)
+
+## List of plugins
+
+<a id="list-of-presets"></a>
+
+For the most awesome projects in the ecosystem,
+see [`remarkjs/awesome-remark`][github-remark-awesome-remark].
+More plugins can be found on GitHub tagged with the
+[`remark-plugin` topic][github-topic-remark-plugin].
+
+> 👉 **Note**:
+> some plugins don’t work with recent versions of remark due to changes in its
+> underlying parser (micromark).
+> Plugins that are up to date or unaffected are marked with `🟢` while plugins
+> that are **currently broken** are marked with `⚠️`.
+
+> 💡 **Tip**:
+> remark plugins work with markdown and **rehype** plugins work with HTML.
+> See [*§ List of plugins* in `rehypejs/rehype`][github-rehype-plugins] for more
+> plugins.
+
+<!--lint disable media-style-->
+
+The list of plugins:
+
+* [`remark-a11y-emoji`](https://github.com/florianeckerstorfer/remark-a11y-emoji)
+ — accessible emoji
+* ⚠️ [`remark-abbr`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-abbr#readme)
+ — new syntax for abbreviations (new node type, rehype compatible)
+* ⚠️ [`remark-admonitions`](https://github.com/elviswolcott/remark-admonitions)
+ — new syntax for admonitions
+ (👉 **note**: [`remark-directive`][github-remark-directive] is similar and up
+ to date)
+* ⚠️ [`remark-align`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-align#readme)
+ — new syntax to align text or blocks (new node types, rehype
+ compatible)
+* 🟢 [`remark-api`](https://github.com/wooorm/remark-api)
+ — generate an API section
+* ⚠️ [`remark-attr`](https://github.com/arobase-che/remark-attr)
+ — new syntax to add attributes to markdown
+* 🟢 [`remark-behead`](https://github.com/mrzmmr/remark-behead)
+ — increase or decrease heading depth
+* 🟢 [`remark-breaks`](https://github.com/remarkjs/remark-breaks)
+ – hard breaks w/o needing spaces (like on issues)
+* 🟢 [`remark-capitalize`](https://github.com/zeit/remark-capitalize)
+ – transform all titles w/ [`title.sh`](https://github.com/zeit/title)
+* 🟢 [`remark-capitalize-headings`](https://github.com/Xunnamius/unified-utils/blob/main/packages/remark-capitalize-headings)
+ – selectively capitalize headings
+ (👉 **note**: alternative to [`remark-capitalize`](https://github.com/zeit/remark-capitalize))
+* 🟢 [`remark-cite`](https://github.com/benrbray/remark-cite)
+ – new syntax for Pandoc-style citations
+* 🟢 [`remark-cjk-friendly`](https://github.com/tats-u/markdown-cjk-friendly/tree/main/packages/remark-cjk-friendly)
+ – recognize emphasis in CJK languages more reliably
+* 🟢 [`remark-cjk-friendly-gfm-strikethrough`](https://github.com/tats-u/markdown-cjk-friendly/tree/main/packages/remark-cjk-friendly-gfm-strikethrough)
+ – recognize GFM strikethrough in CJK languages more reliably
+* 🟢 [`remark-cloudinary-docusaurus`](https://github.com/johnnyreilly/remark-cloudinary-docusaurus)
+ – allows Docusaurus to use Cloudinary to serve optimised images
+* 🟢 [`remark-code-blocks`](https://github.com/mrzmmr/remark-code-blocks)
+ — select and store code blocks
+* 🟢 [`remark-code-extra`](https://github.com/samlanning/remark-code-extra)
+ — add to or transform the HTML output of code blocks (rehype compatible)
+* 🟢 [`remark-code-frontmatter`](https://github.com/samlanning/remark-code-frontmatter)
+ — extract frontmatter from code blocks
+* 🟢 [`remark-code-import`](https://github.com/kevin940726/remark-code-import)
+ — populate code blocks from files
+* 🟢 [`remark-code-screenshot`](https://github.com/Swizec/remark-code-screenshot)
+ – turn code blocks into `carbon.now.sh` screenshots
+* 🟢 [`remark-code-title`](https://github.com/kevinzunigacuellar/remark-code-title)
+ — add titles to code blocks
+* 🟢 [`remark-codesandbox`](https://github.com/kevin940726/remark-codesandbox)
+ – create CodeSandbox from code blocks
+* 🟢 [`remark-collapse`](https://github.com/Rokt33r/remark-collapse)
+ — make a section collapsible
+* 🟢 [`remark-comment-config`](https://github.com/remarkjs/remark-comment-config)
+ — configure remark w/ comments
+* ⚠️ [`remark-comments`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-comments#readme)
+ — new syntax to ignore things
+* ⚠️ [`remark-container`](https://github.com/zWingz/remark-container)
+ — new syntax for containers
+ (👉 **note**: [`remark-directive`][github-remark-directive] is similar and up
+ to date)
+* ⚠️ [`remark-containers`](https://github.com/Nevenall/remark-containers)
+ — new syntax for containers
+ (👉 **note**: [`remark-directive`][github-remark-directive] is similar and up
+ to date)
+* 🟢 [`remark-contributors`](https://github.com/remarkjs/remark-contributors)
+ — add a table of contributors
+* 🟢 [`remark-copy-linked-files`](https://github.com/sergioramos/remark-copy-linked-files)
+ — find and copy files linked files to a destination directory
+* 🟢 [`remark-corebc`](https://github.com/bchainhub/remark-corebc)
+ — transforms Core Blockchain notations into markdown links
+* 🟢 [`remark-corepass`](https://github.com/bchainhub/remark-corepass)
+ — transform CorePass notations into markdown links
+* ⚠️ [`remark-custom-blocks`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-custom-blocks#readme)
+ — new syntax for custom blocks (new node types, rehype compatible)
+ (👉 **note**: [`remark-directive`][github-remark-directive] is similar and up
+ to date)
+* 🟢 [`remark-custom-header-id`](https://github.com/sindresorhus/remark-custom-header-id)
+ — add custom ID attribute to headers (`{#some-id}`)
+* 🟢 [`remark-definition-list`](https://github.com/wataru-chocola/remark-definition-list)
+ — support definition lists
+* 🟢 [`remark-defsplit`](https://github.com/remarkjs/remark-defsplit)
+ — change links and images to references w/ separate definitions
+* ⚠️ [`remark-disable-tokenizers`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-disable-tokenizers#readme)
+ — turn some or all remark’s tokenizers on or off
+* 🟢 [`remark-directive`](https://github.com/remarkjs/remark-directive)
+ — new syntax for directives (generic extensions)
+* 🟢 [`remark-directive-rehype`](https://github.com/IGassmann/remark-directive-rehype)
+ — turn [directives][github-remark-directive] into HTML custom elements
+ (rehype compatible)
+* 🟢 [`remark-directive-sugar`](https://github.com/lin-stephanie/remark-directive-sugar)
+ — predefined directives for customizable badges, links, video embeds, and more
+* 🟢 [`remark-docx`](https://github.com/inokawa/remark-docx)
+ — compile markdown to docx
+* 🟢 [`@m2d/remark-docx`](https://github.com/md2docx/remark-docx)
+ — compile markdown to docx with support for GFM, tables, html, and more.
+* 🟢 [`remark-dropcap`](https://github.com/brev/remark-dropcap)
+ — fancy and accessible drop caps
+* 🟢 [`remark-embed-images`](https://github.com/remarkjs/remark-embed-images)
+ — embed local images as base64-encoded data URIs
+* 🟢 [`remark-emoji`](https://github.com/rhysd/remark-emoji)
+ — transform Gemoji short-codes to emoji
+* 🟢 [`remark-extended-table`](https://github.com/wataru-chocola/remark-extended-table)
+ — extended table syntax allowing colspan / rowspan
+* 🟢 [`remark-extract-frontmatter`](https://github.com/mrzmmr/remark-extract-frontmatter)
+ — store front matter in vfiles
+* 🟢 [`remark-fediverse-user`](https://github.com/bchainhub/remark-fediverse-user)
+ — transform Fediverse user notations into markdown links
+* 🟢 [`remark-first-heading`](https://github.com/laat/remark-first-heading)
+ — change the first heading in a document
+* 🟢 [`remark-fix-guillemets`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-fix-guillemets#readme)
+ — support ASCII guillements (`<<`, `>>`) mapping them to HTML
+* 🟢 [`remark-flexible-code-titles`](https://github.com/ipikuka/remark-flexible-code-titles)
+ — add titles or/and containers for code blocks with customizable attributes
+* 🟢 [`remark-flexible-containers`](https://github.com/ipikuka/remark-flexible-containers)
+ — add custom/flexible containers with customizable properties
+* 🟢 [`remark-flexible-markers`](https://github.com/ipikuka/remark-flexible-markers)
+ — add custom/flexible mark element with customizable properties
+* 🟢 [`remark-flexible-paragraphs`](https://github.com/ipikuka/remark-flexible-paragraphs)
+ — add custom/flexible paragraphs with customizable properties
+* 🟢 [`remark-flexible-toc`](https://github.com/ipikuka/remark-flexible-toc)
+ — expose the table of contents (toc) via Vfile.data or an option reference
+* 🟢 [`remark-footnotes-extra`](https://github.com/miaobuao/remark-footnotes-extra)
+ — add footnotes via short syntax
+* 🟢 [`remark-frontmatter`](https://github.com/remarkjs/remark-frontmatter)
+ – support frontmatter (yaml, toml, and more)
+* 🟢 [`remark-gemoji`](https://github.com/remarkjs/remark-gemoji)
+ — better support for Gemoji shortcodes
+* ⚠️ [`remark-generic-extensions`](https://github.com/medfreeman/remark-generic-extensions)
+ — new syntax for the CommonMark generic directive extension
+ (👉 **note**: [`remark-directive`][github-remark-directive] is similar and up
+ to date)
+* 🟢 [`remark-gfm`](https://github.com/remarkjs/remark-gfm)
+ — support GFM (autolink literals, footnotes, strikethrough, tables,
+ tasklists)
+* 🟢 [`remark-git-contributors`](https://github.com/remarkjs/remark-git-contributors)
+ — add a table of contributors based on Git history, options, and more
+* 🟢 [`remark-github`](https://github.com/remarkjs/remark-github)
+ — autolink references to commits, issues, pull-requests, and users
+* 🟢 [`remark-github-admonitions-to-directives`](https://github.com/incentro-dc/remark-github-admonitions-to-directives)
+ — convert GitHub’s blockquote-based admonitions syntax to directives syntax
+* 🟢 [`remark-github-beta-blockquote-admonitions`](https://github.com/myl7/remark-github-beta-blockquote-admonitions)
+ — [GitHub beta blockquote-based admonitions](https://github.com/github/feedback/discussions/16925)
+* 🟢 [`remark-github-blockquote-alert`](https://github.com/jaywcjlove/remark-github-blockquote-alert)
+ — remark plugin to add support for [GitHub Alert](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)
+* ⚠️ [`remark-grid-tables`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-grid-tables#readme)
+ — new syntax to describe tables (rehype compatible)
+* 🟢 [`@adobe/remark-grid-tables`](https://github.com/adobe/remark-gridtables)
+ — pandoc compatible grid-table syntax
+* 🟢 [`remark-heading-id`](https://github.com/imcuttle/remark-heading-id)
+ — custom heading id support `{#custom-id}`
+* 🟢 [`remark-heading-gap`](https://github.com/remarkjs/remark-heading-gap)
+ — serialize w/ more blank lines between headings
+* 🟢 [`@vcarl/remark-headings`](https://github.com/vcarl/remark-headings)
+ — extract a list of headings as data
+* 🟢 [`remark-hexo`](https://github.com/bennycode/remark-hexo)
+ — renders [Hexo tags](https://hexo.io/docs/tag-plugins)
+* 🟢 [`remark-highlight.js`](https://github.com/remarkjs/remark-highlight.js)
+ — highlight code blocks w/
+ [`highlight.js`](https://github.com/isagalaev/highlight.js)
+ (rehype compatible)
+* 🟢 [`remark-hint`](https://github.com/sergioramos/remark-hint)
+ — add hints/tips/warnings to markdown
+* 🟢 [`remark-html`](https://github.com/remarkjs/remark-html)
+ — serialize markdown as HTML
+* ⚠️ [`remark-iframes`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-iframes#readme)
+ — new syntax to create iframes (new node type, rehype compatible)
+* 🟢 [`remark-ignore`](https://github.com/Xunnamius/unified-utils/blob/main/packages/remark-ignore)
+ — use comments to exclude nodes from transformation
+* 🟢 [`remark-images`](https://github.com/remarkjs/remark-images)
+ — add an improved image syntax
+* 🟢 [`remark-img-links`](https://github.com/Pondorasti/remark-img-links)
+ — prefix relative image paths with an absolute URL
+* 🟢 [`@it-service-npm/remark-include`](https://github.com/IT-Service-NPM/remark-include)
+ — add `::include{file=path.md}` statements to compose markdown files together
+* 🟢 [`remark-inline-links`](https://github.com/remarkjs/remark-inline-links)
+ — change references and definitions to links and images
+* 🟢 [`remark-ins`](https://github.com/ipikuka/remark-ins)
+ — add ins element for inserted texts opposite to deleted texts
+* 🟢 [`remark-join-cjk-lines`](https://github.com/purefun/remark-join-cjk-lines)
+ — remove extra space between CJK Characters.
+* ⚠️ [`remark-kbd`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-kbd#readme)
+ — new syntax for keyboard keys (new node type, rehype compatible)
+* ⚠️ [`remark-kbd-plus`](https://github.com/twardoch/remark-kbd-plus)
+ — new syntax for keyboard keys w/ plusses (new node type, rehype
+ compatible)
+* 🟢 [`remark-license`](https://github.com/remarkjs/remark-license)
+ — add a license section
+* 🟢 [`remark-link-rewrite`](https://github.com/rjanjic/remark-link-rewrite)
+ — customize link URLs dynamically
+* 🟢 [`remark-linkify-regex`](https://gitlab.com/staltz/remark-linkify-regex)
+ — change text matching a regex to links
+* 🟢 [`remark-lint`](https://github.com/remarkjs/remark-lint)
+ — check markdown code style
+* 🟢 [`remark-man`](https://github.com/remarkjs/remark-man)
+ — serialize markdown as man pages (roff)
+* 🟢 [`remark-math`](https://github.com/remarkjs/remark-math)
+ — new syntax for math (new node types, rehype compatible)
+* 🟢 [`remark-mdx`](https://github.com/mdx-js/mdx/tree/main/packages/remark-mdx)
+ — support MDX (JSX, expressions, ESM)
+* 🟢 [`remark-mentions`](https://github.com/FinnRG/remark-mentions)
+ — replace @ mentions with links
+* 🟢 [`remark-merge-data`](https://github.com/s-h-a-d-o-w/remark-merge-data)
+ — merge globally defined data with data declared across code blocks
+* 🟢 [`remark-mermaidjs`](https://github.com/remcohaszing/remark-mermaidjs)
+ — transform mermaid code blocks into inline SVGs
+* 🟢 [`remark-message-control`](https://github.com/remarkjs/remark-message-control)
+ — turn some or all messages on or off
+* 🟢 [`remark-normalize-headings`](https://github.com/remarkjs/remark-normalize-headings)
+ — make sure at most one top-level heading exists
+* 🟢 [`remark-numbered-footnote-labels`](https://github.com/jackfletch/remark-numbered-footnote-labels)
+ — label footnotes w/ numbers
+* 🟢 [`@agentofuser/remark-oembed`](https://github.com/agentofuser/remark-oembed)
+ — transform URLs for youtube, twitter, etc. embeds
+* 🟢 [`remark-oembed`](https://github.com/sergioramos/remark-oembed)
+ — transform URLs surrounded by newlines into *asynchronously* loading
+ embeds
+* 🟢 [`remark-package-dependencies`](https://github.com/unlight/remark-package-dependencies)
+ — inject your dependencies
+* ⚠️ [`remark-parse-yaml`](https://github.com/landakram/remark-parse-yaml)
+ — parse YAML nodes and expose their value as `parsedValue`
+* 🟢 [`remark-pdf`](https://github.com/inokawa/remark-pdf)
+ — compile markdown to pdf
+* ⚠️ [`remark-ping`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-ping#readme)
+ — new syntax for mentions w/ configurable existence check (new node
+ type, rehype compatible)
+* 🟢 [`remark-plugin-autonbsp`](https://github.com/denisinvader/remark-plugin-autonbsp)
+ — replace whitespace with non-breaking spaces
+ to avoid hanging articles, prepositions and digits
+* 🟢 [`remark-prepend-url`](https://github.com/alxjpzmn/remark-prepend-url)
+ — prepend an absolute url to relative links
+* 🟢 [`remark-prettier`](https://github.com/remcohaszing/remark-prettier)
+ — check and format markdown using Prettier
+* 🟢 [`remark-prism`](https://github.com/sergioramos/remark-prism)
+ — highlight code blocks w/ [Prism](https://prismjs.com/) (supporting most
+ Prism plugins)
+* 🟢 [`@handlewithcare/remark-prosemirror`](https://github.com/handlewithcarecollective/remark-prosemirror)
+ — compile markdown to [ProseMirror](https://prosemirror.net/) documents
+* ⚠️ [`remark-redact`](https://github.com/seafoam6/remark-redact)
+ — new syntax to conceal text matching a regex
+* 🟢 [`remark-redactable`](https://github.com/code-dot-org/remark-redactable)
+ — write plugins to redact content from a markdown document,
+ then restore it later
+* 🟢 [`remark-refer-plantuml`](https://github.com/PrinOrange/remark-refer-plantuml)
+ — automatically transform PlantUML code into referenced embeddable image URLs
+* 🟢 [`remark-reference-links`](https://github.com/remarkjs/remark-reference-links)
+ — transform links and images into references and definitions
+* 🟢 [`remark-rehype`](https://github.com/remarkjs/remark-rehype)
+ — transform to [rehype](https://github.com/rehypejs/rehype)
+* 🟢 [`remark-relative-links`](https://github.com/zslabs/remark-relative-links)
+ — change absolute URLs to relative ones
+* 🟢 [`remark-remove-comments`](https://github.com/alvinometric/remark-remove-comments)
+ — remove HTML comments from the processed output
+* 🟢 [`remark-remove-unused-definitions`](https://github.com/Xunnamius/unified-utils/blob/main/packages/remark-remove-unused-definitions)
+ — remove unused reference-style link definitions
+* 🟢 [`remark-remove-url-trailing-slash`](https://github.com/Xunnamius/unified-utils/blob/main/packages/remark-remove-url-trailing-slash)
+ — remove trailing slashes from the ends of all URL paths
+* 🟢 [`remark-renumber-references`](https://github.com/Xunnamius/unified-utils/blob/main/packages/remark-renumber-references)
+ — renumber numeric reference-style link ids contiguously starting from 1
+* 🟢 [`remark-retext`](https://github.com/remarkjs/remark-retext)
+ — transform to [retext](https://github.com/retextjs/retext)
+* 🟢 [`remark-ruby`](https://github.com/laysent/remark-ruby)
+ — new syntax for ruby (furigana)
+* 🟢 [`remark-sectionize`](https://github.com/jake-low/remark-sectionize)
+ — wrap headings and subsequent content in section tags (new node type,
+ rehype compatible)
+* ⚠️ [`remark-shortcodes`](https://github.com/djm/remark-shortcodes)
+ — new syntax for Wordpress- and Hugo-like shortcodes (new node type)
+ (👉 **note**: [`remark-directive`][github-remark-directive] is similar and up
+ to date)
+* 🟢 [`remark-simple-plantuml`](https://github.com/akebifiky/remark-simple-plantuml)
+ — turn PlantUML code blocks to images
+* 🟢 [`remark-slate`](https://github.com/hanford/remark-slate)
+ — compile markdown to [Slate nodes](https://docs.slatejs.org/concepts/02-nodes)
+* 🟢 [`remark-slate-transformer`](https://github.com/inokawa/remark-slate-transformer)
+ — compile markdown to
+ [Slate nodes](https://docs.slatejs.org/concepts/02-nodes)
+ and Slate nodes to markdown
+* 🟢 [`remark-smartypants`](https://github.com/silvenon/remark-smartypants)
+ — SmartyPants
+* 🟢 [`remark-smcat`](https://github.com/shedali/remark-smcat)
+ — state machine cat
+* 🟢 [`remark-sort-definitions`](https://github.com/Xunnamius/unified-utils/blob/main/packages/remark-sort-definitions)
+ — reorder reference-style link definitions
+* 🟢 [`remark-sources`](https://github.com/unlight/remark-sources)
+ — insert source code
+* 🟢 [`remark-strip-badges`](https://github.com/remarkjs/remark-strip-badges)
+ — remove badges (such as `shields.io`)
+* 🟢 [`remark-strip-html`](https://github.com/craftzdog/remark-strip-html)
+ — remove HTML
+* 🟢 [`remark-squeeze-paragraphs`](https://github.com/remarkjs/remark-squeeze-paragraphs)
+ — remove empty paragraphs
+* ⚠️ [`remark-sub-super`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-sub-super)
+ — new syntax for super- and subscript (new node types, rehype
+ compatible)
+* ⚠️ [`remark-terms`](https://github.com/Nevenall/remark-terms)
+ — new customizable syntax for special terms and phrases
+* 🟢 [`remark-textr`](https://github.com/remarkjs/remark-textr)
+ — transform text w/ [`Textr`](https://github.com/shuvalov-anton/textr)
+* 🟢 [`remark-tight-comments`](https://github.com/Xunnamius/unified-utils/blob/main/packages/remark-tight-comments)
+ — selectively remove newlines around comments
+* 🟢 [`remark-title`](https://github.com/RichardLitt/remark-title)
+ — check and add the document title
+* 🟢 [`remark-toc`](https://github.com/remarkjs/remark-toc)
+ — add a table of contents
+* 🟢 [`remark-torchlight`](https://github.com/torchlight-api/remark-torchlight)
+ — syntax highlighting powered by [torchlight.dev](https://torchlight.dev)
+* 🟢 [`remark-tree-sitter`](https://github.com/samlanning/remark-tree-sitter)
+ — highlight code blocks in markdown files using
+ [Tree-sitter](https://tree-sitter.github.io/tree-sitter/)
+ (rehype compatible)
+* 🟢 [`remark-truncate-links`](https://github.com/GaiAma/Coding4GaiAma/tree/HEAD/packages/remark-truncate-links)
+ — truncate/shorten urls not manually named
+* 🟢 [`remark-twemoji`](https://github.com/madiodio/remark-twemoji)
+ — turn emoji into [Twemoji](https://github.com/twitter/twemoji)
+* 🟢 [`remark-typedoc-symbol-links`](https://github.com/kamranayub/remark-typedoc-symbol-links)
+ — turn Typedoc symbol link expressions into markdown links
+* 🟢 [`remark-typescript`](https://github.com/trevorblades/remark-typescript)
+ — turn TypeScript code to JavaScript
+* 🟢 [`remark-typograf`](https://github.com/mavrin/remark-typograf)
+ — transform text w/ [Typograf](https://github.com/typograf)
+* 🟢 [`remark-unlink`](https://github.com/remarkjs/remark-unlink)
+ — remove all links, references, and definitions
+* 🟢 [`remark-usage`](https://github.com/remarkjs/remark-usage)
+ — add a usage example
+* 🟢 [`remark-utf8`](https://github.com/Swizec/remark-utf8)
+ — turn bolds, italics, and code into UTF 8 special characters
+* 🟢 [`remark-validate-links`](https://github.com/remarkjs/remark-validate-links)
+ — check links to headings and files
+* ⚠️ [`remark-variables`](https://github.com/mrzmmr/remark-variables)
+ — new syntax for variables
+* 🟢 [`remark-vdom`](https://github.com/remarkjs/remark-vdom)
+ — compile markdown to [VDOM](https://github.com/Matt-Esch/virtual-dom/)
+* 🟢 [`remark-wiki-link`](https://github.com/landakram/remark-wiki-link)
+ — new syntax for wiki links (rehype compatible)
+* 🟢 [`remark-yaml-config`](https://github.com/remarkjs/remark-yaml-config)
+ — configure remark w/ YAML
+
+<!--lint enable media-style-->
+
+## List of utilities
+
+For things that work with the syntax tree used in remark for markdown,
+see [*§ List of utilities* in `syntax-tree/mdast`][github-mdast-utilities].
+For tools that work with **mdast** and other syntax trees,
+see [*§ List of utilities* in `syntax-tree/unist`][github-unist-utilities].
+For tools that work with the virtual file format used in remark,
+see [*§ List of utilities* in `vfile/vfile`][github-vfile-utilities].
+
+## Use plugins
+
+To use a plugin programmatically (from JavaScript),
+call the [`use()`][github-unified-use] method.
+To use plugin with `remark-cli` (from the terminal),
+pass a [`--use` flag][github-unified-args-use] or
+specify it in a
+[configuration file][github-unified-engine-config-files].
+
+## Create plugins
+
+To create a plugin,
+first read up on what they are in
+[*§ Plugin* in `unifiedjs/unified`][github-unified-plugin].
+After that read
+[*§ Create a remark plugin* on `unifiedjs.com`][unifiedjs-create-a-plugin]
+for a practical introduction.
+Finally take one of the existing plugins,
+which looks similar to what you’re about to make,
+and work from there.
+If you get stuck,
+[discussions][health-discussions] is a good place to get help.
+
+You should pick a name prefixed by `remark-` (such as `remark-lint`).
+**Do not use the `remark-` prefix** if the thing you create doesn’t work with
+`remark().use()`:
+it isn’t a “plugin” and will confuse users.
+If it works with mdast use `mdast-util-`.
+If it works with any unist tree use `unist-util-`.
+If it works with virtual files use `vfile-`.
+
+Use default exports to expose plugins from your packages.
+Add `remark-plugin` keywords in `package.json`.
+Add a `remark-plugin` topic to your repo on GitHub.
+Create a pull request to add the plugin here on this page!
+
+[file-logo]: https://raw.githubusercontent.com/remarkjs/remark/1f338e72/logo.svg?sanitize=true
+
+[github-mdast-utilities]: https://github.com/syntax-tree/mdast#list-of-utilities
+
+[github-rehype-plugins]: https://github.com/rehypejs/rehype/blob/main/doc/plugins.md#list-of-plugins
+
+[github-remark]: https://github.com/remarkjs/remark
+
+[github-remark-awesome-remark]: https://github.com/remarkjs/awesome-remark
+
+[github-remark-directive]: https://github.com/remarkjs/remark-directive
+
+[github-topic-remark-plugin]: https://github.com/topics/remark-plugin
+
+[github-unified-args-use]: https://github.com/unifiedjs/unified-args#--use-plugin
+
+[github-unified-engine-config-files]: https://github.com/unifiedjs/unified-engine#config-files
+
+[github-unified-plugin]: https://github.com/unifiedjs/unified#plugin
+
+[github-unified-use]: https://github.com/unifiedjs/unified#processoruseplugin-options
+
+[github-unist-utilities]: https://github.com/syntax-tree/unist#unist-utilities
+
+[github-vfile-utilities]: https://github.com/vfile/vfile#list-of-utilities
+
+[health-discussions]: https://github.com/remarkjs/remark/discussions
+
+[unifiedjs-create-a-plugin]: https://unifiedjs.com/learn/guide/create-a-remark-plugin/
diff --git a/documents/markdown/remark/doc_products.md b/documents/markdown/remark/doc_products.md
new file mode 100644
index 0000000..09d3004
--- /dev/null
+++ b/documents/markdown/remark/doc_products.md
@@ -0,0 +1,5 @@
+# Products
+
+See [awesome remark][awesome] for the products using remark.
+
+[awesome]: https://github.com/remarkjs/awesome
diff --git a/documents/markdown/remark/packages_remark-cli_readme.md b/documents/markdown/remark/packages_remark-cli_readme.md
new file mode 100644
index 0000000..af5449e
--- /dev/null
+++ b/documents/markdown/remark/packages_remark-cli_readme.md
@@ -0,0 +1,441 @@
+# remark-cli
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+
+Command line interface to inspect and change markdown files with
+**[remark][github-remark]**.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Install](#install)
+* [Use](#use)
+* [CLI](#cli)
+* [Examples](#examples)
+ * [Example: checking and formatting markdown on the CLI](#example-checking-and-formatting-markdown-on-the-cli)
+ * [Example: config files (JSON, YAML, JS)](#example-config-files-json-yaml-js)
+* [Compatibility](#compatibility)
+* [Security](#security)
+* [Contribute](#contribute)
+* [Sponsor](#sponsor)
+* [License](#license)
+
+## What is this?
+
+This package is a command line interface (CLI) that you can use in your terminal
+or in npm scripts and the like to inspect and change markdown files.
+This CLI is built around remark,
+which is an ecosystem of plugins that work with markdown as structured data,
+specifically ASTs (abstract syntax trees).
+You can choose from the 150+ existing plugins or make your own.
+
+See [the monorepo readme][github-remark] for info on what the remark ecosystem
+is.
+
+## When should I use this?
+
+You can use this package when you want to work with the markdown files in your
+project from the command line.
+`remark-cli` has many options and you can combine it with many plugins,
+so it should be possible to do what you want.
+If not,
+you can always use [`remark`][github-remark-core] itself manually in a script.
+
+## Install
+
+This package is [ESM only][esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-cli
+```
+
+## Use
+
+Add a table of contents with [`remark-toc`][github-remark-toc] to
+`readme.md`:
+
+```sh
+remark --output --use remark-toc readme.md
+```
+
+Lint all markdown files in the current directory according to the markdown style
+guide with
+[`remark-preset-lint-markdown-style-guide`][github-markdown-style-guide].
+
+```sh
+remark --use remark-preset-lint-markdown-style-guide .
+```
+
+## CLI
+
+The interface of `remark-cli` is explained as follows on its help page
+(`remark --help`):
+
+```text
+Usage: remark [options] [path | glob ...]
+
+ CLI to process markdown with remark
+
+Options:
+
+ --[no-]color specify color in report (on by default)
+ --[no-]config search for configuration files (on by default)
+ -e --ext <extensions> specify extensions
+ --file-path <path> specify path to process as
+ -f --frail exit with 1 on warnings
+ -h --help output usage information
+ --[no-]ignore search for ignore files (on by default)
+ -i --ignore-path <path> specify ignore file
+ --ignore-path-resolve-from cwd|dir resolve patterns in `ignore-path` from its directory or cwd
+ --ignore-pattern <globs> specify ignore patterns
+ --inspect output formatted syntax tree
+ -o --output [path] specify output location
+ -q --quiet output only warnings and errors
+ -r --rc-path <path> specify configuration file
+ --report <reporter> specify reporter
+ -s --setting <settings> specify settings
+ -S --silent output only errors
+ --silently-ignore do not fail when given ignored files
+ --[no-]stdout specify writing to stdout (on by default)
+ -t --tree specify input and output as syntax tree
+ --tree-in specify input as syntax tree
+ --tree-out output syntax tree
+ -u --use <plugins> use plugins
+ --verbose report extra info for messages
+ -v --version output version number
+ -w --watch watch for changes and reprocess
+
+Examples:
+
+ # Process `input.md`
+ $ remark input.md -o output.md
+
+ # Pipe
+ $ remark < input.md > output.md
+
+ # Rewrite all applicable files
+ $ remark . -o
+```
+
+More info on all these options is available at
+[`unified-args`][github-unified-args],
+which does the work.
+`remark-cli` is `unified-args` preconfigured to:
+
+* load `remark-` plugins
+* search for markdown extensions
+ ([`.md`, `.markdown`, etc][github-markdown-extensions])
+* ignore paths found in
+ [`.remarkignore` files][github-unified-engine-ignore-file]
+* load configuration from
+ [`.remarkrc`, `.remarkrc.js`, etc files and
+ `remarkConfig` in `package.json`s][github-unified-engine-config-file]
+
+## Examples
+
+### Example: checking and formatting markdown on the CLI
+
+This example checks and formats markdown with `remark-cli`.
+It assumes you’re in a Node.js package.
+
+Install the CLI and plugins:
+
+```sh
+npm install --save-dev remark-cli remark-preset-lint-consistent remark-preset-lint-recommended remark-toc
+```
+
+…then add an npm script in your `package.json`:
+
+```js
+ /* … */
+ "scripts": {
+ /* … */
+ "format": "remark . --output",
+ /* … */
+ },
+ /* … */
+```
+
+> 💡 **Tip**:
+> add ESLint and such in the `format` script too.
+
+The above change adds a `format` script,
+which can be run with `npm run format`.
+It runs remark on all markdown files (`.`)
+and rewrites them (`--output`).
+Run `./node_modules/.bin/remark --help` for more info on the CLI.
+
+Then add a `remarkConfig` to your `package.json` to configure remark:
+
+```js
+ /* … */
+ "remarkConfig": {
+ "settings": {
+ "bullet": "*", // Use `*` for list item bullets (default)
+ // See <https://github.com/remarkjs/remark/tree/main/packages/remark-stringify> for more options.
+ },
+ "plugins": [
+ "remark-preset-lint-consistent", // Check that markdown is consistent.
+ "remark-preset-lint-recommended", // Few recommended rules.
+ [
+ // Generate a table of contents in `## Contents`
+ "remark-toc",
+ {
+ "heading": "contents"
+ }
+ ]
+ ]
+ },
+ /* … */
+```
+
+> 👉 **Note**:
+> you must remove the comments in the above examples when copy/pasting them as
+> comments are not supported in `package.json` files.
+
+Finally,
+you can run the npm script to check and format markdown files in your project:
+
+```sh
+npm run format
+```
+
+### Example: config files (JSON, YAML, JS)
+
+In the previous example we saw that `remark-cli` was configured from within a
+`package.json` file.
+That’s a good place when the configuration is relatively short,
+when you have a `package.json`,
+and when you don’t need comments
+(which are not allowed in JSON).
+
+You can also define configuration in separate files in different languages.
+With the `package.json` config as inspiration,
+here’s a JavaScript version that can be placed in `.remarkrc.js`:
+
+```js
+import remarkPresetLintConsistent from 'remark-preset-lint-consistent'
+import remarkPresetLintRecommended from 'remark-preset-lint-recommended'
+import remarkToc from 'remark-toc'
+
+const remarkConfig = {
+ plugins: [
+ remarkPresetLintConsistent, // Check that markdown is consistent.
+ remarkPresetLintRecommended, // Few recommended rules.
+ // Generate a table of contents in `## Contents`
+ [remarkToc, {heading: 'contents'}]
+ ],
+ settings: {
+ bullet: '*' // Use `*` for list item bullets (default)
+ // See <https://github.com/remarkjs/remark/tree/main/packages/remark-stringify> for more options.
+ }
+}
+
+export default remarkConfig
+```
+
+This is the same configuration in YAML,
+which can be placed in `.remarkrc.yml`:
+
+```yml
+plugins:
+ # Check that markdown is consistent.
+ - remark-preset-lint-consistent
+ # Few recommended rules.
+ - remark-preset-lint-recommended
+ # Generate a table of contents in `## Contents`
+ - - remark-toc
+ - heading: contents
+settings:
+ bullet: "*"
+```
+
+When `remark-cli` is about to process a markdown file it’ll search the file
+system upwards for configuration files starting at the folder where that file
+exists.
+Take the following file structure as an illustration:
+
+```text
+folder/
+├─ subfolder/
+│ ├─ .remarkrc.json
+│ └─ file.md
+├─ .remarkrc.js
+├─ package.json
+└─ readme.md
+```
+
+When `folder/subfolder/file.md` is processed,
+the closest config file is `folder/subfolder/.remarkrc.json`.
+For `folder/readme.md`,
+it’s `folder/.remarkrc.js`.
+
+The order of precedence is as follows.
+Earlier wins (so in the above file structure `folder/.remarkrc.js` wins over
+`folder/package.json`):
+
+1. `.remarkrc` (JSON)
+2. `.remarkrc.cjs` (CJS)
+3. `.remarkrc.json` (JSON)
+4. `.remarkrc.js` (CJS or ESM, depending on `type: 'module'` in `package.json`)
+5. `.remarkrc.mjs` (ESM)
+6. `.remarkrc.yaml` (YAML)
+7. `.remarkrc.yml` (YAML)
+8. `package.json` with `remarkConfig` field
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release,
+we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-cli@12`,
+compatible with Node.js 16.
+
+## Security
+
+See [*§ Security* in `remarkjs/remark`][github-remark-security].
+
+## Contribute
+
+See [`contributing.md`][health-contributing] in [`remarkjs/.github`][health]
+for ways to get started.
+See [`support.md`][health-support] for ways to get help.
+
+This project has a [code of conduct][health-coc].
+By interacting with this repository,
+organization,
+or community you agree to abide by its terms.
+
+## Sponsor
+
+Support this effort and give back by sponsoring on [OpenCollective][]!
+
+<table>
+<tr valign="middle">
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://vercel.com">Vercel</a><br><br>
+ <a href="https://vercel.com"><img src="https://avatars1.githubusercontent.com/u/14985020?s=256&v=4" width="128"></a>
+</td>
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://motif.land">Motif</a><br><br>
+ <a href="https://motif.land"><img src="https://avatars1.githubusercontent.com/u/74457950?s=256&v=4" width="128"></a>
+</td>
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://www.hashicorp.com">HashiCorp</a><br><br>
+ <a href="https://www.hashicorp.com"><img src="https://avatars1.githubusercontent.com/u/761456?s=256&v=4" width="128"></a>
+</td>
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://www.gitbook.com">GitBook</a><br><br>
+ <a href="https://www.gitbook.com"><img src="https://avatars1.githubusercontent.com/u/7111340?s=256&v=4" width="128"></a>
+</td>
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://www.gatsbyjs.org">Gatsby</a><br><br>
+ <a href="https://www.gatsbyjs.org"><img src="https://avatars1.githubusercontent.com/u/12551863?s=256&v=4" width="128"></a>
+</td>
+</tr>
+<tr valign="middle">
+</tr>
+<tr valign="middle">
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://www.netlify.com">Netlify</a><br><br>
+ <!--OC has a sharper image-->
+ <a href="https://www.netlify.com"><img src="https://images.opencollective.com/netlify/4087de2/logo/256.png" width="128"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://www.coinbase.com">Coinbase</a><br><br>
+ <a href="https://www.coinbase.com"><img src="https://avatars1.githubusercontent.com/u/1885080?s=256&v=4" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://themeisle.com">ThemeIsle</a><br><br>
+ <a href="https://themeisle.com"><img src="https://avatars1.githubusercontent.com/u/58979018?s=128&v=4" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://expo.io">Expo</a><br><br>
+ <a href="https://expo.io"><img src="https://avatars1.githubusercontent.com/u/12504344?s=128&v=4" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://boostnote.io">Boost Note</a><br><br>
+ <a href="https://boostnote.io"><img src="https://images.opencollective.com/boosthub/6318083/logo/128.png" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://markdown.space">Markdown Space</a><br><br>
+ <a href="https://markdown.space"><img src="https://images.opencollective.com/markdown-space/e1038ed/logo/128.png" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://www.holloway.com">Holloway</a><br><br>
+ <a href="https://www.holloway.com"><img src="https://avatars1.githubusercontent.com/u/35904294?s=128&v=4" width="64"></a>
+</td>
+<td width="10%"></td>
+<td width="10%"></td>
+</tr>
+<tr valign="middle">
+<td width="100%" align="center" colspan="8">
+ <br>
+ <a href="https://opencollective.com/unified"><strong>You?</strong></a>
+ <br><br>
+</td>
+</tr>
+</table>
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+<!-- Definitions -->
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark/actions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-cli.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-cli
+
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[file-license]: license
+
+[github-markdown-extensions]: https://github.com/sindresorhus/markdown-extensions
+
+[github-markdown-style-guide]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide
+
+[github-remark]: https://github.com/remarkjs/remark
+
+[github-remark-core]: https://github.com/remarkjs/remark/tree/main/packages/remark
+
+[github-remark-security]: https://github.com/remarkjs/remark#security
+
+[github-remark-toc]: https://github.com/remarkjs/remark-toc
+
+[github-unified-args]: https://github.com/unifiedjs/unified-args
+
+[github-unified-engine-config-file]: https://github.com/unifiedjs/unified-engine#config-files
+
+[github-unified-engine-ignore-file]: https://github.com/unifiedjs/unified-engine#ignore-files
+
+[health]: https://github.com/remarkjs/.github
+
+[health-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[health-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[health-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[opencollective]: https://opencollective.com/unified
diff --git a/documents/markdown/remark/packages_remark-parse_readme.md b/documents/markdown/remark/packages_remark-parse_readme.md
new file mode 100644
index 0000000..024957a
--- /dev/null
+++ b/documents/markdown/remark/packages_remark-parse_readme.md
@@ -0,0 +1,415 @@
+# remark-parse
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+
+**[remark][github-remark]** plugin to add support for parsing from markdown.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkParse)`](#unifieduseremarkparse)
+* [Examples](#examples)
+ * [Example: support GFM and frontmatter](#example-support-gfm-and-frontmatter)
+ * [Example: turning markdown into a man page](#example-turning-markdown-into-a-man-page)
+* [Syntax](#syntax)
+* [Syntax tree](#syntax-tree)
+* [Types](#types)
+* [Compatibility](#compatibility)
+* [Security](#security)
+* [Contribute](#contribute)
+* [Sponsor](#sponsor)
+* [License](#license)
+
+## What is this?
+
+This package is a [unified][github-unified] ([remark][github-remark])
+plugin that defines how to take markdown as input and turn it into a syntax
+tree.
+
+See [the monorepo readme][github-remark] for info on what the remark ecosystem
+is.
+
+## When should I use this?
+
+This plugin adds support to unified for parsing markdown.
+If you also need to serialize markdown,
+you can alternatively use [`remark`][github-remark-core],
+which combines `unified`,
+this plugin,
+and [`remark-stringify`][github-remark-stringify].
+
+If you *just* want to turn markdown into HTML (with maybe a few extensions),
+we recommend [`micromark`][github-micromark] instead.
+If you don’t use plugins and want to access the syntax tree,
+you can directly use
+[`mdast-util-from-markdown`][github-mdast-util-from-markdown].
+remark focusses on making it easier to transform content by abstracting these
+internals away.
+
+You can combine this plugin with other plugins to add syntax extensions.
+Notable examples that deeply integrate with it are
+[`remark-gfm`][github-remark-gfm],
+[`remark-mdx`][github-remark-mdx],
+[`remark-frontmatter`][github-remark-frontmatter],
+[`remark-math`][github-remark-math],
+and
+[`remark-directive`][github-remark-directive].
+You can also use any other [remark plugin][github-remark-plugins]
+after `remark-parse`.
+
+## Install
+
+This package is [ESM only][esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-parse
+```
+
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import remarkParse from 'https://esm.sh/remark-parse@11'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+ import remarkParse from 'https://esm.sh/remark-parse@11?bundle'
+</script>
+```
+
+## Use
+
+Say we have the following module `example.js`:
+
+```js
+import rehypeStringify from 'rehype-stringify'
+import remarkGfm from 'remark-gfm'
+import remarkParse from 'remark-parse'
+import remarkRehype from 'remark-rehype'
+import {unified} from 'unified'
+
+const value = `
+# Mercury
+
+**Mercury** is the first planet from the [Sun](https://en.wikipedia.org/wiki/Sun)
+and the smallest planet in the Solar System.
+`
+
+const file = await unified()
+ .use(remarkParse)
+ .use(remarkGfm)
+ .use(remarkRehype)
+ .use(rehypeStringify)
+ .process(value)
+
+console.log(String(file))
+```
+
+…then running `node example.js` yields:
+
+```html
+<h1>Mercury</h1>
+<p><strong>Mercury</strong> is the first planet from the <a href="https://en.wikipedia.org/wiki/Sun">Sun</a>
+and the smallest planet in the Solar System.</p>
+```
+
+## API
+
+This package exports no identifiers.
+The default export is [`remarkParse`][api-remark-parse].
+
+### `unified().use(remarkParse)`
+
+Add support for parsing from markdown.
+
+###### Parameters
+
+There are no parameters.
+
+###### Returns
+
+Nothing (`undefined`).
+
+## Examples
+
+### Example: support GFM and frontmatter
+
+We support CommonMark by default.
+Non-standard markdown extensions can be enabled with plugins.
+
+This example shows how to support GFM features
+(autolink literals, footnotes, strikethrough, tables, tasklists)
+and frontmatter (YAML):
+
+```js
+import rehypeStringify from 'rehype-stringify'
+import remarkFrontmatter from 'remark-frontmatter'
+import remarkGfm from 'remark-gfm'
+import remarkParse from 'remark-parse'
+import remarkRehype from 'remark-rehype'
+import {unified} from 'unified'
+
+const doc = `---
+layout: solar-system
+---
+
+# Hi ~~Mars~~Venus!
+`
+
+const file = await unified()
+ .use(remarkParse)
+ .use(remarkFrontmatter)
+ .use(remarkGfm)
+ .use(remarkRehype)
+ .use(rehypeStringify)
+ .process(doc)
+
+console.log(String(file))
+```
+
+Yields:
+
+```html
+<h1>Hi <del>Mars</del>Venus!</h1>
+```
+
+### Example: turning markdown into a man page
+
+Man pages (short for manual pages) are a way to document CLIs.
+For an example,
+type `man git-log` in your terminal.
+They use an old markup format called roff.
+There’s a remark plugin,
+[`remark-man`][github-remark-man],
+that can serialize as roff.
+
+This example shows how to turn markdown into man pages by using unified with
+`remark-parse` and `remark-man`:
+
+```js
+import remarkMan from 'remark-man'
+import remarkParse from 'remark-parse'
+import {unified} from 'unified'
+
+const doc = `
+# titan(7) -- largest moon of saturn
+
+Titan is the largest moon…
+`
+
+const file = await unified().use(remarkParse).use(remarkMan).process(doc)
+
+console.log(String(file))
+```
+
+Yields:
+
+```roff
+.TH "TITAN" "7" "January 2025" "" ""
+.SH "NAME"
+\fBtitan\fR - largest moon of saturn
+.P
+Titan is the largest moon…
+```
+
+## Syntax
+
+Markdown is parsed according to CommonMark.
+Other plugins can add support for syntax extensions.
+If you’re interested in extending markdown,
+see [*§ Extensions* in `micromark/micromark`][github-micromark-extensions].
+
+## Syntax tree
+
+The syntax tree used in remark is [mdast][github-mdast].
+
+## Types
+
+This package is fully typed with [TypeScript][].
+It exports the additional type `Options` (which is currently empty).
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release,
+we drop support for unmaintained versions of Node.
+This means we try to keep the current release line,
+`remark-parse@11`,
+compatible with Node.js 16.
+
+## Security
+
+See [*§ Security* in `remarkjs/remark`][github-remark-security].
+
+## Contribute
+
+See [`contributing.md`][health-contributing] in [`remarkjs/.github`][health]
+for ways to get started.
+See [`support.md`][health-support] for ways to get help.
+
+This project has a [code of conduct][health-coc].
+By interacting with this repository,
+organization,
+or community you agree to abide by its terms.
+
+## Sponsor
+
+Support this effort and give back by sponsoring on [OpenCollective][]!
+
+<table>
+<tr valign="middle">
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://vercel.com">Vercel</a><br><br>
+ <a href="https://vercel.com"><img src="https://avatars1.githubusercontent.com/u/14985020?s=256&v=4" width="128"></a>
+</td>
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://motif.land">Motif</a><br><br>
+ <a href="https://motif.land"><img src="https://avatars1.githubusercontent.com/u/74457950?s=256&v=4" width="128"></a>
+</td>
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://www.hashicorp.com">HashiCorp</a><br><br>
+ <a href="https://www.hashicorp.com"><img src="https://avatars1.githubusercontent.com/u/761456?s=256&v=4" width="128"></a>
+</td>
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://www.gitbook.com">GitBook</a><br><br>
+ <a href="https://www.gitbook.com"><img src="https://avatars1.githubusercontent.com/u/7111340?s=256&v=4" width="128"></a>
+</td>
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://www.gatsbyjs.org">Gatsby</a><br><br>
+ <a href="https://www.gatsbyjs.org"><img src="https://avatars1.githubusercontent.com/u/12551863?s=256&v=4" width="128"></a>
+</td>
+</tr>
+<tr valign="middle">
+</tr>
+<tr valign="middle">
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://www.netlify.com">Netlify</a><br><br>
+ <!--OC has a sharper image-->
+ <a href="https://www.netlify.com"><img src="https://images.opencollective.com/netlify/4087de2/logo/256.png" width="128"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://www.coinbase.com">Coinbase</a><br><br>
+ <a href="https://www.coinbase.com"><img src="https://avatars1.githubusercontent.com/u/1885080?s=256&v=4" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://themeisle.com">ThemeIsle</a><br><br>
+ <a href="https://themeisle.com"><img src="https://avatars1.githubusercontent.com/u/58979018?s=128&v=4" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://expo.io">Expo</a><br><br>
+ <a href="https://expo.io"><img src="https://avatars1.githubusercontent.com/u/12504344?s=128&v=4" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://boostnote.io">Boost Note</a><br><br>
+ <a href="https://boostnote.io"><img src="https://images.opencollective.com/boosthub/6318083/logo/128.png" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://markdown.space">Markdown Space</a><br><br>
+ <a href="https://markdown.space"><img src="https://images.opencollective.com/markdown-space/e1038ed/logo/128.png" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://www.holloway.com">Holloway</a><br><br>
+ <a href="https://www.holloway.com"><img src="https://avatars1.githubusercontent.com/u/35904294?s=128&v=4" width="64"></a>
+</td>
+<td width="10%"></td>
+<td width="10%"></td>
+</tr>
+<tr valign="middle">
+<td width="100%" align="center" colspan="8">
+ <br>
+ <a href="https://opencollective.com/unified"><strong>You?</strong></a>
+ <br><br>
+</td>
+</tr>
+</table>
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+<!-- Definitions -->
+
+[api-remark-parse]: #unifieduseremarkparse
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark/actions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-parse.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-parse
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-parse
+
+[badge-size-url]: https://bundlejs.com/?q=remark-parse
+
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[esmsh]: https://esm.sh
+
+[file-license]: license
+
+[github-mdast]: https://github.com/syntax-tree/mdast
+
+[github-mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown
+
+[github-micromark]: https://github.com/micromark/micromark
+
+[github-micromark-extensions]: https://github.com/micromark/micromark#extensions
+
+[github-remark]: https://github.com/remarkjs/remark
+
+[github-remark-core]: https://github.com/remarkjs/remark/tree/main/packages/remark
+
+[github-remark-directive]: https://github.com/remarkjs/remark-directive
+
+[github-remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-man]: https://github.com/remarkjs/remark-man
+
+[github-remark-math]: https://github.com/remarkjs/remark-math
+
+[github-remark-mdx]: https://github.com/mdx-js/mdx/tree/main/packages/remark-mdx
+
+[github-remark-plugins]: https://github.com/remarkjs/remark#plugins
+
+[github-remark-security]: https://github.com/remarkjs/remark#security
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified]: https://github.com/unifiedjs/unified
+
+[health]: https://github.com/remarkjs/.github
+
+[health-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[health-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[health-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[opencollective]: https://opencollective.com/unified
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/packages_remark-stringify_readme.md b/documents/markdown/remark/packages_remark-stringify_readme.md
new file mode 100644
index 0000000..de178af
--- /dev/null
+++ b/documents/markdown/remark/packages_remark-stringify_readme.md
@@ -0,0 +1,407 @@
+# remark-stringify
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+
+**[remark][github-remark]** plugin to add support for serializing to markdown.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkStringify[, options])`](#unifieduseremarkstringify-options)
+ * [`Options`](#options)
+* [Syntax](#syntax)
+* [Syntax tree](#syntax-tree)
+* [Types](#types)
+* [Compatibility](#compatibility)
+* [Security](#security)
+* [Contribute](#contribute)
+* [Sponsor](#sponsor)
+* [License](#license)
+
+## What is this?
+
+This package is a [unified][github-unified] ([remark][github-remark]) plugin
+that defines how to take a syntax tree as input and turn it into serialized
+markdown.
+When it’s used,
+markdown is serialized as the final result.
+
+See [the monorepo readme][github-remark] for info on what the remark ecosystem
+is.
+
+## When should I use this?
+
+This plugin adds support to unified for serializing markdown.
+If you also need to parse markdown,
+you can alternatively use [`remark`][github-remark-core],
+which combines `unified`,
+[`remark-parse`][github-remark-parse],
+and this plugin.
+
+If you don’t use plugins and have access to a syntax tree,
+you can directly use [`mdast-util-to-markdown`][github-mdast-util-to-markdown],
+which is used inside this plugin.
+remark focusses on making it easier to transform content by abstracting these
+internals away.
+
+You can combine this plugin with other plugins to add syntax extensions.
+Notable examples that deeply integrate with it are
+[`remark-gfm`][github-remark-gfm],
+[`remark-mdx`][github-remark-mdx],
+[`remark-frontmatter`][github-remark-frontmatter],
+[`remark-math`][github-remark-math],
+and [`remark-directive`][github-remark-directive].
+You can also use any other [remark plugin][github-remark-plugins]
+before `remark-stringify`.
+
+## Install
+
+This package is [ESM only][esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-stringify
+```
+
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import remarkStringify from 'https://esm.sh/remark-stringify@11'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+ import remarkStringify from 'https://esm.sh/remark-stringify@11?bundle'
+</script>
+```
+
+## Use
+
+Say we have the following module `example.js`:
+
+```js
+import rehypeParse from 'rehype-parse'
+import rehypeRemark from 'rehype-remark'
+import remarkStringify from 'remark-stringify'
+import {unified} from 'unified'
+
+const value = `
+<h1>Uranus</h1>
+<p><b>Uranus</b> is the seventh
+<a href="/wiki/Planet" title="Planet">planet</a> from the Sun and is a gaseous
+cyan <a href="/wiki/Ice_giant" title="Ice giant">ice giant</a>.</p>
+`
+
+const file = await unified()
+ .use(rehypeParse)
+ .use(rehypeRemark)
+ .use(remarkStringify)
+ .process(value)
+
+console.log(String(file))
+```
+
+…then running `node example.js` yields:
+
+```markdown
+# Uranus
+
+**Uranus** is the seventh [planet](/wiki/Planet "Planet") from the Sun and is a gaseous cyan [ice giant](/wiki/Ice_giant "Ice giant").
+```
+
+## API
+
+This package exports no identifiers.
+The default export is [`remarkStringify`][api-remark-stringify].
+
+### `unified().use(remarkStringify[, options])`
+
+Add support for serializing to markdown.
+
+###### Parameters
+
+* `options`
+ ([`Options`][api-options], optional)
+ — configuration
+
+###### Returns
+
+Nothing (`undefined`).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Fields
+
+* `bullet` (`'*'`, `'+'`, or `'-'`, default: `'*'`)
+ — marker to use for bullets of items in unordered lists
+* `bulletOther` (`'*'`, `'+'`, or `'-'`, default: `'-'` when `bullet` is
+ `'*'`, `'*'` otherwise)
+ — marker to use in certain cases where the primary bullet doesn’t work;
+ cannot be equal to `bullet`
+* `bulletOrdered` (`'.'` or `')'`, default: `'.'`)
+ — marker to use for bullets of items in ordered lists
+* `closeAtx` (`boolean`, default: `false`)
+ — add the same number of number signs (`#`) at the end of an ATX heading as
+ the opening sequence
+* `emphasis` (`'*'` or `'_'`, default: `'*'`)
+ — marker to use for emphasis
+* `fence` (``'`'`` or `'~'`, default: ``'`'``)
+ — marker to use for fenced code
+* `fences` (`boolean`, default: `true`)
+ — use fenced code always;
+ when `false`,
+ uses fenced code if there is a language defined,
+ if the code is empty,
+ or if it starts or ends in blank lines
+* `handlers` (`Handlers`, optional)
+ — handle particular nodes;
+ see [`mdast-util-to-markdown`][github-mdast-util-to-markdown] for more info
+* `incrementListMarker` (`boolean`, default: `true`)
+ — increment the counter of ordered lists items
+* `join` (`Array<Join>`, optional)
+ — how to join blocks;
+ see [`mdast-util-to-markdown`][github-mdast-util-to-markdown] for more info
+* `listItemIndent` (`'mixed'`, `'one'`, or `'tab'`, default: `'one'`)
+ — how to indent the content of list items;
+ either with the size of the bullet plus one space (when `'one'`),
+ a tab stop (`'tab'`),
+ or depending on the item and its parent list: `'mixed'` uses `'one'` if the
+ item and list are tight and `'tab'` otherwise
+* `quote` (`'"'` or `"'"`, default: `'"'`)
+ — marker to use for titles
+* `resourceLink` (`boolean`, default: `false`)
+ — always use resource links (`[text](url)`);
+ when `false`, uses autolinks (`<https://example.com>`) when possible
+* `rule` (`'*'`, `'-'`, or `'_'`, default: `'*'`)
+ — marker to use for thematic breaks
+* `ruleRepetition` (`number`, default: `3`, min: `3`)
+ — number of markers to use for thematic breaks
+* `ruleSpaces` (`boolean`, default: `false`)
+ — add spaces between markers in thematic breaks
+* `setext` (`boolean`, default: `false`)
+ — use setext headings when possible;
+ when `true`, uses setext headings (`heading\n=======`) for non-empty rank 1
+ or 2 headings
+* `strong` (`'*'` or `'_'`, default: `'*'`)
+ — marker to use for strong
+* `tightDefinitions` (`boolean`, default: `false`)
+ — join definitions without a blank line
+* `unsafe` (`Array<Unsafe>`, optional)
+ — schemas that define when characters cannot occur;
+ see [`mdast-util-to-markdown`][github-mdast-util-to-markdown] for more info
+
+<!-- Note: `extensions` intentionally not supported/documented. -->
+
+## Syntax
+
+Markdown is serialized according to CommonMark but care is taken to format in a
+way that works with most markdown parsers.
+Other plugins can add support for syntax extensions.
+
+## Syntax tree
+
+The syntax tree used in remark is [mdast][github-mdast].
+
+## Types
+
+This package is fully typed with [TypeScript][].
+It exports the additional type [`Options`][api-options].
+
+It also registers `Settings` with `unified`.
+If you’re passing options with `.data('settings', …)`,
+make sure to import this package somewhere in your types,
+as that registers the fields.
+
+```js
+/**
+ * @import {} from 'remark-stringify'
+ */
+
+import {unified} from 'unified'
+
+// @ts-expect-error: `thisDoesNotExist` is not a valid option.
+unified().data('settings', {thisDoesNotExist: false})
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release,
+we drop support for unmaintained versions of Node.
+This means we try to keep the current release line,
+`remark-stringify@11`,
+compatible with Node.js 16.
+
+## Security
+
+See [*§ Security* in `remarkjs/remark`][github-remark-security].
+
+## Contribute
+
+See [`contributing.md`][health-contributing] in [`remarkjs/.github`][health]
+for ways to get started.
+See [`support.md`][health-support] for ways to get help.
+
+This project has a [code of conduct][health-coc].
+By interacting with this repository,
+organization,
+or community you agree to abide by its terms.
+
+## Sponsor
+
+Support this effort and give back by sponsoring on [OpenCollective][]!
+
+<table>
+<tr valign="middle">
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://vercel.com">Vercel</a><br><br>
+ <a href="https://vercel.com"><img src="https://avatars1.githubusercontent.com/u/14985020?s=256&v=4" width="128"></a>
+</td>
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://motif.land">Motif</a><br><br>
+ <a href="https://motif.land"><img src="https://avatars1.githubusercontent.com/u/74457950?s=256&v=4" width="128"></a>
+</td>
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://www.hashicorp.com">HashiCorp</a><br><br>
+ <a href="https://www.hashicorp.com"><img src="https://avatars1.githubusercontent.com/u/761456?s=256&v=4" width="128"></a>
+</td>
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://www.gitbook.com">GitBook</a><br><br>
+ <a href="https://www.gitbook.com"><img src="https://avatars1.githubusercontent.com/u/7111340?s=256&v=4" width="128"></a>
+</td>
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://www.gatsbyjs.org">Gatsby</a><br><br>
+ <a href="https://www.gatsbyjs.org"><img src="https://avatars1.githubusercontent.com/u/12551863?s=256&v=4" width="128"></a>
+</td>
+</tr>
+<tr valign="middle">
+</tr>
+<tr valign="middle">
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://www.netlify.com">Netlify</a><br><br>
+ <!--OC has a sharper image-->
+ <a href="https://www.netlify.com"><img src="https://images.opencollective.com/netlify/4087de2/logo/256.png" width="128"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://www.coinbase.com">Coinbase</a><br><br>
+ <a href="https://www.coinbase.com"><img src="https://avatars1.githubusercontent.com/u/1885080?s=256&v=4" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://themeisle.com">ThemeIsle</a><br><br>
+ <a href="https://themeisle.com"><img src="https://avatars1.githubusercontent.com/u/58979018?s=128&v=4" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://expo.io">Expo</a><br><br>
+ <a href="https://expo.io"><img src="https://avatars1.githubusercontent.com/u/12504344?s=128&v=4" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://boostnote.io">Boost Note</a><br><br>
+ <a href="https://boostnote.io"><img src="https://images.opencollective.com/boosthub/6318083/logo/128.png" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://markdown.space">Markdown Space</a><br><br>
+ <a href="https://markdown.space"><img src="https://images.opencollective.com/markdown-space/e1038ed/logo/128.png" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://www.holloway.com">Holloway</a><br><br>
+ <a href="https://www.holloway.com"><img src="https://avatars1.githubusercontent.com/u/35904294?s=128&v=4" width="64"></a>
+</td>
+<td width="10%"></td>
+<td width="10%"></td>
+</tr>
+<tr valign="middle">
+<td width="100%" align="center" colspan="8">
+ <br>
+ <a href="https://opencollective.com/unified"><strong>You?</strong></a>
+ <br><br>
+</td>
+</tr>
+</table>
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+<!-- Definitions -->
+
+[api-options]: #options
+
+[api-remark-stringify]: #unifieduseremarkstringify-options
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark/actions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-stringify.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-stringify
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-stringify
+
+[badge-size-url]: https://bundlejs.com/?q=remark-stringify
+
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[esmsh]: https://esm.sh
+
+[file-license]: license
+
+[github-mdast]: https://github.com/syntax-tree/mdast
+
+[github-mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown
+
+[github-remark]: https://github.com/remarkjs/remark
+
+[github-remark-core]: https://github.com/remarkjs/remark/tree/main/packages/remark
+
+[github-remark-directive]: https://github.com/remarkjs/remark-directive
+
+[github-remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-math]: https://github.com/remarkjs/remark-math
+
+[github-remark-mdx]: https://github.com/mdx-js/mdx/tree/main/packages/remark-mdx
+
+[github-remark-parse]: https://github.com/remarkjs/remark/tree/main/packages/remark-parse
+
+[github-remark-plugins]: https://github.com/remarkjs/remark#plugins
+
+[github-remark-security]: https://github.com/remarkjs/remark#security
+
+[github-unified]: https://github.com/unifiedjs/unified
+
+[health]: https://github.com/remarkjs/.github
+
+[health-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[health-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[health-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[opencollective]: https://opencollective.com/unified
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/packages_remark_readme.md b/documents/markdown/remark/packages_remark_readme.md
new file mode 100644
index 0000000..666b171
--- /dev/null
+++ b/documents/markdown/remark/packages_remark_readme.md
@@ -0,0 +1,427 @@
+# remark
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+
+**[unified][github-unified]** processor with support for parsing from markdown
+and serializing to markdown.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`remark()`](#remark-1)
+* [Examples](#examples)
+ * [Example: checking markdown](#example-checking-markdown)
+ * [Example: passing options to `remark-stringify`](#example-passing-options-to-remark-stringify)
+* [Syntax](#syntax)
+* [Syntax tree](#syntax-tree)
+* [Types](#types)
+* [Compatibility](#compatibility)
+* [Security](#security)
+* [Contribute](#contribute)
+* [Sponsor](#sponsor)
+* [License](#license)
+
+## What is this?
+
+This package is a [unified][github-unified] processor with support for parsing
+markdown as input and serializing markdown as output by using unified with
+[`remark-parse`][github-remark-parse] and
+[`remark-stringify`][github-remark-stringify].
+
+See [the monorepo readme][github-remark] for info on what the remark ecosystem
+is.
+
+## When should I use this?
+
+You can use this package when you want to use unified,
+have markdown as input,
+and want markdown as output.
+This package is a shortcut for
+`unified().use(remarkParse).use(remarkStringify)`.
+When the input isn’t markdown (meaning you don’t need `remark-parse`) or the
+output is not markdown (you don’t need `remark-stringify`),
+it’s recommended to use `unified` directly.
+
+When you want to inspect and format markdown files in a project on the command
+line,
+you can use [`remark-cli`][github-remark-cli].
+
+## Install
+
+This package is [ESM only][esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark
+```
+
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import {remark} from 'https://esm.sh/remark@15'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+ import {remark} from 'https://esm.sh/remark@15?bundle'
+</script>
+```
+
+## Use
+
+Say we have the following module `example.js`:
+
+```js
+import {remark} from 'remark'
+import remarkToc from 'remark-toc'
+
+const value = `
+# Pluto
+
+Pluto is a dwarf planet in the Kuiper belt.
+
+## Contents
+
+## History
+
+### Discovery
+
+In the 1840s, Urbain Le Verrier used Newtonian mechanics to predict the position of…
+
+### Name and symbol
+
+The name Pluto is for the Roman god of the underworld, from a Greek epithet for Hades…
+
+### Planet X disproved
+
+Once Pluto was found, its faintness and lack of a viewable disc cast doubt…
+
+## Orbit
+
+Pluto's orbital period is about 248 years…
+`
+
+const file = await remark().use(remarkToc).process(value)
+
+console.error(String(file))
+```
+
+…running that with `node example.js` yields:
+
+```markdown
+# Pluto
+
+Pluto is a dwarf planet in the Kuiper belt.
+
+## Contents
+
+* [History](#history)
+ * [Discovery](#discovery)
+ * [Name and symbol](#name-and-symbol)
+ * [Planet X disproved](#planet-x-disproved)
+* [Orbit](#orbit)
+
+## History
+
+### Discovery
+
+In the 1840s, Urbain Le Verrier used Newtonian mechanics to predict the position of…
+
+### Name and symbol
+
+The name Pluto is for the Roman god of the underworld, from a Greek epithet for Hades…
+
+### Planet X disproved
+
+Once Pluto was found, its faintness and lack of a viewable disc cast doubt…
+
+## Orbit
+
+Pluto's orbital period is about 248 years…
+```
+
+## API
+
+This package exports the identifier [`remark`][api-remark].
+There is no default export.
+
+### `remark()`
+
+Create a new unified processor that already uses
+[`remark-parse`][github-remark-parse] and
+[`remark-stringify`][github-remark-stringify].
+
+You can add more plugins with `use`.
+See [`unified`][github-unified] for more information.
+
+## Examples
+
+### Example: checking markdown
+
+The following example checks that markdown code style is consistent and follows
+some best practices:
+
+```js
+import {remark} from 'remark'
+import remarkPresetLintConsistent from 'remark-preset-lint-consistent'
+import remarkPresetLintRecommended from 'remark-preset-lint-recommended'
+import {reporter} from 'vfile-reporter'
+
+const file = await remark()
+ .use(remarkPresetLintConsistent)
+ .use(remarkPresetLintRecommended)
+ .process('1) Hello, _Jupiter_ and *Neptune*!')
+
+console.error(reporter(file))
+```
+
+Yields:
+
+```text
+1:2 warning Unexpected ordered list marker `)`, expected `.` ordered-list-marker-style remark-lint
+1:25-1:34 warning Unexpected emphasis marker `*`, expected `_` emphasis-marker remark-lint
+ [cause]:
+ 1:11-1:20 info Emphasis marker style `'_'` first defined for `'consistent'` here emphasis-marker remark-lint
+1:35 warning Unexpected missing final newline character, expected line feed (`\n`) at end of file final-newline remark-lint
+
+⚠ 3 warnings
+```
+
+### Example: passing options to `remark-stringify`
+
+When you use `remark-stringify` manually you can pass options to `use`.
+Because `remark-stringify` is already used in `remark` that’s not possible.
+To define options for `remark-stringify`,
+you can instead pass options to `data`:
+
+```js
+import {remark} from 'remark'
+
+const value = `
+# Moons of Neptune
+
+1. Naiad
+2. Thalassa
+3. Despine
+4. …
+`
+
+const file = await remark()
+ .data('settings', {
+ bulletOrdered: ')',
+ incrementListMarker: false,
+ setext: true
+ })
+ .process(value)
+
+console.log(String(file))
+```
+
+Yields:
+
+```markdown
+Moons of Neptune
+================
+
+1) Naiad
+1) Thalassa
+1) Despine
+1) …
+```
+
+## Syntax
+
+Markdown is parsed and serialized according to CommonMark.
+Other plugins can add support for syntax extensions.
+
+## Syntax tree
+
+The syntax tree used in remark is [mdast][github-mdast].
+
+## Types
+
+This package is fully typed with [TypeScript][].
+There are no extra exported types.
+
+It also registers `Settings` with `unified`.
+If you’re passing options with `.data('settings', …)`,
+make sure to import this package somewhere in your types,
+as that registers the fields.
+
+```js
+/**
+ * @import {} from 'remark'
+ */
+
+import {unified} from 'unified'
+
+// @ts-expect-error: `thisDoesNotExist` is not a valid option.
+unified().data('settings', {thisDoesNotExist: false})
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release,
+we drop support for unmaintained versions of Node.
+This means we try to keep the current release line,
+`remark@15`,
+compatible with Node.js 16.
+
+## Security
+
+See [*§ Security* in `remarkjs/remark`][github-remark-security].
+
+## Contribute
+
+See [`contributing.md`][health-contributing] in [`remarkjs/.github`][health]
+for ways to get started.
+See [`support.md`][health-support] for ways to get help.
+
+This project has a [code of conduct][health-coc].
+By interacting with this repository,
+organization,
+or community you agree to abide by its terms.
+
+## Sponsor
+
+Support this effort and give back by sponsoring on [OpenCollective][]!
+
+<table>
+<tr valign="middle">
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://vercel.com">Vercel</a><br><br>
+ <a href="https://vercel.com"><img src="https://avatars1.githubusercontent.com/u/14985020?s=256&v=4" width="128"></a>
+</td>
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://motif.land">Motif</a><br><br>
+ <a href="https://motif.land"><img src="https://avatars1.githubusercontent.com/u/74457950?s=256&v=4" width="128"></a>
+</td>
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://www.hashicorp.com">HashiCorp</a><br><br>
+ <a href="https://www.hashicorp.com"><img src="https://avatars1.githubusercontent.com/u/761456?s=256&v=4" width="128"></a>
+</td>
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://www.gitbook.com">GitBook</a><br><br>
+ <a href="https://www.gitbook.com"><img src="https://avatars1.githubusercontent.com/u/7111340?s=256&v=4" width="128"></a>
+</td>
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://www.gatsbyjs.org">Gatsby</a><br><br>
+ <a href="https://www.gatsbyjs.org"><img src="https://avatars1.githubusercontent.com/u/12551863?s=256&v=4" width="128"></a>
+</td>
+</tr>
+<tr valign="middle">
+</tr>
+<tr valign="middle">
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://www.netlify.com">Netlify</a><br><br>
+ <!--OC has a sharper image-->
+ <a href="https://www.netlify.com"><img src="https://images.opencollective.com/netlify/4087de2/logo/256.png" width="128"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://www.coinbase.com">Coinbase</a><br><br>
+ <a href="https://www.coinbase.com"><img src="https://avatars1.githubusercontent.com/u/1885080?s=256&v=4" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://themeisle.com">ThemeIsle</a><br><br>
+ <a href="https://themeisle.com"><img src="https://avatars1.githubusercontent.com/u/58979018?s=128&v=4" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://expo.io">Expo</a><br><br>
+ <a href="https://expo.io"><img src="https://avatars1.githubusercontent.com/u/12504344?s=128&v=4" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://boostnote.io">Boost Note</a><br><br>
+ <a href="https://boostnote.io"><img src="https://images.opencollective.com/boosthub/6318083/logo/128.png" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://markdown.space">Markdown Space</a><br><br>
+ <a href="https://markdown.space"><img src="https://images.opencollective.com/markdown-space/e1038ed/logo/128.png" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://www.holloway.com">Holloway</a><br><br>
+ <a href="https://www.holloway.com"><img src="https://avatars1.githubusercontent.com/u/35904294?s=128&v=4" width="64"></a>
+</td>
+<td width="10%"></td>
+<td width="10%"></td>
+</tr>
+<tr valign="middle">
+<td width="100%" align="center" colspan="8">
+ <br>
+ <a href="https://opencollective.com/unified"><strong>You?</strong></a>
+ <br><br>
+</td>
+</tr>
+</table>
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+<!-- Definitions -->
+
+[api-remark]: #remark-1
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark/actions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark
+
+[badge-size-url]: https://bundlejs.com/?q=remark
+
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[esmsh]: https://esm.sh
+
+[file-license]: license
+
+[github-mdast]: https://github.com/syntax-tree/mdast
+
+[github-remark]: https://github.com/remarkjs/remark
+
+[github-remark-cli]: https://github.com/remarkjs/remark/tree/main/packages/remark-cli
+
+[github-remark-parse]: https://github.com/remarkjs/remark/tree/main/packages/remark-parse
+
+[github-remark-security]: https://github.com/remarkjs/remark#security
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified]: https://github.com/unifiedjs/unified
+
+[health]: https://github.com/remarkjs/.github
+
+[health-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[health-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[health-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[opencollective]: https://opencollective.com/unified
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/readme.md b/documents/markdown/remark/readme.md
new file mode 100644
index 0000000..73cd482
--- /dev/null
+++ b/documents/markdown/remark/readme.md
@@ -0,0 +1,688 @@
+# ![remark][file-logo]
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+
+**remark** is a tool that transforms markdown with plugins.
+These plugins can inspect and change your markup.
+You can use remark on the server,
+the client,
+CLIs,
+deno,
+etc.
+
+## Feature highlights
+
+* [x] **[compliant][section-syntax]**
+ — 100% to CommonMark,
+ 100% to GFM or MDX with a plugin
+* [x] **[ASTs][section-syntax-tree]**
+ — inspecting and changing content made easy
+* [x] **[popular][]**
+ — world’s most popular markdown parser
+* [x] **[plugins][section-plugins]**
+ — 150+ plugins you can pick and choose from
+
+## Intro
+
+remark is an ecosystem of plugins that work with markdown as structured data,
+specifically ASTs (abstract syntax trees).
+ASTs make it easy for programs to deal with markdown.
+We call those programs plugins.
+Plugins inspect and change trees.
+You can use the many existing plugins or you can make your own.
+
+* to learn markdown,
+ see this [cheatsheet and tutorial][commonmark-help]
+* for more about us,
+ see [`unifiedjs.com`][unifiedjs]
+* for questions,
+ see [support][health-support]
+* to help,
+ see [contribute][section-contribute] or [sponsor][section-sponsor] below
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Plugins](#plugins)
+* [Examples](#examples)
+ * [Example: turning markdown into HTML](#example-turning-markdown-into-html)
+ * [Example: support for GFM and frontmatter](#example-support-for-gfm-and-frontmatter)
+ * [Example: checking markdown](#example-checking-markdown)
+ * [Example: checking and formatting markdown on the CLI](#example-checking-and-formatting-markdown-on-the-cli)
+* [Syntax](#syntax)
+* [Syntax tree](#syntax-tree)
+* [Types](#types)
+* [Compatibility](#compatibility)
+* [Security](#security)
+* [Contribute](#contribute)
+* [Sponsor](#sponsor)
+* [License](#license)
+
+## What is this?
+
+With this project and a plugin,
+you can turn this markdown:
+
+```markdown
+# Hello, *Mercury*!
+```
+
+…into the following HTML:
+
+```html
+<h1>Hello, <em>Mercury</em>!</h1>
+```
+
+<details><summary>Show example code</summary>
+
+```js
+import rehypeStringify from 'rehype-stringify'
+import remarkParse from 'remark-parse'
+import remarkRehype from 'remark-rehype'
+import {unified} from 'unified'
+
+const file = await unified()
+ .use(remarkParse)
+ .use(remarkRehype)
+ .use(rehypeStringify)
+ .process('# Hello, *Mercury*!')
+
+console.log(String(file)) // => '<h1>Hello, <em>Mercury</em>!</h1>'
+```
+
+</details>
+
+With another plugin,
+you can turn this markdown:
+
+```markdown
+# Hi, Saturn!
+```
+
+…into the following markdown:
+
+```markdown
+## Hi, Saturn!
+```
+
+<details><summary>Show example code</summary>
+
+```js
+/**
+ * @import {Root} from 'mdast'
+ */
+
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {unified} from 'unified'
+import {visit} from 'unist-util-visit'
+
+const file = await unified()
+ .use(remarkParse)
+ .use(myRemarkPluginToIncreaseHeadings)
+ .use(remarkStringify)
+ .process('# Hi, Saturn!')
+
+console.log(String(file)) // => '## Hi, Saturn!'
+
+function myRemarkPluginToIncreaseHeadings() {
+ /**
+ * @param {Root} tree
+ */
+ return function (tree) {
+ visit(tree, function (node) {
+ if (node.type === 'heading') {
+ node.depth++
+ }
+ })
+ }
+}
+```
+
+</details>
+
+You can use remark for many different things.
+**[unified][github-unified]** is the core project that transforms content with
+ASTs.
+**remark** adds support for markdown to unified.
+**[mdast][github-mdast]** is the markdown AST that remark uses.
+
+This GitHub repository is a monorepo that contains the following packages:
+
+* [`remark-parse`][github-remark-parse]
+ — plugin to take markdown as input and turn it into a syntax tree (mdast)
+* [`remark-stringify`][github-remark-stringify]
+ — plugin to take a syntax tree (mdast) and turn it into markdown as output
+* [`remark`][github-remark-core]
+ — `unified`, `remark-parse`, and `remark-stringify`,
+ useful when input and output are markdown
+* [`remark-cli`][github-remark-cli]
+ — CLI around `remark` to inspect and format markdown in scripts
+
+## When should I use this?
+
+Depending on the input you have and output you want,
+you can use different parts of remark.
+If the input is markdown,
+you can use `remark-parse` with `unified`.
+If the output is markdown,
+you can use `remark-stringify` with `unified`.
+If both the input and output are markdown,
+you can use `remark` on its own.
+When you want to inspect and format markdown files in a project,
+you can use `remark-cli`.
+
+If you *just* want to turn markdown into HTML (with maybe a few extensions),
+we recommend [`micromark`][github-micromark] instead.
+
+If you don’t use plugins and want to deal with syntax trees manually,
+you can use [`mdast-util-from-markdown`][github-mdast-util-from-markdown] and
+[`mdast-util-to-markdown`][github-mdast-util-to-markdown].
+
+## Plugins
+
+remark plugins deal with markdown.
+Some popular examples are:
+
+* [`remark-gfm`][github-remark-gfm]
+ — add support for GFM (GitHub flavored markdown)
+* [`remark-lint`][github-remark-lint]
+ — inspect markdown and warn about inconsistencies
+* [`remark-toc`][github-remark-toc]
+ — generate a table of contents
+* [`remark-rehype`][github-remark-rehype]
+ — turn markdown into HTML
+
+These plugins are exemplary because what they do and how they do it is quite
+different,
+respectively to extend markdown syntax,
+inspect trees,
+change trees,
+and transform to other syntax trees.
+
+You can choose from the 150+ plugins that already exist.
+Here are three good ways to find plugins:
+
+* [`awesome-remark`][github-awesome-remark]
+ — selection of the most awesome projects
+* [List of plugins][file-list-of-plugins]
+ — list of all plugins
+* [`remark-plugin` topic][github-topic-remark-plugin]
+ — any tagged repo on GitHub
+
+Some plugins are maintained by us here in the `@remarkjs` organization while
+others are maintained by folks elsewhere.
+Anyone can make remark plugins,
+so as always when choosing whether to include
+dependencies in your project,
+make sure to carefully assess the quality of remark plugins too.
+
+## Examples
+
+### Example: turning markdown into HTML
+
+remark is an ecosystem around markdown.
+A different ecosystem is for HTML:
+[rehype][github-rehype].
+The following example turns markdown into HTML by combining both ecosystems with
+[`remark-rehype`][github-remark-rehype]:
+
+```js
+import rehypeSanitize from 'rehype-sanitize'
+import rehypeStringify from 'rehype-stringify'
+import remarkParse from 'remark-parse'
+import remarkRehype from 'remark-rehype'
+import {unified} from 'unified'
+
+const file = await unified()
+ .use(remarkParse)
+ .use(remarkRehype)
+ .use(rehypeSanitize)
+ .use(rehypeStringify)
+ .process('# Hello, Neptune!')
+
+console.log(String(file))
+```
+
+Yields:
+
+```html
+<h1>Hello, Neptune!</h1>
+```
+
+### Example: support for GFM and frontmatter
+
+remark supports CommonMark by default.
+Non-standard markdown extensions can be enabled with plugins.
+The following example adds support for GFM
+(autolink literals, footnotes, strikethrough, tables, tasklists)
+and frontmatter (YAML):
+
+```js
+import rehypeStringify from 'rehype-stringify'
+import remarkFrontmatter from 'remark-frontmatter'
+import remarkGfm from 'remark-gfm'
+import remarkParse from 'remark-parse'
+import remarkRehype from 'remark-rehype'
+import {unified} from 'unified'
+
+const value = `---
+layout: solar-system
+---
+
+# Hi ~~Mars~~Venus!
+`
+
+const file = await unified()
+ .use(remarkParse)
+ .use(remarkFrontmatter)
+ .use(remarkGfm)
+ .use(remarkRehype)
+ .use(rehypeStringify)
+ .process(value)
+
+console.log(String(file))
+```
+
+Yields:
+
+```html
+<h1>Hi <del>Mars</del>Venus!</h1>
+```
+
+### Example: checking markdown
+
+The following example checks that markdown code style is consistent and follows
+recommended best practices:
+
+```js
+import {remark} from 'remark'
+import remarkPresetLintConsistent from 'remark-preset-lint-consistent'
+import remarkPresetLintRecommended from 'remark-preset-lint-recommended'
+import {reporter} from 'vfile-reporter'
+
+const file = await remark()
+ .use(remarkPresetLintConsistent)
+ .use(remarkPresetLintRecommended)
+ .process('1) Hello, _Jupiter_ and *Neptune*!')
+
+console.error(reporter(file))
+```
+
+Yields:
+
+```text
+1:2 warning Unexpected ordered list marker `)`, expected `.` ordered-list-marker-style remark-lint
+1:25-1:34 warning Unexpected emphasis marker `*`, expected `_` emphasis-marker remark-lint
+ [cause]:
+ 1:11-1:20 info Emphasis marker style `'_'` first defined for `'consistent'` here emphasis-marker remark-lint
+1:35 warning Unexpected missing final newline character, expected line feed (`\n`) at end of file final-newline remark-lint
+
+⚠ 3 warnings
+```
+
+### Example: checking and formatting markdown on the CLI
+
+The following example checks and formats markdown with `remark-cli`,
+which is the CLI (command line interface) of remark that you can use in your
+terminal.
+This example assumes you’re in a Node.js package.
+
+First,
+install the CLI and plugins:
+
+```sh
+npm install --save-dev remark-cli remark-preset-lint-consistent remark-preset-lint-recommended remark-toc
+```
+
+…then add an npm script in your `package.json`:
+
+```js
+ /* … */
+ "scripts": {
+ /* … */
+ "format": "remark . --output",
+ /* … */
+ },
+ /* … */
+```
+
+> 💡 **Tip**:
+> add ESLint and such in the `format` script too.
+
+The above change adds a `format` script,
+which can be run with `npm run format`.
+It runs remark on all markdown files (`.`) and rewrites them (`--output`).
+Run `./node_modules/.bin/remark --help` for more info on the CLI.
+
+Then,
+add a `remarkConfig` to your `package.json` to configure remark:
+
+```js
+ /* … */
+ "remarkConfig": {
+ "settings": {
+ "bullet": "*", // Use `*` for list item bullets (default)
+ // See <https://github.com/remarkjs/remark/tree/main/packages/remark-stringify> for more options.
+ },
+ "plugins": [
+ "remark-preset-lint-consistent", // Check that markdown is consistent.
+ "remark-preset-lint-recommended", // Few recommended rules.
+ [
+ // Generate a table of contents in `## Contents`
+ "remark-toc",
+ {
+ "heading": "contents"
+ }
+ ]
+ ]
+ },
+ /* … */
+```
+
+> 👉 **Note**:
+> you must remove the comments in the above examples when copy/pasting them as
+> comments are not supported in `package.json` files.
+
+Finally,
+you can run the npm script to check and format markdown files in your project:
+
+```sh
+npm run format
+```
+
+## Syntax
+
+Markdown is parsed and serialized according to CommonMark.
+Other plugins can add support for syntax extensions.
+
+We use [`micromark`][github-micromark] for our parsing.
+See its documentation for more information on markdown,
+CommonMark,
+and extensions.
+
+## Syntax tree
+
+The syntax tree used in remark is [mdast][github-mdast].
+It represents markdown constructs as JSON objects.
+
+This markdown:
+
+```markdown
+## Hello *Pluto*!
+```
+
+…yields the following tree (positional info remove for brevity):
+
+```js
+{
+ type: 'heading',
+ depth: 2,
+ children: [
+ {type: 'text', value: 'Hello '},
+ {type: 'emphasis', children: [{type: 'text', value: 'Pluto'}]}
+ {type: 'text', value: '!'}
+ ]
+}
+```
+
+## Types
+
+The remark organization and the unified collective as a whole is fully typed
+with [TypeScript][].
+Types for mdast are available in [`@types/mdast`][github-types-mdast].
+
+For TypeScript to work,
+it is important to type your plugins.
+For example:
+
+```js
+/**
+ * @import {Root} from 'mdast'
+ * @import {VFile} from 'vfile'
+ */
+
+/**
+ * @typedef Options
+ * Configuration.
+ * @property {boolean | null | undefined} [someField]
+ * Some option (optional).
+ */
+
+/**
+ * My plugin.
+ *
+ * @param {Options | null | undefined} [options]
+ * Configuration (optional).
+ * @returns
+ * Transform.
+ */
+export function myRemarkPluginAcceptingOptions(options) {
+ /**
+ * Transform.
+ *
+ * @param {Root} tree
+ * Tree.
+ * @param {VFile} file
+ * File
+ * @returns {undefined}
+ * Nothing.
+ */
+ return function (tree, file) {
+ // Do things.
+ }
+}
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release,
+we drop support for unmaintained versions of Node.
+This means we try to keep the current release line compatible with Node.js 16.
+
+## Security
+
+As markdown can be turned into HTML and improper use of HTML can open you up to
+[cross-site scripting (XSS)][wikipedia-xss] attacks,
+use of remark can be unsafe.
+When going to HTML,
+you will combine remark with **[rehype][github-rehype]**,
+in which case you should use [`rehype-sanitize`][github-rehype-sanitize].
+
+Another security aspect is DDoS attacks.
+An attacker could cause a crash or slow down with big files.
+Crashes can also originate from smaller payloads,
+often when thousands of things (such as lists or links) are opened.
+It is wise to cap the accepted size of input
+(500kb can hold a big book)
+and to process content in a different thread or worker so that it can be
+stopped when needed.
+
+Use of remark plugins could also open you up to other attacks.
+Carefully assess each plugin and the risks involved in using them.
+
+For info on how to submit a report,
+see our [security policy][health-security].
+
+## Contribute
+
+See [`contributing.md`][health-contributing] in [`remarkjs/.github`][health]
+for ways to get started.
+See [`support.md`][health-support] for ways to get help.
+
+This project has a [code of conduct][health-coc].
+By interacting with this repository,
+organization,
+or community you agree to abide by its terms.
+
+## Sponsor
+
+Support this effort and give back by sponsoring on [OpenCollective][]!
+
+<table>
+<tr valign="middle">
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://vercel.com">Vercel</a><br><br>
+ <a href="https://vercel.com"><img src="https://avatars1.githubusercontent.com/u/14985020?s=256&v=4" width="128"></a>
+</td>
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://motif.land">Motif</a><br><br>
+ <a href="https://motif.land"><img src="https://avatars1.githubusercontent.com/u/74457950?s=256&v=4" width="128"></a>
+</td>
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://www.hashicorp.com">HashiCorp</a><br><br>
+ <a href="https://www.hashicorp.com"><img src="https://avatars1.githubusercontent.com/u/761456?s=256&v=4" width="128"></a>
+</td>
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://www.gitbook.com">GitBook</a><br><br>
+ <a href="https://www.gitbook.com"><img src="https://avatars1.githubusercontent.com/u/7111340?s=256&v=4" width="128"></a>
+</td>
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://www.gatsbyjs.org">Gatsby</a><br><br>
+ <a href="https://www.gatsbyjs.org"><img src="https://avatars1.githubusercontent.com/u/12551863?s=256&v=4" width="128"></a>
+</td>
+</tr>
+<tr valign="middle">
+</tr>
+<tr valign="middle">
+<td width="20%" align="center" rowspan="2" colspan="2">
+ <a href="https://www.netlify.com">Netlify</a><br><br>
+ <!--OC has a sharper image-->
+ <a href="https://www.netlify.com"><img src="https://images.opencollective.com/netlify/4087de2/logo/256.png" width="128"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://www.coinbase.com">Coinbase</a><br><br>
+ <a href="https://www.coinbase.com"><img src="https://avatars1.githubusercontent.com/u/1885080?s=256&v=4" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://themeisle.com">ThemeIsle</a><br><br>
+ <a href="https://themeisle.com"><img src="https://avatars1.githubusercontent.com/u/58979018?s=128&v=4" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://expo.io">Expo</a><br><br>
+ <a href="https://expo.io"><img src="https://avatars1.githubusercontent.com/u/12504344?s=128&v=4" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://boostnote.io">Boost Note</a><br><br>
+ <a href="https://boostnote.io"><img src="https://images.opencollective.com/boosthub/6318083/logo/128.png" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://markdown.space">Markdown Space</a><br><br>
+ <a href="https://markdown.space"><img src="https://images.opencollective.com/markdown-space/e1038ed/logo/128.png" width="64"></a>
+</td>
+<td width="10%" align="center">
+ <a href="https://www.holloway.com">Holloway</a><br><br>
+ <a href="https://www.holloway.com"><img src="https://avatars1.githubusercontent.com/u/35904294?s=128&v=4" width="64"></a>
+</td>
+<td width="10%"></td>
+<td width="10%"></td>
+</tr>
+<tr valign="middle">
+<td width="100%" align="center" colspan="8">
+ <br>
+ <a href="https://opencollective.com/unified"><strong>You?</strong></a>
+ <br><br>
+</td>
+</tr>
+</table>
+
+## License
+
+[MIT](license) © [Titus Wormer](https://wooorm.com)
+
+<!-- Definitions -->
+
+[badge-build-image]: https://github.com/remarkjs/remark/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark/actions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark
+
+[badge-size-url]: https://bundlejs.com/?q=remark
+
+[commonmark-help]: https://commonmark.org/help/
+
+[file-list-of-plugins]: doc/plugins.md#list-of-plugins
+
+[file-logo]: https://raw.githubusercontent.com/remarkjs/remark/1f338e72/logo.svg?sanitize=true
+
+[github-awesome-remark]: https://github.com/remarkjs/awesome-remark
+
+[github-mdast]: https://github.com/syntax-tree/mdast
+
+[github-mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown
+
+[github-mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown
+
+[github-micromark]: https://github.com/micromark/micromark
+
+[github-rehype]: https://github.com/rehypejs/rehype
+
+[github-rehype-sanitize]: https://github.com/rehypejs/rehype-sanitize
+
+[github-remark-cli]: https://github.com/remarkjs/remark/tree/main/packages/remark-cli
+
+[github-remark-core]: https://github.com/remarkjs/remark/tree/main/packages/remark
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-parse]: https://github.com/remarkjs/remark/tree/main/packages/remark-parse
+
+[github-remark-rehype]: https://github.com/remarkjs/remark-rehype
+
+[github-remark-stringify]: packages/remark-stringify/
+
+[github-remark-toc]: https://github.com/remarkjs/remark-toc
+
+[github-topic-remark-plugin]: https://github.com/topics/remark-plugin
+
+[github-types-mdast]: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/mdast
+
+[github-unified]: https://github.com/unifiedjs/unified
+
+[health]: https://github.com/remarkjs/.github
+
+[health-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[health-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[health-security]: https://github.com/remarkjs/.github/blob/main/security.md
+
+[health-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[opencollective]: https://opencollective.com/unified
+
+[popular]: https://www.npmtrends.com/remark-parse-vs-marked-vs-micromark-vs-markdown-it
+
+[section-contribute]: #contribute
+
+[section-plugins]: #plugins
+
+[section-sponsor]: #sponsor
+
+[section-syntax]: #syntax
+
+[section-syntax-tree]: #syntax-tree
+
+[typescript]: https://www.typescriptlang.org
+
+[unifiedjs]: https://unifiedjs.com
+
+[wikipedia-xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
diff --git a/documents/markdown/remark/remark-frontmatter_readme.md b/documents/markdown/remark/remark-frontmatter_readme.md
new file mode 100644
index 0000000..7e4da1b
--- /dev/null
+++ b/documents/markdown/remark/remark-frontmatter_readme.md
@@ -0,0 +1,615 @@
+# remark-frontmatter
+
+[![Build][build-badge]][build]
+[![Coverage][coverage-badge]][coverage]
+[![Downloads][downloads-badge]][downloads]
+[![Size][size-badge]][size]
+[![Sponsors][sponsors-badge]][collective]
+[![Backers][backers-badge]][collective]
+[![Chat][chat-badge]][chat]
+
+**[remark][]** plugin to support frontmatter (YAML, TOML, and more).
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkFrontmatter[, options])`](#unifieduseremarkfrontmatter-options)
+ * [`Options`](#options)
+* [Examples](#examples)
+ * [Example: different markers and fences](#example-different-markers-and-fences)
+ * [Example: frontmatter as metadata](#example-frontmatter-as-metadata)
+ * [Example: frontmatter in MDX](#example-frontmatter-in-mdx)
+* [Authoring](#authoring)
+* [HTML](#html)
+* [CSS](#css)
+* [Syntax](#syntax)
+* [Syntax tree](#syntax-tree)
+* [Types](#types)
+* [Compatibility](#compatibility)
+* [Security](#security)
+* [Related](#related)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package is a [unified][] ([remark][]) plugin to add support for YAML, TOML,
+and other frontmatter.
+
+Frontmatter is a metadata format in front of the content.
+It’s typically written in YAML and is often used with markdown.
+
+This plugin follow how GitHub handles frontmatter.
+GitHub only supports YAML frontmatter, but this plugin also supports different
+flavors (such as TOML).
+
+## When should I use this?
+
+You can use frontmatter when you want authors, that have some markup
+experience, to configure where or how the content is displayed or supply
+metadata about content, and know that the markdown is only used in places
+that support frontmatter.
+A good example use case is markdown being rendered by (static) site generators.
+
+If you *just* want to turn markdown into HTML (with maybe a few extensions such
+as frontmatter), we recommend [`micromark`][micromark] with
+[`micromark-extension-frontmatter`][micromark-extension-frontmatter] instead.
+If you don’t use plugins and want to access the syntax tree, you can use
+[`mdast-util-from-markdown`][mdast-util-from-markdown] with
+[`mdast-util-frontmatter`][mdast-util-frontmatter].
+
+## Install
+
+This package is [ESM only][esm].
+In Node.js (version 16+), install with [npm][]:
+
+```sh
+npm install remark-frontmatter
+```
+
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import remarkFrontmatter from 'https://esm.sh/remark-frontmatter@5'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+ import remarkFrontmatter from 'https://esm.sh/remark-frontmatter@5?bundle'
+</script>
+```
+
+## Use
+
+Say our document `example.md` contains:
+
+```markdown
++++
+layout = "solar-system"
++++
+
+# Jupiter
+```
+
+…and our module `example.js` contains:
+
+```js
+import remarkFrontmatter from 'remark-frontmatter'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {unified} from 'unified'
+import {read} from 'to-vfile'
+
+const file = await unified()
+ .use(remarkParse)
+ .use(remarkStringify)
+ .use(remarkFrontmatter, ['yaml', 'toml'])
+ .use(function () {
+ return function (tree) {
+ console.dir(tree)
+ }
+ })
+ .process(await read('example.md'))
+
+console.log(String(file))
+```
+
+…then running `node example.js` yields:
+
+```js
+{
+ type: 'root',
+ children: [
+ {type: 'toml', value: 'layout = "solar-system"', position: [Object]},
+ {type: 'heading', depth: 1, children: [Array], position: [Object]}
+ ],
+ position: {
+ start: {line: 1, column: 1, offset: 0},
+ end: {line: 6, column: 1, offset: 43}
+ }
+}
+```
+
+```markdown
++++
+layout = "solar-system"
++++
+
+# Jupiter
+```
+
+## API
+
+This package exports no identifiers.
+The default export is [`remarkFrontmatter`][api-remark-frontmatter].
+
+### `unified().use(remarkFrontmatter[, options])`
+
+Add support for frontmatter.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], default: `'yaml'`)
+ — configuration
+
+###### Returns
+
+Nothing (`undefined`).
+
+###### Notes
+
+Doesn’t parse the data inside them:
+[create your own plugin][unified-create-plugin] to do that.
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Type
+
+```ts
+type Options = Array<Matter | Preset> | Matter | Preset
+
+/**
+ * Sequence.
+ *
+ * Depending on how this structure is used, it reflects a marker or a fence.
+ */
+export type Info = {
+ /**
+ * Closing.
+ */
+ close: string
+ /**
+ * Opening.
+ */
+ open: string
+}
+
+/**
+ * Fence configuration.
+ */
+type FenceProps = {
+ /**
+ * Complete fences.
+ *
+ * This can be used when fences contain different characters or lengths
+ * other than 3.
+ * Pass `open` and `close` to interface to specify different characters for opening and
+ * closing fences.
+ */
+ fence: Info | string
+ /**
+ * If `fence` is set, `marker` must not be set.
+ */
+ marker?: never
+}
+
+/**
+ * Marker configuration.
+ */
+type MarkerProps = {
+ /**
+ * Character repeated 3 times, used as complete fences.
+ *
+ * For example the character `'-'` will result in `'---'` being used as the
+ * fence
+ * Pass `open` and `close` to specify different characters for opening and
+ * closing fences.
+ */
+ marker: Info | string
+ /**
+ * If `marker` is set, `fence` must not be set.
+ */
+ fence?: never
+}
+
+/**
+ * Fields describing a kind of matter.
+ *
+ * > 👉 **Note**: using `anywhere` is a terrible idea.
+ * > It’s called frontmatter, not matter-in-the-middle or so.
+ * > This makes your markdown less portable.
+ *
+ * > 👉 **Note**: `marker` and `fence` are mutually exclusive.
+ * > If `marker` is set, `fence` must not be set, and vice versa.
+ */
+type Matter = (MatterProps & FenceProps) | (MatterProps & MarkerProps)
+
+/**
+ * Fields describing a kind of matter.
+ */
+type MatterProps = {
+ /**
+ * Node type to tokenize as.
+ */
+ type: string
+ /**
+ * Whether matter can be found anywhere in the document, normally, only matter
+ * at the start of the document is recognized.
+ *
+ * > 👉 **Note**: using this is a terrible idea.
+ * > It’s called frontmatter, not matter-in-the-middle or so.
+ * > This makes your markdown less portable.
+ */
+ anywhere?: boolean | null | undefined
+}
+
+/**
+ * Known name of a frontmatter style.
+ */
+type Preset = 'toml' | 'yaml'
+```
+
+## Examples
+
+### Example: different markers and fences
+
+Here are a couple of example of different matter objects and what frontmatter
+they match.
+
+To match frontmatter with the same opening and closing fence, namely three of
+the same markers, use for example `{type: 'yaml', marker: '-'}`, which matches:
+
+```yaml
+---
+key: value
+---
+```
+
+To match frontmatter with different opening and closing fences, which each use
+three different markers, use for example
+`{type: 'custom', marker: {open: '<', close: '>'}}`, which matches:
+
+```text
+<<<
+data
+>>>
+```
+
+To match frontmatter with the same opening and closing fences, which both use
+the same custom string, use for example `{type: 'custom', fence: '+=+=+=+'}`,
+which matches:
+
+```text
++=+=+=+
+data
++=+=+=+
+```
+
+To match frontmatter with different opening and closing fences, which each use
+different custom strings, use for example
+`{type: 'json', fence: {open: '{', close: '}'}}`, which matches:
+
+```json
+{
+ "key": "value"
+}
+```
+
+### Example: frontmatter as metadata
+
+This plugin handles the syntax of frontmatter in markdown.
+It does not *parse* that frontmatter as say YAML or TOML and expose it
+somewhere.
+
+In unified, there is a place for metadata about files:
+[`file.data`][vfile-file-data].
+For frontmatter specifically, it’s customary to expose parsed data at `file.data.matter`.
+
+We can make a plugin that does this.
+This example uses the utility [`vfile-matter`][vfile-matter], which is specific
+to YAML.
+To support other data languages, look at this utility for inspiration.
+
+`my-unified-plugin-handling-yaml-matter.js`:
+
+```js
+/**
+ * @typedef {import('unist').Node} Node
+ * @typedef {import('vfile').VFile} VFile
+ */
+
+import {matter} from 'vfile-matter'
+
+/**
+ * Parse YAML frontmatter and expose it at `file.data.matter`.
+ *
+ * @returns
+ * Transform.
+ */
+export default function myUnifiedPluginHandlingYamlMatter() {
+ /**
+ * Transform.
+ *
+ * @param {Node} tree
+ * Tree.
+ * @param {VFile} file
+ * File.
+ * @returns {undefined}
+ * Nothing.
+ */
+ return function (tree, file) {
+ matter(file)
+ }
+}
+```
+
+…with an example markdown file `example.md`:
+
+```markdown
+---
+key: value
+---
+
+# Venus
+```
+
+…and using the plugin with an `example.js` containing:
+
+```js
+import remarkParse from 'remark-parse'
+import remarkFrontmatter from 'remark-frontmatter'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import myUnifiedPluginHandlingYamlMatter from './my-unified-plugin-handling-yaml-matter.js'
+
+const file = await unified()
+ .use(remarkParse)
+ .use(remarkStringify)
+ .use(remarkFrontmatter)
+ .use(myUnifiedPluginHandlingYamlMatter)
+ .process(await read('example.md'))
+
+console.log(file.data.matter) // => {key: 'value'}
+```
+
+### Example: frontmatter in MDX
+
+MDX has the ability to export data from it, where markdown does not.
+When authoring MDX, you can write `export` statements and expose arbitrary data
+through them.
+It is also possible to write frontmatter, and let a plugin turn those into
+export statements.
+
+To automatically turn frontmatter into export statements, use
+[`remark-mdx-frontmatter`][remark-mdx-frontmatter].
+
+With an `example.mdx` as follows:
+
+```mdx
+---
+key: value
+---
+
+# Mars
+```
+
+This plugin can be used as follows:
+
+```js
+import {compile} from '@mdx-js/mdx'
+import remarkFrontmatter from 'remark-frontmatter'
+import remarkMdxFrontmatter from 'remark-mdx-frontmatter'
+import {read, write} from 'to-vfile'
+
+const file = await compile(await read('example.mdx'), {
+ remarkPlugins: [remarkFrontmatter, [remarkMdxFrontmatter, {name: 'matter'}]]
+})
+file.path = 'output.js'
+await write(file)
+
+const mod = await import('./output.js')
+console.log(mod.matter) // => {key: 'value'}
+```
+
+## Authoring
+
+When authoring markdown with frontmatter, it’s recommended to use YAML
+frontmatter if possible.
+While YAML has some warts, it works in the most places, so using it guarantees
+the highest chance of portability.
+
+In certain ecosystems, other flavors are widely used.
+For example, in the Rust ecosystem, TOML is often used.
+In such cases, using TOML is an okay choice.
+
+When possible, do not use other types of frontmatter, and do not allow
+frontmatter anywhere.
+
+## HTML
+
+Frontmatter does not relate to HTML elements.
+It is typically stripped, which is what [`remark-rehype`][remark-rehype] does.
+
+## CSS
+
+This package does not relate to CSS.
+
+## Syntax
+
+See [*Syntax* in
+`micromark-extension-frontmatter`](https://github.com/micromark/micromark-extension-frontmatter#syntax).
+
+## Syntax tree
+
+See [*Syntax tree* in
+`mdast-util-frontmatter`](https://github.com/syntax-tree/mdast-util-frontmatter#syntax-tree).
+
+## Types
+
+This package is fully typed with [TypeScript][].
+It exports the additional type [`Options`][api-options].
+
+The YAML node type is supported in `@types/mdast` by default.
+To add other node types, register them by adding them to
+`FrontmatterContentMap`:
+
+```ts
+import type {Data, Literal} from 'mdast'
+
+interface Toml extends Literal {
+ type: 'toml'
+ data?: Data
+}
+
+declare module 'mdast' {
+ interface FrontmatterContentMap {
+ // Allow using TOML nodes defined by `remark-frontmatter`.
+ toml: Toml
+ }
+}
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line, `remark-frontmatter@^5`,
+compatible with Node.js 16.
+
+This plugin works with unified 6+ and remark 13+.
+
+## Security
+
+Use of `remark-frontmatter` does not involve **[rehype][]** ([hast][]) or user
+content so there are no openings for [cross-site scripting (XSS)][wiki-xss]
+attacks.
+
+## Related
+
+* [`remark-yaml-config`](https://github.com/remarkjs/remark-yaml-config)
+ — configure remark from YAML configuration
+* [`remark-gfm`](https://github.com/remarkjs/remark-gfm)
+ — support GFM (autolink literals, footnotes, strikethrough, tables,
+ tasklists)
+* [`remark-mdx`](https://github.com/mdx-js/mdx/tree/main/packages/remark-mdx)
+ — support MDX (ESM, JSX, expressions)
+* [`remark-directive`](https://github.com/remarkjs/remark-directive)
+ — support directives
+* [`remark-math`](https://github.com/remarkjs/remark-math)
+ — support math
+
+## Contribute
+
+See [`contributing.md`][contributing] in [`remarkjs/.github`][health] for ways
+to get started.
+See [`support.md`][support] for ways to get help.
+
+This project has a [code of conduct][coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][license] © [Titus Wormer][author]
+
+<!-- Definitions -->
+
+[build-badge]: https://github.com/remarkjs/remark-frontmatter/workflows/main/badge.svg
+
+[build]: https://github.com/remarkjs/remark-frontmatter/actions
+
+[coverage-badge]: https://img.shields.io/codecov/c/github/remarkjs/remark-frontmatter.svg
+
+[coverage]: https://codecov.io/github/remarkjs/remark-frontmatter
+
+[downloads-badge]: https://img.shields.io/npm/dm/remark-frontmatter.svg
+
+[downloads]: https://www.npmjs.com/package/remark-frontmatter
+
+[size-badge]: https://img.shields.io/bundlejs/size/remark-frontmatter
+
+[size]: https://bundlejs.com/?q=remark-frontmatter
+
+[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
+
+[backers-badge]: https://opencollective.com/unified/backers/badge.svg
+
+[collective]: https://opencollective.com/unified
+
+[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[chat]: https://github.com/remarkjs/remark/discussions
+
+[npm]: https://docs.npmjs.com/cli/install
+
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[esmsh]: https://esm.sh
+
+[health]: https://github.com/remarkjs/.github
+
+[contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[license]: license
+
+[author]: https://wooorm.com
+
+[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown
+
+[mdast-util-frontmatter]: https://github.com/syntax-tree/mdast-util-frontmatter
+
+[micromark]: https://github.com/micromark/micromark
+
+[micromark-extension-frontmatter]: https://github.com/micromark/micromark-extension-frontmatter
+
+[hast]: https://github.com/syntax-tree/hast
+
+[rehype]: https://github.com/rehypejs/rehype
+
+[remark]: https://github.com/remarkjs/remark
+
+[remark-rehype]: https://github.com/remarkjs/remark-rehype
+
+[remark-mdx-frontmatter]: https://github.com/remcohaszing/remark-mdx-frontmatter
+
+[typescript]: https://www.typescriptlang.org
+
+[unified]: https://github.com/unifiedjs/unified
+
+[unified-create-plugin]: https://unifiedjs.com/learn/guide/create-a-plugin/
+
+[vfile-file-data]: https://github.com/vfile/vfile#filedata
+
+[vfile-matter]: https://github.com/vfile/vfile-matter
+
+[wiki-xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
+
+[api-options]: #options
+
+[api-remark-frontmatter]: #unifieduseremarkfrontmatter-options
diff --git a/documents/markdown/remark/remark-frontmatter_test_fixtures_toml-advanced_input.md b/documents/markdown/remark/remark-frontmatter_test_fixtures_toml-advanced_input.md
new file mode 100644
index 0000000..0c96e99
--- /dev/null
+++ b/documents/markdown/remark/remark-frontmatter_test_fixtures_toml-advanced_input.md
@@ -0,0 +1,35 @@
++++
+title = "TOML Example"
+
+[owner]
+name = "Tom Preston-Werner"
+dob = 1979-05-27T07:32:00-08:00 # First class dates
+
+[database]
+server = "192.168.1.1"
+ports = [ 8001, 8001, 8002 ]
+connection_max = 5000
+enabled = true
+
+[servers]
+
+ # Indentation (tabs and/or spaces) is allowed but not required
+ [servers.alpha]
+ ip = "10.0.0.1"
+ dc = "eqdc10"
+
+ [servers.beta]
+ ip = "10.0.0.2"
+ dc = "eqdc10"
+
+[clients]
+data = [ ["gamma", "delta"], [1, 2] ]
+
+# Line breaks are OK when inside arrays
+hosts = [
+ "alpha",
+ "omega"
+]
++++
+
+# Big document
diff --git a/documents/markdown/remark/remark-frontmatter_test_fixtures_yaml-advanced_input.md b/documents/markdown/remark/remark-frontmatter_test_fixtures_yaml-advanced_input.md
new file mode 100644
index 0000000..4610765
--- /dev/null
+++ b/documents/markdown/remark/remark-frontmatter_test_fixtures_yaml-advanced_input.md
@@ -0,0 +1,32 @@
+---
+invoice: 34843
+date : 2001-01-23
+bill-to: &id001
+ given : Chris
+ family : Dumars
+ address:
+ lines: |
+ 458 Walkman Dr.
+ Suite #292
+ city : Royal Oak
+ state : MI
+ postal : 48046
+ship-to: *id001
+product:
+ - sku : BL394D
+ quantity : 4
+ description : Basketball
+ price : 450.00
+ - sku : BL4438H
+ quantity : 1
+ description : Super Hoop
+ price : 2392.00
+tax : 251.42
+total: 4443.52
+comments: >
+ Late afternoon is best.
+ Backup contact is Nancy
+ Billsmer @ 338-4338.
+---
+
+# Big document
diff --git a/documents/markdown/remark/remark-gfm_readme.md b/documents/markdown/remark/remark-gfm_readme.md
new file mode 100644
index 0000000..98ca7de
--- /dev/null
+++ b/documents/markdown/remark/remark-gfm_readme.md
@@ -0,0 +1,518 @@
+# remark-gfm
+
+[![Build][build-badge]][build]
+[![Coverage][coverage-badge]][coverage]
+[![Downloads][downloads-badge]][downloads]
+[![Size][size-badge]][size]
+[![Sponsors][sponsors-badge]][collective]
+[![Backers][backers-badge]][collective]
+[![Chat][chat-badge]][chat]
+
+**[remark][]** plugin to support [GFM][] (autolink literals, footnotes,
+strikethrough, tables, tasklists).
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkGfm[, options])`](#unifieduseremarkgfm-options)
+ * [`Options`](#options)
+* [Examples](#examples)
+ * [Example: `singleTilde`](#example-singletilde)
+ * [Example: `stringLength`](#example-stringlength)
+* [Bugs](#bugs)
+* [Authoring](#authoring)
+* [HTML](#html)
+* [CSS](#css)
+* [Syntax](#syntax)
+* [Syntax tree](#syntax-tree)
+* [Types](#types)
+* [Compatibility](#compatibility)
+* [Security](#security)
+* [Related](#related)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package is a [unified][] ([remark][]) plugin to enable the extensions to
+markdown that GitHub adds with GFM: autolink literals (`www.x.com`), footnotes
+(`[^1]`), strikethrough (`~~stuff~~`), tables (`| cell |…`), and tasklists
+(`* [x]`).
+You can use this plugin to add support for parsing and serializing them.
+These extensions by GitHub to CommonMark are called [GFM][] (GitHub Flavored
+Markdown).
+
+This plugin does not handle how markdown is turned to HTML.
+That’s done by [`remark-rehype`][remark-rehype].
+If your content is not in English and uses footnotes, you should configure that
+plugin.
+When generating HTML, you might also want to enable [`rehype-slug`][rehype-slug]
+to add `id`s on headings.
+
+A different plugin, [`remark-frontmatter`][remark-frontmatter], adds support for
+frontmatter.
+GitHub supports YAML frontmatter for files in repos and Gists but they don’t
+treat it as part of GFM.
+
+Another plugin, [`remark-github`][remark-github], adds support for how markdown
+works in relation to a certain GitHub repo in comments, issues, PRs, and
+releases, by linking references to commits, issues, and users.
+
+Yet another plugin, [`remark-breaks`][remark-breaks], turns soft line endings
+(enters) into hard breaks (`<br>`s).
+GitHub does this in a few places (comments, issues, PRs, and releases).
+
+## When should I use this?
+
+This project is useful when you want to support the same features that GitHub
+does in files in a repo, Gists, and several other places.
+Users frequently believe that some of these extensions, specifically autolink
+literals and tables, are part of normal markdown, so using `remark-gfm` will
+help match your implementation to their understanding of markdown.
+There are several edge cases where GitHub’s implementation works in unexpected
+ways or even different than described in their spec, so *writing* in GFM is not
+always the best choice.
+
+If you *just* want to turn markdown into HTML (with maybe a few extensions such
+as GFM), we recommend [`micromark`][micromark] with
+[`micromark-extension-gfm`][micromark-extension-gfm] instead.
+If you don’t use plugins and want to access the syntax tree, you can use
+[`mdast-util-from-markdown`][mdast-util-from-markdown] with
+[`mdast-util-gfm`][mdast-util-gfm].
+
+## Install
+
+This package is [ESM only][esm].
+In Node.js (version 16+), install with [npm][]:
+
+```sh
+npm install remark-gfm
+```
+
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import remarkGfm from 'https://esm.sh/remark-gfm@4'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+ import remarkGfm from 'https://esm.sh/remark-gfm@4?bundle'
+</script>
+```
+
+## Use
+
+Say our document `example.md` contains:
+
+```markdown
+# GFM
+
+## Autolink literals
+
+www.example.com, https://example.com, and contact@example.com.
+
+## Footnote
+
+A note[^1]
+
+[^1]: Big note.
+
+## Strikethrough
+
+~one~ or ~~two~~ tildes.
+
+## Table
+
+| a | b | c | d |
+| - | :- | -: | :-: |
+
+## Tasklist
+
+* [ ] to do
+* [x] done
+```
+
+…and our module `example.js` contains:
+
+```js
+import rehypeStringify from 'rehype-stringify'
+import remarkGfm from 'remark-gfm'
+import remarkParse from 'remark-parse'
+import remarkRehype from 'remark-rehype'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+
+const file = await unified()
+ .use(remarkParse)
+ .use(remarkGfm)
+ .use(remarkRehype)
+ .use(rehypeStringify)
+ .process(await read('example.md'))
+
+console.log(String(file))
+```
+
+…then running `node example.js` yields:
+
+```html
+<h1>GFM</h1>
+<h2>Autolink literals</h2>
+<p><a href="http://www.example.com">www.example.com</a>, <a href="https://example.com">https://example.com</a>, and <a href="mailto:contact@example.com">contact@example.com</a>.</p>
+<h2>Footnote</h2>
+<p>A note<sup><a href="#user-content-fn-1" id="user-content-fnref-1" data-footnote-ref aria-describedby="footnote-label">1</a></sup></p>
+<h2>Strikethrough</h2>
+<p><del>one</del> or <del>two</del> tildes.</p>
+<h2>Table</h2>
+<table>
+<thead>
+<tr>
+<th>a</th>
+<th align="left">b</th>
+<th align="right">c</th>
+<th align="center">d</th>
+</tr>
+</thead>
+</table>
+<h2>Tasklist</h2>
+<ul class="contains-task-list">
+<li class="task-list-item"><input type="checkbox" disabled> to do</li>
+<li class="task-list-item"><input type="checkbox" checked disabled> done</li>
+</ul>
+<section data-footnotes class="footnotes"><h2 class="sr-only" id="footnote-label">Footnotes</h2>
+<ol>
+<li id="user-content-fn-1">
+<p>Big note. <a href="#user-content-fnref-1" data-footnote-backref class="data-footnote-backref" aria-label="Back to content">↩</a></p>
+</li>
+</ol>
+</section>
+```
+
+## API
+
+This package exports no identifiers.
+The default export is [`remarkGfm`][api-remark-gfm].
+
+### `unified().use(remarkGfm[, options])`
+
+Add support GFM (autolink literals, footnotes, strikethrough, tables,
+tasklists).
+
+###### Parameters
+
+* `options` ([`Options`][api-options], optional)
+ — configuration
+
+###### Returns
+
+Nothing (`undefined`).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Fields
+
+* `firstLineBlank` (`boolean`, default: `false`)
+ — serialize with a blank line for the first line of footnote definitions
+* `stringLength` (`((value: string) => number)`, default: `d => d.length`)
+ — detect the size of table cells, used when aligning cells
+* `singleTilde` (`boolean`, default: `true`)
+ — whether to support strikethrough with a single tilde;
+ single tildes work on github.com, but are technically prohibited by GFM;
+ you can always use 2 or more tildes for strikethrough
+* `tablePipeAlign` (`boolean`, default: `true`)
+ — whether to align table pipes
+* `tableCellPadding` (`boolean`, default: `true`)
+ — whether to add a space of padding between table pipes and cells
+
+## Examples
+
+### Example: `singleTilde`
+
+To turn off support for parsing strikethrough with single tildes, pass
+`singleTilde: false`:
+
+```js
+// …
+
+const file = await unified()
+ .use(remarkParse)
+ .use(remarkGfm, {singleTilde: false})
+ .use(remarkRehype)
+ .use(rehypeStringify)
+ .process('~one~ and ~~two~~')
+
+console.log(String(file))
+```
+
+Yields:
+
+```html
+<p>~one~ and <del>two</del></p>
+```
+
+### Example: `stringLength`
+
+It’s possible to align tables based on the visual width of cells.
+First, let’s show the problem:
+
+```js
+import {remark} from 'remark'
+import remarkGfm from 'remark-gfm'
+
+const input = `| Alpha | Bravo |
+| - | - |
+| 中文 | Charlie |
+| 👩❤️👩 | Delta |`
+
+const file = await remark().use(remarkGfm).process(input)
+
+console.log(String(file))
+```
+
+The above code shows how remark can be used to format markdown.
+The output is as follows:
+
+```markdown
+| Alpha | Bravo |
+| -------- | ------- |
+| 中文 | Charlie |
+| 👩❤️👩 | Delta |
+```
+
+To improve the alignment of these full-width characters and emoji, pass a
+`stringLength` function that calculates the visual width of cells.
+One such algorithm is [`string-width`][string-width].
+It can be used like so:
+
+```diff
+@@ -1,5 +1,6 @@
+ import {remark} from 'remark'
+ import remarkGfm from 'remark-gfm'
++import stringWidth from 'string-width'
+
+@@ -10,7 +11,7 @@ async function main() {
+ | 👩❤️👩 | Delta |`
+
+-const file = await remark().use(remarkGfm).process(input)
++const file = await remark()
++ .use(remarkGfm, {stringLength: stringWidth})
++ .process(input)
+
+ console.log(String(file))
+```
+
+The output of our code with these changes is as follows:
+
+```markdown
+| Alpha | Bravo |
+| ----- | ------- |
+| 中文 | Charlie |
+| 👩❤️👩 | Delta |
+```
+
+## Bugs
+
+For bugs present in GFM but not here, or other peculiarities that are
+supported, see each corresponding readme:
+
+* [autolink literal](https://github.com/micromark/micromark-extension-gfm-autolink-literal#bugs)
+* [footnote](https://github.com/micromark/micromark-extension-gfm-footnote#bugs)
+* strikethrough: n/a
+* [table](https://github.com/micromark/micromark-extension-gfm-table#bugs)
+* tasklists: n/a
+
+## Authoring
+
+For recommendations on how to author GFM, see each corresponding readme:
+
+* [autolink literal](https://github.com/micromark/micromark-extension-gfm-autolink-literal#authoring)
+* [footnote](https://github.com/micromark/micromark-extension-gfm-footnote#authoring)
+* [strikethrough](https://github.com/micromark/micromark-extension-gfm-strikethrough#authoring)
+* [table](https://github.com/micromark/micromark-extension-gfm-table#authoring)
+* [tasklists](https://github.com/micromark/micromark-extension-gfm-task-list-item#authoring)
+
+## HTML
+
+This plugin does not handle how markdown is turned to HTML.
+See [`remark-rehype`][remark-rehype] for how that happens and how to change it.
+
+## CSS
+
+For info on how GitHub styles these features, see each corresponding readme:
+
+* [autolink literal](https://github.com/micromark/micromark-extension-gfm-autolink-literal#css)
+* [footnote](https://github.com/micromark/micromark-extension-gfm-footnote#css)
+* [strikethrough](https://github.com/micromark/micromark-extension-gfm-strikethrough#css)
+* [table](https://github.com/micromark/micromark-extension-gfm-table#css)
+* [tasklists](https://github.com/micromark/micromark-extension-gfm-task-list-item#css)
+
+## Syntax
+
+For info on the syntax of these features, see each corresponding readme:
+
+* [autolink literal](https://github.com/micromark/micromark-extension-gfm-autolink-literal#syntax)
+* [footnote](https://github.com/micromark/micromark-extension-gfm-footnote#syntax)
+* [strikethrough](https://github.com/micromark/micromark-extension-gfm-strikethrough#syntax)
+* [table](https://github.com/micromark/micromark-extension-gfm-table#syntax)
+* [tasklists](https://github.com/micromark/micromark-extension-gfm-task-list-item#syntax)
+
+## Syntax tree
+
+For info on the syntax tree of these features, see each corresponding readme:
+
+* [autolink literal](https://github.com/syntax-tree/mdast-util-gfm-autolink-literal#syntax-tree)
+* [footnote](https://github.com/syntax-tree/mdast-util-gfm-footnote#syntax-tree)
+* [strikethrough](https://github.com/syntax-tree/mdast-util-gfm-strikethrough#syntax-tree)
+* [table](https://github.com/syntax-tree/mdast-util-gfm-table#syntax-tree)
+* [tasklists](https://github.com/syntax-tree/mdast-util-gfm-task-list-item#syntax-tree)
+
+## Types
+
+This package is fully typed with [TypeScript][].
+It exports the additional type [`Options`][api-options].
+
+The node types are supported in `@types/mdast` by default.
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line, `remark-gfm@^4`, compatible
+with Node.js 16.
+
+This plugin works with `remark-parse` version 11+ (`remark` version 15+).
+The previous version (v3) worked with `remark-parse` version 10 (`remark`
+version 14).
+Before that, v2 worked with `remark-parse` version 9 (`remark` version 13).
+Earlier versions of `remark-parse` and `remark` had a `gfm` option that enabled
+this functionality, which defaulted to true.
+
+## Security
+
+Use of `remark-gfm` does not involve **[rehype][]** ([hast][]) or user
+content so there are no openings for [cross-site scripting (XSS)][wiki-xss]
+attacks.
+
+## Related
+
+* [`remark-github`][remark-github]
+ — link references to commits, issues, PRs, and users
+* [`remark-breaks`][remark-breaks]
+ — support breaks without needing spaces or escapes (enters to `<br>`)
+* [`remark-frontmatter`][remark-frontmatter]
+ — support frontmatter (YAML, TOML, and more)
+* [`remark-directive`](https://github.com/remarkjs/remark-directive)
+ — support directives
+* [`remark-math`](https://github.com/remarkjs/remark-math)
+ — support math
+* [`remark-mdx`](https://github.com/mdx-js/mdx/tree/main/packages/remark-mdx)
+ — support MDX (ESM, JSX, expressions)
+
+## Contribute
+
+See [`contributing.md`][contributing] in [`remarkjs/.github`][health] for ways
+to get started.
+See [`support.md`][support] for ways to get help.
+
+This project has a [code of conduct][coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][license] © [Titus Wormer][author]
+
+<!-- Definitions -->
+
+[api-options]: #options
+
+[api-remark-gfm]: #unifieduseremarkgfm-options
+
+[author]: https://wooorm.com
+
+[backers-badge]: https://opencollective.com/unified/backers/badge.svg
+
+[build]: https://github.com/remarkjs/remark-gfm/actions
+
+[build-badge]: https://github.com/remarkjs/remark-gfm/workflows/main/badge.svg
+
+[chat]: https://github.com/remarkjs/remark/discussions
+
+[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[coc]: https://github.com/remarkjs/.github/blob/HEAD/code-of-conduct.md
+
+[collective]: https://opencollective.com/unified
+
+[contributing]: https://github.com/remarkjs/.github/blob/HEAD/contributing.md
+
+[coverage]: https://codecov.io/github/remarkjs/remark-gfm
+
+[coverage-badge]: https://img.shields.io/codecov/c/github/remarkjs/remark-gfm.svg
+
+[downloads]: https://www.npmjs.com/package/remark-gfm
+
+[downloads-badge]: https://img.shields.io/npm/dm/remark-gfm.svg
+
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[esmsh]: https://esm.sh
+
+[gfm]: https://github.github.com/gfm/
+
+[hast]: https://github.com/syntax-tree/hast
+
+[health]: https://github.com/remarkjs/.github
+
+[license]: license
+
+[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown
+
+[mdast-util-gfm]: https://github.com/syntax-tree/mdast-util-gfm
+
+[micromark]: https://github.com/micromark/micromark
+
+[micromark-extension-gfm]: https://github.com/micromark/micromark-extension-gfm
+
+[npm]: https://docs.npmjs.com/cli/install
+
+[rehype]: https://github.com/rehypejs/rehype
+
+[rehype-slug]: https://github.com/rehypejs/rehype-slug
+
+[remark]: https://github.com/remarkjs/remark
+
+[remark-breaks]: https://github.com/remarkjs/remark-breaks
+
+[remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter
+
+[remark-github]: https://github.com/remarkjs/remark-github
+
+[remark-rehype]: https://github.com/remarkjs/remark-rehype
+
+[size]: https://bundlejs.com/?q=remark-gfm
+
+[size-badge]: https://img.shields.io/bundlejs/size/remark-gfm
+
+[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
+
+[string-width]: https://github.com/sindresorhus/string-width
+
+[support]: https://github.com/remarkjs/.github/blob/HEAD/support.md
+
+[typescript]: https://www.typescriptlang.org
+
+[unified]: https://github.com/unifiedjs/unified
+
+[wiki-xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
diff --git a/documents/markdown/remark/remark-gfm_test_fixtures_autolink-literal_input.md b/documents/markdown/remark/remark-gfm_test_fixtures_autolink-literal_input.md
new file mode 100644
index 0000000..76efeb7
--- /dev/null
+++ b/documents/markdown/remark/remark-gfm_test_fixtures_autolink-literal_input.md
@@ -0,0 +1,87 @@
+# Literal autolinks
+
+## WWW autolinks
+
+www.commonmark.org
+
+WWW.COMMONMARK.ORG
+
+Visit www.commonmark.org/help for more information.
+
+Visit www.commonmark.org.
+
+Visit www.commonmark.org/a.b.
+
+www.aaa.bbb.ccc_ccc
+
+www.aaa_bbb.ccc
+
+www.aaa.bbb.ccc.ddd_ddd
+
+www.aaa.bbb.ccc_ccc.ddd
+
+www.aaa.bbb_bbb.ccc.ddd
+
+www.aaa_aaa.bbb.ccc.ddd
+
+Visit www.commonmark.org.
+
+Visit www.commonmark.org/a.b.
+
+www.google.com/search?q=Markup+(business)
+
+www.google.com/search?q=Markup+(business)))
+
+(www.google.com/search?q=Markup+(business))
+
+(www.google.com/search?q=Markup+(business)
+
+www.google.com/search?q=(business))+ok
+
+www.google.com/search?q=commonmark&hl=en
+
+www.google.com/search?q=commonmark&hl;en
+
+www.google.com/search?q=commonmark&hl;
+
+www.commonmark.org/he<lp
+
+## HTTP autolinks
+
+http://example.com
+
+https://example.com
+
+https://example
+
+http://commonmark.org
+
+(Visit https://encrypted.google.com/search?q=Markup+(business))
+
+## Email autolinks
+
+No dot: foo@barbaz
+
+No dot: foo@barbaz.
+
+foo@bar.baz
+
+hello@mail+xyz.example isn’t valid, but hello+xyz@mail.example is.
+
+a.b-c_d@a.b
+
+a.b-c_d@a.b.
+
+a.b-c_d@a.b-
+
+a.b-c_d@a.b_
+
+a@a_b.c
+
+a@a-b.c
+
+Can’t end in an underscore followed by a period: aaa@a.b_.
+
+Can contain an underscore followed by a period: aaa@a.b_.c
+
+[https://google.com](https://google.com)
diff --git a/documents/markdown/remark/remark-gfm_test_fixtures_autolink-literal_output.md b/documents/markdown/remark/remark-gfm_test_fixtures_autolink-literal_output.md
new file mode 100644
index 0000000..4e8a361
--- /dev/null
+++ b/documents/markdown/remark/remark-gfm_test_fixtures_autolink-literal_output.md
@@ -0,0 +1,87 @@
+# Literal autolinks
+
+## WWW autolinks
+
+[www.commonmark.org](http://www.commonmark.org)
+
+[WWW.COMMONMARK.ORG](http://WWW.COMMONMARK.ORG)
+
+Visit [www.commonmark.org/help](http://www.commonmark.org/help) for more information.
+
+Visit [www.commonmark.org](http://www.commonmark.org).
+
+Visit [www.commonmark.org/a.b](http://www.commonmark.org/a.b).
+
+www\.aaa.bbb.ccc\_ccc
+
+www\.aaa\_bbb.ccc
+
+www\.aaa.bbb.ccc.ddd\_ddd
+
+www\.aaa.bbb.ccc\_ccc.ddd
+
+[www.aaa.bbb\_bbb.ccc.ddd](http://www.aaa.bbb_bbb.ccc.ddd)
+
+[www.aaa\_aaa.bbb.ccc.ddd](http://www.aaa_aaa.bbb.ccc.ddd)
+
+Visit [www.commonmark.org](http://www.commonmark.org).
+
+Visit [www.commonmark.org/a.b](http://www.commonmark.org/a.b).
+
+[www.google.com/search?q=Markup+(business)](http://www.google.com/search?q=Markup+\(business\))
+
+[www.google.com/search?q=Markup+(business)](http://www.google.com/search?q=Markup+\(business\))))
+
+([www.google.com/search?q=Markup+(business)](http://www.google.com/search?q=Markup+\(business\)))
+
+([www.google.com/search?q=Markup+(business)](http://www.google.com/search?q=Markup+\(business\))
+
+[www.google.com/search?q=(business))+ok](http://www.google.com/search?q=\(business\)\)+ok)
+
+[www.google.com/search?q=commonmark\&hl=en](http://www.google.com/search?q=commonmark\&hl=en)
+
+[www.google.com/search?q=commonmark\&hl;en](http://www.google.com/search?q=commonmark\&hl;en)
+
+[www.google.com/search?q=commonmark](http://www.google.com/search?q=commonmark)\&hl;
+
+[www.commonmark.org/he](http://www.commonmark.org/he)\<lp
+
+## HTTP autolinks
+
+<http://example.com>
+
+<https://example.com>
+
+<https://example>
+
+<http://commonmark.org>
+
+(Visit <https://encrypted.google.com/search?q=Markup+(business)>)
+
+## Email autolinks
+
+No dot: foo\@barbaz
+
+No dot: foo\@barbaz.
+
+<foo@bar.baz>
+
+hello\@mail+xyz.example isn’t valid, but <hello+xyz@mail.example> is.
+
+<a.b-c_d@a.b>
+
+<a.b-c_d@a.b>.
+
+a.b-c\_d\@a.b-
+
+a.b-c\_d\@a.b\_
+
+<a@a_b.c>
+
+<a@a-b.c>
+
+Can’t end in an underscore followed by a period: aaa\@a.b\_.
+
+Can contain an underscore followed by a period: <aaa@a.b_.c>
+
+<https://google.com>
diff --git a/documents/markdown/remark/remark-gfm_test_fixtures_table_output.md b/documents/markdown/remark/remark-gfm_test_fixtures_table_output.md
new file mode 100644
index 0000000..f0f15d4
--- /dev/null
+++ b/documents/markdown/remark/remark-gfm_test_fixtures_table_output.md
@@ -0,0 +1,4 @@
+| a | b | c | d | |
+| - | :- | -: | :-: | - |
+| e | f | | | |
+| g | h | i | j | k |
diff --git a/documents/markdown/remark/remark-lint_changelog.md b/documents/markdown/remark/remark-lint_changelog.md
new file mode 100644
index 0000000..2594f19
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_changelog.md
@@ -0,0 +1,5 @@
+# Changelog
+
+See [GitHub Releases][releases] for the changelog.
+
+[releases]: https://github.com/remarkjs/remark-lint/releases
diff --git a/documents/markdown/remark/remark-lint_doc_comparison-to-markdownlint.md b/documents/markdown/remark/remark-lint_doc_comparison-to-markdownlint.md
new file mode 100644
index 0000000..dc07763
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_doc_comparison-to-markdownlint.md
@@ -0,0 +1,43 @@
+# [markdownlint](https://github.com/markdownlint/markdownlint)
+
+> ⚠️ **Important**: this comparison hasn’t been updated in years.
+
+This table documents the similarity and difference between
+[**markdownlint**](https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md)
+rules and **remark-lint**’s rules.
+
+| markdownlint | remark | note |
+| - | - | - |
+| MD001 | heading-increment | - |
+| MD002 | first-heading-level | - |
+| MD003 | heading-style | - |
+| MD004 | unordered-list-marker-style | - |
+| MD005 | - | mixture of `list-item-indent`, `list-item-bullet-indent`, and `list-item-content-indent` |
+| MD006 | list-item-bullet-indent | - |
+| MD007 | list-item-bullet-indent | - |
+| MD009 | - | Partially by hard-break-spaces |
+| MD010 | no-tabs | - |
+| MD011 | no-shortcut-reference-link | Although a different message, this will lead you in the right direction |
+| MD012 | no-consecutive-blank-lines | - |
+| MD013 | maximum-line-length | - |
+| MD014 | no-shell-dollars | - |
+| MD018 | no-heading-content-indent | Only works in pedantic mode |
+| MD019 | no-heading-content-indent | - |
+| MD020 | no-heading-content-indent | Only works in pedantic mode |
+| MD021 | no-heading-content-indent | - |
+| MD022 | no-missing-blank-lines | - |
+| MD023 | no-heading-indent | - |
+| MD024 | no-duplicate-headings | - |
+| MD025 | no-multiple-toplevel-headings | - |
+| MD026 | no-heading-punctuation | - |
+| MD027 | blockquote-indentation | Won’t warn when that’s your preferred, consistent style |
+| MD028 | no-blockquote-without-marker | - |
+| MD029 | ordered-list-marker-value | markdownlint defaults to `one`, whereas remark-lint defaults to `ordered` |
+| MD030 | list-item-indent | - |
+| MD031 | no-missing-blank-lines | - |
+| MD032 | no-missing-blank-lines | - |
+| MD033 | no-html | - |
+| MD034 | no-literal-urls | - |
+| MD035 | rule-style | - |
+| MD036 | no-emphasis-as-heading | remark-lint only warns when the emphasis is followed by a colon, but that might change. |
+| MD040 | fenced-code-flag | - |
diff --git a/documents/markdown/remark/remark-lint_doc_create-a-custom-rule.md b/documents/markdown/remark/remark-lint_doc_create-a-custom-rule.md
new file mode 100644
index 0000000..e31d401
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_doc_create-a-custom-rule.md
@@ -0,0 +1,293 @@
+# Create a custom `remark-lint` rule
+
+This guide is part of [a step-by-step tutorial][tutorial], and will help you
+getting started to create your first linting plugin for `remark`.
+
+## Contents
+
+* [Set up the project](#set-up-the-project)
+* [Set up remark](#set-up-remark)
+* [The `no-invalid-gif` rule](#the-no-invalid-gif-rule)
+* [Create the custom rule](#create-the-custom-rule)
+* [Rule arguments](#rule-arguments)
+* [Rule implementation](#rule-implementation)
+* [Import the rule in your remark config](#import-the-rule-in-your-remark-config)
+* [Apply the rule on the Markdown file](#apply-the-rule-on-the-markdown-file)
+
+## Set up the project
+
+Create a new folder and enter it from your terminal.
+For this example I will be using Unix commands (macOS and Linux compatible).
+Then generate a `package.json`:
+
+```sh
+mkdir my-custom-rule
+cd my-custom-rule
+npm init -y
+```
+
+Now we can start installing our dependencies:
+
+```sh
+npm install remark-lint remark-cli
+```
+
+* [`remark-lint`][github-remark-lint]
+ — core lint plugin
+* [`remark-cli`][github-remark-cli]
+ — command line interface
+
+We will also use some utilities:
+
+```sh
+npm install unified-lint-rule unist-util-visit
+```
+
+These will help us creating and managing our custom rules.
+
+## Set up remark
+
+With everything installed, we can now create a `.remarkrc.js` that will contain
+the plugins we’ll use.
+
+For more info on configuration, see
+[Examples in `remark-lint`][github-remark-lint-examples].
+
+```sh
+touch .remarkrc.js
+```
+
+```js
+// .remarkrc.js
+/**
+ * @import {Preset} from 'unified'
+ */
+
+/** @type {Preset} */
+const preset = {plugins: []}
+
+export default preset
+```
+
+Then, in our `package.json`, add the following script to process all the
+markdown files in our project:
+
+```json
+"scripts": {
+ "lint": "remark ."
+}
+```
+
+Let’s create a `doc.md`, the markdown file we want to lint:
+
+```sh
+touch doc.md
+```
+
+…and copy/paste the following:
+
+```markdown
+## Best pets! <3
+
+Some funny images of our favorite pets
+
+
+
+
+```
+
+At this point, we have a working `remark` configuration and a markdown file in
+the project.
+
+If we run `npm run lint` we should expect to see in our terminal:
+
+```sh
+doc.md: no issues found
+```
+
+All good, the file has been processed, and because we haven’t specified any
+plugins nor lint rules, no issues are found.
+
+## The `no-invalid-gif` rule
+
+Let’s imagine we want to write a rule that checks whether a `.gif` file is used
+as an image.
+Given the content of our `doc.md` file declared above, we would expect an
+*error* or *warning* pointing to:
+
+```markdown
+
+```
+
+Because the file extension `.gif` in the image violates our rule.
+
+## Create the custom rule
+
+Let’s create a new folder `rules` under the root directory, where we will place
+all of our custom rules, and create a new file in it named `no-gif-allowed.js`.
+
+```sh
+mkdir rules
+cd rules
+touch no-gif-allowed.js
+cd .. # return to project root
+```
+
+*Note*: the name of folders and files, and where to place them within your
+project, is up to you.
+
+In `./rules/no-gif-allowed.js`, let’s import `unified-lint-rule`.
+
+We then export the result of calling `rule` by providing the *namespace and rule
+name* (`remark-lint:no-gif-allowed`) as the first argument, and our
+implementation of the rule (`noGifAllowed`) as the second argument.
+
+```js
+// rules/no-gif-allowed.js
+import {lintRule} from 'unified-lint-rule'
+
+const remarkLintNoGifAllowed = lintRule(
+ 'remark-lint:no-gif-allowed',
+ function (tree, file, options) {
+ // Rule implementation
+ }
+)
+
+export default remarkLintNoGifAllowed
+```
+
+Let’s say you want all your custom rules to be defined as part of your project
+namespace.
+If your project was named `my-project`, then you can export your rule as:
+
+```js
+const remarkLintNoGifAllowed = lintRule(
+ 'my-project-name:no-gif-allowed',
+ function () {}
+)
+
+// Or:
+const remarkLintNoGifAllowed = lintRule(
+ 'my-npm-published-package:no-gif-allowed',
+ function () {}
+)
+```
+
+This can help you when wanting to create a group of rules under the same
+*namespace*.
+
+## Rule arguments
+
+Your rule function will receive three arguments:
+
+```js
+function rule(tree, file, options) {}
+```
+
+* `tree` (*required*): [mdast][github-mdast]
+* `file` (*required*): [virtual file][github-vfile]
+* `options` (*optional*): additional info passed to the rule by users
+
+## Rule implementation
+
+Because we will be inspecting [mdast][github-mdast],
+which is a markdown abstract syntax tree built upon [unist][github-unist],
+we can take advantage of the many existing
+[unist utilities][github-unist-utilities] to inspect our tree’s nodes.
+
+For this example, we will use [`unist-util-visit`][github-unist-util-visit]
+to recursively inspect all the image nodes, and
+[`unist-util-generated`][github-unist-util-generated] to ensure we are not
+inspecting nodes that we have generated ourselves and do not belong to the
+`doc.md`.
+
+```js
+/**
+ * @import {Root} from 'mdast'
+ */
+
+import {lintRule} from 'unified-lint-rule'
+import {visit} from 'unist-util-visit'
+
+const remarkLintNoGifAllowed = lintRule(
+ 'remark-lint:no-gif-allowed',
+ /**
+ * @param {Root} tree
+ * Tree.
+ * @returns {undefined}
+ * Nothing.
+ */
+ function (tree, file, options) {
+ visit(tree, 'image', function (node) {
+ // This is an extremely simplified example of how to structure
+ // the logic to check whether a node violates your rule.
+ // You have complete freedom over how to visit/inspect the tree,
+ // and on how to implement the validation logic for your node.
+ const isValid = !node.url.endsWith('.gif')
+
+ if (!isValid) {
+ // Remember to provide the node as second argument to the message,
+ // in order to obtain the position and column where the violation occurred.
+ file.message(
+ 'Invalid image file extensions. Please do not use gifs',
+ node
+ )
+ }
+ })
+ }
+)
+
+export default remarkLintNoGifAllowed
+```
+
+## Import the rule in your remark config
+
+Now that our custom rule is defined and ready to be used we need to add it to
+our `remark` configuration.
+
+You can do that by importing your rule and adding it in `plugins` array:
+
+```js
+// .remarkrc.js
+/**
+ * @import {Preset} from 'unified'
+ */
+
+import remarkLintNoGifAllowed from './rules/no-gif-allowed.js'
+
+/** @type {Preset} */
+const preset = {plugins: [remarkLintNoGifAllowed]}
+
+export default preset
+```
+
+## Apply the rule on the Markdown file
+
+If you run `npm run lint`, you should see the following message in the terminal:
+
+```text
+5:1-5:30 warning Invalid image file extensions. Please do not use gifs no-gif-allowed remark-lint
+```
+
+**Congratulations!
+The rule works!**
+
+[github-mdast]: https://github.com/syntax-tree/mdast
+
+[github-remark-cli]: https://github.com/remarkjs/remark/tree/main/packages/remark-cli
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-lint-examples]: https://github.com/remarkjs/remark-lint#examples
+
+[github-unist]: https://github.com/syntax-tree/unist
+
+[github-unist-util-generated]: https://github.com/syntax-tree/unist-util-generated
+
+[github-unist-util-visit]: https://github.com/syntax-tree/unist-util-visit
+
+[github-unist-utilities]: https://github.com/syntax-tree/unist#utilities
+
+[github-vfile]: https://github.com/vfile/vfile
+
+[tutorial]: https://dev.to/floroz/how-to-create-a-custom-lint-rule-for-markdown-and-mdx-using-remark-and-eslint-2jim
diff --git a/documents/markdown/remark/remark-lint_doc_rules.md b/documents/markdown/remark/remark-lint_doc_rules.md
new file mode 100644
index 0000000..33d65f7
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_doc_rules.md
@@ -0,0 +1,13 @@
+# Rules
+
+## Configuration
+
+See the monorepo readme for [configuring rules][config].
+
+## List of rules
+
+See the monorepo readme for the [rules][].
+
+[config]: https://github.com/remarkjs/remark-lint#configure
+
+[rules]: https://github.com/remarkjs/remark-lint#rules
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-blockquote-indentation_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-blockquote-indentation_readme.md
new file mode 100644
index 0000000..edced13
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-blockquote-indentation_readme.md
@@ -0,0 +1,332 @@
+<!--This file is generated-->
+
+# remark-lint-blockquote-indentation
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when block quotes are indented too much or
+too little.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintBlockquoteIndentation[, options])`](#unifieduseremarklintblockquoteindentation-options)
+ * [`Options`](#options)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the “indent” of block quotes: the `>` (greater than)
+marker *and* the spaces before content.
+
+## When should I use this?
+
+You can use this rule to check markdown code style.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | `'consistent'` |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `2` |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-blockquote-indentation
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintBlockquoteIndentation from 'https://esm.sh/remark-lint-blockquote-indentation@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintBlockquoteIndentation from 'https://esm.sh/remark-lint-blockquote-indentation@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintBlockquoteIndentation from 'remark-lint-blockquote-indentation'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintBlockquoteIndentation)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-blockquote-indentation .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-blockquote-indentation",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] type
+[`Options`][api-options].
+The default export is
+[`remarkLintBlockquoteIndentation`][api-remark-lint-blockquote-indentation].
+
+### `unified().use(remarkLintBlockquoteIndentation[, options])`
+
+Warn when block quotes are indented too much or too little.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], default: `'consistent'`)
+ — either a preferred indent or whether to detect the first style
+ and warn for further differences
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Type
+
+```ts
+type Options = number | 'consistent'
+```
+
+## Recommendation
+
+CommonMark specifies that when block quotes are used the `>` markers can be
+followed by an optional space.
+No space at all arguably looks rather ugly:
+
+```markdown
+>Mars and
+>Venus.
+```
+
+There is no specific handling of more that one space, so if 5 spaces were
+used after `>`, then indented code kicks in:
+
+```markdown
+> neptune()
+```
+
+Due to this, it’s recommended to configure this rule with `2`.
+
+## Examples
+
+##### `ok-2.md`
+
+When configured with `2`.
+
+###### In
+
+```markdown
+> Mercury.
+
+Venus.
+
+> Earth.
+```
+
+###### Out
+
+No messages.
+
+##### `ok-4.md`
+
+When configured with `4`.
+
+###### In
+
+```markdown
+> Mercury.
+
+Venus.
+
+> Earth.
+```
+
+###### Out
+
+No messages.
+
+##### `ok-tab.md`
+
+###### In
+
+```markdown
+>␉Mercury.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+> Mercury.
+
+Venus.
+
+> Earth.
+
+Mars.
+
+> Jupiter
+```
+
+###### Out
+
+```text
+5:5: Unexpected `4` spaces between block quote marker and content, expected `3` spaces, remove `1` space
+9:3: Unexpected `2` spaces between block quote marker and content, expected `3` spaces, add `1` space
+```
+
+##### `not-ok-options.md`
+
+When configured with `'🌍'`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `options`, expected `number` or `'consistent'`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-blockquote-indentation@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-options]: #options
+
+[api-remark-lint-blockquote-indentation]: #unifieduseremarklintblockquoteindentation-options
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-blockquote-indentation.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-blockquote-indentation
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-blockquote-indentation
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-blockquote-indentation
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-checkbox-character-style_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-checkbox-character-style_readme.md
new file mode 100644
index 0000000..bbec863
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-checkbox-character-style_readme.md
@@ -0,0 +1,389 @@
+<!--This file is generated-->
+
+# remark-lint-checkbox-character-style
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when list item checkboxes violate a given
+style.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintCheckboxCharacterStyle[, options])`](#unifieduseremarklintcheckboxcharacterstyle-options)
+ * [`Options`](#options)
+ * [`Styles`](#styles)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the character used in checkboxes.
+
+## When should I use this?
+
+You can use this package to check that the style of GFM tasklists is
+consistent.
+Task lists are a GFM feature enabled with
+[`remark-gfm`][github-remark-gfm].
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | `'consistent'` |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-checkbox-character-style
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintCheckboxCharacterStyle from 'https://esm.sh/remark-lint-checkbox-character-style@5'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintCheckboxCharacterStyle from 'https://esm.sh/remark-lint-checkbox-character-style@5?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintCheckboxCharacterStyle from 'remark-lint-checkbox-character-style'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintCheckboxCharacterStyle)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-checkbox-character-style .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-checkbox-character-style",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] types
+[`Options`][api-options] and
+[`Styles`][api-styles].
+The default export is
+[`remarkLintCheckboxCharacterStyle`][api-remark-lint-checkbox-character-style].
+
+### `unified().use(remarkLintCheckboxCharacterStyle[, options])`
+
+Warn when list item checkboxes violate a given style.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], default: `'consistent'`)
+ — either preferred values or whether to detect the first styles
+ and warn for further differences
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Type
+
+```ts
+type Options = Styles | 'consistent'
+```
+
+### `Styles`
+
+Styles (TypeScript type).
+
+###### Fields
+
+* `checked` (`'X'`, `'x'`, or `'consistent'`, default: `'consistent'`)
+ — preferred style to use for checked checkboxes
+* `unchecked` (`'␉'` (a tab), `'␠'` (a space), or `'consistent'`, default:
+ `'consistent'`)
+ — preferred style to use for unchecked checkboxes
+
+## Recommendation
+
+It’s recommended to set `options.checked` to `'x'` (a lowercase X) as it
+prevents an extra keyboard press and `options.unchecked` to `'␠'` (a space)
+to make all checkboxes align.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] formats checked checkboxes
+using `'x'` (lowercase X) and unchecked checkboxes using `'␠'` (a space).
+
+## Examples
+
+##### `ok-x.md`
+
+When configured with `{ checked: 'x' }`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+- [x] Mercury.
+- [x] Venus.
+```
+
+###### Out
+
+No messages.
+
+##### `ok-x-upper.md`
+
+When configured with `{ checked: 'X' }`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+- [X] Mercury.
+- [X] Venus.
+```
+
+###### Out
+
+No messages.
+
+##### `ok-space.md`
+
+When configured with `{ unchecked: ' ' }`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+- [ ] Mercury.
+- [ ] Venus.
+- [ ]␠␠
+- [ ]
+```
+
+###### Out
+
+No messages.
+
+##### `ok-tab.md`
+
+When configured with `{ unchecked: '\t' }`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+- [␉] Mercury.
+- [␉] Venus.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok-default.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+- [x] Mercury.
+- [X] Venus.
+- [ ] Earth.
+- [␉] Mars.
+```
+
+###### Out
+
+```text
+2:5: Unexpected checked checkbox value `X`, expected `x`
+4:5: Unexpected unchecked checkbox value `\t`, expected ` `
+```
+
+##### `not-ok-option.md`
+
+When configured with `'🌍'`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `options`, expected an object or `'consistent'`
+```
+
+##### `not-ok-option-unchecked.md`
+
+When configured with `{ unchecked: '🌍' }`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `options.unchecked`, expected `'\t'`, `' '`, or `'consistent'`
+```
+
+##### `not-ok-option-checked.md`
+
+When configured with `{ checked: '🌍' }`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `options.checked`, expected `'X'`, `'x'`, or `'consistent'`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-checkbox-character-style@5`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-options]: #options
+
+[api-remark-lint-checkbox-character-style]: #unifieduseremarklintcheckboxcharacterstyle-options
+
+[api-styles]: #styles
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-checkbox-character-style.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-checkbox-character-style
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-checkbox-character-style
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-checkbox-character-style
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-checkbox-content-indent_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-checkbox-content-indent_readme.md
new file mode 100644
index 0000000..4873a60
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-checkbox-content-indent_readme.md
@@ -0,0 +1,295 @@
+<!--This file is generated-->
+
+# remark-lint-checkbox-content-indent
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when GFM tasklist checkboxes are followed by
+more than one space.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintCheckboxContentIndent)`](#unifieduseremarklintcheckboxcontentindent)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the space after checkboxes.
+
+## When should I use this?
+
+You can use this package to check that the style of GFM tasklists is
+a single space.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-checkbox-content-indent
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintCheckboxContentIndent from 'https://esm.sh/remark-lint-checkbox-content-indent@5'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintCheckboxContentIndent from 'https://esm.sh/remark-lint-checkbox-content-indent@5?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintCheckboxContentIndent from 'remark-lint-checkbox-content-indent'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintCheckboxContentIndent)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-checkbox-content-indent .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-checkbox-content-indent",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintCheckboxContentIndent`][api-remark-lint-checkbox-content-indent].
+
+### `unified().use(remarkLintCheckboxContentIndent)`
+
+Warn when GFM tasklist checkboxes are followed by more than one space.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+GFM allows zero or more spaces and tabs after checkboxes.
+No space at all arguably looks rather ugly:
+
+```markdown
+* [x]Pluto
+```
+
+More that one space is superfluous:
+
+```markdown
+* [x] Jupiter
+```
+
+Due to this, it’s recommended to turn this rule on.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] formats checkboxes and the
+content after them with a single space between.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+- [ ] Mercury.
++ [x] Venus.
+* [X] Earth.
+- [ ] Mars.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+- [ ] Mercury.
++ [x] Venus.
+* [X] Earth.
+- [ ] Mars.
+```
+
+###### Out
+
+```text
+2:8: Unexpected `2` spaces between checkbox and content, expected `1` space, remove `1` space
+3:9: Unexpected `3` spaces between checkbox and content, expected `1` space, remove `2` spaces
+4:10: Unexpected `4` spaces between checkbox and content, expected `1` space, remove `3` spaces
+```
+
+##### `tab.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+- [ ]␉Mercury.
++ [x]␉␉Venus.
+```
+
+###### Out
+
+```text
+2:8: Unexpected `2` spaces between checkbox and content, expected `1` space, remove `1` space
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-checkbox-content-indent@5`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-checkbox-content-indent]: #unifieduseremarklintcheckboxcontentindent
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-checkbox-content-indent.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-checkbox-content-indent
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-checkbox-content-indent
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-checkbox-content-indent
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-code-block-style_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-code-block-style_readme.md
new file mode 100644
index 0000000..fcedf47
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-code-block-style_readme.md
@@ -0,0 +1,380 @@
+<!--This file is generated-->
+
+# remark-lint-code-block-style
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when code blocks violate a given style.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintCodeBlockStyle[, options])`](#unifieduseremarklintcodeblockstyle-options)
+ * [`Options`](#options)
+ * [`Style`](#style)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the style of code blocks.
+
+## When should I use this?
+
+You can use this package to check that the style of code blocks is
+consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | `'consistent'` |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `'fenced'` |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-code-block-style
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintCodeBlockStyle from 'https://esm.sh/remark-lint-code-block-style@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintCodeBlockStyle from 'https://esm.sh/remark-lint-code-block-style@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintCodeBlockStyle from 'remark-lint-code-block-style'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintCodeBlockStyle)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-code-block-style .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-code-block-style",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] types
+[`Options`][api-options] and
+[`Style`][api-style].
+The default export is
+[`remarkLintCodeBlockStyle`][api-remark-lint-code-block-style].
+
+### `unified().use(remarkLintCodeBlockStyle[, options])`
+
+Warn when code blocks violate a given style.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], default: `'consistent'`)
+ — preferred style or whether to detect the first style and warn for
+ further differences
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Type
+
+```ts
+type Options = Style | 'consistent'
+```
+
+### `Style`
+
+Style (TypeScript type).
+
+###### Type
+
+```ts
+type Style = 'indented' | 'fenced'
+```
+
+## Recommendation
+
+Indentation in markdown is complex as lists and indented code interfere in
+unexpected ways.
+Fenced code has more features than indented code: it can specify a
+programming language.
+Since CommonMark took the idea of fenced code from GFM,
+fenced code became widely supported.
+Due to this, it’s recommended to configure this rule with `'fenced'`.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] always formats code blocks as
+fenced.
+Pass `fences: false` to only use fenced code blocks when they have a
+language and as indented code otherwise.
+
+## Examples
+
+##### `ok-indented.md`
+
+When configured with `'indented'`.
+
+###### In
+
+```markdown
+ venus()
+
+Mercury.
+
+ earth()
+```
+
+###### Out
+
+No messages.
+
+##### `ok-fenced.md`
+
+When configured with `'fenced'`.
+
+###### In
+
+````markdown
+```
+venus()
+```
+
+Mercury.
+
+```
+earth()
+```
+````
+
+###### Out
+
+No messages.
+
+##### `not-ok-consistent.md`
+
+###### In
+
+````markdown
+ venus()
+
+Mercury.
+
+```
+earth()
+```
+````
+
+###### Out
+
+```text
+5:1-7:4: Unexpected fenced code block, expected indented code blocks
+```
+
+##### `not-ok-indented.md`
+
+When configured with `'indented'`.
+
+###### In
+
+````markdown
+```
+venus()
+```
+
+Mercury.
+
+```
+earth()
+```
+````
+
+###### Out
+
+```text
+1:1-3:4: Unexpected fenced code block, expected indented code blocks
+7:1-9:4: Unexpected fenced code block, expected indented code blocks
+```
+
+##### `not-ok-fenced.md`
+
+When configured with `'fenced'`.
+
+###### In
+
+```markdown
+ venus()
+
+Mercury.
+
+ earth()
+```
+
+###### Out
+
+```text
+1:1-1:12: Unexpected indented code block, expected fenced code blocks
+5:1-5:12: Unexpected indented code block, expected fenced code blocks
+```
+
+##### `not-ok-options.md`
+
+When configured with `'🌍'`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `options`, expected `'fenced'`, `'indented'`, or `'consistent'`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-code-block-style@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-options]: #options
+
+[api-remark-lint-code-block-style]: #unifieduseremarklintcodeblockstyle-options
+
+[api-style]: #style
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-code-block-style.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-code-block-style
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-code-block-style
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-code-block-style
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-correct-media-syntax_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-correct-media-syntax_readme.md
new file mode 100644
index 0000000..f099a86
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-correct-media-syntax_readme.md
@@ -0,0 +1,239 @@
+<!--This file is generated-->
+
+# remark-lint-correct-media-syntax
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn for accidental bracket and paren
+mixup for images and links.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintCorrectMediaSyntax)`](#unifieduseremarklintcorrectmediasyntax)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks for accidental image or link mixup:
+`(text)[url]` instead of `[text](url)`.
+
+## When should I use this?
+
+You can use this package to check that brackets and parentheses
+that are used to form image and links are not accidentally swapped.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-correct-media-syntax
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintCorrectMediaSyntax from 'https://esm.sh/remark-lint-correct-media-syntax@1'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintCorrectMediaSyntax from 'https://esm.sh/remark-lint-correct-media-syntax@1?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintCorrectMediaSyntax from 'remark-lint-correct-media-syntax'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintCorrectMediaSyntax)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-correct-media-syntax .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-correct-media-syntax",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintCorrectMediaSyntax`][api-remark-lint-correct-media-syntax].
+
+### `unified().use(remarkLintCorrectMediaSyntax)`
+
+Warn for accidental bracket and paren mixup for images and links.
+
+###### Parameters
+
+There are no parameters.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+[Mercury](https://example.com/mercury/) and
+.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+(Mercury)[https://example.com/mercury/] and
+!(Venus)[https://example.com/venus.png].
+```
+
+###### Out
+
+```text
+1:9-1:11: Unexpected `)[`, expected `[` and `]` around the text (label) and `(` and `)` around the URL for images and links, or an escape (`)\[`)
+2:8-2:10: Unexpected `)[`, expected `[` and `]` around the text (label) and `(` and `)` around the URL for images and links, or an escape (`)\[`)
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-correct-media-syntax@1`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-correct-media-syntax]: #unifieduseremarklintcorrectmediasyntax
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-correct-media-syntax.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-correct-media-syntax
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-correct-media-syntax
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-correct-media-syntax
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-definition-case_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-definition-case_readme.md
new file mode 100644
index 0000000..5530fcd
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-definition-case_readme.md
@@ -0,0 +1,266 @@
+<!--This file is generated-->
+
+# remark-lint-definition-case
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when definition labels are not lowercase.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintDefinitionCase)`](#unifieduseremarklintdefinitioncase)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the case of definition labels.
+
+## When should I use this?
+
+You can use this package to check that definition labels are consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-definition-case
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintDefinitionCase from 'https://esm.sh/remark-lint-definition-case@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintDefinitionCase from 'https://esm.sh/remark-lint-definition-case@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintDefinitionCase from 'remark-lint-definition-case'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintDefinitionCase)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-definition-case .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-definition-case",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintDefinitionCase`][api-remark-lint-definition-case].
+
+### `unified().use(remarkLintDefinitionCase)`
+
+Warn when definition labels are not lowercase.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+Definitions and references are matched together regardless of casing.
+Using uppercase in definition labels might incorrectly indicate that casing
+is of importance.
+Due to this, it’s recommended to use lowercase and turn this rule on.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+[mercury]: https://example.com "Mercury"
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+[Mercury]: https://example.com "Mercury"
+```
+
+###### Out
+
+```text
+1:1-1:41: Unexpected uppercase characters in definition label, expected lowercase
+```
+
+##### `gfm.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+[^Mercury]:
+ **Mercury** is the first planet from the Sun and the smallest
+ in the Solar System.
+```
+
+###### Out
+
+```text
+1:1-3:25: Unexpected uppercase characters in footnote definition label, expected lowercase
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-definition-case@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-definition-case]: #unifieduseremarklintdefinitioncase
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-definition-case.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-definition-case
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-definition-case
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-definition-case
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-definition-sort_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-definition-sort_readme.md
new file mode 100644
index 0000000..94dd887
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-definition-sort_readme.md
@@ -0,0 +1,377 @@
+<!--This file is generated-->
+
+# remark-lint-definition-sort
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when definitions are not sorted.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintDefinitionSort)`](#unifieduseremarklintdefinitionsort)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks definition order.
+
+## When should I use this?
+
+You can use this package to check definition order.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-definition-sort
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintDefinitionSort from 'https://esm.sh/remark-lint-definition-sort@1'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintDefinitionSort from 'https://esm.sh/remark-lint-definition-sort@1?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintDefinitionSort from 'remark-lint-definition-sort'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintDefinitionSort)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-definition-sort .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-definition-sort",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintDefinitionSort`][api-remark-lint-definition-sort].
+
+### `unified().use(remarkLintDefinitionSort)`
+
+Warn when when definitions are not sorted.
+
+###### Parameters
+
+There are no parameters.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+[mercury]: https://example.com/mercury/
+
+[venus]: https://example.com/venus/
+```
+
+###### Out
+
+No messages.
+
+##### `gfm-ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+[^mercury]:
+ **Mercury** is the first planet from the Sun and the smallest
+ in the Solar System.
+
+[^venus]:
+ **Venus** is the second planet from
+ the Sun.
+```
+
+###### Out
+
+No messages.
+
+##### `together.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+Definitions and footnote definitions are sorted separately.
+
+[mercury]: https://example.com/mercury/
+[venus]: https://example.com/venus/
+
+[^mercury]:
+ **Mercury** is the first planet from the Sun and the smallest
+ in the Solar System.
+
+[^venus]:
+ **Venus** is the second planet from
+ the Sun.
+```
+
+###### Out
+
+No messages.
+
+##### `together.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+Definitions are sorted per “group”.
+
+[mercury]: https://example.com/mercury/
+[venus]: https://example.com/venus/
+
+This paragraph introduces another group.
+
+[earth]: https://example.com/earth/
+[mars]: https://example.com/mars/
+```
+
+###### Out
+
+No messages.
+
+##### `comment.md`
+
+###### In
+
+```markdown
+[earth]: https://example.com/earth/
+
+<!-- HTML comments are ignored. -->
+
+[mars]: https://example.com/mars/
+```
+
+###### Out
+
+No messages.
+
+##### `comment.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+[earth]: https://example.com/earth/
+
+{/* Comments in expressions in MDX are ignored. */}
+
+[mars]: https://example.com/mars/
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+[venus]: https://example.com/venus/
+
+[mercury]: https://example.com/mercury/
+
+[earth]: https://example.com/earth/
+
+[mars]: https://example.com/mars/
+```
+
+###### Out
+
+```text
+1:1-1:36: Unexpected definition `venus` in 1st place, expected alphabetically sorted definitions, move it to 4th place
+3:1-3:40: Unexpected definition `mercury` in 2nd place, expected alphabetically sorted definitions, move it to 3rd place
+5:1-5:36: Unexpected definition `earth` in 3rd place, expected alphabetically sorted definitions, move it to 1st place
+7:1-7:34: Unexpected definition `mars` in 4th place, expected alphabetically sorted definitions, move it to 2nd place
+```
+
+##### `not-ok-gfm.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+[^venus]:
+ **Venus** is the second planet from
+ the Sun.
+
+[^mercury]:
+ **Mercury** is the first planet from the Sun and the smallest
+ in the Solar System.
+```
+
+###### Out
+
+```text
+1:1-3:13: Unexpected footnote definition `venus` in 1st place, expected alphabetically sorted definitions, move it to 2nd place
+5:1-7:25: Unexpected footnote definition `mercury` in 2nd place, expected alphabetically sorted definitions, move it to 1st place
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-definition-sort@1`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-definition-sort]: #unifieduseremarklintdefinitionsort
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-definition-sort.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-definition-sort
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-definition-sort
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-definition-sort
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-mdx]: https://mdxjs.com/packages/remark-mdx/
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-definition-spacing_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-definition-spacing_readme.md
new file mode 100644
index 0000000..eacea0b
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-definition-spacing_readme.md
@@ -0,0 +1,267 @@
+<!--This file is generated-->
+
+# remark-lint-definition-spacing
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when consecutive whitespace is used in
+a definition label.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintDefinitionSpacing)`](#unifieduseremarklintdefinitionspacing)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the whitepsace in definition labels.
+
+GFM footnotes are not affected by this rule as footnote labels cannot
+contain whitespace.
+
+## When should I use this?
+
+You can use this package to check that definition labels are consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-definition-spacing
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintDefinitionSpacing from 'https://esm.sh/remark-lint-definition-spacing@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintDefinitionSpacing from 'https://esm.sh/remark-lint-definition-spacing@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintDefinitionSpacing from 'remark-lint-definition-spacing'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintDefinitionSpacing)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-definition-spacing .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-definition-spacing",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintDefinitionSpacing`][api-remark-lint-definition-spacing].
+
+### `unified().use(remarkLintDefinitionSpacing)`
+
+Warn when consecutive whitespace is used in a definition label.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+Definitions and references are matched together by collapsing whitespace.
+Using more whitespace in labels might incorrectly indicate that they are of
+importance.
+Due to this, it’s recommended to use one space and turn this rule on.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+The first planet is [planet mercury][].
+
+[planet mercury]: https://example.com
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok-consecutive.md`
+
+###### In
+
+```markdown
+[planet␠␠␠␠mercury]: https://example.com
+```
+
+###### Out
+
+```text
+1:1-1:41: Unexpected `4` consecutive spaces in definition label, expected `1` space, remove `3` spaces
+```
+
+##### `not-ok-non-space.md`
+
+###### In
+
+```markdown
+[pla␉net␊mer␍cury]: https://e.com
+```
+
+###### Out
+
+```text
+1:1-3:21: Unexpected non-space whitespace character `\t` in definition label, expected `1` space, replace it
+1:1-3:21: Unexpected non-space whitespace character `\n` in definition label, expected `1` space, replace it
+1:1-3:21: Unexpected non-space whitespace character `\r` in definition label, expected `1` space, replace it
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-definition-spacing@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-definition-spacing]: #unifieduseremarklintdefinitionspacing
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-definition-spacing.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-definition-spacing
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-definition-spacing
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-definition-spacing
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-directive-attribute-sort_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-directive-attribute-sort_readme.md
new file mode 100644
index 0000000..0a64f2d
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-directive-attribute-sort_readme.md
@@ -0,0 +1,262 @@
+<!--This file is generated-->
+
+# remark-lint-directive-attribute-sort
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when attributes are not sorted.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintDirectiveAttributeSort)`](#unifieduseremarklintdirectiveattributesort)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks directive attribute order.
+
+## When should I use this?
+
+You can use this package to check directive attribute order.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-directive-attribute-sort
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintDirectiveAttributeSort from 'https://esm.sh/remark-lint-directive-attribute-sort@1'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintDirectiveAttributeSort from 'https://esm.sh/remark-lint-directive-attribute-sort@1?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintDirectiveAttributeSort from 'remark-lint-directive-attribute-sort'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintDirectiveAttributeSort)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-directive-attribute-sort .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-directive-attribute-sort",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintDirectiveAttributeSort`][api-remark-lint-directive-attribute-sort].
+
+### `unified().use(remarkLintDirectiveAttributeSort)`
+
+Warn when attributes are not sorted.
+
+This package does not differentiate between what values attributes have,
+or whether they are collapsed or not.
+
+###### Parameters
+
+There are no parameters.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> directives ([`remark-directive`][github-remark-directive]).
+
+```markdown
+:planet[Saturn]{aphelion="1514.50" largest="no" perihelion="1352.55" satellites=146}
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> directives ([`remark-directive`][github-remark-directive]).
+
+```markdown
+:planet[Saturn]{largest="no" perihelion=1352.55 satellites=146 aphelion="1514.50"}
+```
+
+###### Out
+
+```text
+1:17-1:24: Unexpected attribute `largest` in 1st place, expected alphabetically sorted attributes, move it to 2nd place
+1:30-1:40: Unexpected attribute `perihelion` in 2nd place, expected alphabetically sorted attributes, move it to 3rd place
+1:49-1:59: Unexpected attribute `satellites` in 3rd place, expected alphabetically sorted attributes, move it to 4th place
+1:64-1:72: Unexpected attribute `aphelion` in 4th place, expected alphabetically sorted attributes, move it to 1st place
+```
+
+##### `shortcut.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> directives ([`remark-directive`][github-remark-directive]).
+
+```markdown
+:planet[Saturn]{#saturn.sixth.gas.giant aphelion="1514.50"}
+```
+
+###### Out
+
+No messages.
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-directive-attribute-sort@1`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-directive-attribute-sort]: #unifieduseremarklintdirectiveattributesort
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-directive-attribute-sort.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-directive-attribute-sort
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-directive-attribute-sort
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-directive-attribute-sort
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-directive]: https://github.com/remarkjs/remark-directive
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-directive-collapsed-attribute_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-directive-collapsed-attribute_readme.md
new file mode 100644
index 0000000..af511f0
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-directive-collapsed-attribute_readme.md
@@ -0,0 +1,243 @@
+<!--This file is generated-->
+
+# remark-lint-directive-collapsed-attribute
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when verbose attribute values are used.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintDirectiveCollapsedAttribute)`](#unifieduseremarklintdirectivecollapsedattribute)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks that collapsed attributes are used when
+possible in directives.
+
+## When should I use this?
+
+You can use this package to check that collapsed attributes are used
+when possible in directives.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-directive-collapsed-attribute
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintDirectiveCollapsedAttribute from 'https://esm.sh/remark-lint-directive-collapsed-attribute@1'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintDirectiveCollapsedAttribute from 'https://esm.sh/remark-lint-directive-collapsed-attribute@1?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintDirectiveCollapsedAttribute from 'remark-lint-directive-collapsed-attribute'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintDirectiveCollapsedAttribute)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-directive-collapsed-attribute .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-directive-collapsed-attribute",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintDirectiveCollapsedAttribute`][api-remark-lint-directive-collapsed-attribute].
+
+### `unified().use(remarkLintDirectiveCollapsedAttribute)`
+
+Warn when verbose attribute values are used.
+
+###### Parameters
+
+There are no parameters.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> directives ([`remark-directive`][github-remark-directive]).
+
+```markdown
+:planet[Jupiter]{largest}
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> directives ([`remark-directive`][github-remark-directive]).
+
+```markdown
+:planet[Jupiter]{largest=""}
+```
+
+###### Out
+
+```text
+1:18-1:25: Unexpected verbose attribute value, expected collapsed attribute
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-directive-collapsed-attribute@1`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-directive-collapsed-attribute]: #unifieduseremarklintdirectivecollapsedattribute
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-directive-collapsed-attribute.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-directive-collapsed-attribute
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-directive-collapsed-attribute
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-directive-collapsed-attribute
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-directive]: https://github.com/remarkjs/remark-directive
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-directive-quote-style_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-directive-quote-style_readme.md
new file mode 100644
index 0000000..bd2e55e
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-directive-quote-style_readme.md
@@ -0,0 +1,540 @@
+<!--This file is generated-->
+
+# remark-lint-directive-quote-style
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when directive attribute value
+markers violate a given style.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`inferAttributes(node, document)`](#inferattributesnode-document)
+ * [`unified().use(remarkLintDirectiveQuoteStyle[, options])`](#unifieduseremarklintdirectivequotestyle-options)
+ * [`Attribute`](#attribute)
+ * [`Options`](#options)
+ * [`Style`](#style)
+ * [`Token`](#token)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the style of directive attribute value markers.
+
+## When should I use this?
+
+You can use this package to check that the style of directive
+attribute value markers is consistent.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-directive-quote-style
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintDirectiveQuoteStyle, {inferAttributes} from 'https://esm.sh/remark-lint-directive-quote-style@1'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintDirectiveQuoteStyle, {inferAttributes} from 'https://esm.sh/remark-lint-directive-quote-style@1?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintDirectiveQuoteStyle from 'remark-lint-directive-quote-style'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintDirectiveQuoteStyle)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-directive-quote-style .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-directive-quote-style",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports the identifier
+[`inferAttributes`][api-infer-attributes].
+It exports the [TypeScript][typescript] types
+[`Attribute`][api-attribute],
+[`Options`][api-options],
+[`Style`][api-style], and
+[`Token`][api-token].
+The default export is
+[`remarkLintDirectiveQuoteStyle`][api-remark-lint-directive-quote-style].
+
+### `inferAttributes(node, document)`
+
+Internal API to get offsets of where attributes occur.
+Shared with other lint rules to work with attributes.
+
+###### Parameters
+
+* `node`
+ ([`Directive`][github-mdast-util-directive-nodes])
+* `document`
+ (`string`)
+
+###### Returns
+
+[`Array<Attribute>`][api-attribute].
+
+### `unified().use(remarkLintDirectiveQuoteStyle[, options])`
+
+Warn when directive attribute value markers violate a given style.
+
+###### Parameters
+
+* `options`
+ ([`Options`][api-options], default: `'consistent'`)
+ — configuration
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Attribute`
+
+Internal attribute tokens (TypeScript type).
+
+###### Type
+
+```ts
+export interface Attribute {
+ key: Token
+ value: Token | undefined
+}
+```
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Properties
+
+* `allowUnquoted`
+ (`boolean`, default: `true`)
+ — whether to allow unquoted attributes;
+ otherwise attribute values must be quoted
+* `quote`
+ ([`Style`][api-style] or `'consistent'`, default: `'consistent'`)
+ — quote
+
+### `Style`
+
+Style (TypeScript type).
+
+###### Type
+
+```ts
+type Style = '"' | '\''
+```
+
+### `Token`
+
+Info on an internal token (TypeScript type).
+
+###### Type
+
+```ts
+type Token = [value: string, start: number, end: number]
+```
+
+## Recommendation
+
+In HTML,
+attributes are commonly written with double quotes.
+It’s recommended to go with that.
+To configure this rule with `'"'`.
+
+## Fix
+
+[`remark-directive`][github-remark-directive] typically formats
+attributes with double quotes.
+It can be passed several options to influence which quote it uses.
+The options `quote` and `quoteSmart` can be used together with this
+lint rule.
+
+## Examples
+
+##### `ok-consistent.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> directives ([`remark-directive`][github-remark-directive]).
+
+```markdown
+:planet[Venus]{aphelion="0.728213" perihelion="0.718440" symbol=♀︎}
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok-consistent.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> directives ([`remark-directive`][github-remark-directive]).
+
+```markdown
+:planet[Venus]{aphelion="0.728213" perihelion='0.718440' symbol=♀︎}
+```
+
+###### Out
+
+```text
+1:47-1:57: Unexpected directive attribute quote markers `'`, expected `"`
+```
+
+##### `double-quote.md`
+
+When configured with `'"'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> directives ([`remark-directive`][github-remark-directive]).
+
+```markdown
+:planet[Venus]{aphelion="0.728213" perihelion='0.718440' symbol=♀︎}
+```
+
+###### Out
+
+```text
+1:47-1:57: Unexpected directive attribute quote markers `'`, expected `"`
+```
+
+##### `single-quote.md`
+
+When configured with `"'"`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> directives ([`remark-directive`][github-remark-directive]).
+
+```markdown
+:planet[Venus]{aphelion="0.728213" perihelion='0.718440' symbol=♀︎}
+```
+
+###### Out
+
+```text
+1:25-1:35: Unexpected directive attribute quote markers `"`, expected `'`
+```
+
+##### `other-attributes.md`
+
+When configured with `'"'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> directives ([`remark-directive`][github-remark-directive]).
+
+```markdown
+:planet[Jupiter]{#jupiter.fifth.gas-giant symbol=♃ .zeus}
+```
+
+###### Out
+
+No messages.
+
+##### `whitespace.md`
+
+When configured with `'"'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> directives ([`remark-directive`][github-remark-directive]).
+
+```markdown
+:planet[Mars]{ aphelion = "249261000" perihelion = '206650000' symbol = ♂ }.
+```
+
+###### Out
+
+```text
+1:52-1:63: Unexpected directive attribute quote markers `'`, expected `"`
+```
+
+##### `text-directive.md`
+
+When configured with `'"'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> directives ([`remark-directive`][github-remark-directive]).
+
+```markdown
+:planet{}
+
+:planet[Venus]{aphelion="0.728213" perihelion='0.718440'}
+
+:planet{symbol='♂'}
+
+:planet[]
+```
+
+###### Out
+
+```text
+3:47-3:57: Unexpected directive attribute quote markers `'`, expected `"`
+5:16-5:19: Unexpected directive attribute quote markers `'`, expected `"`
+```
+
+##### `leaf-directive.md`
+
+When configured with `'"'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> directives ([`remark-directive`][github-remark-directive]).
+
+```markdown
+::planet{}
+
+::planet[Venus]{aphelion="0.728213" perihelion='0.718440'}
+
+::planet{symbol='♂'}
+
+::planet[]
+```
+
+###### Out
+
+```text
+3:48-3:58: Unexpected directive attribute quote markers `'`, expected `"`
+5:17-5:20: Unexpected directive attribute quote markers `'`, expected `"`
+```
+
+##### `container-directive.md`
+
+When configured with `'"'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> directives ([`remark-directive`][github-remark-directive]).
+
+```markdown
+:::planet{}
+:::
+
+:::planet[Venus]{aphelion="0.728213" perihelion='0.718440'}
+:::
+
+:::planet{symbol='♃'}
+Jupiter
+:::
+
+:::planet{symbol='🜨'}
+:::
+
+:::planet[]
+:::
+```
+
+###### Out
+
+```text
+4:49-4:59: Unexpected directive attribute quote markers `'`, expected `"`
+7:18-7:21: Unexpected directive attribute quote markers `'`, expected `"`
+11:18-11:22: Unexpected directive attribute quote markers `'`, expected `"`
+```
+
+##### `allow-unquoted.md`
+
+When configured with `{ allowUnquoted: false }`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> directives ([`remark-directive`][github-remark-directive]).
+
+```markdown
+:planet[Venus]{aphelion=0.728213}
+
+:planet[Mars]{aphelion="249261000" symbol=♂}.
+```
+
+###### Out
+
+```text
+1:25-1:33: Unexpected unquoted directive attribute, expected quote around value
+3:43-3:44: Unexpected unquoted directive attribute, expected `"` around value
+```
+
+##### `not-ok.md`
+
+When configured with `'🌍'`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `options`, expected `'"'`, `"'"`, or `'consistent'`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-directive-quote-style@1`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-attribute]: #attribute
+
+[api-infer-attributes]: #inferattributesnode-document
+
+[api-options]: #options
+
+[api-remark-lint-directive-quote-style]: #unifieduseremarklintdirectivequotestyle-options
+
+[api-style]: #style
+
+[api-token]: #token
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-directive-quote-style.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-directive-quote-style
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-directive-quote-style
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-directive-quote-style
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-mdast-util-directive-nodes]: https://github.com/syntax-tree/mdast-util-directive#nodes
+
+[github-remark-directive]: https://github.com/remarkjs/remark-directive
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-directive-shortcut-attribute_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-directive-shortcut-attribute_readme.md
new file mode 100644
index 0000000..3bb2ab1
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-directive-shortcut-attribute_readme.md
@@ -0,0 +1,244 @@
+<!--This file is generated-->
+
+# remark-lint-directive-shortcut-attribute
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when verbose attribute names are used.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintDirectiveShortcutAttribute)`](#unifieduseremarklintdirectiveshortcutattribute)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks that shortcut attributes are used when possible in
+directives.
+
+## When should I use this?
+
+You can use this package to check that shortcut attributes are used
+when possible in directives.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-directive-shortcut-attribute
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintDirectiveShortcutAttribute from 'https://esm.sh/remark-lint-directive-shortcut-attribute@1'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintDirectiveShortcutAttribute from 'https://esm.sh/remark-lint-directive-shortcut-attribute@1?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintDirectiveShortcutAttribute from 'remark-lint-directive-shortcut-attribute'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintDirectiveShortcutAttribute)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-directive-shortcut-attribute .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-directive-shortcut-attribute",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintDirectiveShortcutAttribute`][api-remark-lint-directive-shortcut-attribute].
+
+### `unified().use(remarkLintDirectiveShortcutAttribute)`
+
+Warn when verbose attribute names are used.
+
+###### Parameters
+
+There are no parameters.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> directives ([`remark-directive`][github-remark-directive]).
+
+```markdown
+:planet[Jupiter]{#jupiter.fifth.largest}
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> directives ([`remark-directive`][github-remark-directive]).
+
+```markdown
+:planet[Jupiter]{class="fifth largest" id="jupiter"}
+```
+
+###### Out
+
+```text
+1:18-1:23: Unexpected verbose attribute name `class`, expected shortcut attribute with `.`
+1:40-1:42: Unexpected verbose attribute name `id`, expected shortcut attribute with `#`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-directive-shortcut-attribute@1`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-directive-shortcut-attribute]: #unifieduseremarklintdirectiveshortcutattribute
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-directive-shortcut-attribute.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-directive-shortcut-attribute
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-directive-shortcut-attribute
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-directive-shortcut-attribute
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-directive]: https://github.com/remarkjs/remark-directive
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-directive-unique-attribute-name_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-directive-unique-attribute-name_readme.md
new file mode 100644
index 0000000..3d2f07f
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-directive-unique-attribute-name_readme.md
@@ -0,0 +1,276 @@
+<!--This file is generated-->
+
+# remark-lint-directive-unique-attribute-name
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when directive attribute names
+are reused.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintDirectiveUniqueAttributeName)`](#unifieduseremarklintdirectiveuniqueattributename)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks that directive attribute names are unique.
+
+## When should I use this?
+
+You can use this package to check that directive attribute names
+are unique.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-directive-unique-attribute-name
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintDirectiveUniqueAttributeName from 'https://esm.sh/remark-lint-directive-unique-attribute-name@1'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintDirectiveUniqueAttributeName from 'https://esm.sh/remark-lint-directive-unique-attribute-name@1?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintDirectiveUniqueAttributeName from 'remark-lint-directive-unique-attribute-name'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintDirectiveUniqueAttributeName)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-directive-unique-attribute-name .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-directive-unique-attribute-name",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintDirectiveUniqueAttributeName`][api-remark-lint-directive-unique-attribute-name].
+
+### `unified().use(remarkLintDirectiveUniqueAttributeName)`
+
+Warn when directive attribute names are reused.
+
+###### Parameters
+
+There are no parameters.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> directives ([`remark-directive`][github-remark-directive]).
+
+```markdown
+:planet[Venus]{aphelion=0.728213 perihelion=0.718440 symbol=♀︎}
+```
+
+###### Out
+
+No messages.
+
+##### `ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> directives ([`remark-directive`][github-remark-directive]).
+
+```markdown
+:planet{#mercury value="Mercury"}
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> directives ([`remark-directive`][github-remark-directive]).
+
+```markdown
+:planet{#mercury adjective="Venusian" adjective="Cytherean" aphelion="0.728213" id="venus"}
+```
+
+###### Out
+
+```text
+1:39-1:48: Unexpected attribute name with equal text, expected unique attribute names
+1:81-1:83: Unexpected attribute name with equivalent text, expected unique attribute names
+```
+
+##### `other-attributes.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> directives ([`remark-directive`][github-remark-directive]).
+
+```markdown
+:planet[Mercury]{closest},
+:planet[Venus]{aphelion=0.728213}, and
+:planet[Mars]{.red.orange class="fourth"}.
+```
+
+###### Out
+
+No messages.
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-directive-unique-attribute-name@1`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-directive-unique-attribute-name]: #unifieduseremarklintdirectiveuniqueattributename
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-directive-unique-attribute-name.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-directive-unique-attribute-name
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-directive-unique-attribute-name
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-directive-unique-attribute-name
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-directive]: https://github.com/remarkjs/remark-directive
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-emphasis-marker_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-emphasis-marker_readme.md
new file mode 100644
index 0000000..4030419
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-emphasis-marker_readme.md
@@ -0,0 +1,352 @@
+<!--This file is generated-->
+
+# remark-lint-emphasis-marker
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when emphasis markers are inconsistent.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintEmphasisMarker[, options])`](#unifieduseremarklintemphasismarker-options)
+ * [`Marker`](#marker)
+ * [`Options`](#options)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the style of emphasis markers.
+
+## When should I use this?
+
+You can use this package to check that emphasis is consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | `'consistent'` |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `'*'` |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-emphasis-marker
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintEmphasisMarker from 'https://esm.sh/remark-lint-emphasis-marker@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintEmphasisMarker from 'https://esm.sh/remark-lint-emphasis-marker@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintEmphasisMarker from 'remark-lint-emphasis-marker'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintEmphasisMarker)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-emphasis-marker .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-emphasis-marker",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] types
+[`Marker`][api-marker] and
+[`Options`][api-options].
+The default export is
+[`remarkLintEmphasisMarker`][api-remark-lint-emphasis-marker].
+
+### `unified().use(remarkLintEmphasisMarker[, options])`
+
+Warn when emphasis markers are inconsistent.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], default: `'consistent'`)
+ — preferred style or whether to detect the first style and warn for
+ further differences
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Marker`
+
+Marker (TypeScript type).
+
+###### Type
+
+```ts
+type Marker = '*' | '_'
+```
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Type
+
+```ts
+type Options = Marker | 'consistent'
+```
+
+## Recommendation
+
+Whether asterisks or underscores are used affects how and whether emphasis
+works.
+Underscores are sometimes used to represent normal underscores inside words,
+so there are extra rules in markdown to support that.
+Asterisks are not used in natural language,
+so they don’t need these rules,
+and thus can form emphasis in more cases.
+Asterisks can also be used as the marker of more constructs than underscores:
+lists.
+Due to having simpler parsing rules,
+looking more like syntax,
+and that they can be used for more constructs,
+it’s recommended to prefer asterisks.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] formats emphasis with
+asterisks by default.
+Pass `emphasis: '_'` to always use underscores.
+
+## Examples
+
+##### `ok-asterisk.md`
+
+When configured with `'*'`.
+
+###### In
+
+```markdown
+*Mercury*.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok-asterisk.md`
+
+When configured with `'*'`.
+
+###### In
+
+```markdown
+_Mercury_.
+```
+
+###### Out
+
+```text
+1:1-1:10: Unexpected emphasis marker `_`, expected `*`
+```
+
+##### `ok-underscore.md`
+
+When configured with `'_'`.
+
+###### In
+
+```markdown
+_Mercury_.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok-underscore.md`
+
+When configured with `'_'`.
+
+###### In
+
+```markdown
+*Mercury*.
+```
+
+###### Out
+
+```text
+1:1-1:10: Unexpected emphasis marker `*`, expected `_`
+```
+
+##### `not-ok-consistent.md`
+
+###### In
+
+```markdown
+*Mercury* and _Venus_.
+```
+
+###### Out
+
+```text
+1:15-1:22: Unexpected emphasis marker `_`, expected `*`
+```
+
+##### `not-ok.md`
+
+When configured with `'🌍'`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `options`, expected `'*'`, `'_'`, or `'consistent'`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-emphasis-marker@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-marker]: #marker
+
+[api-options]: #options
+
+[api-remark-lint-emphasis-marker]: #unifieduseremarklintemphasismarker-options
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-emphasis-marker.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-emphasis-marker
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-emphasis-marker
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-emphasis-marker
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-fenced-code-flag_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-fenced-code-flag_readme.md
new file mode 100644
index 0000000..d28e2a8
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-fenced-code-flag_readme.md
@@ -0,0 +1,435 @@
+<!--This file is generated-->
+
+# remark-lint-fenced-code-flag
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when language flags of fenced code
+are not used or used incorrectly.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintFencedCodeFlag[, options])`](#unifieduseremarklintfencedcodeflag-options)
+ * [`checkGithubLinguistFlag(value)`](#checkgithublinguistflagvalue)
+ * [`CheckFlag`](#checkflag)
+ * [`Options`](#options)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the language flags of fenced code blocks,
+whether they exist,
+and optionally what values they hold.
+
+Particularly,
+it provides a check according to GitHub Linguist.
+Which is what GitHub uses to highlight code.
+So you can make sure that the language flags you use are recognized by
+GitHub (or [`starry-night`][github-starry-night])
+
+## When should I use this?
+
+You can use this package to check that the style of language flags of fenced
+code blocks is consistent and known.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `{ allowEmpty: false }` |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-fenced-code-flag
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintFencedCodeFlag, {checkGithubLinguistFlag} from 'https://esm.sh/remark-lint-fenced-code-flag@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintFencedCodeFlag, {checkGithubLinguistFlag} from 'https://esm.sh/remark-lint-fenced-code-flag@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintFencedCodeFlag from 'remark-lint-fenced-code-flag'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintFencedCodeFlag)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-fenced-code-flag .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-fenced-code-flag",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports the identifier
+[`checkGithubLinguistFlag`][api-check-github-linguist-flag].
+It exports the [TypeScript][typescript] types
+[`CheckFlag`][api-check-flag] and
+[`Options`][api-options].
+The default export is
+[`remarkLintFencedCodeFlag`][api-remark-lint-fenced-code-flag].
+
+### `unified().use(remarkLintFencedCodeFlag[, options])`
+
+Warn when language flags of fenced code are not used.
+
+###### Parameters
+
+* `options` (`Array<string>`, [`CheckFlag`][api-check-flag], or
+ [`Options`][api-options], optional)
+ — check, configuration, or flags to allow
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `checkGithubLinguistFlag(value)`
+
+Check according to GitHub Linguist.
+
+###### Parameters
+
+* `value` (`string`)
+ — language flag to check
+
+###### Returns
+
+Whether the flag is valid (`undefined`),
+or a message to warn about (`string`).
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `CheckFlag`
+
+Custom check (TypeScript type).
+
+###### Parameters
+
+* `value` (`string`)
+ — language flag to check
+
+###### Returns
+
+Whether the flag is valid (`undefined`),
+or a message to warn about (`string`).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Fields
+
+* `allowEmpty` (`boolean`, default: `false`)
+ — allow language flags to be omitted
+* `flags` (`Array<string>`, optional)
+ — flags to allow,
+ other flags will result in a warning
+
+## Recommendation
+
+While omitting language flags is fine to signal that code is plain text,
+it *could* point to a mistake.
+It’s recommended to instead use a certain flag for plain text (such as
+`txt`) and to turn this rule on.
+If possible,
+stick with what is supported by GitHub.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+````markdown
+Some markdown:
+
+```markdown
+# Mercury
+```
+````
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+````markdown
+```
+mercury()
+```
+````
+
+###### Out
+
+```text
+1:1-3:4: Unexpected missing fenced code language flag in info string, expected keyword
+```
+
+##### `ok-allow-empty.md`
+
+When configured with `{ allowEmpty: true }`.
+
+###### In
+
+````markdown
+```
+mercury()
+```
+````
+
+###### Out
+
+No messages.
+
+##### `not-ok-allow-empty.md`
+
+When configured with `{ allowEmpty: false }`.
+
+###### In
+
+````markdown
+```
+mercury()
+```
+````
+
+###### Out
+
+```text
+1:1-3:4: Unexpected missing fenced code language flag in info string, expected keyword
+```
+
+##### `ok-array.md`
+
+When configured with `[ 'markdown' ]`.
+
+###### In
+
+````markdown
+```markdown
+# Mercury
+```
+````
+
+###### Out
+
+No messages.
+
+##### `ok-options.md`
+
+When configured with `{ flags: [ 'markdown' ] }`.
+
+###### In
+
+````markdown
+```markdown
+# Mercury
+```
+````
+
+###### Out
+
+No messages.
+
+##### `not-ok-array.md`
+
+When configured with `[ 'markdown' ]`.
+
+###### In
+
+````markdown
+```javascript
+mercury()
+```
+````
+
+###### Out
+
+```text
+1:1-3:4: Unexpected fenced code language flag `javascript` in info string, expected `markdown`
+```
+
+##### `not-ok-long-array.md`
+
+When configured with `[ 'javascript', 'markdown', 'mdx', 'typescript' ]`.
+
+###### In
+
+````markdown
+```html
+<h1>Mercury</h1>
+```
+````
+
+###### Out
+
+```text
+1:1-3:4: Unexpected fenced code language flag `html` in info string, expected `javascript`, `markdown`, `mdx`, …
+```
+
+##### `not-ok-options.md`
+
+When configured with `'🌍'`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `options`, expected array or object
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-fenced-code-flag@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-check-flag]: #checkflag
+
+[api-check-github-linguist-flag]: #checkgithublinguistflagvalue
+
+[api-options]: #options
+
+[api-remark-lint-fenced-code-flag]: #unifieduseremarklintfencedcodeflag-options
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-fenced-code-flag.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-fenced-code-flag
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-fenced-code-flag
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-fenced-code-flag
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-starry-night]: https://github.com/wooorm/starry-night
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-fenced-code-marker_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-fenced-code-marker_readme.md
new file mode 100644
index 0000000..b7a11c6
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-fenced-code-marker_readme.md
@@ -0,0 +1,363 @@
+<!--This file is generated-->
+
+# remark-lint-fenced-code-marker
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when fenced code markers are
+inconsistent.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintFencedCodeMarker[, options])`](#unifieduseremarklintfencedcodemarker-options)
+ * [`Marker`](#marker)
+ * [`Options`](#options)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks fenced code block markers.
+
+## When should I use this?
+
+You can use this package to check that fenced code block markers are
+consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | `'consistent'` |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | ``'`'`` |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-fenced-code-marker
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintFencedCodeMarker from 'https://esm.sh/remark-lint-fenced-code-marker@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintFencedCodeMarker from 'https://esm.sh/remark-lint-fenced-code-marker@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintFencedCodeMarker from 'remark-lint-fenced-code-marker'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintFencedCodeMarker)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-fenced-code-marker .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-fenced-code-marker",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] types
+[`Marker`][api-marker] and
+[`Options`][api-options].
+The default export is
+[`remarkLintFencedCodeMarker`][api-remark-lint-fenced-code-marker].
+
+### `unified().use(remarkLintFencedCodeMarker[, options])`
+
+Warn when fenced code markers are inconsistent.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], default: `'consistent'`)
+ — preferred style or whether to detect the first style and warn for
+ further differences
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Marker`
+
+Marker (TypeScript type).
+
+###### Type
+
+```ts
+type Marker = '`' | '~'
+```
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Type
+
+```ts
+type Options = Marker | 'consistent'
+```
+
+## Recommendation
+
+Tildes are uncommon.
+So it’s recommended to configure this rule with ``'`'``.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] formats fenced code with grave
+accents by default.
+Pass `fence: '~'` to always use tildes.
+
+## Examples
+
+##### `ok-indented.md`
+
+###### In
+
+```markdown
+Indented code blocks are not affected by this rule:
+
+ mercury()
+```
+
+###### Out
+
+No messages.
+
+##### `ok-tick.md`
+
+When configured with ``'`'``.
+
+###### In
+
+````markdown
+```javascript
+mercury()
+```
+
+```
+venus()
+```
+````
+
+###### Out
+
+No messages.
+
+##### `ok-tilde.md`
+
+When configured with `'~'`.
+
+###### In
+
+```markdown
+~~~javascript
+mercury()
+~~~
+
+~~~
+venus()
+~~~
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok-consistent-tick.md`
+
+###### In
+
+````markdown
+```javascript
+mercury()
+```
+
+~~~
+venus()
+~~~
+````
+
+###### Out
+
+```text
+5:1-7:4: Unexpected fenced code marker `~`, expected `` ` ``
+```
+
+##### `not-ok-consistent-tilde.md`
+
+###### In
+
+````markdown
+~~~javascript
+mercury()
+~~~
+
+```
+venus()
+```
+````
+
+###### Out
+
+```text
+5:1-7:4: Unexpected fenced code marker `` ` ``, expected `~`
+```
+
+##### `not-ok-incorrect.md`
+
+When configured with `'🌍'`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `options`, expected ``'`'``, `'~'`, or `'consistent'`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-fenced-code-marker@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-marker]: #marker
+
+[api-options]: #options
+
+[api-remark-lint-fenced-code-marker]: #unifieduseremarklintfencedcodemarker-options
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-fenced-code-marker.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-fenced-code-marker
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-fenced-code-marker
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-fenced-code-marker
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-file-extension_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-file-extension_readme.md
new file mode 100644
index 0000000..ed6f51f
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-file-extension_readme.md
@@ -0,0 +1,310 @@
+<!--This file is generated-->
+
+# remark-lint-file-extension
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn for unexpected file extensions.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintFileExtension[, options])`](#unifieduseremarklintfileextension-options)
+ * [`Extensions`](#extensions)
+ * [`Options`](#options)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the file extension.
+
+## When should I use this?
+
+You can use this package to check that file extensions are consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `'md'` |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-file-extension
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintFileExtension from 'https://esm.sh/remark-lint-file-extension@3'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintFileExtension from 'https://esm.sh/remark-lint-file-extension@3?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintFileExtension from 'remark-lint-file-extension'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintFileExtension)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-file-extension .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-file-extension",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] types
+[`Extensions`][api-extensions] and
+[`Options`][api-options].
+The default export is
+[`remarkLintFileExtension`][api-remark-lint-file-extension].
+
+### `unified().use(remarkLintFileExtension[, options])`
+
+Warn for unexpected extensions.
+
+###### Parameters
+
+* `options` ([`Extensions`][api-extensions] or [`Options`][api-options],
+ optional)
+ — configuration
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Extensions`
+
+File extension(s) (TypeScript type).
+
+###### Type
+
+```ts
+type Extensions = Array<string> | string
+```
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Fields
+
+* `allowExtensionless` (`boolean`, default: `true`)
+ — allow no file extension such as `AUTHORS` or `LICENSE`
+* `extensions` ([`Extensions`][api-extensions], default: `['mdx', 'md']`)
+ — allowed file extension(s)
+
+## Recommendation
+
+Use `md` as it’s the most common.
+Also use `md` when your markdown contains common syntax extensions (such as
+GFM, frontmatter, or math).
+Do not use `md` for MDX: use `mdx` instead.
+
+## Examples
+
+##### `readme.md`
+
+###### Out
+
+No messages.
+
+##### `readme.mdx`
+
+###### Out
+
+No messages.
+
+##### `readme`
+
+###### Out
+
+No messages.
+
+##### `readme`
+
+When configured with `{ allowExtensionless: false }`.
+
+###### Out
+
+```text
+1:1: Unexpected missing file extension, expected `mdx` or `md`
+```
+
+##### `readme.mkd`
+
+###### Out
+
+```text
+1:1: Unexpected file extension `mkd`, expected `mdx` or `md`
+```
+
+##### `readme.mkd`
+
+When configured with `'mkd'`.
+
+###### Out
+
+No messages.
+
+##### `readme.css`
+
+When configured with `[
+ 'markdown', 'md',
+ 'mdown', 'mdwn',
+ 'mdx', 'mkd',
+ 'mkdn', 'mkdown',
+ 'ron'
+]`.
+
+###### Out
+
+```text
+1:1: Unexpected file extension `css`, expected `markdown`, `md`, `mdown`, …
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-file-extension@3`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-extensions]: #extensions
+
+[api-options]: #options
+
+[api-remark-lint-file-extension]: #unifieduseremarklintfileextension-options
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-file-extension.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-file-extension
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-file-extension
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-file-extension
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-final-definition_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-final-definition_readme.md
new file mode 100644
index 0000000..b9905ce
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-final-definition_readme.md
@@ -0,0 +1,352 @@
+<!--This file is generated-->
+
+# remark-lint-final-definition
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when definitions are used *in* the
+document instead of at the end.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintFinalDefinition)`](#unifieduseremarklintfinaldefinition)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks where definitions are placed.
+
+## When should I use this?
+
+You can use this package to check that definitions are consistently at the
+end of the document.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-final-definition
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintFinalDefinition from 'https://esm.sh/remark-lint-final-definition@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintFinalDefinition from 'https://esm.sh/remark-lint-final-definition@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintFinalDefinition from 'remark-lint-final-definition'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintFinalDefinition)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-final-definition .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-final-definition",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintFinalDefinition`][api-remark-lint-final-definition].
+
+### `unified().use(remarkLintFinalDefinition)`
+
+Warn when definitions are used *in* the document instead of at the end.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+There are different strategies for placing definitions.
+The simplest is perhaps to place them all at the bottem of documents.
+If you prefer that, turn on this rule.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+Mercury.
+
+[venus]: https://example.com
+```
+
+###### Out
+
+No messages.
+
+##### `ok.md`
+
+###### In
+
+```markdown
+[mercury]: https://example.com/mercury/
+[venus]: https://example.com/venus/
+```
+
+###### Out
+
+No messages.
+
+##### `ok-html-comments.md`
+
+###### In
+
+```markdown
+Mercury.
+
+[venus]: https://example.com/venus/
+
+<!-- HTML comments in markdown are ignored. -->
+
+[earth]: https://example.com/earth/
+```
+
+###### Out
+
+No messages.
+
+##### `ok-mdx-comments.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+Mercury.
+
+[venus]: https://example.com/venus/
+
+{/* Comments in expressions in MDX are ignored. */}
+
+[earth]: https://example.com/earth/
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+Mercury.
+
+[venus]: https://example.com/venus/
+
+Earth.
+```
+
+###### Out
+
+```text
+3:1-3:36: Unexpected definition before last content, expected definitions after line `5`
+```
+
+##### `gfm-nok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+Mercury.
+
+[^venus]:
+ **Venus** is the second planet from
+ the Sun.
+
+Earth.
+```
+
+###### Out
+
+```text
+3:1-5:13: Unexpected footnote definition before last content, expected definitions after line `7`
+```
+
+##### `gfm-ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+Mercury.
+
+Earth.
+
+[^venus]:
+ **Venus** is the second planet from
+ the Sun.
+```
+
+###### Out
+
+No messages.
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-final-definition@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-final-definition]: #unifieduseremarklintfinaldefinition
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-final-definition.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-final-definition
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-final-definition
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-final-definition
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-mdx]: https://mdxjs.com/packages/remark-mdx/
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-final-newline_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-final-newline_readme.md
new file mode 100644
index 0000000..8fb07ca
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-final-newline_readme.md
@@ -0,0 +1,251 @@
+<!--This file is generated-->
+
+# remark-lint-final-newline
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when a final line ending is missing.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintFinalNewline)`](#unifieduseremarklintfinalnewline)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the final line ending.
+
+## When should I use this?
+
+You can use this package to check final line endings.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-final-newline
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintFinalNewline from 'https://esm.sh/remark-lint-final-newline@3'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintFinalNewline from 'https://esm.sh/remark-lint-final-newline@3?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintFinalNewline from 'remark-lint-final-newline'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintFinalNewline)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-final-newline .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-final-newline",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintFinalNewline`][api-remark-lint-final-newline].
+
+### `unified().use(remarkLintFinalNewline)`
+
+Warn when a final line ending is missing.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+Turn this rule on.
+See [StackExchange][] for more info.
+
+## Fix
+
+[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify)
+always adds final line endings.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+Mercury␊
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+Mercury␀
+```
+
+###### Out
+
+```text
+1:8: Unexpected missing final newline character, expected line feed (`\n`) at end of file
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-final-newline@3`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-final-newline]: #unifieduseremarklintfinalnewline
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-final-newline.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-final-newline
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-final-newline
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-final-newline
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[stackexchange]: https://unix.stackexchange.com/questions/18743
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-first-heading-level_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-first-heading-level_readme.md
new file mode 100644
index 0000000..c0ef5f4
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-first-heading-level_readme.md
@@ -0,0 +1,335 @@
+<!--This file is generated-->
+
+# remark-lint-first-heading-level
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when the first heading has an unexpected rank.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintFirstHeadingLevel[, options])`](#unifieduseremarklintfirstheadinglevel-options)
+ * [`Options`](#options)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the rank of the first heading.
+
+## When should I use this?
+
+You can use this package to check that the rank of first headings is
+consistent.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-first-heading-level
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintFirstHeadingLevel from 'https://esm.sh/remark-lint-first-heading-level@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintFirstHeadingLevel from 'https://esm.sh/remark-lint-first-heading-level@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintFirstHeadingLevel from 'remark-lint-first-heading-level'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintFirstHeadingLevel)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-first-heading-level .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-first-heading-level",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] type
+[`Options`][api-options].
+The default export is
+[`remarkLintFirstHeadingLevel`][api-remark-lint-first-heading-level].
+
+### `unified().use(remarkLintFirstHeadingLevel[, options])`
+
+Warn when the first heading has an unexpected rank.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], default: `1`)
+ — configuration
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Type
+
+```ts
+type Options = 1 | 2 | 3 | 4 | 5 | 6
+```
+
+## Recommendation
+
+In most cases you’d want to first heading in a markdown document to start at
+rank `1`.
+In some cases a different rank makes more sense,
+such as when building a blog and generating the primary heading from
+frontmatter metadata,
+in which case a value of `2` can be defined here or the rule can be turned
+off.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+# Mercury
+```
+
+###### Out
+
+No messages.
+
+##### `ok-delay.md`
+
+###### In
+
+```markdown
+Mercury.
+
+# Venus
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+## Mercury
+
+Venus.
+```
+
+###### Out
+
+```text
+1:1-1:11: Unexpected first heading rank `2`, expected rank `1`
+```
+
+##### `ok.md`
+
+When configured with `2`.
+
+###### In
+
+```markdown
+## Mercury
+
+Venus.
+```
+
+###### Out
+
+No messages.
+
+##### `ok-html.md`
+
+###### In
+
+```markdown
+<div>Mercury.</div>
+
+<h1>Venus</h1>
+```
+
+###### Out
+
+No messages.
+
+##### `ok-mdx.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+<div>Mercury.</div>
+
+<h1>Venus</h1>
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok-options.md`
+
+When configured with `'🌍'`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `options`, expected `1`, `2`, `3`, `4`, `5`, or `6`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-first-heading-level@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-options]: #options
+
+[api-remark-lint-first-heading-level]: #unifieduseremarklintfirstheadinglevel-options
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-first-heading-level.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-first-heading-level
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-first-heading-level
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-first-heading-level
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-mdx]: https://mdxjs.com/packages/remark-mdx/
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-hard-break-spaces_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-hard-break-spaces_readme.md
new file mode 100644
index 0000000..6bc763f
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-hard-break-spaces_readme.md
@@ -0,0 +1,333 @@
+<!--This file is generated-->
+
+# remark-lint-hard-break-spaces
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when spaces are used for hard breaks.
+Either optionally spaces at all,
+or more spaces than the needed 2.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintHardBreakSpaces[, options])`](#unifieduseremarklinthardbreakspaces-options)
+ * [`Options`](#options)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks whitespace hard breaks.
+
+## When should I use this?
+
+You can use this package to check that the spaces in hard breaks are
+consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+| [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-hard-break-spaces
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintHardBreakSpaces from 'https://esm.sh/remark-lint-hard-break-spaces@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintHardBreakSpaces from 'https://esm.sh/remark-lint-hard-break-spaces@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintHardBreakSpaces from 'remark-lint-hard-break-spaces'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintHardBreakSpaces)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-hard-break-spaces .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-hard-break-spaces",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] type
+[`Options`][api-options].
+The default export is
+[`remarkLintHardBreakSpaces`][api-remark-lint-hard-break-spaces].
+
+### `unified().use(remarkLintHardBreakSpaces[, options])`
+
+Warn when more spaces are used than needed for hard breaks.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], default: `'consistent'`)
+ — either a preferred indent or whether to detect the first style
+ and warn for further differences
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Fields
+
+* `allowSpaces` (`boolean`, default: `true`)
+ — allow trailing space hard breaks at all;
+ use escape hard breaks otherwise
+
+## Recommendation
+
+Less than two spaces do not create a hard breaks and more than two spaces
+have no effect.
+Due to this, it’s recommended to turn this rule on.
+
+With CommonMark,
+it is now possible to use a backslash (`\`) at the end of a line to create a
+hard break.
+It is now recommended to pass `allowSpaces: false`.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+**Mercury** is the first planet from the Sun␠␠
+and the smallest in the Solar System.
+**Venus** is the second planet from\
+the Sun.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+**Mercury** is the first planet from the Sun␠␠␠
+and the smallest in the Solar System.
+```
+
+###### Out
+
+```text
+1:45-2:1: Unexpected `3` spaces for hard break, expected `2` spaces
+```
+
+##### `escape.md`
+
+When configured with `{ allowSpaces: false }`.
+
+###### In
+
+```markdown
+**Mercury** is the first planet from the Sun␠␠
+and the smallest in the Solar System.
+**Venus** is the second planet from the\
+Sun.
+```
+
+###### Out
+
+```text
+1:45-2:1: Unexpected `2` spaces for hard break, expected escape
+```
+
+##### `containers.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+[^mercury]:
+ > * > * **Mercury** is the first planet from the Sun␠␠␠
+ > > and the smallest in the Solar System.
+```
+
+###### Out
+
+```text
+2:57-3:1: Unexpected `3` spaces for hard break, expected `2` spaces
+```
+
+##### `not-ok-options.md`
+
+When configured with `'🌍'`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `options`, expected object
+```
+
+##### `not-ok-options-field.md`
+
+When configured with `{ allowSpaces: '🌍' }`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `options.allowSpaces`, expected `boolean`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-hard-break-spaces@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-options]: #options
+
+[api-remark-lint-hard-break-spaces]: #unifieduseremarklinthardbreakspaces-options
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-hard-break-spaces.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-hard-break-spaces
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-hard-break-spaces
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-hard-break-spaces
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-heading-increment_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-heading-increment_readme.md
new file mode 100644
index 0000000..7c91b5b
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-heading-increment_readme.md
@@ -0,0 +1,327 @@
+<!--This file is generated-->
+
+# remark-lint-heading-increment
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when heading ranks increment with more than
+1 at a time.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintHeadingIncrement)`](#unifieduseremarklintheadingincrement)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the increase of headings.
+
+## When should I use this?
+
+You can use this package to check the increase of headings.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-heading-increment
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintHeadingIncrement from 'https://esm.sh/remark-lint-heading-increment@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintHeadingIncrement from 'https://esm.sh/remark-lint-heading-increment@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintHeadingIncrement from 'remark-lint-heading-increment'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintHeadingIncrement)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-heading-increment .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-heading-increment",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintHeadingIncrement`][api-remark-lint-heading-increment].
+
+### `unified().use(remarkLintHeadingIncrement)`
+
+Warn when heading ranks increment with more than 1 at a time.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+While markdown is not only used for HTML,
+HTML accessibility guidelines state that headings should increment by one at
+a time.
+As in,
+say the previous heading had a rank of 2 (so `<h2>`),
+then the following heading that is to be considered “inside” it should have
+a rank of 3 (`<h3>`).
+Due to this,
+when HTML output is a goal of the document,
+it’s recommended that this rule is turned on.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+# Mercury
+
+## Nomenclature
+```
+
+###### Out
+
+No messages.
+
+##### `also-ok.md`
+
+###### In
+
+```markdown
+#### Impact basins and craters
+
+#### Plains
+
+#### Compressional features
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+# Mercury
+
+### Internal structure
+
+### Surface geology
+
+## Observation history
+
+#### Mariner 10
+```
+
+###### Out
+
+```text
+3:1-3:23: Unexpected heading rank `3`, expected rank `2`
+5:1-5:20: Unexpected heading rank `3`, expected rank `2`
+9:1-9:16: Unexpected heading rank `4`, expected rank `3`
+```
+
+##### `html.md`
+
+###### In
+
+```markdown
+# Mercury
+
+<b>Mercury</b> is the first planet from the Sun and the smallest
+in the Solar System.
+
+<h3>Internal structure</h3>
+
+<h2>Orbit, rotation, and longitude</h2>
+```
+
+###### Out
+
+```text
+6:1-6:28: Unexpected heading rank `3`, expected rank `2`
+```
+
+##### `mdx.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+# Mercury
+
+<b>Mercury</b> is the first planet from the Sun and the smallest
+in the Solar System.
+
+<h3>Internal structure</h3>
+
+<h2>Orbit, rotation, and longitude</h2>
+```
+
+###### Out
+
+```text
+6:1-6:28: Unexpected heading rank `3`, expected rank `2`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-heading-increment@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-heading-increment]: #unifieduseremarklintheadingincrement
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-heading-increment.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-heading-increment
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-heading-increment
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-heading-increment
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-mdx]: https://mdxjs.com/packages/remark-mdx/
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-heading-style_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-heading-style_readme.md
new file mode 100644
index 0000000..015840c
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-heading-style_readme.md
@@ -0,0 +1,358 @@
+<!--This file is generated-->
+
+# remark-lint-heading-style
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when headings violate a given style.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintHeadingStyle[, options])`](#unifieduseremarklintheadingstyle-options)
+ * [`Options`](#options)
+ * [`Style`](#style)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the style of headings.
+
+## When should I use this?
+
+You can use this package to check that the style of headings is consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | `'consistent'` |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `'atx'` |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-heading-style
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintHeadingStyle from 'https://esm.sh/remark-lint-heading-style@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintHeadingStyle from 'https://esm.sh/remark-lint-heading-style@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintHeadingStyle from 'remark-lint-heading-style'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintHeadingStyle)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-heading-style .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-heading-style",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] types
+[`Options`][api-options] and
+[`Style`][api-style].
+The default export is
+[`remarkLintHeadingStyle`][api-remark-lint-heading-style].
+
+### `unified().use(remarkLintHeadingStyle[, options])`
+
+Warn when headings violate a given style.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], default: `'consistent'`)
+ — preferred style or whether to detect the first style and warn for
+ further differences
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Type
+
+```ts
+type Options = Style | 'consistent'
+```
+
+### `Style`
+
+Style (TypeScript type).
+
+###### Type
+
+```ts
+type Style = 'atx' | 'atx-closed' | 'setext'
+```
+
+## Recommendation
+
+Setext headings are limited in that they can only construct headings with a
+rank of one and two.
+They do allow multiple lines of content where ATX only allows one line.
+The number of used markers in their underline does not matter,
+leading to either:
+
+* 1 marker (`Hello\n-`),
+ which is the bare minimum,
+ and for rank 2 headings looks suspiciously like an empty list item
+* using as many markers as the content (`Hello\n-----`),
+ which is hard to maintain and diff
+* an arbitrary number (`Hello\n---`), which for rank 2 headings looks
+ suspiciously like a thematic break
+
+Setext headings are also uncommon.
+Using a sequence of hashes at the end of ATX headings is even more uncommon.
+Due to this,
+it’s recommended to use ATX headings, without closing hashes.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] formats headings as ATX by default.
+The other styles can be configured with `setext: true` or `closeAtx: true`.
+
+## Examples
+
+##### `ok.md`
+
+When configured with `'atx'`.
+
+###### In
+
+```markdown
+# Mercury
+
+## Venus
+
+### Earth
+```
+
+###### Out
+
+No messages.
+
+##### `ok.md`
+
+When configured with `'atx-closed'`.
+
+###### In
+
+```markdown
+# Mercury ##
+
+## Venus ##
+
+### Earth ###
+```
+
+###### Out
+
+No messages.
+
+##### `ok.md`
+
+When configured with `'setext'`.
+
+###### In
+
+```markdown
+Mercury
+=======
+
+Venus
+-----
+
+### Earth
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+Mercury
+=======
+
+## Venus
+
+### Earth ###
+```
+
+###### Out
+
+```text
+4:1-4:9: Unexpected ATX heading, expected setext
+6:1-6:14: Unexpected ATX (closed) heading, expected setext
+```
+
+##### `not-ok.md`
+
+When configured with `'🌍'`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `options`, expected `'atx'`, `'atx-closed'`, `'setext'`, or `'consistent'`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-heading-style@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-options]: #options
+
+[api-remark-lint-heading-style]: #unifieduseremarklintheadingstyle-options
+
+[api-style]: #style
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-heading-style.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-heading-style
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-heading-style
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-heading-style
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-linebreak-style_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-linebreak-style_readme.md
new file mode 100644
index 0000000..ba4d25d
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-linebreak-style_readme.md
@@ -0,0 +1,340 @@
+<!--This file is generated-->
+
+# remark-lint-linebreak-style
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when line endings violate a given style.
+
+## Contents
+
+* [When should I use this?](#when-should-i-use-this)
+* [When should I use this?](#when-should-i-use-this-1)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintLinebreakStyle[, options])`](#unifieduseremarklintlinebreakstyle-options)
+ * [`Options`](#options)
+ * [`Style`](#style)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## When should I use this?
+
+This package checks the style of line endings.
+
+## When should I use this?
+
+You can use this package to check that the style of line endings is
+consistent.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-linebreak-style
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintLinebreakStyle from 'https://esm.sh/remark-lint-linebreak-style@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintLinebreakStyle from 'https://esm.sh/remark-lint-linebreak-style@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintLinebreakStyle from 'remark-lint-linebreak-style'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintLinebreakStyle)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-linebreak-style .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-linebreak-style",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] types
+[`Options`][api-options] and
+[`Style`][api-style].
+The default export is
+[`remarkLintLinebreakStyle`][api-remark-lint-linebreak-style].
+
+### `unified().use(remarkLintLinebreakStyle[, options])`
+
+Warn when line endings violate a given style.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], default: `'consistent'`)
+ — preferred style or whether to detect the first style and warn for
+ further differences
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Type
+
+```ts
+type Options = Style | 'consistent'
+```
+
+### `Style`
+
+Style (TypeScript type).
+
+###### Type
+
+```ts
+type Style = 'unix' | 'windows'
+```
+
+## Recommendation
+
+In Git projects, you can configure to automatically switch between line
+endings based on who checks the repo out.
+In other places, you may want to manually force that one or the other is
+used.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] always uses Unix line endings.
+
+## Examples
+
+##### `ok-consistent-as-windows.md`
+
+###### In
+
+```markdown
+Mercury␍␊and␍␊Venus.
+```
+
+###### Out
+
+No messages.
+
+##### `ok-consistent-as-unix.md`
+
+###### In
+
+```markdown
+Mercury␊and␊Venus.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok-unix.md`
+
+When configured with `'unix'`.
+
+###### In
+
+```markdown
+Mercury.␍␊
+```
+
+###### Out
+
+```text
+1:10: Unexpected windows (`\r\n`) line ending, expected unix (`\n`) line endings
+```
+
+##### `not-ok-windows.md`
+
+When configured with `'windows'`.
+
+###### In
+
+```markdown
+Mercury.␊
+```
+
+###### Out
+
+```text
+1:9: Unexpected unix (`\n`) line ending, expected windows (`\r\n`) line endings
+```
+
+##### `not-ok-options.md`
+
+When configured with `'🌍'`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `options`, expected `'unix'`, `'windows'`, or `'consistent'`
+```
+
+##### `many.md`
+
+When configured with `'windows'`.
+
+###### In
+
+```markdown
+Mercury.␊Venus.␊Earth.␊Mars.␊Jupiter.␊Saturn.␊Uranus.␊Neptune.␊
+```
+
+###### Out
+
+```text
+1:9: Unexpected unix (`\n`) line ending, expected windows (`\r\n`) line endings
+2:7: Unexpected unix (`\n`) line ending, expected windows (`\r\n`) line endings
+3:7: Unexpected unix (`\n`) line ending, expected windows (`\r\n`) line endings
+4:6: Unexpected unix (`\n`) line ending, expected windows (`\r\n`) line endings
+5:9: Unexpected unix (`\n`) line ending, expected windows (`\r\n`) line endings
+6:8: Unexpected large number of incorrect line endings, stopping
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-linebreak-style@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-options]: #options
+
+[api-remark-lint-linebreak-style]: #unifieduseremarklintlinebreakstyle-options
+
+[api-style]: #style
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-linebreak-style.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-linebreak-style
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-linebreak-style
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-linebreak-style
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-link-title-style_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-link-title-style_readme.md
new file mode 100644
index 0000000..128e444
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-link-title-style_readme.md
@@ -0,0 +1,433 @@
+<!--This file is generated-->
+
+# remark-lint-link-title-style
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when link title markers violate a given style.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintLinkTitleStyle[, options])`](#unifieduseremarklintlinktitlestyle-options)
+ * [`Options`](#options)
+ * [`Style`](#style)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the style of link (*and* image and definition) title
+markers.
+
+## When should I use this?
+
+You can use this package to check that the style of link title markers is
+consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | `'consistent'` |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `'"'` |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-link-title-style
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintLinkTitleStyle from 'https://esm.sh/remark-lint-link-title-style@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintLinkTitleStyle from 'https://esm.sh/remark-lint-link-title-style@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintLinkTitleStyle from 'remark-lint-link-title-style'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintLinkTitleStyle)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-link-title-style .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-link-title-style",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] types
+[`Options`][api-options] and
+[`Style`][api-style].
+The default export is
+[`remarkLintLinkTitleStyle`][api-remark-lint-link-title-style].
+
+### `unified().use(remarkLintLinkTitleStyle[, options])`
+
+Warn when link title markers violate a given style.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], default: `'consistent'`)
+ — preferred style or whether to detect the first style and warn for
+ further differences
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Type
+
+```ts
+type Options = Style | 'consistent'
+```
+
+### `Style`
+
+Style (TypeScript type).
+
+###### Type
+
+```ts
+type Style = '"' | '\'' | '()'
+```
+
+## Recommendation
+
+Before CommonMark, parens for titles were not supported in markdown.
+They should now work in most places.
+Parens do look a bit weird as they’re inside more parens:
+`[text](url (title))`.
+
+In HTML, attributes are commonly written with double quotes.
+Due to this, titles are almost exclusively wrapped in double quotes in
+markdown, so it’s recommended to configure this rule with `'"'`.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] formats titles with double
+quotes by default.
+Pass `quote: "'"` to use single quotes.
+There is no option to use parens.
+
+## Examples
+
+##### `ok-consistent.md`
+
+###### In
+
+```markdown
+[Mercury](https://example.com/mercury/),
+[Venus](https://example.com/venus/ "Go to Venus"), and
+.
+
+[Mars]: https://example.com/mars/ "Go to Mars"
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok-consistent.md`
+
+###### In
+
+```markdown
+[Mercury](https://example.com/mercury/ "Go to Mercury") and
+.
+
+[Earth]: https://example.com/earth/ (Go to Earth)
+```
+
+###### Out
+
+```text
+2:1-2:51: Unexpected title markers `'`, expected `"`
+4:1-4:50: Unexpected title markers `'('` and `')'`, expected `"`
+```
+
+##### `ok-double.md`
+
+When configured with `'"'`.
+
+###### In
+
+```markdown
+[Mercury](https://example.com/mercury/ "Go to Mercury").
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok-double.md`
+
+When configured with `'"'`.
+
+###### In
+
+```markdown
+[Mercury](https://example.com/mercury/ 'Go to Mercury').
+```
+
+###### Out
+
+```text
+1:1-1:56: Unexpected title markers `'`, expected `"`
+```
+
+##### `ok-single.md`
+
+When configured with `"'"`.
+
+###### In
+
+```markdown
+[Mercury](https://example.com/mercury/ 'Go to Mercury').
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok-single.md`
+
+When configured with `"'"`.
+
+###### In
+
+```markdown
+[Mercury](https://example.com/mercury/ "Go to Mercury").
+```
+
+###### Out
+
+```text
+1:1-1:56: Unexpected title markers `"`, expected `'`
+```
+
+##### `ok-paren.md`
+
+When configured with `'()'`.
+
+###### In
+
+```markdown
+[Mercury](https://example.com/mercury/ (Go to Mercury)).
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok-paren.md`
+
+When configured with `'()'`.
+
+###### In
+
+```markdown
+[Mercury](https://example.com/mercury/ "Go to Mercury").
+```
+
+###### Out
+
+```text
+1:1-1:56: Unexpected title markers `"`, expected `'('` and `')'`
+```
+
+##### `not-ok.md`
+
+When configured with `'🌍'`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `options`, expected `'"'`, `"'"`, `'()'`, or `'consistent'`
+```
+
+##### `ok-parens-in-url.md`
+
+When configured with `'"'`.
+
+###### In
+
+```markdown
+Parens in URLs work correctly:
+
+[Mercury](https://example.com/(mercury) "Go to Mercury") and
+[Venus](https://example.com/(venus)).
+```
+
+###### Out
+
+No messages.
+
+##### `ok-whitespace.md`
+
+When configured with `'"'`.
+
+###### In
+
+```markdown
+Trailing whitespace works correctly:
+
+[Mercury](https://example.com/mercury/␠"Go to Mercury"␠).
+```
+
+###### Out
+
+No messages.
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-link-title-style@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-options]: #options
+
+[api-remark-lint-link-title-style]: #unifieduseremarklintlinktitlestyle-options
+
+[api-style]: #style
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-link-title-style.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-link-title-style
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-link-title-style
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-link-title-style
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-list-item-bullet-indent_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-list-item-bullet-indent_readme.md
new file mode 100644
index 0000000..2303e00
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-list-item-bullet-indent_readme.md
@@ -0,0 +1,270 @@
+<!--This file is generated-->
+
+# remark-lint-list-item-bullet-indent
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when list item markers are indented.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintListItemBulletIndent)`](#unifieduseremarklintlistitembulletindent)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks indentation before list item markers.
+
+## When should I use this?
+
+You can use this package to check that the style of list items is
+consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-list-item-bullet-indent
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintListItemBulletIndent from 'https://esm.sh/remark-lint-list-item-bullet-indent@5'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintListItemBulletIndent from 'https://esm.sh/remark-lint-list-item-bullet-indent@5?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintListItemBulletIndent from 'remark-lint-list-item-bullet-indent'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintListItemBulletIndent)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-list-item-bullet-indent .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-list-item-bullet-indent",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintListItemBulletIndent`][api-remark-lint-list-item-bullet-indent].
+
+### `unified().use(remarkLintListItemBulletIndent)`
+
+Warn when list item markers are indented.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+There is no specific handling of indented list items in markdown.
+While it is possible to use an indent to align ordered lists on their marker:
+
+```markdown
+ 1. Mercury
+ 10. Venus
+100. Earth
+```
+
+…such a style is uncommon and hard to maintain as adding a 10th item
+means 9 other items have to change (more arduous while unlikely would be
+the 100th item).
+So it is recommended to not indent items and to turn this rule on.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] formats all items without
+indent.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+Mercury.
+
+* Venus.
+* Earth.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+Mercury.
+
+␠* Venus.
+␠* Earth.
+```
+
+###### Out
+
+```text
+3:2: Unexpected `1` space before list item, expected `0` spaces, remove them
+4:2: Unexpected `1` space before list item, expected `0` spaces, remove them
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-list-item-bullet-indent@5`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-list-item-bullet-indent]: #unifieduseremarklintlistitembulletindent
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-list-item-bullet-indent.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-list-item-bullet-indent
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-list-item-bullet-indent
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-list-item-bullet-indent
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-list-item-content-indent_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-list-item-content-indent_readme.md
new file mode 100644
index 0000000..83ec2d8
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-list-item-content-indent_readme.md
@@ -0,0 +1,327 @@
+<!--This file is generated-->
+
+# remark-lint-list-item-content-indent
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when the indent of list item content is not
+consistent.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintListItemContentIndent)`](#unifieduseremarklintlistitemcontentindent)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the indent of list item content.
+It checks the first thing in a list item and makes sure that all other
+children have the same indent.
+
+## When should I use this?
+
+You can use this package to check that list item content is indented
+consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-list-item-content-indent
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintListItemContentIndent from 'https://esm.sh/remark-lint-list-item-content-indent@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintListItemContentIndent from 'https://esm.sh/remark-lint-list-item-content-indent@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintListItemContentIndent from 'remark-lint-list-item-content-indent'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintListItemContentIndent)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-list-item-content-indent .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-list-item-content-indent",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintListItemContentIndent`][api-remark-lint-list-item-content-indent].
+
+### `unified().use(remarkLintListItemContentIndent)`
+
+Warn when the indent of list item content is not consistent.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+The position of the first child in a list item matters.
+Further children should align with it.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] aligns the content of items.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+1.␠Mercury.
+␠␠␠***
+␠␠␠* Venus.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+1.␠Mercury.
+␠␠␠␠␠***
+␠␠␠␠* Venus.
+```
+
+###### Out
+
+```text
+2:6: Unexpected unaligned list item child, expected to align with first child, remove `2` spaces
+3:5: Unexpected unaligned list item child, expected to align with first child, remove `1` space
+```
+
+##### `ok-more.md`
+
+###### In
+
+```markdown
+*␠␠␠Mercury.
+␠␠␠␠***
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok-more.md`
+
+###### In
+
+```markdown
+*␠␠␠Mercury.
+␠␠␠␠␠␠***
+```
+
+###### Out
+
+```text
+2:7: Unexpected unaligned list item child, expected to align with first child, remove `2` spaces
+```
+
+##### `gfm-nok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+1.␠[x] Mercury
+␠␠␠␠␠***
+␠␠␠␠* Venus
+```
+
+###### Out
+
+```text
+2:6: Unexpected unaligned list item child, expected to align with first child, remove `2` spaces
+3:5: Unexpected unaligned list item child, expected to align with first child, remove `1` space
+```
+
+##### `initial-blank.md`
+
+###### In
+
+```markdown
+*
+␠␠␠␠␠asd
+
+␠␠***
+```
+
+###### Out
+
+```text
+4:3: Unexpected unaligned list item child, expected to align with first child, add `3` spaces
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-list-item-content-indent@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-list-item-content-indent]: #unifieduseremarklintlistitemcontentindent
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-list-item-content-indent.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-list-item-content-indent
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-list-item-content-indent
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-list-item-content-indent
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-list-item-indent_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-list-item-indent_readme.md
new file mode 100644
index 0000000..7b46ab4
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-list-item-indent_readme.md
@@ -0,0 +1,585 @@
+<!--This file is generated-->
+
+# remark-lint-list-item-indent
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when the whitespace after list item markers violate
+a given style.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintListItemIndent[, options])`](#unifieduseremarklintlistitemindent-options)
+ * [`Options`](#options)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the style of whitespace after list item markers.
+
+## When should I use this?
+
+You can use this package to check that the style of whitespace after list
+item markers and before content is consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `'mixed'` |
+| [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | `'one'` |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-list-item-indent
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintListItemIndent from 'https://esm.sh/remark-lint-list-item-indent@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintListItemIndent from 'https://esm.sh/remark-lint-list-item-indent@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintListItemIndent from 'remark-lint-list-item-indent'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintListItemIndent)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-list-item-indent .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-list-item-indent",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] type
+[`Options`][api-options].
+The default export is
+[`remarkLintListItemIndent`][api-remark-lint-list-item-indent].
+
+### `unified().use(remarkLintListItemIndent[, options])`
+
+Warn when the whitespace after list item markers violate a given style.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], default: `'one'`)
+ — preferred style
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+* `'mixed'`
+ — prefer `'one'` for tight lists and `'tab'` for loose lists
+* `'one'`
+ — prefer the size of the bullet and a single space
+* `'tab'`
+ — prefer the size of the bullet and a single space to the next tab stop
+
+###### Type
+
+```ts
+type Options = 'mixed' | 'one' | 'tab'
+```
+
+## Recommendation
+
+First some background.
+The number of spaces that occur after list markers (`*`, `-`, and `+` for
+unordered lists and `.` and `)` for unordered lists) and before the content
+on the first line,
+defines how much indentation can be used for further lines.
+At least one space is required and up to 4 spaces are allowed.
+If there is no further content after the marker then it’s a blank line which
+is handled as if there was one space.
+If there are 5 or more spaces and then content then it’s also seen as one
+space and the rest is seen as indented code.
+
+Regardless of ordered and unordered,
+there are two kinds of lists in markdown,
+tight and loose.
+Lists are tight by default but if there is a blank line between two list
+items or between two blocks inside an item,
+that turns the whole list into a loose list.
+When turning markdown into HTML,
+paragraphs in tight lists are not wrapped in `<p>` tags.
+
+How indentation of lists works in markdown has historically been a mess,
+especially with how they interact with indented code.
+CommonMark made that a *lot* better,
+but there remain (documented but complex) edge cases and some behavior
+intuitive.
+Due to this, `'tab'` works the best in most markdown parsers *and* in
+CommonMark.
+Currently the situation between markdown parsers is better,
+so the default `'one'`,
+which seems to be the most common style used by authors,
+is okay.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] uses `listItemIndent: 'one'`
+by default.
+`listItemIndent: 'mixed'` or `listItemIndent: 'tab'` is also supported.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+*␠Mercury.
+*␠Venus.
+
+111.␠Earth
+␠␠␠␠␠and Mars.
+
+*␠**Jupiter**.
+
+␠␠Jupiter is the fifth planet from the Sun and the largest in the Solar
+␠␠System.
+
+*␠Saturn.
+
+␠␠Saturn is the sixth planet from the Sun and the second-largest in the Solar System, after Jupiter.
+```
+
+###### Out
+
+No messages.
+
+##### `ok.md`
+
+When configured with `'mixed'`.
+
+###### In
+
+```markdown
+*␠Mercury.
+*␠Venus.
+
+111.␠Earth
+␠␠␠␠␠and Mars.
+
+*␠␠␠**Jupiter**.
+
+␠␠␠␠Jupiter is the fifth planet from the Sun and the largest in the Solar
+␠␠␠␠System.
+
+*␠␠␠Saturn.
+
+␠␠␠␠Saturn is the sixth planet from the Sun and the second-largest in the Solar System, after Jupiter.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+When configured with `'mixed'`.
+
+###### In
+
+```markdown
+*␠␠␠Mercury.
+*␠␠␠Venus.
+
+111.␠␠␠␠Earth
+␠␠␠␠␠␠␠␠and Mars.
+
+*␠**Jupiter**.
+
+␠␠Jupiter is the fifth planet from the Sun and the largest in the Solar
+␠␠System.
+
+*␠Saturn.
+
+␠␠Saturn is the sixth planet from the Sun and the second-largest in the Solar System, after Jupiter.
+```
+
+###### Out
+
+```text
+1:5: Unexpected `3` spaces between list item marker and content in tight list, expected `1` space, remove `2` spaces
+2:5: Unexpected `3` spaces between list item marker and content in tight list, expected `1` space, remove `2` spaces
+4:9: Unexpected `4` spaces between list item marker and content in tight list, expected `1` space, remove `3` spaces
+7:3: Unexpected `1` space between list item marker and content in loose list, expected `3` spaces, add `2` spaces
+12:3: Unexpected `1` space between list item marker and content in loose list, expected `3` spaces, add `2` spaces
+```
+
+##### `ok.md`
+
+When configured with `'one'`.
+
+###### In
+
+```markdown
+*␠Mercury.
+*␠Venus.
+
+111.␠Earth
+␠␠␠␠␠and Mars.
+
+*␠**Jupiter**.
+
+␠␠Jupiter is the fifth planet from the Sun and the largest in the Solar
+␠␠System.
+
+*␠Saturn.
+
+␠␠Saturn is the sixth planet from the Sun and the second-largest in the Solar System, after Jupiter.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+When configured with `'one'`.
+
+###### In
+
+```markdown
+*␠␠␠Mercury.
+*␠␠␠Venus.
+
+111.␠␠␠␠Earth
+␠␠␠␠␠␠␠␠and Mars.
+
+*␠␠␠**Jupiter**.
+
+␠␠␠␠Jupiter is the fifth planet from the Sun and the largest in the Solar
+␠␠␠␠System.
+
+*␠␠␠Saturn.
+
+␠␠␠␠Saturn is the sixth planet from the Sun and the second-largest in the Solar System, after Jupiter.
+```
+
+###### Out
+
+```text
+1:5: Unexpected `3` spaces between list item marker and content, expected `1` space, remove `2` spaces
+2:5: Unexpected `3` spaces between list item marker and content, expected `1` space, remove `2` spaces
+4:9: Unexpected `4` spaces between list item marker and content, expected `1` space, remove `3` spaces
+7:5: Unexpected `3` spaces between list item marker and content, expected `1` space, remove `2` spaces
+12:5: Unexpected `3` spaces between list item marker and content, expected `1` space, remove `2` spaces
+```
+
+##### `ok.md`
+
+When configured with `'tab'`.
+
+###### In
+
+```markdown
+*␠␠␠Mercury.
+*␠␠␠Venus.
+
+111.␠␠␠␠Earth
+␠␠␠␠␠␠␠␠and Mars.
+
+*␠␠␠**Jupiter**.
+
+␠␠␠␠Jupiter is the fifth planet from the Sun and the largest in the Solar
+␠␠␠␠System.
+
+*␠␠␠Saturn.
+
+␠␠␠␠Saturn is the sixth planet from the Sun and the second-largest in the Solar System, after Jupiter.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+When configured with `'tab'`.
+
+###### In
+
+```markdown
+*␠Mercury.
+*␠Venus.
+
+111.␠Earth
+␠␠␠␠␠and Mars.
+
+*␠**Jupiter**.
+
+␠␠Jupiter is the fifth planet from the Sun and the largest in the Solar
+␠␠System.
+
+*␠Saturn.
+
+␠␠Saturn is the sixth planet from the Sun and the second-largest in the Solar System, after Jupiter.
+```
+
+###### Out
+
+```text
+1:3: Unexpected `1` space between list item marker and content, expected `3` spaces, add `2` spaces
+2:3: Unexpected `1` space between list item marker and content, expected `3` spaces, add `2` spaces
+4:6: Unexpected `1` space between list item marker and content, expected `4` spaces, add `3` spaces
+7:3: Unexpected `1` space between list item marker and content, expected `3` spaces, add `2` spaces
+12:3: Unexpected `1` space between list item marker and content, expected `3` spaces, add `2` spaces
+```
+
+##### `not-ok.md`
+
+When configured with `'🌍'`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `options`, expected `'mixed'`, `'one'`, or `'tab'`
+```
+
+##### `gfm.md`
+
+When configured with `'mixed'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+*␠[x] Mercury.
+
+1.␠␠[ ] Venus.
+
+2.␠␠[ ] Earth.
+```
+
+###### Out
+
+No messages.
+
+##### `gfm.md`
+
+When configured with `'one'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+*␠[x] Mercury.
+
+1.␠[ ] Venus.
+
+2.␠[ ] Earth.
+```
+
+###### Out
+
+No messages.
+
+##### `gfm.md`
+
+When configured with `'tab'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+*␠␠␠[x] Mercury.
+
+1.␠␠[ ] Venus.
+
+2.␠␠[ ] Earth.
+```
+
+###### Out
+
+No messages.
+
+##### `loose-tight.md`
+
+When configured with `'mixed'`.
+
+###### In
+
+```markdown
+Loose lists have blank lines between items:
+
+*␠␠␠Mercury.
+
+*␠␠␠Venus.
+
+…or between children of items:
+
+1.␠␠Earth.
+
+␠␠␠␠Earth is the third planet from the Sun and the only astronomical
+␠␠␠␠object known to harbor life.
+```
+
+###### Out
+
+No messages.
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-list-item-indent@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-options]: #options
+
+[api-remark-lint-list-item-indent]: #unifieduseremarklintlistitemindent-options
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-list-item-indent.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-list-item-indent
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-list-item-indent
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-list-item-indent
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-list-item-spacing_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-list-item-spacing_readme.md
new file mode 100644
index 0000000..f5b8e52
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-list-item-spacing_readme.md
@@ -0,0 +1,350 @@
+<!--This file is generated-->
+
+# remark-lint-list-item-spacing
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when lists violate a given style.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintListItemSpacing[, options])`](#unifieduseremarklintlistitemspacing-options)
+ * [`Options`](#options)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks blank lines between list items.
+
+## When should I use this?
+
+You can use this package to check the style of lists.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-list-item-spacing
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintListItemSpacing from 'https://esm.sh/remark-lint-list-item-spacing@5'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintListItemSpacing from 'https://esm.sh/remark-lint-list-item-spacing@5?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintListItemSpacing from 'remark-lint-list-item-spacing'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintListItemSpacing)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-list-item-spacing .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-list-item-spacing",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] type
+[`Options`][api-options].
+The default export is
+[`remarkLintListItemSpacing`][api-remark-lint-list-item-spacing].
+
+### `unified().use(remarkLintListItemSpacing[, options])`
+
+Warn when lists violate a given style.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], optional)
+ — configuration
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Fields
+
+* `checkBlanks` (`boolean`, default: `false`)
+ — expect blank lines between items based on whether an item has blank
+ lines *in* them;
+ the default is to expect blank lines based on whether items span multiple
+ lines
+
+## Recommendation
+
+First some background.
+Regardless of ordered and unordered,
+there are two kinds of lists in markdown,
+tight and loose.
+Lists are tight by default but if there is a blank line between two list
+items or between two blocks inside an item,
+that turns the whole list into a loose list.
+When turning markdown into HTML,
+paragraphs in tight lists are not wrapped in `<p>` tags.
+
+This rule defaults to the [`markdown-style-guide`][markdown-style-guide]
+preference for which lists should be loose or not:
+loose when at least one item spans more than one line and tight otherwise.
+With `{checkBlanks: true}`,
+this rule follows whether a list is loose or not according to Commonmark,
+and when one item is loose,
+all items must be loose.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+* Mercury.
+* Venus.
+
++ Mercury and
+ Venus.
+
++ Earth.
+```
+
+###### Out
+
+No messages.
+
+##### `ok-check-blanks.md`
+
+When configured with `{ checkBlanks: true }`.
+
+###### In
+
+```markdown
+* Mercury.
+* Venus.
+
++ Mercury
+
+ Mercury is the first planet from the Sun and the smallest in the Solar
+ System.
+
++ Earth.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+* Mercury.
+
+* Venus.
+
++ Mercury and
+ Venus.
++ Earth.
+
+* Mercury.
+
+ Mercury is the first planet from the Sun and the smallest in the Solar
+ System.
+* Earth.
+```
+
+###### Out
+
+```text
+1:11-3:1: Unexpected `1` blank line between list items, expected `0` blank lines, remove `1` blank line
+6:11-7:1: Unexpected `0` blank lines between list items, expected `1` blank line, add `1` blank line
+12:12-13:1: Unexpected `0` blank lines between list items, expected `1` blank line, add `1` blank line
+```
+
+##### `not-ok-blank.md`
+
+When configured with `{ checkBlanks: true }`.
+
+###### In
+
+```markdown
+* Mercury.
+
+* Venus.
+
++ Mercury and
+ Venus.
+
++ Earth.
+
+* Mercury.
+
+ Mercury is the first planet from the Sun and the smallest in the Solar
+ System.
+* Earth.
+```
+
+###### Out
+
+```text
+1:11-3:1: Unexpected `1` blank line between list items, expected `0` blank lines, remove `1` blank line
+6:11-8:1: Unexpected `1` blank line between list items, expected `0` blank lines, remove `1` blank line
+13:12-14:1: Unexpected `0` blank lines between list items, expected `1` blank line, add `1` blank line
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-list-item-spacing@5`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-options]: #options
+
+[api-remark-lint-list-item-spacing]: #unifieduseremarklintlistitemspacing-options
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-list-item-spacing.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-list-item-spacing
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-list-item-spacing
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-list-item-spacing
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[markdown-style-guide]: https://cirosantilli.com/markdown-style-guide/
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-maximum-heading-length_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-maximum-heading-length_readme.md
new file mode 100644
index 0000000..bec8654
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-maximum-heading-length_readme.md
@@ -0,0 +1,329 @@
+<!--This file is generated-->
+
+# remark-lint-maximum-heading-length
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when headings are too long.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintMaximumHeadingLength[, options])`](#unifieduseremarklintmaximumheadinglength-options)
+ * [`Options`](#options)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the length of heading text.
+
+## When should I use this?
+
+You can use this package to check that heading text is within reason.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-maximum-heading-length
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintMaximumHeadingLength from 'https://esm.sh/remark-lint-maximum-heading-length@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintMaximumHeadingLength from 'https://esm.sh/remark-lint-maximum-heading-length@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintMaximumHeadingLength from 'remark-lint-maximum-heading-length'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintMaximumHeadingLength)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-maximum-heading-length .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-maximum-heading-length",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] type
+[`Options`][api-options].
+The default export is
+[`remarkLintMaximumHeadingLength`][api-remark-lint-maximum-heading-length].
+
+### `unified().use(remarkLintMaximumHeadingLength[, options])`
+
+Warn when headings are too long.
+
+###### Parameters
+
+* `options` ([`Options`][api-options] or `number`, optional)
+ — configuration
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Properties
+
+* `size` (`number`, default: `60`)
+ — preferred max size
+* `stringLength` (`(value: string) => number`, optional)
+ — function to detect text size
+
+## Recommendation
+
+While this rule is sometimes annoying,
+reasonable size headings do help SEO purposes (bots prefer reasonable
+headings),
+visual users (headings are typically displayed quite large),
+and users of screen readers (who use “jump to heading” features that read
+every heading out loud to navigate within a page).
+
+To better represent how long headings “look”,
+you can pass a `stringLength` function.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+# Mercury is the first planet from the Sun
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+When configured with `30`.
+
+###### In
+
+```markdown
+# Mercury is the first planet from the Sun
+```
+
+###### Out
+
+```text
+1:1-1:43: Unexpected `40` characters in heading, expected at most `30` characters
+```
+
+##### `string-length-default.md`
+
+When configured with `30`.
+
+###### In
+
+```markdown
+# 水星是太陽系的八大行星中最小和最靠近太陽的行星
+```
+
+###### Out
+
+No messages.
+
+##### `string-length-custom.md`
+
+When configured with `{ size: 30, stringLength: [Function: stringWidth] }`.
+
+###### In
+
+```markdown
+# 水星是太陽系的八大行星中最小和最靠近太陽的行星
+```
+
+###### Out
+
+```text
+1:1-1:26: Unexpected `46` characters in heading, expected at most `30` characters
+```
+
+##### `mdx.mdx`
+
+When configured with `30`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+<h1>Mercury is the first planet from the Sun</h1>
+```
+
+###### Out
+
+```text
+1:1-1:50: Unexpected `40` characters in heading, expected at most `30` characters
+```
+
+##### `not-ok.md`
+
+When configured with `'🌍'`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `size`, expected `number`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-maximum-heading-length@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-options]: #options
+
+[api-remark-lint-maximum-heading-length]: #unifieduseremarklintmaximumheadinglength-options
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-maximum-heading-length.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-maximum-heading-length
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-maximum-heading-length
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-maximum-heading-length
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-mdx]: https://mdxjs.com/packages/remark-mdx/
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-maximum-line-length_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-maximum-line-length_readme.md
new file mode 100644
index 0000000..bf89b59
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-maximum-line-length_readme.md
@@ -0,0 +1,525 @@
+<!--This file is generated-->
+
+# remark-lint-maximum-line-length
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when lines are too long.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintMaximumLineLength[, options])`](#unifieduseremarklintmaximumlinelength-options)
+ * [`Options`](#options)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the length of lines.
+
+## When should I use this?
+
+You can use this package to check that lines are within reason.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `80` |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-maximum-line-length
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintMaximumLineLength from 'https://esm.sh/remark-lint-maximum-line-length@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintMaximumLineLength from 'https://esm.sh/remark-lint-maximum-line-length@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintMaximumLineLength from 'remark-lint-maximum-line-length'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintMaximumLineLength)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-maximum-line-length .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-maximum-line-length",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] type
+[`Options`][api-options].
+The default export is
+[`remarkLintMaximumLineLength`][api-remark-lint-maximum-line-length].
+
+### `unified().use(remarkLintMaximumLineLength[, options])`
+
+Warn when lines are too long.
+
+Nodes that cannot be wrapped are ignored,
+such as JSX, HTML, code (flow), definitions, headings, and tables.
+
+When code (phrasing), images, and links start before the wrap,
+end after the wrap,
+and contain no whitespace,
+they are also ignored.
+
+###### Parameters
+
+* `options` ([`Options`][api-options] or `number`, optional)
+ — configuration
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Properties
+
+* `size` (`number`, default: `60`)
+ — preferred max size
+* `stringLength` (`(value: string) => number`, optional)
+ — function to detect text size
+
+## Recommendation
+
+Whether to wrap prose or not is a stylistic choice.
+
+To better represent how long lines “look”,
+you can pass a `stringLength` function.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+Mercury mercury mercury mercury mercury mercury mercury mercury mercury mercury
+mercury.
+
+Mercury mercury mercury mercury mercury mercury mercury mercury mercury `mercury()`.
+
+Mercury mercury mercury mercury mercury mercury mercury mercury mercury <https://localhost>.
+
+Mercury mercury mercury mercury mercury mercury mercury mercury mercury [mercury](https://localhost).
+
+Mercury mercury mercury mercury mercury mercury mercury mercury mercury .
+
+<div>Mercury mercury mercury mercury mercury mercury mercury mercury mercury</div>
+
+[foo]: https://localhost/mercury/mercury/mercury/mercury/mercury/mercury/mercury/mercury
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+When configured with `20`.
+
+###### In
+
+```markdown
+Mercury mercury mercury
+mercury.
+
+Mercury mercury mercury `mercury()`.
+
+Mercury mercury mercury <https://localhost>.
+
+Mercury mercury mercury [m](example.com).
+
+Mercury mercury mercury .
+
+`mercury()` mercury mercury mercury.
+
+<https://localhost> mercury.
+
+[m](example.com) mercury.
+
+ mercury.
+
+Mercury mercury  mercury.
+```
+
+###### Out
+
+```text
+1:24: Unexpected `23` character line, expected at most `20` characters, remove `3` characters
+4:37: Unexpected `36` character line, expected at most `20` characters, remove `16` characters
+6:45: Unexpected `44` character line, expected at most `20` characters, remove `24` characters
+8:42: Unexpected `41` character line, expected at most `20` characters, remove `21` characters
+10:43: Unexpected `42` character line, expected at most `20` characters, remove `22` characters
+12:37: Unexpected `36` character line, expected at most `20` characters, remove `16` characters
+14:29: Unexpected `28` character line, expected at most `20` characters, remove `8` characters
+16:26: Unexpected `25` character line, expected at most `20` characters, remove `5` characters
+18:27: Unexpected `26` character line, expected at most `20` characters, remove `6` characters
+20:43: Unexpected `42` character line, expected at most `20` characters, remove `22` characters
+```
+
+##### `string-length-default.md`
+
+When configured with `40`.
+
+###### In
+
+```markdown
+水星是太陽系的八大行星中最小和最靠近太陽的行星。
+```
+
+###### Out
+
+No messages.
+
+##### `string-length-custom.md`
+
+When configured with `{ size: 40, stringLength: [Function: stringWidth] }`.
+
+###### In
+
+```markdown
+水星是太陽系的八大行星中最小和最靠近太陽的行星。
+```
+
+###### Out
+
+```text
+1:25: Unexpected `48` character line, expected at most `40` characters, remove `8` characters
+```
+
+##### `long-autolinks-ok.md`
+
+When configured with `20`.
+
+###### In
+
+```markdown
+<https://localhost/mercury/>
+
+<https://localhost/mercury/>
+mercury.
+
+Mercury
+<https://localhost/mercury/>.
+
+Mercury
+<https://localhost/mercury/>
+mercury.
+
+Mercury
+<https://localhost/mercury/>
+mercury mercury.
+
+Mercury mercury
+<https://localhost/mercury/>
+mercury mercury.
+```
+
+###### Out
+
+No messages.
+
+##### `long-autolinks-nok.md`
+
+When configured with `20`.
+
+###### In
+
+```markdown
+<https://localhost/mercury/> mercury.
+
+Mercury <https://localhost/mercury/>.
+
+Mercury
+<https://localhost/mercury/> mercury.
+
+Mercury <https://localhost/mercury/>
+mercury.
+```
+
+###### Out
+
+```text
+1:38: Unexpected `37` character line, expected at most `20` characters, remove `17` characters
+6:38: Unexpected `37` character line, expected at most `20` characters, remove `17` characters
+```
+
+##### `ok.md`
+
+When configured with `20`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> frontmatter ([`remark-frontmatter`][github-remark-frontmatter]).
+
+```markdown
+---
+description: Mercury mercury mercury mercury.
+---
+```
+
+###### Out
+
+No messages.
+
+##### `ok.md`
+
+When configured with `20`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+| Mercury | Mercury | Mercury |
+| ------- | ------- | ------- |
+```
+
+###### Out
+
+No messages.
+
+##### `ok.md`
+
+When configured with `20`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> math ([`remark-math`][github-remark-math]).
+
+```markdown
+$$
+L = \frac{1}{2} \rho v^2 S C_L
+$$
+```
+
+###### Out
+
+No messages.
+
+##### `ok.md`
+
+When configured with `20`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+export const description = 'Mercury mercury mercury mercury.'
+
+{description}
+```
+
+###### Out
+
+No messages.
+
+##### `ok-mixed-line-endings.md`
+
+When configured with `10`.
+
+###### In
+
+```markdown
+0123456789␍␊0123456789␊01234␍␊01234␊
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok-mixed-line-endings.md`
+
+When configured with `10`.
+
+###### In
+
+```markdown
+012345678901␍␊012345678901␊01234567890␍␊01234567890␊
+```
+
+###### Out
+
+```text
+1:13: Unexpected `12` character line, expected at most `10` characters, remove `2` characters
+2:13: Unexpected `12` character line, expected at most `10` characters, remove `2` characters
+3:12: Unexpected `11` character line, expected at most `10` characters, remove `1` character
+4:12: Unexpected `11` character line, expected at most `10` characters, remove `1` character
+```
+
+##### `not-ok.md`
+
+When configured with `'🌍'`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `size`, expected `number`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-maximum-line-length@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-options]: #options
+
+[api-remark-lint-maximum-line-length]: #unifieduseremarklintmaximumlinelength-options
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-maximum-line-length.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-maximum-line-length
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-maximum-line-length
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-maximum-line-length
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-math]: https://github.com/remarkjs/remark-math
+
+[github-remark-mdx]: https://mdxjs.com/packages/remark-mdx/
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-mdx-jsx-attribute-sort_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-mdx-jsx-attribute-sort_readme.md
new file mode 100644
index 0000000..085c4a1
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-mdx-jsx-attribute-sort_readme.md
@@ -0,0 +1,280 @@
+<!--This file is generated-->
+
+# remark-lint-mdx-jsx-attribute-sort
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when attributes are not sorted.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintMdxJsxAttributeSort)`](#unifieduseremarklintmdxjsxattributesort)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks MDX JSX attribute order.
+
+## When should I use this?
+
+You can use this package to check MDX JSX attribute order.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-mdx-jsx-attribute-sort
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintMdxJsxAttributeSort from 'https://esm.sh/remark-lint-mdx-jsx-attribute-sort@1'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintMdxJsxAttributeSort from 'https://esm.sh/remark-lint-mdx-jsx-attribute-sort@1?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintMdxJsxAttributeSort from 'remark-lint-mdx-jsx-attribute-sort'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintMdxJsxAttributeSort)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-mdx-jsx-attribute-sort .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-mdx-jsx-attribute-sort",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintMdxJsxAttributeSort`][api-remark-lint-mdx-jsx-attribute-sort].
+
+### `unified().use(remarkLintMdxJsxAttributeSort)`
+
+Warn when attributes are not sorted.
+
+This package does not differentiate between what values attributes have,
+or whether they are shorthand or not.
+
+Spreads must come first.
+
+###### Parameters
+
+There are no parameters.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Examples
+
+##### `ok.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+<Saturn
+ aphelion={1514.50}
+ largest={false}
+ perihelion={1352.55}
+ satellites={146}
+/>
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+<Saturn
+ largest={false}
+ perihelion={1352.55}
+ satellites={146}
+ aphelion={1514.50}
+/>
+```
+
+###### Out
+
+```text
+2:3-2:18: Unexpected attribute `largest` in 1st place, expected alphabetically sorted attributes, move it to 2nd place
+3:3-3:23: Unexpected attribute `perihelion` in 2nd place, expected alphabetically sorted attributes, move it to 3rd place
+4:3-4:19: Unexpected attribute `satellites` in 3rd place, expected alphabetically sorted attributes, move it to 4th place
+5:3-5:21: Unexpected attribute `aphelion` in 4th place, expected alphabetically sorted attributes, move it to 1st place
+```
+
+##### `spread.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+<Earth
+ {...animals}
+ symbol="🜨"
+ {...humans}
+/>
+```
+
+###### Out
+
+```text
+4:3-4:14: Unexpected spread attribute after named attribute, expected spread attributes to come first
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-mdx-jsx-attribute-sort@1`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-mdx-jsx-attribute-sort]: #unifieduseremarklintmdxjsxattributesort
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-mdx-jsx-attribute-sort.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-mdx-jsx-attribute-sort
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-mdx-jsx-attribute-sort
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-mdx-jsx-attribute-sort
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-mdx]: https://mdxjs.com/packages/remark-mdx/
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-mdx-jsx-no-void-children_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-mdx-jsx-no-void-children_readme.md
new file mode 100644
index 0000000..555353e
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-mdx-jsx-no-void-children_readme.md
@@ -0,0 +1,261 @@
+<!--This file is generated-->
+
+# remark-lint-mdx-jsx-no-void-children
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when void HTML elements (such as `<br>`)
+are seen with children.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintMdxJsxNoVoidChildren[, options])`](#unifieduseremarklintmdxjsxnovoidchildren-options)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks that HTML void elements are without children.
+
+## When should I use this?
+
+You can use this package to check that HTML void elements are
+without children.
+
+This package assumes semantics from HTML.
+If you use MDX in a place without HTML you should not use this.
+
+This package also checks `children` and `dangerouslySetInnerHTML` as it
+assumes the semantics that React applies to these names.
+If how you use JSX conflicts with the React semantics this package may not
+work for you.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-mdx-jsx-no-void-children
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintMdxJsxNoVoidChildren from 'https://esm.sh/remark-lint-mdx-jsx-no-void-children@1'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintMdxJsxNoVoidChildren from 'https://esm.sh/remark-lint-mdx-jsx-no-void-children@1?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintMdxJsxNoVoidChildren from 'remark-lint-mdx-jsx-no-void-children'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintMdxJsxNoVoidChildren)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-mdx-jsx-no-void-children .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-mdx-jsx-no-void-children",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintMdxJsxNoVoidChildren`][api-remark-lint-mdx-jsx-no-void-children].
+
+### `unified().use(remarkLintMdxJsxNoVoidChildren[, options])`
+
+Warn when void HTML elements (such as `<br>`) are seen with children.
+
+###### Parameters
+
+There are no parameters.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Examples
+
+##### `ok.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+<b>Mercury</b> is the first planet from the Sun<br />
+and the smallest in the Solar System.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+**Mercury** is the first planet from<br>the</br>
+Sun and the smallest in the Solar System.
+
+<hr children={'***'} />
+
+**Venus** is the second planet
+from <br dangerouslySetInnerHTML={{__html: 'the'}} />
+Sun.
+```
+
+###### Out
+
+```text
+1:41-1:44: Unexpected children in known HTML void element, expected nothing
+4:5-4:21: Unexpected children in known HTML void element, expected nothing
+7:10-7:51: Unexpected children in known HTML void element, expected nothing
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-mdx-jsx-no-void-children@1`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-mdx-jsx-no-void-children]: #unifieduseremarklintmdxjsxnovoidchildren-options
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-mdx-jsx-no-void-children.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-mdx-jsx-no-void-children
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-mdx-jsx-no-void-children
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-mdx-jsx-no-void-children
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-mdx]: https://mdxjs.com/packages/remark-mdx/
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-mdx-jsx-quote-style_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-mdx-jsx-quote-style_readme.md
new file mode 100644
index 0000000..e460896
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-mdx-jsx-quote-style_readme.md
@@ -0,0 +1,374 @@
+<!--This file is generated-->
+
+# remark-lint-mdx-jsx-quote-style
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when MDX JSX attribute value
+markers violate a given style.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintMdxJsxQuoteStyle[, options])`](#unifieduseremarklintmdxjsxquotestyle-options)
+ * [`Options`](#options)
+ * [`Style`](#style)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the style of MDX JSX attribute value markers.
+
+## When should I use this?
+
+You can use this package to check that the style of MDX JSX attribute value
+markers is consistent.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-mdx-jsx-quote-style
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintMdxJsxQuoteStyle from 'https://esm.sh/remark-lint-mdx-jsx-quote-style@1'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintMdxJsxQuoteStyle from 'https://esm.sh/remark-lint-mdx-jsx-quote-style@1?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintMdxJsxQuoteStyle from 'remark-lint-mdx-jsx-quote-style'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintMdxJsxQuoteStyle)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-mdx-jsx-quote-style .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-mdx-jsx-quote-style",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] types
+[`Options`][api-options] and
+[`Style`][api-style].
+The default export is
+[`remarkLintMdxJsxQuoteStyle`][api-remark-lint-mdx-jsx-quote-style].
+
+### `unified().use(remarkLintMdxJsxQuoteStyle[, options])`
+
+Warn when MDX JSX attribute value markers violate a given style.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], default: `'consistent'`)
+ — preferred style or whether to detect the first style and warn for
+ further differences
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Type
+
+```ts
+type Options = Style | 'consistent'
+```
+
+### `Style`
+
+Style (TypeScript type).
+
+###### Type
+
+```ts
+type Style = '"' | '\''
+```
+
+## Recommendation
+
+In HTML,
+attributes are commonly written with double quotes.
+It’s recommended to go with that.
+To configure this rule with `'"'`.
+
+## Fix
+
+[`remark-mdx`][github-remark-mdx] formats titles with double
+quotes by default.
+Pass `quote: "'"` to use single quotes.
+
+## Examples
+
+##### `ok-consistent.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+<a href="https://example.com/venus/">Venus</a> and
+<a href="https://example.com/earth/">Earth</a>.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok-consistent.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+<a href="https://example.com/venus/">Venus</a> and
+<a href='https://example.com/earth/'>Earth</a>.
+```
+
+###### Out
+
+```text
+2:4-2:37: Unexpected JSX quote markers `'`, expected `"`
+```
+
+##### `double-quote.mdx`
+
+When configured with `'"'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+<a href="https://example.com/venus/">Venus</a> and
+<a href='https://example.com/earth/'>Earth</a>.
+```
+
+###### Out
+
+```text
+2:4-2:37: Unexpected JSX quote markers `'`, expected `"`
+```
+
+##### `single-quote.mdx`
+
+When configured with `"'"`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+<a href="https://example.com/venus/">Venus</a> and
+<a href='https://example.com/earth/'>Earth</a>.
+```
+
+###### Out
+
+```text
+1:4-1:37: Unexpected JSX quote markers `"`, expected `'`
+```
+
+##### `other-attributes.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+<Mercury closest />,
+<Venus aphelion={0.728213} />, and
+<Earth {...people} />.
+```
+
+###### Out
+
+No messages.
+
+##### `whitespace.mdx`
+
+When configured with `'"'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+<Mars symbol = "♂" />.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.mdx`
+
+When configured with `'🌍'`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `options`, expected `'"'`, `"'"`, or `'consistent'`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-mdx-jsx-quote-style@1`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-options]: #options
+
+[api-remark-lint-mdx-jsx-quote-style]: #unifieduseremarklintmdxjsxquotestyle-options
+
+[api-style]: #style
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-mdx-jsx-quote-style.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-mdx-jsx-quote-style
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-mdx-jsx-quote-style
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-mdx-jsx-quote-style
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-mdx]: https://mdxjs.com/packages/remark-mdx/
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-mdx-jsx-self-close_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-mdx-jsx-self-close_readme.md
new file mode 100644
index 0000000..919a664
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-mdx-jsx-self-close_readme.md
@@ -0,0 +1,261 @@
+<!--This file is generated-->
+
+# remark-lint-mdx-jsx-self-close
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when closing tags are used without
+children.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintMdxJsxSelfClose)`](#unifieduseremarklintmdxjsxselfclose)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks that self-closing MDX JSX tags are used
+when possible.
+
+## When should I use this?
+
+You can use this package to check that self-closing MDX JSX
+tags are used when possible.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-mdx-jsx-self-close
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintMdxJsxSelfClose from 'https://esm.sh/remark-lint-mdx-jsx-self-close@1'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintMdxJsxSelfClose from 'https://esm.sh/remark-lint-mdx-jsx-self-close@1?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintMdxJsxSelfClose from 'remark-lint-mdx-jsx-self-close'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintMdxJsxSelfClose)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-mdx-jsx-self-close .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-mdx-jsx-self-close",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintMdxJsxSelfClose`][api-remark-lint-mdx-jsx-self-close].
+
+### `unified().use(remarkLintMdxJsxSelfClose)`
+
+Warn when closing tags are used without children.
+
+###### Parameters
+
+There are no parameters.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Examples
+
+##### `ok.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+<strong>Venus</strong> and
+<strong children={'Earth'} />.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+<a href="https://example.com/venus/"></a>.
+```
+
+###### Out
+
+```text
+1:1-1:42: Unexpected closing tag on empty element, expected self-closing opening tag
+```
+
+##### `whitespace.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+Whitespace in tags <Icon / > and whitespace
+in elements <code> </code>.
+```
+
+###### Out
+
+No messages.
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-mdx-jsx-self-close@1`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-mdx-jsx-self-close]: #unifieduseremarklintmdxjsxselfclose
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-mdx-jsx-self-close.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-mdx-jsx-self-close
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-mdx-jsx-self-close
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-mdx-jsx-self-close
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-mdx]: https://mdxjs.com/packages/remark-mdx/
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-mdx-jsx-shorthand-attribute_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-mdx-jsx-shorthand-attribute_readme.md
new file mode 100644
index 0000000..418bcdd
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-mdx-jsx-shorthand-attribute_readme.md
@@ -0,0 +1,249 @@
+<!--This file is generated-->
+
+# remark-lint-mdx-jsx-shorthand-attribute
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when verbose attribute values are used.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintMdxJsxShorthandAttribute)`](#unifieduseremarklintmdxjsxshorthandattribute)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks that shorthand attributes are used when
+possible in MDX JSX.
+
+## When should I use this?
+
+You can use this package to check that shorthand attributes are used
+when possible in MDX JSX.
+
+This package does assume JavaScript:
+that `planet` and `planet={true}` are equal.
+JavaScript is almost always what is used with MDX.
+But if you use other programming languages embedded in MDX
+this package should not be used.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-mdx-jsx-shorthand-attribute
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintMdxJsxShorthandAttribute from 'https://esm.sh/remark-lint-mdx-jsx-shorthand-attribute@1'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintMdxJsxShorthandAttribute from 'https://esm.sh/remark-lint-mdx-jsx-shorthand-attribute@1?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintMdxJsxShorthandAttribute from 'remark-lint-mdx-jsx-shorthand-attribute'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintMdxJsxShorthandAttribute)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-mdx-jsx-shorthand-attribute .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-mdx-jsx-shorthand-attribute",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintMdxJsxShorthandAttribute`][api-remark-lint-mdx-jsx-shorthand-attribute].
+
+### `unified().use(remarkLintMdxJsxShorthandAttribute)`
+
+Warn when verbose attribute values are used.
+
+###### Parameters
+
+There are no parameters.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Examples
+
+##### `ok.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+<Jupiter largest />
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+<Jupiter largest={true} />
+```
+
+###### Out
+
+```text
+1:10-1:24: Unexpected verbose attribute value, expected shorthand boolean attribute
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-mdx-jsx-shorthand-attribute@1`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-mdx-jsx-shorthand-attribute]: #unifieduseremarklintmdxjsxshorthandattribute
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-mdx-jsx-shorthand-attribute.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-mdx-jsx-shorthand-attribute
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-mdx-jsx-shorthand-attribute
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-mdx-jsx-shorthand-attribute
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-mdx]: https://mdxjs.com/packages/remark-mdx/
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-mdx-jsx-unique-attribute-name_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-mdx-jsx-unique-attribute-name_readme.md
new file mode 100644
index 0000000..7b737a6
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-mdx-jsx-unique-attribute-name_readme.md
@@ -0,0 +1,260 @@
+<!--This file is generated-->
+
+# remark-lint-mdx-jsx-unique-attribute-name
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when MDX JSX attribute names
+are reused.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintMdxJsxUniqueAttributeName)`](#unifieduseremarklintmdxjsxuniqueattributename)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks that MDX JSX attribute names are unique.
+
+## When should I use this?
+
+You can use this package to check that MDX JSX attribute names
+are unique.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-mdx-jsx-unique-attribute-name
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintMdxJsxUniqueAttributeName from 'https://esm.sh/remark-lint-mdx-jsx-unique-attribute-name@1'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintMdxJsxUniqueAttributeName from 'https://esm.sh/remark-lint-mdx-jsx-unique-attribute-name@1?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintMdxJsxUniqueAttributeName from 'remark-lint-mdx-jsx-unique-attribute-name'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintMdxJsxUniqueAttributeName)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-mdx-jsx-unique-attribute-name .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-mdx-jsx-unique-attribute-name",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintMdxJsxUniqueAttributeName`][api-remark-lint-mdx-jsx-unique-attribute-name].
+
+### `unified().use(remarkLintMdxJsxUniqueAttributeName)`
+
+Warn when MDX JSX attribute names are reused.
+
+###### Parameters
+
+There are no parameters.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Examples
+
+##### `ok.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+<Component id="mercury" value="Mercury" />
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+<Component id="mercury" id="venus" value="Planet" />
+```
+
+###### Out
+
+```text
+1:25-1:35: Unexpected attribute name with equal text, expected unique attribute names
+```
+
+##### `other-attributes.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+<Mercury closest />,
+<Venus aphelion={0.728213} />, and
+<Earth {...people} />.
+```
+
+###### Out
+
+No messages.
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-mdx-jsx-unique-attribute-name@1`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-mdx-jsx-unique-attribute-name]: #unifieduseremarklintmdxjsxuniqueattributename
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-mdx-jsx-unique-attribute-name.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-mdx-jsx-unique-attribute-name
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-mdx-jsx-unique-attribute-name
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-mdx-jsx-unique-attribute-name
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-mdx]: https://mdxjs.com/packages/remark-mdx/
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-media-style_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-media-style_readme.md
new file mode 100644
index 0000000..0d8b96e
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-media-style_readme.md
@@ -0,0 +1,395 @@
+<!--This file is generated-->
+
+# remark-lint-media-style
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when the style of specifying
+the URL of images and links is incorrect.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintMediaStyle[, options])`](#unifieduseremarklintmediastyle-options)
+ * [`Options`](#options)
+ * [`Style`](#style)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks for media (image and link) style:
+whether references or resources are used.
+
+## When should I use this?
+
+You can use this package to check that the style of specifying the URL
+of images and links is correct.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-media-style
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintMediaStyle from 'https://esm.sh/remark-lint-media-style@1'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintMediaStyle from 'https://esm.sh/remark-lint-media-style@1?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintMediaStyle from 'remark-lint-media-style'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintMediaStyle)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-media-style .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-media-style",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] types
+[`Options`][api-options] and
+[`Style`][api-style].
+The default export is
+[`remarkLintMediaStyle`][api-remark-lint-media-style].
+
+### `unified().use(remarkLintMediaStyle[, options])`
+
+Warn when the style of specifying the URL of images and links is
+incorrect.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], default: `'consistent'`)
+ — preferred style or whether to detect the first style and warn for
+ further differences
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+* `'consistent'`
+ — detect the first used style and warn when further rules differ;
+ “reference-reuse” cannot be detected
+* [`Style`][api-style]
+ — style to prefer
+
+### `Style`
+
+Style (TypeScript type).
+
+* `'reference'`
+ — prefer references
+* `'reference-reuse'`
+ — allow resources when used once,
+ prefer references otherwise
+* `'resource'`
+ — prefer resources
+
+## Examples
+
+##### `ok-consistent-reference.md`
+
+###### In
+
+```markdown
+[Mercury][] and [Venus][].
+
+[mercury]: https://example.com/mercury/
+[venus]: https://example.com/venus/
+```
+
+###### Out
+
+No messages.
+
+##### `ok-consistent-resource.md`
+
+###### In
+
+```markdown
+[Mercury](https://example.com/mercury/) and
+[Venus](https://example.com/venus/).
+```
+
+###### Out
+
+No messages.
+
+##### `ok-reference-reuse.md`
+
+When configured with `'reference-reuse'`.
+
+###### In
+
+```markdown
+[Mercury](https://example.com/mercury/),
+[Venus][], and [Earth][].
+
+**[Venus][]** is the second planet from the Sun.
+
+[venus]: https://example.com/venus/
+[earth]: https://example.com/earth/
+```
+
+###### Out
+
+No messages.
+
+##### `nok-reference.md`
+
+When configured with `'reference'`.
+
+###### In
+
+```markdown
+[Mercury](https://example.com/mercury/),
+[Venus](https://example.com/venus/), and
+[Earth][].
+
+[earth]: https://example.com/earth/
+```
+
+###### Out
+
+```text
+1:1-1:40: Unexpected resource for url `https://example.com/mercury/`, expected a definition and a reference to it
+2:1-2:36: Unexpected resource for url `https://example.com/venus/`, expected a definition and a reference to it
+```
+
+##### `nok-resource.md`
+
+When configured with `'resource'`.
+
+###### In
+
+```markdown
+[Mercury](https://example.com/mercury/),
+[Venus](https://example.com/venus/), and
+[Earth][].
+
+[earth]: https://example.com/earth/
+```
+
+###### Out
+
+```text
+3:1-3:10: Unexpected reference for url `https://example.com/earth/`, expected resource
+```
+
+##### `nok-reference-reuse.md`
+
+When configured with `'reference-reuse'`.
+
+###### In
+
+```markdown
+[Mercury](https://example.com/mercury/),
+[Venus](https://example.com/venus/), and [Earth][].
+
+**[Venus](https://example.com/venus/)** is the second planet from the Sun.
+
+[earth]: https://example.com/earth/
+```
+
+###### Out
+
+```text
+2:1-2:36: Unexpected resource for reused url `https://example.com/venus/`, expected a definition and a reference to it
+4:3-4:38: Unexpected resource for reused url `https://example.com/venus/`, expected a definition and a reference to it
+```
+
+##### `reference-reuse-defined.md`
+
+When configured with `'reference-reuse'`.
+
+###### In
+
+```markdown
+[Mercury](https://example.com/mercury/).
+
+[mercury]: https://example.com/mercury/
+```
+
+###### Out
+
+```text
+1:1-1:40: Unexpected resource for reused url `https://example.com/mercury/`, expected a reference to `mercury`
+```
+
+##### `not-ok.md`
+
+When configured with `'🌍'`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `options`, expected `'reference-reuse'`, `'reference'`, `'resource'`, or `'consistent'`
+```
+
+##### `definitions.md`
+
+###### In
+
+```markdown
+[mercury]: https://example.com/mercury/
+[venus]: https://example.com/venus/
+```
+
+###### Out
+
+No messages.
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-media-style@1`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-options]: #options
+
+[api-remark-lint-media-style]: #unifieduseremarklintmediastyle-options
+
+[api-style]: #style
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-media-style.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-media-style
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-media-style
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-media-style
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-blockquote-without-marker_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-blockquote-without-marker_readme.md
new file mode 100644
index 0000000..8a5d53e
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-blockquote-without-marker_readme.md
@@ -0,0 +1,323 @@
+<!--This file is generated-->
+
+# remark-lint-no-blockquote-without-marker
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn for lazy lines in block quotes.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoBlockquoteWithoutMarker)`](#unifieduseremarklintnoblockquotewithoutmarker)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the style of block quotes.
+
+## When should I use this?
+
+You can use this package to check that the style of block quotes is
+consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+| [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-blockquote-without-marker
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoBlockquoteWithoutMarker from 'https://esm.sh/remark-lint-no-blockquote-without-marker@6'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoBlockquoteWithoutMarker from 'https://esm.sh/remark-lint-no-blockquote-without-marker@6?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoBlockquoteWithoutMarker from 'remark-lint-no-blockquote-without-marker'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoBlockquoteWithoutMarker)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-blockquote-without-marker .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-blockquote-without-marker",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoBlockquoteWithoutMarker`][api-remark-lint-no-blockquote-without-marker].
+
+### `unified().use(remarkLintNoBlockquoteWithoutMarker)`
+
+Warn for lazy lines in block quotes.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+Rules around lazy lines are not straightforward and visually confusing,
+so it’s recommended to start each line with a `>`.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] adds `>` markers to every line
+in a block quote.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+> Mercury,
+> Venus,
+> and Earth.
+
+Mars.
+```
+
+###### Out
+
+No messages.
+
+##### `ok-tabs.md`
+
+###### In
+
+```markdown
+>␉Mercury,
+>␉Venus,
+>␉and Earth.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+> Mercury,
+Venus,
+> and Earth.
+```
+
+###### Out
+
+```text
+2:1: Unexpected `0` block quote markers before paragraph line, expected `1` marker, add `1` marker
+```
+
+##### `not-ok-tabs.md`
+
+###### In
+
+```markdown
+>␉Mercury,
+␉Venus,
+and Earth.
+```
+
+###### Out
+
+```text
+2:2: Unexpected `0` block quote markers before paragraph line, expected `1` marker, add `1` marker
+3:1: Unexpected `0` block quote markers before paragraph line, expected `1` marker, add `1` marker
+```
+
+##### `containers.md`
+
+###### In
+
+```markdown
+* > Mercury and
+Venus.
+
+> * Mercury and
+ Venus.
+
+* > * Mercury and
+ Venus.
+
+> * > Mercury and
+ Venus.
+
+***
+
+> * > Mercury and
+> Venus.
+```
+
+###### Out
+
+```text
+2:1: Unexpected `0` block quote markers before paragraph line, expected `1` marker, add `1` marker
+5:3: Unexpected `0` block quote markers before paragraph line, expected `1` marker, add `1` marker
+8:5: Unexpected `0` block quote markers before paragraph line, expected `1` marker, add `1` marker
+11:7: Unexpected `0` block quote markers before paragraph line, expected `2` markers, add `2` markers
+16:7: Unexpected `1` block quote marker before paragraph line, expected `2` markers, add `1` marker
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-blockquote-without-marker@6`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-blockquote-without-marker]: #unifieduseremarklintnoblockquotewithoutmarker
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-blockquote-without-marker.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-blockquote-without-marker
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-blockquote-without-marker
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-blockquote-without-marker
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-consecutive-blank-lines_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-consecutive-blank-lines_readme.md
new file mode 100644
index 0000000..536b4d8
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-consecutive-blank-lines_readme.md
@@ -0,0 +1,498 @@
+<!--This file is generated-->
+
+# remark-lint-no-consecutive-blank-lines
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when multiple blank lines are used.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoConsecutiveBlankLines)`](#unifieduseremarklintnoconsecutiveblanklines)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the number of blank lines.
+
+## When should I use this?
+
+You can use this package to check that there are no unneeded blank lines.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-consecutive-blank-lines
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoConsecutiveBlankLines from 'https://esm.sh/remark-lint-no-consecutive-blank-lines@5'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoConsecutiveBlankLines from 'https://esm.sh/remark-lint-no-consecutive-blank-lines@5?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoConsecutiveBlankLines from 'remark-lint-no-consecutive-blank-lines'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoConsecutiveBlankLines)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-consecutive-blank-lines .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-consecutive-blank-lines",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoConsecutiveBlankLines`][api-remark-lint-no-consecutive-blank-lines].
+
+### `unified().use(remarkLintNoConsecutiveBlankLines)`
+
+Warn when multiple blank lines are used.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+More than one blank line has no effect between blocks.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] adds exactly one blank line
+between any block.
+It has a `join` option to configure more complex cases.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+# Planets
+
+Mercury.
+
+Venus.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+# Planets
+
+
+Mercury.
+
+
+
+Venus.
+```
+
+###### Out
+
+```text
+4:1: Unexpected `2` blank lines before node, expected up to `1` blank line, remove `1` blank line
+8:1: Unexpected `3` blank lines before node, expected up to `1` blank line, remove `2` blank lines
+```
+
+##### `initial.md`
+
+###### In
+
+```markdown
+␊Mercury.
+```
+
+###### Out
+
+```text
+2:1: Unexpected `1` blank line before node, expected `0` blank lines, remove `1` blank line
+```
+
+##### `final-one.md`
+
+###### In
+
+```markdown
+Mercury.␊
+```
+
+###### Out
+
+No messages.
+
+##### `final-more.md`
+
+###### In
+
+```markdown
+Mercury.␊␊
+```
+
+###### Out
+
+```text
+1:9: Unexpected `1` blank line after node, expected `0` blank lines, remove `1` blank line
+```
+
+##### `empty-document.md`
+
+###### Out
+
+No messages.
+
+##### `block-quote.md`
+
+###### In
+
+```markdown
+> Mercury.
+
+Venus.
+
+>
+> Earth.
+>
+```
+
+###### Out
+
+```text
+6:3: Unexpected `1` blank line before node, expected `0` blank lines, remove `1` blank line
+6:9: Unexpected `1` blank line after node, expected `0` blank lines, remove `1` blank line
+```
+
+##### `directive.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> directives ([`remark-directive`][github-remark-directive]).
+
+```markdown
+:::mercury
+Venus.
+
+
+Earth.
+:::
+```
+
+###### Out
+
+```text
+5:1: Unexpected `2` blank lines before node, expected up to `1` blank line, remove `1` blank line
+```
+
+##### `footnote.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+[^x]:
+ Mercury.
+
+Venus.
+
+[^y]:
+
+ Earth.
+
+
+ Mars.
+```
+
+###### Out
+
+```text
+8:5: Unexpected `1` blank line before node, expected `0` blank lines, remove `1` blank line
+11:5: Unexpected `2` blank lines before node, expected up to `1` blank line, remove `1` blank line
+```
+
+##### `jsx.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+<Mercury>
+ Venus.
+
+
+ Earth.
+</Mercury>
+```
+
+###### Out
+
+```text
+5:3: Unexpected `2` blank lines before node, expected up to `1` blank line, remove `1` blank line
+```
+
+##### `list.md`
+
+###### In
+
+```markdown
+* Mercury.
+* Venus.
+
+***
+
+* Mercury.
+
+* Venus.
+
+***
+
+* Mercury.
+
+
+* Venus.
+```
+
+###### Out
+
+```text
+15:1: Unexpected `2` blank lines before node, expected up to `1` blank line, remove `1` blank line
+```
+
+##### `list-item.md`
+
+###### In
+
+```markdown
+* Mercury.
+ Venus.
+
+***
+
+* Mercury.
+
+ Venus.
+
+***
+
+* Mercury.
+
+
+ Venus.
+
+***
+
+*
+ Mercury.
+```
+
+###### Out
+
+```text
+15:3: Unexpected `2` blank lines before node, expected up to `1` blank line, remove `1` blank line
+20:3: Unexpected `1` blank line before node, expected `0` blank lines, remove `1` blank line
+```
+
+##### `deep-block-quote.md`
+
+###### In
+
+```markdown
+* > * > # Venus␊␊
+```
+
+###### Out
+
+```text
+1:16: Unexpected `1` blank line after node, expected `0` blank lines, remove `1` blank line
+```
+
+##### `deep-list-item.md`
+
+###### In
+
+```markdown
+> * > * # Venus␊␊
+```
+
+###### Out
+
+```text
+1:16: Unexpected `1` blank line after node, expected `0` blank lines, remove `1` blank line
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-consecutive-blank-lines@5`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-consecutive-blank-lines]: #unifieduseremarklintnoconsecutiveblanklines
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-consecutive-blank-lines.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-consecutive-blank-lines
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-consecutive-blank-lines
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-consecutive-blank-lines
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-directive]: https://github.com/remarkjs/remark-directive
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-mdx]: https://mdxjs.com/packages/remark-mdx/
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-duplicate-defined-urls_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-duplicate-defined-urls_readme.md
new file mode 100644
index 0000000..2b968bf
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-duplicate-defined-urls_readme.md
@@ -0,0 +1,243 @@
+<!--This file is generated-->
+
+# remark-lint-no-duplicate-defined-urls
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when URLs are defined multiple times.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoDuplicateDefinedUrls)`](#unifieduseremarklintnoduplicatedefinedurls)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks that defined URLs are unique.
+
+## When should I use this?
+
+You can use this package to check that definitions are useful.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-duplicate-defined-urls
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoDuplicateDefinedUrls from 'https://esm.sh/remark-lint-no-duplicate-defined-urls@3'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoDuplicateDefinedUrls from 'https://esm.sh/remark-lint-no-duplicate-defined-urls@3?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoDuplicateDefinedUrls from 'remark-lint-no-duplicate-defined-urls'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoDuplicateDefinedUrls)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-duplicate-defined-urls .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-duplicate-defined-urls",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoDuplicateDefinedUrls`][api-remark-lint-no-duplicate-defined-urls].
+
+### `unified().use(remarkLintNoDuplicateDefinedUrls)`
+
+Warn when URLs are defined multiple times.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+It’s likely a mistake when the same URL is defined with different
+identifiers.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+The first planet is [mercury][].
+
+[mercury]: https://example.com/mercury/
+[venus]: https://example.com/venus/
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+[mercury]: https://example.com/mercury/
+[venus]: https://example.com/mercury/
+```
+
+###### Out
+
+```text
+2:1-2:38: Unexpected definition with an already defined URL (as `mercury`), expected unique URLs
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-duplicate-defined-urls@3`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-duplicate-defined-urls]: #unifieduseremarklintnoduplicatedefinedurls
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-duplicate-defined-urls.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-duplicate-defined-urls
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-duplicate-defined-urls
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-duplicate-defined-urls
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-duplicate-definitions_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-duplicate-definitions_readme.md
new file mode 100644
index 0000000..86d5387
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-duplicate-definitions_readme.md
@@ -0,0 +1,270 @@
+<!--This file is generated-->
+
+# remark-lint-no-duplicate-definitions
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when identifiers are defined multiple times.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoDuplicateDefinitions)`](#unifieduseremarklintnoduplicatedefinitions)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks that defined identifiers are unique.
+
+## When should I use this?
+
+You can use this package to check that definitions are useful.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-duplicate-definitions
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoDuplicateDefinitions from 'https://esm.sh/remark-lint-no-duplicate-definitions@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoDuplicateDefinitions from 'https://esm.sh/remark-lint-no-duplicate-definitions@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoDuplicateDefinitions from 'remark-lint-no-duplicate-definitions'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoDuplicateDefinitions)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-duplicate-definitions .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-duplicate-definitions",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoDuplicateDefinitions`][api-remark-lint-no-duplicate-definitions].
+
+### `unified().use(remarkLintNoDuplicateDefinitions)`
+
+Warn when identifiers are defined multiple times.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+It’s a mistake when the same identifier is defined multiple times.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+[mercury]: https://example.com/mercury/
+[venus]: https://example.com/venus/
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+[mercury]: https://example.com/mercury/
+[mercury]: https://example.com/venus/
+```
+
+###### Out
+
+```text
+2:1-2:38: Unexpected definition with an already defined identifier (`mercury`), expected unique identifiers
+```
+
+##### `gfm.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+Mercury[^mercury].
+
+[^mercury]:
+ Mercury is the first planet from the Sun and the smallest in the Solar
+ System.
+
+[^mercury]:
+ Venus is the second planet from the Sun.
+```
+
+###### Out
+
+```text
+7:1-7:12: Unexpected footnote definition with an already defined identifier (`mercury`), expected unique identifiers
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-duplicate-definitions@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-duplicate-definitions]: #unifieduseremarklintnoduplicatedefinitions
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-duplicate-definitions.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-duplicate-definitions
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-duplicate-definitions
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-duplicate-definitions
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-duplicate-headings-in-section_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-duplicate-headings-in-section_readme.md
new file mode 100644
index 0000000..4302d75
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-duplicate-headings-in-section_readme.md
@@ -0,0 +1,304 @@
+<!--This file is generated-->
+
+# remark-lint-no-duplicate-headings-in-section
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when the same text is used in multiple headings
+in a section.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoDuplicateHeadingsInSection)`](#unifieduseremarklintnoduplicateheadingsinsection)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks that headings are unique in sections.
+
+## When should I use this?
+
+You can use this package to check that headings are unique.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-duplicate-headings-in-section
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoDuplicateHeadingsInSection from 'https://esm.sh/remark-lint-no-duplicate-headings-in-section@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoDuplicateHeadingsInSection from 'https://esm.sh/remark-lint-no-duplicate-headings-in-section@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoDuplicateHeadingsInSection from 'remark-lint-no-duplicate-headings-in-section'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoDuplicateHeadingsInSection)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-duplicate-headings-in-section .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-duplicate-headings-in-section",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoDuplicateHeadingsInSection`][api-remark-lint-no-duplicate-headings-in-section].
+
+### `unified().use(remarkLintNoDuplicateHeadingsInSection)`
+
+Warn when the same text is used in multiple headings in a section.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+It’s likely a mistake that the same heading text is used in the same
+section.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+# Planets
+
+## Venus
+
+### Discovery
+
+## Mars
+
+### Discovery
+
+### Phobos
+
+#### Discovery
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+# Planets
+
+## Mars
+
+### Discovery
+
+### Discovery
+```
+
+###### Out
+
+```text
+7:1-7:14: Unexpected heading with equivalent text in section, expected unique headings
+```
+
+##### `tolerant-heading-increment.md`
+
+###### In
+
+```markdown
+# Planets
+
+#### Discovery
+
+###### Phobos
+
+#### Discovery
+
+###### Deimos
+```
+
+###### Out
+
+```text
+7:1-7:15: Unexpected heading with equivalent text in section, expected unique headings
+```
+
+##### `mdx.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+MDX is supported <em>too</em>.
+
+<h1>Planets</h1>
+<h2>Mars</h2>
+<h3>Discovery</h3>
+<h3>Discovery</h3>
+```
+
+###### Out
+
+```text
+6:1-6:19: Unexpected heading with equivalent text in section, expected unique headings
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-duplicate-headings-in-section@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-duplicate-headings-in-section]: #unifieduseremarklintnoduplicateheadingsinsection
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-duplicate-headings-in-section.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-duplicate-headings-in-section
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-duplicate-headings-in-section
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-duplicate-headings-in-section
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-mdx]: https://mdxjs.com/packages/remark-mdx/
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-duplicate-headings_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-duplicate-headings_readme.md
new file mode 100644
index 0000000..aa2fb7a
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-duplicate-headings_readme.md
@@ -0,0 +1,277 @@
+<!--This file is generated-->
+
+# remark-lint-no-duplicate-headings
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when the same text is used in multiple headings.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoDuplicateHeadings)`](#unifieduseremarklintnoduplicateheadings)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks that headings are unique.
+
+## When should I use this?
+
+You can use this package to check that headings are unique.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-duplicate-headings
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoDuplicateHeadings from 'https://esm.sh/remark-lint-no-duplicate-headings@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoDuplicateHeadings from 'https://esm.sh/remark-lint-no-duplicate-headings@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoDuplicateHeadings from 'remark-lint-no-duplicate-headings'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoDuplicateHeadings)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-duplicate-headings .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-duplicate-headings",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoDuplicateHeadings`][api-remark-lint-no-duplicate-headings].
+
+### `unified().use(remarkLintNoDuplicateHeadings)`
+
+Warn when the same text is used in multiple headings.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+Headings having unique text helps screen reader users,
+who typically use “jump to heading” features to navigate within a page,
+which reads headings out loud.
+
+It also helps because often headings receive automatic unique IDs,
+and when the same heading text is used,
+they are suffixed with a number based on where they are positioned in the
+document,
+which makes linking to them prone to changes.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+# Mercury
+
+## Venus
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+# Mercury
+
+## Mercury
+
+## [Mercury](https://example.com/mercury/)
+```
+
+###### Out
+
+```text
+3:1-3:11: Unexpected heading with equivalent text, expected unique headings
+5:1-5:43: Unexpected heading with equivalent text, expected unique headings
+```
+
+##### `mdx.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+<h1>Mercury</h1>
+<h2>Mercury</h2>
+```
+
+###### Out
+
+```text
+2:1-2:17: Unexpected heading with equivalent text, expected unique headings
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-duplicate-headings@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-duplicate-headings]: #unifieduseremarklintnoduplicateheadings
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-duplicate-headings.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-duplicate-headings
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-duplicate-headings
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-duplicate-headings
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-mdx]: https://mdxjs.com/packages/remark-mdx/
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-emphasis-as-heading_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-emphasis-as-heading_readme.md
new file mode 100644
index 0000000..ecfa1ab
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-emphasis-as-heading_readme.md
@@ -0,0 +1,257 @@
+<!--This file is generated-->
+
+# remark-lint-no-emphasis-as-heading
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when emphasis or strong are used instead of a
+heading.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoEmphasisAsHeading)`](#unifieduseremarklintnoemphasisasheading)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks emphasis and strong.
+
+## When should I use this?
+
+You can use this package to check that headings are used.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-emphasis-as-heading
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoEmphasisAsHeading from 'https://esm.sh/remark-lint-no-emphasis-as-heading@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoEmphasisAsHeading from 'https://esm.sh/remark-lint-no-emphasis-as-heading@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoEmphasisAsHeading from 'remark-lint-no-emphasis-as-heading'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoEmphasisAsHeading)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-emphasis-as-heading .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-emphasis-as-heading",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoEmphasisAsHeading`][api-remark-lint-no-emphasis-as-heading].
+
+### `unified().use(remarkLintNoEmphasisAsHeading)`
+
+Warn when emphasis or strong are used instead of a heading.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+While not always the case,
+typically emphasis or strong around the text in a paragraph is used as a
+“faux” heading.
+It’s recommended to use actual headings instead.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+# Mercury
+
+**Mercury** is the first planet from the Sun and the smallest in the Solar
+System.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+**Mercury**
+
+**Mercury** is the first planet from the Sun and the smallest in the Solar
+System.
+
+*Venus*
+
+**Venus** is the second planet from the Sun.
+```
+
+###### Out
+
+```text
+1:1-1:12: Unexpected strong introducing a section, expected a heading instead
+6:1-6:8: Unexpected emphasis introducing a section, expected a heading instead
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-emphasis-as-heading@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-emphasis-as-heading]: #unifieduseremarklintnoemphasisasheading
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-emphasis-as-heading.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-emphasis-as-heading
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-emphasis-as-heading
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-emphasis-as-heading
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-empty-url_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-empty-url_readme.md
new file mode 100644
index 0000000..da19501
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-empty-url_readme.md
@@ -0,0 +1,252 @@
+<!--This file is generated-->
+
+# remark-lint-no-empty-url
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when empty URLs are used.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoEmptyUrl)`](#unifieduseremarklintnoemptyurl)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks URLs of definitions, images, and links.
+
+## When should I use this?
+
+You can use this package to check that URLs of definitions, images, and
+links are not empty.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-empty-url
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoEmptyUrl from 'https://esm.sh/remark-lint-no-empty-url@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoEmptyUrl from 'https://esm.sh/remark-lint-no-empty-url@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoEmptyUrl from 'remark-lint-no-empty-url'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoEmptyUrl)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-empty-url .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-empty-url",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoEmptyUrl`][api-remark-lint-no-empty-url].
+
+### `unified().use(remarkLintNoEmptyUrl)`
+
+Warn when empty URLs are used.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+While it is possible to omit URLs in links and images,
+that typically indicates a “placeholder” or something that has to be filled
+out later.
+It’s recommended to fill them out.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+[Mercury](https://example.com/mercury/).
+
+.
+
+[earth]: https://example.com/earth/
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+[Mercury]().
+
+.
+
+[earth]: <>
+```
+
+###### Out
+
+```text
+1:1-1:12: Unexpected empty link URL referencing the current document, expected URL
+3:1-3:12: Unexpected empty image URL referencing the current document, expected URL
+5:1-5:12: Unexpected empty definition URL referencing the current document, expected URL
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-empty-url@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-empty-url]: #unifieduseremarklintnoemptyurl
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-empty-url.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-empty-url
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-empty-url
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-empty-url
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-file-name-articles_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-file-name-articles_readme.md
new file mode 100644
index 0000000..3428716
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-file-name-articles_readme.md
@@ -0,0 +1,241 @@
+<!--This file is generated-->
+
+# remark-lint-no-file-name-articles
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when file names start with `a`, `the`, and such.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoFileNameArticles)`](#unifieduseremarklintnofilenamearticles)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks file names.
+
+## When should I use this?
+
+You can use this package to check that file names are consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-file-name-articles
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoFileNameArticles from 'https://esm.sh/remark-lint-no-file-name-articles@3'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoFileNameArticles from 'https://esm.sh/remark-lint-no-file-name-articles@3?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoFileNameArticles from 'remark-lint-no-file-name-articles'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoFileNameArticles)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-file-name-articles .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-file-name-articles",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoFileNameArticles`][api-remark-lint-no-file-name-articles].
+
+### `unified().use(remarkLintNoFileNameArticles)`
+
+Warn when file names start with `a`, `the`, and such.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Examples
+
+##### `title.md`
+
+###### Out
+
+No messages.
+
+##### `a-title.md`
+
+###### Out
+
+```text
+1:1: Unexpected file name starting with `a`, remove it
+```
+
+##### `the-title.md`
+
+###### Out
+
+```text
+1:1: Unexpected file name starting with `the`, remove it
+```
+
+##### `an-article.md`
+
+###### Out
+
+```text
+1:1: Unexpected file name starting with `an`, remove it
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-file-name-articles@3`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-file-name-articles]: #unifieduseremarklintnofilenamearticles
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-file-name-articles.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-file-name-articles
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-file-name-articles
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-file-name-articles
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-file-name-consecutive-dashes_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-file-name-consecutive-dashes_readme.md
new file mode 100644
index 0000000..f8e7b9f
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-file-name-consecutive-dashes_readme.md
@@ -0,0 +1,225 @@
+<!--This file is generated-->
+
+# remark-lint-no-file-name-consecutive-dashes
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when file names contain consecutive dashes.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoFileNameConsecutiveDashes)`](#unifieduseremarklintnofilenameconsecutivedashes)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks file names.
+
+## When should I use this?
+
+You can use this package to check that file names are consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-file-name-consecutive-dashes
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoFileNameConsecutiveDashes from 'https://esm.sh/remark-lint-no-file-name-consecutive-dashes@3'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoFileNameConsecutiveDashes from 'https://esm.sh/remark-lint-no-file-name-consecutive-dashes@3?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoFileNameConsecutiveDashes from 'remark-lint-no-file-name-consecutive-dashes'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoFileNameConsecutiveDashes)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-file-name-consecutive-dashes .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-file-name-consecutive-dashes",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoFileNameConsecutiveDashes`][api-remark-lint-no-file-name-consecutive-dashes].
+
+### `unified().use(remarkLintNoFileNameConsecutiveDashes)`
+
+Warn when file names contain consecutive dashes.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Examples
+
+##### `plug-ins.md`
+
+###### Out
+
+No messages.
+
+##### `plug--ins.md`
+
+###### Out
+
+```text
+1:1: Unexpected consecutive dashes in a file name, expected `-`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-file-name-consecutive-dashes@3`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-file-name-consecutive-dashes]: #unifieduseremarklintnofilenameconsecutivedashes
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-file-name-consecutive-dashes.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-file-name-consecutive-dashes
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-file-name-consecutive-dashes
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-file-name-consecutive-dashes
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-file-name-irregular-characters_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-file-name-irregular-characters_readme.md
new file mode 100644
index 0000000..087108c
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-file-name-irregular-characters_readme.md
@@ -0,0 +1,272 @@
+<!--This file is generated-->
+
+# remark-lint-no-file-name-irregular-characters
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when file names contain irregular characters.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoFileNameIrregularCharacters[, options])`](#unifieduseremarklintnofilenameirregularcharacters-options)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks file names.
+
+## When should I use this?
+
+You can use this package to check that file names are consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-file-name-irregular-characters
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoFileNameIrregularCharacters from 'https://esm.sh/remark-lint-no-file-name-irregular-characters@3'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoFileNameIrregularCharacters from 'https://esm.sh/remark-lint-no-file-name-irregular-characters@3?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoFileNameIrregularCharacters from 'remark-lint-no-file-name-irregular-characters'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoFileNameIrregularCharacters)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-file-name-irregular-characters .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-file-name-irregular-characters",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoFileNameIrregularCharacters`][api-remark-lint-no-file-name-irregular-characters].
+
+### `unified().use(remarkLintNoFileNameIrregularCharacters[, options])`
+
+Warn when file names contain contain irregular characters.
+
+###### Parameters
+
+* `options` (`RegExp` or `string`, default: `/[^-.\dA-Za-z]/`)
+ — configuration,
+ when string wrapped in `new RegExp('[^' + x + ']')` so make sure
+ to escape regexp characters
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Examples
+
+##### `mercury-and-venus.md`
+
+###### Out
+
+No messages.
+
+##### `mercury.md`
+
+###### Out
+
+No messages.
+
+##### `mercury_and_venus.md`
+
+###### Out
+
+```text
+1:1: Unexpected character `_` in file name
+```
+
+##### `Readme.md`
+
+When configured with `'\\.a-z0-9'`.
+
+###### Out
+
+```text
+1:1: Unexpected character `R` in file name
+```
+
+##### `mercury_and_venus.md`
+
+When configured with `{ source: '[^\\.a-z0-9]' }`.
+
+###### Out
+
+```text
+1:1: Unexpected character `_` in file name
+```
+
+##### `mercury and venus.md`
+
+###### Out
+
+```text
+1:1: Unexpected character ` ` in file name
+```
+
+##### `not-ok-options.md`
+
+When configured with `1`.
+
+###### Out
+
+```text
+1:1: Unexpected value `1` for `options`, expected `RegExp` or `string`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-file-name-irregular-characters@3`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-file-name-irregular-characters]: #unifieduseremarklintnofilenameirregularcharacters-options
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-file-name-irregular-characters.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-file-name-irregular-characters
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-file-name-irregular-characters
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-file-name-irregular-characters
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-file-name-mixed-case_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-file-name-mixed-case_readme.md
new file mode 100644
index 0000000..5b91975
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-file-name-mixed-case_readme.md
@@ -0,0 +1,232 @@
+<!--This file is generated-->
+
+# remark-lint-no-file-name-mixed-case
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when file names case is inconsistent.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoFileNameMixedCase)`](#unifieduseremarklintnofilenamemixedcase)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks file names.
+
+## When should I use this?
+
+You can use this package to check that file names are consistent (either
+lowercase or uppercase).
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-file-name-mixed-case
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoFileNameMixedCase from 'https://esm.sh/remark-lint-no-file-name-mixed-case@3'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoFileNameMixedCase from 'https://esm.sh/remark-lint-no-file-name-mixed-case@3?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoFileNameMixedCase from 'remark-lint-no-file-name-mixed-case'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoFileNameMixedCase)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-file-name-mixed-case .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-file-name-mixed-case",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoFileNameMixedCase`][api-remark-lint-no-file-name-mixed-case].
+
+### `unified().use(remarkLintNoFileNameMixedCase)`
+
+Warn when file names case is inconsistent.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Examples
+
+##### `MERCURY.md`
+
+###### Out
+
+No messages.
+
+##### `mercury.md`
+
+###### Out
+
+No messages.
+
+##### `Mercury.md`
+
+###### Out
+
+```text
+1:1: Unexpected mixed case in file name, expected either lowercase or uppercase
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-file-name-mixed-case@3`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-file-name-mixed-case]: #unifieduseremarklintnofilenamemixedcase
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-file-name-mixed-case.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-file-name-mixed-case
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-file-name-mixed-case
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-file-name-mixed-case
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-file-name-outer-dashes_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-file-name-outer-dashes_readme.md
new file mode 100644
index 0000000..8e16f6a
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-file-name-outer-dashes_readme.md
@@ -0,0 +1,233 @@
+<!--This file is generated-->
+
+# remark-lint-no-file-name-outer-dashes
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when file names start or end with dashes.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoFileNameOuterDashes)`](#unifieduseremarklintnofilenameouterdashes)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks file names.
+
+## When should I use this?
+
+You can use this package to check that file names are consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-file-name-outer-dashes
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoFileNameOuterDashes from 'https://esm.sh/remark-lint-no-file-name-outer-dashes@3'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoFileNameOuterDashes from 'https://esm.sh/remark-lint-no-file-name-outer-dashes@3?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoFileNameOuterDashes from 'remark-lint-no-file-name-outer-dashes'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoFileNameOuterDashes)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-file-name-outer-dashes .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-file-name-outer-dashes",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoFileNameOuterDashes`][api-remark-lint-no-file-name-outer-dashes].
+
+### `unified().use(remarkLintNoFileNameOuterDashes)`
+
+Warn when file names start or end with dashes.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Examples
+
+##### `mercury-and-venus.md`
+
+###### Out
+
+No messages.
+
+##### `-mercury.md`
+
+###### Out
+
+```text
+1:1: Unexpected initial or final dashes in file name, expected dashes to join words
+```
+
+##### `venus-.md`
+
+###### Out
+
+```text
+1:1: Unexpected initial or final dashes in file name, expected dashes to join words
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-file-name-outer-dashes@3`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-file-name-outer-dashes]: #unifieduseremarklintnofilenameouterdashes
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-file-name-outer-dashes.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-file-name-outer-dashes
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-file-name-outer-dashes
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-file-name-outer-dashes
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-heading-content-indent_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-heading-content-indent_readme.md
new file mode 100644
index 0000000..06e9e00
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-heading-content-indent_readme.md
@@ -0,0 +1,283 @@
+<!--This file is generated-->
+
+# remark-lint-no-heading-content-indent
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when extra whitespace is used between hashes and
+content in headings.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoHeadingContentIndent)`](#unifieduseremarklintnoheadingcontentindent)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks whitespace between hashes and content.
+
+## When should I use this?
+
+You can use this package to check that headings are consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-heading-content-indent
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoHeadingContentIndent from 'https://esm.sh/remark-lint-no-heading-content-indent@5'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoHeadingContentIndent from 'https://esm.sh/remark-lint-no-heading-content-indent@5?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoHeadingContentIndent from 'remark-lint-no-heading-content-indent'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoHeadingContentIndent)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-heading-content-indent .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-heading-content-indent",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoHeadingContentIndent`][api-remark-lint-no-heading-content-indent].
+
+### `unified().use(remarkLintNoHeadingContentIndent)`
+
+Warn when extra whitespace is used between hashes and content in headings.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+One space is required and more than one space has no effect.
+Due to this, it’s recommended to turn this rule on.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] formats headings with one space.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+#␠Mercury
+
+##␠Venus␠##
+
+␠␠##␠Earth
+
+Setext headings are not affected:
+
+␠Mars
+=====
+
+␠Jupiter
+--------
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+#␠␠Mercury
+
+##␠Venus␠␠##
+
+␠␠##␠␠␠Earth
+```
+
+###### Out
+
+```text
+1:4: Unexpected `2` spaces between hashes and content, expected `1` space, remove `1` space
+3:11: Unexpected `2` spaces between content and hashes, expected `1` space, remove `1` space
+5:8: Unexpected `3` spaces between hashes and content, expected `1` space, remove `2` spaces
+```
+
+##### `empty-heading.md`
+
+###### In
+
+```markdown
+#␠␠
+```
+
+###### Out
+
+```text
+1:4: Unexpected `2` spaces between hashes and content, expected `1` space, remove `1` space
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-heading-content-indent@5`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-heading-content-indent]: #unifieduseremarklintnoheadingcontentindent
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-heading-content-indent.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-heading-content-indent
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-heading-content-indent
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-heading-content-indent
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-heading-indent_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-heading-indent_readme.md
new file mode 100644
index 0000000..ffb7919
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-heading-indent_readme.md
@@ -0,0 +1,279 @@
+<!--This file is generated-->
+
+# remark-lint-no-heading-indent
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when headings are indented.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoHeadingIndent)`](#unifieduseremarklintnoheadingindent)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the spaces before headings.
+
+## When should I use this?
+
+You can use this rule to check markdown code style.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-heading-indent
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoHeadingIndent from 'https://esm.sh/remark-lint-no-heading-indent@5'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoHeadingIndent from 'https://esm.sh/remark-lint-no-heading-indent@5?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoHeadingIndent from 'remark-lint-no-heading-indent'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoHeadingIndent)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-heading-indent .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-heading-indent",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoHeadingIndent`][api-remark-lint-no-heading-indent].
+
+### `unified().use(remarkLintNoHeadingIndent)`
+
+Warn when headings are indented.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+There is no specific handling of indented headings (or anything else) in
+markdown.
+While it is possible to use an indent to headings on their text:
+
+```markdown
+ # Mercury
+ ## Venus
+ ### Earth
+#### Mars
+```
+
+…such style is uncommon,
+a bit hard to maintain,
+and it’s impossible to add a heading with a rank of 5 as it would form
+indented code instead.
+So it’s recommended to not indent headings and to turn this rule on.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] formats headings without indent.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+#␠Mercury
+
+Venus
+-----
+
+#␠Earth␠#
+
+Mars
+====
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+␠␠␠# Mercury
+
+␠Venus
+------
+
+␠# Earth #
+
+␠␠␠Mars
+======
+```
+
+###### Out
+
+```text
+1:4: Unexpected `3` spaces before heading, expected `0` spaces, remove `3` spaces
+3:2: Unexpected `1` space before heading, expected `0` spaces, remove `1` space
+6:2: Unexpected `1` space before heading, expected `0` spaces, remove `1` space
+8:4: Unexpected `3` spaces before heading, expected `0` spaces, remove `3` spaces
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-heading-indent@5`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-heading-indent]: #unifieduseremarklintnoheadingindent
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-heading-indent.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-heading-indent
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-heading-indent
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-heading-indent
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-heading-like-paragraph_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-heading-like-paragraph_readme.md
new file mode 100644
index 0000000..eaeadd7
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-heading-like-paragraph_readme.md
@@ -0,0 +1,242 @@
+<!--This file is generated-->
+
+# remark-lint-no-heading-like-paragraph
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when “headings” have too many hashes.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoHeadingLikeParagraph)`](#unifieduseremarklintnoheadinglikeparagraph)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks for broken headings.
+
+## When should I use this?
+
+You can use this rule to check markdown code style.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-heading-like-paragraph
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoHeadingLikeParagraph from 'https://esm.sh/remark-lint-no-heading-like-paragraph@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoHeadingLikeParagraph from 'https://esm.sh/remark-lint-no-heading-like-paragraph@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoHeadingLikeParagraph from 'remark-lint-no-heading-like-paragraph'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoHeadingLikeParagraph)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-heading-like-paragraph .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-heading-like-paragraph",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoHeadingLikeParagraph`][api-remark-lint-no-heading-like-paragraph].
+
+### `unified().use(remarkLintNoHeadingLikeParagraph)`
+
+Warn when “headings” have too many hashes.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+###### Venus
+
+Mercury.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+####### Venus
+
+Mercury.
+
+######## Earth
+
+Mars.
+```
+
+###### Out
+
+```text
+1:8: Unexpected `7` hashes starting paragraph looking like a heading, expected up to `6` hashes, remove `1` hash
+5:9: Unexpected `8` hashes starting paragraph looking like a heading, expected up to `6` hashes, remove `2` hashes
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-heading-like-paragraph@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-heading-like-paragraph]: #unifieduseremarklintnoheadinglikeparagraph
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-heading-like-paragraph.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-heading-like-paragraph
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-heading-like-paragraph
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-heading-like-paragraph
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-heading-punctuation_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-heading-punctuation_readme.md
new file mode 100644
index 0000000..024a8d1
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-heading-punctuation_readme.md
@@ -0,0 +1,311 @@
+<!--This file is generated-->
+
+# remark-lint-no-heading-punctuation
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when headings end in irregular characters.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoHeadingPunctuation[, options])`](#unifieduseremarklintnoheadingpunctuation-options)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks heading text.
+
+## When should I use this?
+
+You can use this package to check that heading text is consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `':.'` |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-heading-punctuation
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoHeadingPunctuation from 'https://esm.sh/remark-lint-no-heading-punctuation@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoHeadingPunctuation from 'https://esm.sh/remark-lint-no-heading-punctuation@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoHeadingPunctuation from 'remark-lint-no-heading-punctuation'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoHeadingPunctuation)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-heading-punctuation .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-heading-punctuation",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoHeadingPunctuation`][api-remark-lint-no-heading-punctuation].
+
+### `unified().use(remarkLintNoHeadingPunctuation[, options])`
+
+Warn when headings end in irregular characters.
+
+###### Parameters
+
+* `options` (`RegExp` or `string`, default: `/[!,.:;?]/u`)
+ — configuration,
+ when string wrapped in `new RegExp('[' + x + ']', 'u')` so make sure to
+ escape regexp characters
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+# Mercury
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+# Mercury:
+
+# Venus?
+
+# Earth!
+
+# Mars,
+
+# Jupiter;
+```
+
+###### Out
+
+```text
+1:1-1:11: Unexpected character `:` at end of heading, remove it
+3:1-3:9: Unexpected character `?` at end of heading, remove it
+5:1-5:9: Unexpected character `!` at end of heading, remove it
+7:1-7:8: Unexpected character `,` at end of heading, remove it
+9:1-9:11: Unexpected character `;` at end of heading, remove it
+```
+
+##### `ok.md`
+
+When configured with `',;:!?'`.
+
+###### In
+
+```markdown
+# Mercury…
+```
+
+###### Out
+
+No messages.
+
+##### `regex.md`
+
+When configured with `{ source: '[^A-Za-z0-9]' }`.
+
+###### In
+
+```markdown
+# Mercury!
+```
+
+###### Out
+
+```text
+1:1-1:11: Unexpected character `!` at end of heading, remove it
+```
+
+##### `example.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+<h1>Mercury?</h1>
+```
+
+###### Out
+
+```text
+1:1-1:18: Unexpected character `?` at end of heading, remove it
+```
+
+##### `not-ok-options.md`
+
+When configured with `1`.
+
+###### Out
+
+```text
+1:1: Unexpected value `1` for `options`, expected `RegExp` or `string`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-heading-punctuation@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-heading-punctuation]: #unifieduseremarklintnoheadingpunctuation-options
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-heading-punctuation.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-heading-punctuation
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-heading-punctuation
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-heading-punctuation
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-mdx]: https://mdxjs.com/packages/remark-mdx/
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-hidden-table-cell_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-hidden-table-cell_readme.md
new file mode 100644
index 0000000..674eadb
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-hidden-table-cell_readme.md
@@ -0,0 +1,247 @@
+<!--This file is generated-->
+
+# remark-lint-no-hidden-table-cell
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn for superfluous table cells.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoHiddenTableCell)`](#unifieduseremarklintnohiddentablecell)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks that all table cells are rendered.
+
+## When should I use this?
+
+You can use this package to check that table cells are rendered.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-hidden-table-cell
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoHiddenTableCell from 'https://esm.sh/remark-lint-no-hidden-table-cell@1'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoHiddenTableCell from 'https://esm.sh/remark-lint-no-hidden-table-cell@1?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoHiddenTableCell from 'remark-lint-no-hidden-table-cell'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoHiddenTableCell)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-hidden-table-cell .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-hidden-table-cell",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoHiddenTableCell`][api-remark-lint-no-hidden-table-cell].
+
+### `unified().use(remarkLintNoHiddenTableCell)`
+
+Warn for superfluous table cells.
+
+###### Parameters
+
+There are no parameters.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+| Planet | Mean anomaly (°) |
+| :- | -: |
+| Mercury | 174 796 |
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+| Planet | Symbol | Satellites |
+| :- | - | - |
+| Venus | ♀ |
+| Earth | ♁ | 1 |
+| Mars | ♂ | 2 | 19 412 |
+```
+
+###### Out
+
+```text
+5:16-5:26: Unexpected hidden table cell, expected as many cells in body rows as in the head row
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-hidden-table-cell@1`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-hidden-table-cell]: #unifieduseremarklintnohiddentablecell
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-hidden-table-cell.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-hidden-table-cell
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-hidden-table-cell
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-hidden-table-cell
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-html_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-html_readme.md
new file mode 100644
index 0000000..44f2b0e
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-html_readme.md
@@ -0,0 +1,265 @@
+<!--This file is generated-->
+
+# remark-lint-no-html
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when HTML is used.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoHtml[, options])`](#unifieduseremarklintnohtml-options)
+ * [`Options`](#options)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks HTML.
+
+## When should I use this?
+
+You can use this package to check that no HTML is used.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-html
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoHtml from 'https://esm.sh/remark-lint-no-html@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoHtml from 'https://esm.sh/remark-lint-no-html@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoHtml from 'remark-lint-no-html'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoHtml)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-html .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-html",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] type
+[`Options`][api-options].
+The default export is
+[`remarkLintNoHtml`][api-remark-lint-no-html].
+
+### `unified().use(remarkLintNoHtml[, options])`
+
+Warn when HTML is used.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], optional)
+ — configuration
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Fields
+
+* `allowComments` (`boolean`, default: `true`)
+ — allow comments or not
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+# Mercury
+
+<!--Venus-->
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+<h1>Mercury</h1>
+```
+
+###### Out
+
+```text
+1:1-1:17: Unexpected HTML, use markdown instead
+```
+
+##### `not-ok.md`
+
+When configured with `{ allowComments: false }`.
+
+###### In
+
+```markdown
+<!--Mercury-->
+```
+
+###### Out
+
+```text
+1:1-1:15: Unexpected HTML, use markdown instead
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-html@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-options]: #options
+
+[api-remark-lint-no-html]: #unifieduseremarklintnohtml-options
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-html.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-html
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-html
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-html
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-literal-urls_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-literal-urls_readme.md
new file mode 100644
index 0000000..e7b4b9f
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-literal-urls_readme.md
@@ -0,0 +1,274 @@
+<!--This file is generated-->
+
+# remark-lint-no-literal-urls
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when GFM autolink literals are used.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoLiteralUrls)`](#unifieduseremarklintnoliteralurls)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks that regular autolinks or full links are used.
+Literal autolinks is a GFM feature enabled with
+[`remark-gfm`][github-remark-gfm].
+
+## When should I use this?
+
+You can use this package to check that links are consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+| [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-literal-urls
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoLiteralUrls from 'https://esm.sh/remark-lint-no-literal-urls@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoLiteralUrls from 'https://esm.sh/remark-lint-no-literal-urls@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoLiteralUrls from 'remark-lint-no-literal-urls'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoLiteralUrls)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-literal-urls .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-literal-urls",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoLiteralUrls`][api-remark-lint-no-literal-urls].
+
+### `unified().use(remarkLintNoLiteralUrls)`
+
+Warn when GFM autolink literals are used.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+GFM autolink literals (just a raw URL) are a feature enabled by GFM.
+They don’t work everywhere.
+So,
+it’s recommended to instead use regular autolinks (`<https://url>`) or full
+links (`[text](url)`).
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] never generates GFM autolink
+literals.
+It always generates regular autolinks or full links.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+<https://example.com/mercury/>
+
+.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+https://example.com/mercury/
+
+www.example.com/venus/
+
+earth@mars.planets
+```
+
+###### Out
+
+```text
+1:1-1:29: Unexpected GFM autolink literal, expected regular autolink, add `<` before and `>` after
+3:1-3:23: Unexpected GFM autolink literal, expected regular autolink, add `<http://` before and `>` after
+5:1-5:19: Unexpected GFM autolink literal, expected regular autolink, add `<mailto:` before and `>` after
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-literal-urls@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-literal-urls]: #unifieduseremarklintnoliteralurls
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-literal-urls.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-literal-urls
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-literal-urls
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-literal-urls
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-missing-blank-lines_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-missing-blank-lines_readme.md
new file mode 100644
index 0000000..cda12c3
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-missing-blank-lines_readme.md
@@ -0,0 +1,418 @@
+<!--This file is generated-->
+
+# remark-lint-no-missing-blank-lines
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when blank lines are missing.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoMissingBlankLines[, options])`](#unifieduseremarklintnomissingblanklines-options)
+ * [`Options`](#options)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks missing blank lines.
+
+## When should I use this?
+
+You can use this package to check blank lines.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-missing-blank-lines
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoMissingBlankLines from 'https://esm.sh/remark-lint-no-missing-blank-lines@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoMissingBlankLines from 'https://esm.sh/remark-lint-no-missing-blank-lines@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoMissingBlankLines from 'remark-lint-no-missing-blank-lines'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoMissingBlankLines)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-missing-blank-lines .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-missing-blank-lines",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] type
+[`Options`][api-options].
+The default export is
+[`remarkLintNoMissingBlankLines`][api-remark-lint-no-missing-blank-lines].
+
+### `unified().use(remarkLintNoMissingBlankLines[, options])`
+
+Warn when blank lines are missing.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], optional)
+ — configuration
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Fields
+
+* `exceptTightLists` (`boolean`, default: `false`)
+ — allow omitting blank lines in list items
+
+## Recommendation
+
+Blank lines are required in certain sometimes confusing cases.
+So it’s recommended to always use blank lines between blocks.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] always uses blank lines
+between blocks.
+It has a `join` function to customize such behavior.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+# Mercury
+
+## Venus
+
+* Earth.
+
+ * Mars.
+
+> # Jupiter
+>
+> Saturn.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+# Mercury
+## Venus
+
+* Earth
+ * Mars.
+
+> # Jupiter
+> Saturn.
+```
+
+###### Out
+
+```text
+2:1-2:9: Unexpected `0` blank lines between nodes, expected `1` or more blank lines, add `1` blank line
+5:3-5:10: Unexpected `0` blank lines between nodes, expected `1` or more blank lines, add `1` blank line
+8:3-8:10: Unexpected `0` blank lines between nodes, expected `1` or more blank lines, add `1` blank line
+```
+
+##### `tight.md`
+
+When configured with `{ exceptTightLists: true }`.
+
+###### In
+
+```markdown
+* Venus.
+
+ * Mars.
+```
+
+###### Out
+
+No messages.
+
+##### `containers.md`
+
+###### In
+
+```markdown
+> # Venus
+>
+> Mercury.
+
+- earth.
+- mars.
+
+* # Jupiter
+ Saturn.
+```
+
+###### Out
+
+```text
+9:3-9:10: Unexpected `0` blank lines between nodes, expected `1` or more blank lines, add `1` blank line
+```
+
+##### `gfm.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+| Planet | Diameter |
+| ------- | -------- |
+| Mercury | 4 880 km |
+
+[^Mercury]:
+ **Mercury** is the first planet from the Sun and the smallest
+ in the Solar System.
+[^Venus]:
+ **Venus** is the second planet from the Sun.
+```
+
+###### Out
+
+```text
+8:1-9:49: Unexpected `0` blank lines between nodes, expected `1` or more blank lines, add `1` blank line
+```
+
+##### `mdx.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+<Tip kind="info">
+ # Venus
+ Mars.
+</Tip>
+{Math.PI}
+```
+
+###### Out
+
+```text
+3:3-3:8: Unexpected `0` blank lines between nodes, expected `1` or more blank lines, add `1` blank line
+5:1-5:10: Unexpected `0` blank lines between nodes, expected `1` or more blank lines, add `1` blank line
+```
+
+##### `math.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> math ([`remark-math`][github-remark-math]).
+
+```markdown
+$$
+\frac{1}{2}
+$$
+$$
+\frac{2}{3}
+$$
+```
+
+###### Out
+
+```text
+4:1-6:3: Unexpected `0` blank lines between nodes, expected `1` or more blank lines, add `1` blank line
+```
+
+##### `directive.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> directives ([`remark-directive`][github-remark-directive]).
+
+```markdown
+Directives are also checked.
+
+::video{#mercury}
+:::planet
+Venus.
+:::
+```
+
+###### Out
+
+```text
+4:1-6:4: Unexpected `0` blank lines between nodes, expected `1` or more blank lines, add `1` blank line
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-missing-blank-lines@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-options]: #options
+
+[api-remark-lint-no-missing-blank-lines]: #unifieduseremarklintnomissingblanklines-options
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-missing-blank-lines.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-missing-blank-lines
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-missing-blank-lines
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-missing-blank-lines
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-directive]: https://github.com/remarkjs/remark-directive
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-math]: https://github.com/remarkjs/remark-math
+
+[github-remark-mdx]: https://mdxjs.com/packages/remark-mdx/
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-multiple-toplevel-headings_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-multiple-toplevel-headings_readme.md
new file mode 100644
index 0000000..b001ef6
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-multiple-toplevel-headings_readme.md
@@ -0,0 +1,334 @@
+<!--This file is generated-->
+
+# remark-lint-no-multiple-toplevel-headings
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when top-level headings are used multiple times.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoMultipleToplevelHeadings[, options])`](#unifieduseremarklintnomultipletoplevelheadings-options)
+ * [`Depth`](#depth)
+ * [`Options`](#options)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks that top-level headings are unique.
+
+## When should I use this?
+
+You can use this package to check heading structure.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-multiple-toplevel-headings
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoMultipleToplevelHeadings from 'https://esm.sh/remark-lint-no-multiple-toplevel-headings@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoMultipleToplevelHeadings from 'https://esm.sh/remark-lint-no-multiple-toplevel-headings@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoMultipleToplevelHeadings from 'remark-lint-no-multiple-toplevel-headings'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoMultipleToplevelHeadings)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-multiple-toplevel-headings .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-multiple-toplevel-headings",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] types
+[`Depth`][api-depth] and
+[`Options`][api-options].
+The default export is
+[`remarkLintNoMultipleToplevelHeadings`][api-remark-lint-no-multiple-toplevel-headings].
+
+### `unified().use(remarkLintNoMultipleToplevelHeadings[, options])`
+
+Warn when top-level headings are used multiple times.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], default: `1`)
+ — configuration
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Depth`
+
+Depth (TypeScript type).
+
+###### Type
+
+```ts
+type Depth = 1 | 2 | 3 | 4 | 5 | 6
+```
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Type
+
+```ts
+type Options = Depth
+```
+
+## Recommendation
+
+Documents should almost always have one main heading,
+which is typically a heading with a rank of `1`.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+# Mercury
+
+## Venus
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+# Venus
+
+# Mercury
+```
+
+###### Out
+
+```text
+3:1-3:10: Unexpected duplicate toplevel heading, expected a single heading with rank `1`
+```
+
+##### `not-ok.md`
+
+When configured with `2`.
+
+###### In
+
+```markdown
+## Venus
+
+## Mercury
+```
+
+###### Out
+
+```text
+3:1-3:11: Unexpected duplicate toplevel heading, expected a single heading with rank `2`
+```
+
+##### `html.md`
+
+###### In
+
+```markdown
+Venus <b>and</b> mercury.
+
+<h1>Earth</h1>
+
+<h1>Mars</h1>
+```
+
+###### Out
+
+```text
+5:1-5:14: Unexpected duplicate toplevel heading, expected a single heading with rank `1`
+```
+
+##### `mdx.mdx`
+
+###### In
+
+> 👉 **Note**: this example uses
+> MDX ([`remark-mdx`][github-remark-mdx]).
+
+```mdx
+Venus <b>and</b> mercury.
+
+<h1>Earth</h1>
+<h1>Mars</h1>
+```
+
+###### Out
+
+```text
+4:1-4:14: Unexpected duplicate toplevel heading, expected a single heading with rank `1`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-multiple-toplevel-headings@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-depth]: #depth
+
+[api-options]: #options
+
+[api-remark-lint-no-multiple-toplevel-headings]: #unifieduseremarklintnomultipletoplevelheadings-options
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-multiple-toplevel-headings.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-multiple-toplevel-headings
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-multiple-toplevel-headings
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-multiple-toplevel-headings
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-mdx]: https://mdxjs.com/packages/remark-mdx/
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-paragraph-content-indent_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-paragraph-content-indent_readme.md
new file mode 100644
index 0000000..d09f830
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-paragraph-content-indent_readme.md
@@ -0,0 +1,270 @@
+<!--This file is generated-->
+
+# remark-lint-no-paragraph-content-indent
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when text in paragraphs is indented.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoParagraphContentIndent)`](#unifieduseremarklintnoparagraphcontentindent)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks that text in paragraphs is not indented.
+
+## When should I use this?
+
+You can use this package to check that paragraphs are consistent.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-paragraph-content-indent
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoParagraphContentIndent from 'https://esm.sh/remark-lint-no-paragraph-content-indent@5'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoParagraphContentIndent from 'https://esm.sh/remark-lint-no-paragraph-content-indent@5?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoParagraphContentIndent from 'remark-lint-no-paragraph-content-indent'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoParagraphContentIndent)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-paragraph-content-indent .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-paragraph-content-indent",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoParagraphContentIndent`][api-remark-lint-no-paragraph-content-indent].
+
+### `unified().use(remarkLintNoParagraphContentIndent)`
+
+Warn when text in paragraphs is indented.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+Indenting further lines in a paragraph has no effect.
+So it’s recommended to turn this rule on.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+Mercury.
+
+Venus and
+**Earth**.
+
+* Mars and
+ Jupiter.
+
+> Saturn and
+> Uranus.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+␠Mercury.
+
+Venus and
+␠␠**Earth**.
+
+* Mars and
+ ␠␠Jupiter.
+
+> Saturn and
+> ␠Uranus.
+
+* Neptune
+and
+ ␠␠Pluto.
+
+> Ceres
+and
+> ␠Makemake.
+```
+
+###### Out
+
+```text
+1:2: Unexpected `1` extra space before content line, remove `1` space
+4:3: Unexpected `2` extra spaces before content line, remove `2` spaces
+7:5: Unexpected `2` extra spaces before content line, remove `2` spaces
+10:4: Unexpected `1` extra space before content line, remove `1` space
+14:5: Unexpected `2` extra spaces before content line, remove `2` spaces
+18:4: Unexpected `1` extra space before content line, remove `1` space
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-paragraph-content-indent@5`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-paragraph-content-indent]: #unifieduseremarklintnoparagraphcontentindent
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-paragraph-content-indent.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-paragraph-content-indent
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-paragraph-content-indent
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-paragraph-content-indent
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-reference-like-url_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-reference-like-url_readme.md
new file mode 100644
index 0000000..b9f1e9d
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-reference-like-url_readme.md
@@ -0,0 +1,264 @@
+<!--This file is generated-->
+
+# remark-lint-no-reference-like-url
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when URLs are also defined identifiers.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoReferenceLikeUrl)`](#unifieduseremarklintnoreferencelikeurl)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks for likely broken URLs that should probably have been
+references.
+
+## When should I use this?
+
+You can use this package to check links.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-reference-like-url
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoReferenceLikeUrl from 'https://esm.sh/remark-lint-no-reference-like-url@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoReferenceLikeUrl from 'https://esm.sh/remark-lint-no-reference-like-url@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoReferenceLikeUrl from 'remark-lint-no-reference-like-url'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoReferenceLikeUrl)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-reference-like-url .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-reference-like-url",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoReferenceLikeUrl`][api-remark-lint-no-reference-like-url].
+
+### `unified().use(remarkLintNoReferenceLikeUrl)`
+
+Warn when URLs are also defined identifiers.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+While full URLs for definition identifiers are okay
+(`[https://example.com]: https://example.com`),
+and what looks like an identifier could be an actual URL (`[text](alpha)`),
+the more common case is that,
+assuming a definition `[alpha]: https://example.com`,
+then a link `[text](alpha)` should instead have been `[text][alpha]`.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+[**Mercury**][mercury] is the first planet from the sun.
+
+[mercury]: https://example.com/mercury/
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+[**Mercury**](mercury) is the first planet from the sun.
+
+[mercury]: https://example.com/mercury/
+```
+
+###### Out
+
+```text
+1:1-1:23: Unexpected resource link (`[text](url)`) with URL that matches a definition identifier (as `mercury`), expected reference (`[text][id]`)
+```
+
+##### `image.md`
+
+###### In
+
+```markdown
+.
+
+[mercury]: https://example.com/mercury.jpg
+```
+
+###### Out
+
+```text
+1:1-1:36: Unexpected resource image (``) with URL that matches a definition identifier (as `mercury`), expected reference (`![text][id]`)
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-reference-like-url@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-reference-like-url]: #unifieduseremarklintnoreferencelikeurl
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-reference-like-url.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-reference-like-url
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-reference-like-url
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-reference-like-url
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-shell-dollars_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-shell-dollars_readme.md
new file mode 100644
index 0000000..d352ab6
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-shell-dollars_readme.md
@@ -0,0 +1,276 @@
+<!--This file is generated-->
+
+# remark-lint-no-shell-dollars
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when every line in shell code is preceded by `$`s.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoShellDollars)`](#unifieduseremarklintnoshelldollars)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks for `$` markers prefixing shell code,
+which are hard to copy/paste.
+
+## When should I use this?
+
+You can use this package to check shell code blocks.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-shell-dollars
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoShellDollars from 'https://esm.sh/remark-lint-no-shell-dollars@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoShellDollars from 'https://esm.sh/remark-lint-no-shell-dollars@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoShellDollars from 'remark-lint-no-shell-dollars'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoShellDollars)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-shell-dollars .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-shell-dollars",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoShellDollars`][api-remark-lint-no-shell-dollars].
+
+### `unified().use(remarkLintNoShellDollars)`
+
+Warn when every line in shell code is preceded by `$`s.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+Dollars make copy/pasting hard.
+Either put dollars in front of some lines (commands) and don’t put them in
+front of other lines (output),
+or use different code blocks for commands and output.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+````markdown
+```bash
+echo "Mercury and Venus"
+```
+
+```sh
+echo "Mercury and Venus"
+echo "Earth and Mars" > file
+```
+
+Mixed dollars for input lines and without for output is also OK:
+
+```zsh
+$ echo "Mercury and Venus"
+Mercury and Venus
+$ echo "Earth and Mars" > file
+```
+
+```command
+```
+
+```js
+$('div').remove()
+```
+````
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+````markdown
+```sh
+$ echo "Mercury and Venus"
+```
+
+```bash
+$ echo "Mercury and Venus"
+$ echo "Earth and Mars" > file
+```
+````
+
+###### Out
+
+```text
+1:1-3:4: Unexpected shell code with every line prefixed by `$`, expected different code for input and output
+5:1-8:4: Unexpected shell code with every line prefixed by `$`, expected different code for input and output
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-shell-dollars@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-shell-dollars]: #unifieduseremarklintnoshelldollars
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-shell-dollars.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-shell-dollars
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-shell-dollars
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-shell-dollars
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-shortcut-reference-image_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-shortcut-reference-image_readme.md
new file mode 100644
index 0000000..62faf1a
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-shortcut-reference-image_readme.md
@@ -0,0 +1,251 @@
+<!--This file is generated-->
+
+# remark-lint-no-shortcut-reference-image
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when shortcut reference images are used.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoShortcutReferenceImage)`](#unifieduseremarklintnoshortcutreferenceimage)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks that collapsed or full reference images are used.
+
+## When should I use this?
+
+You can use this package to check that references are consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+| [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-shortcut-reference-image
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoShortcutReferenceImage from 'https://esm.sh/remark-lint-no-shortcut-reference-image@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoShortcutReferenceImage from 'https://esm.sh/remark-lint-no-shortcut-reference-image@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoShortcutReferenceImage from 'remark-lint-no-shortcut-reference-image'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoShortcutReferenceImage)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-shortcut-reference-image .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-shortcut-reference-image",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoShortcutReferenceImage`][api-remark-lint-no-shortcut-reference-image].
+
+### `unified().use(remarkLintNoShortcutReferenceImage)`
+
+Warn when shortcut reference images are used.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+Shortcut references use an implicit style that looks a lot like something
+that could occur as plain text instead of syntax.
+In some cases,
+plain text is intended instead of an image.
+So it’s recommended to use collapsed or full references instead.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+![Mercury][]
+
+[mercury]: /mercury.png
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+![Mercury]
+
+[mercury]: /mercury.png
+```
+
+###### Out
+
+```text
+1:1-1:11: Unexpected shortcut reference image (`![text]`), expected collapsed reference (`![text][]`)
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-shortcut-reference-image@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-shortcut-reference-image]: #unifieduseremarklintnoshortcutreferenceimage
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-shortcut-reference-image.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-shortcut-reference-image
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-shortcut-reference-image
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-shortcut-reference-image
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-shortcut-reference-link_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-shortcut-reference-link_readme.md
new file mode 100644
index 0000000..0b46999
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-shortcut-reference-link_readme.md
@@ -0,0 +1,251 @@
+<!--This file is generated-->
+
+# remark-lint-no-shortcut-reference-link
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when shortcut reference links are used.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoShortcutReferenceLink)`](#unifieduseremarklintnoshortcutreferencelink)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks that collapsed or full reference links are used.
+
+## When should I use this?
+
+You can use this package to check that references are consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+| [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-shortcut-reference-link
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoShortcutReferenceLink from 'https://esm.sh/remark-lint-no-shortcut-reference-link@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoShortcutReferenceLink from 'https://esm.sh/remark-lint-no-shortcut-reference-link@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoShortcutReferenceLink from 'remark-lint-no-shortcut-reference-link'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoShortcutReferenceLink)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-shortcut-reference-link .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-shortcut-reference-link",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoShortcutReferenceLink`][api-remark-lint-no-shortcut-reference-link].
+
+### `unified().use(remarkLintNoShortcutReferenceLink)`
+
+Warn when shortcut reference links are used.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+Shortcut references use an implicit style that looks a lot like something
+that could occur as plain text instead of syntax.
+In some cases,
+plain text is intended instead of a link.
+So it’s recommended to use collapsed or full references instead.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+[Mercury][]
+
+[mercury]: https://example.com/mercury/
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+[Mercury]
+
+[mercury]: https://example.com/mercury/
+```
+
+###### Out
+
+```text
+1:1-1:10: Unexpected shortcut reference link (`[text]`), expected collapsed reference (`[text][]`)
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-shortcut-reference-link@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-shortcut-reference-link]: #unifieduseremarklintnoshortcutreferencelink
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-shortcut-reference-link.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-shortcut-reference-link
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-shortcut-reference-link
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-shortcut-reference-link
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-table-indentation_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-table-indentation_readme.md
new file mode 100644
index 0000000..d6baf99
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-table-indentation_readme.md
@@ -0,0 +1,304 @@
+<!--This file is generated-->
+
+# remark-lint-no-table-indentation
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when GFM tables are indented.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoTableIndentation)`](#unifieduseremarklintnotableindentation)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the indent of GFM tables.
+Tables are a GFM feature enabled with
+[`remark-gfm`][github-remark-gfm].
+
+## When should I use this?
+
+You can use this package to check that tables are consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-table-indentation
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoTableIndentation from 'https://esm.sh/remark-lint-no-table-indentation@5'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoTableIndentation from 'https://esm.sh/remark-lint-no-table-indentation@5?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoTableIndentation from 'remark-lint-no-table-indentation'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoTableIndentation)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-table-indentation .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-table-indentation",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoTableIndentation`][api-remark-lint-no-table-indentation].
+
+### `unified().use(remarkLintNoTableIndentation)`
+
+Warn when GFM tables are indented.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+There is no specific handling of indented tables (or anything else) in
+markdown.
+So it’s recommended to not indent tables and to turn this rule on.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] with
+[`remark-gfm`][github-remark-gfm] formats all tables without indent.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+| Planet | Mean anomaly (°) |
+| ------- | ---------------: |
+| Mercury | 174 796 |
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+␠| Planet | Mean anomaly (°) |
+␠␠| ------- | ---------------: |
+␠␠␠| Mercury | 174 796 |
+```
+
+###### Out
+
+```text
+1:2: Unexpected `1` extra space before table row, remove `1` space
+2:3: Unexpected `2` extra spaces before table row, remove `2` spaces
+3:4: Unexpected `3` extra spaces before table row, remove `3` spaces
+```
+
+##### `blockquote.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+>␠| Planet |
+>␠␠| ------- |
+```
+
+###### Out
+
+```text
+2:4: Unexpected `1` extra space before table row, remove `1` space
+```
+
+##### `list.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+*␠| Planet |
+␠␠␠| ------- |
+```
+
+###### Out
+
+```text
+2:4: Unexpected `1` extra space before table row, remove `1` space
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-table-indentation@5`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-table-indentation]: #unifieduseremarklintnotableindentation
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-table-indentation.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-table-indentation
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-table-indentation
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-table-indentation
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-tabs_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-tabs_readme.md
new file mode 100644
index 0000000..509ff2f
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-tabs_readme.md
@@ -0,0 +1,285 @@
+<!--This file is generated-->
+
+# remark-lint-no-tabs
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when tabs are used.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoTabs)`](#unifieduseremarklintnotabs)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks for tabs.
+
+## When should I use this?
+
+You can use this package to check tabs.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-tabs
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoTabs from 'https://esm.sh/remark-lint-no-tabs@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoTabs from 'https://esm.sh/remark-lint-no-tabs@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoTabs from 'remark-lint-no-tabs'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoTabs)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-tabs .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-tabs",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoTabs`][api-remark-lint-no-tabs].
+
+### `unified().use(remarkLintNoTabs)`
+
+Warn when tabs are used.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+Regardless of the debate in other languages of whether to use tabs versus
+spaces,
+when it comes to markdown,
+tabs do not work as expected.
+Largely around things such as block quotes, lists, and indented code.
+
+Take for example block quotes: `>\ta` gives a paragraph with the text `a`
+in a blockquote,
+so one might expect that `>\t\ta` results in indented code with the text `a`
+in a block quote.
+
+```markdown
+>\ta
+
+>\t\ta
+```
+
+Yields:
+
+```html
+<blockquote>
+<p>a</p>
+</blockquote>
+<blockquote>
+<pre><code> a
+</code></pre>
+</blockquote>
+```
+
+Because markdown uses a hardcoded tab size of 4,
+the first tab could be represented as 3 spaces (because there’s a `>`
+before).
+One of those “spaces” is taken because block quotes allow the `>` to be
+followed by one space,
+leaving 2 spaces.
+The next tab can be represented as 4 spaces,
+so together we have 6 spaces.
+The indented code uses 4 spaces, so there are two spaces left, which are
+shown in the indented code.
+
+## Fix
+
+[`remark-stringify`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify)
+uses spaces exclusively for indentation.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+␠␠␠␠mercury()
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+␉mercury()
+
+Venus␉and Earth.
+```
+
+###### Out
+
+```text
+1:1: Unexpected tab (`\t`), expected spaces
+3:6: Unexpected tab (`\t`), expected spaces
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-tabs@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-tabs]: #unifieduseremarklintnotabs
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-tabs.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-tabs
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-tabs
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-tabs
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-undefined-references_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-undefined-references_readme.md
new file mode 100644
index 0000000..0222452
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-undefined-references_readme.md
@@ -0,0 +1,416 @@
+<!--This file is generated-->
+
+# remark-lint-no-undefined-references
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when undefined definitions are referenced.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoUndefinedReferences[, options])`](#unifieduseremarklintnoundefinedreferences-options)
+ * [`Options`](#options)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks that referenced definitions are defined.
+
+## When should I use this?
+
+You can use this package to check for broken references.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-undefined-references
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoUndefinedReferences from 'https://esm.sh/remark-lint-no-undefined-references@5'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoUndefinedReferences from 'https://esm.sh/remark-lint-no-undefined-references@5?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoUndefinedReferences from 'remark-lint-no-undefined-references'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoUndefinedReferences)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-undefined-references .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-undefined-references",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] type
+[`Options`][api-options].
+The default export is
+[`remarkLintNoUndefinedReferences`][api-remark-lint-no-undefined-references].
+
+### `unified().use(remarkLintNoUndefinedReferences[, options])`
+
+Warn when undefined definitions are referenced.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], optional)
+ — configuration
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Fields
+
+* `allow` (`Array<RegExp | string>`, optional)
+ — list of values to allow between `[` and `]`
+* `allowShortcutLink` (`boolean`, default: `false`)
+ — allow shortcut references, which are just brackets such as `[text]`
+
+## Recommendation
+
+Shortcut references use an implicit syntax that could also occur as plain
+text.
+To illustrate,
+it is reasonable to expect an author adding `[…]` to abbreviate some text
+somewhere in a document:
+
+```markdown
+> Some […] quote.
+```
+
+This isn’t a problem,
+but it might become one when an author later adds a definition:
+
+```markdown
+Some new text […][].
+
+[…]: #read-more
+```
+
+The second author might expect only their newly added text to form a link,
+but their changes also result in a link for the text by the first author.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+[Mercury][] is the first planet from the Sun and the smallest in the Solar
+System.
+
+Venus is the second planet from the [Sun.
+
+Earth is the third planet from the \[Sun] and the only astronomical object
+known to harbor life\.
+
+Mars is the fourth planet from the Sun: [].
+
+[mercury]: https://example.com/mercury/
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+[Mercury] is the first planet from the Sun and the smallest in the Solar
+System.
+
+[Venus][] is the second planet from the Sun.
+
+[Earth][earth] is the third planet from the Sun and the only astronomical
+object known to harbor life.
+
+![Mars] is the fourth planet from the Sun in the [Solar
+System].
+
+> Jupiter is the fifth planet from the Sun and the largest in the [Solar
+> System][].
+
+[Saturn][ is the sixth planet from the Sun and the second-largest
+in the Solar System, after Jupiter.
+
+[*Uranus*][] is the seventh planet from the Sun.
+
+[Neptune][neptune][more] is the eighth and farthest planet from the Sun.
+```
+
+###### Out
+
+```text
+1:1-1:10: Unexpected reference to undefined definition, expected corresponding definition (`mercury`) for a link or escaped opening bracket (`\[`) for regular text
+4:1-4:10: Unexpected reference to undefined definition, expected corresponding definition (`venus`) for a link or escaped opening bracket (`\[`) for regular text
+6:1-6:15: Unexpected reference to undefined definition, expected corresponding definition (`earth`) for a link or escaped opening bracket (`\[`) for regular text
+9:2-9:8: Unexpected reference to undefined definition, expected corresponding definition (`mars`) for an image or escaped opening bracket (`\[`) for regular text
+9:50-10:8: Unexpected reference to undefined definition, expected corresponding definition (`solar system`) for a link or escaped opening bracket (`\[`) for regular text
+12:67-13:12: Unexpected reference to undefined definition, expected corresponding definition (`solar > system`) for a link or escaped opening bracket (`\[`) for regular text
+15:1-15:9: Unexpected reference to undefined definition, expected corresponding definition (`saturn`) for a link or escaped opening bracket (`\[`) for regular text
+18:1-18:13: Unexpected reference to undefined definition, expected corresponding definition (`*uranus*`) for a link or escaped opening bracket (`\[`) for regular text
+20:1-20:19: Unexpected reference to undefined definition, expected corresponding definition (`neptune`) for a link or escaped opening bracket (`\[`) for regular text
+20:19-20:25: Unexpected reference to undefined definition, expected corresponding definition (`more`) for a link or escaped opening bracket (`\[`) for regular text
+```
+
+##### `ok-allow.md`
+
+When configured with `{ allow: [ '…' ] }`.
+
+###### In
+
+```markdown
+Mercury is the first planet from the Sun and the smallest in the Solar
+System. […]
+```
+
+###### Out
+
+No messages.
+
+##### `source.md`
+
+When configured with `{ allow: [ { source: '^mer' }, 'venus' ] }`.
+
+###### In
+
+```markdown
+[Mercury][] is the first planet from the Sun and the smallest in the Solar
+System.
+
+[Venus][] is the second planet from the Sun.
+```
+
+###### Out
+
+No messages.
+
+##### `gfm.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+Mercury[^mercury] is the first planet from the Sun and the smallest in the
+Solar System.
+
+[^venus]:
+ **Venus** is the second planet from the Sun.
+```
+
+###### Out
+
+```text
+1:8-1:18: Unexpected reference to undefined definition, expected corresponding definition (`mercury`) for a footnote or escaped opening bracket (`\[`) for regular text
+```
+
+##### `gfm-table.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+| [Planet] | [Radius] |
+| ----------------- | --------- |
+| [Mercury] | 2439.7 km |
+
+[planet]: https://example.com/planet/
+```
+
+###### Out
+
+```text
+1:23-1:31: Unexpected reference to undefined definition, expected corresponding definition (`radius`) for a link or escaped opening bracket (`\[`) for regular text
+3:3-3:12: Unexpected reference to undefined definition, expected corresponding definition (`mercury`) for a link or escaped opening bracket (`\[`) for regular text
+```
+
+##### `allow-shortcut-link.md`
+
+When configured with `{ allowShortcutLink: true }`.
+
+###### In
+
+```markdown
+[Mercury] is the first planet from the Sun and the smallest in the Solar
+System.
+
+[Venus][] is the second planet from the Sun.
+
+[Earth][earth] is the third planet from the Sun and the only astronomical object
+known to harbor life.
+```
+
+###### Out
+
+```text
+4:1-4:10: Unexpected reference to undefined definition, expected corresponding definition (`venus`) for a link or escaped opening bracket (`\[`) for regular text
+6:1-6:15: Unexpected reference to undefined definition, expected corresponding definition (`earth`) for a link or escaped opening bracket (`\[`) for regular text
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-undefined-references@5`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-options]: #options
+
+[api-remark-lint-no-undefined-references]: #unifieduseremarklintnoundefinedreferences-options
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-undefined-references.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-undefined-references
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-undefined-references
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-undefined-references
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-unneeded-full-reference-image_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-unneeded-full-reference-image_readme.md
new file mode 100644
index 0000000..735cce7
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-unneeded-full-reference-image_readme.md
@@ -0,0 +1,280 @@
+<!--This file is generated-->
+
+# remark-lint-no-unneeded-full-reference-image
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when unneeded full reference images are used.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoUnneededFullReferenceImage)`](#unifieduseremarklintnounneededfullreferenceimage)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks for unneeded full reference images.
+
+## When should I use this?
+
+You can use this package to check that reference images are consistent.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-unneeded-full-reference-image
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoUnneededFullReferenceImage from 'https://esm.sh/remark-lint-no-unneeded-full-reference-image@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoUnneededFullReferenceImage from 'https://esm.sh/remark-lint-no-unneeded-full-reference-image@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoUnneededFullReferenceImage from 'remark-lint-no-unneeded-full-reference-image'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoUnneededFullReferenceImage)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-unneeded-full-reference-image .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-unneeded-full-reference-image",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoUnneededFullReferenceImage`][api-remark-lint-no-unneeded-full-reference-image].
+
+### `unified().use(remarkLintNoUnneededFullReferenceImage)`
+
+Warn when unneeded full reference images are used.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+Full reference syntax (`![Alt][alt]`) is quite verbose compared to
+the concise collapsed reference syntax (`![Alt][]`).
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+![Mercury][] and ![Venus][venus-image].
+
+[mercury]: /mercury.png
+[venus-image]: /venus.png
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+![Mercury][mercury].
+
+[mercury]: /mercury.png
+```
+
+###### Out
+
+```text
+1:1-1:20: Unexpected full reference image (`![text][label]`) where the identifier can be inferred from the text, expected collapsed reference (`![text][]`)
+```
+
+##### `escape.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+Matrix:
+
+| Kind | Text normal | Text escape | Text character reference |
+| ------------------------- | ----------- | ------------ | ------------------------ |
+| Label normal | ![&][&] | ![\&][&] | ![&][&] |
+| Label escape | ![&][\&] | ![\&][\&] | ![&][\&] |
+| Label character reference | ![&][&] | ![\&][&] | ![&][&] |
+
+When using the above matrix, the first row will go to `/a.png`, the second
+to `b`, third to `c`.
+Removing all labels, you’d instead get it per column: `/a.png`, `b`, `c`.
+That shows the label is not needed when it matches the text, and is otherwise.
+
+[&]: /a.png
+[\&]: /b.png
+[&]: /c.png
+```
+
+###### Out
+
+```text
+5:31-5:38: Unexpected full reference image (`![text][label]`) where the identifier can be inferred from the text, expected collapsed reference (`![text][]`)
+6:45-6:54: Unexpected full reference image (`![text][label]`) where the identifier can be inferred from the text, expected collapsed reference (`![text][]`)
+7:60-7:75: Unexpected full reference image (`![text][label]`) where the identifier can be inferred from the text, expected collapsed reference (`![text][]`)
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-unneeded-full-reference-image@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-unneeded-full-reference-image]: #unifieduseremarklintnounneededfullreferenceimage
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-unneeded-full-reference-image.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-unneeded-full-reference-image
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-unneeded-full-reference-image
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-unneeded-full-reference-image
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-unneeded-full-reference-link_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-unneeded-full-reference-link_readme.md
new file mode 100644
index 0000000..49a6c9f
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-unneeded-full-reference-link_readme.md
@@ -0,0 +1,280 @@
+<!--This file is generated-->
+
+# remark-lint-no-unneeded-full-reference-link
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when unneeded full reference links are used.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoUnneededFullReferenceLink)`](#unifieduseremarklintnounneededfullreferencelink)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks for unneeded full reference links.
+
+## When should I use this?
+
+You can use this package to check that reference links are consistent.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-unneeded-full-reference-link
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoUnneededFullReferenceLink from 'https://esm.sh/remark-lint-no-unneeded-full-reference-link@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoUnneededFullReferenceLink from 'https://esm.sh/remark-lint-no-unneeded-full-reference-link@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoUnneededFullReferenceLink from 'remark-lint-no-unneeded-full-reference-link'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoUnneededFullReferenceLink)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-unneeded-full-reference-link .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-unneeded-full-reference-link",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoUnneededFullReferenceLink`][api-remark-lint-no-unneeded-full-reference-link].
+
+### `unified().use(remarkLintNoUnneededFullReferenceLink)`
+
+Warn when unneeded full reference links are used.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+Full reference syntax (`[Text][text]`) is quite verbose compared to
+the concise collapsed reference syntax (`[Text][]`).
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+[Mercury][] and [Venus][venus-url].
+
+[mercury]: https://example.com/mercury/
+[venus-url]: https://example.com/venus/
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+[Mercury][mercury].
+
+[mercury]: https://example.com/mercury/
+```
+
+###### Out
+
+```text
+1:1-1:19: Unexpected full reference link (`[text][label]`) where the identifier can be inferred from the text, expected collapsed reference (`[text][]`)
+```
+
+##### `escape.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+Matrix:
+
+| Kind | Text normal | Text escape | Text character reference |
+| ------------------------- | ----------- | ------------ | ------------------------ |
+| Label normal | [&][&] | [\&][&] | [&][&] |
+| Label escape | [&][\&] | [\&][\&] | [&][\&] |
+| Label character reference | [&][&] | [\&][&] | [&][&] |
+
+When using the above matrix, the first row will go to `a`, the second
+to `b`, third to `c`.
+Removing all labels, you’d instead get it per column: `a`, `b`, `c`.
+That shows the label is not needed when it matches the text, and is otherwise.
+
+[&]: a
+[\&]: b
+[&]: c
+```
+
+###### Out
+
+```text
+5:31-5:37: Unexpected full reference link (`[text][label]`) where the identifier can be inferred from the text, expected collapsed reference (`[text][]`)
+6:45-6:53: Unexpected full reference link (`[text][label]`) where the identifier can be inferred from the text, expected collapsed reference (`[text][]`)
+7:60-7:74: Unexpected full reference link (`[text][label]`) where the identifier can be inferred from the text, expected collapsed reference (`[text][]`)
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-unneeded-full-reference-link@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-unneeded-full-reference-link]: #unifieduseremarklintnounneededfullreferencelink
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-unneeded-full-reference-link.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-unneeded-full-reference-link
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-unneeded-full-reference-link
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-unneeded-full-reference-link
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-no-unused-definitions_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-no-unused-definitions_readme.md
new file mode 100644
index 0000000..0d96aff
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-no-unused-definitions_readme.md
@@ -0,0 +1,270 @@
+<!--This file is generated-->
+
+# remark-lint-no-unused-definitions
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when unreferenced definitions are used.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintNoUnusedDefinitions)`](#unifieduseremarklintnounuseddefinitions)
+* [Recommendation](#recommendation)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks that definitions are referenced.
+
+## When should I use this?
+
+You can use this package to check definitions.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-no-unused-definitions
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintNoUnusedDefinitions from 'https://esm.sh/remark-lint-no-unused-definitions@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintNoUnusedDefinitions from 'https://esm.sh/remark-lint-no-unused-definitions@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintNoUnusedDefinitions from 'remark-lint-no-unused-definitions'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintNoUnusedDefinitions)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-no-unused-definitions .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-no-unused-definitions",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintNoUnusedDefinitions`][api-remark-lint-no-unused-definitions].
+
+### `unified().use(remarkLintNoUnusedDefinitions)`
+
+Warn when unreferenced definitions are used.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+Unused definitions do not contribute anything, so they can be removed.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+[Mercury][]
+
+[mercury]: https://example.com/mercury/
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+[mercury]: https://example.com/mercury/
+```
+
+###### Out
+
+```text
+1:1-1:40: Unexpected unused definition, expected no definition or one or more references to `mercury`
+```
+
+##### `gfm.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+Mercury[^mercury] is a planet.
+
+[^Mercury]:
+ **Mercury** is the first planet from the Sun and the smallest
+ in the Solar System.
+[^Venus]:
+ **Venus** is the second planet from
+ the Sun.
+```
+
+###### Out
+
+```text
+6:1-8:13: Unexpected unused footnote definition, expected no definition or one or more footnote references to `venus`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-no-unused-definitions@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-no-unused-definitions]: #unifieduseremarklintnounuseddefinitions
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-no-unused-definitions.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-no-unused-definitions
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-no-unused-definitions
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-no-unused-definitions
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-ordered-list-marker-style_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-ordered-list-marker-style_readme.md
new file mode 100644
index 0000000..6b4c7d0
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-ordered-list-marker-style_readme.md
@@ -0,0 +1,330 @@
+<!--This file is generated-->
+
+# remark-lint-ordered-list-marker-style
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when ordered list markers are inconsistent.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintOrderedListMarkerStyle[, options])`](#unifieduseremarklintorderedlistmarkerstyle-options)
+ * [`Options`](#options)
+ * [`Style`](#style)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks ordered list markers.
+
+## When should I use this?
+
+You can use this package to check ordered lists.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | `'consistent'` |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `'.'` |
+| [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | `'.'` |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-ordered-list-marker-style
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintOrderedListMarkerStyle from 'https://esm.sh/remark-lint-ordered-list-marker-style@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintOrderedListMarkerStyle from 'https://esm.sh/remark-lint-ordered-list-marker-style@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintOrderedListMarkerStyle from 'remark-lint-ordered-list-marker-style'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintOrderedListMarkerStyle)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-ordered-list-marker-style .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-ordered-list-marker-style",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] types
+[`Options`][api-options] and
+[`Style`][api-style].
+The default export is
+[`remarkLintOrderedListMarkerStyle`][api-remark-lint-ordered-list-marker-style].
+
+### `unified().use(remarkLintOrderedListMarkerStyle[, options])`
+
+Warn when ordered list markers are inconsistent.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], default: `'consistent'`)
+ — preferred style or whether to detect the first style and warn for
+ further differences
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Type
+
+```ts
+type Options = Style | 'consistent'
+```
+
+### `Style`
+
+Style (TypeScript type).
+
+###### Type
+
+```ts
+type Style = '.' | ')'
+```
+
+## Recommendation
+
+Parens for list markers were not supported in markdown before CommonMark.
+While they should work in most places now,
+not all markdown parsers follow CommonMark.
+So it’s recommended to prefer dots.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] formats ordered lists with
+dots by default.
+Pass `bulletOrdered: ')'` to always use parens.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+1. Mercury
+
+* Venus
+
+1. Earth
+```
+
+###### Out
+
+No messages.
+
+##### `ok.md`
+
+When configured with `'.'`.
+
+###### In
+
+```markdown
+1. Mercury
+```
+
+###### Out
+
+No messages.
+
+##### `ok.md`
+
+When configured with `')'`.
+
+###### In
+
+```markdown
+1) Mercury
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+1. Mercury
+
+1) Venus
+```
+
+###### Out
+
+```text
+3:2: Unexpected ordered list marker `)`, expected `.`
+```
+
+##### `not-ok.md`
+
+When configured with `'🌍'`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `options`, expected `'.'`, `')'`, or `'consistent'`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-ordered-list-marker-style@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-options]: #options
+
+[api-remark-lint-ordered-list-marker-style]: #unifieduseremarklintorderedlistmarkerstyle-options
+
+[api-style]: #style
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-ordered-list-marker-style.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-ordered-list-marker-style
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-ordered-list-marker-style
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-ordered-list-marker-style
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-ordered-list-marker-value_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-ordered-list-marker-value_readme.md
new file mode 100644
index 0000000..69ff211
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-ordered-list-marker-value_readme.md
@@ -0,0 +1,484 @@
+<!--This file is generated-->
+
+# remark-lint-ordered-list-marker-value
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when ordered list values are inconsistent.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintOrderedListMarkerValue[, options])`](#unifieduseremarklintorderedlistmarkervalue-options)
+ * [`Options`](#options)
+ * [`Style`](#style)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks ordered list values.
+
+## When should I use this?
+
+You can use this package to check ordered lists.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | `'consistent'` |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `'one'` |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-ordered-list-marker-value
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintOrderedListMarkerValue from 'https://esm.sh/remark-lint-ordered-list-marker-value@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintOrderedListMarkerValue from 'https://esm.sh/remark-lint-ordered-list-marker-value@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintOrderedListMarkerValue from 'remark-lint-ordered-list-marker-value'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintOrderedListMarkerValue)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-ordered-list-marker-value .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-ordered-list-marker-value",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] types
+[`Options`][api-options] and
+[`Style`][api-style].
+The default export is
+[`remarkLintOrderedListMarkerValue`][api-remark-lint-ordered-list-marker-value].
+
+### `unified().use(remarkLintOrderedListMarkerValue[, options])`
+
+Warn when ordered list values are inconsistent.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], default: `'consistent'`)
+ — preferred style
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+`consistent` looks at the first list with two or more items, and
+infer `'single'` if both are the same, and `'ordered'` otherwise.
+
+###### Type
+
+```ts
+type Options = Style | 'consistent'
+```
+
+### `Style`
+
+Counter style (TypeScript type).
+
+* `'one'`
+ — values should always be exactly `1`
+* `'ordered'`
+ — values should increment by one from the first item
+* `'single'`
+ — values should stay the same as the first item
+
+###### Type
+
+```ts
+type Style = 'one' | 'ordered' | 'single'
+```
+
+## Recommendation
+
+While `'single'` might be the smartest style,
+as it makes it easier to move items around without having to renumber
+everything and doesn’t have problems with aligning content of the 9th and
+the 10th item,
+it’s not used a lot and arguably looks unnatural.
+`'one'` is like `'single'` but forces every list to start at `1`.
+While not often needed,
+starting lists at other values is sometimes useful.
+So `'ordered'` is recommended,
+although `'single'` is also a viable choice.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] retains the value of the first
+item and increments further items by default.
+Pass `incrementListMarker: false` to not increment further items.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+1. Mercury
+2. Venus
+
+***
+
+3. Earth
+4. Mars
+
+***
+
+* Jupiter
+```
+
+###### Out
+
+No messages.
+
+##### `ok-infer-single.md`
+
+###### In
+
+```markdown
+2. Mercury
+2. Venus
+
+***
+
+3. Earth
+3. Mars
+```
+
+###### Out
+
+No messages.
+
+##### `nok-chaotic.md`
+
+###### In
+
+```markdown
+2. Mercury
+1. Venus
+
+***
+
+1. Earth
+1. Mars
+```
+
+###### Out
+
+```text
+2:2: Unexpected ordered list item value `1`, expected `3`
+7:2: Unexpected ordered list item value `1`, expected `2`
+```
+
+##### `ok.md`
+
+When configured with `'one'`.
+
+###### In
+
+```markdown
+1. Mercury
+1. Venus
+```
+
+###### Out
+
+No messages.
+
+##### `ok.md`
+
+When configured with `'ordered'`.
+
+###### In
+
+```markdown
+1. Mercury
+2. Venus
+
+***
+
+3. Earth
+4. Mars
+
+***
+
+0. Jupiter
+1. Saturn
+```
+
+###### Out
+
+No messages.
+
+##### `ok.md`
+
+When configured with `'single'`.
+
+###### In
+
+```markdown
+1. Mercury
+1. Venus
+
+***
+
+3. Earth
+3. Mars
+
+***
+
+0. Jupiter
+0. Saturn
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+When configured with `'one'`.
+
+###### In
+
+```markdown
+1. Mercury
+2. Venus
+
+***
+
+3. Earth
+
+***
+
+2. Mars
+1. Jupiter
+```
+
+###### Out
+
+```text
+2:2: Unexpected ordered list item value `2`, expected `1`
+6:2: Unexpected ordered list item value `3`, expected `1`
+10:2: Unexpected ordered list item value `2`, expected `1`
+```
+
+##### `not-ok.md`
+
+When configured with `'ordered'`.
+
+###### In
+
+```markdown
+1. Mercury
+1. Venus
+
+***
+
+2. Mars
+1. Jupiter
+```
+
+###### Out
+
+```text
+2:2: Unexpected ordered list item value `1`, expected `2`
+7:2: Unexpected ordered list item value `1`, expected `3`
+```
+
+##### `not-ok.md`
+
+When configured with `'single'`.
+
+###### In
+
+```markdown
+1. Mercury
+2. Venus
+
+***
+
+2. Mars
+1. Jupiter
+```
+
+###### Out
+
+```text
+2:2: Unexpected ordered list item value `2`, expected `1`
+7:2: Unexpected ordered list item value `1`, expected `2`
+```
+
+##### `not-ok.md`
+
+When configured with `'🌍'`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `options`, expected `'one'`, `'ordered'`, `'single'`, or `'consistent'`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-ordered-list-marker-value@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-options]: #options
+
+[api-remark-lint-ordered-list-marker-value]: #unifieduseremarklintorderedlistmarkervalue-options
+
+[api-style]: #style
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-ordered-list-marker-value.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-ordered-list-marker-value
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-ordered-list-marker-value
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-ordered-list-marker-value
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-rule-style_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-rule-style_readme.md
new file mode 100644
index 0000000..49e9e83
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-rule-style_readme.md
@@ -0,0 +1,317 @@
+<!--This file is generated-->
+
+# remark-lint-rule-style
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when thematic breaks (horizontal rules) are
+inconsistent.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintRuleStyle[, options])`](#unifieduseremarklintrulestyle-options)
+ * [`Options`](#options)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks markers and whitespace of thematic rules.
+
+## When should I use this?
+
+You can use this package to check that thematic breaks are consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | `'consistent'` |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `'---'` |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-rule-style
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintRuleStyle from 'https://esm.sh/remark-lint-rule-style@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintRuleStyle from 'https://esm.sh/remark-lint-rule-style@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintRuleStyle from 'remark-lint-rule-style'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintRuleStyle)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-rule-style .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-rule-style",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] type
+[`Options`][api-options].
+The default export is
+[`remarkLintRuleStyle`][api-remark-lint-rule-style].
+
+### `unified().use(remarkLintRuleStyle[, options])`
+
+Warn when thematic breaks (horizontal rules) are inconsistent.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], default: `'consistent'`)
+ — preferred style or whether to detect the first style and warn for
+ further differences
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+* `'consistent'`
+ — detect the first used style and warn when further rules differ
+* `string` (example: `'** * **'`, `'___'`)
+ — thematic break to prefer
+
+###### Type
+
+```ts
+type Options = string | 'consistent'
+```
+
+## Recommendation
+
+Rules consist of a `*`, `-`, or `_` character,
+which occurs at least three times with nothing else except for arbitrary
+spaces or tabs on a single line.
+Using spaces, tabs, or more than three markers is unnecessary work to type
+out.
+As asterisks can be used as a marker for more markdown constructs,
+it’s recommended to use that for rules (and lists, emphasis, strong) too.
+So it’s recommended to pass `'***'`.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] formats rules with `***` by
+default.
+There are three settings to control rules:
+
+* `rule` (default: `'*'`) — marker
+* `ruleRepetition` (default: `3`) — repetitions
+* `ruleSpaces` (default: `false`) — use spaces between markers
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+Two rules:
+
+* * *
+
+* * *
+```
+
+###### Out
+
+No messages.
+
+##### `ok.md`
+
+When configured with `'_______'`.
+
+###### In
+
+```markdown
+_______
+
+_______
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+***
+
+* * *
+```
+
+###### Out
+
+```text
+3:1-3:6: Unexpected thematic rule `* * *`, expected `***`
+```
+
+##### `not-ok.md`
+
+When configured with `'🌍'`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `options`, expected thematic rule or `'consistent'`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-rule-style@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-options]: #options
+
+[api-remark-lint-rule-style]: #unifieduseremarklintrulestyle-options
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-rule-style.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-rule-style
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-rule-style
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-rule-style
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-strikethrough-marker_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-strikethrough-marker_readme.md
new file mode 100644
index 0000000..3a4b15d
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-strikethrough-marker_readme.md
@@ -0,0 +1,356 @@
+<!--This file is generated-->
+
+# remark-lint-strikethrough-marker
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when the number of GFM strikethrough markers are
+inconsistent.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintStrikethroughMarker[, options])`](#unifieduseremarklintstrikethroughmarker-options)
+ * [`Marker`](#marker)
+ * [`Options`](#options)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the number of strikethrough markers.
+Strikethrough is a GFM feature enabled with
+[`remark-gfm`][github-remark-gfm].
+
+## When should I use this?
+
+You can use this package to check that GFM strikethrough is consistent.
+
+## Presets
+
+This plugin is not included in presets maintained here.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-strikethrough-marker
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintStrikethroughMarker from 'https://esm.sh/remark-lint-strikethrough-marker@3'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintStrikethroughMarker from 'https://esm.sh/remark-lint-strikethrough-marker@3?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintStrikethroughMarker from 'remark-lint-strikethrough-marker'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintStrikethroughMarker)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-strikethrough-marker .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-strikethrough-marker",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] types
+[`Marker`][api-marker] and
+[`Options`][api-options].
+The default export is
+[`remarkLintStrikethroughMarker`][api-remark-lint-strikethrough-marker].
+
+### `unified().use(remarkLintStrikethroughMarker[, options])`
+
+Warn when the number of GFM strikethrough markers are inconsistent.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], default: `'consistent'`)
+ — preferred style or whether to detect the first style and warn for
+ further differences
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Marker`
+
+Marker (TypeScript type).
+
+###### Type
+
+```ts
+type Marker = '~~' | '~'
+```
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Type
+
+```ts
+type Options = Marker | 'consistent'
+```
+
+## Recommendation
+
+GitHub flavored markdown (GFM) specifies that two tildes should be used,
+but `github.com` allows one tilde everywhere.
+It’s recommended to use two tildes.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] with
+[`remark-gfm`][github-remark-gfm] formats all strikethrough with two tildes.
+
+## Examples
+
+##### `not-ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+~Mercury~Venus and ~~Earth~~Mars.
+```
+
+###### Out
+
+```text
+1:20-1:29: Unexpected double tilde strikethrough sequences (`~~`), expected single tilde (`~`)
+```
+
+##### `ok.md`
+
+When configured with `'~'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+~Mercury~Venus.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+When configured with `'~'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+~~Mercury~~Venus.
+```
+
+###### Out
+
+```text
+1:1-1:12: Unexpected double tilde strikethrough sequences (`~~`), expected single tilde (`~`)
+```
+
+##### `ok.md`
+
+When configured with `'~~'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+~~Mercury~~Venus.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+When configured with `'~~'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+~Mercury~Venus.
+```
+
+###### Out
+
+```text
+1:1-1:10: Unexpected single tilde strikethrough sequences (`~`), expected double tilde (`~~`)
+```
+
+##### `not-ok.md`
+
+When configured with `'🌍'`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `options`, expected `'~~'`, `'~'`, or `'consistent'`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-strikethrough-marker@3`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-marker]: #marker
+
+[api-options]: #options
+
+[api-remark-lint-strikethrough-marker]: #unifieduseremarklintstrikethroughmarker-options
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-strikethrough-marker.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-strikethrough-marker
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-strikethrough-marker
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-strikethrough-marker
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-strong-marker_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-strong-marker_readme.md
new file mode 100644
index 0000000..3cfeb00
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-strong-marker_readme.md
@@ -0,0 +1,352 @@
+<!--This file is generated-->
+
+# remark-lint-strong-marker
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when strong markers are inconsistent.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintStrongMarker[, options])`](#unifieduseremarklintstrongmarker-options)
+ * [`Marker`](#marker)
+ * [`Options`](#options)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks the style of strong markers.
+
+## When should I use this?
+
+You can use this package to check that strong is consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | `'consistent'` |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `'*'` |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-strong-marker
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintStrongMarker from 'https://esm.sh/remark-lint-strong-marker@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintStrongMarker from 'https://esm.sh/remark-lint-strong-marker@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintStrongMarker from 'remark-lint-strong-marker'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintStrongMarker)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-strong-marker .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-strong-marker",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] types
+[`Marker`][api-marker] and
+[`Options`][api-options].
+The default export is
+[`remarkLintStrongMarker`][api-remark-lint-strong-marker].
+
+### `unified().use(remarkLintStrongMarker[, options])`
+
+Warn when strong markers are inconsistent.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], default: `'consistent'`)
+ — preferred style or whether to detect the first style and warn for
+ further differences
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Marker`
+
+Marker (TypeScript type).
+
+###### Type
+
+```ts
+type Marker = '*' | '_'
+```
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Type
+
+```ts
+type Options = Marker | 'consistent'
+```
+
+## Recommendation
+
+Whether asterisks or underscores are used affects how and whether strong
+works.
+Underscores are sometimes used to represent normal underscores inside words,
+so there are extra rules in markdown to support that.
+Asterisks are not used in natural language,
+so they don’t need these rules,
+and thus can form strong in more cases.
+Asterisks can also be used as the marker of more constructs than underscores:
+lists.
+Due to having simpler parsing rules,
+looking more like syntax,
+and that they can be used for more constructs,
+it’s recommended to prefer asterisks.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] formats strong with asterisks
+by default.
+Pass `strong: '_'` to always use underscores.
+
+## Examples
+
+##### `ok-asterisk.md`
+
+When configured with `'*'`.
+
+###### In
+
+```markdown
+**Mercury**.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok-asterisk.md`
+
+When configured with `'*'`.
+
+###### In
+
+```markdown
+__Mercury__.
+```
+
+###### Out
+
+```text
+1:1-1:12: Unexpected strong marker `_`, expected `*`
+```
+
+##### `ok-underscore.md`
+
+When configured with `'_'`.
+
+###### In
+
+```markdown
+__Mercury__.
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok-underscore.md`
+
+When configured with `'_'`.
+
+###### In
+
+```markdown
+**Mercury**.
+```
+
+###### Out
+
+```text
+1:1-1:12: Unexpected strong marker `*`, expected `_`
+```
+
+##### `not-ok-consistent.md`
+
+###### In
+
+```markdown
+**Mercury** and __Venus__.
+```
+
+###### Out
+
+```text
+1:17-1:26: Unexpected strong marker `_`, expected `*`
+```
+
+##### `not-ok.md`
+
+When configured with `'🌍'`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `options`, expected `'*'`, `'_'`, or `'consistent'`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-strong-marker@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-marker]: #marker
+
+[api-options]: #options
+
+[api-remark-lint-strong-marker]: #unifieduseremarklintstrongmarker-options
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-strong-marker.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-strong-marker
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-strong-marker
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-strong-marker
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-table-cell-padding_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-table-cell-padding_readme.md
new file mode 100644
index 0000000..907262f
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-table-cell-padding_readme.md
@@ -0,0 +1,814 @@
+<!--This file is generated-->
+
+# remark-lint-table-cell-padding
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when GFM table cells are padded inconsistently.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintTableCellPadding[, options])`](#unifieduseremarklinttablecellpadding-options)
+ * [`Options`](#options)
+ * [`Style`](#style)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks table cell padding.
+Tables are a GFM feature enabled with [`remark-gfm`][github-remark-gfm].
+
+## When should I use this?
+
+You can use this package to check that tables are consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | `'consistent'` |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `'padded'` |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-table-cell-padding
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintTableCellPadding from 'https://esm.sh/remark-lint-table-cell-padding@5'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintTableCellPadding from 'https://esm.sh/remark-lint-table-cell-padding@5?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintTableCellPadding from 'remark-lint-table-cell-padding'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintTableCellPadding)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-table-cell-padding .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-table-cell-padding",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] types
+[`Options`][api-options] and
+[`Style`][api-style].
+The default export is
+[`remarkLintTableCellPadding`][api-remark-lint-table-cell-padding].
+
+### `unified().use(remarkLintTableCellPadding[, options])`
+
+Warn when GFM table cells are padded inconsistently.
+
+###### Parameters
+
+* `options`
+ ([`Options`][api-options], [`Style`][api-style], or `'consistent'`,
+ default: `'consistent'`)
+ — configuration
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Properties
+
+* `stringLength` (`(value: string) => number`, optional)
+ — function to detect cell size
+* `style` ([`Style`][api-style] or `'consistent'`, optional)
+ — preferred style or whether to detect the first style
+
+### `Style`
+
+Style (TypeScript type).
+
+* `'compact'`
+ — prefer zero spaces between pipes and content
+* `'padded'`
+ — prefer at least one space between pipes and content
+
+###### Type
+
+```ts
+type Style = 'compact' | 'padded'
+```
+
+## Recommendation
+
+It’s recommended to use at least one space between pipes and content for
+legibility of the markup (`'padded'`).
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] with
+[`remark-gfm`][github-remark-gfm] formats all table cells as padded by
+default.
+Pass `tableCellPadding: false` to use a more compact style.
+
+Aligning perfectly in all cases is not possible because whether characters
+look aligned or not depends on where the markup is shown.
+Some characters (such as emoji or Chinese characters) show smaller or bigger
+in different places.
+You can pass a `stringLength` function to `remark-gfm`,
+to align better for your use case,
+in which case this rule must be configured with the same `stringLength`.
+
+## Examples
+
+##### `ok.md`
+
+When configured with `'padded'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+| Planet | Symbol | Satellites | Mean anomaly (°) |
+| ------- | :----- | :--------: | ---------------: |
+| Mercury | ☿ | None | 174 796 |
+
+| Planet | Symbol | Satellites | Mean anomaly (°) |
+| - | :- | :-: | -: |
+| Venus | ♀ | None | 50 115 |
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+When configured with `'padded'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+| Planet |
+| -------|
+| Mercury|
+
+|Planet |
+|------ |
+|Venus |
+
+| Planet |
+| ------ |
+| Venus |
+```
+
+###### Out
+
+```text
+2:10: Unexpected `0` spaces between cell content and edge, expected `1` space, add `1` space
+3:10: Unexpected `0` spaces between cell content and edge, expected `1` space, add `1` space
+5:2: Unexpected `0` spaces between cell edge and content, expected `1` space, add `1` space
+6:2: Unexpected `0` spaces between cell edge and content, expected `1` space, add `1` space
+7:2: Unexpected `0` spaces between cell edge and content, expected `1` space, add `1` space
+9:4: Unexpected `2` spaces between cell edge and content, expected `1` space, remove `1` space
+9:12: Unexpected `2` spaces between cell content and edge, expected `1` space, remove `1` space
+10:4: Unexpected `2` spaces between cell edge and content, expected `1` space, remove `1` space
+10:12: Unexpected `2` spaces between cell content and edge, expected `1` space, remove `1` space
+11:4: Unexpected `2` spaces between cell edge and content, expected `1` space, remove `1` space
+11:12: Unexpected `3` spaces between cell content and edge, expected between `1` (unaligned) and `2` (aligned) spaces, remove between `1` and `2` spaces
+```
+
+##### `ok.md`
+
+When configured with `'compact'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+|Planet |Symbol|Satellites|Mean anomaly (°)|
+|-------|:-----|:--------:|---------------:|
+|Mercury|☿ | None | 174 796|
+
+|Planet|Symbol|Satellites|Mean anomaly (°)|
+|-|:-|:-:|-:|
+|Venus|♀|None|50 115|
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+When configured with `'compact'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+| Planet |
+| -------|
+| Mercury|
+
+|Planet |
+|------ |
+|Venus |
+
+| Planet |
+| ------ |
+| Venus |
+```
+
+###### Out
+
+```text
+1:3: Unexpected `1` space between cell edge and content, expected `0` spaces, remove `1` space
+2:3: Unexpected `1` space between cell edge and content, expected `0` spaces, remove `1` space
+3:3: Unexpected `1` space between cell edge and content, expected `0` spaces, remove `1` space
+5:9: Unexpected `1` space between cell content and edge, expected `0` spaces, remove `1` space
+6:9: Unexpected `1` space between cell content and edge, expected `0` spaces, remove `1` space
+7:9: Unexpected `2` spaces between cell content and edge, expected between `0` (unaligned) and `1` (aligned) space, remove between `1` and `2` spaces
+9:4: Unexpected `2` spaces between cell edge and content, expected `0` spaces, remove `2` spaces
+9:12: Unexpected `2` spaces between cell content and edge, expected `0` spaces, remove `2` spaces
+10:4: Unexpected `2` spaces between cell edge and content, expected `0` spaces, remove `2` spaces
+10:12: Unexpected `2` spaces between cell content and edge, expected `0` spaces, remove `2` spaces
+11:4: Unexpected `2` spaces between cell edge and content, expected `0` spaces, remove `2` spaces
+11:12: Unexpected `3` spaces between cell content and edge, expected between `0` (unaligned) and `1` (aligned) space, remove between `2` and `3` spaces
+```
+
+##### `consistent-padded-ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+| Planet |
+| - |
+```
+
+###### Out
+
+No messages.
+
+##### `consistent-padded-nok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+| Planet|
+| - |
+```
+
+###### Out
+
+```text
+1:9: Unexpected `0` spaces between cell content and edge, expected `1` space, add `1` space
+```
+
+##### `consistent-compact-ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+|Planet|
+|-|
+```
+
+###### Out
+
+No messages.
+
+##### `consistent-compact-nok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+|Planet |
+|-|
+```
+
+###### Out
+
+```text
+1:9: Unexpected `1` space between cell content and edge, expected `0` spaces, remove `1` space
+```
+
+##### `empty.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+| | Satellites |
+| - | - |
+| Mercury | |
+```
+
+###### Out
+
+No messages.
+
+##### `string-length-default.md`
+
+When configured with `'compact'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+|Alpha|Bravo |
+|-----|-------|
+|冥王星 |Charlie|
+|🪐 |Delta |
+```
+
+###### Out
+
+No messages.
+
+##### `string-length-custom.md`
+
+When configured with `{ style: 'compact', stringLength: [Function: stringWidth] }`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+|Alpha|Bravo |
+|-----|-------|
+|冥王星|Charlie|
+|🪐 |Delta |
+```
+
+###### Out
+
+No messages.
+
+##### `missing-cells.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+| Planet | Symbol | Satellites |
+| - | - | - |
+| Mercury |
+| Venus | ♀ |
+| Earth | 🜨 and ♁ | 1 |
+| Mars | ♂ | 2 | 19 412 |
+```
+
+###### Out
+
+No messages.
+
+##### `missing-fences.md`
+
+When configured with `'padded'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+␠Planet|Symbol|Satellites
+------:|:-----|----------
+Mercury|☿ |0
+
+Planet|Symbol
+-----:|------
+␠Venus|♀
+```
+
+###### Out
+
+```text
+1:8: Unexpected `0` spaces between cell content and edge, expected `1` space, add `1` space
+1:9: Unexpected `0` spaces between cell edge and content, expected `1` space, add `1` space
+1:15: Unexpected `0` spaces between cell content and edge, expected `1` space, add `1` space
+1:16: Unexpected `0` spaces between cell edge and content, expected `1` space, add `1` space
+2:8: Unexpected `0` spaces between cell content and edge, expected `1` space, add `1` space
+2:9: Unexpected `0` spaces between cell edge and content, expected `1` space, add `1` space
+2:15: Unexpected `0` spaces between cell content and edge, expected `1` space, add `1` space
+2:16: Unexpected `0` spaces between cell edge and content, expected `1` space, add `1` space
+3:8: Unexpected `0` spaces between cell content and edge, expected `1` space, add `1` space
+3:9: Unexpected `0` spaces between cell edge and content, expected `1` space, add `1` space
+3:16: Unexpected `0` spaces between cell edge and content, expected `1` space, add `1` space
+5:7: Unexpected `0` spaces between cell content and edge, expected `1` space, add `1` space
+5:8: Unexpected `0` spaces between cell edge and content, expected `1` space, add `1` space
+6:7: Unexpected `0` spaces between cell content and edge, expected `1` space, add `1` space
+6:8: Unexpected `0` spaces between cell edge and content, expected `1` space, add `1` space
+7:7: Unexpected `0` spaces between cell content and edge, expected `1` space, add `1` space
+7:8: Unexpected `0` spaces between cell edge and content, expected `1` space, add `1` space
+```
+
+##### `missing-fences.md`
+
+When configured with `'compact'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+Planet | Symbol | Satellites
+-: | - | -
+Mercury | ☿ | 0
+
+Planet | Symbol
+-----: | ------
+␠Venus | ♀
+```
+
+###### Out
+
+```text
+1:8: Unexpected `1` space between cell content and edge, expected `0` spaces, remove `1` space
+1:10: Unexpected `1` space between cell edge and content, expected `0` spaces, remove `1` space
+1:17: Unexpected `1` space between cell content and edge, expected `0` spaces, remove `1` space
+1:19: Unexpected `1` space between cell edge and content, expected `0` spaces, remove `1` space
+2:4: Unexpected `1` space between cell content and edge, expected `0` spaces, remove `1` space
+2:6: Unexpected `1` space between cell edge and content, expected `0` spaces, remove `1` space
+2:10: Unexpected `1` space between cell edge and content, expected `0` spaces, remove `1` space
+3:9: Unexpected `1` space between cell content and edge, expected `0` spaces, remove `1` space
+3:11: Unexpected `1` space between cell edge and content, expected `0` spaces, remove `1` space
+3:15: Unexpected `1` space between cell edge and content, expected `0` spaces, remove `1` space
+5:8: Unexpected `1` space between cell content and edge, expected `0` spaces, remove `1` space
+5:10: Unexpected `1` space between cell edge and content, expected `0` spaces, remove `1` space
+6:8: Unexpected `1` space between cell content and edge, expected `0` spaces, remove `1` space
+6:10: Unexpected `1` space between cell edge and content, expected `0` spaces, remove `1` space
+7:8: Unexpected `1` space between cell content and edge, expected `0` spaces, remove `1` space
+7:10: Unexpected `1` space between cell edge and content, expected `0` spaces, remove `1` space
+```
+
+##### `trailing-spaces.md`
+
+When configured with `'compact'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+Planet | Symbol␠
+-: | -␠
+Mercury | ☿␠␠
+
+| Planet | Symbol |␠
+| ------ | ------ |␠
+| Venus | ♀ |␠␠
+```
+
+###### Out
+
+```text
+1:8: Unexpected `1` space between cell content and edge, expected `0` spaces, remove `1` space
+1:10: Unexpected `1` space between cell edge and content, expected `0` spaces, remove `1` space
+2:4: Unexpected `1` space between cell content and edge, expected `0` spaces, remove `1` space
+2:6: Unexpected `1` space between cell edge and content, expected `0` spaces, remove `1` space
+3:9: Unexpected `1` space between cell content and edge, expected `0` spaces, remove `1` space
+3:11: Unexpected `1` space between cell edge and content, expected `0` spaces, remove `1` space
+5:3: Unexpected `1` space between cell edge and content, expected `0` spaces, remove `1` space
+5:10: Unexpected `1` space between cell content and edge, expected `0` spaces, remove `1` space
+5:12: Unexpected `1` space between cell edge and content, expected `0` spaces, remove `1` space
+5:19: Unexpected `1` space between cell content and edge, expected `0` spaces, remove `1` space
+6:3: Unexpected `1` space between cell edge and content, expected `0` spaces, remove `1` space
+6:10: Unexpected `1` space between cell content and edge, expected `0` spaces, remove `1` space
+6:12: Unexpected `1` space between cell edge and content, expected `0` spaces, remove `1` space
+6:19: Unexpected `1` space between cell content and edge, expected `0` spaces, remove `1` space
+7:3: Unexpected `1` space between cell edge and content, expected `0` spaces, remove `1` space
+7:10: Unexpected `2` spaces between cell content and edge, expected between `0` (unaligned) and `1` (aligned) space, remove between `1` and `2` spaces
+7:12: Unexpected `1` space between cell edge and content, expected `0` spaces, remove `1` space
+7:19: Unexpected `6` spaces between cell content and edge, expected between `0` (unaligned) and `5` (aligned) spaces, remove between `1` and `6` spaces
+```
+
+##### `nothing.md`
+
+When configured with `'compact'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+| | | |
+| - | - | - |
+| | | |
+```
+
+###### Out
+
+```text
+1:5: Unexpected `3` spaces between cell edge and content, expected between `0` (unaligned) and `1` (aligned) space, remove between `2` and `3` spaces
+1:9: Unexpected `3` spaces between cell edge and content, expected between `0` (unaligned) and `1` (aligned) space, remove between `2` and `3` spaces
+1:13: Unexpected `3` spaces between cell edge and content, expected between `0` (unaligned) and `1` (aligned) space, remove between `2` and `3` spaces
+2:3: Unexpected `1` space between cell edge and content, expected `0` spaces, remove `1` space
+2:5: Unexpected `1` space between cell content and edge, expected `0` spaces, remove `1` space
+2:7: Unexpected `1` space between cell edge and content, expected `0` spaces, remove `1` space
+2:9: Unexpected `1` space between cell content and edge, expected `0` spaces, remove `1` space
+2:11: Unexpected `1` space between cell edge and content, expected `0` spaces, remove `1` space
+2:13: Unexpected `1` space between cell content and edge, expected `0` spaces, remove `1` space
+3:5: Unexpected `3` spaces between cell edge and content, expected between `0` (unaligned) and `1` (aligned) space, remove between `2` and `3` spaces
+3:9: Unexpected `3` spaces between cell edge and content, expected between `0` (unaligned) and `1` (aligned) space, remove between `2` and `3` spaces
+3:13: Unexpected `3` spaces between cell edge and content, expected between `0` (unaligned) and `1` (aligned) space, remove between `2` and `3` spaces
+```
+
+##### `nothing.md`
+
+When configured with `'padded'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+||||
+|-|-|-|
+||||
+```
+
+###### Out
+
+```text
+1:2: Unexpected `0` spaces between cell edge and content, expected between `1` (unaligned) and `3` (aligned) spaces, add between `3` and `1` space
+1:3: Unexpected `0` spaces between cell edge and content, expected between `1` (unaligned) and `3` (aligned) spaces, add between `3` and `1` space
+1:4: Unexpected `0` spaces between cell edge and content, expected between `1` (unaligned) and `3` (aligned) spaces, add between `3` and `1` space
+2:2: Unexpected `0` spaces between cell edge and content, expected `1` space, add `1` space
+2:3: Unexpected `0` spaces between cell content and edge, expected `1` space, add `1` space
+2:4: Unexpected `0` spaces between cell edge and content, expected `1` space, add `1` space
+2:5: Unexpected `0` spaces between cell content and edge, expected `1` space, add `1` space
+2:6: Unexpected `0` spaces between cell edge and content, expected `1` space, add `1` space
+2:7: Unexpected `0` spaces between cell content and edge, expected `1` space, add `1` space
+3:2: Unexpected `0` spaces between cell edge and content, expected between `1` (unaligned) and `3` (aligned) spaces, add between `3` and `1` space
+3:3: Unexpected `0` spaces between cell edge and content, expected between `1` (unaligned) and `3` (aligned) spaces, add between `3` and `1` space
+3:4: Unexpected `0` spaces between cell edge and content, expected between `1` (unaligned) and `3` (aligned) spaces, add between `3` and `1` space
+```
+
+##### `more-weirdness.md`
+
+When configured with `'padded'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+Mercury
+|-
+
+Venus
+-|
+```
+
+###### Out
+
+```text
+2:2: Unexpected `0` spaces between cell edge and content, expected `1` space, add `1` space
+5:2: Unexpected `0` spaces between cell content and edge, expected between `1` (unaligned) and `5` (aligned) spaces, add between `5` and `1` space
+```
+
+##### `containers.md`
+
+When configured with `'padded'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+> | Mercury|
+> | - |
+
+* | Venus|
+ | - |
+
+> * > | Earth|
+> > | - |
+```
+
+###### Out
+
+```text
+1:12: Unexpected `0` spaces between cell content and edge, expected `1` space, add `1` space
+4:10: Unexpected `0` spaces between cell content and edge, expected `1` space, add `1` space
+7:14: Unexpected `0` spaces between cell content and edge, expected `1` space, add `1` space
+```
+
+##### `windows.md`
+
+When configured with `'padded'`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+| Mercury|␍␊| --- |␍␊| None |
+```
+
+###### Out
+
+```text
+1:10: Unexpected `0` spaces between cell content and edge, expected `1` space, add `1` space
+```
+
+##### `not-ok.md`
+
+When configured with `'🌍'`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `style`, expected `'compact'`, `'padded'`, or `'consistent'`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-table-cell-padding@5`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-options]: #options
+
+[api-remark-lint-table-cell-padding]: #unifieduseremarklinttablecellpadding-options
+
+[api-style]: #style
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-table-cell-padding.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-table-cell-padding
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-table-cell-padding
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-table-cell-padding
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-table-pipe-alignment_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-table-pipe-alignment_readme.md
new file mode 100644
index 0000000..6dd9344
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-table-pipe-alignment_readme.md
@@ -0,0 +1,544 @@
+<!--This file is generated-->
+
+# remark-lint-table-pipe-alignment
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when GFM table cells are aligned inconsistently.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintTablePipeAlignment[, options])`](#unifieduseremarklinttablepipealignment-options)
+ * [`Options`](#options)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks table cell dividers are aligned.
+Tables are a GFM feature enabled with [`remark-gfm`][github-remark-gfm].
+
+## When should I use this?
+
+You can use this package to check that tables are consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-table-pipe-alignment
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintTablePipeAlignment from 'https://esm.sh/remark-lint-table-pipe-alignment@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintTablePipeAlignment from 'https://esm.sh/remark-lint-table-pipe-alignment@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintTablePipeAlignment from 'remark-lint-table-pipe-alignment'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintTablePipeAlignment)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-table-pipe-alignment .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-table-pipe-alignment",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] type
+[`Options`][api-options].
+The default export is
+[`remarkLintTablePipeAlignment`][api-remark-lint-table-pipe-alignment].
+
+### `unified().use(remarkLintTablePipeAlignment[, options])`
+
+Warn when GFM table cells are aligned inconsistently.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], optional)
+ — configuration
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Properties
+
+* `stringLength` (`(value: string) => number`, optional)
+ — function to detect cell size
+
+## Recommendation
+
+While aligning table dividers improves their legibility,
+it is somewhat hard to maintain manually,
+especially for tables with many rows.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] with
+[`remark-gfm`][github-remark-gfm] aligns table cell dividers by default.
+Pass `tablePipeAlign: false` to use a more compact style.
+
+Aligning perfectly in all cases is not possible because whether characters
+look aligned or not depends on where the markup is shown.
+Some characters (such as emoji or Chinese characters) show smaller or bigger
+in different places.
+You can pass a `stringLength` function to `remark-gfm`,
+to align better for your use case,
+in which case this rule must be configured with the same `stringLength`.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+This rule is only about the alignment of pipes across rows:
+
+| Planet | Mean anomaly (°) |
+| ------- | ---------------: |
+| Mercury | 174 796 |
+
+|Planet|Mean anomaly (°)|
+|------|---------------:|
+|Venus | 50 115 |
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+| Planet | Mean anomaly (°) |
+| - | -: |
+| Mercury | 174 796 |
+```
+
+###### Out
+
+```text
+1:10: Unexpected unaligned cell, expected aligned pipes, add `1` space
+2:5: Unexpected unaligned cell, expected aligned pipes, add `6` spaces (or add `-` to pad alignment row cells)
+2:7: Unexpected unaligned cell, expected aligned pipes, add `14` spaces (or add `-` to pad alignment row cells)
+3:13: Unexpected unaligned cell, expected aligned pipes, add `9` spaces
+```
+
+##### `empty.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+| | Satellites | |
+| ------- | ---------- | --- |
+| Mercury | | |
+
+| aaa | bbb | ccc | ddd |
+| --- | :-- | :-: | --: |
+| | | | |
+```
+
+###### Out
+
+No messages.
+
+##### `aligned-pipes-but-weird-content.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+| Planet | Moon | Mercury | Venus | Sun | Mars | Jupiter | Saturn |
+| ------ | ---- | :------ | :---- | --: | ---: | :-----: | :----: |
+| Symbol | ☾ | ☿ | ♀ | ☉ | ♂ | ♃ | ♄ |
+```
+
+###### Out
+
+No messages.
+
+##### `missing-cells.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+| Planet | Symbol | Satellites |
+| ------- | ------ | ---------- |
+| Mercury |
+| Venus | ♀ |
+| Earth | ♁ | 1 |
+| Mars | ♂ | 2 | 19 412 |
+```
+
+###### Out
+
+No messages.
+
+##### `alignment.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+| Planet | Symbol | Satellites | Mean anomaly (°) |
+| - | :- | :-: | -: |
+| Mercury | ☿ | None | 174 796 |
+```
+
+###### Out
+
+```text
+1:10: Unexpected unaligned cell, expected aligned pipes, add `1` space
+2:5: Unexpected unaligned cell, expected aligned pipes, add `6` spaces (or add `-` to pad alignment row cells)
+2:10: Unexpected unaligned cell, expected aligned pipes, add `4` spaces (or add `-` to pad alignment row cells)
+2:12: Unexpected unaligned cell, expected aligned pipes, add `4` spaces (or add `-` to pad alignment row cells)
+2:16: Unexpected unaligned cell, expected aligned pipes, add `3` spaces (or add `-` to pad alignment row cells)
+2:18: Unexpected unaligned cell, expected aligned pipes, add `14` spaces (or add `-` to pad alignment row cells)
+3:15: Unexpected unaligned cell, expected aligned pipes, add `5` spaces
+3:17: Unexpected unaligned cell, expected aligned pipes, add `3` spaces
+3:22: Unexpected unaligned cell, expected aligned pipes, add `3` spaces
+3:24: Unexpected unaligned cell, expected aligned pipes, add `9` spaces
+```
+
+##### `missing-fences.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+Planet | Satellites
+-: | -
+Mercury | ☿
+```
+
+###### Out
+
+```text
+1:1: Unexpected unaligned cell, expected aligned pipes, add `1` space
+2:1: Unexpected unaligned cell, expected aligned pipes, add `5` spaces (or add `-` to pad alignment row cells)
+```
+
+##### `trailing-spaces.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+| Planet |␠␠
+| -: |␠
+```
+
+###### Out
+
+```text
+2:3: Unexpected unaligned cell, expected aligned pipes, add `4` spaces (or add `-` to pad alignment row cells)
+```
+
+##### `nothing.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+||||
+|-|-|-|
+```
+
+###### Out
+
+```text
+1:2: Unexpected unaligned cell, expected aligned pipes, add `1` space
+1:3: Unexpected unaligned cell, expected aligned pipes, add `1` space
+1:4: Unexpected unaligned cell, expected aligned pipes, add `1` space
+```
+
+##### `more-weirdness.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+Mercury
+|-
+
+Venus
+-|
+```
+
+###### Out
+
+```text
+5:2: Unexpected unaligned cell, expected aligned pipes, add `4` spaces (or add `-` to pad alignment row cells)
+```
+
+##### `containers.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+> | Mercury|
+> | - |
+
+* | Venus|
+ | - |
+
+> * > | Earth|
+> > | - |
+```
+
+###### Out
+
+```text
+2:5: Unexpected unaligned cell, expected aligned pipes, add `5` spaces (or add `-` to pad alignment row cells)
+5:5: Unexpected unaligned cell, expected aligned pipes, add `3` spaces (or add `-` to pad alignment row cells)
+8:5: Unexpected unaligned cell, expected aligned pipes, add `3` spaces (or add `-` to pad alignment row cells)
+```
+
+##### `windows.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+| Mercury|␍␊| --- |␍␊| None |
+```
+
+###### Out
+
+```text
+2:7: Unexpected unaligned cell, expected aligned pipes, add `3` spaces (or add `-` to pad alignment row cells)
+3:8: Unexpected unaligned cell, expected aligned pipes, add `2` spaces
+```
+
+##### `string-length-default.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+| Alpha | Bravo |
+| ----- | ------- |
+| 冥王星 | Charlie |
+| 🪐 | Delta |
+```
+
+###### Out
+
+No messages.
+
+##### `string-length-custom.md`
+
+When configured with `{ stringLength: [Function: stringWidth] }`.
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+| Alpha | Bravo |
+| ------ | ------- |
+| 冥王星 | Charlie |
+| 🪐 | Delta |
+```
+
+###### Out
+
+No messages.
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-table-pipe-alignment@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-options]: #options
+
+[api-remark-lint-table-pipe-alignment]: #unifieduseremarklinttablepipealignment-options
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-table-pipe-alignment.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-table-pipe-alignment
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-table-pipe-alignment
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-table-pipe-alignment
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-table-pipes_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-table-pipes_readme.md
new file mode 100644
index 0000000..6b0e277
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-table-pipes_readme.md
@@ -0,0 +1,353 @@
+<!--This file is generated-->
+
+# remark-lint-table-pipes
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when GFM table rows have no initial or
+final cell delimiter.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintTablePipes)`](#unifieduseremarklinttablepipes)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks that table rows have initial and final delimiters.
+Tables are a GFM feature enabled with [`remark-gfm`][github-remark-gfm].
+
+## When should I use this?
+
+You can use this package to check that tables are consistent.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-table-pipes
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintTablePipes from 'https://esm.sh/remark-lint-table-pipes@5'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintTablePipes from 'https://esm.sh/remark-lint-table-pipes@5?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintTablePipes from 'remark-lint-table-pipes'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintTablePipes)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-table-pipes .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-table-pipes",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLintTablePipes`][api-remark-lint-table-pipes].
+
+### `unified().use(remarkLintTablePipes)`
+
+Warn when GFM table rows have no initial or final cell delimiter.
+
+###### Parameters
+
+There are no options.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Recommendation
+
+While tables don’t require initial or final delimiters (the pipes before the
+first and after the last cells in a row),
+it arguably does look weird without.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] with
+[`remark-gfm`][github-remark-gfm] formats all tables with initial and final
+delimiters.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+Small table:
+
+| Planet | Mean anomaly (°) |
+| :- | -: |
+| Mercury | 174 796 |
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+Planet | Mean anomaly (°)
+:- | -:
+Mercury | 174 796
+```
+
+###### Out
+
+```text
+1:1: Unexpected missing closing pipe in row, expected `|`
+1:26: Unexpected missing opening pipe in row, expected `|`
+2:1: Unexpected missing closing pipe in row, expected `|`
+2:8: Unexpected missing opening pipe in row, expected `|`
+3:1: Unexpected missing closing pipe in row, expected `|`
+3:18: Unexpected missing opening pipe in row, expected `|`
+```
+
+##### `missing-cells.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+Planet | Symbol | Satellites
+:- | - | -
+Mercury
+Venus | ♀
+Earth | ♁ | 1
+Mars | ♂ | 2 | 19 412
+```
+
+###### Out
+
+```text
+1:1: Unexpected missing closing pipe in row, expected `|`
+1:29: Unexpected missing opening pipe in row, expected `|`
+2:1: Unexpected missing closing pipe in row, expected `|`
+2:11: Unexpected missing opening pipe in row, expected `|`
+3:1: Unexpected missing closing pipe in row, expected `|`
+3:8: Unexpected missing opening pipe in row, expected `|`
+4:1: Unexpected missing closing pipe in row, expected `|`
+4:10: Unexpected missing opening pipe in row, expected `|`
+5:1: Unexpected missing closing pipe in row, expected `|`
+5:14: Unexpected missing opening pipe in row, expected `|`
+6:1: Unexpected missing closing pipe in row, expected `|`
+6:22: Unexpected missing opening pipe in row, expected `|`
+```
+
+##### `trailing-spaces.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+␠␠Planet␠␠
+␠-:␠
+
+␠␠| Planet |␠␠
+␠| -: |␠
+```
+
+###### Out
+
+```text
+1:3: Unexpected missing closing pipe in row, expected `|`
+1:11: Unexpected missing opening pipe in row, expected `|`
+2:2: Unexpected missing closing pipe in row, expected `|`
+2:5: Unexpected missing opening pipe in row, expected `|`
+```
+
+##### `windows.md`
+
+###### In
+
+> 👉 **Note**: this example uses
+> GFM ([`remark-gfm`][github-remark-gfm]).
+
+```markdown
+Mercury␍␊:-␍␊None
+```
+
+###### Out
+
+```text
+1:1: Unexpected missing closing pipe in row, expected `|`
+1:8: Unexpected missing opening pipe in row, expected `|`
+2:1: Unexpected missing closing pipe in row, expected `|`
+2:3: Unexpected missing opening pipe in row, expected `|`
+3:1: Unexpected missing closing pipe in row, expected `|`
+3:5: Unexpected missing opening pipe in row, expected `|`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-table-pipes@5`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint-table-pipes]: #unifieduseremarklinttablepipes
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-table-pipes.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-table-pipes
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-table-pipes
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-table-pipes
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint-unordered-list-marker-style_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint-unordered-list-marker-style_readme.md
new file mode 100644
index 0000000..f71da99
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint-unordered-list-marker-style_readme.md
@@ -0,0 +1,344 @@
+<!--This file is generated-->
+
+# remark-lint-unordered-list-marker-style
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+[`remark-lint`][github-remark-lint] rule to warn when unordered list markers are inconsistent.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLintUnorderedListMarkerStyle[, options])`](#unifieduseremarklintunorderedlistmarkerstyle-options)
+ * [`Options`](#options)
+ * [`Style`](#style)
+* [Recommendation](#recommendation)
+* [Fix](#fix)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package checks unordered list markers.
+
+## When should I use this?
+
+You can use this package to check unordered lists.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | `'-'` |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint-unordered-list-marker-style
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLintUnorderedListMarkerStyle from 'https://esm.sh/remark-lint-unordered-list-marker-style@4'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLintUnorderedListMarkerStyle from 'https://esm.sh/remark-lint-unordered-list-marker-style@4?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkLintUnorderedListMarkerStyle from 'remark-lint-unordered-list-marker-style'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkLintUnorderedListMarkerStyle)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint --use remark-lint-unordered-list-marker-style .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
+ "remark-lint",
++ "remark-lint-unordered-list-marker-style",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports the [TypeScript][typescript] types
+[`Options`][api-options] and
+[`Style`][api-style].
+The default export is
+[`remarkLintUnorderedListMarkerStyle`][api-remark-lint-unordered-list-marker-style].
+
+### `unified().use(remarkLintUnorderedListMarkerStyle[, options])`
+
+Warn when unordered list markers are inconsistent.
+
+###### Parameters
+
+* `options` ([`Options`][api-options], default: `'consistent'`)
+ — preferred style or whether to detect the first style and warn for
+ further differences
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+### `Options`
+
+Configuration (TypeScript type).
+
+###### Type
+
+```ts
+type Options = Style | 'consistent'
+```
+
+### `Style`
+
+Style (TypeScript type).
+
+###### Type
+
+```ts
+type Style = '*' | '+' | '-'
+```
+
+## Recommendation
+
+Because asterisks can be used as a marker for more markdown constructs,
+it’s recommended to use that for lists (and thematic breaks, emphasis,
+strong) too.
+
+## Fix
+
+[`remark-stringify`][github-remark-stringify] formats unordered lists with
+asterisks by default.
+Pass `bullet: '+'` or `bullet: '-'` to use a different marker.
+
+## Examples
+
+##### `ok.md`
+
+###### In
+
+```markdown
+* Mercury
+
+1. Venus
+
+* Earth
+```
+
+###### Out
+
+No messages.
+
+##### `ok.md`
+
+When configured with `'*'`.
+
+###### In
+
+```markdown
+* Mercury
+```
+
+###### Out
+
+No messages.
+
+##### `ok.md`
+
+When configured with `'-'`.
+
+###### In
+
+```markdown
+- Mercury
+```
+
+###### Out
+
+No messages.
+
+##### `ok.md`
+
+When configured with `'+'`.
+
+###### In
+
+```markdown
++ Mercury
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.md`
+
+###### In
+
+```markdown
+* Mercury
+
+- Venus
+
++ Earth
+```
+
+###### Out
+
+```text
+3:1: Unexpected unordered list marker `-`, expected `*`
+5:1: Unexpected unordered list marker `+`, expected `*`
+```
+
+##### `not-ok.md`
+
+When configured with `'🌍'`.
+
+###### Out
+
+```text
+1:1: Unexpected value `🌍` for `options`, expected `'*'`, `'+'`, `'-'`, or `'consistent'`
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint-unordered-list-marker-style@4`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-options]: #options
+
+[api-remark-lint-unordered-list-marker-style]: #unifieduseremarklintunorderedlistmarkerstyle-options
+
+[api-style]: #style
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint-unordered-list-marker-style.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint-unordered-list-marker-style
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint-unordered-list-marker-style
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint-unordered-list-marker-style
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-lint_readme.md b/documents/markdown/remark/remark-lint_packages_remark-lint_readme.md
new file mode 100644
index 0000000..07ba43b
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-lint_readme.md
@@ -0,0 +1,214 @@
+<!--This file is generated-->
+
+# remark-lint
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+**[remark][github-remark]** plugin to support configuration comments for
+[`remark-lint`][github-remark-lint] rules.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkLint)`](#unifieduseremarklint)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This plugin adds support for configuration comments to control remark lint
+rule messages.
+
+## When should I use this?
+
+This project is useful when you’re using remark lint rules and want to let
+authors ignore messages in certain cases.
+This package is already included in all our presets.
+If you’re building a preset yourself, you should include this package.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) | |
+| [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) | |
+| [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) | |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-lint
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkLint from 'https://esm.sh/remark-lint@10'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkLint from 'https://esm.sh/remark-lint@10?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkLint from 'remark-lint'
+import remarkParse from 'remark-parse'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkLint)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-lint .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
++ "remark-lint",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkLint`][api-remark-lint].
+
+### `unified().use(remarkLint)`
+
+Add support for configuration comments.
+
+See [Ignore warnings][mono-ignore] in the monorepo readme for how to use it.
+
+###### Returns
+
+Transform ([`Transformer` from `unified`][github-unified-transformer]).
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-lint@10`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-lint]: #unifieduseremarklint
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark]: https://github.com/remarkjs/remark
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[github-unified-transformer]: https://github.com/unifiedjs/unified#transformer
+
+[mono-ignore]: https://github.com/remarkjs/remark-lint#ignore-warnings
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-preset-lint-consistent_readme.md b/documents/markdown/remark/remark-lint_packages_remark-preset-lint-consistent_readme.md
new file mode 100644
index 0000000..3ea4351
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-preset-lint-consistent_readme.md
@@ -0,0 +1,212 @@
+<!--This file is generated-->
+
+# remark-preset-lint-consistent
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+Preset of [`remark-lint`][github-remark-lint] rules to warn for inconsistencies.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Plugins](#plugins)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkPresetLintConsistent)`](#unifieduseremarkpresetlintconsistent)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package is a preset containing `remark-lint` rules.
+Lint rules check markdown code style.
+
+## When should I use this?
+
+You can use this package to check that markdown is consistent.
+
+## Plugins
+
+This preset includes the following plugins:
+
+| Plugin | Options |
+| - | - |
+| [`remark-lint`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint) | |
+| [`remark-lint-blockquote-indentation`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-blockquote-indentation) | `'consistent'` |
+| [`remark-lint-checkbox-character-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-checkbox-character-style) | `'consistent'` |
+| [`remark-lint-code-block-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-code-block-style) | `'consistent'` |
+| [`remark-lint-emphasis-marker`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-emphasis-marker) | `'consistent'` |
+| [`remark-lint-fenced-code-marker`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-fenced-code-marker) | `'consistent'` |
+| [`remark-lint-heading-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-heading-style) | `'consistent'` |
+| [`remark-lint-link-title-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-link-title-style) | `'consistent'` |
+| [`remark-lint-list-item-content-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-content-indent) | |
+| [`remark-lint-ordered-list-marker-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-ordered-list-marker-style) | `'consistent'` |
+| [`remark-lint-ordered-list-marker-value`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-ordered-list-marker-value) | `'consistent'` |
+| [`remark-lint-rule-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-rule-style) | `'consistent'` |
+| [`remark-lint-strong-marker`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-strong-marker) | `'consistent'` |
+| [`remark-lint-table-cell-padding`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-table-cell-padding) | `'consistent'` |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-preset-lint-consistent
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkPresetLintConsistent from 'https://esm.sh/remark-preset-lint-consistent@6'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkPresetLintConsistent from 'https://esm.sh/remark-preset-lint-consistent@6?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkParse from 'remark-parse'
+import remarkPresetLintConsistent from 'remark-preset-lint-consistent'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkPresetLintConsistent)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-preset-lint-consistent .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
++ "remark-preset-lint-consistent",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkPresetLintConsistent`][api-remark-preset-lint-consistent].
+
+### `unified().use(remarkPresetLintConsistent)`
+
+Check that markdown is consistent.
+
+You can reconfigure rules in the preset by using them afterwards with different
+options.
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-preset-lint-consistent@6`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-preset-lint-consistent]: #unifieduseremarkpresetlintconsistent
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-preset-lint-consistent.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-preset-lint-consistent
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-preset-lint-consistent
+
+[badge-size-url]: https://bundlejs.com/?q=remark-preset-lint-consistent
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-preset-lint-markdown-style-guide_readme.md b/documents/markdown/remark/remark-lint_packages_remark-preset-lint-markdown-style-guide_readme.md
new file mode 100644
index 0000000..fee61cf
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-preset-lint-markdown-style-guide_readme.md
@@ -0,0 +1,331 @@
+<!--This file is generated-->
+
+# remark-preset-lint-markdown-style-guide
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+Preset of [`remark-lint`][github-remark-lint] rules that follow an opinionated style guide.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Plugins](#plugins)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkPresetLintMarkdownStyleGuide)`](#unifieduseremarkpresetlintmarkdownstyleguide)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package is a preset containing `remark-lint` rules.
+Lint rules check markdown code style.
+
+## When should I use this?
+
+You can use this package to check that markdown follows the
+[Markdown Style Guide](https://cirosantilli.com/markdown-style-guide/).
+
+This uses the following style guide option system: `wrap:space`,
+`header:atx`, `list-marker:hyphen`, `list-space:mixed`, and `code:fenced`.
+
+###### `space-sentence`
+
+Both `space-sentence:1` and `space-sentence:2` are not supported by
+`remark-lint` as they relate to prose rather than markdown syntax.
+You could set-up
+[`remark-retext`](https://github.com/remarkjs/remark-retext)
+with
+[`retext-sentence-spacing`](https://github.com/retextjs/retext-sentence-spacing)
+to check this.
+
+###### `wrap`
+
+`wrap:inner-sentence` and `wrap:sentence` are not supported by `remark-lint`.
+
+The default is `wrap:space`.
+To use `wrap:no`, turn off `remark-lint-maximum-line-length` like so:
+
+```diff
+ "plugins": [
+ …
+ "remark-preset-lint-markdown-style-guide",
++ ["remark-lint-maximum-line-length", false],
+ …
+ ]
+```
+
+###### `header`
+
+The default is `header:atx`.
+To use `header:setext`, change the setting for `remark-lint-heading-style`
+like so:
+
+```diff
+ "plugins": [
+ …
+ "remark-preset-lint-markdown-style-guide",
++ ["remark-lint-heading-style", "setext"],
+ …
+ ]
+```
+
+###### `list-marker`
+
+The default is `list-marker:hyphen`.
+For `list-marker:asterisk` or `list-marker:plus`, change the setting for
+`remark-lint-unordered-list-marker-style` like so:
+
+```diff
+ "plugins": [
+ …
+ "remark-preset-lint-markdown-style-guide",
++ ["remark-lint-unordered-list-marker-style", "*"],
+ …
+ ]
+```
+
+###### `list-space`
+
+The default is `list-space:mixed`.
+For `list-space:1`, change the setting for `remark-lint-list-item-indent`
+like so:
+
+```diff
+ "plugins": [
+ …
+ "remark-preset-lint-markdown-style-guide",
++ ["remark-lint-list-item-indent", "space"],
+ …
+ ]
+```
+
+###### `code`
+
+The default is `code:fenced`.
+For `code:indented`, change the setting for `remark-lint-code-block-style`
+like so:
+
+```diff
+ "plugins": [
+ …
+ "remark-preset-lint-markdown-style-guide",
++ ["remark-lint-code-block-style", "indented"],
+ …
+ ]
+```
+
+## Plugins
+
+This preset includes the following plugins:
+
+| Plugin | Options |
+| - | - |
+| [`remark-lint`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint) | |
+| [`remark-lint-blockquote-indentation`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-blockquote-indentation) | `2` |
+| [`remark-lint-code-block-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-code-block-style) | `'fenced'` |
+| [`remark-lint-definition-case`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-definition-case) | |
+| [`remark-lint-definition-spacing`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-definition-spacing) | |
+| [`remark-lint-emphasis-marker`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-emphasis-marker) | `'*'` |
+| [`remark-lint-fenced-code-flag`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-fenced-code-flag) | `{ allowEmpty: false }` |
+| [`remark-lint-fenced-code-marker`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-fenced-code-marker) | ``'`'`` |
+| [`remark-lint-file-extension`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-file-extension) | `'md'` |
+| [`remark-lint-final-definition`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-final-definition) | |
+| [`remark-lint-hard-break-spaces`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-hard-break-spaces) | |
+| [`remark-lint-heading-increment`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-heading-increment) | |
+| [`remark-lint-heading-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-heading-style) | `'atx'` |
+| [`remark-lint-link-title-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-link-title-style) | `'"'` |
+| [`remark-lint-list-item-content-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-content-indent) | |
+| [`remark-lint-list-item-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-indent) | `'mixed'` |
+| [`remark-lint-list-item-spacing`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-spacing) | |
+| [`remark-lint-maximum-heading-length`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-maximum-heading-length) | |
+| [`remark-lint-maximum-line-length`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-maximum-line-length) | `80` |
+| [`remark-lint-no-blockquote-without-marker`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-blockquote-without-marker) | |
+| [`remark-lint-no-consecutive-blank-lines`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-consecutive-blank-lines) | |
+| [`remark-lint-no-duplicate-headings`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-headings) | |
+| [`remark-lint-no-emphasis-as-heading`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-emphasis-as-heading) | |
+| [`remark-lint-no-file-name-articles`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-articles) | |
+| [`remark-lint-no-file-name-consecutive-dashes`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-consecutive-dashes) | |
+| [`remark-lint-no-file-name-irregular-characters`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-irregular-characters) | |
+| [`remark-lint-no-file-name-mixed-case`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-mixed-case) | |
+| [`remark-lint-no-file-name-outer-dashes`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-outer-dashes) | |
+| [`remark-lint-no-heading-punctuation`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-punctuation) | `':.'` |
+| [`remark-lint-no-literal-urls`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-literal-urls) | |
+| [`remark-lint-no-multiple-toplevel-headings`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-multiple-toplevel-headings) | |
+| [`remark-lint-no-shell-dollars`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-shell-dollars) | |
+| [`remark-lint-no-shortcut-reference-image`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-shortcut-reference-image) | |
+| [`remark-lint-no-shortcut-reference-link`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-shortcut-reference-link) | |
+| [`remark-lint-no-table-indentation`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-table-indentation) | |
+| [`remark-lint-ordered-list-marker-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-ordered-list-marker-style) | `'.'` |
+| [`remark-lint-ordered-list-marker-value`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-ordered-list-marker-value) | `'one'` |
+| [`remark-lint-rule-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-rule-style) | `'---'` |
+| [`remark-lint-strong-marker`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-strong-marker) | `'*'` |
+| [`remark-lint-table-cell-padding`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-table-cell-padding) | `'padded'` |
+| [`remark-lint-table-pipe-alignment`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-table-pipe-alignment) | |
+| [`remark-lint-table-pipes`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-table-pipes) | |
+| [`remark-lint-unordered-list-marker-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-unordered-list-marker-style) | `'-'` |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-preset-lint-markdown-style-guide
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkPresetLintMarkdownStyleGuide from 'https://esm.sh/remark-preset-lint-markdown-style-guide@6'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkPresetLintMarkdownStyleGuide from 'https://esm.sh/remark-preset-lint-markdown-style-guide@6?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkParse from 'remark-parse'
+import remarkPresetLintMarkdownStyleGuide from 'remark-preset-lint-markdown-style-guide'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkPresetLintMarkdownStyleGuide)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-preset-lint-markdown-style-guide .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
++ "remark-preset-lint-markdown-style-guide",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkPresetLintMarkdownStyleGuide`][api-remark-preset-lint-markdown-style-guide].
+
+### `unified().use(remarkPresetLintMarkdownStyleGuide)`
+
+Check that markdown follows “Markdown Style Guide”.
+
+You can reconfigure rules in the preset by using them afterwards with different
+options.
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-preset-lint-markdown-style-guide@6`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-preset-lint-markdown-style-guide]: #unifieduseremarkpresetlintmarkdownstyleguide
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-preset-lint-markdown-style-guide.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-preset-lint-markdown-style-guide
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-preset-lint-markdown-style-guide
+
+[badge-size-url]: https://bundlejs.com/?q=remark-preset-lint-markdown-style-guide
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_remark-preset-lint-recommended_readme.md b/documents/markdown/remark/remark-lint_packages_remark-preset-lint-recommended_readme.md
new file mode 100644
index 0000000..da2b5a5
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_remark-preset-lint-recommended_readme.md
@@ -0,0 +1,212 @@
+<!--This file is generated-->
+
+# remark-preset-lint-recommended
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+Preset of [`remark-lint`][github-remark-lint] rules to warn for likely problems.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Plugins](#plugins)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`unified().use(remarkPresetLintRecommended)`](#unifieduseremarkpresetlintrecommended)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package is a preset containing `remark-lint` rules.
+Lint rules check markdown code style.
+
+## When should I use this?
+
+You can use this package to check that markdown follows some best practices.
+
+## Plugins
+
+This preset includes the following plugins:
+
+| Plugin | Options |
+| - | - |
+| [`remark-lint`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint) | |
+| [`remark-lint-final-newline`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-final-newline) | |
+| [`remark-lint-hard-break-spaces`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-hard-break-spaces) | |
+| [`remark-lint-list-item-bullet-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-bullet-indent) | |
+| [`remark-lint-list-item-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-indent) | `'one'` |
+| [`remark-lint-no-blockquote-without-marker`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-blockquote-without-marker) | |
+| [`remark-lint-no-duplicate-definitions`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-definitions) | |
+| [`remark-lint-no-heading-content-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-content-indent) | |
+| [`remark-lint-no-literal-urls`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-literal-urls) | |
+| [`remark-lint-no-shortcut-reference-image`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-shortcut-reference-image) | |
+| [`remark-lint-no-shortcut-reference-link`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-shortcut-reference-link) | |
+| [`remark-lint-no-undefined-references`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-undefined-references) | |
+| [`remark-lint-no-unused-definitions`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-unused-definitions) | |
+| [`remark-lint-ordered-list-marker-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-ordered-list-marker-style) | `'.'` |
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install remark-preset-lint-recommended
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import remarkPresetLintRecommended from 'https://esm.sh/remark-preset-lint-recommended@7'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import remarkPresetLintRecommended from 'https://esm.sh/remark-preset-lint-recommended@7?bundle'
+</script>
+```
+
+## Use
+
+On the API:
+
+```js
+import remarkParse from 'remark-parse'
+import remarkPresetLintRecommended from 'remark-preset-lint-recommended'
+import remarkStringify from 'remark-stringify'
+import {read} from 'to-vfile'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
+
+const file = await read('example.md')
+
+await unified()
+ .use(remarkParse)
+ .use(remarkPresetLintRecommended)
+ .use(remarkStringify)
+ .process(file)
+
+console.error(reporter(file))
+```
+
+On the CLI:
+
+```sh
+remark --frail --use remark-preset-lint-recommended .
+```
+
+On the CLI in a config file (here a `package.json`):
+
+```diff
+ …
+ "remarkConfig": {
+ "plugins": [
+ …
++ "remark-preset-lint-recommended",
+ …
+ ]
+ }
+ …
+```
+
+## API
+
+This package exports no identifiers.
+It exports no additional [TypeScript][typescript] types.
+The default export is
+[`remarkPresetLintRecommended`][api-remark-preset-lint-recommended].
+
+### `unified().use(remarkPresetLintRecommended)`
+
+Check that markdown follows some best practices.
+
+You can reconfigure rules in the preset by using them afterwards with different
+options.
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`remark-preset-lint-recommended@7`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-remark-preset-lint-recommended]: #unifieduseremarkpresetlintrecommended
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-preset-lint-recommended.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-preset-lint-recommended
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-preset-lint-recommended
+
+[badge-size-url]: https://bundlejs.com/?q=remark-preset-lint-recommended
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-remark-lint]: https://github.com/remarkjs/remark-lint
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_packages_unified-lint-rule_readme.md b/documents/markdown/remark/remark-lint_packages_unified-lint-rule_readme.md
new file mode 100644
index 0000000..1057b9f
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_packages_unified-lint-rule_readme.md
@@ -0,0 +1,266 @@
+<!--This file is generated-->
+
+# unified-lint-rule
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-funding-sponsors-image]][badge-funding-url]
+[![Backers][badge-funding-backers-image]][badge-funding-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+**[unified][github-unified]** helper to help make lint rules.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`lintRule(meta, rule)`](#lintrulemeta-rule)
+ * [`Label`](#label)
+ * [`Meta`](#meta)
+ * [`Next`](#next)
+ * [`Rule`](#rule)
+ * [`Severity`](#severity)
+* [Compatibility](#compatibility)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+This package is a helper that makes it a bit easier to create linting rules.
+
+## When should I use this?
+
+You can use this package when you want to make custom lint rules.
+
+## Install
+
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
+
+```sh
+npm install unified-lint-rule
+```
+
+In Deno with [`esm.sh`][esm-sh]:
+
+```js
+import {lintRule} from 'https://esm.sh/unified-lint-rule@3'
+```
+
+In browsers with [`esm.sh`][esm-sh]:
+
+```html
+<script type="module">
+ import {lintRule} from 'https://esm.sh/unified-lint-rule@3?bundle'
+</script>
+```
+
+## Use
+
+```js
+import {lintRule} from 'unified-lint-rule'
+
+const remarkLintFileExtension = lintRule(
+ 'remark-lint:file-extension',
+ function (tree, file, options) {
+ const ext = file.extname
+ const option = options || 'md'
+
+ if (ext && ext.slice(1) !== option) {
+ file.message('Incorrect extension: use `' + option + '`')
+ }
+ }
+)
+
+export default remarkLintFileExtension
+```
+
+## API
+
+This package exports the identifier
+[`lintRule`][api-lint-rule].
+It exports the [TypeScript][typescript] types
+[`Label`][api-label],
+[`Meta`][api-meta],
+[`Next`][api-next], and
+[`Severity`][api-severity].
+There is no default export.
+
+### `lintRule(meta, rule)`
+
+Create a plugin.
+
+###### Parameters
+
+* `meta` ([`Meta`][api-meta] or `string`)
+ — info or origin
+* `rule` ([`Rule`][api-rule])
+ — rule
+
+###### Returns
+
+Plugin ([`Plugin` from `unified`][github-unified-plugin]).
+
+### `Label`
+
+Severity label (TypeScript type);
+`'off'`: `0`, `'on'` and `warn`: `1`, `'error'`: `2`.
+
+###### Type
+
+```ts
+type Label = 'error' | 'on' | 'off' | 'warn'
+```
+
+### `Meta`
+
+Rule metadata (TypeScript type).
+
+###### Fields
+
+* `origin` (`string`)
+ — name of the lint rule
+* `url` (`string`, optional)
+ — link to documentation
+
+### `Next`
+
+Callback passed to rules (TypeScript type).
+
+If the signature of a rule accepts a fourth argument,
+the rule may perform asynchronous operations,
+and must call it.
+
+###### Parameters
+
+* `error` (`Error`, optional)
+ — fatal error to stop linting
+
+###### Returns
+
+Nothing (`undefined`).
+
+### `Rule`
+
+Rule (TypeScript type).
+
+###### Parameters
+
+* `tree` ([`Node` from `unist`][github-unist-node])
+ — tree
+* `file` ([`VFile`][github-vfile])
+ — file
+* `options` (`unknown`, optional)
+ — parameter
+
+###### Returns
+
+Nothing (`Promise<undefined>` or `undefined`).
+
+### `Severity`
+
+Severity number (TypeScript type);
+`0`: `'off'`, `1`: `'on'` and `warn`, `2`: `'error'`.
+
+###### Type
+
+```ts
+type Severity = 0 | 1 | 2
+```
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line,
+`unified-lint-rule@3`,
+compatible with Node.js 16.
+
+## Contribute
+
+See [`contributing.md`][github-dotfiles-contributing] in [`remarkjs/.github`][github-dotfiles-health] for ways
+to get started.
+See [`support.md`][github-dotfiles-support] for ways to get help.
+
+This project has a [code of conduct][github-dotfiles-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][author]
+
+[api-label]: #label
+
+[api-lint-rule]: #lintrulemeta-rule
+
+[api-meta]: #meta
+
+[api-next]: #next
+
+[api-rule]: #rule
+
+[api-severity]: #severity
+
+[author]: https://wooorm.com
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/workflows/main/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/unified-lint-rule.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/unified-lint-rule
+
+[badge-funding-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-funding-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[badge-funding-url]: https://opencollective.com/unified
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/unified-lint-rule
+
+[badge-size-url]: https://bundlejs.com/?q=unified-lint-rule
+
+[esm-sh]: https://esm.sh
+
+[file-license]: https://github.com/remarkjs/remark-lint/blob/main/license
+
+[github-dotfiles-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[github-dotfiles-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[github-dotfiles-health]: https://github.com/remarkjs/.github
+
+[github-dotfiles-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[github-unified]: https://github.com/unifiedjs/unified
+
+[github-unified-plugin]: https://github.com/unifiedjs/unified#plugin
+
+[github-unist-node]: https://github.com/syntax-tree/unist#node
+
+[github-vfile]: https://github.com/vfile/vfile
+
+[npm-install]: https://docs.npmjs.com/cli/install
+
+[typescript]: https://www.typescriptlang.org
diff --git a/documents/markdown/remark/remark-lint_readme.md b/documents/markdown/remark/remark-lint_readme.md
new file mode 100644
index 0000000..69ea8c8
--- /dev/null
+++ b/documents/markdown/remark/remark-lint_readme.md
@@ -0,0 +1,724 @@
+# ![remark-lint][file-logo]
+
+[![Build][badge-build-image]][badge-build-url]
+[![Coverage][badge-coverage-image]][badge-coverage-url]
+[![Downloads][badge-downloads-image]][badge-downloads-url]
+[![Size][badge-size-image]][badge-size-url]
+[![Sponsors][badge-sponsors-image]][badge-collective-url]
+[![Backers][badge-backers-image]][badge-collective-url]
+[![Chat][badge-chat-image]][badge-chat-url]
+
+**[remark][github-remark]** plugins to check (lint) markdown code style.
+
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Presets](#presets)
+* [Rules](#rules)
+* [Configure](#configure)
+* [Ignore warnings](#ignore-warnings)
+* [Examples](#examples)
+ * [Example: check markdown on the API](#example-check-markdown-on-the-api)
+ * [Example: check and format markdown on the API](#example-check-and-format-markdown-on-the-api)
+ * [Example: check markdown on the CLI](#example-check-markdown-on-the-cli)
+ * [Example: check and format markdown on the CLI](#example-check-and-format-markdown-on-the-cli)
+* [Integrations](#integrations)
+* [Syntax](#syntax)
+* [Compatibility](#compatibility)
+* [Security](#security)
+* [Contribute](#contribute)
+* [License](#license)
+
+## What is this?
+
+
+
+You can use this to check markdown.
+Say we have a markdown file `doc/example.md` that contains:
+
+```markdown
+1) Hello, _Jupiter_ and *Neptune*!
+```
+
+Then assuming we installed dependencies and run:
+
+```sh
+npx remark doc/ --use remark-preset-lint-consistent --use remark-preset-lint-recommended
+```
+
+We would get a report like this:
+
+```text
+doc/example.md
+1:2 warning Unexpected ordered list marker `)`, expected `.` ordered-list-marker-style remark-lint
+1:25-1:34 warning Unexpected emphasis marker `*`, expected `_` emphasis-marker remark-lint
+ [cause]:
+ 1:11-1:20 info Emphasis marker style `'_'` first defined for `'consistent'` here emphasis-marker remark-lint
+
+⚠ 2 warnings
+```
+
+This GitHub repository is a monorepo that contains ±70 plugins (each a rule that
+checks one specific thing) and 3 presets (combinations of rules configured to
+check for certain styles).
+
+These packages are build on [unified][github-unified]
+([remark][github-remark]).
+**unified** is a project that inspects and transforms content with abstract
+syntax trees (ASTs).
+**remark** adds support for markdown to unified.
+**mdast** is the markdown AST that remark uses.
+These lint rules inspect mdast.
+
+## When should I use this?
+
+This project is useful when developers or technical writers are authoring
+documentation in markdown and you want to ensure that the markdown is
+consistent, free of bugs, and works well across different markdown parsers.
+
+These packages are quite good at checking markdown.
+They especially shine when combined with other
+[remark plugins][github-remark-plugin]
+and at letting you make your own rules.
+
+## Presets
+
+Presets are combinations of rules configured to check for certain styles.
+The following presets only contain lint rules but you can make your own that
+include any remark plugins or other presets.
+The presets that are maintained here:
+
+<!--presets start-->
+
+* [`remark-preset-lint-consistent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent) — rules that enforce consistency
+* [`remark-preset-lint-markdown-style-guide`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide) — rules that enforce the markdown style guide
+* [`remark-preset-lint-recommended`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended) — rules that prevent mistakes or stuff that fails across vendors.
+
+<!--presets end-->
+
+## Rules
+
+The rules that are maintained here:
+
+<!--
+ 👉 **Note**: the following list is automatically generated.
+-->
+
+<!--rules start-->
+
+* [`remark-lint-blockquote-indentation`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-blockquote-indentation) — check whitespace after block quote markers
+* [`remark-lint-checkbox-character-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-checkbox-character-style) — check list item checkbox characters
+* [`remark-lint-checkbox-content-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-checkbox-content-indent) — warn when too much whitespace follows list item checkboxes
+* [`remark-lint-code-block-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-code-block-style) — warn when code blocks do not adhere to a given style
+* [`remark-lint-correct-media-syntax`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-correct-media-syntax) — check for accidental bracket and paren mixup for images and links
+* [`remark-lint-definition-case`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-definition-case) — warn when definition labels are not lowercase
+* [`remark-lint-definition-sort`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-definition-sort) — check definition order
+* [`remark-lint-definition-spacing`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-definition-spacing) — warn when consecutive whitespace is used in a definition
+* [`remark-lint-directive-attribute-sort`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-directive-attribute-sort) — check directive attribute order
+* [`remark-lint-directive-collapsed-attribute`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-directive-collapsed-attribute) — check that collapsed attributes are used in directives
+* [`remark-lint-directive-quote-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-directive-quote-style) — check quotes of directive attributes
+* [`remark-lint-directive-shortcut-attribute`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-directive-shortcut-attribute) — check that shortcut attributes are used in directives
+* [`remark-lint-directive-unique-attribute-name`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-directive-unique-attribute-name) — check that attribute names are unique
+* [`remark-lint-emphasis-marker`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-emphasis-marker) — warn when emphasis markers violate the given style
+* [`remark-lint-fenced-code-flag`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-fenced-code-flag) — warn when fenced code blocks occur without language flag
+* [`remark-lint-fenced-code-marker`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-fenced-code-marker) — warn when fenced code markers violate the given style
+* [`remark-lint-file-extension`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-file-extension) — warn when the file’s extension violates the given style
+* [`remark-lint-final-definition`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-final-definition) — warn when definitions are not placed at the end of the file
+* [`remark-lint-final-newline`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-final-newline) — warn when a newline at the end of a file is missing
+* [`remark-lint-first-heading-level`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-first-heading-level) — warn when the first heading has a level other than a specified value
+* [`remark-lint-hard-break-spaces`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-hard-break-spaces) — warn when too many spaces are used to create a hard break
+* [`remark-lint-heading-increment`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-heading-increment) — warn when headings increment with more than 1 level at a time
+* [`remark-lint-heading-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-heading-style) — warn when heading style violates the given style
+* [`remark-lint-linebreak-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-linebreak-style) — warn when linebreaks violate a given or detected style
+* [`remark-lint-link-title-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-link-title-style) — warn when link and definition titles occur with incorrect quotes
+* [`remark-lint-list-item-bullet-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-bullet-indent) — warn when list item bullets are indented
+* [`remark-lint-list-item-content-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-content-indent) — warn when the content of a list item has mixed indentation
+* [`remark-lint-list-item-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-indent) — check the spacing between list item bullets and content
+* [`remark-lint-list-item-spacing`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-spacing) — warn when list looseness is incorrect
+* [`remark-lint-maximum-heading-length`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-maximum-heading-length) — warn when headings are too long
+* [`remark-lint-maximum-line-length`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-maximum-line-length) — warn when lines are too long
+* [`remark-lint-mdx-jsx-attribute-sort`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-mdx-jsx-attribute-sort) — check mdx jsx attribute order
+* [`remark-lint-mdx-jsx-no-void-children`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-mdx-jsx-no-void-children) — check mdx jsx quotes
+* [`remark-lint-mdx-jsx-quote-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-mdx-jsx-quote-style) — check mdx jsx quotes
+* [`remark-lint-mdx-jsx-self-close`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-mdx-jsx-self-close) — check that self-closing tags are used when possible
+* [`remark-lint-mdx-jsx-shorthand-attribute`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-mdx-jsx-shorthand-attribute) — check that shorthand attributes are used in MDX JSX
+* [`remark-lint-mdx-jsx-unique-attribute-name`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-mdx-jsx-unique-attribute-name) — check that mdx jsx attributes are unique
+* [`remark-lint-media-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-media-style) — check whether references or resources are used
+* [`remark-lint-no-blockquote-without-marker`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-blockquote-without-marker) — warn when block quotes have blank lines without markers
+* [`remark-lint-no-consecutive-blank-lines`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-consecutive-blank-lines) — warn for too many consecutive blank lines
+* [`remark-lint-no-duplicate-defined-urls`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-defined-urls) — warn on definitions that define the same urls
+* [`remark-lint-no-duplicate-definitions`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-definitions) — warn on duplicate definitions
+* [`remark-lint-no-duplicate-headings`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-headings) — warn on duplicate headings
+* [`remark-lint-no-duplicate-headings-in-section`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-headings-in-section) — warn on duplicate headings in a section
+* [`remark-lint-no-emphasis-as-heading`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-emphasis-as-heading) — warn when emphasis or importance is used instead of a heading
+* [`remark-lint-no-empty-url`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-empty-url) — warn on empty URLs in links and images
+* [`remark-lint-no-file-name-articles`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-articles) — warn when file name start with an article
+* [`remark-lint-no-file-name-consecutive-dashes`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-consecutive-dashes) — warn when file names contain consecutive dashes
+* [`remark-lint-no-file-name-irregular-characters`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-irregular-characters) — warn when file names contain irregular characters
+* [`remark-lint-no-file-name-mixed-case`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-mixed-case) — warn when file names use mixed case
+* [`remark-lint-no-file-name-outer-dashes`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-outer-dashes) — warn when file names contain initial or final dashes
+* [`remark-lint-no-heading-content-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-content-indent) — warn when heading content is indented
+* [`remark-lint-no-heading-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-indent) — warn when headings are indented
+* [`remark-lint-no-heading-like-paragraph`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-like-paragraph) — for too many hashes (h7+ “headings”)
+* [`remark-lint-no-heading-punctuation`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-punctuation) — warn when headings end in illegal characters
+* [`remark-lint-no-hidden-table-cell`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-hidden-table-cell) — check superfluous table cells
+* [`remark-lint-no-html`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-html) — warn when HTML nodes are used
+* [`remark-lint-no-literal-urls`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-literal-urls) — warn when URLs without angle brackets are used
+* [`remark-lint-no-missing-blank-lines`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-missing-blank-lines) — warn when missing blank lines
+* [`remark-lint-no-multiple-toplevel-headings`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-multiple-toplevel-headings) — warn when multiple top level headings are used
+* [`remark-lint-no-paragraph-content-indent`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-paragraph-content-indent) — warn when the content in paragraphs are indented
+* [`remark-lint-no-reference-like-url`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-reference-like-url) — warn when URLs are also defined identifiers
+* [`remark-lint-no-shell-dollars`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-shell-dollars) — warn when shell code is prefixed by dollars
+* [`remark-lint-no-shortcut-reference-image`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-shortcut-reference-image) — warn when shortcut reference images are used
+* [`remark-lint-no-shortcut-reference-link`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-shortcut-reference-link) — warn when shortcut reference links are used
+* [`remark-lint-no-table-indentation`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-table-indentation) — warn when tables are indented
+* [`remark-lint-no-tabs`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-tabs) — warn when hard tabs are used instead of spaces
+* [`remark-lint-no-undefined-references`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-undefined-references) — warn when references to undefined definitions are found
+* [`remark-lint-no-unneeded-full-reference-image`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-unneeded-full-reference-image) — check that full reference images can be collapsed
+* [`remark-lint-no-unneeded-full-reference-link`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-unneeded-full-reference-link) — check that full reference links can be collapsed
+* [`remark-lint-no-unused-definitions`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-unused-definitions) — warn when unused definitions are found
+* [`remark-lint-ordered-list-marker-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-ordered-list-marker-style) — warn when the markers of ordered lists violate a given style
+* [`remark-lint-ordered-list-marker-value`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-ordered-list-marker-value) — check the marker value of ordered lists
+* [`remark-lint-rule-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-rule-style) — warn when horizontal rules violate a given style
+* [`remark-lint-strikethrough-marker`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-strikethrough-marker) — warn when strikethrough markers violate the given style
+* [`remark-lint-strong-marker`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-strong-marker) — warn when importance (strong) markers violate the given style
+* [`remark-lint-table-cell-padding`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-table-cell-padding) — warn when table cells are incorrectly padded
+* [`remark-lint-table-pipe-alignment`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-table-pipe-alignment) — warn when table pipes are not aligned
+* [`remark-lint-table-pipes`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-table-pipes) — warn when table rows are not fenced with pipes
+* [`remark-lint-unordered-list-marker-style`](https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-unordered-list-marker-style) — warn when markers of unordered lists violate a given style
+
+<!--rules end-->
+
+<!--Old ID of this section:-->
+
+<a name="list-of-external-rules"></a>
+
+You can make and share your own rules, which can be used just like the rules
+maintained here.
+The following rules are maintained by the community:
+
+<!--
+ 👉 **Note**: this list is ordered based on the name without prefix, so
+ excluding `remark-lint-`
+-->
+
+* [`remark-lint-alphabetize-lists`](https://github.com/vhf/remark-lint-alphabetize-lists)
+ — ensure list items are in alphabetical order
+* [`remark-lint-appropriate-heading`](https://github.com/RichardLitt/remark-lint-appropriate-heading)
+ — check that the top level heading matches the directory name
+* [`remark-lint-are-links-valid`](https://github.com/wemake-services/remark-lint-are-links-valid)
+ — check if your links are reachable and/or unique
+* [`remark-lint-blank-lines-1-0-2`](https://github.com/vhf/remark-lint-blank-lines-1-0-2)
+ — ensure a specific number of lines between blocks
+* [`remark-lint-books-links`](https://github.com/vhf/remark-lint-books-links)
+ — ensure links in lists of books follow a standard format
+* [`remark-lint-check-toc`](https://github.com/ilyatitovich/remark-lint-check-toc)
+ — ensure TOC is correct
+* [`remark-lint-code`](https://github.com/Qard/remark-lint-code)
+ — lint fenced code blocks by corresponding language tags,
+ currently supporting [ESLint](https://github.com/Qard/remark-lint-code-eslint)
+* [`remark-lint-code-block-split-list`](https://github.com/ilyatitovich/remark-lint-code-block-split-list)
+ — ensure code block inside list doesn't split the list
+* [`remark-lint-double-link`](https://github.com/Scrum/remark-lint-double-link)
+ — ensure the same URL is not linked multiple times.
+* [`remark-lint-emoji-limit`](https://github.com/zerok/remark-lint-emoji-limit)
+ — enforce a limit of emoji per paragraph
+* [`remark-lint-fenced-code-flag-case`](https://github.com/Xunnamius/unified-utils/blob/main/packages/remark-lint-fenced-code-flag-case)
+ — warn when fenced code blocks have improperly cased language flags
+* [`remark-lint-frontmatter-schema`](https://github.com/JulianCataldo/remark-lint-frontmatter-schema)
+ — validate YAML frontmatter against a JSON schema
+* [`remark-lint-heading-capitalization`](https://github.com/ilyatitovich/remark-lint-heading-capitalization)
+ — ensure headings capitalization is correct
+* [`remark-lint-heading-length`](https://github.com/zerok/remark-lint-heading-length)
+ — ensure headings have the appropriate length
+* [`remark-lint-heading-whitespace`](https://github.com/vhf/remark-lint-heading-whitespace)
+ — ensure heading parsing is not broken by weird whitespace
+* [`remark-lint-heading-word-length`](https://github.com/Xunnamius/unified-utils/tree/main/packages/remark-lint-heading-word-length)
+ — warn when headings have too many or too few words with unicode support
+* [`remark-lint-list-item-style`](https://github.com/Xunnamius/unified-utils/blob/main/packages/remark-lint-list-item-style)
+ — warn when list items violate a given capitalization or punctuation style
+* [`remark-lint-match-punctuation`](https://github.com/laysent/remark-lint-plugins/tree/HEAD/packages/remark-lint-match-punctuation)
+ — ensures punctuations are used in pairs if necessary.
+* [`remark-lint-mdash-style`](https://github.com/alexandrtovmach/remark-lint-mdash-style)
+ — ensure em-dash (`—`) style follows a standard format
+* [`remark-lint-no-chinese-punctuation-in-number`](https://github.com/laysent/remark-lint-plugins/tree/HEAD/packages/remark-lint-no-chinese-punctuation-in-number)
+ — ensures that Chinese punctuation’s not used in numbers
+* [`remark-lint-no-dead-urls`](https://github.com/davidtheclark/remark-lint-no-dead-urls)
+ — check that external links are alive
+* [`remark-lint-no-empty-sections`](https://github.com/vhf/remark-lint-no-empty-sections)
+ — ensure every heading is followed by content (forming a section)
+* [`remark-lint-no-long-code`](https://github.com/laysent/remark-lint-plugins/tree/HEAD/packages/remark-lint-no-long-code)
+ — ensures that each line in code block won't be too long.
+* [`remark-lint-no-repeat-punctuation`](https://github.com/laysent/remark-lint-plugins/tree/HEAD/packages/remark-lint-no-repeat-punctuation)
+ — ensures punctuation is not repeated
+* [`remark-lint-no-url-trailing-slash`](https://github.com/vhf/remark-lint-no-url-trailing-slash)
+ — ensure that the `href` of links has no trailing slash
+* [`remark-lint-spaces-around-number`](https://github.com/laysent/remark-lint-plugins/tree/HEAD/packages/remark-lint-spaces-around-number)
+ — ensures there are spaces around number and Chinese.
+* [`remark-lint-spaces-around-word`](https://github.com/laysent/remark-lint-plugins/tree/HEAD/packages/remark-lint-spaces-around-word)
+ — ensures there are spaces around English word and Chinese.
+* [`remark-lint-write-good`](https://github.com/zerok/remark-lint-write-good)
+ — wrapper for `write-good`
+
+For help creating your own rule, it’s suggested to look at existing rules and to
+[follow this tutorial][file-create-a-custom-rule].
+
+## Configure
+
+<!--Old ID of this section:-->
+
+<a name="configuring-remark-lint"></a>
+
+All rules can be configured in one standard way:
+
+```js
+import {remark} from 'remark'
+import remarkLintFinalNewline from 'remark-lint-final-newline'
+import remarkLintMaximumLineLength from 'remark-lint-maximum-line-length'
+import remarkLintUnorderedListMarkerStyle from 'remark-lint-unordered-list-marker-style'
+
+remark()
+ // Pass `false` to turn a rule off — the code no longer runs:
+ .use(remarkLintFinalNewline, false)
+ // Pass `true` to turn a rule on again:
+ .use(remarkLintFinalNewline, true)
+ // You can also configure whether messages by the rule should be ignored,
+ // are seen as code style warnings (default), or are seen as exceptions.
+ // Ignore messages with `'off'` or `0` as the first value of an array:
+ .use(remarkLintFinalNewline, ['off'])
+ .use(remarkLintFinalNewline, [0])
+ // Use `'warn'`, `'on'`, or `1` to treat messages as code style warnings:
+ .use(remarkLintFinalNewline, ['warn'])
+ .use(remarkLintFinalNewline, ['on'])
+ .use(remarkLintFinalNewline, [1])
+ // Use `'error'` or `2` to treat messages as exceptions:
+ .use(remarkLintFinalNewline, ['error'])
+ .use(remarkLintFinalNewline, [2])
+ // Some rules accept options, and what they exactly accept is different for
+ // each rule (sometimes a string, a number, or an object).
+ // The following rule accepts a string:
+ .use(remarkLintUnorderedListMarkerStyle, '*')
+ .use(remarkLintUnorderedListMarkerStyle, ['on', '*'])
+ .use(remarkLintUnorderedListMarkerStyle, [1, '*'])
+ // The following rule accepts a number:
+ .use(remarkLintMaximumLineLength, 72)
+ .use(remarkLintMaximumLineLength, ['on', 72])
+ .use(remarkLintMaximumLineLength, [1, 72])
+```
+
+See [`use()` in `unified`s readme][github-unified-use] for more info on how to use
+plugins.
+
+> 🧑🏫 **Info**: messages in `remark-lint` are warnings instead of errors.
+> Other linters (such as ESLint) almost always use errors.
+> Why?
+> Those tools *only* check code style.
+> They don’t generate, transform, and format code, which is what remark and
+> unified focus on, too.
+> Errors in unified mean the same as an exception in your JavaScript code: a
+> crash.
+> That’s why we use warnings instead, because we continue checking more markdown
+> and continue running more plugins.
+
+## Ignore warnings
+
+You can use HTML comments to hide or show warnings from within markdown.
+Turn off all remark lint messages with `<!--lint disable-->` and turn them on
+again with `<!--lint enable-->`:
+
+```markdown
+<!--lint disable-->
+
+[Naiad]: https://naiad.neptune
+
+[Thalassa]: https://thalassa.neptune
+
+<!--lint enable-->
+```
+
+You can toggle specific rules by using their names without `remark-lint-`:
+
+```markdown
+<!--lint disable no-unused-definitions definition-case-->
+
+[Naiad]: https://naiad.neptune
+
+[Thalassa]: https://thalassa.neptune
+
+<!--lint enable no-unused-definitions definition-case-->
+```
+
+You can ignore a message in the next block with `<!--lint ignore-->`:
+
+```markdown
+<!--lint ignore-->
+
+[Naiad]: https://naiad.neptune
+```
+
+`ignore` also accepts a list of rules:
+
+```markdown
+<!--lint ignore no-unused-definitions definition-case-->
+
+[Naiad]: https://naiad.neptune
+```
+
+> 👉 **Note**: you’ll typically need blank lines between HTML comments and other
+> constructs.
+> More info is available at the package that handles comments,
+> [`remark-message-control`][github-remark-message-control].
+
+> 💡 **Tip**: MDX comments are supported when [`remark-mdx`][mdx-remark-mdx] is
+> used:
+>
+> ```mdx
+> {/* lint ignore no-unused-definitions definition-case */}
+> ```
+
+## Examples
+
+### Example: check markdown on the API
+
+The following example checks that markdown code style is consistent and follows
+some best practices.
+It also reconfigures a rule.
+First install dependencies:
+
+```sh
+npm install vfile-reporter remark remark-preset-lint-consistent remark-preset-lint-recommended remark-lint-list-item-indent --save-dev
+```
+
+Then create a module `example.js` that contains:
+
+```js
+import {remark} from 'remark'
+import remarkLintListItemIndent from 'remark-lint-list-item-indent'
+import remarkPresetLintConsistent from 'remark-preset-lint-consistent'
+import remarkPresetLintRecommended from 'remark-preset-lint-recommended'
+import {reporter} from 'vfile-reporter'
+
+const file = await remark()
+ // Check that markdown is consistent.
+ .use(remarkPresetLintConsistent)
+ // Few recommended rules.
+ .use(remarkPresetLintRecommended)
+ // `remark-lint-list-item-indent` is configured with `one` in the
+ // recommended preset, but if we’d prefer something else, it can be
+ // reconfigured:
+ .use(remarkLintListItemIndent, 'tab')
+ .process('1) Hello, _Jupiter_ and *Neptune*!')
+
+console.error(reporter(file))
+```
+
+Running that with `node example.js` yields:
+
+```text
+1:2 warning Unexpected ordered list marker `)`, expected `.` ordered-list-marker-style remark-lint
+1:4 warning Unexpected `1` space between list item marker and content, expected `2` spaces, add `1` space list-item-indent remark-lint
+1:25-1:34 warning Unexpected emphasis marker `*`, expected `_` emphasis-marker remark-lint
+ [cause]:
+ 1:11-1:20 info Emphasis marker style `'_'` first defined for `'consistent'` here emphasis-marker remark-lint
+1:35 warning Unexpected missing final newline character, expected line feed (`\n`) at end of file final-newline remark-lint
+
+⚠ 4 warnings
+```
+
+### Example: check and format markdown on the API
+
+remark lint rules *check* markdown.
+[`remark-stringify`][github-remark-stringify]
+(used in remark) *formats* markdown.
+When you configure lint rules and use remark to format markdown, you must
+manually synchronize their configuration:
+
+```js
+import {remark} from 'remark'
+import remarkLintEmphasisMarker from 'remark-lint-emphasis-marker'
+import remarkLintStrongMarker from 'remark-lint-strong-marker'
+import {reporter} from 'vfile-reporter'
+
+const file = await remark()
+ .use(remarkLintEmphasisMarker, '*')
+ .use(remarkLintStrongMarker, '*')
+ .use({
+ settings: {emphasis: '*', strong: '*'} // `remark-stringify` settings.
+ })
+ .process('_Hello_, __world__!')
+
+console.error(reporter(file))
+console.log(String(file))
+```
+
+Yields:
+
+```text
+ 1:1-1:8 warning Emphasis should use `*` as a marker emphasis-marker remark-lint
+ 1:10-1:19 warning Strong should use `*` as a marker strong-marker remark-lint
+
+⚠ 2 warnings
+```
+
+```markdown
+*Hello*, **world**!
+```
+
+Observe that the lint rules check the input and afterwards remark formats using
+asterisks.
+If that output was given the the processor, the lint rules would be satisfied.
+
+### Example: check markdown on the CLI
+
+This example checks markdown with [`remark-cli`][github-remark-cli].
+It assumes you’re in a Node.js package.
+First install dependencies:
+
+```sh
+npm install remark-cli remark-preset-lint-consistent remark-preset-lint-recommended remark-lint-list-item-indent --save-dev
+```
+
+Then add an npm script to your `package.json`:
+
+```js
+ /* … */
+ "scripts": {
+ /* … */
+ "check": "remark . --quiet --frail",
+ /* … */
+ },
+ /* … */
+```
+
+> 💡 **Tip**: add ESLint and such in the `check` script too.
+
+Observe that the above change adds a `check` script, which can be run with
+`npm run check`.
+It runs remark on all markdown files (`.`), shows only warnings and errors
+(`--quiet`), and exits as failed on warnings (`--frail`).
+Run `./node_modules/.bin/remark --help` for more info on the CLI.
+
+Now add a `remarkConfig` to your `package.json` to configure remark:
+
+```js
+ /* … */
+ "remarkConfig": {
+ "plugins": [
+ "remark-preset-lint-consistent", // Check that markdown is consistent.
+ "remark-preset-lint-recommended", // Few recommended rules.
+ // `remark-lint-list-item-indent` is configured with `one` in the
+ // recommended preset, but if we’d prefer something else, it can be
+ // reconfigured:
+ [
+ "remark-lint-list-item-indent",
+ "tab"
+ ]
+ ]
+ },
+ /* … */
+```
+
+> 👉 **Note**: you must remove the comments in the above examples when
+> copy/pasting them, as comments are not supported in `package.json` files.
+
+Finally run the npm script to check markdown files in your project:
+
+```sh
+npm run check
+```
+
+### Example: check and format markdown on the CLI
+
+remark lint rules *check* markdown.
+The CLI can *format* markdown.
+You can combine these features but have to manually synchronize their
+configuration.
+Please first follow the previous example (checking markdown on the CLI) and then
+change the npm script:
+
+```js
+ /* … */
+ "scripts": {
+ /* … */
+ "format": "remark . --frail --output --quiet",
+ /* … */
+ },
+ /* … */
+```
+
+The script is now called `format` to reflect what it does.
+It now includes an `--output` flag, which means it will overwrite existing files
+with changes.
+
+Update `remarkConfig`:
+
+```js
+ /* … */
+ "remarkConfig": {
+ "settings": {
+ "emphasis": "*",
+ "strong": "*"
+ },
+ "plugins": [
+ "remark-preset-lint-consistent",
+ "remark-preset-lint-recommended",
+ ["remark-lint-list-item-indent", "tab"]
+ ["remark-lint-emphasis-marker", "*"],
+ ["remark-lint-strong-marker", "*"]
+ ]
+ },
+ /* … */
+```
+
+This now includes `settings`, which configures
+[`remark-stringify`][github-remark-stringify], and explicitly prefers asterisks
+for emphasis and strong.
+Install the new dependencies:
+
+```sh
+npm install remark-lint-emphasis-marker remark-lint-strong-marker --save-dev
+```
+
+Finally run the npm script to format markdown files in your project:
+
+```sh
+npm run format
+```
+
+> 👉 **Note**: running `npm run format` now checks *and* formats your files.
+> The first time you run it, assuming you have underscores for emphasis and
+> strong, it would first warn and then format.
+> The second time you run it, no warnings should appear.
+
+## Integrations
+
+* [`vscode-remark-lint`](https://github.com/drewbourne/vscode-remark-lint)
+ ([VS Code](https://code.visualstudio.com))
+ — use `remark-lint` from Visual Studio Code
+* [`SublimeLinter-contrib-remark-lint`](https://packagecontrol.io/packages/SublimeLinter-contrib-remark-lint)
+ ([Sublime](https://www.sublimetext.com))
+ — use `remark-lint` from Sublime Text
+* [`ale`](https://github.com/w0rp/ale)
+ ([Vim](https://www.vim.org))
+ — use `remark-lint` from Vim
+* [`jest-runner-remark`](https://github.com/keplersj/jest-runner-remark)
+ ([Jest](https://jestjs.io))
+ — use remark with Jest
+
+## Syntax
+
+Markdown is parsed by [`remark-parse`][github-remark-parse]
+(included in `remark`)
+according to CommonMark.
+You can combine it with other plugins to add syntax extensions.
+Notable examples that deeply integrate with it are
+[`remark-gfm`][github-remark-gfm],
+[`remark-mdx`][mdx-remark-mdx],
+[`remark-frontmatter`][github-remark-frontmatter],
+[`remark-math`][github-remark-math], and
+[`remark-directive`][github-remark-directive].
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with maintained
+versions of Node.js.
+
+When we cut a new major release, we drop support for unmaintained versions of
+Node.
+This means we try to keep the current release line, `remark-lint@9`, compatible
+with Node.js 16.
+
+## Security
+
+Use of `remark-lint` does not change the tree so there are no openings for
+[cross-site scripting (XSS)][wikipedia-xss] attacks.
+Messages from linting rules may be hidden from user content though, causing
+builds to fail or pass.
+
+## Contribute
+
+See [`contributing.md`][health-contributing]
+in [`remarkjs/.github`][health]
+for ways to get started.
+See [`support.md`][health-support] for ways to get help.
+
+This project has a [code of conduct][health-coc].
+By interacting with this repository, organization, or community you agree to
+abide by its terms.
+
+## License
+
+[MIT][file-license] © [Titus Wormer][wooorm]
+
+<!-- Definitions -->
+
+[badge-backers-image]: https://opencollective.com/unified/backers/badge.svg
+
+[badge-build-image]: https://github.com/remarkjs/remark-lint/actions/workflows/main.yml/badge.svg
+
+[badge-build-url]: https://github.com/remarkjs/remark-lint/actions
+
+[badge-chat-image]: https://img.shields.io/badge/chat-discussions-success.svg
+
+[badge-chat-url]: https://github.com/remarkjs/remark/discussions
+
+[badge-collective-url]: https://opencollective.com/unified
+
+[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark-lint.svg
+
+[badge-coverage-url]: https://codecov.io/github/remarkjs/remark-lint
+
+[badge-downloads-image]: https://img.shields.io/npm/dm/remark-lint.svg
+
+[badge-downloads-url]: https://www.npmjs.com/package/remark-lint
+
+[badge-size-image]: https://img.shields.io/bundlejs/size/remark-lint
+
+[badge-size-url]: https://bundlejs.com/?q=remark-lint
+
+[badge-sponsors-image]: https://opencollective.com/unified/sponsors/badge.svg
+
+[file-create-a-custom-rule]: doc/create-a-custom-rule.md
+
+[file-license]: license
+
+[file-logo]: https://raw.githubusercontent.com/remarkjs/remark-lint/014fca7/logo.svg?sanitize=true
+
+[github-remark]: https://github.com/remarkjs/remark
+
+[github-remark-cli]: https://github.com/remarkjs/remark/tree/main/packages/remark-cli
+
+[github-remark-directive]: https://github.com/remarkjs/remark-directive
+
+[github-remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter
+
+[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
+
+[github-remark-math]: https://github.com/remarkjs/remark-math
+
+[github-remark-message-control]: https://github.com/remarkjs/remark-message-control
+
+[github-remark-parse]: https://github.com/remarkjs/remark/tree/main/packages/remark-parse
+
+[github-remark-plugin]: https://github.com/remarkjs/remark#plugins
+
+[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
+
+[github-unified]: https://github.com/unifiedjs/unified
+
+[github-unified-use]: https://github.com/unifiedjs/unified#processoruseplugin-options
+
+[health]: https://github.com/remarkjs/.github
+
+[health-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
+
+[health-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
+
+[health-support]: https://github.com/remarkjs/.github/blob/main/support.md
+
+[mdx-remark-mdx]: https://mdxjs.com/packages/remark-mdx/
+
+[wikipedia-xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
+
+[wooorm]: https://wooorm.com
diff --git a/documents/odt/abiword/10177-symptoms.abw.exp.raw.odt b/documents/odt/abiword/10177-symptoms.abw.exp.raw.odt
new file mode 100644
index 0000000..12e67d5
--- /dev/null
+++ b/documents/odt/abiword/10177-symptoms.abw.exp.raw.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:73520f7e8194015ec1fde3cd0a6cd9a4ad02e1ed1b8222bb9996556071ae2482
+size 3420
diff --git a/documents/odt/abiword/1758-insane_bullets.abw.exp.raw.odt b/documents/odt/abiword/1758-insane_bullets.abw.exp.raw.odt
new file mode 100644
index 0000000..a5ce238
--- /dev/null
+++ b/documents/odt/abiword/1758-insane_bullets.abw.exp.raw.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:58c30e21c2ce1c617611a2c2b0cf41822d365fdf8abd9245c5ca0553e538b9fa
+size 3256
diff --git a/documents/odt/abiword/6754-hidden.abw.exp.raw.odt b/documents/odt/abiword/6754-hidden.abw.exp.raw.odt
new file mode 100644
index 0000000..11df5ae
--- /dev/null
+++ b/documents/odt/abiword/6754-hidden.abw.exp.raw.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b4be156f48d28722a3b61f111d394d0f9f3fb107ded68def4012db03327b218a
+size 4768
diff --git a/documents/odt/abiword/7081-genealogy.abw.exp.raw.odt b/documents/odt/abiword/7081-genealogy.abw.exp.raw.odt
new file mode 100644
index 0000000..58d670a
--- /dev/null
+++ b/documents/odt/abiword/7081-genealogy.abw.exp.raw.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d024a3055180a7df24f05b9d596bd57ef9cb82b57ca06f48c62fa7071aff3a20
+size 12634
diff --git a/documents/odt/abiword/7420-google_hidden.abw.exp.raw.odt b/documents/odt/abiword/7420-google_hidden.abw.exp.raw.odt
new file mode 100644
index 0000000..7f53ce0
--- /dev/null
+++ b/documents/odt/abiword/7420-google_hidden.abw.exp.raw.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:787c6514510a090230d3992b58fdcf772ffa7ac27c0bb638c7fd3e31560a2161
+size 3786
diff --git a/documents/odt/abiword/9218-bullet_in_table.abw.exp.raw.odt b/documents/odt/abiword/9218-bullet_in_table.abw.exp.raw.odt
new file mode 100644
index 0000000..219edc7
--- /dev/null
+++ b/documents/odt/abiword/9218-bullet_in_table.abw.exp.raw.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1675f3b3a49280bd7f7e119367ec17bfea7fd5be655315bfefee6d73b221d742
+size 3055
diff --git a/documents/odt/abiword/9223-table_in_textbox.abw.exp.raw.odt b/documents/odt/abiword/9223-table_in_textbox.abw.exp.raw.odt
new file mode 100644
index 0000000..0574722
--- /dev/null
+++ b/documents/odt/abiword/9223-table_in_textbox.abw.exp.raw.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7a8568258272cc5df898f4f965b57fc2fd49772549baef73245cd6fdc9cdf6a3
+size 3116
diff --git a/documents/odt/abiword/9225-table_in_list.abw.exp.raw.odt b/documents/odt/abiword/9225-table_in_list.abw.exp.raw.odt
new file mode 100644
index 0000000..1b0e8df
--- /dev/null
+++ b/documents/odt/abiword/9225-table_in_list.abw.exp.raw.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f9a76aee0965bf61753ea598b579c69a0feb4c8bb452dba4b51cea2294accc89
+size 3056
diff --git a/documents/odt/abiword/9870-break_in_list.abw.exp.raw.odt b/documents/odt/abiword/9870-break_in_list.abw.exp.raw.odt
new file mode 100644
index 0000000..1084fdd
--- /dev/null
+++ b/documents/odt/abiword/9870-break_in_list.abw.exp.raw.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b62f983bd7ae9056bb26bf7b29bf577d84007475a0485169248557b1e1a40e26
+size 2725
diff --git a/documents/odt/abiword/bug10399.odt b/documents/odt/abiword/bug10399.odt
new file mode 100644
index 0000000..ce87eac
--- /dev/null
+++ b/documents/odt/abiword/bug10399.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:038c27671ecfd8942db275d2e6259084ab8f9e9499e6055ab6fb8a155287c368
+size 116709
diff --git a/documents/odt/abiword/bug10808.odt b/documents/odt/abiword/bug10808.odt
new file mode 100644
index 0000000..34e4fde
--- /dev/null
+++ b/documents/odt/abiword/bug10808.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:dd4f659abc27f78c360a8493dd9dc340d2e48058b0c805811a4487eaf7f64384
+size 6510
diff --git a/documents/odt/abiword/cjk-office.odt b/documents/odt/abiword/cjk-office.odt
new file mode 100644
index 0000000..bc79e5c
--- /dev/null
+++ b/documents/odt/abiword/cjk-office.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8806108d4630d25122977921f66e66f12c6155b9cfafd15e2f0f46ca9539855c
+size 13668
diff --git a/documents/odt/abiword/dad_indt.odt b/documents/odt/abiword/dad_indt.odt
new file mode 100644
index 0000000..bcb0384
--- /dev/null
+++ b/documents/odt/abiword/dad_indt.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f88d9bd89465cda2478b529fe656f0c7c48e3b20bc825eddca4bc44f4f3e7ecf
+size 18700
diff --git a/documents/odt/abiword/dbk_corner_cases_general.abw.exp.raw.odt b/documents/odt/abiword/dbk_corner_cases_general.abw.exp.raw.odt
new file mode 100644
index 0000000..cb00e30
--- /dev/null
+++ b/documents/odt/abiword/dbk_corner_cases_general.abw.exp.raw.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c9373940f8ed66e9489c88a6129804fc7221ef7175f8d7ec8d2f5c5c2f6916b6
+size 6714
diff --git a/documents/odt/abiword/document.odt b/documents/odt/abiword/document.odt
new file mode 100644
index 0000000..cc0fa79
--- /dev/null
+++ b/documents/odt/abiword/document.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fab955bc55aad357fff7227135856e5ce3a39c9fcc28e888cc855912c971211c
+size 12700
diff --git a/documents/odt/abiword/equation.odt b/documents/odt/abiword/equation.odt
new file mode 100644
index 0000000..ef4dcf5
--- /dev/null
+++ b/documents/odt/abiword/equation.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b425ab450d8df163e54250211d72a1cb1926e89b73e256539d84fe55ed7cff67
+size 9338
diff --git a/documents/odt/abiword/external.odt b/documents/odt/abiword/external.odt
new file mode 100644
index 0000000..4ae3fc6
--- /dev/null
+++ b/documents/odt/abiword/external.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bb03ea41fab90e22fc420e008ebf19aa6bb14059ce7583cf269aeaae05972b01
+size 13251
diff --git a/documents/odt/abiword/hello_world.abw.exp.raw.odt b/documents/odt/abiword/hello_world.abw.exp.raw.odt
new file mode 100644
index 0000000..44ab687
--- /dev/null
+++ b/documents/odt/abiword/hello_world.abw.exp.raw.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:99101344df3baca9c643f57cfa0d71ecc9c54219b098fa5d0d6c8ae640c9aaf4
+size 2641
diff --git a/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_10177-symptoms.abw.exp.raw.odt.odt b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_10177-symptoms.abw.exp.raw.odt.odt
new file mode 100644
index 0000000..6304cca
--- /dev/null
+++ b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_10177-symptoms.abw.exp.raw.odt.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:47293705c712eff0cc6e99895ba965bf02d17ed8eaadcd13dd655f4ed08f5f9b
+size 3420
diff --git a/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_1758-insane_bullets.abw.exp.raw.odt.odt b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_1758-insane_bullets.abw.exp.raw.odt.odt
new file mode 100644
index 0000000..dd2b597
--- /dev/null
+++ b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_1758-insane_bullets.abw.exp.raw.odt.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:30b10d13cd6c0e7625bd7952083f2da60339951ff10f4caa93a5ccf2691bd5a3
+size 3256
diff --git a/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_6754-hidden.abw.exp.raw.odt.odt b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_6754-hidden.abw.exp.raw.odt.odt
new file mode 100644
index 0000000..86dd83a
--- /dev/null
+++ b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_6754-hidden.abw.exp.raw.odt.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e7a199d4103e732852d031b3f198e6938407ff194359ebf1049521ba8bc5c0bc
+size 4768
diff --git a/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_7081-genealogy.abw.exp.raw.odt.odt b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_7081-genealogy.abw.exp.raw.odt.odt
new file mode 100644
index 0000000..b88b4eb
--- /dev/null
+++ b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_7081-genealogy.abw.exp.raw.odt.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e54b8ed89c4ebe90aababe0f0ce4adf1e7acbc5f04decc7ee1364bcd248bb03a
+size 12634
diff --git a/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_7420-google_hidden.abw.exp.raw.odt.odt b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_7420-google_hidden.abw.exp.raw.odt.odt
new file mode 100644
index 0000000..b800571
--- /dev/null
+++ b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_7420-google_hidden.abw.exp.raw.odt.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d7df6b5db745b3a9addf589dea001d17b03f57266d911f795aa25368f2d7eff0
+size 3786
diff --git a/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_9218-bullet_in_table.abw.exp.raw.odt.odt b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_9218-bullet_in_table.abw.exp.raw.odt.odt
new file mode 100644
index 0000000..3fb7a3b
--- /dev/null
+++ b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_9218-bullet_in_table.abw.exp.raw.odt.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ec65ec54b553f26d9fa271d27bc0faab1206cefdf9fbb82373962fc9329f4fa7
+size 3055
diff --git a/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_9223-table_in_textbox.abw.exp.raw.odt.odt b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_9223-table_in_textbox.abw.exp.raw.odt.odt
new file mode 100644
index 0000000..3d74360
--- /dev/null
+++ b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_9223-table_in_textbox.abw.exp.raw.odt.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4ed5a588388e4f6328a55d3d38931e3e88c3a08ee17f784478e18235287a233c
+size 3116
diff --git a/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_9225-table_in_list.abw.exp.raw.odt.odt b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_9225-table_in_list.abw.exp.raw.odt.odt
new file mode 100644
index 0000000..686e2e6
--- /dev/null
+++ b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_9225-table_in_list.abw.exp.raw.odt.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ba742563b75221ca02072c84caad9f7d44901f19b2a047753aa225a336f8d5f2
+size 3056
diff --git a/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_9870-break_in_list.abw.exp.raw.odt.odt b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_9870-break_in_list.abw.exp.raw.odt.odt
new file mode 100644
index 0000000..412e77d
--- /dev/null
+++ b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_9870-break_in_list.abw.exp.raw.odt.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:457640c658f993ac463903108cd63641fe783a1ba22ca32f8d3d41091e0f7003
+size 2725
diff --git a/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_dbk_corner_cases_general.abw.exp.raw.odt.odt b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_dbk_corner_cases_general.abw.exp.raw.odt.odt
new file mode 100644
index 0000000..075aa74
--- /dev/null
+++ b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_dbk_corner_cases_general.abw.exp.raw.odt.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:07261e9e63812bfb88f92a52ab1cdd8dafc70be14c0215d815f5170bdd6e7c19
+size 6750
diff --git a/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_hello_world.abw.exp.raw.odt.odt b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_hello_world.abw.exp.raw.odt.odt
new file mode 100644
index 0000000..42462e1
--- /dev/null
+++ b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_hello_world.abw.exp.raw.odt.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0fc2d286b57b4d375fe8d3e03339a7859bb2fe3c73f400527ff9d7fc8719f8ee
+size 2641
diff --git a/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_simple-chart.abw.exp.raw.odt.odt b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_simple-chart.abw.exp.raw.odt.odt
new file mode 100644
index 0000000..93113ba
--- /dev/null
+++ b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_simple-chart.abw.exp.raw.odt.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e98b761da815ec87dc8665a3b018db5a61a12dea1345ad5f1a3684df4fb4dabd
+size 28102
diff --git a/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_simple-equation.abw.exp.raw.odt.odt b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_simple-equation.abw.exp.raw.odt.odt
new file mode 100644
index 0000000..fac3d37
--- /dev/null
+++ b/documents/odt/abiword/scrape_abiword-testsuite_impexp_abw_raw-trunk_simple-equation.abw.exp.raw.odt.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a6db23b63cc269745328e5f58bc136da0d86e997d481701f6fa07dc6b2d845ed
+size 3720
diff --git a/documents/odt/abiword/simple-chart.abw.exp.raw.odt b/documents/odt/abiword/simple-chart.abw.exp.raw.odt
new file mode 100644
index 0000000..1c6f920
--- /dev/null
+++ b/documents/odt/abiword/simple-chart.abw.exp.raw.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2abbdeda2fc3b114be3e38e0194f84ce2cb69e54db20db6dc24740def547d749
+size 28102
diff --git a/documents/odt/abiword/simple-equation.abw.exp.raw.odt b/documents/odt/abiword/simple-equation.abw.exp.raw.odt
new file mode 100644
index 0000000..cdadf60
--- /dev/null
+++ b/documents/odt/abiword/simple-equation.abw.exp.raw.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:90d3df2f446b0aef8324294f1dda336c13f08455a0e18ac8d51888a9bcfd42cc
+size 3720
diff --git a/documents/odt/abiword/ucf-alignment.odt b/documents/odt/abiword/ucf-alignment.odt
new file mode 100644
index 0000000..be4a9ff
--- /dev/null
+++ b/documents/odt/abiword/ucf-alignment.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0a6eacc72535b3f274fdbb55af562cacb49338626d3469a49dca3f7d2d5794b0
+size 2983
diff --git a/documents/odt/abiword/ucf-automaticTextIndent.odt b/documents/odt/abiword/ucf-automaticTextIndent.odt
new file mode 100644
index 0000000..da7c38f
--- /dev/null
+++ b/documents/odt/abiword/ucf-automaticTextIndent.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:59806a456d2c1a7dbdb03d4d3d892b3c3b600605d31274562a3c0069ee21e8b3
+size 2662
diff --git a/documents/odt/abiword/ucf-basicContents.odt b/documents/odt/abiword/ucf-basicContents.odt
new file mode 100644
index 0000000..d6fe2d8
--- /dev/null
+++ b/documents/odt/abiword/ucf-basicContents.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:64f1d5b5c65a5a8fe666e6f2ff2d866aac5a6f19f3d6ca6ffee104df1b23960d
+size 2833
diff --git a/documents/odt/abiword/ucf-bold.odt b/documents/odt/abiword/ucf-bold.odt
new file mode 100644
index 0000000..bd74269
--- /dev/null
+++ b/documents/odt/abiword/ucf-bold.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0ea9f00870afeb42841d72a82e6322d01603c6a33dbe5e20931f7b77dbf29808
+size 3221
diff --git a/documents/odt/abiword/ucf-border.odt b/documents/odt/abiword/ucf-border.odt
new file mode 100644
index 0000000..fdc87a3
--- /dev/null
+++ b/documents/odt/abiword/ucf-border.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d03c22522702c83bbfb9f146fbb2785655a4eedcb61b4b7e9fd7d87335827d62
+size 2718
diff --git a/documents/odt/abiword/ucf-borderLineWidth-table.odt b/documents/odt/abiword/ucf-borderLineWidth-table.odt
new file mode 100644
index 0000000..addec85
--- /dev/null
+++ b/documents/odt/abiword/ucf-borderLineWidth-table.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9ce6c5e188f6c67bd542008f732b01d62ac3f5b80810dde8e5c150b7c4bde9b3
+size 2771
diff --git a/documents/odt/abiword/ucf-borderLineWidth.odt b/documents/odt/abiword/ucf-borderLineWidth.odt
new file mode 100644
index 0000000..cee9cb1
--- /dev/null
+++ b/documents/odt/abiword/ucf-borderLineWidth.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7cd63c99958fb5518309bde51b12920f835e8a44d317fda7eca9c703f6f25b23
+size 2740
diff --git a/documents/odt/abiword/ucf-borderModelProperty.odt b/documents/odt/abiword/ucf-borderModelProperty.odt
new file mode 100644
index 0000000..760a95d
--- /dev/null
+++ b/documents/odt/abiword/ucf-borderModelProperty.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1ae68fbeb6b24bf6265828e1b45a37cc619390c87391255f88d0940c4cbbea5a
+size 2692
diff --git a/documents/odt/abiword/ucf-breakBeforeAndBreakAfter-column.odt b/documents/odt/abiword/ucf-breakBeforeAndBreakAfter-column.odt
new file mode 100644
index 0000000..80f826f
--- /dev/null
+++ b/documents/odt/abiword/ucf-breakBeforeAndBreakAfter-column.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7e91ef20fde5ce98d63771640c949ed9d49caaf77f5f83237ce250962e97c216
+size 2749
diff --git a/documents/odt/abiword/ucf-breakBeforeAndBreakAfter-table.odt b/documents/odt/abiword/ucf-breakBeforeAndBreakAfter-table.odt
new file mode 100644
index 0000000..77cbd3e
--- /dev/null
+++ b/documents/odt/abiword/ucf-breakBeforeAndBreakAfter-table.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ee234d467be24484e1f4cf754c6a52aa83ca4d6ebd19309c57507bc4ef7d4c46
+size 2690
diff --git a/documents/odt/abiword/ucf-breakBeforeAndBreakAfter-tablerow.odt b/documents/odt/abiword/ucf-breakBeforeAndBreakAfter-tablerow.odt
new file mode 100644
index 0000000..4e0f05b
--- /dev/null
+++ b/documents/odt/abiword/ucf-breakBeforeAndBreakAfter-tablerow.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fdf64c8f1a5f7e44f390f932085ad9d876e85cfd159f476a2c4025bc7badf144
+size 2691
diff --git a/documents/odt/abiword/ucf-breakBeforeAndBreakAfter.odt b/documents/odt/abiword/ucf-breakBeforeAndBreakAfter.odt
new file mode 100644
index 0000000..cc7129f
--- /dev/null
+++ b/documents/odt/abiword/ucf-breakBeforeAndBreakAfter.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2df266b57f4cd223d95835ad69aa767731e4173b87298e2f9492ee554a07384e
+size 2670
diff --git a/documents/odt/abiword/ucf-bulletedList.odt b/documents/odt/abiword/ucf-bulletedList.odt
new file mode 100644
index 0000000..8ee6dc6
--- /dev/null
+++ b/documents/odt/abiword/ucf-bulletedList.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:08faca97482923cca067b0f4f0e396906043486f9882be54cbda7cbc0ce3f70c
+size 3049
diff --git a/documents/odt/abiword/ucf-cellBackground.odt b/documents/odt/abiword/ucf-cellBackground.odt
new file mode 100644
index 0000000..fcb936a
--- /dev/null
+++ b/documents/odt/abiword/ucf-cellBackground.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3905aedf6184b5dd97d9137fe08946faadcd8fb00135b2b3aa722ebdff2232eb
+size 2719
diff --git a/documents/odt/abiword/ucf-cellBorder.odt b/documents/odt/abiword/ucf-cellBorder.odt
new file mode 100644
index 0000000..6a7031d
--- /dev/null
+++ b/documents/odt/abiword/ucf-cellBorder.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4073f16f028ccc1492840c006c36777460da185864b700ee54ee1e5b45fd1ca8
+size 2707
diff --git a/documents/odt/abiword/ucf-cellProtect.odt b/documents/odt/abiword/ucf-cellProtect.odt
new file mode 100644
index 0000000..5ab7086
--- /dev/null
+++ b/documents/odt/abiword/ucf-cellProtect.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2541cdebc447e1a77a83c6ed6a524214000cca486b9811548e5c8a4cdfa7d990
+size 2718
diff --git a/documents/odt/abiword/ucf-cellShadow.odt b/documents/odt/abiword/ucf-cellShadow.odt
new file mode 100644
index 0000000..c6670de
--- /dev/null
+++ b/documents/odt/abiword/ucf-cellShadow.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:54a4d06220a0f189b790b2e0f686c4b77a93b9e462213883eb2a4fd4e1f1bfba
+size 2689
diff --git a/documents/odt/abiword/ucf-color.odt b/documents/odt/abiword/ucf-color.odt
new file mode 100644
index 0000000..157632b
--- /dev/null
+++ b/documents/odt/abiword/ucf-color.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b0205f229cc12cd5dc2a56680db0ef7937b6454014a7ef3edbdcb9ac57361af1
+size 2842
diff --git a/documents/odt/abiword/ucf-columnWidth.odt b/documents/odt/abiword/ucf-columnWidth.odt
new file mode 100644
index 0000000..b8f3cf2
--- /dev/null
+++ b/documents/odt/abiword/ucf-columnWidth.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:365c8cc7f689e9660c50d274e5c6e258374e906355fad1e6e19fb83c5cfccfc1
+size 2840
diff --git a/documents/odt/abiword/ucf-continueNumbering.odt b/documents/odt/abiword/ucf-continueNumbering.odt
new file mode 100644
index 0000000..26a2a82
--- /dev/null
+++ b/documents/odt/abiword/ucf-continueNumbering.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:545faf6274631dfcb6f3b226ae149911704caf24e1ec0f4e2de30dcd36b76314
+size 2915
diff --git a/documents/odt/abiword/ucf-country.odt b/documents/odt/abiword/ucf-country.odt
new file mode 100644
index 0000000..ece1065
--- /dev/null
+++ b/documents/odt/abiword/ucf-country.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:275fe51d53960142bd4fda6f4763614f30d63fb5ee821d4a0054d931ae055318
+size 2875
diff --git a/documents/odt/abiword/ucf-delimiterCharacter.odt b/documents/odt/abiword/ucf-delimiterCharacter.odt
new file mode 100644
index 0000000..22d227d
--- /dev/null
+++ b/documents/odt/abiword/ucf-delimiterCharacter.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:87143849f82e0e83dd28539bde6d190363c7636a88867f14445211f57cedadcc
+size 2644
diff --git a/documents/odt/abiword/ucf-diagonalLines.odt b/documents/odt/abiword/ucf-diagonalLines.odt
new file mode 100644
index 0000000..dc9417d
--- /dev/null
+++ b/documents/odt/abiword/ucf-diagonalLines.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cc01ccf6249b25219789bb6d5463676aaca1a79e6508151b21f528a30b7f7f8a
+size 2751
diff --git a/documents/odt/abiword/ucf-direction.odt b/documents/odt/abiword/ucf-direction.odt
new file mode 100644
index 0000000..335c61b
--- /dev/null
+++ b/documents/odt/abiword/ucf-direction.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b6d9f693c4722326edc5a5211f957ccc77f94b8a05f88b2d79769cb076913d72
+size 2703
diff --git a/documents/odt/abiword/ucf-display.odt b/documents/odt/abiword/ucf-display.odt
new file mode 100644
index 0000000..e9e3382
--- /dev/null
+++ b/documents/odt/abiword/ucf-display.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:91ca792739c6cbde114ef4b57175b14e81a0f2d66bf69bd06c1e67d41f61d7b0
+size 2676
diff --git a/documents/odt/abiword/ucf-dropCapsDistance.odt b/documents/odt/abiword/ucf-dropCapsDistance.odt
new file mode 100644
index 0000000..fe42930
--- /dev/null
+++ b/documents/odt/abiword/ucf-dropCapsDistance.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3404d5c119d3a588a56932b83ea2e393c9573d13c65d672c60724a1d408e13a9
+size 2670
diff --git a/documents/odt/abiword/ucf-dropCapsLength.odt b/documents/odt/abiword/ucf-dropCapsLength.odt
new file mode 100644
index 0000000..07dbb6f
--- /dev/null
+++ b/documents/odt/abiword/ucf-dropCapsLength.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:36c98664a276c6fed06e8d3280e87c1304dd480bc060cf6fac88e0eb190c3a3d
+size 2633
diff --git a/documents/odt/abiword/ucf-dropCapsLines.odt b/documents/odt/abiword/ucf-dropCapsLines.odt
new file mode 100644
index 0000000..7522177
--- /dev/null
+++ b/documents/odt/abiword/ucf-dropCapsLines.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5ab737d87b5b9e7cb9006019bff62c41040ad906f9a955728cd6060f586e8c32
+size 2655
diff --git a/documents/odt/abiword/ucf-dropCapsTextStyle.odt b/documents/odt/abiword/ucf-dropCapsTextStyle.odt
new file mode 100644
index 0000000..f756f5a
--- /dev/null
+++ b/documents/odt/abiword/ucf-dropCapsTextStyle.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:18f32d5b674c3d29a1b3858ea5afafaed9bdf50f0588063e17c7cb02e16d395e
+size 2704
diff --git a/documents/odt/abiword/ucf-embededBulletedList.odt b/documents/odt/abiword/ucf-embededBulletedList.odt
new file mode 100644
index 0000000..2edc2bc
--- /dev/null
+++ b/documents/odt/abiword/ucf-embededBulletedList.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c0994cefaba55ef80de9210775ccb03284d270993b5181ef2d8d2d310f197f70
+size 3160
diff --git a/documents/odt/abiword/ucf-fixedLineHeight.odt b/documents/odt/abiword/ucf-fixedLineHeight.odt
new file mode 100644
index 0000000..f1fceac
--- /dev/null
+++ b/documents/odt/abiword/ucf-fixedLineHeight.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ba549c8cc7b4a28e900fb5b4b5d5cac6cea1878c1b807df5f2204f529f8e1846
+size 2884
diff --git a/documents/odt/abiword/ucf-foldAndItalic.odt b/documents/odt/abiword/ucf-foldAndItalic.odt
new file mode 100644
index 0000000..a00c311
--- /dev/null
+++ b/documents/odt/abiword/ucf-foldAndItalic.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8383e2b91c660df5a8edc387288f5936095c326d393ee4979340e40b73c6f169
+size 2955
diff --git a/documents/odt/abiword/ucf-foldVariant.odt b/documents/odt/abiword/ucf-foldVariant.odt
new file mode 100644
index 0000000..d634926
--- /dev/null
+++ b/documents/odt/abiword/ucf-foldVariant.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:15bc13054dbf060576874b9ce18e6ce88fe1acb1606c91978ac33104c16efcfc
+size 2961
diff --git a/documents/odt/abiword/ucf-font-independentLineSpacing.odt b/documents/odt/abiword/ucf-font-independentLineSpacing.odt
new file mode 100644
index 0000000..582294c
--- /dev/null
+++ b/documents/odt/abiword/ucf-font-independentLineSpacing.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e12a1c28eac292e42f092f4b44cf910390b4e9d5a6139b043e091b6276c63725
+size 2909
diff --git a/documents/odt/abiword/ucf-fontCharacterSet.odt b/documents/odt/abiword/ucf-fontCharacterSet.odt
new file mode 100644
index 0000000..7689195
--- /dev/null
+++ b/documents/odt/abiword/ucf-fontCharacterSet.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b219b6a00782362eb90f7dcb2255ddd241a7832875f16f979051897abc8ff0a7
+size 2852
diff --git a/documents/odt/abiword/ucf-fontColors.odt b/documents/odt/abiword/ucf-fontColors.odt
new file mode 100644
index 0000000..60fe936
--- /dev/null
+++ b/documents/odt/abiword/ucf-fontColors.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:29bf4560550c8cb4d6eaeeca7a5e47aa819c7ddb404437933d669e0cc7ae247c
+size 2954
diff --git a/documents/odt/abiword/ucf-fontFamily.odt b/documents/odt/abiword/ucf-fontFamily.odt
new file mode 100644
index 0000000..eaeaf77
--- /dev/null
+++ b/documents/odt/abiword/ucf-fontFamily.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e46b036c91641192964770d63387f5cfe142b26a025d0a501296b0897ce8ec4f
+size 2962
diff --git a/documents/odt/abiword/ucf-fontFamilyGeneric.odt b/documents/odt/abiword/ucf-fontFamilyGeneric.odt
new file mode 100644
index 0000000..d1bafb4
--- /dev/null
+++ b/documents/odt/abiword/ucf-fontFamilyGeneric.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d4980235d0d525d4145b11db5a00637c581b0fec32d24434c4a115935a15c712
+size 2973
diff --git a/documents/odt/abiword/ucf-fontName.odt b/documents/odt/abiword/ucf-fontName.odt
new file mode 100644
index 0000000..4c78444
--- /dev/null
+++ b/documents/odt/abiword/ucf-fontName.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d0d551e389a2f93fef4eda21e4c21aeb127956b806613e366c79bac664fff154
+size 2957
diff --git a/documents/odt/abiword/ucf-fontPitch.odt b/documents/odt/abiword/ucf-fontPitch.odt
new file mode 100644
index 0000000..fb62a06
--- /dev/null
+++ b/documents/odt/abiword/ucf-fontPitch.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7af9b4779c7cec8e7c47b7972863c04889e9b8335b3d87a7f0786f636b3b7f59
+size 2883
diff --git a/documents/odt/abiword/ucf-fontRelief.odt b/documents/odt/abiword/ucf-fontRelief.odt
new file mode 100644
index 0000000..3728d13
--- /dev/null
+++ b/documents/odt/abiword/ucf-fontRelief.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bef4db05e54900d25d3d98b5ecd85172068b50b02b3202713e910ce2f94decb1
+size 2853
diff --git a/documents/odt/abiword/ucf-fontRelif.odt b/documents/odt/abiword/ucf-fontRelif.odt
new file mode 100644
index 0000000..c1cdc83
--- /dev/null
+++ b/documents/odt/abiword/ucf-fontRelif.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4160150e3d2cfd25121652ac430c24cc1b63b875f166835784fed2b3242957f4
+size 2947
diff --git a/documents/odt/abiword/ucf-fontSize-fp.odt b/documents/odt/abiword/ucf-fontSize-fp.odt
new file mode 100644
index 0000000..cd8a4ab
--- /dev/null
+++ b/documents/odt/abiword/ucf-fontSize-fp.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2d2587a3ea5748494a1231c54acdc96aaf539acbe171ad19874a743962e1c0db
+size 2872
diff --git a/documents/odt/abiword/ucf-fontSize-tc.odt b/documents/odt/abiword/ucf-fontSize-tc.odt
new file mode 100644
index 0000000..1d1a450
--- /dev/null
+++ b/documents/odt/abiword/ucf-fontSize-tc.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0739ee1d7388177ff1698d6601455f102b3e4aadd3927b4ce4d82ea1bd058267
+size 2926
diff --git a/documents/odt/abiword/ucf-fontStyle.odt b/documents/odt/abiword/ucf-fontStyle.odt
new file mode 100644
index 0000000..9b5e50e
--- /dev/null
+++ b/documents/odt/abiword/ucf-fontStyle.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7afaa624853d39e40ca117aec3ffcf2193c5ed95a9f7adaa6ea4c13456334bf8
+size 2869
diff --git a/documents/odt/abiword/ucf-fontVariant.odt b/documents/odt/abiword/ucf-fontVariant.odt
new file mode 100644
index 0000000..714a1fe
--- /dev/null
+++ b/documents/odt/abiword/ucf-fontVariant.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c133196cd5f294976dd7920f232058370e93e1dba45a62ff162106089862aafb
+size 2868
diff --git a/documents/odt/abiword/ucf-fontWeight.odt b/documents/odt/abiword/ucf-fontWeight.odt
new file mode 100644
index 0000000..369b7f4
--- /dev/null
+++ b/documents/odt/abiword/ucf-fontWeight.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b8402c4d83410746b092e0155acd2bb23980ad37e510ddd520b286a64f20ac86
+size 2871
diff --git a/documents/odt/abiword/ucf-fontWeight_bug.odt b/documents/odt/abiword/ucf-fontWeight_bug.odt
new file mode 100644
index 0000000..8b40a7c
--- /dev/null
+++ b/documents/odt/abiword/ucf-fontWeight_bug.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0aa948fa066898cac763eaa8358e550a6cb90b77cf97b3e1b2dd25d736b1e518
+size 2965
diff --git a/documents/odt/abiword/ucf-frameIndividualPadding.odt b/documents/odt/abiword/ucf-frameIndividualPadding.odt
new file mode 100644
index 0000000..f40b0c7
--- /dev/null
+++ b/documents/odt/abiword/ucf-frameIndividualPadding.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b9c0df24d2eeea4d9c25bf00de308d2014928168388541482c4ffb0cde46f7b6
+size 4431
diff --git a/documents/odt/abiword/ucf-framePadding.odt b/documents/odt/abiword/ucf-framePadding.odt
new file mode 100644
index 0000000..84034a8
--- /dev/null
+++ b/documents/odt/abiword/ucf-framePadding.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:df9196c92bc4cc461f3876b8b16dee7e1d8b47c14a6592122056c6dcb2ba5787
+size 4358
diff --git a/documents/odt/abiword/ucf-headings.odt b/documents/odt/abiword/ucf-headings.odt
new file mode 100644
index 0000000..ce61da2
--- /dev/null
+++ b/documents/odt/abiword/ucf-headings.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c08ae52c70fe24a6be6d4b715ea910d86ee1be1fa19483206563d7c534b31c00
+size 3095
diff --git a/documents/odt/abiword/ucf-hiddenOrConditionalText.odt b/documents/odt/abiword/ucf-hiddenOrConditionalText.odt
new file mode 100644
index 0000000..65362bf
--- /dev/null
+++ b/documents/odt/abiword/ucf-hiddenOrConditionalText.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:48f22d0cbe2264fcf77b9ac602e46022b3da9617621f66e6a11685843ea6e074
+size 2848
diff --git a/documents/odt/abiword/ucf-hyphenation.odt b/documents/odt/abiword/ucf-hyphenation.odt
new file mode 100644
index 0000000..a09a844
--- /dev/null
+++ b/documents/odt/abiword/ucf-hyphenation.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:035b2c802c2460a36b049307cca93747f7f9ba0aaf8bf61e2220a19a7b8d1446
+size 2850
diff --git a/documents/odt/abiword/ucf-hyphenationPushCharCount.odt b/documents/odt/abiword/ucf-hyphenationPushCharCount.odt
new file mode 100644
index 0000000..ea6977b
--- /dev/null
+++ b/documents/odt/abiword/ucf-hyphenationPushCharCount.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7e51afa89c4685c36b7dac059c0d37c8ba33c9be2033e88cdeaa7bed8da267e5
+size 2896
diff --git a/documents/odt/abiword/ucf-hyphenationRemainCharCount.odt b/documents/odt/abiword/ucf-hyphenationRemainCharCount.odt
new file mode 100644
index 0000000..e366ed9
--- /dev/null
+++ b/documents/odt/abiword/ucf-hyphenationRemainCharCount.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6f3648f9206191df0f04f08b93f8679de78dc0d414bcead6444ea6d51b3f26a4
+size 2879
diff --git a/documents/odt/abiword/ucf-justifySingleWord.odt b/documents/odt/abiword/ucf-justifySingleWord.odt
new file mode 100644
index 0000000..30d2874
--- /dev/null
+++ b/documents/odt/abiword/ucf-justifySingleWord.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2761492290096f86781e68f3c2b52625c06c1191dd7d13b950432ebf3d6f3920
+size 2913
diff --git a/documents/odt/abiword/ucf-keepTogather.odt b/documents/odt/abiword/ucf-keepTogather.odt
new file mode 100644
index 0000000..9c18322
--- /dev/null
+++ b/documents/odt/abiword/ucf-keepTogather.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b3692ecab415dadbf1f68e6df511eb7576fd86ce9767d66c64fab420df50cc9f
+size 2940
diff --git a/documents/odt/abiword/ucf-keepTogether-tablerow.odt b/documents/odt/abiword/ucf-keepTogether-tablerow.odt
new file mode 100644
index 0000000..08c0ded
--- /dev/null
+++ b/documents/odt/abiword/ucf-keepTogether-tablerow.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3e1b6442d073682f80ff62a38ac98e33dd6247da780b9a30ca8eea58969f78b5
+size 2802
diff --git a/documents/odt/abiword/ucf-language.odt b/documents/odt/abiword/ucf-language.odt
new file mode 100644
index 0000000..e5904d4
--- /dev/null
+++ b/documents/odt/abiword/ucf-language.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4d1c9678353b25b35d9ae54cb68e480039a14b4600ffbbef15536041251351ee
+size 2882
diff --git a/documents/odt/abiword/ucf-leaderColor.odt b/documents/odt/abiword/ucf-leaderColor.odt
new file mode 100644
index 0000000..7046d18
--- /dev/null
+++ b/documents/odt/abiword/ucf-leaderColor.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bacb58bcfe789385bd59e51278be260268a5bc6c67177fe7556657d4b3a2181a
+size 2662
diff --git a/documents/odt/abiword/ucf-leaderStyle.odt b/documents/odt/abiword/ucf-leaderStyle.odt
new file mode 100644
index 0000000..0c44474
--- /dev/null
+++ b/documents/odt/abiword/ucf-leaderStyle.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:46f44c915d13afcd7e1a861a2d3d212b2b506a4bf7dd3512ea8ea13417724fc9
+size 2656
diff --git a/documents/odt/abiword/ucf-leaderText.odt b/documents/odt/abiword/ucf-leaderText.odt
new file mode 100644
index 0000000..6d02bfe
--- /dev/null
+++ b/documents/odt/abiword/ucf-leaderText.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:954ac4cd71ce80762b9373dcac363f8eb9706593ebf5cc8897b7a152f66343e6
+size 2657
diff --git a/documents/odt/abiword/ucf-leaderTextStyle.odt b/documents/odt/abiword/ucf-leaderTextStyle.odt
new file mode 100644
index 0000000..db7f665
--- /dev/null
+++ b/documents/odt/abiword/ucf-leaderTextStyle.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:afc806b2dfccc5f05a7ca49dac745ce635abe54fa0b0b073d37e48eeae85c353
+size 2747
diff --git a/documents/odt/abiword/ucf-leaderType.odt b/documents/odt/abiword/ucf-leaderType.odt
new file mode 100644
index 0000000..288011a
--- /dev/null
+++ b/documents/odt/abiword/ucf-leaderType.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3ade6d9747ccabc621673c912a2f61e67d3625d0bd863a45c996a4e651569fa9
+size 2644
diff --git a/documents/odt/abiword/ucf-leaderWidth.odt b/documents/odt/abiword/ucf-leaderWidth.odt
new file mode 100644
index 0000000..7c99180
--- /dev/null
+++ b/documents/odt/abiword/ucf-leaderWidth.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:000fcc4c0882bfa238f13067e117daba641fed8b87547b6473a66de58a811098
+size 2669
diff --git a/documents/odt/abiword/ucf-leftAndRightMargins.odt b/documents/odt/abiword/ucf-leftAndRightMargins.odt
new file mode 100644
index 0000000..c37282d
--- /dev/null
+++ b/documents/odt/abiword/ucf-leftAndRightMargins.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7421397263111ba41e6caa448af3586b11623f838ea319477d2ce10be8f08763
+size 2623
diff --git a/documents/odt/abiword/ucf-letterKerning.odt b/documents/odt/abiword/ucf-letterKerning.odt
new file mode 100644
index 0000000..22abab1
--- /dev/null
+++ b/documents/odt/abiword/ucf-letterKerning.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c178f85f35cd84b93994eb2c9fe5513c9aab72d6438811ec603d3f52dd8c100c
+size 2857
diff --git a/documents/odt/abiword/ucf-letterSpacing.odt b/documents/odt/abiword/ucf-letterSpacing.odt
new file mode 100644
index 0000000..e6a2cba
--- /dev/null
+++ b/documents/odt/abiword/ucf-letterSpacing.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9aa1f2fd90cf8e2fd8dab08d954df48c35a8d8e5738e5bcae1f2b2204ee25c4a
+size 2833
diff --git a/documents/odt/abiword/ucf-lineDistance.odt b/documents/odt/abiword/ucf-lineDistance.odt
new file mode 100644
index 0000000..ac44892
--- /dev/null
+++ b/documents/odt/abiword/ucf-lineDistance.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:208f8a936ad02657546a60bc42287da62e26ed5b7bde6c40c028adfd9026c4ec
+size 2878
diff --git a/documents/odt/abiword/ucf-lineNumberStartValue.odt b/documents/odt/abiword/ucf-lineNumberStartValue.odt
new file mode 100644
index 0000000..4123229
--- /dev/null
+++ b/documents/odt/abiword/ucf-lineNumberStartValue.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:26442f65848550c8e8a06212a56dd8b507be5a9598c82d50a0de8f2de0f0cda5
+size 2738
diff --git a/documents/odt/abiword/ucf-lineNumbering.odt b/documents/odt/abiword/ucf-lineNumbering.odt
new file mode 100644
index 0000000..c3b2a53
--- /dev/null
+++ b/documents/odt/abiword/ucf-lineNumbering.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6db4590c3d62179544cb3eae33b2efae902274f2c689a9d0ab4a8472ac822527
+size 2718
diff --git a/documents/odt/abiword/ucf-lineThroughColor.odt b/documents/odt/abiword/ucf-lineThroughColor.odt
new file mode 100644
index 0000000..681a5a6
--- /dev/null
+++ b/documents/odt/abiword/ucf-lineThroughColor.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a1172755f82564f8e7239bd5eb34e18b6e1a67f41af5f3870eaf065abf9a6c0a
+size 2876
diff --git a/documents/odt/abiword/ucf-lineThroughStyle.odt b/documents/odt/abiword/ucf-lineThroughStyle.odt
new file mode 100644
index 0000000..d57dadd
--- /dev/null
+++ b/documents/odt/abiword/ucf-lineThroughStyle.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b2a64887edd08c0a7951f5b40bcbe78ac7f0d0c6550a27aac490461ddbf4f347
+size 2994
diff --git a/documents/odt/abiword/ucf-lineThroughText.odt b/documents/odt/abiword/ucf-lineThroughText.odt
new file mode 100644
index 0000000..926fddb
--- /dev/null
+++ b/documents/odt/abiword/ucf-lineThroughText.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cc74f8db7fd09c9fb0111bcc870da966573a3b470275e635808439c8fc6ee04c
+size 3003
diff --git a/documents/odt/abiword/ucf-lineThroughTextStyle-test.odt b/documents/odt/abiword/ucf-lineThroughTextStyle-test.odt
new file mode 100644
index 0000000..2a8af0d
--- /dev/null
+++ b/documents/odt/abiword/ucf-lineThroughTextStyle-test.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:abc865afe5293a466eb89bdd664688834fbfce25f97f77d99c8b75f5da10f8b9
+size 2919
diff --git a/documents/odt/abiword/ucf-lineThroughTextStyle-text.odt b/documents/odt/abiword/ucf-lineThroughTextStyle-text.odt
new file mode 100644
index 0000000..c8eacb7
--- /dev/null
+++ b/documents/odt/abiword/ucf-lineThroughTextStyle-text.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8de10f3f8bd00514b030636c66defd194efa45876abd797f38f63878e574cc11
+size 3013
diff --git a/documents/odt/abiword/ucf-lineThroughType.odt b/documents/odt/abiword/ucf-lineThroughType.odt
new file mode 100644
index 0000000..080ca25
--- /dev/null
+++ b/documents/odt/abiword/ucf-lineThroughType.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:25123f375b2ba17835f0a5a0771a5f1e63e8f116f214c6e59fd1f530be25b0d9
+size 2970
diff --git a/documents/odt/abiword/ucf-lineThroughWidth.odt b/documents/odt/abiword/ucf-lineThroughWidth.odt
new file mode 100644
index 0000000..66eb704
--- /dev/null
+++ b/documents/odt/abiword/ucf-lineThroughWidth.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2ebb365806b294152cb3733348937aecf706f8d5f834ebd5c3daafa0ca7d4157
+size 3006
diff --git a/documents/odt/abiword/ucf-lineTroughType.odt b/documents/odt/abiword/ucf-lineTroughType.odt
new file mode 100644
index 0000000..2cfe557
--- /dev/null
+++ b/documents/odt/abiword/ucf-lineTroughType.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b49cf45cad3e22cf8ee8dec5e31b00526b254ec5d70ac61f4f5b9b8d678ed73a
+size 2841
diff --git a/documents/odt/abiword/ucf-listHeader.odt b/documents/odt/abiword/ucf-listHeader.odt
new file mode 100644
index 0000000..6aa9933
--- /dev/null
+++ b/documents/odt/abiword/ucf-listHeader.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ac94266a39e8143acda779d138e17fed6b1f949f305311d8de1663b0a517e2cc
+size 2830
diff --git a/documents/odt/abiword/ucf-margins.odt b/documents/odt/abiword/ucf-margins.odt
new file mode 100644
index 0000000..0d434bc
--- /dev/null
+++ b/documents/odt/abiword/ucf-margins.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0c5353f07bffa5ec11527a89ea14f5c49221581a6e3759f554cb62323aacb7fc
+size 2640
diff --git a/documents/odt/abiword/ucf-mayBreakBetweenRows.odt b/documents/odt/abiword/ucf-mayBreakBetweenRows.odt
new file mode 100644
index 0000000..8020f2d
--- /dev/null
+++ b/documents/odt/abiword/ucf-mayBreakBetweenRows.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c9d0316855301b4ea256ff6630d946ffb657b497664c9358c79e68f3a7bd1f20
+size 2811
diff --git a/documents/odt/abiword/ucf-metadata-predefined.odt b/documents/odt/abiword/ucf-metadata-predefined.odt
new file mode 100644
index 0000000..629ac03
--- /dev/null
+++ b/documents/odt/abiword/ucf-metadata-predefined.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f2e6ab997b6dac30dd968a45979a9d788ad8807954e4041e9e48595d6a68f0d0
+size 2835
diff --git a/documents/odt/abiword/ucf-metadata-userdefined.odt b/documents/odt/abiword/ucf-metadata-userdefined.odt
new file mode 100644
index 0000000..d36e615
--- /dev/null
+++ b/documents/odt/abiword/ucf-metadata-userdefined.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8975e8475e3b5145603f87a9c19e57ad3401f583f5e6ccf8d7d7baffe06540e5
+size 2460
diff --git a/documents/odt/abiword/ucf-minimumLineHeight.odt b/documents/odt/abiword/ucf-minimumLineHeight.odt
new file mode 100644
index 0000000..9245fd2
--- /dev/null
+++ b/documents/odt/abiword/ucf-minimumLineHeight.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:59f57dd1cf62df778c35432b6fc2572f61c7ef6728a88dc00c95974a8ffd2d9a
+size 2861
diff --git a/documents/odt/abiword/ucf-multipleDocumentContents.odt b/documents/odt/abiword/ucf-multipleDocumentContents.odt
new file mode 100644
index 0000000..021ec0e
--- /dev/null
+++ b/documents/odt/abiword/ucf-multipleDocumentContents.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8a0b063eceacf51fc43ec9a53c8118b06017a3dcefd5f58d52483321cbff7367
+size 6422
diff --git a/documents/odt/abiword/ucf-numberedList.odt b/documents/odt/abiword/ucf-numberedList.odt
new file mode 100644
index 0000000..4f19fb4
--- /dev/null
+++ b/documents/odt/abiword/ucf-numberedList.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:93aadc9cebf09f0a45a4bc27fa4990bea5a321bb26653a2434b5c875cc15ae78
+size 2925
diff --git a/documents/odt/abiword/ucf-optimalTableColumnWidth.odt b/documents/odt/abiword/ucf-optimalTableColumnWidth.odt
new file mode 100644
index 0000000..5e3d3c8
--- /dev/null
+++ b/documents/odt/abiword/ucf-optimalTableColumnWidth.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1c9edc62859658f33093ae0d1ac33ff2afedb2a1fbf7db4803d876806c6320dd
+size 2781
diff --git a/documents/odt/abiword/ucf-optimalTableRowHeight.odt b/documents/odt/abiword/ucf-optimalTableRowHeight.odt
new file mode 100644
index 0000000..3a8ac27
--- /dev/null
+++ b/documents/odt/abiword/ucf-optimalTableRowHeight.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:152e863afc64d8de8cca0dc9ad3156a8c9f658ee005101e68a5fd3d118c5404d
+size 2778
diff --git a/documents/odt/abiword/ucf-orphans.odt b/documents/odt/abiword/ucf-orphans.odt
new file mode 100644
index 0000000..0a4b2b5
--- /dev/null
+++ b/documents/odt/abiword/ucf-orphans.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3b9156d236abe1f60de2dacb617e6ce615c7b6347048a79cf0b5e39ea6f21c79
+size 2872
diff --git a/documents/odt/abiword/ucf-padding-tablecell.odt b/documents/odt/abiword/ucf-padding-tablecell.odt
new file mode 100644
index 0000000..ca063c0
--- /dev/null
+++ b/documents/odt/abiword/ucf-padding-tablecell.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a4b53251657b1988a1e971fe8cec3784236f5a3c1f68f1bcadfcf2938b5de441
+size 2700
diff --git a/documents/odt/abiword/ucf-padding.odt b/documents/odt/abiword/ucf-padding.odt
new file mode 100644
index 0000000..71c26c3
--- /dev/null
+++ b/documents/odt/abiword/ucf-padding.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a45f612f18ad0e62ac6c18945a931aed255b97075bf2fc0cd1bc3aeebf87239b
+size 2692
diff --git a/documents/odt/abiword/ucf-pageNumber.odt b/documents/odt/abiword/ucf-pageNumber.odt
new file mode 100644
index 0000000..08dfb9d
--- /dev/null
+++ b/documents/odt/abiword/ucf-pageNumber.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ccf4efc1b91a1740d92b7934e0e694bba789262cc6c12543d0c7556cab90416d
+size 2632
diff --git a/documents/odt/abiword/ucf-paragraphBackgroundColor.odt b/documents/odt/abiword/ucf-paragraphBackgroundColor.odt
new file mode 100644
index 0000000..6c3ab9f
--- /dev/null
+++ b/documents/odt/abiword/ucf-paragraphBackgroundColor.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:84c2862529637045dc9fa137fbf4f4380007c04f647a5a9a121d1ff018ee58b2
+size 2612
diff --git a/documents/odt/abiword/ucf-paragraphBackgroundImageOpacity.odt b/documents/odt/abiword/ucf-paragraphBackgroundImageOpacity.odt
new file mode 100644
index 0000000..c553065
--- /dev/null
+++ b/documents/odt/abiword/ucf-paragraphBackgroundImageOpacity.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9696cca0a5a9526fbe6b13a2adec27b4cd19bfa9246031b8d814200e6f51f5c7
+size 2717
diff --git a/documents/odt/abiword/ucf-paragraphBackgroundImagePosition.odt b/documents/odt/abiword/ucf-paragraphBackgroundImagePosition.odt
new file mode 100644
index 0000000..3d400f6
--- /dev/null
+++ b/documents/odt/abiword/ucf-paragraphBackgroundImagePosition.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a79044fca261390551632fbf38d4a4782b50c494eadd39810ae4eaad84265c5b
+size 2754
diff --git a/documents/odt/abiword/ucf-paragraphBackgroundImageRepetition.odt b/documents/odt/abiword/ucf-paragraphBackgroundImageRepetition.odt
new file mode 100644
index 0000000..8198844
--- /dev/null
+++ b/documents/odt/abiword/ucf-paragraphBackgroundImageRepetition.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f3d0ba35cf22451ea28b1e8032891e66bb1fbcb447ed56f87ab90d9caf301e29
+size 2641
diff --git a/documents/odt/abiword/ucf-printContent.odt b/documents/odt/abiword/ucf-printContent.odt
new file mode 100644
index 0000000..e18a020
--- /dev/null
+++ b/documents/odt/abiword/ucf-printContent.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ef23a8b404aae8de78d0732030b7905b852e4edae86d9a5d038877d13f748ac7
+size 2710
diff --git a/documents/odt/abiword/ucf-punctuationWrap.odt b/documents/odt/abiword/ucf-punctuationWrap.odt
new file mode 100644
index 0000000..b70e555
--- /dev/null
+++ b/documents/odt/abiword/ucf-punctuationWrap.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:377bf07714ab1e028bd3898665ccaad68252a7327831cd0cd482e28a9913d0aa
+size 2747
diff --git a/documents/odt/abiword/ucf-registerTrue.odt b/documents/odt/abiword/ucf-registerTrue.odt
new file mode 100644
index 0000000..12947ef
--- /dev/null
+++ b/documents/odt/abiword/ucf-registerTrue.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:55c1a1d194d3dd37958e25cd2f4a6bdd01bbb2e740ee23f6aebe1b49ea05c568
+size 2828
diff --git a/documents/odt/abiword/ucf-relativeFontSize.odt b/documents/odt/abiword/ucf-relativeFontSize.odt
new file mode 100644
index 0000000..51dc02b
--- /dev/null
+++ b/documents/odt/abiword/ucf-relativeFontSize.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b50400b235376b6c65bf805e662044113e772240ef2383f9f742fe2b97c2f368
+size 2866
diff --git a/documents/odt/abiword/ucf-repeatContent.odt b/documents/odt/abiword/ucf-repeatContent.odt
new file mode 100644
index 0000000..20670e5
--- /dev/null
+++ b/documents/odt/abiword/ucf-repeatContent.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:596353344742cb27a04e230dfb3808c09c8db167a8022af2f689861a79ab9362
+size 2750
diff --git a/documents/odt/abiword/ucf-rootAttributes-1.odt b/documents/odt/abiword/ucf-rootAttributes-1.odt
new file mode 100644
index 0000000..bfb25ab
--- /dev/null
+++ b/documents/odt/abiword/ucf-rootAttributes-1.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6228512c1fd6abb540032c9397f5b354c0d3f23996dcc2a8a1b58be9275bcd4b
+size 2557
diff --git a/documents/odt/abiword/ucf-rootAttributes-2.odt b/documents/odt/abiword/ucf-rootAttributes-2.odt
new file mode 100644
index 0000000..5243abb
--- /dev/null
+++ b/documents/odt/abiword/ucf-rootAttributes-2.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7210757424d6cada9b18034d226c81e20ee7289a87c1b3933073c62c3d53a327
+size 2454
diff --git a/documents/odt/abiword/ucf-rotationAlign.odt b/documents/odt/abiword/ucf-rotationAlign.odt
new file mode 100644
index 0000000..024a6f3
--- /dev/null
+++ b/documents/odt/abiword/ucf-rotationAlign.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bc20aa2c760709d6b6ca2c18699c1cd3f5023238aa62e88d849cc3eebee54b2b
+size 2759
diff --git a/documents/odt/abiword/ucf-rotationAngle.odt b/documents/odt/abiword/ucf-rotationAngle.odt
new file mode 100644
index 0000000..d0ad128
--- /dev/null
+++ b/documents/odt/abiword/ucf-rotationAngle.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2ee7da5919ecebecee235f16656831a924cb48168028b00a76f27c4af6d9de06
+size 2723
diff --git a/documents/odt/abiword/ucf-rowBackground.odt b/documents/odt/abiword/ucf-rowBackground.odt
new file mode 100644
index 0000000..b49177b
--- /dev/null
+++ b/documents/odt/abiword/ucf-rowBackground.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d1dc0074051ca12da71e3cf974a7c893882a92937bf7fef089db2ba9d971c47b
+size 2747
diff --git a/documents/odt/abiword/ucf-rowHeight.odt b/documents/odt/abiword/ucf-rowHeight.odt
new file mode 100644
index 0000000..3141527
--- /dev/null
+++ b/documents/odt/abiword/ucf-rowHeight.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1f1870ee61da665cd725998ccda52d6ce075f5c9f4b1ca7dfa1c1e4de211162f
+size 2747
diff --git a/documents/odt/abiword/ucf-scriptType.odt b/documents/odt/abiword/ucf-scriptType.odt
new file mode 100644
index 0000000..7b980d4
--- /dev/null
+++ b/documents/odt/abiword/ucf-scriptType.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:814e08c3306253f73a26180b5d449770be26199f6b15d4a9c5eec56c9ae6d410
+size 2892
diff --git a/documents/odt/abiword/ucf-sectionAttribute-1.odt b/documents/odt/abiword/ucf-sectionAttribute-1.odt
new file mode 100644
index 0000000..8e8b5ba
--- /dev/null
+++ b/documents/odt/abiword/ucf-sectionAttribute-1.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c3214b5fce7e4e9a274760ea575e73b58db00d3a65a0cd86ad4dd9ca4e2efbc9
+size 3077
diff --git a/documents/odt/abiword/ucf-sectionAttribute-2.odt b/documents/odt/abiword/ucf-sectionAttribute-2.odt
new file mode 100644
index 0000000..456c875
--- /dev/null
+++ b/documents/odt/abiword/ucf-sectionAttribute-2.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a83700f1f38d647a303863777d1171118b65fbcae1f7f126cebea348fcaa9678
+size 2858
diff --git a/documents/odt/abiword/ucf-shadow.odt b/documents/odt/abiword/ucf-shadow.odt
new file mode 100644
index 0000000..0d403bb
--- /dev/null
+++ b/documents/odt/abiword/ucf-shadow.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4a6edc9dd3e29a3084380fcad4e1c358fa4c1b5f4998e21c7c07edcd02e42772
+size 2673
diff --git a/documents/odt/abiword/ucf-shrinkToFit.odt b/documents/odt/abiword/ucf-shrinkToFit.odt
new file mode 100644
index 0000000..7d513cb
--- /dev/null
+++ b/documents/odt/abiword/ucf-shrinkToFit.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:707859fdf6297f291ce30151d12670c96bb8841b1f8cdd567f3ebb19ecc7255d
+size 2749
diff --git a/documents/odt/abiword/ucf-singleDocumentContents.odt b/documents/odt/abiword/ucf-singleDocumentContents.odt
new file mode 100644
index 0000000..8881cbb
--- /dev/null
+++ b/documents/odt/abiword/ucf-singleDocumentContents.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5f78801fec97406e1e938d5e2fc50c99b5ce15b9408c90d4933ea68e24a22b78
+size 1555
diff --git a/documents/odt/abiword/ucf-startValue.odt b/documents/odt/abiword/ucf-startValue.odt
new file mode 100644
index 0000000..61e61d7
--- /dev/null
+++ b/documents/odt/abiword/ucf-startValue.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0c2cdb84916a86e0902828a854c291f0c193f4bbe4dc1110b2dc0ac077f43937
+size 2926
diff --git a/documents/odt/abiword/ucf-tabPosition.odt b/documents/odt/abiword/ucf-tabPosition.odt
new file mode 100644
index 0000000..2432146
--- /dev/null
+++ b/documents/odt/abiword/ucf-tabPosition.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7fab108f797078f1964dbe933cc12b339dbd9f72459b4a6a42277e806f20c802
+size 2597
diff --git a/documents/odt/abiword/ucf-tabStopDistance.odt b/documents/odt/abiword/ucf-tabStopDistance.odt
new file mode 100644
index 0000000..8713e33
--- /dev/null
+++ b/documents/odt/abiword/ucf-tabStopDistance.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:48622cb55ac9dc6227e2419ef90ecbe9c5a3b89d5990a3b76760d883cb6d8deb
+size 2547
diff --git a/documents/odt/abiword/ucf-tabType.odt b/documents/odt/abiword/ucf-tabType.odt
new file mode 100644
index 0000000..f4ac4e3
--- /dev/null
+++ b/documents/odt/abiword/ucf-tabType.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:61dc4ba7822ec0db8c23ff5e5d9f4c01f82d842f295cbd669e3f5044396faa68
+size 2645
diff --git a/documents/odt/abiword/ucf-tableAlignment.odt b/documents/odt/abiword/ucf-tableAlignment.odt
new file mode 100644
index 0000000..9695f86
--- /dev/null
+++ b/documents/odt/abiword/ucf-tableAlignment.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8d16a5d29960551e6221d88ee25e6b1798f74325b3d2edb8940a693f73e00b87
+size 2746
diff --git a/documents/odt/abiword/ucf-tableBackgroundAndBackgroundImage.odt b/documents/odt/abiword/ucf-tableBackgroundAndBackgroundImage.odt
new file mode 100644
index 0000000..482b488
--- /dev/null
+++ b/documents/odt/abiword/ucf-tableBackgroundAndBackgroundImage.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f898acc3f9554c1abb696714381950617e96d552c6ff9643d0b0c948ef8a945c
+size 2719
diff --git a/documents/odt/abiword/ucf-tableLeftAndRightMargin.odt b/documents/odt/abiword/ucf-tableLeftAndRightMargin.odt
new file mode 100644
index 0000000..1e4b487
--- /dev/null
+++ b/documents/odt/abiword/ucf-tableLeftAndRightMargin.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2bbc5406d4b344ae0018b8c4f17c2ec5bd8af888c5eeb0b74ede27b9ba778003
+size 2744
diff --git a/documents/odt/abiword/ucf-tableMargins.odt b/documents/odt/abiword/ucf-tableMargins.odt
new file mode 100644
index 0000000..5b3e2d7
--- /dev/null
+++ b/documents/odt/abiword/ucf-tableMargins.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8f162cf41f613adc0538ea6f35ea983885b611fa18af01a258b4077d78689879
+size 2719
diff --git a/documents/odt/abiword/ucf-tableShadow.odt b/documents/odt/abiword/ucf-tableShadow.odt
new file mode 100644
index 0000000..a9cfe5c
--- /dev/null
+++ b/documents/odt/abiword/ucf-tableShadow.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9df834b64a818aca6ceaacd4445ff05fa14b867154c5fa3eb7645355e5705c85
+size 2727
diff --git a/documents/odt/abiword/ucf-tableTopAndBottomMargin.odt b/documents/odt/abiword/ucf-tableTopAndBottomMargin.odt
new file mode 100644
index 0000000..9bc7580
--- /dev/null
+++ b/documents/odt/abiword/ucf-tableTopAndBottomMargin.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cc24d0b09a99f5c8c83196374dc5c05c0c684133fcc0f557b831e8bb71c83838
+size 2740
diff --git a/documents/odt/abiword/ucf-tableWidth.odt b/documents/odt/abiword/ucf-tableWidth.odt
new file mode 100644
index 0000000..c315a5b
--- /dev/null
+++ b/documents/odt/abiword/ucf-tableWidth.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a8c67f1511d7ad336ed7327037b12ad67c76124b9c6e4b3d3f43420b921f0351
+size 2734
diff --git a/documents/odt/abiword/ucf-textAlign.odt b/documents/odt/abiword/ucf-textAlign.odt
new file mode 100644
index 0000000..8ac06f5
--- /dev/null
+++ b/documents/odt/abiword/ucf-textAlign.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:732ed29b14fb1a8e57321396ebf2122761605c8645e6caa72c1dbfefa5823810
+size 2904
diff --git a/documents/odt/abiword/ucf-textAlignOfLastLine.odt b/documents/odt/abiword/ucf-textAlignOfLastLine.odt
new file mode 100644
index 0000000..97621b1
--- /dev/null
+++ b/documents/odt/abiword/ucf-textAlignOfLastLine.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0ab30bfede72d8571484c2cba60ed07e172bec5ed0202b769a71c642cb0cc086
+size 2911
diff --git a/documents/odt/abiword/ucf-textAlignSource.odt b/documents/odt/abiword/ucf-textAlignSource.odt
new file mode 100644
index 0000000..2d7e0f5
--- /dev/null
+++ b/documents/odt/abiword/ucf-textAlignSource.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0c17b2bb3ea1bef32dbadd5d902ec959d77797c8ce731c6147920f4ed89cf2a3
+size 2873
diff --git a/documents/odt/abiword/ucf-textAutospace.odt b/documents/odt/abiword/ucf-textAutospace.odt
new file mode 100644
index 0000000..41f40ce
--- /dev/null
+++ b/documents/odt/abiword/ucf-textAutospace.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:226ee01c60fee3c3e4f24a330cd1744caf929136d4bda5861a37dd0f17e29ea2
+size 2699
diff --git a/documents/odt/abiword/ucf-textBackgroundColor.odt b/documents/odt/abiword/ucf-textBackgroundColor.odt
new file mode 100644
index 0000000..05f1de4
--- /dev/null
+++ b/documents/odt/abiword/ucf-textBackgroundColor.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d9d59bb99a9dbc53f91f47c21276034e772aabc39a6c9f19722c97c452b565d9
+size 2845
diff --git a/documents/odt/abiword/ucf-textBlinking.odt b/documents/odt/abiword/ucf-textBlinking.odt
new file mode 100644
index 0000000..78849e9
--- /dev/null
+++ b/documents/odt/abiword/ucf-textBlinking.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e7630639498bcf8e652d4ffc11532755ba0fadc6c69e77ebab37b4c3f1235796
+size 2826
diff --git a/documents/odt/abiword/ucf-textCombine.odt b/documents/odt/abiword/ucf-textCombine.odt
new file mode 100644
index 0000000..09e8366
--- /dev/null
+++ b/documents/odt/abiword/ucf-textCombine.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ceaabc1d2e4b630fc0ed6ec8a70e7cef2ba7ea850afe600ec0453b22f764954b
+size 2861
diff --git a/documents/odt/abiword/ucf-textCombineStartAndEndCharacters.odt b/documents/odt/abiword/ucf-textCombineStartAndEndCharacters.odt
new file mode 100644
index 0000000..ff7ca3f
--- /dev/null
+++ b/documents/odt/abiword/ucf-textCombineStartAndEndCharacters.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e2e97af5019f377e47a95f57e583538c1d23cacdc60ef0363ccfdcbe0d861d04
+size 2880
diff --git a/documents/odt/abiword/ucf-textEmphasis.odt b/documents/odt/abiword/ucf-textEmphasis.odt
new file mode 100644
index 0000000..a21ca82
--- /dev/null
+++ b/documents/odt/abiword/ucf-textEmphasis.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:36adf27d43c2b726b0fcdfb308939137cc1d8711e8212734b3c648a66aa96caf
+size 2862
diff --git a/documents/odt/abiword/ucf-textEmphasise.odt b/documents/odt/abiword/ucf-textEmphasise.odt
new file mode 100644
index 0000000..16ea1d5
--- /dev/null
+++ b/documents/odt/abiword/ucf-textEmphasise.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:33bdc3e813d5c75e455cf61d4421779d116809825c41c2994881cf4473e752bd
+size 2951
diff --git a/documents/odt/abiword/ucf-textIndent.odt b/documents/odt/abiword/ucf-textIndent.odt
new file mode 100644
index 0000000..fd46d6a
--- /dev/null
+++ b/documents/odt/abiword/ucf-textIndent.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c0688d8af68d520abea4ba15ffcd706a17aba1a29eed97a1ba87993b7a41a788
+size 2601
diff --git a/documents/odt/abiword/ucf-textLineThroughWordMode.odt b/documents/odt/abiword/ucf-textLineThroughWordMode.odt
new file mode 100644
index 0000000..29cfe24
--- /dev/null
+++ b/documents/odt/abiword/ucf-textLineThroughWordMode.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2ffb99b231f5924741f1864a3f34e53fecffc866ceb5db6cadd234d957dad5ff
+size 2870
diff --git a/documents/odt/abiword/ucf-textLineTroughWordMode.odt b/documents/odt/abiword/ucf-textLineTroughWordMode.odt
new file mode 100644
index 0000000..1fc8004
--- /dev/null
+++ b/documents/odt/abiword/ucf-textLineTroughWordMode.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9b9570084a3fd16ab9f1d3d29cedec93d71d1f862f2aff073e22ff9e9351bce3
+size 2964
diff --git a/documents/odt/abiword/ucf-textOutline.odt b/documents/odt/abiword/ucf-textOutline.odt
new file mode 100644
index 0000000..0a97f8d
--- /dev/null
+++ b/documents/odt/abiword/ucf-textOutline.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:26e0c919b4e9027fb1741d5d77bc8dd91cf9a7e88cb0a46be1a0013f30ef08a3
+size 2856
diff --git a/documents/odt/abiword/ucf-textPosition.odt b/documents/odt/abiword/ucf-textPosition.odt
new file mode 100644
index 0000000..8a978d7
--- /dev/null
+++ b/documents/odt/abiword/ucf-textPosition.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:55458a378518b94747e44e428f7cac3c01efb94e0442052d806efd4f6b6cff20
+size 2898
diff --git a/documents/odt/abiword/ucf-textRotationAngle.odt b/documents/odt/abiword/ucf-textRotationAngle.odt
new file mode 100644
index 0000000..ebbe039
--- /dev/null
+++ b/documents/odt/abiword/ucf-textRotationAngle.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e330af9d9195c6b924c1a1b2d94df67aed00f0e2820b463c54ef278fd51418f4
+size 2868
diff --git a/documents/odt/abiword/ucf-textRotationScale.odt b/documents/odt/abiword/ucf-textRotationScale.odt
new file mode 100644
index 0000000..fdf5776
--- /dev/null
+++ b/documents/odt/abiword/ucf-textRotationScale.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6caef5c86f085f5bc664129ffd341542d24c6184d72bf4e61cb8753a0693b917
+size 2887
diff --git a/documents/odt/abiword/ucf-textScale.odt b/documents/odt/abiword/ucf-textScale.odt
new file mode 100644
index 0000000..2066fbe
--- /dev/null
+++ b/documents/odt/abiword/ucf-textScale.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:808e85a1a2eb1d5a27d32d48bd93fb7a3265c26f836457037308eca1016d6b85
+size 2857
diff --git a/documents/odt/abiword/ucf-textShadow.odt b/documents/odt/abiword/ucf-textShadow.odt
new file mode 100644
index 0000000..b5b0531
--- /dev/null
+++ b/documents/odt/abiword/ucf-textShadow.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4a8b5787998ae6cbf938ff749729fe8c1d0d14b66acb079750c6e1154b530503
+size 2830
diff --git a/documents/odt/abiword/ucf-textTransformation.odt b/documents/odt/abiword/ucf-textTransformation.odt
new file mode 100644
index 0000000..eb958d5
--- /dev/null
+++ b/documents/odt/abiword/ucf-textTransformation.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:637382f6599a77b3ac1e375bb613778253a44d5962086ebca6fd2b52f9d7704b
+size 2971
diff --git a/documents/odt/abiword/ucf-textTransformations.odt b/documents/odt/abiword/ucf-textTransformations.odt
new file mode 100644
index 0000000..20430b1
--- /dev/null
+++ b/documents/odt/abiword/ucf-textTransformations.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cad975dcd58fe4c743d282728bdf51b737ecbaf1e52857e3d9bf84666de61dae
+size 2877
diff --git a/documents/odt/abiword/ucf-textUnderlineWordMode.odt b/documents/odt/abiword/ucf-textUnderlineWordMode.odt
new file mode 100644
index 0000000..116984c
--- /dev/null
+++ b/documents/odt/abiword/ucf-textUnderlineWordMode.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:53c8c3fa4aa65e85b8f15cddd7b9e31e0ad630a9ac3851b2a2a3d09a869f66fc
+size 2861
diff --git a/documents/odt/abiword/ucf-topAndBottomMargins.odt b/documents/odt/abiword/ucf-topAndBottomMargins.odt
new file mode 100644
index 0000000..74ac3be
--- /dev/null
+++ b/documents/odt/abiword/ucf-topAndBottomMargins.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:72401cb246eb8f4c121b2308b825832885fb4533b3db257758ac49d1b102869c
+size 2621
diff --git a/documents/odt/abiword/ucf-underlineColor.odt b/documents/odt/abiword/ucf-underlineColor.odt
new file mode 100644
index 0000000..f680153
--- /dev/null
+++ b/documents/odt/abiword/ucf-underlineColor.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1b04c025794129bf186a199ccdb8fce59dec6531f72038792d656366f17aee48
+size 2887
diff --git a/documents/odt/abiword/ucf-underliningStyle.odt b/documents/odt/abiword/ucf-underliningStyle.odt
new file mode 100644
index 0000000..cb58843
--- /dev/null
+++ b/documents/odt/abiword/ucf-underliningStyle.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d313b9c22821860bf4673e5ba07ae79197a9c4854cc22180e53dee7993cd7655
+size 2937
diff --git a/documents/odt/abiword/ucf-underliningType.odt b/documents/odt/abiword/ucf-underliningType.odt
new file mode 100644
index 0000000..737045c
--- /dev/null
+++ b/documents/odt/abiword/ucf-underliningType.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:692900bf886583a71d6d30f9e75fccf8f1585d2e6c0be27b4a4f1e51b263ca0e
+size 2867
diff --git a/documents/odt/abiword/ucf-underliningWidth.odt b/documents/odt/abiword/ucf-underliningWidth.odt
new file mode 100644
index 0000000..af4cd59
--- /dev/null
+++ b/documents/odt/abiword/ucf-underliningWidth.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a7460145dcf2fd79aa94413bde08a45763faca8c910fb8bd8351567818baa24c
+size 3002
diff --git a/documents/odt/abiword/ucf-verticalAlignment-tablecell.odt b/documents/odt/abiword/ucf-verticalAlignment-tablecell.odt
new file mode 100644
index 0000000..bdecb16
--- /dev/null
+++ b/documents/odt/abiword/ucf-verticalAlignment-tablecell.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e86f50da55d4f8fbc3358beeeaeca0f8ad23d5cb36c942026e6af70d608fdb76
+size 2746
diff --git a/documents/odt/abiword/ucf-verticalAlignment.odt b/documents/odt/abiword/ucf-verticalAlignment.odt
new file mode 100644
index 0000000..bb78a96
--- /dev/null
+++ b/documents/odt/abiword/ucf-verticalAlignment.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:061876e7cc6cd3c6e1337488aa760c4e265686479375445979031a7d32a70c1f
+size 2695
diff --git a/documents/odt/abiword/ucf-verticalGlyphOrientation.odt b/documents/odt/abiword/ucf-verticalGlyphOrientation.odt
new file mode 100644
index 0000000..91fa13b
--- /dev/null
+++ b/documents/odt/abiword/ucf-verticalGlyphOrientation.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6f172f194b6fa4a17ce9a87518e5de48cc5ba517c3bc0621f3054549803e2ed4
+size 2706
diff --git a/documents/odt/abiword/ucf-widows.odt b/documents/odt/abiword/ucf-widows.odt
new file mode 100644
index 0000000..d653a5e
--- /dev/null
+++ b/documents/odt/abiword/ucf-widows.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:eca929d6750898d0071a59d20fd9762f8d670df67723d4ed07dc7d3f21b0366d
+size 2855
diff --git a/documents/odt/abiword/ucf-windowFontColor.odt b/documents/odt/abiword/ucf-windowFontColor.odt
new file mode 100644
index 0000000..89a1d38
--- /dev/null
+++ b/documents/odt/abiword/ucf-windowFontColor.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b57ad912715d9d1aa208e04747b2e179114cb200988a798017574f3f57124660
+size 2989
diff --git a/documents/odt/abiword/ucf-wrapOption.odt b/documents/odt/abiword/ucf-wrapOption.odt
new file mode 100644
index 0000000..b7e7ec7
--- /dev/null
+++ b/documents/odt/abiword/ucf-wrapOption.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d4ca4f09579f0e34eb4f1e45c06f2042f063dc4c2b3c7aadf629dc016b18b9a7
+size 2783
diff --git a/documents/odt/abiword/ucf-writingMode-table.odt b/documents/odt/abiword/ucf-writingMode-table.odt
new file mode 100644
index 0000000..8a82653
--- /dev/null
+++ b/documents/odt/abiword/ucf-writingMode-table.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b9202a8175f9a521a6ecb4f3fbf3867e9b3d6043cd964da60b8d9101346b5969
+size 2810
diff --git a/documents/odt/abiword/ucf-writingMode.odt b/documents/odt/abiword/ucf-writingMode.odt
new file mode 100644
index 0000000..606f1a1
--- /dev/null
+++ b/documents/odt/abiword/ucf-writingMode.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d192665cf6dafc149935530c0dcb058a96e324e9ca6f18c03071cb2e938144fa
+size 2833
diff --git a/documents/odt/collabora/3pages.odt b/documents/odt/collabora/3pages.odt
new file mode 100644
index 0000000..72699e4
--- /dev/null
+++ b/documents/odt/collabora/3pages.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3d76165b1c2cf6e2cc95929272058cb3d68aba3a9c15cfbcd964c650fbf4c7ce
+size 10092
diff --git a/documents/odt/collabora/About LibreoOffice.odt b/documents/odt/collabora/About LibreoOffice.odt
new file mode 100644
index 0000000..c0d0609
--- /dev/null
+++ b/documents/odt/collabora/About LibreoOffice.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:de67c8636296fadb7086151ea2542f92c02a5cfc3045208a81e5fbea3525fbca
+size 34561
diff --git a/documents/odt/collabora/CV.odt b/documents/odt/collabora/CV.odt
new file mode 100644
index 0000000..d5bdd99
--- /dev/null
+++ b/documents/odt/collabora/CV.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:631ede44a637591c345e1e02ff72429b00e81a2b8f11cafc312dc81249f3a2bb
+size 21494
diff --git a/documents/odt/collabora/Default.odt b/documents/odt/collabora/Default.odt
new file mode 100644
index 0000000..25d67b0
--- /dev/null
+++ b/documents/odt/collabora/Default.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:26c81bc52364fa10a8afd1378a8a135d52a453e7f12ff6f1d1b309f42f955344
+size 8398
diff --git a/documents/odt/collabora/Example.odt b/documents/odt/collabora/Example.odt
new file mode 100644
index 0000000..ccab01d
--- /dev/null
+++ b/documents/odt/collabora/Example.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e0960067b2cc48d5cac875e33bc2e45ad7ac96093be56e33472674463a583c72
+size 16679
diff --git a/documents/odt/collabora/Lorem.odt b/documents/odt/collabora/Lorem.odt
new file mode 100644
index 0000000..9580c04
--- /dev/null
+++ b/documents/odt/collabora/Lorem.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:52e205af6a828b97f01cdc8787bf1e0c2115c7ff9f54cc05896659962c81cb45
+size 20162
diff --git a/documents/odt/collabora/Modern.odt b/documents/odt/collabora/Modern.odt
new file mode 100644
index 0000000..c91153e
--- /dev/null
+++ b/documents/odt/collabora/Modern.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:70c520b3d963b9254c56ec63e99fea79bbdac4d690eb23738b21ecece7232a81
+size 8654
diff --git a/documents/odt/collabora/Modern_business_letter_sans_serif.odt b/documents/odt/collabora/Modern_business_letter_sans_serif.odt
new file mode 100644
index 0000000..7525e27
--- /dev/null
+++ b/documents/odt/collabora/Modern_business_letter_sans_serif.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:91e8cf202b174fae16011553e1b501ea0ed996a59deabc3693278c67d88b2cd2
+size 21805
diff --git a/documents/odt/collabora/Modern_business_letter_serif.odt b/documents/odt/collabora/Modern_business_letter_serif.odt
new file mode 100644
index 0000000..5a7de4e
--- /dev/null
+++ b/documents/odt/collabora/Modern_business_letter_serif.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d39a672d502de31897cda71fd49407453097da2efea3d2ecc9b362dd499f0b6a
+size 33976
diff --git a/documents/odt/collabora/ODTTestFile.odt b/documents/odt/collabora/ODTTestFile.odt
new file mode 100644
index 0000000..c063ebd
--- /dev/null
+++ b/documents/odt/collabora/ODTTestFile.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f66b46f33f88ee185039469d65d17064910eb734fe9f82508378c2937111b978
+size 34209
diff --git a/documents/odt/collabora/Oasis - ODF Advantages.odt b/documents/odt/collabora/Oasis - ODF Advantages.odt
new file mode 100644
index 0000000..b6afce0
--- /dev/null
+++ b/documents/odt/collabora/Oasis - ODF Advantages.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:abb0a23c15b7f277d004259e5c509026467289c234fd7b3eb38b28d0f675c6b9
+size 73693
diff --git a/documents/odt/collabora/RenderSearchResultTest.odt b/documents/odt/collabora/RenderSearchResultTest.odt
new file mode 100644
index 0000000..0f420b2
--- /dev/null
+++ b/documents/odt/collabora/RenderSearchResultTest.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6a8a3f2673580ebdf011a59102a200a172678f828f921424a52871b8ec1adb49
+size 126871
diff --git a/documents/odt/collabora/Resume1page.odt b/documents/odt/collabora/Resume1page.odt
new file mode 100644
index 0000000..64fd005
--- /dev/null
+++ b/documents/odt/collabora/Resume1page.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c6d70b71f5afc6870eeef8494e7f3c7295c15f315ba24a23953abeefe74c557e
+size 16087
diff --git a/documents/odt/collabora/Simple.odt b/documents/odt/collabora/Simple.odt
new file mode 100644
index 0000000..b6e62c1
--- /dev/null
+++ b/documents/odt/collabora/Simple.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ba9f1751d28efa6f7ce1d5a4bab0c42e0cddc13dba8e1af40c5106507d4ce59e
+size 11635
diff --git a/documents/odt/collabora/SimpleSample.odt b/documents/odt/collabora/SimpleSample.odt
new file mode 100644
index 0000000..5d575db
--- /dev/null
+++ b/documents/odt/collabora/SimpleSample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6376fa8301334cdae934f73d1e155f731bc342dbeb742a41b8817871df6485c4
+size 38206
diff --git a/documents/odt/collabora/TextDocument.odt b/documents/odt/collabora/TextDocument.odt
new file mode 100644
index 0000000..71fb8a9
--- /dev/null
+++ b/documents/odt/collabora/TextDocument.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a3354bae8409302103faf1b15876de7faa22576187169e9052bb91a24df14a89
+size 1268
diff --git a/documents/odt/collabora/annotation.odt b/documents/odt/collabora/annotation.odt
new file mode 100644
index 0000000..ca1f8a0
--- /dev/null
+++ b/documents/odt/collabora/annotation.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:338f65ead8ed43e7bebe51501eaa29f8a5a426b05d67b1f339d807f4164f0e6c
+size 8214
diff --git a/documents/odt/collabora/apply_font.odt b/documents/odt/collabora/apply_font.odt
new file mode 100644
index 0000000..4b83b60
--- /dev/null
+++ b/documents/odt/collabora/apply_font.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:246d365659bbed51c3feeba7d7279527d78dc0f5cf9fbdebed8ecebc6eaea869
+size 8487
diff --git a/documents/odt/collabora/bullets.odt b/documents/odt/collabora/bullets.odt
new file mode 100644
index 0000000..4e2d662
--- /dev/null
+++ b/documents/odt/collabora/bullets.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7a37114050ec0252f3a2e20b47057cfbade2b32c37435d763b9debb07f207c0b
+size 10796
diff --git a/documents/odt/collabora/chart_wizard.odt b/documents/odt/collabora/chart_wizard.odt
new file mode 100644
index 0000000..5d4d883
--- /dev/null
+++ b/documents/odt/collabora/chart_wizard.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d22ac180c40de964d886576f18f8df15d2dc6321dadb070428b5e3fa77214924
+size 8569
diff --git a/documents/odt/collabora/complex_image_operation.odt b/documents/odt/collabora/complex_image_operation.odt
new file mode 100644
index 0000000..7b4e041
--- /dev/null
+++ b/documents/odt/collabora/complex_image_operation.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8c610c0e5280b780b1fcc6869fe8736ff7e0342f93ad1f7b9d056d503676bf7b
+size 323413
diff --git a/documents/odt/collabora/copy_markdown.odt b/documents/odt/collabora/copy_markdown.odt
new file mode 100644
index 0000000..756f435
--- /dev/null
+++ b/documents/odt/collabora/copy_markdown.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3e75313baf0d83fb6298cff4e389c2e4a1beee64cb3e78af21652f66939e51de
+size 9778
diff --git a/documents/odt/collabora/copy_paste.odt b/documents/odt/collabora/copy_paste.odt
new file mode 100644
index 0000000..3aaab94
--- /dev/null
+++ b/documents/odt/collabora/copy_paste.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:24d14c87058acf0583975816981b44ea0ca77247ecd57fd66588762bbd5e451a
+size 8398
diff --git a/documents/odt/collabora/copy_paste_simple.odt b/documents/odt/collabora/copy_paste_simple.odt
new file mode 100644
index 0000000..0e88622
--- /dev/null
+++ b/documents/odt/collabora/copy_paste_simple.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1d69c1b47a1d8316e4aa2cc9e8d63f8452ad53b7bc6dfbf79a73ba8050cef4fe
+size 10841
diff --git a/documents/odt/collabora/cursor.odt b/documents/odt/collabora/cursor.odt
new file mode 100644
index 0000000..c194a28
--- /dev/null
+++ b/documents/odt/collabora/cursor.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9deab1a730c4fec847ba9bd1eeefd321a5c21c407f12c4bf314b462d104adcac
+size 8978
diff --git a/documents/odt/collabora/cursor_in_table.odt b/documents/odt/collabora/cursor_in_table.odt
new file mode 100644
index 0000000..77c4354
--- /dev/null
+++ b/documents/odt/collabora/cursor_in_table.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0a0903f2b69ab36aad7c481f43b135dbf9dfe8000a5981f5c565e9e5aa6abf77
+size 9170
diff --git a/documents/odt/collabora/cursor_jump.odt b/documents/odt/collabora/cursor_jump.odt
new file mode 100644
index 0000000..d5144ea
--- /dev/null
+++ b/documents/odt/collabora/cursor_jump.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:eeb8fd534b35506cf0f5c74f905162146bed87d5d22aa339f1ce66716b863517
+size 62976
diff --git a/documents/odt/collabora/cypress_test_data_desktop_writer_focus.odt b/documents/odt/collabora/cypress_test_data_desktop_writer_focus.odt
new file mode 100644
index 0000000..1ea181a
--- /dev/null
+++ b/documents/odt/collabora/cypress_test_data_desktop_writer_focus.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e9691eae0355ab822da61e585483d43dd8683eb86e798c5999a5c2c628666581
+size 8793
diff --git a/documents/odt/collabora/cypress_test_data_desktop_writer_invalidations.odt b/documents/odt/collabora/cypress_test_data_desktop_writer_invalidations.odt
new file mode 100644
index 0000000..bce039e
--- /dev/null
+++ b/documents/odt/collabora/cypress_test_data_desktop_writer_invalidations.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:86a151ddcf840a7b21d61d767074464a34b641d3f70ed89c280826783a5c0213
+size 8633
diff --git a/documents/odt/collabora/cypress_test_data_desktop_writer_navigator.odt b/documents/odt/collabora/cypress_test_data_desktop_writer_navigator.odt
new file mode 100644
index 0000000..3e1bba9
--- /dev/null
+++ b/documents/odt/collabora/cypress_test_data_desktop_writer_navigator.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6a970c31e700a1546c24aff01833103daa89e3ae3380f28877fcda43a0005304
+size 47032
diff --git a/documents/odt/collabora/cypress_test_data_desktop_writer_search_bar.odt b/documents/odt/collabora/cypress_test_data_desktop_writer_search_bar.odt
new file mode 100644
index 0000000..c40170b
--- /dev/null
+++ b/documents/odt/collabora/cypress_test_data_desktop_writer_search_bar.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bc6bca6eefa222c60c029ec102e191291a3178bfc1510aef6d1fdfd46814ecd2
+size 11088
diff --git a/documents/odt/collabora/cypress_test_data_mobile_writer_annotation.odt b/documents/odt/collabora/cypress_test_data_mobile_writer_annotation.odt
new file mode 100644
index 0000000..b2fbbf1
--- /dev/null
+++ b/documents/odt/collabora/cypress_test_data_mobile_writer_annotation.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3738760094528a77237dad9cacf0d717779d9785fb71fcee65c3ccdd6aa0ac34
+size 8276
diff --git a/documents/odt/collabora/delete_objects.odt b/documents/odt/collabora/delete_objects.odt
new file mode 100644
index 0000000..e62933d
--- /dev/null
+++ b/documents/odt/collabora/delete_objects.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c2c1f0b2bc0f33378b9b4fe620b2f92032f0b3b9c301965e348bcd4b52048e86
+size 8172
diff --git a/documents/odt/collabora/drop_down_form_field_noitem.odt b/documents/odt/collabora/drop_down_form_field_noitem.odt
new file mode 100644
index 0000000..937b3ed
--- /dev/null
+++ b/documents/odt/collabora/drop_down_form_field_noitem.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b8c1476a587f13dbdeb260bc37f5625d95db89a4a180c62fff0a814a6e731fff
+size 8467
diff --git a/documents/odt/collabora/drop_down_form_field_noselection.odt b/documents/odt/collabora/drop_down_form_field_noselection.odt
new file mode 100644
index 0000000..256c3a4
--- /dev/null
+++ b/documents/odt/collabora/drop_down_form_field_noselection.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:770f03e4a6fb942b035daa9d2f313ffc1a6668a1b86ac210fe201c607880b3ba
+size 8512
diff --git a/documents/odt/collabora/empty.odt b/documents/odt/collabora/empty.odt
new file mode 100644
index 0000000..b17ead3
--- /dev/null
+++ b/documents/odt/collabora/empty.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5f3c1545f19ffca64eb5f86cc735ce228f481c693550ad9efc7c21b413ea1d81
+size 7405
diff --git a/documents/odt/collabora/find_replace.odt b/documents/odt/collabora/find_replace.odt
new file mode 100644
index 0000000..c316269
--- /dev/null
+++ b/documents/odt/collabora/find_replace.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:083d01d38daa01724e39fa1c51d4f9a1fa025ae6e6f68d80a848277eaa4e2d16
+size 14036
diff --git a/documents/odt/collabora/focus.odt b/documents/odt/collabora/focus.odt
new file mode 100644
index 0000000..7210c50
--- /dev/null
+++ b/documents/odt/collabora/focus.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f880dce5d7a046c7ca340e1489dc297fcc704d00cc371ca956298bcd87f20007
+size 8062
diff --git a/documents/odt/collabora/form_field.odt b/documents/odt/collabora/form_field.odt
new file mode 100644
index 0000000..d693a59
--- /dev/null
+++ b/documents/odt/collabora/form_field.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e1b0ecaeace1c0016ffb84525654cdb972b9626a12bfca1fdcd37c17c56afb06
+size 8497
diff --git a/documents/odt/collabora/graphicviewselection.odt b/documents/odt/collabora/graphicviewselection.odt
new file mode 100644
index 0000000..16281ef
--- /dev/null
+++ b/documents/odt/collabora/graphicviewselection.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1496de8b9275b35ce2c74aad6c420d480655055f614115c88d45e176be061465
+size 16700
diff --git a/documents/odt/collabora/hamburger_menu.odt b/documents/odt/collabora/hamburger_menu.odt
new file mode 100644
index 0000000..e0d5836
--- /dev/null
+++ b/documents/odt/collabora/hamburger_menu.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5fe1cb8db954a83b9ba5ba62f72cdf8656c9bd5dd1c9e34026052189dbce6eba
+size 10889
diff --git a/documents/odt/collabora/hello.odt b/documents/odt/collabora/hello.odt
new file mode 100644
index 0000000..ba2837e
--- /dev/null
+++ b/documents/odt/collabora/hello.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9407d8c1c8f8a9268773fbfa4c8cf7c3456e100d477ef79734f2bf7045bacd39
+size 7441
diff --git a/documents/odt/collabora/help_dialog.odt b/documents/odt/collabora/help_dialog.odt
new file mode 100644
index 0000000..601030e
--- /dev/null
+++ b/documents/odt/collabora/help_dialog.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d812dbe77bb06c50155a32dd18a72b823e01376194b97305b0f8e3a30c46679e
+size 28836
diff --git a/documents/odt/collabora/hide-whitespace.odt b/documents/odt/collabora/hide-whitespace.odt
new file mode 100644
index 0000000..67c5daf
--- /dev/null
+++ b/documents/odt/collabora/hide-whitespace.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:dcfd71fbc76bb2507ede6080b659c119cf82d63b546e026b1c492ae4fb0f59e7
+size 8460
diff --git a/documents/odt/collabora/hide_change_tracking_controls.odt b/documents/odt/collabora/hide_change_tracking_controls.odt
new file mode 100644
index 0000000..c338a3d
--- /dev/null
+++ b/documents/odt/collabora/hide_change_tracking_controls.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ed0eb4b5ea3fd0939c2379a27fda0ef5f0a033b0f4de4f2bd6ae2571411200eb
+size 7622
diff --git a/documents/odt/collabora/invalidations_headers.odt b/documents/odt/collabora/invalidations_headers.odt
new file mode 100644
index 0000000..b14d4a4
--- /dev/null
+++ b/documents/odt/collabora/invalidations_headers.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:714d0187db7af8add792e79c8d2a026dbc2f1d62bd6a67f731a5bdeb85bd5715
+size 9695
diff --git a/documents/odt/collabora/large-six-hundred.odt b/documents/odt/collabora/large-six-hundred.odt
new file mode 100644
index 0000000..21923d5
--- /dev/null
+++ b/documents/odt/collabora/large-six-hundred.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e6ce22cdaa45caea85a5eb752ec97b9754045249f4afe50f9d846b18ec17fd1d
+size 46837
diff --git a/documents/odt/collabora/manage_tracking_changes.odt b/documents/odt/collabora/manage_tracking_changes.odt
new file mode 100644
index 0000000..dcf1662
--- /dev/null
+++ b/documents/odt/collabora/manage_tracking_changes.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d7206a834cb80c29cb75d48f885e390eb83d0aeadb0ab114e57be49c1f418744
+size 14584
diff --git a/documents/odt/collabora/multiple_form_fields.odt b/documents/odt/collabora/multiple_form_fields.odt
new file mode 100644
index 0000000..6c74d57
--- /dev/null
+++ b/documents/odt/collabora/multiple_form_fields.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:69f236d5b18229930eb0d0273e20bd79448dbe06396eab631ea92973e9c18039
+size 8552
diff --git a/documents/odt/collabora/non-shape-image.odt b/documents/odt/collabora/non-shape-image.odt
new file mode 100644
index 0000000..a2275c7
--- /dev/null
+++ b/documents/odt/collabora/non-shape-image.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f130fc1dc47c9f361ed561cbed5a81de2ede2a9aa495b3f6194de11975161e94
+size 194465
diff --git a/documents/odt/collabora/notebookbar-redline.odt b/documents/odt/collabora/notebookbar-redline.odt
new file mode 100644
index 0000000..0f51312
--- /dev/null
+++ b/documents/odt/collabora/notebookbar-redline.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0fccce5a30b7fda8866f0616e66c86b5c68034e035d6102debd68714ba07099e
+size 14479
diff --git a/documents/odt/collabora/notebookbar.odt b/documents/odt/collabora/notebookbar.odt
new file mode 100644
index 0000000..11422d7
--- /dev/null
+++ b/documents/odt/collabora/notebookbar.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c8f0fc52ca2117df493cdfd56309c4e99f16eac4b0b4431998e3062b14f7dad4
+size 8797
diff --git a/documents/odt/collabora/perf-test.odt b/documents/odt/collabora/perf-test.odt
new file mode 100644
index 0000000..383aee1
--- /dev/null
+++ b/documents/odt/collabora/perf-test.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c721ca20b637ce97e2a9000609eb9f9bd2b595ab81ff7311e6ccc71fe603a57e
+size 2929799
diff --git a/documents/odt/collabora/presets.odt b/documents/odt/collabora/presets.odt
new file mode 100644
index 0000000..9c43d01
--- /dev/null
+++ b/documents/odt/collabora/presets.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9a5655c446235c3dc6ff92fc0f57ced9ffa3780d627d89e71c2ef9c46a9d5669
+size 8872
diff --git a/documents/odt/collabora/scrolling.odt b/documents/odt/collabora/scrolling.odt
new file mode 100644
index 0000000..f8eff5c
--- /dev/null
+++ b/documents/odt/collabora/scrolling.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f8b46eec89f0ec41a54e2d537630a7c4f77d3c469d3de1b2c57383b5e9d780bc
+size 22708
diff --git a/documents/odt/collabora/search_bar.odt b/documents/odt/collabora/search_bar.odt
new file mode 100644
index 0000000..e8e1a04
--- /dev/null
+++ b/documents/odt/collabora/search_bar.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:806accafe74b531a34231490aa4d56d7f52a79589bcb98e85df0d75d49c4e5b0
+size 8437
diff --git a/documents/odt/collabora/shape.odt b/documents/odt/collabora/shape.odt
new file mode 100644
index 0000000..69295cb
--- /dev/null
+++ b/documents/odt/collabora/shape.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:12f58befa4d8a3f7403b0deb1ee9cab97ae36a7c1fd415e3d5be1839425c5714
+size 9018
diff --git a/documents/odt/collabora/shape_operations.odt b/documents/odt/collabora/shape_operations.odt
new file mode 100644
index 0000000..b2a0b36
--- /dev/null
+++ b/documents/odt/collabora/shape_operations.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3afb4f729bcd255b223f5692063e8d1a82e85b8604ee03528f24279bbb859ece
+size 8061
diff --git a/documents/odt/collabora/shape_properties.odt b/documents/odt/collabora/shape_properties.odt
new file mode 100644
index 0000000..18926be
--- /dev/null
+++ b/documents/odt/collabora/shape_properties.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a45913e050d96dd61144ab3e57378d26025785adbe811dc57c4ffb9754520210
+size 8404
diff --git a/documents/odt/collabora/simultaneous_typing.odt b/documents/odt/collabora/simultaneous_typing.odt
new file mode 100644
index 0000000..8f978d7
--- /dev/null
+++ b/documents/odt/collabora/simultaneous_typing.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:27798c855e690b54721b8f29e52fa2026f826781eec5ed6f8db6a11e84e68018
+size 8242
diff --git a/documents/odt/collabora/spellchecking.odt b/documents/odt/collabora/spellchecking.odt
new file mode 100644
index 0000000..6f83766
--- /dev/null
+++ b/documents/odt/collabora/spellchecking.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e78e9fd8827f5fa1f425a69882f422f5a91d0995e1ab7cd8b35a75aa1d3921bc
+size 8574
diff --git a/documents/odt/collabora/statusbar.odt b/documents/odt/collabora/statusbar.odt
new file mode 100644
index 0000000..3453f29
--- /dev/null
+++ b/documents/odt/collabora/statusbar.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a4abeaa90ec032dd8423aff3c9d7494ed3a2726efc42934f83bd9a61065b114d
+size 8677
diff --git a/documents/odt/collabora/styles.odt b/documents/odt/collabora/styles.odt
new file mode 100644
index 0000000..0d3b70f
--- /dev/null
+++ b/documents/odt/collabora/styles.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6202cea0d441e1517f0dbeed3318dec16ee8c61c397df64a1a57ecdb99d09b7f
+size 27809
diff --git a/documents/odt/collabora/table_accessibility.odt b/documents/odt/collabora/table_accessibility.odt
new file mode 100644
index 0000000..3a3fa9d
--- /dev/null
+++ b/documents/odt/collabora/table_accessibility.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:255223e1361ef706ccb69d63fafbf1479fdf84bf7bd921009d422f545e17962a
+size 14065
diff --git a/documents/odt/collabora/table_operation.odt b/documents/odt/collabora/table_operation.odt
new file mode 100644
index 0000000..361dd73
--- /dev/null
+++ b/documents/odt/collabora/table_operation.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:48e2929acdb496890148efe29e3a958a9412c3a76cb8b767de027a9d5e8054f7
+size 8747
diff --git a/documents/odt/collabora/table_properties.odt b/documents/odt/collabora/table_properties.odt
new file mode 100644
index 0000000..1605457
--- /dev/null
+++ b/documents/odt/collabora/table_properties.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:717d7795f16085ddb930ee5288f02ed46d081dfa1fb2bfd51d3317cedd1a292e
+size 9095
diff --git a/documents/odt/collabora/table_with_text.odt b/documents/odt/collabora/table_with_text.odt
new file mode 100644
index 0000000..03007df
--- /dev/null
+++ b/documents/odt/collabora/table_with_text.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0da64235832164a5c0f9eba856f735e5506e94563ff2ce0568b1a75b1e08892a
+size 9131
diff --git a/documents/odt/collabora/tiff.odt b/documents/odt/collabora/tiff.odt
new file mode 100644
index 0000000..8ce9eda
--- /dev/null
+++ b/documents/odt/collabora/tiff.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bd60400702c5df3ce7ccc53e7a9632c930e0834fab4c587f1808c43363b9f8cf
+size 18844
diff --git a/documents/odt/collabora/track_changes.odt b/documents/odt/collabora/track_changes.odt
new file mode 100644
index 0000000..e7c6839
--- /dev/null
+++ b/documents/odt/collabora/track_changes.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fd5991312ef762ea9d401d04cde9d6ec29a0591019877c9a64e865498533c0db
+size 8218
diff --git a/documents/odt/collabora/track_changes_old.odt b/documents/odt/collabora/track_changes_old.odt
new file mode 100644
index 0000000..f7b3d0a
--- /dev/null
+++ b/documents/odt/collabora/track_changes_old.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a14b5494fe03507b8c9dc6e3991d1cfd7863ece02af27fb2ecdd108ecf57513a
+size 8194
diff --git a/documents/odt/collabora/unordered_list.odt b/documents/odt/collabora/unordered_list.odt
new file mode 100644
index 0000000..f633464
--- /dev/null
+++ b/documents/odt/collabora/unordered_list.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:19a227e8e9aa64b540655728d3800e001f30f651b886045dbbc6d656c50b74b6
+size 9397
diff --git a/documents/odt/collabora/with_comment.odt b/documents/odt/collabora/with_comment.odt
new file mode 100644
index 0000000..84fbe1f
--- /dev/null
+++ b/documents/odt/collabora/with_comment.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3678ecee138e1ff792d48873a6651e3a549b8c1fd3c1e6320305e126b530c55b
+size 9607
diff --git a/documents/odt/odftoolkit/opendocument-v1.2-os-part1.odt b/documents/odt/odftoolkit/opendocument-v1.2-os-part1.odt
deleted file mode 100644
index 4e8da43..0000000
--- a/documents/odt/odftoolkit/opendocument-v1.2-os-part1.odt
+++ /dev/null
@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:07c76a5ac11828005399dd4787244892ef6241211e467a61d5b409d0218488d1
-size 758963
diff --git a/documents/odt/openoffice/extras_source_shellnew_soffice.odt b/documents/odt/openoffice/extras_source_shellnew_soffice.odt
new file mode 100644
index 0000000..6b60e94
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_shellnew_soffice.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9bd21ac6aaac8a9beb694ed6c5394a7031c06bfdc22b3a24ce879e69ee297d92
+size 7334
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_bg_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_bg_idxexample.odt
new file mode 100644
index 0000000..b76a944
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_bg_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:08d9edd9c3dc5bc06f24a879437bc5fd80bba984b9713ab0f00a2af05da14ae7
+size 21286
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_cs_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_cs_idxexample.odt
new file mode 100644
index 0000000..1df5365
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_cs_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:37f167018aeb10250fe73db8f7ec5bdbf41448c411804d3457b25270cf5a0712
+size 21272
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_da_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_da_idxexample.odt
new file mode 100644
index 0000000..e02f208
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_da_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2d46f6f42617408b5c199e916f55c9d91d90531867a4e7346ba1facd23c63f61
+size 21140
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_de_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_de_idxexample.odt
new file mode 100644
index 0000000..73e24ca
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_de_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8ce1caef5f55b13c44c711bc286331f9bc16f9959175a2dffeade13ae96c794c
+size 21157
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_en-GB_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_en-GB_idxexample.odt
new file mode 100644
index 0000000..928aba3
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_en-GB_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:752d4816de9dd79cb9b1a8773e7df285dc665cd786d9b9edb8ccb3eaf3daa0c0
+size 21837
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_en-US_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_en-US_idxexample.odt
new file mode 100644
index 0000000..90e1376
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_en-US_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c381fc20bdd0656e9e93f8fb350e83f28c10212e378864d041247cf96e868530
+size 21126
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_es_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_es_idxexample.odt
new file mode 100644
index 0000000..dd55cc9
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_es_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5605665349639474248a214d7cab694f5137e66825a199acbf8d21c3d2bd194e
+size 21146
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_eu_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_eu_idxexample.odt
new file mode 100644
index 0000000..b39faec
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_eu_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:41995c71728a5774ac1ba5598ade07a3d2c0d949367318d0bafd57bafeeae5ec
+size 22234
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_fr_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_fr_idxexample.odt
new file mode 100644
index 0000000..e3663ca
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_fr_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d5dc9e02696a2c11bbf523531f804b255468cdb25bf8a0a7693ae0bd65076d23
+size 21152
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_hu_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_hu_idxexample.odt
new file mode 100644
index 0000000..c24ba3c
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_hu_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:68b21050babc13531d47a178a16a7eff5031e10ab928db62f780a63450fd0d3b
+size 21196
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_it_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_it_idxexample.odt
new file mode 100644
index 0000000..cdd39f7
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_it_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2ae90afa66fe0ac699e7e97dd142c32ee9c291a4f4d4d822448b9b16d4b46d54
+size 21150
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_ja_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_ja_idxexample.odt
new file mode 100644
index 0000000..8be1a31
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_ja_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:46099a2e886f1f9950dc3a8d07a005aa7520555794a9a4be9f486709a36365db
+size 24039
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_km_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_km_idxexample.odt
new file mode 100644
index 0000000..9f3fa8c
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_km_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:94898946ae9feac809375c9b4d03b3b1c9bb3114d99dd46be963867a68ae53d6
+size 21643
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_ko_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_ko_idxexample.odt
new file mode 100644
index 0000000..f594478
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_ko_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9c61cebbc2fabd95af53c9bb8a283e6f5259bf9318fca7faf492b4d46151c8a7
+size 24086
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_nl_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_nl_idxexample.odt
new file mode 100644
index 0000000..10e801f
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_nl_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d258d1c21b46786f19ffdcbd1ea76f510721e6251b9b1e1d5940512797f96fa5
+size 9361
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_pl_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_pl_idxexample.odt
new file mode 100644
index 0000000..ec37446
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_pl_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7bfb6dd58e9c084acdf518ca8cdc66870af5b6833be3bfd283cbabcfa69248c4
+size 13229
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_pt-BR_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_pt-BR_idxexample.odt
new file mode 100644
index 0000000..1dcfe0b
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_pt-BR_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1cbfabc9263138d7e5a52cf96177f3f17dbf9ccf6cef0c52caf929291b1203ee
+size 21200
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_pt_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_pt_idxexample.odt
new file mode 100644
index 0000000..17d92a3
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_pt_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:81c1e6ab35d9bde0dffd0eafc385e6cf524cef9c21dcafbc9189debd3ec055b6
+size 9339
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_ru_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_ru_idxexample.odt
new file mode 100644
index 0000000..e2fcb35
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_ru_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b437e1c63ef25b163c4497c150f5c5acab6b5ece0779944c164a38481534471d
+size 13458
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_sk_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_sk_idxexample.odt
new file mode 100644
index 0000000..41457b1
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_sk_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9d1f57fea51815464fc1dea3babdeb02d85ff933ccc562be492c12ebaf1f4e01
+size 9399
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_sl_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_sl_idxexample.odt
new file mode 100644
index 0000000..714acb2
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_sl_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b5cd271c4651268346bd8dd0ef1bafa07375898417666f66714f795a038147c1
+size 21320
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_sv_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_sv_idxexample.odt
new file mode 100644
index 0000000..b269880
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_sv_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bddc65d558d05bb2129d339c5753c21e9c3de1127becd9b084ac629cbde8d222
+size 21170
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_vi_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_vi_idxexample.odt
new file mode 100644
index 0000000..52d517f
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_vi_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cddee95858535b791ae8675d4d47111192a67326d28bc7d1282acc6fe2122d35
+size 22170
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_zh-CN_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_zh-CN_idxexample.odt
new file mode 100644
index 0000000..07d1780
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_zh-CN_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bb33f60ac1f585197b73a30b8c1f30006a0c0644780e922c06a7fc109ef5f05b
+size 24054
diff --git a/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_zh-TW_idxexample.odt b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_zh-TW_idxexample.odt
new file mode 100644
index 0000000..730479c
--- /dev/null
+++ b/documents/odt/openoffice/extras_source_templates_wizard_desktop_lang_zh-TW_idxexample.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fcc97a998a2ea92ee7e3059c03cb57e5f181c050b2f298d21e3a2a4761150ab3
+size 24033
diff --git a/documents/odt/openoffice/odk_examples_DevelopersGuide_BasicAndDialogs_CreatingDialogs_CreatingDialogs.odt b/documents/odt/openoffice/odk_examples_DevelopersGuide_BasicAndDialogs_CreatingDialogs_CreatingDialogs.odt
new file mode 100644
index 0000000..2366963
--- /dev/null
+++ b/documents/odt/openoffice/odk_examples_DevelopersGuide_BasicAndDialogs_CreatingDialogs_CreatingDialogs.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f327c15a8ca35ec1444b4da9b93ef9a89a1a7656ca2a99f72a1f6607f9c21a1c
+size 8654
diff --git a/documents/odt/openoffice/odk_examples_DevelopersGuide_BasicAndDialogs_FirstStepsBasic.odt b/documents/odt/openoffice/odk_examples_DevelopersGuide_BasicAndDialogs_FirstStepsBasic.odt
new file mode 100644
index 0000000..3017b06
--- /dev/null
+++ b/documents/odt/openoffice/odk_examples_DevelopersGuide_BasicAndDialogs_FirstStepsBasic.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a901ffa5bb03505faa7a2aca8dfc491ac2ecb18f5bbefd2d4835ba9098dbcb31
+size 18560
diff --git a/documents/odt/openoffice/odk_examples_DevelopersGuide_BasicAndDialogs_ToolkitControls_ToolkitControls.odt b/documents/odt/openoffice/odk_examples_DevelopersGuide_BasicAndDialogs_ToolkitControls_ToolkitControls.odt
new file mode 100644
index 0000000..508c247
--- /dev/null
+++ b/documents/odt/openoffice/odk_examples_DevelopersGuide_BasicAndDialogs_ToolkitControls_ToolkitControls.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:86abfe9626b674373ba5c2361c7497cffd1869c13de82f148c2ff9ee1ab09025
+size 7793
diff --git a/documents/odt/openoffice/odk_examples_DevelopersGuide_Components_CppComponent_SimpleComponent.odt b/documents/odt/openoffice/odk_examples_DevelopersGuide_Components_CppComponent_SimpleComponent.odt
new file mode 100644
index 0000000..fea5d14
--- /dev/null
+++ b/documents/odt/openoffice/odk_examples_DevelopersGuide_Components_CppComponent_SimpleComponent.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d71f2fad5ba6a008a511387231a664c5a9e8b8ff2257f7f8c5862b932a71755a
+size 8841
diff --git a/documents/odt/openoffice/odk_examples_DevelopersGuide_Components_dialogcomponent_DialogComponent.odt b/documents/odt/openoffice/odk_examples_DevelopersGuide_Components_dialogcomponent_DialogComponent.odt
new file mode 100644
index 0000000..380487a
--- /dev/null
+++ b/documents/odt/openoffice/odk_examples_DevelopersGuide_Components_dialogcomponent_DialogComponent.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b9197fc00095066fea8804e38551c9d9a97f9dc3584a0eed5bacb638540694b9
+size 11902
diff --git a/documents/odt/openoffice/odk_examples_DevelopersGuide_Forms_ProgrammaticScriptAssignment.odt b/documents/odt/openoffice/odk_examples_DevelopersGuide_Forms_ProgrammaticScriptAssignment.odt
new file mode 100644
index 0000000..e243a9f
--- /dev/null
+++ b/documents/odt/openoffice/odk_examples_DevelopersGuide_Forms_ProgrammaticScriptAssignment.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8f5598eb19d292df6712eeb8f3a756ba72d1607091f92e0cfddc9d2e86d5eca8
+size 19198
diff --git a/documents/odt/openoffice/odk_examples_DevelopersGuide_ScriptingFramework_SayHello_SayHello.odt b/documents/odt/openoffice/odk_examples_DevelopersGuide_ScriptingFramework_SayHello_SayHello.odt
new file mode 100644
index 0000000..eb6b8a1
--- /dev/null
+++ b/documents/odt/openoffice/odk_examples_DevelopersGuide_ScriptingFramework_SayHello_SayHello.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:79b6d2ea8135bb5fe3b77bfbcdf0feba063744b182a639225b434cac18cfdbfe
+size 8874
diff --git a/documents/odt/openoffice/odk_examples_DevelopersGuide_ScriptingFramework_ScriptSelector_ScriptSelector.odt b/documents/odt/openoffice/odk_examples_DevelopersGuide_ScriptingFramework_ScriptSelector_ScriptSelector.odt
new file mode 100644
index 0000000..4f04c81
--- /dev/null
+++ b/documents/odt/openoffice/odk_examples_DevelopersGuide_ScriptingFramework_ScriptSelector_ScriptSelector.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:95fe49a0d20ba51259e45cb25671bcacf1aece3ec146c1fb88c0823ab3900d6d
+size 8921
diff --git a/documents/odt/openoffice/odk_examples_DevelopersGuide_Text_PrintDemo.odt b/documents/odt/openoffice/odk_examples_DevelopersGuide_Text_PrintDemo.odt
new file mode 100644
index 0000000..cd2f7f9
--- /dev/null
+++ b/documents/odt/openoffice/odk_examples_DevelopersGuide_Text_PrintDemo.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cf2775183b347c2b225a748f96e6d46658f609aa5624b65e3b95f89996bf63de
+size 6909
diff --git a/documents/odt/openoffice/odk_examples_DevelopersGuide_Text_TextTemplateWithUserFields.odt b/documents/odt/openoffice/odk_examples_DevelopersGuide_Text_TextTemplateWithUserFields.odt
new file mode 100644
index 0000000..abaf2cf
--- /dev/null
+++ b/documents/odt/openoffice/odk_examples_DevelopersGuide_Text_TextTemplateWithUserFields.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:03814f881c015732abf6e48eef03021281fffb1d36bb05be3e5fc17edd4366a5
+size 6641
diff --git a/documents/odt/openoffice/odk_examples_basic_forms_and_controls_burger_factory.odt b/documents/odt/openoffice/odk_examples_basic_forms_and_controls_burger_factory.odt
new file mode 100644
index 0000000..3bbed02
--- /dev/null
+++ b/documents/odt/openoffice/odk_examples_basic_forms_and_controls_burger_factory.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:18c1ae5ca097bfa2554cca6ef779df6ba5e5ae3852c6d1507c875b88983893bc
+size 18934
diff --git a/documents/odt/openoffice/odk_examples_basic_text_creating_an_index_index.odt b/documents/odt/openoffice/odk_examples_basic_text_creating_an_index_index.odt
new file mode 100644
index 0000000..1bc5152
--- /dev/null
+++ b/documents/odt/openoffice/odk_examples_basic_text_creating_an_index_index.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f10ad6d05dcf85de555a195deb3abd619734aab26059ab157e360f1dc24f5b6d
+size 21748
diff --git a/documents/odt/openoffice/odk_examples_basic_text_modifying_text_automatically_changing_appearance.odt b/documents/odt/openoffice/odk_examples_basic_text_modifying_text_automatically_changing_appearance.odt
new file mode 100644
index 0000000..c8c64ab
--- /dev/null
+++ b/documents/odt/openoffice/odk_examples_basic_text_modifying_text_automatically_changing_appearance.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e5285b772197411abaef14bcd41046cec04c763fc9c7300a50177f711f4ede88
+size 9883
diff --git a/documents/odt/openoffice/odk_examples_basic_text_modifying_text_automatically_inserting_bookmarks.odt b/documents/odt/openoffice/odk_examples_basic_text_modifying_text_automatically_inserting_bookmarks.odt
new file mode 100644
index 0000000..40c7857
--- /dev/null
+++ b/documents/odt/openoffice/odk_examples_basic_text_modifying_text_automatically_inserting_bookmarks.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:35892b5d678eea0a95f8bd4c7d084f338b1bafcfcfee31fc6780d773446fcee0
+size 10207
diff --git a/documents/odt/openoffice/odk_examples_basic_text_modifying_text_automatically_replacing_text.odt b/documents/odt/openoffice/odk_examples_basic_text_modifying_text_automatically_replacing_text.odt
new file mode 100644
index 0000000..ad2e380
--- /dev/null
+++ b/documents/odt/openoffice/odk_examples_basic_text_modifying_text_automatically_replacing_text.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b70ccd3cab374ce395a85185dd8ca18253eee6179b15efe43f461a41b74d3fb6
+size 10021
diff --git a/documents/odt/openoffice/odk_examples_basic_text_modifying_text_automatically_using_regular_expressions.odt b/documents/odt/openoffice/odk_examples_basic_text_modifying_text_automatically_using_regular_expressions.odt
new file mode 100644
index 0000000..4a24c40
--- /dev/null
+++ b/documents/odt/openoffice/odk_examples_basic_text_modifying_text_automatically_using_regular_expressions.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:88ff8411ffe5693541b8b7b701c036b829651cde5d6a2f2fedf3702410394333
+size 10072
diff --git a/documents/odt/openoffice/odk_examples_cpp_DocumentLoader_test.odt b/documents/odt/openoffice/odk_examples_cpp_DocumentLoader_test.odt
new file mode 100644
index 0000000..4ff767e
--- /dev/null
+++ b/documents/odt/openoffice/odk_examples_cpp_DocumentLoader_test.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9847339a2fda4c89b05df4fc66d55375d88bfe8744d8c482799e54a93844bf7e
+size 6737
diff --git a/documents/odt/openoffice/odk_examples_java_DocumentHandling_test_test1.odt b/documents/odt/openoffice/odk_examples_java_DocumentHandling_test_test1.odt
new file mode 100644
index 0000000..7e2fcfb
--- /dev/null
+++ b/documents/odt/openoffice/odk_examples_java_DocumentHandling_test_test1.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f8fd9f671f7d2d06aeaf1a4232bc376e39ded5c0f5d08ace0f246e2580309c13
+size 7999
diff --git a/documents/odt/openoffice/odk_examples_java_EmbedDocument_EmbeddedObject_EmbeddedObject.odt b/documents/odt/openoffice/odk_examples_java_EmbedDocument_EmbeddedObject_EmbeddedObject.odt
new file mode 100644
index 0000000..859378a
--- /dev/null
+++ b/documents/odt/openoffice/odk_examples_java_EmbedDocument_EmbeddedObject_EmbeddedObject.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2c2f727ec6196537d647ce43b8cd3027d49d7e4da616ab507831b993fab3d5e5
+size 9975
diff --git a/documents/odt/openoffice/odk_examples_java_Inspector_InstanceInspectorTest.odt b/documents/odt/openoffice/odk_examples_java_Inspector_InstanceInspectorTest.odt
new file mode 100644
index 0000000..f0b25a0
--- /dev/null
+++ b/documents/odt/openoffice/odk_examples_java_Inspector_InstanceInspectorTest.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:307cc01e8a6265fd36fe8f08586fe7c4c97abe4208dc8db93f2033fdac84921d
+size 12272
diff --git a/documents/odt/openoffice/odk_examples_java_PropertySet_PropertySet.odt b/documents/odt/openoffice/odk_examples_java_PropertySet_PropertySet.odt
new file mode 100644
index 0000000..c504575
--- /dev/null
+++ b/documents/odt/openoffice/odk_examples_java_PropertySet_PropertySet.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7923e0c242cab07f5aeb4090e0840113a98c7223d350b4a6cc3809bde1932686
+size 8391
diff --git a/documents/odt/openoffice/sw_qa_complex_writer_testdocuments_CheckCrossReferences.odt b/documents/odt/openoffice/sw_qa_complex_writer_testdocuments_CheckCrossReferences.odt
new file mode 100644
index 0000000..8db9a2b
--- /dev/null
+++ b/documents/odt/openoffice/sw_qa_complex_writer_testdocuments_CheckCrossReferences.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ca37bc3e9a7d5ae340bca41d1c403af4aef7566c0e939338122034cec866aa93
+size 11628
diff --git a/documents/odt/openoffice/sw_qa_complex_writer_testdocuments_CheckFlies.odt b/documents/odt/openoffice/sw_qa_complex_writer_testdocuments_CheckFlies.odt
new file mode 100644
index 0000000..3d6e0a6
--- /dev/null
+++ b/documents/odt/openoffice/sw_qa_complex_writer_testdocuments_CheckFlies.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ba39483b3be948075920c84137500b8755e8cedef6d1c271b254643e26d12eea
+size 65022
diff --git a/documents/odt/openoffice/sw_qa_complex_writer_testdocuments_TESTMETA.odt b/documents/odt/openoffice/sw_qa_complex_writer_testdocuments_TESTMETA.odt
new file mode 100644
index 0000000..ade84bb
--- /dev/null
+++ b/documents/odt/openoffice/sw_qa_complex_writer_testdocuments_TESTMETA.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:698ad80b4d69f1afdd1e61ca0f0072f51ec2e0f2430c1c72100623b69292900b
+size 8678
diff --git a/documents/odt/openoffice/sw_qa_complex_writer_testdocuments_TESTXMLID.odt b/documents/odt/openoffice/sw_qa_complex_writer_testdocuments_TESTXMLID.odt
new file mode 100644
index 0000000..a45f947
--- /dev/null
+++ b/documents/odt/openoffice/sw_qa_complex_writer_testdocuments_TESTXMLID.odt
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:36e492e0ce76baa37f992624db6283f9f0f69534f97658e5d8bc1268606ed1fb
+size 10879
diff --git a/documents/rtf/openpreserve/Lorem Ipsum - Andrew Jackson.rtf b/documents/rtf/openpreserve/Lorem Ipsum - Andrew Jackson.rtf
new file mode 100644
index 0000000..f0013ee
--- /dev/null
+++ b/documents/rtf/openpreserve/Lorem Ipsum - Andrew Jackson.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:daeebcc804dc07298c6d9c15691aa059b3451ba0fd327f09f113edc6a4a3030c
+size 6960
diff --git a/documents/rtf/openpreserve/Neddy_Flyer_README_HeatherRyan.md.rtf b/documents/rtf/openpreserve/Neddy_Flyer_README_HeatherRyan.md.rtf
new file mode 100644
index 0000000..0e6f201
--- /dev/null
+++ b/documents/rtf/openpreserve/Neddy_Flyer_README_HeatherRyan.md.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0ea7e051db0da4ff576c4cd442ae186e0048624e9216a303325b5852eae77063
+size 1210
diff --git a/documents/rtf/openpreserve/lorem-ipsum.rtf b/documents/rtf/openpreserve/lorem-ipsum.rtf
new file mode 100644
index 0000000..2fd4cae
--- /dev/null
+++ b/documents/rtf/openpreserve/lorem-ipsum.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ad49a611abf8b98733af22621ab8399716dd7c0d965e741eebf91299251ba709
+size 35834
diff --git a/documents/rtf/openpreserve/scrape_openpreserve_ebooks_calibre 0.9.0_lorem-ipsum.rtf b/documents/rtf/openpreserve/scrape_openpreserve_ebooks_calibre 0.9.0_lorem-ipsum.rtf
new file mode 100644
index 0000000..e38ab72
--- /dev/null
+++ b/documents/rtf/openpreserve/scrape_openpreserve_ebooks_calibre 0.9.0_lorem-ipsum.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:32719734d1f586a3745790da5ddcce01dbd2dc1805adaf79f4dd5e0d4ab17ea2
+size 6891
diff --git a/documents/rtf/openpreserve/testRTF.rtf b/documents/rtf/openpreserve/testRTF.rtf
new file mode 100644
index 0000000..d09b243
--- /dev/null
+++ b/documents/rtf/openpreserve/testRTF.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:99538d0a6b4583271f5e4d62207940df9c5cd9f6fe17ae73d965193abd662668
+size 1308
diff --git a/documents/rtf/pandoc/default.rtf b/documents/rtf/pandoc/default.rtf
new file mode 100644
index 0000000..14b7532
--- /dev/null
+++ b/documents/rtf/pandoc/default.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b7ab5a560e82a29aa92aa9ad508213708a92e5fee26e5d48a54f4f81c9aebe29
+size 609
diff --git a/documents/rtf/pandoc/footnote.rtf b/documents/rtf/pandoc/footnote.rtf
new file mode 100644
index 0000000..92a041a
--- /dev/null
+++ b/documents/rtf/pandoc/footnote.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ec95f4ee52066f3d269571e5b584cb08c2b547393f7fa247790bddaff8227d20
+size 566
diff --git a/documents/rtf/pandoc/formatting.rtf b/documents/rtf/pandoc/formatting.rtf
new file mode 100644
index 0000000..8e1e901
--- /dev/null
+++ b/documents/rtf/pandoc/formatting.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:abca13508e29e97fc13609e1143b2a705e3fc8b0a35ef0cf6196588339d6f14c
+size 40208
diff --git a/documents/rtf/pandoc/heading.rtf b/documents/rtf/pandoc/heading.rtf
new file mode 100644
index 0000000..2e98808
--- /dev/null
+++ b/documents/rtf/pandoc/heading.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b7d543fbd02f7a61f2a17c6cc3ca932b2d0b6709bb683c31e8feacd8b54500df
+size 45478
diff --git a/documents/rtf/pandoc/image.rtf b/documents/rtf/pandoc/image.rtf
new file mode 100644
index 0000000..8e1a919
--- /dev/null
+++ b/documents/rtf/pandoc/image.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3a0c3c2773b208fe4802bab8418921aae0f27cb1f32c82791ebf2887f414e306
+size 32795
diff --git a/documents/rtf/pandoc/list_complex.rtf b/documents/rtf/pandoc/list_complex.rtf
new file mode 100644
index 0000000..30856ef
--- /dev/null
+++ b/documents/rtf/pandoc/list_complex.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:dea00b2d977de8c4cc922d168884c2711e68c499c64da3998c9dbe9d56b6c4d4
+size 63244
diff --git a/documents/rtf/pandoc/list_simple.rtf b/documents/rtf/pandoc/list_simple.rtf
new file mode 100644
index 0000000..159a4df
--- /dev/null
+++ b/documents/rtf/pandoc/list_simple.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:27e60a2ff2bf81892f4451070007062b395d7b8d393ee4d826833cae5c0f407d
+size 1711
diff --git a/documents/rtf/pandoc/table_error_codes.rtf b/documents/rtf/pandoc/table_error_codes.rtf
new file mode 100644
index 0000000..cd6d0f2
--- /dev/null
+++ b/documents/rtf/pandoc/table_error_codes.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:261aff735836a22e8ebe9b000a1753d47d5f564fb62cce9a7275a861c26dd2cf
+size 5300
diff --git a/documents/rtf/rtfparserkit/test10001Encoding.rtf b/documents/rtf/rtfparserkit/test10001Encoding.rtf
new file mode 100644
index 0000000..6928276
--- /dev/null
+++ b/documents/rtf/rtfparserkit/test10001Encoding.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b6e6f4d3a9085680f7e9dca9660d83ffa1d6f01cd3a5a24b8db2e9728687d2cb
+size 852
diff --git a/documents/rtf/rtfparserkit/test10007Encoding.rtf b/documents/rtf/rtfparserkit/test10007Encoding.rtf
new file mode 100644
index 0000000..758e7dc
--- /dev/null
+++ b/documents/rtf/rtfparserkit/test10007Encoding.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:064fb38e90a3e31efc13b04859d035f1686d4212f4cc939d605203d000f11e6a
+size 520
diff --git a/documents/rtf/rtfparserkit/test437Encoding.rtf b/documents/rtf/rtfparserkit/test437Encoding.rtf
new file mode 100644
index 0000000..ae58144
--- /dev/null
+++ b/documents/rtf/rtfparserkit/test437Encoding.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f0fa8bd6a27c07a7089b34446adfa7a20884a88e236276d974afc09042f79475
+size 1640
diff --git a/documents/rtf/rtfparserkit/test874Encoding.rtf b/documents/rtf/rtfparserkit/test874Encoding.rtf
new file mode 100644
index 0000000..da60e52
--- /dev/null
+++ b/documents/rtf/rtfparserkit/test874Encoding.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c034bdd873846ba1f87a750489cb580c138c4f1dc9137084c82706ecb70f8ed2
+size 4163
diff --git a/documents/rtf/rtfparserkit/test950Encoding.rtf b/documents/rtf/rtfparserkit/test950Encoding.rtf
new file mode 100644
index 0000000..651f8a0
--- /dev/null
+++ b/documents/rtf/rtfparserkit/test950Encoding.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f7825198383adb9a986177447b4ed5997620802c868ca8b4f4c54c73ce858ded
+size 428
diff --git a/documents/rtf/rtfparserkit/testEncodingParse.rtf b/documents/rtf/rtfparserkit/testEncodingParse.rtf
new file mode 100644
index 0000000..9fc7e78
--- /dev/null
+++ b/documents/rtf/rtfparserkit/testEncodingParse.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f41d9b0386ea6246cdd87d73f44e5d914eba0acf22ecfc3d5d4fcbf899a7c5f5
+size 188
diff --git a/documents/rtf/rtfparserkit/testGitHubIssue6.rtf b/documents/rtf/rtfparserkit/testGitHubIssue6.rtf
new file mode 100644
index 0000000..4fb7aa6
--- /dev/null
+++ b/documents/rtf/rtfparserkit/testGitHubIssue6.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9f1d5a8f120d6a59023337648f73897612c38a22f3fedb51b0da364e35c9379f
+size 1406
diff --git a/documents/rtf/rtfparserkit/testGreekEncoding.rtf b/documents/rtf/rtfparserkit/testGreekEncoding.rtf
new file mode 100644
index 0000000..9a2f1bc
--- /dev/null
+++ b/documents/rtf/rtfparserkit/testGreekEncoding.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:99a9402bd4aae35b4d212d7b58c2849850e7cf1d7cb91a6d3c0d2b409c81fe22
+size 168
diff --git a/documents/rtf/rtfparserkit/testHex.rtf b/documents/rtf/rtfparserkit/testHex.rtf
new file mode 100644
index 0000000..92552f1
--- /dev/null
+++ b/documents/rtf/rtfparserkit/testHex.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0b224123a29e1d0bc3e127e56575f5fa9481db035f568fc7e4e6c2816d95e47d
+size 194
diff --git a/documents/rtf/rtfparserkit/testJapaneseJisEncoding.rtf b/documents/rtf/rtfparserkit/testJapaneseJisEncoding.rtf
new file mode 100644
index 0000000..f368c61
--- /dev/null
+++ b/documents/rtf/rtfparserkit/testJapaneseJisEncoding.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:49d45a4d4ca241a41af5ee2c80177404ac9c3aa7cf2b5df8d6cfe60e294c8bf9
+size 134
diff --git a/documents/rtf/rtfparserkit/testJapaneseJisEncodingTwoFonts.rtf b/documents/rtf/rtfparserkit/testJapaneseJisEncodingTwoFonts.rtf
new file mode 100644
index 0000000..bc5f091
--- /dev/null
+++ b/documents/rtf/rtfparserkit/testJapaneseJisEncodingTwoFonts.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:103fa7310713b8a5438c592fa2de9d981b2cfbef04f21c4f5cebd53fa12951fe
+size 168
diff --git a/documents/rtf/rtfparserkit/testJapaneseUtf8Encoding.rtf b/documents/rtf/rtfparserkit/testJapaneseUtf8Encoding.rtf
new file mode 100644
index 0000000..50d63d6
--- /dev/null
+++ b/documents/rtf/rtfparserkit/testJapaneseUtf8Encoding.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7b8e410897c43d7c987ccbfda213cb889dd1c94c4151c2529ebce5daf458ee5e
+size 143
diff --git a/documents/rtf/rtfparserkit/testKoreanEncoding.rtf b/documents/rtf/rtfparserkit/testKoreanEncoding.rtf
new file mode 100644
index 0000000..b60f5b3
--- /dev/null
+++ b/documents/rtf/rtfparserkit/testKoreanEncoding.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:123a2e4a73e6290845175800e699ad01ade71684818e4e36432ff1269aa53ddf
+size 285
diff --git a/documents/rtf/rtfparserkit/testMultiByteHex.rtf b/documents/rtf/rtfparserkit/testMultiByteHex.rtf
new file mode 100644
index 0000000..1bdcfea
--- /dev/null
+++ b/documents/rtf/rtfparserkit/testMultiByteHex.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b0ffae8d08215e76bbfb334d523430bde52a551f2381781e003d089e7090522c
+size 329
diff --git a/documents/rtf/rtfparserkit/testNecCharacters.rtf b/documents/rtf/rtfparserkit/testNecCharacters.rtf
new file mode 100644
index 0000000..baea9f8
--- /dev/null
+++ b/documents/rtf/rtfparserkit/testNecCharacters.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:591e1f053ca30378a3f38c97888d666738ad4a1f4312e77c62fa06f6558fe410
+size 508
diff --git a/documents/rtf/rtfparserkit/testNegativeUnicode.rtf b/documents/rtf/rtfparserkit/testNegativeUnicode.rtf
new file mode 100644
index 0000000..76180b0
--- /dev/null
+++ b/documents/rtf/rtfparserkit/testNegativeUnicode.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9dfaa2fa0d46fa5e01b32de8c342c99eee63d326e59e044a279bf9bb6305c03e
+size 719
diff --git a/documents/rtf/rtfparserkit/testSpecialChars.rtf b/documents/rtf/rtfparserkit/testSpecialChars.rtf
new file mode 100644
index 0000000..97dab7d
--- /dev/null
+++ b/documents/rtf/rtfparserkit/testSpecialChars.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:34bf211378ed9527c1d0724ba7fd4e17325d4a66f44a6743678af3834e12f346
+size 515
diff --git a/documents/rtf/rtfparserkit/testStyles.rtf b/documents/rtf/rtfparserkit/testStyles.rtf
new file mode 100644
index 0000000..1530363
--- /dev/null
+++ b/documents/rtf/rtfparserkit/testStyles.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cc8025f51f8464d9ebf0a4ae003f9b5a141ddba64604a2a3a77129b6534db0bd
+size 460
diff --git a/documents/rtf/rtfparserkit/testTextConversion.rtf b/documents/rtf/rtfparserkit/testTextConversion.rtf
new file mode 100644
index 0000000..5d117ab
--- /dev/null
+++ b/documents/rtf/rtfparserkit/testTextConversion.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9b9aa6bca0b9ad2efb3b3da6a75143f107bcf88e6f1f89158ab99ec4a5136f5f
+size 46593
diff --git a/documents/rtf/rtfparserkit/testTurkishEncoding.rtf b/documents/rtf/rtfparserkit/testTurkishEncoding.rtf
new file mode 100644
index 0000000..d6d72a7
--- /dev/null
+++ b/documents/rtf/rtfparserkit/testTurkishEncoding.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ddebe4c47379ac58d8a0deeb21e1374f3e6cbc289ff17164a20d250a7dfe8cf5
+size 246
diff --git a/documents/rtf/rtfparserkit/testUnicode.rtf b/documents/rtf/rtfparserkit/testUnicode.rtf
new file mode 100644
index 0000000..0275f1a
--- /dev/null
+++ b/documents/rtf/rtfparserkit/testUnicode.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c00f11b9ecb2ed083787955c7d05b2ef1d998a4826af41d0aa839efd5abb76b7
+size 873
diff --git a/documents/rtf/rtfparserkit/testUpr.rtf b/documents/rtf/rtfparserkit/testUpr.rtf
new file mode 100644
index 0000000..e1c5ff7
--- /dev/null
+++ b/documents/rtf/rtfparserkit/testUpr.rtf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c0ca25634734078cdb85d771b74b09177a6bba325671bef60dd3684233be6882
+size 8874
]]>