### 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 key,summary,assignee,reporter,status 20 project = SI ``` -------------------------------- ### 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=] ``` -------------------------------- ### 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 --user --password --space --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] ---- world ---- <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/ 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
Docs [reference](https://docs.spring.io/spring-kafka/reference/html)
Samples [sample](http://example.org/sample)
``` -------------------------------- ### 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/ ``` ```shell text2confl upload --docs . --confluence-url https://api.atlassian.com/ex/confluence/ ... ``` -------------------------------- ### 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/ \ --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 ++++ key,summary,assignee,reporter,status 20 project = SI ++++ ``` -------------------------------- ### 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 world ``` -------------------------------- ### 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 ``` -------------------------------- ### 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
Text for expand macro Arbitrary markdown here
``` -------------------------------- ### 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 --- ```