daux.io/docs/00_Getting_Started.md

133 regels
4.5 KiB
Markdown

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
2016-04-12 08:38:52 +02:00
[TOC]
2013-06-04 19:26:14 +02:00
## Features
2013-06-03 15:32:55 +02:00
2015-12-12 00:22:43 +01:00
### For Authors
* [Auto Generated Navigation / Page sorting](!Features/Navigation_and_Sorting)
* [Internal documentation links](!Features/Internal_links)
* [Github Flavored Markdown](!Features/GitHub_Flavored_Markdown)
* [Auto created homepage/landing page](!Features/Landing_page)
* [Multiple Output Formats](!Features/Multiple_Output_Formats)
* [Multiple Languages Support](!Features/Multilanguage)
* [No Build Step](!Features/Live_mode)
* [Static Output Generation](!Features/Static_Site_Generation)
2016-04-12 08:38:52 +02:00
* [Table of Contents](!Features/Table_of_contents)
2015-12-12 00:22:43 +01:00
### For Developers
* [Auto Syntax Highlighting](!Features/Auto_Syntax_Highlight)
* [Extend Daux.io with Processors](!For_Developers/Creating_a_Processor)
* Full access to the internal API to create new pages programatically
* Work with pages metadata
### For Marketing
* 100% Mobile Responsive
2013-06-12 00:28:29 +02:00
* 4 Built-In Themes or roll your own
* Functional, Flat Design Style
2015-12-12 00:22:43 +01:00
* Optional code float layout
2013-06-04 19:26:14 +02:00
* Shareable/Linkable SEO Friendly URLs
2013-07-22 17:38:04 +02:00
* Supports Google Analytics and Piwik Analytics
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)
* [jDrupal](http://jdrupal.easystreet3.com/8/docs/)
* [DrupalGap](http://docs.drupalgap.org/8/)
* [Invade & Annex 3 - An Arma 3 Co-operative Mission](http://ia3.ahoyworld.co.uk/)
2013-07-29 03:58:19 +02:00
* [Munee: Standalone PHP 5.3 Asset Optimisation & Manipulation](http://mun.ee)
* [ICADMIN: An admin panel powered by CodeIgniter.](http://istocode.com/shared/ic-admin/)
2013-06-04 20:23:01 +02:00
2015-12-12 00:22:43 +01:00
Do you use Daux.io? Send us 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
2015-12-12 00:22:43 +01:00
## Getting Started
### Download
2013-06-04 19:26:14 +02:00
2015-07-21 09:49:49 +02:00
Download this repository as a zip, and unpack. Copy the files to a web server that can run PHP 5.3 or greater.
You can also run the documentation locally using Grunt.js, which is covered at the end of this readme.
If you don't intend to modify Daux.io and just want to use it, you only need to copy `resources`, `daux.phar`, `global.json`, `generate`, `serve` and `index.php` With these, you're ready to create your documentation.
If however you wish to do some advanced modifications, I recommend you use the raw version and run `composer install` to get started.
2013-06-04 19:26:14 +02:00
2015-12-12 00:22:43 +01:00
### Writing pages
2015-07-19 16:36:59 +02:00
2015-12-12 00:22:43 +01:00
Creating new pages is very easy:
1. Create a markdown file (`*.md` or `*.markdown`)
2. Start writing
2013-06-04 20:23:01 +02:00
2015-12-12 00:22:43 +01:00
By default, 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
2015-12-12 00:22:43 +01: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
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
* _5_Ways_to_Be_Happy.md = 5 Ways To Be Happy
2013-06-04 20:23:01 +02:00
**Bad:**
* File Name With Space.md = FAIL
2013-06-04 19:26:14 +02:00
2015-12-12 00:22:43 +01:00
### See your pages
2013-06-12 00:28:29 +02:00
2015-12-12 00:22:43 +01:00
Now you can see your pages. you have two options for that : serve them directly, or generate to various formats.
2013-06-04 19:26:14 +02:00
2015-12-12 00:22:43 +01:00
We recommend the first one while you write your documentation, you get a much quicker feedback while writing.
2013-06-04 19:26:14 +02:00
2015-12-12 00:22:43 +01:00
#### Serving files
2013-06-04 19:26:14 +02:00
2015-12-12 00:22:43 +01:00
You can use PHP's embedded web server by running the following command in the root of your documentation
2013-06-04 19:26:14 +02:00
2013-07-29 03:58:19 +02:00
```
2015-12-12 00:22:43 +01:00
./serve
2013-07-29 03:58:19 +02:00
```
2013-06-21 21:36:50 +02:00
2015-12-12 00:22:43 +01:00
Upload your files to an apache / nginx server and see your documentation
2013-07-22 17:38:04 +02:00
2015-12-12 00:22:43 +01:00
[More informations here](!Features/Live_mode)
2013-10-22 22:50:46 +02:00
2015-12-12 00:22:43 +01:00
#### Export to other formats
2014-05-31 07:43:07 +02:00
2015-12-12 00:22:43 +01:00
Daux.io is extendable and comes by default with three export formats:
2013-07-29 20:58:04 +02:00
2015-12-12 00:22:43 +01:00
- Export to HTML, same as the website, but can be hosted without PHP.
- Export all documentation in a single HTML page
- Upload to your Atlassian Confluence server.
2015-07-19 16:36:59 +02:00
2015-12-12 00:22:43 +01:00
[See a detailed feature comparison matrix](!Features/Multiple_Output_Formats)
2015-07-19 16:36:59 +02:00
2015-12-12 00:22:43 +01:00
Here's how you run an export:
2015-12-12 00:22:43 +01:00
```bash
./generate
```
2015-12-12 00:22:43 +01:00
[See here for all options](!Features/Static_Site_Generation)
2015-12-12 00:22:43 +01:00
## Configuration
2015-12-12 00:22:43 +01:00
Now that you got the basics, you can also [see what you can configure](!Configuration)
2013-07-30 15:56:16 +02:00
## Known Issues
- __Windows UTF-8 files support__ Files with UTF-8 characters cannot be handled on windows, this issue has no known fix yet.
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>.