From 625d7fffbf0329be35cd37b340af9f09fe54354a Mon Sep 17 00:00:00 2001 From: Dmitry Pavlov Date: Sat, 4 Nov 2023 23:45:37 +0400 Subject: [PATCH] Adjusted documentation of markdown features - using tables for side by side comparision --- CONTRIBUTING.md | 5 +- docs/configuration-reference.md | 20 ++-- .../storage-formats/asciidoc/admonitions.adoc | 6 +- docs/storage-formats/asciidoc/basic.adoc | 9 ++ docs/storage-formats/asciidoc/code.adoc | 7 ++ .../asciidoc/confluence-specific.adoc | 6 +- docs/storage-formats/asciidoc/diagrams.adoc | 4 + .../asciidoc/links-images.adoc | 4 +- docs/storage-formats/markdown/basic.md | 99 ++++++++++++++++- docs/storage-formats/markdown/code.md | 72 ++++++++++++ .../markdown/confluence-specific.md | 103 +++++++++++++++++- docs/storage-formats/markdown/diagrams.md | 86 ++++++++++++++- docs/storage-formats/markdown/links-images.md | 38 ++++--- docs/storage-formats/markdown/tables.md | 38 +++++++ docs/user-guide.md | 2 +- docs/user-guide/multitenant.md | 4 +- docs/user-guide/toc-attributes.md | 2 +- 17 files changed, 451 insertions(+), 54 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9a904de4..45cbeaf4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,8 +10,7 @@ occasional code reformatting. ### Rules of thumb for PRs -1. It can be a good idea to start with issue, rather than PR - let's discuss your needs first and then proceed to code - changes. +1. Start with issue, rather than PR - let's discuss your needs first and then proceed to code changes. 2. One PR - one purpose of change. This will simplify review and speed up merges. Avoid doing all the things in one branch that will be a source of one PR. 3. Dependencies - it is fine to add new dependencies if they are required for the purpose of feature you are working @@ -19,7 +18,7 @@ occasional code reformatting. - just for kicks - by replacing specific dependencies with "catch all" deps, (e.g. replacing specific flexmark modules with `flexmark-all`) -4. Small cleanups along the way are fine to do in scope of your main PR, but if you consider something large, like +4. Small cleanups along the way are fine to do in the scope of your main PR, but if you consider something large, like reformatting all the source code or massively renaming some class/term - do it in separate PR. 5. IntelliJ IDEA users - I suggest you to enable "optimize imports" on commit and also reformatting code only for changed lines by default. \ No newline at end of file diff --git a/docs/configuration-reference.md b/docs/configuration-reference.md index 6445983d..f0818199 100644 --- a/docs/configuration-reference.md +++ b/docs/configuration-reference.md @@ -7,13 +7,15 @@ alternatives in command line or env variables format. !!! warning - Keep in mind the lookup order of values: - - 1. command line argument - 2. environment variable - 3. value in `.text2confl.yml` - -| .text2confl.yml | cli option | env variable | description | + Keep in mind the lookup order of values: + + 1. command line argument + 2. environment variable + 3. value in `.text2confl.yml`/`.textconfl.yaml`/`text2confl.yml`/`text2confl.yaml` file (whatever is found first) + + For brevity, we will use `.text2confl.yml` in examples below. + +| configuration file | cli option | env variable | description | |------------------------------|--------------------------------------------|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | server | `--Confluence-url` | `CONFLUENCE_URL` | Address of Confluence server. For Confluence Cloud specify in format `https://YOURSITE.atlassian.net/wiki` | | space | `--space` | `CONFLUENCE_SPACE` | Space where documents will be uploaded. It is not possible to upload docs to multiple spaces in one run | @@ -36,7 +38,7 @@ alternatives in command line or env variables format. ### Markdown configuration options -Markdown can be configured in `.text2confl.yaml` file, in `markdown` section. +Markdown can be configured in `.text2confl.yml` file, in `markdown` section. Table contains available parameters. Dot (`.`) means that this is next level, e.g. @@ -72,7 +74,7 @@ markdown: ### AsciiDoc configuration options -AsciiDoc can be configured in `.text2confl.yaml` file, in `asciidoc` section. +AsciiDoc can be configured in `.text2confl.yml` file, in `asciidoc` section. Table contains available parameters. Dot (`.`) means that this is next level, e.g. diff --git a/docs/storage-formats/asciidoc/admonitions.adoc b/docs/storage-formats/asciidoc/admonitions.adoc index 16014815..9eaa3067 100644 --- a/docs/storage-formats/asciidoc/admonitions.adoc +++ b/docs/storage-formats/asciidoc/admonitions.adoc @@ -9,8 +9,7 @@ Mapping: [cols="a,a"] |=== -| AsciiDoc -| Confluence +| AsciiDoc | Confluence | .... @@ -53,8 +52,7 @@ Short syntax for admonitions works too: [cols="a,a"] |=== -| AsciiDoc -| Confluence +| AsciiDoc | Confluence | .... diff --git a/docs/storage-formats/asciidoc/basic.adoc b/docs/storage-formats/asciidoc/basic.adoc index 1767d28e..b9450d2e 100644 --- a/docs/storage-formats/asciidoc/basic.adoc +++ b/docs/storage-formats/asciidoc/basic.adoc @@ -9,6 +9,7 @@ All basic styling features are supported — text can be: [cols="a,a"] |=== +| AsciiDoc | Confluence | `+*bold*+` | *bold* | `+_italic_+` | _italic_ @@ -26,6 +27,8 @@ You can also use quotation blocks: [cols="a,a"] |=== +| AsciiDoc | Confluence + | ---- include::_assets/example.adoc[tag=style-quotation] @@ -39,6 +42,8 @@ Both numbered and bullet lists are supported: [cols="a,a"] |=== +| AsciiDoc | Confluence + | ---- include::_assets/example.adoc[tag=style-list] @@ -52,6 +57,8 @@ This will work: [cols="a,a"] |=== +| AsciiDoc | Confluence + | ---- include::_assets/example.adoc[tag=style-tasklist-ok] @@ -63,6 +70,8 @@ But this will not work: [cols="a,a"] |=== +| AsciiDoc | Confluence + | ---- include::_assets/example.adoc[tag=style-tasklist-bad] diff --git a/docs/storage-formats/asciidoc/code.adoc b/docs/storage-formats/asciidoc/code.adoc index afa390c2..46d0e880 100644 --- a/docs/storage-formats/asciidoc/code.adoc +++ b/docs/storage-formats/asciidoc/code.adoc @@ -12,6 +12,7 @@ Code blocks are also supported including callouts [cols="a,a"] |=== +| AsciiDoc | Confluence | [listing,subs="none"] @@ -26,6 +27,7 @@ Callouts in xml and similar markup supported too: [cols="a,a"] |=== +| AsciiDoc | Confluence | [listing,subs="none"] @@ -61,6 +63,7 @@ Other attributes are Confluence specific. [cols="a,a"] |=== +| AsciiDoc | Confluence | [listing,subs="none"] @@ -77,6 +80,8 @@ Literal blocks are converted as pre-formatted text. [cols="a,a"] |=== +| AsciiDoc | Confluence + | ---- .... @@ -94,6 +99,7 @@ Same is applied to literal line (one prepended with space) [cols="a,a"] |=== +| AsciiDoc | Confluence | ---- @@ -109,6 +115,7 @@ Listing blocks are converted using the `noformat` macro. [cols="a,a"] |=== +| AsciiDoc | Confluence | [listing] diff --git a/docs/storage-formats/asciidoc/confluence-specific.adoc b/docs/storage-formats/asciidoc/confluence-specific.adoc index 7cd17588..a7908f3a 100644 --- a/docs/storage-formats/asciidoc/confluence-specific.adoc +++ b/docs/storage-formats/asciidoc/confluence-specific.adoc @@ -43,9 +43,9 @@ Values can be unquoted if they don't contain spaces, or you can put value in quo [NOTE] .Parameters for macros - how to find them? ==== -Parameters are ***not validated***, so make sure that you use expected params for your macro. +Parameters are **not validated**, so make sure that you use expected params for your macro. This can be done by adding the macro you need on sample page in WYSIWYG editor and then opening page in "storage format". -Macro name will be in `` block and all `` elements are macro parameters. +Macro name will be in `ac:structured-macro ac:name="MACRONAME"` block and all `ac:parameter ac:name="columns"` elements are macro parameters. This is especially helpful for special hidden parameters like `serverId` in jira chart macro, that is GUID string and unique per jira server integration. ==== @@ -74,7 +74,7 @@ Some examples: For complex cases, you can always generate raw html/confluence markup via {adocs_pass}[passthrough] -So this tags +So these tags [source,asciidoc] ---- diff --git a/docs/storage-formats/asciidoc/diagrams.adoc b/docs/storage-formats/asciidoc/diagrams.adoc index 55a6a426..6e87f6c2 100644 --- a/docs/storage-formats/asciidoc/diagrams.adoc +++ b/docs/storage-formats/asciidoc/diagrams.adoc @@ -23,6 +23,8 @@ Some attributes such as diagram file format can be convenient to configure not o [cols="a,a"] |=== +| AsciiDoc | Confluence + | ---- include::_assets/example.adoc[tag=diagram] @@ -34,6 +36,8 @@ include::_assets/example.adoc[tag=diagram] [cols="a,a"] |=== +| AsciiDoc | Confluence + |`+plantuml::_assets/test.puml[format=png]+` | plantuml::_assets/test.puml[format=png] |=== diff --git a/docs/storage-formats/asciidoc/links-images.adoc b/docs/storage-formats/asciidoc/links-images.adoc index 647b46ef..2c5140b4 100644 --- a/docs/storage-formats/asciidoc/links-images.adoc +++ b/docs/storage-formats/asciidoc/links-images.adoc @@ -25,6 +25,7 @@ Images support attributes that you can use to customize their alignment and widt [cols=",a,a"] |=== +| Image type | AsciiDoc | Result |External |`+image:https://myoctocat.com/assets/images/base-octocat.svg[Octocat,100]+` @@ -45,11 +46,12 @@ Besides images, you can attach to page any other file: [cols=","] |=== +| AsciiDoc | Confluence | `+link:../markdown/_assets/sample_file.txt[simple text file]+` | link:../markdown/_assets/sample_file.txt[simple text file] -2+|Link title is optional, in this case it will be equal to name of file +2+^|Link title is optional, in this case it will be equal to the name of the file | `+link:../markdown/_assets/sample_file.txt[]+` | link:../markdown/_assets/sample_file.txt[] diff --git a/docs/storage-formats/markdown/basic.md b/docs/storage-formats/markdown/basic.md index 07c0f204..322e5c5e 100644 --- a/docs/storage-formats/markdown/basic.md +++ b/docs/storage-formats/markdown/basic.md @@ -8,20 +8,56 @@ labels: supported-format,markdown ## Text styling -All basic styling features are supported — text can be **bold**, _italic_, ~~strikethrough~~ or mixed one like -**bold with _emphasis_ part**, all ***bold and italic***. For those who need ~subscript~ or ^superscript^ text - it is -supported as well. +All basic styling features are supported — text can be + +| Markdown | Confluence | +|----------------------------------------------------------------------------|---------------------------------------------------------------------------| +| `**bold**` | **bold** | +| `_italic_` | _italic_ | +| `~~strikethrough~~` | ~~strikethrough~~ | +| `With ~subscript~ and ^superscript^` | With ~subscript~ and ^superscript^ | +| `Mixed one like **bold with _emphasis_ part**, all ***bold and italic***` | Mixed one like **bold with _emphasis_ part**, all ***bold and italic*** | + You can also use quotation blocks: + + + + + + + + +
MarkdownConfluence
+ +```markdown +> This is a quote +> +> Spanning multiple paragraphs **styled** and `monoscript` +``` + + + > This is a quote > > Spanning multiple paragraphs **styled** and `monoscript` +
+ + ## Lists Both numbered and bullet lists are supported: + + + + + + + + +
MarkdownConfluence
+ +```markdown 1. one 2. two 3. three @@ -30,23 +66,76 @@ Both numbered and bullet lists are supported: * as nested 1. And ordered 2. again +``` + + + +1. one +2. two +3. three + * unordered + * list + * as nested + 1. And ordered + 2. again + +
Simple task lists are supported too, but due to limitations of Confluence no mixed items are supported. This will work: + + + + + +
MarkdownConfluence
+ +```markdown +* [ ] not done +* [x] done +``` + + * [ ] not done * [x] done +
+ But this will not work: + + + + + +
MarkdownConfluence
+ +```markdown * [ ] not done * [x] done * simple item +``` + + +* [ ] not done +* [x] done +* simple item + +
## Emojis :rocket: -You can embed emojis supported in unicode by using `:emoji-code:` notation :metal:. In some cases it is way easier +You can embed emojis supported in unicode by using `:emoji-code:`. In some cases it is way easier compared to putting just unicode symbol. -You can :mag_right: supported codes on [emoji cheat sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) page. +| Markdown | Confluence | +|-----------|------------| +| `:metal:` | :metal: | + + +You can find supported codes on [emoji cheat sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) page. diff --git a/docs/storage-formats/markdown/code.md b/docs/storage-formats/markdown/code.md index 0289c5d9..47a20bbb 100644 --- a/docs/storage-formats/markdown/code.md +++ b/docs/storage-formats/markdown/code.md @@ -6,12 +6,35 @@ labels: supported-format,markdown ## Inline code + + + + + +
MarkdownConfluence
+ +```markdown +Inline code: `printf("Hello world!")` +``` + + + Inline code: `printf("Hello world!")` +
+ ## Code blocks Code blocks are also supported including language tags: + + + + + +
MarkdownConfluence
+ +````markdown ```java class Test { public static void main(String[] args) { @@ -19,20 +42,69 @@ class Test { } } ``` +```` + + + +```java +class Test { + public static void main(String[] args) { + System.out.println("Hello world!"); + } +} +``` + +
With attributes, you can customize code block element. They can be put after language tag + + + + + +
MarkdownConfluence
+ +````markdown +```kotlin {title="hello.kt"} +println("Hello world!") +``` +```` + + + ```kotlin {title="hello.kt"} println("Hello world!") ``` +
+ or after code block (on separate line) + + + + + +
MarkdownConfluence
+ +````markdown ```kotlin println("Same here!") ``` {title="hello.kt"} +```` + + + +```kotlin +println("Same here!") +``` + +{title="hello.kt"} + +
You can find details about supported languages and other code block attributes on separate page: [Code highlight](../../user-guide/code-blocks.md) diff --git a/docs/storage-formats/markdown/confluence-specific.md b/docs/storage-formats/markdown/confluence-specific.md index a2cefb0e..e1f3b72e 100644 --- a/docs/storage-formats/markdown/confluence-specific.md +++ b/docs/storage-formats/markdown/confluence-specific.md @@ -13,29 +13,86 @@ and rendered as information panels as they called in Confluence Cloud or _note_, Server edition. Note that expand functionality (block that starts with `???`) is not supported because Confluence can't configure expand for these macros (and wrapping them into separate expand section seems too much). -!!! note + + + + + + + + + + + + + +
MarkdownConfluence
+ +```markdown +!!! note "Optional header in quotes" + + A note to yourself +``` + + + +!!! note "Optional header in quotes" A note to yourself +
+ +```markdown +!!! tip + + Some tips and tricks with `rich` ~formatting~ +``` + + + !!! tip Some tips and tricks with `rich` ~formatting~ +
+ +```markdown +!!! warning + + Description of pitfalls that your user + + Should know about +``` + + + !!! warning Description of pitfalls that your user Should know about +
+ +```markdown +!!! info + + Information message +``` + + + !!! info Information message +
+ ## Table of contents Table of contents is supported via [custom extension](https://github.com/vsch/flexmark-java/wiki/Table-of-Contents-Extension) that can be put in any -document location by special `[TOC]` reference put on separate line. +document location by special `[TOC]` reference put on separate line. [Supported attributes](../../user-guide/toc-attributes.md) can be passed as key value inside `TOC`. @@ -47,7 +104,11 @@ Status is a specific element that can serve as eye candy element for various rep on track, on hold, off track For this you need to put custom tag: `$text_of_status`, where `$color` is valid color -and `$text_of_status` is simple text that will be put in block. +and `$text_of_status` is simple text that will be put in block: + +| Markdown | Confluence | +|-------------------------------------------|-----------------------------------------| +| `on track` | on track | Note that only limited colors are supported, and you need to properly specify one of the following allowed values: `grey` @@ -70,10 +131,44 @@ more standard format of this tag by putting text inside time block: