jekyll-theme-open-project 1.2.1 → 1.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd51e58cf787fe3eed46a3766151ac1a46a651528baa440b93edbb5ebd24c5ba
-  data.tar.gz: 003d4f632e2422ec7ce59e81c1fbeda2b5d395e592d51ea3b2e36e7110a57295
+  metadata.gz: 8a673364013abeb093b9d6a59734a968b56d66a51758968b25837d58922c9a7c
+  data.tar.gz: 3a6fca4a290f2366b3e9166c2696cc1c48e5e718d12e2f0289e929049a448c4a
 SHA512:
-  metadata.gz: 053c60c6f0d72ed930ae5d3cc0e9bff22fb4e2d9189a98044495d712627829cd473e8d09665571190acf19e74da9b0f653cd285ad4687de13c8b2ba330c2935f
-  data.tar.gz: 3a75201bdc86cf1ccec7cb4174e2b9c2dd65de0e55c02b90f1cabdbbbd97b3b6c96fe191a150eff46818b9ed2ca0085fde6ce939a1a94247ff171892ac762bfc
+  metadata.gz: acbfaa01271a7f2da212b412c125c2f205e6f718674989668f8103d3c3bde74c386037cbff1410a70cde8eadd038afbfb1f1a186effdf5f69fc0c13916bba67c
+  data.tar.gz: 5557395128439c9b70526519949c2447531da8e791f9f578bc073547d9173af6569e2e9650d29d83978108d9b3f39b8dd411a3dae07612a0d001f75d3f7bdb2e

data/README.md

@@ -16,10 +16,7 @@ to AWS S3.
 
   * [General site setup](#general-setup)
   * [Hub site setup](#hub-site)
-  * [Project site setup](#project-site)
-
-* Describing open projects:
-  [Project data structure](#describing-a-project-shared-data-structure)
+  * [Project site setup](#project-site) and describing your software and specs
 
 * Customizing site looks:
 
@@ -219,7 +216,7 @@ author:
 For hub-wide posts, put posts under _posts/ in site root and name files e.g.
 `2018-04-20-welcome-to-jekyll.markdown` (no change from the usual Jekyll setup).
 
-For project posts, see below about shared project data structure.
+For project posts, see below the project site section.
 
 
 ## Hub site
@@ -248,9 +245,7 @@ tag_namespaces:
 
 ### Project, spec and software data
 
-See the section about project data structure.
-
-_When used within hub site_ (only), each project subdirectory
+Each project subdirectory
 must contain a file "index.md" with frontmatter like this:
 
 ```yaml
@@ -264,26 +259,10 @@ featured: true | false
 
 site:
   git_repo_url: <Git URL to standalone project site source repo>
-home_url: <URL to standalone project site>
 
-# Note: Avoid whitespaces and other characters that may make Jekyll
-# percent-encode the tag in URLs. Replace " " (a regular space)
-# with "_" (underline); underlines will be rewritten as spaces when tags
-# are presented to site users.
-# Tag can be prepended with a namespace to signify the type,
-# e.g. chosen programming language or target viewer audience
-# (see hub site configuration for tag namespace setup).
-# Avoid long namespace/tag combos as they can overflow item’s card widget.
-tags: [Ruby, Python, RFC, "<some_namespace_id>:<appropriate_tag>"]
+home_url: <URL to standalone project site>
 
-# NOTE: Must match corresponding hub site’s configuration entry.
-tag_namespaces:
-  software:
-    namespace_id: "Human-readable namespace name"
-    # E.g.:
-    # writtenin: "Written in"
-  specs:
-    namespace_id: "Human-readable namespace name"
+tags: [some, tags]
 ```
 
 ### Project index page
@@ -340,7 +319,7 @@ hero_include: index-page-hero.html
 
 ## Project site
 
-When project is set up as a standalone site, _config.yml should include
+For standalone sites of each of your projects, _config.yml should include
 site-wide `title` that is the same as project name.
 
 Additional items allowed/expected in _config.yml:
@@ -363,45 +342,113 @@ algolia_search:
   api_key: '<your Algolia API key>'
   index_name: '<your Algolia index name>'
 # Only add this if you want to use Algolia’s search on your project site.
-```
-
-File layout is the same as described in the section
-about shared project data structure, with _software, _specs, _posts, assets
-subdirectories found in the root of your Jekyll site.
 
+# NOTE: Must match corresponding hub site’s configuration entry.
+tag_namespaces:
+  software:
+    namespace_id: "Human-readable namespace name"
+    # E.g.:
+    # writtenin: "Written in"
+  specs:
+    namespace_id: "Human-readable namespace name"
+```
 
-## Describing a project: shared data structure
+### File 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.
+a description, a symbol, one or more software products and/or specs.
+Blog, docs, and other pages are optional.
 
-Following data structure is shared and used to describe projects,
-whether on hub home site or each individual project site:
+Following data structure is used for project sites:
 
-    - <project-name>/
-      - _posts/
-        - 2038-02-31-blog-post-title.markdown
+    - <project-name>/    # Jekyll site root containing _config.yml
       - assets/
-        - symbol.svg
+        - symbol.svg     # Required — project logo
       - _software/
-        - <name>.md
+        - <name>.adoc
         - <name>/
           - assets/
             - symbol.svg
       - _specs/
-        - <name>.md
+        - <name>.adoc
+      - _pages/
+        - blog.html
+        - software.html  # Software index
+        - specs.html     # Spec index
+        - docs.html
+      - docs/            # Project-wide documentation
+        - getting-started.adoc
+        - <some-page>.adoc
+      - _posts/          # Blog
+        - 2038-02-31-blog-post-title.markdown
+      - _layouts/
+        - docs.html
 
 ### Blog
 
 Author project site blog posts as described in the general site setup section.
 
+### Project docs
+
+Two kinds of docs can coexist on a given open project site:
+
+- Project-wide documentation. It’s well-suited for describing the idea behind the project,
+  the “whys”, for tutorials and similar.
+- Documentation specific to a piece of software (of which there can be more than one
+  for any given open project). This may go in detail about that piece of software,
+  and things like implementation specifics, extended installation instructions,
+  development guidelines may go here.
+
+This section is about project-wide docs, for software docs see software and specs section.
+
+The suggested convention is to create
+_pages/docs.adoc for the main documentation page, put other pages under docs/,
+and create custom layout `docs.html` that inherits from `docs-base`, specifies
+`html-class: docs-page` and provides `navigation` structure linking to all docs pages
+in a hierarchy.
+
+Example _layouts/docs.html:
+
+```
+---
+layout: docs-base
+html-class: docs-page
+docs_title: <Project name>
+navigation:
+  items:
+  - title: Introduction
+    items:
+      - title: "Overview"
+        path: /docs/
+      - title: "Get started"
+        path: /docs/getting-started/
+---
+
+{{ content }}
+```
+
+Example _pages/docs.adoc:
+
+```
+---
+layout: docs
+title: Overview
+html-class: >-
+  overview
+  # ^^ classes you can use to style the page in your custom CSS rules
+---
+:page-liquid:
+
+Your main docs page goes here.
+```
+
 ### 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,
+Each product or spec is described by its own <name>.adoc file with frontmatter,
+placed under _software/ or _specs/ subdirectory (respectively)
 of your open project’s Jekyll site.
 
 A software product additionally is required to have a symbol in SVG format,
@@ -418,7 +465,15 @@ description: A sentence.
 # Not necessarily shown to the user,
 # but used for HTML metadata if jekyll-seo-tag is enabled
 
-tags: [Python, Ruby]
+# Note: Avoid whitespaces and other characters that may make Jekyll
+# percent-encode the tag in URLs. Replace " " (a regular space)
+# with "_" (underline); underlines will be rewritten as spaces when tags
+# are presented to site users.
+# Tag can be prepended with a namespace to signify the type,
+# e.g. chosen programming language or target viewer audience
+# (see hub site configuration for tag namespace setup).
+# Avoid long namespace/tag combos as they can overflow item’s card widget.
+tags: [Ruby, Python, RFC, "<some_namespace_id>:<appropriate_tag>"]
 
 feature_with_priority: 1
 # With this key, software or spec will be featured on home
@@ -452,10 +507,11 @@ docs_url: https://docs.rs/proj/ver/…/
 #### Displaying software docs
 
 Inside the repository and optionally subtree specified under `docs`
-in above sample, place a file called `navigation.md` containing
+in above sample, place a file `navigation.adoc` (or `navigation.md`) containing
 only frontmatter, following this sample:
 
 ```yaml
+---
 items:
 - title: Introduction
   items:
@@ -464,10 +520,13 @@ items:
 - title: Usage
   items:
     - { title: Basic, path: basic-usage/ }
+---
+
+= Navigation
 ```
 
-In the same directory, place the required document pages—in this case, `overview.md`,
-`installation.md`, and `basic-usage.md`. Each file must contain
+In the same directory, place the required document pages—in this case, `overview.adoc`,
+`installation.adoc`, and `basic-usage.adoc`. Each file must contain
 standard YAML frontmatter with at least `title` specified.
 
 During project site build, Jekyll pulls docs for software that’s part of the
@@ -594,7 +653,7 @@ Commonly used layouts are:
 - blog-index: Blog index page. Pages using this layout are recommended
   to supply hero_include.
 
-- post: Blog post
+- post: Blog post.
 
 - project-index: Open project index page (hub site only).
   Suggested to supply hero_include.
@@ -608,9 +667,12 @@ Commonly used layouts are:
   Suggested to supply hero_include.
   Will show a list of specs across projects within the hub.
 
-- product: Software product (project site only)
+- product: Software product (project site only).
+
+- spec: Open specification (project site only).
 
-- spec: Open specification (project site only)
+- default: Main layout; among other things adds `html-class` specified in frontmatter
+  of last inheriting layout and the concrete page frontmatter to the `<body>` element.
 
 ### Page frontmatter
 

data/_includes/item-doc-page.html

@@ -1,3 +1,8 @@
+{% comment %}
+This page conforms to the structure introduced by docs-base layout,
+supporting expandable navigation widget.
+{% endcomment %}
+
 {% assign product_base_url = page.url | split: "/" | slice: 0, 3 | join: "/" | append: "/" %}
 {% assign docs_base_url = product_base_url | append: "docs/" %}
 
@@ -10,6 +15,7 @@
 {% assign docs_base_url = product_base_url | append: "docs/" %} 
 {% assign item_docs = include.items | where_exp: "item", "item.url contains docs_base_url" %}
 {% assign nav = item_docs | where_exp: "item", "item.path contains 'docs/navigation'" | first %}
+{% assign num_top_nav_items = nav.items | size %}
 {% assign item_data = include.items | where_exp: "item", "item.url == product_base_url" | first %}
 
 {% if nav == nil %}
@@ -17,7 +23,7 @@
 {% endif %}
 
 {% if is_docs_landing != true %}
-  <header class="documentation-header">
+  <header class="documentation-header {% if num_top_nav_items > 0 %} has-nav {% endif %}">
     <span class="section-title">
       {{ page.title|replace: " ", "&nbsp;" }}
     </span>
@@ -33,10 +39,12 @@
         <a href="{{ product_base_url | relative_url }}">{{ item_data.title }}</a>
       </h3>
 
-      <span class="nav-toggle-icon">
-        <i class="open far fa-ellipsis-v"></i>
-        <i class="close far fa-times"></i>
-      </span>
+      {% if num_top_nav_items > 0 %}
+        <span class="nav-toggle-icon">
+          <i class="open far fa-ellipsis-v"></i>
+          <i class="close far fa-times"></i>
+        </span>
+      {% endif %}
     </div>
   </header>
 {% endif %}

data/_layouts/docs-base.html

@@ -3,7 +3,7 @@ layout: default
 ---
 
 {% assign nav = page.navigation | default: layout.navigation %}
-{% assign num_nav_sections = nav.sections | size %}
+{% assign num_top_nav_items = nav.items | size %}
 
 {% for item in nav.items %}
   {% assign topmost_item = item %}
@@ -24,29 +24,37 @@ layout: default
 {% endfor %}
 
 
-<header class="documentation-header">
+<header class="documentation-header {% if num_top_nav_items > 0 %} has-nav {% endif %}">
   {% if page.title %}
-  <span class="section-title">
-    {{ page.title|replace: " ", "&nbsp;" }}
-  </span>
+    <span class="section-title">
+      {{ page.title|replace: " ", "&nbsp;" }}
+    </span>
   {% endif %}
 
   <div class="nav-header">
     <h3 class="title">
-      <a href="javascript: void 0;">
+      {% capture docs_nav_title %}
         {{ layout.docs_title }}{% if selected_section %}: {{ selected_section.title }}{% endif %}
-      </a>
+      {% endcapture %}
+
+      {% if num_top_nav_items > 0 %}
+        <a href="javascript: void 0;">{{ docs_nav_title }}</a>
+      {% else %}
+        <span>{{ docs_nav_title }}</span>
+      {% endif %}
     </h3>
 
-    <span class="nav-toggle-icon">
-      <i class="open far fa-ellipsis-v"></i>
-      <i class="close far fa-times"></i>
-    </span>
+    {% if num_top_nav_items > 0 %}
+      <span class="nav-toggle-icon">
+        <i class="open far fa-ellipsis-v"></i>
+        <i class="close far fa-times"></i>
+      </span>
+    {% endif %}
   </div>
 </header>
 
 
-<section class="documentation {{ page.html-class }}">
+<section class="documentation {% if num_top_nav_items > 0 %}has-nav{% endif %}">
   <nav class="docs-nav">
     <ul class="nav-items">
       {% for item in nav.items %}

data/_sass/open-project-mixins.scss

@@ -206,8 +206,6 @@
 
     transition: background .1s linear, border-bottom .1s linear, transform .1s linear;
 
-    cursor: pointer;
-
     .section-title {
       flex: 1;
       flex-grow: 0;
@@ -236,7 +234,13 @@
         text-transform: uppercase;
         letter-spacing: 0.08em;
 
-        a { @include static-link-color(#444); }
+        a {
+          @include static-link-color(#444);
+        }
+
+        .nav-toggle-icon {
+          cursor: pointer;
+        }
       }
 
       .logo-container {

data/assets/js/opf.js

@@ -2,6 +2,9 @@
   'use strict';
 
 
+  var bigscreenBreakpoint = 900;
+  // Conforms to CSS @media rules
+
   var body = document.querySelector('body');
 
   // TODO: Best way (preferably w/o Node) to split these across files 
@@ -115,7 +118,8 @@
 
     var docsNavItemsContainer = docsNav.querySelector('.nav-items');
     var docsHeader = mainRoot.querySelector('header.documentation-header');
-    var docsHeaderLink = docsHeader.querySelector('a');
+
+    var hasNav = docsHeader.classList.contains('has-nav');
     var docsHeaderH = docsHeader.offsetHeight - 1;   // 1px to compensate for border
 
 
@@ -155,9 +159,17 @@
       else { open(docsNav); }
     };
 
-    docsHeader.addEventListener('click', toggle);
-
-    open(docsNav);
+    if (hasNav) {
+      docsHeader.addEventListener('click', toggle);
+      var viewportW = Math.max(document.documentElement.clientWidth, window.innerWidth || 0);
+      if (viewportW > bigscreenBreakpoint) {
+        open(docsNav);
+      } else {
+        collapse(docsNav);
+      }
+    } else {
+      collapse(docsNav);
+    }
 
 
     // Hiding docs nav

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-theme-open-project
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.2.2
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-12-24 00:00:00.000000000 Z
+date: 2018-12-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -72,14 +72,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.2.1
+        version: 1.2.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.2.1
+        version: 1.2.2
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement