jekyll-theme-open-hub 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 545aa2d3d98b1b7597ce2a4dff712df3016e4e9a0d0117b34873e35977f1425a
-  data.tar.gz: a3fc839166d1ee2f3b7dd6ad4664b5a31a7a74cada3b0ab353a7ba04c2cc4079
+  metadata.gz: 727caf1528610157d086b8a66e77263a0a949a29e520251e4774a6e083da50aa
+  data.tar.gz: fa5cb19c66214932aab3df38ffbff6935f95b4f7476f2949d9925aa542574231
 SHA512:
-  metadata.gz: 5398070664abe153d479954848bb7d2b83352f7706e63cc44dfa9b9aa88e511bc7f7e6e049eee1aab05c15fbc713a8599f416cf5952ba60b95d70e244b4cb312
-  data.tar.gz: 0dbd53fd766f34fc2218f6e9c4f3f896e35b3a501cf237978e06f9171136df2a347813be24b0639eef86f8ae9759604ad607ea1679e94660d9cc90431f830348
+  metadata.gz: 2c7824c01f27f450af0a508ee9727978e21500ed0f3aa0ec274121d3def41cbc8a9ea5269807fdb74fb6f2d5c203b4dcde4f3fa4d0a1ac938ed362168128700b
+  data.tar.gz: b717df76e95e9d3d41ef6b883a87a9b00c8683f2d3d510402f62f325dd929caae30f673811a738971014b8749e4dc6cb2c4a68706d85c8213248b7cc1e98c278

data/README.md

@@ -1,13 +1,36 @@
-# Open Project theme by Ribose
+# Open Hub theme by Ribose
 
-Open Project is a theme for Jekyll oriented towards presenting open efforts
+Open Hub 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:
+Open Hub fits two types of sites:
 that describe one individual project, and that combine projects into a hub.
 
+See also: CI_OPS for how to set up automated build and deployment of the site
+to AWS S3.
 
-## Starting a site based on gem-based theme
+
+## Contents
+
+* Creating a site: [quick-start](#starting-a-site-with-this-theme)
+
+  * [Universal site setup](#universal-setup)
+  * [Hub site setup](#hub-site)
+  * [Project site setup](#project-site)
+
+* Describing open projects:
+  [Project data structure](#describing-a-project-shared-data-structure)
+
+* Customizing site looks without violating theme design constraints:
+
+  * [Style customization](#style-customization)
+  * [SVG guidelines](#svg-guidelines)
+  * [Content guidelines](#content-guidelines)
+
+* [Select layout reference](#select-layout-reference)
+
+
+## Starting a site with this theme
 
 ### Getting started with Ruby
 
@@ -17,7 +40,7 @@ let’s say 2.4.4.
 
 ### Start new Jekyll site
 
-jekyll new my-open-hub
+    jekyll new my-open-hub
 
 ### Installing theme
 
@@ -35,46 +58,244 @@ replacing default theme requirement:
 theme: jekyll-theme-open-hub
 ```
 
-(Default theme is “minima” at the time of this writing.)
+(Jekyll’s default theme was “minima” at the time of this writing.)
 
 Execute to install dependencies:
 
     $ bundle
 
-### Setting up pages
+### Configuring site
+
+Edit _config.yml to add necessary site-wide configuration options,
+and add necessary files and folders to site contents. This step depends
+on the type of site you’re creating: open hub or individual open project site.
+
+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 locally and watch for changes:
+
+    $ bundle exec jekyll serve --host mysite.local --port 4000
+
+This assumes you have mysite.local mapped, otherwise omit --host
+and it’ll use localhost.
+
+
+## Universal setup
+
+These are applicable to both site types (hub and project).
+
+- You may want to remove the default about.md page added by Jekyll,
+  as this theme does not account for its existence.
+- Add following items to _config.yml:
+
+  ```yaml
+  title: Site title
+  description: Site description
+  # The above two are used by jekyll-seo-tag for things such as
+  # `<title>` and `<meta>` tags, as well as elsewhere by the theme.
+  
+  collections:
+    posts:
+      output: true
+      permalink: /blog/:month-:day-:year/:title/
+    pages:
+      output: true
+      permalink: /:name/
+  
+  defaults:
+    - scope:
+        path: ""
+      values:
+        layout: default
+    - scope:
+        path: _posts
+        type: posts
+      values:
+        layout: post
+
+  plugins:
+    - jekyll-seo-tag
+  ```
+
+### Logo
+
+Logo consists of a symbol and site name.
+
+**Symbol** is basically an icon for the site.
+Should look OK in dimensions of 30x30px, and fit inside a square.
+Should be in SVG format (see also the SVG guidelines section).
+Place the symbol in _includes/symbol.svg.
+
+**Site name** displayed to the right of the symbol.
+Limit the name to 1-3 words.
+By default, the title you define in site config is used (for project site,
+it is the name of the project).
+Alternatively, you can place site name in _includes/title.html with custom HTML
+or SVG. (In that case it must look good when placed in a 30px tall container,
+and in case of 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 MyCompany. All rights reserved.</span>
+<nav>
+  <a href="https://www.example.com/tos">Terms</a>
+  <a href="https://www.example.com/privacy">Privacy</a>
+</nav>
+```
+
+### Blog
+
+Project sites and hub site can have a blog.
+
+#### Index
+
+Create blog index page as _pages/blog.html, with nothing but frontmatter.
+Use layout called "blog-index", pass `hero_include: index-page-hero.html`,
+and set `title` and `description` as appropriate for blog index page.
+
+Example:
+
+```yaml
+---
+title: Blog
+description: >-
+  Get the latest announcements and technical how-to’s
+  about our software and projects.
+layout: blog-index
+hero_include: index-page-hero.html
+---
+```
+
+#### Posts
+
+Place posts under _posts and name files e.g.
+`2018-04-20-welcome-to-jekyll.markdown`. This is typical Jekyll setup.
+
+
+## Hub site
+
+The hub represents your company or department, links to all projects
+and offers a software and specification index.
+
+Additional items allowed/expected in _config.yml:
+
+```yaml
+social:
+  links:
+    - https://twitter.com/RiboseUS
+    - https://github.com/riboseinc
+
+# Since a hub would typically represent an organization as opposed
+# to individual, this would make sense:
+seo:
+  type: Organization
+
+collections:
+  projects:
+    output: false
+  # ... (other collections)
+```
+
+### Project, spec and software data
+
+See the section about project data structure.
+
+In addition to that, _when used within hub site_ each project subdirectory
+must contain a file "index.md" with frontmatter like this:
+
+```yaml
+title: Sample Awesome Project
+
+description: >-
+  A sentence or two go here.
+
+# Whether the project is included in featured three projects on hub home page
+featured: true | false
+
+home_url: <URL to standalone project site>
+```
 
-You may want to remove the default about.md page (theme does not account
-for its existence).
+### Software index page
 
-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`.
+Create software index in _pages/software.html, with nothing but frontmatter.
+Use layout called "software-index", pass `hero_include: index-page-hero.html`,
+and set `title` and `description` as appropriate.
 
-Example page frontmatter:
+Example:
 
 ```yaml
 ---
 title: Software
-description: Open-source software developed with our company’s cooperation.
+description: Open-source software developed with MyCompany’s cooperation.
 layout: software-index
 hero_include: index-page-hero.html
 ---
 ```
 
-### Configuring site
+### Specification index page
 
-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.
+Create spec index in _pages/specs.html, with nothing but frontmatter.
+Use layout called "spec-index", pass `hero_include: index-page-hero.html`,
+and set `title` and `description` as appropriate.
 
-Below sections explain core concepts of open project and hub, and go
-into detail about how to configure a project or hub site.
+Example:
 
-### Building site
+```yaml
+---
+title: Specifications
+description: Because specifications are cool!
+layout: spec-index
+hero_include: index-page-hero.html
+---
+```
 
-Execute to build the site:
 
-    $ bundle exec jekyll serve --host mysite.local --port 4000
+## Project site
+
+When project is set up as a standalone site, _config.yml should include
+site-wide `title` that is the same as project name.
+
+Additional items allowed/expected in _config.yml:
+
+```yaml
+authors:
+  - name: Your Name
+    email: your-email@example.com
+
+author: "Company or Individual Name Goes Here"
+
+collections:
+  software:
+    output: true
+    permalink: /:name/
+  specs:
+    output: true
+    permalink: /:name/
+  # ... (other collections)
+
+defaults:
+  - scope:
+      path: _software
+      type: software
+    values:
+      layout: product
+  - scope:
+      path: _specs
+      type: specs
+    values:
+      layout: spec
+  # ... (other defaults)
+```
+
+File layout is the same as described in the section
+about shared project data structure, with _software and _specs directories
+found in the root of your Jekyll site.
 
 
 ## Describing a project: shared data structure
@@ -143,114 +364,121 @@ Start with second-level header (##).
 
 ### Symbol
 
-Symbol should be in SVG format, have equal height and width,
-and look OK with height under 30px.
+Should look OK in dimensions of 30x30px, and fit inside a square.
+Should be in SVG format (see also the SVG guidelines section).
 Place the symbol in _includes/symbol.svg within project directory.
 
 
-## Generic site
+## SVG guidelines
 
-### Blog
+- 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.
 
-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
+## Content guidelines
 
-Logo consists of a symbol and site name.
+- 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
 
-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.
+## Select layout reference
 
-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).
+Normally you don’t need to specify layouts manually, except where
+instructed in site setup sections of this document.
 
-### Legal small text
+Commonly used layouts are:
 
-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>
-```
+- blog-index: Blog index page. Pages using this layout are recommended
+  to supply hero_include.
 
+- post: Blog post
 
-## Hub site
+- software-index: Software index page (hub site only).
+  Suggested to supply hero_include.
+  Will show a list of software across projects within the hub.
 
-The hub represents your company or department.
+- spec-index: Specification index page (hub site only).
+  Suggested to supply hero_include.
+  Will show a list of specs across projects within the hub.
 
-### Projects, software and specs
+- product: Software product (project site only)
 
-See above section about project data structure.
+- spec: Open specification (project site only)
 
-When used within hub site, each project is expected to contain directly inside
-project directory a file index.md with following frontmatter:
+### Page frontmatter
 
-```yaml
-title: Sample Awesome Project
+Typical expected page frontmatter is `title` and `description`. Those are 
+also used by jekyll-seo-tag plugin to add the appropriate meta tags.
 
-description: >-
-  A sentence or two go here.
+Commonly supported in page frontmatter is the hero_include option,
+which would show hero unit underneath top header.
+Currently, theme supports _includes/index-page-hero.html as the only value
+you can pass for hero_include (or you can leave hero_include out altogether).
 
-# Whether the project is included in the three projects on hub home page
-featured: true | false
 
-home_url: <URL to standalone project site>
-```
+## Style customization
 
+To customize site appearance, create a file in your Jekyll site
+under assets/css/style.scss with following exact contents:
 
-## 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.
+@import '{{ site.theme }}';
+```
 
+You can define custom style rules after the import, and customize variables
+before the import.
 
-## SVG format guidelines
+### Custom rules
 
-- Ensure SVG markup does not use IDs. It may appear multiple times
-on the page hence IDs would fail markup validation.
+One suggested custom rule would be to change the fill color for SVG paths
+used for your custom site symbol to white, unless it’s white by default.
 
-- Ensure root <svg> element specifies its viewBox,
-but no width or height attributes.
+The rule would look like this:
 
-- You can style SVG shapes using in site’s assets/css/style.scss.
+```scss
+.site-logo svg path {
+  fill: white;
+}
+```
 
+### SASS variables
 
-## 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
+Following are the variables along with their defaults:
 
+```scss
+# Primary color—should be bright but dark enough to be readable,
+# since some text elements are set using this color:
+$primary-color: lightblue !default;
 
-## TODO: Note on shared data
+# Darker variation of primary color used for background on elements where
+# text is set in white:
+$primary-dark-color: navy !default;
 
-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).
+# Bright color for accent elements, such as buttons (not yet in use).
+# Text on those elements is set in bold and white, so this color
+# should be dark enough:
+$accent-color: red !default;
 
-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`.
+# Below are used for `background` CSS rule for top header, and for
+# hero unit respectively. Gradients can be supplied.
+$header-background: $primary-dark-color !default;
+$hero-background: $primary-dark-color !default;
+```
 
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub
-at https://github.com/riboseinc/openproject-theme.
+at https://github.com/riboseinc/jekyll-theme-open-hub.
 
 This project is intended to be a safe, welcoming space for collaboration,
 and contributors are expected to adhere
@@ -259,14 +487,12 @@ 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`.
+Generally, this directory is setup like a Jekyll site. To set it up,
+run `bundle install`.
 
-This starts a Jekyll server using your theme at `http://localhost:4000`. 
+To experiment with this code, add content (projects, software, specs)
+and run `bundle exec jekyll serve`. This starts a Jekyll server
+using this 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`.
@@ -277,10 +503,21 @@ 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.
+When your theme is released, only files specified with gemspec file
+will be included. If you modify theme to add more directories that
+need to be included in the gem, edit regexp in the gemspec.
+
+### Building and releasing
+
+To check your theme, run:
+
+    ./develop/build
+
+It’ll build Jekyll site and run some checks, like HTML markup validation.
+
+To build new gem and push it to rubygems.org, run:
+
+    ./develop/release
 
 
 ## License

metadata

@@ -1,16 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-theme-open-hub
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Ribose Inc.
-- Anton Strogonoff
-- Ricardo Salazar
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-04-25 00:00:00.000000000 Z
+date: 2018-05-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -112,7 +110,7 @@ dependencies:
         version: '1.3'
 description: 
 email:
-- feedback@ribose.com
+- open.source@ribose.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -151,7 +149,7 @@ files:
 - assets/fa/fa-brands.js
 - assets/fa/fa-solid.js
 - assets/fa/fontawesome.js
-homepage: ''
+homepage: https://github.com/riboseinc/jekyll-theme-open-hub/
 licenses:
 - MIT
 metadata: {}