Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Restructure headscale documentation #2163

Open
wants to merge 26 commits into
base: main
Choose a base branch
from
Open

Restructure headscale documentation #2163

wants to merge 26 commits into from

Conversation

nblock
Copy link
Contributor

@nblock nblock commented Oct 2, 2024 •
edited
Loading

Following the spirit of the 0.23 release, this PR aims to restructure the existing documentation to improve
maintanability while providing more information to users. It is mainly a preparation for versioned documentation in the
future which will allow us to evolve the documentation alongside headscale releases. Relevant aspects of this PR:

  • Split the documentation into multiple sections:
    • About: Information about the project: FAQ, features, client compat, contributing, …
    • Setup: Requirements, Install page for varous release, Upgrading
    • Usage: "Getting started", Connecting with Android/Apple/Windows
    • Reference: specific documentation (acl, dns, oidc, …) and integration with other components (reverse proxy, Web UI)
  • Remove duplication and split the common parts into their own pages
  • Document more ways to install headscale (official binaries and packages, distribution, container, …).
  • Add a configuration reference
  • Reuse existing documentation such as CONTRIBUTING.md
  • Replace duplicate content in the README with links to the docs (features, client)
  • Update wording to headscale (in regular text), Headscale (beginning of a sentence) and headscale when referring to the CLI.
  • Add redirects from old links to the new pages

A preview is available here: https://nblock.github.io/headscale/

  • have read the CONTRIBUTING.md file
  • raised a GitHub issue or discussed it on the projects chat beforehand
  • added unit tests
  • added integration tests
  • updated documentation if needed
  • updated CHANGELOG.md

@nblock
Setup mkdocs-redirects
5e9862e
@nblock
Restructure existing documentation
7e28d0d
@nblock
Move client OS support into the documentation
3e3e7dd 
* Move existing Client OS support table into its own documentation page
* Link from README.md to the rendered documentation
* Document minimum Tailscale client version
@nblock
Reuse CONTRIBUTING.md" in the documentation
ddd655b 
* Include "CONTRIBUTING.md" from the repository root
* Update FAQ and index page and link to the contributing docs
@nblock
Add configuration reference
caa00e5
@nblock
Add a getting started page and explain the first steps with headscale
7b4eae6 
* Use the existing "Using headscale" sections and combine them into a
  single getting started guide with a little bit more explanation.
* Explain how to get help from the command line client.
* Remove duplicated sections from existing installation guides
@nblock
Document requirements and assumptions
c3a1eb9
@nblock
Document packages provided by the community
bfc6626
@nblock
Move deb install guide to official releases
561abd6
@nblock
Move manual install guide to official releases
ed727b8
@nblock
Move container documentation to setup section
e2b559f
@nblock
Move sealos documentation to cloud install page
07d8038
@nblock
Move OpenBSD docs to build from source
0ceeaa3
@nblock
Simplify DNS documentation
ff90173
@nblock
Add sponsor page
37f2a7e
@nblock
Add releases page
cc4e9ab
@nblock
Add features page
7a0609b
@nblock
Add help page
e3f6255
@nblock
Add upgrading page
452f83a
@nblock
Adjust mkdocs nav
df5d50f
@nblock
Update wording
596685e 
Use the term headscale for the project, Headscale on the beginning of a
sentence and `headscale` when refering to the CLI.
@nblock
Welcome to headscale
b37c7b9
@nblock
Link to existing documentation in the FAQ
1f525cd
@nblock
Remove the goal header and use the text as opener
c2b06ba
@nblock
Indent code block in OIDC
02bb866
@nblock
Make a few pages linter compatible
05d694b 
Also update ignored files for prettier
@nblock nblock marked this pull request as draft October 2, 2024 12:31
@nblock nblock changed the title Docs Restructure headscale documentation Oct 2, 2024
@nblock nblock marked this pull request as ready for review October 2, 2024 14:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ohdearaugustin ohdearaugustin Awaiting requested review from ohdearaugustin ohdearaugustin is a code owner

@juanfont juanfont Awaiting requested review from juanfont juanfont is a code owner

@kradalby kradalby Awaiting requested review from kradalby kradalby is a code owner

At least 1 approving review is required to merge this pull request.

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
1 participant
@nblock