An SBT plugin that can publish Markdown to an Atlassian Confluence installation - lenalebt/sbt-confluence.

conflr is an R package to post R Markdown documents to Confluence, a content collaboration tool by Atlassian.

Installation

Install conflr from CRAN with:

Nov 24, 2019 Install Markdown Exporter for Confluence Once it is successfully installed, you can use it from action icon on the right: Export page to Markdown Markdown file will be generated and can be. Help and support. Markdown for Confluence. While there were challenges we had to overcome to mirror our content to Confluence, it was well worth it. After all, research is only effective if it can be shared with others. We think the goal of deploying Markdown to Confluence is a common problem, and we think that markdown-to-confluence helps solve it. Take it for a spin and, as always. One of my biggest mistakes with this blog was not finding a WordPress plugin that would allow me to write my posts with markdown; to this day I still need to write posts in “Visual” mode and then.

Alternatively, if you need the development version, install it with:

Preparation

conflr uses these environmental variables to access your Confluence.

• CONFLUENCE_URL: The base URL of your Confluence. e.g. https://confluence.example.com (On Atlassian Cloud, https://<your-domain>.atlassian.net/wiki).
• CONFLUENCE_USERNAME: Your username (On Atlassian Cloud, your email address).
• CONFLUENCE_PASSWORD: Your password (On Atlassian Cloud, your API token. For more details about API token, please read the official document).

There are several ways to set these environmental variables. The quickest way is to enter in the popups that are displayed when you run the addin (see Usages section below). The inputs are cached in the environmental variables listed above by default.

Another way is to set the variables in the .Renviron file (you can open the file with usethis::edit_r_environ()). For example, you can set the base URL in the file as the following.

Usages

conflr provides the following ways to post R Markdown documents to Confluence.

1. Use an RStudio Addin
2. Run confl_create_post_from_Rmd() on console
3. Specify conflr::confluence_document on the YAML front-matter

RStudio Addin

1. Move focus to the .Rmd file and click “Post to Confluence” Addin

(Caution for those who are not familiar with R Markdown: R Markdown’s powerfulness allows you to execute arbitrary code; be sure about what the code does before clicking “Post to Confluence”!)

Then, you will be asked your username and password.

2. Check the preview and click “Publish”

• type: The type of the page (page means a normal wiki page, whereas blogpost mean a blog post, not a page).
• Space Key: The key of the space you want to post.
• Parent page ID: (optional): The ID of the parent page to the page.
• Use original image sizes: If checked, do not resize the images.
• Fold code blocks: If checked, code blocks are folded by default.
• TOC: If checked, add a Table of Contents.
• TOC depth: The lowest heading level to include in the Table of Contents.

confl_create_post_from_Rmd()

If you don’t use RStudio, you can use confl_create_post_from_Rmd(). The basic usage is

Batch use

If you want to use this function without interaction, specify interactive = FALSE. This skips any confirmations or previews.

Note that, if you want to run this periodically, you also need to set update = TRUE to allow conflr to overwrite the existing page.

conflr::conflence_document

conflr’s functionality is also available as a custom R Markdown format; You can specify conflr::confluence_document to output in the front matter of your R Markdown document.

For example, if you set the following front matter, pressing Knit button on RStudio (or running rmarkdown::render()) will publish the R Markdown document to Confluence.

For the detail about available options, please refer to ?confluence_document.

Options

conflr recognizes these options:

• conflr_supported_syntax_highlighting: A character vector of languages that your Confluence supports the syntax highlighting in addition to the default languages (by default, sql, cpp, python, html, css, bash, and yaml are supported).
• conflr_addin_clear_password_after_success: If TRUE, unset CONFLUENCE_PASSWORD after the page is successfully uploaded via addin.

Know limitations

LaTeX support

conflr supports Math expressions to some extent. But, it requires LaTeX Math addon installed. Otherwise, you will see “unknown macro” errors on the page.

htmlwidgets (e.g. leaflet, plotly)

conflr doesn’t support htmlwidgets-based packages like leaflet and plotly. Instead, you can embed the screenshot by setting screenshot.force = TRUE in the chunk option (c.f. https://bookdown.org/yihui/bookdown/html-widgets.html).

Advanced Usages

conflr is also a (non-complete) binding to Confluence’s REST API. These low-level functions might be useful when you need to access to your Confluence programmatically.

How to contribute

See CONTRIBUTING.md

License

See LICENSE.md for more detail.

Today, we’re going to settle the question once and for all – which is superior? Documentation in a plain-text editor using Markdown, or creating content in a rich-text editor the WYSIWYG (what you see is what you get) way? How will it be decided, you ask? A good, clean head-to-head fight!

Mr. Mark ‘Markdown’ Down

In the left corner: Mr. Mark “Markdown” Down, lightweight champion of the world for writing web content into plain text files. You can recognize Markdown easily by his file extension .md, but you don’t need an MD to understand it – the syntax is so simple that any developer in the world can adapt to it with ease.

Mark’s strengths: code handling, offline availability, minimalism and something he likes to call “bringing it down.”

Supported by: Jekyll, your favorite text editor (e.g. Emacs), and file repositories such as Github.

Mr. Richard ‘Rich Text’ Formatting

In the right corner: Richard “Rich Text” Formatting – used by millions of casual writers who want to see their results instantly. Rich doesn’t see many advantages in separating editing from viewing: “Juggling markup syntax? What is this, the ‘90s?”

Rich’s strengths: advanced content formatting skills, editor shortcuts (and he’s not afraid to use them), and immediate availability of the resulting document.

Supported by: the Atlassian Confluence collaboration platform and wiki, and other cloud-based content creation tools such as Google Docs. Microsoft Word isn’t a big fan, though.

Let’s Get Ready To Rumble!

This match will go the full 12 rounds. Mark and Rich will flex their muscles to see who can create and publish content faster and easier.

Round #1: Getting Started

Markdown: “Oh, this one’s easy – open a new document in the text editor and start typing.” Or use an online markdown editor such as dillinger.io that supports synchronization with Dropbox, Google Drive and Github.

Rich Text: “The same goes for me. Just create a new document, give it a title and away you go.” Before the web arrived, using a desktop text processor to format rich text was the norm. Today, rich text authoring is done collaboratively in a web browser, using a content collaboration platform such as Atlassian Confluence.

Round #2: Defining Headings and Paragraphs

Markdown: “Enter 1 to 6 hash characters before your headers, e.g. # This is a H1 for a first-class heading, or ## This is a H2 for a subheading.” Creating a paragraph is even easier. Mark recommends: “Write consecutive lines of text followed by a blank line to create a paragraph.”

Rich Text: “I don’t like blank lines, useless spaces or hashes. Instead, write a heading or paragraph, and assign the corresponding paragraph format.” Using the rich text approach, writers need only to select the desired heading level or paragraph format from the toolbar once.

Round #3: Using Bulleted and Numbered Lists

Markdown: “Choose your favorite list item (*/+/-) to create bullet points, or just start numbering your ordered list items (1., 2., etc.).”

If you don’t want the problem in the above tweet to happen to you, you’ll need to enter a tab (or four spaces) before you begin to write paragraphs within a list.

Confluence Use Markdown Formula

Rich Text: “Hmph. That just looks like a workaround, not a real solution. To add line breaks within a list item, simply press Shift+Return in the Confluence editor instead of pressing the Return key.”

Round #4: Embedding Code and Block Quotes

Markdown: “Just indent your lines of code with a tab or at least four spaces so they’re recognized as code. A no-brainer, right?” Absolutely – code is automatically indented in any development environment.

Rich Text: “I can do code examples and script listings too! Sure, you’ll need to wrap Confluence’s Code Block macro around them – but once that’s done, you can define proper syntax highlighting for your programming/scripting language, line numbering, and more.”

Round #5: Inserting Tables

Markdown: “Okay, so I’m not perfect. Tables are only supported by inline HTML, which you can write whenever a markup element isn’t covered by Markdown’s syntax.”

Rich Text: “In the Confluence rich content editor, adding tables and managing tabular content is a breeze. Just click the Table button in Confluence’s editor toolbar, and voila.”

Round #6: Images and Other Media Assets

Markdown: “OK, I admit it – embedding images into a plain text document format isn’t easy.” There are two different ways to do it:

• Inline (within a paragraph): ![alt text](/path/to/img.jpg 'title'), for example !Logo (/folder/logo.jpg 'My Logo')
• Reference-style: [id]: url/to/image 'Optional title attribute', for example [logo]: /folder/logo.jpg 'My Logo'

Rich Text: “Great media support is one of the reasons why they call me ‘Rich’. Give me almost any file type, and I’ll display it however you want. Scaled proportionally and aligned on the right? No problem!” In Confluence, just drag and drop an image into the editor to upload it automatically. You can also use a Multimedia macro to embed videos or other multimedia formats.

Round #7: Defining Links

Markdown: “This is pretty similar to embedding images. There are two ways to build links:

• Either place the URL after the link text, e.g. [link text](http://example.com/ “Title”),
• or include it as a reference, with the ID placed behind the link text.”

Rich Text: “Just select the link text and click the link icon in the toolbar to select a target. That’s it.”

Round #8: Using the Keyboard

Markdown: “You don’t need your mouse to work with Markdown. You can do everything using your keyboard. However, this means each syntax element must be entered manually, unless you use a markdown editor with syntax completion.”

Rich Text: “Editor autoformatting is a little-known Confluence feature that allows you to convert text-only syntax (called wiki markup) into formatted content as you type. For example, if you enter h1. Biggest heading, it will be converted into a first level heading. The same is true for other headings, lists, text effects (bold, italic etc.) and much more – and you can do it without even touching your mouse.”

In addition, there are keyboard shortcuts for each formatting option, e.g. Ctrl+B to bold a selected word or phrase in Confluence.

Round #9: Having Full Markup Control

Markdown: “Since all content is in a plain-text format, writers have total markup control. If there’s an error in the markup, you can fix it easily – assuming you know the correct Markdown syntax.”

Rich Text: “If you are working solely in a WYSIWYG (what you see is what you get) editor, you can’t fix formatting problems. It’s much easier to access the markup directly – and with the free Confluence Source Editor add-on, this is a real option for wiki users, too.”

Round #10: Displaying Formatted Content

Markdown: “Formatting? I don’t need to be formatted, my content is plain text! If you want to display content in style, just hit the preview button in your Markdown editor, or run a quick text-to-HTML conversion script.”

Rich Text: “Bah! Plain-text purist! Why don’t you come and join us in the 21st century? Whatever formatting you’ve selected, it will look the same afterwards, or at least very similar. There’s nothing else for authors to do.”

Round #11: Collaborating, Saving and Restoring

Markdown: “You’ll need to save your text file and other resources, such as images or styles, in a local directory, and/or a version control system like Git. Version control systems (VCS) are great for managing, comparing, merging and updating text-based files such as source code. They also allow developers to work with those files in multiple branches or versions at the same time. Since most software engineers already have access to a VCS, such as the Github Pages hosted service, this may not be a hurdle for them.”

Rich Text: “To save a wiki page, just hit the Save button. Every time you edit content, a new page revision will be created automatically. You can restore older revisions of a page easily, or even manage multiple versions of your pages with the Scroll Versions add-on for Confluence.”

Round #12: Deploying Content as Website

Markdown: “Many static site generators, such as Jekyll, allow you to build websites with your Markdown content. Jekyll doesn’t require any database-driven CMS, but you’ll need to be comfortable working with config files and command lines; you’ll also need an understanding of source control platforms like Github. This approach might be particularly attractive for software engineers, but less tech-savvy authors may not be quite as keen.”

Rich Text: “Rich-text wiki platforms like Confluence are geared towards users who want to write content and publish it instantly. When creating a new Confluence page, you don’t need to run a build script afterwards to display the formatted content in the web browser – it’s already there.”

And The Winner Is …

Confluence Use Markdown Form

You, the writer! When creating assets such as notes, readme files or other content including large sets of documentation, you can choose the text processor best suited to your workflow.

Confluence Use Markdown In Python

Casual users will find it easier to write, collaborate and track changes with Confluence. If you’re already familiar with version control, e.g. with Git, Markdown is also an option – particularly for software engineers. But it’s difficult to compare an out-of-the-box content management solution like Confluence with a plain-text format and toolkits for building static web resources.

Perhaps you want the best of both worlds – Markdown’s minimalism, but with a rich-text editor’s advanced formatting functionality? If so, you can use the Atlassian Confluence collaboration platform and still write using Markdown. With Confluence, you can easily insert existing Markdown content, or embed it using the Markdown macro. And by using this approach, Markdown and Confluence both come out on top – meaning everyone’s a winner.

Confluence Markdown Code

Do you use Markdown to write documentation? Do you have a different perspective on collaborative authoring? Please let us know in the comments, or drop us an email at hello@k15t.com.