Documentation Writing Guide

Welcome to the Help Center! This system is powered completely by Markdown files stored right in the application repository. Follow this guide to add new articles, manage translations, organize categories, and upload media assets.

1. Directory & File Structure

Articles are dynamically discovered based on folders and filenames inside resources/help-center/.

  • Subdirectories act as the sidebar navigation groups.
  • Filenames define the article URLs (slugs).
  • Extensions (.en.md, .ro.md) dictate the language translation.

Example layout:

resources/
└── help-center/
    ├── getting-started/
    │   ├── how-to-write-docs.en.md  <-- This article (English)
    │   └── how-to-write-docs.ro.md  <-- This article (Romanian)
    └── settings/
        └── profile-setup.en.md

Media Assets Layout:

Images, diagrams, and files are stored directly inside the public directory so the browser can serve them directly:

public/
└── help-center-assets/
    └── images/
        └── logo-example.png

2. Dynamic Titles & Headers

Every article must begin with a single # H1 Title on the very first line.

# Your Page Title Here
This is the opening paragraph of your help document...
  • Sidebar & Browser Tab: The system scans the first line of the file, extracts the # H1 text, and uses it dynamically as the label in the sidebar navigation and browser title tab.
  • Duplicate Prevention: The rendering system automatically strips out this first H1 line from the page content body, ensuring it isn't rendered twice.

3. Localizing Sidebar Group Names

While the dynamic folder names dictate how files are grouped (e.g., the getting-started directory), their actual display names in the sidebar are fully localized using Laravel's standard language files.

To add or update a navigation group name, add the folder key to the help-center.php translation file:

English (lang/en/help-center.php):

return [
    'groups' => [
        'getting-started' => 'Getting Started',
        'settings'        => 'Account Settings',
    ],
];

Romanian (lang/ro/help-center.php):

return [
    'groups' => [
        'getting-started' => 'Ghid introductiv',
        'settings'        => 'Setări cont',
    ],
];

If a translation key is missing, the system will fall back to a capitalized version of the folder name.

4. How to Use Images and Media

All images, diagrams, or file downloads must be placed inside the public/help-center-assets/ directory. You can reference them using a clean absolute path in standard Markdown syntax.

Syntax:

![Alternative text description](/help-center-assets/images/logo-example.png)

💡 Tip: Always use descriptive text inside the brackets [...] for better accessibility and screen-reader support.

5. Markdown Formatting Cheat Sheet

Feel free to use standard GitHub-Flavored Markdown components to format your documentation:

Subheadings

Use ## for major sections and ### for sub-sections. Do not use # anywhere else except the first line.

Emphasis

Use bold text for important details or keywords, and italics for emphasis.

Lists

  • Use bullet points for unordered items.
  1. Use numbers for step-by-step processes.

Code Blocks

Wrap technical references or config examples in triple backticks:

{
  "status": "success",
  "message": "System operational"
}