Links
In links and image references, URLs and absolute file paths are kept unchanged in the composite file. So are internal links to other parts of the document (markdown links begining with #).
It's up to you to ensure that internal links are unique within the composite document. If several different files of your just-the-docs site link to #introduction, for example, the result in the composite will be syntactically valid CommonMark with unspecified semantics.
Example of links passed through unchanged
Within this repository's docs/src/assets directory, the externallink directory has a single file with examples of a link and image reference.
externallink = joinpath("assets", "externallink")
srcfile = joinpath(externallink, "f1.md")
read(srcfile) |> String |> print---
layout: page
title: "Example link"
---
External [link to "Just-the-Docs"](https://pmarsceill.github.io/just-the-docs/)
Link to an The links are unchanged in the output from composite.
using UnifyJustTheDocs
composite(externallink) |> String |> print┌ Info: Reading markdown source files from
└ starthere = "assets/externallink"
[ Info:
┌ Info: Pages read:
└ length(jtdpages) = 1
External [link to "Just-the-Docs"](https://pmarsceill.github.io/just-the-docs/)
Link to an Relative references: images
For image links, relative paths are replaced with absolute paths, since links relative to the original source page would be meaningless once the hierarchical page organization of the original web site has been flattened into a single file.
The resulting markdown can be directly used by other markdown-aware applications, such as pandoc to generate PDF or other formatted files.
The absolute paths will only be valid on the system where the composite was built so the resulting composite is not portable to other systems.
Relative references: local files
Links to content using relative links to file paths are also meaningless in the composite file. The composite functions accepts an optional pandoc_anchors parameter you can use to insert a pandoc-style named anchor in the composite at the point where each file begins, and convert relative file links to corresponding internal references.
This is most easily seen with an example. The assets/externallink directory has two short files, f1.md and f2.md; the second includes a link to the first using a relative file link.
f2 = joinpath("assets", "internallink", "f2.md")
read(f2) |> String |> print---
layout: page
title: "Topic page"
---
Linked to [home page](f1).When we composite these files with the pandoc_anchors parameter set to true, the result now includes an empty header # with a pandoc named anchor at the points where content from f1 and f2 begin. The name for the anchor point is derived from the path to the file; in f2, the relative reference to f1 is converted to the internal reference marking the beginning of f1.
internallink = joinpath("assets", "internallink")
composite(internallink, pandoc_anchors = true) |> String |> print┌ Info: Reading markdown source files from
└ starthere = "assets/internallink"
[ Info: # {#assets-internallink-f1}
[ Info: # {#assets-internallink-f2}
┌ Info: Pages read:
└ length(jtdpages) = 2
# {#assets-internallink-f1}
Home page.
# {#assets-internallink-f2}
Linked to [home page](#assets-internallink-f1).Using pandoc_anchors, you can use portable relative references in your markdown source files, and produce a composite with portable internal references that can be processed by pandoc on any system.