Skip to content

G
gitlab-ce
Commit c1897afe authored by Amy Qualls's avatar Amy Qualls Committed by Suzanne Selhorn
Browse files
Options

Major revisions to wiki page (part 3)

parent 12793cf6
Hide whitespace changes
Inline Side-by-side
Showing with 100 additions and 109 deletions
doc/user/project/wiki/index.md
View file @ c1897afe
...@@ -16,12 +16,27 @@ To access the wiki for a project or group, go to the page for your project or gr ...@@ -16,12 +16,27 @@ To access the wiki for a project or group, go to the page for your project or gr
and, in the left sidebar, select **Wiki**. If **Wiki** is not listed in the 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). 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:
![Wiki sidebar](img/wiki_sidebar_v13_5.png)
## Create the wiki home page ## Create the wiki home page
When a wiki is created, it is empty. On your first visit, GitLab instructs you When a wiki is created, it is empty. On your first visit, create the landing page
to create a page to serve as the landing page when a user views the wiki: users see when viewing the wiki:
1. Select a **Format** for [styling your text](#style-your-wiki-content). 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 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 1. Add a **Commit message**. Git requires a commit message, so GitLab creates one
if you don't enter one yourself. if you don't enter one yourself.
...@@ -34,34 +49,34 @@ Users with Developer [permissions](../../permissions.md) can create new wiki pag ...@@ -34,34 +49,34 @@ Users with Developer [permissions](../../permissions.md) can create new wiki pag
1. Go to the page for your project or group. 1. Go to the page for your project or group.
1. In the left sidebar, select **Wiki**. 1. In the left sidebar, select **Wiki**.
1. Select **New page** on this page, or any other wiki page. 1. Select **New page** on this page, or any other wiki page.
1. Select a [content format](#style-your-wiki-content). 1. Select a content format.
1. Add a title for your new page. You can specify a full path for the wiki page 1. Add a title for your new page. Page titles use
by using `/` in the title to indicate subdirectories. GitLab creates any missing [special characters](#special-characters-in-page-titles) for subdirectories and formatting,
subdirectories in the path. For example, a title of `docs/my-page` creates a wiki and have [length restrictions](#length-restrictions-for-file-and-directory-names).
page with a path `/wikis/docs/my-page`.
1. Add content to your wiki page. 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 1. Add a **Commit message**. Git requires a commit message, so GitLab creates one
if you don't enter one yourself. if you don't enter one yourself.
1. Select **Create page**. 1. Select **Create page**.
## Style your wiki content ### Create or edit wiki pages locally
GitLab wikis support Markdown, RDoc, AsciiDoc, and Org for content. 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
Wiki pages written in Markdown support all [Markdown features](../../markdown.md), locally, select **Clone repository** from the right-hand sidebar of any wiki page,
and also provide some [wiki-specific behavior](../../markdown.md#wiki-specific-markdown) and follow the on-screen instructions.
for links.
### Store attachments for wiki pages 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:
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33475) in GitLab 11.3. - Markdown extensions: `.mdown`, `.mkd`, `.mkdn`, `.md`, `.markdown`.
- AsciiDoc extensions: `.adoc`, `.ad`, `.asciidoc`.
When you upload a file to the wiki through the GitLab interface, the file is stored - Other markup extensions: `.textile`, `.rdoc`, `.org`, `.creole`, `.wiki`, `.mediawiki`, `.rst`.
in the wiki's Git repository. The file is available to you if you clone the
wiki repository locally.
Files uploaded to a wiki in GitLab 11.3 and earlier are stored in GitLab itself.
You must re-upload the files to add them to the wiki's Git repository.
### Special characters in page titles ### Special characters in page titles
...@@ -69,100 +84,88 @@ Wiki pages are stored as files in a Git repository, so certain characters have a ...@@ -69,100 +84,88 @@ Wiki pages are stored as files in a Git repository, so certain characters have a
- Spaces are converted into hyphens when storing a page. - Spaces are converted into hyphens when storing a page.
- Hyphens (`-`) are converted back into spaces when displaying 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 ### Length restrictions for file and directory names
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/24364) in GitLab 12.8. > - [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. 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
To avoid this situation, these limits are enforced when editing pages through the GitLab web interface and API: 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). - 245 bytes for page titles (reserving 10 bytes for the file extension).
- 255 bytes for directory names. - 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. While you can still create files locally that exceed these limits, your teammates
- It's still possible to create files and directories exceeding those limits locally through Git, but this might break on other people's machines. may not be able to check out the wiki locally afterward.
## Edit a wiki page ## Edit a wiki page
You need Developer [permissions](../../permissions.md) or higher to edit a wiki page. You need Developer [permissions](../../permissions.md) or higher to edit a wiki page:
To do so:
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. Select the edit icon (**{pencil}**).
1. Edit the content. 1. Edit the content.
1. Select **Save changes**. 1. Select **Save changes**.
### Create 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. To generate a table of contents from a wiki page's subheadings, use the `[[_TOC_]]` tag.
For an example, see [Table of contents](../../markdown.md#table-of-contents). For an example, read [Table of contents](../../markdown.md#table-of-contents).
## Delete a wiki page ## Delete a wiki page
You need Maintainer [permissions](../../permissions.md) or higher to delete a wiki page. You need Maintainer [permissions](../../permissions.md) or higher to delete a wiki page:
To do so:
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. Select **Delete page**.
1. Confirm the deletion. 1. Confirm the deletion.
## Move a wiki page ## Move a wiki page
You need Developer [permissions](../../permissions.md) or higher to move a wiki page. You need Developer [permissions](../../permissions.md) or higher to move a wiki page:
To do so:
1. Select the edit icon (**{pencil}**).
1. Add the new path to the **Title** field.
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. 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. Select the edit icon (**{pencil}**).
1. Change the **Title** from `about` to `company/about`. 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**. 1. Select **Save changes**.
## View list of all wiki pages
> - [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.
## View history of a wiki page ## View history of a wiki page
The changes of a wiki page over time are recorded in the wiki's Git repository, 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**. To view the changes for a wiki page, select **Page history**.
From the history page you can see the revision of the page (Git commit SHA), its From the history page you can see:
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.
![Wiki page history](img/wiki_page_history.png) ![Wiki page history](img/wiki_page_history.png)
- 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 ### View changes between page versions
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15242) in GitLab 13.2. > - [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 **Page history** to see all page versions.
1. Select the commit message in the **Changes** column for the version you're interested in. 1. Select the commit message in the **Changes** column for the version you're interested in.
...@@ -174,36 +177,25 @@ Similar to versioned diff file views, you can see the changes made in a given Wi ...@@ -174,36 +177,25 @@ Similar to versioned diff file views, you can see the changes made in a given Wi
> - Git events were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216014) in **GitLab 13.0.** > - 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** > - [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 GitLab tracks wiki creation, deletion, and update events. These events are displayed on the
displayed on the [user profile](../../profile/index.md#access-your-user-profile), [user profile](../../profile/index.md#access-your-user-profile),
[group](../../group/index.md#view-group-activity), [group](../../group/index.md#view-group-activity),
and [project](../working_with_projects.md#project-activity) activity pages. and [project](../working_with_projects.md#project-activity) activity pages.
## Create or edit 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`.
## Customize 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. > - [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 ```markdown
### [Home](home) ### [Home](home)
...@@ -219,18 +211,21 @@ Example for `_sidebar` (using Markdown format): ...@@ -219,18 +211,21 @@ Example for `_sidebar` (using Markdown format):
Support for displaying a generated table of contents with a custom side navigation is planned. Support for displaying a generated table of contents with a custom side navigation is planned.
## Group wikis **(PREMIUM)** ## Enable or disable a project wiki
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. 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).
Group wikis work the same way as project wikis. Their usage is similar to project wikis, with a few limitations. Administrators for self-managed GitLab installs can
[configure additional wiki settings](../../../administration/wikis/index.md).
Group wikis can be edited by members with [Developer permissions](../../permissions.md#group-members-permissions) ## Group wikis **(PREMIUM)**
and above.
You can move group wiki repositories by using the [Group repository storage moves API](../../../api/group_repository_storage_moves.md). > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5.
There are a few limitations compared to project wikis: 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. - Git LFS is not supported.
- Group wikis are not included in global search. - Group wikis are not included in global search.
...@@ -238,17 +233,13 @@ There are a few limitations compared to project wikis: ...@@ -238,17 +233,13 @@ There are a few limitations compared to project wikis:
For updates, follow [the epic that tracks feature parity with project wikis](https://gitlab.com/groups/gitlab-org/-/epics/2782). For updates, follow [the epic that tracks feature parity with project wikis](https://gitlab.com/groups/gitlab-org/-/epics/2782).
## Enable or disable a project wiki 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
Wikis are enabled by default in GitLab. Project [administrators](../../permissions.md) [Group repository storage moves API](../../../api/group_repository_storage_moves.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).
## Resources ## Resources
- [Wiki settings for administrators](../../../administration/wikis/index.md) - [Wiki settings for administrators](../../../administration/wikis/index.md)
- [Project wikis API](../../../api/wikis.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) - [Group wikis API](../../../api/group_wikis.md)
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7