- Meeting info
- Past meeting notes
- Documentation office hours in the NixOS Calendar
- Attendees: @hsjobeki @trespaul @friedow @samestep
- Notes by: everyone
vision doc: nix.dev/maintainers/vision.md at master · NixOS/nix.dev · GitHub
Summary
This meeting was mostly a walkthrough of in-progress work on the docs.nixos.org theme and structure. @hsjobeki showed the latest sidebar development in the Nixpkgs manual, and @trespaul demonstrated a custom docs.nixos.org theme. Discussion on frontmatter, mobile navigation, and sidebar group behaviour. The recommendation was to upstream the custom theme in incremental chunks, and a frontpage is needed before it can be upstreamed. We also aligned on what the landing page should be: functional and welcoming, without a wall of text.
Notes
@samestep Wanted to help implementing a sidebar; Just discovered its already done in unstable.
@hsjobeki showed the latest developments in the Nixpkgs manual.
@trespaul showed their development version of a custom docs.nixos.org theme with two sidebars. This led to several discussions:
Frontmatter in Markdown pages
- @trespaul: we should add a title to the frontmatter.
- @hsjobeki: would taking the first heading of a document work?
- Conclusion: it probably makes sense to add frontmatter automatically.
@hsjobeki noted there is an open PR for the sidebar structure, and recommended upstreaming the custom docs.nixos.org theme in incremental chunks.
Markdown features
- @trespaul: looked into Sätteri which is the new markdown pipeline behind astro. Could not figure out yet how markdown directives work. For example Starlight has a custom integration for it.
Mobile navigation
- Which should collapse first: page navigation or site navigation?
- @trespaul presented the idea of putting both navigations into the same mobile menu.
- @hsjobeki and @friedow recommended using the same mobile navigation style as Starlight or Clan.
Sidebar groups
- @hsjobeki recommended restricting sidebar groups from being navigated to, they should just be collapsible.
- @trespaul: navigating to sidebar group links will end in a 404.
- @friedow: sidebar group links should redirect to the first page in the group.
- @hsjobeki: currently there is no index page for sidebar groups. They can be autogenerated later.
@hsjobeki: the new theme needs a frontpage before it can be upstreamed.
Contributing and content
@hsjobeki showed the getting started PR he created for contributing to docs.nixos.org, and explained his implementation of converting includes to separate Markdown files.
@hsjobeki @trespaul Took a look into how the nixpkgs manual is currently structured and worded.
General agreement that a lot of work needs to go into restructuring and rewording.
Also why the docs-styleguide was created earlier this year.
Landing page
@trespaul will join the marketing meeting to ask about the appearance of the frontpage.
@trespaul and @hsjobeki agreed the landing page should be functional:
- No wall of text.
- Doesn’t really need pretty pictures.
- A welcoming introduction/overview.
- Something like the Kubernetes docs home, with a better design.
- Funnelling by persona is bad for us. See Ansible docs as an example of what to avoid.
Other
- Some more reviewing of existing docs.
- Viewing the manpages and docs of
nixos-rebuildand other tools