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 a static directory that renders in any browser. The problem is never building the docs. It's getting them in front of the PM, the designer, or the support lead who needs to read them but doesn't live in 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
 
dsp publish ./site/ --name "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 full rendered MkDocs site: navigation sidebar, client-side search, code highlighting, all of it. On Pro that sign-in is one click via Google or Microsoft SSO; on the Free plan viewers verify with a one-time passcode (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
      - name: Publish docs
        run: |
          npm install -g @displaydev/cli
          BASE_VERSION=$(dsp get "${{ vars.DISPLAY_ARTIFACT_ID }}" | jq -r .currentVersion)
          dsp publish ./site/ --id "${{ vars.DISPLAY_ARTIFACT_ID }}" --base-version "$BASE_VERSION"
        env:
          DISPLAYDEV_API_KEY: ${{ secrets.DISPLAYDEV_API_KEY }}

Every push that touches docs/ or mkdocs.yml rebuilds and republishes to the artifact ID stored in DISPLAY_ARTIFACT_ID. The URL stays the same, so bookmarks don't break. --base-version prevents a concurrent publish from being 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/
dsp publish ./build/ --name "product-docs"
 
make html                # Output: ./_build/html/
dsp publish ./_build/html/ --name "api-reference"

Any static site generator that emits a directory of HTML works with dsp publish ./output-dir/. For notebook-based docs, see share a Quarto report with your team.

Getting links right when served at a subpath

display.dev serves a published site at a path like /0kzNYG7O-engineering-docs/, not at the domain root. MkDocs handles this cleanly if you leave use_directory_urls: true (the default), because it emits relative links between pages. 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 keep navigation inside the published site.