jekyll-theme-open-hub 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57957817f694456ea8924a1ed36370fdabc0ce75b1119cb7d06579c271e5c9a7
-  data.tar.gz: ab2269327e4e45bfd4f42a3db8ee56294fc51d381e0ed6c44799b797d0eac788
+  metadata.gz: 545aa2d3d98b1b7597ce2a4dff712df3016e4e9a0d0117b34873e35977f1425a
+  data.tar.gz: a3fc839166d1ee2f3b7dd6ad4664b5a31a7a74cada3b0ab353a7ba04c2cc4079
 SHA512:
-  metadata.gz: 045ad528948cdcaeb859777a33466d0f62b2a1a85f16abf18977fc6195b769b68435bc4daa5f97a2c1e0331d65cce2a0a8171b7b61fa78d3b227832e6f445030
-  data.tar.gz: 696a463bc0e03598c56773af6cb3fe7b7cd28fe88d6646aa50883877ff37d831008c994fb5231ba12727674e6d7f2d769f7fa414bc525a124955ef1b3656b7aa
+  metadata.gz: 5398070664abe153d479954848bb7d2b83352f7706e63cc44dfa9b9aa88e511bc7f7e6e049eee1aab05c15fbc713a8599f416cf5952ba60b95d70e244b4cb312
+  data.tar.gz: 0dbd53fd766f34fc2218f6e9c4f3f896e35b3a501cf237978e06f9171136df2a347813be24b0639eef86f8ae9759604ad607ea1679e94660d9cc90431f830348

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Anton Strogonoff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,288 @@
+# Open Project theme by Ribose
+
+Open Project is a theme for Jekyll oriented towards presenting open efforts
+such as open-source software and specifications in a navigable and elegant way.
+
+Open Project fits two types of sites:
+that describe one individual project, and that combine projects into a hub.
+
+
+## Starting a site based on gem-based theme
+
+### Getting started with Ruby
+
+If you aren’t using Ruby often, the recommended way to install it is with RVM.
+Refer to RVM docs and use it to install a reasonably fresh Ruby version,
+let’s say 2.4.4.
+
+### Start new Jekyll site
+
+jekyll new my-open-hub
+
+### Installing theme
+
+Add this line to your Jekyll site's `Gemfile`,
+replacing default theme requirement:
+
+```ruby
+gem 'jekyll-theme-open-hub'
+```
+
+Add this line to your Jekyll site's `_config.yml`,
+replacing default theme requirement:
+
+```yaml
+theme: jekyll-theme-open-hub
+```
+
+(Default theme is “minima” at the time of this writing.)
+
+Execute to install dependencies:
+
+    $ bundle
+
+### Setting up pages
+
+You may want to remove the default about.md page (theme does not account
+for its existence).
+
+Create _pages directory and put in there pages for blog, software
+index, and specification index. Layouts to use are correspondingly
+`blog-index`, `software-index`, and `spec-index`.
+
+Example page frontmatter:
+
+```yaml
+---
+title: Software
+description: Open-source software developed with our company’s cooperation.
+layout: software-index
+hero_include: index-page-hero.html
+---
+```
+
+### Configuring site
+
+Depending on the type of site, copy _config-hub.yml or _config-project.yml
+into main _config.yml of Jekyll installation. Edit that file to add necessary
+site-wide configuration options, and add necessary files and folders to site contents.
+
+Below sections explain core concepts of open project and hub, and go
+into detail about how to configure a project or hub site.
+
+### Building site
+
+Execute to build the site:
+
+    $ bundle exec jekyll serve --host mysite.local --port 4000
+
+
+## Describing a project: shared data structure
+
+Each project is expected to have a machine-readable and unique name, a title,
+a description, a symbol, and one or more software products and/or specs.
+
+Following data structure is shared and used to describe projects,
+whether on hub home site or each individual project site:
+
+    - <project-name>/
+      - _includes/
+        - symbol.svg
+      - _software/
+        - <name>.md
+      - _specs/
+        - <name>.md
+
+### Software and specs
+
+An open project serves as an umbrella for related
+software products and/or specifications.
+
+Each product or spec is described by its own <name>.md file with frontmatter,
+placed under _software/ or _specs/ subdirectory, respectively,
+of your open project’s Jekyll site.
+
+Note: even though they’re in different subdirectories, all software products and specs
+within one project share URL namespace and hence must have unique names.
+
+### Software product
+
+YAML frontmatter specific to software:
+
+```yaml
+version: v1.2.3
+docs_url: https://foobar.readthedocs.io/en/latest
+stack: [Python, Django, AWS]
+```
+
+#### Documentation
+
+**Recommended:** use a dedicated service supporting versioned and well-structured
+multi-page docs, such as Read the Docs. You can link users to that documentation
+using docs_url in software product’s frontmatter.
+
+Otherwise, if this open project’s page will serve as the authoritative source
+of documentation for the software product, documentation contents are expected
+to follow frontmatter. 
+
+Keep in mind that project name and description from before
+will be displayed by the theme first. Start with second-level header (##),
+with installation instructions or quick-start guide.
+
+### Specification
+
+YAML frontmatter specific to specs:
+
+```yaml
+rfc_id: XXXX
+```
+
+Specs that are not hosted elsewhere (such as ietf.org for RFCs)
+are expected to contain the actual specification content after frontmatter.
+Start with second-level header (##).
+
+### Symbol
+
+Symbol should be in SVG format, have equal height and width,
+and look OK with height under 30px.
+Place the symbol in _includes/symbol.svg within project directory.
+
+
+## Generic site
+
+### Blog
+
+Both project site and hub site have blogs. Place posts under _posts
+and named files e.g. `2018-04-20-welcome-to-jekyll.markdown`.
+
+### Logo
+
+Logo consists of a symbol and site name.
+
+Both should look OK when placed in a 30px container.
+
+Symbol: should have equal height and width. Should look OK with height under 30px.
+Should be in SVG format. Place the symbol in _includes/symbol.svg.
+See also SVG guidelines.
+
+Site name: 1-3 words displayed to the right of the symbol.
+By default, the title you define in site config is used.
+Alternatively, you can place site name in _includes/title.html with custom HTML
+or even SVG (same SVG guidelines apply).
+
+### Legal small text
+
+You may want to supply _includes/legal.html with content like this:
+
+```html
+<span class="copyright">Copyright © 2018 Example. All rights reserved.</span>
+<nav>
+  <a href="https://www.example.com/tos">Terms</a>
+  <a href="https://www.example.com/privacy">Privacy</a>
+</nav>
+```
+
+
+## Hub site
+
+The hub represents your company or department.
+
+### Projects, software and specs
+
+See above section about project data structure.
+
+When used within hub site, each project is expected to contain directly inside
+project directory a file index.md with following frontmatter:
+
+```yaml
+title: Sample Awesome Project
+
+description: >-
+  A sentence or two go here.
+
+# Whether the project is included in the three projects on hub home page
+featured: true | false
+
+home_url: <URL to standalone project site>
+```
+
+
+## Project site
+
+When project is set up as a standalone site, _config.yml should include
+"title" and "description", corresponding to project’s information.
+
+Otherwise file layout is the same as described in the section
+about shared project data structure.
+
+
+## SVG format guidelines
+
+- Ensure SVG markup does not use IDs. It may appear multiple times
+on the page hence IDs would fail markup validation.
+
+- Ensure root <svg> element specifies its viewBox,
+but no width or height attributes.
+
+- You can style SVG shapes using in site’s assets/css/style.scss.
+
+
+## Content guidelines
+
+- Project title: 1-3 words, capital case
+- Project feature description: about 20-24 words, no markup
+- Project, software, spec regular description: about 12 words, no markup
+- Post title: 3–7 words
+- Post excerpt: about 20–24 words, no markup
+
+
+## TODO: Note on shared data
+
+In the long run it is recommended to avoid maintaining two separate copies
+of data (e.g., same project data for project site, and one for parent hub site,
+or reposting posts from project site blogs into hub blog).
+
+Ideally, during static site build the automation would pull relevant data
+from a centralized or distributed source and place it as needed
+inside Jekyll site structure before executing `jekyll build`.
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub
+at https://github.com/riboseinc/openproject-theme.
+
+This project is intended to be a safe, welcoming space for collaboration,
+and contributors are expected to adhere
+to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+
+## Theme development
+
+This directory is setup just like a Jekyll site.
+
+To set up your environment to develop this theme, run `bundle install`.
+
+To experiment with this code, add some sample content
+and run `bundle exec jekyll serve`.
+
+This starts a Jekyll server using your theme at `http://localhost:4000`. 
+
+Put your layouts in `_layouts`, your includes in `_includes`,
+your sass files in `_sass` and any other assets in `assets`.
+
+Add pages, documents, data, etc. like normal to test your theme's contents.
+
+As you make modifications to your theme and to your content, your site will
+regenerate and you should see the changes in the browser after a refresh,
+like normal.
+
+When your theme is released, only the files in `_layouts`, `_includes`,
+`_sass` and `assets` tracked with Git will be bundled.
+To add a custom directory to your theme-gem, please edit the regexp in
+`openhub.gemspec` accordingly.
+
+
+## License
+
+The theme is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/_includes/home-hero.html

@@ -0,0 +1,2 @@
+<h1>{{ site.title }}</h1>
+<p class="desc">{{ site.description }}</p>

data/_includes/home-hub.html

@@ -0,0 +1,61 @@
+{% assign featured_projects = site.projects | where: "featured", true %}
+{% assign num_featured_projects = featured_projects | size %}
+{% if num_featured_projects > 0 %}
+  <section class="featured-projects">
+    <h2 class="title">Featured Projects</h2>
+
+    <div class="items" role="presentation">
+
+      {% for item in featured_projects limit:3 %}
+        {% assign symbol_path = item.path | split: "/" | slice: 0, 2 | join: "/" | append: "/_includes/symbol.svg" %}
+        {% assign relative_symbol_path = "/" | append: symbol_path %}
+
+        <a class="item" href="{{ item.home_url }}" role="article">
+          <div class="logo-container" role="presentation">
+            <div class="logo">{% include_relative {{ relative_symbol_path }} %}</div>
+          </div>
+          <h3 class="header">{{ item.title }}</h3>
+          <p class="body">
+            {{ item.description }}
+          </p>
+        </a>
+      {% endfor %}
+    </div>
+  </section>
+{% endif %}
+
+{% assign num_featured_posts = site.posts | size %}
+{% if num_featured_posts > 0 %}
+  <section class="featured-posts">
+    <div role="presentation" class="puny-label">Latest news</div>
+    <h2 class="title">From the Blog</h2>
+
+    <div class="items" role="presentation">
+      {% for item in site.posts limit:3 %}
+        <a class="item" href="{{ item.url }}" role="article">
+          {% include post-card.html %}
+        </a>
+      {% endfor %}
+    </div>
+  </section>
+{% endif %}
+
+{% assign other_projects = site.projects | where: "featured", false %}
+{% assign num_other_projects = other_projects | size %}
+{% if num_other_projects > 0 %}
+<section class="other-projects">
+  <h2 class="title">Other Projects</h2>
+
+  <div class="items {% if num_other_projects < 5 %}one-row{% endif %}"
+      role="presentation">
+    {% for item in other_projects %}
+      <a class="item" href="{{ item.home_url }}" role="article">
+        <h3 class="header">{{ item.title }}</h3>
+        <p class="body">
+          {{ item.description }}
+        </p>
+      </a>
+    {% endfor %}
+  </div>
+</section>
+{% endif %}

data/_includes/home-project.html

@@ -0,0 +1,56 @@
+{% assign num_software = site.software | size %}
+{% assign num_specs = site.specs | size %}
+{% assign num_posts = site.posts | size %}
+
+{% if num_software > 0 %}
+  <section class="software">
+    <h2 class="title">Software</h2>
+
+    <div class="items">
+      {% for item in site.software %}
+        <a class="item" href="{{ item.url }}" role="article">
+          {% if item.logo_svg %}
+            <div class="logo-container" role="presentation">
+              <div class="logo">{{ item.logo_svg }}</div>
+            </div>
+          {% endif %}
+          <h3 class="header">{{ item.title }}</h3>
+          <p class="body">
+            {{ item.description }}
+          </p>
+        </a>
+      {% endfor %}
+    </div>
+  </section>
+{% endif %}
+
+{% if num_specs > 0 %}
+  <section class="specs">
+    <h2 class="title">Specifications</h2>
+
+    <div class="items">
+      {% for item in site.specs %}
+        <a class="item" href="{{ item.url }}" role="article">
+          <h3 class="header">{{ item.title }}</h3>
+          <p class="body">
+            {{ item.description }}
+          </p>
+        </a>
+      {% endfor %}
+    </div>
+  </section>
+{% endif %}
+
+{% if num_posts > 0 %}
+  <section class="featured-posts">
+    <h2 class="title">From the Blog</h2>
+
+    <div class="items" role="presentation">
+      {% for item in site.posts %}
+        <a class="item" href="{{ item.url }}" role="article">
+          {% include post-card.html %}
+        </a>
+      {% endfor %}
+    </div>
+  </section>
+{% endif %}

data/_includes/index-page-hero.html

@@ -0,0 +1,2 @@
+<h1>{{ page.title }}</h1>
+<p class="desc">{{ page.description }}</p>