h759bkyo4/Documentation
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

Fix getting-started/wiki.md

Browse source
This commit is contained in:
Jeremy 2022-07-05 19:12:58 +12:00 committed by Gitea
parent 641b525087
commit d6e691468e
1 changed files with 19 additions and 19 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

38
content/getting-started/wiki.md
View file

@ -6,49 +6,49 @@ eleventyNavigation:
order: 60
---
A [Wiki](https://en.wikipedia.org/wiki/Wiki) is a collaborative space on the web. It is a common practice to use Wikis to collect knowledge and share information.
Codeberg allows you to add a Wiki to a repo for additional documentation.
A [wiki](https://en.wikipedia.org/wiki/Wiki) is a collaborative space on the web. It is a common practice to use wikis to collect knowledge and share information.
Codeberg allows you to add a wiki to a repo for additional documentation.
The user in these examples is `knut` the polar bear and its repository is `foobar`.
The user in these examples is `knut`, the polar bear and its repository is `foobar`.
## Activation and Permissions
To enable the Wiki for a repository, visit the `Settings` page and activate `Enable Repository Wiki` in the `Advanced Section`. It will default to the built-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).
To enable the wiki for a repository, visit the `Settings` page and activate `Enable Repository Wiki` in the `Advanced Section`. It will default to the built-in wiki which is described here, but you can add an URI to an external site the "Wiki" tab should link to.
> **Warning**
> Be aware that the wiki, once enabled, is accessible for *everyone* who has `read` access your repository - on public repositories even unauthenticated guests can access the wiki.
> Be aware that the wiki, once enabled, is accessible for *everyone* who has `read` access to your repository - on public repositories even unauthenticated guests can access the wiki.
> The wiki is *not* a suitable place for storing private information or secrets (like passwords).
To edit the Wiki `write` permission to the repository is required.
To edit the wiki `write` permission to the repository is required.
## Wiki structure
The Wiki is essentially a separate Git repo in your repository with a predefined name in the form of `<your-repository-name>.wiki.git`.
The wiki is essentially a separate Git repo in your repository with a predefined name in the form of `<your-repository-name>.wiki.git`.
It consists of [Markdown](https://en.wikipedia.org/wiki/Markdown) files (file extension `.md`) and additional assets like images.
No further style sheets are needed. The markdown files are automatically rendered according to the selected Codeberg theme.
No further stylesheets are needed. The Markdown files are automatically rendered according to the selected Codeberg theme.
## Adding content via web
After you have enabled the Wiki you are asked to create the initial page `Home.md`.
After you have enabled the wiki you are prompted 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.
The web UI in your browser is currently limited to adding, updating, and deleting pages; you can't manage assets like images this way.
<picture>
<source srcset="/assets/images/getting-started/wiki/wiki_pageview.png" type="image/png">
<img src="/assets/images/getting-started/wiki/wiki_pageview.png" alt="Wiki home page with edit buttons">
</picture>
## 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).
You can work with the wiki repo as you would 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).
```shell
git clone git@codeberg.org:knut/foobar.wiki.git
cd foobar.wiki
nano Home.md
nano Home.md # or your editor of choice
git commit -am "create Home page"
```
Editing locally allows you to use your favorite editor (preferably with markdown syntax check and highlighting) and manage additional assets like images.
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.
You can 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:
@ -56,7 +56,7 @@ A feasible workflow might look like this:
# create a subfolder for images
mkdir images
cd images
# copy the image file into this folder
# copy the image into this folder
git add images/image.png
git commit -m "add image"
git push
@ -70,13 +70,13 @@ Now, you can reference the image in Markdown, like this:
After saving your changes, the image should be visible.
> In contrast to embedding external images, images in Git are only rendered after saving the wiki or markdown file changes.
> In contrast to embedding external images, images in Git are only rendered after saving the wiki or Markdown file changes.
## Adding a sidebar and a footer
To enhance the usability of your wiki you can add a custom sidebar and a footer that are shown on every page. The sidebar will be displayed to the right of the main content and the footer below.
To enable the sidebar, just add a filed named `_Sidebar.md` to your wiki. For a footer the file must be named `_Footer.md`.
Both file types allow common markdown syntax to adjust the presentation to your needs.
To enable the sidebar, just add a file named `_Sidebar.md` to your wiki. For a footer the file must be named `_Footer.md`.
Both file types allow common Markdown syntax to adjust the presentation to your needs.
Very basic example for a sidebar:
```markdown
@ -88,5 +88,5 @@ Very basic example for a sidebar:
> knuts wiki
```
> To edit these special files in the Web UI you need to manually browse to the files, e.g. for our user *knut* and his *foobar* repo:
> These files starting with `_` are hidden, so in the web UI you need to manually browse for the files. E.g. for our user *knut* and his *foobar* repo:
> `https://codeberg.org/knut/foobar/wiki/_Sidebar`