Reformat documentation
This commit is contained in:
Stéphane Goetz
parent
ec8530b264
commit
4d312a44e6
|
|
@ -14,22 +14,22 @@ appearance, race, religion, or sexual identity and orientation.
|
|||
Examples of behavior that contributes to creating a positive environment
|
||||
include:
|
||||
|
||||
* Using welcoming and inclusive language
|
||||
* Being respectful of differing viewpoints and experiences
|
||||
* Gracefully accepting constructive criticism
|
||||
* Focusing on what is best for the community
|
||||
* Showing empathy towards other community members
|
||||
- Using welcoming and inclusive language
|
||||
- Being respectful of differing viewpoints and experiences
|
||||
- Gracefully accepting constructive criticism
|
||||
- Focusing on what is best for the community
|
||||
- Showing empathy towards other community members
|
||||
|
||||
Examples of unacceptable behavior by participants include:
|
||||
|
||||
* The use of sexualized language or imagery and unwelcome sexual attention or
|
||||
advances
|
||||
* Trolling, insulting/derogatory comments, and personal or political attacks
|
||||
* Public or private harassment
|
||||
* Publishing others' private information, such as a physical or electronic
|
||||
address, without explicit permission
|
||||
* Other conduct which could reasonably be considered inappropriate in a
|
||||
professional setting
|
||||
- The use of sexualized language or imagery and unwelcome sexual attention or
|
||||
advances
|
||||
- Trolling, insulting/derogatory comments, and personal or political attacks
|
||||
- Public or private harassment
|
||||
- Publishing others' private information, such as a physical or electronic
|
||||
address, without explicit permission
|
||||
- Other conduct which could reasonably be considered inappropriate in a
|
||||
professional setting
|
||||
|
||||
## Our Responsibilities
|
||||
|
||||
|
|
|
|||
146
README.md
146
README.md
|
|
@ -1,6 +1,5 @@
|
|||
# Daux.io
|
||||
|
||||
|
||||
[](https://github.com/dauxio/daux.io/releases)
|
||||
[](https://github.com/dauxio/daux.io/blob/master/LICENSE.md)
|
||||
[](https://github.com/dauxio/daux.io/actions)
|
||||
|
|
@ -8,45 +7,42 @@
|
|||
[](https://scrutinizer-ci.com/g/dauxio/daux.io)
|
||||
[](https://packagist.org/packages/daux/daux.io)
|
||||
|
||||
|
||||
**Daux.io** is a 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.
|
||||
|
||||
## Features
|
||||
|
||||
* 100% Mobile Responsive
|
||||
* CommonMark compliant (a Markdown specification)
|
||||
* Supports Markdown tables
|
||||
* Auto created homepage/landing page
|
||||
* Auto Syntax Highlighting
|
||||
* Auto Generated Navigation
|
||||
* 4 Built-In Themes or roll your own
|
||||
* Functional, Flat Design Style
|
||||
* Shareable/Linkable SEO Friendly URLs
|
||||
* Built On Bootstrap
|
||||
* No Build Step
|
||||
* Git/SVN Friendly
|
||||
* Supports Google Analytics and Piwik Analytics
|
||||
* Optional code float layout
|
||||
* Static Output Generation
|
||||
- 100% Mobile Responsive
|
||||
- CommonMark compliant (a Markdown specification)
|
||||
- Supports Markdown tables
|
||||
- Auto created homepage/landing page
|
||||
- Auto Syntax Highlighting
|
||||
- Auto Generated Navigation
|
||||
- 4 Built-In Themes or roll your own
|
||||
- Functional, Flat Design Style
|
||||
- Shareable/Linkable SEO Friendly URLs
|
||||
- Built On Bootstrap
|
||||
- No Build Step
|
||||
- Git/SVN Friendly
|
||||
- Supports Google Analytics and Piwik Analytics
|
||||
- Optional code float layout
|
||||
- Static Output Generation
|
||||
|
||||
## Demos
|
||||
|
||||
This is a list of sites using Daux.io:
|
||||
|
||||
- With a custom theme:
|
||||
* [Crafty](https://swissquote.github.io/crafty)
|
||||
* [Pixolution flow](https://docs.pixolution.org)
|
||||
* [Soisy](https://doc.soisy.it/)
|
||||
* [Vulkan Tutorial](https://vulkan-tutorial.com)
|
||||
* [3Q](https://docs.3q.video/)
|
||||
* [The Advanced RSS Environment](https://thearsse.com/manual/)
|
||||
- With the default Theme
|
||||
* [Daux.io](https://daux.io/)
|
||||
* [DoctrineWatcher](https://dsentker.github.io/WatcherDocumentation/)
|
||||
* [DrupalGap](http://docs.drupalgap.org/8/)
|
||||
* [ICADMIN: An admin panel powered by CodeIgniter.](http://istocode.com/shared/ic-admin/)
|
||||
* [Munee: Standalone PHP 5.3 Asset Optimisation & Manipulation](http://mun.ee)
|
||||
* [Nuntius: A PHP framework for bots](https://roysegall.github.io/nuntius-bot/)
|
||||
- With a custom theme:
|
||||
- [Crafty](https://swissquote.github.io/crafty)
|
||||
- [Pixolution flow](https://docs.pixolution.org) \* [Soisy](https://doc.soisy.it/)
|
||||
- [Vulkan Tutorial](https://vulkan-tutorial.com) \* [3Q](https://docs.3q.video/)
|
||||
- [The Advanced RSS Environment](https://thearsse.com/manual/)
|
||||
- With the default Theme
|
||||
- [Daux.io](https://daux.io/)
|
||||
_ [DoctrineWatcher](https://dsentker.github.io/WatcherDocumentation/)
|
||||
_ [DrupalGap](http://docs.drupalgap.org/8/)
|
||||
- [ICADMIN: An admin panel powered by CodeIgniter.](http://istocode.com/shared/ic-admin/)
|
||||
- [Munee: Standalone PHP 5.3 Asset Optimisation & Manipulation](http://mun.ee)
|
||||
- [Nuntius: A PHP framework for bots](https://roysegall.github.io/nuntius-bot/)
|
||||
|
||||
Do you use Daux.io? Send me a pull request or open an [issue](https://github.com/dauxio/daux.io/issues) and I will add you to the list.
|
||||
|
||||
|
|
@ -101,18 +97,18 @@ You must use underscores instead of spaces. Here are some example file names and
|
|||
|
||||
**Good:**
|
||||
|
||||
* 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
|
||||
- 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
|
||||
|
||||
**Bad:**
|
||||
|
||||
* File Name With Space.md = FAIL
|
||||
- File Name With Space.md = FAIL
|
||||
|
||||
## Sorting
|
||||
|
||||
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. For the file `6 Ways to Get Rich`, you can use `/docs/_6_Ways_to_Get_Rich.md`
|
||||
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. For the file `6 Ways to Get Rich`, you can use `/docs/_6_Ways_to_Get_Rich.md`
|
||||
|
||||
## Landing page
|
||||
|
||||
|
|
@ -120,9 +116,9 @@ If you want to create a beautiful landing page for your project, simply create a
|
|||
|
||||
```json
|
||||
{
|
||||
"title": "Daux.io",
|
||||
"tagline": "The Easiest Way To Document Your Project",
|
||||
"image": "app.png"
|
||||
"title": "Daux.io",
|
||||
"tagline": "The Easiest Way To Document Your Project",
|
||||
"image": "app.png"
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -138,33 +134,37 @@ To customize the look and feel of your documentation, you can create a `config.j
|
|||
The `config.json` file is a simple JSON object that you can use to change some of the basic settings of the documentation.
|
||||
|
||||
### Title
|
||||
|
||||
Change the title bar in the docs
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "Daux.io"
|
||||
"title": "Daux.io"
|
||||
}
|
||||
```
|
||||
|
||||
### Themes
|
||||
|
||||
We have 4 built-in Bootstrap themes. To use one of the themes, just set the `theme` option to one of the following:
|
||||
|
||||
* daux-blue
|
||||
* daux-green
|
||||
* daux-navy
|
||||
* daux-red
|
||||
- daux-blue
|
||||
- daux-green
|
||||
- daux-navy
|
||||
- daux-red
|
||||
|
||||
```json
|
||||
{
|
||||
"html": { "theme": "daux-green" }
|
||||
"html": { "theme": "daux-green" }
|
||||
}
|
||||
```
|
||||
|
||||
### More options
|
||||
|
||||
Many other options are available:
|
||||
- [Global options](http://daux.io/Configuration/index)
|
||||
- [HTML Options](http://daux.io/Configuration/Html_export)
|
||||
- [Confluence options](http://daux.io/Configuration/Confluence_upload)
|
||||
|
||||
- [Global options](http://daux.io/Configuration/index)
|
||||
- [HTML Options](http://daux.io/Configuration/Html_export)
|
||||
- [Confluence options](http://daux.io/Configuration/Confluence_upload)
|
||||
|
||||
## Running Remotely
|
||||
|
||||
|
|
@ -173,7 +173,7 @@ Copy the files from the repo to a web server that can run PHP 7.2.0 or newer.
|
|||
## Running Locally
|
||||
|
||||
There are several ways to run the docs locally.
|
||||
The recommended way is to run `daux serve` which will execute PHP's embedded server.
|
||||
The recommended way is to run `daux serve` which will execute PHP's embedded server.
|
||||
|
||||
By default the server will run at: <a href="http://localhost:8085" target="_blank">http://localhost:8085</a>
|
||||
|
||||
|
|
@ -193,8 +193,8 @@ daux --source=docs --destination=static
|
|||
|
||||
If you have set up a local or remote IIS web site, you may need a `web.config` with:
|
||||
|
||||
* A rewrite configuration, for handling clean urls.
|
||||
* A mime type handler for less files, if using a custom theme.
|
||||
- A rewrite configuration, for handling clean urls.
|
||||
- A mime type handler for less files, if using a custom theme.
|
||||
|
||||
### Clean URLs
|
||||
|
||||
|
|
@ -202,20 +202,32 @@ The `web.config` needs an entry for `<rewrite>` under `<system.webServer>`:
|
|||
|
||||
```xml
|
||||
<configuration>
|
||||
<system.webServer>
|
||||
<rewrite>
|
||||
<rules>
|
||||
<rule name="Main Rule" stopProcessing="true">
|
||||
<match url=".*" />
|
||||
<conditions logicalGrouping="MatchAll">
|
||||
<add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
|
||||
<add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
|
||||
</conditions>
|
||||
<action type="Rewrite" url="index.php" appendQueryString="false" />
|
||||
</rule>
|
||||
</rules>
|
||||
</rewrite>
|
||||
</system.webServer>
|
||||
<system.webServer>
|
||||
<rewrite>
|
||||
<rules>
|
||||
<rule name="Main Rule" stopProcessing="true">
|
||||
<match url=".*" />
|
||||
<conditions logicalGrouping="MatchAll">
|
||||
<add
|
||||
input="{REQUEST_FILENAME}"
|
||||
matchType="IsFile"
|
||||
negate="true"
|
||||
/>
|
||||
<add
|
||||
input="{REQUEST_FILENAME}"
|
||||
matchType="IsDirectory"
|
||||
negate="true"
|
||||
/>
|
||||
</conditions>
|
||||
<action
|
||||
type="Rewrite"
|
||||
url="index.php"
|
||||
appendQueryString="false"
|
||||
/>
|
||||
</rule>
|
||||
</rules>
|
||||
</rewrite>
|
||||
</system.webServer>
|
||||
</configuration>
|
||||
```
|
||||
|
||||
|
|
@ -223,7 +235,7 @@ To use clean URLs on IIS 6, you will need to use a custom URL rewrite module, su
|
|||
|
||||
## PHP Requirements
|
||||
|
||||
Daux.io is compatible with the [officially supported](https://www.php.net/supported-versions.php) PHP versions; 7.2.0 and up.
|
||||
Daux.io is compatible with the [officially supported](https://www.php.net/supported-versions.php) PHP versions; 7.2.0 and up.
|
||||
|
||||
### Extensions
|
||||
|
||||
|
|
|
|||
|
|
@ -6,49 +6,48 @@
|
|||
|
||||
### For Authors
|
||||
|
||||
* [Auto Generated Navigation / Page sorting](01_Features/Navigation_and_Sorting.md)
|
||||
* [Internal documentation links](01_Features/Internal_links.md)
|
||||
* [CommonMark compliant](01_Features/CommonMark_compliant.md)
|
||||
* [Auto created homepage/landing page](01_Features/Landing_page.md)
|
||||
* [Multiple Output Formats](01_Features/Multiple_Output_Formats.md)
|
||||
* [Multiple Languages Support](01_Features/Multilanguage.md)
|
||||
* [No Build Step](01_Features/Live_mode.md)
|
||||
* [Static Output Generation](01_Features/Static_Site_Generation.md)
|
||||
* [Table of Contents](01_Features/Table_of_contents.md)
|
||||
- [Auto Generated Navigation / Page sorting](01_Features/Navigation_and_Sorting.md)
|
||||
- [Internal documentation links](01_Features/Internal_links.md)
|
||||
- [CommonMark compliant](01_Features/CommonMark_compliant.md)
|
||||
- [Auto created homepage/landing page](01_Features/Landing_page.md)
|
||||
- [Multiple Output Formats](01_Features/Multiple_Output_Formats.md)
|
||||
- [Multiple Languages Support](01_Features/Multilanguage.md)
|
||||
- [No Build Step](01_Features/Live_mode.md)
|
||||
- [Static Output Generation](01_Features/Static_Site_Generation.md)
|
||||
- [Table of Contents](01_Features/Table_of_contents.md)
|
||||
|
||||
### For Developers
|
||||
|
||||
* [Auto Syntax Highlighting](01_Features/Auto_Syntax_Highlight.md)
|
||||
* [Extend Daux.io with Processors](01_For_Developers/Creating_a_Processor.md)
|
||||
* Full access to the internal API to create new pages programatically
|
||||
* Work with pages metadata
|
||||
- [Auto Syntax Highlighting](01_Features/Auto_Syntax_Highlight.md)
|
||||
- [Extend Daux.io with Processors](01_For_Developers/Creating_a_Processor.md)
|
||||
- Full access to the internal API to create new pages programatically
|
||||
- Work with pages metadata
|
||||
|
||||
### For Marketing
|
||||
|
||||
* 100% Mobile Responsive
|
||||
* 4 Built-In Themes or roll your own
|
||||
* Functional, Flat Design Style
|
||||
* Optional code float layout
|
||||
* Shareable/Linkable SEO Friendly URLs
|
||||
* Supports Google Analytics and Piwik Analytics
|
||||
- 100% Mobile Responsive
|
||||
- 4 Built-In Themes or roll your own
|
||||
- Functional, Flat Design Style
|
||||
- Optional code float layout
|
||||
- Shareable/Linkable SEO Friendly URLs
|
||||
- Supports Google Analytics and Piwik Analytics
|
||||
|
||||
## Demos
|
||||
|
||||
This is a list of sites using Daux.io:
|
||||
|
||||
- With a custom theme:
|
||||
* [Crafty](https://swissquote.github.io/crafty)
|
||||
* [Pixolution flow](https://docs.pixolution.org)
|
||||
* [Soisy](https://doc.soisy.it/)
|
||||
* [Vulkan Tutorial](https://vulkan-tutorial.com)
|
||||
* [3Q](https://docs.3q.video/)
|
||||
- With the default Theme
|
||||
* [Daux.io](https://daux.io/)
|
||||
* [DoctrineWatcher](https://dsentker.github.io/WatcherDocumentation/)
|
||||
* [DrupalGap](http://docs.drupalgap.org/8/)
|
||||
* [ICADMIN: An admin panel powered by CodeIgniter.](http://istocode.com/shared/ic-admin/)
|
||||
* [Munee: Standalone PHP 5.3 Asset Optimisation & Manipulation](http://mun.ee)
|
||||
* [Nuntius: A PHP framework for bots](https://roysegall.github.io/nuntius-bot/)
|
||||
- With a custom theme:
|
||||
- [Crafty](https://swissquote.github.io/crafty)
|
||||
- [Pixolution flow](https://docs.pixolution.org) \* [Soisy](https://doc.soisy.it/)
|
||||
- [Vulkan Tutorial](https://vulkan-tutorial.com)
|
||||
- [3Q](https://docs.3q.video/)
|
||||
- With the default Theme
|
||||
- [Daux.io](https://daux.io/)
|
||||
_ [DoctrineWatcher](https://dsentker.github.io/WatcherDocumentation/)
|
||||
_ [DrupalGap](http://docs.drupalgap.org/8/)
|
||||
- [ICADMIN: An admin panel powered by CodeIgniter.](http://istocode.com/shared/ic-admin/)
|
||||
- [Munee: Standalone PHP 5.3 Asset Optimisation & Manipulation](http://mun.ee)
|
||||
- [Nuntius: A PHP framework for bots](https://roysegall.github.io/nuntius-bot/)
|
||||
|
||||
Do you use Daux.io? Send us a pull request or open an [issue](https://github.com/dauxio/daux.io/issues) and I will add you to the list.
|
||||
|
||||
|
|
@ -81,10 +80,10 @@ docker run --rm -it -w /build -v "$PWD":/build daux/daux.io daux
|
|||
|
||||
Any parameter valid in the PHP version is valid in the Docker version
|
||||
|
||||
|
||||
### Writing pages
|
||||
|
||||
Creating new pages is very easy:
|
||||
|
||||
1. Create a markdown file (`*.md` or `*.markdown`)
|
||||
2. Start writing
|
||||
|
||||
|
|
@ -98,14 +97,14 @@ You must use underscores instead of spaces. Here are some example file names and
|
|||
|
||||
**Good:**
|
||||
|
||||
* 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
|
||||
- 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
|
||||
|
||||
**Bad:**
|
||||
|
||||
* File Name With Space.md = FAIL
|
||||
- File Name With Space.md = FAIL
|
||||
|
||||
### See your pages
|
||||
|
||||
|
|
@ -129,9 +128,9 @@ Upload your files to an apache / nginx server and see your documentation
|
|||
|
||||
Daux.io is extendable and comes by default with three export formats:
|
||||
|
||||
- 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.
|
||||
- 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.
|
||||
|
||||
[See a detailed feature comparison matrix](01_Features/Multiple_Output_Formats.md)
|
||||
|
||||
|
|
@ -145,7 +144,7 @@ Now that you got the basics, you can also [see what you can configure](05_Config
|
|||
|
||||
## PHP Requirements
|
||||
|
||||
Daux.io is compatible with the [officially supported](https://www.php.net/supported-versions.php) PHP versions; 7.2.0 and up.
|
||||
Daux.io is compatible with the [officially supported](https://www.php.net/supported-versions.php) PHP versions; 7.2.0 and up.
|
||||
|
||||
### Extensions
|
||||
|
||||
|
|
@ -153,7 +152,6 @@ Daux.io needs the following PHP extensions to work : `php-mbstring` and `php-xml
|
|||
|
||||
If you encounter an error similar to `utf8_decode() not found` this means that you're missing the `php-xml` package.
|
||||
|
||||
|
||||
## Support
|
||||
|
||||
If you need help using Daux.io, or have found a bug, please create an issue on the <a href="https://github.com/dauxio/daux.io/issues" target="_blank">GitHub repo</a>.
|
||||
|
|
|
|||
|
|
@ -1,17 +1,14 @@
|
|||
|
||||
As we support CommonMark, a broad range of markdown features is available to you.
|
||||
|
||||
Many of the features shown below were known as Github Flavored Markdown.
|
||||
|
||||
|
||||
We all like making lists
|
||||
------------------------
|
||||
## We all like making lists
|
||||
|
||||
The above header should be an H2 tag. Now, for a list of fruits:
|
||||
|
||||
* Red Apples
|
||||
* Purple Grapes
|
||||
* Green Kiwifruits
|
||||
- Red Apples
|
||||
- Purple Grapes
|
||||
- Green Kiwifruits
|
||||
|
||||
Let's get crazy:
|
||||
|
||||
|
|
@ -27,18 +24,17 @@ Let's get crazy:
|
|||
|
||||
What about some code **in** a list? That's insane, right?
|
||||
|
||||
1. In Ruby you can map like this:
|
||||
1. In Ruby you can map like this:
|
||||
|
||||
['a', 'b'].map { |x| x.uppercase }
|
||||
|
||||
2. In Rails, you can do a shortcut:
|
||||
2. In Rails, you can do a shortcut:
|
||||
|
||||
['a', 'b'].map(&:uppercase)
|
||||
|
||||
Some people seem to like definition lists
|
||||
|
||||
I am a robot
|
||||
------------
|
||||
## I am a robot
|
||||
|
||||
Maybe you want to print `robot` to the console 1000 times. Why not?
|
||||
|
||||
|
|
@ -54,8 +50,7 @@ How about we throw some angle braces and ampersands in there?
|
|||
© 2004 Foo Corporation
|
||||
</div>
|
||||
|
||||
Set in stone
|
||||
------------
|
||||
## Set in stone
|
||||
|
||||
Preformatted blocks are useful for ASCII art:
|
||||
|
||||
|
|
@ -73,8 +68,7 @@ Preformatted blocks are useful for ASCII art:
|
|||
___|_____________
|
||||
</pre>
|
||||
|
||||
Playing the blame game
|
||||
----------------------
|
||||
## Playing the blame game
|
||||
|
||||
If you need to blame someone, the best way to do so is by quoting them:
|
||||
|
||||
|
|
@ -92,26 +86,23 @@ Or perhaps someone a little less eloquent:
|
|||
> just put me under the spot here, and maybe I'm not as quick on my feet
|
||||
> as I should be in coming up with one.
|
||||
|
||||
Table for two
|
||||
-------------
|
||||
## Table for two
|
||||
|
||||
ID | Name | Rank
|
||||
---|:------:|------:
|
||||
1 | Tom Preston-Werner | Awesome
|
||||
2 | Albert Einstein | Nearly as awesome
|
||||
| ID | Name | Rank |
|
||||
| --- | :----------------: | ----------------: |
|
||||
| 1 | Tom Preston-Werner | Awesome |
|
||||
| 2 | Albert Einstein | Nearly as awesome |
|
||||
|
||||
Crazy linking action
|
||||
--------------------
|
||||
## Crazy linking action
|
||||
|
||||
I get 10 times more traffic from [Google] [1] than from
|
||||
[Yahoo] [2] or [MSN] [3].
|
||||
I get 10 times more traffic from [Google][1] than from
|
||||
[Yahoo][2] or [MSN][3].
|
||||
|
||||
[1]: http://google.com/ "Google"
|
||||
[2]: http://search.yahoo.com/ "Yahoo Search"
|
||||
[3]: http://search.msn.com/ "MSN Search"
|
||||
[1]: http://google.com/ "Google"
|
||||
[2]: http://search.yahoo.com/ "Yahoo Search"
|
||||
[3]: http://search.msn.com/ "MSN Search"
|
||||
|
||||
Images
|
||||
------
|
||||
## Images
|
||||
|
||||
Here's an image.
|
||||
|
||||
|
|
@ -119,4 +110,4 @@ Here's an image.
|
|||
|
||||
Note: to use images on a landing page (index.md), prefix the image URL with the name of the directory it appears in, omitting the numerical prefix used to order the sections. For example in this section, to display this image on the landing page (index.md), the URL for the image would be "Features/sampleimage.png" to display the same image.
|
||||
|
||||
*View the [source of this content](https://github.com/dauxio/daux.io/blob/master/docs/01_Features/CommonMark_compliant.md).*
|
||||
_View the [source of this content](https://github.com/dauxio/daux.io/blob/master/docs/01_Features/CommonMark_compliant.md)._
|
||||
|
|
|
|||
|
|
@ -1,4 +1,3 @@
|
|||
|
||||
As you can see on the top of this page, you can add "Edit on Github" links to your pages, this feature can be enabled with a single parameter.
|
||||
|
||||
The value has to be the path to the root of your documentation folder in your repository.
|
||||
|
|
@ -7,12 +6,11 @@ In the value you see below, Daux's documentation is in the `docs` folder in the
|
|||
|
||||
Daux.io will handle the rest
|
||||
|
||||
|
||||
```json
|
||||
{
|
||||
"html": {
|
||||
"edit_on_github": "dauxio/daux.io/blob/master/docs"
|
||||
}
|
||||
"html": {
|
||||
"edit_on_github": "dauxio/daux.io/blob/master/docs"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -22,14 +20,13 @@ While GitHub is the most popular, it isn't the only, collaborative VCS out there
|
|||
|
||||
As long as you can refer your files by a URL, you can create an edit link for your VCS with the following configuration:
|
||||
|
||||
|
||||
```json
|
||||
{
|
||||
"html": {
|
||||
"edit_on": {
|
||||
"name": "Bitbucket",
|
||||
"basepath": "https://bitbucket.org/dauxio/daux.io/src/master/docs"
|
||||
"html": {
|
||||
"edit_on": {
|
||||
"name": "Bitbucket",
|
||||
"basepath": "https://bitbucket.org/dauxio/daux.io/src/master/docs"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -2,9 +2,9 @@ If you want to create a beautiful landing page for your project, create a `_inde
|
|||
|
||||
```json
|
||||
{
|
||||
"title": "Daux.io",
|
||||
"tagline": "The Easiest Way To Document Your Project",
|
||||
"image": "app.png"
|
||||
"title": "Daux.io",
|
||||
"tagline": "The Easiest Way To Document Your Project",
|
||||
"image": "app.png"
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -14,8 +14,8 @@ To disable the automatic landing page, you can set `auto_landing` to false in th
|
|||
|
||||
```json
|
||||
{
|
||||
"html": {
|
||||
"auto_landing": false
|
||||
}
|
||||
"html": {
|
||||
"auto_landing": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -10,7 +10,6 @@ The easiest is to use PHP's built-in server.
|
|||
|
||||
For that i've included a short command, run `daux serve` 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>
|
||||
|
||||
|
||||
## Running Remotely
|
||||
|
||||
### Clean URLs configuration
|
||||
|
|
@ -20,9 +19,9 @@ To enable the same, set the toggle in the `config.json` file in the `/docs` fold
|
|||
|
||||
```json
|
||||
{
|
||||
"live": {
|
||||
"clean_urls": true
|
||||
}
|
||||
"live": {
|
||||
"clean_urls": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -70,8 +69,8 @@ server {
|
|||
|
||||
If you have set up a local or remote IIS web site, you may need a `web.config` with:
|
||||
|
||||
* A rewrite configuration, for handling clean urls.
|
||||
* A mime type handler for less files, if using a custom theme.
|
||||
- A rewrite configuration, for handling clean urls.
|
||||
- A mime type handler for less files, if using a custom theme.
|
||||
|
||||
### Clean URLs
|
||||
|
||||
|
|
@ -79,20 +78,32 @@ The `web.config` needs an entry for `<rewrite>` under `<system.webServer>`:
|
|||
|
||||
```xml
|
||||
<configuration>
|
||||
<system.webServer>
|
||||
<rewrite>
|
||||
<rules>
|
||||
<rule name="Main Rule" stopProcessing="true">
|
||||
<match url=".*" />
|
||||
<conditions logicalGrouping="MatchAll">
|
||||
<add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
|
||||
<add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
|
||||
</conditions>
|
||||
<action type="Rewrite" url="index.php" appendQueryString="false" />
|
||||
</rule>
|
||||
</rules>
|
||||
</rewrite>
|
||||
</system.webServer>
|
||||
<system.webServer>
|
||||
<rewrite>
|
||||
<rules>
|
||||
<rule name="Main Rule" stopProcessing="true">
|
||||
<match url=".*" />
|
||||
<conditions logicalGrouping="MatchAll">
|
||||
<add
|
||||
input="{REQUEST_FILENAME}"
|
||||
matchType="IsFile"
|
||||
negate="true"
|
||||
/>
|
||||
<add
|
||||
input="{REQUEST_FILENAME}"
|
||||
matchType="IsDirectory"
|
||||
negate="true"
|
||||
/>
|
||||
</conditions>
|
||||
<action
|
||||
type="Rewrite"
|
||||
url="index.php"
|
||||
appendQueryString="false"
|
||||
/>
|
||||
</rule>
|
||||
</rules>
|
||||
</rewrite>
|
||||
</system.webServer>
|
||||
</configuration>
|
||||
```
|
||||
|
||||
|
|
@ -114,4 +125,4 @@ ENTRYPOINT [ "php", "-S", "0.0.0.0:80", "index.php" ]
|
|||
|
||||
When you add this to a `Dockerfile` and run `docker build --name my-daux-doc .` and then `docker --rm run -p 8000:80 my-daux-doc`
|
||||
|
||||
You can access your documentation at `localhost:8000`
|
||||
You can access your documentation at `localhost:8000`
|
||||
|
|
|
|||
|
|
@ -4,11 +4,12 @@ Add this to your config.json :
|
|||
|
||||
```json
|
||||
{
|
||||
"languages": { "en": "English", "de": "German" }
|
||||
"languages": { "en": "English", "de": "German" }
|
||||
}
|
||||
```
|
||||
|
||||
You will the need separate directories for each language in `docs/` folder.
|
||||
|
||||
```
|
||||
├── docs/
|
||||
│ ├── _index.md
|
||||
|
|
|
|||
|
|
@ -1,21 +1,21 @@
|
|||
Daux.io is extendable and comes by default with three export formats:
|
||||
|
||||
- Export to HTML
|
||||
- Export all documentation in a single HTML page
|
||||
- Upload to your Atlassian Confluence server
|
||||
- Export to HTML
|
||||
- Export all documentation in a single HTML page
|
||||
- Upload to your Atlassian Confluence server
|
||||
|
||||
## Feature Matrix
|
||||
|
||||
Feature | HTML | Single Page HTML | Confluence
|
||||
--------------:|:----:|:----------------:|:----------:
|
||||
Multilanguage | √ | X (Planned) | X
|
||||
Landing Pages | √ | X | X
|
||||
Index Pages | √ | √ | √
|
||||
Internal Links | √ | X (Planned) | √
|
||||
Code Highlight | √ | X (Planned) | √ (Using macros)
|
||||
Live Mode | √ | X | X
|
||||
Pages Ordering | √ | √ | X (API Limitation)
|
||||
Google / Piwik analytics | √ | √ | √ (Configured on Conflence)
|
||||
| Feature | HTML | Single Page HTML | Confluence |
|
||||
| -----------------------: | :--: | :--------------: | :-------------------------: |
|
||||
| Multilanguage | √ | X (Planned) | X |
|
||||
| Landing Pages | √ | X | X |
|
||||
| Index Pages | √ | √ | √ |
|
||||
| Internal Links | √ | X (Planned) | √ |
|
||||
| Code Highlight | √ | X (Planned) | √ (Using macros) |
|
||||
| Live Mode | √ | X | X |
|
||||
| Pages Ordering | √ | √ | X (API Limitation) |
|
||||
| Google / Piwik analytics | √ | √ | √ (Configured on Conflence) |
|
||||
|
||||
## Confluence Example
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,3 @@
|
|||
|
||||
## Navigation
|
||||
|
||||
The navigation is generated automatically with all pages that end with `.md` or `.markdown`
|
||||
|
|
@ -12,21 +11,21 @@ For example, `/docs/02_Examples` has a landing page for that section since there
|
|||
## Sorting
|
||||
|
||||
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.
|
||||
This will list _Hello World_ before _Features_, overriding the default alpha-numeric sorting.
|
||||
The numbers will be stripped out of the navigation and urls. For the file `6 Ways to Get Rich`, you can use `/docs/_6_Ways_to_Get_Rich.md`
|
||||
|
||||
You might also wish to stick certain links to the bottom of a page.
|
||||
You can do so by prefixing the file name with a '-', e.g. a new file `/docs/-Contact_Us.md` will always appear at the bottom of the current list.
|
||||
You can do so by prefixing the file name with a '-', e.g. a new file `/docs/-Contact_Us.md` will always appear at the bottom of the current list.
|
||||
Weights can also be added to further sort the bottom entries. e.g. `/docs/-01_Coming.md` will appear before `/docs/-02_Soon.md` but both will only appear after all positive or non-weighted files.
|
||||
|
||||
It works the same for files prefixed with `+`.
|
||||
|
||||
Page order priorities are like this:
|
||||
|
||||
- `+` in front of the filename and numbers in front
|
||||
- `+` in front of the filename
|
||||
- The index page
|
||||
- Numbers in the front
|
||||
- Pages without prefix
|
||||
- `-` in front of the filename and numbers in front
|
||||
- `-` in front of the filename
|
||||
- `+` in front of the filename and numbers in front
|
||||
- `+` in front of the filename
|
||||
- The index page
|
||||
- Numbers in the front
|
||||
- Pages without prefix
|
||||
- `-` in front of the filename and numbers in front
|
||||
- `-` in front of the filename
|
||||
|
|
|
|||
|
|
@ -6,8 +6,8 @@ To enable the generated search, you can set `search` to true in the `html` secti
|
|||
|
||||
```json
|
||||
{
|
||||
"html": {
|
||||
"search": true
|
||||
}
|
||||
"html": {
|
||||
"search": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,9 +1,8 @@
|
|||
If you don't want to serve the live version of your site, you can also generate files, these can be one of the three supported formats :
|
||||
|
||||
If you don't want to serve the live version of your site, you can also generate files, these can be one of the three supported formats :
|
||||
|
||||
- HTML output
|
||||
- Single page HTML output
|
||||
- Atlassian Confluence upload
|
||||
- HTML output
|
||||
- Single page HTML output
|
||||
- Atlassian Confluence upload
|
||||
|
||||
Generating a complete set of pages, with navigation
|
||||
|
||||
|
|
@ -13,7 +12,7 @@ daux --destination=[Output Directory Relative Direction]
|
|||
|
||||
## Options
|
||||
|
||||
For more options, run
|
||||
For more options, run
|
||||
|
||||
```bash
|
||||
daux generate --help
|
||||
|
|
@ -32,7 +31,7 @@ daux --format=html
|
|||
|
||||
### Specify a processor
|
||||
|
||||
A processor can be specified through the `--processor` option, this should be the name of a class inside the `Todaymade\Daux\Extension` namespace.
|
||||
A processor can be specified through the `--processor` option, this should be the name of a class inside the `Todaymade\Daux\Extension` namespace.
|
||||
|
||||
By running :
|
||||
|
||||
|
|
|
|||
|
|
@ -18,10 +18,8 @@ You can enable this feature in your configuration
|
|||
|
||||
```json
|
||||
{
|
||||
"html": {
|
||||
"auto_toc": true
|
||||
}
|
||||
"html": {
|
||||
"auto_toc": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load Diff
|
|
@ -1,2 +1,3 @@
|
|||
### This is a landing page for the Examples section
|
||||
Adding a landing page is pretty simple, all you need to do is add an "index.md" file to the related folder.
|
||||
|
||||
Adding a landing page is pretty simple, all you need to do is add an "index.md" file to the related folder.
|
||||
|
|
|
|||
|
|
@ -1,21 +1,23 @@
|
|||
__Table of contents__
|
||||
**Table of contents**
|
||||
|
||||
[TOC]
|
||||
|
||||
## Configuring the connection
|
||||
|
||||
The connection requires three parameters `base_url`, `user` and `pass`. While `user` and `pass` don't really need an explanation, for `base_url` you need to set the path to the server without `rest/api`, this will be added automatically.
|
||||
|
||||
```json
|
||||
{
|
||||
"confluence": {
|
||||
"base_url": "http://my_confluence_server.com/",
|
||||
"user" : "my_username",
|
||||
"pass" : "my_password"
|
||||
}
|
||||
"confluence": {
|
||||
"base_url": "http://my_confluence_server.com/",
|
||||
"user": "my_username",
|
||||
"pass": "my_password"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Where to upload
|
||||
|
||||
Now that the connection is defined, you need to tell it where you want your documentation to be uploaded.
|
||||
|
||||
For that you need a `space_id` (name that appears at the beginning of the urls) and an `ancestor_id`; the id of the page that will be the parent of the documentation's homepage.
|
||||
|
|
@ -24,10 +26,10 @@ You can obtain the `ancestor_id` id by editing the page you want to define as a
|
|||
|
||||
```json
|
||||
{
|
||||
"confluence": {
|
||||
"space_id": "my_space",
|
||||
"ancestor_id": 50370632
|
||||
}
|
||||
"confluence": {
|
||||
"space_id": "my_space",
|
||||
"ancestor_id": 50370632
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -36,20 +38,22 @@ You can also provide a `root_id` instead of an `ancestor_id` in this case, you s
|
|||
You can use that when you're uploading your documentation to the root of a Confluence Space or if your page already exists.
|
||||
|
||||
## Prefix
|
||||
|
||||
Because confluence can't have two pages with the same name in a space, I recommend you define a prefix for your pages.
|
||||
|
||||
```json
|
||||
{
|
||||
"confluence": { "prefix": "DAUX -" }
|
||||
"confluence": { "prefix": "DAUX -" }
|
||||
}
|
||||
```
|
||||
|
||||
## Update threshold
|
||||
|
||||
To make the upload quicker, we try to determine if a page changed or not, first with a strict comparison and if it's not completely identical, we compute the difference.
|
||||
|
||||
```json
|
||||
{
|
||||
"confluence": { "update_threshold": 1 }
|
||||
"confluence": { "update_threshold": 1 }
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -59,22 +63,22 @@ By default the threshold is 2%.
|
|||
|
||||
Setting the value to `0` disables the feature altogether.
|
||||
|
||||
|
||||
## Delete old pages
|
||||
|
||||
When a page is renamed, there is no way to tell it was renamed, so when uploading to Confluence, the page will be uploaded and the old page will stay here.
|
||||
|
||||
By default, it will inform you that some pages aren't needed anymore and you can delete them by hand.
|
||||
|
||||
```json
|
||||
{
|
||||
"confluence": { "delete": true }
|
||||
"confluence": { "delete": true }
|
||||
}
|
||||
```
|
||||
|
||||
By setting `delete` to `true` (or running `daux` with the `--delete` flag) you tell the generator that it can safely delete the pages.
|
||||
|
||||
|
||||
## Information message
|
||||
|
||||
When you create your page. there is no indication that the upload process will override the content of the pages.
|
||||
|
||||
It happens sometimes that users edit the pages to add / fix an information.
|
||||
|
|
@ -83,9 +87,9 @@ You can add a text in a "information" macro on top of the document by setting th
|
|||
|
||||
```json
|
||||
{
|
||||
"confluence": {
|
||||
"header": "These pages are updated automatically, your changes will be overriden."
|
||||
}
|
||||
"confluence": {
|
||||
"header": "These pages are updated automatically, your changes will be overriden."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -1,24 +1,26 @@
|
|||
__Table of contents__
|
||||
**Table of contents**
|
||||
|
||||
[TOC]
|
||||
|
||||
## Analytics
|
||||
|
||||
### Google Analytics
|
||||
|
||||
This will embed the google analytics tracking code.
|
||||
|
||||
```json
|
||||
{
|
||||
"html": { "google_analytics": "UA-XXXXXXXXX-XX" }
|
||||
"html": { "google_analytics": "UA-XXXXXXXXX-XX" }
|
||||
}
|
||||
```
|
||||
|
||||
### Piwik Analytics
|
||||
|
||||
This will embed the piwik tracking code.
|
||||
|
||||
```json
|
||||
{
|
||||
"html": { "piwik_analytics": "my-url-for-piwik.com" }
|
||||
"html": { "piwik_analytics": "my-url-for-piwik.com" }
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -26,119 +28,130 @@ You can Also give a specific Piwik ID as well.
|
|||
|
||||
```json
|
||||
{
|
||||
"html": { "piwik_analytics_id": "43" }
|
||||
"html": { "piwik_analytics_id": "43" }
|
||||
}
|
||||
```
|
||||
|
||||
### Plausible Analytics
|
||||
|
||||
This will embed the https://plausible.io/ tracking code.
|
||||
|
||||
```json
|
||||
{
|
||||
"html": { "plausible_domain": "daux.io" }
|
||||
"html": { "plausible_domain": "daux.io" }
|
||||
}
|
||||
```
|
||||
|
||||
## Automatic Table of Contents
|
||||
|
||||
You can add a table of contents on each page automatically, read about it [here](../01_Features/Table_of_contents.md)
|
||||
|
||||
|
||||
## Buttons
|
||||
|
||||
You can add buttons to the landing page.
|
||||
|
||||
```json
|
||||
{
|
||||
"html": {
|
||||
"buttons": {
|
||||
"My Website": "http://example.com"
|
||||
"html": {
|
||||
"buttons": {
|
||||
"My Website": "http://example.com"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Breadcrumb titles
|
||||
Daux.io provides the option to present page titles as breadcrumb navigation.
|
||||
You can *optionally* specify the separator used for breadcrumbs.
|
||||
|
||||
Daux.io provides the option to present page titles as breadcrumb navigation.
|
||||
You can _optionally_ specify the separator used for breadcrumbs.
|
||||
|
||||
```json
|
||||
{
|
||||
"html": {
|
||||
"breadcrumbs": true,
|
||||
"breadcrumb_separator" : " > "
|
||||
}
|
||||
"html": {
|
||||
"breadcrumbs": true,
|
||||
"breadcrumb_separator": " > "
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Date Modified
|
||||
By default, daux.io will display the last modified time as reported by the system underneath the title for each document.
|
||||
|
||||
By default, daux.io will display the last modified time as reported by the system underneath the title for each document.
|
||||
To disable this, change the option in your config.json to `false`.
|
||||
|
||||
```json
|
||||
{
|
||||
"html": { "date_modified": false }
|
||||
"html": { "date_modified": false }
|
||||
}
|
||||
```
|
||||
|
||||
## GitHub Repo
|
||||
|
||||
Add a 'Fork me on GitHub' ribbon.
|
||||
|
||||
```json
|
||||
{
|
||||
"html": { "repo": "dauxio/daux.io" }
|
||||
"html": { "repo": "dauxio/daux.io" }
|
||||
}
|
||||
```
|
||||
|
||||
## Inherit Index
|
||||
|
||||
This feature will instructs the navigation generator to seek the first available file to use when there is no index in a folder.
|
||||
|
||||
```json
|
||||
{
|
||||
"html": { "inherit_index": true }
|
||||
"html": { "inherit_index": true }
|
||||
}
|
||||
```
|
||||
|
||||
## Jump buttons
|
||||
|
||||
You can have previous/next buttons on each page.
|
||||
They can be disabled by setting `jump_buttons` to `false`.
|
||||
|
||||
```json
|
||||
{
|
||||
"html": { "jump_buttons": false }
|
||||
"html": { "jump_buttons": false }
|
||||
}
|
||||
```
|
||||
|
||||
## Landing page
|
||||
The automatic landing page can be disabled through the `auto_landing` option, read about it [here](../01_Features/Landing_page.md)
|
||||
|
||||
The automatic landing page can be disabled through the `auto_landing` option, read about it [here](../01_Features/Landing_page.md)
|
||||
|
||||
## Links
|
||||
|
||||
Include custom links in the sidebar.
|
||||
|
||||
```json
|
||||
{
|
||||
"html": {
|
||||
"links": {
|
||||
"GitHub Repo": "https://github.com/dauxio/daux.io",
|
||||
"Help/Support/Bugs": "https://github.com/dauxio/daux.io/issues",
|
||||
"Made by Todaymade": "http://todaymade.com"
|
||||
"html": {
|
||||
"links": {
|
||||
"GitHub Repo": "https://github.com/dauxio/daux.io",
|
||||
"Help/Support/Bugs": "https://github.com/dauxio/daux.io/issues",
|
||||
"Made by Todaymade": "http://todaymade.com"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Search
|
||||
|
||||
Daux has an embedded search engine read all about it [here](../01_Features/Search.md)
|
||||
|
||||
## Themes
|
||||
|
||||
We have 4 built-in Bootstrap themes. To use one of the themes, just set the `theme` option to one of the following:
|
||||
|
||||
* daux-blue
|
||||
* daux-green
|
||||
* daux-navy
|
||||
* daux-red
|
||||
- daux-blue
|
||||
- daux-green
|
||||
- daux-navy
|
||||
- daux-red
|
||||
|
||||
```json
|
||||
{
|
||||
"html": { "theme": "daux-blue" }
|
||||
"html": { "theme": "daux-blue" }
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -146,25 +159,27 @@ To use a custom theme, just copy over the theme folder into the `themes` directo
|
|||
|
||||
```json
|
||||
{
|
||||
"html": { "theme": "new-theme" }
|
||||
"html": { "theme": "new-theme" }
|
||||
}
|
||||
```
|
||||
|
||||
## Toggling Code Blocks
|
||||
Some users might wish to hide the code blocks & view just the documentation.
|
||||
|
||||
Some users might wish to hide the code blocks & view just the documentation.
|
||||
By setting the `toggle_code` property to `true`, you can offer a toggle button on the page.
|
||||
|
||||
```json
|
||||
{
|
||||
"html": { "toggle_code": true }
|
||||
"html": { "toggle_code": true }
|
||||
}
|
||||
```
|
||||
|
||||
## Twitter
|
||||
|
||||
Include twitter follow buttons in the sidebar.
|
||||
|
||||
```json
|
||||
{
|
||||
"html": { "twitter": ["justin_walsh", "todaymade"] }
|
||||
"html": { "twitter": ["justin_walsh", "todaymade"] }
|
||||
}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,91 +1,100 @@
|
|||
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 JSON object that you can use to change some of the basic settings of the documentation.
|
||||
|
||||
__Table of contents__
|
||||
**Table of contents**
|
||||
|
||||
[TOC]
|
||||
|
||||
### Title
|
||||
|
||||
Change the title bar in the docs
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "Daux.io"
|
||||
"title": "Daux.io"
|
||||
}
|
||||
```
|
||||
|
||||
### Tagline
|
||||
|
||||
Change the tagline bar in the docs
|
||||
|
||||
```json
|
||||
{
|
||||
"tagline": "The Easiest Way To Document Your Project"
|
||||
"tagline": "The Easiest Way To Document Your Project"
|
||||
}
|
||||
```
|
||||
|
||||
### Author
|
||||
|
||||
Change the documentation's author
|
||||
|
||||
```json
|
||||
{
|
||||
"author": "Stéphane Goetz"
|
||||
"author": "Stéphane Goetz"
|
||||
}
|
||||
```
|
||||
|
||||
### Image
|
||||
|
||||
An image to show on the landing page. A relative path from the documentation root.
|
||||
|
||||
```json
|
||||
{
|
||||
"image": "image.png"
|
||||
"image": "image.png"
|
||||
}
|
||||
```
|
||||
|
||||
### Format
|
||||
|
||||
Change the output format. It is recommended you set only formats that support the live mode as this will also
|
||||
be read by the integrated web server. And you set the other formats (like confluence) only by command line
|
||||
|
||||
```json
|
||||
{
|
||||
"format": "html"
|
||||
"format": "html"
|
||||
}
|
||||
```
|
||||
|
||||
- __html__ with [its options](./Html_export.md)
|
||||
- __confluence__ with [its options](./Confluence_upload.md)
|
||||
- **html** with [its options](./Html_export.md)
|
||||
- **confluence** with [its options](./Confluence_upload.md)
|
||||
|
||||
Available formats are __HTML__ and __Confluence__
|
||||
Available formats are **HTML** and **Confluence**
|
||||
|
||||
### 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.
|
||||
|
||||
```json
|
||||
{
|
||||
"ignore": {
|
||||
"files": ["Work_In_Progress.md"],
|
||||
"folders": ["99_Not_Ready"]
|
||||
}
|
||||
"ignore": {
|
||||
"files": ["Work_In_Progress.md"],
|
||||
"folders": ["99_Not_Ready"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Timezone
|
||||
|
||||
If your server does not have a default timezone set in php.ini, it may return errors when it tries to generate the last modified date/time for docs. To fix these errors, specify a timezone in your config file. Valid options are available in the [PHP Manual](http://php.net/manual/en/timezones.php).
|
||||
|
||||
```json
|
||||
{
|
||||
"timezone": "America/Los_Angeles"
|
||||
"timezone": "America/Los_Angeles"
|
||||
}
|
||||
```
|
||||
|
||||
### Multi-language
|
||||
|
||||
Enables multi-language support which needs separate directories for each language in `docs/` folder.
|
||||
|
||||
```json
|
||||
{
|
||||
"languages": {"en": "English", "de": "German"}
|
||||
"languages": { "en": "English", "de": "German" }
|
||||
}
|
||||
```
|
||||
|
||||
Directory structure:
|
||||
|
||||
```
|
||||
├── docs/
|
||||
│ ├── _index.md
|
||||
|
|
@ -113,7 +122,7 @@ You can change the default language with the `language` option.
|
|||
|
||||
```json
|
||||
{
|
||||
"language": "fr"
|
||||
"language": "fr"
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -124,27 +133,28 @@ A string that isn't found will fall back to english.
|
|||
|
||||
```json
|
||||
{
|
||||
"strings": {
|
||||
"fr": {
|
||||
"CodeBlocks_show": "Afficher le code",
|
||||
"Search_placeholder": "Rechercher...",
|
||||
"Link_previous": "Précédent",
|
||||
"Link_next": "Suivant",
|
||||
"Edit_on": "Editer sur :name:",
|
||||
"View_on_github": "Voir sur GitHub",
|
||||
"View_documentation": "Voir la Documentation"
|
||||
"strings": {
|
||||
"fr": {
|
||||
"CodeBlocks_show": "Afficher le code",
|
||||
"Search_placeholder": "Rechercher...",
|
||||
"Link_previous": "Précédent",
|
||||
"Link_next": "Suivant",
|
||||
"Edit_on": "Editer sur :name:",
|
||||
"View_on_github": "Voir sur GitHub",
|
||||
"View_documentation": "Voir la Documentation"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Processor
|
||||
|
||||
You can set the processor in the documentation or as an option to the command line. If you need it when running the server, you should add it to the configuration.
|
||||
|
||||
More information on how to create a Processor can be found [here](!For_Developers/Creating_a_Processor).
|
||||
|
||||
|
||||
```json
|
||||
{
|
||||
"processor": "MyProcessor"
|
||||
"processor": "MyProcessor"
|
||||
}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ The main advantage, is that you can run it with the source or with `daux` indepe
|
|||
Next to your `docs` directory, you can create a `daux` directory that can contain your Processor.
|
||||
|
||||
The classes must respect the PSR-4 Naming convention. And have `\Todaymade\Daux\Extension` as a base namespace.
|
||||
|
||||
|
||||
By default, we created a `daux/Processor.php` file to get you started.
|
||||
|
||||
## A quick test ?
|
||||
|
|
@ -40,7 +40,7 @@ There are a few methods that you can override to add some
|
|||
|
||||
By default, Daux.io parses your directory to find pages. but, for a reason or another, you might want to programmatically add some pages.
|
||||
|
||||
This can be done with:
|
||||
This can be done with:
|
||||
|
||||
```php
|
||||
public function manipulateTree(Root $root)
|
||||
|
|
@ -65,7 +65,7 @@ Both methods `getOrCreateDir` and `getOrCreatePage` take two parameters : `paren
|
|||
The page will automatically be treated as markdown and converted like a normal page.
|
||||
|
||||
If you create a new ContentType, like let's say LaTeX, you would set the title `My Page.tex` it will keep the title `My Page` and use your renderer.
|
||||
|
||||
|
||||
If the extension is not mapped to a Generator, it will simply create the file as-is without manipulation.
|
||||
|
||||
### Extend the Markdown Generator
|
||||
|
|
@ -82,9 +82,9 @@ See the details on [CommonMark's website](http://commonmark.thephpleague.com/cus
|
|||
|
||||
### Add new generators
|
||||
|
||||
You can add new generators to Daux.io and use them right away, they must implement the
|
||||
`\Todaymade\Daux\Format\Base\Generator` interface and if you want to use the live mode with your generator
|
||||
you have to implement `\Todaymade\Daux\Format\Base\LiveGenerator`.
|
||||
You can add new generators to Daux.io and use them right away, they must implement the
|
||||
`\Todaymade\Daux\Format\Base\Generator` interface and if you want to use the live mode with your generator
|
||||
you have to implement `\Todaymade\Daux\Format\Base\LiveGenerator`.
|
||||
|
||||
```php
|
||||
public function addGenerators()
|
||||
|
|
@ -92,4 +92,3 @@ public function addGenerators()
|
|||
return ['custom_generator' => '\Todaymade\Daux\Extension\MyNewGenerator'];
|
||||
}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -8,43 +8,45 @@ Here is an example `config.json` file :
|
|||
|
||||
```json
|
||||
{
|
||||
"favicon": "<theme_url>img/favicon.png",
|
||||
"css": ["<theme_url>css/theme.min.css"],
|
||||
"js": [],
|
||||
"fonts": ["https://fonts.googleapis.com/css?family=Roboto+Slab:400,100,300,700&subset=latin,cyrillic-ext,cyrillic"],
|
||||
"variants": {
|
||||
"blue": {
|
||||
"favicon": "<theme_url>img/favicon-blue.png",
|
||||
"css": ["<theme_url>css/theme-blue.min.css"]
|
||||
},
|
||||
"green": {
|
||||
"favicon": "<theme_url>img/favicon-green.png",
|
||||
"css": ["<theme_url>css/theme-green.min.css"]
|
||||
"favicon": "<theme_url>img/favicon.png",
|
||||
"css": ["<theme_url>css/theme.min.css"],
|
||||
"js": [],
|
||||
"fonts": [
|
||||
"https://fonts.googleapis.com/css?family=Roboto+Slab:400,100,300,700&subset=latin,cyrillic-ext,cyrillic"
|
||||
],
|
||||
"variants": {
|
||||
"blue": {
|
||||
"favicon": "<theme_url>img/favicon-blue.png",
|
||||
"css": ["<theme_url>css/theme-blue.min.css"]
|
||||
},
|
||||
"green": {
|
||||
"favicon": "<theme_url>img/favicon-green.png",
|
||||
"css": ["<theme_url>css/theme-green.min.css"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
There are five options :
|
||||
|
||||
- __`favicon`__: The URL to your favicon
|
||||
- __`css`__: An array of CSS Stylesheets to add to the page
|
||||
- __`js`__: An array of JavaScript files to load
|
||||
- __`fonts`__: An array of Font sources, these are added as stylesheets
|
||||
- __`variants`__: An object containing sub-themes. Each sub theme, can provide the same configurations as the main theme (`favicon`, `css`, `js`, `fonts`)
|
||||
- **`favicon`**: The URL to your favicon
|
||||
- **`css`**: An array of CSS Stylesheets to add to the page
|
||||
- **`js`**: An array of JavaScript files to load
|
||||
- **`fonts`**: An array of Font sources, these are added as stylesheets
|
||||
- **`variants`**: An object containing sub-themes. Each sub theme, can provide the same configurations as the main theme (`favicon`, `css`, `js`, `fonts`)
|
||||
|
||||
|
||||
You will also notice this `<theme_url>` in the url.
|
||||
You will also notice this `<theme_url>` in the url.
|
||||
This is automatically substituted with the final url to the theme when generating the final page.
|
||||
|
||||
There are two possible substitutions :
|
||||
- __`<theme_url>`__: The url to the current theme
|
||||
- __`<base_url>`__: The url to the documentation root
|
||||
|
||||
|
||||
- **`<theme_url>`**: The url to the current theme
|
||||
- **`<base_url>`**: The url to the documentation root
|
||||
|
||||
## Theme variants
|
||||
|
||||
|
||||
Like the default Daux.io theme, you might want to provide variants of your theme.
|
||||
|
||||
|
||||
In the example before, there were two variants : blue and green.
|
||||
|
||||
The configuration of a variant is added to the configuration of the main theme, it doesn't replace it.
|
||||
|
|
@ -63,10 +65,10 @@ Change the `theme` option inside `html`
|
|||
|
||||
```json
|
||||
{
|
||||
"themes_directory": "/home/user/themes",
|
||||
"html": {
|
||||
"theme": "{theme}-{variant}"
|
||||
}
|
||||
"themes_directory": "/home/user/themes",
|
||||
"html": {
|
||||
"theme": "{theme}-{variant}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -85,11 +87,12 @@ You can create a folder named `templates` in your theme, copy-paste the original
|
|||
You can even do it one template at a time if you wish to do only small changes.
|
||||
|
||||
By default, we have the following templates :
|
||||
- `content.php`: The content page.
|
||||
- `home.php`: The landing page.
|
||||
- `error.php`: The page to show when a page is not found or some other error happened.
|
||||
- `partials/navbar_content.php`: The content of the top navigation bar.
|
||||
- `partials/google_analytics.php`: The script to load Google Analytics.
|
||||
- `partials/piwik_analytics.php`: The script to load Piwik Analytics.
|
||||
- `layout/00_layout.php`: The master template, containing the `<html>` tag.
|
||||
- `layout/05_page.php`: The page layout, with left navigation.
|
||||
|
||||
- `content.php`: The content page.
|
||||
- `home.php`: The landing page.
|
||||
- `error.php`: The page to show when a page is not found or some other error happened.
|
||||
- `partials/navbar_content.php`: The content of the top navigation bar.
|
||||
- `partials/google_analytics.php`: The script to load Google Analytics.
|
||||
- `partials/piwik_analytics.php`: The script to load Piwik Analytics.
|
||||
- `layout/00_layout.php`: The master template, containing the `<html>` tag.
|
||||
- `layout/05_page.php`: The page layout, with left navigation.
|
||||
|
|
|
|||
|
|
@ -13,37 +13,37 @@
|
|||
|
||||
#### For Authors
|
||||
|
||||
* [Auto Generated Navigation / Page sorting](01_Features/Navigation_and_Sorting.md)
|
||||
* [Internal documentation links](01_Features/Internal_links.md)
|
||||
* [CommonMark compliant](01_Features/CommonMark_compliant.md)
|
||||
* [Auto created homepage/landing page](01_Features/Landing_page.md)
|
||||
* [Multiple Output Formats](01_Features/Multiple_Output_Formats.md)
|
||||
* [Multiple Languages Support](01_Features/Multilanguage.md)
|
||||
* [No Build Step](01_Features/Live_mode.md)
|
||||
* [Static Output Generation](01_Features/Static_Site_Generation.md)
|
||||
* [Table of Contents](01_Features/Table_of_contents.md)
|
||||
- [Auto Generated Navigation / Page sorting](01_Features/Navigation_and_Sorting.md)
|
||||
- [Internal documentation links](01_Features/Internal_links.md)
|
||||
- [CommonMark compliant](01_Features/CommonMark_compliant.md)
|
||||
- [Auto created homepage/landing page](01_Features/Landing_page.md)
|
||||
- [Multiple Output Formats](01_Features/Multiple_Output_Formats.md)
|
||||
- [Multiple Languages Support](01_Features/Multilanguage.md)
|
||||
- [No Build Step](01_Features/Live_mode.md)
|
||||
- [Static Output Generation](01_Features/Static_Site_Generation.md)
|
||||
- [Table of Contents](01_Features/Table_of_contents.md)
|
||||
|
||||
</div>
|
||||
<div class="Row__third">
|
||||
|
||||
#### For Developers
|
||||
|
||||
* [Auto Syntax Highlighting](01_Features/Auto_Syntax_Highlight.md)
|
||||
* [Extend Daux.io with Processors](01_For_Developers/Creating_a_Processor.md)
|
||||
* Full access to the internal API to create new pages programatically
|
||||
* Work with pages metadata
|
||||
- [Auto Syntax Highlighting](01_Features/Auto_Syntax_Highlight.md)
|
||||
- [Extend Daux.io with Processors](01_For_Developers/Creating_a_Processor.md)
|
||||
- Full access to the internal API to create new pages programatically
|
||||
- Work with pages metadata
|
||||
|
||||
</div>
|
||||
<div class="Row__third">
|
||||
|
||||
#### For Marketing
|
||||
|
||||
* 100% Mobile Responsive
|
||||
* 4 Built-In Themes or roll your own
|
||||
* Functional, Flat Design Style
|
||||
* Optional code float layout
|
||||
* Shareable/Linkable SEO Friendly URLs
|
||||
* Supports Google Analytics and Piwik Analytics
|
||||
- 100% Mobile Responsive
|
||||
- 4 Built-In Themes or roll your own
|
||||
- Functional, Flat Design Style
|
||||
- Optional code float layout
|
||||
- Shareable/Linkable SEO Friendly URLs
|
||||
- Supports Google Analytics and Piwik Analytics
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
|
@ -52,7 +52,7 @@
|
|||
|
||||
### Installation and usage
|
||||
|
||||
If you have __PHP__ and Composer installed
|
||||
If you have **PHP** and Composer installed
|
||||
|
||||
```bash
|
||||
composer global require daux/daux.io
|
||||
|
|
@ -61,7 +61,7 @@ composer global require daux/daux.io
|
|||
daux generate
|
||||
```
|
||||
|
||||
Or if you wish to use __Docker__
|
||||
Or if you wish to use **Docker**
|
||||
|
||||
```bash
|
||||
# Next to your `docs` folder, run
|
||||
|
|
|
|||
Loading…
Reference in New Issue