jekyll-theme-open-project 1.2.1 → 1.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: bd51e58cf787fe3eed46a3766151ac1a46a651528baa440b93edbb5ebd24c5ba
4
- data.tar.gz: 003d4f632e2422ec7ce59e81c1fbeda2b5d395e592d51ea3b2e36e7110a57295
3
+ metadata.gz: 8a673364013abeb093b9d6a59734a968b56d66a51758968b25837d58922c9a7c
4
+ data.tar.gz: 3a6fca4a290f2366b3e9166c2696cc1c48e5e718d12e2f0289e929049a448c4a
5
5
  SHA512:
6
- metadata.gz: 053c60c6f0d72ed930ae5d3cc0e9bff22fb4e2d9189a98044495d712627829cd473e8d09665571190acf19e74da9b0f653cd285ad4687de13c8b2ba330c2935f
7
- data.tar.gz: 3a75201bdc86cf1ccec7cb4174e2b9c2dd65de0e55c02b90f1cabdbbbd97b3b6c96fe191a150eff46818b9ed2ca0085fde6ce939a1a94247ff171892ac762bfc
6
+ metadata.gz: acbfaa01271a7f2da212b412c125c2f205e6f718674989668f8103d3c3bde74c386037cbff1410a70cde8eadd038afbfb1f1a186effdf5f69fc0c13916bba67c
7
+ data.tar.gz: 5557395128439c9b70526519949c2447531da8e791f9f578bc073547d9173af6569e2e9650d29d83978108d9b3f39b8dd411a3dae07612a0d001f75d3f7bdb2e
data/README.md CHANGED
@@ -16,10 +16,7 @@ to AWS S3.
16
16
 
17
17
  * [General site setup](#general-setup)
18
18
  * [Hub site setup](#hub-site)
19
- * [Project site setup](#project-site)
20
-
21
- * Describing open projects:
22
- [Project data structure](#describing-a-project-shared-data-structure)
19
+ * [Project site setup](#project-site) and describing your software and specs
23
20
 
24
21
  * Customizing site looks:
25
22
 
@@ -219,7 +216,7 @@ author:
219
216
  For hub-wide posts, put posts under _posts/ in site root and name files e.g.
220
217
  `2018-04-20-welcome-to-jekyll.markdown` (no change from the usual Jekyll setup).
221
218
 
222
- For project posts, see below about shared project data structure.
219
+ For project posts, see below the project site section.
223
220
 
224
221
 
225
222
  ## Hub site
@@ -248,9 +245,7 @@ tag_namespaces:
248
245
 
249
246
  ### Project, spec and software data
250
247
 
251
- See the section about project data structure.
252
-
253
- _When used within hub site_ (only), each project subdirectory
248
+ Each project subdirectory
254
249
  must contain a file "index.md" with frontmatter like this:
255
250
 
256
251
  ```yaml
@@ -264,26 +259,10 @@ featured: true | false
264
259
 
265
260
  site:
266
261
  git_repo_url: <Git URL to standalone project site source repo>
267
- home_url: <URL to standalone project site>
268
262
 
269
- # Note: Avoid whitespaces and other characters that may make Jekyll
270
- # percent-encode the tag in URLs. Replace " " (a regular space)
271
- # with "_" (underline); underlines will be rewritten as spaces when tags
272
- # are presented to site users.
273
- # Tag can be prepended with a namespace to signify the type,
274
- # e.g. chosen programming language or target viewer audience
275
- # (see hub site configuration for tag namespace setup).
276
- # Avoid long namespace/tag combos as they can overflow item’s card widget.
277
- tags: [Ruby, Python, RFC, "<some_namespace_id>:<appropriate_tag>"]
263
+ home_url: <URL to standalone project site>
278
264
 
279
- # NOTE: Must match corresponding hub site’s configuration entry.
280
- tag_namespaces:
281
- software:
282
- namespace_id: "Human-readable namespace name"
283
- # E.g.:
284
- # writtenin: "Written in"
285
- specs:
286
- namespace_id: "Human-readable namespace name"
265
+ tags: [some, tags]
287
266
  ```
288
267
 
289
268
  ### Project index page
@@ -340,7 +319,7 @@ hero_include: index-page-hero.html
340
319
 
341
320
  ## Project site
342
321
 
343
- When project is set up as a standalone site, _config.yml should include
322
+ For standalone sites of each of your projects, _config.yml should include
344
323
  site-wide `title` that is the same as project name.
345
324
 
346
325
  Additional items allowed/expected in _config.yml:
@@ -363,45 +342,113 @@ algolia_search:
363
342
  api_key: '<your Algolia API key>'
364
343
  index_name: '<your Algolia index name>'
365
344
  # Only add this if you want to use Algolia’s search on your project site.
366
- ```
367
-
368
- File layout is the same as described in the section
369
- about shared project data structure, with _software, _specs, _posts, assets
370
- subdirectories found in the root of your Jekyll site.
371
345
 
346
+ # NOTE: Must match corresponding hub site’s configuration entry.
347
+ tag_namespaces:
348
+ software:
349
+ namespace_id: "Human-readable namespace name"
350
+ # E.g.:
351
+ # writtenin: "Written in"
352
+ specs:
353
+ namespace_id: "Human-readable namespace name"
354
+ ```
372
355
 
373
- ## Describing a project: shared data structure
356
+ ### File structure
374
357
 
375
358
  Each project is expected to have a machine-readable and unique name, a title,
376
- a description, a symbol, and one or more software products and/or specs.
359
+ a description, a symbol, one or more software products and/or specs.
360
+ Blog, docs, and other pages are optional.
377
361
 
378
- Following data structure is shared and used to describe projects,
379
- whether on hub home site or each individual project site:
362
+ Following data structure is used for project sites:
380
363
 
381
- - <project-name>/
382
- - _posts/
383
- - 2038-02-31-blog-post-title.markdown
364
+ - <project-name>/ # Jekyll site root containing _config.yml
384
365
  - assets/
385
- - symbol.svg
366
+ - symbol.svg # Required — project logo
386
367
  - _software/
387
- - <name>.md
368
+ - <name>.adoc
388
369
  - <name>/
389
370
  - assets/
390
371
  - symbol.svg
391
372
  - _specs/
392
- - <name>.md
373
+ - <name>.adoc
374
+ - _pages/
375
+ - blog.html
376
+ - software.html # Software index
377
+ - specs.html # Spec index
378
+ - docs.html
379
+ - docs/ # Project-wide documentation
380
+ - getting-started.adoc
381
+ - <some-page>.adoc
382
+ - _posts/ # Blog
383
+ - 2038-02-31-blog-post-title.markdown
384
+ - _layouts/
385
+ - docs.html
393
386
 
394
387
  ### Blog
395
388
 
396
389
  Author project site blog posts as described in the general site setup section.
397
390
 
391
+ ### Project docs
392
+
393
+ Two kinds of docs can coexist on a given open project site:
394
+
395
+ - Project-wide documentation. It’s well-suited for describing the idea behind the project,
396
+ the “whys”, for tutorials and similar.
397
+ - Documentation specific to a piece of software (of which there can be more than one
398
+ for any given open project). This may go in detail about that piece of software,
399
+ and things like implementation specifics, extended installation instructions,
400
+ development guidelines may go here.
401
+
402
+ This section is about project-wide docs, for software docs see software and specs section.
403
+
404
+ The suggested convention is to create
405
+ _pages/docs.adoc for the main documentation page, put other pages under docs/,
406
+ and create custom layout `docs.html` that inherits from `docs-base`, specifies
407
+ `html-class: docs-page` and provides `navigation` structure linking to all docs pages
408
+ in a hierarchy.
409
+
410
+ Example _layouts/docs.html:
411
+
412
+ ```
413
+ ---
414
+ layout: docs-base
415
+ html-class: docs-page
416
+ docs_title: <Project name>
417
+ navigation:
418
+ items:
419
+ - title: Introduction
420
+ items:
421
+ - title: "Overview"
422
+ path: /docs/
423
+ - title: "Get started"
424
+ path: /docs/getting-started/
425
+ ---
426
+
427
+ {{ content }}
428
+ ```
429
+
430
+ Example _pages/docs.adoc:
431
+
432
+ ```
433
+ ---
434
+ layout: docs
435
+ title: Overview
436
+ html-class: >-
437
+ overview
438
+ # ^^ classes you can use to style the page in your custom CSS rules
439
+ ---
440
+ :page-liquid:
441
+
442
+ Your main docs page goes here.
443
+ ```
444
+
398
445
  ### Software and specs
399
446
 
400
447
  An open project serves as an umbrella for related
401
448
  software products and/or specifications.
402
449
 
403
- Each product or spec is described by its own <name>.md file with frontmatter,
404
- placed under _software/ or _specs/ subdirectory, respectively,
450
+ Each product or spec is described by its own <name>.adoc file with frontmatter,
451
+ placed under _software/ or _specs/ subdirectory (respectively)
405
452
  of your open project’s Jekyll site.
406
453
 
407
454
  A software product additionally is required to have a symbol in SVG format,
@@ -418,7 +465,15 @@ description: A sentence.
418
465
  # Not necessarily shown to the user,
419
466
  # but used for HTML metadata if jekyll-seo-tag is enabled
420
467
 
421
- tags: [Python, Ruby]
468
+ # Note: Avoid whitespaces and other characters that may make Jekyll
469
+ # percent-encode the tag in URLs. Replace " " (a regular space)
470
+ # with "_" (underline); underlines will be rewritten as spaces when tags
471
+ # are presented to site users.
472
+ # Tag can be prepended with a namespace to signify the type,
473
+ # e.g. chosen programming language or target viewer audience
474
+ # (see hub site configuration for tag namespace setup).
475
+ # Avoid long namespace/tag combos as they can overflow item’s card widget.
476
+ tags: [Ruby, Python, RFC, "<some_namespace_id>:<appropriate_tag>"]
422
477
 
423
478
  feature_with_priority: 1
424
479
  # With this key, software or spec will be featured on home
@@ -452,10 +507,11 @@ docs_url: https://docs.rs/proj/ver/…/
452
507
  #### Displaying software docs
453
508
 
454
509
  Inside the repository and optionally subtree specified under `docs`
455
- in above sample, place a file called `navigation.md` containing
510
+ in above sample, place a file `navigation.adoc` (or `navigation.md`) containing
456
511
  only frontmatter, following this sample:
457
512
 
458
513
  ```yaml
514
+ ---
459
515
  items:
460
516
  - title: Introduction
461
517
  items:
@@ -464,10 +520,13 @@ items:
464
520
  - title: Usage
465
521
  items:
466
522
  - { title: Basic, path: basic-usage/ }
523
+ ---
524
+
525
+ = Navigation
467
526
  ```
468
527
 
469
- In the same directory, place the required document pages—in this case, `overview.md`,
470
- `installation.md`, and `basic-usage.md`. Each file must contain
528
+ In the same directory, place the required document pages—in this case, `overview.adoc`,
529
+ `installation.adoc`, and `basic-usage.adoc`. Each file must contain
471
530
  standard YAML frontmatter with at least `title` specified.
472
531
 
473
532
  During project site build, Jekyll pulls docs for software that’s part of the
@@ -594,7 +653,7 @@ Commonly used layouts are:
594
653
  - blog-index: Blog index page. Pages using this layout are recommended
595
654
  to supply hero_include.
596
655
 
597
- - post: Blog post
656
+ - post: Blog post.
598
657
 
599
658
  - project-index: Open project index page (hub site only).
600
659
  Suggested to supply hero_include.
@@ -608,9 +667,12 @@ Commonly used layouts are:
608
667
  Suggested to supply hero_include.
609
668
  Will show a list of specs across projects within the hub.
610
669
 
611
- - product: Software product (project site only)
670
+ - product: Software product (project site only).
671
+
672
+ - spec: Open specification (project site only).
612
673
 
613
- - spec: Open specification (project site only)
674
+ - default: Main layout; among other things adds `html-class` specified in frontmatter
675
+ of last inheriting layout and the concrete page frontmatter to the `<body>` element.
614
676
 
615
677
  ### Page frontmatter
616
678
 
@@ -1,3 +1,8 @@
1
+ {% comment %}
2
+ This page conforms to the structure introduced by docs-base layout,
3
+ supporting expandable navigation widget.
4
+ {% endcomment %}
5
+
1
6
  {% assign product_base_url = page.url | split: "/" | slice: 0, 3 | join: "/" | append: "/" %}
2
7
  {% assign docs_base_url = product_base_url | append: "docs/" %}
3
8
 
@@ -10,6 +15,7 @@
10
15
  {% assign docs_base_url = product_base_url | append: "docs/" %}
11
16
  {% assign item_docs = include.items | where_exp: "item", "item.url contains docs_base_url" %}
12
17
  {% assign nav = item_docs | where_exp: "item", "item.path contains 'docs/navigation'" | first %}
18
+ {% assign num_top_nav_items = nav.items | size %}
13
19
  {% assign item_data = include.items | where_exp: "item", "item.url == product_base_url" | first %}
14
20
 
15
21
  {% if nav == nil %}
@@ -17,7 +23,7 @@
17
23
  {% endif %}
18
24
 
19
25
  {% if is_docs_landing != true %}
20
- <header class="documentation-header">
26
+ <header class="documentation-header {% if num_top_nav_items > 0 %} has-nav {% endif %}">
21
27
  <span class="section-title">
22
28
  {{ page.title|replace: " ", "&nbsp;" }}
23
29
  </span>
@@ -33,10 +39,12 @@
33
39
  <a href="{{ product_base_url | relative_url }}">{{ item_data.title }}</a>
34
40
  </h3>
35
41
 
36
- <span class="nav-toggle-icon">
37
- <i class="open far fa-ellipsis-v"></i>
38
- <i class="close far fa-times"></i>
39
- </span>
42
+ {% if num_top_nav_items > 0 %}
43
+ <span class="nav-toggle-icon">
44
+ <i class="open far fa-ellipsis-v"></i>
45
+ <i class="close far fa-times"></i>
46
+ </span>
47
+ {% endif %}
40
48
  </div>
41
49
  </header>
42
50
  {% endif %}
@@ -3,7 +3,7 @@ layout: default
3
3
  ---
4
4
 
5
5
  {% assign nav = page.navigation | default: layout.navigation %}
6
- {% assign num_nav_sections = nav.sections | size %}
6
+ {% assign num_top_nav_items = nav.items | size %}
7
7
 
8
8
  {% for item in nav.items %}
9
9
  {% assign topmost_item = item %}
@@ -24,29 +24,37 @@ layout: default
24
24
  {% endfor %}
25
25
 
26
26
 
27
- <header class="documentation-header">
27
+ <header class="documentation-header {% if num_top_nav_items > 0 %} has-nav {% endif %}">
28
28
  {% if page.title %}
29
- <span class="section-title">
30
- {{ page.title|replace: " ", "&nbsp;" }}
31
- </span>
29
+ <span class="section-title">
30
+ {{ page.title|replace: " ", "&nbsp;" }}
31
+ </span>
32
32
  {% endif %}
33
33
 
34
34
  <div class="nav-header">
35
35
  <h3 class="title">
36
- <a href="javascript: void 0;">
36
+ {% capture docs_nav_title %}
37
37
  {{ layout.docs_title }}{% if selected_section %}: {{ selected_section.title }}{% endif %}
38
- </a>
38
+ {% endcapture %}
39
+
40
+ {% if num_top_nav_items > 0 %}
41
+ <a href="javascript: void 0;">{{ docs_nav_title }}</a>
42
+ {% else %}
43
+ <span>{{ docs_nav_title }}</span>
44
+ {% endif %}
39
45
  </h3>
40
46
 
41
- <span class="nav-toggle-icon">
42
- <i class="open far fa-ellipsis-v"></i>
43
- <i class="close far fa-times"></i>
44
- </span>
47
+ {% if num_top_nav_items > 0 %}
48
+ <span class="nav-toggle-icon">
49
+ <i class="open far fa-ellipsis-v"></i>
50
+ <i class="close far fa-times"></i>
51
+ </span>
52
+ {% endif %}
45
53
  </div>
46
54
  </header>
47
55
 
48
56
 
49
- <section class="documentation {{ page.html-class }}">
57
+ <section class="documentation {% if num_top_nav_items > 0 %}has-nav{% endif %}">
50
58
  <nav class="docs-nav">
51
59
  <ul class="nav-items">
52
60
  {% for item in nav.items %}
@@ -206,8 +206,6 @@
206
206
 
207
207
  transition: background .1s linear, border-bottom .1s linear, transform .1s linear;
208
208
 
209
- cursor: pointer;
210
-
211
209
  .section-title {
212
210
  flex: 1;
213
211
  flex-grow: 0;
@@ -236,7 +234,13 @@
236
234
  text-transform: uppercase;
237
235
  letter-spacing: 0.08em;
238
236
 
239
- a { @include static-link-color(#444); }
237
+ a {
238
+ @include static-link-color(#444);
239
+ }
240
+
241
+ .nav-toggle-icon {
242
+ cursor: pointer;
243
+ }
240
244
  }
241
245
 
242
246
  .logo-container {
data/assets/js/opf.js CHANGED
@@ -2,6 +2,9 @@
2
2
  'use strict';
3
3
 
4
4
 
5
+ var bigscreenBreakpoint = 900;
6
+ // Conforms to CSS @media rules
7
+
5
8
  var body = document.querySelector('body');
6
9
 
7
10
  // TODO: Best way (preferably w/o Node) to split these across files
@@ -115,7 +118,8 @@
115
118
 
116
119
  var docsNavItemsContainer = docsNav.querySelector('.nav-items');
117
120
  var docsHeader = mainRoot.querySelector('header.documentation-header');
118
- var docsHeaderLink = docsHeader.querySelector('a');
121
+
122
+ var hasNav = docsHeader.classList.contains('has-nav');
119
123
  var docsHeaderH = docsHeader.offsetHeight - 1; // 1px to compensate for border
120
124
 
121
125
 
@@ -155,9 +159,17 @@
155
159
  else { open(docsNav); }
156
160
  };
157
161
 
158
- docsHeader.addEventListener('click', toggle);
159
-
160
- open(docsNav);
162
+ if (hasNav) {
163
+ docsHeader.addEventListener('click', toggle);
164
+ var viewportW = Math.max(document.documentElement.clientWidth, window.innerWidth || 0);
165
+ if (viewportW > bigscreenBreakpoint) {
166
+ open(docsNav);
167
+ } else {
168
+ collapse(docsNav);
169
+ }
170
+ } else {
171
+ collapse(docsNav);
172
+ }
161
173
 
162
174
 
163
175
  // Hiding docs nav
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: jekyll-theme-open-project
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.2.1
4
+ version: 1.2.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - Ribose Inc.
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2018-12-24 00:00:00.000000000 Z
11
+ date: 2018-12-26 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: jekyll
@@ -72,14 +72,14 @@ dependencies:
72
72
  requirements:
73
73
  - - '='
74
74
  - !ruby/object:Gem::Version
75
- version: 1.2.1
75
+ version: 1.2.2
76
76
  type: :runtime
77
77
  prerelease: false
78
78
  version_requirements: !ruby/object:Gem::Requirement
79
79
  requirements:
80
80
  - - '='
81
81
  - !ruby/object:Gem::Version
82
- version: 1.2.1
82
+ version: 1.2.2
83
83
  - !ruby/object:Gem::Dependency
84
84
  name: bundler
85
85
  requirement: !ruby/object:Gem::Requirement