If you find any problems in the docs or have a question, open an issue. Please submit edits & additions as pull requests against master
.
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).
- 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
.
- Be brief but clear.
- Carefully consider organization.
- Cross-reference with links liberally.
- Break up long sentences and paragraphs.
- Consciously build menus using the front-matter
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.
- Make sure you have
npm
installed:- OS X:
$ brew install npm
- Windows: ???
- OS X:
- 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.
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!
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 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
.