Documentation/content/advanced/wiki.md

---
eleventyNavigation:
  key: ThirdPartyTools
  title: integrated Wiki
  parent: AdvancedUsage
---

Codeberg features an integrated [Wiki](https://en.wikipedia.org/wiki/Wiki) on project level for additional documentation.

The user in these examples is *knut* the polar bear and its repository is *foobar*.

## Activation and Permissions
To enable the Wiki for a project, visit the `Settings` page and set `Enable Repository Wiki` in the `Advanced Section`. It will default to the build-in wiki which is described here, but you can as well add an URI to an external site the "Wiki" tab should link to (not part of this doc).

Be aware that the wiki, once enabled, is accessible for everyone who has `read` access your project - on public projects this would be everybody. It is **not** suitable for storing secrets (like passwords and so on).

To edit the Wiki `write` permission to the project is required.

## Wiki structure 
The Wiki is essentially a separate Git repo in your project with a predefined name. It should consist of [Markdown](https://en.wikipedia.org/wiki/Markdown) files and additional assets like images. No further style sheets are needed. The markdown files are automatically rendered according to the selected Codeberg theme.

The name of the Wiki of a project is fixed as `<project-name>.wiki.git`. The markdown files should use the extension `.md`.

## Adding content via web 
After you have enabled the Wiki you are asked to create the initial page `Home.md`.

Using the web UI in your browser is currently limited to add/update/delete pages, you can not manage assets like images this way.

![Wiki home page with edit buttons](assets/images/advanced/wiki/wiki_pageview.png "View of Wiki Home page with edit buttons")

## Adding content via a local git client
You can work with the Wiki repo as with any other Git repo on Codeberg, see our docs about managing a Git repo [via CLI](https://docs.codeberg.org/git/clone-commit-via-cli).

Editing locally allows you to use your favorite editor (preferably with markdown syntax check and highlighting) and manage additional assets like images.

### Adding images
You could add images to the root directory or a specific subfolder (like `assets` or `images`) using your local git client.

A feasible workflow might look like this (replace `<user>` and `<project>` with your user and project name):

```shell
git clone git@codeberg.org:knut/foobar.wiki.git
cd foobar.wiki.git
# create a subfolder for images
mkdir images
cd images
## now copy image file into this folder
git add images/image.png
git commit -m "add image"
git push
```

Now, you can reference the image in Markdown, like this:

```markdown
![image alt text](images/image.png "image title")
```

After saving your changes, the image should be visible.

*NOTE: In contrast to embedding external images, images in Git are only rendered after saving the wiki or markdown file changes.*