also looking at this
fix: resolve documentation source links in native rendering
#87
7 files
+958
-254
| @@ -294,6 +294,20 @@ Content here... | ||
| 294 | 294 | <!--@include: ./shared/footer.md--> |
| 295 | 295 | ``` |
| 296 | 296 | |
| 297 | Put each include directive on its own line. Include paths are relative to the | |
| 298 | documentation root. Links inside included content resolve from that included | |
| 299 | file's directory, including recursive includes, while keeping the rendered | |
| 300 | page's locale. Inline includes are refused because their source boundaries | |
| 301 | cannot be preserved reliably through Markdown parsing. | |
| 302 | ||
| 303 | Use inline links in documents that expand includes. Reference definitions can | |
| 304 | bind uses across file boundaries, and the Markdown parser does not expose the | |
| 305 | definition's source location. These documents refuse reference definitions; | |
| 306 | literal examples in code spans, fenced blocks and HTML code remain supported. | |
| 307 | Reference validation is bounded to 256 candidate labels per expanded document. | |
| 308 | Split a document that exceeds this limit. Documents without includes continue | |
| 309 | to support reference-style links. | |
| 310 | ||
| 297 | 311 | ## Images |
| 298 | 312 | |
| 299 | 313 | ### Basic Images |
| @@ -310,6 +324,40 @@ Content here... | ||
| 310 | 324 | |
| 311 | 325 | Images are automatically lazy-loaded for better performance. |
| 312 | 326 | |
| 327 | ## Documentation Links | |
| 328 | ||
| 329 | Use source-relative Markdown links so authored files also work on GitHub: | |
| 330 | ||
| 331 | ```markdown | |
| 332 | [Overview](../overview.md#configuration) | |
| 333 | [This section](index.md) | |
| 334 | [Reference](README.md) | |
| 335 | [Named reference][guide] | |
| 336 | ||
| 337 | [guide]: ../guide.md?example=1#setup | |
| 338 | ``` | |
| 339 | ||
| 340 | Native builds and dev serving map these destinations to the generated page | |
| 341 | routes and apply the configured base path. For example, a page in `docs/guide/` | |
| 342 | linking to `../overview.md` becomes `/overview`, or `/docs/overview` with | |
| 343 | `basePath: '/docs'`. `index.md` uses its directory route; `README.md` keeps a | |
| 344 | `README` route. Query strings and fragments stay attached to the destination. | |
| 345 | ||
| 346 | Unqualified sources use the current rendered locale, including fallback | |
| 347 | content. An explicit language suffix such as `guide.en.md` selects that language | |
| 348 | even when the referring page uses another locale. | |
| 349 | ||
| 350 | External URLs, image destinations, links outside the documentation source tree, | |
| 351 | and literal code examples stay unchanged. Use explicit repository URLs for | |
| 352 | source and evidence references that should open on GitHub. | |
| 353 | ||
| 354 | A missing linked Markdown source or two sources sharing one output route | |
| 355 | refuses the build. A failed rebuild keeps the previous complete output. Builds | |
| 356 | in one process queue for the same output; another process holding that output's | |
| 357 | lock causes a clear refusal. Before manually removing a stale `.bunpress.lock` | |
| 358 | directory, inspect its `owner.json` and verify that the recorded builder has | |
| 359 | stopped. | |
| 360 | ||
| 313 | 361 | ## External Links |
| 314 | 362 | |
| 315 | 363 | External links automatically: |