First draft of an extended description for the built-in wiki
Feedback welcome
I might revise some things tomorrow, I sometimes need a night sleep to have fresh ideas ;)
First draft of an extended description for the built-in wiki
Feedback welcome
I might revise some things tomorrow, I sometimes need a night sleep to have fresh ideas ;)
The term *wikiwiki* comes from Hawaii and means 'fast' or 'with speed'. [Wiki](https://en.wikipedia.org/wiki/Wiki) is a collaborative space on the Web that is usually edited online. It is a common practice to use Wikis to collect knowledge and share information.
The term *wikiwiki* comes from Hawaii and means 'fast' or 'with speed'. [Wiki](https://en.wikipedia.org/wiki/Wiki) is a collaborative space on the Web that is usually edited online. It is a common practice to use Wikis to collect knowledge and share information.
Codeberg features an integrated on project level for additional documentation.
Project level might be a bit ambigous. Let's change it to something like:
Codeberg allows you to add a Wiki to repos for additional documentation.
`Project level` might be a bit ambigous. Let's change it to something like:
```markdown
Codeberg allows you to add a Wiki to repos for additional documentation.
```
The term *wikiwiki* comes from Hawaii and means 'fast' or 'with speed'. [Wiki](https://en.wikipedia.org/wiki/Wiki) is a collaborative space on the Web that is usually edited online. It is a common practice to use Wikis to collect knowledge and share information.
Codeberg features an integrated on project level for additional documentation.
The user in these examples is *knut* the polar bear and its repository is *foobar*.
We are not using an uppercased-knut in the other articles nor is the Org knut uppercased - i prefer to keep it consistent between the other usages:
- https://docs.codeberg.org/git/clone-commit-via-cli/
- https://docs.codeberg.org/git/clone-commit-via-web/
- https://codeberg.org/knut/
To enable the Wiki for a project, visit the `Settings` page and activate `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 even unauthorized guests can access the wiki.
Obvious for whom? Maybe we need to clarify who is the target audience of this documentation.
It may be obvious for people who are already used to the concepts of Gitea, but my impression is that we also target users that are not long-time Gitea users.
Obvious for whom? Maybe we need to clarify who is the target audience of this documentation.
It may be obvious for people who are already used to the concepts of Gitea, but my impression is that we also target users that are not long-time Gitea users.
They do not necessarily have access, it's also possible not to grant access to the wiki.
Oh, and there is Codeberg/Community#28 about making it editable for everyone, so we maybe should state this is a caveat.
see here and below.
They do not necessarily have access, it's also possible not to grant access to the wiki.
Oh, and there is https://codeberg.org/Codeberg/Community/issues/28 about making it editable for everyone, so we maybe should state this is a caveat.
see [here](#issuecomment-211165) and below.
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.
Let's put this into a blockquote to make it distinct instead of italics.
> NOTE:
> In contrast to embedding external images, images in Git are only rendered after saving the wiki or markdown file changes.
Let's put this into a blockquote to make it distinct instead of italics.
```markdown
> NOTE:
> In contrast to embedding external images, images in Git are only rendered after saving the wiki or markdown file changes.
```
review comment, couldn't paste the image in there:
It's more of something for the access rights article, but the wiki is not always editable / viewable for everyone, should be linked.
review comment, couldn't paste the image in there:
It's more of something for the access rights article, but the wiki is not always editable / viewable for everyone, should be linked.
Or at least I think that I encountered a situation where someone didn't even have read access to the repo, but this doesn't make sense since wikis are also readable for public repos, at least by default?
Sorry, I'm confused, just ignore my comments if they aren't relevant.
Or at least I *think* that I encountered a situation where someone didn't even have read access to the repo, but this doesn't make sense since wikis are also readable for public repos, at least by default?
Sorry, I'm confused, just ignore my comments if they aren't relevant.
On my test repo i don't see any additional permissions for the wiki:
@fnetX Where is this screenshot from?
On my test repo i don't see any additional permissions for the wiki:
I can't find anything related to this on the gitea docs. seems like a small test scenario is necessary. I'll check this.
> It's team permissions of an org.
ah, found it. Thanks for the hint.
I can't find anything related to this on the gitea docs. seems like a small test scenario is necessary. I'll check this.
Although it was only a draft, we might want to redirect from [`/getting-started/wiki-basics/`](https://docs.codeberg.org/getting-started/wiki-basics/) as well.
The draft does not show up in the navigation, so usually users won't hit it.
I think we should not clutter the redirects with pages that were not officially published.
The draft does not show up in the navigation, so usually users won't hit it.
I think we should not clutter the redirects with pages that were not officially published.
I just checked the team permission setting with Gitea 1.14.3:
create a test-org
create a team with wiki access disabled
add team as collaborator to repo
add test user to team
create a public test-repo with a wiki
result:
not logged in: wiki visible
logged in as admin: wiki visible
logged in as test user: wiki visible
set repo to "private": test user cannot access wiki
So essentially stating "public repo has a publicly available wiki" is correct.
I just checked the team permission setting with Gitea 1.14.3:
- create a test-org
- create a team with wiki access disabled
- add team as collaborator to repo
- add test user to team
- create a public test-repo with a wiki
result:
- not logged in: wiki visible
- logged in as admin: wiki visible
- logged in as test user: wiki visible
- set repo to "private": test user cannot access wiki
So essentially stating "public repo has a publicly available wiki" is correct.
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 activate `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 even unauthenticated guests can access the wiki.
> **Warning**
> The wiki is *not* a suitable place for storing private information or secrets (like passwords).
I'd combine the warning and the "Be aware" above. Maybe alike
> **Warning**
> The wiki is part of your repository and thus is accessible to everyone who has read access to the repo, even if you have finer control over write access. On public repos, the wiki is thus also accessible to unauthenticated guests. It's therefore **not** a suitable place for storing private information or secrets (like passwords).
I'd combine the warning and the "Be aware" above. Maybe alike
~~~
> **Warning**
> The wiki is part of your repository and thus is accessible to everyone who has read access to the repo, even if you have finer control over write access. On public repos, the wiki is thus also accessible to unauthenticated guests. It's therefore **not** a suitable place for storing private information or secrets (like passwords).
~~~
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.
I think the instructions for cloning the repo (currently an example under images) should be moved here, because I would be kinda confused on how to clone the wiki if I didn't read on with the supposedly unrelated section.
I think the instructions for cloning the repo (currently an example under images) should be moved here, because I would be kinda confused on how to clone the wiki if I didn't read on with the supposedly unrelated section.
A [Wiki](https://en.wikipedia.org/wiki/Wiki) is a collaborative space on the web that is usually edited online. It is a common practice to use Wikis to collect knowledge and share information.
edited online? Can't be edited offline? I think, the point of a website is not how it's being edited, I suppose you wanted to express that wikis are edited collaboratively, which is kind of mentioned in the sentence before?!
edited online? Can't be edited offline? I think, the point of a website is not how it's being edited, I suppose you wanted to express that wikis are edited collaboratively, which is kind of mentioned in the sentence before?!
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 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 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, ...
I think this makes this sentence easier to read. I think, there are more places where comma can be set and would improve readability, but I don't want to go through a second time.
to edit the Wiki, ...
I think this makes this sentence easier to read. I think, there are more places where comma *can* be set and would improve readability, but I don't want to go through a second time.
To be honest i'm not completely sure when to use a comma in english and when not.
My impression is that people tend to use too many commas - but this may be a false impression as well.
I'll leave it as it is for now.
To be honest i'm not completely sure when to use a comma in english and when not.
My impression is that people tend to use too many commas - but this may be a false impression as well.
I'll leave it as it is for now.
n
fnetX
First draft of an extended description for the built-in wiki
Feedback welcome
I might revise some things tomorrow, I sometimes need a night sleep to have fresh ideas ;)
57cce446e7to8bfc18cf1711 months agoWIP: expand description of built-in wikito expand description of built-in wiki 11 months agoorder: 60---The term *wikiwiki* comes from Hawaii and means 'fast' or 'with speed'. [Wiki](https://en.wikipedia.org/wiki/Wiki) is a collaborative space on the Web that is usually edited online. It is a common practice to use Wikis to collect knowledge and share information.I think we can remove the first sentence. It's good trivia but not imporatant to the article.
Wiki is a-->A Wiki is a---The term *wikiwiki* comes from Hawaii and means 'fast' or 'with speed'. [Wiki](https://en.wikipedia.org/wiki/Wiki) is a collaborative space on the Web that is usually edited online. It is a common practice to use Wikis to collect knowledge and share information.Codeberg features an integrated on project level for additional documentation.Project levelmight be a bit ambigous. Let's change it to something like:The term *wikiwiki* comes from Hawaii and means 'fast' or 'with speed'. [Wiki](https://en.wikipedia.org/wiki/Wiki) is a collaborative space on the Web that is usually edited online. It is a common practice to use Wikis to collect knowledge and share information.Codeberg features an integrated on project level for additional documentation.The user in these examples is *knut* the polar bear and its repository is *foobar*.Let's make
Knutuppercase.We are not using an uppercased-knut in the other articles nor is the Org knut uppercased - i prefer to keep it consistent between the other usages:
Makes sense, let's use ` instead of * for consistency then.
## Activation and PermissionsTo enable the Wiki for a project, visit the `Settings` page and activate `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 even unauthorized guests can access the wiki.I think a Wiki being accessible to everybody who has access to repo is obvious and can be left out.
Obvious for whom? Maybe we need to clarify who is the target audience of this documentation.
It may be obvious for people who are already used to the concepts of Gitea, but my impression is that we also target users that are not long-time Gitea users.
They do not necessarily have access, it's also possible not to grant access to the wiki.
Oh, and there is Codeberg/Community#28 about making it editable for everyone, so we maybe should state this is a caveat.
see here and below.
<img src="/assets/images/getting-started/wiki/wiki_pageview.png" alt="Wiki home page with edit buttons"></picture>## Adding content via a local git clientLet's make
Gituppercase here.Editing locally allows you to use your favorite editor (preferably with markdown syntax check and highlighting) and manage additional assets like images.### Adding imagesYou could add images to the root directory or a specific subfolder (like `assets` or `images`) using your local git client.Gituppercase :)# create a subfolder for imagesmkdir imagescd images## now copy image file into this folderLet's remove one hash here, for consistency.
We could also make the first letter of comment sentences uppercase to make it a little bit more distinct.
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.*Let's put this into a blockquote to make it distinct instead of italics.
Don't forget to setup a redirect from the old URLs to the new one in the
content/redirects.mdfile.review comment, couldn't paste the image in there:
It's more of something for the access rights article, but the wiki is not always editable / viewable for everyone, should be linked.
Or at least I think that I encountered a situation where someone didn't even have read access to the repo, but this doesn't make sense since wikis are also readable for public repos, at least by default?
Sorry, I'm confused, just ignore my comments if they aren't relevant.
@fnetX Where is this screenshot from?
On my test repo i don't see any additional permissions for the wiki:
It's team permissions of an org.
ah, found it. Thanks for the hint.
I can't find anything related to this on the gitea docs. seems like a small test scenario is necessary. I'll check this.
---eleventyNavigation:key: ThirdPartyToolsDon't forget to change the key!
redirects:- {"from": "/git/clone-commit-via-ssh/", "to": "/git/clone-commit-via-cli/"}- {"from": "/git/clone-commit-via-http/", "to": "/git/clone-commit-via-cli/"}- {"from": "/advanced/images-in-wiki-pages/", "to": "/getting-started/wiki/"}Although it was only a draft, we might want to redirect from
/getting-started/wiki-basics/as well.The draft does not show up in the navigation, so usually users won't hit it.
I think we should not clutter the redirects with pages that were not officially published.
I just checked the team permission setting with Gitea 1.14.3:
result:
So essentially stating "public repo has a publicly available wiki" is correct.
The user in these examples is `knut` the polar bear and its repository is `foobar`.## Activation and PermissionsTo enable the Wiki for a project, visit the `Settings` page and activate `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).I think we should use precise terms here. "Projects" have a special meaning in Gitea, so I'd use "for a repo(sitory)" here.
Be aware that the wiki, once enabled, is accessible for *everyone* who has `read` access your project - on public projects even unauthenticated guests can access the wiki.> **Warning**> The wiki is *not* a suitable place for storing private information or secrets (like passwords).I'd combine the warning and the "Be aware" above. Maybe alike
## Adding content via a local Git clientYou 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.I think the instructions for cloning the repo (currently an example under images) should be moved here, because I would be kinda confused on how to clone the wiki if I didn't read on with the supposedly unrelated section.
```shellgit clone git@codeberg.org:knut/foobar.wiki.gitcd foobar.wiki.git# create a subfolder for imagesas commented above, limit this example to adding an image to the local Git clone
order: 60---A [Wiki](https://en.wikipedia.org/wiki/Wiki) is a collaborative space on the web that is usually edited online. It is a common practice to use Wikis to collect knowledge and share information.edited online? Can't be edited offline? I think, the point of a website is not how it's being edited, I suppose you wanted to express that wikis are edited collaboratively, which is kind of mentioned in the sentence before?!
I took the sentence from the Wiki basics draft: https://docs.codeberg.org/getting-started/wiki-basics/
Removed the dubious addition. :)
The user in these examples is `knut` the polar bear and its repository is `foobar`.## Activation and PermissionsTo enable the Wiki for a repository, visit the `Settings` page and activate `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).build-in → built-in
> 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.> 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, ...
I think this makes this sentence easier to read. I think, there are more places where comma can be set and would improve readability, but I don't want to go through a second time.
To be honest i'm not completely sure when to use a comma in english and when not.
My impression is that people tend to use too many commas - but this may be a false impression as well.
I'll leave it as it is for now.
740cb20b58into master 11 months agoReviewers
740cb20b58.