jekyll-theme-open-hub 0.1.1 → 0.1.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: 57957817f694456ea8924a1ed36370fdabc0ce75b1119cb7d06579c271e5c9a7
4
- data.tar.gz: ab2269327e4e45bfd4f42a3db8ee56294fc51d381e0ed6c44799b797d0eac788
3
+ metadata.gz: 545aa2d3d98b1b7597ce2a4dff712df3016e4e9a0d0117b34873e35977f1425a
4
+ data.tar.gz: a3fc839166d1ee2f3b7dd6ad4664b5a31a7a74cada3b0ab353a7ba04c2cc4079
5
5
  SHA512:
6
- metadata.gz: 045ad528948cdcaeb859777a33466d0f62b2a1a85f16abf18977fc6195b769b68435bc4daa5f97a2c1e0331d65cce2a0a8171b7b61fa78d3b227832e6f445030
7
- data.tar.gz: 696a463bc0e03598c56773af6cb3fe7b7cd28fe88d6646aa50883877ff37d831008c994fb5231ba12727674e6d7f2d769f7fa414bc525a124955ef1b3656b7aa
6
+ metadata.gz: 5398070664abe153d479954848bb7d2b83352f7706e63cc44dfa9b9aa88e511bc7f7e6e049eee1aab05c15fbc713a8599f416cf5952ba60b95d70e244b4cb312
7
+ data.tar.gz: 0dbd53fd766f34fc2218f6e9c4f3f896e35b3a501cf237978e06f9171136df2a347813be24b0639eef86f8ae9759604ad607ea1679e94660d9cc90431f830348
@@ -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,288 @@
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 a hub.
8
+
9
+
10
+ ## Starting a site based on gem-based theme
11
+
12
+ ### Getting started with Ruby
13
+
14
+ If you aren’t using Ruby often, the recommended way to install it is with RVM.
15
+ Refer to RVM docs and use it to install a reasonably fresh Ruby version,
16
+ let’s say 2.4.4.
17
+
18
+ ### Start new Jekyll site
19
+
20
+ jekyll new my-open-hub
21
+
22
+ ### Installing theme
23
+
24
+ Add this line to your Jekyll site's `Gemfile`,
25
+ replacing default theme requirement:
26
+
27
+ ```ruby
28
+ gem 'jekyll-theme-open-hub'
29
+ ```
30
+
31
+ Add this line to your Jekyll site's `_config.yml`,
32
+ replacing default theme requirement:
33
+
34
+ ```yaml
35
+ theme: jekyll-theme-open-hub
36
+ ```
37
+
38
+ (Default theme is “minima” at the time of this writing.)
39
+
40
+ Execute to install dependencies:
41
+
42
+ $ bundle
43
+
44
+ ### Setting up pages
45
+
46
+ You may want to remove the default about.md page (theme does not account
47
+ for its existence).
48
+
49
+ Create _pages directory and put in there pages for blog, software
50
+ index, and specification index. Layouts to use are correspondingly
51
+ `blog-index`, `software-index`, and `spec-index`.
52
+
53
+ Example page frontmatter:
54
+
55
+ ```yaml
56
+ ---
57
+ title: Software
58
+ description: Open-source software developed with our company’s cooperation.
59
+ layout: software-index
60
+ hero_include: index-page-hero.html
61
+ ---
62
+ ```
63
+
64
+ ### Configuring site
65
+
66
+ Depending on the type of site, copy _config-hub.yml or _config-project.yml
67
+ into main _config.yml of Jekyll installation. Edit that file to add necessary
68
+ site-wide configuration options, and add necessary files and folders to site contents.
69
+
70
+ Below sections explain core concepts of open project and hub, and go
71
+ into detail about how to configure a project or hub site.
72
+
73
+ ### Building site
74
+
75
+ Execute to build the site:
76
+
77
+ $ bundle exec jekyll serve --host mysite.local --port 4000
78
+
79
+
80
+ ## Describing a project: shared data structure
81
+
82
+ Each project is expected to have a machine-readable and unique name, a title,
83
+ a description, a symbol, and one or more software products and/or specs.
84
+
85
+ Following data structure is shared and used to describe projects,
86
+ whether on hub home site or each individual project site:
87
+
88
+ - <project-name>/
89
+ - _includes/
90
+ - symbol.svg
91
+ - _software/
92
+ - <name>.md
93
+ - _specs/
94
+ - <name>.md
95
+
96
+ ### Software and specs
97
+
98
+ An open project serves as an umbrella for related
99
+ software products and/or specifications.
100
+
101
+ Each product or spec is described by its own <name>.md file with frontmatter,
102
+ placed under _software/ or _specs/ subdirectory, respectively,
103
+ of your open project’s Jekyll site.
104
+
105
+ Note: even though they’re in different subdirectories, all software products and specs
106
+ within one project share URL namespace and hence must have unique names.
107
+
108
+ ### Software product
109
+
110
+ YAML frontmatter specific to software:
111
+
112
+ ```yaml
113
+ version: v1.2.3
114
+ docs_url: https://foobar.readthedocs.io/en/latest
115
+ stack: [Python, Django, AWS]
116
+ ```
117
+
118
+ #### Documentation
119
+
120
+ **Recommended:** use a dedicated service supporting versioned and well-structured
121
+ multi-page docs, such as Read the Docs. You can link users to that documentation
122
+ using docs_url in software product’s frontmatter.
123
+
124
+ Otherwise, if this open project’s page will serve as the authoritative source
125
+ of documentation for the software product, documentation contents are expected
126
+ to follow frontmatter.
127
+
128
+ Keep in mind that project name and description from before
129
+ will be displayed by the theme first. Start with second-level header (##),
130
+ with installation instructions or quick-start guide.
131
+
132
+ ### Specification
133
+
134
+ YAML frontmatter specific to specs:
135
+
136
+ ```yaml
137
+ rfc_id: XXXX
138
+ ```
139
+
140
+ Specs that are not hosted elsewhere (such as ietf.org for RFCs)
141
+ are expected to contain the actual specification content after frontmatter.
142
+ Start with second-level header (##).
143
+
144
+ ### Symbol
145
+
146
+ Symbol should be in SVG format, have equal height and width,
147
+ and look OK with height under 30px.
148
+ Place the symbol in _includes/symbol.svg within project directory.
149
+
150
+
151
+ ## Generic site
152
+
153
+ ### Blog
154
+
155
+ Both project site and hub site have blogs. Place posts under _posts
156
+ and named files e.g. `2018-04-20-welcome-to-jekyll.markdown`.
157
+
158
+ ### Logo
159
+
160
+ Logo consists of a symbol and site name.
161
+
162
+ Both should look OK when placed in a 30px container.
163
+
164
+ Symbol: should have equal height and width. Should look OK with height under 30px.
165
+ Should be in SVG format. Place the symbol in _includes/symbol.svg.
166
+ See also SVG guidelines.
167
+
168
+ Site name: 1-3 words displayed to the right of the symbol.
169
+ By default, the title you define in site config is used.
170
+ Alternatively, you can place site name in _includes/title.html with custom HTML
171
+ or even SVG (same SVG guidelines apply).
172
+
173
+ ### Legal small text
174
+
175
+ You may want to supply _includes/legal.html with content like this:
176
+
177
+ ```html
178
+ <span class="copyright">Copyright © 2018 Example. All rights reserved.</span>
179
+ <nav>
180
+ <a href="https://www.example.com/tos">Terms</a>
181
+ <a href="https://www.example.com/privacy">Privacy</a>
182
+ </nav>
183
+ ```
184
+
185
+
186
+ ## Hub site
187
+
188
+ The hub represents your company or department.
189
+
190
+ ### Projects, software and specs
191
+
192
+ See above section about project data structure.
193
+
194
+ When used within hub site, each project is expected to contain directly inside
195
+ project directory a file index.md with following frontmatter:
196
+
197
+ ```yaml
198
+ title: Sample Awesome Project
199
+
200
+ description: >-
201
+ A sentence or two go here.
202
+
203
+ # Whether the project is included in the three projects on hub home page
204
+ featured: true | false
205
+
206
+ home_url: <URL to standalone project site>
207
+ ```
208
+
209
+
210
+ ## Project site
211
+
212
+ When project is set up as a standalone site, _config.yml should include
213
+ "title" and "description", corresponding to project’s information.
214
+
215
+ Otherwise file layout is the same as described in the section
216
+ about shared project data structure.
217
+
218
+
219
+ ## SVG format guidelines
220
+
221
+ - Ensure SVG markup does not use IDs. It may appear multiple times
222
+ on the page hence IDs would fail markup validation.
223
+
224
+ - Ensure root <svg> element specifies its viewBox,
225
+ but no width or height attributes.
226
+
227
+ - You can style SVG shapes using in site’s assets/css/style.scss.
228
+
229
+
230
+ ## Content guidelines
231
+
232
+ - Project title: 1-3 words, capital case
233
+ - Project feature description: about 20-24 words, no markup
234
+ - Project, software, spec regular description: about 12 words, no markup
235
+ - Post title: 3–7 words
236
+ - Post excerpt: about 20–24 words, no markup
237
+
238
+
239
+ ## TODO: Note on shared data
240
+
241
+ In the long run it is recommended to avoid maintaining two separate copies
242
+ of data (e.g., same project data for project site, and one for parent hub site,
243
+ or reposting posts from project site blogs into hub blog).
244
+
245
+ Ideally, during static site build the automation would pull relevant data
246
+ from a centralized or distributed source and place it as needed
247
+ inside Jekyll site structure before executing `jekyll build`.
248
+
249
+
250
+ ## Contributing
251
+
252
+ Bug reports and pull requests are welcome on GitHub
253
+ at https://github.com/riboseinc/openproject-theme.
254
+
255
+ This project is intended to be a safe, welcoming space for collaboration,
256
+ and contributors are expected to adhere
257
+ to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
258
+
259
+
260
+ ## Theme development
261
+
262
+ This directory is setup just like a Jekyll site.
263
+
264
+ To set up your environment to develop this theme, run `bundle install`.
265
+
266
+ To experiment with this code, add some sample content
267
+ and run `bundle exec jekyll serve`.
268
+
269
+ This starts a Jekyll server using your theme at `http://localhost:4000`.
270
+
271
+ Put your layouts in `_layouts`, your includes in `_includes`,
272
+ your sass files in `_sass` and any other assets in `assets`.
273
+
274
+ Add pages, documents, data, etc. like normal to test your theme's contents.
275
+
276
+ As you make modifications to your theme and to your content, your site will
277
+ regenerate and you should see the changes in the browser after a refresh,
278
+ like normal.
279
+
280
+ When your theme is released, only the files in `_layouts`, `_includes`,
281
+ `_sass` and `assets` tracked with Git will be bundled.
282
+ To add a custom directory to your theme-gem, please edit the regexp in
283
+ `openhub.gemspec` accordingly.
284
+
285
+
286
+ ## License
287
+
288
+ The theme is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
@@ -0,0 +1,2 @@
1
+ <h1>{{ site.title }}</h1>
2
+ <p class="desc">{{ site.description }}</p>
@@ -0,0 +1,61 @@
1
+ {% assign featured_projects = site.projects | where: "featured", true %}
2
+ {% assign num_featured_projects = featured_projects | size %}
3
+ {% if num_featured_projects > 0 %}
4
+ <section class="featured-projects">
5
+ <h2 class="title">Featured Projects</h2>
6
+
7
+ <div class="items" role="presentation">
8
+
9
+ {% for item in featured_projects limit:3 %}
10
+ {% assign symbol_path = item.path | split: "/" | slice: 0, 2 | join: "/" | append: "/_includes/symbol.svg" %}
11
+ {% assign relative_symbol_path = "/" | append: symbol_path %}
12
+
13
+ <a class="item" href="{{ item.home_url }}" role="article">
14
+ <div class="logo-container" role="presentation">
15
+ <div class="logo">{% include_relative {{ relative_symbol_path }} %}</div>
16
+ </div>
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 %}
26
+
27
+ {% assign num_featured_posts = site.posts | size %}
28
+ {% if num_featured_posts > 0 %}
29
+ <section class="featured-posts">
30
+ <div role="presentation" class="puny-label">Latest news</div>
31
+ <h2 class="title">From the Blog</h2>
32
+
33
+ <div class="items" role="presentation">
34
+ {% for item in site.posts limit:3 %}
35
+ <a class="item" href="{{ item.url }}" role="article">
36
+ {% include post-card.html %}
37
+ </a>
38
+ {% endfor %}
39
+ </div>
40
+ </section>
41
+ {% endif %}
42
+
43
+ {% assign other_projects = site.projects | where: "featured", false %}
44
+ {% assign num_other_projects = other_projects | size %}
45
+ {% if num_other_projects > 0 %}
46
+ <section class="other-projects">
47
+ <h2 class="title">Other Projects</h2>
48
+
49
+ <div class="items {% if num_other_projects < 5 %}one-row{% endif %}"
50
+ role="presentation">
51
+ {% for item in other_projects %}
52
+ <a class="item" href="{{ item.home_url }}" role="article">
53
+ <h3 class="header">{{ item.title }}</h3>
54
+ <p class="body">
55
+ {{ item.description }}
56
+ </p>
57
+ </a>
58
+ {% endfor %}
59
+ </div>
60
+ </section>
61
+ {% endif %}
@@ -0,0 +1,56 @@
1
+ {% assign num_software = site.software | size %}
2
+ {% assign num_specs = site.specs | size %}
3
+ {% assign num_posts = site.posts | size %}
4
+
5
+ {% if num_software > 0 %}
6
+ <section class="software">
7
+ <h2 class="title">Software</h2>
8
+
9
+ <div class="items">
10
+ {% for item in site.software %}
11
+ <a class="item" href="{{ item.url }}" role="article">
12
+ {% if item.logo_svg %}
13
+ <div class="logo-container" role="presentation">
14
+ <div class="logo">{{ item.logo_svg }}</div>
15
+ </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 %}
26
+
27
+ {% if num_specs > 0 %}
28
+ <section class="specs">
29
+ <h2 class="title">Specifications</h2>
30
+
31
+ <div class="items">
32
+ {% for item in site.specs %}
33
+ <a class="item" href="{{ item.url }}" role="article">
34
+ <h3 class="header">{{ item.title }}</h3>
35
+ <p class="body">
36
+ {{ item.description }}
37
+ </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
+
48
+ <div class="items" role="presentation">
49
+ {% for item in site.posts %}
50
+ <a class="item" href="{{ item.url }}" role="article">
51
+ {% include post-card.html %}
52
+ </a>
53
+ {% endfor %}
54
+ </div>
55
+ </section>
56
+ {% endif %}
@@ -0,0 +1,2 @@
1
+ <h1>{{ page.title }}</h1>
2
+ <p class="desc">{{ page.description }}</p>