Frequently Asked Questions

How do I change the URL for an existing guide?

First, you must understand how a URL for a guide is created. The URLs for a guide are based on the following components:

• Stack
• Title
• publish status

The stack and title are the slug versions of the stack and title, which are generated by the utils.slugify() function. In short, all characters that are not ascii letters or numbers are translated to -, which results in readable, SEO-friendly URLs.

The publish status is an optional query string to hint to the CMS which folder to read the guide from. The CMS will search all possible publish statuses to find a guide if this is missing.

This scheme causes a problem if you want to change the stack or title of an existing guide, namely the old URL will not work. Therefore, it’s possible to setup 301 redirects for guides in the redirects file.

Finally, to change a URL for an existing guide you need to make an entry in the redirects file with the old URL that you want to replace followed by the new URL and update the URL in the associated guide listing file.

How do I change the title for an existing guide?

This process is a bit involved since the URL for a guide is based on the URL (see previous question). To do this you need to do a bit of manual work with the underlying git repository:

1. Clone your CMS content repository locally
2. Edit the title attribute in the details.json file for the guide you want to change
3. Save the file

4. Determine new slug for the new title

   • You can do this by replacing all non-ascii letters or numbers with the - character or by running the utils.slugify() function on your new title.

5. Run git mv <curr_path_to_guide> <new_path_to_guide>

   • The <new_path_to_guide> should include your new title

6. Make an entry in the redirects file.

   • Make sure to use the new title slug in the new URL.

7. Edit the URL for your guide in the guide listing file your guide belongs to
8. Commit these changes to your CMS content repository and push to github.com.
9. You can manually flush your redis cache or wait a few minutes for things to automatically refresh.

How do I change the stack for an existing guide?

1. Change the stack of your guide in the CMS web interface and save it
2. Clone your CMS content repository locally

3. Determine new slug for the new stack

   • You can do this by replacing all non-ascii letters or numbers with the - character or by running the utils.slugify() function on your new stack.

4. Make an entry in the redirects file.

   • Make sure to use the new stack slug in the new URL.

5. Edit the URL for your guide in the guide listing file your guide belongs to
6. Commit these changes to your CMS content repository and push to github.com.
7. You can manually flush your redis cache or wait a few minutes for things to automatically refresh.