search

Doctave / doctave

A batteries-included developer documentation site generator
https://cli.doctave.com
MIT License
549 stars 33 forks source link

Linking to README pages results in broken links #33

Open jschaf opened 2 years ago

jschaf commented 2 years ago

I have a README.md page that links to two internal docs pages:

- [Developing](doc/dev/README.md):
- [Bazel](doc/dev/developing_bazel.md):

The first link to doc/dev/README.md doesn't work in doctave because doctave serves that page from doc/dev (no trailing /README.md).

The second links works as expected.

begleynk commented 2 years ago

In general you should be using the final URL paths instead of paths to the actual Markdown files on disk. Doctave doesn't do any special transformations to the URLs.

So the first example would become doc/dev or doc/dev/index.html. I think the second link is working in the local development mode for you because of how Doctave's local server tries to resolve the file (I'm actually a bit surprised that got resolved - I'm going to investigate this further). I'm not sure that would actually work on most hosting providers since the final .md files won't actually be deployed.

In Doctave 0.4.0 we actually added broken link checking. Doctave will now tell you at build/serve time if it finds any internal links in your docs that don't resolve.