Various Ways to Preview YAML

Tip

As the use of YAML increases—especially with generative AI prompts—I’ve organized a few preview methods here.

Basic Code Display in Docusaurus

1. If the YAML is short, it’s easier to just write it directly inside the markdown file. In that case, this is sufficient.

View Code

```yaml title='sample1.yaml' showLineNumbers
story-overview:
title: Title
description: 'Description'
prologue-summary:
  description: 'Prologue'
  key-events:
    - Key Event 1
    - Key Event 2
```

sample1.yaml

story-overview:
  title: Title
  description: 'Description'
  prologue-summary:
    description: 'Prologue'
    key-events:
      - Key Event 1
      - Key Event 2

Using the CodeBlock Tag

1. If the YAML is large or you'd like to extract it to a separate file, this method works well.
2. Place the YAML file under the static folder to serve it as a static file in Docusaurus.
3. To import raw text, you’ll need the raw-loader npm package.
   1. pnpm add -D raw-loader
4. Import the YAML file and wrap it with <CodeBlock></CodeBlock> to render it.

View Code

import CodeBlock from '@theme/CodeBlock';
import sampleYaml from '@site/static/data/sample.yaml?raw';

<CodeBlock className='language-yaml' title='sample2.yaml' showLineNumbers>
  {sampleYaml}
</CodeBlock>

/static/data/sample.yaml

story-overview:
  title: 'Title (from static/data/sample.yaml)'
  description: 'Description'
  prologue-summary:
    description: 'Prologue - previewed from static YAML file'
    key-events:
      - Key Event A
      - Key Event B

sample2.yaml

story-overview:
  title: 'title(static/data/sample.yaml)'
  description: 'If you see this, it means sample.yaml is loaded.'
  prologue-summary:
    description: 'Prologue'
    key-events:
      - key event A
      - key event B
  chapter-1:
    title: 'chapter-1'
    description: 'Chapter 1'
    characters:
      - actor 1
      - actor 2

Custom TreeViewer Component

1. YAML files can get lengthy, so I created a custom component to support collapsible display.
2. By default, it collapses content deeper than two levels.
3. Styling (colors and fonts) remains the default from react-json-tree.
   1. Might adjust later if needed.

View Code

import YamlTreeViewer from '@site/src/components/YamlTreeViewer';

<YamlTreeViewer filePath='/data/sample.yaml' expandLevel={3} />

or

<YamlTreeViewer filePath={useBaseUrl('/data/sample.yaml')} expandLevel={3} />

docs/docusaurus/yaml-preview.mdx

/**
Required npm package:
- react-json-tree: `pnpm add -D react-json-tree`
*/
import { useEffect, useState } from 'react';
import { parse } from 'yaml';
import { JSONTree } from 'react-json-tree';

/**
* @param {Object} props
* @param {string} props.filePath         Public URL (useBaseUrl recommended)
* @param {number} [props.expandLevel=2]  Initial depth to expand
*/
export default function YamlTreeViewer({ filePath, expandLevel = 2 }) {
  const [data, setData] = useState(null);
  const [error, setError] = useState(null);

  useEffect(() => {
    fetch(filePath)
    .then((r) => {
      if (!r.ok) throw new Error(`${r.status} ${r.statusText}`);
      return r.text();
    })
    .then((src) => setData(parse(src)))
    .catch((e) => setError(e.message));
  },[filePath]);

  if (error) return <p style={{ color: 'red' }}>Failed to load: {error}</p>;
  if (!data) return <p>Loading…</p>;

  return (
    <div className='yaml-tree'>
    <JSONTree
      data={data}
      hideRoot
      shouldExpandNodeInitially={(_k, _v, lvl) => lvl < expandLevel}
    />
    </div>
  );
}

Loading…

Note

1. react-json-tree is handy but a bit quirky.
2. Even if your original YAML uses single quotes, it will show double quotes on render.
   1. Likely due to the way it's parsed before display—understandable, but not ideal if you want it to look exactly like the source.
3. I’ll deal with any issues as they come up.