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, it can be as simple as pasting Swimmโ€™s markdownfiles into the right place. You can automate this process (for example by writing a script) to copy the files or upload them to whatever publishing software you are using.

Working with Swimm files

You can create two types of assets in Swimm: Repo Docs and Cloud Docs

Repo Docs are code-coupled documents that are saved in the repository in a markdown format. All the content that you and your team create under Repo Docs is saved under the ./swm folder in the root folder.

Cloud Docs are not code coupled and they are saved in Swimm database. To export Cloud Docs please contact support@swimm.io

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.

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. Never work on the original .sw.md files. Make sure to have a copy.

  2. 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
  3. 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.

If you have a question about a particular one, or one that isn't listed, head to our Community Slack channel and we'll help you out.

Export to Notion

As you can import Markdown in Notion, it might be the best option. However, Notion might not parse code snippets properly when imported as markdown. Try to use Pandoc to convert the Swimm markdown to HTML, and import to Notion.

Export to 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 an 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-premises documentation centers using Jira Wiki Formatting should use Pandoc to convert from .swm.md to Jira Wiki. 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.