= Asciidoctor Tools
:version: 20200501
:toc: left
:toclevels: 5
:highlightjs-theme: monokai
:imagesdir: docs/images
:tylesheet: foo.css
:max-width: 20000px
:themes:

== Two Minutes Short Version

In order to get asciidoctor source code rendered within your browser do this:

. Install the Asciidoctor extension:

    - Chrome, Opera: https://chrome.google.com/webstore/search/asciidoctor
    - Firefox: https://addons.mozilla.org/de/firefox/addon/asciidoctorjs-live-preview/ 

. Download addon script for themes and sidebar TOC: `wget https://raw.githubusercontent.com/axiros/adoctools/master/browser/ax-adoc-chrome.js`

. Configure extension to use it (right click -> options):

    - Custom attributes: *source-highlighter=highlight.js toc=left*
    - Safe mode: *unsafe*
    - Enable the diagram extension: *checked*
    - Poll for changes: *1s* To local files
    - Server URL: *https://kroki.io* (or your company diagram rendering server, ask your admin)
    - JavaScript: *ax-adoc-chrome* (click the Add a JavaScript Button, point to the downloaded file)
    - Load the JavaScript…: *before the document has been rendered*
    - image:https://raw.githubusercontent.com/axiros/adoctools/master/docs/images/cfg.png[]

. *Allow access to file URLs* in the Extension management of Chrome, if you want to render file URLs.
. Done.


== Changelog

- 20200501: Pages toc support, below sections toc.
[%collapsible]
====
Simply include it at the end of your docs, after a specific separator:

[source, adoc]
----
==      ─────

== <<intro#,icon:file[] Introduction>>
== <<operators#,icon:file[] Operator Mechanics>>
(...)
----

Key is the separator.
====

- 20200427: Overwriting `white-space: pre wrap` for boot styles code boxes to `pre`, in order to not have ascii drawings wrapped on narrow screens.

=== Installation

1. Download script into any local directory:

[source,bash]
----
wget https://raw.githubusercontent.com/axiros/adoctools/master/browser/ax-adoc-chrome.js
----

2. Configure the extension to use it:

[cols="1,1"]
.Extension config
|===
|image:cfg1.png[]
|image:cfg.png[]
|===

NOTE: We set `toc=left` always, this is optional.

Thats it. You get two theme selector boxes, one for code style and one for the asciidoctor skin.

.Examples (raw view of .adoc sources in the browser with varying selected themes)
|===
|image:ex_ma_teal.png[dark, 400]| image:ex_noteboo.png[dark, 400]
|image:ex_boot_sl.png[dark, 400]| image:ex_gazette.png[dark, 400]
|image:fed.png[fedora, 400]     | image:dark.png[dark, 400]
|===

or

image:graphs.png[graphs, 400]

* You have quite a few variations regarding style - see link:server/asciidoctor/index.txt[here].
* All adoc themes taken from https://github.com/darshandsoni/asciidoctor-skins[darshandsoni/asciidoctor-skins], unmodified (but a bit tweaked using our JS, e.g. for the side toc)
* All code themes from https://highlightjs.org[hilightjs]

TIP: To cycle through themes, hit `Alt-s` or `Alt-c` to focus, then arrow up or down.

=== Configuration

None - the file works standalone. Adapt the link:browser/ax-adoc-chrome.js[source] to your liking.

=== Security

* The file is injected as page script by the extension, i.e. has the same restrictions as any javascript.
* The extension does not offer a messaging channel currently, i.e. there is no communication with the extension. Means we cannot modify the source *before* rendering - only the HTML after rendering, like any javascript.

NOTE: Nevertheless we hook in in _prerender_ phase, in order to see set attributes while we have the source.



== Extended Version / Details

While code documentation generation and publishing to e.g. Github pages, using static page generation tools, it is often desirable to get docu rendered directly within the repository browser:

- You do not need to set up a build pipeline only to get documentation online
- Version support is being delivered by definition (since yes, docu should stay with the code)
- Access control is already set up for the code browser, so comes out of the box. This is not always desired but in most cases it is, especially when docu links directly into the source.


Repo browsing frontends often do support limitted rendering of common text formats, like `.md`, `.rst` or, as you can see, also asciidoctor, `.adoc`.

This project tries to help make the viewing experience a bit better, for the https://asciidoctor.org/docs/asciidoc-syntax-quick-reference[`.adoc` format].


== Intro into the Subject: The Asciidoctor Browser Extension

When you see raw https://asciidoctor.org[asciidoctor] source in your browser, then either you are viewing a local file or the server did not render it:

[frame=topbot]
image::adocraw.png[asciidoc raw, 400 role=related thumb right]

What you probably *want* to see instead is something like this:

[frame=sides]
image::rendered.png[asciidoc rendered,400]


This comes to rescue: +
https://github.com/asciidoctor/asciidoctor-browser-extension[asciidoctor/asciidoctor-browser-extension: An extension for web browsers that converts AsciiDoc files to HTML using Asciidoctor.js.]

As described there, the extension is available for chrome, ff and opera.

IMPORTANT: Install the extension and your *browser* will take care of the rendering, using a javascript port of asciidoctor.

NOTE: In repository browsers, you have to view the page as raw in order to get it rendered. +
Means: Click the `raw view` button. +
On github:
:image:raw.png[raw, 60]



== This Custom Script

=== Added Value 

The extension allows to hook in custom javascript.

This repo provides such a script, which adds support for

- Fixed sidebar TOC (`:toc: left`) support - i.e. a table of contents on the left side. Rather useful for longer documents.
- A https://darshandsoni.com/asciidoctor-skins/screenshots/[bigger] variety of default themes
- Theme switchers (via: `:theme:`) and query string support for a suggested theme: (via `?theme=<theme name>`)
- Any code https://highlightjs.org/[hilightjs] theme
- Handling revisioned browsing also for repo viewers which have the revision in the query string instead of the path (which effectively disables relative links w/o that feature).
- Toc logo (`:toclogo: <url>`) 

==== Details

===== Toc Logo

Inserted before the TOC title. Choose an svg/png with transparent background.

`:toclogo: https://static.foo.com/images/mylogo.svg`


===== Link Rewrites for Revisioned Browsing

If the document specifies `:qsappend: local` or the query string contains `qsappend=local` then we'll rewrite all hrefs and src attributes of the DOM, with a query string parameter added, like at page load, provided that the hostname of the link is identical to the one at page load.

That erradicates the need to adapt all links to the hosting environment (looking at _you_, bitbucket).

Example:

.(page is at ".../docs/index.adoc?&at=refs%2Fheads%2Ffeature%2Fcontainers")
|===
|Source contains | "link: ./install.adoc?foo=bar"
|Rendered | "https://my.bitbucket.com/myproject/raw/docs/install.adoc?foo=bar"
|Rewritten | "https://my.bitbucket.com/myproject/raw/docs/install.adoc?&foo=bar&at=refs%2Fheads%2Ffeature%2Fcontainers"
|===

NOTE: This not necessary for sane repo browsers, with the revision in the path, like Github or Gitlab.


===== Tweaks for Bootstrap Based Styles

Bootstrap has nice stylesheets but they sometimes collide for document viewing use cases. We adapted their CSS accordingly.


=== Known Problems / TODOs

==== Sandboxed mode

Some servers deliver the source in sandboxed mode - e.g. github(!). Then the custom JS is running limitted:

.console output
[source]
----
Blocked script execution in 'https://raw.githubusercontent.com/asciidoctor/asciidoctor-browser-extension/master/README.adoc' because the document's frame is sandboxed and the 'allow-scripts' permission is not set.
----

Fortunatelly at least the syncronous style rewrites necessary for the side toc do work:

E.g. for https://raw.githubusercontent.com/axiros/adoctools/master/README.adoc[this document] you get something like:


image:gh.png[gh, 400]

https://raw.githubusercontent.com/asciidoctor/asciidoctor.org/master/docs/_includes/table-formatting.adoc[Here] is another example to try - again you should see the sidebar toc:


image:ex2.png[example2, 400]

We can *not* inject custom styles into the document though, i.e. the page will be rendered using the style which is configured in the extension incl. its code style.

==== No TOC

When the original document does not set a toc attribute, we do not produce one (did not want to manually recurse over Hx tags in the DOM).

Solution: Configure `toc=left` in the Extension, like suggested in the screenshot above, i.e. tell asciidoctor to always produce one.

==== Sporadic Rendering Errors

Some styles do not define all attributes, especially the bootstrap derived ones.
Then your extension's set stylesheet's css "leaks" into the document, since we cannot prevent the extension to insert the default stylesheet before we overwrite.

Workaround: Set the extension stylesheet to a rather neutral one, matching your preferences.


==== binread error

Do not use data-uri=true as attribute in the config.

==== No offline mode

Requires access to server.

Currently the script is not storing the themes locally explicitely, but pulls them from a configurable server (default: This github repo), which would not work offline.

Workaround: You can throw them on any static webserver within your premises or on your localhost. Configuration is in the source of this script:

[source,javascript]
----
var SERVER_URL = <your url>
----

CAUTION: Reload the script within the extension config after changes.


