Skip to content

Commit

Permalink
Adjusted documentation of markdown features - using tables for side b…
Browse files Browse the repository at this point in the history 
…y side comparision
  • Loading branch information
@zeldigas
zeldigas committed Nov 4, 2023
1 parent 8e3a7c1 commit 625d7ff
Show file tree
Hide file tree
Showing 17 changed files with 451 additions and 54 deletions.
5 changes: 2 additions & 3 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,16 +10,15 @@ 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
on, but please refrain from adding/removing deps:
- 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.
20 changes: 11 additions & 9 deletions docs/configuration-reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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.

Expand Down Expand Up @@ -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.

Expand Down
6 changes: 2 additions & 4 deletions docs/storage-formats/asciidoc/admonitions.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,7 @@ Mapping:

[cols="a,a"]
|===
| AsciiDoc
| Confluence
| AsciiDoc | Confluence

|
....
Expand Down Expand Up @@ -53,8 +52,7 @@ Short syntax for admonitions works too:

[cols="a,a"]
|===
| AsciiDoc
| Confluence
| AsciiDoc | Confluence

|
....
Expand Down
9 changes: 9 additions & 0 deletions docs/storage-formats/asciidoc/basic.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ All basic styling features are supported — text can be:

[cols="a,a"]
|===
| AsciiDoc | Confluence

| `+*bold*+` | *bold*
| `+_italic_+` | _italic_
Expand All @@ -26,6 +27,8 @@ You can also use quotation blocks:

[cols="a,a"]
|===
| AsciiDoc | Confluence

|
----
include::_assets/example.adoc[tag=style-quotation]
Expand All @@ -39,6 +42,8 @@ Both numbered and bullet lists are supported:

[cols="a,a"]
|===
| AsciiDoc | Confluence

|
----
include::_assets/example.adoc[tag=style-list]
Expand All @@ -52,6 +57,8 @@ This will work:

[cols="a,a"]
|===
| AsciiDoc | Confluence

|
----
include::_assets/example.adoc[tag=style-tasklist-ok]
Expand All @@ -63,6 +70,8 @@ But this will not work:

[cols="a,a"]
|===
| AsciiDoc | Confluence

|
----
include::_assets/example.adoc[tag=style-tasklist-bad]
Expand Down
7 changes: 7 additions & 0 deletions docs/storage-formats/asciidoc/code.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ Code blocks are also supported including callouts

[cols="a,a"]
|===
| AsciiDoc | Confluence

|
[listing,subs="none"]
Expand All @@ -26,6 +27,7 @@ Callouts in xml and similar markup supported too:

[cols="a,a"]
|===
| AsciiDoc | Confluence

|
[listing,subs="none"]
Expand Down Expand Up @@ -61,6 +63,7 @@ Other attributes are Confluence specific.

[cols="a,a"]
|===
| AsciiDoc | Confluence

|
[listing,subs="none"]
Expand All @@ -77,6 +80,8 @@ Literal blocks are converted as pre-formatted text.

[cols="a,a"]
|===
| AsciiDoc | Confluence

|
----
....
Expand All @@ -94,6 +99,7 @@ Same is applied to literal line (one prepended with space)

[cols="a,a"]
|===
| AsciiDoc | Confluence

|
----
Expand All @@ -109,6 +115,7 @@ Listing blocks are converted using the `noformat` macro.

[cols="a,a"]
|===
| AsciiDoc | Confluence

|
[listing]
Expand Down
6 changes: 3 additions & 3 deletions docs/storage-formats/asciidoc/confluence-specific.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<ac-structured-macro ac:name="MACRONAME">` block and all `<ac-parameter ac:name="columns">` 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.
====
Expand Down Expand Up @@ -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]
----
Expand Down
4 changes: 4 additions & 0 deletions docs/storage-formats/asciidoc/diagrams.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand All @@ -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]
|===
Expand Down
4 changes: 3 additions & 1 deletion docs/storage-formats/asciidoc/links-images.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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]+`
Expand All @@ -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[]
Expand Down
99 changes: 94 additions & 5 deletions docs/storage-formats/markdown/basic.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,20 +8,56 @@ labels: supported-format,markdown

## Text styling

All basic styling features are supported &mdash; 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 &mdash; 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:

<table>
<thead>
<tr><th>Markdown</th><th>Confluence</th></tr>
</thead>
<tbody><tr>
<td>

```markdown
> This is a quote
>
> Spanning multiple paragraphs **styled** and `monoscript`
```

</td>
<td>

> This is a quote
>
> Spanning multiple paragraphs **styled** and `monoscript`
</td>
</tr></tbody>
</table>


## Lists

Both numbered and bullet lists are supported:

<table>
<thead>
<tr><th>Markdown</th><th>Confluence</th></tr>
</thead>
<tbody><tr>
<td>

```markdown
1. one
2. two
3. three
Expand All @@ -30,23 +66,76 @@ Both numbered and bullet lists are supported:
* as nested
1. And ordered
2. again
```

</td>
<td>

1. one
2. two
3. three
* unordered
* list
* as nested
1. And ordered
2. again

</td>
</tr></tbody>
</table>

Simple task lists are supported too, but due to limitations of Confluence no mixed items are supported.

This will work:

<table>
<thead>
<tr><th>Markdown</th><th>Confluence</th></tr>
</thead>
<tbody><tr>
<td>

```markdown
* [ ] not done
* [x] done
```
</td><td>

* [ ] not done
* [x] done

</td></tr></tbody></table>

But this will not work:

<table>
<thead>
<tr><th>Markdown</th><th>Confluence</th></tr>
</thead>
<tbody><tr>
<td>

```markdown
* [ ] not done
* [x] done
* simple item
```
</td><td>

* [ ] not done
* [x] done
* simple item

</td></tr></tbody></table>

## 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.
Loading

0 comments on commit 625d7ff

Please sign in to comment.