AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |
Back to Blog
Knowing if a post exists is simple using a CQL query, but applying the label is a bit trickier.īoth the "Add Labels" and the "Create Attachments" endpoints require the caller to specify the post ID as part of the URL in the request. To make this work, we create a unique label for each post which is a slug of its filename plus the author name and add that label to the post. To start, we want to update a post if it already exists, and create a new one if it doesn't. The next hurdle to overcome is the actual process of uploading a post. We're keeping an eye out for Mistune v2 which supports plugins, addressing this problem. It's worth noting that right now markdown-to-confluence doesn't support rendering Hugo shortcodes, since this requires hooking into the lexer. We use this to return the correct macros for images and code blocks. For example, if we want to display a local image that we've uploaded as an attachment, we'd need to use the following markup:įortunately for us, the mistune library supports creating custom renderers, allowing us to override what the output HTML looks like for a given element. The biggest challenge we encountered was leveraging macros to support image links, code blocks, and more. To do this rendering, we leveraged the mistune Python library. In general, basic HTML rendered from Markdown is compatible with the storage format. Instead, we opted to use the storage format. However, there are enough differences to make this translation really tricky. At first glance, it would make sense to use the wiki format, since it looks similar to Markdown. The first hurdle is generating the post content. The Confluence hierarchy, content structure, and associated metadata introduces some challenges, specifically with the way we generate the content and the order of operations we use to create a new post. With this background in mind, let's talk about the details of how leverage this API to deploy Markdown posts into Confluence. In addition to the content itself, each post also contains labels (aka "tags"), and attachments such as images. The unique aspect of the storage format is the ability to use macros, which are Confluence-defined tags that render content in a special way, like code blocks, embedded third-party content, or user profile information. There are currently two formats Confluence supports for uploading content: the XHTML " storage" format, or the traditional " wiki" format. Posts are organized into a "space", as well as a hierarchy where each post can have both parent and child posts. While we're far from Confluence experts, before talking about how we handled our specific use-case, it helps to give a quick background on how the Confluence API works.Ĭonfluence offers a REST API that exposes all the CRUD (Create, Replace, Update, Delete) operations you would expect for posts. This didn't come without challenges, so in this post we'd like to walk through how we were able to leverage the Confluence API to both let us keep the Journal experience that works for our team, while making our research more accessible to the wider company. To that end, we're open-sourcing a project we built called markdown-to-confluence which is able to mirror posts we write in Journal (or any Markdown posts, for that matter) to an upstream Confluence instance. However, we feel it's important to make our findings available to the wider company. This works fine for many use cases, but it didn't fit the requirements we needed to take daily notes without breaking from our workflow. However, while Journal opens the door for us as a Lab to communicate our findings more regularly and effectively within the team, it also has the potential to introduce a serious problem with any research group: becoming a silo of information.įor background, most of Duo uses Confluence for sharing information. Since adopting it across our team, we've seen the quality and quantity of our research notes go up. We made Journal because we recognized that writing and sharing research notes is a critical part of the research process. IntroductionĪ couple of months ago, we open-sourced Journal, the system we use here in Duo Labs to share research notes within the team.
0 Comments
Read More
Leave a Reply. |