image DB Schema Changes

Markdown converted for Atlassian’s Confluence

If you ever have a need to convert a bunch of markdown or html files to confluence it is really easy. Their Rest-API is pretty clean and if you use Ruby there is a small Confluence API gem to make it even easier.

Why Move To Confluence?

Why would we move our documentation from Markdown in a git repo, to Confluence? Well our team is growing and we interact with more and more non developers, who could benefit and contribute to our documentation. While some of our documentation was very technical much of it wasn’t. It would be helpful to our Support, IT, Project Management, and Stakeholders. Markdown and git aren’t the best way to get other folks comfort able reading or contributing to our documentation.

  • Increased collaboration
  • Simplified access control to read
  • Ability to mix ticketing, widgets, and wiki docs

That was enough for us to decide on moving our documentation over.

Bulk Conversion & Upload

I didn’t want to take the time to move over 80+ documents by hand. So I wrote a script to help. I created a page in our confluence space for imported docs. I set that as a parent page and then just converted all of the Markdown to HTML and uploaded it in a single step. Linking to the original document in case anything was lost in translation. Now we can pull content and link to the old content, but start building out newer documentation on our confluence space.

Show Me the Code

You can view the gist or see the code below.

#!/usr/bin/env ruby

require 'rubygems'
require 'confluence/api/client'
require 'kramdown'


username = '[email protected]'
password = 'your_pass'
url      = 'https://your_co.atlassian.net/wiki'
space    = 'DP'
# if you don't want your files at the root give a parent page to nest them under
parent_page_id = 5564541
path     = '/Users/danmayer/projects/DevDocuments'
original_root_path = 'https://github.com/OffgridElectric/DevDocuments/blob/master'

###
# see https://github.com/amishyn/confluence-api-client for usage
###
client = Confluence::Api::Client.new(username, password, url)

errors = []
files = Dir.glob("#{path}/**/*")
converted = 0

files.each do |file|
  if file.to_s.match('.md')
    converted += 1
    next if converted <= 3
    relative_path = file.to_s.gsub("#{path}/",'')
    title = file.to_s.gsub("#{path}/",'').gsub('/','_').gsub('.md','')
    content = File.read(file)
    content += "\n\n\n [original document](#{original_root_path}/#{relative_path})"
    html_content = Kramdown::Document.new(content).to_html

    puts "creating #{title}"
    page = client.create({type:"page",
                      title: title,
                      space: {key: space},
                      ancestors:[{id: parent_page_id}],
                      body: {storage:{value: html_content,
                                      representation: "storage"}}})
    errors << page if page['statusCode'].to_i > 200
  end
end

puts "converted #{converted}"
puts "errors:"
puts errors.inspect

puts 'done'


blog comments powered by Disqus
Dan Mayer Profile Pic
Welcome to Dan Mayer's development blog. I primary write about Ruby development, distributed teams, and dev/PM process. The archives go back to my first CS classes during college when I was first learning programming. I contribute to a few OSS projects and often work on my own projects, You can find my code on github.

Twitter @danmayer

Github @danmayer