KB Article Linking: Best Practices

We know that over time, you may have a need to combine, split, or deprecate individual KB articles. To help you keep your KB organized (with as few broken links as possible), here's some recommendations on the best way to manage changes:

• Relative Linking: Whenever you link from one article to another, always use relative links instead of hard-coded ones. You can learn how to do this in our article, 📄 How to create relative links to other KB articles. Right now these function similarly to simple links, but the Pylon team is looking into future Relative Linking capabilities such as:

  • Broken link detection to help you identify and fix other articles that may reference a deleted article

  • Deep links that will allow you to link to specific sections of another help article

• Deleting Articles: Our current recommendation is to avoid deleting articles whenever possible. Instead, keep the article in place and under its settings, toggle it to "Accessible only by direct link" to prevent it from appearing in your KB. Then, you can replace the content with a link to the appropriate new article -- functionally acting as a redirect with one extra click for your customer.

• Renaming Articles: Whether it's because you changed the name of a feature or feel there's an adjustment to a title that can be made for clarity, you should also manually update the URL slug. This ensures that your KB is optimized for SEO -- and don't worry, it won't break existing links since navigation relies only on the article ID (which can't be changed). You can adjust slugs through the article settings.

  

• Splitting / Reorganizing Articles: If you need to separate out a portion of an article to a new article, you'll need to create a new article with the correct title, then copy/paste the existing content from your old article. Consider whether it makes sense to include a link to the new content in the original article.

• Merging Articles: If you think two articles should be combined (because they're duplicates or simply grouped features), you should decide which article is most likely to be linked to in other places. In that article, copy/paste in any relevant content from the article to be deleted, and then follow the best practices for Renaming and Deleting articles as needed.