expand description of built-in wiki #147

Merged
rwa merged 12 commits from wiki into master 11 months ago
rwa commented 12 months ago
Collaborator

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 ;)
rwa added 2 commits 12 months ago
rwa force-pushed wiki from 57cce446e7 to 8bfc18cf17 11 months ago
rwa added 1 commit 11 months ago
rwa added 1 commit 11 months ago
rwa changed title from WIP: expand description of built-in wiki to expand description of built-in wiki 11 months ago
rwa added the
Kind: Documentation
label 11 months ago
n requested changes 11 months ago
order: 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.
n commented 11 months ago
Collaborator

I think we can remove the first sentence. It's good trivia but not imporatant to the article.

I think we can remove the first sentence. It's good trivia but not imporatant to the article.
n commented 11 months ago
Collaborator

Wiki is a --> A Wiki is a

`Wiki is a` --> `A Wiki is a`
rwa marked this conversation as resolved
---
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.
n commented 11 months ago
Collaborator

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. ```
rwa marked this conversation as resolved
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*.
n commented 11 months ago
Collaborator

Let's make Knut uppercase.

Let's make `Knut` uppercase.
rwa commented 11 months ago
Poster
Collaborator

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:

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/
n commented 11 months ago
Collaborator

Makes sense, let's use ` instead of * for consistency then.

Makes sense, let's use ` instead of * for consistency then.
rwa marked this conversation as resolved
## 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 unauthorized guests can access the wiki.
n commented 11 months ago
Collaborator

I think a Wiki being accessible to everybody who has access to repo is obvious and can be left out.

I think a Wiki being accessible to everybody who has access to repo is obvious and can be left out.
rwa commented 11 months ago
Poster
Collaborator

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.
Collaborator

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.
rwa marked this conversation as resolved
<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
n commented 11 months ago
Collaborator

Let's make Git uppercase here.

Let's make `Git` uppercase here.
rwa marked this conversation as resolved
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.
n commented 11 months ago
Collaborator

Git uppercase :)

`Git` uppercase :)
rwa marked this conversation as resolved
# create a subfolder for images
mkdir images
cd images
## now copy image file into this folder
n commented 11 months ago
Collaborator

Let's remove one hash here, for consistency.

Let's remove one hash here, for consistency.
n commented 11 months ago
Collaborator

We could also make the first letter of comment sentences uppercase to make it a little bit more distinct.

We could also make the first letter of comment sentences uppercase to make it a little bit more distinct.
rwa marked this conversation as resolved
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.*
n commented 11 months ago
Collaborator

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. ```
rwa marked this conversation as resolved
n added 1 commit 11 months ago
n commented 11 months ago
Collaborator

Don't forget to setup a redirect from the old URLs to the new one in the content/redirects.md file.

Don't forget to setup a redirect from the old URLs to the new one in the `content/redirects.md` file.
Collaborator

review comment, couldn't paste the image in there:
image
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: ![image](/attachments/19b000c8-8ec4-4a13-b3c3-610e190eaba5) It's more of something for the access rights article, but the wiki is not always editable / viewable for everyone, should be linked.
Collaborator

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.
rwa added 2 commits 11 months ago
Poster
Collaborator

@fnetX Where is this screenshot from?

On my test repo i don't see any additional permissions for the wiki:
image

@fnetX Where is this screenshot from? On my test repo i don't see any additional permissions for the wiki: ![image](/attachments/2ec6e237-7e85-4da6-9b1e-1e0e671d9fa2)
Collaborator

It's team permissions of an org.

It's team permissions of an org.
Poster
Collaborator

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.

> 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.
n reviewed 11 months ago
---
eleventyNavigation:
key: ThirdPartyTools
n commented 11 months ago
Collaborator

Don't forget to change the key!

Don't forget to change the key!
rwa marked this conversation as resolved
n reviewed 11 months ago
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/"}
n commented 11 months ago
Collaborator

Although it was only a draft, we might want to redirect from /getting-started/wiki-basics/ as well.

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.
rwa commented 11 months ago
Poster
Collaborator

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.
n marked this conversation as resolved
Poster
Collaborator

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.
rwa added 1 commit 11 months ago
rwa requested review from n 11 months ago
fnetX requested changes 11 months ago
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).
Collaborator

I think we should use precise terms here. "Projects" have a special meaning in Gitea, so I'd use "for a repo(sitory)" here.

I think we should use precise terms here. "Projects" have a special meaning in Gitea, so I'd use "for a repo(sitory)" here.
rwa marked this conversation as resolved
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).
Collaborator

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). ~~~
rwa marked this conversation as resolved
## 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.
Collaborator

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.
rwa marked this conversation as resolved
```shell
git clone git@codeberg.org:knut/foobar.wiki.git
cd foobar.wiki.git
# create a subfolder for images
Collaborator

as commented above, limit this example to adding an image to the local Git clone

as commented above, limit this example to adding an image to the local Git clone
rwa marked this conversation as resolved
rwa added 1 commit 11 months ago
ed179df4ef
use "repository" instead of "project"
n added 1 commit 11 months ago
rwa requested review from fnetX 11 months ago
fnetX reviewed 11 months ago
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.
Collaborator

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?!
rwa commented 11 months ago
Poster
Collaborator

I took the sentence from the Wiki basics draft: https://docs.codeberg.org/getting-started/wiki-basics/

Removed the dubious addition. :)

I took the sentence from the Wiki basics draft: https://docs.codeberg.org/getting-started/wiki-basics/ Removed the dubious addition. :)
rwa marked this conversation as resolved
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).
Collaborator

build-in → built-in

build-in → built-in
rwa marked this conversation as resolved
> 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.
Collaborator

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.
rwa commented 11 months ago
Poster
Collaborator

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.
rwa added 1 commit 11 months ago
rwa merged commit 740cb20b58 into master 11 months ago

Reviewers

n was requested for review 11 months ago
fnetX was requested for review 11 months ago
The pull request has been merged as 740cb20b58.
Sign in to join this conversation.
No reviewers
No Milestone
No Assignees
3 Participants
Notifications
Due Date

No due date set.

Dependencies

This pull request currently doesn't have any dependencies.

Loading…
There is no content yet.