diff --git a/docs/about/attribution.md b/docs/about/attribution.md index 387060e..6655495 100644 --- a/docs/about/attribution.md +++ b/docs/about/attribution.md @@ -6,11 +6,14 @@ This site, and all StarCat Systems projects, products, and services make use of - [`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. - [`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/). +- [`policies` repo](https://git.starcat.systems/starcatsys/policies) icon - adapted from [scroll](https://fontawesome.com/icons/scroll?f=classic&s=solid) by FontAwesome. +- 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/), [Simple Icons](https://simpleicons.org/), and [OpenMoji](https://openmoji.org/). StarCat product logo icons are attributed elsewhere in this list. - StarCat Cloud icon - adapted from [cloud](https://primer.style/octicons/icon/cloud-16/) by [Octicons](https://octicons.github.com/). - [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. +- [PostLine](https://postline.email) logo - adapted from [Group Mail](https://thenounproject.com/icon/group-mail-1571732/) by [Smashicons](https://thenounproject.com/creator/smashicons/) from Noun Project. +- [OpenHosted](https://openhosted.net) logo - adapted from [Blockchain](https://thenounproject.com/icon/blockchain-7881143/) by [Hermanto](https://thenounproject.com/creator/kak.her1992/) from Noun Project. ## Images diff --git a/docs/handbook/meta/.nav.yml b/docs/handbook/meta/.nav.yml index 9d27d6d..d21ca40 100644 --- a/docs/handbook/meta/.nav.yml +++ b/docs/handbook/meta/.nav.yml @@ -2,4 +2,5 @@ title: Meta nav: - index.md - editing.md - - syntax.md \ No newline at end of file + - syntax.md + - custom_icons.md \ No newline at end of file diff --git a/docs/handbook/meta/custom_icons.md b/docs/handbook/meta/custom_icons.md new file mode 100644 index 0000000..4b2c843 --- /dev/null +++ b/docs/handbook/meta/custom_icons.md @@ -0,0 +1,25 @@ +# Custom Icons +Material for MkDocs supports custom icons (for example, for our product logos). Here are some notes and steps on adding these files to this site. + +## 0. Start with an svg +You will need the icon in a square `.svg` file format, with a transparent background. I haven't experimented too much with size, but files up to 1000 x 1000 seem to work fine so far. + +## 1. Minify the svg +So that the image will work with MkDocs' color switching and CSS, we need to remove any embedded colors and cruft from the SVG file. + +1. Open [:octicons-link-external-16: SVGOMG Optimize](https://optimize.svgomg.net/) +2. In the left menu, choose **Open SVG** and upload your SVG file +3. In the *Global Settings* menu, turn on all the options **except for** `Show original`. Leave the sliders at their default settings. +4. In the *Features* menu, turn on all the options **except for** `Remove xmlns`. +5. Use the blue download button to download your newly optimized SVG. + +## 2. Add the optimized svg to this repo +In the `about` repo, add the optimized svg file you just downloaded to the `overrides\.icons\` folder. The category will depend on what kind of icon you're adding. (StarCat product icons go in `logos`, etc.) + +## 3. Use your new icon +If you're using the new icon in a Markdown page, you can use the syntax `-`. So, if the category is `logos` and the icon is `docshub.svg`, your icon syntax would be `icons-docshub`. + +## Reference +For a list of the major custom icons and their syntax, see [:octicons-arrow-right-16: Syntax #Custom Icons](syntax.md#custom-icons). + +For the primary documentation on Custom Icons in Material for MkDocs, see [:simple-materialformkdocs: Customization - Additional icons](https://squidfunk.github.io/mkdocs-material/setup/changing-the-logo-and-icons/#additional-icons). \ No newline at end of file diff --git a/docs/handbook/meta/syntax.md b/docs/handbook/meta/syntax.md index 36ab0e9..6f2a30c 100644 --- a/docs/handbook/meta/syntax.md +++ b/docs/handbook/meta/syntax.md @@ -12,6 +12,17 @@ Reference for all available Material for MkDocs icons: [:simple-materialformkdoc :material-book-lock: `:material-book-lock:` - used for links to the StarCat Systems internal handbook :material-folder-lock: `:material-folder-lock:` - used for restricted links to files hosted on StarCat Cloud. +### Custom icons +There are some custom icons added to this MkDocs instance, for example for StarCat product logos. See [:octicons-arrow-right-16: Custom Icons](custom_icons.md) for more details on adding and using custom icons. + +#### Logos +:logos-starcat-circle: `:logos-starcat-circle:` - StarCat Systems circle logo +:logos-sourcecamp: `:logos-sourcecamp:` - SourceCamp logo +:logos-docshub: `:logos-docshub:` - DocsHub logo +:logos-stagelink: `:logos-stagelink:` - StageLink logo +:logos-postline: `:logos-postline:` - PostLine logo +:logos-openhosted: `:logos-openhosted:` - OpenHosted logo + ### 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 }` @@ -85,6 +96,34 @@ Here are some common admonitions, when you might use them, and quick code snippe ### Custom We've modified a couple of the standard admonitions to mean something a little different on this site. +#### Deprecated +For pages that were once accurate, but are either no longer accurate and not being updated, or have become obsolete due to discontinuation, etc. Place this admonition at the top of the page, just below the title. + +!!! deprecated "Deprecated" + The `deprecated` admonition looks like this. + +??? quote "Syntax" + Copy and paste at the top of page content: + ``` + !!! deprecated "Deprecated" + The contents of this page are deprecated. Do not rely on any information on this page to be accurate, as it is not being updated. + + Please see for the equivalet updated information. + ``` + +#### Page Moved +If a page has been moved, but you still need to link to the original page location for whatever reason. Remove the content of the page (just cut and paste it to the new location), and leave a blank page with just a title and this admonition, linking to the new page location. + +!!! page-moved "Page Moved" + This page has been moved to a new location. Please view the relocated page [:octicons-arrow-right-16: here](#). + +??? quote "Syntax" + Copy and paste at the top of page content: + ``` + !!! page-moved "Page Moved" + This page has been moved to a new location. Please view the relocated page [:octicons-arrow-right-16: here](#). + ``` + #### 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.) diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index c61704b..1868549 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -1,3 +1,39 @@ +:root { + --md-admonition-icon--deprecated: url('data:image/svg+xml;charset=utf-8,') +} +.md-typeset .admonition.deprecated, +.md-typeset details.deprecated { + border-color: rgb(98, 114, 164); +} +.md-typeset .deprecated > .admonition-title, +.md-typeset .deprecated > summary { + background-color: rgba(98, 114, 164, 0.1); +} +.md-typeset .deprecated > .admonition-title::before, +.md-typeset .deprecated > summary::before { + background-color: rgb(98, 114, 164); + -webkit-mask-image: var(--md-admonition-icon--deprecated); + mask-image: var(--md-admonition-icon--deprecated); +} + +:root { + --md-admonition-icon--page-moved: url('data:image/svg+xml;charset=utf-8,') +} +.md-typeset .admonition.page-moved, +.md-typeset details.page-moved { + border-color: rgb(255, 121, 198); +} +.md-typeset .page-moved > .admonition-title, +.md-typeset .page-moved > summary { + background-color: rgba(255, 121, 198, 0.1); +} +.md-typeset .page-moved > .admonition-title::before, +.md-typeset .page-moved > summary::before { + background-color: rgb(255, 121, 198); + -webkit-mask-image: var(--md-admonition-icon--page-moved); + mask-image: var(--md-admonition-icon--page-moved); +} + .note-blue { color: #448AFF; } diff --git a/mkdocs.yml b/mkdocs.yml index be1d57c..c62eb59 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,6 +2,7 @@ site_name: StarCat Systems site_url: https://about.starcat.systems theme: name: material + custom_dir: overrides palette: - media: "(prefers-color-scheme: light)" scheme: default @@ -68,6 +69,9 @@ markdown_extensions: - pymdownx.emoji: emoji_index: !!python/name:material.extensions.emoji.twemoji emoji_generator: !!python/name:material.extensions.emoji.to_svg + options: + custom_icons: + - overrides/.icons - pymdownx.highlight: anchor_linenums: true line_spans: __span diff --git a/overrides/.icons/flags/finland.svg b/overrides/.icons/flags/finland.svg new file mode 100644 index 0000000..2b43273 --- /dev/null +++ b/overrides/.icons/flags/finland.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/overrides/.icons/flags/germany.svg b/overrides/.icons/flags/germany.svg new file mode 100644 index 0000000..c1c47f5 --- /dev/null +++ b/overrides/.icons/flags/germany.svg @@ -0,0 +1,31 @@ + + + + + + + + + + + \ No newline at end of file diff --git a/overrides/.icons/flags/luxembourg.svg b/overrides/.icons/flags/luxembourg.svg new file mode 100644 index 0000000..beab020 --- /dev/null +++ b/overrides/.icons/flags/luxembourg.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/overrides/.icons/flags/usa.svg b/overrides/.icons/flags/usa.svg new file mode 100644 index 0000000..880e3e8 --- /dev/null +++ b/overrides/.icons/flags/usa.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/overrides/.icons/logos/docshub.svg b/overrides/.icons/logos/docshub.svg new file mode 100644 index 0000000..988adca --- /dev/null +++ b/overrides/.icons/logos/docshub.svg @@ -0,0 +1,4 @@ + + + + diff --git a/overrides/.icons/logos/openhosted.svg b/overrides/.icons/logos/openhosted.svg new file mode 100644 index 0000000..92a8b0a --- /dev/null +++ b/overrides/.icons/logos/openhosted.svg @@ -0,0 +1,3 @@ + + + diff --git a/overrides/.icons/logos/postline.svg b/overrides/.icons/logos/postline.svg new file mode 100644 index 0000000..0d59b13 --- /dev/null +++ b/overrides/.icons/logos/postline.svg @@ -0,0 +1,3 @@ + + + diff --git a/overrides/.icons/logos/sourcecamp.svg b/overrides/.icons/logos/sourcecamp.svg new file mode 100644 index 0000000..2ce6244 --- /dev/null +++ b/overrides/.icons/logos/sourcecamp.svg @@ -0,0 +1,3 @@ + + + diff --git a/overrides/.icons/logos/stagelink.svg b/overrides/.icons/logos/stagelink.svg new file mode 100644 index 0000000..b490393 --- /dev/null +++ b/overrides/.icons/logos/stagelink.svg @@ -0,0 +1,4 @@ + + + + diff --git a/overrides/.icons/logos/starcat-circle.svg b/overrides/.icons/logos/starcat-circle.svg new file mode 100644 index 0000000..569d2b8 --- /dev/null +++ b/overrides/.icons/logos/starcat-circle.svg @@ -0,0 +1,4 @@ + + + +