PostHog / PostHog/posthog

Docs preview CI report links the site root and points at /handbook/engineering/

Open Beginner friendly
#84,367 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug team-devex
Dominant language
Python
Stars
39.9k
Forks
3.4k
Avg merge
6h 51m
Merged PRs (30d)
232

Description

Problem

Someone who adds a page under docs/published/docs/ gets a preview link to the site root, plus an instruction to open /handbook/engineering/. They have to work out their own page's URL, and the path they are pointed at has nothing to do with what they changed.

Current output

The docs-preview section of the CI report reads:

Docs from this PR will be published at posthog.com.

Project Preview Updated (UTC)
posthog.com Open preview ...

The preview should be ready in about 10 minutes. Open the preview at /handbook/engineering/.

Example on #83116, which adds docs/published/docs/data/test-accounts.mdx. The page is at /docs/data/test-accounts, which the section never mentions.

Cause

The hint is hardcoded, and predates product docs living in this repo. docs/published/ held only handbook content when it was written. It now also publishes pages under docs/published/docs/, which land on /docs/....

Suggested fix

.github/scripts/post-docs-preview-section.mjs runs where the changed files are known. The URL is already a pure function of the path, per docs/README.md: strip the docs/published/ prefix. Listing a direct link per changed page would remove the guesswork, and would also make it obvious when a page has landed at an unintended URL.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with .github/scripts/post-docs-preview-section.mjs and read the URL rules in docs/README.md. Trace how changed files under docs/published/ reach the docs-preview section, then verify the report gives each changed page its direct preview URL instead of the unrelated site root and handbook path.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
ci-cd, documentation
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.