A couple of months ago we released our public API for Swagger file uploads. At the end of that post, we promised to introduce more endpoints to open up and allow more access via APIs. Today we're releasing the ability to sync a folder of markdown files on your computer to a ReadMe project. This has been one of our most popular requests over the years (especially from engineers!).
Now when you create a new doc on ReadMe, it'll give you the option to create that doc via our API instead:
Upon clicking this you will see a tutorial for creating this doc via our API:
We use a combination of frontmatter (to allow you to set things like category, title, and whether it is hidden) and markdown to determine the body content.
This is available in our newly rewritten rdme command line program which we've bumped to version 2. This is really exciting as it enables our customers to integrate this into their workflow however they need to: pull requests for documentation changes, resolving merge conflicts locally and automatically keeping your docs up to date on every deploy (via CI/CD).
This is all brand new, so there may be problems. This is the first time we're exposing our property names which have typically been internal prior to this change, so there may be undocumented properties or no simple ways to do things that are currently easy to do within ReadMe. If you're having problems, please email [support@readme.io](mailto:support@readme.io?subject=ReadMe Docs API Problem).
FAQs
Do I have to sync everything?
No, this is totally optional and can be done on a per doc basis or slowly migrated as and when required.
How do I edit an existing doc?
Right now we do not have an amazing way to expose category ids within our dash. The only way to get it is to start the process of creating a new doc (in the category of the existing doc), grab the example markdown from there and put it into a file with a filename of the existing slug.
To grab the raw markdown body content, press the "Switch to raw mode" button in the top right next to "Save". Then copy and paste the whole contents below the frontmatter in your markdown file.
If you accidentally delete anything, you can check the page history to restore.
How do I delete?
As the doc syncing is done via "merging" what we have remotely on ReadMe and what you are presenting locally, if a file is deleted from your file system, we have to make the assumption that you've just decided to stop updating via the file system.
To delete, you must delete both from the file system and from ReadMe.
How do I know if a doc has been updated via the API?
Similarly to how we tell you if a doc is being synced via Swagger, we show you a message in the dash if this doc has ever been synced from the API:
How do I change slug?
Both the filename and the slug in ReadMe must be updated. If it is only changed in one of these, then a new doc would be created.
Future
We're going to be working on improvements to this in future. Some examples may include syncing a whole folder solely from the API (which could help with deletes/renames), nested folders or includes. Any suggestions? Email [support@readme.io](mailto:support@readme.io?subject=ReadMe Docs API Feature Request)
