Current Situation⌗

Currently, our company’s internal documentation is relatively scattered. As a technical person, I write relevant documents in Markdown and render them with VuePress, which has a friendly UI and interaction, but there are two issues:

• The writing process is cumbersome, requiring packaging and publishing (although we use Runner and Pages services on Gitlab for packaging and deployment, which simplifies operations to some extent, and we can edit using the Web UI in the Gitlab repository, but overall it’s still not as convenient as a CMS).

• Access control is an issue. These open-source projects are inherently designed for all users, but we want to set different document permissions based on internal company roles (although we can implement a certain degree of access control through Gitlab Pages, it can only go so far and cannot achieve more granular permission control).

Besides VuePress, we’ve also used Yuque and Gitlab Wiki, resulting in quite scattered documentation. Yuque is well-developed and mature in many aspects, but it’s complicated to integrate with some of our company’s internal authentication systems, so we abandoned it after using it for a while. Then there’s Gitlab Wiki, which we’re still using to record meeting minutes, but it’s very unfriendly for searching and reading.

Discovering Wiki.js⌗

While browsing Github Trending, I discovered the Wiki.js open-source project. With an experimental mindset, I deployed a Wiki system locally using Docker Compose.

I must say, at first it felt a bit overwhelming, especially regarding navigation and document content organization. There wasn’t an intuitive UI interface for managing directories.

After several hours of research and testing, I finally figured it out and discovered that it’s quite powerful, especially in terms of access control.

Concepts⌗

Wiki.js has designed navigation with a high degree of freedom. It can be customized, and multiple visible groups can be set for each section, which I think is a great feature. This allows for setting the visibility of navigation menus based on groups. Combined with group permissions and page access rules, it can achieve permission control at any granularity.

Wiki.js makes team collaboration easier. Internal company documentation may not be maintained by a single person or department but is a top-down collaborative approach for the entire company. In Wiki.js, you can view change history, add comments, and more.

It also supports multilingual directory switching and directory structure associated with document structure. However, it must be said that this leads to a higher learning curve, which is not very friendly to newcomers, especially non-technical personnel. It requires some prerequisite knowledge, and I hope this will be optimized in version 3.*.

Operations Configuration⌗

The regular configuration of Wiki.js is relatively simple and supports multiple languages. Below, I’ll mainly introduce the management of Storage, Authentication, and User Groups.

Storage⌗

Because we have MinIO storage service internally, I directly created a bucket for Wiki.js and used MinIO as storage. However, it’s worth noting that there’s no MinIO option in the settings, but you can select S3 Generic.

After completion, you can click the Run button on the Export All panel below to upload documents to MinIO. After the export is complete, you can see the synchronization status in the lower left corner!

Note that I didn’t enable Single Bucket Endpoint because my Endpoint URI is not bound to the Bucket.

Gitlab Authentication⌗

Create a corresponding Application on Gitlab, fill in the callback URL/redirect path from the reference configuration below into the Gitlab Application’s callback address, then fill in the Client ID, Client Secret, and Base URL in Wiki.js and save. You can then log in using Gitlab.

For convenience, I enabled open registration, which means that users logging in with our internal Gitlab will automatically have account information created, avoiding the need for me to manually import them.

User Group Settings⌗

Wiki.js permissions are bound to Groups, not directly associated with users, making management more flexible.

Default Redirect After Group User Login⌗

You can set a default redirect page for group users, which helps better distinguish and guide users from different groups.

PAGE ACL Rules⌗

Through this group setting, you can achieve various granularities of permission control for pages. For example, if we want developers to only see development-related documentation, we can add a rule in the rules:

Then we place all development-related documents in the /zh/developer directory. For images or attachments, it’s also recommended to place them in the group directory to avoid having to set permissions multiple times.

Whether the Homepage Requires Authentication⌗

By default, the Guest group can access the homepage documents. If you want only logged-in users to see it, you can go to the Group settings, click on the Guests group, and switch to the PERMISSIONS tab.

Ensure that only the read:assets permission is checked.

read:assets is used to get the site LOGO and background image on the login page. If not checked, it will cause the LOGO and background on the login page to be black.

Navigation Bar Settings⌗

It’s recommended to choose a custom navigation bar, which is a static navigation menu + site tree mode. You can set visible groups through the visibility settings in the lower right.

If you want users in a certain group to be able to modify the navigation bar, you can assign permissions to the group, but remember to assign the write:groups permission, otherwise, they won’t be able to read group list information through the API.

Conclusion⌗

After completing the configuration, you can quietly write documents!!! However, this configuration process is indeed quite thoughtful, and this may just be the beginning. Later on, you will encounter some issues with personnel assignment and permission management, as well as directory division and multi-person collaboration.

I hope this is helpful, Happy hacking…