From 082564101e0cb72859da5816fbd1279cacf87faa Mon Sep 17 00:00:00 2001 From: m-fr Date: Fri, 1 Nov 2024 09:47:44 +0100 Subject: [PATCH] Added markdown building blocks to documentation --- .../markdown_building_blocks.md | 185 ++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 186 insertions(+) create mode 100644 docs/default_templates/markdown_building_blocks.md diff --git a/docs/default_templates/markdown_building_blocks.md b/docs/default_templates/markdown_building_blocks.md new file mode 100644 index 0000000..d80b799 --- /dev/null +++ b/docs/default_templates/markdown_building_blocks.md @@ -0,0 +1,185 @@ +# Markdown building blocks + +This page provides an overview of the building blocks for writing your own findings. It covers the nuances of the markdown syntax available for the default templates. + +For more details about the markdown language, we recommend checking the [Markdown Guide][mdguide] and [Pandoc Flavoured Markdown][pandocmd]. + +!!! tip + The public templates include a `test_finding` example. You can use it as a reference and inspiration for creating your own findings. + +## Text highlighting + +The template supports various text highlighting options: + +- **Emphasis**: Use `*` or `_` to emphasize text. +- **Strong emphasis**: Use `**` or `__` to make text bold. +- **Strikethrough**: Use `~~` to strike through text. +- **Subscripts**: Use `H~2~O` to create subscripts. +- **Superscripts**: Use `x^2^` to create superscripts. +- **Underlining**: Use `[Underline this.]{.underline}` to underline text. +- **Small caps**: Use `[Small caps]{.smallcaps}` to create small caps text. + +## Acronyms + +Another feature of the template is the ability to define acronyms using the `[!acr]` syntax, implemented via the [pandoc filter][filter]. + +This feature supports both capitalization and pluralization: + +- Capitalization: Use the `^` prefix, e.g., `[!^acr]`. +- Pluralization: Use the `+` prefix, e.g., `[!+acr]`. + +By default, the acronym appears as `acronym (acr)` on the first occurrence and `acr` thereafter. You can explicitly set the form using the following suffixes: + +- `<` for the short form +- `>` for the long form +- `!` for the full form. + +
+ + Check this reference for all possible combinations. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FormTagDisplay
Default[!acr]acronym (acr)
Short[!acr<]acr
Long[!acr>]acronym
Full[!acr!]acronym (acr)
Default plural[!+acr]acrs
Short plural[!+acr<]acrs
Long plural[!+acr>]acronyms
Full plural[!+acr!]acronyms (acrs)
Default capitalized[!^acr]Acr
Short capitalized[!^acr<]Acr
Long capitalized[!^acr>]Acronym
Full capitalized[!^acr!]Acronym (acr)
Default capitalized plural[!+^acr]Acrs
Short capitalized plural[!+^acr<]Acrs
Long capitalized plural[!+^acr>]Acronyms
Full capitalized plural[!+^acr!]Acronyms (acrs)
+
+ +## Code + +Another feature implemented via the [pandoc filter][filter] is code typesetting. +Code segments are translated into [minted] macros, supporting both inline and block code. + +The verbatim environment supports language highlighting and any [minted] attributes. +The language can be specified directly after the backticks (`` ` ``) if there are no other attributes. + +``````markdown +```py +random.seed(42) +print(random.random) +``` +`````` + +Attributes can be added after the backticks (`` ` ``) within curly braces (`{}`). +When specifying attributes, place the language as a dot parameter before other parameters. + +``````markdown +```{.py linenos=true} +random.seed(42) +print(random.random) +``` +`````` + +This extension also supports typesetting code directly from a file using the `source` attribute. + +``````markdown +` `{.py source=hello.py} +`````` + +## Other features + +The public template is configured to support all the default [pandoc markdown][pandocmd] features. This includes: + +- [Text emphasizing](#text-highlighting) +- Lists + - Unordered + - Ordered + - Task + - Definition +- Tables +- Math +- Links +- Footnotes +- Images + +[mdguide]: https://www.markdownguide.org/ +[pandocmd]: https://pandoc.org/MANUAL.html#pandocs-markdown +[filter]: https://pandoc.org/filters.html +[minted]: https://ctan.org/pkg/minted diff --git a/mkdocs.yml b/mkdocs.yml index 4ca35e9..4f5612a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -77,6 +77,7 @@ nav: - Templates: - default_templates/structure.md - default_templates/building_blocks.md + - default_templates/markdown_building_blocks.md - Reference: - CLI: - reference/cli/cli.md