daux.io/docs/00_Getting_Started.md

186 lines
5.5 KiB
Markdown
Raw Normal View History

2013-06-12 00:28:29 +02:00
**Daux.io** is an documentation generator that uses a simple folder structure and Markdown files to create custom documentation on the fly. It helps you create great looking documentation in a developer friendly way.
2013-06-03 15:32:55 +02:00
2013-06-04 19:26:14 +02:00
## Features
2013-06-03 15:32:55 +02:00
* 100% Mobile Responsive
2013-06-04 20:23:01 +02:00
* Supports GitHub Flavored Markdown
2013-06-12 00:28:29 +02:00
* Auto created homepage/landing page
2013-06-04 20:23:01 +02:00
* Auto Syntax Highlighting
2013-06-03 15:57:20 +02:00
* Auto Generated Navigation
2013-06-12 00:28:29 +02:00
* 4 Built-In Themes or roll your own
* Functional, Flat Design Style
2013-06-04 19:26:14 +02:00
* Shareable/Linkable SEO Friendly URLs
2013-06-04 20:23:01 +02:00
* Built On Bootstrap
* No Build Step
2013-06-04 19:26:14 +02:00
* Git/SVN Friendly
2013-07-22 17:38:04 +02:00
* Supports Google Analytics and Piwik Analytics
2013-06-12 00:28:29 +02:00
* Optional code float layout
2013-06-04 19:26:14 +02:00
2013-06-04 20:23:01 +02:00
## Demos
2013-06-12 00:28:29 +02:00
This is a list of sites using Daux.io:
2013-06-04 20:23:01 +02:00
2013-06-21 18:36:57 +02:00
* [Daux.io](http://daux.io)
2013-06-04 20:23:01 +02:00
2013-06-21 17:49:05 +02:00
Do you use Daux.io? Send me a pull request or open an [issue](https://github.com/justinwalsh/daux.io/issues) and I will add you to the list.
2013-06-04 20:23:01 +02:00
2013-06-04 19:26:14 +02:00
## Download
2013-06-04 20:23:01 +02:00
Download this repository as a zip, and unpack. Copy the files to a web server that can run PHP. You can also run the documentation locally using Grunt.js, which is covered at the end of this readme.
2013-06-04 19:26:14 +02:00
## Folders
2013-06-04 20:23:01 +02:00
2013-06-12 00:28:29 +02:00
The generator will look for folders in the `/docs` folder. Add your folders inside the `/docs` folder. This project contains some example folders and files to get you started.
2013-06-04 19:26:14 +02:00
2013-06-12 00:28:29 +02:00
You can nest folders any number of levels to get the exact structure you want. The folder structure will be converted to the nested navigation.
2013-06-04 19:26:14 +02:00
## Files
2013-06-04 20:23:01 +02:00
2013-06-21 21:09:37 +02:00
The generator will look for Markdown `*.md` files inside the `/docs` folder and any of the subfolders within /docs.
2013-06-04 19:26:14 +02:00
2013-06-04 20:23:01 +02:00
You must use the `.md` file extension for your files. Also, you must use underscores instead of spaces. Here are some example file names and what they will be converted to:
2013-06-04 19:26:14 +02:00
2013-06-04 20:23:01 +02:00
**Good:**
2013-06-04 19:26:14 +02:00
2013-06-04 20:23:01 +02:00
* 01_Getting_Started.md = Getting Started
* API_Calls.md = API Calls
* 200_Something_Else-Cool.md = Something Else-Cool
**Bad:**
* File Name With Space.md = FAIL
2013-06-04 19:26:14 +02:00
## Sorting
2013-06-04 20:23:01 +02:00
2013-07-15 21:23:50 +02:00
To sort your files and folders in a specific way, you can prefix them with a number and underscore, e.g. `/docs/01_Hello_World.md` and `/docs/05_Features.md` This will list *Hello World* before *Features*, overriding the default alpha-numeric sorting. The numbers will be stripped out of the navigation and urls.
2013-06-04 19:26:14 +02:00
2013-06-21 21:09:37 +02:00
## Landing page
If you want to create a beautiful landing page for your project, simply create a `index.md` file in the root of the `/docs` folder. This file will then be used to create a landing page. You can also add a tagline and image to this page using the config file like this:
{
"title": "Daux.io",
"tagline": "The Easiest Way To Document Your Project",
"image": "/img/app.png"
}
Note: The image can be a local or remote image.
2013-06-04 19:26:14 +02:00
## Configuration
2013-06-04 20:23:01 +02:00
To customize the look and feel of your documentation, you can create a `config.json` file in the of the `/docs` folder. The `config.json` file is a simple JSON object that you can use to change some of the basic settings of the documentation.
2013-06-12 00:28:29 +02:00
###Title:
2013-06-04 19:26:14 +02:00
Change the title bar in the docs
{
2013-06-12 00:28:29 +02:00
"title": "Daux.io"
2013-06-04 19:26:14 +02:00
}
2013-06-12 00:28:29 +02:00
###Themes:
We have 4 built-in Bootstrap themes. To use one of the themes, just set the `theme` option to one of the following:
2013-06-04 19:26:14 +02:00
2013-06-12 00:28:29 +02:00
* blue
* green
* navy
* red
2013-06-04 19:26:14 +02:00
2013-06-12 00:28:29 +02:00
```
{
"theme": "blue"
}
```
###Custom Theme:
To create a custom color scheme, set the `theme` property to `custom` and then define the required colors. Copy the following configuration to get started:
2013-06-04 19:26:14 +02:00
{
2013-06-12 00:28:29 +02:00
"theme": "custom",
"colors": {
"sidebar-background": "#f7f7f7",
"sidebar-hover": "#c5c5cb",
"lines": "#e7e7e9",
"dark": "#3f4657",
"light": "#82becd",
"text": "#2d2d2d",
"syntax-string": "#022e99",
"syntax-comment": "#84989b",
"syntax-number": "#2f9b92",
"syntax-label": "#840d7a"
}
2013-06-04 19:26:14 +02:00
}
2013-06-12 00:28:29 +02:00
###Code Floating:
By deafult your code blocks will be floated to a column on the right side of your content. To disable this feature, set the `float` property to `false`.
2013-06-04 19:26:14 +02:00
{
2013-06-12 00:28:29 +02:00
"float": false
2013-06-04 19:26:14 +02:00
}
2013-06-12 00:28:29 +02:00
2013-07-17 18:54:08 +02:00
###GitHub Repo:
Add a 'Fork me on GitHub' ribbon.
2013-06-04 19:26:14 +02:00
{
2013-06-21 17:49:05 +02:00
"repo": "justinwalsh/daux.io"
2013-06-04 19:26:14 +02:00
}
2013-06-12 00:28:29 +02:00
###Twitter:
2013-06-04 19:26:14 +02:00
Include twitter follow buttons in the sidebar.
{
"twitter": ["justin_walsh", "todaymade"]
}
2013-06-12 00:28:29 +02:00
###Links:
2013-06-04 19:26:14 +02:00
Include custom links in the sidebar.
{
"links": {
2013-07-17 18:54:08 +02:00
"GitHub Repo": "https://github.com/justinwalsh/daux.io",
2013-06-21 17:49:05 +02:00
"Help/Support/Bugs": "https://github.com/justinwalsh/daux.io/issues",
"Made by Todaymade": "http://todaymade.com"
2013-06-04 19:26:14 +02:00
}
}
2013-06-21 21:36:50 +02:00
###Google Analytics:
This will embed the google analytics tracking code.
{
"google_analytics": "UA-XXXXXXXXX-XX"
}
2013-07-22 17:38:04 +02:00
###Piwik Analytics:
This will embed the piwik tracking code.
{
"piwik_analytics": "my-url-for-piwik.com"
}
2013-07-22 17:48:18 +02:00
###Ignore:
Set custom files and entire folders to ignore within your `/docs` folder. For files make sure to include the file extension in the name. For both files and folders, names are case-sensitive.
{
"ignore": {
files: ["Work_In_Progress.md"],
folders: ["99_Not_Ready"]
}
}
2013-06-04 19:26:14 +02:00
## Running Locally
2013-06-12 00:28:29 +02:00
You can run the docs locally using <a href="http://gruntjs.com/" target="_blank">Grunt.js</a> I assume you are familiar with how to use Grunt and have the latest version of PHP 5.4 installed which is able to run a webserver.
2013-06-04 19:26:14 +02:00
**Requirements:**
2013-06-04 20:23:01 +02:00
2013-06-04 19:26:14 +02:00
* Node.js
* npm
* Grunt.js
* PHP 5.4 or greater
2013-06-04 20:23:01 +02:00
This project contains a package.json file, so once you have the requirements installed, you can simply run a `npm install` and then `grunt` in the projects folder to start the local web server. By default the server will run at: <a href="http://localhost:8085" target="_blank">http://localhost:8085</a>
2013-06-04 19:26:14 +02:00
2013-06-04 20:23:01 +02:00
## Support
2013-06-04 19:26:14 +02:00
2013-07-17 18:54:08 +02:00
If you need help using Daux.io, or have found a bug, please create an issue on the <a href="https://github.com/justinwalsh/daux.io/issues" target="_blank">GitHub repo</a>.