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 +4 -4
- data/README.md +113 -51
- data/_includes/item-doc-page.html +13 -5
- data/_layouts/docs-base.html +20 -12
- data/_sass/open-project-mixins.scss +7 -3
- data/assets/js/opf.js +16 -4
- metadata +4 -4
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 8a673364013abeb093b9d6a59734a968b56d66a51758968b25837d58922c9a7c
|
4
|
+
data.tar.gz: 3a6fca4a290f2366b3e9166c2696cc1c48e5e718d12e2f0289e929049a448c4a
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
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
|
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
|
-
|
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
|
-
|
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
|
-
|
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
|
-
|
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
|
-
|
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,
|
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
|
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>.
|
368
|
+
- <name>.adoc
|
388
369
|
- <name>/
|
389
370
|
- assets/
|
390
371
|
- symbol.svg
|
391
372
|
- _specs/
|
392
|
-
- <name>.
|
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>.
|
404
|
-
placed under _software/ or _specs/ subdirectory
|
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
|
-
|
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
|
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.
|
470
|
-
`installation.
|
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
|
-
-
|
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: " ", " " }}
|
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
|
-
|
37
|
-
<
|
38
|
-
|
39
|
-
|
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 %}
|
data/_layouts/docs-base.html
CHANGED
@@ -3,7 +3,7 @@ layout: default
|
|
3
3
|
---
|
4
4
|
|
5
5
|
{% assign nav = page.navigation | default: layout.navigation %}
|
6
|
-
{% assign
|
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
|
-
|
30
|
-
|
31
|
-
|
29
|
+
<span class="section-title">
|
30
|
+
{{ page.title|replace: " ", " " }}
|
31
|
+
</span>
|
32
32
|
{% endif %}
|
33
33
|
|
34
34
|
<div class="nav-header">
|
35
35
|
<h3 class="title">
|
36
|
-
|
36
|
+
{% capture docs_nav_title %}
|
37
37
|
{{ layout.docs_title }}{% if selected_section %}: {{ selected_section.title }}{% endif %}
|
38
|
-
|
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
|
-
|
42
|
-
<
|
43
|
-
|
44
|
-
|
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 {
|
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 {
|
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
|
-
|
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
|
-
|
159
|
-
|
160
|
-
|
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.
|
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-
|
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.
|
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.
|
82
|
+
version: 1.2.2
|
83
83
|
- !ruby/object:Gem::Dependency
|
84
84
|
name: bundler
|
85
85
|
requirement: !ruby/object:Gem::Requirement
|