diff --git a/README.md b/README.md index 316bb37..60a3ba3 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,7 @@ This repo contains the source Markdown and MkDocs files that generate [about.starcat.systems](https://about.starcat.systems) using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). +[![Gitea Last Commit](https://img.shields.io/gitea/last-commit/starcatsys/about?display_timestamp=committer&gitea_url=https%3A%2F%2Fgit.starcat.systems&style=flat&logo=git&logoColor=fff&logoSize=auto)](https://git.starcat.systems/starcatsys/about_docs/) ## Contributing diff --git a/docs/about/attribution.md b/docs/about/attribution.md index 3365e47..a9e5a9c 100644 --- a/docs/about/attribution.md +++ b/docs/about/attribution.md @@ -4,9 +4,9 @@ This site, and all StarCat Systems projects, products, and services make use of ## Icons - [StarCat Systems](https://starcat.systems) logo - adapted from [Cat](https://thenounproject.com/icon/cat-6441095/) by [Md Ahasan Habib](https://thenounproject.com/creator/md_ahasan/) from Noun Project. - [`about` site](https://about.starcat.systems) favicon - adapted from [Book](https://thenounproject.com/icon/book-6252926/) by [iconpro86](https://thenounproject.com/creator/iconpro86/) from Noun Project. -- [`about` repo](https://git.starcat.systems/starcatsys/about) icon - adapted from [Book](https://thenounproject.com/icon/book-1833960/) by [Untashable](https://thenounproject.com/creator/untashable/) from Noun Project. +- [`about-docs` repo](https://git.starcat.systems/starcatsys/about) icon - adapted from [Book](https://thenounproject.com/icon/book-1833960/) by [Untashable](https://thenounproject.com/creator/untashable/) from Noun Project. - [`starcat-infra` org](https://git.starcat.systems/starcat-infra) icon - adapted from [Engineering](https://thenounproject.com/icon/engineering-7486606/) by [sunardi](https://thenounproject.com/creator/matah3574/) from Noun Project. -- Icons used on this `about` site are by [Material Design](https://pictogrammers.com/library/mdi/), [FontAwesome](https://fontawesome.com/search?m=free), [Octicons](https://octicons.github.com/), and [Simple Icons](https://simpleicons.org/). +- [`starcat-dev` org](https://git.starcat.systems/starcat-dev) icon - adapted from [lab](https://thenounproject.com/icon/lab-4581077/) by [cr9183353](https://thenounproject.com/creator/cr9183353/) from Noun Project. +- [Git server](https://git.starcat.systems/) icon - adapted from [Arcticons Thin Line Icons Collection](https://www.svgrepo.com/collection/arcticons-thin-line-icons/) by [Donnnno](https://www.svgrepo.com/author/Donnnno/) and from the StarCat Systems logo, above. - [SourceCamp](https://source.camp) logo - adapted from [camp](https://thenounproject.com/icon/camp-7375488/) by [Ricons](https://thenounproject.com/creator/ricons/) from Noun Project. -- [DocsHub](https://docshub.io) logo - adapted from [Document](https://thenounproject.com/icon/document-6244658/) by [Reion](https://thenounproject.com/creator/dickydante/) from Noun Project. -- [StageLink](https://stagelink.cloud) logo - adapted from [slider](https://thenounproject.com/icon/slider-2309209/) by [DinosoftLabs](https://thenounproject.com/creator/dinosoftlab/) from Noun Project. \ No newline at end of file +- Icons used on this `about` site are by [Material Design](https://pictogrammers.com/library/mdi/), [FontAwesome](https://fontawesome.com/search?m=free), [Octicons](https://octicons.github.com/), and [Simple Icons](https://simpleicons.org/). \ No newline at end of file diff --git a/docs/handbook/meta/.nav.yml b/docs/handbook/meta/.nav.yml index 9d27d6d..3fbd06f 100644 --- a/docs/handbook/meta/.nav.yml +++ b/docs/handbook/meta/.nav.yml @@ -1,5 +1,4 @@ title: Meta nav: - index.md - - editing.md - - syntax.md \ No newline at end of file + - editing.md \ No newline at end of file diff --git a/docs/handbook/meta/editing.md b/docs/handbook/meta/editing.md index 810a45b..84a7f99 100644 --- a/docs/handbook/meta/editing.md +++ b/docs/handbook/meta/editing.md @@ -2,8 +2,127 @@ This page contains information on editing/making changes to this website. -## Syntax -Please see [:octicons-arrow-right-16: Syntax](syntax.md) for reference on various Material for MkDocs syntax you can use in your Markdown, and specific usage on this site. +## 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/index.md b/docs/handbook/meta/index.md index 7441ac7..408ffb5 100644 --- a/docs/handbook/meta/index.md +++ b/docs/handbook/meta/index.md @@ -1,12 +1,7 @@ # Handbook Meta -This Meta section is for information about this `about.starcat.systems` site itself. - -## 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). - -## Editing -If you're looking for information about editing this site, please see [:octicons-arrow-right-16: Editing](editing.md). For specific Markdown syntax you can use with Material for MkDocs, please see [:octicons-arrow-right-16: Syntax](syntax.md). +!!! abstract "Placeholder Page" + This is a placeholder page. Please see the site navigation for any sub-pages that exist. --- diff --git a/docs/handbook/meta/syntax.md b/docs/handbook/meta/syntax.md deleted file mode 100644 index 794f544..0000000 --- a/docs/handbook/meta/syntax.md +++ /dev/null @@ -1,129 +0,0 @@ -# Syntax - -You can find a reference for the syntax used in writing this site in the Material for MkDocs [:simple-materialformkdocs: Reference section](https://squidfunk.github.io/mkdocs-material/reference/). On this particular site, there are some specific syntax point that we use. This page is intended to provide a reference for those specifics. - -## 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