112 lines
No EOL
5 KiB
Markdown
112 lines
No EOL
5 KiB
Markdown
# Editing this site
|
|
|
|
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_docs Git repo](https://git.starcat.systems/starcatsys/about_docs).
|
|
|
|
## 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
|
|
|
|
### 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_docs/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:
|
|
|
|
??? 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_docs) for this site.
|
|
```
|
|
|
|
---
|
|
|
|
!!! 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_docs) for this site. |