You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: dactyl/templates/children.html
+1-1
Original file line number
Diff line number
Diff line change
@@ -22,7 +22,7 @@
22
22
{% for child in parent.children %}
23
23
{% if child.nav_omit is defined and child.nav_omit %}{# skip pages that are omitted from navigation #}
24
24
{% elif ns.count_printed <count_limit%}
25
-
<liclass="level-{{indent_level}}"><ahref="{{target.prefix}}{{child.html}}">{{child.name}}</a>{% if show_blurbs and child.blurb is defined and indent_level == 1%}<pclass="blurb child-blurb">{{child.blurb}}</p>{% endif %}</li>
25
+
<liclass="level-{{indent_level}}"><ahref="{{target.prefix}}{{child.html}}">{{child.name}}</a>{% if show_blurbs and child.blurb is defined %}<pclass="blurb child-blurb">{{child.blurb}}</p>{% endif %}</li>
Copy file name to clipboardexpand all lines: examples/content/code-highlighting.md
+3
Original file line number
Diff line number
Diff line change
@@ -1,3 +1,6 @@
1
+
---
2
+
blurb: Dactyl automatically adds syntax highlighting to code blocks.
3
+
---
1
4
# Code Highlighting
2
5
3
6
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.)
categories: ["Tests", "Dactyl ignores categories beyond the first"]
4
+
---
5
+
# Frontmatter
6
+
7
+
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:
8
+
9
+
```yaml
10
+
---
11
+
desc: This file has Jekyll-style frontmatter
12
+
categories: ["Tests", "Dactyl ignores categories beyond the first"]
13
+
---
14
+
```
15
+
16
+
The frontmatter can be referenced by the preprocessor and by templates. For example:
17
+
18
+
```
19
+
> Description: {{"{{"}}currentpage.desc{{"}}"}}
20
+
```
21
+
22
+
Results:
23
+
24
+
> Description: {{currentpage.desc}}
25
+
26
+
27
+
**Caution:** If you [include](includes.html) a page, the frontmatter of the included page is not available to the including page.
Copy file name to clipboardexpand all lines: examples/content/includes.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -1,4 +1,4 @@
1
-
# Includes Test
1
+
# Includes
2
2
3
3
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.
Dactyl includes a link-checking script to automatically detect and report on broken hyperlinks in your generated documentation.
8
+
9
+
## Usage
10
+
11
+
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.
12
+
13
+
Then, run the link checker as follows:
14
+
15
+
```sh
16
+
$ dactyl_link_checker
17
+
```
18
+
19
+
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.
20
+
21
+
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.
22
+
23
+
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).
24
+
25
+
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.)
26
+
27
+
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.
28
+
29
+
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.
30
+
31
+
## Unusual Link Types
32
+
33
+
Some unusual types of links that you may encounter in HTML or Markdown include:
34
+
35
+
-[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.
36
+
-[Mailto URL](mailto:[email protected]) - Email addresses. The link checker ignores these and other links that use other URI schemes.
37
+
-[Javascript Bookmarklet](javascript:alert%28'A bookmarklet did this'%29) - JavaScript code embedded in the href directly with `javascript:`. The link checker ignores these.
38
+
-[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.
"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.
8
+
9
+
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.
10
+
11
+
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:
12
+
13
+
```yaml
14
+
- name: Dactyl Homepage
15
+
parent: virtual-pages.html
16
+
html: https://dactyl.link/
17
+
targets:
18
+
- everything
19
+
```
20
+
21
+
Specifically, a virtual page is **any page with `//` in its `html` attribute.**
22
+
23
+
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:
24
+
25
+
```md
26
+
---
27
+
html: https://dactyl.link/
28
+
blurb: This is an example of a virtual page defined by MD frontmatter.
29
+
category: Features
30
+
parent: virtual-pages.html
31
+
---
32
+
# Virtual Placeholder
33
+
34
+
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.
blurb: This is an example of a virtual page defined by MD frontmatter.
4
+
category: Features
5
+
parent: virtual-pages.html
6
+
---
7
+
# Virtual Placeholder
8
+
9
+
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.
Copy file name to clipboardexpand all lines: examples/dactyl-config.yml
+37-21
Original file line number
Diff line number
Diff line change
@@ -8,6 +8,8 @@ filter_paths:
8
8
defaults: &defaults
9
9
hover_anchors: "¶"
10
10
11
+
spelling_file: spelling.txt
12
+
11
13
targets:
12
14
- name: everything
13
15
display_name: Dactyl Examples
@@ -28,9 +30,9 @@ targets:
28
30
<<: *defaults
29
31
30
32
pages:
31
-
- name: Tests
32
-
html: tests-index.html
33
-
category: Tests
33
+
- name: Features
34
+
html: features.html
35
+
category: Features
34
36
section_header: true
35
37
parent: index.html
36
38
template: landing.html
@@ -39,57 +41,71 @@ pages:
39
41
40
42
- md: code-highlighting.md
41
43
html: code-highlighting.html
42
-
parent: tests-index.html
44
+
parent: features.html
43
45
targets:
44
46
- everything
45
47
46
48
- md: includes.md
47
-
category: Tests
48
-
parent: tests-index.html
49
+
category: Features
50
+
parent: features.html
49
51
targets:
50
52
- everything
51
53
52
-
- md: with-frontmatter.md
53
-
html: with-frontmatter.html
54
-
parent: tests-index.html
54
+
- md: frontmatter.md
55
+
html: frontmatter.html
56
+
parent: features.html
55
57
targets:
56
58
- everything
57
59
58
60
- md: cli-vars.md
59
61
html: cli-vars.html
60
-
parent: tests-index.html
62
+
parent: features.html
61
63
targets:
62
64
- everything
63
65
64
-
- md: link-types.md
66
+
- md: link-checking.md
65
67
targets:
66
68
- everything
67
69
68
-
- name: Conditionals Test
69
-
category: Tests
70
-
md: conditionals.md
71
-
parent: tests-index.html
70
+
- md: conditionals.md
71
+
category: Features
72
+
parent: features.html
72
73
targets:
73
74
- everything
74
75
- conditionals
75
76
76
77
- name: Lists and Code Blocks Demo
77
-
category: Tests
78
+
category: Features
78
79
md: lists-and-codeblocks.md
79
-
parent: tests-index.html
80
+
parent: features.html
80
81
targets:
81
82
- everything
82
83
83
84
- name: GitHub Markdown Compatibility
84
-
category: Tests
85
+
category: Features
85
86
md: gfm-compat.md
86
-
parent: tests-index.html
87
+
parent: features.html
87
88
targets:
88
89
- everything
89
90
90
91
- md: header_stress_test.md
91
-
category: Tests
92
-
parent: tests-index.html
92
+
category: Features
93
+
parent: features.html
94
+
targets:
95
+
- everything
96
+
97
+
- md: virtual-pages.md
98
+
targets:
99
+
- everything
100
+
101
+
- name: Dactyl Homepage
102
+
parent: virtual-pages.html
103
+
html: https://dactyl.link/#
104
+
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.
0 commit comments