diff --git a/CHANGELOG.md b/CHANGELOG.md index fd0ce85b..6ea884ce 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/components/rendering/src/markdown.rs b/components/rendering/src/markdown.rs index 8843e8ff..ce622bfb 100644 --- a/components/rendering/src/markdown.rs +++ b/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) -> Resultrel link

"#)); } @@ -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, diff --git a/components/templates/src/global_fns/mod.rs b/components/templates/src/global_fns/mod.rs index cc347404..16a8a1eb 100644 --- a/components/templates/src/global_fns/mod.rs +++ b/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(_) => { diff --git a/components/utils/src/site.rs b/components/utils/src/site.rs index d89babe3..90f2ef84 100644 --- a/components/utils/src/site.rs +++ b/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) -> Result { // 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::>(); @@ -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()); } diff --git a/docs/content/documentation/content/image-processing/index.md b/docs/content/documentation/content/image-processing/index.md index 53958e74..697cbe02 100644 --- a/docs/content/documentation/content/image-processing/index.md +++ b/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), -but it can be used in markdown, too, using [Shortcodes](./documentation/content/shortcodes.md). +`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). 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 diff --git a/docs/content/documentation/content/linking.md b/docs/content/documentation/content/linking.md index 25732f29..98487a39 100644 --- a/docs/content/documentation/content/linking.md +++ b/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)`. -You can still link to a header directly: `[my link](./pages/about.md#example)` will work as expected. +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. diff --git a/docs/content/documentation/content/overview.md b/docs/content/documentation/content/overview.md index c5a0daa3..16a5092f 100644 --- a/docs/content/documentation/content/overview.md +++ b/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) -that contains [pages](./documentation/content/page.md): your `.md` files. +Each folder in the `content` directory represents a [section](@/documentation/content/section.md) +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 diff --git a/docs/content/documentation/content/page.md b/docs/content/documentation/content/page.md index fef7f3a4..c1ab2766 100644 --- a/docs/content/documentation/content/page.md +++ b/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 <!-- more --> 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: diff --git a/docs/content/documentation/content/section.md b/docs/content/documentation/content/section.md index ec3669a9..1fa18c7c 100644 --- a/docs/content/documentation/content/section.md +++ b/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`) diff --git a/docs/content/documentation/content/syntax-highlighting.md b/docs/content/documentation/content/syntax-highlighting.md index 1cb5f173..f3d97e99 100644 --- a/docs/content/documentation/content/syntax-highlighting.md +++ b/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: diff --git a/docs/content/documentation/content/table-of-contents.md b/docs/content/documentation/content/table-of-contents.md index e93c9c00..5d2b35c2 100644 --- a/docs/content/documentation/content/table-of-contents.md +++ b/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: diff --git a/docs/content/documentation/content/taxonomies.md b/docs/content/documentation/content/taxonomies.md index b446fa0c..8b79cf0c 100644 --- a/docs/content/documentation/content/taxonomies.md +++ b/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: diff --git a/docs/content/documentation/getting-started/directory-structure.md b/docs/content/documentation/getting-started/directory-structure.md index 41a216ad..015fa6ed 100644 --- a/docs/content/documentation/getting-started/directory-structure.md +++ b/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) -that contains [pages](./documentation/content/page.md) : your `.md` files. +Each folder in the `content` directory represents a [section](@/documentation/content/section.md) +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). diff --git a/docs/content/documentation/templates/overview.md b/docs/content/documentation/templates/overview.md index cc827fd7..bd0df029 100644 --- a/docs/content/documentation/templates/overview.md +++ b/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 -link like the ones used in markdown. +If the path starts with `@/`, it will be understood as an internal +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. diff --git a/docs/content/documentation/templates/pagination.md b/docs/content/documentation/templates/pagination.md index df8736f2..c6fda401 100644 --- a/docs/content/documentation/templates/pagination.md +++ b/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. diff --git a/docs/content/documentation/templates/rss.md b/docs/content/documentation/templates/rss.md index c9117f0b..6212f792 100644 --- a/docs/content/documentation/templates/rss.md +++ b/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 diff --git a/docs/content/documentation/templates/taxonomies.md b/docs/content/documentation/templates/taxonomies.md index 3012c36b..b901a3df 100644 --- a/docs/content/documentation/templates/taxonomies.md +++ b/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. diff --git a/docs/content/documentation/themes/creating-a-theme.md b/docs/content/documentation/themes/creating-a-theme.md index e42b03fb..c043649a 100644 --- a/docs/content/documentation/themes/creating-a-theme.md +++ b/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 diff --git a/docs/content/documentation/themes/installing-and-using-themes.md b/docs/content/documentation/themes/installing-and-using-themes.md index 3205eb8c..f7552d9f 100644 --- a/docs/content/documentation/themes/installing-and-using-themes.md +++ b/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: diff --git a/docs/content/documentation/themes/overview.md b/docs/content/documentation/themes/overview.md index 4d808460..46abeb34 100644 --- a/docs/content/documentation/themes/overview.md +++ b/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). diff --git a/docs/templates/index.html b/docs/templates/index.html index c950bfb3..a5117908 100644 --- a/docs/templates/index.html +++ b/docs/templates/index.html @@ -15,8 +15,8 @@