---
sidebar_label: Updating Documentation
sidebar_position: 99
---

# How to Update Documentation

This document explains the documentation system and procedures for updating {{PROJECT_TITLE}} documentation.

## Documentation Architecture

{{PROJECT_TITLE}} documentation is managed through a **centralized documentation system**:

```
~/PycharmProjects/project-docs/          # Central documentation hub
├── docs/projects/{{PROJECT_NAME}}/      # Docs source (THIS FOLDER)
├── scripts/build-public-docs.sh         # Builds public docs
└── public-builds/{{PROJECT_NAME}}/      # Built static site

~/PycharmProjects/{{PROJECT_NAME}}/
└── docs -> ../project-docs/docs/projects/{{PROJECT_NAME}}/  # Symlink to here
```

## Two Documentation Modes

### Private Documentation (Internal)

- **Location**: `~/PycharmProjects/project-docs/`
- **View locally**: `cd ~/PycharmProjects/project-docs && npm start`
- **Contains**: All docs including credentials, internal notes, todos, deployment details
- **Audience**: Internal team only

### Public Documentation (Contributors)

- **Location**: `https://pages.brrd.tech/{{GITEA_OWNER}}/{{PROJECT_NAME}}/`
- **Build command**: `~/PycharmProjects/project-docs/scripts/build-public-docs.sh {{PROJECT_NAME}} --deploy`
- **Contains**: Only whitelisted public files
- **Audience**: Open-source contributors

## File Visibility Rules

### Automatically Public Files

These filenames are included in public builds:
- `overview.md`
- `architecture.md`
- `formats.md`
- `configuration.md`
- `index.md`

### Making Other Files Public

Add frontmatter to include a file in public builds:

```markdown
---
public: true
---

# Your Document Title
```

### Hiding Sections Within Public Files

Use HTML comments to hide sensitive sections:

```markdown
## Public Section

This content is visible to everyone.

<!-- PRIVATE_START -->
## Internal Notes

This section is stripped from public builds.
Credentials, internal discussions, etc.
<!-- PRIVATE_END -->

## Another Public Section
```

## Procedures

### Adding New Documentation

1. Create the file in `~/PycharmProjects/project-docs/docs/projects/{{PROJECT_NAME}}/`
2. Add appropriate frontmatter (title, sidebar position)
3. If it should be public, either:
   - Use a whitelisted filename, OR
   - Add `public: true` to frontmatter
4. Preview locally: `cd ~/PycharmProjects/project-docs && npm start`

### Updating Existing Documentation

1. Navigate via symlink: `cd ~/PycharmProjects/{{PROJECT_NAME}}/docs`
   - Or directly: `cd ~/PycharmProjects/project-docs/docs/projects/{{PROJECT_NAME}}`
2. Edit the relevant `.md` file
3. Preview locally if needed

### Publishing to Public Site

```bash
# Build and deploy {{PROJECT_NAME}} docs only
~/PycharmProjects/project-docs/scripts/build-public-docs.sh {{PROJECT_NAME}} --deploy

# Or build all projects
~/PycharmProjects/project-docs/scripts/build-public-docs.sh --deploy

# Dry run (see what would happen)
~/PycharmProjects/project-docs/scripts/build-public-docs.sh {{PROJECT_NAME}} --dry-run
```

### Viewing Documentation

```bash
# Private docs (all content)
cd ~/PycharmProjects/project-docs && npm start
# Opens http://localhost:3000

# Public docs
# Visit https://pages.brrd.tech/{{GITEA_OWNER}}/{{PROJECT_NAME}}/
```

## For AI Assistants

When asked to update documentation for this project:

1. **DO** edit files in `docs/` (the symlink) or the full path above
2. **DO NOT** create documentation files in the project root
3. **DO** use appropriate visibility (public/private) based on content
4. **DO** run the build script if publishing changes to the public site
5. **DO** preview changes locally before publishing

The `docs/` folder you see in this project is a symlink to the central documentation system. All changes are reflected in both the private hub and (after building) the public site.