syntax docs for footnotes (#50)

Author: cscheid

CLAUDE.md

@@ -16,4 +16,5 @@ The main documentation for this repository is located at:
 - In the tree-sitter-markdown and tree-sitter-markdown-inline directories, you rebuild the parsers using "tree-sitter generate; tree-sitter build". Make sure the shell is in the correct directory before running those. Every time you change the tree-sitter parsers, rebuild them and run "tree-sitter test". If the tests fail, fix the code. Only change tree-sitter tests you've just added; do not touch any other tests. If you end up getting stuck there, stop and ask for my help.
 - When attempting to find binary differences between files, always use `xxd` instead of other tools.
 - .c only works in JSON formats. Inside Lua filters, you need to use Pandoc's Lua API. Study https://raw.githubusercontent.com/jgm/pandoc/refs/heads/main/doc/lua-filters.md and make notes to yourself as necessary (use docs/for-claude in this directory)
-- Sometimes you get confused by macOS's weird renaming of /tmp. Prefer to use temporary directories local to the project you're working on (which you can later clean)
+- Sometimes you get confused by macOS's weird renaming of /tmp. Prefer to use temporary directories local to the project you're working on (which you can later clean)
+- The documentation in docs/ is a user-facing Quarto website. There, you should document usage and not technical details.

docs/syntax/footnotes.qmd

@@ -0,0 +1,187 @@
+---
+title: "Footnotes"
+---
+
+## Overview
+
+Footnotes allow you to add references and additional information without cluttering your main text. In `quarto-markdown`, footnotes support both inline and fenced block syntax for definitions, giving you flexibility in how you structure your content.
+
+## Syntax
+
+### Inline Footnote Definitions
+
+The standard Pandoc-style inline syntax uses square brackets with a caret:
+
+```markdown
+[^id]: The footnote definition text goes here.
+```
+
+This syntax is best for short, single-paragraph footnotes.
+
+### Fenced Block Footnote Definitions
+
+For longer footnotes that contain multiple paragraphs, lists, or other block-level content, use the fenced block syntax:
+
+```markdown
+::: ^id
+Footnote content goes here.
+
+You can include multiple paragraphs, lists, and other block elements.
+:::
+```
+
+The fenced block syntax starts with `:::` followed by a space and `^` with the footnote identifier. The content is enclosed between the opening `:::` and closing `:::` markers.
+
+### Footnote References
+
+Reference a footnote in your text using the same `[^id]` syntax:
+
+```markdown
+Here is some text with a footnote reference[^1].
+```
+
+## Examples
+
+### Basic Inline Footnote
+
+Here is a sentence with a footnote[^basic].
+
+[^basic]: This is a simple inline footnote definition.
+
+```markdown
+Here is a sentence with a footnote[^basic].
+
+[^basic]: This is a simple inline footnote definition.
+```
+
+### Fenced Block with Single Paragraph
+
+This example demonstrates a simple fenced block footnote[^simple].
+
+::: ^simple
+This is a footnote defined using the fenced block syntax. It contains a single paragraph.
+:::
+
+```markdown
+This example demonstrates a simple fenced block footnote[^simple].
+
+::: ^simple
+This is a footnote defined using the fenced block syntax. It contains a single paragraph.
+:::
+```
+
+### Fenced Block with Multiple Paragraphs
+
+For more detailed footnotes, you can include multiple paragraphs[^multipara].
+
+::: ^multipara
+This is the first paragraph of the footnote.
+
+This is the second paragraph, providing additional context or information.
+
+And here's a third paragraph for even more detail.
+:::
+
+```markdown
+For more detailed footnotes, you can include multiple paragraphs[^multipara].
+
+::: ^multipara
+This is the first paragraph of the footnote.
+
+This is the second paragraph, providing additional context or information.
+
+And here's a third paragraph for even more detail.
+:::
+```
+
+### Fenced Block with Lists
+
+Footnotes can contain complex content like lists[^withlist].
+
+::: ^withlist
+This footnote contains a bulleted list:
+
+- First item in the list
+- Second item in the list
+- Third item in the list
+
+Lists help organize information within footnotes.
+:::
+
+```markdown
+Footnotes can contain complex content like lists[^withlist].
+
+::: ^withlist
+This footnote contains a bulleted list:
+
+- First item in the list
+- Second item in the list
+- Third item in the list
+
+Lists help organize information within footnotes.
+:::
+```
+
+### Fenced Block with Inline Formatting
+
+Footnotes support rich inline formatting[^formatted].
+
+::: ^formatted
+This footnote has **bold text**, *italic text*, and `inline code`.
+
+It also supports [links](https://example.com) and other inline elements.
+:::
+
+```markdown
+Footnotes support rich inline formatting[^formatted].
+
+::: ^formatted
+This footnote has **bold text**, *italic text*, and `inline code`.
+
+It also supports [links](https://example.com) and other inline elements.
+:::
+```
+
+### Mixing Inline and Fenced Block Footnotes
+
+You can use both styles in the same document[^inline][^fenced].
+
+[^inline]: This is an inline-style footnote definition.
+
+::: ^fenced
+This is a fenced block footnote definition.
+
+It can contain multiple paragraphs and other block-level content.
+:::
+
+```markdown
+You can use both styles in the same document[^inline][^fenced].
+
+[^inline]: This is an inline-style footnote definition.
+
+::: ^fenced
+This is a fenced block footnote definition.
+
+It can contain multiple paragraphs and other block-level content.
+:::
+```
+
+### Named Footnote Identifiers
+
+Footnote identifiers can be descriptive names, not just numbers[^descriptive-name].
+
+::: ^descriptive-name
+Using descriptive names like `^descriptive-name` instead of numbers like `^1` can make your markdown more readable and maintainable.
+
+Identifiers can include letters, numbers, and hyphens.
+:::
+
+```markdown
+Footnote identifiers can be descriptive names, not just numbers[^descriptive-name].
+
+::: ^descriptive-name
+Using descriptive names like `^descriptive-name` instead of numbers like `^1` can make your markdown more readable and maintainable.
+
+Identifiers can include letters, numbers, and hyphens.
+:::
+```

docs/syntax/index.qmd

@@ -11,3 +11,4 @@ The features documented here are currently under development. The syntax and beh
 ## Available Features
 
 - [Definition Lists](definition-lists.qmd) - Create definition lists using an embedded markdown DSL
+- [Footnotes](footnotes.qmd) - Add footnotes with inline or fenced block syntax