Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Where links go

Say your README is in the repository root, and docs/index.md includes it. Here’s where its links end up on your docs site:

Link in the READMEGoes to
[guide](docs/guide.md)The guide page on your docs site
![logo](docs/logo.png)The image, copied into your docs site
[license](LICENSE)LICENSE on GitHub
[source](src/)The src/ folder on GitHub

The rule: files inside your MyST project (the folder with myst.yml) stay on your docs site, and images always do. Folders, and files outside the project, go to GitHub.

Full URLs, #section links, and paths starting with / are left as they are. This works for any {include}, not just READMEs.

Linking to GitHub

GitHub links use the repository in project.github in your myst.yml. If you haven’t set it, MyST shows a warning and those links stay broken.

Links point to the repository’s default branch. If you’re working on a fork, keep project.github pointing at the main repository. Your links then go to where the files will be once your pull request is merged. A file that only exists on your branch will 404 on GitHub until then.

Limitations