README.md in jekyll-theme-open-project-1.0.0.pre3 vs README.md in jekyll-theme-open-project-1.0.0.pre4

- old
+ new

@@ -33,40 +33,44 @@ ## 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. +Refer to RVM docs and use it to install a fresh Ruby version. +The currently recommended version is 2.4.4, it’s known to not work under 2.3 +and it hasn’t been tested on newer versions. + ### Start new Jekyll site jekyll new my-open-site ### Installing theme Add this line to your Jekyll site's `Gemfile`, replacing default theme requirement: ```ruby -gem 'jekyll-theme-open-project' +gem "jekyll-theme-open-project" ``` (Jekyll’s default theme was “minima” at the time of this writing.) Also in the `Gemfile`, add two important plugins to the `:jekyll_plugins` group. (The SEO tag plugin is not mandatory, but these docs assume you use it.) ```ruby group :jekyll_plugins do gem "jekyll-seo-tag" + gem "jekyll-data" + gem "jekyll-data" gem "jekyll-theme-open-project-helpers" # ...other plugins, if you use any end ``` -Execute to install dependencies: +Execute the following to install dependencies: $ bundle ### Configuring site @@ -91,10 +95,11 @@ These settings are required 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 `hero_include: home-hero.html` to YAML frontmatter in `index.md`. - Add following items to _config.yml (don’t forget to remove default theme requirement): ```yaml title: Site title @@ -104,40 +109,18 @@ tagline: Site tagline pitch: Site pitch # The above two are used on home hero unit. + permalink: /blog/:month-:day-:year/:title/ - # Further settings are not expected to be changed, - # unless you know what you’re doing: - - markdown: kramdown theme: jekyll-theme-open-project - # Theme layouts can include from any directory, not just _includes. - # There’s a quirk in Jekyll’s “safe” behavior around include and gem-based themes - # which means include_relative wouldn’t cut it. - includes_dir: . - - 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 + social: + links: + - https://twitter.com/<orgname> + - https://github.com/<orgname> ``` ### Logo Logo consists of a symbol and site name. @@ -223,24 +206,16 @@ 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 +is_hub: true # 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. @@ -323,37 +298,15 @@ authors: - name: Your Name email: your-email@example.com author: "Company or Individual Name Goes Here" - -collections: - # ... (other collections) - software: - output: true - permalink: /:name/ - specs: - output: true - permalink: /:name/ - -defaults: - # ... (other defaults) - - scope: - path: _software - type: software - values: - layout: product - - scope: - path: _specs - type: specs - values: - layout: spec ``` File layout is the same as described in the section -about shared project data structure, with _software, _specs, _posts directories -found in the root of your Jekyll site. +about shared project data structure, with _software, _specs, _posts, _includes +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, @@ -366,74 +319,61 @@ - _posts/ - 2038-02-31-blog-post-title.markdown - _includes/ - symbol.svg - _software/ + - <name>.md - <name>/ - - symbol.svg - - index.md - - _docs/ - - <version>/ - - overview.md - - <documentation-page-name>.md + - _includes/ + - symbol.svg - _specs/ - <name>.md ### Blog -Project blog posts should be authored as described in the universal setup -section. +Author project site blog posts as described in the universal setup section. ### 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. +A software product additionally is required to have a symbol in SVG format, +placed in <name>/_includes/symbol.svg under _software/ directory. -YAML frontmatter that can be used with both software and specs: +YAML frontmatter that is expected with both software and specs: ```yaml title: A Few Words # Shown to the user # and used for HTML metadata if jekyll-seo-tag is enabled description: A sentence. # Not necessarily shown to the user, # but used for HTML metadata if jekyll-seo-tag is enabled + +tags: [Python, Ruby] ``` ### Software product -YAML frontmatter specific to software: +YAML frontmatter required for software: ```yaml -version: v1.2.3 -docs_url: https://foobar.readthedocs.io/en/latest -repo_url: https://github.com/… -stack: [Python, Django, AWS] +repo_url: https://github.com/riboseinc/asciidoctor-rfc +docs: + git_repo_url: git@example.com:path/to-repo.git + git_repo_subtree: docs ``` -#### Documentation +About the `docs` key in this frontmatter, see nearby section +about 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 @@ -447,14 +387,35 @@ # https://datatracker.ietf.org/doc/<id>[-<version>] source_url: https://example.com/spec-source-markup ``` -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 (##). +### Documentation for specs and software +Documentation contents for software should be kept in software +package’s own repository, under a directory such as `docs/`. +Inside that directory, place a file called `navigation.md` containing +only frontmatter, in format like this: + +```yaml +sections: +- name: Introduction + items: + - overview + - installation +- name: Usage + items: + - basic +``` + +In the same directory, place the required document pages—in this case, overview.md, +installation.md, and basic.md. Each document page is required to contain +standard YAML frontmatter with at least `title` specified. + +During project site build, Jekyll will pull docs for software products +that are hosted under that project site. + ### Symbol 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. @@ -523,12 +484,17 @@ under assets/css/style.scss with following exact contents: ``` --- --- +// Font imports can go here -@import '{{ site.theme }}'; +// Variable redefinitions can go here + +@import 'jekyll-theme-open-project'; + +// Custom rules can go here ``` There are two aspects to theme customization: * Cutomize SASS variables before the import (such as colors) @@ -550,10 +516,12 @@ ### SASS variables Following are the variables along with their defaults: ```scss +$font-family: Helvetica, Arial, sans-serif !default; + # 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 @@ -567,9 +535,12 @@ # 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; + +# This is for the big big hero unit on home page. +$superhero-background: $primary-dark-color !default; # Below customize colors for different sections of the site. $hub-software--primary-color: lightsalmon !default; $hub-software--primary-dark-color: tomato !default; $hub-software--hero-background: $hub-software--primary-dark-color !default;