documentation-site-setup

仓库: aj-geddes/useful-ai-prompts
安装量: 122
排名: #7013

安装

npx skills add https://github.com/aj-geddes/useful-ai-prompts --skill documentation-site-setup

Documentation Site Setup Overview

Set up professional documentation websites using popular static site generators like Docusaurus, MkDocs, VitePress, and GitBook.

When to Use Documentation website setup API documentation portals Product documentation sites Technical documentation hubs Static site generation GitHub Pages deployment Multi-version documentation Docusaurus Setup Installation

Create new Docusaurus site

npx create-docusaurus@latest my-docs classic

cd my-docs

Install dependencies

npm install

Start development server

npm start

Project Structure my-docs/ ├── docs/ # Documentation pages │ ├── intro.md │ ├── tutorial/ │ │ ├── basics.md │ │ └── advanced.md │ └── api/ │ └── reference.md ├── blog/ # Blog posts (optional) │ ├── 2025-01-15-post.md │ └── authors.yml ├── src/ │ ├── components/ # React components │ ├── css/ # Custom CSS │ └── pages/ # Custom pages │ ├── index.js # Homepage │ └── about.md ├── static/ # Static assets │ └── img/ ├── docusaurus.config.js # Site configuration ├── sidebars.js # Sidebar configuration └── package.json

Configuration // docusaurus.config.js module.exports = { title: 'My Documentation', tagline: 'Comprehensive documentation for developers', url: 'https://docs.example.com', baseUrl: '/', onBrokenLinks: 'throw', onBrokenMarkdownLinks: 'warn', favicon: 'img/favicon.ico', organizationName: 'myorg', projectName: 'my-docs',

presets: [ [ 'classic', { docs: { sidebarPath: require.resolve('./sidebars.js'), editUrl: 'https://github.com/myorg/my-docs/tree/main/', showLastUpdateTime: true, showLastUpdateAuthor: true, }, blog: { showReadingTime: true, editUrl: 'https://github.com/myorg/my-docs/tree/main/', }, theme: { customCss: require.resolve('./src/css/custom.css'), }, }, ], ],

themeConfig: { navbar: { title: 'My Docs', logo: { alt: 'Logo', src: 'img/logo.svg', }, items: [ { type: 'doc', docId: 'intro', position: 'left', label: 'Docs', }, { to: '/blog', label: 'Blog', position: 'left' }, { href: 'https://github.com/myorg/repo', label: 'GitHub', position: 'right', }, ], }, footer: { style: 'dark', links: [ { title: 'Docs', items: [ { label: 'Getting Started', to: '/docs/intro', }, { label: 'API Reference', to: '/docs/api/reference', }, ], }, { title: 'Community', items: [ { label: 'Discord', href: 'https://discord.gg/example', }, { label: 'Twitter', href: 'https://twitter.com/example', }, ], }, ], copyright: Copyright © ${new Date().getFullYear()} My Company., }, prism: { theme: require('prism-react-renderer/themes/github'), darkTheme: require('prism-react-renderer/themes/dracula'), additionalLanguages: ['bash', 'diff', 'json'], }, algolia: { appId: 'YOUR_APP_ID', apiKey: 'YOUR_SEARCH_API_KEY', indexName: 'YOUR_INDEX_NAME', }, }, };

Sidebar Configuration // sidebars.js module.exports = { docs: [ 'intro', { type: 'category', label: 'Getting Started', items: [ 'getting-started/installation', 'getting-started/quick-start', 'getting-started/configuration', ], }, { type: 'category', label: 'Guides', items: [ 'guides/authentication', 'guides/database', 'guides/deployment', ], }, { type: 'category', label: 'API Reference', items: [ 'api/overview', 'api/endpoints', 'api/errors', ], }, ], };

Versioning

Create version 1.0

npm run docusaurus docs:version 1.0

Files created:

- versioned_docs/version-1.0/

- versioned_sidebars/version-1.0-sidebars.json

- versions.json

Deployment

Build for production

npm run build

Deploy to GitHub Pages

GIT_USER= npm run deploy

MkDocs Setup Installation

Install MkDocs

pip install mkdocs

Install Material theme

pip install mkdocs-material

Create new project

mkdocs new my-docs cd my-docs

Start development server

mkdocs serve

Project Structure my-docs/ ├── docs/ │ ├── index.md │ ├── getting-started.md │ ├── api/ │ │ └── reference.md │ └── guides/ │ └── tutorial.md ├── mkdocs.yml └── requirements.txt

Configuration

mkdocs.yml

site_name: My Documentation site_url: https://docs.example.com site_description: Comprehensive documentation site_author: Your Name

repo_name: myorg/repo repo_url: https://github.com/myorg/repo edit_uri: edit/main/docs/

theme: name: material palette: # Light mode - media: "(prefers-color-scheme: light)" scheme: default primary: indigo accent: indigo toggle: icon: material/brightness-7 name: Switch to dark mode # Dark mode - media: "(prefers-color-scheme: dark)" scheme: slate primary: indigo accent: indigo toggle: icon: material/brightness-4 name: Switch to light mode features: - navigation.instant - navigation.tracking - navigation.tabs - navigation.sections - navigation.expand - navigation.top - search.suggest - search.highlight - content.code.annotate - content.tabs.link

plugins: - search - minify: minify_html: true

markdown_extensions: - pymdownx.highlight: anchor_linenums: true - pymdownx.inlinehilite - pymdownx.snippets - pymdownx.superfences: custom_fences: - name: mermaid class: mermaid format: !!python/name:pymdownx.superfences.fence_code_format - pymdownx.tabbed: alternate_style: true - admonition - pymdownx.details - pymdownx.emoji: emoji_index: !!python/name:materialx.emoji.twemoji emoji_generator: !!python/name:materialx.emoji.to_svg - attr_list - md_in_html

nav: - Home: index.md - Getting Started: - Installation: getting-started/installation.md - Quick Start: getting-started/quick-start.md - Guides: - Tutorial: guides/tutorial.md - Best Practices: guides/best-practices.md - API Reference: - Overview: api/overview.md - Endpoints: api/reference.md

extra: social: - icon: fontawesome/brands/github link: https://github.com/myorg - icon: fontawesome/brands/twitter link: https://twitter.com/myorg version: provider: mike

Admonitions !!! note This is a note

!!! tip This is a tip

!!! warning This is a warning

!!! danger This is dangerous

!!! info "Custom Title" Custom admonition with title

Deployment

Build site

mkdocs build

Deploy to GitHub Pages

mkdocs gh-deploy

VitePress Setup Installation

Create project

mkdir my-docs cd my-docs

Initialize

npm init -y npm install -D vitepress

Create docs

mkdir docs echo '# Hello VitePress' > docs/index.md

Add scripts to package.json

{ "scripts": { "docs:dev": "vitepress dev docs", "docs:build": "vitepress build docs", "docs:preview": "vitepress preview docs" } }

Configuration // docs/.vitepress/config.js export default { title: 'My Documentation', description: 'Comprehensive documentation', themeConfig: { nav: [ { text: 'Guide', link: '/guide/' }, { text: 'API', link: '/api/' }, { text: 'GitHub', link: 'https://github.com/myorg/repo' } ], sidebar: { '/guide/': [ { text: 'Getting Started', items: [ { text: 'Introduction', link: '/guide/' }, { text: 'Installation', link: '/guide/installation' }, { text: 'Quick Start', link: '/guide/quick-start' } ] }, { text: 'Advanced', items: [ { text: 'Configuration', link: '/guide/configuration' }, { text: 'Deployment', link: '/guide/deployment' } ] } ], '/api/': [ { text: 'API Reference', items: [ { text: 'Overview', link: '/api/' }, { text: 'Endpoints', link: '/api/endpoints' } ] } ] }, socialLinks: [ { icon: 'github', link: 'https://github.com/myorg/repo' } ], editLink: { pattern: 'https://github.com/myorg/repo/edit/main/docs/:path', text: 'Edit this page on GitHub' }, footer: { message: 'Released under the MIT License.', copyright: 'Copyright © 2025-present My Company' }, search: { provider: 'local' } } }

GitBook Setup Installation

Install GitBook CLI

npm install -g gitbook-cli

Initialize book

gitbook init

Start development server

gitbook serve

Project Structure my-docs/ ├── README.md # Introduction ├── SUMMARY.md # Table of contents ├── book.json # Configuration └── chapters/ ├── chapter1.md └── chapter2.md

Configuration { "title": "My Documentation", "description": "Comprehensive documentation", "author": "Your Name", "language": "en", "gitbook": "3.2.3", "plugins": [ "search", "prism", "-highlight", "github", "edit-link", "versions" ], "pluginsConfig": { "github": { "url": "https://github.com/myorg/repo" }, "edit-link": { "base": "https://github.com/myorg/repo/edit/main", "label": "Edit This Page" } } }

Table of Contents

Summary

Getting Started

Guides

API Reference

GitHub Pages Deployment Workflow

.github/workflows/deploy-docs.yml

name: Deploy Documentation

on: push: branches: [main]

jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3

  - name: Setup Node.js
    uses: actions/setup-node@v3
    with:
      node-version: 18

  - name: Install dependencies
    run: npm ci

  - name: Build documentation
    run: npm run build

  - name: Deploy to GitHub Pages
    uses: peaceiris/actions-gh-pages@v3
    with:
      github_token: ${{ secrets.GITHUB_TOKEN }}
      publish_dir: ./build

Custom Domain Setup DNS Configuration

Add CNAME record

docs.example.com -> username.github.io

GitHub Pages Settings Go to repository Settings > Pages Set source to gh-pages branch Add custom domain: docs.example.com Enable "Enforce HTTPS" Search Integration Algolia DocSearch // docusaurus.config.js module.exports = { themeConfig: { algolia: { appId: 'YOUR_APP_ID', apiKey: 'YOUR_SEARCH_API_KEY', indexName: 'YOUR_INDEX_NAME', contextualSearch: true, searchParameters: {}, searchPagePath: 'search', }, }, };

Local Search

MkDocs

pip install mkdocs-material[search]

VitePress (built-in)

No additional setup needed

Best Practices ✅ DO Use consistent navigation structure Enable search functionality Add edit links to pages Include version selector for versioned docs Use syntax highlighting for code blocks Add dark mode support Optimize images and assets Enable analytics Add social media links Use responsive design Include breadcrumbs Add table of contents Test on mobile devices ❌ DON'T Use outdated frameworks Skip search functionality Forget mobile responsiveness Use slow-loading assets Skip accessibility features Ignore SEO optimization Resources Docusaurus MkDocs MkDocs Material VitePress GitBook GitHub Pages Algolia DocSearch

← 返回排行榜