Links and Inner Links

For navigating between pages within your site, inner links [[...]] are recommended — they are resolved to final URLs by the publishing system during preview and export, rather than requiring manually written relative paths. Inner links are used for cross-references in body text, chapter navigation (such as _nav.md in Navigation and Table of Contents), breadcrumb titles, and the from_file parameter of template functions like nav_tree.

Standard Markdown Links

For external sites or fixed URLs, use the common syntax:

[Everkm Website](https://everkm.cn)
<https://everkm.cn>
[Reference Link][ref]

[ref]: https://everkm.cn

When exporting a static site, relative path links in body text (e.g., [Next Page](./next.html)) will be intercepted by validation. Intra-site navigation should use inner links instead — see below.

Inner Link Syntax

Inner links are written as [[target]] and resolved to the publish URL during the Markdown rendering stage; unresolved or ambiguous links will immediately trigger an error (behavior is the same for preview and export).

[[quick-start]]                    # Match by slug or title
[[./faq/]]                         # Relative to current file directory
[[/docs/guide/quick-start.md]]     # Site-root logical path
[[./page#section-title]]           # Anchor
[[./faq/|FAQ]]                     # Custom display text (| separates target from display text)

The guide's _nav.md organizes chapters using inner links:

* [[navigation]]
* [[inner-link]]
* [[everkm-markdown]]

Matching Rules

Resolution is attempted in the following order (all based on the current language's content index):

Order	Syntax	Description
1	External links, `~/` prefix	Output as-is or replaced with site `base_prefix`
2	slug	Case-insensitive; multiple matches → error
3	title	Case-insensitive; multiple matches → error
4	path	See "Path Prefixes" below
5	Non-`.md` media	Copied to static assets and URL output

Path Prefixes (used when neither slug nor title uniquely matches):

Syntax	Behavior
Starts with `/`	Logical path relative to site root, e.g., `[[/docs/faq.md]]`
Starts with `./` or `../`	Relative to the current Markdown file's directory
No prefix	First matched by path suffix across the entire site (e.g., `use-cases` → find paths ending with `/use-cases.md`); unique match is used, multiple matches are ambiguous; if no match, falls back to relative to current directory

[[FAQ]] is typically resolved by slug / page title first, not directly as "a filename in the current directory." Titles or slugs may be duplicated across different directories. For directory default pages, chapter navigation, and similar scenarios, prefer [[./subdirectory/]] or [[/absolute/logical/path]] to disambiguate.

Paths ending with / are resolved as directory default pages (e.g., index.md or pages with slug: index in that directory).

Inner links can also point to non-Markdown media (such as PDFs, images), which are automatically copied to the static assets directory and output as URLs during export.

Common Scenarios

Cross-references in Body Text

For configuration details, see [[dir-config]]; for Markdown extensions, see [[everkm-markdown]].

Chapter Navigation `_nav.md`

Simply write inner links as list items; the theme reads nav_file and renders the sidebar tree and previous/next navigation. See Navigation and Table of Contents.

Breadcrumbs

In folders.breadcrumbs of everkm.yaml, only when the entry does not have url configured (or url is empty), a title of [[...]] will be resolved as an inner link, adopting the target page's title and URL; if url is also specified, the configured title and url are used directly without inner link resolution.

folders:
  "/blog/":
    breadcrumbs:
      - title: "[[blog]]"              # No url: resolve inner link → target page title + URL
      - title: "@i18n:nav.blog"
        url: /blog/                      # Has url: use as-is, title is not resolved as inner link

For merging rules and more examples, see Directory Configuration.

Template Navigation Functions

For nav_tree, nav_path, and nav_indicator, if the from_file parameter is wrapped in [[...]], the same inner link resolution rules as body text apply:

{{ nav_tree(from_file="[[./_nav.md]]") | json_encode }}

Pre-publish Check

everkm-publish lint ./my-site

Lists unresolved or ambiguous [[...]] links by line number, suitable for CI and pre-publish self-checks. When ambiguous, a list of candidate pages is output for easy switching to a more specific path.

Common fixes:

[[quick-start]] matches multiple pages → change to [[/docs/guide/quick-start]] or [[./guide/quick-start]]
Duplicate titles → use explicit paths, do not rely on title matching

For more troubleshooting, see FAQ.

Differences from Relative Links

	Inner Link `[[...]]`	Standard Link `[text](./page.md)`
Resolution time	Markdown → HTML stage	Post-export validation of relative `href`
Target	Pages / media in index	Hand-written path, prone to breakage with URL rule changes
Failure behavior	Rendering fails immediately	Export reports `RelativeLinkNotAllowed`

For complete Markdown link syntax, in-page anchors {id=...}, link extended attributes, and more, see Everkm Markdown Format and Everkm Markdown Format.