| 1 | package App::Dapper::Theme::Docs; | ||
| 2 | |||
| 3 | =head1 NAME | ||
| 4 | |||
| 5 | App::Dapper::Theme::Docs - A documentation starter for "dapper init --template docs". | ||
| 6 | |||
| 7 | =head1 DESCRIPTION | ||
| 8 | |||
| 9 | Documentation pages with a sidebar built from C<_data/nav.yml>, previous and | ||
| 10 | next links in the same order, highlighted code, and optional search. Every | ||
| 11 | page must match C<_source/_schema.yml>. | ||
| 12 | |||
| 13 | =cut | ||
| 14 | |||
| 15 | 190 | ▶ | use utf8; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 16 | 190 | ▶ | use 5.010; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 17 | 190 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 18 | 190 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 19 | |||
| 20 | =head2 description | ||
| 21 | |||
| 22 | A one-line description of the theme. | ||
| 23 | |||
| 24 | =cut | ||
| 25 | |||
| 26 | 191 | ▶ | sub description { 'Documentation: a sidebar from a data file, previous and next links, code highlighting and search' } |
|
Subroutine
description: called CC=1 SCAR=0.0
Pod
documented
| |||
| 27 | |||
| 28 | =head2 notes | ||
| 29 | |||
| 30 | Notes about the theme for AGENTS.md. | ||
| 31 | |||
| 32 | =cut | ||
| 33 | |||
| 34 | 192 | ▶ | sub notes { |
|
Subroutine
notes: called CC=1 SCAR=0.0
Pod
documented
| |||
| 35 | 192 | return <<'NOTES'; | |
| 36 | ## About these docs | ||
| 37 | |||
| 38 | - Every page is Markdown with a `title` and a `description`; they live in | ||
| 39 | `_source/` (sections can be folders, like `_source/guide/`). | ||
| 40 | - **The sidebar is `_data/nav.yml`.** When you add, move or remove a page, update | ||
| 41 | it too: it decides the sidebar and the previous and next links. A page that | ||
| 42 | isn't in it can still be reached by URL, but readers won't find it. | ||
| 43 | - Use fenced code blocks with a language (```` ```bash ````) so they are | ||
| 44 | highlighted. | ||
| 45 | - Set `search: true` in `_config.yml` (with Pagefind installed) to add search. | ||
| 46 | NOTES | ||
| 47 | } | ||
| 48 | |||
| 49 | =head2 files | ||
| 50 | |||
| 51 | Returns the theme's files, as a hash of path to content. | ||
| 52 | |||
| 53 | =cut | ||
| 54 | |||
| 55 | 191 | ▶ | sub files { |
|
Subroutine
files: called CC=1 SCAR=0.0
Pod
documented
| |||
| 56 | return { | ||
| 57 | 191 | '_config.yml' => <<'FILE', | |
| 58 | # Dapper configuration file. See https://github.com/markdbenson/dapper | ||
| 59 | --- | ||
| 60 | name: Widget Docs | ||
| 61 | description: How to install, configure and use Widget. | ||
| 62 | |||
| 63 | # The address the site will be published at, without a trailing slash. | ||
| 64 | url: https://example.com | ||
| 65 | |||
| 66 | # Set to true to build a search index with Pagefind (https://pagefind.app). | ||
| 67 | search: false | ||
| 68 | |||
| 69 | # Where "dapper deploy" publishes the site. Uncomment "deploy:" and one | ||
| 70 | # of the targets below. See "Deploying with dapper deploy" in the README. | ||
| 71 | #deploy: | ||
| 72 | # s3: | ||
| 73 | # bucket: example.com | ||
| 74 | # github_pages: | ||
| 75 | # branch: gh-pages | ||
| 76 | # command: rsync -av --delete _output/ me@example.com:/var/www/site/ | ||
| 77 | FILE | ||
| 78 | |||
| 79 | '_data/nav.yml' => <<'FILE', | ||
| 80 | # The sidebar, in reading order (site.data.nav). Each page's url must match | ||
| 81 | # its address on the site. | ||
| 82 | - section: Introduction | ||
| 83 | pages: | ||
| 84 | - title: Overview | ||
| 85 | url: / | ||
| 86 | - title: Getting Started | ||
| 87 | url: /getting-started.html | ||
| 88 | - section: Guide | ||
| 89 | pages: | ||
| 90 | - title: Configuration | ||
| 91 | url: /guide/configuration.html | ||
| 92 | - title: Writing Pages | ||
| 93 | url: /guide/writing-pages.html | ||
| 94 | FILE | ||
| 95 | |||
| 96 | '_layout/index.html' => <<'FILE', | ||
| 97 | --- | ||
| 98 | description: "Every docs page: sidebar from _data/nav.yml, the page, and previous and next links" | ||
| 99 | --- | ||
| 100 | [% all = [] %][% FOR section IN site.data.nav %][% FOR p IN section.pages %][% all.push(p) %][% END %][% END %] | ||
| 101 | [% here = -1 %][% i = 0 %][% FOR p IN all %][% IF p.url == page.url %][% here = i %][% END %][% i = i + 1 %][% END %] | ||
| 102 | <!DOCTYPE html> | ||
| 103 | <html lang="en"> | ||
| 104 | <head> | ||
| 105 | <meta charset="utf-8"> | ||
| 106 | <meta name="viewport" content="width=device-width, initial-scale=1"> | ||
| 107 | <title>[% page.title | html %] - [% site.name | html %]</title> | ||
| 108 | [% page.seo %] | ||
| 109 | <link rel="stylesheet" href="/css/site.css"> | ||
| 110 | <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github.min.css" media="(prefers-color-scheme: light)"> | ||
| 111 | <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github-dark.min.css" media="(prefers-color-scheme: dark)"> | ||
| 112 | [% IF site.search %] | ||
| 113 | <link rel="stylesheet" href="/pagefind/pagefind-ui.css"> | ||
| 114 | [% END %] | ||
| 115 | </head> | ||
| 116 | <body> | ||
| 117 | <a class="skip" href="#main">Skip to content</a> | ||
| 118 | <header class="site-header"> | ||
| 119 | <a class="site-name" href="/">[% site.name | html %]</a> | ||
| 120 | [% IF site.search %] | ||
| 121 | <div id="search"></div> | ||
| 122 | [% END %] | ||
| 123 | </header> | ||
| 124 | <div class="layout"> | ||
| 125 | <nav class="sidebar" aria-label="Documentation"> | ||
| 126 | [% FOR section IN site.data.nav %] | ||
| 127 | <h2>[% section.section | html %]</h2> | ||
| 128 | <ul> | ||
| 129 | [% FOR p IN section.pages %] | ||
| 130 | <li><a href="[% p.url %]"[% IF p.url == page.url %] aria-current="page"[% END %]>[% p.title | html %]</a></li> | ||
| 131 | [% END %] | ||
| 132 | </ul> | ||
| 133 | [% END %] | ||
| 134 | </nav> | ||
| 135 | <main id="main" data-pagefind-body> | ||
| 136 | <h1>[% page.title | html %]</h1> | ||
| 137 | [% page.content %] | ||
| 138 | <nav class="pager" aria-label="Previous and next"> | ||
| 139 | [% IF here > 0 %][% before = here - 1 %][% earlier = all.$before %] | ||
| 140 | <a class="prev" href="[% earlier.url %]">← [% earlier.title | html %]</a> | ||
| 141 | [% END %] | ||
| 142 | [% IF here >= 0 AND here < all.size - 1 %][% after = here + 1 %][% later = all.$after %] | ||
| 143 | <a class="next" href="[% later.url %]">[% later.title | html %] →</a> | ||
| 144 | [% END %] | ||
| 145 | </nav> | ||
| 146 | </main> | ||
| 147 | </div> | ||
| 148 | <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script> | ||
| 149 | <script>hljs.highlightAll();</script> | ||
| 150 | [% IF site.search %] | ||
| 151 | <script src="/pagefind/pagefind-ui.js"></script> | ||
| 152 | <script>new PagefindUI({ element: "#search", showSubResults: true });</script> | ||
| 153 | [% END %] | ||
| 154 | </body> | ||
| 155 | </html> | ||
| 156 | FILE | ||
| 157 | |||
| 158 | '_source/_schema.yml' => <<'FILE', | ||
| 159 | # Every docs page must have these. Run "dapper check" to see any problems. | ||
| 160 | required: [title, description] | ||
| 161 | fields: | ||
| 162 | title: | ||
| 163 | type: string | ||
| 164 | max_length: 70 | ||
| 165 | description: | ||
| 166 | type: string | ||
| 167 | max_length: 200 | ||
| 168 | FILE | ||
| 169 | |||
| 170 | '_source/index.md' => <<'FILE', | ||
| 171 | --- | ||
| 172 | title: Overview | ||
| 173 | description: What Widget is, and where to start. | ||
| 174 | --- | ||
| 175 | |||
| 176 | Widget turns your notes into tidy reports. These docs show you how to install | ||
| 177 | it, set it up and get the most from it. | ||
| 178 | |||
| 179 | - New to Widget? Start with [Getting Started](/getting-started.html). | ||
| 180 | - Setting it up for a team? See [Configuration](/guide/configuration.html). | ||
| 181 | |||
| 182 | Replace these pages with your own: edit the Markdown in `_source/`, and the | ||
| 183 | sidebar in `_data/nav.yml`. | ||
| 184 | FILE | ||
| 185 | |||
| 186 | '_source/getting-started.md' => <<'FILE', | ||
| 187 | --- | ||
| 188 | title: Getting Started | ||
| 189 | description: Install Widget and make your first report in five minutes. | ||
| 190 | --- | ||
| 191 | |||
| 192 | ## Install | ||
| 193 | |||
| 194 | ```bash | ||
| 195 | curl -fsSL https://example.com/install.sh | sh | ||
| 196 | ``` | ||
| 197 | |||
| 198 | ## Make a report | ||
| 199 | |||
| 200 | ```bash | ||
| 201 | widget report notes/ --out report.html | ||
| 202 | ``` | ||
| 203 | |||
| 204 | Open `report.html` in your browser. Next, read about | ||
| 205 | [configuration](/guide/configuration.html). | ||
| 206 | FILE | ||
| 207 | |||
| 208 | '_source/guide/configuration.md' => <<'FILE', | ||
| 209 | --- | ||
| 210 | title: Configuration | ||
| 211 | description: Every setting in widget.yml, with examples. | ||
| 212 | --- | ||
| 213 | |||
| 214 | Widget reads `widget.yml` in the current directory: | ||
| 215 | |||
| 216 | ```yaml | ||
| 217 | title: Weekly report | ||
| 218 | include: | ||
| 219 | - notes/*.md | ||
| 220 | ``` | ||
| 221 | |||
| 222 | Setting | Meaning | ||
| 223 | ----------|--------------------------------------- | ||
| 224 | `title` | The report's title | ||
| 225 | `include` | Which files to read, as glob patterns | ||
| 226 | FILE | ||
| 227 | |||
| 228 | '_source/guide/writing-pages.md' => <<'FILE', | ||
| 229 | --- | ||
| 230 | title: Writing Pages | ||
| 231 | description: How to write notes that make good reports. | ||
| 232 | --- | ||
| 233 | |||
| 234 | Write one note per topic, starting with a heading. Widget uses the first | ||
| 235 | paragraph of each note as its summary. | ||
| 236 | |||
| 237 | > Short notes make better reports than long ones. | ||
| 238 | FILE | ||
| 239 | |||
| 240 | 'css/site.css' => <<'FILE', | ||
| 241 | :root { | ||
| 242 | --bg: #ffffff; | ||
| 243 | --text: #1f2328; | ||
| 244 | --muted: #59636e; | ||
| 245 | --accent: #0b62c4; | ||
| 246 | --sidebar: #f6f8fa; | ||
| 247 | --border: #d1d9e0; | ||
| 248 | --code: #f6f8fa; | ||
| 249 | } | ||
| 250 | @media (prefers-color-scheme: dark) { | ||
| 251 | :root { | ||
| 252 | --bg: #0d1117; | ||
| 253 | --text: #e6edf3; | ||
| 254 | --muted: #9198a1; | ||
| 255 | --accent: #58a6ff; | ||
| 256 | --sidebar: #151b23; | ||
| 257 | --border: #2f3742; | ||
| 258 | --code: #151b23; | ||
| 259 | } | ||
| 260 | } | ||
| 261 | * { box-sizing: border-box; } | ||
| 262 | body { margin: 0; background: var(--bg); color: var(--text); font: 17px/1.65 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; } | ||
| 263 | a { color: var(--accent); } | ||
| 264 | a:focus-visible { outline: 3px solid var(--accent); outline-offset: 2px; } | ||
| 265 | .skip { position: absolute; left: -999px; } | ||
| 266 | .skip:focus { left: 1rem; top: 1rem; background: var(--bg); padding: .5rem 1rem; } | ||
| 267 | .site-header { display: flex; justify-content: space-between; align-items: center; gap: 1rem; padding: 1rem 1.5rem; border-bottom: 1px solid var(--border); } | ||
| 268 | .site-name { font-weight: 700; color: var(--text); text-decoration: none; } | ||
| 269 | #search { min-width: 16rem; } | ||
| 270 | .layout { display: grid; grid-template-columns: 16rem minmax(0, 1fr); max-width: 76rem; margin: 0 auto; } | ||
| 271 | .sidebar { background: var(--sidebar); border-right: 1px solid var(--border); padding: 1.5rem; min-height: calc(100vh - 4rem); } | ||
| 272 | .sidebar h2 { font-size: .8rem; text-transform: uppercase; letter-spacing: .06em; color: var(--muted); margin: 1.5rem 0 .5rem; } | ||
| 273 | .sidebar h2:first-child { margin-top: 0; } | ||
| 274 | .sidebar ul { list-style: none; margin: 0; padding: 0; } | ||
| 275 | .sidebar a { display: block; padding: .25rem .5rem; border-radius: 6px; color: var(--text); text-decoration: none; } | ||
| 276 | .sidebar a:hover { background: var(--border); } | ||
| 277 | .sidebar a[aria-current="page"] { background: var(--accent); color: var(--bg); } | ||
| 278 | main { padding: 2rem 2.5rem 3rem; max-width: 50rem; } | ||
| 279 | main h1 { margin-top: 0; } | ||
| 280 | pre, code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: .9em; } | ||
| 281 | pre { background: var(--code); border: 1px solid var(--border); border-radius: 8px; padding: 1rem; overflow-x: auto; } | ||
| 282 | pre code.hljs { background: transparent; padding: 0; } | ||
| 283 | :not(pre) > code { background: var(--code); padding: .1em .35em; border-radius: 4px; } | ||
| 284 | table { border-collapse: collapse; } | ||
| 285 | th, td { border: 1px solid var(--border); padding: .4rem .75rem; text-align: left; } | ||
| 286 | blockquote { margin: 0; padding: .25rem 1rem; border-left: 4px solid var(--accent); color: var(--muted); } | ||
| 287 | .pager { display: flex; justify-content: space-between; gap: 1rem; margin-top: 3rem; padding-top: 1.5rem; border-top: 1px solid var(--border); } | ||
| 288 | .pager .next { margin-left: auto; } | ||
| 289 | @media (max-width: 760px) { | ||
| 290 | .layout { grid-template-columns: 1fr; } | ||
| 291 | .sidebar { min-height: 0; border-right: 0; border-bottom: 1px solid var(--border); } | ||
| 292 | main { padding: 1.5rem 1.25rem; } | ||
| 293 | } | ||
| 294 | FILE | ||
| 295 | }; | ||
| 296 | } | ||
| 297 | |||
| 298 | 190 | 1; | |