mic92/nixos-wiki-infra

This project contains the setup of https://wiki.nixos.org

nixos-wiki-infra

This project contains the setup of the official NixOS Wiki (wiki.nixos.org).

Additionally, this project's GitHub Issues host a space for coordination and discussion of wiki activities, in tandem with the Matrix channel #wiki:nixos.org.

Examples

Checkout ./targets/nixos-wiki.nixos.org for an example terraform deployment on hetzner cloud.

Downloading a dump of the wiki

This is useful if you want to run your own instance. Every day an XML dump is updated here:

https://wiki.nixos.org/wikidump.xml.zst

Restoring from a backup (wiki admins only)

$ systemctl stop phpfpm-mediawiki.service
$ borg-job-wiki list
$ borg-job-wiki mount [email protected]:wiki.nixos.org/repo::wiki-wiki-2024-04-01T12:40:37 /tmp/restore
$ ls -la /tmp/restore/var/lib/mediawiki/backup/
$ sudo dropdb db
$ sudo -u postgres dropdb mediawiki
$ systemctl restart postgresql.service
$ sudo -u postgres pg_restore -d mediawiki < /tmp/restore/var/lib/mediawiki/backup/db
$ systemctl start phpfpm-mediawiki.service
$ ls -la /tmp/restore/var/lib/mediawiki-uploads/
$ umount /tmp/restore/

FAQ:

When logging in with "GitHub auth", the app shows "Act on your behalf" as a permission.

We created the Oauth app with read-only access and minimal permissions:

Unfortunately, GitHub misrepresents this information. Read more about this issue here: https://github.com/orgs/community/discussions/37117

Roles

Various roles are present on the wiki:

• Bureaucrats can assign roles to others. (members, permissions)
• Administrators can perform almost all restricted actions. (members, permissions)
• Moderators can perform a limited subset of restricted actions. (members, permissions)
• Trusted users can perform page deletions. (members, permissions)

nixos-wiki-infra's Issues

MediaWiki:*.css read-only [to me]

• https://wiki.nixos.org/wiki/MediaWiki:Common.css

Even though I'm in those groups:

Member of groups: Administrators, Autoconfirmed users, Bureaucrats, Users

I suppose it could be a configuration value.

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Errored

These updates encountered an error and will be retried. Click on a checkbox below to force a retry now.

• chore(deps): lock file maintenance

Detected dependencies

github-actions

.github/workflows/update-extensions.yml

• actions/checkout v4
• cachix/install-nix-action v27
• peter-evans/create-pull-request v6

nix

flake.nix

• nixpkgs nixos-unstable-small

terraform

targets/admins/terraform.tf

targets/nixos-wiki.nixos.org/terraform.tf

terraform/admins/providers.tf

terraform/nixos-wiki/main.tf

terraform/nixos-wiki/providers.tf

---

• Check this box to trigger a request for Renovate to run again on this repository

Linking

Feature

I think it would be very neat to have the ability to declare a given article is about a specific package (or packages) in Nixpkgs. This would improve clarity of the wiki article, and it would facilitate integration with search.nixos.org. Besides Source and Homepage, there could be a link to an article about a package, if there is one on the wiki. This would make it much easier to learn the differences between versions of packages. For example, for the Julia language has the following versions of packages:

julia
julia-bin
julia-lts
julia_18
julia_18-bin

All these point to the same home page. You might think the difference between all these packages is immediately obvious from the names, but there is a more detailed description on the wiki. It would be neat to immediately see that a wiki article exists about these packages.

Approach

There are two fundamental approaches: marking the relationship in meta attribute of each package (like homepage) or marking it in the wiki.

The easier way to implement this feature would be to add a meta attribute to the packages. Then, displaying it in the search results would be as easy as displaying the other links in meta. But I think this approach has some disadvantages. Nixpkgs is already responsible for a lot. Changing the wiki links will would be slow, especially for people on stable. Changing the wiki is much simpler than merging a pull request to Nixpkgs. Furthermore, you would likely mention the relationship on the wiki too, which means you repeat yourself and split the source of truth.

If the relationship is marked in the wiki (with some kind of a tag), you would then query the wiki for all articles related to each packages. After getting the response of the search from the backed, the extract the package_attr_name and query the wiki for articles about the packages you are displaying. It would be trivial if you wanted to query the packages one by one, but I would have to make more research into how exactly we could get the wiki links for all the packages with one request..

[email protected] email not reachable

I was trying to send an email to the admins at [email protected] but the email was not deliverable.

This is the email address shown on the main page:

This is the mail system at host mout-p-102.mailbox.org.

I'm sorry to have to inform you that your message could not
be delivered to one or more recipients. It's attached below.

For further assistance, please send mail to postmaster.

If you do so, please include this problem report. You can
delete your own text from the attached returned message.

                   The mail system

<[[email protected]](mailto:[email protected])>: host mx2.improvmx.com[2a05:d012:412:e202:e81e:cc44:3b53:8a3d]
    said: 550 5.1.1 The email account that you tried to reach does not exist.
    Please try double-checking the recipient's email address for typos or
    unnecessary spaces. - ImprovMX (in reply to RCPT TO command)

Nixvim documentation page request

Comment

Nix vim is a nice to configure vim it is based on NeoVim but the only documentation is here it allows you to configure vim using nix. So whats so special about?? It special since you don't need to have a separate config for vim in Lua rather you can just use nix. You can use Lua for plugins but It set your vim up for Nix/NixOS. Since the wiki just came out it would be cool to include something that use nix.

Links to help-out:

• https://nix-community.github.io/nixvim/
• https://github.com/nix-community/nixvim

Documentation for `trusted`, `moderator`, `Administrator`, and `Bureaucrat` groups?

Looking at Special:ListGroupRights, I see a number of groups, some of which appear to be in active use. Where can documentation for them be found? Are there material criteria for these roles?

Tangentially related: Is the moderator group for people who are part of the NixOS moderation team? If so, we should document that here, as well as document it in the moderation team's onboarding/offboarding process

Tasks

• trusted:
  • Document group on-wiki
• moderator:
  • Document group on-wiki (done)
  • Add instructions to the moderation team's onboarding and offboarding process (NixOS/moderation#27)
• Administrator:
  • Document group on-wiki
• Bureaucrat:
  • Document group on-wiki

Multilanguage support on the Wiki

Someone brought up on the Brazilian NixOS community that there isn't much Nix-related content in Brazilian Portuguese (PT-BR). I wonder if the community could start working on this by translating/contributing to the wiki in Brazilian Portuguese.

This could also open space for other languages!

Confirmation email not received

I'm trying to confirm my email address, but the confirmation email never came in.

I tried twice, got nothing.

Yes, I checked the spambox too ;)

Really bad SEO

This site (https://wiki.nixos.org/) has really bad SEO in comparison to the old site (https://nixos.wiki/).

The following search: zfs nixos wiki has zero results from wiki.nixos.org. Even changing it to zfs nixos wiki wiki.nixos.org does not do much: and the page in question, https://wiki.nixos.org/wiki/ZFS, is nowhere to be seen.

I do not know much about SEO, but this seems possibly due to wiki.nixos.org lacking a robots.txt. It might be prudent to copy https://nixos.wiki/robots.txt directly.

Formatting of Nix Code on the wiki

Should we format the nix code on the wiki with the nixfmt-rfc-style formatter?
This would make it so that the code on the wiki is following the same style that currently in the process of being adopted by nixpkgs.

Automating this could bring some issues with it, some of these being the unintended formatting of code that is intended to be formatted differently than the standard defined in RFC166, another one is that it could turn into a fight against the tools when editing.

We would need to find out how we investigate how the tools will behave when run against the wiki!

Search is hidden on mobile

The following screenshot shows, that the search is normally hidden on mobile. No search bar or button is shown in the default view, or by scrolling down.

The search however becomes visible, if the user scrolls sideways. This is very unintuitive for a mobile use case.

For better UX, the search bar or a search button should be visible without horizontal scrolling.

Migrating wiki links on Github

tracking issue for migration of github links from nixos.wiki to wiki.nixos.org

The flake article

As per the NixOS wiki contribution guidelines, language on the wiki has to be simple and concise. As of writing this, the flake article is the exact opposite of that. I'm not the most knowledgeable on flakes, but if anyone here is, I think this is an important thing to do given how widely used flakes are.

Action Required: Fix Renovate Configuration

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

Location: renovate.json
Error type: Invalid JSON (parsing failed)
Message: Syntax error: expecting end of expression or separator near oard""
]

Some suggestions for improvements

• There does not seem to be a way to setup email notifications yet?
• The "external link" css icon is also appearing for internal talk page links, such as here: https://wiki.nixos.org/wiki/Template:Expansion#Example
• Mention the content license in the footer.
  • Under About the NixOS Wiki

Helpful extensions:

• https://www.mediawiki.org/wiki/Extension:DiscussionTools so that talk pages have reply buttons
• https://www.mediawiki.org/wiki/Notifications
• https://www.mediawiki.org/wiki/Extension:Thanks

Infobox table problems

Screenshots

1. Font is too big
2. (might be linked to 1) goes over the width of the page (highlighted in red in the second screenshot)

Blocked on #56

Enabling TemplateData extension

This will allow Templates to be documented! See the MediaWiki wiki

incorrect example for boot.kernelParams

according to the https://search.nixos.org/options
boot.kernelParams is type of list of string, with spaces inside double quotes

but in https://nixos.wiki/wiki/Linux_kernel, it gave out example

{ pkgs, config, ... }:
{
  boot.kernelParams = [ 
    // example settings
    "quiet"
    "splash"
    usbcore.blinkenlights=1 // example kernel module parameter
  ];
}

the line usbcore.blinkenlights=1 which will raise syntax error

Attempting to change your password throws an internal error

When trying to change my password on the account page, it threw an internal error at me:

Allow use of images from Wikimedia Commons

The commons is an archive of lots of images, that we could reuse, instead of uploading our own. Mediawiki can automatically fetch and proxy file references that already exist in commons.

This plugin makes the whole workflow faster and should be preferred over the built-in $wgUseInstantCommons

https://www.mediawiki.org/wiki/Extension:QuickInstantCommons

Structured Approach to NixOS Wiki Uniformization

In my recent efforts to contribute to the NixOS official wiki, I have identified a critical need for standardization across the platform. The current state of the wiki is characterized by a lack of uniformity, with no two pages displaying consistent structure or format. This disorganization significantly undermines the efficacy and accessibility of the wiki as a resource. Consequently, I propose a plan for the systematic uniformization of the NixOS wiki.

Important

This is a foundational framework, not an exhaustive guide. Feedback and suggestions are encouraged.

Initiative 1: Standardized Page Categorization

To establish a coherent structure, it is imperative that we adopt a uniform naming convention for the page categories. I propose the following standardized categories, to be implemented in this specific order across all wiki pages:

1. Installation
2. Configuration
3. Tips and Tricks
4. Troubleshooting
5. References

Currently, similar categories appear sporadically under varied names and orders (e.g., "Install" instead of "Installation"). Implementing consistent naming and ordering will significantly enhance user experience by providing a predictable and navigable structure.

Initiative 2: Uniform Content Guidelines

Beyond standardizing category names, we must establish specific content guidelines for each category to ensure comprehensive and consistent information. For instance:

• Description: A detailed description of the software/service, preferably 100-150 words.
• Installation:
  • Using nix-shell
  • System-Wide Installation on NixOS
  • User-Specific Installation with Home Manager
• Configuration:
  • Basic
  • Advanced
• Tips and Tricks
• Troubleshooting
• References: Allow users to trace the sources of information that contributed to the creation of the page.

Initiative 3: Pre-formatted Code with Alejandra

To ensure the highest quality of code formatting, we should use Alejandra, the only formatter right now that does not compromise on quality. All code examples should be pre-formatted using Alejandra to ensure consistency and readability, at least until nixfmt-rfc-style resolves its current issues and becomes the official formatter. (#57)

Initiative 4: Enhanced Tagging System

The current tagging system, inherited from the old wiki, merely clutters the user experience with pages that are hardly navigable. An updated tagging system is essential. I propose the following structured approach:

• Major Category → Category → Subcategory → Pages

For example, the "Applications" or "Gaming" tags offer minimal utility. Instead, adopting a more structured approach, with the "Software" tag as the major one would greatly improve the navigation:

• Software
  • Server
    • Mailserver
      • Maddy
      • Mailman
  • Desktop
    • Communications
      • Signald
      • Discord

A more intuitive structure would replace Hardware → Hardware → Framework Laptop 13 with Hardware → Laptops → Framework Laptop 13.

Initiative 5: Regular Audits and Updates

To maintain the relevance and accuracy of the wiki, regular audits and updates are essential. This involves:

• Automated Monitoring Tools: Implement tools to flag outdated content or broken links, prompting reviews and updates.
• Editorial Board: Form an editorial board comprising experienced NixOS users and developers to oversee the quality and consistency of updates.
• Community Engagement: Promote the wiki across various NixOS communities (Discord, Reddit, Discourse, Stack Overflow, IRC, Matrix, Telegram, etc.) to ensure it is recognized as the central place of our collective knowledge. Pinning it would be the best case scenario.

Note

I urge the community to support and contribute to this initiative, as a unified approach will benefit all users. By embracing these initiatives, we can transform the NixOS wiki into a structured, user-friendly, and reliable tool for the NixOS community.

Multilingual support

A multilingual wiki can make NixOS more international, but it may also require more complex maintenance and moderation. So I'm not sure whether it is a good idea to make the site multilingual, it is just a suggestion.

I'm not familiar with MediaWiki. After some search, it seems that the recommended way to setup a multilingual MediaWiki is to use MediaWiki Language Extension Bundle.
https://stackoverflow.com/questions/12144303/how-to-make-a-mediawiki-site-multilingual

The MediaWiki language extension bundle (MLEB) is a curated set of MediaWiki extensions offering multilingual features. It attempts to provide an easy way to bring comprehensive language support to a MediaWiki.

The current version of MLEB contains the following extensions: [1]

• Babel
• CLDR ("Common Locale Data Repository")
• CleanChanges
• Translate
• UniversalLanguageSelector

MLEB has a quarterly release schedule, so that you can easily stay on the cutting edge with the constantly improving language support. The bundle is tested against recent MediaWiki release versions, so you can avoid most of the temporary breaks that would happen if you were using the latest development versions of each extension.

Switching theme breaks layout

Switching from dark mode to light mode and vice versa breaks the layout until the page is refreshed