Make separate syntax page
This commit is contained in:
parent
ca54fd4f3c
commit
f0299921ff
SSH key fingerprint:
SHA256:bLOq3d7dN1v5+W5U6pQekP0rBm0YUtC9qvh3TDYyAsg
3 changed files with 129 additions and 118 deletions
|
|
@ -1,4 +1,5 @@
|
|||
title: Meta
|
||||
nav:
|
||||
- index.md
|
||||
- editing.md
|
||||
- editing.md
|
||||
- syntax.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).
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
127
docs/handbook/meta/syntax.md
Normal file
127
docs/handbook/meta/syntax.md
Normal file
|
|
@ -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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue