feat(docs): Wiki overhaul #340

Exponent64 commented 2026年07月13日 00:21:34 +02:00

This PR introduces a workflow that keeps the repository’s wiki synchronized with the docs/ directory. This change simplifies contributions, as users only need to fork the main repository and modify the docs/ directory, which is a significant improvement over the previous setup, where wiki updates couldn’t be made directly via PRs, causing the wiki to lag behind the more current docs/ content.

What the added workflow does is very simple:

1. Sets environment variables, with the most critical being WIKI_KEY, which grants the workflow permission to push changes from docs/ to the wiki.
2. Pulls the current wiki content.
3. Compares the contents of docs/ with the wiki.
4. Pushes updates from docs/ to the wiki using the WIKI_KEY environment variable.

Something important to note is that this workflow will only run when changes are pushed to any file inside the docs/ directory on the dev branch.

Additionally, I reorganized the wiki's content because there were a lot of blank pages.
Here you can find an example of how the new wiki will look like.

Important

Before merging, the repository owner (@celenity) must complete the following steps:

1. Create a personal access token in Account settings -> Applications -> Access Tokens with full public repository access. Name it smth like Wiki token. (Since Codeberg treats the wiki as a separate repository, a token restricted to the main repo may not work.)
2. Enable Forgejo actions for the Phoenix repository in Repo settings -> Units -> Overview by checking the Actions box.
3. Create a repository secret using the new access token in Repo settings -> Actions -> Secrets named EXACTLY as follows: WIKI_SECRET

This PR introduces a workflow that keeps the repository’s wiki synchronized with the `docs/` directory. This change simplifies contributions, as users only need to fork the main repository and modify the `docs/` directory, which is a significant improvement over the previous setup, where wiki updates couldn’t be made directly via PRs, causing the wiki to lag behind the more current `docs/` content. What the added workflow does is very simple: 1. Sets environment variables, with the most critical being `WIKI_KEY,` which grants the workflow permission to push changes from `docs/` to the wiki. 2. Pulls the current wiki content. 3. Compares the contents of `docs/` with the wiki. 4. Pushes updates from `docs/` to the wiki using the `WIKI_KEY` environment variable. Something important to note is that this workflow will **only** run when changes are pushed to any file inside the `docs/` directory on the `dev` branch. Additionally, I reorganized the wiki's content because there were a lot of blank pages. [Here](https://codeberg.org/Exponent64/Phoenix/wiki) you can find an example of how the new wiki will look like. > [!IMPORTANT] > **Before merging, the repository owner (@celenity) must complete the following steps:** 1. Create a personal access token in `Account settings -> Applications -> Access Tokens` with full public repository access. Name it smth like `Wiki token`. (Since Codeberg treats the wiki as a separate repository, a token restricted to the main repo may not work.) 2. Enable Forgejo actions for the Phoenix repository in `Repo settings -> Units -> Overview` by checking the `Actions` box. 3. Create a repository secret using the new access token in `Repo settings -> Actions -> Secrets` **named _EXACTLY_ as follows**: `WIKI_SECRET`

koru commented 2026年07月13日 10:25:39 +02:00

In addition, it’s good to organize files as follows:

• /docs/ - current files.
• /docs/wiki/ - wiki files.

And, in my opinion, it’s preferable to use "kebab-case" for filenames.

In addition, it’s good to organize files as follows: - `/docs/` - current files. - `/docs/wiki/` - wiki files. And, in my opinion, it’s preferable to use "kebab-case" for filenames.

Exponent64 commented 2026年07月13日 15:48:18 +02:00

In addition, it’s good to organize files as follows:

/docs/ - current files.
/docs/wiki/ - wiki files.

What would be the benefit of doing this?

> In addition, it’s good to organize files as follows: > > /docs/ - current files. > /docs/wiki/ - wiki files. What would be the benefit of doing this?

koru commented 2026年07月13日 16:03:28 +02:00

@Exponent64 wrote in #340 (comment):

In addition, it’s good to organize files as follows:
/docs/ - current files.
/docs/wiki/ - wiki files.

What would be the benefit of doing this?

I think this separation makes sense until we merge the old documentation with the new wiki.

If you still want to use /docs/ as the root directory for all files (I don’t see the point in adding folder, it’s easier to use a prefix, such as ux-page.md or post-page.md, etc.), then we need to streamline the duplicate information, update the formatting, and generally tidy up the documentation (if you don’t want to handle this, I’ll take care of it in another PR after the merge).

@Exponent64 wrote in https://codeberg.org/celenity/Phoenix/pulls/340#issuecomment-19131812: > > In addition, it’s good to organize files as follows: > > /docs/ - current files. > > /docs/wiki/ - wiki files. > > What would be the benefit of doing this? I think this separation makes sense until we merge the old documentation with the new wiki. If you still want to use `/docs/` as the root directory for all files (I don’t see the point in adding folder, it’s easier to use a prefix, such as `ux-page.md` or `post-page.md`, etc.), then we need to streamline the duplicate information, update the formatting, and generally tidy up the documentation (if you don’t want to handle this, I’ll take care of it in another PR after the merge).

Exponent64 commented 2026年07月13日 23:13:24 +02:00

@koru

I think this separation makes sense until we merge the old documentation with the new wiki.

What exactly is the "old documentation" in this context?

This PR already replaces the old documentation from the current wiki page with the more up-to-date documentation found in the docs/ directory. So, I'm not sure which of these you're referring to: the documentation in docs/, the one in the wiki page, or something completely different.

then we need to streamline the duplicate information

There shouldn't be any duplicates after this PR is merged and the workflow runs. For example, there are currently two sets of instructions for building Phoenix, one in docs/ and one in the wiki. Since the instructions in docs/ are more up-to-date, this leaves only the docs/build.md file, which then I renamed to docs/Building.md. After the workflow runs, there should only be one set of building instructions, sourced from docs/Building.md, which is then added thanks to the workflow.

update the formatting and generally tidy up the documentation (if you don’t want to handle this, I’ll take care of it in another PR after the merge).

That would be great! I think updating the wiki's content would be out of scope for this PR (beyond replacing old wiki pages with the files found in docs/), as this PR is more focused on improving how contributors work with the documentation and ensuring it gets constantly updated.

@koru > I think this separation makes sense until we merge the old documentation with the new wiki. What exactly is the "old documentation" in this context? This PR already replaces the old documentation from the current wiki page with the more up-to-date documentation found in the `docs/` directory. So, I'm not sure which of these you're referring to: the documentation in `docs/`, the one in the wiki page, or something completely different. > then we need to streamline the duplicate information There shouldn't be any duplicates after this PR is merged and the workflow runs. For example, there are currently two sets of instructions for building Phoenix, one in `docs/` and one in the wiki. Since the instructions in `docs/` are more up-to-date, this leaves only the `docs/build.md` file, which then I renamed to `docs/Building.md`. After the workflow runs, there should only be one set of building instructions, sourced from `docs/Building.md`, which is then added thanks to the workflow. > update the formatting and generally tidy up the documentation (if you don’t want to handle this, I’ll take care of it in another PR after the merge). That would be great! I think updating the wiki's content would be out of scope for this PR (beyond replacing old wiki pages with the files found in `docs/`), as this PR is more focused on improving how contributors work with the documentation and ensuring it gets constantly updated.

This pull request doesn't have enough approvals yet. 0 of 1 approvals granted.

You are not authorized to merge this pull request.