Formatting in Quip just got twice as fast. If you are not already a member of the Docs Team, let John Boteler or Italo Rossi know before the sprint day so that we can add you to the Confluence. Exploring Markdown in Collaborative Authoring to Publishing Workflows. The HTML export from Confluence can be problematic as well.

HTML isn’t exactly easy for ordinary people to comprehend and use correctly, and allowing it’s use in web forms then entails measures to be taken to prevent malicious code from being inserted.

The infamous John Gruber came up with Markdown, with the help of Aaron Swartz, and whether they intended it to be or not, they came up with the solution to our problem. Using Markdown formatting, you can make text italics by putting an *asterisk* on either side, or bold by using **two.** Blockquotes are as simple as putting a “>” before a paragraph of text. Links are a little more complicated, but they’re easier to do than with straight HTML for the average user.

Markdown is a nifty solution for allowing users of a website to format their input, and it’s gained a good measure of popularity. Reddit is one site that makes use of it for it’s comment forms.

Markdown-enabling a website isn’t too hard for someone with a bit of coding experience. You first need to find an implementation for the language of your choice, unless you want to write your own. Daring Fireball has a Perl implementation right on the Markdown homepage, but what if you’re like me and prefer PHP? Download a copy of PHP Markdown. The script functions like an ordinary PHP library, or as a WordPress plugin, enabling you to use Markdown in comments and the Post Editor.

Using Markdown in your own PHP script is as simple as including markdown.php and passing any Markdown-formatted text through a function to convert it to straight HTML.

include_once 'markdown.php';
$my_html = Markdown($my_text);


I would also recommend additionally using the strip_tags PHP function to first remove any HTML tags someone may have put in.

Or you could use the WMD Editor, which applies a JavaScript formatting bar to an input form, allowing the contents to be formatted with Markdown. It then spits out full HTML for the form when it is submitted.

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:

Confluence Markdown Code

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.

Links

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

Embed Markdown In Confluence

Follow me on Twitter: @reconquestio

Confluence Import Markdown

Comments