1--- 2stage: Create 3group: Editor 4info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" 5type: reference, how-to 6--- 7 8# Wiki **(FREE)** 9 10If you don't want to keep your documentation in your repository, but you want 11to keep it in the same project as your code, you can use the wiki GitLab provides 12in each GitLab project. Every wiki is a separate Git repository, so you can create 13wiki pages in the web interface, or [locally using Git](#create-or-edit-wiki-pages-locally). 14 15GitLab wikis support Markdown, RDoc, AsciiDoc, and Org for content. 16Wiki pages written in Markdown support all [Markdown features](../../markdown.md), 17and also provide some [wiki-specific behavior](../../markdown.md#wiki-specific-markdown) 18for links. 19 20In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/17673/), 21wiki pages display a sidebar, which you [can customize](#customize-sidebar). This 22sidebar contains a partial list of pages in the wiki, displayed as a nested tree, 23with sibling pages listed in alphabetical order. To view a list of all pages, select 24**View All Pages** in the sidebar: 25 26![Wiki sidebar](img/wiki_sidebar_v13_5.png) 27 28## View a project wiki 29 30To access a project wiki: 31 321. On the top bar, select **Menu > Projects** and find your project. 331. To display the wiki, either: 34 - On the left sidebar, select **Wiki**. 35 - On any page in the project, use the <kbd>g</kbd> + <kbd>w</kbd> 36 [wiki keyboard shortcut](../../shortcuts.md). 37 38If **Wiki** is not listed in the left sidebar of your project, a project administrator 39has [disabled it](#enable-or-disable-a-project-wiki). 40 41## Configure a default branch for your wiki 42 43> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221159) in GitLab 14.1. 44 45The default branch for your wiki repository depends on your version of GitLab: 46 47- *GitLab versions 14.1 and later:* Wikis inherit the 48 [default branch name](../repository/branches/default.md) configured for 49 your instance or group. If no custom value is configured, GitLab uses `main`. 50- *GitLab versions 14.0 and earlier:* GitLab uses `master`. 51 52For any version of GitLab, you can 53[rename this default branch](../repository/branches/default.md#update-the-default-branch-name-in-your-repository) 54for previously created wikis. 55 56## Create the wiki home page 57 58When a wiki is created, it is empty. On your first visit, you can create the 59home page users see when viewing the wiki. This page requires a specific title 60to be used as your wiki's home page. To create it: 61 621. On the top bar, select **Menu**. 63 - For project wikis, select **Projects** and find your project. 64 - For group wikis, select **Groups** and find your group. 651. On the left sidebar, select **Wiki**. 661. Select **Create your first page**. 671. GitLab requires this first page be titled `home`. The page with this 68 title serves as the front page for your wiki. 691. Select a **Format** for styling your text. 701. Add a welcome message for your home page in the **Content** section. You can 71 always edit it later. 721. Add a **Commit message**. Git requires a commit message, so GitLab creates one 73 if you don't enter one yourself. 741. Select **Create page**. 75 76## Create a new wiki page 77 78Users with the [Developer role](../../permissions.md) can create new wiki pages: 79 801. On the top bar, select **Menu**. 81 - For project wikis, select **Projects** and find your project. 82 - For group wikis, select **Groups** and find your group. 831. On the left sidebar, select **Wiki**. 841. Select **New page** on this page, or any other wiki page. 851. Select a content format. 861. Add a title for your new page. Page titles use 87 [special characters](#special-characters-in-page-titles) for subdirectories and formatting, 88 and have [length restrictions](#length-restrictions-for-file-and-directory-names). 891. Add content to your wiki page. 901. Optional. Attach a file, and GitLab stores it according to your installed version of GitLab: 91 - *Files added in [GitLab 11.3 and later](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33475):* 92 Files are stored in the wiki's Git repository. 93 - *Files added GitLab 11.2 and earlier:* Files are stored in GitLab itself. To add 94 the file to the wiki's Git repository, you must re-upload the file. 951. Add a **Commit message**. Git requires a commit message, so GitLab creates one 96 if you don't enter one yourself. 971. Select **Create page**. 98 99### Create or edit wiki pages locally 100 101Wikis are based on Git repositories, so you can clone them locally and edit 102them like you would do with every other Git repository. To clone a wiki repository 103locally, select **Clone repository** from the right-hand sidebar of any wiki page, 104and follow the on-screen instructions. 105 106Files you add to your wiki locally must use one of the following 107supported extensions, depending on the markup language you wish to use. 108Files with unsupported extensions don't display when pushed to GitLab: 109 110- Markdown extensions: `.mdown`, `.mkd`, `.mkdn`, `.md`, `.markdown`. 111- AsciiDoc extensions: `.adoc`, `.ad`, `.asciidoc`. 112- Other markup extensions: `.textile`, `.rdoc`, `.org`, `.creole`, `.wiki`, `.mediawiki`, `.rst`. 113 114### Special characters in page titles 115 116Wiki pages are stored as files in a Git repository, so certain characters have a special meaning: 117 118- Spaces are converted into hyphens when storing a page. 119- Hyphens (`-`) are converted back into spaces when displaying a page. 120- Slashes (`/`) are used as path separators, and can't be displayed in titles. If you 121 create a title containing `/` characters, GitLab creates all the subdirectories 122 needed to build that path. For example, a title of `docs/my-page` creates a wiki 123 page with a path `/wikis/docs/my-page`. 124 125### Length restrictions for file and directory names 126 127> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/24364) in GitLab 12.8. 128 129Many common file systems have a [limit of 255 bytes](https://en.wikipedia.org/wiki/Comparison_of_file_systems#Limits) 130for file and directory names. Git and GitLab both support paths exceeding 131those limits. However, if your file system enforces these limits, you cannot check out a 132local copy of a wiki that contains filenames exceeding this limit. To prevent this 133problem, the GitLab web interface and API enforce these limits: 134 135- 245 bytes for page titles (reserving 10 bytes for the file extension). 136- 255 bytes for directory names. 137 138Non-ASCII characters take up more than one byte. 139 140While you can still create files locally that exceed these limits, your teammates 141may not be able to check out the wiki locally afterward. 142 143## Edit a wiki page 144 145You need at least the [Developer role](../../permissions.md) to edit a wiki page: 146 1471. On the top bar, select **Menu**. 148 - For project wikis, select **Projects** and find your project. 149 - For group wikis, select **Groups** and find your group. 1501. On the left sidebar, select **Wiki**. 1511. Go to the page you want to edit, and either: 152 - Use the <kbd>e</kbd> wiki [keyboard shortcut](../../shortcuts.md#wiki-pages). 153 - Select the edit icon (**{pencil}**). 1541. Edit the content. 1551. Select **Save changes**. 156 157### Create a table of contents 158 159To generate a table of contents from a wiki page's subheadings, use the `[[_TOC_]]` tag. 160For an example, read [Table of contents](../../markdown.md#table-of-contents). 161 162## Delete a wiki page 163 164You need at least the [Developer role](../../permissions.md) to delete a wiki page: 165 1661. On the top bar, select **Menu**. 167 - For project wikis, select **Projects** and find your project. 168 - For group wikis, select **Groups** and find your group. 1691. On the left sidebar, select **Wiki**. 1701. Go to the page you want to delete. 1711. Select the edit icon (**{pencil}**). 1721. Select **Delete page**. 1731. Confirm the deletion. 174 175## Move a wiki page 176 177You need at least the [Developer role](../../permissions.md) to move a wiki page: 178 1791. On the top bar, select **Menu**. 180 - For project wikis, select **Projects** and find your project. 181 - For group wikis, select **Groups** and find your group. 1821. On the left sidebar, select **Wiki**. 1831. Go to the page you want to move. 1841. Select the edit icon (**{pencil}**). 1851. Add the new path to the **Title** field. For example, if you have a wiki page 186 called `about` under `company` and you want to move it to the wiki's root, 187 change the **Title** from `about` to `/about`. 1881. Select **Save changes**. 189 190## View history of a wiki page 191 192The changes of a wiki page over time are recorded in the wiki's Git repository. 193The history page shows: 194 195![Wiki page history](img/wiki_page_history.png) 196 197- The revision (Git commit SHA) of the page. 198- The page author. 199- The commit message. 200- The last update. 201- Previous revisions, by selecting a revision number in the **Page version** column. 202 203To view the changes for a wiki page: 204 2051. On the top bar, select **Menu**. 206 - For project wikis, select **Projects** and find your project. 207 - For group wikis, select **Groups** and find your group. 2081. On the left sidebar, select **Wiki**. 2091. Go to the page you want to view history for. 2101. Select **Page history**. 211 212### View changes between page versions 213 214> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15242) in GitLab 13.2. 215 216You can see the changes made in a version of a wiki page, similar to versioned diff file views: 217 2181. On the top bar, select **Menu**. 219 - For project wikis, select **Projects** and find your project. 220 - For group wikis, select **Groups** and find your group. 2211. On the left sidebar, select **Wiki**. 2221. Go to the wiki page you're interested in. 2231. Select **Page history** to see all page versions. 2241. Select the commit message in the **Changes** column for the version you're interested in. 225 226 ![Wiki page changes](img/wiki_page_diffs_v13_2.png) 227 228## Track wiki events 229 230> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14902) in **GitLab 12.10.** 231> - Git events were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216014) in **GitLab 13.0.** 232> - [Feature flag for Git events was removed](https://gitlab.com/gitlab-org/gitlab/-/issues/258665) in **GitLab 13.5** 233 234GitLab tracks wiki creation, deletion, and update events. These events are displayed on these pages: 235 236- [User profile](../../profile/index.md#access-your-user-profile). 237- Activity pages, depending on the type of wiki: 238 - [Group activity](../../group/index.md#view-group-activity). 239 - [Project activity](../working_with_projects.md#view-project-activity). 240 241Commits to wikis are not counted in [repository analytics](../../analytics/repository_analytics.md). 242 243## Customize sidebar 244 245> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23109) in GitLab 13.8, the sidebar can be customized by selecting the **Edit sidebar** button. 246 247You need at least the [Developer role](../../permissions.md) to customize the wiki 248navigation sidebar. This process creates a wiki page named `_sidebar` which fully 249replaces the default sidebar navigation: 250 2511. On the top bar, select **Menu**. 252 - For project wikis, select **Projects** and find your project. 253 - For group wikis, select **Groups** and find your group. 2541. On the left sidebar, select **Wiki**. 2551. In the top right corner of the page, select **Edit sidebar**. 2561. When complete, select **Save changes**. 257 258A `_sidebar` example, formatted with Markdown: 259 260```markdown 261### [Home](home) 262 263- [Hello World](hello) 264- [Foo](foo) 265- [Bar](bar) 266 267--- 268 269- [Sidebar](_sidebar) 270``` 271 272Support for displaying a generated table of contents with a custom side navigation is being considered. 273 274## Enable or disable a project wiki 275 276Wikis are enabled by default in GitLab. Project [administrators](../../permissions.md) 277can enable or disable a project wiki by following the instructions in 278[Sharing and permissions](../settings/index.md#sharing-and-permissions). 279 280Administrators for self-managed GitLab installs can 281[configure additional wiki settings](../../../administration/wikis/index.md). 282 283You can't disable [group wikis](group.md) from the GitLab user interface. 284 285## Link an external wiki 286 287To add a link to an external wiki from a project's left sidebar: 288 2891. On the top bar, select **Menu > Projects** and find your project. 2901. On the left sidebar, select **Settings > Integrations**. 2911. Select **External wiki**. 2921. Add the URL to your external wiki. 2931. Optional. To verify the connection, select **Test settings**. 2941. Select **Save changes**. 295 296You can now see the **External wiki** option from your project's 297left sidebar. 298 299When you enable this integration, the link to the external 300wiki doesn't replace the link to the internal wiki. 301To hide the internal wiki from the sidebar, [disable the project's wiki](#disable-the-projects-wiki). 302 303To hide the link to an external wiki: 304 3051. On the top bar, select **Menu > Projects** and find your project. 3061. On the left sidebar, select **Settings > Integrations**. 3071. Select **External wiki**. 3081. In the **Enable integration** section, clear the **Active** checkbox. 3091. Select **Save changes**. 310 311## Disable the project's wiki 312 313To disable a project's internal wiki: 314 3151. On the top bar, select **Menu > Projects** and find your project. 3161. Go to your project and select **Settings > General**. 3171. Expand **Visibility, project features, permissions**. 3181. Scroll down to find **Wiki** and toggle it off (in gray). 3191. Select **Save changes**. 320 321The internal wiki is now disabled, and users and project members: 322 323- Cannot find the link to the wiki from the project's sidebar. 324- Cannot add, delete, or edit wiki pages. 325- Cannot view any wiki page. 326 327Previously added wiki pages are preserved in case you 328want to re-enable the wiki. To re-enable it, repeat the process 329to disable the wiki but toggle it on (in blue). 330 331## Content Editor **(FREE)** 332 333> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5643) in GitLab 14.0. 334 335GitLab version 14.0 introduces a WYSIWYG editing experience for GitLab Flavored Markdown 336in Wikis through the [Content Editor](../../../development/fe_guide/content_editor.md). 337The Content Editor is under active development, and is not yet the default editing 338experience in the Wiki. To opt in for the new editor: 339 3401. Create a new wiki page, or edit an existing one. 3411. Ensure the wiki page uses the Markdown format. Other formats are not yet supported. 3421. Above the content field, select **Edit rich text**: 343 344 ![Use new editor button image](img/use_new_editor_button_v14.6.png) 345 346### Use the Content Editor 347 3481. [Create](#create-a-new-wiki-page) a new wiki page, or [edit](#edit-a-wiki-page) an existing one. 3491. Select **Markdown** as your format. 3501. Above **Content**, select **Edit rich text**. 3511. Customize your page's content using the various formatting options available in the content editor. 3521. Select **Create page** for a new page, or **Save changes** for an existing page: 353 354 ![Content Editor in Wikis image](img/content_editor_v14.6.png) 355 356### Switch back to the old editor 357 3581. *If you're editing the page in the content editor,* scroll to **Content**. 3591. Select **Edit source**. 360 361### GitLab Flavored Markdown support 362 363Supporting all GitLab Flavored Markdown content types in the Content Editor is a work in progress. 364For the status of the ongoing development for CommonMark and GitLab Flavored Markdown support, read: 365 366- [Basic Markdown formatting extensions](https://gitlab.com/groups/gitlab-org/-/epics/5404) epic. 367- [GitLab Flavored Markdown extensions](https://gitlab.com/groups/gitlab-org/-/epics/5438) epic. 368 369## Related topics 370 371- [Wiki settings for administrators](../../../administration/wikis/index.md) 372- [Project wikis API](../../../api/wikis.md) 373- [Group repository storage moves API](../../../api/group_repository_storage_moves.md) 374- [Group wikis API](../../../api/group_wikis.md) 375- [Wiki keyboard shortcuts](../../shortcuts.md#wiki-pages) 376