diff --git a/_data/sidebar_doc.yml b/_data/sidebar_doc.yml index 9853f89..ef23cb8 100644 --- a/_data/sidebar_doc.yml +++ b/_data/sidebar_doc.yml @@ -18,6 +18,7 @@ entries: product: all version: all web: false + frontmatter: true - title: Table of Contents url: /tocpage.html @@ -26,6 +27,7 @@ entries: product: all version: all web: false + frontmatter: true - title: Getting started audience: writers, designers @@ -256,21 +258,28 @@ entries: product: all version: all - - title: Generating PDFs - url: /doc_generating_pdfs.html + - title: Link validation + url: /doc_link_validation.html audience: writers, designers platform: all product: all version: all - - title: Exclude files + - title: Generating PDFs + url: /doc_generating_pdfsx.html + audience: writers, designers + platform: all + product: all + version: all + + - title: Excluding files url: /doc_excluding_files.html audience: writers, designers platform: all product: all version: all - - title: Help API and UI tooltips + - title: Help APIs and UI tooltips url: /doc_help_api.html audience: writers, designers platform: all diff --git a/_data/topnav_doc.yml b/_data/topnav_doc.yml index 739a726..bf32f66 100644 --- a/_data/topnav_doc.yml +++ b/_data/topnav_doc.yml @@ -20,7 +20,7 @@ topnav_dropdowns: product: all version: all items: - - title: About + - title: About this theme url: /doc_about.html audience: writers, designers platform: all diff --git a/doc_link_validation.md b/doc_link_validation.md new file mode 100644 index 0000000..fdd00ab --- /dev/null +++ b/doc_link_validation.md @@ -0,0 +1,38 @@ +--- +title: Link validation +keywords: broken links, orphan links, publishing errors, validation, link validity, hyperlink issues +tags: [publishing] +last_updated: September 13, 2015 +summary: "Before deploying your published site, you want to ensure that you don't have any broken links. There are a few ways to check for broken links." +--- + +## Why broken links are challenging for technical writers +One of the challenging aspects of technical writing is avoiding broken links in your output. Consider this example. You have three outputs, with different topics included for different audiences. The topics each have inline cross references pointing to the other topics, but since some of the topics aren't included for each audience, you risk having a broken link for the output that omits that topic. + +Additionally, technical writers frequently manage large numbers of topics, and as they make updates, they rename titles, remote some topics, combine multiple topics into the same topic, and make other edits. When you're developing content, the pages and titles in your topics and navigation are in flux. You shift things around constantly trying to find the right organization, the right titles, and more. + +During this time, if you have inline links that point to specific pages, how do you avoid broken links in your output? + +## Use the URL checker + +The theme has a file called url-checker.html. This file will iterate through all the pages listed in the sidebar navigation and top navigation, and compare the navigation titles against the page titles based on matching URLs. If there are inconsistencies in the titles, they get noted on the url-checker.html page. + +To run the link checker, just build or serve your project, and go to url-checker.html in your browser (such as Chrome). If there are inconsistencies, they will be noted on the page. + +Note that in order for the URL checker to run correctly, it has to detect a match between the URL listed in the sidebar or top navigation with the URL for the page (based on the file name). If you have the wrong URL, it won't tell you if the page titles match. Therefore you should always click through all the topics in your navigation to make sure the URLs are accurate. + +## Generate a PDF + +When you generate a PDF, Prince XML will print "page 0" for any cross references it can't find. This lets you know that a particular link is bad. + +If you have links in your PDF that aren't references to other topics (maybe they're links to PDF file assets, or links within a navtab or collapsible section), then you must add a class of `noCrossRef` to the link to avoid having Prince write "page 0" for the link. + +(Note that there are still some kinks I'm working out with this. You may find that links still say "page 0" even if they have the `noCrossRef` class.) + +## Use data references for all inline links + +Instead of creating links to direct pages, use the data reference technique described in {{site.data.urls.doc_hyperlinks.link}}. With this method, the urls.txt file iterates through all the pages in your navigation and formats them into a YAML syntax. + +Then you insert an inline link by referring to that YAML data. For example, the previous hyperlink is `{% raw %}{{site.data.urls.doc_hyperlinks.link}}{% endraw %}`. + +As you go through the link validation process, make sure you copy over the content from the generated urls.txt (in the Jekyll site output) and insert it into the urls.yml file in your \_data folder. \ No newline at end of file diff --git a/doc_navtabs.md b/doc_navtabs.md index c2d2374..ad5028f 100644 --- a/doc_navtabs.md +++ b/doc_navtabs.md @@ -1,5 +1,5 @@ --- -title: NavTabs +title: Navtabs tags: [formatting] keywords: navigation tabs, hide sections, tabbers, interface tabs last_updated: August 12, 2015 diff --git a/doc_series.md b/doc_series.md index 92470b4..ef140c6 100644 --- a/doc_series.md +++ b/doc_series.md @@ -1,5 +1,5 @@ --- -title: Series pages +title: Series tags: [content-types] keywords: series, connected articles, tutorials, hello world last_updated: August 12, 2015 diff --git a/doc_tag-content-types.html b/doc_tag-content-types.html index 9948806..d57d915 100644 --- a/doc_tag-content-types.html +++ b/doc_tag-content-types.html @@ -1,5 +1,5 @@ --- -title: "Content Types pages" +title: "Content types pages" tagName: content-types search: exclude --- diff --git a/doc_webstorm_text_editor.md b/doc_webstorm_text_editor.md index 904d5ba..183be93 100644 --- a/doc_webstorm_text_editor.md +++ b/doc_webstorm_text_editor.md @@ -1,5 +1,5 @@ --- -title: WebStorm Text editor +title: WebStorm Text Editor keywords: webstorm, sublime, markdown, atom, gnome, notepad ++, textpad, bbedit tags: [getting-started] last_updated: August 12, 2015 diff --git a/url-checker.html b/url-checker.html new file mode 100644 index 0000000..40bfbd9 --- /dev/null +++ b/url-checker.html @@ -0,0 +1,94 @@ +--- +layout: none +search: exclude +--- + + +URL checker + + +

URL Checker Report

+{% include custom/conditions.html %} + +{% for entry in sidebar %} +{% for subcategory in entry.subcategories %} +{% for item in subcategory.items %} +{% unless item.frontmatter == true %} + {% assign itemTitle = item.title | replace: '"', '' %} + {% assign itemUrl = item.url %} + {% for page in site.pages %} + {% if page.url == item.url %} + {% assign pageTitle = page.title | replace: '"', '' %} + {% assign pageUrl = page.url %} + {% if pageTitle != itemTitle %} +
+

Problem: The sidebar item title "{{itemTitle}}" does not match the page title "{{pageTitle}}".

+{% endif %} + {% endif %} + {% endfor %} + {% endunless %} +{% for thirdlevel in item.thirdlevel %} +{% for deeplevel in thirdlevel.thirdlevelitems %} +{% unless deeplevel.frontmatter == true %} + + {% assign deeplevelTitle = deeplevel.title | replace: '"', '' %} + {% assign deeplevelUrl = deeplevel.url %} + {% for page in site.pages %} + {% if page.url == deeplevel.url %} + {% assign pageTitle = page.title | replace: '"', '' %} + {% assign pageUrl = page.url %} + {% if pageTitle != deeplevelTitle %} +
+

Problem: The sidebar deeplevel title "{{deeplevelTitle}}" does not match the page title "{{pageTitle}}".

+ {% endif %} + {% endif %} + {% endfor %} + {% endunless %} +{% endfor %} +{% endfor %} +{% endfor %} +{% endfor %} +{% endfor %} + + +{% for entry in topnav %} +{% for subcategory in entry.subcategories %} +{% unless subcategory.external_url or subcategory.frontmatter %} +
+ {% assign subcategoryTitle = subcategory.title | replace: '"', '' %} + {% assign subcategoryUrl = subcategory.url %} + {% for page in site.pages %} + {% if page.url == subcategory.url %} + {% assign pageTitle = page.title | replace: '"', '' %} + {% assign pageUrl = page.url %} + {% if pageTitle != subcategoryTitle %} +

Problem: The top navigation item title "{{subcategoryTitle}}" does not match the page title "{{pageTitle}}".

+ {% endif %} + {% endif %} + {% endfor %} + {% endunless %} +{% endfor %} +{% endfor %} + +{% for entry in topnav_dropdowns %} +{% for subcategory in entry.subcategories %} +{% for subitem in subcategory.items %} +{% unless subitem.external_url or subitem.frontmatter %} + + {% assign subitemTitle = subitem.title | replace: '"', '' %} + {% assign subitemUrl = subitem.url %} + {% for page in site.pages %} + {% if page.url == subitem.url %} + {% assign pageTitle = page.title | replace: '"', '' %} + {% assign pageUrl = page.url %} + {% if pageTitle != subitemTitle %} + Problem: The top drop-down navigation item title "{{subitemTitle}}" does not match the page title "{{pageTitle}}". + {% endif %} + {% endif %} + {% endfor %} + {% endunless %} +{% endfor %} +{% endfor %} +{% endfor %} + + \ No newline at end of file