Transform README content into structured VitePress documentation

- Restructured homepage with clear category overview - Created comprehensive Site Generators page with detailed tool descriptions - Built API Documentation page covering tools, testing, and best practices - Added Quality Assurance page with linting, testing, and accessibility tools - Updated navigation with organized tool categories and resources - Enhanced sidebar with logical content grouping - Transformed flat README list into searchable, navigable documentation New structure: - Core Tools: Site Generators, API Documentation - Content & Quality: Writing Tools, Quality Assurance - Resources: Style Guides, Reading List, GitHub Actions - Getting Started: Introduction, Installation All content now properly categorized and easily discoverable through navigation and search.
2026-07-16 14:31:25 -05:00 · 2025-11-01 10:19:55 +01:00
parent 402861943d
commit edbcb85587
5 changed files with 314 additions and 90 deletions
--- a/docs/.vitepress/config.mjs
+++ b/docs/.vitepress/config.mjs
@@ -30,8 +30,22 @@ export default defineConfig({
    },
    nav: [
      { text: 'Home', link: '/' },
-      { text: 'Guide', link: '/guide' },
-      { text: 'API', link: '/api' }
+      { text: 'Tools', 
+        items: [
+          { text: 'Site Generators', link: '/generators' },
+          { text: 'API Documentation', link: '/api' },
+          { text: 'Quality Assurance', link: '/quality' },
+          { text: 'Writing Tools', link: '/writing' }
+        ]
+      },
+      { text: 'Resources',
+        items: [
+          { text: 'Style Guides', link: '/style-guides' },
+          { text: 'Reading List', link: '/reading' },
+          { text: 'GitHub Actions', link: '/github-actions' }
+        ]
+      },
+      { text: 'Guide', link: '/guide' }
    ],
    sidebar: [
      {
@@ -42,9 +56,25 @@ export default defineConfig({
        ]
      },
      {
-        text: 'Reference',
+        text: 'Core Tools',
        items: [
-          { text: 'API Reference', link: '/api' }
+          { text: 'Site Generators', link: '/generators' },
+          { text: 'API Documentation', link: '/api' }
+        ]
+      },
+      {
+        text: 'Content & Quality',
+        items: [
+          { text: 'Writing Tools', link: '/writing' },
+          { text: 'Quality Assurance', link: '/quality' }
+        ]
+      },
+      {
+        text: 'Resources',
+        items: [
+          { text: 'Style Guides', link: '/style-guides' },
+          { text: 'Reading List', link: '/reading' },
+          { text: 'GitHub Actions', link: '/github-actions' }
        ]
      }
    ],
--- a/docs/api.md
+++ b/docs/api.md
@@ -1,81 +1,50 @@
-# API Reference
+# API Documentation

-This page contains the API reference for our documentation system.
+Tools and resources for creating, testing, and maintaining API documentation.

-## Configuration
+## Documentation Generators

-### Basic Configuration
+### Interactive Documentation
+- [Swagger](https://swagger.io/) - Industry standard for API documentation
+- [ReDoc](https://redocly.github.io/redoc/) - Beautiful API documentation from OpenAPI
+- [RapiDoc](https://mrin9.github.io/RapiDoc/index.html) - Custom element for OpenAPI docs
+- [Bump.sh](https://bump.sh/) - API documentation platform with automated updates

-The basic configuration includes:
+### API Design Tools
+- [Stoplight Studio](https://stoplight.io/studio/) - Visual API design editor
+- [Postman](https://www.getpostman.com/) - API development environment
+- [Hoppscotch](https://github.com/hoppscotch/hoppscotch) - Open source API development

- **Title**: Set the main title of your documentation
- **Description**: Provide a brief description
- **Theme**: Configure the appearance and behavior
+## Testing & Validation

-### Advanced Configuration
+### Linting & Quality
+- [Spectral](https://stoplight.io/open-source/spectral/) - JSON/YAML linter with OpenAPI rules
+- [OpenAPI 3 CLI](https://github.com/Redocly/openapi-cli) - Command line tools for OpenAPI
+- [Speccy](https://github.com/wework/speccy) - OpenAPI specification linter

-For advanced users, you can customize:
+### API Testing
+- [Optic](https://www.useoptic.com/) - API change detection and testing
+- [Restish](https://rest.sh/#/) - CLI for interacting with REST APIs

- **Navigation**: Custom navigation menus
- **Sidebar**: Dynamic sidebar generation
- **Search**: Local search configuration
- **Plugins**: Additional functionality
+## Best Practices

-## Methods
+### Structure Your API Docs
+1. **Overview** - What does your API do?
+2. **Authentication** - How to authenticate requests
+3. **Endpoints** - Available endpoints with examples
+4. **Data Models** - Request/response schemas
+5. **Error Handling** - Error codes and messages

-### `configure(options)`
+### Tips for Better Documentation
+- Use real examples in your API documentation
+- Include interactive testing capabilities
+- Document error scenarios thoroughly
+- Provide code samples in multiple languages
+- Keep documentation in sync with API changes

-Configure the documentation system with the provided options.
+## Guidelines & Resources

-**Parameters:**
- `options` (Object): Configuration options
-  - `title` (String): Documentation title
-  - `description` (String): Site description
-  - `theme` (Object): Theme configuration
-
-**Example:**
-```javascript
-configure({
-  title: 'My Docs',
-  description: 'Comprehensive documentation',
-  theme: {
-    nav: [...],
-    sidebar: [...]
-  }
-})
-```
-
-### `search(query)`
-
-Perform a search across all documentation content.
-
-**Parameters:**
- `query` (String): Search query string
-
-**Returns:**
- Array of search results with matches
-
-## Examples
-
-Here are some common usage examples:
-
-### Setting up Navigation
-
-```javascript
-nav: [
-  { text: 'Home', link: '/' },
-  { text: 'Guide', link: '/guide' },
-  { text: 'API', link: '/api' }
-]
-```
-
-### Configuring Search
-
-```javascript
-search: {
-  provider: 'local',
-  options: {
-    // Search configuration
-  }
-}
-```
+- [API Guidelines](https://dret.github.io/guidelines/) - Collection of API design guidelines
+- [Zalando RESTful API Guidelines](https://opensource.zalando.com/restful-api-guidelines/#) - Comprehensive REST API guidelines
+- [API Handyman](https://apihandyman.io/) - API design and documentation blog
+- [Tips for better documentation with OpenAPI](https://lornajane.net/posts/2023/tips-for-better-documentation-with-openapi)
--- a/docs/generators.md
+++ b/docs/generators.md
@@ -0,0 +1,128 @@
+# Site Generators
+
+Static site generators specifically designed for documentation, offering features like themes, plugins, and optimized workflows for technical content.
+
+## Popular Documentation Generators
+
+### VitePress
+- **Website**: [vitepress.dev](https://vitepress.dev/)
+- **Description**: Vue-powered static site generator, fast and modern
+- **Best for**: Vue.js projects, modern documentation sites
+
+### Docusaurus
+- **Website**: [docusaurus.io](https://docusaurus.io/)
+- **Description**: React-based documentation platform by Meta
+- **Best for**: React projects, large documentation sites
+
+### MkDocs
+- **Website**: [mkdocs.org](https://www.mkdocs.org/)
+- **Description**: Python-based static site generator
+- **Best for**: Python projects, simple setup
+
+### GitBook
+- **Website**: [gitbook.com](https://www.gitbook.com/)
+- **Description**: Modern documentation platform with collaborative features
+- **Best for**: Team collaboration, internal documentation
+
+## Framework-Specific Generators
+
+### Astro
+- **Website**: [astro.build](https://astro.build/)
+- **Extensions**: [Starlight](https://starlight.astro.build/) - Documentation theme
+- **Best for**: Performance-focused sites, multi-framework support
+
+### Next.js
+- **Website**: [nextra.site](https://nextra.site/)
+- **Description**: Simple, powerful and flexible site generation framework
+- **Best for**: React/Next.js projects
+
+### Nuxt.js
+- **Website**: [docus.dev](https://docus.dev/)
+- **Description**: Write docs with MDX and deploy with Nuxt
+- **Best for**: Vue/Nuxt projects
+
+## Language-Specific Generators
+
+### Rust
+- **Tool**: [mdBook](https://github.com/rust-lang/mdBook)
+- **Description**: Command line tool to create books with Markdown files
+- **Best for**: Rust projects, book-style documentation
+
+### .NET
+- **Tool**: [DocFX](https://dotnet.github.io/docfx/)
+- **Description**: Static documentation generator for .NET
+- **Best for**: .NET projects, API documentation
+
+### Python
+- **Tool**: [Sphinx](https://www.sphinx-doc.org/en/master/)
+- **Description**: Documentation generator with powerful extensions
+- **Best for**: Python projects, complex documentation
+
+## Lightweight & Simple
+
+### Docsify
+- **Website**: [docsify.js.org](https://docsify.js.org/)
+- **Description**: Magical documentation site generator without build process
+- **Best for**: Simple sites, no build step required
+
+### 11ty
+- **Website**: [11ty.dev](https://www.11ty.dev/)
+- **Description**: Simple static site generator with multiple template languages
+- **Best for**: Flexibility, custom designs
+
+### Zola
+- **Website**: [getzola.org](https://www.getzola.org/)
+- **Description**: Fast static site generator written in Rust
+- **Best for**: Performance, simplicity
+
+## Specialized Solutions
+
+### Antora
+- **Website**: [antora.org](https://antora.org/)
+- **Description**: Multi-repository documentation site generator
+- **Best for**: Large organizations, multiple repositories
+
+### Quartz
+- **Website**: [quartz.jzhao.xyz](https://quartz.jzhao.xyz/)
+- **Description**: Transform your Obsidian vault into a website
+- **Best for**: Knowledge management, Obsidian users
+
+### Log4brains
+- **Website**: [log4brains.org](https://log4brains.org/)
+- **Description**: Documentation of architecture decision records (ADRs)
+- **Best for**: Architecture decisions, ADR documentation
+
+## Extensions & Themes
+
+### Docsify Extensions
+- [docsify-themeable](https://jhildenbiddle.github.io/docsify-themeable/#/) - Themeable extension
+
+### MkDocs Extensions
+- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) - Material Design theme
+- [Tooltipster Links Plugin](https://github.com/midnightprioriem/mkdocs-tooltipster-links-plugin) - Enhanced tooltips
+
+### Sphinx Extensions
+- [MyST](https://myst-parser.readthedocs.io/en/latest/using/intro.html) - Markdown parser
+- [sphinx-design](https://sphinx-design.readthedocs.io/en/latest/) - UI components
+- [Furo](https://github.com/pradyunsg/furo) - Clean theme
+
+## Search Solutions
+- [Meilisearch](https://www.meilisearch.com/) - Fast, typo-tolerant search
+- [pagefind](https://pagefind.app/) - Static search for static sites
+- [Typesense](https://typesense.org/) - Open source search engine
+
+## Choosing the Right Generator
+
+### Consider These Factors:
+1. **Team Skills** - What languages/frameworks does your team know?
+2. **Project Size** - Single repo vs. multi-repo documentation?
+3. **Customization** - How much design flexibility do you need?
+4. **Performance** - How fast does the site need to be?
+5. **Maintenance** - How much ongoing maintenance can you handle?
+
+### Quick Recommendations:
+- **New to docs**: Start with Docusaurus or VitePress
+- **Python team**: Use MkDocs or Sphinx
+- **Performance focus**: Try Astro or Zola
+- **Simple needs**: Consider Docsify or 11ty
+- **Large organization**: Look at Antora or GitBook
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,28 +1,45 @@
 # Awesome Docs

-Welcome to Awesome Docs! This is your home page.
+[![Awesome](https://awesome.re/badge-flat2.svg)](https://awesome.re)

-## What is this?
+A **curated list** of awesome documentation tools, guides and best practices for creating, maintaining, and improving documentation.

-This is a documentation site built with VitePress, a fast static site generator powered by Vite and Vue.
+*If you see a package or project here that is no longer maintained or is not a good fit, please submit a pull request to improve this file. Thank you!*

-## Quick Start
+## 🚀 Quick Start

-To get started with this documentation:
+- **Browse by Category**: Use the navigation menu to explore specific tool categories
+- **Search**: Use the search function to find specific tools or topics
+- **Contributing**: Check our [contribution guidelines](https://github.com/testthedocs/awesome-docs/blob/master/CONTRIBUTING.md)

-1. [Read the Guide](/guide)
-2. [Learn about Installation](/guide/installation)
+## 📋 Categories Overview

-## Features
+### 🛠️ Core Tools
+- [Site Generators](./generators/) - Static site generators for documentation
+- [API Documentation](./api/) - Tools for API documentation and testing
+- [Editors](./editors/) - Markdown and documentation editors

-::: info
-VitePress provides many great features out of the box including:
- ⚡️ Fast hot reload
- 📝 Markdown-based content
- 🎨 Vue-powered theming
- 🔍 Built-in search
-:::
+### 🎨 Content Creation
+- [Writing Tools](./writing/) - Grammar, style, and writing assistance
+- [Visual Tools](./visual/) - Screenshots, screencasts, and mockups
+- [Quality Assurance](./quality/) - Linting, testing, and validation

-## Getting Help
+### 🌐 Publishing & Hosting
+- [Hosting Platforms](./hosting/) - Places to host your documentation
+- [GitHub Actions](./github-actions/) - Automation for documentation workflows
+- [Analytics](./analytics/) - Understanding your documentation usage

-If you need help, please check out our [GitHub repository](https://github.com/testthedocs/awesome-docs).
+### <20> Learning Resources
+- [Style Guides](./style-guides/) - Documentation and writing style guides
+- [Reading List](./reading/) - Articles and resources about documentation
+- [Best Practices](./best-practices/) - Proven strategies and approaches
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [contribution guidelines](https://github.com/testthedocs/awesome-docs/blob/master/CONTRIBUTING.md) for details.
+
+Thanks to all [contributors](https://github.com/testthedocs/awesome-docs/graphs/contributors) - you rock! 🎉
+
+## 📄 License
+
+This project is licensed under [CC0 1.0 Universal](https://github.com/testthedocs/awesome-docs/blob/master/LICENSE).
--- a/docs/quality.md
+++ b/docs/quality.md
@@ -0,0 +1,80 @@
+# Quality Assurance
+
+Tools and practices for ensuring documentation quality, accuracy, and consistency.
+
+## Language & Style Tools
+
+### Grammar & Writing
+- [Alex](https://github.com/get-alex/alex) - Catch insensitive, inconsiderate writing
+- [Harper](https://writewithharper.com/) - Grammar checker for developers
+- [Vale](https://vale.sh/) - Syntax-aware linter for prose
+- [Woke](https://getwoke.tech/) - Detect non-inclusive language
+
+### Style Consistency
+- [case-police](https://github.com/antfu/case-police) - Make casing consistent
+- [Capitalize My Title](https://capitalizemytitle.com/) - Title case formatter
+
+## Link & Content Validation
+
+### Link Checking
+- [lychee](https://github.com/lycheeverse/lychee) - Fast link checker written in Rust
+- [Linkspector](https://github.com/UmbrellaDocs/linkspector) - Web crawler for broken links
+- [HtmlTest](https://github.com/wjdp/htmltest) - HTML validation and link checking
+- [brok](https://github.com/smallhadroncollider/brok) - Find broken links in text files
+
+### Content Testing
+- [Doc Detective](https://github.com/doc-detective/doc-detective) - Test documentation accuracy
+- [Swimm](https://swimm.io/) - Keep code documentation synchronized
+
+## Accessibility & Readability
+
+### Accessibility Testing
+- [AXE-CLI](https://github.com/dequelabs/axe-cli) - Accessibility testing from command line
+- [Pa11y](https://pa11y.org/) - Automated accessibility testing
+- [Lumberjack](https://github.com/JakePartusch/lumberjack) - Accessibility checker
+
+### Readability Analysis
+- [Readable](https://www.webfx.com/tools/read-able/) - Readability score calculator
+- [Contrastchecker](https://webaim.org/resources/contrastchecker/) - Color contrast validation
+
+## Automation & CI/CD
+
+### Automated Testing
+- [Your automated tester](https://squidler.io/) - Documentation testing platform
+- [InnovationEngine](https://github.com/Azure/InnovationEngine) - Content analysis and suggestions
+
+## Quality Assurance Workflow
+
+### Pre-Publishing Checklist
+1. **Grammar & Style** - Run through Alex, Vale, or similar tools
+2. **Link Validation** - Check all internal and external links
+3. **Accessibility** - Ensure content meets accessibility standards
+4. **Readability** - Verify content is appropriate for target audience
+5. **Consistency** - Check terminology and formatting consistency
+
+### Continuous Quality
+- Set up automated checks in CI/CD pipeline
+- Regular link validation schedules
+- Style guide enforcement
+- User feedback integration
+
+### Tools Integration
+Most quality assurance tools can be integrated into:
+- **Git Hooks** - Run checks before commits
+- **CI/CD Pipelines** - Automated quality gates
+- **Editor Extensions** - Real-time feedback
+- **GitHub Actions** - Automated PR checks
+
+## Best Practices
+
+### Establish Standards
+- Create and maintain a style guide
+- Define quality metrics and thresholds
+- Document review processes
+- Train team members on tools and standards
+
+### Monitor Continuously
+- Regular audits of documentation quality
+- Track metrics over time
+- User feedback analysis
+- Tool effectiveness evaluation