First draft of the Glossary page

astro.config.mjs

@@ -3,18 +3,32 @@ import starlight from "@astrojs/starlight";
 import starlightThemeFlexoki from "starlight-theme-flexoki";
 import remarkGemoji from "remark-gemoji";
 import rehypeTargetBlank from "./src/plugins/rehype-target-blank.js";
+import remarkGlossaryDirective from "./src/plugins/remark-glossary-directive.js";
+import icon from "astro-icon";
 
 export default defineConfig({
   site: "https://how-to-git.netlify.app/",
   markdown: {
-    remarkPlugins: [remarkGemoji],
+    remarkPlugins: [remarkGemoji, remarkGlossaryDirective],
     rehypePlugins: [rehypeTargetBlank],
   },
   integrations: [
     starlight({
       title: "How To Git",
       description: "A guide to Git",
       plugins: [starlightThemeFlexoki()],
+      sidebar: [
+        {
+          label: "Documentation",
+          autogenerate: { directory: "documentation" },
+        },
+        {
+          label: "Glossary",
+          link: "/glossary",
+        },
+      ],
+      customCss: ["./src/styles/glossary.css"],
     }),
+    icon(),
   ],
 });

src/components/CustomCard.astro

@@ -1,12 +1,12 @@
 ---
 import { Icon } from "@astrojs/starlight/components";
-import { Icon as CustomIcon } from "astro-icon/components/Icon.astro";
+import { Icon as CustomIcon } from "astro-icon/components";
 import type { StarlightIcon } from "@astrojs/starlight/types";
 
 export interface Props {
-  icon?: string | StarlightIcon;
-  title: string;
-  customIcon?: string;
+    icon?: string | StarlightIcon;
+    title: string;
+    customIcon?: string;
 }
 
 const { icon, title, customIcon } = Astro.props;
@@ -15,79 +15,83 @@ const useStarlightCard = icon && !customIcon;
 ---
 
 {
-  useStarlightCard ? (
-    <article class="card sl-flex">
-      <p class="title sl-flex">
-        {icon && (
-          <Icon name={icon as StarlightIcon} class="icon" size="1.333em" />
-        )}
-        <span set:html={title} />
-      </p>
-      <div class="body">
-        <slot />
-      </div>
-    </article>
-  ) : (
-    <article class="card sl-flex">
-      <p class="title sl-flex">
-        {customIcon && (
-          <CustomIcon name={customIcon} size="1.333em" class="icon" />
-        )}
-        <span set:html={title} />
-      </p>
-      <div class="body">
-        <slot />
-      </div>
-    </article>
-  )
+    useStarlightCard ? (
+        <article class="card sl-flex">
+            <p class="title sl-flex">
+                {icon && (
+                    <Icon
+                        name={icon as StarlightIcon}
+                        class="icon"
+                        size="1.333em"
+                    />
+                )}
+                <span set:html={title} />
+            </p>
+            <div class="body">
+                <slot />
+            </div>
+        </article>
+    ) : (
+        <article class="card sl-flex">
+            <p class="title sl-flex">
+                {customIcon && (
+                    <CustomIcon name={customIcon} size="1.333em" class="icon" />
+                )}
+                <span set:html={title} />
+            </p>
+            <div class="body">
+                <slot />
+            </div>
+        </article>
+    )
 }
 
 <style>
-  .card {
-    --sl-card-border: var(--sl-color-purple);
-    --sl-card-bg: var(--sl-color-purple-low);
-    border: 1px solid var(--sl-color-gray-5);
-    background-color: var(--sl-color-black);
-    padding: clamp(1rem, calc(0.125rem + 3vw), 2.5rem);
-    flex-direction: column;
-    gap: clamp(0.5rem, calc(0.125rem + 1vw), 1rem);
-  }
-  .card:nth-child(4n + 1) {
-    --sl-card-border: var(--sl-color-orange);
-    --sl-card-bg: var(--sl-color-orange-low);
-  }
-  .card:nth-child(4n + 3) {
-    --sl-card-border: var(--sl-color-green);
-    --sl-card-bg: var(--sl-color-green-low);
-  }
-  .card:nth-child(4n + 4) {
-    --sl-card-border: var(--sl-color-red);
-    --sl-card-bg: var(--sl-color-red-low);
-  }
-  .card:nth-child(4n + 5) {
-    --sl-card-border: var(--sl-color-blue);
-    --sl-card-bg: var(--sl-color-blue-low);
-  }
-  .title {
-    font-weight: 600;
-    font-size: var(--sl-text-h4);
-    color: var(--sl-color-white);
-    line-height: var(--sl-line-height-headings);
-    gap: 1rem;
-    align-items: center;
-  }
-  .card .icon {
-    border: 1px solid var(--sl-card-border);
-    background-color: var(--sl-card-bg);
-    padding: 0.2em;
-    border-radius: 0.25rem;
-  }
-  .card .body {
-    margin: 0;
-    font-size: clamp(
-      var(--sl-text-sm),
-      calc(0.5rem + 1vw),
-      var(--sl-text-body)
-    );
-  }
+    .card {
+        --sl-card-border: var(--sl-color-purple);
+        --sl-card-bg: var(--sl-color-purple-low);
+        border: 1px solid var(--sl-color-gray-5);
+        background-color: var(--sl-color-black);
+        padding: clamp(1rem, calc(0.125rem + 3vw), 2.5rem);
+        flex-direction: column;
+        gap: clamp(0.5rem, calc(0.125rem + 1vw), 1rem);
+    }
+    .card:nth-child(4n + 1) {
+        --sl-card-border: var(--sl-color-orange);
+        --sl-card-bg: var(--sl-color-orange-low);
+    }
+    .card:nth-child(4n + 3) {
+        --sl-card-border: var(--sl-color-green);
+        --sl-card-bg: var(--sl-color-green-low);
+    }
+    .card:nth-child(4n + 4) {
+        --sl-card-border: var(--sl-color-red);
+        --sl-card-bg: var(--sl-color-red-low);
+    }
+    .card:nth-child(4n + 5) {
+        --sl-card-border: var(--sl-color-blue);
+        --sl-card-bg: var(--sl-color-blue-low);
+    }
+    .title {
+        font-weight: 600;
+        font-size: var(--sl-text-h4);
+        color: var(--sl-color-white);
+        line-height: var(--sl-line-height-headings);
+        gap: 1rem;
+        align-items: center;
+    }
+    .card .icon {
+        border: 1px solid var(--sl-card-border);
+        background-color: var(--sl-card-bg);
+        padding: 0.2em;
+        border-radius: 0.25rem;
+    }
+    .card .body {
+        margin: 0;
+        font-size: clamp(
+            var(--sl-text-sm),
+            calc(0.5rem + 1vw),
+            var(--sl-text-body)
+        );
+    }
 </style>

src/components/GlossaryTerm.astro

@@ -0,0 +1,133 @@
+---
+import { type CollectionEntry, render } from "astro:content";
+
+interface Props {
+    entry: CollectionEntry<"glossary">;
+    backlinks?: Array<{ title: string; path: string }>;
+}
+
+const { entry, backlinks = [] } = Astro.props;
+const { Content } = await render(entry);
+const hasBody = (entry.body?.trim().length ?? 0) > 0;
+const { term, definition, aliases, related } = entry.data;
+---
+
+<div class="term-card">
+    <dt id={entry.id}>{term}</dt>
+    <dd>
+        {
+            aliases.length > 0 && (
+                <p class="aliases">Aliases: {aliases.join(", ")}</p>
+            )
+        }
+
+        <p class="definition">{definition}</p>
+
+        {hasBody && <Content />}
+
+        {
+            related.length > 0 && (
+                <div class="see-also">
+                    <span class="see-also-label">Related:</span>
+                    {related.map((slug) => (
+                        <a href={`#${slug}`}>{slug}</a>
+                    ))}
+                </div>
+            )
+        }
+        {
+            backlinks.length > 0 && (
+                <div class="backlinks">
+                    <span class="backlinks-label">References:</span>
+                    <div class="backlinks-list">
+                        {backlinks.map((link) => (
+                            <a href={link.path}>{link.title}</a>
+                        ))}
+                    </div>
+                </div>
+            )
+        }
+    </dd>
+</div>
+
+<style>
+    dt {
+        font-weight: 600;
+        font-size: var(--sl-text-lg);
+        scroll-margin-top: 4rem;
+    }
+
+    .term-card {
+        border: 1px solid var(--sl-color-gray-5);
+        background-color: var(--sl-color-gray-6);
+        padding: clamp(1rem, calc(0.125rem + 3vw), 2.5rem);
+        display: flex;
+        flex-direction: column;
+        gap: clamp(0.5rem, calc(0.125rem + 1vw), 1rem);
+        margin: 0.5rem 0 1.5rem 0;
+    }
+
+    .aliases {
+        font-size: var(--sl-text-xs);
+        color: var(--sl-color-gray-4);
+        display: inline-block;
+        margin: 0;
+    }
+
+    .definition {
+        color: var(--sl-color-gray-2);
+        margin: 0;
+    }
+
+    .see-also {
+        display: flex;
+        flex-wrap: wrap;
+        align-items: baseline;
+        gap: 0.5rem;
+        font-size: var(--sl-text-sm);
+        margin: 0;
+    }
+
+    .see-also-label {
+        color: var(--sl-color-gray-3);
+    }
+
+    .see-also a {
+        color: var(--sl-color-accent);
+        background-color: var(--sl-color-gray-5);
+        padding: 0.25rem 0.625rem;
+        border-radius: 0.25rem;
+        text-decoration: none;
+    }
+
+    .see-also a:hover {
+        background-color: var(--sl-color-gray-4);
+    }
+
+    .backlinks {
+        font-size: var(--sl-text-sm);
+        margin: 0;
+    }
+
+    .backlinks-label {
+        display: block;
+        color: var(--sl-color-gray-3);
+        margin-bottom: 0.25rem;
+    }
+
+    .backlinks-list {
+        display: flex;
+        flex-direction: column;
+        gap: 0.25rem;
+    }
+
+    .backlinks a {
+        color: var(--sl-color-accent);
+        text-decoration: none;
+        padding: 0.125rem 0;
+    }
+
+    .backlinks a:hover {
+        text-decoration: underline;
+    }
+</style>

src/content.config.ts

@@ -1,7 +1,22 @@
-import { defineCollection } from 'astro:content';
-import { docsLoader } from '@astrojs/starlight/loaders';
-import { docsSchema } from '@astrojs/starlight/schema';
+import { defineCollection, z } from "astro:content";
+import { docsLoader } from "@astrojs/starlight/loaders";
+import { docsSchema } from "@astrojs/starlight/schema";
+import { glob } from "astro/loaders";
+
+const glossarySchema = z.object({
+  term: z.string(),
+  definition: z.string(),
+  aliases: z.array(z.string()).default([]),
+  related: z.array(z.string()).default([]),
+});
 
 export const collections = {
   docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
-};
+  glossary: defineCollection({
+    loader: glob({
+      base: "./src/content/glossary",
+      pattern: "**/*.{md,mdx}",
+    }),
+    schema: glossarySchema,
+  }),
+};

src/content/docs/01-repository.mdx → src/content/docs/documentation/01-repository.mdx

@@ -9,7 +9,7 @@ import { Steps } from "@astrojs/starlight/components";
 
 ### What is a Git repository?
 
-A Git repository is a folder that contains all the files and folders related to a project.
+A Git :term[repository] is a folder that contains all the files and folders related to a project.
 Beyond that, it also contains the history of all changes made to them.
 Further in the tutorial, we will learn how to use Git to manage a repository: track changes, work on different topics in parallel, and collaborate with others, and more.
 

src/content/docs/02-track-changes.mdx → src/content/docs/documentation/02-track-changes.mdx

@@ -39,7 +39,7 @@ Clicking on it will open a dialogue window with different fields to fill:
 
 - **Commit message**: Give a name to your changes - later you will be able to search for them.
 - **Extended description**: If needed, give more detailed information.
-- Commit directly to the *any name* branch: For now choose this.
+- Commit directly to the *any name* :term[branch]: For now choose this.
 - Create a **new branch** for this commit and start a pull request: Branching out will be described further [down](#branching-out-topics).
 - Agree by committing your changes again.
 

src/content/docs/04-parallel-topics.mdx → src/content/docs/documentation/04-parallel-topics.mdx

@@ -11,8 +11,8 @@ import { Steps } from "@astrojs/starlight/components";
 
 Often, you will want to work on different topics in parallel and keep them separate from the main codebase.
 Those include the development of new features, bug fixes, or experiments.
-Git is offering the possibility for branching out.
-This is like working on isolated copies of your files, try out new things until everything works: in Git, this is called a branch.
+Git is offering the possibility of branching out.
+This is like working on isolated copies of your files, try out new things until everything works: in Git's terminology, this is called a :term[branch].
 Once you are satisfied with the changes, you can merge them back into the default branch, where the latest changes of the projects are reflected.
 Usually, the default branch is called `main`; in the past it was often called `master`.
 When you want to work on a new feature or fix a bug, you create a new branch from the `main` branch.