Hunterbasic183

Markdown Extensions for Confluence + 2. Created by Mohammed Davoodi. Last updated Apr 06, 2021 by Gabriela Costa. The Markdown Extensions for Confluence documentation. Feb 02, 2021 Bitbucket Data Center and Server uses Markdown for formatting text, as specified in CommonMark (with a few extensions). You can use Markdown in the following places: any pull request's descriptions or comments, or; in README files (if they have the.md file extension). Use Control-Shift-P or Command-Shift-P to preview your markdown. Markdown syntax. MkDocs plugin for uploading markdown documentation to Confluence via Confluence REST API Skip to main content Switch to mobile version Warning Some features may not work without JavaScript. Mark — a tool for syncing your Markdown documentation with Atlassian Confluence Mark reads your Markdown file, creates a Confluence page if it doesn’t, uploads attachments if any, translates Markdown into HTML, and updates the contents of the page via REST API. We are in 2015, now. Markdown support is ubiquitous on the web. It's everywhere. It's even the default markup language used by Stash. I also know that there are Confluence plugins to add Markdown support, but currently in the market place, only one of those plugins is compatible with the Cloud hosted Confluence.

1. Confluence Markdown Plugin
2. Confluence Markdown Code

TL;DRMark — a tool for syncing your Markdown with Confluence

Oh man, I was so frustrated when I was trying to edit docs in Confluence, and itbroke all my text, trying to adjust any tags led to breaking the text even more.I felt the same when Slack introduced their Wysiwyg editor that solved problems that never existed,but at least they added an option to disable it.

Wysiwyg is the Devil’s Playground, but there is a solution.

Store with Git, write in Markdown, automatically sync with Confluence. Interesting? Let me tell youabout seven benefits that you could have if you could use Git for storing your docs instead of editingthem directly in Confluence:

1. Git
   Confluence has a history of changes, but it’s very limited: you can’t do git blame,you can’t do git log -S to search who added a specific text.

2. Pull Requests
   Now, someone with a fresh set of eyes can identify problems and provide suggestions for docs.You write code — someone reviews it, you write a book — someone reviews it.Now, you write docs — someone reviews it.

3. Instruments
   We have some great tools like VSCode, Neovim, Sublime, or Idea with all required set ofextensions that make our coding even more efficient and less frustrating.

   Then why not using it for writing docs? It’s more efficient than Wysiwyg for sure.

4. No context switching
   No need to jump around to read docs a bit. Just open it up in your editorbecause you store the docs near to the code.

5. Hosting Agnostic
   You can just push your docs on GitHub if you want to open source it.

6. Decentralization
   Everyone has their own complete copy of docs, develops it, and syncs up later.

7. Continuous Integration
   If you have a proper tool that I’m going to introduce, you can automatically update your docs inConfluence after a successful git push.

Mark reads your Markdown file, creates a Confluence page if it doesn’t, uploadsattachments if any, translates Markdown into HTML, and updates the contents of the page via REST API.

It’s like you don’t even need to create sections/pages in your Confluence anymore, just mention them inyour .md files.

Mark uses an extended file format, which, still being valid markdown, contains several HTML-ishmetadata headers, which can be used to locate page inside Confluence instance and update itaccordingly.

Example

mark.md

Mark will upload file images/screenshot.png as an attachment, create a page in Confluence by thefollowing path:
Dev / Automation / Documentation → Sync Markdown to Confluence, then renderMarkdown as HTML and put the contents via REST API on the user’s behalf.

Continuous Integration

It’s quite trivial to integrate Mark into a CI/CD system, here is an example with Snake CIin case of self-hosted Bitbucket Server / Data Center.

In this example, I’m using the kovetskiy/mark image for creating a job container where therepository with documentation will be cloned to. The following command finds all *.md files and runs mark against them one by one:

The following directive tells the CI to run this particular job only if the changes are pushed into themain branch. It means you can safely push your changes into feature branches without being afraidthat they automatically shown in Confluence, then go through the reviewal process and automaticallydeploy them when PR got merged.

Confluence Markdown Plugin

Links

Mark is open source and available on GitHub: github.com/kovetskiy/mark

Follow me on Twitter: @reconquestio

I recently did some investigations at work on how to keep documentation up to date. I guess we’ve all been in the situation that the documentation we have is drifting from how the actual systems/applications look like. I believe that it’s easier to keep the documentation close the the actual code, e.g by README’s in markdown, than by have them as separate confluence pages that no one remembers to keep up to date. If you are using Confluence you can create/update documentation by using the REST api, however Confluence does not accept markdown so you have two options;

• install markdown plugins (that’s available in the api)
• or convert markdown to confluence markup language

I went with the latter options since that felt a bit easier. I found this ruby gem. Unfortunately it’s installed as a gem with dependencies you might not have available and it only runs as a cli-tool which might not be ideal if you want to include this as a step in your CI/CD pipeline. I quickly hacked together a way to run this gem as a REST server instead inside a docker container, which eliminates bothersome dependencies and make’s it easier to include in your pipeline.

Quick Tutorial

• Run the container by pulling the image from docker hub:

• Test the conversion (example script in ruby)

Confluence Markdown Code

Asciicast Demo

Complete Example

If you want to check out the complete source code you can take a look at this repo and follow the README.