jekyll-theme-open-project 1.0.0.pre3 → 1.0.0.pre4

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 3df314ababa96df5cf5719237344057cda2b2acf
4
- data.tar.gz: 7977f0d4a1aaba0344dae0667aca7ae6d769ee66
3
+ metadata.gz: 9dfb7f0fe421f7f9a85c8de523114d11af0aaf58
4
+ data.tar.gz: 997932d8fba5a0b3ec255bcfd12feec724571204
5
5
  SHA512:
6
- metadata.gz: a0daf97b370f660792aea54c1e55b9ac091161a5a3470e43c5cdd478aa96230e9492c67fce4f1e007debae9482941bdb46627b841ef60ab39d4950f1dc370dca
7
- data.tar.gz: a2007a720f54cff01def36c929357bf681ed702c5347e9e34e6a7f2bc7c4eaf7e3e03153c5773b3f4a6c7fd95acca9d6c787853311a505d45c488a0f7f878d1f
6
+ metadata.gz: d288ce95ad99f49db13987ccbc1e8e874bb1c63002533a4cf22dcb26ecf7b9132e179ca85da9cfeb62da60ef65f765d38f1b8cdeb29ff858a947d19f6d4cb719
7
+ data.tar.gz: 9731f0c687cca273db333e85467c9e279e47f8a8422faf5bc60a18506e654f5fa6c0211bec63385423ed8bd5c79d91acefc047c062b64d6a7325a7319a484876
data/README.md CHANGED
@@ -35,8 +35,10 @@ to AWS S3.
35
35
  ### Getting started with Ruby
36
36
 
37
37
  If you aren’t using Ruby often, the recommended way to install it is with RVM.
38
- Refer to RVM docs and use it to install a reasonably fresh Ruby version,
39
- let’s say 2.4.4.
38
+ Refer to RVM docs and use it to install a fresh Ruby version.
39
+
40
+ The currently recommended version is 2.4.4, it’s known to not work under 2.3
41
+ and it hasn’t been tested on newer versions.
40
42
 
41
43
  ### Start new Jekyll site
42
44
 
@@ -48,7 +50,7 @@ Add this line to your Jekyll site's `Gemfile`,
48
50
  replacing default theme requirement:
49
51
 
50
52
  ```ruby
51
- gem 'jekyll-theme-open-project'
53
+ gem "jekyll-theme-open-project"
52
54
  ```
53
55
 
54
56
  (Jekyll’s default theme was “minima” at the time of this writing.)
@@ -59,12 +61,14 @@ Also in the `Gemfile`, add two important plugins to the `:jekyll_plugins` group.
59
61
  ```ruby
60
62
  group :jekyll_plugins do
61
63
  gem "jekyll-seo-tag"
64
+ gem "jekyll-data"
65
+ gem "jekyll-data"
62
66
  gem "jekyll-theme-open-project-helpers"
63
67
  # ...other plugins, if you use any
64
68
  end
65
69
  ```
66
70
 
67
- Execute to install dependencies:
71
+ Execute the following to install dependencies:
68
72
 
69
73
  $ bundle
70
74
 
@@ -93,6 +97,7 @@ These settings are required to both site types (hub and project).
93
97
 
94
98
  - You may want to remove the default about.md page added by Jekyll,
95
99
  as this theme does not account for its existence.
100
+ - Add `hero_include: home-hero.html` to YAML frontmatter in `index.md`.
96
101
  - Add following items to _config.yml
97
102
  (don’t forget to remove default theme requirement):
98
103
 
@@ -106,36 +111,14 @@ These settings are required to both site types (hub and project).
106
111
  pitch: Site pitch
107
112
  # The above two are used on home hero unit.
108
113
 
114
+ permalink: /blog/:month-:day-:year/:title/
109
115
 
110
- # Further settings are not expected to be changed,
111
- # unless you know what you’re doing:
112
-
113
- markdown: kramdown
114
116
  theme: jekyll-theme-open-project
115
117
 
116
- # Theme layouts can include from any directory, not just _includes.
117
- # There’s a quirk in Jekyll’s “safe” behavior around include and gem-based themes
118
- # which means include_relative wouldn’t cut it.
119
- includes_dir: .
120
-
121
- collections:
122
- posts:
123
- output: true
124
- permalink: /blog/:month-:day-:year/:title/
125
- pages:
126
- output: true
127
- permalink: /:name/
128
-
129
- defaults:
130
- - scope:
131
- path: ""
132
- values:
133
- layout: default
134
- - scope:
135
- path: _posts
136
- type: posts
137
- values:
138
- layout: post
118
+ social:
119
+ links:
120
+ - https://twitter.com/<orgname>
121
+ - https://github.com/<orgname>
139
122
  ```
140
123
 
141
124
  ### Logo
@@ -225,20 +208,12 @@ and offers a software and specification index.
225
208
  Additional items allowed/expected in _config.yml:
226
209
 
227
210
  ```yaml
228
- social:
229
- links:
230
- - https://twitter.com/RiboseUS
231
- - https://github.com/riboseinc
211
+ is_hub: true
232
212
 
233
213
  # Since a hub would typically represent an organization as opposed
234
214
  # to individual, this would make sense:
235
215
  seo:
236
216
  type: Organization
237
-
238
- collections:
239
- projects:
240
- output: false
241
- # ... (other collections)
242
217
  ```
243
218
 
244
219
  ### Project, spec and software data
@@ -325,33 +300,11 @@ authors:
325
300
  email: your-email@example.com
326
301
 
327
302
  author: "Company or Individual Name Goes Here"
328
-
329
- collections:
330
- # ... (other collections)
331
- software:
332
- output: true
333
- permalink: /:name/
334
- specs:
335
- output: true
336
- permalink: /:name/
337
-
338
- defaults:
339
- # ... (other defaults)
340
- - scope:
341
- path: _software
342
- type: software
343
- values:
344
- layout: product
345
- - scope:
346
- path: _specs
347
- type: specs
348
- values:
349
- layout: spec
350
303
  ```
351
304
 
352
305
  File layout is the same as described in the section
353
- about shared project data structure, with _software, _specs, _posts directories
354
- found in the root of your Jekyll site.
306
+ about shared project data structure, with _software, _specs, _posts, _includes
307
+ directories found in the root of your Jekyll site.
355
308
 
356
309
 
357
310
  ## Describing a project: shared data structure
@@ -368,20 +321,16 @@ whether on hub home site or each individual project site:
368
321
  - _includes/
369
322
  - symbol.svg
370
323
  - _software/
324
+ - <name>.md
371
325
  - <name>/
372
- - symbol.svg
373
- - index.md
374
- - _docs/
375
- - <version>/
376
- - overview.md
377
- - <documentation-page-name>.md
326
+ - _includes/
327
+ - symbol.svg
378
328
  - _specs/
379
329
  - <name>.md
380
330
 
381
331
  ### Blog
382
332
 
383
- Project blog posts should be authored as described in the universal setup
384
- section.
333
+ Author project site blog posts as described in the universal setup section.
385
334
 
386
335
  ### Software and specs
387
336
 
@@ -392,10 +341,10 @@ Each product or spec is described by its own <name>.md file with frontmatter,
392
341
  placed under _software/ or _specs/ subdirectory, respectively,
393
342
  of your open project’s Jekyll site.
394
343
 
395
- Note: even though they’re in different subdirectories, all software products and specs
396
- within one project share URL namespace and hence must have unique names.
344
+ A software product additionally is required to have a symbol in SVG format,
345
+ placed in <name>/_includes/symbol.svg under _software/ directory.
397
346
 
398
- YAML frontmatter that can be used with both software and specs:
347
+ YAML frontmatter that is expected with both software and specs:
399
348
 
400
349
  ```yaml
401
350
  title: A Few Words
@@ -405,32 +354,23 @@ title: A Few Words
405
354
  description: A sentence.
406
355
  # Not necessarily shown to the user,
407
356
  # but used for HTML metadata if jekyll-seo-tag is enabled
357
+
358
+ tags: [Python, Ruby]
408
359
  ```
409
360
 
410
361
  ### Software product
411
362
 
412
- YAML frontmatter specific to software:
363
+ YAML frontmatter required for software:
413
364
 
414
365
  ```yaml
415
- version: v1.2.3
416
- docs_url: https://foobar.readthedocs.io/en/latest
417
- repo_url: https://github.com/…
418
- stack: [Python, Django, AWS]
366
+ repo_url: https://github.com/riboseinc/asciidoctor-rfc
367
+ docs:
368
+ git_repo_url: git@example.com:path/to-repo.git
369
+ git_repo_subtree: docs
419
370
  ```
420
371
 
421
- #### Documentation
422
-
423
- **Recommended:** use a dedicated service supporting versioned and well-structured
424
- multi-page docs, such as Read the Docs. You can link users to that documentation
425
- using docs_url in software product’s frontmatter.
426
-
427
- Otherwise, if this open project’s page will serve as the authoritative source
428
- of documentation for the software product, documentation contents are expected
429
- to follow frontmatter.
430
-
431
- Keep in mind that project name and description from before
432
- will be displayed by the theme first. Start with second-level header (##),
433
- with installation instructions or quick-start guide.
372
+ About the `docs` key in this frontmatter, see nearby section
373
+ about documentation.
434
374
 
435
375
  ### Specification
436
376
 
@@ -449,9 +389,30 @@ ietf_datatracker_ver: "01"
449
389
  source_url: https://example.com/spec-source-markup
450
390
  ```
451
391
 
452
- Specs that are not hosted elsewhere (such as ietf.org for RFCs)
453
- are expected to contain the actual specification content after frontmatter.
454
- Start with second-level header (##).
392
+ ### Documentation for specs and software
393
+
394
+ Documentation contents for software should be kept in software
395
+ package’s own repository, under a directory such as `docs/`.
396
+ Inside that directory, place a file called `navigation.md` containing
397
+ only frontmatter, in format like this:
398
+
399
+ ```yaml
400
+ sections:
401
+ - name: Introduction
402
+ items:
403
+ - overview
404
+ - installation
405
+ - name: Usage
406
+ items:
407
+ - basic
408
+ ```
409
+
410
+ In the same directory, place the required document pages—in this case, overview.md,
411
+ installation.md, and basic.md. Each document page is required to contain
412
+ standard YAML frontmatter with at least `title` specified.
413
+
414
+ During project site build, Jekyll will pull docs for software products
415
+ that are hosted under that project site.
455
416
 
456
417
  ### Symbol
457
418
 
@@ -525,8 +486,13 @@ under assets/css/style.scss with following exact contents:
525
486
  ```
526
487
  ---
527
488
  ---
489
+ // Font imports can go here
528
490
 
529
- @import '{{ site.theme }}';
491
+ // Variable redefinitions can go here
492
+
493
+ @import 'jekyll-theme-open-project';
494
+
495
+ // Custom rules can go here
530
496
  ```
531
497
 
532
498
  There are two aspects to theme customization:
@@ -552,6 +518,8 @@ The rule would look like this:
552
518
  Following are the variables along with their defaults:
553
519
 
554
520
  ```scss
521
+ $font-family: Helvetica, Arial, sans-serif !default;
522
+
555
523
  # Primary color—should be bright but dark enough to be readable,
556
524
  # since some text elements are set using this color:
557
525
  $primary-color: lightblue !default;
@@ -570,6 +538,9 @@ $accent-color: red !default;
570
538
  $header-background: $primary-dark-color !default;
571
539
  $hero-background: $primary-dark-color !default;
572
540
 
541
+ # This is for the big big hero unit on home page.
542
+ $superhero-background: $primary-dark-color !default;
543
+
573
544
  # Below customize colors for different sections of the site.
574
545
  $hub-software--primary-color: lightsalmon !default;
575
546
  $hub-software--primary-dark-color: tomato !default;
@@ -2,14 +2,15 @@
2
2
  <h1 class="title">{{ site.tagline }}</h1>
3
3
  <p class="desc">{{ site.pitch | safe }}</p>
4
4
  <div class="cta explore-projects" role="presentation">
5
- <a class="button" href="{{ "/projects/" | relative_url }}">
6
- <i class="icon far fa-search"></i>
7
- Explore Projects
8
- </a>
9
- </div>
10
- </div>
11
- <div role="presentation" class="illustration">
12
- <div role="presentation" class="logo">
13
- {% include symbol-hero.svg %}
5
+ {% if site.is_hub %}
6
+ <a class="button" href="{{ "/projects/" | relative_url }}">
7
+ <i class="icon far fa-search"></i>
8
+ Explore Projects
9
+ </a>
10
+ {% else if %}
11
+ <a class="button" href="{{ site.get_started_url | relative_url }}">
12
+ Get Started
13
+ </a>
14
+ {% endif %}
14
15
  </div>
15
16
  </div>
@@ -57,7 +57,7 @@
57
57
  {% assign num_other_projects = other_projects | size %}
58
58
  {% if num_other_projects > 0 %}
59
59
  <section class="other-projects">
60
- {% include symbol.svg %}
60
+ {% include _includes/symbol.svg %}
61
61
 
62
62
  <h2 class="title">Other Projects</h2>
63
63
 
@@ -76,16 +76,7 @@
76
76
  {{ item.description }}
77
77
  </p>
78
78
 
79
- {% assign num_tags = item.tags | size %}
80
- {% if num_tags > 0 %}
81
- <footer class="meta">
82
- <ul class="tags">
83
- {% for tag in item.tags %}
84
- <li>{{ tag }}</li>
85
- {% endfor %}
86
- </ul>
87
- </footer>
88
- {% endif %}
79
+ {% include tag-list.html tags=item.tags %}
89
80
  </a>
90
81
  {% endfor %}
91
82
  </div>
@@ -1,53 +1,72 @@
1
- {% assign num_software = site.software | size %}
2
- {% assign num_specs = site.specs | size %}
1
+ {% assign software = site.software | where_exp: "item", "item.repo_url != nil" %}
2
+ {% assign specs = site.specs | where_exp: "item", "item.source_url != nil" %}
3
+ {% assign posts = site.posts %}
4
+
5
+ {% assign num_software = software | size %}
6
+ {% assign num_specs = specs | size %}
3
7
  {% assign num_posts = site.posts | size %}
4
8
 
5
- {% if num_software > 0 %}
6
- <section class="software">
7
- <h2 class="title">Software</h2>
9
+ <div class="underlay top-background" role="presentation">
10
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" preserveAspectRatio="none">
11
+ <polygon fill="white" points="0,0 100,0 100,60 0,100"/>
12
+ </svg>
8
13
 
9
- <div class="items">
10
- {% for item in site.software %}
11
- <a class="item" href="{{ item.url }}" role="article">
12
- {% if item.logo_svg %}
14
+ {% if num_software > 0 %}
15
+ <section class="software">
16
+ <h2 class="title">Open Source Software</h2>
17
+
18
+ <div class="items">
19
+ {% for item in software %}
20
+ <a class="item" href="{{ item.url }}" role="article">
13
21
  <div class="logo-container" role="presentation">
14
- <div class="logo">{{ item.logo_svg }}</div>
22
+ {% include software-symbol.html item_id=item.id %}
15
23
  </div>
16
- {% endif %}
17
- <h3 class="header">{{ item.title }}</h3>
18
- <p class="body">
19
- {{ item.description }}
20
- </p>
21
- </a>
22
- {% endfor %}
23
- </div>
24
- </section>
25
- {% endif %}
24
+
25
+ <header>
26
+ <h3 class="title">{{ item.title }}</h3>
27
+ </header>
28
+
29
+ <p class="body">
30
+ {{ item.description }}
31
+ </p>
32
+
33
+ {% include tag-list.html tags=item.tags %}
34
+ </a>
35
+ {% endfor %}
36
+ </div>
37
+ </section>
38
+ {% endif %}
39
+
40
+ {% if num_posts > 0 %}
41
+ <section class="featured-posts">
42
+ <h2 class="title">From the Blog</h2>
43
+
44
+ <div class="items" role="presentation">
45
+ {% for item in posts %}
46
+ {% include post-card.html post=item %}
47
+ {% endfor %}
48
+ </div>
49
+ </section>
50
+ {% endif %}
51
+ </div>
26
52
 
27
53
  {% if num_specs > 0 %}
28
54
  <section class="specs">
29
- <h2 class="title">Specifications</h2>
55
+ <h2 class="title">Open Specifications</h2>
30
56
 
31
57
  <div class="items">
32
- {% for item in site.specs %}
58
+ {% for item in specs %}
33
59
  <a class="item" href="{{ item.url }}" role="article">
34
- <h3 class="header">{{ item.title }}</h3>
60
+ <header>
61
+ <h3 class="title">{{ item.title }}</h3>
62
+ </header>
63
+
35
64
  <p class="body">
36
65
  {{ item.description }}
37
66
  </p>
38
- </a>
39
- {% endfor %}
40
- </div>
41
- </section>
42
- {% endif %}
43
-
44
- {% if num_posts > 0 %}
45
- <section class="featured-posts">
46
- <h2 class="title">From the Blog</h2>
47
67
 
48
- <div class="items" role="presentation">
49
- {% for item in site.posts %}
50
- {% include post-card.html post=item %}
68
+ {% include tag-list.html tags=item.tags %}
69
+ </a>
51
70
  {% endfor %}
52
71
  </div>
53
72
  </section>