Docfy
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

Sidebar Navigation

Edit this demo

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

Edit this demo

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.

On this page: 
<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>

Edit this page

Edit this demo

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.

For this to work, you need to include repository in your docfy-config:

// in your docfy-config.js
module.exports = {
  repository: {
    url: 'https://github.com/@username/repo-name',
    editBranch: 'main',
  },
  ...// rest of your config
}

Enterprise (aka on premise) git services

page.editUrl works for Github, Bitbucket, Gitlab and Sourcehut.

For on-premise instances git solutions (i.e. on-premise Gitlab, or on-premise Bitbucket), we expose the page.relativePath so that you might construct your own custom editUrl:

<DocfyOutput @fromCurrentURL={{true}} as |page|>
  {{#if page.relativePath}}
    <a href=(concat "http://some-enterpise.com/browse/" page.relativePath)
      Click here to edit this page
    </a>
  {{/if}}
</DocfyOutput>

Note: the edit url for your on-premise instance might be more complex than the example above. But the page.relativePath will give you the relative path to that file in your repo.

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

Top Navigation

Edit this demo

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>

Flat output

Edit this demo

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
Edit this page on GitHub
Writing Demos
<DocfyLink>