Organize your docs so readers can find the right guide and follow related tasks in a sensible order. This guide explains products, sections, sidebar labels, article order, nested pages, aliases, and visibility, with a workflow for changing them without duplicating articles.
Before you begin
You need permission to edit and publish documentation. Open Site → Docs to find the articles you want to organize. If you cannot access them, see Why can’t I see or edit a feature?.
The basic article editor exposes Category and Tags in Taxonomy, but it does not have a sidebar organizer or fields for products, sections, order, parents, and aliases. Those settings can be changed by a site assistant with documentation-editing access or by the person who maintains your docs. If your assistant cannot perform the requested change, ask your site administrator rather than creating replacement articles.
Before changing an established collection:
- Record each affected article’s current public address and intended placement.
- Check for unpublished work and coordinate with anyone editing the same articles. Publishing a navigation change also publishes the article’s current saved content.
- Clear or coordinate any scheduled release before making changes that might affect it.
- Decide what readers should see first, what belongs together, and which articles need to remain easy to find from shared links.
For writing the article itself, use Creating a documentation article.
Understand the different ways readers find a guide
Product identifies a collection, such as a particular application or service. Ask your assistant or docs administrator to reuse the existing product when adding or moving articles, so they stay in one collection. A product is not the same thing as a topic such as “Billing.”
Section groups articles within the documentation, such as “Account and billing” or “Working with files.” New articles created in the editor start in the default Getting Started section, so check placement before publishing.
Category groups articles in the docs index and its filters. It is separate from the sidebar section. Setting a category does not override an article’s explicit section. You can use the same readable name for both when that makes the collection easier to understand.
Navigation label is the short text readers see in the sidebar. It can be shorter than the article title: “Download an invoice” can link to an article titled “Downloading invoices for your subscription.” Changing the navigation label does not change the article’s title or address.
Address is where the article lives, usually /docs/ followed by its slug. Moving an article to a different section or changing its order does not require changing that address.
A collection with one product commonly shows sections as the main sidebar groups. A collection containing multiple products can group navigation by product instead. The theme and the current product view affect the presentation, so check the resulting sidebar on your actual website.
Plan sections and article order
- List the existing articles and their current addresses. Remove duplicate entries from your proposed outline; link to one canonical guide for each task.
- Choose a small set of recognizable sections. Use customer language such as “Account and billing,” not team names or internal project names.
- Put initial setup before advanced options, then place troubleshooting near the tasks it supports. Keep related articles together.
- Choose concise navigation labels that remain clear on a phone. Avoid several adjacent links called “Overview,” “Setup,” or “Getting started” without enough context.
- Record the intended order before asking for changes. For example: “Download an invoice,” “Update payment details,” then “Fix a failed payment.”
Use a section to group useful articles; do not create an empty welcome article solely to give the section a name.
How ordering works
Products, sections, and articles have separate positions. Decide which section comes first, then the article sequence within each section. Ask your assistant or docs administrator to apply the complete sequence consistently across the affected articles.
For example, put “Download an invoice” before “Fix a failed payment,” and use an existing neighboring article to identify the right section. You do not need to change article addresses to rearrange the list.
Nested articles stay within their branches. Moving an article earlier does not move it into a different parent or section. Sorting rows in the admin Docs list also does not rearrange the public sidebar.
Apply a navigation change to existing articles
Use the site’s assistant if it has permission to manage docs. Otherwise, give the same information to your docs administrator.
- Identify the target article by its exact public path. Include the path of an existing article in the destination section so the correct product and section can be reused.
- State the intended sidebar label and position. Say which article it should follow or precede, rather than leaving the assistant to guess the sequence.
- Ask for a draft change first. Specify that the article’s address, body, existing aliases, and visibility must be preserved unless you are deliberately changing them.
- Review the returned article and navigation settings. Confirm that the existing article was updated and that no duplicate was created.
- Reopen the article to load the saved changes before doing more editing. Check the draft body as well as its navigation settings, then preview and publish the affected articles when ready.
Here is an example request. Replace both paths and the label with articles on your own site:
For
/docs/billing/download-invoice, use the same product and section as/docs/billing/update-payment. Put it immediately before that article and use “Download an invoice” as its navigation label. Keep the other articles in their existing relative order. Preserve the current address, body, category, aliases, and visibility. Update the existing article and save as a draft; do not publish. Show me the resulting placement and any unpublished content changes before release.
For a section rename or move, identify every affected article. Changing a section’s label or ordering on only one article can leave inconsistent settings across the collection. If you also want the docs index category renamed, request that separately.
Changes to multiple articles are saved and published per article. Coordinate their release and check the collection after all affected articles are published; do not assume a single article’s Publish action updates every other article.
Importing Markdown documentation explains how Upload docs sets product and section names when creating articles from files. The current upload form does not apply every navigation setting from a file. Do not rely on adding order, parent, alias, or visibility fields to an upload to reorganize existing articles. Use the targeted change workflow above for those settings.
Nest related articles without moving their addresses
Use nesting only when it makes a relationship clearer. A short, mostly flat list is often easier to scan than several levels of folders.
Choose the article or group under which the child should appear. Give your assistant or docs administrator the parent’s exact address or name and ask them to preserve the child’s current address.
For example, a guide at /docs/download-invoice can remain at that address while being placed under the billing parent. Ask the assistant or your docs administrator to keep the parent and child in the intended product and section and verify that the child opens its original address.
Nested slugs can also contribute to the navigation tree. A path such as /docs/billing/invoices/download may appear within nested branches. An explicit parent and a nested slug can therefore affect the displayed position even when the article order numbers look correct.
Keep the hierarchy shallow. Do not assign an article as its own parent or create a loop between parent entries. After changing a parent, check its children as well as the moved entry, especially if any have the same final slug segment.
Articles, groups, and external links
The navigation supports three entry types:
- Page: an ordinary article with its own content and address. Use this for customer guides.
- Group: a container for related entries, without an article link of its own. How the group label and children appear depends on the theme; some sidebars flatten the children instead of showing a separate folder control.
- External link: an entry that sends the reader to an HTTP or HTTPS destination, such as another help center. Test the destination and label it clearly.
Groups and external links are not ordinary searchable articles. Do not convert a useful published article into one merely to make a heading or shortcut; coordinate a separate navigation entry with your docs administrator and preserve the original guide.
Keep old links working with aliases
An alias is an additional docs path associated with an article. It can help readers reach the same guide from an older address without creating a second copy.
For a navigation-only change, keep the current slug and public path. You do not need a new alias just because the sidebar label, order, or section changed.
If an article genuinely needs a new address:
- Record the old public address and the intended new one. Check that the destination is available and that the old path or alias does not belong to another article.
- Ask your docs administrator to preserve the old docs path as an alias or configure the appropriate redirect. Preserve any aliases the article already has.
- Update the article’s address and any menus or related links that should use the new address. Review and publish the changed article.
- Open the old address, the new address, and the sidebar link as a visitor. Confirm that all reach the intended guide. Test a commonly shared section link too, if one exists.
An alias is not a substitute for testing an HTTP redirect. Your site’s routing determines whether an alternate path redirects or serves the article there. Aliases also do not repair renamed heading anchors or links outside the docs area. If an old URL fails or you need it to redirect to one canonical address, use the site’s redirect settings with your administrator. See Changing a page address without breaking links for redirect planning and checks.
Choose visibility deliberately
These settings answer different questions:
- Hide from docs navigation: removes the entry from the sidebar. It can still be reachable at its public address and appear in docs search.
- Exclude from docs search: removes an article from the docs search/index collection. It can still appear in the sidebar if navigation visibility remains enabled.
- Exclude from search engines: marks the page not to be indexed by search engines. This is separate from the site’s own docs search and can take time for a search engine to reflect.
For an ordinary customer guide, leave all three exclusions off. Ask for a specific setting change rather than saying only “hide this page.” Check the direct address, sidebar, and docs search separately after publication.
None of these options makes confidential information private. Keep unfinished material in draft, and use appropriate site access controls for restricted content. See Controlling when your site is public.
The sidebar is also separate from the article’s On this page heading outline. Hiding the outline changes navigation within that article; it does not remove the article from the docs sidebar.
Verify the published navigation
After publishing every intended change:
- Open the public docs index and an affected article. Check the category in the index and the product or section in the sidebar separately.
- Expand the relevant section and confirm labels, article order, parents, and children. Click each moved link and verify the address as well as the title.
- Search the docs for a visible article by title. Check that intentionally excluded articles do not appear in docs search.
- Test any preserved aliases, redirects, and external links. Confirm the destination is correct rather than accepting any successful page load.
- Repeat the sidebar check on a phone, opening the mobile docs menu. Verify that labels are understandable and every intended article is reachable.
- Check as a visitor or appropriate reader account. Your admin access can conceal site access restrictions or missing permissions.
If your theme shows previous/next article links, check those too after reordering. They should still provide useful next steps.
Troubleshooting
The article is still in Getting Started
Check its section identifier and label. Changing Category does not replace the default section. Ask for the product and section settings to match a known article in the intended destination, then publish the reviewed change.
The sidebar order looks wrong
Compare the published sidebar with your intended sequence. Ask your assistant or docs administrator to check the product, section, and article positions together. If the sequence is correct but an article still appears elsewhere, check its parent and nested address: it may belong to a branch that is ordered as a group.
A section is split or has inconsistent names
Compare the section identifiers, readable labels, product identifiers, and order values across all affected articles. Reuse one consistent set for the section. Check Category separately if the duplication is in the docs index rather than the sidebar.
An article is missing, but its address works
Check that its saved navigation changes are published, that it is an ordinary page entry, and that it is not hidden from navigation. Expand the expected product or section and check the parent. If it is missing only from search, inspect search exclusion instead. Follow Fixing an article missing from navigation or search for the complete checks.
A navigation change has not appeared
Reopen the affected article and confirm the intended settings are saved and published. Check every article involved in a multi-article change. If the saved values are correct but the public layout still differs, ask your theme or site maintainer to check which navigation settings the layout uses. Do not create duplicates to force a particular position.
You need to undo a move
Use the recorded previous product, section, parent, label, order, and visibility to make a focused correction, then review and publish it. Restoring an older whole-article revision can also restore older content and settings, so inspect everything it changes before publishing.