README.md in jekyll-theme-open-hub-0.1.2 vs README.md in jekyll-theme-open-hub-0.1.3
- old
+ new
@@ -1,25 +1,48 @@
-# 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
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
+ jekyll new my-open-hub
### Installing theme
Add this line to your Jekyll site's `Gemfile`,
replacing default theme requirement:
@@ -33,52 +56,250 @@
```yaml
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
-You may want to remove the default about.md page (theme does not account
-for its existence).
+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.
-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`.
+Below sections explain core concepts of open project and hub, and go
+into detail about how to configure a project or hub site.
-Example page frontmatter:
+### 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>
+```
+
+### Software index page
+
+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:
+
+```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
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.
@@ -141,147 +362,163 @@
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.
+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:
+- blog-index: Blog index page. Pages using this layout are recommended
+ to supply hero_include.
-```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>
-```
+- post: Blog post
+- software-index: Software index page (hub site only).
+ Suggested to supply hero_include.
+ Will show a list of software across projects within the hub.
-## Hub site
+- spec-index: Specification index page (hub site only).
+ Suggested to supply hero_include.
+ Will show a list of specs across projects within the hub.
-The hub represents your company or department.
+- product: Software product (project site only)
-### Projects, software and specs
+- spec: Open specification (project site only)
-See above section about project data structure.
+### Page frontmatter
-When used within hub site, each project is expected to contain directly inside
-project directory a file index.md with following frontmatter:
+Typical expected page frontmatter is `title` and `description`. Those are
+also used by jekyll-seo-tag plugin to add the appropriate meta tags.
-```yaml
-title: Sample Awesome Project
+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).
-description: >-
- A sentence or two go here.
-# Whether the project is included in the three projects on hub home page
-featured: true | false
+## Style customization
-home_url: <URL to standalone project site>
+To customize site appearance, create a file in your Jekyll site
+under assets/css/style.scss with following exact contents:
+
```
+---
+---
+@import '{{ site.theme }}';
+```
-## Project site
+You can define custom style rules after the import, and customize variables
+before the import.
-When project is set up as a standalone site, _config.yml should include
-"title" and "description", corresponding to project’s information.
+### Custom rules
-Otherwise file layout is the same as described in the section
-about shared project data structure.
+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.
+The rule would look like this:
-## SVG format guidelines
+```scss
+.site-logo svg path {
+ fill: white;
+}
+```
-- Ensure SVG markup does not use IDs. It may appear multiple times
-on the page hence IDs would fail markup validation.
+### SASS variables
-- Ensure root <svg> element specifies its viewBox,
-but no width or height attributes.
+Following are the variables along with their defaults:
-- You can style SVG shapes using in site’s assets/css/style.scss.
+```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;
+# Darker variation of primary color used for background on elements where
+# text is set in white:
+$primary-dark-color: navy !default;
-## Content guidelines
+# 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;
-- 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
+# 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;
+```
-## 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.
+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
to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
## Theme development
-This directory is setup just like a Jekyll site.
+Generally, this directory is setup like a Jekyll site. To set it up,
+run `bundle install`.
-To set up your environment to develop this theme, run `bundle install`.
+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`.
-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.
+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
The theme is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).