starcatsys/about
starcatsys/about
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
about/docs/handbook/meta/editing.md

6.4 KiB
Raw Blame History

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 Insiders. The source Markdown is stored in the :simple-forgejo: about Git repo.

Icons

Reference for all available Material for MkDocs icons: :simple-materialformkdocs: 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.

Admonitions

Reference for using Admonitions: :simple-materialformkdocs: Admonitions

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

??? 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

??? 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.