Contributing to the Knowledge Base

This guide explains how to add and edit content in the Emergent Solutions Knowledge Base.

For Non-Technical Editors

You can edit content directly through GitHub's web interface without installing any software.

Editing an Existing Page

1. Navigate to the page you want to edit in the knowledge base
2. Go to the GitHub repository: github.com/[org]/emergentsolution.com
3. Navigate to site/src/app/knowledge-base/[section]/[page]/page.mdx
4. Click the pencil icon (Edit this file)
5. Make your changes in the editor
6. Add a commit message describing your changes
7. Click Commit changes
8. Changes deploy automatically

Creating a New Page

1. Navigate to the appropriate section folder in GitHub
2. Click Add file > Create new file
3. Name it: your-page-name/page.mdx
4. Add your content using Markdown
5. Commit the file

Markdown Basics

Headings

# Main Title (H1) - one per page
## Section Heading (H2)
### Subsection (H3)
#### Minor heading (H4)

Text Formatting

**Bold text**
*Italic text*
`inline code`
[Link text](https://example.com)
[Internal link](/knowledge-base/playbooks/ga4-setup-guide)

Lists

- Bullet point
- Another point
  - Nested point

1. Numbered item
2. Second item
3. Third item

Code Blocks

Use triple backticks with the language name:

```javascript
function example() {
  return "Hello";
}
```

Tables

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

Blockquotes

> This is a callout or important note

File Structure

Each page lives in its own folder with a page.mdx file:

knowledge-base/
├── getting-started/
│   ├── what-we-do/
│   │   └── page.mdx
│   ├── how-we-work/
│   │   └── page.mdx
│   └── first-engagement/
│       └── page.mdx
├── playbooks/
│   ├── ga4-setup-guide/
│   │   └── page.mdx
│   └── ...
└── ...

Style Guidelines

Writing Style

• Be concise - Get to the point quickly
• Use active voice - "We implement tracking" not "Tracking is implemented"
• Be specific - Include concrete examples
• Avoid jargon - Explain technical terms when first used

Page Structure

Every page should have:

1. Title (H1) - One main title at the top
2. Introduction - Brief overview paragraph
3. Main content - Organized with H2/H3 headings
4. Navigation - Links to related pages at the bottom

Linking

• Use relative links for internal pages: /knowledge-base/playbooks/ga4-setup-guide
• Use descriptive text for links: "See the GA4 Setup Guide" not "click here"
• External links open in new tabs automatically

Images

Currently, images should be placed in /public/kb/ and referenced as:

![Alt text](/kb/image-name.png)

Common Tasks

Adding a New Section

1. Create a folder in knowledge-base/
2. Add pages as folder-name/page.mdx
3. Update the sidebar navigation in layout.tsx

Updating Navigation

The sidebar is defined in site/src/app/knowledge-base/layout.tsx. Add new pages to the navigation array:

{
  title: "Section Name",
  items: [
    { title: "Page Title", href: "/knowledge-base/section/page" },
  ],
},

Need Help?

• Questions: Ask in the team Slack channel
• Issues: Create a GitHub issue
• Training: Request a walkthrough session

Next: Markdown Style Guide