MkDocs Documentation Setup Guide¶

How to Build and Deploy Professional Documentation

📋 Overview¶

This project uses MkDocs with the Material theme for beautiful, professional documentation.

Benefits: - ✅ Write in Markdown (simple) - ✅ Version control with Git - ✅ Professional appearance - ✅ Fast static site generation - ✅ Search functionality - ✅ Mobile responsive - ✅ Host on your domain

🛠️ Setup (One-Time)¶

Step 1: Install MkDocs¶

pip install mkdocs mkdocs-material

Verify installation:

mkdocs --version

Step 2: Review Configuration¶

The configuration is in mkdocs.yml at the project root.

Key settings:

site_name: MagicON AI Documentation
site_url: https://pcbgenerator.com/docs
theme:
  name: material
  palette:
    - scheme: default  # Light mode
    - scheme: slate    # Dark mode

Step 3: Preview Locally¶

Start development server:

mkdocs serve

Access at:

http://localhost:8001

Features: - ✅ Live reload (changes appear instantly) - ✅ Search functionality - ✅ Full navigation - ✅ Exactly as users will see it

📝 Writing Documentation¶

File Structure:¶

docs/
├── index.md                    # Home page
├── getting-started/
│   ├── quick-start.md
│   ├── installation.md
│   └── first-design.md
├── rf-module/
│   ├── overview.md
│   ├── phase1-requirements.md
│   ├── phase2-components.md
│   ├── component-ai.md
│   └── alternatives.md
├── stackup/
│   ├── overview.md
│   ├── materials.md
│   └── export.md
├── legal/
│   ├── terms.md
│   ├── privacy.md
│   └── licenses.md
└── assets/
    └── images/

Creating a New Page:¶

Create Markdown file:

# Create new page
echo "# My New Page" > docs/my-section/new-page.md

Add to navigation in mkdocs.yml:

nav:
  - My Section:
    - New Page: my-section/new-page.md

Preview:
```
mkdocs serve
```

Markdown Enhancements:¶

Admonitions (callout boxes):

!!! note "Important Note"
    This is highlighted information

!!! tip "Pro Tip"
    This is a helpful tip

!!! warning "Warning"
    This is a warning

!!! success "Success"
    This indicates success

Code blocks with syntax highlighting:

```python
def hello_world():
    print("Hello, World!")

**Tabs:**
```markdown
=== "Python"
    ```python
    print("Hello")
    ```

=== "JavaScript"
    ```javascript
    console.log("Hello");
    ```

Task lists:

- [x] Completed task
- [ ] Pending task

🏗️ Building for Production¶

Step 1: Build Static Site¶

mkdocs build

Output: - Creates site/ directory - Contains all HTML, CSS, JS files - Ready to deploy - Size: ~2-5 MB (lightweight!)

Step 2: Deploy to Your Server¶

Option A: Manual Upload (Simple)

Build the site:
```
mkdocs build
```

Upload via FTP/SFTP:

# Upload contents of site/ folder to:
# pcbgenerator.com/docs/

Access at:
```
https://pcbgenerator.com/docs/
```

Option B: Hostinger Deployment (Recommended)

Since you use Hostinger for hosting:

Build locally:
```
mkdocs build
```
Upload via Hostinger File Manager:
Log into Hostinger control panel
Navigate to public_html/
Create docs/ folder
Upload contents of site/ folder
Set permissions (755 for folders, 644 for files)
Access at:
```
https://pcbgenerator.com/docs/
```

Option C: GitHub Pages (Free, Automated)

Create gh-pages branch:
```
mkdocs gh-deploy
```

Access at:

https://magiccadai.github.io/AI-assisted-PCB-stackup-generator/

Add CNAME for custom domain (optional):

echo "docs.pcbgenerator.com" > docs/CNAME
mkdocs gh-deploy

Option D: Automated CI/CD (Advanced)

Create .github/workflows/docs.yml:

name: Deploy Documentation

on:
  push:
    branches:
      - main
    paths:
      - 'docs/**'
      - 'mkdocs.yml'

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

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: 3.x

      - name: Install dependencies
        run: pip install mkdocs mkdocs-material

      - name: Build documentation
        run: mkdocs build

      - name: Deploy to Hostinger via FTP
        uses: SamKirkland/FTP-Deploy-Action@4.3.0
        with:
          server: ${{ secrets.FTP_SERVER }}
          username: ${{ secrets.FTP_USERNAME }}
          password: ${{ secrets.FTP_PASSWORD }}
          local-dir: ./site/
          server-dir: /public_html/docs/

This auto-deploys docs whenever you update them!

🔗 Updating Documentation Links¶

In Your App:¶

Update footer and legal pages to point to your hosted docs:

// frontend/src/components/Footer.tsx
<a href="https://pcbgenerator.com/docs">
  Documentation
</a>

// frontend/src/pages/TermsOfService.tsx
<a href="https://pcbgenerator.com/docs">User Guide</a>

📊 Documentation Structure¶

Current Pages to Create:¶

Getting Started (3 pages): - [x] quick-start.md - Quick start guide - [ ] installation.md - Detailed installation - [ ] first-design.md - First design walkthrough

RF Module (7 pages): - [ ] overview.md - Phase-based workflow overview - [ ] phase1-requirements.md - Phase 1 guide - [ ] phase2-components.md - Phase 2 guide - [ ] component-ai.md - AI selection explained - [ ] alternatives.md - Understanding alternatives

Stackup (6 pages): - [ ] overview.md - Stackup designer overview - [ ] materials.md - Material selection guide - [ ] impedance.md - Impedance calculator - [ ] export.md - Export options

Legal (3 pages): - [ ] terms.md - Terms of Service - [ ] privacy.md - Privacy Policy - [ ] licenses.md - Third-Party Licenses

Total: ~20 pages

Time estimate: 1-2 hours to convert existing content

🎨 Customization¶

Branding:¶

Add logo:

# Copy your logo to:
docs/assets/logo.png

Add favicon:

# Copy favicon to:
docs/assets/favicon.ico

Custom CSS:
```
# Create:
docs/stylesheets/extra.css
```

Colors:¶

In mkdocs.yml:

theme:
  palette:
    primary: blue      # Header color
    accent: emerald    # Link color

Available colors: red, pink, purple, deep purple, indigo, blue, light blue, cyan, teal, green, light green, lime, yellow, amber, orange, deep orange

📈 Analytics (Optional)¶

Add Google Analytics to track documentation usage:

# In mkdocs.yml
extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX

🔍 Search Optimization¶

MkDocs includes built-in search. To improve it:

Use clear headings (# ## ###)
Add keywords in page metadata
Use descriptive titles
Link between pages

🚀 Deployment Checklist¶

All pages created and reviewed
Images added (if any)
Links tested (internal + external)
Build successful (mkdocs build)
Preview looks good (mkdocs serve)
Upload to pcbgenerator.com/docs/
Test live site
Update app links to point to docs
Submit sitemap to Google (SEO)

📞 Questions?¶

MkDocs Docs: https://www.mkdocs.org/
Material Theme: https://squidfunk.github.io/mkdocs-material/
Support: support@pcbgenerator.com

Next: Convert USER_GUIDE.md content into organized pages (installation guide coming soon)