Merge pull request #268 from pyladies/docs-categories

Enable grouping/sections in the documentation

Author: egeakman

astro.config.mjs

@@ -48,4 +48,14 @@ export default defineConfig({
     extendDefaultPlugins: true,
     highlighter: getHighlighter,
   },
+  redirects: {
+    "/docs/committee_communications": "/docs/volunteers/committee_communications",
+    "/docs/committee_design": "/docs/volunteers/committee_design",
+    "/docs/committee_finance": "/docs/volunteers/committee_finance",
+    "/docs/committee_infra": "/docs/volunteers/committee_infra",
+    "/docs/committee_program": "/docs/volunteers/committee_program",
+    "/docs/committee_volunteers": "/docs/volunteers/committee_volunteers",
+    "/docs/roles_and_responsibilities": "/docs/volunteers/roles_and_responsibilities",
+    "/docs/speaker_guide": "/docs/speakers/speaker_guide",
+  }
 });

src/content.config.ts

@@ -60,7 +60,9 @@ const docsCollection = defineCollection({
     image: z.string().optional(),
     layout: z.string().optional(),
     draft: z.boolean().optional(),
+    section: z.string().optional(),
     weight: z.number().optional(),
+    url: z.string().url().optional(), // only for external links
   }),
 });
 

src/content/README.md

@@ -0,0 +1,4 @@
+<!--
+  Adding empty file to prevent GitHub showing src/content/docs/README.md 
+  Please add content to this file as needed.
+-->

src/content/docs/README.md

@@ -0,0 +1,99 @@
+---
+draft: true
+title: "Documentation Inception"
+---
+
+# Documentation
+
+This directory contains all documentation organized into sections.
+
+## Structure
+
+- **`volunteers/`** - Guides for conference volunteers and committee members
+- **`speakers/`** - Information and guides for speakers
+- **`resources/`** - External resources and helpful links
+
+## Adding a New Doc
+
+Create a markdown file in the appropriate subfolder:
+
+```bash
+# For volunteer guides
+src/content/docs/volunteers/your-guide.md
+
+# For speaker guides
+src/content/docs/speakers/your-guide.md
+
+# For other resources
+src/content/docs/resources/your-resource.md
+```
+
+## Frontmatter
+
+Basic frontmatter structure:
+
+```yaml
+---
+title: "Your Doc Title"
+description: "Brief description"
+section: "volunteers"  # optional - inferred from folder if not specified
+weight: 1              # optional - controls ordering within section
+---
+```
+
+## External Resources
+
+To link to an external resource instead of creating a doc page:
+
+```yaml
+---
+title: "Astro Framework"
+description: "Learn about Astro"
+section: "resources"
+url: "https://astro.build"  # opens in new tab with icon
+---
+```
+
+## Section Ordering
+
+Sections appear in this order:
+
+1. Speakers
+2. Volunteers
+3. Resources
+4. Any other sections (alphabetically)
+
+Within each section, docs are sorted by `weight` (lower numbers first).
+
+## Creating a New Section
+
+You can add new sections by simply creating a new folder:
+
+```bash
+src/content/docs/sponsors/sponsor-info.md
+```
+
+This will automatically create a "Sponsors" section. The section name is inferred from the folder name and humanized (e.g., `my-section` becomes "My Section").
+
+### Customizing Section Labels and Order
+
+To customize section display names and ordering, edit `src/lib/utils/docsHelpers.ts`:
+
+**1. Add a custom label:**
+
+```typescript
+const SECTION_LABELS: Record<string, string> = {
+  volunteers: "Volunteer Guides",
+  speakers: "Speaker Guides",
+  resources: "Resources",
+  sponsors: "Sponsor Information",  // add your new section here
+};
+```
+
+**2. Add to the ordering:**
+
+```typescript
+const SECTION_ORDER = ["speakers", "volunteers", "resources", "sponsors"] as const;
+```
+
+Sections not in `SECTION_ORDER` will appear after the ordered ones, sorted alphabetically.

src/content/docs/resources/astro.md

@@ -0,0 +1,11 @@
+---
+title: "Astro"
+meta_title: "Astro Framework"
+description: "The framework for this website, in case you want to contribute to it."
+draft: false
+section: "resources"
+weight: 1
+url: "https://astro.build"
+---
+
+Astro is the web framework used to build this PyLadiesCon website. If you're interested in contributing to the website, learning Astro will help you understand how the site is structured and how to make improvements. Visit the [Astro Documentation](https://docs.astro.build) to get started with Astro!

src/content/docs/speaker_guide.md renamed to src/content/docs/speakers/speaker_guide.md

@@ -4,6 +4,7 @@ meta_title: "Speaker Guide"
 description: "Guide and Resources for Speakers"
 draft: false
 weight: 1
+section: "speakers"
 ---
 
 

src/content/docs/committee_communications.md renamed to src/content/docs/volunteers/committee_communications.md

@@ -4,6 +4,7 @@ meta_title: "Communications Committee"
 description: "Team in charge of all the internal and external communications"
 draft: false
 weight: 5
+section: "volunteers"
 ---
 
 ## Roles

src/content/docs/committee_design.md renamed to src/content/docs/volunteers/committee_design.md

@@ -4,6 +4,7 @@ meta_title: "Design Committee"
 description: "Team in charge of the creation of all the conference assets"
 draft: false
 weight: 6
+section: "volunteers"
 ---
 
 ## Roles

src/content/docs/committee_finance.md renamed to src/content/docs/volunteers/committee_finance.md

@@ -4,6 +4,7 @@ meta_title: "Finance and Sponsorship Committee"
 description: "Team in charge of the budget and sponsorship of the confenrence"
 draft: false
 weight: 3
+section: "volunteers"
 ---
 
 

src/content/docs/committee_infra.md renamed to src/content/docs/volunteers/committee_infra.md

@@ -5,6 +5,7 @@ description: "Team in charge of the infra in the conference including website,
 bots, ticketing system, streaming, etc."
 draft: false
 weight: 4
+section: "volunteers"
 ---
 
 ## Roles