Plugins

Git Docs

Git Docs

A Git Docs page renders the documentation living in a git repository as a live, read-only doc site inside the wiki. Git stays the source of truth — docu.nexus never writes back to the repo. Teams keep writing docs next to their code; the wiki picks them up on every push.

One Git Docs page shows one repository. The page has its own in-view navigation tree, a branch/tag switcher, and shareable deep links, but it is still a single page in the sidebar: it lives in a space, inherits permissions and sharing, and has a normal URL.

Git Docs is free and always on (no SKU). It has no admin tab; the only administration it needs is a credential, which an instance administrator adds under Admin -> Connections and lets nexuses use under Admin -> People & Access -> Connections.

There are two ways to present a repo, chosen per page:

Add a credential first (private repos)

Most teams connect private repositories, and a private repo cannot be cloned without a credential. An instance administrator sets one up before the page is created:

1. On your git host, create a read-only token.

   • GitLab. A personal, group, or project access token with the read_repository scope. A group token with the Reporter role covers every repo in the group.
   • GitHub. A fine-grained personal access token with Contents set to read-only, limited to the repositories you are connecting. Fine-grained tokens belong to a user account, so create it under your own developer settings. For a repository owned by an organization, set the token’s resource owner to that organization; the organization may also require an owner to approve it, and may cap how long it can live. Add each further repository to the token as you connect it.

2. In docu.nexus, open Admin -> Connections and add a Git host connection:

   • Limited to host. For example https://github.com, https://gitlab.com, or your self-hosted instance. The token is sent to this host and nowhere else: a page whose repository is on another host cannot use the connection. Git Docs also matches this host against repo URLs to suggest the credential automatically. Changing the host later means entering the token again.
   • Username. Optional. Left blank it becomes oauth2, which GitHub and GitLab both accept alongside a token.
   • Access token. The token from step 1.

   A GitLab connection works too, when its access token also has the read_repository scope. Its token goes only to repositories under its Base URL.

3. A new connection is allowed in no nexus. Saving it opens Admin -> People & Access -> Connections with the connection selected: switch on each nexus whose pages may use it, or Every nexus, including future ones. A personal nexus is covered only when switched on by name.

One credential per git host is usually enough, and every Git Docs page pointing at that host, in every nexus it is allowed in, can use it. The exception is a GitHub fine-grained token, which reaches only the repositories listed on it, so connecting another repo means adding it to the token first.

Connect a repository (markdown mode)

1. Create a Git Docs page from the New content menu in a space, or from the space rail.
2. The page opens on the setup form. Fill in:
   • Repository URL — the HTTPS clone URL, exactly what your git host’s Clone -> HTTPS button copies, for example https://github.com/team/project.git.
   • Default branch or tag (optional) — pins the version readers land on. Left blank, the repo’s default branch is used.
   • Mode — leave on Auto (markdown unless the repo says otherwise), or force Markdown / Artifact.
   • Credential — required for private repos. When a saved credential’s host matches the repo URL it is preselected; the form warns if you leave “none” selected for a host that has one.
3. Press Connect repository. The repository is checked before anything is saved, so a URL docu.nexus cannot reach is refused on the form, with nothing saved and no webhook secret issued.

Save the webhook credentials

Right after connecting, the page shows the webhook payload URL and a signing secret, exactly once. Copy both now — the secret cannot be read again, only rotated (from the page’s settings, Rotate the secret; the old one stops working immediately).

Add the webhook to the repository so pushes update the docs automatically:

• GitHub: repo -> Settings -> Webhooks -> the payload URL and secret from above, content type application/json, event push.
• GitLab: repo -> Settings -> Webhooks -> URL from above, Secret token = the secret, triggers Push events and Tag push events. GitLab labels the secret-token field “not recommended” in favor of its newer signing tokens; the token is what docu.nexus verifies today, and it is fine over HTTPS.

The webhook only ever triggers a git fetch — nothing anyone sends to it can inject content. Without a webhook, editors can still use the refresh button in the banner, and self-hosters can enable polling (below).

Reading

Once the clone finishes, readers get:

• Navigation tree — every markdown/HTML file in the repo (junk directories like node_modules are excluded), or exactly the tree the repo defines (next section).
• Version switcher — a dropdown of branches and tags; readers can browse any of them without changing anything for anyone else.
• Provenance banner — which repo, ref, and commit is being shown, with a link to the source on the git host, and a refresh button for editors.
• Deep links — the open document, ref, and heading mirror into the URL, so any spot in any version is a shareable link. Headings have hover permalinks, GitLab-style.
• Page rail, the column of buttons on the right: open the page’s chat, watch the page, add it to your favorites, check who has access, and tag it. More options copies a link (once a document is open, the link lands on that document, version and heading) or moves the page to Trash; the repository is not touched.

Rendered markdown follows each reader’s docu.nexus appearance (theme and fonts), Mermaid diagrams included: they re-draw when the theme changes. Repos that want full styling control can commit HTML files instead; those render too, sanitized.

Viewing needs can_view on the page; connecting or reconfiguring needs can_edit.

Control the view with DOCUNEXUS.md

Without any configuration, the landing page is the repo’s README.md and the tree lists every doc file alphabetically. To curate the view, commit a DOCUNEXUS.md at the repo root:

---
title: My Project Docs        # sidebar title (default: repo name)
home: docs/intro.md           # landing document (default: README)
include:
  - docs/**
exclude:
  - docs/internal/**
nav:                          # explicit order and grouping; replaces the
  - docs/intro.md             # auto-generated tree entirely
  - label: Guides
    children:
      - path: docs/guide-a.md
        label: Guide A
---

All keys are optional, unknown keys are ignored, and the file itself never appears in the tree. Setting mode: artifact here switches the page to artifact mode (the page’s own setting wins if both are set).

Artifact mode

When the documentation is a generated site — Sphinx, Doxygen, Hugo, mdBook — the build output is what readers should see, not the sources. In artifact mode your CI builds the site, pushes it to docu.nexus, and the page serves it as-is: its own styling, its own JavaScript, its own search.

1. Connect the repository as above, with Mode set to Artifact (or mode: artifact in DOCUNEXUS.md).
2. In the page’s settings, press Generate an upload token. Like the webhook secret it is shown once — store it as a masked CI variable, for example DOCU_NEXUS_UPLOAD_TOKEN. Rotating it invalidates the old token immediately.
3. Have CI tar the built site and POST it, versioned by commit or tag. The exact URL, with the page id filled in, is shown next to the token, along with this GitLab CI example:

publish-docs:
  stage: deploy
  script:
    - tar -czf site.tar.gz -C public .
    - >
      curl --fail -X POST
      -H "Authorization: Bearer $DOCU_NEXUS_UPLOAD_TOKEN"
      --data-binary @site.tar.gz
      "https://your-docu-nexus/api/x/gitdocs/pages/<page-id>/artifact?version=$CI_COMMIT_SHORT_SHA"

The same push works from GitHub Actions or plain curl. Re-pushing an existing version label replaces it atomically. The newest versions are kept (five by default, configurable when self-hosting) and older ones are evicted; the version switcher lists what is stored, newest first.

Uploaded sites run in a sandboxed frame on an isolated origin: their scripts execute, but they cannot reach docu.nexus cookies, storage, or the page around them. Files are only served to signed-in readers with can_view — artifacts are never publicly reachable.

Sites that expect to live at a domain root

A generated site often references its own files from the server root — /css/main.css, /pagefind/…. Whether that works depends on one setting on your instance:

• Configured. GITDOCS_ARTIFACT_HOST is set (ask your admin; see Configuration). Each version is served from a hostname of its own, at its root. Any site works unmodified, whatever built it.
• Not configured — versions are served under a path prefix, and only relocatable builds render correctly. Sphinx, Doxygen and mdBook already emit relative links and are fine as-is. Hugo needs relativeURLs = true in hugo.toml, and any hand-written /... paths have to become relative — the same adjustment those sites need for GitLab Pages project pages or any other sub-path host.

A site whose CSS and links are dead in the frame is almost always this, not a failed upload.

Troubleshooting

Self-hosting knobs — clone timeouts, file-size caps, artifact size/count/retention limits (GITDOCS_ARTIFACT_KEEP and friends), and the host allowlist — are environment variables on the server; see Configuration.