Onboarding docs that stay current

Keep onboarding docs in your repo. Publish to URLs. New hires get accurate instructions on day one, every time.

Wiki-based onboarding docs go stale

Onboarding docs in wikis go stale fast. Nobody owns them. Nobody reviews changes. The wiki version drifts from reality. A new hire follows the setup guide, hits an error on step 3, and spends half a day debugging instructions that were accurate six months ago.

Keeping onboarding docs as markdown in your repo means they go through code review. When someone updates the setup process, they update the docs in the same PR. The documentation stays in sync with the codebase.

The remaining problem: repo access. New hires on day one might not have GitHub access yet. MDtoLink publishes those repo-based docs to URLs anyone can open.

How it works

1. Write onboarding docs as markdown in your repo

docs/
  onboarding/
    setup.md          # Dev environment setup
    tools.md          # Required tools and access
    first-week.md     # What to do in your first week
    architecture.md   # System overview

Standard markdown files. Track them in Git alongside your code.

2. Publish each doc to a URL

mdtolink publish docs/onboarding/setup.md --slug onboarding-setup
mdtolink publish docs/onboarding/tools.md --slug onboarding-tools
mdtolink publish docs/onboarding/first-week.md --slug onboarding-first-week

Each doc gets its own URL. Share them individually or collect them in a welcome email.

3. Automate in CI so docs update on every merge

# .github/workflows/docs.yml
- name: Publish onboarding docs
  run: |
    npx mdtolink publish docs/onboarding/setup.md --slug onboarding-setup
    npx mdtolink publish docs/onboarding/tools.md --slug onboarding-tools
  env:
    MDTOLINK_API_KEY: ${{ secrets.MDTOLINK_API_KEY }}

When someone updates the docs and merges, the published URLs reflect the changes automatically.

Why use MDtoLink for onboarding docs?

Version-controlled docs

Docs live in your repo. Every change has a commit, a PR, and a reviewer. No more "who changed the wiki?"
Code-reviewed changes

Onboarding doc updates go through the same review process as code. Someone always validates the instructions.
Always current

CI publishing means the live URLs update on every merge. No manual syncing between your repo and a wiki.
No wiki account needed for new hires

New hires open the URL and read. No Confluence login, no GitHub access, no waiting for IT to provision accounts.

Frequently Asked Questions

Can I automate onboarding doc publishing in CI?

Yes. Add a step in your GitHub Actions or GitLab CI pipeline to run mdtolink publish on every merge to main. Docs update automatically when the source changes. See our GitHub Actions integration for a full example.

Do new hires need an account to read the docs?

No. Published pages are accessible to anyone with the link. New hires can read onboarding docs on day one without waiting for account provisioning.

Can I publish multiple onboarding docs?

Yes. Publish each file with its own slug: mdtolink publish onboarding/setup.md --slug onboarding-setup. Each gets a separate URL. Link between them using standard markdown links.

How do onboarding docs stay up to date?

Because the source files live in your repo, changes go through pull requests and code review. Publishing in CI means the live docs update on every merge. No manual syncing required.

Publish your onboarding docs in minutes

Free to start. No credit card required.

Start Publishing Free Read the Docs

Set up CI publishing with GitHub Actions. Or browse all use cases.