From e9e95c974739485cbcd12e2d81bb8a6a2dc106dd Mon Sep 17 00:00:00 2001 From: Tim Mathews Date: Thu, 22 Sep 2016 15:46:54 -0400 Subject: [PATCH] Update README.md Rewrite content authoring guidelines --- README.md | 36 ++++++++++++++++++++++++++++-------- specification.md | 2 +- 2 files changed, 29 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 7960866..be8a2f7 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,32 @@ -This is the repository for the website at http://signalk.github.io +# SignalK.org -#### Instructions for adding posts, pages, etc. +This is the repository for the [Signal K](http://signalk.org) website. -New blog posts go in the _posts folder and should be named YYYY-MM-DD-post-name.. The front matter for these -posts should include a title and author. The layout should be 'post'. Markdown, textile and HTML are pretty much the -format choices. Markdown is preferred except in cases where the content is to complex. +## Making Changes -Pages that aren't API reference material should be in the root folder, API reference pages go in the api folder. These -don't need a date prepended and their layout should be 'page'. +The website is hosted by GitHub Pages and most content is authored in Markdown format. HTML is also acceptable. Each +page has at the beginning a section called _front matter_. This is YAML between three dashes and looks like: -New navbar links can be addd in _includes/header.html and use Bootstrap classes for styling. +``` +--- +layout: page +title: Some Page +--- +``` + +Every page needs at least a layout and a title. It is also useful to add a description to be helpful to search engines. +Valid layouts can be found in the `_layouts` directory. Generally, you will want to use `onecolumn`, but `post` and +`rsidebar` can also be used. If you specify `rsidebar`, you will also need to create content for the sidebar and a +front matter variable `sidebar` which points to the sidebar file. This file should be placed in the `_includes` +directory. See `installation.md` or `overview.md` for an example of how this works. + +To create a new published subdirectory, add it to `collections` in `_config.yml`. Published subdirectories should be +named with a leading underscore. + +If you rename a page or move its content elsewhere, be a good web citizen and add a redirect from the old location to +the new. For instance, if you want to move the content of `overview.md` to `getting_started.md`, don't just remove +`overview.md`, rather remove its content and add a `redirect` variable to its front matter pointing to the new page. See +`specification.md` for an example of this. + +When creating links to local resources, such as between pages, prefix them with `{{site.path}}` and use absolute, rather +than relative paths. This ensures links continue to work in staging. diff --git a/specification.md b/specification.md index 11a930b..4a10581 100644 --- a/specification.md +++ b/specification.md @@ -9,4 +9,4 @@ redirect: http://signalk.org/specification/master/keys ## {{page.title}} The specification has been relocated to the consolidated Signal K documentation at -{{site.baseurl}}/specification/master. You should be redirected shortly. +{{site.path}}/specification/master. You should be redirected shortly.