Contributing to the PowerGrid Documentation

Thanks for wanting to help improve the PowerGrid docs! This guide explains how to set up your environment, how our documentation is structured, and — most importantly — how to write new pages so they read like they belong here. Please read it fully before opening a pull request.

Getting Started
Doing Your Work
Writing Style Guide
Validating Your Changes
Pushing Your Changes
Documentation Structure Reference

Getting Started

Fork this repository.

   git clone https://github.com/Power-Components/powergrid-doc

Create a new branch with a short, descriptive name, e.g. 6x-add-export-section or 6x-fix-typo-install.

   git checkout -b 6x-add-export-section

Install dependencies.

   npm install

Doing Your Work

Before editing or creating a page, read the "Writing Style Guide" and "Documentation Structure Reference" sections below. These explain exactly how our .md files are built — front matter, headings, code blocks, callouts, everything. Your contribution should be indistinguishable in style from the existing docs.

A few ground rules:

Always include a code example when describing a feature. A description without a code sample is only half a page.
Reuse the existing DishTable component in examples. Don't invent a new example component (no UserTable, no ProductGrid) — consistency across pages helps readers follow along from page to page.
Always show which file the code belongs in. Readers should never have to guess where a snippet goes.
Run your text through a grammar checker (Grammarly, Scribens, or similar) before submitting.

Writing Style Guide

This is the most important section of this guide. The documentation has a very specific tone and structure, and every new or edited page must follow it.

Voice and Tone

Write in second person ("you"), addressing the reader directly (E,g: "Sometimes you may need to translate your table. To do this, you must create a file...").
Use short, plain, declarative sentences. Avoid long, winding explanations.
Be friendly but efficient — guide the reader step by step ("First, require PowerGrid via Composer.", "Next, publish the config file.", "To enable this feature, just chain the ->editOnClick() method...").
Avoid jargon when a simpler word works just as well.
Don't be robotic or overly formal, but don't be overly casual either — imagine a knowledgeable colleague walking someone through a feature.

Every Doc Page Must Start With Front Matter

Every documentation .md file under docs/ must begin with a YAML front matter block containing a title and a description. The description should be a short, two-sentence, welcoming pitch for what the page covers. For example, a real page would begin like this:

---
title: Updating Data
description: Save time with quick, inline updates. Allow users to click and edit fields directly inside the table cell and save changes instantly without page reloads.
---

Every Doc Page Must Open the Same Way

Right after the front matter, every page follows this exact opening pattern:

An H1 heading (#) matching the page title.
One sentence: "This section covers [topic]."
The line: "Here you will find:"
A table of contents marker: [[toc]]

For example, a real page opens like this:

# Table Columns

This section covers the features of your Table Component Columns.

Here you will find:

[[toc]]

Do not skip this pattern, and do not rewrite it creatively — it should look the same on every page.

Headings Must Be Hierarchical

Use # only once, for the page title. Major features get ##. Sub-variants of a feature get ###, nested under their parent ##. Never skip a level (for example, don't jump from ## straight to ####). Look at how the "Column Summary" page nests Sum, Count, Average, Min, and Max as ### under one ## parent — follow that pattern.

Code Blocks

Every code block in the docs must declare its language right after the triple backticks, and must indicate the file it belongs to in angle brackets. For terminal commands, use terminal instead of a file path. If there's no real file (e.g. plain CSS snippet), just indicate the language, like <css>.

✅ Good (this is what a real doc code block looks like):

```php <app/Livewire/DishTable.php>
use PowerComponents\LivewirePowerGrid\Column;

Column::add()
    ->field('name'),
```

❌ Bad (missing the file annotation):

```php
Column::add()->field('name'),
```

For terminal commands:

```shell <terminal>
composer require power-components/livewire-powergrid
```

Code Groups

When you want to show multiple related files side by side (for example, a component plus the view that renders it), use a code group. Each tab needs its own [title] and must still follow the file-annotation rule above:

::: code-group

```php [PowerGrid Component] <app/Livewire/DishTable.php>
use PowerComponents\LivewirePowerGrid\PowerGridComponent;

class DishTable extends PowerGridComponent
//...
```

```php [App View] <resources/views/my-app.blade.php>
<livewire:dish-table />
```

:::

Code Diff

When you're showing the reader how to add or remove a line (e.g. a config change or a new import), add a // [!code ++] or // [!code --] comment at the end of that line. This keeps the normal code coloring but also marks the line as added or removed:

```javascript <resources/js/app.js>
import './../../vendor/power-components/livewire-powergrid/dist/powergrid' // [!code ++]
```

You can mark a range of lines by adding a count, like // [!code ++:2] to mark that line plus the next one:

```javascript <resources/js/app.js>
import './../../vendor/power-components/livewire-powergrid/dist/powergrid' // [!code ++:2]
import './../../vendor/power-components/livewire-powergrid/dist/foobar'
```

Use code diffs every time you're showing the reader an addition, removal, or configuration change — don't just describe it in prose, show it.

Code Highlight

To draw attention to a line without implying it was added or removed, use // [!code highlight] (or // [!code highlight:2] to highlight a range):

```javascript <resources/js/app.js>
import './../../vendor/power-components/livewire-powergrid/dist/powergrid' // [!code highlight:1]
import './../../vendor/power-components/livewire-powergrid/dist/foobar'
```

Containers (Callout Boxes)

Use containers to call out notes, tips, warnings, and dangers — never plain bold text or blockquotes for this purpose. Containers are written as colon-fenced blocks: ::: type ... :::.

Some containers already come with a built-in title and icon, so you don't need to add your own:

::: hint
Read more about Events in the Livewire documentation: https://foo.bar/baz
:::

::: risk
eval() is evil!
:::

::: success
Let's go on and configure PowerGrid!
:::

The available pre-titled blocks are: note, caution, risk, hint, done.

You can also use a default block and supply your own custom title, like this:

::: success 🎉 All done!
Let's go on and configure PowerGrid!
:::

The available default blocks you can customize a title for are: info, warning, danger, details, success, message.

There's also a special demo container. Use it whenever a feature has a live, interactive example on the demo site, to point readers there:

::: demo
See a live example of this feature: https://foo.bar/baz
:::

If you're documenting a complex feature, consider also adding a working example to the live demo repository (foo.bar/baz) and linking to it with a ::: demo block.

Reference Tables for Parameters

When documenting a method's parameters, use a three-column table with this exact header: Parameter | Description | Default. Show the parameter's PHP type and variable name together in the first column, like (bool) $hasPermission. This format is used consistently across the docs (see the editOnClick() and toggleable() examples on the Table Columns page) — don't deviate from it.

Media

Media files (images, video, audio) live under the media directory, not under docs. Supported formats are: image/jpeg, image/png, image/gif, image/webp, video/mp4, video/webm, audio/mpeg, audio/wav, and audio/ogg.

No Raw HTML

Write clean Markdown only. Don't mix in raw HTML tags — if you think you need HTML, there's almost certainly a Markdown extension above (code blocks, code groups, diffs, highlights, or containers) that already covers your use case.

Validating Your Changes

Before opening a pull request, run the following npm scripts to format and lint your work:

npm run json:format

This formats all JSON files in the project.

npm run md:format

This formats all Markdown files under docs.

npm run md:lint

This lints (and auto-fixes, when possible) all Markdown files under docs.

Then run the check-only versions below to confirm everything is clean before you push:

npm run md:format-check
npm run md:lint-check
npm run json:validate

If all of these pass without errors, you're ready to commit.

Pushing Your Changes

Commit your work with a meaningful message and description. For example:

git commit -m "Add section on exporting filtered data"

A good commit description explains what changed and why, for example: "This adds a new section explaining how to export only the rows that match the current filters, including a code example using the DishTable component."

Then push your branch:

git push

Finally, open a pull request. Your PR description should clearly state what you're changing and why, for example: "This PR updates the Install page, adding a new section about publishing translation files for users with multilingual applications."

Thank you for contributing — we really appreciate it!

Documentation Structure Reference

Folder Structure

All Markdown files and configuration live under the docs directory. All images, video, and audio files live under the media directory.

Config File

There is a docs/config.json file that configures the documentation sidebar and other settings. The sidebar key holds a list of sections. Each section has a title, an is_collapsed flag (controls whether it renders collapsed by default), and an items list of the pages in that section, each with its own title and slug.

{
  "config": {},
  "sidebar": [
    {
      "title": "📄 Release Notes",
      "is_collapsed": true,
      "items": [
        {
          "title": "Release Notes",
          "slug": "release-notes-and-upgrade/release-notes"
        },
        {
          "title": "Upgrade Guide",
          "slug": "release-notes-and-upgrade/upgrade-guide"
        }
      ]
    }
  ]
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Contributing to the PowerGrid Documentation

Table of Contents

Getting Started

Doing Your Work

Writing Style Guide

Voice and Tone

Every Doc Page Must Start With Front Matter

Every Doc Page Must Open the Same Way

Headings Must Be Hierarchical

Code Blocks

Code Groups

Code Diff

Code Highlight

Containers (Callout Boxes)

Reference Tables for Parameters

Links

Media

No Raw HTML

Validating Your Changes

Pushing Your Changes

Documentation Structure Reference

Folder Structure

Config File

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to the PowerGrid Documentation

Table of Contents

Getting Started

Doing Your Work

Writing Style Guide

Voice and Tone

Every Doc Page Must Start With Front Matter

Every Doc Page Must Open the Same Way

Headings Must Be Hierarchical

Code Blocks

Code Groups

Code Diff

Code Highlight

Containers (Callout Boxes)

Reference Tables for Parameters

Links

Media

No Raw HTML

Validating Your Changes

Pushing Your Changes

Documentation Structure Reference

Folder Structure

Config File