Use @/ for internal links rather than ./

Close #686

CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Breaking
 
 - Allow specifying heading IDs. It is a breaking change in the unlikely case you are using `{#..}` in your heading
+- Internal links are now starting by `@/` rather than `./` to avoid confusion with relative links
 
 ### Other
 

components/rendering/src/markdown.rs

@@ -71,10 +71,10 @@ fn fix_link(link_type: LinkType, link: &str, context: &RenderContext, external_l
         return Ok(link.to_string());
     }
     // A few situations here:
-    // - it could be a relative link (starting with `./`)
+    // - it could be a relative link (starting with `@/`)
     // - it could be a link to a co-located asset
     // - it could be a normal link
-    let result = if link.starts_with("./") {
+    let result = if link.starts_with("@/") {
         match resolve_internal_link(&link, context.permalinks) {
             Ok(url) => url,
             Err(_) => {
@@ -296,7 +296,7 @@ pub fn markdown_to_html(content: &str, context: &RenderContext) -> Result<Render
             summary_len: if has_summary { html.find(CONTINUE_READING) } else { None },
             body: html,
             toc: make_table_of_contents(headers),
-            external_links: external_links,
+            external_links,
         })
     }
 }

components/rendering/tests/markdown.rs

@@ -299,7 +299,7 @@ fn can_make_valid_relative_link() {
     let config = Config::default();
     let context = RenderContext::new(&tera_ctx, &config, "", &permalinks, InsertAnchor::None);
     let res = render_content(
-        r#"[rel link](./pages/about.md), [abs link](https://vincent.is/about)"#,
+        r#"[rel link](@/pages/about.md), [abs link](https://vincent.is/about)"#,
         &context,
     )
     .unwrap();
@@ -316,7 +316,7 @@ fn can_make_relative_links_with_anchors() {
     let tera_ctx = Tera::default();
     let config = Config::default();
     let context = RenderContext::new(&tera_ctx, &config, "", &permalinks, InsertAnchor::None);
-    let res = render_content(r#"[rel link](./pages/about.md#cv)"#, &context).unwrap();
+    let res = render_content(r#"[rel link](@/pages/about.md#cv)"#, &context).unwrap();
 
     assert!(res.body.contains(r#"<p><a href="https://vincent.is/about#cv">rel link</a></p>"#));
 }
@@ -327,7 +327,7 @@ fn errors_relative_link_inexistant() {
     let permalinks_ctx = HashMap::new();
     let config = Config::default();
     let context = RenderContext::new(&tera_ctx, &config, "", &permalinks_ctx, InsertAnchor::None);
-    let res = render_content("[rel link](./pages/about.md)", &context);
+    let res = render_content("[rel link](@/pages/about.md)", &context);
     assert!(res.is_err());
 }
 
@@ -623,7 +623,7 @@ fn can_make_valid_relative_link_in_header() {
     let tera_ctx = Tera::default();
     let config = Config::default();
     let context = RenderContext::new(&tera_ctx, &config, "", &permalinks, InsertAnchor::None);
-    let res = render_content(r#" # [rel link](./pages/about.md)"#, &context).unwrap();
+    let res = render_content(r#" # [rel link](@/pages/about.md)"#, &context).unwrap();
 
     assert_eq!(
         res.body,

components/templates/src/global_fns/mod.rs

@@ -60,7 +60,7 @@ impl TeraFn for GetUrl {
             args.get("path"),
             "`get_url` requires a `path` argument with a string value"
         );
-        if path.starts_with("./") {
+        if path.starts_with("@/") {
             match resolve_internal_link(&path, &self.permalinks) {
                 Ok(url) => Ok(to_value(url).unwrap()),
                 Err(_) => {

components/utils/src/site.rs

@@ -15,7 +15,7 @@ pub fn get_reading_analytics(content: &str) -> (usize, usize) {
 /// Resolves an internal link (of the `./posts/something.md#hey` sort) to its absolute link
 pub fn resolve_internal_link(link: &str, permalinks: &HashMap<String, String>) -> Result<String> {
     // First we remove the ./ since that's zola specific
-    let clean_link = link.replacen("./", "", 1);
+    let clean_link = link.replacen("@/", "", 1);
     // Then we remove any potential anchor
     // parts[0] will be the file path and parts[1] the anchor if present
     let parts = clean_link.split('#').collect::<Vec<_>>();
@@ -41,7 +41,7 @@ mod tests {
     fn can_resolve_valid_internal_link() {
         let mut permalinks = HashMap::new();
         permalinks.insert("pages/about.md".to_string(), "https://vincent.is/about".to_string());
-        let res = resolve_internal_link("./pages/about.md", &permalinks).unwrap();
+        let res = resolve_internal_link("@/pages/about.md", &permalinks).unwrap();
         assert_eq!(res, "https://vincent.is/about");
     }
 
@@ -49,7 +49,7 @@ mod tests {
     fn can_resolve_valid_root_internal_link() {
         let mut permalinks = HashMap::new();
         permalinks.insert("about.md".to_string(), "https://vincent.is/about".to_string());
-        let res = resolve_internal_link("./about.md", &permalinks).unwrap();
+        let res = resolve_internal_link("@/about.md", &permalinks).unwrap();
         assert_eq!(res, "https://vincent.is/about");
     }
 
@@ -57,13 +57,13 @@ mod tests {
     fn can_resolve_internal_links_with_anchors() {
         let mut permalinks = HashMap::new();
         permalinks.insert("pages/about.md".to_string(), "https://vincent.is/about".to_string());
-        let res = resolve_internal_link("./pages/about.md#hello", &permalinks).unwrap();
+        let res = resolve_internal_link("@/pages/about.md#hello", &permalinks).unwrap();
         assert_eq!(res, "https://vincent.is/about#hello");
     }
 
     #[test]
     fn errors_resolve_inexistant_internal_link() {
-        let res = resolve_internal_link("./pages/about.md#hello", &HashMap::new());
+        let res = resolve_internal_link("@/pages/about.md#hello", &HashMap::new());
         assert!(res.is_err());
     }
 

docs/content/documentation/content/image-processing/index.md

@@ -14,7 +14,7 @@ resize_image(path, width, height, op, quality)
 
 ### Arguments
 
-- `path`: The path to the source image relative to the `content` directory in the [directory structure](./documentation/getting-started/directory-structure.md).
+- `path`: The path to the source image relative to the `content` directory in the [directory structure](@/documentation/getting-started/directory-structure.md).
 - `width` and `height`: The dimensions in pixels of the resized image. Usage depends on the `op` argument.
 - `op` (_optional_): Resize operation. This can be one of:
     - `"scale"`
@@ -97,8 +97,8 @@ The source for all examples is this 300 × 380 pixels image:
 
 ## Using `resize_image` in markdown via shortcodes
 
-`resize_image` is a built-in Tera global function (see the [Templates](./documentation/templates/_index.md) chapter),
+`resize_image` is a built-in Tera global function (see the [Templates](@/documentation/templates/_index.md) chapter),
-but it can be used in markdown, too, using [Shortcodes](./documentation/content/shortcodes.md).
+but it can be used in markdown, too, using [Shortcodes](@/documentation/content/shortcodes.md).
 
 The examples above were generated using a shortcode file named `resize_image.html` with this content:
 
@@ -110,9 +110,9 @@ The examples above were generated using a shortcode file named `resize_image.htm
 
 The `resize_image()` can be used multiple times and/or in loops. It is designed to handle this efficiently.
 
-This can be used along with `assets` [page metadata](./documentation/templates/pages-sections.md) to create picture galleries.
+This can be used along with `assets` [page metadata](@/documentation/templates/pages-sections.md) to create picture galleries.
 The `assets` variable holds paths to all assets in the directory of a page with resources
-(see [assets colocation](./documentation/content/overview.md#assets-colocation)): if you have files other than images you
+(see [assets colocation](@/documentation/content/overview.md#assets-colocation)): if you have files other than images you
 will need to filter them out in the loop first like in the example below.
 
 This can be used in shortcodes. For example, we can create a very simple html-only clickable

docs/content/documentation/content/linking.md

@@ -29,7 +29,7 @@ It is possible to have Zola automatically insert anchor links next to the header
 reading if you hover a title.
 
 This option is set at the section level: the `insert_anchor_links` variable on the
-[Section front-matter page](./documentation/content/section.md#front-matter).
+[Section front-matter page](@/documentation/content/section.md#front-matter).
 
 The default template is very basic and will need CSS tweaks in your project to look decent.
 If you want to change the anchor template, it can easily be overwritten by
@@ -37,8 +37,8 @@ creating a `anchor-link.html` file in the `templates` directory.
 
 ## Internal links
 Linking to other pages and their headers is so common that Zola adds a
-special syntax to Markdown links to handle them: start the link with `./` and point to the `.md` file you want
+special syntax to Markdown links to handle them: start the link with `@/` and point to the `.md` file you want
 to link to. The path to the file starts from the `content` directory.
 
-For example, linking to a file located at `content/pages/about.md` would be `[my link](./pages/about.md)`.
+For example, linking to a file located at `content/pages/about.md` would be `[my link](@/pages/about.md)`.
-You can still link to a header directly: `[my link](./pages/about.md#example)` will work as expected.
+You can still link to a header directly: `[my link](@/pages/about.md#example)` will work as expected.

docs/content/documentation/content/overview.md

@@ -5,8 +5,8 @@ weight = 10
 
 
 Zola uses the folder structure to determine the site structure.
-Each folder in the `content` directory represents a [section](./documentation/content/section.md)
+Each folder in the `content` directory represents a [section](@/documentation/content/section.md)
-that contains [pages](./documentation/content/page.md): your `.md` files.
+that contains [pages](@/documentation/content/page.md): your `.md` files.
 
 ```bash
 .
@@ -24,7 +24,7 @@ that contains [pages](./documentation/content/page.md): your `.md` files.
 ```
 
 Each page path (the part after the `base_url`, for example `blog/cli-usage/`) can be customised by changing the `path` or `slug`
-attribute of the [page front-matter](./documentation/content/page.md#front-matter).
+attribute of the [page front-matter](@/documentation/content/page.md#front-matter).
 
 You might have noticed a file named `_index.md` in the example above.
 This file is used to store both metadata and content of the section itself and is not considered a page.
@@ -70,7 +70,7 @@ By default, this page will get the folder name as its slug. So its permalink wou
 ### Excluding files from assets
 
 It is possible to ignore selected asset files using the
-[ignored_content](./documentation/getting-started/configuration.md) setting in the config file.
+[ignored_content](@/documentation/getting-started/configuration.md) setting in the config file.
 For example, say you have an Excel spreadsheet from which you are taking several screenshots and
 then linking to those image files on your website. For maintainability purposes, you want to keep
 the spreadsheet in the same folder as the markdown, but you don't want to copy the spreadsheet to

docs/content/documentation/content/page.md

@@ -25,7 +25,7 @@ character in a filename on Windows.
 As you can see, creating an `about.md` file is exactly equivalent to creating an
 `about/index.md` file.  The only difference between the two methods is that creating
 the `about` folder allows you to use asset colocation, as discussed in the
-[Overview](./documentation/content/overview.md#assets-colocation) section of this documentation.
+[Overview](@/documentation/content/overview.md#assets-colocation) section of this documentation.
 
 ## Front-matter
 
@@ -100,7 +100,7 @@ paragraph of each page in a list for example.
 To do so, add <code>&lt;!-- more --&gt;</code> in your content at the point
 where you want the summary to end and the content up to that point will be also
 available separately in the
-[template](./documentation/templates/pages-sections.md#page-variables).
+[template](@/documentation/templates/pages-sections.md#page-variables).
 
 An anchor link to this position named `continue-reading` is created, wrapped in a paragraph
 with a `zola-continue-reading` id, so you can link directly to it if needed for example:

docs/content/documentation/content/section.md

@@ -14,7 +14,7 @@ not have any content or metadata.  If you would like to add content or metadata,
 `_index.md` file at the root of the `content` folder and edit it just as you would edit any other
 `_index.md` file; your `index.html` template will then have access to that content and metadata.
 
-Any non-Markdown file in the section folder is added to the `assets` collection of the section, as explained in the [Content Overview](./documentation/content/overview.md#assets-colocation). These files are then available from the Markdown using relative links.
+Any non-Markdown file in the section folder is added to the `assets` collection of the section, as explained in the [Content Overview](@/documentation/content/overview.md#assets-colocation). These files are then available from the Markdown using relative links.
 
 ## Front-matter
 
@@ -101,7 +101,7 @@ Keep in mind that any configuration apply only to the direct pages, not to the s
 ## Pagination
 
 To enable pagination for a section's pages, simply set `paginate_by` to a positive number and it will automatically
-paginate by this much. See [pagination template documentation](./documentation/templates/pagination.md) for more information
+paginate by this much. See [pagination template documentation](@/documentation/templates/pagination.md) for more information
 on what will be available in the template.
 
 You can also change the pagination path (the word displayed while paginated in the URL, like `page/1`)

docs/content/documentation/content/syntax-highlighting.md

@@ -4,7 +4,7 @@ weight = 80
 +++
 
 Zola comes with built-in syntax highlighting but you first
-need to enable it in the [configuration](./documentation/getting-started/configuration.md).
+need to enable it in the [configuration](@/documentation/getting-started/configuration.md).
 
 Once this is done, Zola will automatically highlight all code blocks
 in your content. A code block in Markdown looks like the following:

docs/content/documentation/content/table-of-contents.md

@@ -6,7 +6,7 @@ weight = 60
 Each page/section will automatically generate a table of contents for itself based on the headers present.
 
 It is available in the template through the `toc` variable.
-You can view the [template variables](./documentation/templates/pages-sections.md#table-of-contents)
+You can view the [template variables](@/documentation/templates/pages-sections.md#table-of-contents)
 documentation for information on its structure.
 
 Here is an example of using that field to render a 2-level table of contents:

docs/content/documentation/content/taxonomies.md

@@ -5,7 +5,7 @@ weight = 90
 
 Zola has built-in support for taxonomies.
 
-The first step is to define the taxonomies in your [config.toml](./documentation/getting-started/configuration.md).
+The first step is to define the taxonomies in your [config.toml](@/documentation/getting-started/configuration.md).
 
 A taxonomy has 5 variables:
 

docs/content/documentation/getting-started/directory-structure.md

@@ -22,14 +22,14 @@ Here's a high level overview of each of these folders and `config.toml`.
 
 ## `config.toml`
 A mandatory configuration file of Zola in TOML format.
-It is explained in details in the [Configuration page](./documentation/getting-started/configuration.md).
+It is explained in details in the [Configuration page](@/documentation/getting-started/configuration.md).
 
 ## `content`
 Where all your markup content lies: this will be mostly comprised of `.md` files.
-Each folder in the `content` directory represents a [section](./documentation/content/section.md)
+Each folder in the `content` directory represents a [section](@/documentation/content/section.md)
-that contains [pages](./documentation/content/page.md) : your `.md` files.
+that contains [pages](@/documentation/content/page.md) : your `.md` files.
 
-To learn more, read [the content overview](./documentation/content/overview.md).
+To learn more, read [the content overview](@/documentation/content/overview.md).
 
 ## `sass`
 Contains the [Sass](http://sass-lang.com) files to be compiled. Non-Sass files will be ignored.
@@ -41,9 +41,9 @@ Contains any kind of files. All the files/folders in the `static` folder will be
 
 ## `templates`
 Contains all the [Tera](https://tera.netlify.com) templates that will be used to render this site.
-Have a look at the [Templates](./documentation/templates/_index.md) to learn more about default templates
+Have a look at the [Templates](@/documentation/templates/_index.md) to learn more about default templates
 and available variables.
 
 ## `themes`
 Contains themes that can be used for that site. If you are not planning to use themes, leave this folder empty.
-If you want to learn about themes, head to the [themes documentation](./documentation/themes/_index.md).
+If you want to learn about themes, head to the [themes documentation](@/documentation/themes/_index.md).

docs/content/documentation/templates/overview.md

@@ -15,7 +15,7 @@ to print the whole context.
 
 A few variables are available on all templates minus RSS and sitemap:
 
-- `config`: the [configuration](./documentation/getting-started/configuration.md) without any modifications
+- `config`: the [configuration](@/documentation/getting-started/configuration.md) without any modifications
 - `current_path`: the path (full URL without the `base_url`) of the current page, never starting with a `/`
 - `current_url`: the full URL for that page
 - `lang`: the language for that page, `null` if the page/section doesn't have a language set
@@ -105,11 +105,11 @@ If you only need the metadata of the section, you can pass `metadata_only=true`
 
 ### ` get_url`
 Gets the permalink for the given path.
-If the path starts with `./`, it will be understood as an internal
+If the path starts with `@/`, it will be understood as an internal
-link like the ones used in markdown.
+link like the ones used in markdown, starting from the root `content` directory.
 
 ```jinja2
-{% set url = get_url(path="./blog/_index.md") %}
+{% set url = get_url(path="@/blog/_index.md") %}
 ```
 
 This can also be used to get the permalinks for static assets for example if
@@ -230,4 +230,4 @@ Gets the translation of the given `key`, for the `default_language` or the `lang
 
 ### `resize_image`
 Resizes an image file.
-Pease refer to [_Content / Image Processing_](./documentation/content/image-processing/index.md) for complete documentation.
+Pease refer to [_Content / Image Processing_](@/documentation/content/image-processing/index.md) for complete documentation.

docs/content/documentation/templates/pagination.md

@@ -32,7 +32,7 @@ current_index: Number;
 ## Section
 
 A paginated section gets the same `section` variable as a normal
-[section page](./documentation/templates/pages-sections.md#section-variables) minus its pages.
+[section page](@/documentation/templates/pages-sections.md#section-variables) minus its pages.
 
 ## Taxonomy term
 
@@ -41,4 +41,4 @@ A paginated taxonomy gets two variables:
 - a `taxonomy` variable of type `TaxonomyConfig`
 - a `term` variable of type `TaxonomyTerm`.
 
-See the [taxonomies page](./documentation/templates/taxonomies.md) for a detailed version of the types.
+See the [taxonomies page](@/documentation/templates/taxonomies.md) for a detailed version of the types.

docs/content/documentation/templates/rss.md

@@ -13,5 +13,5 @@ directory or, if one does not exist, will use the use the built-in rss template.
 The RSS template gets two variables in addition of the config:
 
 - `last_build_date`: the date of the latest post
-- `pages`: see [the page variables](./documentation/templates/pages-sections.md#page-variables) for
+- `pages`: see [the page variables](@/documentation/templates/pages-sections.md#page-variables) for
 a detailed description of what this contains

docs/content/documentation/templates/taxonomies.md

@@ -60,5 +60,5 @@ current_path: String;
 term: TaxonomyTerm;
 ```
 
-A paginated taxonomy term will also get a `paginator` variable, see the [pagination page](./documentation/templates/pagination.md)
+A paginated taxonomy term will also get a `paginator` variable, see the [pagination page](@/documentation/templates/pagination.md)
 for more details on that.

docs/content/documentation/themes/creating-a-theme.md

@@ -58,7 +58,7 @@ Theme templates should use [macros](https://tera.netlify.com/docs/templates/#mac
 
 ## Submitting a theme to the gallery
 
-If you want your theme to be featured in the [themes](./themes/_index.md) section
+If you want your theme to be featured in the [themes](@/themes/_index.md) section
 of this site, the theme will require two more things:
 
 - `screenshot.png`: a screenshot of the theme in action with a max size of around 2000x1000

docs/content/documentation/themes/installing-and-using-themes.md

@@ -18,13 +18,13 @@ Cloning the repository using Git or another VCS will allow you to easily
 update it but you can also simply download the files manually and paste
 them in a folder.
 
-You can find a list of themes [on this very website](./themes/_index.md).
+You can find a list of themes [on this very website](@/themes/_index.md).
 
 ## Using a theme
 
 Now that you have the theme in your `themes` directory, you only need to tell
 Zola to use it to get started by setting the `theme` variable of the
-[configuration file](./documentation/getting-started/configuration.md). The theme
+[configuration file](@/documentation/getting-started/configuration.md). The theme
 name has to be name of the directory you cloned the theme in.
 For example, if you cloned a theme in `themes/simple-blog`, the theme name to use
 in the configuration file is `simple-blog`.
@@ -52,7 +52,7 @@ Some custom data
 ```
 
 Most themes will also provide some variables that are meant to be overriden: this happens in the `extra` section
-of the [configuration file](./documentation/getting-started/configuration.md).
+of the [configuration file](@/documentation/getting-started/configuration.md).
 Let's say a theme uses a `show_twitter` variable and sets it to `false` by default. If you want to set it to `true`,
 you can update your `config.toml` like so:
 

docs/content/documentation/themes/overview.md

@@ -8,5 +8,5 @@ but still easy to update if needed.
 
 All themes can use the full power of Zola, from shortcodes to Sass compilation.
 
-A list of themes is available [on this very website](./themes/_index.md).
+A list of themes is available [on this very website](@/themes/_index.md).
 

docs/templates/index.html

@@ -15,8 +15,8 @@
         <header>
             <nav class="{% block extra_nav_class %}container{% endblock extra_nav_class %}">
                 <a class="header__logo white" href="{{ config.base_url }}">Zola</a>
-                <a class="white" href="{{ get_url(path="./documentation/_index.md") }}" class="nav-link">Docs</a>
+                <a class="white" href="{{ get_url(path="@/documentation/_index.md") }}" class="nav-link">Docs</a>
-                <a class="white" href="{{ get_url(path="./themes/_index.md") }}" class="nav-link">Themes</a>
+                <a class="white" href="{{ get_url(path="@/themes/_index.md") }}" class="nav-link">Themes</a>
                 <a class="white" href="https://zola.discourse.group/" class="nav-link">Forum</a>
                 <a class="white" href="https://github.com/getzola/zola" class="nav-link">GitHub</a>
 
@@ -37,7 +37,7 @@
                     <p class="hero__tagline">
                         Forget dependencies. Everything you need in one binary.
                     </p>
-                    <a href="{{ get_url(path="./documentation/_index.md") }}" class="button">Get started</a>
+                    <a href="{{ get_url(path="@/documentation/_index.md") }}" class="button">Get started</a>
                 </div>
 
                 <div class="inverted-colours selling-points">
@@ -73,7 +73,7 @@
                             <p>
                                 From the CLI to the template engine, everything is designed to be intuitive.
                                 Don't take my words for it though, look at the
-                                <a href="{{ get_url(path="./documentation/_index.md") }}">documentation</a> and see for yourself.
+                                <a href="{{ get_url(path="@/documentation/_index.md") }}">documentation</a> and see for yourself.
                             </p>
                         </div>
 
@@ -88,8 +88,8 @@
                         <div class="selling-point">
                             <h2>Augmented Markdown</h2>
                             <p>
-                                Zola comes with <a href="{{ get_url(path="./documentation/content/shortcodes.md") }}">shortcodes</a> and
+                                Zola comes with <a href="{{ get_url(path="@/documentation/content/shortcodes.md") }}">shortcodes</a> and
-                                <a href="{{ get_url(path="./documentation/content/linking.md") }}">internal links</a>
+                                <a href="{{ get_url(path="@/documentation/content/linking.md") }}">internal links</a>
                                 to make it easier to write your content.
                             </p>
                         </div>

test_site/content/posts/draft.md

@@ -7,4 +7,4 @@ date = 2016-03-01
 
 {{ theme_shortcode() }}
 
-Link to [root](./hello.md).
+Link to [root](@/hello.md).