We have many questions that pertain to general technical concepts in Swimm asked and answered on our website. If you have not yet seen them, please take a look - they answer questions you might have about setting up workflows, and how Swimm thinks and works at a high level.
Below are questions that you might have as you actually dive into writing documentation using Swimm. If you have a question that isn't answered here, please don't hesitate to reach out to us!
You can also check our troubleshooting tips for common problems.
How do I enable markdown exporting?
From the "Integrations" menu in any repository:
An admin needs to click the slider to enable exporting:
How do I start a document from a commit SHA? What are the advantages to this?
Think about the last time you committed a non-trivial feature to something. You had code that implemented the feature, code that perhaps implemented configuration options for the feature, changes that added the feature to the build system, tests for the feature, and maybe even some configuration settings for your cluster or web server. That's a fantastic basis from which to structure a document about the new feature, because Swimm will automatically pull in snippets from what you committed.
This means that your new document will be auto-populated with the feature code, configuration code, styles, whatever might be there, and you can simply reselect or discard anything that isn't relevant. Now, all you have to do is write the narrative around how it works.
To do this, open a new document, but select the "From commit SHA" option:
This will open a dialog box where you can put in the SHA from the commit log:
At this point, you'll be brought to the editor where you can adjust the snippets that were imported from the commit, write your text and save it.
How do I incorporate markdown documents that I already have into playlists? Can I import them?
We're working hard on a way to import existing markdown documentation so that your Markdown files become Swimm documents ready to be coupled to your code. We're not quite there yet, but you can link to your existing markdown files in playlists (as we'll show below), or use Smart Paths within docs to reference other
.md files in your repository.
The playlist link editor allows you to link to files within the repo using a path that is relative to the repo root. In this example, we'd link to the README file in the root of the repository. If we wanted to, we could change that to
documents/markdown/README.md instead. Make sure you click on the "links" option in the playlist editor, and then add your link as shown: