CONFIGURATION.md

Configuration

1. The Sync Paths File
2. The Sync Config File

The Sync Paths File

readmeio-sync tracks all your content using the syncPaths.json file. This file is created during initialization.

Here is an example syncPaths.json file:

{
    "adaptivejs-staging": {
        "v2.0": {
            "documentation": "adaptivejs-staging/v2.0/documentation",
            "customPages": "adaptivejs-staging/v2.0/customPages",
            "customContent": {
                "appearance": {
                    "html_body": "adaptivejs-staging/v2.0/customContent/appearance/landing_page.html",
                    "stylesheet": "adaptivejs-staging/v2.0/customContent/appearance/styles.css"
                }
            }
        },
        "v1.0": {
            "documentation": "adaptivejs-staging/v1.0/documentation",
            "customPages": "adaptivejs-staging/v1.0/customPages",
            "customContent": {
                "appearance": {
                    "html_body": "adaptivejs-staging/v1.0/customContent/appearance/landing_page.html",
                    "stylesheet": "adaptivejs-staging/v1.0/customContent/appearance/styles.css"
                }
            }
        }
    }
}

Explanation of the Sections

Project Root

The top level key is the slug for the project the registry is representing.

"adaptivejs-staging": {...}

Versions

Within the top level object are all the hosted versions of the documentation.

This tool is currently not capable of creating new versions. You will need to ensure any versions listed in this file already exist on readme.io

"adaptive-restructing-test": {
	"v2.0": {...},
	"v1.0": {...}
}

Documentation

Each version has a documentation field, which holds a path to the folder where the documentation is contained.

"v2.0": {
	"documentation": "adativejs-staging/v2.0/documentation",
	...
},
...

Documentation Folder Structure

Documentation is automatically extracted from your filesystem. All you need to do is provide the path to the directory where the documentation for that version is.

The directory should have the following structure:

- <root_folder>
    - <category_order_#>-<category_title>
        * <document_order_#>-<document_title>.md
        * ...
    - ...

Example:

- documentation
    - 1-Category 1
        * 1-Document 1.md
        * 2-Document 2.md
        * ...
    - 2-Category 2
        * 1-Document 1.md
        * 2-Document 2.md
        * ...
    - ...

* = File - = Directory

The order numbers where determine the order that the documents/categories are organized.

If you don't want a document to be uploaded, remove the order number from the beginning of its name.

Document File Structure

Readmeio-sync does special parsing of your markdown files to:

1. Extract metadata (excerpt and custom slug)
2. Code block conversion

Example Documentation File:

excerpt: This is the description of your doc.
slug: important-doc

# Content!

 ` ``javascript
 	// This code block will get converted to readmeio format!

 	var foo = 'bar';
 ` ``

Make sure to include an excerpt and slug descriptor at the top of all your files, followed by a newline.

Custom Pages

Each version will have a section for custom pages. customPages is a path to the folder where custom page (html) files are contained.

(Currently there is a Readme.io bug which does not allow versioned pages. As such, only use one custom pages section for all versions.)

"v2.0": {
	"customPages": "adaptivejs-staging/v2.0/customPages"
	...
}
...

Custom Page Folder Structure

Custom pages are extracted from the specified directory. In the directory, your custom pages should be specified like so:

- <root_folder>
	* <page_title>.html
	* ...

Example:

- customPages
	* FirstCustomPage.html
	* SecondCustomPage.html
	* ...

* = File
- = Directory

Custom Content

The custom content object let's you upload a stylesheet (Dashboard > Appearance > Custom Stylesheet) as well as html for the landing page (Dashboard > Appearance > Landing Page (Body Content)).

"v2.0": {
	"customContent": {
		"selector": ".c-readme-body",
		"appearance": {
			"html_body": "www/index.html",
			"stylesheet": "www/css/main.css"
		}
	}
}
...

• selector (Optional): Can be used to select a subset of the html specified in the html_body file
• appearance: Necessary object expected by the api
• html_body: Path to the landing page html file
• stylesheet: Path to a css stylesheet

---

The Sync Config File

readmeio-sync allows you to specify a docs staging project so that you can test out your changes. To tell readmeio-sync about the different projects a syncConfig.json is used. This file holds the slugs for both your staging and production projects.

Example syncConfig.json

{
    "projectNames": {
        "staging": "readme-io-sync",
        "production": "readme-io-sync"
    }
}

Although editing this file by hand works, readmeio-sync config [-s <staging-slug>] [-p <production-slug] is a convenience command for updating these values.