Share a MkDocs Site With Your Team (No GitHub Account Required)

MkDocs builds clean, well-formatted documentation sites from Markdown (MkDocs docs). The build output in ./site/ is static HTML that renders in any browser. The problem is never building the docs. The goal is to get them in front of the PM, the designer, or the support lead. These people need to read them but do not use your GitHub repo.

This guide publishes the built site at a company-authenticated URL that never changes, so anyone with a company email can read it, and nobody needs a GitHub seat.

Why the usual options don't fit internal docs

• GitHub Pages (public): Anyone on the internet can read it. Wrong for internal engineering docs.
• GitHub Pages (private repos): Requires GitHub Enterprise Cloud, and every viewer needs a GitHub account with repo access (GitHub Pages docs). At $21/user/month, 100 readers is $2,100/month.
• Confluence: You'd manually recreate the content, and the Markdown-to-wiki round trip strips formatting and code blocks.
• Read the Docs: Sphinx-oriented; MkDocs works but you inherit their build and their hosting model.
• Raw Markdown in the repo: Your PM reads unrendered .md files with broken links and unstyled tables.

Setup

pip install mkdocs mkdocs-material
 
mkdocs build

Display publishes docs and files. A single self-contained HTML file is the safe shape. Ask your agent to inline the CSS, JS, and images from ./site/ into one HTML file. Then ask it to publish that file:

"Publish the bundled docs to Display for everyone at my company."

Your agent returns a link such as https://acme.dsp.so/0kzNYG7O-engineering-docs.

Share the URL in your onboarding docs, company Notion, or Slack. Anyone with a company email clicks it, authenticates once, and reads the rendered docs. On Pro that sign-in is one click via Google or Microsoft SSO. On the Free plan viewers verify with a one-time password (a six-digit code by email).

Comparison

Auto-deploy on push to main

name: Deploy Docs
 
on:
  push:
    branches: [main]
    paths: ['docs/**', 'mkdocs.yml']
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Install dependencies
        run: pip install mkdocs mkdocs-material
      - name: Build docs
        run: mkdocs build
      # Next step: bundle ./site/ into one self-contained HTML file, then
      # publish it to Display with a scoped API key (DISPLAYDEV_API_KEY).
      # The job calls Display's REST API, or an agent runs the publish.

Every push that touches docs/ or mkdocs.yml rebuilds the docs and publishes the new version to the artifact ID stored in DISPLAY_ARTIFACT_ID. The URL stays the same, so bookmarks don't break. Display records the version you edited from, so a concurrent publish is not overwritten silently. For the general CI pattern, see publishing HTML from GitHub Actions.

Works with Docusaurus, Sphinx, and Quarto too

npm run build            # Output: ./build/
 
make html                # Output: ./_build/html/

For a build output, ask your agent to bundle it into one self-contained HTML file, then publish that file. For notebook-based docs, see share a Quarto report with your team.

Getting links right when published

display.dev serves a published document at a path like /0kzNYG7O-engineering-docs/, not at the domain root. Two things to check in mkdocs.yml:

• Don't hard-code an absolute site_url that assumes the root. Leave site_url unset or set it to the published artifact URL so the sitemap and canonical tags match where the docs actually live.
• Keep asset references relative. Material for MkDocs does this by default. If you added custom extra_css or extra_javascript, use relative paths (css/extra.css), not absolute ones (/css/extra.css), so they resolve under the subpath.

If something links to /, it will jump out of the artifact. Relative links stay inside the published document.