Skip to main content

Third-party Knowledgebases

Swimm's markdown (.swm.md) is easily shared to your internal wikis or knowledgebases. If the back-end supports markdown, you can open your docs right from the .swm/ directory and copy/paste it, or write a script to read the files and upload them using whatever API the software provides. Most developer-centric platforms have a RESTful API that allows simple 'Create this if it doesn't exist, update it if it does' functionality.

Tools like Pandoc can be used to convert your Swimm content to HTML, MediaWiki / JiraWiki, TeX formats, DocBook and many many more. AsciiDoc is another great open source option for converting between formats.

Below, we've got some guidance on the best way to proceed with publishing on some of the more popular platforms.

Things to keep in mind with all integrations

We want Swimm to be as frictionless as possible in all ways that you use it. We want your documentation to be easy to read because it was easy to create, easy to keep up-to-date and easy to publish. Right now, our main development focus is on how those experiences happen within Swimm itself, and we plan to make major strides forward in all of those areas.

With that said, we want to keep Swimm's format as portable and easy to incorporate into your existing systems as possible, so we try to make this easy as we can to accomplish with existing tools.

No matter which way you go, you'll likely need to do the following things:

  1. At the bottom of every .sw.md file is a line that looks like this:

     <!-- THIS IS AN AUTOGENERATED SECTION. DO NOT EDIT THIS SECTION DIRECTLY -->
    ### Swimm Note

    You'll probably want to remove that in the intermediate output of your tool, like Pandoc. This means you'll remove it after it has been read from your source file in .swm/, but before it's written to the destination format. Pandoc calls this an Abstract Syntax Tree, which is just a phase where every part of the document can be manipulated before it's written.

  2. Different documentation systems don't always strictly adhere to the formats that they support, some extend those formats, and some only support certain parts of them. A great example is many tools that support only certain features of Commonmark.

Here's a list of what we recommend with the most common systems. If you have a question about a particular one, or one that isn't listed, head to our Community Slack channel and we'll try to help.

Notion

Use Pandoc to convert the Swimm markdown to HTML, and import it into notion.

Atlassian Confluence

Use Pandoc to convert the Swimm markdown to HTML, and then import it into confluence. You can also try automating this by exporting to other formats that their RESTful API supports.

With Atlassian Confluence, this is most easily accomplished by defining a page ID that will be the parent for your Swimm content, and creating pages as children of that page for each document you want to publish. This allows you to automate updating Confluence when your Swimm docs update.

Docusaurus

Swimm maintains a docs only mode template for Docusaurus - just fork this repo and follow the instructions in the README. You'll have a site complete with offline search that you can deploy to any host that supports node apps.

Stack Overflow For Teams & Stack Overflow Enterprise

Export the .swm.md to Commonmark with pandoc, and you can use it on both Teams & Enterprise. Automation will be feasible if the corresponding APIs allow read/write access, currently both are read-only.

Jira Wiki (All)

Cloud and on-premisis documentation centers using Jira Wiki Formatting should use Pandoc to convert from .swm.md to Jira Wiki, and then check with your IT / DevOps / SRE team to figure out what your automation options might look like.

MediaWiki / Generic Wiki

Use Pandoc to convert to the closest markup flavor (MediaWiki is generally good for most of them), and then paste / update the content. This can be automated in many ways; while MediaWiki has a very easy RESTful API; you can also just update the database.