Vanilla Docs

Contributing

If you find any problems in the docs or have a question, open an issue. Please submit edits & additions as pull requests against master.

Organization

All docs belong in the content folder, with further subdivisions based on the type of the document. Picking the right location for your docs is important.

The content/help folder is for all users of Vanilla Forums. Descriptions may include services and features specific to the vanillaforums.com cloud.

The content/developer folder is for all technical documentation. This is targetted at developers that are perhaps implementing their own code solutions. These docs may include descriptions of solutions that are not possible or disallowed on VanillaForums.com cloud. Clients of VanillaForums.com should consult support or their customer success manager for guidance.

The content/api folder is for API documentation and api-related information (such as Smart ID and how it works).

Formatting

Every doc file must end in .md and be formatted in Markdown.
Use H2 (## in Markdown) for major sub-topics and H3 (###) for minor headings.
Document H1 tags are automatically generated, so don't add your own.
All images go within static/img and must be referenced absolutely (/img/foo.png).
Images may be deeply nested for organizational purposes.
Use descriptive image names that include their topic area and what they depict, and hyphenate-the-names.png.

Writing

Be brief but clear.
Carefully consider organization.
Cross-reference with links liberally.
Break up long sentences and paragraphs.

Structure

Consciously build menus using the front-matter

Technical Setup

These documents are built using the Hugo static site generator. The content is formatted in Markdown and the templates use the Go html/template library. The generator supports both partials and shortcodes (partials that can be used in the content too).

This repository uses Grunt to automate the build and editing processes. Grunt and its various plugins and dependencies (including Hugo itself) are installed using Node Package Manager.

The docs themselves are published to GitHub Pages and live at http://docs.vanillaforums.com.

How to get started

Installing the project locally

Make sure you have npm installed:
- OS X: $ brew install npm
- Windows: ???
Fork or clone the repository (depending on whether you have commit access)
From the root of the folder, use npm to install the project: $ npm install

That should be it, you now have a working copy of the docs.

Live Editing

The docs can be viewed live while you edit them, which makes writing new content really easy.

Simply enable editing mode: $ npm run edit You should now have a locally accessible webserver providing the docs site at http://127.0.0.1:8080. This site should be livereload-enabled, so changes you make locally should trigger a page reload on the site. Now create some docs!

Submitting your changes

When you're done writing docs or making edits, just create a pull-request against master and wait for your content to be merged and published!

Publishing (for maintainers)

Publishing is easy. Just build the site statically using $ grunt build and then push it to the gh-pages branch using $ grunt push.

Note: Having built the site using the live editor is NOT SUFFICIENT for a push, and will likely break the deployment. Always deploy a freshly built site using grunt build.

austins / docs