lib/App/Dapper/Theme/Docs.pm

filter: Statementstmt 100% 15 / 15 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 7 / 7 Podpod 100% 3 / 3 totaltotal 100% 25 / 25 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« lib/App/Dapper/Theme/Business.pm ↑ Summary lib/App/Dapper/Theme/Portfolio.pm »
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 32 ▶use utf8;
Subroutine BEGIN: called CC=1 SCAR=0.0
16 32 ▶use 5.010;
Subroutine BEGIN: called CC=1 SCAR=0.0
17 32 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
18 32 ▶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 32 ▶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 32 ▶sub notes {
Subroutine notes: called CC=1 SCAR=0.0
Pod documented
35 32 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 32 ▶sub files {
Subroutine files: called CC=1 SCAR=0.0
Pod documented
56 return {
57 32 '_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 %]">&larr; [% 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 %] &rarr;</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 32 1;
« lib/App/Dapper/Theme/Business.pm ↑ Summary lib/App/Dapper/Theme/Portfolio.pm »