Text2Confl

https://github.com/zeldigas/text2confl
Admin
Text2Confl is a CLI tool that publishes structured text documents written in Markdown or AsciiDoc to...
Tokens:21,526
Snippets:425
Trust Score:8.2
License:Apache-2.0
Update:2 months ago
Show doc for...
Tokens:
Raw
### Verify Installation

Source: https://github.com/zeldigas/text2confl/blob/master/docs/tutorials/_step-download.adoc

Check that the binary is executable and correctly installed by querying the version.

```shell
$T2C --version
```

--------------------------------

### Import diagram from file

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/asciidoc/diagrams.adoc

Example of importing a diagram using the plantuml macro.

```asciidoc
plantuml::_assets/test.puml[target=test,format=png]
```

--------------------------------

### Confluence Structured Macro Example

Source: https://github.com/zeldigas/text2confl/blob/master/convert/src/test/resources/convert/confluence-specific.md

Example of a Jira structured macro using standard Confluence namespace prefixes.

```xml
<ac-structured-macro ac:name="jira">
    <ac-parameter ac:name="columns">key,summary,assignee,reporter,status</ac-parameter>
    <ac-parameter ac:name="maximumIssues">20</ac-parameter>
    <ac-parameter ac:name="jqlQuery">project = SI</ac-parameter>
</ac-structured-macro>
```

--------------------------------

### Generate a Jira chart

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/markdown/confluence-specific.md

Example of using the JIRACHART macro with specific chart parameters.

```markdown
[JIRACHART jql="project = SI" chartType=pie statType=components serverId=<JIRA_SERVER_ID>]
```

--------------------------------

### Standard Markdown Table

Source: https://github.com/zeldigas/text2confl/blob/master/convert/src/test/resources/convert/tables.md

A basic Markdown table example.

```markdown
| First | Second |
|-------|--------|
| a     | a      |
| b     | b      |
```

--------------------------------

### Files structure for virtual pages

Source: https://github.com/zeldigas/text2confl/blob/master/docs/explanation/virtual-pages.md

Example file system layout using virtual pages to mirror a wiki hierarchy.

```text
├── another-page.md
├── parent-page.md
├── parent-page
│   ├── page-a.md
│   ├── page-b.md
```

--------------------------------

### Define an AsciiDoc include file

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/asciidoc/includes.adoc

Example of a file structure for an included document.

```asciidoc
include::_assets/included.adoc[]
```

--------------------------------

### Generate a Jira report table

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/markdown/confluence-specific.md

Example of using the JIRA macro with multiple parameters for a report table.

```markdown
[JIRA jqlQuery="project = SI" columns=key,summary,assignee,reporter,status maximumIssues=20]
```

--------------------------------

### Inline diagram example

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/asciidoc/diagrams.adoc

Example of an inlined diagram block in AsciiDoc.

```asciidoc
include::_assets/example.adoc[tag=diagram]
```

--------------------------------

### Inline Code Example

Source: https://github.com/zeldigas/text2confl/blob/master/convert/src/test/resources/convert/code.html

Use backticks to format short snippets of code inline.

```c
printf("Hello world!")
```

--------------------------------

### Run Confluence diagnostic checks

Source: https://github.com/zeldigas/text2confl/blob/master/docs/how-to/troubleshoot-with-doctor.md

Executes a series of API checks against the specified Confluence instance to verify setup.

```shell
text2confl doctor confluence \
  --confluence-url https://mysite.atlassian.net/wiki \
  --access-token YOUR_TOKEN \
  --space MYSPACE \
  --parent-id 123456
```

--------------------------------

### Configure AsciiDoc attributes

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/configuration.adoc

Example of setting the plantuml-format attribute in the asciidoc configuration section of .text2confl.yml.

```yaml
asciidoc:
  attributes:
    plantuml-format: png
```

--------------------------------

### Reference a single Jira ticket

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/markdown/confluence-specific.md

Example of using the JIRA macro to reference a specific ticket.

```markdown
[JIRA key=SI-1]
```

--------------------------------

### Integrate text2confl in GitHub Actions

Source: https://github.com/zeldigas/text2confl/blob/master/docs/how-to/run-with-docker.md

Example step for a GitHub Actions workflow to publish documentation to Confluence using the Docker image.

```yaml
- name: Publish docs to Confluence
  run: |
    docker run --rm \
      -v "${{ github.workspace }}/docs:/wd" \
      --workdir /wd \
      -e CONFLUENCE_ACCESS_TOKEN=${{ secrets.CONFLUENCE_TOKEN }} \
      zeldigas/text2confl upload --docs .
```

--------------------------------

### Define page metadata with YAML front matter

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/markdown.md

Use a YAML block at the start of a document to define page titles, labels, and complex properties parsed as JSON.

```markdown
---
title: hello
labels: docs,intro
property_simple: custom_value
property_nl_avisi_nh: { "isEnabled": true }
---

Document content
```

--------------------------------

### Configure Markdown tables

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/configuration.adoc

Example of disabling column spans in the markdown configuration section of .text2confl.yml.

```yaml
markdown:
  tables:
    column-spans: false
```

--------------------------------

### Create a Markdown file for Confluence

Source: https://github.com/zeldigas/text2confl/blob/master/docs/tutorials/_step-create-page.adoc

Use this command to generate a sample Markdown file named hello-world.md with basic content.

```shell
cat > hello-world.md << 'EOF'
# Hello from text2confl

This page was published automatically using [text2confl](https://github.com/zeldigas/text2confl).

## What is text2confl?

text2confl converts Markdown and AsciiDoc files into Confluence pages. You write docs as plain text files, commit them to version control, and text2confl keeps your Confluence space in sync.
EOF
```

--------------------------------

### Configure Kroki settings

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/asciidoc/diagrams.adoc

Define Kroki server, format, and fetch behavior in the configuration file.

```yaml
asciidoc:
  diagrams: Kroki
  kroki:
    server: ... # <1>
    format: png # <2>
    fetch: true/false # <3>
```

--------------------------------

### Build and Test Commands

Source: https://github.com/zeldigas/text2confl/blob/master/CLAUDE.md

Standard Maven commands for building the project and running tests on specific modules.

```shell
mvn package
```

```shell
# build a specific module
mvn package -pl convert -am

# test a specific module
mvn test -pl core -am

# test everything
mvn test
```

--------------------------------

### Run text2confl with a credentials file

Source: https://github.com/zeldigas/text2confl/blob/master/docs/how-to/run-with-docker.md

Mounts a local configuration directory as read-only to provide credentials to the container.

```shell
docker run --rm -it \
  -v ~/.config/text2confl:/root/.config/text2confl:ro \
  -v "$PWD:/wd" \
  --workdir /wd \
  zeldigas/text2confl upload --docs .
```

--------------------------------

### Inspect converted output locally

Source: https://github.com/zeldigas/text2confl/blob/master/docs/how-to/troubleshoot-conversion.md

Run this command from the documentation root to generate Confluence Storage Format files in the local output directory.

```shell
text2confl convert --docs .
```

--------------------------------

### Upload documentation to Confluence

Source: https://github.com/zeldigas/text2confl/blob/master/docs/internal/documentation-guide.md

Use this command to publish documentation from the local docs directory to a specified Confluence space.

```shell
text2confl upload --docs ./docs --confluence-url <url> --user <user> --password <token> --space <SPACE> --parent "<parent>"
```

--------------------------------

### Create a simple Markdown table

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/markdown/tables.md

Uses GitHub Flavored Markdown syntax to define columns and alignment.

```markdown
| foo                 |     bar      |               baz | 
|---------------------|:------------:|------------------:|
| bip                 |     bim      |              boop |
| I'm left by default | I'm centered | I'm aligned right |
```

--------------------------------

### Extract and Define Binary Path

Source: https://github.com/zeldigas/text2confl/blob/master/docs/tutorials/_step-download.adoc

Extract the downloaded archive and set an environment variable to point to the binary location.

```shell
tar xzf text2confl-*.tar.gz
T2C=$(pwd)/text2confl
```

--------------------------------

### Interpret doctor output

Source: https://github.com/zeldigas/text2confl/blob/master/docs/how-to/troubleshoot-with-doctor.md

Example of the status output format showing passed, failed, and skipped checks.

```text
[ OK  ] describe-space
[ OK  ] get-page
[ OK  ] create-page
[FAIL ] add-labels
         Error: 403 Forbidden
         Hint:  Scoped token needs 'write:label:confluence' scope.
[SKIP ] read-labels
...

1 check(s) failed, 3 passed, 12 skipped.
```

--------------------------------

### Define GitHub-style admonition tip

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/markdown/confluence-specific.md

Uses the GitHub-style alert format to create a tip block.

```markdown
> [!TIP]
> Some tips and tricks with `rich` ~formatting~
```

--------------------------------

### Configure tenant ID via command line

Source: https://github.com/zeldigas/text2confl/blob/master/docs/how-to/configure-multi-tenancy.md

Pass the tenant parameter directly during the upload command to override or set the tenant context.

```shell
text2confl upload --docs . --tenant team-a
```

--------------------------------

### Upload documentation to Confluence

Source: https://github.com/zeldigas/text2confl/blob/master/docs/tutorials/first-upload-dc.adoc

Execute the upload command in your terminal to convert and publish Markdown files. Use the --dry flag to preview changes without modifying the server.

```shell
$T2C upload --docs . \
  --access-token YOUR_PERSONAL_ACCESS_TOKEN
```

--------------------------------

### Upload documentation to Confluence

Source: https://github.com/zeldigas/text2confl/blob/master/README.md

Use this command from the root of the repository to upload documentation files to a specified Confluence space and parent page.

```shell
# from the root of the checked out text2confl repo
text2confl upload --docs ./docs \
  --confluence-url https://wiki.example.org \
  --user bob \
  --password secret_password \
  --space DOCS \
  --parent "Text2Confl test"
```

--------------------------------

### Apply text styling in Markdown

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/markdown/basic.md

Demonstrates basic text formatting including bold, italic, strikethrough, and script tags.

```markdown
**bold**
```

```markdown
_italic_
```

```markdown
~~strikethrough~~
```

```markdown
With ~subscript~ and ^superscript^
```

```markdown
Mixed one like **bold with _emphasis_ part**, all  ***bold and italic***
```

--------------------------------

### Configure diagram storage in .text2confl.yml

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/markdown/diagrams.md

Define the base directory and temporary directory settings for diagram generation.

```yaml
markdown:
  diagrams:
#  parameters here
```

--------------------------------

### Configure diagram provider

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/asciidoc/diagrams.adoc

Set the diagram generation approach in the .text2confl.yml configuration file.

```yaml
asciidoc:
  diagrams: Diagrams / Kroki / None
```

--------------------------------

### Create expand blocks

Source: https://github.com/zeldigas/text2confl/blob/master/convert/src/test/resources/convert/confluence-specific.md

Use admonition-style syntax to generate collapsible expand blocks in Confluence.

```markdown
!!! expand

    I'm text that is put inside expand block
```

--------------------------------

### Upload a single file via CLI

Source: https://github.com/zeldigas/text2confl/blob/master/docs/how-to/upload-adhoc.md

Uploads a specific markdown file by pointing the --docs flag to the file path instead of a directory.

```shell
text2confl upload --docs ./my-file.md \
  --confluence-url https://wiki.example.org \
  --user bob \
  --password secret_password \
  --space DOCS
```

--------------------------------

### Use Single Paragraph Admonition Syntax

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/asciidoc/admonitions.adoc

Shows the short syntax for creating a single paragraph warning admonition.

```asciidoc
WARNING: Important message to keep in mind
```

--------------------------------

### Configure tenant ID in configuration file

Source: https://github.com/zeldigas/text2confl/blob/master/docs/how-to/configure-multi-tenancy.md

Add the tenant parameter to the .text2confl.yml file to associate the project with a specific team.

```yaml
tenant: team-a
```

--------------------------------

### Create a listing block

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/asciidoc/code.adoc

Listing blocks are converted using the noformat macro in Confluence.

```text
.Title of the listing block
----
this is a listing block
----
```

--------------------------------

### View Module Dependency Chain

Source: https://github.com/zeldigas/text2confl/blob/master/CLAUDE.md

Visual representation of the project's multi-module dependency structure.

```text
cli
 └── core
      ├── convert
      └── confluence-client

gem-kroki  (standalone diagram plugin)
```

--------------------------------

### Team B file tree configuration

Source: https://github.com/zeldigas/text2confl/blob/master/docs/explanation/virtual-pages.md

File structure for a tenant to place pages under a hierarchy they do not own.

```text
├── team-a-section.md           ← virtual (not owned, not modified)
├── team-a-section/
│   ├── team-b-subsection.md    ← virtual or managed by Team B
│   └── team-b-subsection/
│       ├── service-docs.md
│       └── api-reference.md
```

--------------------------------

### Create expand blocks with admonition syntax

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/markdown/confluence-specific.md

Use the expand admonition to create collapsible content blocks. Supports custom link text.

```markdown
!!! expand

    I'm text that is put inside expand block
```

```markdown
!!! expand "Custom text on expand link"

    I'm text that is put inside expand block
```

--------------------------------

### Define XML source code block with callouts

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/asciidoc/code.adoc

Use the source block syntax with XML highlighting and numbered callouts.

```xml
[source,xml]
----
<hello>world</hello><!--1-->
----
<1> xml style of hello world
```

--------------------------------

### Set page labels

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/page-attributes.md

Define multiple labels as a comma-separated string.

```markdown
---
labels: one, two, three
---
Document content
```

--------------------------------

### Configure TOC placement with macro

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/asciidoc/toc.adoc

Enables manual placement of the table of contents using the toc::[] macro.

```asciidoc
= Page Title
:toc: macro

Intro paragraph

== Section

toc::[]
```

--------------------------------

### Define page properties

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/page-attributes.md

Use the property_ prefix to define custom key-value pairs for Confluence.

```yaml
property_first: hello
property_complex: { "first": one, "flag": false }
```

--------------------------------

### Configure diagram generation directory

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/asciidoc/diagrams.adoc

Set the base directory for generated diagram files.

```yaml
asciidoc:
  attributes:
    baseDir: .asciidoc
```

--------------------------------

### Upload a directory via CLI

Source: https://github.com/zeldigas/text2confl/blob/master/docs/how-to/upload-adhoc.md

Uploads all documents within a directory by specifying the source path and Confluence connection details directly in the command.

```shell
text2confl upload --docs . \
  --confluence-url https://wiki.example.org \
  --user bob \
  --password secret_password \
  --space DOCS \
  --parent "Autogenerated docs"
```

--------------------------------

### Run text2confl with environment variables

Source: https://github.com/zeldigas/text2confl/blob/master/docs/how-to/run-with-docker.md

Executes the container by mounting the current directory and providing the Confluence access token via an environment variable.

```shell
docker run --rm -it \
  -v "$PWD:/wd" \
  --workdir /wd \
  -e CONFLUENCE_ACCESS_TOKEN=your_token \
  zeldigas/text2confl upload --docs .
```

--------------------------------

### Configure .text2confl.yml

Source: https://github.com/zeldigas/text2confl/blob/master/docs/tutorials/first-upload-cloud-scoped-tokens.adoc

Define the server, space, and parent page settings for the text2confl tool.

```yaml
server: https://api.atlassian.com/ex/confluence/<cloudId>
space: MYSPACE
default-parent-id: 123456789
docs-location: https://github.com/yourorg/yourrepo/tree/main/my-docs/
```

--------------------------------

### Configure cleanup mode via CLI

Source: https://github.com/zeldigas/text2confl/blob/master/docs/how-to/manage-orphaned-pages.md

Use the --remove-orphans flag during the upload command to specify the desired cleanup behavior.

```shell
# Delete only managed orphans (default behavior - explicit)
text2confl upload --docs . --remove-orphans managed

# Delete all orphaned pages under the upload root
text2confl upload --docs . --remove-orphans all

# Disable cleanup entirely
text2confl upload --docs . --remove-orphans none
```

--------------------------------

### Implement task lists in Markdown

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/markdown/basic.md

Task lists are supported, but mixing task items with standard list items is not permitted.

```markdown
* [ ] not done
* [x] done
```

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

--------------------------------

### HTML Table for Documentation Links

Source: https://github.com/zeldigas/text2confl/blob/master/convert/src/test/resources/convert/tables.md

A simple HTML table structure used for organizing documentation references and samples.

```html
<table>
<tbody>
<tr>
<th>Docs</th>
<td>

[reference](https://docs.spring.io/spring-kafka/reference/html)
</td>
</tr>
<tr>
<th>Samples</th>
<td>

[sample](http://example.org/sample)
</td>
</tr>
</tbody>
</table>
```

--------------------------------

### Render inline code

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/markdown/code.md

Use backticks to format text as inline code.

```markdown
Inline code: `printf("Hello world!")`
```

--------------------------------

### Configure TOC placement with preamble attribute

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/asciidoc/toc.adoc

Sets the table of contents to appear before the first section of the page.

```asciidoc
= Page Title
:toc: preamble

Intro paragraph

== Section
```

--------------------------------

### Configure server URL

Source: https://github.com/zeldigas/text2confl/blob/master/docs/how-to/authenticate-with-scoped-tokens.md

Set the server URL in the configuration file or via CLI flags to enable scoped token mode.

```yaml
server: https://api.atlassian.com/ex/confluence/<cloudId>
```

```shell
text2confl upload --docs . --confluence-url https://api.atlassian.com/ex/confluence/<cloudId> ...
```

--------------------------------

### Define GitHub-style admonition note

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/markdown/confluence-specific.md

Uses the GitHub-style alert format to create a note block.

```markdown
> [!NOTE]
> A note to yourself
```

--------------------------------

### Multi-tenant hierarchy visualization

Source: https://github.com/zeldigas/text2confl/blob/master/docs/explanation/virtual-pages.md

Conceptual layout of overlapping page hierarchies in a multi-tenant environment.

```text
├── Team A section          ← owned by Team A (tenant: team-a)
│   ├── Guide X
│   ├── Guide Y
│   └── Team B subsection   ← Team B wants to publish here
│       ├── Service docs    ← owned by Team B (tenant: team-b)
│       └── API reference   ← owned by Team B (tenant: team-b)
```

--------------------------------

### Authenticate with access token

Source: https://github.com/zeldigas/text2confl/blob/master/docs/how-to/authenticate-with-scoped-tokens.md

Pass the scoped access token directly to the CLI command.

```shell
text2confl upload --docs . \
  --confluence-url https://api.atlassian.com/ex/confluence/<cloudId> \
  --access-token YOUR_SCOPED_TOKEN \
  --space MYSPACE
```

--------------------------------

### Apply TOC styling

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/asciidoc/toc.adoc

Demonstrates applying a specific style to the generated table of contents.

```asciidoc
toc::[style=square]
```

--------------------------------

### Define a table with cell background colors

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/asciidoc/tables.adoc

Apply background colors to table cells using the supported trick.

```asciidoc
include::_assets/example.adoc[tag=bgcolor-table]
```

--------------------------------

### Add Raw Confluence Formatting

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/asciidoc/confluence-specific.adoc

Use passthrough blocks to inject raw Confluence storage format XML for complex macro configurations.

```asciidoc
++++
<ac:structured-macro ac:name="jira">
    <ac:parameter ac:name="columns">key,summary,assignee,reporter,status</ac:parameter>
    <ac:parameter ac:name="maximumIssues">20</ac:parameter>
    <ac:parameter ac:name="jqlQuery">project = SI</ac:parameter>
</ac:structured-macro>
++++
```

--------------------------------

### Define GitHub-style admonition caution

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/markdown/confluence-specific.md

Uses the GitHub-style alert format to create a caution block for pitfalls.

```markdown
> [!CAUTION]
> Description of pitfalls that your user
> 
> Should know about
```

--------------------------------

### Insert simple Confluence macros

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/markdown/confluence-specific.md

Use the bracketed syntax to define macros. Values can be unquoted if they contain no spaces, or quoted if they do.

```markdown
[MYMACRo width=100 searchQuery="project in (A,B,C)"]
```

--------------------------------

### Configure Kroki in .text2confl.yml

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/markdown/diagrams.md

Specify Kroki generator parameters within the configuration file.

```yaml
markdown:
  diagrams:
    kroki:
#      parameters here
```

--------------------------------

### Map AsciiDoc Admonitions to Confluence

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/asciidoc/admonitions.adoc

Demonstrates the mapping of various AsciiDoc admonition types to Confluence macros using include tags.

```asciidoc
include::_assets/example.adoc[tag=adm-note]
```

```asciidoc
include::_assets/example.adoc[tag=adm-tip]
```

```asciidoc
include::_assets/example.adoc[tag=adm-caution]
```

```asciidoc
include::_assets/example.adoc[tag=adm-warning]
```

```asciidoc
include::_assets/example.adoc[tag=adm-important]
```

--------------------------------

### Include an AsciiDoc file

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/asciidoc/includes.adoc

Syntax for including a file and setting the path attribute for asset resolution.

```asciidoc
:included_path: _assets/

\include::_assets/included.adoc[]
```

--------------------------------

### Configure Kroki attributes

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/asciidoc/diagrams.adoc

Add custom attributes for the Kroki extension.

```yaml
asciidoc:
  attributes:
```

--------------------------------

### Store Credentials in Properties File

Source: https://github.com/zeldigas/text2confl/blob/master/docs/how-to/authenticate.md

Define credentials in a properties file to avoid manual entry on every execution.

```properties
upload.user=your@email.com
upload.password=YOUR_API_TOKEN
```

--------------------------------

### Configure cleanup mode in YAML

Source: https://github.com/zeldigas/text2confl/blob/master/docs/how-to/manage-orphaned-pages.md

Set the remove-orphans option in the .text2confl.yml configuration file.

```yaml
remove-orphans: managed   # default
# remove-orphans: all
# remove-orphans: none
```

--------------------------------

### GitHub Flavored Markdown Table

Source: https://github.com/zeldigas/text2confl/blob/master/convert/src/test/resources/convert/tables.md

Standard table syntax using GitHub Flavored Markdown.

```markdown
| foo | bar |
|-----|-----|
| baz | bim |
```

--------------------------------

### Define custom admonition tip

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/markdown/confluence-specific.md

Uses the custom extension format to create a tip block with rich formatting.

```markdown
!!! tip

    Some tips and tricks with `rich` ~formatting~
```

--------------------------------

### Virtual page front matter configuration

Source: https://github.com/zeldigas/text2confl/blob/master/docs/explanation/virtual-pages.md

Markdown front matter configuration to define a page as virtual.

```markdown
---
title: Parent page
_virtual_: true
---
```

--------------------------------

### Define a Java class with callouts

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/asciidoc/_assets/example.adoc

Demonstrates a Java class structure with inline callouts. Note that the callouts will cause compilation errors if copied directly into an IDE.

```java
public class MyCode { //<1>
    public static void main(String[] args){
        System.out.println("Hello world!"); //<2>
    }
} <3>
```

--------------------------------

### Apply text alignment roles

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/asciidoc/basic.adoc

Use CSS-like roles to align headings and paragraphs to the left, center, or right.

```asciidoc
[.text-right]
=== Heading aligned to the right

Paragraph aligned to the right.

[.text-center]
Centered paragraph
```

--------------------------------

### Represent a sparse page tree structure

Source: https://github.com/zeldigas/text2confl/blob/master/docs/how-to/use-virtual-pages.md

Visualize the file system layout where a virtual page acts as a parent for managed content.

```text
├── another-page.md
├── parent-page.md         ← virtual (placeholder only)
├── parent-page/
│   ├── page-a.md          ← managed
│   └── page-b.md          ← managed
```

--------------------------------

### Define Admonition Blocks

Source: https://github.com/zeldigas/text2confl/blob/master/convert/src/test/resources/convert/confluence-specific.md

Use the triple-exclamation syntax to create information panels in Confluence. Supported types include note, tip, warning, and info.

```markdown
!!! note

    A note to yourself

!!! tip

    Some tips and tricks with `rich` ~formatting~

!!! warning

    Description of pitfalls that your user

    Should know about

!!! info

    Information message
```

--------------------------------

### Enable auto-fix for a single run

Source: https://github.com/zeldigas/text2confl/blob/master/docs/how-to/enable-auto-fix.md

Use the --auto-fix-content flag during the upload command to enable the feature for a one-time execution.

```shell
text2confl upload --docs . --auto-fix-content
```

--------------------------------

### Define an XML snippet with callout

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/asciidoc/_assets/example.adoc

Shows a basic XML element with an inline comment callout.

```xml
<hello>world</hello><!--1-->
```

--------------------------------

### Enable auto-fix in configuration file

Source: https://github.com/zeldigas/text2confl/blob/master/docs/how-to/enable-auto-fix.md

Add this setting to your .text2confl.yml to enable auto-fix for all project runs.

```yaml
auto-fix-content-tags: true
```

--------------------------------

### Tenant Info JSON Response

Source: https://github.com/zeldigas/text2confl/blob/master/docs/tutorials/first-upload-cloud-scoped-tokens.adoc

The expected JSON output containing the cloudId needed for authentication.

```json
{"cloudId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","siteUrl":"https://yoursite.atlassian.net"}
```

--------------------------------

### Configure PlantUML in .text2confl.yml

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/markdown/diagrams.md

Specify PlantUML parameters and settings within the project configuration file.

```yaml
markdown:
  diagrams:
    plantuml:
#      parameters here
```

--------------------------------

### Generate a PlantUML diagram

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/asciidoc/_assets/example.adoc

Renders a sequence diagram using PlantUML syntax.

```plantuml
@startuml
client -> server
@enduml
```

--------------------------------

### Title via filename

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/page-attributes.md

Falls back to the filename if no title attribute or header is found.

```markdown
Document content
```

--------------------------------

### Upload Documents to Confluence

Source: https://github.com/zeldigas/text2confl/blob/master/docs/tutorials/first-upload-cloud-scoped-tokens.adoc

Execute the upload command using the scoped API token for authentication.

```shell
$T2C upload --docs . --access-token YOUR_SCOPED_TOKEN
```

--------------------------------

### Export Confluence page by title

Source: https://github.com/zeldigas/text2confl/blob/master/docs/how-to/export-to-markdown.md

Downloads a page by specifying its title and the space it belongs to when the page ID is unknown.

```shell
text2confl export-to-md \
  --confluence-url https://yoursite.atlassian.net/wiki \
  --access-token YOUR_TOKEN \
  --space MYSPACE \
  --page-title "My existing page" \
  --dest ./docs
```

--------------------------------

### Convert single file with specific editor version

Source: https://github.com/zeldigas/text2confl/blob/master/docs/how-to/troubleshoot-conversion.md

Use this command when converting individual files to specify the legacy editor version if required by your Confluence instance.

```shell
text2confl convert --file my-page.md --editor-version v1
```

--------------------------------

### Create a literal block

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/asciidoc/code.adoc

Literal blocks are rendered as pre-formatted text.

```text
....
this is a literal block
....
```

--------------------------------

### Title via YAML front matter with header

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/page-attributes.md

The title attribute takes precedence over top-level headers.

```markdown
---
title: My page
---

# Header that is not used as a title

Document content
```

--------------------------------

### Define GitHub-style admonition important

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/markdown/confluence-specific.md

Uses the GitHub-style alert format to create an important information block.

```markdown
> [!IMPORTANT]
> Information message
```

--------------------------------

### Configure Mermaid in .text2confl.yml

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/markdown/diagrams.md

Specify Mermaid generator parameters within the configuration file.

```yaml
markdown:
  diagrams:
    mermaid:
#      parameters here
```

--------------------------------

### Render code blocks with language tags

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/markdown/code.md

Use triple backticks followed by a language identifier to create a syntax-highlighted code block.

```markdown
```java
class Test {
    public static void main(String[] args) {
        System.out.println("Hello world!");
    }
}
```
```

--------------------------------

### Define custom admonition warning

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/markdown/confluence-specific.md

Uses the custom extension format to create a warning block for pitfalls.

```markdown
!!! warning

    Description of pitfalls that your user
    
    Should know about
```

--------------------------------

### Specify column width in pixels

Source: https://github.com/zeldigas/text2confl/blob/master/docs/contributing/table-width.md

Syntax for defining column widths using colgroup and col elements with pixel values.

```html
<col style="width: 147.0px;" />
```

--------------------------------

### Export with raw Confluence Storage Format

Source: https://github.com/zeldigas/text2confl/blob/master/docs/how-to/export-to-markdown.md

Saves the original Confluence XML alongside the generated Markdown for debugging purposes.

```shell
text2confl export-to-md \
  --confluence-url https://yoursite.atlassian.net/wiki \
  --access-token YOUR_TOKEN \
  --page-id 12345678 \
  --dest ./docs \
  --dump-also-storage-format
```

--------------------------------

### Create a literal line

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/asciidoc/code.adoc

A line prepended with a space is treated as a literal line.

```text
 A line with space
```

--------------------------------

### Define custom admonition info

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/markdown/confluence-specific.md

Uses the custom extension format to create an information message block.

```markdown
!!! info

    Information message
```

--------------------------------

### Define custom admonition note

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/markdown/confluence-specific.md

Uses the custom extension format to create a note block with an optional header.

```markdown
!!! note "Optional header in quotes"

    A note to yourself
```

--------------------------------

### Authenticate with Confluence Server/Data Center

Source: https://github.com/zeldigas/text2confl/blob/master/docs/how-to/authenticate.md

Use a personal access token or standard username/password credentials.

```shell
text2confl upload --docs . --access-token YOUR_PERSONAL_ACCESS_TOKEN
```

```shell
text2confl upload --docs . --user yourname --password yourpassword
```

--------------------------------

### Mention User Macro

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/asciidoc/confluence-specific.adoc

Mention users by username or email. This feature is only supported on Confluence Server/Datacenter editions.

```asciidoc
user:username[]
```

```asciidoc
user:jsmith@example.org[]
```

--------------------------------

### Create expand blocks with details tag

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/markdown/confluence-specific.md

Use the standard HTML details tag for expand blocks to avoid indentation issues in text editors. Note that nested expands are not supported.

```markdown
<details>
<summary>Text for expand macro</summary>

Arbitrary markdown here

</details>
```

--------------------------------

### Calculate table and column dimensions

Source: https://github.com/zeldigas/text2confl/blob/master/docs/contributing/table-width.md

Formulas for determining pixel widths based on page mode and percentage values.

```text
actual_width = 1800 * (custom_width / 100)
column_actual_width = table_actual_width * (column_width / 100)
```

--------------------------------

### Kotlin Code Block with Attributes

Source: https://github.com/zeldigas/text2confl/blob/master/convert/src/test/resources/convert/code.md

Fenced code block using a language tag followed by custom attributes for title and collapse state.

```kotlin
println("Hello world!")
```

--------------------------------

### Set custom parent

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/page-attributes.md

Specify a parent page title to organize the document hierarchy.

```markdown
---
parent: Custom Parent Page
---
Document content
```

--------------------------------

### Configure Table of Contents

Source: https://github.com/zeldigas/text2confl/blob/master/convert/src/test/resources/convert/confluence-specific.md

Insert a table of contents using the [TOC] tag, with optional parameters to control depth and formatting.

```markdown
This page will tell you about important widget `FOO` usage in our project

[TOC maxLevel=2]

## Setting up

....

## Using in project

....

## Tips and tricks
```

--------------------------------

### Mark as virtual page

Source: https://github.com/zeldigas/text2confl/blob/master/docs/reference/page-attributes.md

Use the _virtual_ attribute to create a hierarchy placeholder without modifying content.

```markdown
---
_virtual_: true
---
```
Tokens:
Raw