Contributing to Documentation

Thank you for your interest in contributing to the Xainflow documentation! This guide will help you get started.

Prerequisites

Before you begin, make sure you have:

• Node.js version 20.0 or higher
• Git installed
• A GitHub account

Getting Started

1. Clone the Repository

git clone https://github.com/xainflow/xainflow-docs.git
cd xainflow-docs

2. Install Dependencies

cd docs
npm install

3. Start the Development Server

npm start

This will start a local development server at http://localhost:3000. The site will automatically reload when you make changes.

Adding Documentation

Creating a New Document

1. Navigate to docs/docs/ directory
2. Create a new Markdown file (e.g., my-new-doc.md)
3. Add frontmatter at the top of the file:

---
sidebar_position: 3
---

# My New Document

Your content here...

Document Structure

Each document should have:

• Frontmatter - YAML metadata at the top
• Title - H1 heading (automatically used as page title)
• Content - Your documentation in Markdown

Frontmatter Options

Property	Description	Example
sidebar_position	Order in the sidebar	1, 2, 3
sidebar_label	Custom sidebar label	"Getting Started"
title	Page title (overrides H1)	"My Custom Title"
description	Meta description	"A guide to..."
slug	Custom URL path	/custom-path

Organizing Documents

Creating Categories

To create a new category (folder with multiple docs):

1. Create a new folder in docs/docs/ (e.g., docs/docs/guides/)
2. Add a _category_.json file:

{
  "label": "Guides",
  "position": 3,
  "link": {
    "type": "generated-index",
    "description": "Learn how to use Xainflow with these guides."
  }
}

3. Add your documents inside the folder

Example Structure

docs/docs/
├── intro.md
├── contributing.md
├── guides/
│   ├── _category_.json
│   ├── getting-started.md
│   └── advanced-usage.md
└── architecture/
    ├── _category_.json
    ├── overview.md
    └── deployment.md

Writing Guidelines

Markdown Features

Docusaurus supports extended Markdown features:

Code Blocks with Syntax Highlighting

```javascript title="example.js"
function hello() {
  console.log('Hello, Xainflow!');
}
```

Admonitions

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

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

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

:::danger
This is a danger alert.
:::

:::info
This is informational.
:::

Tabs

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="npm" label="npm" default>
    npm install package
  </TabItem>
  <TabItem value="yarn" label="Yarn">
    yarn add package
  </TabItem>
</Tabs>

Best Practices

1. Be Clear and Concise - Use simple language and short sentences
2. Use Examples - Include code examples whenever possible
3. Add Images - Visual aids help explain complex concepts
4. Link Related Docs - Cross-reference related documentation
5. Keep Updated - Update docs when features change

Adding Blog Posts

Creating a Blog Post

1. Navigate to docs/blog/ directory
2. Create a new file with the naming convention: YYYY-MM-DD-title.md

---
slug: my-first-post
title: My First Blog Post
authors: [your-name]
tags: [announcement, feature]
---

Your blog content here...

<!-- truncate -->

More content after the fold...

Blog Post Options

Property	Description
slug	URL path for the post
title	Post title
authors	Array of author IDs (defined in authors.yml)
tags	Array of tags
date	Override publish date
image	Social card image

Adding Images

1. Place images in docs/static/img/
2. Reference them in your Markdown:

![Alt text](/img/my-image.png)

For documentation-specific images, you can also use relative paths:

![Alt text](./img/my-image.png)

Submitting Changes

1. Create a Branch

git checkout -b docs/my-new-feature

2. Make Your Changes

Edit or create documentation files as needed.

3. Preview Your Changes

npm start

4. Commit Your Changes

git add .
git commit -m "docs: add guide for new feature"

5. Push and Create a Pull Request

git push origin docs/my-new-feature

Then create a Pull Request on GitHub.

Building for Production

To test the production build locally:

npm run build
npm run serve

This will build the site and serve it at http://localhost:3000.

Need Help?

• Check the Docusaurus documentation
• Open an issue on GitHub