Specify category slug and order on creation

[garrett-wade]

In our CI/CD pipeline, we are syncing documents from Project 1 to Project 2. However, we have encountered an issue with category names and slugs not matching between the two projects.

Currently, when creating a category in Project 1, the category name and slug generally match, unless there is a duplicate where it appends -1. This works fine until we have to change the category name in Project 1, which does not update the slug. As a result, when we create the same category in Project 2, the names will match but the slugs will not, causing issues when uploading documents as each document can only have one categorySlug.

To alleviate this, we propose specifying the category slug when creating a category to ensure the match between projects, even if the category name differs. This will prevent the issue of duplicated slugs and allow us to sync documents seamlessly between projects.

Furthermore, we want to preserve the category order between projects, which can only be done through the admin UI. We propose adding functionality to our CI/CD pipeline to allow us to specify the category order programmatically.

We believe these changes will improve our workflow and streamline our document syncing process between projects.

[kanadgupta]

Hi @garrett-wade! This would be a breaking change to our API and we're currently in the process of totally revamping our API and docs syncing patterns. The goal would be to move away from the confusing ID vs. slug paradigm entirely. Don't have an ETA on these changes but will definitely keep this feedback in mind!

[mnahkies]

Just ran into a similar issue, don't suppose you have an ETA now?

My use-case:

• We upload our documentation through a CI job
• We want to "stage" larger changes on a hidden version, to review what they look like rendered prior to pushing them live
• The category id in the front matter is annoying, as the id's are unique to each version, meaning I'll need to write a script to query the README API and dynamically adjust the front matter, which feels awkward
  • If I could use a category-slug in place of the id that would solve my use-case

[ashleysamay]

Hey @mnahkies! We're working on this now and aiming to have a beta in the next few months. If you're interested in being part of the alpha/beta drop us a line at alpha@readme.io