README.md in jekyll-theme-open-project-1.2.1 vs README.md in jekyll-theme-open-project-1.2.2

- old
+ new

@@ -14,15 +14,12 @@ * Creating a site: [how to](#starting-a-site-with-this-theme) * [General site setup](#general-setup) * [Hub site setup](#hub-site) - * [Project site setup](#project-site) + * [Project site setup](#project-site) and describing your software and specs -* Describing open projects: - [Project data structure](#describing-a-project-shared-data-structure) - * Customizing site looks: * [Style customization](#style-customization) * [SVG guidelines](#svg-guidelines) * [Content guidelines](#content-guidelines) @@ -217,11 +214,11 @@ ``` 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 The hub represents your company or department, links to all projects @@ -246,13 +243,11 @@ namespace_id: "Human-readable namespace name" ``` ### 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 title: Sample Awesome Project @@ -262,30 +257,14 @@ # Whether the project is included in featured three projects on hub home page 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>"] - -# 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 Create software index in _pages/projects.html, with nothing but frontmatter. @@ -338,11 +317,11 @@ ``` ## 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: ```yaml @@ -361,49 +340,117 @@ 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. + +# 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" ``` -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. +### File structure - -## 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. +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, placed in <name>/assets/symbol.svg within _software/ directory. @@ -416,11 +463,19 @@ 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 # page of project site. Lower number means higher priority # (as in, priority no. 1 means topmost item on home page, @@ -450,26 +505,30 @@ ``` #### 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: - { title: Overview, path: overview/ } - { title: Installation, path: installation/ } - 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 site and builds them, converting pages from Markdown/AsciiDoc to HTML and adding the navigation. @@ -592,11 +651,11 @@ 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. Will show a list of open projects across the hub. @@ -606,12 +665,15 @@ - spec-index: Specification index page (hub site only). 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 Typical expected page frontmatter is `title` and `description`. Those are also used by jekyll-seo-tag plugin to add the appropriate meta tags.