diff options
Diffstat (limited to 'doc/user/project/wiki/index.md')
| -rw-r--r-- | doc/user/project/wiki/index.md | 337 |
1 files changed, 199 insertions, 138 deletions
diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index eb8270b8740..a69141ac04d 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -7,68 +7,76 @@ type: reference, how-to # Wiki **(FREE)** -A separate system for documentation called Wiki, is built right into each -GitLab project. It is enabled by default on all new projects and you can find -it under **Wiki** in your project. +If you don't want to keep your documentation in your repository, but you do want +to keep it in the same project as your code, you can use the wiki GitLab provides +in each GitLab project. Every wiki is a separate Git repository, so you can create +wiki pages in the web interface, or [locally using Git](#create-or-edit-wiki-pages-locally). + +To access the wiki for a project or group, go to the page for your project or group +and, in the left sidebar, select **Wiki**. If **Wiki** is not listed in the +left sidebar, a project administrator has [disabled it](#enable-or-disable-a-project-wiki). + +GitLab wikis support Markdown, RDoc, AsciiDoc, and Org for content. +Wiki pages written in Markdown support all [Markdown features](../../markdown.md), +and also provide some [wiki-specific behavior](../../markdown.md#wiki-specific-markdown) +for links. + +In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/17673/), +wiki pages display a sidebar, which you [can customize](#customize-sidebar). This +sidebar contains a partial list of pages in the wiki, displayed as a nested tree, +with sibling pages listed in alphabetical order. To view a list of all pages, select +**View All Pages** in the sidebar: -Wikis are very convenient if you don't want to keep your documentation in your -repository, but you do want to keep it in the same project where your code -resides. - -You can create Wiki pages in the web interface or -[locally using Git](#adding-and-editing-wiki-pages-locally) since every Wiki is -a separate Git repository. - -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5, -**group wikis** became available. Their usage is similar to project wikis, with a few [limitations](../../group/index.md#group-wikis). - -## First time creating the Home page - -The first time you visit a Wiki, you are directed to create the Home page. -The Home page is necessary to be created because it serves as the landing page -when viewing a Wiki. Complete the **Content** section, and then select -**Create page**. You can always edit it later, so go ahead and write a welcome -message. - - - -## Creating a new wiki page - -NOTE: -Requires Developer [permissions](../../permissions.md). - -Create a new page by selecting the **New page** button that can be found -in all wiki pages. - -Enter a title for your new wiki page. - -You can specify a full path for the wiki page by using '/' in the -title to indicate subdirectories. Any missing directories are created -automatically. For example, a title of `docs/my-page` creates a wiki -page with a path `/wikis/docs/my-page`. - -After you enter the page name, it's time to fill in its content. GitLab wikis -support Markdown, RDoc, AsciiDoc, and Org. For Markdown based pages, all the -[Markdown features](../../markdown.md) are supported and for links there is -some [wiki specific](../../markdown.md#wiki-specific-markdown) behavior. - -In the web interface the commit message is optional, but the GitLab Wiki is -based on Git and needs a commit message, so one is created for you if you -don't enter one. - -When you're ready, select **Create page** and the new page is created. - - - -### Attachment storage + -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33475) in GitLab 11.3. +## Create the wiki home page + +When a wiki is created, it is empty. On your first visit, create the landing page +users see when viewing the wiki: + +1. Go to the page for your project or group. +1. In the left sidebar, select **Wiki**, then **Create your first page**. +1. Select a **Format** for styling your text. +1. Add a welcome message in the **Content** section. You can always edit it later. +1. Add a **Commit message**. Git requires a commit message, so GitLab creates one + if you don't enter one yourself. +1. Select **Create page**. + +## Create a new wiki page + +Users with Developer [permissions](../../permissions.md) can create new wiki pages: + +1. Go to the page for your project or group. +1. In the left sidebar, select **Wiki**. +1. Select **New page** on this page, or any other wiki page. +1. Select a content format. +1. Add a title for your new page. Page titles use + [special characters](#special-characters-in-page-titles) for subdirectories and formatting, + and have [length restrictions](#length-restrictions-for-file-and-directory-names). +1. Add content to your wiki page. +1. (Optional) Attach a file, and GitLab stores it according to your installed version of GitLab: + - *Files added in [GitLab 11.3 and later](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33475):* + Files are stored in the wiki's Git repository. + - *Files added GitLab 11.2 and earlier:* Files are stored in GitLab itself. To add + the file to the wiki's Git repository, you must re-upload the file. +1. Add a **Commit message**. Git requires a commit message, so GitLab creates one + if you don't enter one yourself. +1. Select **Create page**. + +### Create or edit wiki pages locally + +Wikis are based on Git repositories, so you can clone them locally and edit +them like you would do with every other Git repository. To clone a wiki repository +locally, select **Clone repository** from the right-hand sidebar of any wiki page, +and follow the on-screen instructions. + +Files you add to your wiki locally must use one of the following +supported extensions, depending on the markup language you wish to use. +Files with unsupported extensions don't display when pushed to GitLab: -Any file uploaded to the wiki with the GitLab -interface is stored in the wiki Git repository, and is available -if you clone the wiki repository locally. All uploaded files prior to GitLab -11.3 are stored in GitLab itself. If you want them to be part of the wiki's Git -repository, you must upload them again. +- Markdown extensions: `.mdown`, `.mkd`, `.mkdn`, `.md`, `.markdown`. +- AsciiDoc extensions: `.adoc`, `.ad`, `.asciidoc`. +- Other markup extensions: `.textile`, `.rdoc`, `.org`, `.creole`, `.wiki`, `.mediawiki`, `.rst`. ### Special characters in page titles @@ -76,141 +84,118 @@ Wiki pages are stored as files in a Git repository, so certain characters have a - Spaces are converted into hyphens when storing a page. - Hyphens (`-`) are converted back into spaces when displaying a page. -- Slashes (`/`) can't be used, because they're used as path separator. +- Slashes (`/`) are used as path separators, and can't be displayed in titles. If you + create a title containing `/` characters, GitLab creates all the subdirectories + needed to build that path. For example, a title of `docs/my-page` creates a wiki + page with a path `/wikis/docs/my-page`. ### Length restrictions for file and directory names > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/24364) in GitLab 12.8. -Many common file systems have a [limit of 255 bytes for file and directory names](https://en.wikipedia.org/wiki/Comparison_of_file_systems#Limits), and while Git and GitLab both support paths exceeding those limits, the presence of them makes it impossible for users on those file systems to checkout a wiki repository locally. - -To avoid this situation, these limits are enforced when editing pages through the GitLab web interface and API: +Many common file systems have a [limit of 255 bytes](https://en.wikipedia.org/wiki/Comparison_of_file_systems#Limits) +for file and directory names. Git and GitLab both support paths exceeding +those limits. However, if your file system enforces these limits, you cannot check out a +local copy of a wiki that contains filenames exceeding this limit. To prevent this +problem, the GitLab web interface and API enforce these limits: - 245 bytes for page titles (reserving 10 bytes for the file extension). - 255 bytes for directory names. -Please note that: +Non-ASCII characters take up more than one byte. -- Non-ASCII characters take up more than one byte. -- It's still possible to create files and directories exceeding those limits locally through Git, but this might break on other people's machines. +While you can still create files locally that exceed these limits, your teammates +may not be able to check out the wiki locally afterward. -## Editing a wiki page +## Edit a wiki page -You need Developer [permissions](../../permissions.md) or higher to edit a wiki page. -To do so: +You need Developer [permissions](../../permissions.md) or higher to edit a wiki page: +1. Go to the page for your project or group. +1. In the left sidebar, select **Wiki**, and go to the page you want to edit. 1. Select the edit icon (**{pencil}**). 1. Edit the content. 1. Select **Save changes**. -### Adding a table of contents +### Create a table of contents -To generate a table of contents from the headings in a Wiki page, use the `[[_TOC_]]` tag. -For an example, see [Table of contents](../../markdown.md#table-of-contents). +To generate a table of contents from a wiki page's subheadings, use the `[[_TOC_]]` tag. +For an example, read [Table of contents](../../markdown.md#table-of-contents). -## Deleting a wiki page +## Delete a wiki page -You need Maintainer [permissions](../../permissions.md) or higher to delete a wiki page. -To do so: +You need Maintainer [permissions](../../permissions.md) or higher to delete a wiki page: -1. Open the page you want to delete. +1. Go to the page for your project or group. +1. In the left sidebar, select **Wiki**, and go to the page you want to delete. 1. Select **Delete page**. 1. Confirm the deletion. -## Moving a wiki page +## Move a wiki page -You need Developer [permissions](../../permissions.md) or higher to move a wiki page. -To do so: +You need Developer [permissions](../../permissions.md) or higher to move a wiki page: +1. Go to the page for your project or group. +1. In the left sidebar, select **Wiki**, and go to the page you want to move. 1. Select the edit icon (**{pencil}**). -1. Add the new path to the **Title** field. +1. Add the new path to the **Title** field. For example, if you have a wiki page + called `about` under `company` and you want to move it to the wiki's root, + change the **Title** from `about` to `/about`. 1. Select **Save changes**. -For example, if you have a wiki page called `about` under `company` and you want to -move it to the wiki's root: - -1. Select the edit icon (**{pencil}**). -1. Change the **Title** from `about` to `/about`. -1. Select **Save changes**. - -If you want to do the opposite: - -1. Select the edit icon (**{pencil}**). -1. Change the **Title** from `about` to `company/about`. -1. Select **Save changes**. +## View history of a wiki page -## Viewing a list of all created wiki pages +The changes of a wiki page over time are recorded in the wiki's Git repository. +To view the changes for a wiki page, select **Page history**. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17673/) in GitLab 13.5, wiki pages are displayed as a nested tree in the sidebar and pages overview. - -Every wiki has a sidebar from which a short list of the created pages can be -found. The list is ordered alphabetically. - - - -If you have many pages, not all are listed in the sidebar. Select -**View All Pages** to see all of them. - -## Viewing the history of a wiki page - -The changes of a wiki page over time are recorded in the wiki's Git repository, -and you can view them by selecting **Page history**. - -From the history page you can see the revision of the page (Git commit SHA), its -author, the commit message, and when it was last updated. -To see how a previous version of the page looked like, select a revision -number in the **Page version** column. +From the history page you can see:  -### Viewing the changes between page versions +- The revision (Git commit SHA) of the page. +- The page author. +- The commit message. +- The last update. +- Previous revisions, by selecting a revision number in the **Page version** column. + +### View changes between page versions > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15242) in GitLab 13.2. -Similar to versioned diff file views, you can see the changes made in a given Wiki page version: +You can see the changes made in a version of a wiki page, similar to versioned diff file views: -1. Navigate to the Wiki page you're interested in. +1. Go to the page for your project or group. +1. In the left sidebar, select **Wiki**, and go to the wiki page you're interested in. 1. Select **Page history** to see all page versions. 1. Select the commit message in the **Changes** column for the version you're interested in.  -## Wiki activity records +## Track wiki events > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14902) in **GitLab 12.10.** > - Git events were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216014) in **GitLab 13.0.** > - [Feature flag for Git events was removed](https://gitlab.com/gitlab-org/gitlab/-/issues/258665) in **GitLab 13.5** -Wiki events (creation, deletion, and updates) are tracked by GitLab and -displayed on the [user profile](../../profile/index.md#access-your-user-profile), +GitLab tracks wiki creation, deletion, and update events. These events are displayed on the +[user profile](../../profile/index.md#access-your-user-profile), [group](../../group/index.md#view-group-activity), and [project](../working_with_projects.md#project-activity) activity pages. -## Adding and editing wiki pages locally - -Since wikis are based on Git repositories, you can clone them locally and edit -them like you would do with every other Git repository. - -In the right sidebar, select **Clone repository** and follow the on-screen -instructions. - -Files that you add to your wiki locally must have one of the following -supported extensions, depending on the markup language you wish to use, -otherwise they don't display when pushed to GitLab: - -- Markdown extensions: `.mdown`, `.mkd`, `.mkdn`, `.md`, `.markdown`. -- AsciiDoc extensions: `.adoc`, `.ad`, `.asciidoc`. -- Other markup extensions: `.textile`, `.rdoc`, `.org`, `.creole`, `.wiki`, `.mediawiki`, `.rst`. - -## Customizing sidebar +## Customize sidebar > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23109) in GitLab 13.8, the sidebar can be customized by selecting the **Edit sidebar** button. -To customize the Wiki's navigation sidebar, you need Developer permissions to the project. +You need Developer [permissions](../../permissions.md) or higher to customize the wiki +navigation sidebar. This process creates a wiki page named `_sidebar` which fully +replaces the default sidebar navigation: -In the top-right, select **Edit sidebar** and make your changes. This creates a wiki page named `_sidebar` which fully replaces the default sidebar navigation. +1. Go to the page for your project or group. +1. In the left sidebar, select **Wiki**. +1. In the top right corner of the page, select **Edit sidebar**. +1. When complete, select **Save changes**. -Example for `_sidebar` (using Markdown format): +A `_sidebar` example, formatted with Markdown: ```markdown ### [Home](home) @@ -225,3 +210,79 @@ Example for `_sidebar` (using Markdown format): ``` Support for displaying a generated table of contents with a custom side navigation is planned. + +## Enable or disable a project wiki + +Wikis are enabled by default in GitLab. Project [administrators](../../permissions.md) +can enable or disable the project wiki by following the instructions in +[Sharing and permissions](../settings/index.md#sharing-and-permissions). + +Administrators for self-managed GitLab installs can +[configure additional wiki settings](../../../administration/wikis/index.md). + +## Group wikis **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. + +Group wikis work the same way as project wikis. Their usage is similar to project +wikis, with a few limitations: + +- Git LFS is not supported. +- Group wikis are not included in global search. +- Changes to group wikis don't show up in the group's activity feed. + +For updates, follow [the epic that tracks feature parity with project wikis](https://gitlab.com/groups/gitlab-org/-/epics/2782). + +Group wikis can be edited by members with [Developer permissions](../../permissions.md#group-members-permissions) +and above. Group wiki repositories can be moved using the +[Group repository storage moves API](../../../api/group_repository_storage_moves.md). + +## Link an external wiki + +To add a link to an external wiki from a project's left sidebar: + +1. In your project, go to **Settings > Integrations**. +1. Select **External wiki**. +1. Add the URL to your external wiki. +1. (Optional) Select **Test settings** to verify the connection. +1. Select **Save changes**. + +You can now see the **External wiki** option from your project's +left sidebar. + +When you enable this integration, the link to the external +wiki won't replace the link to the internal wiki. +To hide the internal wiki from the sidebar, [disable the project's wiki](#disable-the-projects-wiki). + +To hide the link to an external wiki: + +1. In your project, go to **Settings > Integrations**. +1. Select **External wiki**. +1. Unselect **Enable integration**. +1. Select **Save changes**. + +## Disable the project's wiki + +To disable a project's internal wiki: + +1. In your project, go to **Settings > General**. +1. Expand **Visibility, project features, permissions**. +1. Scroll down to find **Wiki** and toggle it off (in gray). +1. Select **Save changes**. + +The internal wiki is now disabled, and users and project members: + +- Cannot find the link to the wiki from the project's sidebar. +- Cannot add, delete, or edit wiki pages. +- Cannot view any wiki page. + +Previously added wiki pages are preserved in case you +want to re-enable the wiki. To re-enable it, repeat the process +to disable the wiki but toggle it on (in blue). + +## Resources + +- [Wiki settings for administrators](../../../administration/wikis/index.md) +- [Project wikis API](../../../api/wikis.md) +- [Group repository storage moves API](../../../api/group_repository_storage_moves.md) +- [Group wikis API](../../../api/group_wikis.md) |