GitHub

<DocfyOutput>

This component exposes some of the result data from the build that you can use to render, for example, a sidebar navigation, "on this page" section, and more.

Depending on the arguments you pass to the component, the output could be one of the following values:

  • NestedPageMetadata
  • PageMetadata[]
  • PageMetadata
  • undefined

To learn more about each data type, please refer to the API docs.

Below you can see several examples of what is possible to build using this component.

Examples

In this example, we are filtering the NestedPageMetadata by the scope name docs. Then we use the yielded data to render pages, their children, and their children's pages. Depending on how your documentation is structured, you might need to render more deep into the tree or more shadow.

You might have noticed that for this documentation site, we haven't rendered too deep into the tree to display all items.

<DocfyOutput @scope="docs" as |node|>
  <ul class="list-disc list-inside space-y-2">
    {{#each node.pages as |page|}}
      <li>
        <DocfyLink @to={{page.url}}>
          {{page.title}}
        </DocfyLink>
      </li>
    {{/each}}

    {{#each node.children as |child|}}
      <li class="block ml-4">
        <div class="py-2">
          {{child.label}}
        </div>

        <ul class="list-disc list-inside space-y-2">
          {{#each child.pages as |page|}}
            <li>
              <DocfyLink @to={{page.url}}>
                {{page.title}}
              </DocfyLink>
            </li>
          {{/each}}
        </ul>
      </li>
    {{/each}}
  </ul>
</DocfyOutput>
On this page:

In this example, we are using the option @fromCurrentURL. It tells the component to search for the definition of the page that corresponds to the current URL. We are then using the headings property, a data structure that represents a Table of Content. The headings is a recursive data structure, meaning that you can render their child for subheadings and their sub-subheadings. The depth of headings available here is default to 6 but can be changed using the configuration option tocMaxDepth.

<DocfyOutput @fromCurrentURL={{true}} as |page|>
  <div class="mb-4 font-medium">
    On this page:
  </div>
  <ul class="list-disc list-inside space-y-2">
    {{#each page.headings as |heading|}}
      <li>
        <a href="#{{heading.id}}">
          {{heading.title}}
        </a>
      </li>
    {{/each}}
  </ul>
</DocfyOutput>

This is another example using @fromCurrentURL, but here we build a "edit this page" link.

For this feature to work, Docfy must be able to find the repository URL. In Ember apps, we extract that from the package.json, but you can configure the repository URL as well as the branch to edit.

<DocfyOutput @fromCurrentURL={{true}} as |page|>
  {{#if page.editUrl}}
    <a href={{page.editUrl}}>
      Click here to edit this page
    </a>
  {{/if}}
</DocfyOutput>

Here is another example that builds a top nav that could be used for the entire application. It will link to any top-level pages as well as to the first page of every child.

<DocfyOutput @type="nested" as |node|>
  <ul>
    {{#each node.pages as |page|}}
      <li>
        <DocfyLink @to={{page.url}}>
          {{page.title}}
        </DocfyLink>
     </li>
    {{/each}}

    {{#each node.children as |child|}}
      {{#let (get child.pages 0) as |page|}}
        {{#if page}}
          <li>
            <DocfyLink @to={{page.url}}>
              {{child.label}}
            </DocfyLink>
          </li>
        {{/if}}
      {{/let}}
    {{/each}}
  </ul>
</DocfyOutput>

This option will return an array of PageMetadata. It will contain all the pages in a flat array, one could render a list of all the pages without worrying about the scope.

<DocfyOutput @type="flat" as |pages|>
  <ul class="list-disc list-inside space-y-2">
    {{#each pages as |page|}}
      <li>
        <DocfyLink @to={{page.url}}>
          {{page.title}}
        </DocfyLink>
     </li>
    {{/each}}
  </ul>
</DocfyOutput>

API

This component has a few different options that are used to filter what the returning value should be. Here is the arguments this component accepts.

Argument Description Type Default Value
@type If the result should be a flat list or nested 'flat' | 'nested' 'nested'
@fromCurrentURL If the result should be filtered from the current URL boolean | undefined
@url Find the page definition for the given URL string | undefined
@scope If the result should be filtered by an scope name string | undefined