Polish look & feel + rearrange styleguide

astro.config.mjs

@@ -3,10 +3,20 @@ import { defineConfig } from "astro/config";
 import starlight from "@astrojs/starlight";
 import starlightSidebarTopics from "starlight-sidebar-topics";
 import starlightLinksValidator from "starlight-links-validator";
+import remarkDirective from "remark-directive";
+import remarkDoDont from "./src/plugins/remark-do-dont.ts";
+import baseLinksIntegration from "./src/plugins/base-links-integration.ts";
+
+const base = process.env.BASE_PATH;
 
 // https://astro.build/config
 export default defineConfig({
+  base,
+  markdown: {
+    remarkPlugins: [remarkDirective, remarkDoDont],
+  },
   integrations: [
+    ...(base ? [baseLinksIntegration(base)] : []),
     starlight({
       title: "Community@",
       social: [
@@ -16,7 +26,7 @@ export default defineConfig({
           href: "https://github.com/FujoWebDev/community-at",
         },
       ],
-      customCss: ["./src/index.css"],
+      customCss: ["./src/index.css", "./src/styles/do-dont.css"],
       plugins: [
         starlightSidebarTopics([
           {
@@ -61,7 +71,7 @@ export default defineConfig({
             ],
           },
         ]),
-        starlightLinksValidator(),
+        ...(base ? [] : [starlightLinksValidator()]),
       ],
     }),
   ],

package.json

@@ -12,9 +12,11 @@
   "dependencies": {
     "@astrojs/starlight": "^0.36.1",
     "astro": "^5.14.5",
+    "remark-directive": "^4.0.0",
     "sharp": "^0.32.5",
     "starlight-links-validator": "^0.19.2",
-    "starlight-sidebar-topics": "^0.6.2"
+    "starlight-sidebar-topics": "^0.6.2",
+    "unist-util-visit": "^5.1.0"
   },
   "repository": {
     "url": "https://github.com/FujoWebDev/community-at",

src/content/docs/fujowebdev/style-guide/formatting.md

@@ -6,63 +6,98 @@ sidebar:
 
 Our content is designed for *skimmability*: as you write it, imagine you’re only reading bits and pieces of it as you go in search of the sections most relevant to what you’re trying to do.
 
-## **General Formatting**
-
-* Paragraphs:   
-  * Keep them short and focused on a single idea.   
-  * Be generous with them.  
-  * The key idea should be in the first sentence of each paragraph. Follow up sentences provide additional context/information.
-
-* Bold:   
-  * Use bold to highlight the key big idea in an article, or other crucial concepts. For highlights, try to capture a whole idea. For example: “As one of the most popular Version Control Systems, **Git helps you never lose track of changes to your code**, no matter how long it’s been since you last worked on it\!”  
-    * How much of the sentence to highlight is a bit of an art\! As a general rule, highlight the one thing that you’d want the reader to take away from the article after they finish reading it.  
-    * Make sure not to bold too often in a row, as it can get overwhelming and lose effectiveness. If you find yourself with multiple key big ideas, you should consider if they would be better served by being separated into their own article each. This also applies to sections and paragraphs, too.   
-* Italics:  
-  * Group together longer titles without using “” (e.g. These articles are designed as companions to *FujoGuide Issue 1: Local Version Control with Git*, which you can buy…)  
-  * Stress important points in sentences, e.g. pay *very close* attention to the path you give to the `rm` command. Similar to bold, you should not emphasize every other word in a sentence. If there are multiple important points in a single sentence, consider breaking them up into their unique paragraph to better space them out.
-
-* DFN  
-  * Use DFN tag to highlight technical terms that aren’t code commands (e.g. In coding, it’s often useful to use **relative paths** for files and directories).
-
-* Linking:   
-  * Use links generously, and make sure you’re linking descriptive text (not “`click here`” but “`find the official documentation here`”).   
-  * You should link to:  
-    * Relevant articles from elsewhere on `learn.fujoweb.dev`, especially for prerequisites, terms definitions, or deeper knowledge  
-    * Authoritative external sources (e.g. `MDN`, official tool docs)  
-    * If we don’t have a guide, we might try to find a good substitute on the web. However, these links tend to rot.
-
-* Lists:   
-  * Use lists generously, as they help with skimmability.   
-  * You should:  
-    * Use numbered lists for items in sequence (e.g. we’ll learn 1\) how to do A 2\) how to do B…)  
-    * Use bullet point lists for key takeaways or items not in a sequence (like this list\!)  
-    * Use [Steps](https://starlight.astro.build/components/steps/) for sequences of instructions
-
-## **Code Formatting**
-
-* Inline Code: We use inline code to highlight:  
-  * Commands (e.g. `git commit -m “your message”`)  
-  * File names (`index.html`), paths `~/my_site/`, keyboard shortcuts (`ctrl + k`) or tool names (`vim`, `zsh`)  
-* Code blocks: Code blocks are an essential part of our guides, as they help people see how things work *in practice* and help break the flow of the text (and aid in skimmability). You should:  
-  * Make sure to explain what the code does and why it’s there.
-  * Provide both input and output (unless confusing). You can omit part of the output if it helps the user focus on what you want to see. Similarly, you can make some output lighter to de-emphasize it.  
-  * Use the code block captions to call out any particular element of the example you want the user to notice.
-
-## **Other Formatting**
-
-Images: 
-
-* Use images to show non-code results, UIs, or examples of programs in action. You can annotate if needed, but be mindful that it makes them harder to edit later.  
-* If you cannot provide ALT text yourself, let us know: we’ll get someone to write it for you.  
+## General Formatting
+
+1. [Paragraphs](#1-paragraphs)
+2. [Bold](#2-bold)
+3. [Italics](#3-italics)
+4. [Definition tag](#4-definition-tag)
+5. [Linking](#5-linking)
+6. [Lists](#6-lists)
+
+### 1. Paragraphs
+
+* Keep them short and focused on a single idea.
+* Be generous with them.
+* The key idea should be in the first sentence of each paragraph. Follow-up sentences provide additional context/information.
+
+### 2. Bold
+
+Use bold to highlight the key big idea in an article, or other crucial concepts. For highlights, try to capture a whole idea. For example: “As one of the most popular Version Control Systems, **Git helps you never lose track of changes to your code**, no matter how long it’s been since you last worked on it!”
+
+* How much of the sentence to highlight is a bit of an art! As a general rule, highlight the one thing that you’d want the reader to take away from the article after they finish reading it.
+* Make sure not to bold too often in a row, as it can get overwhelming and lose effectiveness. If you find yourself with multiple key big ideas, you should consider if they would be better served by being separated into their own article each. This also applies to sections and paragraphs, too.
+
+### 3. Italics
+
+* Group together longer titles without using “” (e.g. These articles are designed as companions to *FujoGuide Issue 1: Local Version Control with Git*, which you can buy…)
+* Stress important points in sentences, e.g. pay *very close* attention to the path you give to the `rm` command. Similar to bold, you should not emphasize every other word in a sentence. If there are multiple important points in a single sentence, consider breaking them up into their unique paragraph to better space them out.
+
+### 4. Definition tag
+
+Use the [definition tag (`<dfn>`)](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dfn) to highlight technical terms that aren’t code commands (e.g. In coding, it’s often useful to use <dfn>relative paths</dfn> for files and directories). It semantically marks the term being defined in a sentence.
+
+### 5. Linking
+
+Use links generously, and make sure you’re linking descriptive text (not “`click here`” but “`find the official documentation here`”).
+
+You should link to:
+
+* Relevant articles from elsewhere on `learn.fujoweb.dev`, especially for prerequisites, terms definitions, or deeper knowledge
+* Authoritative external sources (e.g. `MDN`, official tool docs)
+* If we don’t have a guide, we might try to find a good substitute on the web. However, these links tend to rot.
+
+### 6. Lists
+
+Use lists generously, as they help with skimmability. You should:
+
+* Use numbered lists for items in sequence (e.g. we’ll learn 1. how to do A 2. how to do B…)
+* Use bullet point lists for key takeaways or items not in a sequence (like this list!)
+* Use [Steps](https://starlight.astro.build/components/steps/) for sequences of instructions
+
+## Code Formatting
+
+1. [Inline Code](#1-inline-code)
+2. [Code blocks](#2-code-blocks)
+
+### 1. Inline Code
+
+We use inline code to highlight:
+
+* Commands (e.g. `git commit -m “your message”`)
+* File names (`index.html`), paths `~/my_site/`, keyboard shortcuts (`ctrl + k`) or tool names (`vim`, `zsh`)
+
+### 2. Code blocks
+
+Code blocks are an essential part of our guides, as they help people see how things work *in practice* and help break the flow of the text (and aid in skimmability). You should:
+
+* Make sure to explain what the code does and why it’s there.
+* Provide both input and output (unless confusing). You can omit part of the output if it helps the user focus on what you want to see. Similarly, you can make some output lighter to de-emphasize it.
+* Use the code block captions to call out any particular element of the example you want the user to notice.
+
+## Other Formatting
+
+1. [Images](#1-images)
+2. [Diagrams](#2-diagrams)
+3. [Tabs](#3-tabs)
+
+### 1. Images
+
+* Use images to show non-code results, UIs, or examples of programs in action. You can annotate if needed, but be mindful that it makes them harder to edit later.
+* If you cannot provide ALT text yourself, let us know: we’ll get someone to write it for you.
 * Use captions to help the reader understand what they’re looking at and what matters about it.
 
-Diagrams:
+### 2. Diagrams
 
-* [We use Excalidraw for diagrams](https://excalidraw.com/).   
+* [We use Excalidraw for diagrams](https://excalidraw.com/).
 * Make sure you download the `.excalidraw` file and not just the PNG.
 
-Tabs: 
+### 3. Tabs
+
+When a command differs across programs or Operating Systems, you can use [Tabs](https://starlight.astro.build/components/tabs/) to provide alternative versions of commands or explanations.
+
+:::tip[More components]
 
-* When a command differs across programs or Operating Systems, you can use [Tabs](https://starlight.astro.build/components/tabs/) to provide alternative versions of commands or explanations.
+We can easily use [all components from Starlight](https://starlight.astro.build/components/steps/). If you think a specific functionality not covered by these would help, you can ask Ms Boba whether it can be provided.
 
-**More components:** we can easily use [all components from Starlight](https://starlight.astro.build/components/steps/). If you think a specific functionality not covered by these would help, you can ask Ms Boba whether it can be provided.
+:::