<commit_before>image:https://travis-ci.org/jenkinsci/doktor-plugin.svg?branch=master["Build Status", link="https://travis-ci.org/jenkinsci/doktor-plugin"]

= Doktor

Doktor is a Jenkins plugin for automated documentation uploading to Confluence.

== Usage

=== Features

==== Supported formats

Doktor supports https://daringfireball.net/projects/markdown/syntax[Markdown] and http://asciidoc.org[AsciiDoc].
Markdown support is provided by awesome https://github.com/vsch/flexmark-java[flexmark-java] library.
AsciiDoc is supported thanks to https://github.com/asciidoctor/asciidoctorj[AsciidoctorJ].
Please note that AsciiDoc support is very experimental.

==== Front matter

_Front matter_ is another word for _metadata_, used by bloggers and hipsters widely.
Doktor uses front matter to configure the way pages appear in Confluence.

===== Markdown

Doktor supports http://www.yaml.org[YAML] front matter in your Markdown files.
Front matter looks like a small YAML fragment at the beginning of the file, separated by a triple minus sign (`---`) in this case:

[source,yml]
----
---
key: value
---
----

===== AsciiDoc

Doktor supports http://www.yaml.org[YAML] front matter in your AsciiDoc files as well.
Front matter looks like a small YAML fragment at the beginning of the file, separated by a triple minus sign (`---`) in this case.
Note, that due to a more strict YAML parser logic for AsciiDoc, strings with special characters need to be quoted:

[source, asciidoc]
----
---
key: value
key_with_specials: 'value: with specials'
---
----

===== Supported front matter attributes:

`title`::
Required.
Page title, unsurprisingly.

`parent`::
Optional.
Parent page title, if any.
If omitted, https://confluence.atlassian.com/doc/orphaned-pages-139542.html["orphaned" page] will be created.
If parent page is not found by title, child page will not be created at all.

`labels`::
Optional.
List of labels to add to a page.

==== Tables

===== Markdown

Though Markdown does not have any support for tables, Doktor supports https://help.github.com/articles/organizing-information-with-tables[GitHub Flavored Markdown tables].
You can also create tables by inlining XHTML markup directly in your docs.

===== AsciiDoc

AsciiDoc (thus Asciidoctor and AsciidoctorJ) http://asciidoctor.org/docs/user-manual/#tables[supports tables natively].

==== Images

Doktor supports images.
When an image is referred by relative URL it will be uploaded to a Confluence server as an attachment of a page, given unique name.
When an image is referred by remote URL (Internet link) it will be referred by this URL from a Confluence server.

===== Markdown

https://daringfireball.net/projects/markdown/syntax#img[Markdown syntax] for images:

[source, markdown]
----
![Millennium Falcon](./millennium_falcon.png "The Millennium Falcon, Han Solo's most prized possession")
----

===== AsciiDoc

Images look like http://asciidoctor.org/docs/asciidoc-writers-guide/#images[this] is AsciiDoc:

[source, asciidoc]
----
.The Millennium Falcon, Han Solo's most prized possession
[link=http://starwars.wikia.com/wiki/Millennium_Falcon]
image::./millennium_falcon.png[Millennium Falcon,400,float="right",align="center"]
----

As you see, AsciiDoc is more feature-rich.

==== Diagrams

Diagrams are only supported in AsciiDoc, the markup looks like this:

[seqdiag]
....
seqdiag {
  // normal edge and doted edge
  A -> B [label = "normal edge"];
  B --> C [label = "dotted edge"];

  B <-- C [label = "return dotted edge"];
  A <- B [label = "return edge"];

  // asynchronus edge
  A ->> B [label = "asynchronus edge"];
  B -->> C [label = "asynchronus dotted edge"];

  B <<-- C [label = "return asynchronus doted edge"];
  A <<- B [label = "return asynchronus edge"];

  // self referenced edge
  A -> A [label = "self reference edge"];
}
....

The snippet above will be rendered in this image:

image::https://github.com/madhead/doktor/blob/master/.github/images/seqdiag.png[]

Read more about diagram syntax in http://asciidoctor.org/docs/asciidoctor-diagram[in the official AsciiDoc guide].
Be warned, that most types of diagrams require external tools (like `seqdiag` or `dot`) to be installed and available on the `PATH`.

Currently, these diagrams are supported:

 - `actdiag` / `blockdiag` / `nwdiag` / `packetdiag` / `rackdiag` / `seqdiag`.
These diagrams require http://blockdiag.com[`blockdiag`] and related Python packages to be available on the `PATH`.
 - http://ditaa.sourceforge.net[`ditaa`].
No additional tools needed.
 - `graphviz`.
Obviously, requires http://www.graphviz.org[Graphviz] tool to be on the `PATH`.
 - `mermaid`
Requires https://mermaidjs.github.io[mermaid] (version prior to `7.x`) and http://phantomjs.org[PhantomJS] to be on the `PATH`.
 - http://plantuml.com[`plantuml`]
No additional tools needed.

=== Configure Confluence servers

As you might suspect, Confluence REST API requires authentication.
Doktor supports basic authentication (username and password).
So, first thing to do is to https://github.com/jenkinsci/credentials-plugin/blob/master/docs/user.adoc[configure credentials] in Jenkins.

Create a "Username with password" credentials to be used to authenticate on Confluence server:

image::https://github.com/madhead/doktor/blob/master/.github/images/new_credentials.png[]

You may have as many Confluence servers and credentials for them as you need.

Next thing to do is to configure Confluence servers.
Go to global configuration screen ("Manage Jenkins" -> "Configure System") and find "Confluence Servers" section.
Configure the list of available Confluence servers:
<commit_msg>Add a few lines about custom stylesheets / selectors<commit_after>image:https://travis-ci.org/jenkinsci/doktor-plugin.svg?branch=master["Build Status", link="https://travis-ci.org/jenkinsci/doktor-plugin"]

= Doktor

Doktor is a Jenkins plugin for automated documentation uploading to Confluence.

== Usage

=== Features

==== Supported formats

Doktor supports https://daringfireball.net/projects/markdown/syntax[Markdown] and http://asciidoc.org[AsciiDoc].
Markdown support is provided by awesome https://github.com/vsch/flexmark-java[flexmark-java] library.
AsciiDoc is supported thanks to https://github.com/asciidoctor/asciidoctorj[AsciidoctorJ].
Please note that AsciiDoc support is very experimental.

==== Front matter

_Front matter_ is another word for _metadata_, used by bloggers and hipsters widely.
Doktor uses front matter to configure the way pages appear in Confluence.

===== Markdown

Doktor supports http://www.yaml.org[YAML] front matter in your Markdown files.
Front matter looks like a small YAML fragment at the beginning of the file, separated by a triple minus sign (`---`) in this case:

[source,yml]
----
---
key: value
---
----

===== AsciiDoc

Doktor supports http://www.yaml.org[YAML] front matter in your AsciiDoc files as well.
Front matter looks like a small YAML fragment at the beginning of the file, separated by a triple minus sign (`---`) in this case.
Note, that due to a more strict YAML parser logic for AsciiDoc, strings with special characters need to be quoted:

[source, asciidoc]
----
---
key: value
key_with_specials: 'value: with specials'
---
----

===== Supported front matter attributes:

`title`::
Required.
Page title, unsurprisingly.

`parent`::
Optional.
Parent page title, if any.
If omitted, https://confluence.atlassian.com/doc/orphaned-pages-139542.html["orphaned" page] will be created.
If parent page is not found by title, child page will not be created at all.

`labels`::
Optional.
List of labels to add to a page.

==== Tables

===== Markdown

Though Markdown does not have any support for tables, Doktor supports https://help.github.com/articles/organizing-information-with-tables[GitHub Flavored Markdown tables].
You can also create tables by inlining XHTML markup directly in your docs.

===== AsciiDoc

AsciiDoc (thus Asciidoctor and AsciidoctorJ) http://asciidoctor.org/docs/user-manual/#tables[supports tables natively].

==== Images

Doktor supports images.
When an image is referred by relative URL it will be uploaded to a Confluence server as an attachment of a page, given unique name.
When an image is referred by remote URL (Internet link) it will be referred by this URL from a Confluence server.

===== Markdown

https://daringfireball.net/projects/markdown/syntax#img[Markdown syntax] for images:

[source, markdown]
----
![Millennium Falcon](./millennium_falcon.png "The Millennium Falcon, Han Solo's most prized possession")
----

===== AsciiDoc

Images look like http://asciidoctor.org/docs/asciidoc-writers-guide/#images[this] is AsciiDoc:

[source, asciidoc]
----
.The Millennium Falcon, Han Solo's most prized possession
[link=http://starwars.wikia.com/wiki/Millennium_Falcon]
image::./millennium_falcon.png[Millennium Falcon,400,float="right",align="center"]
----

As you see, AsciiDoc is more feature-rich.

==== Diagrams

Diagrams are only supported in AsciiDoc, the markup looks like this:

[seqdiag]
....
seqdiag {
  // normal edge and doted edge
  A -> B [label = "normal edge"];
  B --> C [label = "dotted edge"];

  B <-- C [label = "return dotted edge"];
  A <- B [label = "return edge"];

  // asynchronus edge
  A ->> B [label = "asynchronus edge"];
  B -->> C [label = "asynchronus dotted edge"];

  B <<-- C [label = "return asynchronus doted edge"];
  A <<- B [label = "return asynchronus edge"];

  // self referenced edge
  A -> A [label = "self reference edge"];
}
....

The snippet above will be rendered in this image:

image::https://github.com/madhead/doktor/blob/master/.github/images/seqdiag.png[]

Read more about diagram syntax in http://asciidoctor.org/docs/asciidoctor-diagram[in the official AsciiDoc guide].
Be warned, that most types of diagrams require external tools (like `seqdiag` or `dot`) to be installed and available on the `PATH`.

Currently, these diagrams are supported:

 - `actdiag` / `blockdiag` / `nwdiag` / `packetdiag` / `rackdiag` / `seqdiag`.
These diagrams require http://blockdiag.com[`blockdiag`] and related Python packages to be available on the `PATH`.
 - http://ditaa.sourceforge.net[`ditaa`].
No additional tools needed.
 - `graphviz`.
Obviously, requires http://www.graphviz.org[Graphviz] tool to be on the `PATH`.
 - `mermaid`
Requires https://mermaidjs.github.io[mermaid] (version prior to `7.x`) and http://phantomjs.org[PhantomJS] to be on the `PATH`.
 - http://plantuml.com[`plantuml`]
No additional tools needed.

==== Custom stylesheets

Confluence allows space admins to provide custom stylesheets that override globals.
Doktor supports styling generated content by wrapping it in a `<div class="doktor">`, so you can use `.doctor` prefix in your selector to stylize content.

=== Configure Confluence servers

As you might suspect, Confluence REST API requires authentication.
Doktor supports basic authentication (username and password).
So, first thing to do is to https://github.com/jenkinsci/credentials-plugin/blob/master/docs/user.adoc[configure credentials] in Jenkins.

Create a "Username with password" credentials to be used to authenticate on Confluence server:

image::https://github.com/madhead/doktor/blob/master/.github/images/new_credentials.png[]

You may have as many Confluence servers and credentials for them as you need.

Next thing to do is to configure Confluence servers.
Go to global configuration screen ("Manage Jenkins" -> "Configure System") and find "Confluence Servers" section.
Configure the list of available Confluence servers:

{'fraction_non_alphanumeric': 0.11652505635512399, 'fraction_numerical': 0.0017340038148083927, 'mean_word_length': 4.33780657103193, 'pattern_counts': {'":': 0, '<': 16, '<?xml version=': 0, '>': 20, 'https://': 24, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1292968', 'n_tokens_mistral': 3607, 'n_tokens_neox': 3404, 'n_words': 1284}