Skip to main content

Editing Existing Content

This guide shows you how to edit existing documentation pages and verify your changes.

The Basic Workflow​

  1. Find the file — Navigate to clients/{client-slug}/{site-slug}/ and locate the markdown file
  2. Edit the markdown — Make your changes (text, code blocks, links, etc.)
  3. Test locally — Run npm run start to preview changes at http://localhost:3000
  4. Build and verify — Run npm run build to check for broken links
  5. Commit and push — git add, git commit, git push to deploy

Finding the File to Edit​

All documentation lives in the clients/ directory:

clients/
├── gsm-outdoors/
│   ├── index.md                      ← Client landing page
│   ├── middleware/
│   │   ├── intro.md                  ← Site intro page
│   │   ├── architecture.md
│   │   └── api-reference.md
│   └── stealthcam/
├── scottsdale-mint/
└── rhinogroup/

Example: Edit the GSM Outdoors Middleware API Reference​

The file is at:

clients/gsm-outdoors/middleware/api-reference.md

Open it in VS Code and make your changes.

Editing Markdown​

Text and Headings​

# Main Title (H1)
## Section (H2)
### Subsection (H3)

Regular paragraph text.

**Bold text** and *italic text*.

Code Blocks​

Use fenced code blocks with syntax highlighting:

```php
<?php
function greet($name) {
    return "Hello, " . $name;
}
```

```javascript
function greet(name) {
    return `Hello, ${name}`;
}
```

```bash
npm run build
```

Internal links (within the same site):

See [API Reference](./api-reference) for details.
See [Database Schema](./database/schema) for the schema.

External links:

Visit [Docusaurus](https://docusaurus.io/) for documentation.

Lists​

- Unordered item 1
- Unordered item 2
  - Nested item

1. Ordered item 1
2. Ordered item 2

Tables​

| Column 1 | Column 2 | Column 3 |
|---|---|---|
| Value 1 | Value 2 | Value 3 |
| Value 4 | Value 5 | Value 6 |

Admonitions (Call-out Boxes)​

:::note
Informational note.
:::

:::tip
Helpful hint or best practice.
:::

:::caution
Warning — important but non-blocking.
:::

:::danger
Critical — breaking or destructive action.
:::

Images​

Place images in static/img/ and reference them:

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

Testing Your Changes​

Development Server (Hot Reload)​

Start the dev server:

npm run start
  • Opens http://localhost:3000 automatically
  • Changes to markdown files reload instantly
  • Navigate to the page you edited to verify

Production Build​

Before committing, always run a full build:

npm run build

This will:

  • Compile all pages
  • Report any broken links
  • Create a build/ directory

Fix any errors before deploying.

Common Editing Tasks​

Update a Code Example​

Find the code block and replace it:

```php
// Old code
function old() {
    return "old";
}

Replace with:

```md
```php
// New code
function new() {
    return "new";
}

### Fix a Broken Link

If `npm run build` reports a broken link:

[clients/scottsdale-mint/retail/payments/overview.md] Docs markdown link couldn't be resolved: (../invalid-page) in path=/scottsdale-mint/retail/payments


Open the file and fix the link:

```md
<!-- Before (broken) -->
See [Invalid Page](../invalid-page)

<!-- After (fixed) -->
See [Payment Gateway](./gateway)

Change Page Order in Sidebar​

Edit the sidebar_position in the frontmatter:

---
sidebar_position: 3    # Change this number to reorder
id: my-page
title: My Page
---

Lower numbers appear first. If two pages have the same position, they're sorted alphabetically.

Example Copilot Prompts for Editing​

Here are some prompts you can use with GitHub Copilot to speed up editing:

Update Code Examples​

Update all PHP code examples in clients/gsm-outdoors/middleware/api-reference.md 
to use typed properties and return types (PHP 8.2+).
Fix all broken internal links in clients/scottsdale-mint/retail/ by verifying 
the target files exist and using correct relative paths.

Add Missing Frontmatter​

Add sidebar_position values to all markdown files in clients/tenpoint-crossbows/retail/ 
in logical order based on the content hierarchy.

Improve Code Block Syntax Highlighting​

Add language identifiers to all fenced code blocks in 
clients/rhinogroup/documentation/architecture.md (php, bash, json, etc.).

Add Admonitions for Important Notes​

Convert all "Note:", "Warning:", and "Tip:" plain text callouts in 
clients/hha-sports/retail/intro.md to Docusaurus admonitions (:::note, :::caution, :::tip).

Committing Your Changes​

Once you've verified your edits work locally:

# Stage your changes
git add .

# Commit with a descriptive message
git commit -m "Update API examples in middleware docs"

# Push to GitHub
git push origin master

The site will be automatically deployed after pushing to master. See Deployment for details.

Next Steps​