Skip to content

Commit 3ab38d4

Browse files
dhuzarddhuzard
committed
Add MkDocs configuration and comprehensive documentation for the Open BeatBox project
1 parent 643e2e5 commit 3ab38d4

12 files changed

Lines changed: 288 additions & 0 deletions

File tree

‎.github/workflows/mkdocs.yml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: Deploy MkDocs site
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- "docs/**"
8+
- "mkdocs.yml"
9+
- ".github/workflows/mkdocs.yml"
10+
workflow_dispatch:
11+
12+
permissions:
13+
contents: write
14+
15+
jobs:
16+
build-deploy:
17+
runs-on: ubuntu-latest
18+
steps:
19+
- name: Checkout
20+
uses: actions/checkout@v4
21+
with:
22+
fetch-depth: 0
23+
24+
- name: Set up Python
25+
uses: actions/setup-python@v5
26+
with:
27+
python-version: "3.x"
28+
29+
- name: Install MkDocs
30+
run: |
31+
python -m pip install --upgrade pip
32+
pip install mkdocs mkdocs-material
33+
34+
- name: Build docs
35+
run: mkdocs build --strict
36+
37+
- name: Deploy to gh-pages
38+
uses: peaceiris/actions-gh-pages@v4
39+
with:
40+
github_token: ${{ secrets.GITHUB_TOKEN }}
41+
publish_dir: ./site
42+
publish_branch: gh-pages

‎docs/architecture.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Architecture
2+
3+
## Overview
4+
- Next.js 15 App Router project that renders all pages from Markdown in `content/`.
5+
- Frontmatter drives layout, hero blocks, navigation, and metadata; bodies render via `react-markdown` with safe HTML enabled through sanitization.
6+
- Content loading, navigation, and metadata derivation live in `src/lib/content.ts` with helper utilities in `src/lib/utils.ts`.
7+
8+
## Key directories
9+
- `content/` — Markdown for pages and blog posts (`content/blog/`). `_site.md` stores global metadata (title, description, authors, default OG/Twitter assets).
10+
- `src/app/` — App Router routes, layout, sitemap/robots, loading and not-found states, API routes (including `api/send-email`).
11+
- `src/components/` — Reusable UI blocks for hero sections, content sections, navigation, and layout.
12+
- `src/lib/` — Content parsing, icon registry, utilities (text truncation, formatting).
13+
- `public/` — Static assets (images, icons).
14+
- `styles/` — Tailwind layer config plus scoped component CSS for glass/hero styling.
15+
16+
## Content pipeline
17+
1. Markdown is parsed with `gray-matter` for frontmatter and content body.
18+
2. Slugs default to the relative path (with `/home` mapped to `/`) unless explicitly set.
19+
3. Navigation is derived from pages with `showInNav` and ordered by `navOrder`; groups use `navGroup`.
20+
4. Blog posts respect `publishAt`; future-dated posts stay hidden.
21+
5. SEO metadata is built from page fields with fallbacks from `_site.md` (title, description, OG/Twitter defaults). Hero background images or the first Markdown image are used as OG images when available.
22+
23+
## Rendering and styling
24+
- Markdown renders through `react-markdown` with `remark-gfm` and sanitized raw HTML via `rehype-raw` + `rehype-sanitize`.
25+
- Tailwind CSS v4 (via `@tailwindcss/postcss`) provides utility layers; component-specific CSS refines the glass aesthetic.
26+
- Fonts are loaded through `src/app/fonts.css`; global styles in `src/app/globals.css`.
27+
28+
## API and integrations
29+
- Contact form posts to `/api/send-email`, sanitizes inputs, and forwards through Mailgun. Configure `MAILGUN_API_KEY`, `MAILGUN_DOMAIN`, `MAILGUN_API_URL`, `MAILGUN_FROM_EMAIL`, and `MAILGUN_TO_EMAIL`.
30+
- Optional Google reCAPTCHA: set `NEXT_PUBLIC_RECAPTCHA_SITE_KEY` and wire the client component.
31+
32+
## Build and output
33+
- `npm run build` produces the production bundle under `.next/`.
34+
- `mkdocs build` (for this wiki) outputs to `site/` when needed; keep it untracked or publish via a docs-specific pipeline.

‎docs/assets/.gitkeep‎

Whitespace-only changes.

‎docs/changelog.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Changelog
2+
3+
Use this page to capture notable changes for each release. Keep entries concise and link to pull requests or issues when useful.
4+
5+
## Unreleased
6+
- Add new entries here as work lands.
7+
8+
## Template
9+
- **Date / Version** — short description of the change.
10+
- Highlights: bullets of key updates.
11+
- Links: PRs/issues (e.g., #123).

‎docs/content-style.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Content Style Guide
2+
3+
## Voice and tone
4+
- Clear, concise, and confident; favor active voice.
5+
- Assume readers are technically capable but new to the project.
6+
- Define domain terms on first use; avoid unexplained acronyms.
7+
8+
## Formatting
9+
- One H1 per page; use logical heading hierarchy.
10+
- Prefer short paragraphs and bullet lists.
11+
- Use fenced code blocks with language hints (` ```bash `, ` ```ts `).
12+
- Always include alt text for images; store assets in `docs/assets/` or `public/` as appropriate.
13+
14+
## Links and navigation
15+
- Use relative links between wiki pages (e.g., `[Development](development.md)`).
16+
- Keep link text descriptive (`Preview locally` instead of `click here`).
17+
- Update `mkdocs.yml` when adding new pages so navigation stays current.
18+
19+
## Examples
20+
- Good: “Run `npm run build` before merging to catch integration issues.”
21+
- Avoid: “Just run the build” (vague) or “obviously” (assumes knowledge).
22+
23+
## Writing for the site content
24+
- Keep hero titles punchy; subtitles should clarify value.
25+
- Section titles should summarize the takeaway (“Why Beatbox for home-cage tasks?”).
26+
- For FAQs, answer directly in the first sentence, then add detail if needed.

‎docs/contributing.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Contributing
2+
3+
## Code of conduct
4+
Be respectful and constructive. Assume good intent, and surface concerns with empathy. Escalate harmful behavior to maintainers.
5+
6+
## Ways to contribute
7+
- File issues with clear steps, expected vs. actual behavior, and screenshots when helpful.
8+
- Improve content structure and copy in `content/`.
9+
- Extend components or styling to support new section types.
10+
- Enhance documentation and runbooks in `docs/`.
11+
12+
## Pull request checklist
13+
- [ ] Branch created from `main`
14+
- [ ] `npm run lint`, `npm run type-check`, `npm run test`, and `npm run build` pass
15+
- [ ] For docs: `mkdocs build --strict` passes
16+
- [ ] Links and assets verified; navigation updated if needed
17+
- [ ] PR description explains what/why, testing performed, and screenshots for UI changes
18+
19+
## Reviews and approvals
20+
- Seek at least one maintainer review for non-trivial changes.
21+
- Address feedback with follow-up commits (avoid force-push when possible to keep context).
22+
- Re-run validations after major updates.
23+
24+
## Filing issues
25+
- Use a descriptive title.
26+
- Include environment info (OS, browser, Node.js version).
27+
- Provide reproduction steps or sample content snippets that trigger the issue.

‎docs/development.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Development
2+
3+
## Branching and flow
4+
- Create topic branches from `main` (e.g., `feature/<topic>` or `dax/<topic>`).
5+
- Keep commits small and purposeful; write present-tense messages (`Add community docs`).
6+
- Open pull requests early for feedback; request at least one review before merging.
7+
8+
## Core commands
9+
- Dev server: `npm run dev`
10+
- Lint: `npm run lint`
11+
- Types: `npm run type-check`
12+
- Tests: `npm run test`
13+
- Build: `npm run build`
14+
- Docs preview: `mkdocs serve`
15+
16+
## Content workflow
17+
1. Add or edit Markdown in `content/`.
18+
2. Ensure frontmatter includes `layout`, `slug`, `hero`, `sections`, and navigation fields when needed.
19+
3. For blog posts, confirm `publishAt` is set and in the past if you want it live.
20+
4. Check SEO: hero images, metadata in `content/_site.md`, and page-level overrides as needed.
21+
5. Run `npm run dev` to visually verify sections render correctly.
22+
23+
## Quality gates
24+
- `npm run lint` and `npm run type-check` must pass.
25+
- `npm run build` before merging larger changes to catch integration issues.
26+
- `mkdocs build --strict` before publishing wiki updates to avoid broken links.
27+
- Add screenshots or diagrams to `docs/assets/` when useful and reference them with relative paths.
28+
29+
## Security and data handling
30+
- The contact endpoint sanitizes fields, but keep payloads minimal and avoid collecting sensitive data unnecessarily.
31+
- Do not commit secrets; use `.env.local` for local development and platform-specific secret storage in deployment environments.

‎docs/faq.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# FAQ
2+
3+
- **How do I preview the site locally?** Run `npm run dev` and open http://localhost:3000.
4+
- **Where do docs live?** Project wiki files are in `docs/`; site content lives in `content/`.
5+
- **How do I add a nav item?** Set `showInNav: true` and `navOrder` in the page’s frontmatter; update `mkdocs.yml` for wiki nav.
6+
- **Why is my blog post hidden?** Future-dated posts (via `publishAt`) are suppressed until their date.
7+
- **Where do images go?** Site assets in `public/`; wiki images in `docs/assets/`.
8+
- **How do I run the wiki locally?** Install MkDocs + Material (`pip install mkdocs mkdocs-material`), then `mkdocs serve`.

‎docs/getting-started.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Getting Started
2+
3+
## Prerequisites
4+
- Node.js 18+ and npm.
5+
- Git for version control.
6+
- Optional: Python 3.10+ and `pip install mkdocs mkdocs-material` if you want to preview this wiki locally.
7+
8+
## Install the project
9+
```bash
10+
git clone https://github.com/Open-BeatBox/Open-BeatBox.github.io.git
11+
cd Open-BeatBox.github.io
12+
npm install
13+
```
14+
15+
## Run locally
16+
```bash
17+
npm run dev
18+
# Open http://localhost:3000
19+
```
20+
21+
## Validate before pushing
22+
- Lint: `npm run lint`
23+
- Type check: `npm run type-check`
24+
- Tests: `npm run test`
25+
- Build: `npm run build`
26+
- Docs preview: `mkdocs serve` (from repo root)
27+
28+
## Adding content
29+
1. Duplicate an existing Markdown file in `content/` (or create one).
30+
2. Set frontmatter: `title`, `layout` (e.g., `page` or `blog`), `slug`, `hero`, `sections`, and navigation fields (`showInNav`, `navOrder`).
31+
3. For blog posts, place files in `content/blog/` with `layout: "blog"` and `publishAt`. Future-dated posts stay hidden until their date.
32+
4. Run `npm run dev` to preview changes. Navigation derives from `showInNav` and `navOrder`.

‎docs/index.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Open BeatBox Wiki
2+
3+
Welcome to the project wiki for the Beatbox content-driven Next.js site. This space centralizes onboarding, development workflow, architecture notes, and operations runbooks so contributors can move quickly and safely.
4+
5+
## Quick links
6+
- Start coding: [Getting Started](getting-started.md)
7+
- How we build and ship: [Development](development.md)
8+
- Voice, tone, and formatting: [Content Style](content-style.md)
9+
- System overview: [Architecture](architecture.md)
10+
- Contribute changes: [Contributing](contributing.md)
11+
- Runbooks and deployments: [Operations](operations.md)
12+
13+
## What this repo is
14+
- A Next.js 15 App Router site where all page structure and copy live in `content/` Markdown.
15+
- Components render sections like hero blocks, text, lists, FAQs, and links from frontmatter-driven content.
16+
- A contact API route relays sanitized form submissions to Mailgun (see environment variables in [Operations](operations.md)).

0 commit comments

Comments
 (0)