Emmie

Appearance

Instructions for Writing VitePress Documentation ​

Welcome to the guidelines for writing documentation in our VitePress guide. Follow these steps and rules to create clear, consistent, and maintainable documentation.

📁 File Structure ​

Be aware of the structure of the guide. When adding files, try to put them into the existing structure. Only add to the structure of the guide when you really can't put an addition anywhere else.

Creating New Files ​

  • Use short, descriptive filenames, such as getting-started.md.
  • Add a title and description in the frontmatter at the top of each file:
markdown
---
title: Getting Started
description: How to start contributing to our SaaS code
---

✍️ Style and Formatting ​

General Guidelines ​

  1. Write clearly and concisely:
    • Use short sentences and paragraphs (max 3-4 sentences).
  2. Use active voice:
    • Write "You can clone the repository" instead of "The repository can be cloned".
  3. Use consistent terminology:
    • For example, choose "component" and stick to it (don’t switch between "module" and "block").

Markdown Syntax ​

  • Use the following structures:

Headings ​

Use headings to structure the content:

markdown
# Main Title

## Subtitle

### Sub-subtitle

Lists ​

  • Use bullet points:
    markdown
    -   First point
-   Second point
  • Use numbered steps:
    markdown
    1. Step one
2. Step two

Code Blocks ​

Add examples with the appropriate language specification:

markdown
```javascript
const greet = name => {
    console.log(`Hello, ${name}!`);
};
greet('Developer');
```

#### Alerts and Tips
Use VitePress shortcodes for standout notes:
```markdown
::: tip
This is a helpful tip.
:::

::: warning
Be careful! Potential pitfall.
:::
  • Add images with descriptive alt texts:
    markdown
    ![Project overview](../images/overview.png)
  • Use relative links within the guide:
    markdown
    Read more in the [API documentation](../api/overview.md).

🚀 Content Guidelines ​

Writing an Introduction ​

  • Begin each file with a brief introduction explaining the purpose of the page.

Example:

markdown
# Getting Started

Welcome to the guide! Here, you’ll learn everything you need to know to effectively contribute to our SaaS code.

Code Examples ​

  • Keep code examples short and functional.
  • Provide context for examples:
markdown
## Example: Cloning the Repository

To set up the project:

```bash
git clone https://github.com/company/project.git
cd project
yarn install
```

### **Accessibility**
- Avoid jargon without explanation.
- Use inclusive language, such as "they" instead of "he/she".

## 🔄 Collaboration and Git Workflow

### **Commit Messages**
Use meaningful commit messages:
```plaintext
docs: Update getting-started.md with new installation steps

Review Process ​

  1. Have changes reviewed by at least one colleague.
  2. Use tools like Prettier or Markdownlint to ensure consistency.

⚙️ Configuration in VitePress ​

Setting Up Navigation ​

Adjust navigation in docs/.vitepress/config.js:

javascript
export default {
    themeConfig: {
        sidebar: [
            {
                text: 'Guide',
                items: [
                    {text: 'Getting Started', link: '/guide/getting-started'},
                    {text: 'Conventions', link: '/guide/conventions'},
                ],
            },
        ],
    },
};

✅ Checklist for Writers ​

  1. Is the language clear and simple?
  2. Have you followed a logical structure?
  3. Are all examples tested?
  4. Did you use VitePress shortcodes where needed?
  5. Are all links verified?
  6. Has the page been reviewed by a colleague?

With these guidelines, we can create consistent and user-friendly documentation together. Happy writing! 🚀