README.md in jekyll-theme-open-project-1.0.0.pre5 vs README.md in jekyll-theme-open-project-1.0.0.rc1

- old
+ new

@@ -10,26 +10,27 @@ to AWS S3. ## Contents -* Creating a site: [quick-start](#starting-a-site-with-this-theme) +* Creating a site: [how to](#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: +* Customizing site looks: * [Style customization](#style-customization) * [SVG guidelines](#svg-guidelines) * [Content guidelines](#content-guidelines) * [Select layout reference](#select-layout-reference) +* [Implementation gotchas](#gotchas) ## Starting a site with this theme ### Getting started with Ruby @@ -73,85 +74,93 @@ $ bundle ### 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. +and add files and folders to site contents. This step depends +on the type of site you’re creating: hub or individual project site. -Below sections explain core concepts of open project and hub, and go +Further 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. +This assumes you have mysite.local mapped in your hosts file, +otherwise omit --host and it’ll use “localhost” as domain name. ## Universal setup -These settings are required to both site types (hub and project). +These settings apply 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): +- Add `hero_include: home-hero.html` to YAML frontmatter + in your main `index.md`. + +- Add following items to site’s _config.yml + (and don’t forget to remove default theme requirement there): + ```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. tagline: Site tagline pitch: Site pitch # The above two are used on home hero unit. - permalink: /blog/:month-:day-:year/:title/ + seo: + type: Organization - theme: jekyll-theme-open-project - social: links: - https://twitter.com/<orgname> - https://github.com/<orgname> + + legal: + name: Full Organization Name + tos_link: https://www.example.com/tos + privacy_policy_link: https://www.example.com/privacy + + # These are required for the theme to work: + + theme: jekyll-theme-open-project + permalink: /blog/:month-:day-:year/:title/ ``` ### Logo -Logo consists of a symbol and site name. +By “logo” is meant the combination of site symbol as a graphic +and name as word(s). -**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. +- **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). -**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). + Drop your site-wide symbol in <site root>/assets/symbol.svg. -### Legal small text +- **Site name** displayed to the right of the symbol. + Limit the name to 1-3 words. -You may want to supply _includes/legal.html with content like this: + Drop a file called `title.html` in the root of your site. + In its contents you can go as simple as `{{ site.name }}` + and as complex as a custom SVG shape. + + Note that it must look good when placed inside ~30px tall container. + In case of SVG, SVG guidelines apply. + +Do not create custom CSS rules for .site-logo descendants: +this may cause issues when one site’s logo is used in context of another site +of the same hub. You can use inline styling, though. -```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. In case of the hub, blog index will show combined timeline @@ -301,12 +310,12 @@ author: "Company or Individual Name Goes Here" ``` File layout is the same as described in the section -about shared project data structure, with _software, _specs, _posts, _includes -directories found in the root of your Jekyll site. +about shared project data structure, with _software, _specs, _posts, assets +subdirectories 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, @@ -316,16 +325,16 @@ whether on hub home site or each individual project site: - <project-name>/ - _posts/ - 2038-02-31-blog-post-title.markdown - - _includes/ + - assets/ - symbol.svg - _software/ - <name>.md - <name>/ - - _includes/ + - assets/ - symbol.svg - _specs/ - <name>.md ### Blog @@ -340,11 +349,11 @@ 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. A software product additionally is required to have a symbol in SVG format, -placed in <name>/_includes/symbol.svg under _software/ directory. +placed in <name>/assets/symbol.svg within _software/ directory. YAML frontmatter that is expected with both software and specs: ```yaml title: A Few Words @@ -414,13 +423,13 @@ 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 look OK in dimensions of about 30x30, 60x60px. Must fit in a square. Should be in SVG format (see also the SVG guidelines section). -Place the symbol in _includes/symbol.svg within project directory. +Place the symbol in assets/symbol.svg within project directory. ## SVG guidelines - Ensure SVG markup does not use IDs. It may appear multiple times @@ -437,10 +446,32 @@ - Project description (featured): about 20-24 words, no markup - Blog post title: 3–7 words - Blog post excerpt: about 20–24 words, no markup -## Select layout reference +## Theme includes + +Commonly used overridable includes are (paths relative to your site root): + +- title.html: Site name in case you want to provide custom typography, + possibly as SVG. + +- project-nav.html (currently project sites only): Additional + links in project site’s top navigation, if needed. + +- assets/symbol.svg: Site-wide symbol is used as an include + to facilitate path fill color overrides via CSS rules. + +### Include location gotcha + +Theme configuration adds `includes_dir: .` to your site. +This means when Jekyll encounters `{% include <include_name> %}` +in a template, it looks first in `<site root>/<include_name>`, +and then in `<theme root>/_includes/<include_name>`. Consequently, +you put your include overrides directly in site root, **not** inside +`_includes/` directory of your side. + +## Theme layouts Normally you don’t need to specify layouts manually, except where instructed in site setup sections of this document. Commonly used layouts are: