Skip to content

Commit

Permalink
Format README
Browse files Browse the repository at this point in the history
  • Loading branch information
vrugtehagel committed Jun 16, 2024
1 parent 8c86f92 commit 6524b79
Showing 1 changed file with 34 additions and 20 deletions.
54 changes: 34 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,49 +19,63 @@ deno add @vrugtehagel/eleventy-document-outline

## Config

In your Eleventy configuration file (usually `.eleventy.js`), import/require the module and add the plugin using `.addPlugin()`:
In your Eleventy configuration file (usually `.eleventy.js`), import/require the
module and add the plugin using `.addPlugin()`:

```js
import EleventyDocumentOutline from 'eleventy-document-outline';

export default function(eleventyConfig){
//
eleventyConfig.addPlugin(EleventyDocumentOutline, {
headers: ['h1', 'h2', 'h3'],
});
//
import EleventyDocumentOutline from "eleventy-document-outline";

export default function (eleventyConfig) {
//
eleventyConfig.addPlugin(EleventyDocumentOutline, {
headers: ["h1", "h2", "h3"],
});
//
}
```

As shown above, there are additional options one may pass as second argument to the `.addPlugin()` call, as an object. It may have the following keys:
As shown above, there are additional options one may pass as second argument to
the `.addPlugin()` call, as an object. It may have the following keys:

- `headers`: an array of headers to include in the document outline. By default, this is set to `['h1', 'h2', 'h3']`. Note that this can be overwritten on a case-by-case basis in the `{% outline %}` shortcode.
- `output`: a function receiving a single argument `{ id, text, header }`. The function must return a snippet of HTML to output. By default, this is
- `headers`: an array of headers to include in the document outline. By default,
this is set to `['h1', 'h2', 'h3']`. Note that this can be overwritten on a
case-by-case basis in the `{% outline %}` shortcode.
- `output`: a function receiving a single argument `{ id, text, header }`. The
function must return a snippet of HTML to output. By default, this is

```js
function output({ id, text, header }){
return `<a href="#${id}" class="link-${header}">${text}</a>`;
function output({ id, text, header }) {
return `<a href="#${id}" class="link-${header}">${text}</a>`;
}
```

Which means the options are rendered as sibling anchor tags. The function runs once per header found, in the same order that they are found in the document. The `id` then matches the `id` attribute of the given header, the `header` matches the `.localName` (i.e. lowercased `.tagName`) and the `text` is the text found inside the header.
Which means the options are rendered as sibling anchor tags. The function runs
once per header found, in the same order that they are found in the document.
The `id` then matches the `id` attribute of the given header, the `header`
matches the `.localName` (i.e. lowercased `.tagName`) and the `text` is the text
found inside the header.

## Usage

To output the list of links, use the `{% outline %}` shortcode like so:

```liquid
<nav id="doc-outline">
{% outline "h2", "h3" %}
</nav>
<nav id="doc-outline">
{% outline "h2", "h3" %}
</nav>
```

In this case, only the `h2` and `h3` elements (with `id` attributes) are included in the outline. If the arguments are left out, as in `{% outline %}`, then the default headers as configured are used (if not explicityly configured, only `h1`, `h2` and `h3` elements are included).
In this case, only the `h2` and `h3` elements (with `id` attributes) are
included in the outline. If the arguments are left out, as in `{% outline %}`,
then the default headers as configured are used (if not explicityly configured,
only `h1`, `h2` and `h3` elements are included).

### Excluding a header

To exclude a header, add a `data-outline-ignore` attribute to it.

### Generating header ids

This plugin does not automatically generate `id` attributes for your headers. If this is something you want or need, use a separate plugin to generate them, such as e.g. [markdown-it-anchor](https://www.npmjs.com/package/markdown-it-anchor).
This plugin does not automatically generate `id` attributes for your headers. If
this is something you want or need, use a separate plugin to generate them, such
as e.g. [markdown-it-anchor](https://www.npmjs.com/package/markdown-it-anchor).

0 comments on commit 6524b79

Please sign in to comment.