Publishing Markdown to Confluence

For what seems like a long time now, I have been using RittmanMead’s md_to_conf project to automatically publish documentation from Markdown files into Confluence Cloud. I am on something of a documentation kick, and what started as a quick fix ultimately turned into a new project.

It all started with the word “legacy”…

In publishing our Markdown files, I noticed that the pages all had the legacy editor text in Confluence Cloud. I wanted to move our pages to the updated editor, and my gut reaction was “well, maybe it is because the md_to_conf project was using the v1 APIs.

The RittmanMead project is great, but it has not changed in about a year. Now, granted, once things work, I wouldn’t expect much change.

So I forked the project and started changing some API calls. The issue is, well, I just did not know when to stop. My object-oriented tendencies took over, and I ended up way past the point of no return:

• Split converter and client code into separate Python classes to simplify the main module.
• Converted the entire project to a Python module and built a wheel for simplified installation and execution.
• Added Flake8/Black for Linting
• Added a GitHub workflow for building and publishing.
• Added analysis steps to analyze the code in SonarCloud.io.

It is worth noting that, at the end of the day, the editor value was already supported in RittmanMead/md_to_conf: You just have to set the version argument to 2 when running. I found that out about an hour or so into my journey, but, by that time, I was committed.

Making a break for it

At this point, a few things had happened:

1. My code had diverged greatly from the RittmanMead project.
2. Most likely, the functionality and purpose for which the original project was written had changed.
3. I broke support for Confluence Server.
4. I have some plans for additional features for the module, including the ability to pull labels from the Markdown.

With that in mind, I had GitHub “break” the fork connection between my repository and the RittmanMead repository.

Let me be VERY clear: the README will ALWAYS reflect the source of this repository. This project would not be possible without the contributors to the RittmanMead script, and whatever happens in my respository is building on their fine work. But I have designs on a more formal package and process, as well as my own functional roadmap, so a split makes the most sense.

Introducing md-to-conf

With that in mind, I give you md-to-conf (PyPi / GitHub)! I will be adding some issues for feature enhancements and work on them as I can, although, my first order of business will most likely be some basic testing to make sure I don’t break anything as I work.

If you have a desire to contribute, please see the contribution guideline and have at it!