From 38e13302458cc3266b3fc12e480e50ed09fa2a20 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabr=C3=ADcio=20Zimmerer=20Murta?= Date: Thu, 30 Sep 2021 00:04:07 -0300 Subject: [PATCH 1/4] Begins draft for the "linking" guide. --- guides/linking.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 guides/linking.md diff --git a/guides/linking.md b/guides/linking.md new file mode 100644 index 000000000..5b31cf910 --- /dev/null +++ b/guides/linking.md @@ -0,0 +1,42 @@ +--- +icon: link +--- + +# Linking + +When Retype builds your pages it transforms the address for the input markdown files into HTML pages as follows: + +`articles/my_article.md` => `articles/my_article/index.html` + +At the same time, it also analyzes markdown links and transform them accordingly. This article will explain how linking works in different scenarios and components. + +## Markdown links + +Linking using markdown is basically via the simple link syntax (`[]()`) but there are also the [**reference link** component](/components/reference-link.md), the [file download component](/components/file-download.md), and the [image component](/components/image.md). + +### Usual markdown links + +```md +[home](/readme.md) +``` + +- supports .md +- supports .html +- supports no extension at all +- tries its best to guess + +## URL Tokens + +### Circumflex URL Token + +### Tilde URL Token + +## Raw HTML links + +- does not change links +- understand how retype transform paths +- still replaces tokens + +## Examples + +All links working for the retype.com website \ No newline at end of file From 095c98e868606d9a7c17ff2a224387a77cc15161 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabr=C3=ADcio=20Zimmerer=20Murta?= Date: Wed, 6 Oct 2021 00:33:13 -0300 Subject: [PATCH 2/4] Expands on the linking article. In the plan, only the "other components" section is pending changes. --- guides/linking.md | 244 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 226 insertions(+), 18 deletions(-) diff --git a/guides/linking.md b/guides/linking.md index 5b31cf910..6f95cbb6b 100644 --- a/guides/linking.md +++ b/guides/linking.md @@ -4,39 +4,247 @@ icon: link # Linking -When Retype builds your pages it transforms the address for the input markdown files into HTML pages as follows: +When Retype builds your pages it transforms input path into website links like this: `articles/my_article.md` => `articles/my_article/index.html` -At the same time, it also analyzes markdown links and transform them accordingly. This article will explain how linking works in different scenarios and components. +Which is accessed by simply `articles/my_article/`. -## Markdown links +Because of this, Retype also transforms links to .md files within the project when they are composed using the link markdown `[text](link)`. -Linking using markdown is basically via the simple link syntax (`[]()`) but there are also the [**reference link** component](/components/reference-link.md), the [file download component](/components/file-download.md), and the [image component](/components/image.md). +!!! Handle the links yourself +If control is needed over the address, using [raw HTML links](#raw-html-links) should be the way to go. +!!! -### Usual markdown links +## Markdown linking -```md -[home](/readme.md) -``` +The examples below illustrate how markdown links are transformed during Retype Build -- supports .md -- supports .html -- supports no extension at all -- tries its best to guess +!!! +For effect of the examples below, we assume the edited file is the source of this page itself, that is, `guides/linking.md` in the project's input directory. +!!! +=== Examples + +**Markdown:** `[Home](/README.md)` \ +**Output:** [Home](/README.md) \ +**Link:** `/` + +**Markdown:** `[FAQ](/FAQ.md)` \ +**Output:** [FAQ](/FAQ.md) \ +**Link:** `/faq/` + +**Markdown:** `[Formatting](formatting.md)` \ +**Output:** [Formatting](formatting.md) \ +**Link:** `../formatting/` + +**Markdown:** `[Here](linking.md)` \ +**Output:** [Here](linking.md) \ +**Link:** (empty) + +**Markdown:** `[../guides/Here](../guides/linking.md)` \ +**Output:** [../guides/Here](../guides/linking.md) \ +**Link:** (empty) + +**Markdown:** `[/guides/Here](/guides/linking.md)` \ +**Output:** [/guides/Here](/guides/linking.md) \ +**Link:** `/guides/linking/` + +**Markdown:** `[Back to top](#linking)` \ +**Output:** [Back to top](#linking) \ +**Link:** `#linking` + +**Markdown:** `[Alert Component (relative)](../components/alert.md)` \ +**Output:** [Alert Component (relative)](../components/alert.md) \ +**Link:** `../../components/alert/` + +**Markdown:** `[Alert Component (absolute)](/components/alert.md)` \ +**Output:** [Alert Component (absolute)](/components/alert.md) \ +**Link:** `/components/alert/` + +**Markdown:** `[Alert variants (anchor)](../components/alert.md#variants)` \ +**Output:** [Alert variants (anchor)](../components/alert.md#variants) \ +**Link:** `../../components/alert/#variants` + +**Markdown:** `[No `.md` extension](formatting)` \ +**Output:** [No `.md` extension](formatting) \ +**Link:** `../formatting/` + +**Markdown:** `[Link to HTML output](../formatting/index.html)` \ +**Output:** [Link to HTML output](../formatting/index.html) \ +**Link:** `../formatting/` \ +**Notes:** Retype is able to tell the link refers to `/guides/formatting.md`, but displays a warning saying "consider revising URL to a proper input path". + +=== + +### Invalid links + +If a link points within the retype website -and- no .md file matches it, retype won't transform it. + +=== Examples + +**Markdown:** `[Broken link](no-page-here.md)` \ +**Output:** [Broken link](no-page-here.md) \ +**Link:** `no-page-here.md` + +**Markdown:** `[Relative Broken link](../components/no-page-here.md)` \ +**Output:** [Relative Broken link](../components/no-page-here.md) \ +**Link:** `../components/no-page-here.md`\ +**Notes:** The link to an upper level folder will still point within `guides/`. + +**Markdown:** `[Broken link to .html](not-exiting-page.html)` \ +**Output:** [Broken link to .html](not-exiting-page.html) \ +**Link:** `not-existing-page.html` + +**Markdown:** `[Alert (broken anchor)](../components/alert.md#invalid-anchor)` \ +**Output:** [Alert (broken anchor)](../components/alert.md#invalid-anchor) \ +**Link:** `../../components/alert/#invalid-anchor` \ +**Notes:** An invalid anchor still allows the page itself to be resolved, but the anchor will be kept. + +=== + +--- ## URL Tokens +To help with links, two token characters can be used with links. They are particularly useful for websites deployed inside a domain's directory or virtual path, like `http://www.mysite.com/docs`. + ### Circumflex URL Token +The circumflex token (`^`), also called "root token", allows the reference to a path outside Retype's deploy file structure. Using the `http://www.mysite.com/docs` example, this would help define links outside the `/docs` prefix, as a means to ensure links could point to resources outside of retype's root yet in the same website. + +One side effect of using rooted links is, the address won't be checked or replaced by Retype at build time like tokenless links are, so linking to `.md` files won't be subject to the usual transformation from the examples above. + +!!! +For effect of the examples below, we asume Retype is being deployed to `http://www.mysite.com/docs`. +!!! + +=== Examples + +**Markdown:** `[Home](^/)` \ +**Link:** `/` + +**Markdown:** `[Pricing](^/pricing)` \ +**Link:** `/pricing` + +**Markdown:** `[Pricing](^/docs/FAQ.md)` \ +**Link:** `/docs/faq.md` +**Notes:** Even if `FAQ.md` exists, retype won't transform or check the link. + +=== + ### Tilde URL Token -## Raw HTML links +The tilde token (`~`), or "base path token", prefixes retype's base directory to the specified link. Again, it is useful in scenarios where retype is hosted in a subdirectory of a website (like `http://www.myhsite.com/docs`), but it is also particularlyh useful when the same Retype installation may be deployed to different bases (staging/development releases to temporary hosting, for instances) or simply if the project may be deployed to different websites and root directories. + +In other words, it would allow a Retype project to be deployed to different hosts and different root directories, changing just [the `url` config](~/configuration/project/#url) in project settings. + +Like root tokens, base path tokens prevent the address from being replaced by Retype e.g. if a `.md` file in input is pointed by the link. + +!!! +For effect of the examples below, we assume Retype is being deployed to `http://www.mysite.com/docs`. +!!! + +=== Examples + +**Markdown:** `[Docs home](~/)` \ +**Link:** `/docs` + +**Markdown:** `[A Text file](~/static/sample.txt)` \ +**Link:** `/docs/static/sample.txt` + +**Markdown:** `[A broken link](~/FAQ.md)` \ +**Link:** `/docs/faq.md` +**Notes:** Like with root tokens, base path tokens prevent Retype from resolving links by itself, so linking `.md` files likely would bring unexpected results. + +=== + +--- + +## Other Markdown components + +Other markdown components like ref, image, etc, follows the same rules + +!!!danger TODO +TODO TODO TODO +!!! + +## Raw HTML anchor links + +If retype markdown is not letting your link the way you need it, linking via HTML Anchor tags should help. Retype won't touch raw HTML links unless they begin with any of the URL tokens above. + +!!! +For effect of the examples below, we assume the edited file is the source of this page itself, that is, `guides/linking.md` in the project's input directory. +!!! + +=== Examples + +**HTML:** `Website Root` \ +**Output:** Website Root \ +**Link:** `/` + +**HTML:** `Formatting guide` \ +**Output:** formatting.md \ +**Link:** `/` +**Notes:** For a document in the same level directory we'd pass the link as one level above, for the `.md` file becomes a directory in the built website. + +**HTML:** `Project configs` \ +**Output:** ../configuration/project.md \ +**Link:** `../../configuration/project/` + +=== + +### URL Tokens in raw links + +The only transformation that actually takes place in raw HTML links is token substitution. + +!!! +For effect of the examples below, we assume Retype is being deployed to `http://www.mysite.com/docs`. +!!! + +=== Examples + +**HTML:** `Docs home`\ +**Link:** `/docs` + +**HTML:** `(A Text file` \ +**Link:** `/docs/static/sample.txt` + +**HTML:** `FAQ` \ +**Link:** `/docs/faq/` + +**HTML:** `Website root` \ +**Link:** `/` + +**HTML:** `Pricing` \ +**Link:** `/pricing` + +=== + +--- + +## Outside world + +Links to other websites are not mangled by retype, and URL tokens in the middle of URLs aren't replaced by Retype. + +=== Examples + +**Markdown:** `[Google search](https://www.google.com/)` \ +**Output:** [Google search](https://www.google.com/) \ +**Link:** `https://www.google.com/` + +**Markdown:** `[PuTTY home](https://www.chiark.greenend.org.uk/~sgtatham/putty/)` \ +**Output:** [PuTTY home](https://www.chiark.greenend.org.uk/~sgtatham/putty/) \ +**Link:** `https://www.chiark.greenend.org.uk/~sgtatham/putty/` -- does not change links -- understand how retype transform paths -- still replaces tokens +**HTML:** `Google search` \ +**Output:** Google search \ +**Link:** `https://www.google.com/` -## Examples +**HTML:** `PuTTY home` \ +**Output:** PuTTY home \ +**Link:** `https://www.chiark.greenend.org.uk/~sgtatham/putty/` -All links working for the retype.com website \ No newline at end of file +=== \ No newline at end of file From 97a183cd38e64236e93c5007ba4476f2c7274ad7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabr=C3=ADcio=20Zimmerer=20Murta?= Date: Wed, 6 Oct 2021 17:54:48 -0300 Subject: [PATCH 3/4] Finishes the 'Linking' guide with the missing section. --- guides/linking.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/guides/linking.md b/guides/linking.md index 6f95cbb6b..aade20dcf 100644 --- a/guides/linking.md +++ b/guides/linking.md @@ -162,11 +162,14 @@ For effect of the examples below, we assume Retype is being deployed to `http:// ## Other Markdown components -Other markdown components like ref, image, etc, follows the same rules +The same rules portrayed above also applies to other components involving links, specific to Markdown specification, or Retype-flavored exclusive components: -!!!danger TODO -TODO TODO TODO -!!! +- [Button](../components/button.md) +- [File download](../components/file-download.md) +- [Image](../components/image.md) +- [Reference link](../components/reference-link.md) + +--- ## Raw HTML anchor links From 20874ab9f0fe308055c12c0b6e225a7e7b2ae487 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabr=C3=ADcio=20Zimmerer=20Murta?= Date: Fri, 15 Oct 2021 00:49:32 -0300 Subject: [PATCH 4/4] Reviews the Linking guide. --- guides/linking.md | 48 ++++++++++++++++++++++------------------------- 1 file changed, 22 insertions(+), 26 deletions(-) diff --git a/guides/linking.md b/guides/linking.md index aade20dcf..ce8d3b4a7 100644 --- a/guides/linking.md +++ b/guides/linking.md @@ -4,24 +4,20 @@ icon: link # Linking -When Retype builds your pages it transforms input path into website links like this: +When Retype builds your pages, it transforms input paths into website links like this: `articles/my_article.md` => `articles/my_article/index.html` -Which is accessed by simply `articles/my_article/`. +Which can be accessed simply by `articles/my_article/` as part of the website address. -Because of this, Retype also transforms links to .md files within the project when they are composed using the link markdown `[text](link)`. - -!!! Handle the links yourself -If control is needed over the address, using [raw HTML links](#raw-html-links) should be the way to go. -!!! +Because of this, Retype also transforms links to `.md` files within the project when they are composed using the link markdown `[text](link)`. ## Markdown linking The examples below illustrate how markdown links are transformed during Retype Build !!! -For effect of the examples below, we assume the edited file is the source of this page itself, that is, `guides/linking.md` in the project's input directory. +For the examples below, suppose the edited file is the source of this page itself, that is, `guides/linking.md` in the project's input directory. !!! === Examples @@ -66,7 +62,7 @@ For effect of the examples below, we assume the edited file is the source of thi **Output:** [Alert variants (anchor)](../components/alert.md#variants) \ **Link:** `../../components/alert/#variants` -**Markdown:** `[No `.md` extension](formatting)` \ +**Markdown:** ``[No `.md` extension](formatting)`` \ **Output:** [No `.md` extension](formatting) \ **Link:** `../formatting/` @@ -79,7 +75,7 @@ For effect of the examples below, we assume the edited file is the source of thi ### Invalid links -If a link points within the retype website -and- no .md file matches it, retype won't transform it. +If a link points within the Retype website -and- no .md file matches it, no transformation will be made. === Examples @@ -106,16 +102,16 @@ If a link points within the retype website -and- no .md file matches it, retype --- ## URL Tokens -To help with links, two token characters can be used with links. They are particularly useful for websites deployed inside a domain's directory or virtual path, like `http://www.mysite.com/docs`. +To help linking around Retype documents, two different token characters can be used to prefix addresses. They are particularly useful for websites deployed inside a domain's directory or virtual path, like `http://example.com/docs`. ### Circumflex URL Token -The circumflex token (`^`), also called "root token", allows the reference to a path outside Retype's deploy file structure. Using the `http://www.mysite.com/docs` example, this would help define links outside the `/docs` prefix, as a means to ensure links could point to resources outside of retype's root yet in the same website. +The circumflex token (`^`), often called "root token" or "caret token", allows the reference to a path outside Retype's deploy file structure. Using the `http://example.com/docs` site as example, the token helps making links outside the `/docs` path space, as a means to ensure links pointing to resources outside of Retype's root, yet in the same website. Avoiding then unintended transformations in the final URL. -One side effect of using rooted links is, the address won't be checked or replaced by Retype at build time like tokenless links are, so linking to `.md` files won't be subject to the usual transformation from the examples above. +One side effect of using rooted links is, the address will not be checked or replaced by Retype at build time like ordinary links are. This means, linking to `.md` files will not be subject to the usual transformation showcased in the examples above. !!! -For effect of the examples below, we asume Retype is being deployed to `http://www.mysite.com/docs`. +For the examples below, suppose Retype is being deployed to `http://example.com/docs`. !!! === Examples @@ -127,21 +123,21 @@ For effect of the examples below, we asume Retype is being deployed to `http://w **Link:** `/pricing` **Markdown:** `[Pricing](^/docs/FAQ.md)` \ -**Link:** `/docs/faq.md` -**Notes:** Even if `FAQ.md` exists, retype won't transform or check the link. +**Link:** `/docs/faq.md` \ +**Notes:** Even if `FAQ.md` exists, Retype will not transform or check the link. === ### Tilde URL Token -The tilde token (`~`), or "base path token", prefixes retype's base directory to the specified link. Again, it is useful in scenarios where retype is hosted in a subdirectory of a website (like `http://www.myhsite.com/docs`), but it is also particularlyh useful when the same Retype installation may be deployed to different bases (staging/development releases to temporary hosting, for instances) or simply if the project may be deployed to different websites and root directories. +The tilde token (`~`), or "base path token", prefixes the base directory to the specified link. Again, it is useful in scenarios where Retype is hosted in a subdirectory of a website (like `http://example.com/docs`), but it is also particularly useful when the same Retype installation may be deployed to different bases (staging/development releases to temporary hosting, for instance) or simply if the project may be deployed to different websites and root directories. In other words, it would allow a Retype project to be deployed to different hosts and different root directories, changing just [the `url` config](~/configuration/project/#url) in project settings. -Like root tokens, base path tokens prevent the address from being replaced by Retype e.g. if a `.md` file in input is pointed by the link. +Like **root tokens**, the **base path tokens** prevent the address from being replaced by Retype e.g. if a `.md` file in input is pointed by the link. !!! -For effect of the examples below, we assume Retype is being deployed to `http://www.mysite.com/docs`. +For the examples below, suppose Retype is being deployed to `http://example.com/docs`. !!! === Examples @@ -153,7 +149,7 @@ For effect of the examples below, we assume Retype is being deployed to `http:// **Link:** `/docs/static/sample.txt` **Markdown:** `[A broken link](~/FAQ.md)` \ -**Link:** `/docs/faq.md` +**Link:** `/docs/faq.md` \ **Notes:** Like with root tokens, base path tokens prevent Retype from resolving links by itself, so linking `.md` files likely would bring unexpected results. === @@ -162,7 +158,7 @@ For effect of the examples below, we assume Retype is being deployed to `http:// ## Other Markdown components -The same rules portrayed above also applies to other components involving links, specific to Markdown specification, or Retype-flavored exclusive components: +The same rules portrayed above also apply to other markdown components involving links. Likewise, the following Retype-flavored, exclusive components, are also affected: - [Button](../components/button.md) - [File download](../components/file-download.md) @@ -173,10 +169,10 @@ The same rules portrayed above also applies to other components involving links, ## Raw HTML anchor links -If retype markdown is not letting your link the way you need it, linking via HTML Anchor tags should help. Retype won't touch raw HTML links unless they begin with any of the URL tokens above. +If Retype markdown is not letting your link the way you need it, linking via HTML Anchor tags (`text`) should help. Retype will not touch raw HTML links unless they begin with any of the URL tokens above. !!! -For effect of the examples below, we assume the edited file is the source of this page itself, that is, `guides/linking.md` in the project's input directory. +For the examples below, suppose the edited file is the source of this page itself, that is, `guides/linking.md` in the project's input directory. !!! === Examples @@ -188,7 +184,7 @@ For effect of the examples below, we assume the edited file is the source of thi **HTML:** `Formatting guide` \ **Output:** formatting.md \ **Link:** `/` -**Notes:** For a document in the same level directory we'd pass the link as one level above, for the `.md` file becomes a directory in the built website. +**Notes:** For a document in the same level directory we would pass the link as one level above, for the `.md` file becomes a directory in the built website. **HTML:** `Project configs` \ **Output:** ../configuration/project.md \ @@ -201,7 +197,7 @@ For effect of the examples below, we assume the edited file is the source of thi The only transformation that actually takes place in raw HTML links is token substitution. !!! -For effect of the examples below, we assume Retype is being deployed to `http://www.mysite.com/docs`. +For the examples below, suppose Retype is being deployed to `http://example.com/docs`. !!! === Examples @@ -230,7 +226,7 @@ For effect of the examples below, we assume Retype is being deployed to `http:// ## Outside world -Links to other websites are not mangled by retype, and URL tokens in the middle of URLs aren't replaced by Retype. +Links to other websites are not manipulated by Retype, and URL tokens in the middle of URLs are not replaced by Retype. === Examples