1<!DOCTYPE html> 2<html lang="en-gb"> 3 <head> 4 <meta charset="UTF-8"> 5 <meta name="apple-mobile-web-app-capable" content="yes"> 6 <meta name="viewport" content="width=device-width, initial-scale=1"> 7 <meta name="description" content="Everything you need to make a static site engine in one binary."> 8 <meta name="author" content="Vincent Prouillet"> 9 <title>Internal links & deep linking | Zola </title> 10 <link rel="stylesheet" href="https://www.getzola.org/site.css"> 11 <link rel="icon" href="https://www.getzola.org/favicon.ico"> 12 </head> 13 <body> 14 15 <header> 16 <a class="header__logo white" href="https://www.getzola.org/"><img 17 src="https://www.getzola.org/logos/Zola-logo-white.svg" 18 title="Zola main logo in white" 19 alt="Zola" 20 /></a> 21 <nav> 22 <ul> 23 <li><a class="white" href="https://www.getzola.org/documentation/" class="nav-link">Docs</a></li> 24 <li><a class="white" href="https://www.getzola.org/themes/" class="nav-link">Themes</a></li> 25 <li><a class="white external" href="https://zola.discourse.group/" class="nav-link">Forum</a></li> 26 <li><a class="white external" href="https://github.com/getzola/zola" class="nav-link">GitHub</a></li> 27 </ul> 28 <div class="search-container"> 29 <input id="search" type="search" placeholder="ð Search the docs"> 30 31 <div class="search-results"> 32 <div class="search-results__items"></div> 33 </div> 34 </div> 35 </nav> 36 </header> 37 38 <div class="content content--reversed"> 39 40 41<div class="documentation"> 42 <aside class="documentation__sidebar"> 43 <ul> 44 45 46 <li> 47 <span class="documentation__sidebar__title">Getting Started</span> 48 <ul> 49 50 <li class=""> 51 <a href="https://www.getzola.org/documentation/getting-started/overview/">Overview</a> 52 </li> 53 54 <li class=""> 55 <a href="https://www.getzola.org/documentation/getting-started/installation/">Installation</a> 56 </li> 57 58 <li class=""> 59 <a href="https://www.getzola.org/documentation/getting-started/cli-usage/">CLI usage</a> 60 </li> 61 62 <li class=""> 63 <a href="https://www.getzola.org/documentation/getting-started/directory-structure/">Directory structure</a> 64 </li> 65 66 <li class=""> 67 <a href="https://www.getzola.org/documentation/getting-started/configuration/">Configuration</a> 68 </li> 69 70 </ul> 71 </li> 72 73 74 <li> 75 <span class="documentation__sidebar__title">Content</span> 76 <ul> 77 78 <li class=""> 79 <a href="https://www.getzola.org/documentation/content/overview/">Overview</a> 80 </li> 81 82 <li class=""> 83 <a href="https://www.getzola.org/documentation/content/section/">Section</a> 84 </li> 85 86 <li class=""> 87 <a href="https://www.getzola.org/documentation/content/page/">Page</a> 88 </li> 89 90 <li class="active"> 91 <a href="https://www.getzola.org/documentation/content/linking/">Internal links & deep linking</a> 92 </li> 93 94 <li class=""> 95 <a href="https://www.getzola.org/documentation/content/table-of-contents/">Table of Contents</a> 96 </li> 97 98 <li class=""> 99 <a href="https://www.getzola.org/documentation/content/syntax-highlighting/">Syntax Highlighting</a> 100 </li> 101 102 <li class=""> 103 <a href="https://www.getzola.org/documentation/content/taxonomies/">Taxonomies</a> 104 </li> 105 106 <li class=""> 107 <a href="https://www.getzola.org/documentation/content/search/">Search</a> 108 </li> 109 110 <li class=""> 111 <a href="https://www.getzola.org/documentation/content/sass/">Sass</a> 112 </li> 113 114 <li class=""> 115 <a href="https://www.getzola.org/documentation/content/image-processing/">Image processing</a> 116 </li> 117 118 <li class=""> 119 <a href="https://www.getzola.org/documentation/content/multilingual/">Multilingual sites</a> 120 </li> 121 122 </ul> 123 </li> 124 125 126 <li>
127 <span class="documentation__sidebar__title">Templates</span> 128 <ul> 129 130 <li class=""> 131 <a href="https://www.getzola.org/documentation/templates/overview/">Overview</a> 132 </li> 133 134 <li class=""> 135 <a href="https://www.getzola.org/documentation/templates/pages-sections/">Sections and Pages</a> 136 </li> 137 138 <li class=""> 139 <a href="https://www.getzola.org/documentation/templates/pagination/">Pagination</a> 140 </li> 141 142 <li class=""> 143 <a href="https://www.getzola.org/documentation/templates/taxonomies/">Taxonomies</a> 144 </li> 145 146 <li class=""> 147 <a href="https://www.getzola.org/documentation/templates/feeds/">Feeds</a> 148 </li> 149 150 <li class=""> 151 <a href="https://www.getzola.org/documentation/templates/sitemap/">Sitemap</a> 152 </li> 153 154 <li class=""> 155 <a href="https://www.getzola.org/documentation/templates/robots/">Robots.txt</a> 156 </li> 157 158 <li class=""> 159 <a href="https://www.getzola.org/documentation/templates/404/">404 error page</a> 160 </li> 161 162 <li class=""> 163 <a href="https://www.getzola.org/documentation/templates/archive/">Archive</a> 164 </li> 165 166 </ul> 167 </li> 168 169 170 <li> 171 <span class="documentation__sidebar__title">Themes</span> 172 <ul> 173 174 <li class=""> 175 <a href="https://www.getzola.org/documentation/themes/overview/">Overview</a> 176 </li> 177 178 <li class=""> 179 <a href="https://www.getzola.org/documentation/themes/installing-and-using-themes/">Installing & using themes</a> 180 </li> 181 182 <li class=""> 183 <a href="https://www.getzola.org/documentation/themes/creating-a-theme/">Creating a theme</a> 184 </li> 185 186 <li class=""> 187 <a href="https://www.getzola.org/documentation/themes/extending-a-theme/">Customizing a theme</a> 188 </li> 189 190 </ul> 191 </li> 192 193 194 <li> 195 <span class="documentation__sidebar__title">Deployment</span> 196 <ul> 197 198 <li class=""> 199 <a href="https://www.getzola.org/documentation/deployment/overview/">Overview</a> 200 </li> 201 202 <li class=""> 203 <a href="https://www.getzola.org/documentation/deployment/sourcehut/">Sourcehut Pages</a> 204 </li> 205 206 <li class=""> 207 <a href="https://www.getzola.org/documentation/deployment/netlify/">Netlify</a> 208 </li> 209 210 <li class=""> 211 <a href="https://www.getzola.org/documentation/deployment/github-pages/">GitHub Pages</a> 212 </li> 213 214 <li class=""> 215 <a href="https://www.getzola.org/documentation/deployment/gitlab-pages/">GitLab Pages</a> 216 </li> 217 218 <li class=""> 219 <a href="https://www.getzola.org/documentation/deployment/codeberg-pages/">Codeberg Pages</a> 220 </li> 221 222 <li class=""> 223 <a href="https://www.getzola.org/documentation/deployment/edgio/">Edgio</a> 224 </li> 225 226 <li class=""> 227 <a href="https://www.getzola.org/documentation/deployment/vercel/">Vercel</a> 228 </li> 229 230 <li class=""> 231 <a href="https://www.getzola.org/documentation/deployment/zeabur/">Zeabur</a> 232 </li> 233 234 <li class=""> 235 <a href="https://www.getzola.org/documentation/deployment/azure-static-webapps/">Azure Static Web Apps</a> 236 </li> 237 238 <li class=""> 239 <a href="https://www.getzola.org/documentation/deployment/cloudflare-pages/">Cloudflare Pages</a> 240 </li> 241 242 <li class=""> 243 <a href="https://www.getzola.org/documentation/deployment/cloudflare-workers/">Cloudflare Workers</a> 244 </li> 245 246 <li class=""> 247 <a href="https://www.getzola.org/documentation/deployment/flyio/">Fly.io</a> 248 </li> 249 250 <li class=""> 251 <a href="https://www.getzola.org/documentation/deployment/aws-s3/">AWS S3 Bucket</a> 252 </li> 253 254 <li class=""> 255 <a href="https://www.getzola.org/documentation/deployment/docker-image/">Docker image</a> 256 </li> 257 258 </ul> 259 </li> 260 261 </ul> 262 </aside> 263 <div class="documentation__content"> 264 265 <h1>Internal links & deep linking</h1> 266 <h2 id="heading-id-and-anchor-insertion"><a class="zola-anchor" href="#heading-id-and-anchor-insertion" aria-label="Anchor link for: heading-id-and-anchor-insertion">ð</a>Heading id and anchor insertion</h2> 267<p>While rendering the Markdown content, a unique id will automatically be assigned to each heading.
268This id is created by converting the heading text to a <a class="external" rel="external" href="https://en.wikipedia.org/wiki/Semantic_URL#Slug">slug</a> if <code>slugify.anchors</code> is set to <code>"on"</code> (the default). 269If <code>slugify.paths</code> is set to <code>"safe"</code>, whitespaces are replaced by <code>-</code> and the following characters are stripped: <code>#</code>, <code>%</code>, <code><</code>, <code>></code>, <code>[</code>, <code>]</code>, <code>(</code>, <code>)</code>, `, <code>^</code>, <code>{</code>, <code>|</code>, <code>}</code>. 270If <code>slugify.paths</code> is set to <code>"off"</code>, no modifications are made, and you may be left with nominally illegal ids. 271A number is appended at the end if the slug already exists for that article. 272For example:</p> 273<pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;" ><code data-lang="markdown"><span class="giallo-l"><span style="color: #F38BA8;"># Something exciting! <- something-exciting</span></span> 274<span class="giallo-l"><span style="color: #FAB387;">## Example code <- example-code</span></span> 275<span class="giallo-l"></span> 276<span class="giallo-l"><span style="color: #F38BA8;"># Something else <- something-else</span></span> 277<span class="giallo-l"><span style="color: #FAB387;">## Example code <- example-code-1</span></span></code></pre> 278<p>You can also manually specify an id with a <code>{#â¦}</code> suffix on the heading line as well as CSS classes:</p> 279<pre class="giallo" style="color: #CDD6F4; background-color: #1E1E2E;" ><code data-lang="markdown"><span class="giallo-l"><span style="color: #F38BA8;"># Something manual! {#manual .header .bold}</span></span></code></pre> 280<p>This is useful for making deep links robust, either proactively (so that you can later change the text of a heading 281without breaking links to it) or retroactively (keeping the slug of the old header text when changing the text). It 282can also be useful for migration of existing sites with different header id schemes, so that you can keep deep 283links working.</p> 284<h2 id="anchor-insertion"><a class="zola-anchor" href="#anchor-insertion" aria-label="Anchor link for: anchor-insertion">ð</a>Anchor insertion</h2> 285<p>It is possible to have Zola automatically insert anchor links next to the heading, as you can see on this documentation 286if you hover a title or covering the full heading text.</p> 287<p>This option is set in the global <a href="https://www.getzola.org/documentation/getting-started/configuration/"><code>zola.toml</code></a>'s <code>[markdown]</code> section and can be overridden at the section level with the <code>insert_anchor_links</code> variable on the 288<a href="https://www.getzola.org/documentation/content/section/#front-matter">section front matter page</a>.</p> 289<p>The default template is very basic and will need CSS tweaks in your project to look decent. 290If you want to change the anchor template, it can be easily overwritten by 291creating an <code>anchor-link.html</code> file in the <code>templates</code> directory. <a class="external" rel="external" href="https://github.com/getzola/zola/blob/master/components/templates/src/builtins/anchor-link.html">Here</a> you can find the default template.</p> 292<p>The anchor link template has the following variables:</p> 293<ul> 294<li><code>id</code>: the heading's id after applying the rules defined by <code>slugify.anchors</code></li> 295<li><code>lang</code>: the current language, unless called from the <code>markdown</code> template filter, in which case it will always be <code>en</code></li> 296<li><code>level</code>: the heading level (between 1 and 6)</li> 297</ul> 298<p>If you use <code>insert_anchor_links = "heading"</code>, the template will still be used but only the opening <code><a></code> tag will get extracted 299from it, everything else will not be used.</p> 300<h2 id="internal-links"><a class="zola-anchor" href="#internal-links" aria-label="Anchor link for: internal-links">ð</a>Internal links</h2> 301<p>Linking to other pages and their headings is so common that Zola adds a 302special syntax to Markdown links to handle them: start the link with <code>@/</code> and point to the <code>.md</code> file you want 303to link to. The path to the file starts from the <code>content</code> directory.</p> 304<p>For example, linking to a file located at <code>content/pages/about.md</code> would be <code>[my link](@/pages/about.md)</code>. 305You can still link to an anchor directly; <code>[my link](@/pages/about.md#example)</code> will work as expected.</p> 306<p>The <code>@/</code> syntax also resolves <a href="https://www.getzola.org/documentation/content/overview/#asset-colocation">colocated assets</a>.</p> 307<p>By default, broken internal links are treated as errors. To treat them as warnings instead, visit the <code>[link_checker]</code> section of <code>zola.toml</code> and set <code>internal_level = "warn"</code>. Note: treating broken links as warnings allows the site to be built with broken links intact, so a link such as <code>[my link](@/pages/whoops.md)</code> will be rendered to HTML as <code><a href="@/pages/whoops.md"></code>.</p> 308 309 310 </div> 311</div> 312 313 </div> 314 <footer> 315 ©2017-2026 â <a class="white" href="https://www.vincentprouillet.com">Vincent Prouillet</a> and <a class="white" href="https://github.com/getzola/zola/graphs/contributors">contributors</a> 316 </footer> 317 318
318<script type="text/javascript" src="https://www.getzola.org/elasticlunr.min.js"></script>
318 319
319<script type="text/javascript" src="https://www.getzola.org/search.js"></script>
319 320 </body> 321</html>
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.