From 682e5b6bbd77ea9c8c892e9141dded394feb2cc6 Mon Sep 17 00:00:00 2001 From: thhsh-local Date: Tue, 20 May 2025 11:30:35 -0400 Subject: [PATCH 1/8] Add custom icons and flags --- mkdocs.yml | 4 ++++ overrides/.icons/flags/finland.svg | 1 + overrides/.icons/flags/germany.svg | 31 +++++++++++++++++++++++++++ overrides/.icons/flags/luxembourg.svg | 1 + overrides/.icons/flags/usa.svg | 1 + 5 files changed, 38 insertions(+) create mode 100644 overrides/.icons/flags/finland.svg create mode 100644 overrides/.icons/flags/germany.svg create mode 100644 overrides/.icons/flags/luxembourg.svg create mode 100644 overrides/.icons/flags/usa.svg 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 From ac7afd56378c3c5f2829ed9b1d15ffefea97d3f3 Mon Sep 17 00:00:00 2001 From: thhsh-local Date: Tue, 20 May 2025 11:30:49 -0400 Subject: [PATCH 2/8] Add attribution for flag emoji and policies repo --- docs/about/attribution.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/about/attribution.md b/docs/about/attribution.md index 387060e..b647811 100644 --- a/docs/about/attribution.md +++ b/docs/about/attribution.md @@ -6,7 +6,8 @@ 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. From bf74be37a7ef60af7a86d0689dc5a0c8b7341f2e Mon Sep 17 00:00:00 2001 From: thhsh-local Date: Tue, 20 May 2025 12:42:22 -0400 Subject: [PATCH 3/8] Add StarCat logo icons --- overrides/.icons/logos/docshub.svg | 4 ++++ overrides/.icons/logos/openhosted.svg | 3 +++ overrides/.icons/logos/postline.svg | 3 +++ overrides/.icons/logos/sourcecamp.svg | 3 +++ overrides/.icons/logos/stagelink.svg | 4 ++++ overrides/.icons/logos/starcat-circle.svg | 4 ++++ 6 files changed, 21 insertions(+) create mode 100644 overrides/.icons/logos/docshub.svg create mode 100644 overrides/.icons/logos/openhosted.svg create mode 100644 overrides/.icons/logos/postline.svg create mode 100644 overrides/.icons/logos/sourcecamp.svg create mode 100644 overrides/.icons/logos/stagelink.svg create mode 100644 overrides/.icons/logos/starcat-circle.svg 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 @@ + + + + From 6900f7f43cf02215b2c75572980ac875207a02a5 Mon Sep 17 00:00:00 2001 From: thhsh-local Date: Tue, 20 May 2025 12:42:39 -0400 Subject: [PATCH 4/8] Add info about custom icons to meta --- docs/handbook/meta/.nav.yml | 3 ++- docs/handbook/meta/custom_icons.md | 25 +++++++++++++++++++++++++ 2 files changed, 27 insertions(+), 1 deletion(-) create mode 100644 docs/handbook/meta/custom_icons.md 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 From 633688236305663a4762a4a2de9bce402ae936d2 Mon Sep 17 00:00:00 2001 From: thhsh-local Date: Tue, 20 May 2025 12:43:07 -0400 Subject: [PATCH 5/8] Add custom icons to syntax info --- docs/handbook/meta/syntax.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/handbook/meta/syntax.md b/docs/handbook/meta/syntax.md index 36ab0e9..4450110 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 }` From 5b4a0a884555fc29340a9c6bb9fcfc46ab9851e6 Mon Sep 17 00:00:00 2001 From: thhsh-local Date: Tue, 20 May 2025 12:43:20 -0400 Subject: [PATCH 6/8] Add PostLine and OpenHosted logo attribution --- docs/about/attribution.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/about/attribution.md b/docs/about/attribution.md index b647811..6655495 100644 --- a/docs/about/attribution.md +++ b/docs/about/attribution.md @@ -12,6 +12,8 @@ This site, and all StarCat Systems projects, products, and services make use of - [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 From e305c9a8df061b96664bd8dc5b3fea56d114eb84 Mon Sep 17 00:00:00 2001 From: thhsh-local Date: Tue, 20 May 2025 12:57:15 -0400 Subject: [PATCH 7/8] Add deprecated admonition --- docs/handbook/meta/syntax.md | 15 +++++++++++++++ docs/stylesheets/extra.css | 18 ++++++++++++++++++ 2 files changed, 33 insertions(+) diff --git a/docs/handbook/meta/syntax.md b/docs/handbook/meta/syntax.md index 4450110..6936b38 100644 --- a/docs/handbook/meta/syntax.md +++ b/docs/handbook/meta/syntax.md @@ -96,6 +96,21 @@ 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. + +!!! 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. + ``` + #### 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..8288ea2 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -1,3 +1,21 @@ +: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); +} + .note-blue { color: #448AFF; } From 76755b810c688f8200c7c697955cdcb3e4a9b5f9 Mon Sep 17 00:00:00 2001 From: thhsh-local Date: Tue, 20 May 2025 13:04:57 -0400 Subject: [PATCH 8/8] Add page-moved admonition --- docs/handbook/meta/syntax.md | 15 ++++++++++++++- docs/stylesheets/extra.css | 18 ++++++++++++++++++ 2 files changed, 32 insertions(+), 1 deletion(-) diff --git a/docs/handbook/meta/syntax.md b/docs/handbook/meta/syntax.md index 6936b38..6f2a30c 100644 --- a/docs/handbook/meta/syntax.md +++ b/docs/handbook/meta/syntax.md @@ -97,7 +97,7 @@ Here are some common admonitions, when you might use them, and quick code snippe 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. +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. @@ -111,6 +111,19 @@ For pages that were once accurate, but are either no longer accurate and not bei 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 8288ea2..1868549 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -16,6 +16,24 @@ 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; }