jekyll-theme-open-project 0.1.6

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.
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA1:
3
+ metadata.gz: 1455bc3d106d07589f676621e160bcc927f21723
4
+ data.tar.gz: 7ed324c9a0be2aecd73a1cfffd5e057ce76a5e32
5
+ SHA512:
6
+ metadata.gz: 951495b57e7b5a4b1b068258e2d7ff744dfa80d570b704696c33d2d10b3fbe464f67a31acc8bd628d95e6369837af06392c3fe422af9867c8a31a6a750ae6895
7
+ data.tar.gz: 2e0f09342c69b7b629d4991871acf1b8f7298ae3d524d89e30ad86510e5064d40d4e64d182e61b4c7917af5dbf994daeb763b62caa87bd920889d473db25c135
@@ -0,0 +1,21 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2018 Anton Strogonoff
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
@@ -0,0 +1,547 @@
1
+ # Open Project theme by Ribose
2
+
3
+ Open Project is a theme for Jekyll oriented towards presenting open efforts
4
+ such as open-source software and specifications in a navigable and elegant way.
5
+
6
+ Open Project fits two types of sites:
7
+ that describe one individual project, and that combine projects into sort of an open hub.
8
+
9
+ See also: CI_OPS for how to set up automated build and deployment of the site
10
+ to AWS S3.
11
+
12
+
13
+ ## Contents
14
+
15
+ * Creating a site: [quick-start](#starting-a-site-with-this-theme)
16
+
17
+ * [Universal site setup](#universal-setup)
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)
23
+
24
+ * Customizing site looks without violating theme design constraints:
25
+
26
+ * [Style customization](#style-customization)
27
+ * [SVG guidelines](#svg-guidelines)
28
+ * [Content guidelines](#content-guidelines)
29
+
30
+ * [Select layout reference](#select-layout-reference)
31
+
32
+
33
+ ## Starting a site with this theme
34
+
35
+ ### Getting started with Ruby
36
+
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.
40
+
41
+ ### Start new Jekyll site
42
+
43
+ jekyll new my-open-site
44
+
45
+ ### Installing theme
46
+
47
+ Add this line to your Jekyll site's `Gemfile`,
48
+ replacing default theme requirement:
49
+
50
+ ```ruby
51
+ gem 'jekyll-theme-open-project'
52
+ ```
53
+
54
+ Add this line to your Jekyll site's `_config.yml`,
55
+ replacing default theme requirement:
56
+
57
+ ```yaml
58
+ theme: jekyll-theme-open-project
59
+ ```
60
+
61
+ (Jekyll’s default theme was “minima” at the time of this writing.)
62
+
63
+ Execute to install dependencies:
64
+
65
+ $ bundle
66
+
67
+ ### Configuring site
68
+
69
+ Edit _config.yml to add necessary site-wide configuration options,
70
+ and add necessary files and folders to site contents. This step depends
71
+ on the type of site you’re creating: open hub or individual open project site.
72
+
73
+ Below sections explain core concepts of open project and hub, and go
74
+ into detail about how to configure a project or hub site.
75
+
76
+ ### Building site
77
+
78
+ Execute to build the site locally and watch for changes:
79
+
80
+ $ bundle exec jekyll serve --host mysite.local --port 4000
81
+
82
+ This assumes you have mysite.local mapped, otherwise omit --host
83
+ and it’ll use localhost.
84
+
85
+
86
+ ## Universal setup
87
+
88
+ These are applicable to both site types (hub and project).
89
+
90
+ - You may want to remove the default about.md page added by Jekyll,
91
+ as this theme does not account for its existence.
92
+ - Add following items to _config.yml:
93
+
94
+ ```yaml
95
+ title: Site title
96
+ description: Site description
97
+ # The above two are used by jekyll-seo-tag for things such as
98
+ # `<title>` and `<meta>` tags, as well as elsewhere by the theme.
99
+
100
+ collections:
101
+ posts:
102
+ output: true
103
+ permalink: /blog/:month-:day-:year/:title/
104
+ pages:
105
+ output: true
106
+ permalink: /:name/
107
+
108
+ defaults:
109
+ - scope:
110
+ path: ""
111
+ values:
112
+ layout: default
113
+ - scope:
114
+ path: _posts
115
+ type: posts
116
+ values:
117
+ layout: post
118
+
119
+ plugins:
120
+ - jekyll-seo-tag
121
+ ```
122
+
123
+ ### Logo
124
+
125
+ Logo consists of a symbol and site name.
126
+
127
+ **Symbol** is basically an icon for the site.
128
+ Should look OK in dimensions of 30x30px, and fit inside a square.
129
+ Should be in SVG format (see also the SVG guidelines section).
130
+ Place the symbol in _includes/symbol.svg.
131
+
132
+ **Site name** displayed to the right of the symbol.
133
+ Limit the name to 1-3 words.
134
+ By default, the title you define in site config is used (for project site,
135
+ it is the name of the project).
136
+ Alternatively, you can place site name in _includes/title.html with custom HTML
137
+ or SVG. (In that case it must look good when placed in a 30px tall container,
138
+ and in case of SVG same SVG guidelines apply).
139
+
140
+ ### Legal small text
141
+
142
+ You may want to supply _includes/legal.html with content like this:
143
+
144
+ ```html
145
+ <span class="copyright">Copyright © 2018 MyCompany. All rights reserved.</span>
146
+ <nav>
147
+ <a href="https://www.example.com/tos">Terms</a>
148
+ <a href="https://www.example.com/privacy">Privacy</a>
149
+ </nav>
150
+ ```
151
+
152
+ ### Blog
153
+
154
+ Project sites and hub site can have a blog.
155
+
156
+ #### Index
157
+
158
+ Create blog index page as _pages/blog.html, with nothing but frontmatter.
159
+ Use layout called "blog-index", pass `hero_include: index-page-hero.html`,
160
+ and set `title` and `description` as appropriate for blog index page.
161
+
162
+ Example:
163
+
164
+ ```yaml
165
+ ---
166
+ title: Blog
167
+ description: >-
168
+ Get the latest announcements and technical how-to’s
169
+ about our software and projects.
170
+ layout: blog-index
171
+ hero_include: index-page-hero.html
172
+ ---
173
+ ```
174
+
175
+ #### Posts
176
+
177
+ Place posts under _posts and name files e.g.
178
+ `2018-04-20-welcome-to-jekyll.markdown`. This is typical Jekyll setup.
179
+
180
+
181
+ ## Hub site
182
+
183
+ The hub represents your company or department, links to all projects
184
+ and offers a software and specification index.
185
+
186
+ Additional items allowed/expected in _config.yml:
187
+
188
+ ```yaml
189
+ social:
190
+ links:
191
+ - https://twitter.com/RiboseUS
192
+ - https://github.com/riboseinc
193
+
194
+ # Since a hub would typically represent an organization as opposed
195
+ # to individual, this would make sense:
196
+ seo:
197
+ type: Organization
198
+
199
+ collections:
200
+ projects:
201
+ output: false
202
+ # ... (other collections)
203
+ ```
204
+
205
+ ### Project, spec and software data
206
+
207
+ See the section about project data structure.
208
+
209
+ _When used within hub site_ (only), each project subdirectory
210
+ must contain a file "index.md" with frontmatter like this:
211
+
212
+ ```yaml
213
+ title: Sample Awesome Project
214
+
215
+ description: >-
216
+ A sentence or two go here.
217
+
218
+ # Whether the project is included in featured three projects on hub home page
219
+ featured: true | false
220
+
221
+ home_url: <URL to standalone project site>
222
+ ```
223
+
224
+ ### Software index page
225
+
226
+ Create software index in _pages/software.html, with nothing but frontmatter.
227
+ Use layout called "software-index", pass `hero_include: index-page-hero.html`,
228
+ and set `title` and `description` as appropriate.
229
+
230
+ Example:
231
+
232
+ ```yaml
233
+ ---
234
+ title: Software
235
+ description: Open-source software developed with MyCompany’s cooperation.
236
+ layout: software-index
237
+ hero_include: index-page-hero.html
238
+ ---
239
+ ```
240
+
241
+ ### Specification index page
242
+
243
+ Create spec index in _pages/specs.html, with nothing but frontmatter.
244
+ Use layout called "spec-index", pass `hero_include: index-page-hero.html`,
245
+ and set `title` and `description` as appropriate.
246
+
247
+ Example:
248
+
249
+ ```yaml
250
+ ---
251
+ title: Specifications
252
+ description: Because specifications are cool!
253
+ layout: spec-index
254
+ hero_include: index-page-hero.html
255
+ ---
256
+ ```
257
+
258
+
259
+ ## Project site
260
+
261
+ When project is set up as a standalone site, _config.yml should include
262
+ site-wide `title` that is the same as project name.
263
+
264
+ Additional items allowed/expected in _config.yml:
265
+
266
+ ```yaml
267
+ authors:
268
+ - name: Your Name
269
+ email: your-email@example.com
270
+
271
+ author: "Company or Individual Name Goes Here"
272
+
273
+ collections:
274
+ # ... (other collections)
275
+ software:
276
+ output: true
277
+ permalink: /:name/
278
+ specs:
279
+ output: true
280
+ permalink: /:name/
281
+
282
+ defaults:
283
+ # ... (other defaults)
284
+ - scope:
285
+ path: _software
286
+ type: software
287
+ values:
288
+ layout: product
289
+ - scope:
290
+ path: _specs
291
+ type: specs
292
+ values:
293
+ layout: spec
294
+ ```
295
+
296
+ File layout is the same as described in the section
297
+ about shared project data structure, with _software and _specs directories
298
+ found in the root of your Jekyll site.
299
+
300
+
301
+ ## Describing a project: shared data structure
302
+
303
+ Each project is expected to have a machine-readable and unique name, a title,
304
+ a description, a symbol, and one or more software products and/or specs.
305
+
306
+ Following data structure is shared and used to describe projects,
307
+ whether on hub home site or each individual project site:
308
+
309
+ - <project-name>/
310
+ - _includes/
311
+ - symbol.svg
312
+ - _software/
313
+ - <name>.md
314
+ - _specs/
315
+ - <name>.md
316
+
317
+ ### Software and specs
318
+
319
+ An open project serves as an umbrella for related
320
+ software products and/or specifications.
321
+
322
+ Each product or spec is described by its own <name>.md file with frontmatter,
323
+ placed under _software/ or _specs/ subdirectory, respectively,
324
+ of your open project’s Jekyll site.
325
+
326
+ Note: even though they’re in different subdirectories, all software products and specs
327
+ within one project share URL namespace and hence must have unique names.
328
+
329
+ YAML frontmatter that can be used with both software and specs:
330
+
331
+ ```yaml
332
+ title: A Few Words
333
+ # Shown to the user
334
+ # and used for HTML metadata if jekyll-seo-tag is enabled
335
+
336
+ description: A sentence.
337
+ # Not necessarily shown to the user,
338
+ # but used for HTML metadata if jekyll-seo-tag is enabled
339
+ ```
340
+
341
+ ### Software product
342
+
343
+ YAML frontmatter specific to software:
344
+
345
+ ```yaml
346
+ version: v1.2.3
347
+ docs_url: https://foobar.readthedocs.io/en/latest
348
+ repo_url: https://github.com/…
349
+ stack: [Python, Django, AWS]
350
+ ```
351
+
352
+ #### Documentation
353
+
354
+ **Recommended:** use a dedicated service supporting versioned and well-structured
355
+ multi-page docs, such as Read the Docs. You can link users to that documentation
356
+ using docs_url in software product’s frontmatter.
357
+
358
+ Otherwise, if this open project’s page will serve as the authoritative source
359
+ of documentation for the software product, documentation contents are expected
360
+ to follow frontmatter.
361
+
362
+ Keep in mind that project name and description from before
363
+ will be displayed by the theme first. Start with second-level header (##),
364
+ with installation instructions or quick-start guide.
365
+
366
+ ### Specification
367
+
368
+ YAML frontmatter specific to specs:
369
+
370
+ ```yaml
371
+ rfc_id: XXXX
372
+ # IETF RFC URL would be in the form
373
+ # http://ietf.org/html/rfc<id>
374
+
375
+ ietf_datatracker_id: some-string-identifier-here
376
+ ietf_datatracker_ver: "01"
377
+ # IETF datatracker URL would be in the form
378
+ # https://datatracker.ietf.org/doc/<id>[-<version>]
379
+
380
+ source_url: https://example.com/spec-source-markup
381
+ ```
382
+
383
+ Specs that are not hosted elsewhere (such as ietf.org for RFCs)
384
+ are expected to contain the actual specification content after frontmatter.
385
+ Start with second-level header (##).
386
+
387
+ ### Symbol
388
+
389
+ Should look OK in dimensions of 30x30px, and fit inside a square.
390
+ Should be in SVG format (see also the SVG guidelines section).
391
+ Place the symbol in _includes/symbol.svg within project directory.
392
+
393
+
394
+ ## SVG guidelines
395
+
396
+ - Ensure SVG markup does not use IDs. It may appear multiple times
397
+ on the page hence IDs would fail markup validation.
398
+ - Ensure root <svg> element specifies its viewBox,
399
+ but no width or height attributes.
400
+ - You can style SVG shapes using in site’s assets/css/style.scss.
401
+
402
+
403
+ ## Content guidelines
404
+
405
+ - Project, software, spec title: 1-3 words, capital case
406
+ - Project, software, spec description: about 12 words, no markup
407
+ - Project description (featured): about 20-24 words, no markup
408
+ - Blog post title: 3–7 words
409
+ - Blog post excerpt: about 20–24 words, no markup
410
+
411
+
412
+ ## Select layout reference
413
+
414
+ Normally you don’t need to specify layouts manually, except where
415
+ instructed in site setup sections of this document.
416
+
417
+ Commonly used layouts are:
418
+
419
+ - blog-index: Blog index page. Pages using this layout are recommended
420
+ to supply hero_include.
421
+
422
+ - post: Blog post
423
+
424
+ - software-index: Software index page (hub site only).
425
+ Suggested to supply hero_include.
426
+ Will show a list of software across projects within the hub.
427
+
428
+ - spec-index: Specification index page (hub site only).
429
+ Suggested to supply hero_include.
430
+ Will show a list of specs across projects within the hub.
431
+
432
+ - product: Software product (project site only)
433
+
434
+ - spec: Open specification (project site only)
435
+
436
+ ### Page frontmatter
437
+
438
+ Typical expected page frontmatter is `title` and `description`. Those are
439
+ also used by jekyll-seo-tag plugin to add the appropriate meta tags.
440
+
441
+ Commonly supported in page frontmatter is the hero_include option,
442
+ which would show hero unit underneath top header.
443
+ Currently, theme supports _includes/index-page-hero.html as the only value
444
+ you can pass for hero_include (or you can leave hero_include out altogether).
445
+
446
+
447
+ ## Style customization
448
+
449
+ To customize site appearance, create a file in your Jekyll site
450
+ under assets/css/style.scss with following exact contents:
451
+
452
+ ```
453
+ ---
454
+ ---
455
+
456
+ @import '{{ site.theme }}';
457
+ ```
458
+
459
+ You can define custom style rules after the import, and customize variables
460
+ before the import.
461
+
462
+ ### Custom rules
463
+
464
+ One suggested custom rule would be to change the fill color for SVG paths
465
+ used for your custom site symbol to white, unless it’s white by default.
466
+
467
+ The rule would look like this:
468
+
469
+ ```scss
470
+ .site-logo svg path {
471
+ fill: white;
472
+ }
473
+ ```
474
+
475
+ ### SASS variables
476
+
477
+ Following are the variables along with their defaults:
478
+
479
+ ```scss
480
+ # Primary color—should be bright but dark enough to be readable,
481
+ # since some text elements are set using this color:
482
+ $primary-color: lightblue !default;
483
+
484
+ # Darker variation of primary color used for background on elements where
485
+ # text is set in white:
486
+ $primary-dark-color: navy !default;
487
+
488
+ # Bright color for accent elements, such as buttons (not yet in use).
489
+ # Text on those elements is set in bold and white, so this color
490
+ # should be dark enough:
491
+ $accent-color: red !default;
492
+
493
+ # Below are used for `background` CSS rule for top header, and for
494
+ # hero unit respectively. Gradients can be supplied.
495
+ $header-background: $primary-dark-color !default;
496
+ $hero-background: $primary-dark-color !default;
497
+ ```
498
+
499
+
500
+ ## Contributing
501
+
502
+ Bug reports and pull requests are welcome on GitHub
503
+ at https://github.com/riboseinc/jekyll-theme-open-project.
504
+
505
+ This project is intended to be a safe, welcoming space for collaboration,
506
+ and contributors are expected to adhere
507
+ to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
508
+
509
+
510
+ ## Theme development
511
+
512
+ Generally, this directory is setup like a Jekyll site. To set it up,
513
+ run `bundle install`.
514
+
515
+ To experiment with this code, add content (projects, software, specs)
516
+ and run `bundle exec jekyll serve`. This starts a Jekyll server
517
+ using this theme at `http://localhost:4000`.
518
+
519
+ Put your layouts in `_layouts`, your includes in `_includes`,
520
+ your sass files in `_sass` and any other assets in `assets`.
521
+
522
+ Add pages, documents, data, etc. like normal to test your theme's contents.
523
+
524
+ As you make modifications to your theme and to your content, your site will
525
+ regenerate and you should see the changes in the browser after a refresh,
526
+ like normal.
527
+
528
+ When your theme is released, only files specified with gemspec file
529
+ will be included. If you modify theme to add more directories that
530
+ need to be included in the gem, edit regexp in the gemspec.
531
+
532
+ ### Building and releasing
533
+
534
+ To check your theme, run:
535
+
536
+ ./develop/build
537
+
538
+ It’ll build Jekyll site and run some checks, like HTML markup validation.
539
+
540
+ To build new gem and push it to rubygems.org, run:
541
+
542
+ ./develop/release
543
+
544
+
545
+ ## License
546
+
547
+ The theme is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).