├── .gitignore ├── src ├── usage │ ├── index.md │ ├── npm-library.md │ ├── obsidian.md │ ├── npm-library │ │ └── md-to-adf.md │ ├── cli.md │ ├── docker.md │ └── github-actions.md ├── features │ ├── attachments │ │ └── Pasted image 20230413135017.png │ ├── index.md │ ├── mermaid.md │ ├── folder-structure.md │ ├── folder-note.md │ ├── callouts.md │ ├── wikilinks.md │ ├── image-upload.md │ ├── supported-markdown.md │ ├── mentions.md │ ├── yaml-frontmatter.md │ ├── raw-adf.md │ ├── comment-handling.md │ └── setting-sources.md ├── development │ ├── obsidian.md │ ├── cli.md │ └── guide.md ├── SUMMARY.md ├── thanks.md └── introduction.md ├── .markdown-confluence.json ├── theme └── head.hbs ├── book.toml ├── .github └── workflows │ ├── confluence.yml │ └── docs.yml └── LICENSE /.gitignore: -------------------------------------------------------------------------------- 1 | book 2 | -------------------------------------------------------------------------------- /src/usage/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '1343826' 4 | --- 5 | # Usage 6 | This is about the usage of the tools 7 | -------------------------------------------------------------------------------- /src/features/attachments/Pasted image 20230413135017.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/markdown-confluence/docs-markdown-confluence/HEAD/src/features/attachments/Pasted image 20230413135017.png -------------------------------------------------------------------------------- /src/usage/npm-library.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '1343852' 4 | --- 5 | 6 | # NPM Library Documentation 7 | 8 | * Please log an issue with what documentation you require 9 | -------------------------------------------------------------------------------- /src/features/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '1442146' 4 | --- 5 | # Features 6 | Currently not everything in Obsidian is supported but slowly increasing support where possible over time. 7 | -------------------------------------------------------------------------------- /src/usage/obsidian.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '1442183' 4 | --- 5 | 6 | # Obsidian Plugin Usage 7 | Go to [https://obsidian-confluence.com](https://obsidian-confluence.com) for usage information. 8 | -------------------------------------------------------------------------------- /.markdown-confluence.json: -------------------------------------------------------------------------------- 1 | { 2 | "confluenceBaseUrl": "https://markdown-confluence.atlassian.net", 3 | "confluenceParentId": "524353", 4 | "atlassianUserName": "andrew.mcclenaghan@gmail.com", 5 | "folderToPublish": ".", 6 | "contentRoot": "/github/workspace/src/", 7 | "firstHeadingPageTitle": true 8 | } 9 | -------------------------------------------------------------------------------- /theme/head.hbs: -------------------------------------------------------------------------------- 1 | 2 | 3 | -------------------------------------------------------------------------------- /book.toml: -------------------------------------------------------------------------------- 1 | [book] 2 | authors = ["andymac4182"] 3 | language = "en" 4 | multilingual = false 5 | src = "src" 6 | title = "Markdown Confluence Tools" 7 | create-missing = false 8 | 9 | [preprocessor.mermaid] 10 | command = "mdbook-mermaid" 11 | 12 | [preprocessor.yml-header] 13 | 14 | [output.html] 15 | git-repository-url = "https://github.com/markdown-confluence/docs-markdown-confluence" 16 | git-repository-icon = "fa-github" 17 | edit-url-template = "https://github.com/markdown-confluence/docs-markdown-confluence/edit/main/{path}" 18 | cname = "markdown-confluence.com" 19 | additional-js = ["mermaid.min.js", "mermaid-init.js"] 20 | -------------------------------------------------------------------------------- /src/development/obsidian.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '1835022' 4 | --- 5 | # 📘 Obsidian Development 6 | 7 | To work on Obsidian development, follow these steps: 8 | 9 | 1. Run `npm run dev-obsidian`. This command builds and watches code, pushing it into the `dev-vault` part of the repo. 10 | 2. Make sure you've set the appropriate settings, as they're excluded from the repo. 11 | 3. Use the `dev-vault` in Obsidian to test out the plugin. The `hot-reload` plugin is installed to automatically reload the plugin right after you save the code. 12 | 4. Sometimes Obsidian might act up, and you'll need to restart it. 13 | 5. Most importantly, have fun! 🎉 14 | -------------------------------------------------------------------------------- /src/development/cli.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '1736714' 4 | --- 5 | ## 🏗️ Building and Testing the CLI 6 | 7 | To build and test the CLI for the markdown-confluence project, follow these steps: 8 | 9 | ### 1. Build the Project 10 | 11 | Before you can test the CLI, you need to build the entire project. Run the following command: 12 | 13 | ```bash 14 | npm run build 15 | ``` 16 | 17 | This command builds all the packages within the workspace, including the CLI package. 18 | 19 | ### 2. Test the CLI 20 | 21 | After building the project, you can test the CLI using the output from the `dist` folder within the `cli` package. Run the following command: 22 | 23 | ```bash 24 | node ./packages/cli/dist/index.js [options] 25 | ``` 26 | 27 | Replace `[options]` with the appropriate options and commands for the markdown-confluence CLI. 28 | 29 | See [CLI Usage](../usage/cli.md) for a list of options. 30 | -------------------------------------------------------------------------------- /src/SUMMARY.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: false 3 | --- 4 | [Introduction](introduction.md) 5 | 6 | - [Usage](./usage/index.md) 7 | - [CLI](./usage/cli.md) 8 | - [Docker](./usage/docker.md) 9 | - [GitHub Actions](./usage/github-actions.md) 10 | - [NPM Library](./usage/npm-library.md) 11 | - [Markdown to ADF](./usage/npm-library/md-to-adf.md) 12 | - [Obsidian](./usage/obsidian.md) 13 | 14 | - [Supported Features](./features/index.md) 15 | - [Comments](./features/comment-handling.md) 16 | - [Supported Markdown](./features/supported-markdown.md) 17 | - [Folder Note](./features/folder-note.md) 18 | - [Folder Structure](./features/folder-structure.md) 19 | - [Image Upload](./features/image-upload.md) 20 | - [Mermaid Diagrams](./features/mermaid.md) 21 | - [YAML Frontmatter](./features/yaml-frontmatter.md) 22 | - [Callouts](./features/callouts.md) 23 | - [Wikilinks](./features/wikilinks.md) 24 | - [Setting Sources](./features/setting-sources.md) 25 | - [Mentions](./features/mentions.md) 26 | - [Raw ADF](./features/raw-adf.md) 27 | 28 | - [Development Guide](./development/guide.md) 29 | - [Obsidian](./development/obsidian.md) 30 | - [CLI](./development/cli.md) 31 | 32 | [Thanks](./thanks.md) 33 | [Changelog](CHANGELOG.md) 34 | -------------------------------------------------------------------------------- /src/thanks.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '2916353' 4 | --- 5 | # Thank you 6 | 7 | - Thanks for a great library for interacting with the Confluence api and also for being responsive to questions and contributions [https://github.com/MrRefactoring/confluence.js](https://github.com/MrRefactoring/confluence.js) 8 | - Atlassian teams, for Open Sourcing libraries that helped enable this project. Some packages that are used but not all. 9 | - Render ADF in React [https://atlaskit.atlassian.com/packages/editor/renderer](https://atlaskit.atlassian.com/packages/editor/renderer) 10 | - Convert Prosemirror to ADF [https://atlaskit.atlassian.com/packages/editor/editor-json-transformer](https://atlaskit.atlassian.com/packages/editor/editor-json-transformer) 11 | - Convert Markdown to Prosemirror (The Markdown transformer used was based on code originally from the NPM package) [https://atlaskit.atlassian.com/packages/editor/editor-markdown-transformer](https://atlaskit.atlassian.com/packages/editor/editor-markdown-transformer) 12 | - traverse is used extensively to mutate ADF elements [https://atlaskit.atlassian.com/packages/editor/adf-utils](https://atlaskit.atlassian.com/packages/editor/adf-utils) 13 | - Markdown-it is the core Markdown parser [https://github.com/markdown-it/markdown-it](https://github.com/markdown-it/markdown-it) 14 | -------------------------------------------------------------------------------- /.github/workflows/confluence.yml: -------------------------------------------------------------------------------- 1 | name: Docs to Confluence 2 | on: 3 | push: 4 | branches: 5 | - main 6 | workflow_dispatch: 7 | 8 | permissions: 9 | contents: read 10 | 11 | # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. 12 | # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. 13 | concurrency: 14 | group: "confluence" 15 | cancel-in-progress: false 16 | 17 | jobs: 18 | deploy: 19 | runs-on: ubuntu-latest 20 | permissions: 21 | contents: write 22 | steps: 23 | - name: Harden Runner 24 | uses: step-security/harden-runner@6b3083af2869dc3314a0257a42f4af696cc79ba3 # v2.3.1 25 | with: 26 | egress-policy: audit # TODO: change to 'egress-policy: block' after couple of runs 27 | 28 | - uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2 29 | 30 | - name: Publish to Confluence 31 | uses: markdown-confluence/publish-action@main 32 | with: 33 | atlassianApiToken: ${{ secrets.ATLASSIAN_API_TOKEN }} 34 | 35 | - name: Commit and push changes 36 | run: | 37 | git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com" 38 | git config --global user.name "github-actions[bot]" 39 | git add -A 40 | git diff --quiet && git diff --staged --quiet || git commit -m "Automated changes" 41 | git push 42 | -------------------------------------------------------------------------------- /src/features/mermaid.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '1343850' 4 | --- 5 | ## Mermaid Diagram Support 6 | 7 | As Confluence does not currently support [Mermaid](https://mermaid.js.org/) diagrams natively, the Confluence Integration plugin for Obsidian provides a workaround to enable the rendering of Mermaid diagrams. The plugin includes a copy of Mermaid that is injected into a [BrowserWindow](https://www.electronjs.org/docs/latest/api/browser-window), which is then used to render each diagram and capture a screenshot as a PNG image. This image is then uploaded to Confluence for rendering. 8 | 9 | ### Usage 10 | 11 | 1. Create a Mermaid diagram in your Obsidian note using the appropriate syntax. 12 | 13 | _Insert example here_ 14 | 15 | 2. When you publish your files using the Confluence Integration plugin, the plugin will automatically render the Mermaid diagram, capture a screenshot, and upload it as a PNG image to Confluence. 16 | 17 | _Insert example here_ 18 | 19 | ### Naming Convention 20 | 21 | To prevent conflicts with file names when uploading diagrams to Confluence, the plugin uses the following naming convention for the uploaded diagram images: 22 | 23 | ``` 24 | RenderedMermaidChart-${MD5 of diagram text}.png 25 | ``` 26 | 27 | This naming convention helps to avoid conflicts and ensures that each uploaded diagram image has a unique identifier. 28 | 29 | ### Limitations 30 | 31 | Currently, the Confluence Integration plugin does not support deleting diagram images from Confluence. 32 | -------------------------------------------------------------------------------- /src/features/folder-structure.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '1409444' 4 | --- 5 | ## Folder Structure 6 | 7 | The folder structure feature is designed to help you easily manage and organize your files when they are published to Confluence. The plugin will identify the first common folder and match the folder structure in your local Obsidian vault in Confluence. This also ensures the plugin will move pages on Confluence to align with your local file layout. 8 | 9 | ### Usage 10 | 11 | When you publish your files, the plugin will automatically find the first common folder and upload the files according to that folder structure. 12 | 13 | ![](attachments/Pasted%20image%2020230413135017.png) 14 | 15 | ### Preventing Pages from Moving 16 | 17 | If you don't want a specific page to be moved or you want to move a Confluence page outside of your page tree into another Space, you can use the `connie-dont-change-parent-page` tag. This will prevent the plugin from moving the page back to the file tree where it would expect the page to live when matching the local file tree. 18 | 19 | ```yaml 20 | --- 21 | connie-dont-change-parent-page: true 22 | --- 23 | ``` 24 | 25 | ### Moving a Folder with Folder Note 26 | 27 | You can use the folder structure feature in conjunction with the [Folder Note](./folder-note.md) feature to move a whole folder of files to a new location in Confluence. By adding the `connie-dont-change-parent-page` tag to the Folder Note, you can prevent the pages within the folder from being moved back to their original locations in the file tree. 28 | -------------------------------------------------------------------------------- /src/features/folder-note.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '1442161' 4 | --- 5 | ## Folder Notes 6 | 7 | The Folder Note feature allows you to define and manage the content for the "Folder" in Confluence by creating a file directly in the folder with the same name as the folder. This feature ensures that the file is not uploaded as a child of the page in Confluence, but instead becomes the page under which other files are uploaded. 8 | 9 | ### Usage 10 | 11 | 1. In your Obsidian vault, create a file directly within the folder you want to manage in Confluence. The file should have the same name as the folder. 12 | 2. Add your desired content to the file, which will be used to represent the folder in Confluence. 13 | 3. When you publish your files using the Confluence Integration plugin, the file will be uploaded to Confluence as the folder representation, and other files within the folder will be uploaded as child pages underneath it. 14 | 15 | ### Benefits 16 | 17 | By utilizing the Folder Note feature, you can achieve the following benefits: 18 | 19 | - Maintain a clear and organized folder structure in Confluence that matches your Obsidian vault. 20 | - Easily manage the content and hierarchy of your pages in Confluence. 21 | - Move a folder of files to a new Space in Confluence. 22 | - Seamlessly upload files as child pages underneath the corresponding folder representation in Confluence. 23 | 24 | 25 | # Obsidian Use 26 | You can use this feature in Obsidian using the [Obsidian folder notes](https://github.com/LostPaul/obsidian-folder-notes/tree/main) plugin. 27 | -------------------------------------------------------------------------------- /src/features/callouts.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '3047425' 4 | --- 5 | # Callouts 6 | 7 | The Callouts feature allows you to transform Markdown callouts, also known as admonitions, into Atlassian Document Format (ADF) [Panels](https://support.atlassian.com/confluence-cloud/docs/insert-the-info-tip-note-and-warning-macros/). This feature supports both normal and foldable callouts. 8 | 9 | ## Normal Callouts 10 | 11 | Normal callouts are converted to [Panels](https://support.atlassian.com/confluence-cloud/docs/insert-the-info-tip-note-and-warning-macros/) in Confluence. 12 | 13 | ### Example: 14 | ```md 15 | > [!note] 16 | > Lorem ipsum dolor sit amet 17 | ``` 18 | 19 | 20 | ## Foldable Callouts 21 | 22 | Foldable callouts are converted to [Expand Macros](https://support.atlassian.com/confluence-cloud/docs/insert-the-expand-macro/) in Confluence. Note that Expand Macros do not support the same colors and formatting that Panels do. 23 | 24 | ### Example: 25 | ```md 26 | > [!faq]- Are callouts foldable? 27 | > Yes! In a foldable callout, the contents are hidden when the callout is collapsed. 28 | ``` 29 | 30 | ## Nested Callouts 31 | 32 | Due to Confluence restrictions, nested callouts are not supported. 33 | 34 | ## Supported Features 35 | 36 | - Title 37 | - Types: Refer to the [supported types](https://github.com/markdown-confluence/markdown-confluence/blob/main/src/MarkdownTransformer/callout.ts#L8-L70) 38 | - Foldable 39 | 40 | For more information on Obsidian callouts, visit the [Obsidian documentation](https://help.obsidian.md/Editing+and+formatting/Callouts). 41 | 42 | 43 | -------------------------------------------------------------------------------- /src/features/wikilinks.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '1278470' 4 | --- 5 | ## Wikilinks Support 6 | 7 | The Confluence Integration plugin for Obsidian offers basic support for Wikilinks. This support is limited to linking to other files that are being published. If a Wikilink refers to a page that is not set to be published, the link will be removed during the publishing process and will be rendered as plain text in Confluence. 8 | 9 | Wikilinks can be used to connect pages within a single Confluence site, including across multiple spaces. 10 | 11 | When using Wikilinks, the plugin supports three ways to provide information about the link: 12 | 13 | ### Link to Page 14 | 15 | ```md 16 | [[Page To Link To]] 17 | ``` 18 | 19 | This syntax creates a [smart link](https://community.atlassian.com/t5/Confluence-articles/Smart-Links-a-richer-way-to-hyperlink/ba-p/1412786) to the specified page, displaying the page title and image. 20 | 21 | ### Link to Header 22 | 23 | ```md 24 | [[Page To Link To#Header]] 25 | ``` 26 | 27 | This syntax creates a [smart link](https://community.atlassian.com/t5/Confluence-articles/Smart-Links-a-richer-way-to-hyperlink/ba-p/1412786) to the specified page, displaying the page title and image. The link will point to a specific header within the page. 28 | 29 | ### Alias 30 | 31 | ```md 32 | [[Page To Link To|Alias To Display]] 33 | [[Page To Link To#Header|Alias To Display]] 34 | ``` 35 | 36 | This syntax allows you to define an alias for the link, which will be displayed instead of the original page title or header. The link will be rendered as regular text that points to the specified page and header (if included). 37 | -------------------------------------------------------------------------------- /.github/workflows/docs.yml: -------------------------------------------------------------------------------- 1 | name: Docs 2 | on: 3 | push: 4 | branches: 5 | - main 6 | 7 | permissions: 8 | contents: read 9 | 10 | # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. 11 | # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. 12 | concurrency: 13 | group: "pages" 14 | cancel-in-progress: false 15 | 16 | jobs: 17 | deploy: 18 | runs-on: ubuntu-latest 19 | permissions: 20 | contents: read 21 | pages: write 22 | id-token: write 23 | steps: 24 | - name: Harden Runner 25 | uses: step-security/harden-runner@6b3083af2869dc3314a0257a42f4af696cc79ba3 # v2.3.1 26 | with: 27 | egress-policy: audit # TODO: change to 'egress-policy: block' after couple of runs 28 | 29 | - uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2 30 | with: 31 | fetch-depth: 0 32 | - name: Install mdbook 33 | run: | 34 | mkdir mdbook 35 | curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.27/mdbook-v0.4.27-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook 36 | echo `pwd`/mdbook >> $GITHUB_PATH 37 | cargo install mdbook-mermaid 38 | cargo install mdbook-yml-header 39 | - name: Deploy GitHub Pages 40 | run: | 41 | # This assumes your book is in the root of your repository. 42 | # Just add a `cd` here if you need to change to another directory. 43 | curl https://raw.githubusercontent.com/obsidian-confluence/obsidian-confluence/main/CHANGELOG.md --output src/CHANGELOG.md 44 | mdbook-mermaid install . 45 | mdbook build 46 | cd ./book 47 | npx static-sitemap-cli --no-clean --base https://markdown-confluence.com 48 | - name: Setup Pages 49 | uses: actions/configure-pages@f156874f8191504dae5b037505266ed5dda6c382 # v3.0.6 50 | - name: Upload artifact 51 | uses: actions/upload-pages-artifact@64bcae551a7b18bcb9a09042ddf1960979799187 # v1.0.8 52 | with: 53 | # Upload entire repository 54 | path: './book' 55 | - name: Deploy to GitHub Pages 56 | id: deployment 57 | uses: actions/deploy-pages@af48cf94a42f2c634308b1c9dc0151830b6f190a # v2.0.1 58 | -------------------------------------------------------------------------------- /src/features/image-upload.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '1409446' 4 | --- 5 | ## Image Uploads: Bedrock's Picto-Rama: Rockin' Pages with Dino-Sized Fun 6 | 7 | Unleash your inner caveman and include images in your markdown-confluence pages with both wikilinks and regular markdown styles. They'll search high and low for the right file, just like a hungry dinosaur on the hunt. 8 | 9 | Here are the two markdown formats for adding images: 10 | 11 | ```md 12 | ![[cave_painting.png]] 13 | ``` 14 | or 15 | ```md 16 | ![](images/dinosaur.png) 17 | ``` 18 | 19 | Paths for these images are always relative to the markdown file they're in, so you'll never lose your way in the Bedrock wilderness. 20 | 21 | Need to grab a file from another folder? Use `../` like this: 22 | 23 | ```md 24 | ![](../other_cave/images/sabertooth.png) 25 | ``` 26 | 27 | ## Dino-Sized Attachments Adventure 28 | 29 | Whoa, hold onto your dino-sized hats! When you add images to a page, they'll hitch a ride as attachments for that specific page in Confluence, just like a pterodactyl flying through the sky. And if the same image struts its stuff on multiple pages, it'll be attached to each one, spreading prehistoric cheer all around! 30 | 31 | ### No More Duplicate Dino Images! 32 | 33 | To avoid fetching the image from Confluence every time you run the publish process, our plugin uses the hash (MD5) of the image file and stores it as a comment on the attachment. This way, images are only uploaded once per page and updated only when the contents change. 34 | 35 | To prevent name clashes when uploading images to Confluence, we use this unique naming convention: 36 | 37 | ``` 38 | ${Absolute Path MD5}-${Filename without path} 39 | ``` 40 | 41 | This ensures each image has a unique identifier, just like a dino's footprint. 42 | 43 | ### Limitations 44 | 45 | Currently, our Confluence Integration plugin can't delete images from Confluence. But hey, neither could Fred Flintstone! 46 | 47 | ### References 48 | 49 | - [Embed an image in a note - Obsidian Help](https://help.obsidian.md/Linking+notes+and+files/Embedding+files#Embed+an+image+in+a+note) 50 | - [Manage uploaded files - Atlassian Support](https://support.atlassian.com/confluence-cloud/docs/manage-uploaded-files/) 51 | 52 | Now you're ready to make your documentation a modern Stone Age masterpiece! 53 | -------------------------------------------------------------------------------- /src/features/supported-markdown.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '1442188' 4 | --- 5 | ## Supported Markdown Features 6 | 7 | The Confluence Integration plugin for Obsidian supports a variety of Markdown features, allowing you to create rich and interactive content in your Confluence pages. The following Markdown elements are supported: 8 | 9 | ### Blockquotes 10 | 11 | Blockquotes are supported and can be created using the `>` character followed by the text you want to quote. 12 | 13 | ### Callouts 14 | 15 | Callouts can be created using the [Callouts](./callouts.md) feature, which allows you to create custom, styled callout boxes in Confluence. 16 | 17 | ### Code 18 | 19 | Code blocks and inline code can be created using triple backticks (\`\`\`) for blocks and single backticks (\`) for inline code. 20 | 21 | ### Diagrams (Mermaid.js) 22 | 23 | Mermaid.js diagrams are supported through the plugin's Mermaid diagram feature, which renders diagrams as images in Confluence. 24 | 25 | ### Images (Image Upload Supported) 26 | 27 | Image embedding and uploading are supported through the Image Upload feature. Images included in a page will be uploaded as attachments in Confluence. This includes support for transcluded images. 28 | 29 | ### Linking 30 | 31 | - Wikilinks: The plugin supports basic Wikilinks functionality, allowing you to link to other files that are being published. 32 | - Extenal links: Rendered as a Smart Link 33 | 34 | ### Headings 35 | 36 | Headings can be created using the `#` character followed by the heading text. Multiple levels of headings can be created by using multiple `#` characters. 37 | 38 | ### Horizontal Bar 39 | 40 | Horizontal bars can be created using three hyphens (`---`). 41 | 42 | ### Lists 43 | 44 | Both ordered and unordered lists can be created using Markdown syntax. 45 | 46 | ### Text Formatting 47 | 48 | - Strike-through: Text can be formatted with strike-through using double tildes (`~~`). 49 | - Emphasis: Emphasis can be added using single (`*`) or double (`**`) asterisks for italic and bold formatting, respectively. 50 | 51 | ### Tables 52 | 53 | Tables can be created using Markdown syntax with pipes (`|`) and hyphens (`-`) to define the table structure. 54 | 55 | ### Callouts 56 | 57 | Callouts can be created using the [Callouts](./callouts.md) feature. This allows you to create custom, styled callout boxes in Confluence. 58 | 59 | -------------------------------------------------------------------------------- /src/features/mentions.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '3506177' 4 | --- 5 | # 🚀 Mentions Support: It's Time to Have Fun with Mentions! 🎉 6 | 7 | Hello there, fellow adventurer! Are you ready to embark on a thrilling journey to bring your Markdown Confluence skills to the next level? Do you want to engage your teammates and colleagues in a fun and interactive way? Say no more, as you've just arrived at the perfect destination! 🌟 8 | 9 | Introducing **Mentions Support** in Markdown-Confluence! A feature that allows you to mention your teammates with flair and pizzazz. It's super easy and fun to use. Let's get started! 10 | 11 | ## 🎩 The Magic Mention Formula 12 | 13 | To conjure up a mention, you just need to type the following magical incantation: 14 | 15 | ``` 16 | [[mentions:{userid}|@{Users Name}]] 17 | ``` 18 | 19 | This magical spell transforms into a marvelous Atlassian Document Format Mention node. You can learn more about the enchanting world of nodes [here](https://developer.atlassian.com/cloud/jira/platform/apis/document/nodes/mention/). 20 | 21 | ## 🔍 Seeking the User ID Treasure 22 | 23 | But wait! To complete the spell, you'll need the mystical _User ID_. Fear not, for we shall guide you on your quest! 24 | 25 | 1. Set sail to the land of **Teams** 🏴‍☠️ 26 | 2. Unleash the power of the **Search** 🔍 27 | 3. Click on the desired user to reveal their secret URL 🗝️ 28 | 29 | For example, if the search URL is: 30 | ``` 31 | https://markdown-confluence.atlassian.net/wiki/people/search 32 | ``` 33 | 34 | And you discover the user's URL to be: 35 | ``` 36 | https://markdown-confluence.atlassian.net/wiki/people/557058:aea5688c-52b9-4d15-aabe-96def1abc413 37 | ``` 38 | 39 | Eureka! You've found the hidden treasure: the User ID! In this case: 40 | ``` 41 | 557058:aea5688c-52b9-4d15-aabe-96def1abc413 42 | ``` 43 | 44 | ## 🌈 Making Mention Magic Happen 45 | 46 | Now that you've obtained the User ID, you can cast the magical mention spell! 47 | 48 | For instance, if you want to mention `Captain Confluence` with their User ID, you'd simply type: 49 | ``` 50 | [[mentions:557058:aea5688c-52b9-4d15-aabe-96def1abc413|@Captain Confluence]] 51 | ``` 52 | 53 | And there you have it, brave adventurer! You've mastered the art of **Mentions Support** in Markdown-Confluence. Spread the joy and summon your teammates in a fun and captivating way, making your collaboration experience more delightful than ever! 🎊🎉 54 | -------------------------------------------------------------------------------- /src/development/guide.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '1736718' 4 | --- 5 | # Markdown-Confluence Development Guide 🚀 6 | 7 | Welcome to the development documentation for the markdown-confluence project! Let's dive into the development process for this fantastic TypeScript project that uses `tsc` and `esbuild` for building and packaging. 8 | 9 | ## 🛠️ Development Scripts 10 | 11 | Here's a detailed overview of the essential scripts that keep our project flowing: 12 | 13 | ### 1. dev-obsidian 14 | 15 | ```bash 16 | npm run dev --workspace=@markdown-confluence/lib & npm run dev --workspace=@markdown-confluence/mermaid-electron-renderer & npm run dev --workspace=obsidian-confluence 17 | ``` 18 | 19 | `dev-obsidian` is used for local development of the Obsidian plugin. This script simultaneously watches and builds code for the `lib`, `mermaid-electron-renderer`, and `obsidian-confluence` workspaces. 20 | 21 | ### 2. build 22 | 23 | ```bash 24 | npm run build -ws --if-present 25 | ``` 26 | 27 | `build` is used to build all packages within the workspace. It's essential to run this command whenever you add a new type or modify an exported type across the package boundary to ensure everything is updated accordingly. 28 | 29 | ### 3. fmt 30 | 31 | ```bash 32 | npm run fmt -ws --if-present 33 | ``` 34 | 35 | `fmt` is a convenient script for formatting all the code in the workspace using Prettier. This command helps maintain code consistency and readability throughout the project. 36 | 37 | ### 4. test 38 | 39 | ```bash 40 | npm test -ws --if-present 41 | ``` 42 | 43 | `test` is used to run all the tests within the workspace. It helps ensure that new changes don't introduce unexpected issues or break existing functionality. 44 | 45 | ⚠️ **Note:** If you add a new type or modify an exported type across the package boundary, make sure to run `npm run build`. 46 | 47 | ## 🌐 Mono Repo Development 48 | 49 | Development is done in the mono repo `markdown-confluence/markdown-confluence`. 50 | 51 | ### Code Consistency and Formatting 52 | 53 | We use `husky` to help keep files formatted, but please rely on `eslint` and `prettier` to maintain code consistency. These tools run as part of the CI in check mode. 54 | 55 | ### TypeScript Strict Mode 56 | 57 | TypeScript strict mode is enabled to assist with type checking as much as possible. 58 | 59 | ## Have Fun 60 | 61 | Happy coding, and we hope you enjoy contributing to the delightful universe of markdown-confluence! 62 | -------------------------------------------------------------------------------- /src/features/yaml-frontmatter.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '1442185' 4 | --- 5 | ## YAML Frontmatter Support 6 | 7 | The Confluence Integration plugin for Obsidian supports various YAML frontmatter items, allowing you to customize and modify how the publish process works. 8 | 9 | ### connie-title 10 | 11 | This item allows you to override the title of the Confluence page without renaming the Obsidian file. 12 | 13 | #### Example 14 | 15 | ```yaml 16 | --- 17 | connie-title: New Title 18 | --- 19 | ``` 20 | 21 | ### connie-frontmatter-to-publish 22 | 23 | This item is set to an array of frontmatter keys that you want to include in a table at the beginning of the document. 24 | 25 | #### Example 26 | 27 | The example below will include four rows in the Frontmatter table at the beginning of the document. 28 | 29 | ```yaml 30 | --- 31 | array-singleline: 32 | - testing 33 | - testing 34 | array-multiline: 35 | - testing tag1 36 | - testing tag2 37 | string: Testing 38 | boolean-value: true 39 | connie-frontmatter-to-publish: 40 | - array-singleline 41 | - array-multiline 42 | - string 43 | - boolean-value 44 | --- 45 | ``` 46 | 47 | ### tags 48 | 49 | This item reuses the [Tags](https://help.obsidian.md/Editing+and+formatting/Tags) feature from Obsidian, allowing you to specify [Confluence Labels](https://support.atlassian.com/confluence-cloud/docs/use-labels-to-organize-your-content/) that will be applied to the page. Tags must be a single string without spaces and can include a hyphen (-). 50 | 51 | #### Example 52 | 53 | ```yaml 54 | --- 55 | tags: 56 | - testing 57 | - test-tag 58 | --- 59 | ``` 60 | 61 | ### connie-page-id 62 | 63 | This item specifies the Confluence Page ID that the file will be uploaded to. It is set for every file. If it is not set when you publish a file, it will be assigned after the page has been created for that file in Confluence. 64 | 65 | #### Example 66 | 67 | ``` 68 | --- 69 | connie-page-id: "12312" 70 | --- 71 | ``` 72 | 73 | ### connie-dont-change-parent-page 74 | 75 | If you want to move a Confluence page outside of your page tree and into another Space, you can use this item to prevent the page from being moved back to the file tree where the plugin would expect the page to be when matching the local file tree. When used with the [Folder Note](./folder-note.md) feature, you can move an entire folder of files to a new location in Confluence. 76 | 77 | #### Example 78 | 79 | ```yaml 80 | --- 81 | connie-dont-change-parent-page: true 82 | --- 83 | ``` 84 | -------------------------------------------------------------------------------- /src/usage/npm-library/md-to-adf.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '5144577' 4 | --- 5 | # ❄️ _The Frosty Chronicles of Markdown to Atlassian Document Format Conversion_ ❄️ 6 | 7 | Hello, friends, it's me again - Olaf! And boy, do I like warm hugs! But today, we're venturing a bit away from the land of warmth and into the magical frosty realm of converting Markdown to Atlassian Document Format (ADF) using the `@markdown-confluence/lib` function. Just like a good snowfall, this might seem a bit overwhelming at first, but don't worry, I'll guide you through it all. 8 | 9 | ## 🎇 Spellcasting 101: `parseMarkdownToADF` 10 | 11 | Our journey begins with our first spell, `parseMarkdownToADF`. This enchanting piece of incantation transforms the everyday language of Markdown into the mysterious tongue of ADF. It requires two ingredients: a string of `markdown` and a `confluenceBaseUrl`. 12 | 13 | ```typescript 14 | const magicalMarkdown = "# Welcome to Arendelle"; 15 | const confluenceBaseUrl = "https://arendelle.atlassian.net/wiki"; 16 | 17 | let adfNodes = parseMarkdownToADF(magicalMarkdown, confluenceBaseUrl); 18 | ``` 19 | Just like that, it conjures up a flurry of nodes which are then delicately shaped into a format that our friends at Atlassian can understand. Now that we've whipped up our magic snowstorm, let's step back and admire our handiwork. 20 | 21 | ## 🎇 Transmutation Magic: `convertMDtoADF` 22 | 23 | After our initial spellcasting, we have another magical formula to share. This one's called `convertMDtoADF` and it's quite the spectacle. Unlike our previous enchantment, this spell takes an entire Markdown file and some Confluence settings to create a grand ADF spectacle. 24 | 25 | ```typescript 26 | const markdownFile: MarkdownFile = { 27 | contents: "# Welcome to Arendelle", 28 | ... 29 | }; 30 | 31 | const confluenceSettings: ConfluenceSettings = { 32 | confluenceBaseUrl: "https://arendelle.atlassian.net/wiki", 33 | ... 34 | }; 35 | 36 | let adfFile = convertMDtoADF(markdownFile, confluenceSettings); 37 | ``` 38 | And just like that, our Markdown file is transformed into an ADF masterpiece, ready to take center stage on our Confluence platform. 39 | 40 | Our magical journey is complete, dear friends. But remember, the joy is in the journey, not the destination. So don't be afraid to practice your spells, make a few mistakes, and get a bit frosty in the process. The magic of transformation is all around us, and with these spells, you're well on your way to becoming a true snow wizard! 41 | 42 | And don't forget - warm hugs make the journey all the more magical. 🤗 43 | -------------------------------------------------------------------------------- /src/features/raw-adf.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '3735553' 4 | --- 5 | # Markdown-Confluence: Unleashing the Ninja Power of Raw Atlassian Document Format Blocks 🥷 6 | 7 | Greetings, honorable Markdown-Confluence user! Are you ready to unleash the ninja power of raw Atlassian Document Format (ADF) blocks in your Markdown? Behold, the secret technique to render ADF elements in your Markdown-Confluence documents! 🐉 8 | 9 | ## The Secret Art of Raw ADF Blocks 10 | 11 | The ancient ninja art of raw ADF blocks allows you to embed ADF content directly into your Markdown document using a special code block. To master this technique, you must first learn the sacred format for raw blocks: 12 | 13 | ~~~md 14 | ```adf 15 | {"type":"yourADFType","attrs":{...},"content":[...]} 16 | ``` 17 | ~~~ 18 | 19 | The path to enlightenment begins with the following example, young grasshopper: 20 | 21 | ~~~md 22 | ```adf 23 | {"type":"decisionList","attrs":{"localId":"39becc7a-48c3-4e2d-a6bc-35648d6689a2"},"content":[{"type":"decisionItem","attrs":{"state":"DECIDED","localId":"95268b83-2fc0-4801-9b4f-e5c42cc530e6"},"content":[{"text":"Decision to track","type":"text"}]},{"type":"decisionItem","attrs":{"state":"DECIDED","localId":"564ab974-e6fe-48d2-a144-507f5ec30906"},"content":[{"text":"Testing Decision 2","type":"text"}]}]} 24 | ``` 25 | ~~~ 26 | 27 | This mystical incantation will transform into an ADF node, as described in the ancient scrolls of Atlassian: [Atlassian Document Format Structure](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/) 28 | For the latest information on nodes check out [https://atlaskit.atlassian.com/packages/editor/adf-schema](https://atlaskit.atlassian.com/packages/editor/adf-schema). You can use unpkg to view the nodes folder under types and see what attributes you can set on each node type. [https://unpkg.com/browse/@atlaskit/adf-schema@25.6.0/dist/types/schema/nodes/](https://unpkg.com/browse/@atlaskit/adf-schema@25.6.0/dist/types/schema/nodes/). NB. This unpkg link is for a particular version. Make sure you use the latest version for any new updates. 29 | 30 | ## The Forbidden API Technique 31 | 32 | To peer into the heart of the `atlaskit_doc_format`, which stores the ADF content, you must invoke the power of the forbidden API. Gaze upon its hidden knowledge: 33 | 34 | [https://markdown-confluence.atlassian.net/wiki/rest/api/content/2916353?expand=body.atlas_doc_format](https://markdown-confluence.atlassian.net/wiki/rest/api/content/2916353?expand=body.atlas_doc_format) 35 | 36 | To adapt this technique to your own Confluence domain and page, replace the domain with your Confluence site domain and `2916353` with the page id you wish to reveal the ADF for. 37 | 38 | ## Conclusion 39 | 40 | You have now learned the secret ninja art of raw ADF blocks in Markdown-Confluence. Use your newfound power wisely, and remember: with great power comes great responsibility. Now, go forth and create stunning Confluence documents like the ninja you are! 🥷📜💥 41 | -------------------------------------------------------------------------------- /src/usage/cli.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '1409233' 4 | --- 5 | # NPM CLI 6 | 7 | This tool is designed to make the process of publishing documentation to Confluence faster, more streamlined, and more efficient. It supports multiple authentication methods and allows you to publish your Markdown files to any Confluence space or page of your choice. 8 | 9 | With its user-friendly and clear documentation, this tool is accessible to everyone, regardless of their technical expertise. Whether you're a software developer, technical writer, or project team member, this CLI tool is a game-changer for anyone who needs to publish documentation to Confluence. 10 | 11 | ## Configuration 12 | Setting up the configuration for an application is an essential step to ensure its proper functioning. For non-technical users, it is important to understand the basics of managing settings. Generally, there are two types of settings you'll need to work with: non-sensitive values and sensitive values. 13 | 14 | For non-sensitive values like the website's address, page identifiers, your username, or the folders you're working with, using a configuration file is the preferred method. A configuration file is a simple, organized, and user-friendly way to store settings. You don't need technical expertise to manage it, as the settings are typically listed in a readable format. By keeping these settings in a separate file, you can easily find and change them whenever needed without worrying about breaking the application. 15 | 16 | Sensitive values, such as API tokens or passwords, should be handled with more care. Instead of storing them in a configuration file, it's recommended to use environment variables. Environment variables are a secure way to store sensitive information because they are accessible only to the application when needed and not exposed to others. As a non-technical user, you may need assistance from a technical team member or follow step-by-step instructions provided by the application to set up environment variables. By separating your settings into non-sensitive and sensitive categories and storing them appropriately, you can help ensure your application runs smoothly and securely. 17 | 18 | ### Example setup 19 | #### [.markdown-confluence.json](https://github.com/markdown-confluence/docs-markdown-confluence/blob/main/.markdown-confluence.json) 20 | ```json 21 | { 22 | "confluenceBaseUrl": "https://markdown-confluence.atlassian.net", 23 | "confluenceParentId": "524353", 24 | "atlassianUserName": "andrew.mcclenaghan@gmail.com", 25 | "folderToPublish": "." 26 | } 27 | ``` 28 | 29 | #### Environment Variables 30 | ##### macOS / Linux 31 | ```bash 32 | export ATLASSIAN_API_TOKEN="YOUR API TOKEN" 33 | ``` 34 | 35 | ##### Windows 36 | ```command 37 | set ATLASSIAN_API_TOKEN="YOUR API TOKEN" 38 | ``` 39 | [https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/set_1](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/set_1) 40 | 41 | 42 | #### CLI Command 43 | ```bash 44 | npx @markdown-confluence/cli 45 | ``` 46 | 47 | -------------------------------------------------------------------------------- /src/usage/docker.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '1343688' 4 | --- 5 | # Docker Image 6 | 7 | The `ghcr.io/markdown-confluence/publish:latest` Docker image is a ready-to-use container that wraps up the npm CLI and has the same arguments. By using this Docker image, you can quickly start publishing your Markdown files to Confluence without the need to set up the npm CLI tool manually. 8 | 9 | ## Usage 10 | 11 | To use the `ghcr.io/markdown-confluence/publish:latest` Docker image, follow these steps: 12 | 13 | 1. Create a `.markdown-confluence.json` configuration file in your project directory as described in the "Example setup" section above. 14 | 15 | 2. Set up environment variables for sensitive information like the Atlassian API token. 16 | 17 | 3. Run the Docker container using the following command: 18 | 19 | ```bash 20 | docker run -it --rm -v "$(pwd):/content" -e ATLASSIAN_API_TOKEN ghcr.io/markdown-confluence/publish:latest 21 | ``` 22 | 23 | This command does the following: 24 | 25 | - `-it`: Runs the Docker container interactively, allowing you to see the output and interact with the running process if necessary. 26 | 27 | - `--rm`: Removes the container once the process has completed. 28 | 29 | - `-v "$(pwd):/content"`: Maps your current working directory (where your configuration file and Markdown files are located) to the `/content` volume inside the container. This allows the container to access your files. 30 | 31 | - `-e ATLASSIAN_API_TOKEN`: Loads environment variables from the current console. 32 | 33 | ### Example setup 34 | #### [.markdown-confluence.json](https://github.com/markdown-confluence/docs-markdown-confluence/blob/main/.markdown-confluence.json) 35 | ```json 36 | { 37 | "confluenceBaseUrl": "https://markdown-confluence.atlassian.net", 38 | "confluenceParentId": "524353", 39 | "atlassianUserName": "andrew.mcclenaghan@gmail.com", 40 | "folderToPublish": ".", 41 | } 42 | ``` 43 | 44 | #### Environment Variables 45 | ##### macOS / Linux 46 | ```bash 47 | export ATLASSIAN_API_TOKEN="YOUR API TOKEN" 48 | ``` 49 | 50 | ##### Windows 51 | ```command 52 | set ATLASSIAN_API_TOKEN="YOUR API TOKEN" 53 | ``` 54 | [https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/set_1](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/set_1) 55 | 56 | 57 | ## Updating the Docker Image 58 | 59 | To update the Docker image to the latest version, run the following command: 60 | 61 | ```bash 62 | docker pull ghcr.io/markdown-confluence/publish:latest 63 | ``` 64 | 65 | This command fetches the latest version of the `ghcr.io/markdown-confluence/publish:latest` Docker image and replaces the existing one on your system. 66 | 67 | ## Conclusion 68 | 69 | By using the `ghcr.io/markdown-confluence/publish:latest` Docker image, you can quickly and easily publish your Markdown files to Confluence without any additional setup. With its straightforward configuration and seamless integration with Docker, this tool is a valuable resource for anyone who needs to work with Confluence and Markdown files. 70 | 71 | -------------------------------------------------------------------------------- /src/introduction.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '1442144' 4 | --- 5 | # Markdown to Confluence Tools 6 | 7 | Hello there, Markdown aficionados and Confluence connoisseurs! We're excited to introduce you to the markdown-confluence project, a seamless solution that bridges the gap between the elegant simplicity of Markdown and the powerful flexibility of Confluence. We understand your passion for the ease and convenience of Markdown writing, and we're committed to ensuring you can continue to enjoy it while effortlessly publishing your content on Confluence. 8 | 9 | Our suite of tools, including an Obsidian plugin, npm CLI, Docker CLI, GitHub Action, and npm library, enables you to smoothly convert your Markdown files to Atlassian Document Format (ADF) and integrate them seamlessly with Confluence. 10 | 11 | The markdown-confluence project was born from the desire to simplify the publishing process, making it a delightful experience for Markdown enthusiasts who also work with Confluence. We believe that the best tools should make life easier and more enjoyable. That's why we've designed an opinionated, streamlined workflow that makes the publishing process a breeze, while still allowing for customization and flexibility. Obsidian.md is our recommended editor, but have no fear! Our tools are compatible with any Markdown files, so you're free to choose the setup that suits you best. 12 | 13 | As we dive into the wonderful world of markdown-confluence, we're eager to grow a vibrant community around this project and are thrilled to have you as part of this adventure. We envision a future where our users not only appreciate the simplicity and efficiency of our tools but also find joy in sharing ideas, collaborating, and contributing to the project. So, go ahead and give markdown-confluence a spin! Experience firsthand how it can revolutionize your Markdown-to-Confluence workflow. And remember, we're here to support you every step of the way, making sure your journey into the delightful universe of markdown-confluence is nothing short of amazing! 🎉 14 | 15 | ## Further Resources 16 | 17 | In this documentation, we have explored various aspects of the Markdown-Confluence project. Below, you will find quick summaries and links to each section for easy reference. 18 | 19 | 1. [**Github Org**](https://github.com/markdown-confluence) - This is the main organization page on GitHub for the Markdown-Confluence project, where you can find all related repositories and ongoing development efforts. 20 | 2. [**Github mono repo**](https://github.com/markdown-confluence/markdown-confluence) - This is the mono repository for the Markdown-Confluence project, containing the core source code and modules for the project's functionality. 21 | 3. [**Edit docs**](https://github.com/markdown-confluence/docs-markdown-confluence) - This repository houses the editable Markdown source files for the documentation, where you can contribute to or edit the project documentation directly. 22 | 4. [**Docs rendered in Confluence**](https://markdown-confluence.atlassian.net/wiki/spaces/docs/overview) - View the fully rendered documentation within the Confluence platform, providing a comprehensive and navigable guide for using the Markdown-Confluence project. 23 | -------------------------------------------------------------------------------- /src/features/comment-handling.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '1409412' 4 | --- 5 | # Comment Handling 6 | 7 | This plugin attempts to find the original location of a comment and reattach it. If it cannot determine the correct location, it will add a section to the bottom of the page and place the comment there. 8 | 9 | # Comment Matching Process 10 | 11 | ## No matches found 12 | If no matches for the text the comment was attached to are found, the comment is moved to the unmatched comment section. 13 | 14 | ## Exact Match 15 | The plugin first tries to find an exact match for the comment by comparing the text before and after the comment. If an exact match is found, the comment is attached at that location. 16 | 17 | ## Distance of whole before and after 18 | If an exact match is not found, the plugin calculates the "distance" between the text before and after the comment in the original location and each potential new location. This distance is calculated using the Levenshtein distance algorithm, which measures the number of changes (insertions, deletions, or substitutions) required to transform one string into another. If there are more than 40 changes before and after the comment text the node is excluded from being a viable option. The potential matches are sorted based on the calculated distances, and the match with the smallest distance is chosen. 19 | 20 | ## Distance of 2 words before and after 21 | If there are still multiple matches with similar distances, the plugin narrows down the selection by comparing only the words immediately surrounding the comment. The Levenshtein distance is calculated again, and the best match is chosen based on the smallest distance. 22 | 23 | ## No ability to match 24 | If no suitable match is found, the function returns undefined. 25 | 26 | ## Flow chart 27 | ```mermaid 28 | flowchart TD 29 | Start --> DoesCommentTextExist{Does comment text exist on page?} 30 | DoesCommentTextExist -->|Yes| DoesExactMatchExist{Does exact match before and after comment text?} 31 | DoesCommentTextExist -->|No| UnmatchedCommentSection[Unmatched Comment Section] 32 | DoesExactMatchExist -->|Yes| AttachComment[Attach Comment To This ADF Node] 33 | DoesExactMatchExist -->|No| CalculateLevenshtein 34 | 35 | subgraph WholeBeforeAfter 36 | CalculateLevenshtein[Calculate Levenshtein Distance Between Before and After text] --> SortByMinimumDistance[Sort by minimum distance] 37 | SortByMinimumDistance --> IsFirstItemMinimumDistanceUnder40{Is first item minimum distance under 40 changes?} 38 | end 39 | 40 | IsFirstItemMinimumDistanceUnder40 -->|Yes| AttachComment 41 | IsFirstItemMinimumDistanceUnder40 -->|No| GetXWordsBeforeAfterComment[Get X Words before and after comment] 42 | 43 | subgraph WordsBeforeAfter 44 | GetXWordsBeforeAfterComment --> TrimBeforeAndAfterToSameLength 45 | TrimBeforeAndAfterToSameLength --> CalculateWordsLevenshtein 46 | CalculateWordsLevenshtein --> IsDistanceLessThan50percentCharacters{IsDistanceLessThan50percentCharacters} 47 | IsDistanceLessThan50percentCharacters -->|Yes| AddToChecks 48 | IsDistanceLessThan50percentCharacters -->|Yes| CalculateWordsLevenshtein 49 | IsDistanceLessThan50percentCharacters -->|No| CalculateWordsLevenshtein 50 | AddToChecks --> SortByWordsMinimumDistance 51 | SortByWordsMinimumDistance --> IsThereAnyItems{IsThereAnyItems} 52 | end 53 | 54 | IsThereAnyItems -->|Yes| AttachComment 55 | IsThereAnyItems -->|No| UnmatchedCommentSection 56 | ``` 57 | -------------------------------------------------------------------------------- /src/features/setting-sources.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '1442001' 4 | --- 5 | # Settings Loaders 6 | 7 | This document describes the different settings loaders used to load and merge settings for the `ConfluenceSettings` configuration object. Each loader is responsible for loading settings from a specific source, and they can be combined to create a merged configuration. 8 | 9 | ## DefaultSettingsLoader 10 | 11 | **Purpose:** Load default settings from the `DEFAULT_SETTINGS` object. 12 | 13 | **Settings source:** `DEFAULT_SETTINGS` object. 14 | 15 | **Example:** 16 | 17 | ```javascript 18 | const defaultLoader = new DefaultSettingsLoader(); 19 | const defaultSettings = defaultLoader.loadPartial(); 20 | ``` 21 | 22 | ## StaticSettingsLoader 23 | 24 | **Purpose:** Load settings provided as a static object. 25 | 26 | **Settings source:** User-provided object. 27 | 28 | **Example:** 29 | 30 | ```javascript 31 | const staticSettings = { 32 | confluenceBaseUrl: "https://example.com", 33 | confluenceParentId: "12345", 34 | }; 35 | const staticLoader = new StaticSettingsLoader(staticSettings); 36 | const loadedSettings = staticLoader.loadPartial(); 37 | ``` 38 | 39 | ## EnvironmentVariableSettingsLoader 40 | 41 | **Purpose:** Load settings from environment variables. 42 | 43 | **Settings source:** Environment variables. 44 | 45 | **Example:** 46 | 47 | Set the environment variables: 48 | 49 | ```bash 50 | export CONFLUENCE_BASE_URL=https://example.com 51 | export CONFLUENCE_PARENT_ID=12345 52 | ``` 53 | 54 | 55 | Load settings from environment variables: 56 | 57 | ```js 58 | const envLoader = new EnvironmentVariableSettingsLoader(); 59 | const envSettings = envLoader.loadPartial(); 60 | ``` 61 | 62 | ## ConfigFileSettingsLoader 63 | 64 | **Purpose:** Load settings from a JSON configuration file. 65 | 66 | **Settings source:** User-specified JSON configuration file. 67 | 68 | **Example:** 69 | 70 | Create a JSON configuration file (`.mermaid-confluence.json`): 71 | 72 | ```json 73 | { 74 | "confluenceBaseUrl": "https://example.com", 75 | "confluenceParentId": "12345" 76 | } 77 | ``` 78 | 79 | 80 | Load settings from the configuration file: 81 | 82 | ```js 83 | const configFileLoader = new ConfigFileSettingsLoader(); 84 | const configFileSettings = configFileLoader.loadPartial(); 85 | ``` 86 | 87 | ## CommandLineArgumentSettingsLoader 88 | 89 | **Purpose:** Load settings from command line arguments. 90 | 91 | **Settings source:** Command line arguments. 92 | 93 | **Example:** 94 | 95 | Pass settings as command line arguments: 96 | 97 | ```bash 98 | node index.js --baseUrl https://example.com --parentId 12345 99 | ``` 100 | 101 | 102 | Load settings from command line arguments: 103 | 104 | ```js 105 | const cmdLoader = new CommandLineArgumentSettingsLoader(); 106 | const cmdSettings = cmdLoader.loadPartial(); 107 | ``` 108 | 109 | ## AutoSettingsLoader 110 | 111 | **Purpose:** Automatically load and merge settings from multiple loaders. 112 | 113 | **Settings source:** Multiple settings loaders. 114 | 115 | **Example:** 116 | 117 | Create an `AutoSettingsLoader` with custom loaders: 118 | 119 | ````js 120 | const loaders = [ 121 | new ConfigFileSettingsLoader(), 122 | new EnvironmentVariableSettingsLoader(), 123 | new CommandLineArgumentSettingsLoader(), 124 | new DefaultSettingsLoader() 125 | ]; 126 | 127 | const autoLoader = new AutoSettingsLoader(loaders); 128 | const autoSettings = autoLoader.load(); 129 | ``` 130 | -------------------------------------------------------------------------------- /src/usage/github-actions.md: -------------------------------------------------------------------------------- 1 | --- 2 | connie-publish: true 3 | connie-page-id: '1278241' 4 | --- 5 | # markdown-confluence/publish GitHub Action 6 | 7 | This GitHub Action wraps up an NPM CLI that allows you to publish your Markdown files to Confluence quickly and easily. By using this action in your workflows, you can automate the process of publishing documentation to Confluence, making it faster, more streamlined, and more efficient. 8 | 9 | ## Usage 10 | 11 | To use this GitHub Action in your repository, you'll need to create a workflow file (e.g., `.github/workflows/publish.yml`) and configure the action as described below. 12 | 13 | ### Basic example 14 | 15 | ```yaml 16 | name: Publish to Confluence 17 | on: push 18 | 19 | jobs: 20 | publish: 21 | runs-on: ubuntu-latest 22 | steps: 23 | - name: Checkout code 24 | uses: actions/checkout@v2 25 | 26 | - name: Publish Markdown to Confluence 27 | uses: markdown-confluence/publish@v1 28 | with: 29 | confluenceBaseUrl: https://your-confluence-instance-url 30 | confluenceParentId: 123456 31 | atlassianUserName: ${{ secrets.ATLASSIAN_USERNAME }} 32 | atlassianApiToken: ${{ secrets.ATLASSIAN_API_TOKEN }} 33 | ``` 34 | 35 | ### Example using a config file 36 | 37 | Create a `.markdown-confluence.json` file in your repository with the following content: 38 | 39 | ```json 40 | { 41 | "confluenceBaseUrl": "https://your-confluence-instance-url", 42 | "confluenceParentId": "123456", 43 | "atlassianUserName": "your-email@example.com", 44 | "folderToPublish": "docs", 45 | "contentRoot": "/docs" 46 | } 47 | ``` 48 | 49 | Then configure the GitHub Action in your workflow file: 50 | 51 | ```yaml 52 | name: Publish to Confluence 53 | on: push 54 | 55 | jobs: 56 | publish: 57 | runs-on: ubuntu-latest 58 | steps: 59 | - name: Checkout code 60 | uses: actions/checkout@v2 61 | 62 | - name: Publish Markdown to Confluence 63 | uses: markdown-confluence/publish@v1 64 | with: 65 | configFile: .markdown-confluence.json 66 | atlassianApiToken: ${{ secrets.ATLASSIAN_API_TOKEN }} 67 | ``` 68 | 69 | 70 | ## Input Options 71 | 72 | This section provides an overview of all the input options available for the `markdown-confluence/publish` GitHub Action and examples of how to use them in your workflows. 73 | 74 | ### confluenceBaseUrl 75 | 76 | The base URL of your Confluence instance, used for API calls and publishing content. This value should include the protocol (e.g., `https://`) but not a trailing slash. 77 | 78 | Example: 79 | 80 | ```yaml 81 | with: 82 | confluenceBaseUrl: https://your-confluence-instance-url 83 | ``` 84 | 85 | ### confluenceParentId 86 | 87 | The ID of the parent page in Confluence where the Markdown files will be published as child pages. 88 | 89 | Example: 90 | 91 | ```yaml 92 | with: 93 | confluenceParentId: 123456 94 | ``` 95 | 96 | ### atlassianUserName 97 | 98 | Your Atlassian account's username, required for authentication when interacting with Confluence. 99 | 100 | Example: 101 | 102 | ```yaml 103 | with: 104 | atlassianUserName: ${{ secrets.ATLASSIAN_USERNAME }} 105 | ``` 106 | 107 | ### atlassianApiToken 108 | 109 | An API token generated for your Atlassian account, used for authentication when making API calls to Confluence. This value should be stored as a repository secret. 110 | 111 | Example: 112 | 113 | ```yaml 114 | with: 115 | atlassianApiToken: ${{ secrets.ATLASSIAN_API_TOKEN }} 116 | ``` 117 | 118 | ### folderToPublish 119 | 120 | The folder you want to apply a default of "connie-publish: true" to. All Markdown files within this folder will be considered for publishing. 121 | 122 | Example: 123 | 124 | ```yaml 125 | with: 126 | folderToPublish: docs 127 | ``` 128 | 129 | ### contentRoot 130 | 131 | The root path for published content on Confluence. This is used to tell the action where to look for Markdown files and content. 132 | 133 | Example: 134 | 135 | ```yaml 136 | with: 137 | contentRoot: /docs 138 | ``` 139 | 140 | ### configFile 141 | 142 | A configuration file containing additional settings and customizations for the publishing process. You can use this option to keep your workflow file clean and maintain all configuration settings in a separate file. 143 | 144 | Example: 145 | 146 | ```yaml 147 | with: 148 | configFile: .markdown-confluence.json 149 | ``` 150 | 151 | ## Advanced Example 152 | 153 | Here's an example of using all input options in a single workflow: 154 | 155 | ```yaml 156 | name: Publish to Confluence 157 | on: push 158 | 159 | jobs: 160 | publish: 161 | runs-on: ubuntu-latest 162 | steps: 163 | - name: Checkout code 164 | uses: actions/checkout@v2 165 | 166 | - name: Publish Markdown to Confluence 167 | uses: markdown-confluence/publish@v1 168 | with: 169 | confluenceBaseUrl: https://your-confluence-instance-url 170 | confluenceParentId: 123456 171 | atlassianUserName: ${{ secrets.ATLASSIAN_USERNAME }} 172 | atlassianApiToken: ${{ secrets.ATLASSIAN_API_TOKEN }} 173 | folderToPublish: docs 174 | contentRoot: /docs 175 | configFile: .markdown-confluence.json 176 | ``` 177 | 178 | Remember to create and configure the `.markdown-confluence.json` file in your repository as needed. 179 | 180 | ### Storing API token as a repository secret 181 | 182 | To store your Atlassian API token as a repository secret, follow these steps: 183 | 184 | 1. Go to your GitHub repository and click on the "Settings" tab. 185 | 2. In the left sidebar, click on "Secrets". 186 | 3. Click on the "New repository secret" button. 187 | 4. Enter `ATLASSIAN_API_TOKEN` as the name and paste your API token as the value. 188 | 5. Click on the "Add secret" button. 189 | 190 | Now you can reference the `ATLASSIAN_API_TOKEN` secret in your GitHub Actions workflows using the syntax `${{ secrets.ATLASSIAN_API_TOKEN }}`. 191 | 192 | 193 | ## Support 194 | 195 | If you need help with using this action or encounter any issues, please open an issue in the [GitHub repository](https://github.com/markdown-confluence/markdown-confluence/issues). 196 | 197 | ## License 198 | 199 | This GitHub Action is released under the Apache 2.0 License. 200 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | 2 | Apache License 3 | Version 2.0, January 2004 4 | http://www.apache.org/licenses/ 5 | 6 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 7 | 8 | 1. Definitions. 9 | 10 | "License" shall mean the terms and conditions for use, reproduction, 11 | and distribution as defined by Sections 1 through 9 of this document. 12 | 13 | "Licensor" shall mean the copyright owner or entity authorized by 14 | the copyright owner that is granting the License. 15 | 16 | "Legal Entity" shall mean the union of the acting entity and all 17 | other entities that control, are controlled by, or are under common 18 | control with that entity. For the purposes of this definition, 19 | "control" means (i) the power, direct or indirect, to cause the 20 | direction or management of such entity, whether by contract or 21 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 22 | outstanding shares, or (iii) beneficial ownership of such entity. 23 | 24 | "You" (or "Your") shall mean an individual or Legal Entity 25 | exercising permissions granted by this License. 26 | 27 | "Source" form shall mean the preferred form for making modifications, 28 | including but not limited to software source code, documentation 29 | source, and configuration files. 30 | 31 | "Object" form shall mean any form resulting from mechanical 32 | transformation or translation of a Source form, including but 33 | not limited to compiled object code, generated documentation, 34 | and conversions to other media types. 35 | 36 | "Work" shall mean the work of authorship, whether in Source or 37 | Object form, made available under the License, as indicated by a 38 | copyright notice that is included in or attached to the work 39 | (an example is provided in the Appendix below). 40 | 41 | "Derivative Works" shall mean any work, whether in Source or Object 42 | form, that is based on (or derived from) the Work and for which the 43 | editorial revisions, annotations, elaborations, or other modifications 44 | represent, as a whole, an original work of authorship. For the purposes 45 | of this License, Derivative Works shall not include works that remain 46 | separable from, or merely link (or bind by name) to the interfaces of, 47 | the Work and Derivative Works thereof. 48 | 49 | "Contribution" shall mean any work of authorship, including 50 | the original version of the Work and any modifications or additions 51 | to that Work or Derivative Works thereof, that is intentionally 52 | submitted to Licensor for inclusion in the Work by the copyright owner 53 | or by an individual or Legal Entity authorized to submit on behalf of 54 | the copyright owner. For the purposes of this definition, "submitted" 55 | means any form of electronic, verbal, or written communication sent 56 | to the Licensor or its representatives, including but not limited to 57 | communication on electronic mailing lists, source code control systems, 58 | and issue tracking systems that are managed by, or on behalf of, the 59 | Licensor for the purpose of discussing and improving the Work, but 60 | excluding communication that is conspicuously marked or otherwise 61 | designated in writing by the copyright owner as "Not a Contribution." 62 | 63 | "Contributor" shall mean Licensor and any individual or Legal Entity 64 | on behalf of whom a Contribution has been received by Licensor and 65 | subsequently incorporated within the Work. 66 | 67 | 2. Grant of Copyright License. Subject to the terms and conditions of 68 | this License, each Contributor hereby grants to You a perpetual, 69 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 70 | copyright license to reproduce, prepare Derivative Works of, 71 | publicly display, publicly perform, sublicense, and distribute the 72 | Work and such Derivative Works in Source or Object form. 73 | 74 | 3. Grant of Patent License. Subject to the terms and conditions of 75 | this License, each Contributor hereby grants to You a perpetual, 76 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 77 | (except as stated in this section) patent license to make, have made, 78 | use, offer to sell, sell, import, and otherwise transfer the Work, 79 | where such license applies only to those patent claims licensable 80 | by such Contributor that are necessarily infringed by their 81 | Contribution(s) alone or by combination of their Contribution(s) 82 | with the Work to which such Contribution(s) was submitted. If You 83 | institute patent litigation against any entity (including a 84 | cross-claim or counterclaim in a lawsuit) alleging that the Work 85 | or a Contribution incorporated within the Work constitutes direct 86 | or contributory patent infringement, then any patent licenses 87 | granted to You under this License for that Work shall terminate 88 | as of the date such litigation is filed. 89 | 90 | 4. Redistribution. You may reproduce and distribute copies of the 91 | Work or Derivative Works thereof in any medium, with or without 92 | modifications, and in Source or Object form, provided that You 93 | meet the following conditions: 94 | 95 | (a) You must give any other recipients of the Work or 96 | Derivative Works a copy of this License; and 97 | 98 | (b) You must cause any modified files to carry prominent notices 99 | stating that You changed the files; and 100 | 101 | (c) You must retain, in the Source form of any Derivative Works 102 | that You distribute, all copyright, patent, trademark, and 103 | attribution notices from the Source form of the Work, 104 | excluding those notices that do not pertain to any part of 105 | the Derivative Works; and 106 | 107 | (d) If the Work includes a "NOTICE" text file as part of its 108 | distribution, then any Derivative Works that You distribute must 109 | include a readable copy of the attribution notices contained 110 | within such NOTICE file, excluding those notices that do not 111 | pertain to any part of the Derivative Works, in at least one 112 | of the following places: within a NOTICE text file distributed 113 | as part of the Derivative Works; within the Source form or 114 | documentation, if provided along with the Derivative Works; or, 115 | within a display generated by the Derivative Works, if and 116 | wherever such third-party notices normally appear. The contents 117 | of the NOTICE file are for informational purposes only and 118 | do not modify the License. You may add Your own attribution 119 | notices within Derivative Works that You distribute, alongside 120 | or as an addendum to the NOTICE text from the Work, provided 121 | that such additional attribution notices cannot be construed 122 | as modifying the License. 123 | 124 | You may add Your own copyright statement to Your modifications and 125 | may provide additional or different license terms and conditions 126 | for use, reproduction, or distribution of Your modifications, or 127 | for any such Derivative Works as a whole, provided Your use, 128 | reproduction, and distribution of the Work otherwise complies with 129 | the conditions stated in this License. 130 | 131 | 5. Submission of Contributions. Unless You explicitly state otherwise, 132 | any Contribution intentionally submitted for inclusion in the Work 133 | by You to the Licensor shall be under the terms and conditions of 134 | this License, without any additional terms or conditions. 135 | Notwithstanding the above, nothing herein shall supersede or modify 136 | the terms of any separate license agreement you may have executed 137 | with Licensor regarding such Contributions. 138 | 139 | 6. Trademarks. This License does not grant permission to use the trade 140 | names, trademarks, service marks, or product names of the Licensor, 141 | except as required for reasonable and customary use in describing the 142 | origin of the Work and reproducing the content of the NOTICE file. 143 | 144 | 7. Disclaimer of Warranty. Unless required by applicable law or 145 | agreed to in writing, Licensor provides the Work (and each 146 | Contributor provides its Contributions) on an "AS IS" BASIS, 147 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 148 | implied, including, without limitation, any warranties or conditions 149 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 150 | PARTICULAR PURPOSE. You are solely responsible for determining the 151 | appropriateness of using or redistributing the Work and assume any 152 | risks associated with Your exercise of permissions under this License. 153 | 154 | 8. Limitation of Liability. In no event and under no legal theory, 155 | whether in tort (including negligence), contract, or otherwise, 156 | unless required by applicable law (such as deliberate and grossly 157 | negligent acts) or agreed to in writing, shall any Contributor be 158 | liable to You for damages, including any direct, indirect, special, 159 | incidental, or consequential damages of any character arising as a 160 | result of this License or out of the use or inability to use the 161 | Work (including but not limited to damages for loss of goodwill, 162 | work stoppage, computer failure or malfunction, or any and all 163 | other commercial damages or losses), even if such Contributor 164 | has been advised of the possibility of such damages. 165 | 166 | 9. Accepting Warranty or Additional Liability. While redistributing 167 | the Work or Derivative Works thereof, You may choose to offer, 168 | and charge a fee for, acceptance of support, warranty, indemnity, 169 | or other liability obligations and/or rights consistent with this 170 | License. However, in accepting such obligations, You may act only 171 | on Your own behalf and on Your sole responsibility, not on behalf 172 | of any other Contributor, and only if You agree to indemnify, 173 | defend, and hold each Contributor harmless for any liability 174 | incurred by, or claims asserted against, such Contributor by reason 175 | of your accepting any such warranty or additional liability. 176 | 177 | END OF TERMS AND CONDITIONS 178 | 179 | APPENDIX: How to apply the Apache License to your work. 180 | 181 | To apply the Apache License to your work, attach the following 182 | boilerplate notice, with the fields enclosed by brackets "[]" 183 | replaced with your own identifying information. (Don't include 184 | the brackets!) The text should be enclosed in the appropriate 185 | comment syntax for the file format. We also recommend that a 186 | file or class name and description of purpose be included on the 187 | same "printed page" as the copyright notice for easier 188 | identification within third-party archives. 189 | 190 | Copyright [yyyy] [name of copyright owner] 191 | 192 | Licensed under the Apache License, Version 2.0 (the "License"); 193 | you may not use this file except in compliance with the License. 194 | You may obtain a copy of the License at 195 | 196 | http://www.apache.org/licenses/LICENSE-2.0 197 | 198 | Unless required by applicable law or agreed to in writing, software 199 | distributed under the License is distributed on an "AS IS" BASIS, 200 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 201 | See the License for the specific language governing permissions and 202 | limitations under the License. 203 | --------------------------------------------------------------------------------