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. To link selected inline text while editing a KB article, highlight the text and press Cmd+K on macOS or Ctrl+K on Windows/Linux to open the link popover, then enter the URL and apply it. 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 allow you to link to specific H1, H2, and H3 heading sections within articles using anchor links (e.g., https://support.example.com/articles/[article-id]#[heading-text-with-number])

• 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.

  If you do need to delete an article, follow these steps:

  1. Open the article

  2. Click on the settings icon

  3. Scroll to the bottom of the sidebar where you'll find the "Delete" button

• 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. To change the URL slug: In the article editor, click the settings wheel in the top right corner, then update the article slug field. This ensures that your KB is optimized for SEO. Important: While changing the slug won't break relative links (since navigation relies only on the article ID which can't be changed), any hard‑coded URLs with the old slug will NOT automatically redirect to the new slug. Pylon's redirect feature is only intended for external KB migrations, not for internal article slug changes. This is another reason to always use relative links when linking between articles.

• 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), or if Pylon's Similar Article Detection warning appears indicating overlapping content, 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.