How to Update Documentation¶

This guide explains how any EgyGeeks developer can add or update documentation.

Quick Start¶

Prerequisites¶

• Git installed
• Python 3.8+ installed
• Text editor (VS Code, Sublime, etc.)

1. Clone the Documentation Repository¶

# Clone the repo
git clone <your-repo-url> egygeeks-docs
cd egygeeks-docs

# Or if already cloned, pull latest
cd egygeeks-docs
git pull origin main

2. Install MkDocs Material¶

# Install MkDocs Material
pip install mkdocs-material

# Verify installation
mkdocs --version

3. Preview Locally¶

# Start local preview server
mkdocs serve

# Open in browser
open http://127.0.0.1:8000

The site will auto-reload when you make changes!

Adding New Documentation¶

1. Create a New Page¶

All documentation is in the docs/ folder as Markdown files:

# Navigate to appropriate section
cd docs/projects/

# Create new markdown file
touch my-new-project.md

2. Write Content in Markdown¶

Open the file in your editor and write:

# My New Project

Brief description of the project.

## Overview

What does this project do?

## Tech Stack

- Frontend: React
- Backend: Node.js
- Database: PostgreSQL

## API Reference

### GET /api/users

Returns list of users.

**Response:**
\`\`\`json
{
  "users": [...]
}
\`\`\`

## Deployment

How to deploy this project...

3. Add to Navigation¶

Edit mkdocs.yml to add your page to the navigation:

nav:
  - Projects:
      - Overview: projects/index.md
      - My New Project: projects/my-new-project.md  # Add this line

4. Preview Your Changes¶

# If mkdocs serve is running, it will auto-reload
# If not, start it:
mkdocs serve

Visit http://127.0.0.1:8000 to see your changes.

Editing Existing Documentation¶

1. Find the File¶

All documentation files are in docs/:

docs/
├── index.md (Home page)
├── server/
│   ├── overview.md
│   ├── deployment.md
│   └── ...
├── claude/
│   └── ...
├── projects/
│   └── ...
└── ...

2. Edit the Markdown File¶

# Open in your editor
code docs/server/deployment.md

# Or use any text editor
nano docs/server/deployment.md

3. Save and Preview¶

Save the file and check http://127.0.0.1:8000 - changes appear instantly!

Markdown Formatting¶

Headers¶

# H1 - Page Title
## H2 - Section
### H3 - Subsection

Code Blocks¶

With syntax highlighting:

```python
def hello():
    print("Hello, world!")
```

```javascript
function hello() {
  console.log("Hello, world!");
}
```

```bash
docker-compose up -d
```

Links¶

[Link text](https://example.com)
[Link to another page](../server/overview.md)

Images¶

![Alt text](../images/screenshot.png)

Lists¶

- Unordered item
- Another item
  - Nested item

1. Ordered item
2. Another item

Tables¶

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |
| Cell 3   | Cell 4   |

Admonitions (Info Boxes)¶

!!! note "Optional Title"
    This is a note

!!! warning
    This is a warning

!!! tip
    This is a tip

!!! danger
    This is danger/error info

Tabs¶

=== "Python"

    ```python
    print("Hello")
    ```

=== "JavaScript"

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

Adding a New Project¶

1. Create Project Directory¶

mkdir -p docs/projects/my-project

2. Create Project Files¶

cd docs/projects/my-project
touch index.md api-reference.md deployment.md

3. Structure Your Project Docs¶

docs/projects/my-project/index.md:

# My Project Name

## Overview
Brief description

## Tech Stack
- List technologies

## Quick Start
How to get started

## Links
- [API Reference](api-reference.md)
- [Deployment Guide](deployment.md)

docs/projects/my-project/api-reference.md:

# API Reference - My Project

## Authentication
How to authenticate

## Endpoints

### GET /api/resource
Description...

4. Update Navigation¶

Edit mkdocs.yml:

nav:
  - Projects:
      - Overview: projects/index.md
      - My Project:
          - Overview: projects/my-project/index.md
          - API Reference: projects/my-project/api-reference.md
          - Deployment: projects/my-project/deployment.md

Git Workflow¶

1. Create a Branch¶

# Create and switch to new branch
git checkout -b docs/add-my-feature

# Or
git checkout -b docs/update-deployment-guide

2. Make Changes¶

Edit files, preview locally with mkdocs serve.

3. Commit Changes¶

# Stage changes
git add docs/

# Commit with clear message
git commit -m "docs: add deployment guide for chat app"

# Or
git commit -m "docs: update server overview with new specs"

4. Push to Remote¶

# Push branch
git push origin docs/add-my-feature

5. Create Pull Request (if using GitHub/GitLab)¶

• Go to your repository
• Click "New Pull Request"
• Select your branch
• Add description
• Request review from team

6. Merge¶

After review, merge to main:

git checkout main
git pull origin main

Deploying to Server¶

Once your changes are merged to main, deploy to the server:

# SSH to server
ssh user@50.3.85.110

# Navigate to docs directory
cd /opt/apps/egygeeks-docs

# Pull latest changes
git pull origin main

# Rebuild docs
docker-compose restart

# Or if not using Docker:
mkdocs build

The docs will be live at: http://50.3.85.110/developers

Tips & Best Practices¶

✅ DO¶

• Use clear, descriptive titles
• Include code examples - show, don't just tell
• Add screenshots when helpful
• Keep it concise - developers skim docs
• Link to related pages
• Test all code examples
• Preview locally before committing
• Write clear commit messages

❌ DON'T¶

• Don't commit secrets or API keys
• Don't use absolute URLs for internal links
• Don't forget to add new files to navigation
• Don't use huge images (optimize first)
• Don't write walls of text (use headers, lists, code blocks)

Common Tasks¶

Add a Screenshot¶

# Create images directory
mkdir -p docs/images

# Copy screenshot
cp ~/Desktop/screenshot.png docs/images/my-feature.png

# Reference in markdown
![Feature Screenshot](../images/my-feature.png)

Update Project API Docs¶

# Edit the API reference file
code docs/projects/my-project/api-reference.md

# Add new endpoints
### POST /api/new-endpoint

Description of endpoint...

**Request:**
\`\`\`json
{ "key": "value" }
\`\`\`

**Response:**
\`\`\`json
{ "result": "success" }
\`\`\`

Fix a Typo¶

# Quick fix workflow
git checkout -b docs/fix-typo
# Edit file
git add docs/path/to/file.md
git commit -m "docs: fix typo in deployment guide"
git push origin docs/fix-typo
# Merge or create PR

Troubleshooting¶

MkDocs serve not working¶

# Reinstall mkdocs-material
pip install --upgrade mkdocs-material

# Check Python version
python --version  # Should be 3.8+

# Try running with verbose
mkdocs serve --verbose

Page not showing in navigation¶

• Check that the file exists in docs/
• Verify it's added to nav: in mkdocs.yml
• Check indentation in mkdocs.yml (use spaces, not tabs)
• Restart mkdocs serve

Changes not appearing¶

• Hard refresh browser (Cmd+Shift+R or Ctrl+F5)
• Check terminal for errors
• Verify file was saved
• Restart mkdocs serve

Build errors¶

# Check for syntax errors in mkdocs.yml
mkdocs build --verbose

# Common issues:
# - Invalid YAML indentation
# - Missing files referenced in nav
# - Broken links

Getting Help¶

• Check MkDocs Material docs: squidfunk.github.io/mkdocs-material
• Markdown guide: markdownguide.org
• Ask the team: Slack/Discord channel

Git Workflow Details | Team Standards