Skip to content

About

A MyST plugin to re-write relative links for files inserted with {include} so that they don't break

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

4 Commits

Folders and files

Repository files navigation

MyST Include Link Rewrites

A MyST plugin that fixes relative links and images in files you {include} into your docs, so the same file works both on GitHub and in your documentation. The most common use is a README, but it works for any included file.

A README included into a docs page

The problem this solves

Many repositories use the {include} directive to reuse their README as the home page of their docs. Some also include CONTRIBUTING.md in a contributing page. READMEs usually have relative links, like [license](LICENSE) or [guide](docs/guide.md). By default, MyST reads those paths as if they were written in the docs page where {include} is used, not the README, so they break.

This plugin fixes them:

  • Links to pages in your docs stay inside your docs site.
  • Links to other repository files, like the plugin source or the LICENSE, point to GitHub.
  • Images are copied into your site as usual.

See Where links go for the full rules.

Usage

Add the plugin to your myst.yml, and set project.github so links outside your docs can point to your repository:

project:
  github: https://github.com/org/repo
  plugins:
    - https://github.com/myst-contrib/myst-include-link-rewrites/releases/latest/download/index.mjs

Then include your README from a docs page:

```{include} ../README.md
```

Contributing

See CONTRIBUTING.md.

About

A MyST plugin to re-write relative links for files inserted with {include} so that they don't break

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Contributors

Languages