Skip to content

Commit

Permalink
Separate use-cases, quick start pages: (#652) (#654) (#659)
Browse files Browse the repository at this point in the history
  • Loading branch information
sturtison authored Oct 20, 2023
1 parent ba24f5a commit fb26526
Show file tree
Hide file tree
Showing 8 changed files with 269 additions and 244 deletions.
2 changes: 2 additions & 0 deletions changelog.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

== Unreleased

* Docs: reorganize use-cases to separate page, try-it-yourself to a quickstart page, diagrams try-it-yourself to a diagrams quickstart page (#652) (#654)

== 2.7.1 (2023-06-03)

* Add `accept` header when fetching AsciiDoc content (mainly to workaround an issue on github.com)
Expand Down
5 changes: 4 additions & 1 deletion docs/modules/ROOT/nav.adoc
Original file line number Diff line number Diff line change
@@ -1,9 +1,12 @@
* xref:install.adoc[]
* xref:quickstart.adoc[]
* xref:features.adoc[]
* xref:options.adoc[]
** xref:custom-attributes-option.adoc[]
** xref:diagrams-extension-option.adoc[]
** xref:theme-stylesheet-option.adoc[]
** xref:javascript-option.adoc[]
** xref:load-the-javascript-option.adoc[]
* xref:firefox-known-issues.adoc[Known issues]
* xref:diagrams-extension-quickstart.adoc[]
* xref:use-cases.adoc[]
* xref:firefox-known-issues.adoc[Known issues]
2 changes: 1 addition & 1 deletion docs/modules/ROOT/pages/custom-attributes-option.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ See section xref:features.adoc#set-asciidoc-attributes[Set AsciiDoc attributes]

== Use cases

For more ideas and use cases for setting attributes, see section xref:features.adoc#use-cases[Use cases] on the features page.
For more ideas and use cases for setting attributes, see the xref:use-cases.adoc[] page.

== AsciiDoc Attributes

Expand Down
91 changes: 25 additions & 66 deletions docs/modules/ROOT/pages/diagrams-extension-option.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -2,25 +2,29 @@
:navtitle: Diagrams extension
:keywords: kroki,diagrams like code,diagrams

With the extension option *Diagrams extension* you can embed diagrams in your AsciiDoc files as text based descriptions using the https://kroki.io[Kroki.io] online service.
On this page you will learn:

The Kroki server (default or custom) converts the text to its corresponding image.
You do not need any other software installed on your machine or browser.
* [x] about the diagrams extension
* [x] about Kroki
* [x] how to configure the extension option *Diagrams extension*
* [x] a simple example
On this page you will find:
For a more complex example, see the xref::diagrams-extension-quickstart.adoc[] page.

* [x] how to configure the extension option *Diagrams extension*
* [x] an example
* [x] a try-it-yourself example.
== Use Kroki via the diagrams extension

With the extension option *Diagrams extension* you can embed diagrams in your AsciiDoc files as text based descriptions using the https://kroki.io[Kroki.io] online service.

The Kroki server (default or custom) converts the text to its corresponding image with no extra software installed on your machine or browser.

To learn more about diagrams from text based descriptions and "diagrams like code", visit https://kroki.io.

== Diagrams extension options

There are two options for the diagrams extension:
The two options of the diagrams extension are:

* Enable the diagrams extension
* The Server URL
* Enabled or disabled
* Kroki Server URL

=== Enable the diagrams extension

Expand Down Expand Up @@ -60,8 +64,17 @@ Diagrams from text in general enables further documentation automation.
The benefits of running Kroki locally, or installing it on your own infrastructure are:

* Diagram conversion traffic remains inside your organization

* Depending on the diagram generator used, you may standardise diagram themes for consistency across your organization without changing source diagrams

=== Security, diagrams and Kroki

Using Kroki via the diagrams extension removes the need to install and maintain diagramming software on individual machines, centralising their deployment to a central Kroki server.

To satisfy security policies, organizations may choose to deploy a Kroki service within their own network.

=== Learn more Kroki

Learn more about installing Kroki at https://kroki.io

== Example diagram
Expand All @@ -83,60 +96,6 @@ digraph { rankdir=LR a -> b -> c}

For more information about embedding diagrams as text and GraphViz diagrams, visit https://kroki.io and https://graphviz.org.

== Try it yourself

Below is an example diagram showing communication between the Diagrams extension and the Kroki.io server set by the *Server URL* in xref:options.adoc[].

You'll create the AsciiDoc file that both holds and displays the diagram when viewed with the {project-name}.

The diagram below uses the PlantUML diagram generator.
To learn more about embedding diagrams, other diagram languages and PlantUML, visit https://kroki.io and https://plantuml.com.

.Diagrams extension sequence
image::diagrams-extension-sequence.svg[]

To create the above diagram after installing the {project-name}, do the following:

. Create a file "diagram-extension-example.adoc" with the following contents:
+
.diagram-extension-example.adoc
[,asciidoc]
----
= Diagrams extension example with Kroki.io
The sequence diagram is below:
[plantuml]
....
@startuml
entity "Local or remote file" as file
box Browser #white
participant Browser as browser
participant "Asciidoctor\nBrowser Extension" as extension
box "Kroki Server" #white
participant "Kroki Gateway" as kroki
participant "Diagram generator" as generator
end box
file -> browser : AsciiDoc
browser -> extension : AsciiDoc
activate extension
extension -> kroki : encoded diagram text
kroki -> generator : diagram text
kroki <- generator : image
extension <- kroki : image
browser <- extension : HTML5
deactivate extension
@enduml
....
----

. Enable the Diagrams extension with the default *Server URL* from the extension options.
For help enabling and disabling the Diagrams extension, see the xref:options.adoc[] page.

. Open or reload the above file in the browser to see the diagram.

. Modify the diagram text in the AsciiDoc and reload the page to see your updated diagram.
== Quickstart

. Disable the Diagrams extension.
+
IMPORTANT: Disable the Diagrams extension to stop communication with the *Server URL*.
To try it your yourself, visit the xref::diagrams-extension-quickstart.adoc[] page.
64 changes: 64 additions & 0 deletions docs/modules/ROOT/pages/diagrams-extension-quickstart.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
= Diagrams extension quickstart

In this quick start you'll:

* [x] create an AsciiDoc file that both holds and displays a diagram when viewed with the {project-name}
* [x] configure the extension to use Kroki
* [x] view the converted diagram
* [x] stop the extension using Kroki
Below is an example diagram showing communication between the Diagrams extension and the Kroki.io server set by the *Server URL* in xref:options.adoc[].

.Diagrams extension sequence
image::diagrams-extension-sequence.svg[]

The diagram above uses the PlantUML diagram generator via Kroki.
To learn more about embedding diagrams, other diagram languages and PlantUML, visit https://kroki.io and https://plantuml.com.

== Steps

To create the above diagram after installing the {project-name}, do the following:

. Create a file "diagram-extension-example.adoc" with the following contents:
+
.diagram-extension-example.adoc
[,asciidoc]
----
= Diagrams extension example with Kroki.io
The sequence diagram is below:
[plantuml]
....
@startuml
entity "Local or remote file" as file
box Browser #white
participant Browser as browser
participant "Asciidoctor\nBrowser Extension" as extension
box "Kroki Server" #white
participant "Kroki Gateway" as kroki
participant "Diagram generator" as generator
end box
file -> browser : AsciiDoc
browser -> extension : AsciiDoc
activate extension
extension -> kroki : encoded diagram text
kroki -> generator : diagram text
kroki <- generator : image
extension <- kroki : image
browser <- extension : HTML5
deactivate extension
@enduml
....
----

. Enable the Diagrams extension with the default *Server URL* from the extension options.
For help enabling and disabling the Diagrams extension, see the xref:options.adoc[] page.

. Open or reload the above file in the browser to see the diagram.

. Modify the diagram text in the AsciiDoc and reload the page to see your updated diagram.

. Disable the Diagrams extension.
+
IMPORTANT: Disable the Diagrams extension to stop communication with the *Server URL*.
Loading

0 comments on commit fb26526

Please sign in to comment.