From 7544693337fa9e1d47831f27517070c599d86bc1 Mon Sep 17 00:00:00 2001 From: tomjohnson1492 Date: Fri, 8 Jul 2016 20:44:23 -0700 Subject: [PATCH] updated the doc for managed links esp. in regards to use of the other.yml file and linking to jump headings on a page --- _data/sidebars/other.yml | 9 +++------ _includes/links.html | 4 ++++ pages/mydoc/mydoc_hyperlinks.md | 28 +++++++++++++++++----------- 3 files changed, 24 insertions(+), 17 deletions(-) diff --git a/_data/sidebars/other.yml b/_data/sidebars/other.yml index d458527..4be86f0 100644 --- a/_data/sidebars/other.yml +++ b/_data/sidebars/other.yml @@ -9,13 +9,10 @@ entries: folderitems: - title: Automated links bookmark - url: mydoc_hyperlinks.html#automatedlinks - ref: mydoc_hyperlinks-automatedlinks + url: /mydoc_hyperlinks.html#automatedlinks - title: Bookmark links - url: mydoc_hyperlinks.html#bookmarklinks - ref: mydoc_hyperlinks-bookmarklinks + url: /mydoc_hyperlinks.html#bookmarklinks - title: Some link bookmark - url: mydoc_pages.html#someIdTag - ref: someIdTag + url: /mydoc_pages.html#someIdTag diff --git a/_includes/links.html b/_includes/links.html index ce2bf35..4f99e94 100644 --- a/_includes/links.html +++ b/_includes/links.html @@ -4,7 +4,11 @@ {% for entry in site.data.sidebars[sidebar].entries %} {% for folder in entry.folders %} {% for folderitem in folder.folderitems %} +{% if folderitem.url contains "html#" %} +[{{folderitem.url | remove: "/" }}]: {{folderitem.url | remove: "/"}} +{% else %} [{{folderitem.url | remove: "/" | remove: ".html"}}]: {{folderitem.url | remove: "/"}} +{% endif %} {% for subfolders in folderitem.subfolders %} {% for subfolderitem in subfolders.subfolderitems %} [{{subfolderitem.url | remove: "/" | remove: ".html"}}]: {{subfolderitem.url | remove: "/"}} diff --git a/pages/mydoc/mydoc_hyperlinks.md b/pages/mydoc/mydoc_hyperlinks.md index c6a86cd..8555872 100644 --- a/pages/mydoc/mydoc_hyperlinks.md +++ b/pages/mydoc/mydoc_hyperlinks.md @@ -3,7 +3,7 @@ title: Links audience: writer, designer tags: [formatting, navigation] keywords: links, hyperlinks, cross references, related links, relationship tables -summary: "When creating links, you can use standard HTML or Markdown formatting. Note that this approach is susceptible to errors and broken links, so check your outputs for broken links." +summary: "When creating links, you can use standard HTML or Markdown formatting. However, you can also implement an automated approach to linking that makes linking much less error-prone (meaning less chances of broken links in your output) and requiring less effort." last_updated: July 3, 2016 sidebar: mydoc_sidebar permalink: mydoc_hyperlinks.html @@ -26,19 +26,21 @@ When linking to internal pages, you can manually link to the pages like this: [Icons](mydoc_icons.html) ``` -However, if you change the file name, you'll have to update all of your links. It's much easier to use Automated Links, as described in the next section. +However, if you change the file name, you'll have to update all of your links. It's much easier to use Automated links, as described in the next section. ## Automated links {#automatedlinks} This method for automated links creates a master list of all links in a Markdown reference format based on entries in your sidebar table of contents. -With this Automated links method, make sure all your pages are referenced in a sidebar or topnav data file (inside \_data > sidebars). If they're not in a sidebar or top nav (such as links to headings on a page), list them in the `otherlinks.yml` file (which is in the \_data folder). +With this Automated links method, make sure all your pages are referenced in a sidebar or topnav data file (inside \_data > sidebars). If they're not in a sidebar or top nav (such as links to headings on a page), list them in the `other.yml` file (which is in the \_data/sidebars folder). -The links.html file (in \_includes) will iterate through all your sidebars and create a list of reference-style markdown links. This feature works like magic. +The links.html file (in \_includes) will iterate through all your sidebars and create a list of reference-style markdown links based on the `url` properties in the sidebar items. + +{% include note.html content="For the automated links method to work, each of your pages must have a `permalink` property in the frontmatter. The `permalink` property must match the file name. For example, if the file name is `somefile.html`, your permalink property would be `somefile.html`. See [Pages][mydoc_pages] for more details." %} To implement managed links: -1. In your \_config.yml file, list each sidebar in the `sidebars` property — except for the otherlinks.yml file. (Do not list it here, since there's a different script that parses through its content.) +1. In your \_config.yml file, list each sidebar in the `sidebars` property — including the other.yml file too: ```yaml sidebars: @@ -46,9 +48,10 @@ To implement managed links: - mydoc_sidebar - product1_sidebar - product2_sidebar + - other ``` -2. At the bottom of each topic, include the links.html file: +2. At the bottom of each topic where you plan to include links, include the links.html file: ``` {% raw %}{% include links.html %}{% endraw %} @@ -74,20 +77,23 @@ If you're linking to the specific heading from another page, first give the head ## Some heading {#someheading} ``` -Then add a property into the otherlinks.yml file in your \_data folder: +Then add a property into the other.yml file in your \_data/sidebars folder: ```yaml - title: Some link bookmark - exact_url: mydoc_pages.html#someheading - ref: mydocpages_pages-someheading - + url: /mydoc_pages.html#someIdTag ``` And reference it like this: ``` -This is [Some link][mydocpages_pages-someheading]. +This is [Some link][mydoc_pages.html#someIdTag]. ``` +**Result:** + +This is [Some link][mydoc_pages.html#someIdTag]. + +It's a little strange having the `.html#` in a reference like this, but it works. {% include links.html %}