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,13 +9,10 @@ entries:
     folderitems:
 
     - title: Automated links bookmark
-      url: mydoc_hyperlinks.html#automatedlinks
+      url: /mydoc_hyperlinks.html#automatedlinks
-      ref: mydoc_hyperlinks-automatedlinks
 
     - title: Bookmark links
-      url: mydoc_hyperlinks.html#bookmarklinks
+      url: /mydoc_hyperlinks.html#bookmarklinks
-      ref: mydoc_hyperlinks-bookmarklinks
 
     - title: Some link bookmark
-      url: mydoc_pages.html#someIdTag
+      url: /mydoc_pages.html#someIdTag
-      ref: someIdTag

_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: "/"}}

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
+      url: /mydoc_pages.html#someIdTag
-      ref: mydocpages_pages-someheading
-      
 ```
 
 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 %}