Use Cases

Use cases for typical situations you may encounter.

Add a table of contents (TOC)

Add a TOC to a document written without one, so that it’s easier to navigate and use.

Sometimes documents are written without TOCs for good reason - they may be part of a larger system, or automatically generated. What ever the reason, you can add one using the Asciidoctor Browser Extension.

Problem: A document is not written with a TOC

It’s long. It’s hard to navigate.

Solution: Use Asciidoctor Browser Extension to add a TOC

Add the toc setting depending on your need below:

For all documents viewed, use a common attribute:
```
toc=left
```
For the current document, use a query parameters:
```
?toc=left
```
If editing the document, use this AsciiDoc in the header:
```
:toc: left
```

To remove a TOC that’s already there use toc followed by an exclamation mark (!).

Custom attribute: toc!
Query parameter: ?toc!

Simplify a table of contents

Reduce the TOC heading levels for a simplified view of the document.

Some documents have so many headings and sections that there is too much detail, even in the TOC. While that may be OK for the final purpose, for your purpose you want to change your view of it.

Problem: The number of section levels and headings are many

A simple view of the TOC is needed to understand the document.

Solution: Use the viewer to reduce the TOC heading levels

Attribute toclevels controls the section levels that are included in the TOC, from 1 to 7. Add the toclevels setting depending on your need below:

For all documents viewed, use a common attribute:
```
toclevels=1
```
For the current document, use a query parameters:
```
?toclevels=1
```
If editing the document, use this AsciiDoc in the header:
```
:toclevels: 1
```

To see more detail in the TOC, increase the toclevels value.

Add a simplified table of contents

To combine the use cases of Add a table of contents (TOC) and Simplify a table of contents you can set both toc and toclevels at the same time:

For all documents viewed, set these as common attributes:
```
toc=left toclevels=1
```
For the current document, use these query parameters:
```
?toc=left&toclevels=1
```
If editing the document, use this AsciiDoc in the header:
```
:toc: left
:toclevels: 1
```

Writing with minimal effort

Create and write an AsciiDoc quickly using the Asciidoctor Browser Extension to apply your most commonly used settings.

When taking notes, you just want to write and not add for example settings for the TOC, nice admonition icons and other items.

Objective: Just write, leaving other settings until later if at all

Use the features of Asciidoctor Browser Extension to save time.

Solution: Put commonly used attributes into the Option: Custom Attributes String

For all documents viewed, set this custom attributes option string:

toc=left icons=font experimental source-highlighter=highlight.js

The above Custom attributes options string set the equivalent AsciiDoc attributes below:

AsciiDoc header

= <title>
:toc: left (1)
:icons: font (2)
:experimental: (3)
:source-highlighter: highlight.js (4)

1	A left hand TOC
2	Use Font Awesome for icons and admonition icons
3	Enable GUI macros `btn:[button]` for button `kbd:[control-A]` for `control-A` and `menu:Menu[Item,…]` for select Menu Item …
4	Syntax highlighting with `highlight.js`

Congratulations, you can now have a collection of AsciiDoc notes with minimal effort, and view them with the Asciidoctor Browser Extension.