Contributing to Documentation

This guide explains how to contribute to the SEO Platform documentation.

Getting Started

Prerequisites

• Node.js 18+
• Git
• A GitHub account

Local Setup

# Clone the repository
git clone https://github.com/sebastianebg/seo-platform.git
cd seo-platform/docs-site

# Install dependencies
npm install

# Start local development server
npm run start

The docs will be available at http://localhost:3000.

Creating New Documentation

1. Create a Branch

git checkout -b docs/your-topic-name

2. Create the File

Create a new Markdown file in the appropriate directory:

Content Type	Directory
Getting started guides	docs/getting-started/
User guides	docs/user-guide/
Developer docs	docs/developer/
API documentation	docs/api/

3. Add Frontmatter

Every documentation file requires YAML frontmatter at the top:

---
sidebar_position: 1
title: Your Page Title
description: Brief description for SEO (max 160 characters)
tags:
  - relevant
  - tags
---

4. Write Content

Use Markdown with MDX support. See Style Guide below.

5. Preview Locally

npm run start

Navigate to your new page and verify it renders correctly.

6. Submit a Pull Request

git add .
git commit -m "docs: add documentation for [topic]"
git push origin docs/your-topic-name

Open a Pull Request on GitHub. A preview deployment will be automatically created.

Frontmatter Schema

Required Fields

Field	Type	Description
title	string	Page title (displayed in sidebar and browser)
description	string	SEO meta description (max 160 chars)

Optional Fields

Field	Type	Description
sidebar_position	number	Order in sidebar (lower = higher)
sidebar_label	string	Alternative sidebar text
tags	string[]	Keywords for search and categorization
hide_title	boolean	Hide the page title
hide_table_of_contents	boolean	Hide the TOC

Example

---
sidebar_position: 2
sidebar_label: Quick Start
title: Quick Start Guide for SEO Platform
description: Get started with SEO Platform in under 5 minutes with this step-by-step guide.
tags:
  - getting-started
  - quick-start
  - tutorial
hide_table_of_contents: false
---

Style Guide

Headings

• Use # for the main title (one per page)
• Use ## for major sections
• Use ### for subsections
• Don't skip heading levels

Code Blocks

Use fenced code blocks with language specification:

```python
def example():
    return "Hello, World!"
```

Supported languages: python, typescript, javascript, bash, json, yaml, sql, css, html

Admonitions

Use admonitions for important callouts:

:::note
This is a note.
:::

:::tip
This is a helpful tip.
:::

:::warning
This is a warning.
:::

:::danger
This is a danger notice.
:::

Links

• Internal links: [Text](/docs/path/to/page)
• External links: [Text](https://example.com)
• Always use descriptive link text (avoid "click here")

Images

Place images in static/img/ and reference them:

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

Tables

Use standard Markdown tables:

| Column 1 | Column 2 |
|----------|----------|
| Value 1  | Value 2  |

Workflow

PR Review Process

1. Create PR - Open a pull request with your changes
2. Preview Deploy - Vercel automatically creates a preview URL
3. Review - Team members review content and preview
4. Approve - At least one approval required
5. Merge - Merge to main triggers production deployment

Commit Message Format

Use conventional commits:

docs: add guide for keyword classification
docs: fix typo in API authentication
docs: update setup instructions for Python 3.13

File Naming

• Use lowercase with hyphens: keyword-classification.md
• Be descriptive but concise
• Match the page title when possible

Best Practices

Content

• Start with a brief introduction explaining what the page covers
• Use step-by-step instructions for procedural content
• Include code examples where applicable
• Add screenshots for UI-related documentation
• Keep paragraphs short (3-5 sentences)

Technical Accuracy

• Test all code examples
• Verify links work
• Keep content up-to-date with latest features
• Note version requirements where applicable

Accessibility

• Use descriptive alt text for images
• Maintain proper heading hierarchy
• Provide text alternatives for complex diagrams
• Use sufficient color contrast

Need Help?

• Check existing documentation for examples
• Ask in GitHub Discussions
• Open an issue for documentation requests