Skip to main content

Using describe blocks

You can use Playwright describe function to add metadata and configure how the directory structure is generated for the Docusaurus output.

Imports​

Before using the metadata functions, import them in your test file:

import { withDocMeta, withDocCategory } from "@test2doc/playwright/DocMeta";

When to Use Each Function​

  • withDocMeta: Use when you want to create a single page with multiple sections
  • withDocCategory: Use when you want to group multiple pages under a category in the sidebar
  • Both together: Use withDocCategory for the parent describe and withDocMeta for child describes to create organized documentation sections

Adding Docusaurus Page Metadata​

Docusaurus supports markdown front matter to allow for more control of pages and to help position links in the sidebar.

To add this metadata to the test2doc markdown files that are generated, use the withDocMeta function in your describe blocks in your test.

Using withDocMeta function will create a new markdown file. Nested describe blocks inside will generate header tags within that markdown file:

  • First level nested describe → ## Header (h2)
  • Second level nested describe → ### Header (h3)
  • And so on...

Example test file​

import { withDocMeta } from "@test2doc/playwright/DocMeta";

...

describe(withDocMeta("Title of Page", {
  title: "Title in Sidebar",
  sidebar_position: 1,
  ...
  }), () => {
    test("test block", () => {
      ...
    })
  })

Example generated markdown​

---
title: Title in Sidebar
sidebar_position: 1
---
# Title in Sidebar

## test block

Adding Docusaurus Category Routes​

Docusaurus supports grouping docs by category.

By using the withDocCategory function for a describe block's title, this will add the metadata to allow Test2Doc to generate a new directory and a _category_.json file. It will then place all subsequent generated files within the describe block under this new route.

Example test​

import { withDocCategory, withDocMeta } from "@test2doc/playwright/DocMeta";
...

describe(withDocCategory("Title of Category Route", {
  label: "Category Sidebar Label",
  position: 1,
  className: "class-to-add-on-sidebar-label",
  ...
  }),
  () => {
    describe(withDocMeta("Title of Page in Category", {
      title: "Title in Sidebar under Category",
      sidebar_position: 1,
      ...
      }), () => {
        test("test block", () => {
          ...
        })
      })
  })

Example directory structure​

doc/docs/
├─ test2doc-title-of-category-route/
│  ├─ _category_.json
│  └─ test2doc-title-of-page-in-category.md

Example _category_.json​

{
  "label": "Category Sidebar Label",
  "position": 1,
  "className": "class-to-add-on-sidebar-label"
}

Example generated markdown (test2doc-title-of-page-in-category.md)​

---
title: Title in Sidebar under Category
sidebar_position: 1
---
# Title of Page in Category

## test block

Tips​

  • Ensure describe block titles are meaningful - they become your page titles and headers
  • Avoid deeply nesting categories (2-3 levels recommended for readability)
  • The metadata object accepts any valid Docusaurus frontmatter properties