Merge branch 'main' of https://github.com/MicrosoftDocs/azure-devops-docs-pr into wiki-421753-d

Author: GitHubber17

docs/project/wiki/includes/wiki-naming-conventions.md

@@ -1,34 +1,38 @@
 ---
 ms.topic: include
+ms.date: 05/29/2025
 ---
 
-Each wiki page corresponds to a file within the wiki Git repo. Names you assign to a wiki page title must conform to the following restrictions.
+Each wiki page corresponds to a file in the wiki Git repository. The following restrictions apply to page file names and the file size:
 
-::: moniker range="<=azure-devops"
+- **File name**: When choosing a name for the page file, keep in mind that the fully qualified path to the file should be 235 characters or less. The full path to the page consists of the repo URL, the folder path to the page file, and the page file name. For example, `https://github.com/ExampleWiki/Contributors/Code/How-to-add-code-to-the-project.md`.
+- **Uniqueness**: The page file name must be unique within its folder location in the wiki repo hierarchy. The name is case sensitive.
+- **Special characters**: The page file name has restrictions about the following special characters:
+   - No Unicode control characters or surrogate characters
+   - No printable characters: forward slash `/`, back slash `\`, hash `#`
+   - No period `.` symbol at the start or end of the name
 
-|Restriction type| Restriction|
-|---------------|-----------|
-| File name     | The fully qualified page path shouldn't exceed 235 characters.  |
-| Uniqueness    | Page titles are case sensitive and must be unique within the wiki hierarchy.|
-|Special characters| - Must not contain any Unicode control characters or surrogate characters.<br>- Must not contain the following printable characters: `/ \ #`.<br>- Must not start or end with a period `.`.|
-| File size     | Must not exceed the maximum of 18 MB. |
-| Attachment file size |  Must not exceed the maximum of 19 MB.  |
+- **File size**: The maximum page file size is 18 MB.
+- **Attachment file size**: The maximum size for any attachment to a page file is 19 MB.
 
-### Special characters in Wiki page titles
+### Allowed special characters
 
-You can specify page titles which contain one or more of these special characters `: < > * ? | -`. For example, you can name a Markdown file as "FAQ?" or "Set-up guide". The characters have the following URI encoded strings:
+Several special characters are allowed in a page file name, such as the colon `:` and hyphen `-`. For example, you might name a Markdown file as _FAQ:0525_ or _Setup-Guide_. 
 
-> [!div class="mx-tdCol2BreakAll"]
-> |        Character        | Encoded string |
-> |------|---------|
-> |        `:`      |      %3A       |
-> |        `<`     |      %3C       |
-> |        `>`        |      %3E       |
-> |        `*`        |      %2A       |
-> |        `?`        |      %3F       |
-> |        `|`      |      %7C       |
-> |       `-`       |      %2D       |
-> |         `"`      |      %22       |
+> [!IMPORTANT]
+> To avoid errors in page syntax and browser navigation, don't use the space character (` `) in page file names. If you name your page files based on the page title, replace any spaces in the page title with a hyphen (`-`) in the file name.
 
-::: moniker-end
+The following table lists the special characters allowed in wiki page file names and the corresponding URI encoded string:
 
+| Character  | Symbol  | URI string      |
+|------------|:-------:|:---------------:|
+| **Colon**                 | `:`  | %3A |
+| **Left angle bracket**    | `<`  | %3C |
+| **Right angle bracket**   | `>`  | %3E |
+| **Asterisk** (_wildcard_) | `*`  | %2A |
+| **Question mark**         | `?`  | %3F |
+| **Pipe**                  | `\|` | %7C |
+| **Hyphen** (_dash_)       | `-`  | %2D |
+| **Double quote**          | `"`  | %22 |
+
+For example, the file name _FAQ:0525_ is encoded as `FAQ%3A0525`.

docs/project/wiki/media/wiki/wiki-repo-order-file-example.png

@@ -48,7 +48,7 @@ Both types of wiki apply the same folder and file structure within the Git repo.
 
 For a *provisioned wiki*, GitHub manages the page sequence and page list automatically as you add or move pages within the navigation pane.
 
-For a _published as code wiki_, you need to maintain the page sequence **manually**. To structure the list of pages in the navigation pane, you define an _*.order*_ file at the root and for each subfolder or parent page that contains subpages. For more information, see [Wiki Git repository files and file structure](wiki-file-structure.md#order-file).
+For a _published as code wiki_, you need to maintain the page sequence **manually**. To structure the list of pages in the navigation pane, you define an _*.order*_ file at the root and for each subfolder or parent page that contains subpages. For more information, see [Wiki Git repository files and file structure](wiki-file-structure.md#page-sequence-and-the-order-file).
 
 <a id="revisions"></a>
 

docs/project/wiki/media/wiki/wiki-toc-example.png

@@ -1,71 +1,92 @@
 ---
-title: Wiki files, structure, and conventions
+title: Wiki Files, Folder Structure, Git Repo Conventions
 titleSuffix: Azure DevOps 
-description: Learn about the file conventions of the Git repository and project wikis in Azure DevOps.
+description: Explore the file and folder structure for provisioned wikis or wikis published as code in Azure DevOps, including naming and location conventions for the Git repository.
 ms.subservice: azure-devops-wiki
 ms.custom: wiki, devdivchpfy22
-ms.topic: conceptual 
+ms.topic: concept-article
 ms.author: chcomley
 ms.reviewer: gopinach
 author: chcomley
-monikerRange: "<=azure-devops"
-ms.date: 01/05/2024  
+ms.date: 05/29/2025
+#customer intent: As an Azure DevOps developer, I want to understand the wiki file and folder structure in the Git repository, so I can follow the naming and location conventions.
 ---
 
-# Wiki files and file structure
+# Wiki file and folder structure in Git
 
 [!INCLUDE [version-lt-eq-azure-devops](../../includes/version-lt-eq-azure-devops.md)] 
 
-Learn about the files and file structure for project wikis and code wikis. The following guidance might specify code wikis, but it applies to both types of wiki.
+This article describes the files and folder structure for provisioned wikis and wikis published as code. For both types of wiki, the files are stored in a Git repository. Files can include Markdown pages, code, images, attachments, or other artifacts. To establish the presentation sequence of the files, Git adds a special file (_.order_) in each repo folder. 
 
-When you create a team project, a wiki isn't created by default. For more information, see [Create a wiki](wiki-create-repo.md), [Create a README](../../repos/git/create-a-readme.md), or [Provisioned wikis vs. published code as a wiki](provisioned-vs-published-wiki.md).
+When you create a project, a wiki isn't created by default. You can [provision a wiki](wiki-create-repo.md), [create a README](../../repos/git/create-a-readme.md), or [publish project code as a wiki](../../project/wiki/publish-repo-to-wiki.md).
 
-Each code wiki is powered by a Git repository in the back-end. This repository stores the Markdown pages, images, attachments, and the sequence of pages and subpages. You create your wiki via the Azure DevOps user interface, and then you can edit the wiki via your [Git repository URL path](wiki-create-repo.md#how-can-i-go-to-the-git-repository). For more information about publishing code wikis, see [Publish a Git repository to a wiki](publish-repo-to-wiki.md).
+You create your wiki by using the Azure DevOps user interface. Then you can edit the wiki from your [Git repository URL path](wiki-create-repo.md#how-can-i-go-to-the-git-repository).
 
-## Wiki file and folder structure
+## Repository files and folder structure
 
-The team project wiki Git repositories are assigned the following labels.
+The Git repository for a wiki has two naming conventions:
 
-- Wiki repo for a team project: `ProjectName.wiki`
-- Main branch: `wikiMain`
+- The wiki repo name is `<ProjectName>.wiki` where `<ProjectName>` is the name of your project.
+- The name of the root branch for the wiki repo is `wikiMain`.
 
-Manage your wiki repo in the same way you manage any other Git repo, by defining branch policies on the wikiMain branch. But, you can make changes to your local wikiMain branch and push them directly to the remote branch without defining any policies.
+You manage a wiki repo in the same way you manage other Git repos by defining branch policies on the `wikiMain` branch. You can also make changes to your local `wikiMain` branch and push them directly to the remote branch without defining any policies.
 
-The wiki repository has the following files and folders:
-- File for each Markdown page entered at the root level
-- File labeled `.order` at the root and under each folder  
-- Folder for each page that has subpages  
-- `.attachments` folder, storing all the attachments of the wiki  
+A wiki repo consists of the following files and folders:
+
+- A file for each Markdown page located at the root level
+- A file named _.order_ located at the root level and also within each subfolder
+- A subfolder for each wiki page that has subpages
+- A folder named _.attachments_ to store all attachments used in the wiki
 
 ## File naming conventions
 
-Each file requires using hyphens instead of spaces in the page title. For example, the *How to contribute* page title corresponds to the `How-to-contribute.md` file name. The page name gets added to the URL, ensuring that links you share remain intact as the wiki changes over time.
+The file name for each wiki page corresponds to the wiki page title. In the file name, a hyphen (`-`) represents a space in the page title. For example, the page title "How to contribute" corresponds to the file name _How-to-contribute.md_. The URL path to the wiki page includes the file name. For example, `https://github.com/ExampleWiki/How-To/How-to-contribute.md`. This approach helps ensure bookmark links to the page remain intact as the wiki changes over time.
 
 [!INCLUDE [temp](./includes/wiki-naming-conventions.md)]
 
-## *.order* file
+## Page sequence and the .order file
+
+The _.order_ file defines the wiki page sequence. Git looks for this file in each folder to identify the sequence to present files at that location. The default page sequence is alphabetical order (A to Z) by file name.
+
+### Define custom page sequence
+
+When a folder doesn't have an _.order_ file, Git uses the default alphabetical sequence.
+
+You can define a custom sequence for any folder by updating the _.order_ file in the folder, including at the root level.
+
+The following visual shows an example of a wiki table of contents (TOC) and the corresponding _.order_ file that creates the TOC.
+
+:::row:::
+:::column span="":::
+
+**Wiki TOC displays in the web browser**
+
+:::image type="content" source="media/wiki/wiki-toc-example.png" border="false" alt-text="Screenshot of the TOC for a wiki with several folders expanded to show subfolders.":::
+
+:::column-end:::
+:::column span="":::
+
+**.order file defines the TOC page sequence**
+
+:::image type="content" source="media/wiki/wiki-repo-order-file-example.png" border="false" alt-text="Screenshot of a wiki folder and file list in a Git repository. The .order file is open and shows the definition for the TOC page sequence."::: 
+
+:::column-end:::
+:::row-end:::
 
-The *.order* file defines the sequence of pages within the wiki. The following visual shows an example of a wiki TOC and it's corresponding .order file.
+The _.order_ file changes the sequence from alphabetical to "Marketing" followed by "Fabrikam Fiber."
 
-| **Wiki TOC**     | ***.order* file**                               |
-|--------------|--------------------------------------------|
-| :::image type="content" source="media/wiki/wiki-toc-example.png" alt-text="Screenshot of wiki TOC example."::: | :::image type="content" source="media/wiki/wiki-repo-order-file-example.png" alt-text="Screenshot of Wiki example order file."::: |
+For more information about how to reorder wiki pages, see [Add, edit, and reorder wiki pages](add-edit-wiki.md#reorder-a-wiki-page).
 
-The default hierarchy is in alphabetical sequence, however you can change this hierarchy in the *.order* file. For more information about how to reorder wiki pages, see [Add and edit wiki pages, Reorder a wiki page](add-edit-wiki.md#reorder-a-wiki-page).
+### Restore alphabetical sequence
 
-### Delete the *.order* file to revert to alphabetical sorting
+If a folder has a custom sequence, you can revert the sort method to alphabetical by following these steps:
 
-When there's no *.order* file the pages get sorted alphabetically. To revert to alphabetical sorting, do the following steps:
+1. Copy the clone URL for the wiki and open it in a browser. The Git repository for the wiki opens.
 
-1. Copy the clone URL for the wiki and open it in a browser.
-   Doing so opens the Git repository (files hub), which backs the wiki.
-2. Go to the *.order* file and delete it.
-   The file gets automatically (re)created after deletion, for example, in a drag and drop action on an article.
+1. Go to the _.order_ file that you want to revert and delete the file. After the file is deleted, Git automatically creates a new _.order_ file for that location. The new file uses the default sequence.
 
-## Related articles
+## Related content
 
 - [Set up wiki vs. publish code as wiki](provisioned-vs-published-wiki.md)
 - [Create a wiki for your team project](wiki-create-repo.md)
-- [Publish a Git repository to a wiki](publish-repo-to-wiki.md)
-- [Update wiki pages offline](wiki-update-offline.md)
-- [Manage README and wiki permissions](manage-readme-wiki-permissions.md)
+- [Publish a Git repository to a wiki](publish-repo-to-wiki.md)