summaryrefslogtreecommitdiff
path: root/doc/user/project/wiki/index.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/user/project/wiki/index.md')
-rw-r--r--doc/user/project/wiki/index.md337
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.
-
-![New home page](img/wiki_create_home_page.png)
-
-## 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.
-
-![New page](img/wiki_create_new_page.png)
-
-### Attachment storage
+![Wiki sidebar](img/wiki_sidebar_v13_5.png)
-> - [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.
-
-![Wiki sidebar](img/wiki_sidebar_v13_5.png)
-
-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:
![Wiki page history](img/wiki_page_history.png)
-### 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 page changes](img/wiki_page_diffs_v13_2.png)
-## 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)