v0.14.0: virtual pages, template fixes

dactyl/dactyl_build.py

@@ -140,6 +140,10 @@ def build_all(self, only_page=None):
         es_data = {}
         matched_only = False
         for page in pages:
+            if page.is_virtual():
+                logger.debug("skipping virtual page: %s" % page)
+                continue
+
             if only_page:
                 if self.match_only_page(only_page, page.data):
                     matched_only = True
@@ -444,7 +448,7 @@ def assemble_pdf(self, only_page=None):
         if not self.config["legacy_prince"]:
             args.append('--no-warn-css')
 
-        pages = self.target.pages
+        pages = [p for p in self.target.pages if not p.is_virtual()]
         if only_page:
             pages = [p for p in pages if self.match_only_page(only_page, p.data)][:1]
             if not len(pages):

dactyl/filter_demote_headers.py

@@ -18,8 +18,13 @@ def filter_html(html, mode="html", target={}, **kwargs):
         return html
 
     html = html.replace("<h5", "<h6")
+    html = html.replace("</h5", "</h6")
     html = html.replace("<h4", "<h5")
+    html = html.replace("</h4", "</h5")
     html = html.replace("<h3", "<h4")
+    html = html.replace("</h3", "</h4")
     html = html.replace("<h2", "<h3")
+    html = html.replace("</h2", "</h3")
     html = html.replace("<h1", "<h2")
+    html = html.replace("</h1", "</h2")
     return html

dactyl/page.py

@@ -555,6 +555,15 @@ def filter_exports(self):
                     exported_vals[key] = val
         return exported_vals
 
+    def is_virtual(self):
+        """
+        Returns True if this is a "virtual" page that does not have a real HTML
+        output. These types of pages are essentially placeholders for navigation.
+        """
+        if "//" in self.data["html"]:
+            return True
+        return False
+
     def filters(self, save=True):
         """
         Returns the names of filters to use when processing this page.

dactyl/target.py

@@ -234,7 +234,7 @@ def load_pages(self):
         for p in pages:
             if "html" not in p.data.keys():
                 logger.error("page has no html somehow? %s"%p.data)
-            if p.data["html"] in html_outs:
+            if p.data["html"] in html_outs and not p.is_virtual():
                 recoverable_error(("Repeated output filename '%s'. The earlier "+
                     "instances will be overwritten") % p.data["html"],
                     self.config.bypass_errors)

dactyl/templates/children.html

@@ -22,7 +22,7 @@
   {% for child in parent.children %}
     {% if child.nav_omit is defined and child.nav_omit %}{# skip pages that are omitted from navigation #}
     {% elif ns.count_printed < count_limit %}
-      <li class="level-{{indent_level}}"><a href="{{target.prefix}}{{child.html}}">{{child.name}}</a>{% if show_blurbs and child.blurb is defined and indent_level == 1%}<p class="blurb child-blurb">{{child.blurb}}</p>{% endif %}</li>
+      <li class="level-{{indent_level}}"><a href="{{target.prefix}}{{child.html}}">{{child.name}}</a>{% if show_blurbs and child.blurb is defined %}<p class="blurb child-blurb">{{child.blurb}}</p>{% endif %}</li>
       {% set ns.count_printed = ns.count_printed + 1 %}
       {% if indent_level+1 <= depth_limit %}
         {# recursively print descendants #}

dactyl/templates/pdf-cover.html

@@ -11,6 +11,17 @@
         .dactyl-pdf-toc {
             page-break-after: always;
         }
+        .level-1 {
+          margin-left: 1rem;
+        }
+        .level-2 {
+          list-style-type: circle;
+          margin-left: 2rem;
+        }
+        .level-3 {
+          list-style-type: square;
+          margin-left: 3rem;
+        }
         .dactyl-pdf-cover .dactyl-pdf-title-area {
             position: absolute;
             top: 26%;

dactyl/templates/simple.html

@@ -37,6 +37,7 @@
 
     @media print {
       .dactyl-sidebar {display: none;}
+      .hover_anchor {display:none;}
 
       @page {
         @bottom-left {

dactyl/version.py

@@ -1 +1 @@
-__version__ = '0.14.0a5'
+__version__ = '0.14.0'

examples/content/code-highlighting.md

@@ -1,3 +1,6 @@
+---
+blurb: Dactyl automatically adds syntax highlighting to code blocks.
+---
 # Code Highlighting
 
 Dactyl automatically adds syntax highlighting to code blocks when it parses Markdown, using the [Pygments](https://pygments.org/)-derived [CodeHilite](https://python-markdown.github.io/extensions/code_hilite/) extension. Parsing the syntax highlighting at compile time like this is faster and less work for readers' computers than in-browser syntax highlighting such as using [highlight.js](https://highlightjs.readthedocs.io/en/latest/api.html). (If you prefer highlight.js's output, though, you can still run it to overwrite Dactyl's syntax highlighting.)

examples/content/frontmatter.md

@@ -0,0 +1,27 @@
+---
+desc: This file has Jekyll-style frontmatter
+categories: ["Tests", "Dactyl ignores categories beyond the first"]
+---
+# Frontmatter
+
+Frontmatter is a set of YAML keys and values to start a Markdown file, set off by two lines of `---`. For example, this page has the following frontmatter:
+
+```yaml
+---
+desc: This file has Jekyll-style frontmatter
+categories: ["Tests", "Dactyl ignores categories beyond the first"]
+---
+```
+
+The frontmatter can be referenced by the preprocessor and by templates. For example:
+
+```
+> Description: {{"{{"}}currentpage.desc{{"}}"}}
+```
+
+Results:
+
+> Description: {{currentpage.desc}}
+
+
+**Caution:** If you [include](includes.html) a page, the frontmatter of the included page is not available to the including page.

examples/content/includes.md

@@ -1,4 +1,4 @@
-# Includes Test
+# Includes
 
 This page demonstrates including a file using the [preprocessor's `include` syntax](https://jinja.palletsprojects.com/en/2.11.x/templates/#include). The path to including a file is always relative to the **`content_path`** from the config.
 

examples/content/link-checking.md

@@ -0,0 +1,38 @@
+---
+html: link-checking.html
+parent: features.html
+---
+# Link Checking
+
+Dactyl includes a link-checking script to automatically detect and report on broken hyperlinks in your generated documentation.
+
+## Usage
+
+First, build some documentation to an output path. Depending on your configuration, you may want to build multiple targets to different output directories before running the link checker.
+
+Then, run the link checker as follows:
+
+```sh
+$ dactyl_link_checker
+```
+
+This checks all the files in the output directory for links and confirms that any HTTP(S) links, including relative links to other files, are valid. For anchor links, it checks that an element with the correct ID exists in the target file. It also checks that the `src` of all image tags exists.
+
+If there are links that are always reported as broken but you don't want to remove (for example, URLs that block Python's user-agent) you can add them to the `known_broken_links` array in the config.
+
+In quiet mode (`-q`), the link checker still reports in every 30 seconds just so that it doesn't get treated as stalled and killed by continuous integration software (e.g. Jenkins).
+
+To reduce the number of meaningless failure reports (because a particular website happened to be down momentarily while you ran the link checker), if there are any broken remote links, the link checker waits 2 minutes after finishing and then retries those links in case they came back up. (If they did, they're not considered broken for the link checker's final report.)
+
+You can also run the link checker in offline mode (`-o`) to skip any remote links and just check that the files and anchors referenced exist in the output directory.
+
+If you have a page that uses JavaScript or something to generate anchors dynamically, the link checker can't find those anchors (since it doesn't run any JS). You can add such pages to the `ignore_anchors_in` array in your config to skip checking for links that go to anchors in such pages.
+
+## Unusual Link Types
+
+Some unusual types of links that you may encounter in HTML or Markdown include:
+
+- [Protocol relative URL](//dactyl.link/features.html) - these start with `//` and refer to "whatever protocl is being used now". Dactyl assumes HTTPS should work for these URLs.
+- [Mailto URL](mailto:[email protected]) - Email addresses. The link checker ignores these and other links that use other URI schemes.
+- [Javascript Bookmarklet](javascript:alert%28'A bookmarklet did this'%29) - JavaScript code embedded in the href directly with `javascript:`. The link checker ignores these.
+- [Empty anchor](#) - A link to `#`. This type of link is often used to trigger JavaScript events. The link checker considers these invalid for `<img>` paths but OK for `<a>` tags.

examples/content/virtual-pages.md

@@ -0,0 +1,35 @@
+---
+category: Features
+parent: features.html
+---
+# Virtual Pages
+
+"Virtual Pages" are placeholders for pages or websites that are not part of the Dactyl site, but that you want to link from within the Dactyl-generated navigation. Dactyl's built-in templates automatically create links to virtual pages in the appropriate places within the navigation.
+
+Dactyl does not build an associated output HTML file for these pages, so they are linked from PDF builds but their contents are not part of the generated PDF. The [link checker](link-checking.html) treats virtual pages the same as other external links, so it checks links _to_ them but not _in_ the virtual pages.
+
+The "Dactyl Homepage" link listed under this page is an example of a Virtual Page. To create a virtual link, add a stanza such as the following to the page array in your config file:
+
+```yaml
+-   name: Dactyl Homepage
+    parent: virtual-pages.html
+    html: https://dactyl.link/
+    targets:
+        - everything
+```
+
+Specifically, a virtual page is **any page with `//` in its `html` attribute.**
+
+You can also define a virtual page using a `.md` file with [frontmatter](frontmatter.html). For example, you could have a file with the following contents:
+
+```md
+---
+html: https://dactyl.link/
+blurb: This is an example of a virtual page defined by MD frontmatter.
+category: Features
+parent: virtual-pages.html
+---
+# Virtual Placeholder
+
+The actual Markdown contents of a "virtual page" are mostly ignored. However, they can be used to provide metadata such as the title and blurb used in navigation on other pages.
+```

examples/content/virtual-placeholder.md

@@ -0,0 +1,9 @@
+---
+html: https://dactyl.link/
+blurb: This is an example of a virtual page defined by MD frontmatter.
+category: Features
+parent: virtual-pages.html
+---
+# Virtual Placeholder
+
+The actual Markdown contents of a "virtual page" are mostly ignored. However, they can be used to provide metadata such as the title and blurb used in navigation on other pages.

examples/dactyl-config.yml

@@ -8,6 +8,8 @@ filter_paths:
 defaults: &defaults
     hover_anchors: "¶"
 
+spelling_file: spelling.txt
+
 targets:
     -   name: everything
         display_name: Dactyl Examples
@@ -28,9 +30,9 @@ targets:
         <<: *defaults
 
 pages:
-    -   name: Tests
-        html: tests-index.html
-        category: Tests
+    -   name: Features
+        html: features.html
+        category: Features
         section_header: true
         parent: index.html
         template: landing.html
@@ -39,57 +41,71 @@ pages:
 
     -   md: code-highlighting.md
         html: code-highlighting.html
-        parent: tests-index.html
+        parent: features.html
         targets:
             - everything
 
     -   md: includes.md
-        category: Tests
-        parent: tests-index.html
+        category: Features
+        parent: features.html
         targets:
             - everything
 
-    -   md: with-frontmatter.md
-        html: with-frontmatter.html
-        parent: tests-index.html
+    -   md: frontmatter.md
+        html: frontmatter.html
+        parent: features.html
         targets:
             - everything
 
     -   md: cli-vars.md
         html: cli-vars.html
-        parent: tests-index.html
+        parent: features.html
         targets:
             - everything
 
-    -   md: link-types.md
+    -   md: link-checking.md
         targets:
             - everything
 
-    -   name: Conditionals Test
-        category: Tests
-        md: conditionals.md
-        parent: tests-index.html
+    -   md: conditionals.md
+        category: Features
+        parent: features.html
         targets:
             - everything
             - conditionals
 
     -   name: Lists and Code Blocks Demo
-        category: Tests
+        category: Features
         md: lists-and-codeblocks.md
-        parent: tests-index.html
+        parent: features.html
         targets:
             - everything
 
     -   name: GitHub Markdown Compatibility
-        category: Tests
+        category: Features
         md: gfm-compat.md
-        parent: tests-index.html
+        parent: features.html
         targets:
             - everything
 
     -   md: header_stress_test.md
-        category: Tests
-        parent: tests-index.html
+        category: Features
+        parent: features.html
+        targets:
+            - everything
+
+    -   md: virtual-pages.md
+        targets:
+            - everything
+
+    -   name: Dactyl Homepage
+        parent: virtual-pages.html
+        html: https://dactyl.link/#
+        blurb: This is a placeholder that shows up in navigation but does not have an actual output file. Use this if you want to link to external resources at a specific place in your navigation.
+        targets:
+            - everything
+
+    -   md: virtual-placeholder.md
         targets:
             - everything
 

examples/spelling.txt

@@ -0,0 +1 @@
+frontmatter

examples/template_assets/dactyl-buttonize.css

@@ -1,4 +1,6 @@
-a.button {
+/* Stand-alone CSS for use with the buttonize filter. Skip if you use
+   Bootstrap. */
+a.btn-primary {
   color: white;
   background: #0000EE;
   text-decoration: none;