diff --git a/docs/handbook/meta/.nav.yml b/docs/handbook/meta/.nav.yml index 3fbd06f..9d27d6d 100644 --- a/docs/handbook/meta/.nav.yml +++ b/docs/handbook/meta/.nav.yml @@ -1,4 +1,5 @@ title: Meta nav: - index.md - - editing.md \ No newline at end of file + - editing.md + - syntax.md \ No newline at end of file diff --git a/docs/handbook/meta/editing.md b/docs/handbook/meta/editing.md index 84a7f99..7009b8a 100644 --- a/docs/handbook/meta/editing.md +++ b/docs/handbook/meta/editing.md @@ -5,124 +5,7 @@ This page contains information on editing/making changes to this website. ## Material for MkDocs This site is written in Markdown and is generated using [:simple-materialformkdocs: Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) Insiders. The source Markdown is stored in the [:simple-forgejo: about Git repo](https://git.starcat.systems/starcatsys/about). -## Icons -Reference for all available Material for MkDocs icons: [:simple-materialformkdocs: Icons, Emojis](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/) -### Commonly-used icons for links -:octicons-arrow-right-16: `:octicons-arrow-right-16:` - used for links within the wiki -:octicons-tab-external-16: `:octicons-tab-external-16:` - used for links outside the wiki, but within StarCat Systems -:octicons-link-external-16: `:octicons-link-external-16:` - used for external links to sites not controlled by StarCat Systems -:material-book-lock: `:material-book-lock:` - used for links to the StarCat Systems internal handbook - -### Coloring icons -You can add a color to an icon by adding the CSS color after the icon, like this: -:fontawesome-solid-dragon:{ .bug-pink } `:fontawesome-solid-dragon:{ .bug-pink }` - - -Currently, the available configured colors are based off the built-in admonition colors and icons, as follows: - -:fontawesome-regular-note-sticky:{ .note-blue } `:fontawesome-regular-note-sticky:{ .note-blue }` -:octicons-info-16:{ .info-blue } `:octicons-info-16:{ .info-blue }` -:octicons-flame-16:{ .tip-teal } `:octicons-flame-16:{ .tip-teal }` -:octicons-check-16:{ .success-green } `:octicons-check-16:{ .success-green }` -:octicons-question-16:{ .question-green } `:octicons-question-16:{ .question-green }` -:octicons-alert-16:{ .warning-yellow } `:octicons-alert-16:{ .warning-yellow }` -:octicons-x-circle-16:{ .failure-red } `:octicons-x-circle-16:{ .failure-red }` -:octicons-zap-16:{ .danger-red } `:octicons-zap-16:{ .danger-red }` -:octicons-bug-16:{ .bug-pink } `:octicons-bug-16:{ .bug-pink }` -:octicons-beaker-16:{ .example-purple } `:octicons-beaker-16:{ .example-purple }` -:octicons-quote-16:{ .quote-grey } `:octicons-quote-16:{ .quote-grey }` - -:octicons-flame-16:{ .tip-teal } Want to know how these colors work? Check out [:simple-forgejo: the CSS in the source](https://git.starcat.systems/starcatsys/about/src/branch/main/docs/stylesheets/extra.css). - -## Admonitions -Reference for using Admonitions: [:simple-materialformkdocs: Admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#usage) - - - -### Common Admonition Usage -Here are some common admonitions, when you might use them, and quick code snippets that you can paste in. - -!!! note - Highlights information that users should take into account, even when skimming. - - - ``` - !!! note - Highlights information that users should take into account, even when skimming. - ``` - -!!! tip - Helpful advice for doing things better or more easily. - - ``` - !!! tip - Helpful advice for doing things better or more easily. - ``` - -!!! warning - Advises about risks or negative outcomes of certain actions. - - ``` - !!! warning - Advises about risks or negative outcomes of certain actions. - ``` - -!!! danger - Urgent info that needs immediate user attention to avoid problems. - - ``` - !!! danger - Urgent info that needs immediate user attention to avoid problems. - ``` - -!!! bug - Information about a known bug in a current version. Whenever possible, provide a link to the issue report. Place a link back to the page with this admonition, in the issue report so that the admonition can be removed when the bug is closed. - - ``` - !!! bug - Information about a known bug in a current version. Whenever possible, provide a link to the issue report. Place a link back to the page with this admonition, in the issue report so that the admonition can be removed when the bug is closed. - ``` - -### Custom -We've modified a couple of the standard admonitions to mean something a little different on this site. - -#### Work in Progress -For pages that aren't yet complete, and need revisions (that we know are going to be revised sooner/more frequently than a typical page.) - -Typically, we will put this at the bottom of the page content, with a dividing line between any page content and this admonition. - -Example page with this Work in Progress admonition: [:octicons-arrow-right-16: Example WIP Admonition](example_pages/example_wip_admonition.md) - -??? quote "Syntax" - Copy and paste at the bottom of page content: - ``` - --- - - !!! example "Work in Progress" - This page is not complete, and is subject to change. - - Want to help with this page? Please see [:octicons-arrow-right-16: Editing this site](https://about.starcat.systems/editing/) and the [:simple-forgejo: Git repo](https://git.starcat.systems/starcatsys/about) for this site. - ``` - - -#### Placeholder Page -For pages that are newly created and have no (or very little) content on the page itself. Also used for `index.md` pages in directories that have other contents, but no content on the directory index. - -Example page with the Placeholder Page admonition: [:octicons-arrow-right-16: Example Placeholder Page Admonition](example_pages/example_placeholder_page_admonition.md) - -??? quote "Syntax" - Copy and paste at the bottom of page content: - ``` - !!! abstract "Placeholder Page" - This is a placeholder page. Please see the site navigation for any sub-pages that exist. - ``` - -!!! tip - Typically, any page that is marked as a Placeholder Page should also be marked with the **Work in Progress** admonition because they are, by their nature, incomplete. - - Example page with the Placeholder and WIP admonitions: [:octicons-arrow-right-16: Example Placeholder and WIP Admonitions](example_pages/example_wip_placeholder_admonitions.md) - Source code that you can quickly copy from when making an index or placeholder page is located [:simple-forgejo: here](https://git.starcat.systems/starcatsys/about/src/branch/main/docs/handbook/meta/example_pages/example_wip_placeholder_admonitions.md). --- diff --git a/docs/handbook/meta/syntax.md b/docs/handbook/meta/syntax.md new file mode 100644 index 0000000..09d3b47 --- /dev/null +++ b/docs/handbook/meta/syntax.md @@ -0,0 +1,127 @@ +# Syntax + +## Icons +Reference for all available Material for MkDocs icons: [:simple-materialformkdocs: Icons, Emojis](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/) + +### Commonly-used icons for links +:octicons-arrow-right-16: `:octicons-arrow-right-16:` - used for links within the wiki +:octicons-tab-external-16: `:octicons-tab-external-16:` - used for links outside the wiki, but within StarCat Systems +:octicons-link-external-16: `:octicons-link-external-16:` - used for external links to sites not controlled by StarCat Systems +:material-book-lock: `:material-book-lock:` - used for links to the StarCat Systems internal handbook + +### Coloring icons +You can add a color to an icon by adding the CSS color after the icon, like this: +:fontawesome-solid-dragon:{ .bug-pink } `:fontawesome-solid-dragon:{ .bug-pink }` + + +Currently, the available configured colors are based off the built-in admonition colors and icons, as follows: + +:fontawesome-regular-note-sticky:{ .note-blue } `:fontawesome-regular-note-sticky:{ .note-blue }` +:octicons-info-16:{ .info-blue } `:octicons-info-16:{ .info-blue }` +:octicons-flame-16:{ .tip-teal } `:octicons-flame-16:{ .tip-teal }` +:octicons-check-16:{ .success-green } `:octicons-check-16:{ .success-green }` +:octicons-question-16:{ .question-green } `:octicons-question-16:{ .question-green }` +:octicons-alert-16:{ .warning-yellow } `:octicons-alert-16:{ .warning-yellow }` +:octicons-x-circle-16:{ .failure-red } `:octicons-x-circle-16:{ .failure-red }` +:octicons-zap-16:{ .danger-red } `:octicons-zap-16:{ .danger-red }` +:octicons-bug-16:{ .bug-pink } `:octicons-bug-16:{ .bug-pink }` +:octicons-beaker-16:{ .example-purple } `:octicons-beaker-16:{ .example-purple }` +:octicons-quote-16:{ .quote-grey } `:octicons-quote-16:{ .quote-grey }` + +:octicons-flame-16:{ .tip-teal } Want to know how these colors work? Check out [:simple-forgejo: the CSS in the source](https://git.starcat.systems/starcatsys/about/src/branch/main/docs/stylesheets/extra.css). + +## Admonitions +Reference for using Admonitions: [:simple-materialformkdocs: Admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#usage) + + + +### Common Admonition Usage +Here are some common admonitions, when you might use them, and quick code snippets that you can paste in. + +!!! note + Highlights information that users should take into account, even when skimming. + + + ``` + !!! note + Highlights information that users should take into account, even when skimming. + ``` + +!!! tip + Helpful advice for doing things better or more easily. + + ``` + !!! tip + Helpful advice for doing things better or more easily. + ``` + +!!! warning + Advises about risks or negative outcomes of certain actions. + + ``` + !!! warning + Advises about risks or negative outcomes of certain actions. + ``` + +!!! danger + Urgent info that needs immediate user attention to avoid problems. + + ``` + !!! danger + Urgent info that needs immediate user attention to avoid problems. + ``` + +!!! bug + Information about a known bug in a current version. Whenever possible, provide a link to the issue report. Place a link back to the page with this admonition, in the issue report so that the admonition can be removed when the bug is closed. + + ``` + !!! bug + Information about a known bug in a current version. Whenever possible, provide a link to the issue report. Place a link back to the page with this admonition, in the issue report so that the admonition can be removed when the bug is closed. + ``` + +### Custom +We've modified a couple of the standard admonitions to mean something a little different on this site. + +#### Work in Progress +For pages that aren't yet complete, and need revisions (that we know are going to be revised sooner/more frequently than a typical page.) + +Typically, we will put this at the bottom of the page content, with a dividing line between any page content and this admonition. + +Example page with this Work in Progress admonition: [:octicons-arrow-right-16: Example WIP Admonition](example_pages/example_wip_admonition.md) + +??? quote "Syntax" + Copy and paste at the bottom of page content: + ``` + --- + + !!! example "Work in Progress" + This page is not complete, and is subject to change. + + Want to help with this page? Please see [:octicons-arrow-right-16: Editing this site](https://about.starcat.systems/editing/) and the [:simple-forgejo: Git repo](https://git.starcat.systems/starcatsys/about) for this site. + ``` + + +#### Placeholder Page +For pages that are newly created and have no (or very little) content on the page itself. Also used for `index.md` pages in directories that have other contents, but no content on the directory index. + +Example page with the Placeholder Page admonition: [:octicons-arrow-right-16: Example Placeholder Page Admonition](example_pages/example_placeholder_page_admonition.md) + +??? quote "Syntax" + Copy and paste at the bottom of page content: + ``` + !!! abstract "Placeholder Page" + This is a placeholder page. Please see the site navigation for any sub-pages that exist. + ``` + +!!! tip + Typically, any page that is marked as a Placeholder Page should also be marked with the **Work in Progress** admonition because they are, by their nature, incomplete. + + Example page with the Placeholder and WIP admonitions: [:octicons-arrow-right-16: Example Placeholder and WIP Admonitions](example_pages/example_wip_placeholder_admonitions.md) + Source code that you can quickly copy from when making an index or placeholder page is located [:simple-forgejo: here](https://git.starcat.systems/starcatsys/about/src/branch/main/docs/handbook/meta/example_pages/example_wip_placeholder_admonitions.md). + +--- + +!!! example "Work in Progress" + This page is not complete, and is subject to change. + + Want to help with this page? Please see [:octicons-arrow-right-16: Editing this site](https://about.starcat.systems/editing/) and the [:simple-forgejo: Git repo](https://git.starcat.systems/starcatsys/about) for this site. \ No newline at end of file