mirror of
https://github.com/frappe/gunicorn.git
synced 2026-07-03 03:01:31 +08:00
36 lines
2.6 KiB
Markdown
36 lines
2.6 KiB
Markdown
# Website Modernization Plan
|
||
|
||
## Goals
|
||
- Serve a single, canonical domain backed by a static MkDocs build.
|
||
- Keep the documentation authoring experience entirely in Markdown.
|
||
- Modernize the marketing home page with a refreshed visual identity.
|
||
- Preserve the generated settings reference sourced from Python code.
|
||
|
||
## Architecture Overview
|
||
- **Static site generator:** MkDocs with the Material theme.
|
||
- **Content layout:** Markdown files in `docs/content/`, grouped by guides, reference, and news archives.
|
||
- **Styling:** Lightweight CSS overrides in `docs/content/styles/overrides.css` for hero, feature cards, and color palette.
|
||
- **Dynamic data:** `docs/macros.py` exposes the Gunicorn version, while `scripts/build_settings_doc.py` renders the settings reference into Markdown during every build.
|
||
- **Assets:** SVG mascot and hero art live under `docs/content/assets/` so both the homepage and docs share the same branding.
|
||
|
||
## Completed Work
|
||
- Removed Sphinx configuration, themes, and the legacy static snapshot under `docs/site/`.
|
||
- Converted the entire content library (guides, FAQ, design notes, yearly news) from MyST/RST to MkDocs-friendly Markdown.
|
||
- Rebuilt the homepage using Material’s layout primitives with responsive hero, CTAs, and feature cards.
|
||
- Added CSS overrides that mirror Gunicorn’s brand colors and support light/dark modes.
|
||
- Replaced the Sphinx extension with a standalone Markdown generator for the settings reference.
|
||
- Introduced an automated MkDocs workflow (`.github/workflows/docs.yml`) that builds on every push and deploys to `gh-pages` from the `main` branch.
|
||
|
||
## Remaining Enhancements
|
||
1. **Visual polish:** produce updated screenshots/asciicasts for quickstart and deployment examples; add Open Graph imagery.
|
||
2. **Content review:** prune outdated news entries, tighten FAQs, and add framework-specific quickstarts (FastAPI, Flask, Django).
|
||
3. **Accessibility & internationalization:** run axe audits, ensure color contrast, and consider adding minimal localization support.
|
||
4. **Performance extras:** enable MkDocs search index minification and gzip the GitHub Pages output (served automatically once deployed).
|
||
5. **Contributor docs:** extend `CONTRIBUTING.md` with MkDocs authoring tips, link to preview artifacts, and describe the `mkdocs serve` workflow.
|
||
|
||
## Deployment Checklist
|
||
- [x] Update DNS to point away from ReadTheDocs once `gh-pages` is published.
|
||
- [x] Verify `site_url` in `mkdocs.yml` for canonical URLs and sitemap generation.
|
||
- [x] Ensure `CNAME` (if required) is checked into `gh-pages` during deployment.
|
||
- [ ] Announce the migration to end-users and update links in READMEs and PyPI metadata.
|