Updated changelog, docs polishing

zeldigas · Jan 2, 2024 · c618084 · c618084
1 parent 470b74a
commit c618084
Show file tree

Hide file tree

Showing 12 changed files with 43 additions and 23 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,9 +7,12 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
 
+## 0.15.1 - 2024-01-02
+
 ### Fixed
 
 - Detection of duplicate titles in scanned files (#131)
+- User macro in asciidoc files with email format (#135)
 
 ### Changed
 

diff --git a/convert/src/main/kotlin/com/github/zeldigas/text2confl/convert/Converter.kt b/convert/src/main/kotlin/com/github/zeldigas/text2confl/convert/Converter.kt
@@ -7,9 +7,10 @@ import com.github.zeldigas.text2confl.convert.confluence.ReferenceProvider
 import com.github.zeldigas.text2confl.convert.markdown.MarkdownConfiguration
 import com.github.zeldigas.text2confl.convert.markdown.MarkdownFileConverter
 import java.io.File
-import java.nio.file.Files
 import java.nio.file.Path
-import kotlin.io.path.*
+import kotlin.io.path.exists
+import kotlin.io.path.extension
+import kotlin.io.path.relativeTo
 
 interface Converter {
 

diff --git a/docs/configuration-reference.md b/docs/configuration-reference.md
@@ -87,7 +87,7 @@ asciidoc:
 | Parameter      | Default value | Description                                                                                                                                  |
 |----------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------------|
 | diagrams       | `Diagrams`    | How to generate diagrams. The only option now is `Diagrams` that activates `asciidoctor-diagrams`                                            |
-| bundled-macros | `true`        | Enables [asciidoctor macros for confluence](./storage-formats/asciidoc/confluence-specific.adoc)                                             |
+| bundled-macros | `true`        | Enables [asciidoctor macros for Confluence](./storage-formats/asciidoc/confluence-specific.adoc)                                             |
 | attributes     | emtpy map     | Section where you can specify key-value pairs. All provided pairs will be passed to Asciidoc as attributes.                                  | 
 | gems           | empty list    | Additional ruby gems to _require_. Mentioned gems must be on classpath, packaged as jar files (like `asciidoctor-diagram`)                   | 
 | temp-dir       | false         | If temporary directory should be used to store all generated content                                                                         | 

diff --git a/docs/contribution.md b/docs/contribution.md
@@ -2,9 +2,9 @@
 
 # Adding support for Confluence formatting features
 
-Wiki pages are stored in confluence in special xml-like format that is called "storage format".
+Wiki pages are stored in Confluence in special xml-like format that is called "storage format".
 
-If you find some confluence formatting feature missing and would like to add them, here is the recommended steps to
+If you find some Confluence formatting feature missing and would like to add them, here is the recommended steps to
 take.
 
 1. Check [Confluence storage format](https://confluence.atlassian.com/doc/confluence-storage-format-790796544.html)
@@ -19,3 +19,19 @@ take.
 
 Rest api reference for confluence - <https://docs.atlassian.com/atlassian-confluence/REST/6.6.0/>. It is for confluence
 server, but it works for cloud as well.
+
+# Asciidoc
+
+Adapting existing asciidoc feature to Confluence requires analysis of how it is generated by default and then finding
+appropriate way to generate Confluence storage format.
+
+Location of code that generates standard html for
+asciidoc: `<asciidoctor-gem-location>/lib/asciidoctor/converter/html5.rb`
+
+Steps:
+
+1. Find `convert_xxx` method, where `xxx` is the name of feature you need.
+2. Analyze code and decide what you want to do differently
+3. Create template in `convert/src/main/resources/com/github/zeldigas/text2confl/asciidoc`. For block name it should be
+   named `block_xxx.html.slim`, for inline content - `inline_xxx.html.slim`
+4. In created file, you need to specify generate structure using [slim template](https://slim-template.github.io/)
diff --git a/docs/storage-formats/asciidoc/_assets/example.adoc b/docs/storage-formats/asciidoc/_assets/example.adoc
@@ -133,7 +133,7 @@ Should know about
 //tag::adm-important[]
 [IMPORTANT]
 ====
-Also mapped to warning in confluence
+Also mapped to warning in Confluence
 ====
 //end::adm-important[]
 

diff --git a/docs/storage-formats/asciidoc/confluence-specific.adoc b/docs/storage-formats/asciidoc/confluence-specific.adoc
@@ -71,9 +71,9 @@ Some examples:
 |===
 
 [#raw-confluence-formatting]
-== Adding raw confluence formatting
+== Adding raw Confluence formatting
 
-For complex cases, you can always generate raw html/confluence markup via {adocs_pass}[passthrough]
+For complex cases, you can always generate raw html/Confluence markup via {adocs_pass}[passthrough]
 
 So these tags
 

diff --git a/docs/storage-formats/markdown.md b/docs/storage-formats/markdown.md
@@ -8,7 +8,7 @@ labels: supported-format,markdown
 
 # Document structure
 
-Every Markdown document corresponds to separate confluence page.
+Every Markdown document corresponds to separate Confluence page.
 
 Document can contain *YAML Front Matter* block at the very beginning - section in YAML format where various metadata can
 be defined like custom title for page, page labels and properties. You can read about supported attributes
@@ -39,7 +39,7 @@ On subpages, you will find details about various formatting aspects:
 3. [](./markdown/links-images.md) - using links (cross links and external), attaching images and other files
 4. [](./markdown/code.md) -
 5. [](./markdown/diagrams.md) - support for diagrmas defined as text
-6. [](./markdown/confluence-specific.md) - details about confluence specific goodies, such as macros support (table of
+6. [](./markdown/confluence-specific.md) - details about Confluence specific goodies, such as macros support (table of
    contents, status text, others)
 
 How to read subpages:

diff --git a/docs/storage-formats/markdown/confluence-specific.md b/docs/storage-formats/markdown/confluence-specific.md
@@ -119,7 +119,7 @@ values: `grey`
 You can mention user using `@username` format just like you can do on GitHub or in WYSIWYG Confluence editor.
 Unfortunately due to absence of human-readable usernames in Cloud edition this will work only on Server/Datacenter where
 human-readable usernames are still supported. If you still need to mention user in Cloud, consider
-using [raw confluence markdown](#adding-raw-confluence-formatting)
+using [raw Confluence markdown](#adding-raw-confluence-formatting)
 
 ## Putting date
 
@@ -172,7 +172,7 @@ You can use admonition-like syntax to add Confluence expand block:
 ## Confluence macros with simple options
 
 Confluence has a lot of [*macros*](https://confluence.atlassian.com/doc/macros-139387.html) - special gadgets that can
-add extra features to your confluence page. While some of them has comprehensive configuration or can embed text
+add extra features to your Confluence page. While some of them has comprehensive configuration or can embed text
 content (like expand block), a lot of macros are as simple as macro keyword and a number of options that helps you
 configure behavior.
 
@@ -203,12 +203,12 @@ Some examples:
 | [Jira report table][JIRA_MACRO_TABLE]         | `[JIRA jqlQuery="project = SI" columns=key,summary,assignee,reporter,status maximumIssues=20]` | [JIRA jqlQuery="project = SI" columns=key,summary,assignee,reporter,status maximumIssues=5] |
 | [Jira charts][JIRA_CHART]                     | `[JIRACHART jql="project = SI" chartType=pie statType=components serverId=<JIRA_SERVER_ID>]`   | [JIRACHART jql="project = SI" chartType=pie statType=components serverId=<JIRA_SERVER_ID>]  |
 
-## Adding raw confluence formatting
+## Adding raw Confluence formatting
 
 Flexmark library that is used to parse markdown follows common mark spec that prohibits html tags with colons, but this
 is the heart of custom Confluence markup because they use `ac:` and `ri:` as their namespace prefixes for all macro
 tags.
-To overcome this limitation, **text2confl** supports alternative format confluence tags with dashes.
+To overcome this limitation, **text2confl** supports alternative format Confluence tags with dashes.
 
 So this tags
 

diff --git a/docs/storage-formats/markdown/diagrams.md b/docs/storage-formats/markdown/diagrams.md
@@ -4,7 +4,7 @@ labels: supported-format,markdown
 
 # Markdown - diagrams
 
-**text2confl** supports a number of text diagram formats to be embedded in confluence page as code blocks:
+**text2confl** supports a number of text diagram formats to be embedded in Confluence page as code blocks:
 
 * [PlantUML](https://plantuml.com/en/)
 * [Mermaid](https://mermaid.js.org/)

diff --git a/docs/user-guide.md b/docs/user-guide.md
@@ -18,7 +18,7 @@ is easier for building various automation scenarios and CI/CD pipelines for your
 
 ## Initial setup
 
-Assuming that you plan to store many documents uploaded to confluence and version them in some VCS (e.g. git) it makes
+Assuming that you plan to store many documents uploaded to Confluence and version them in some VCS (e.g. git) it makes
 sense to spend some time and configure the place for our docs and make it in the way so that subsequent uploads will
 require minimal amount of parameters or not parameters at all. If you want just to quickly upload something, say just
 one document you can check [adhoc upload section](#adhoc-upload) below.
@@ -36,14 +36,14 @@ documentation root dir.
 For the start put the following contents:
 
 ```yaml
-server: <address of confluence server>
+server: <address of Confluence server>
 space: <space for docs>
 docs-location: <root url of your documents>
 ```
 
 Where:
 
-1. `address of confluence server` - is the address of server/datacenter confluence server
+1. `address of Confluence server` - is the address of server/datacenter Confluence server
    or `https://<YOURNAME>.atlassian.net/wiki` for Cloud version
 2. `space for docs` - is space key where you will publish your pages (the string that you can find in url e.g. with
    url https://text2conf.atlassian.net/wiki/spaces/DOCS/pages/2818199/Markdown `DOCS` will be a space we are looking
@@ -148,10 +148,10 @@ text2confl upload --docs .
 ```
 
 Assuming that you are currently in directory with docs. You can also enable ***dry** mode for upload by passing `--dry`
-option to command. In dry-run mode no confluence content will be modified, instead all changes will be logged
+option to command. In dry-run mode no Confluence content will be modified, instead all changes will be logged
 with `(dryrun)` marker.
 
-If you want to see how your documents will be converted in confluence *storage format* without uploading them (or if you
+If you want to see how your documents will be converted in Confluence *storage format* without uploading them (or if you
 just want conversion part because for some reason you plan to upload them yourself) you can use `convert` command to
 produce documents as files on machine:
 

diff --git a/docs/user-guide/code-blocks.md b/docs/user-guide/code-blocks.md
@@ -13,7 +13,7 @@ List of supported attributes:
 | `collapse`    | Flag that control if code block is collapsed on page by default. Allowed values - `true` or `false`                               | :white_check_mark:️ | :warning:️ Only if editor v1 is forcibly set :warning:️ |
 | `linenumbers` | Flag that controls if line numbers are displayed. Allowed values - `true` or `false`                                              | :white_check_mark:️ | :warning:️ Only if editor v1 is forcibly set :warning:️ |
 | `firstline`   | Sets starting line number for codeblocks                                                                                          | :white_check_mark:️ | :warning:️ Only if editor v1 is forcibly set :warning:️ |
-| `theme`       | Sets theme for code block. Valid values - in [confluence docs](https://confluence.atlassian.com/doc/code-block-macro-139390.html) | :white_check_mark:️ | :warning:️ Only if editor v1 is forcibly set :warning:️ |
+| `theme`       | Sets theme for code block. Valid values - in [Confluence docs](https://confluence.atlassian.com/doc/code-block-macro-139390.html) | :white_check_mark:️ | :warning:️ Only if editor v1 is forcibly set :warning:️ |
 
 ## Language tags
 

diff --git a/docs/user-guide/page-attributes.md b/docs/user-guide/page-attributes.md
@@ -15,7 +15,7 @@ Document title (name) can be defined in the following ways (from top priority to
 3. name of file
 
 Recommended approach is to use first level heading as it provides also good-looking content outside of
-Confluence. Usage of `title` attribute also fine, especially if you prefer to hide as much confluence-specific things
+Confluence. Usage of `title` attribute also fine, especially if you prefer to hide as much Confluence-specific things
 from content as possible.
 
 ### Example 1 - title will be taken from *yaml front matter*
@@ -98,7 +98,7 @@ Document content
 
 ## Page properties
 
-Page properties is set of special key-value pairs in confluence. Confluence and plugins use them to configure page
+Page properties is set of special key-value pairs in Confluence. Confluence and plugins use them to configure page
 behavior.
 
 Properties can be of the following types: string, boolean, list of strings, object (json)