D3Public
/
daux.io
8
0
Fork 0
Code Pull Requests Releases Activity

Reformat documentation

This commit is contained in:
Stéphane Goetz 2020-04-25 14:44:43 +02:00
parent ec8530b264
commit 4d312a44e6
21 changed files with 2455 additions and 2421 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
CODE_OF_CONDUCT.md
View File

@ -14,22 +14,22 @@ appearance, race, religion, or sexual identity and orientation.
Examples of behavior that contributes to creating a positive environment Examples of behavior that contributes to creating a positive environment
include: include:
* Using welcoming and inclusive language - Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences - Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism - Gracefully accepting constructive criticism
* Focusing on what is best for the community - Focusing on what is best for the community
* Showing empathy towards other community members - Showing empathy towards other community members
Examples of unacceptable behavior by participants include: Examples of unacceptable behavior by participants include:
* The use of sexualized language or imagery and unwelcome sexual attention or - The use of sexualized language or imagery and unwelcome sexual attention or
advances advances
* Trolling, insulting/derogatory comments, and personal or political attacks - Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment - Public or private harassment
* Publishing others' private information, such as a physical or electronic - Publishing others' private information, such as a physical or electronic
address, without explicit permission address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a - Other conduct which could reasonably be considered inappropriate in a
professional setting professional setting
## Our Responsibilities ## Our Responsibilities

146
README.md
View File

@ -1,6 +1,5 @@
# Daux.io # Daux.io
[![Latest Version](https://img.shields.io/github/release/dauxio/daux.io.svg?style=flat-square)](https://github.com/dauxio/daux.io/releases) [![Latest Version](https://img.shields.io/github/release/dauxio/daux.io.svg?style=flat-square)](https://github.com/dauxio/daux.io/releases)
[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](https://github.com/dauxio/daux.io/blob/master/LICENSE.md) [![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](https://github.com/dauxio/daux.io/blob/master/LICENSE.md)
[![Build Status](https://github.com/dauxio/daux.io/workflows/CI/badge.svg)](https://github.com/dauxio/daux.io/actions) [![Build Status](https://github.com/dauxio/daux.io/workflows/CI/badge.svg)](https://github.com/dauxio/daux.io/actions)
@ -8,45 +7,42 @@
[![Quality Score](https://img.shields.io/scrutinizer/g/dauxio/daux.io.svg?style=flat-square)](https://scrutinizer-ci.com/g/dauxio/daux.io) [![Quality Score](https://img.shields.io/scrutinizer/g/dauxio/daux.io.svg?style=flat-square)](https://scrutinizer-ci.com/g/dauxio/daux.io)
[![Total Downloads](https://img.shields.io/packagist/dt/daux/daux.io.svg?style=flat-square)](https://packagist.org/packages/daux/daux.io) [![Total Downloads](https://img.shields.io/packagist/dt/daux/daux.io.svg?style=flat-square)](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. **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 ## Features
* 100% Mobile Responsive - 100% Mobile Responsive
* CommonMark compliant (a Markdown specification) - CommonMark compliant (a Markdown specification)
* Supports Markdown tables - Supports Markdown tables
* Auto created homepage/landing page - Auto created homepage/landing page
* Auto Syntax Highlighting - Auto Syntax Highlighting
* Auto Generated Navigation - Auto Generated Navigation
* 4 Built-In Themes or roll your own - 4 Built-In Themes or roll your own
* Functional, Flat Design Style - Functional, Flat Design Style
* Shareable/Linkable SEO Friendly URLs - Shareable/Linkable SEO Friendly URLs
* Built On Bootstrap - Built On Bootstrap
* No Build Step - No Build Step
* Git/SVN Friendly - Git/SVN Friendly
* Supports Google Analytics and Piwik Analytics - Supports Google Analytics and Piwik Analytics
* Optional code float layout - Optional code float layout
* Static Output Generation - Static Output Generation
## Demos ## Demos
This is a list of sites using Daux.io: This is a list of sites using Daux.io:
- With a custom theme: - With a custom theme:
* [Crafty](https://swissquote.github.io/crafty) - [Crafty](https://swissquote.github.io/crafty)
* [Pixolution flow](https://docs.pixolution.org) - [Pixolution flow](https://docs.pixolution.org) \* [Soisy](https://doc.soisy.it/)
* [Soisy](https://doc.soisy.it/) - [Vulkan Tutorial](https://vulkan-tutorial.com) \* [3Q](https://docs.3q.video/)
* [Vulkan Tutorial](https://vulkan-tutorial.com) - [The Advanced RSS Environment](https://thearsse.com/manual/)
* [3Q](https://docs.3q.video/) - With the default Theme
* [The Advanced RSS Environment](https://thearsse.com/manual/) - [Daux.io](https://daux.io/)
- With the default Theme _ [DoctrineWatcher](https://dsentker.github.io/WatcherDocumentation/)
* [Daux.io](https://daux.io/) _ [DrupalGap](http://docs.drupalgap.org/8/)
* [DoctrineWatcher](https://dsentker.github.io/WatcherDocumentation/) - [ICADMIN: An admin panel powered by CodeIgniter.](http://istocode.com/shared/ic-admin/)
* [DrupalGap](http://docs.drupalgap.org/8/) - [Munee: Standalone PHP 5.3 Asset Optimisation & Manipulation](http://mun.ee)
* [ICADMIN: An admin panel powered by CodeIgniter.](http://istocode.com/shared/ic-admin/) - [Nuntius: A PHP framework for bots](https://roysegall.github.io/nuntius-bot/)
* [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. 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:** **Good:**
* 01_Getting_Started.md = Getting Started - 01_Getting_Started.md = Getting Started
* API_Calls.md = API Calls - API_Calls.md = API Calls
* 200_Something_Else-Cool.md = Something Else-Cool - 200_Something_Else-Cool.md = Something Else-Cool
* _5_Ways_to_Be_Happy.md = 5 Ways To Be Happy - \_5_Ways_to_Be_Happy.md = 5 Ways To Be Happy
**Bad:** **Bad:**
* File Name With Space.md = FAIL - File Name With Space.md = FAIL
## Sorting ## 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 ## Landing page
@ -120,9 +116,9 @@ If you want to create a beautiful landing page for your project, simply create a
```json ```json
{ {
"title": "Daux.io", "title": "Daux.io",
"tagline": "The Easiest Way To Document Your Project", "tagline": "The Easiest Way To Document Your Project",
"image": "app.png" "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. The `config.json` file is a simple JSON object that you can use to change some of the basic settings of the documentation.
### Title ### Title
Change the title bar in the docs Change the title bar in the docs
```json ```json
{ {
"title": "Daux.io" "title": "Daux.io"
} }
``` ```
### Themes ### Themes
We have 4 built-in Bootstrap themes. To use one of the themes, just set the `theme` option to one of the following: 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-blue
* daux-green - daux-green
* daux-navy - daux-navy
* daux-red - daux-red
```json ```json
{ {
"html": { "theme": "daux-green" } "html": { "theme": "daux-green" }
} }
``` ```
### More options ### More options
Many other options are available: Many other options are available:
- [Global options](http://daux.io/Configuration/index)
- [HTML Options](http://daux.io/Configuration/Html_export) - [Global options](http://daux.io/Configuration/index)
- [Confluence options](http://daux.io/Configuration/Confluence_upload) - [HTML Options](http://daux.io/Configuration/Html_export)
- [Confluence options](http://daux.io/Configuration/Confluence_upload)
## Running Remotely ## 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 ## Running Locally
There are several ways to run the docs 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> 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: 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 rewrite configuration, for handling clean urls.
* A mime type handler for less files, if using a custom theme. - A mime type handler for less files, if using a custom theme.
### Clean URLs ### Clean URLs
@ -202,20 +202,32 @@ The `web.config` needs an entry for `<rewrite>` under `<system.webServer>`:
```xml ```xml
<configuration> <configuration>
<system.webServer> <system.webServer>
<rewrite> <rewrite>
<rules> <rules>
<rule name="Main Rule" stopProcessing="true"> <rule name="Main Rule" stopProcessing="true">
<match url=".*" /> <match url=".*" />
<conditions logicalGrouping="MatchAll"> <conditions logicalGrouping="MatchAll">
<add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" /> <add
<add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" /> input="{REQUEST_FILENAME}"
</conditions> matchType="IsFile"
<action type="Rewrite" url="index.php" appendQueryString="false" /> negate="true"
</rule> />
</rules> <add
</rewrite> input="{REQUEST_FILENAME}"
</system.webServer> matchType="IsDirectory"
negate="true"
/>
</conditions>
<action
type="Rewrite"
url="index.php"
appendQueryString="false"
/>
</rule>
</rules>
</rewrite>
</system.webServer>
</configuration> </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 ## 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 ### Extensions

84
docs/00_Getting_Started.md
View File

@ -6,49 +6,48 @@
### For Authors ### For Authors
* [Auto Generated Navigation / Page sorting](01_Features/Navigation_and_Sorting.md) - [Auto Generated Navigation / Page sorting](01_Features/Navigation_and_Sorting.md)
* [Internal documentation links](01_Features/Internal_links.md) - [Internal documentation links](01_Features/Internal_links.md)
* [CommonMark compliant](01_Features/CommonMark_compliant.md) - [CommonMark compliant](01_Features/CommonMark_compliant.md)
* [Auto created homepage/landing page](01_Features/Landing_page.md) - [Auto created homepage/landing page](01_Features/Landing_page.md)
* [Multiple Output Formats](01_Features/Multiple_Output_Formats.md) - [Multiple Output Formats](01_Features/Multiple_Output_Formats.md)
* [Multiple Languages Support](01_Features/Multilanguage.md) - [Multiple Languages Support](01_Features/Multilanguage.md)
* [No Build Step](01_Features/Live_mode.md) - [No Build Step](01_Features/Live_mode.md)
* [Static Output Generation](01_Features/Static_Site_Generation.md) - [Static Output Generation](01_Features/Static_Site_Generation.md)
* [Table of Contents](01_Features/Table_of_contents.md) - [Table of Contents](01_Features/Table_of_contents.md)
### For Developers ### For Developers
* [Auto Syntax Highlighting](01_Features/Auto_Syntax_Highlight.md) - [Auto Syntax Highlighting](01_Features/Auto_Syntax_Highlight.md)
* [Extend Daux.io with Processors](01_For_Developers/Creating_a_Processor.md) - [Extend Daux.io with Processors](01_For_Developers/Creating_a_Processor.md)
* Full access to the internal API to create new pages programatically - Full access to the internal API to create new pages programatically
* Work with pages metadata - Work with pages metadata
### For Marketing ### For Marketing
* 100% Mobile Responsive - 100% Mobile Responsive
* 4 Built-In Themes or roll your own - 4 Built-In Themes or roll your own
* Functional, Flat Design Style - Functional, Flat Design Style
* Optional code float layout - Optional code float layout
* Shareable/Linkable SEO Friendly URLs - Shareable/Linkable SEO Friendly URLs
* Supports Google Analytics and Piwik Analytics - Supports Google Analytics and Piwik Analytics
## Demos ## Demos
This is a list of sites using Daux.io: This is a list of sites using Daux.io:
- With a custom theme: - With a custom theme:
* [Crafty](https://swissquote.github.io/crafty) - [Crafty](https://swissquote.github.io/crafty)
* [Pixolution flow](https://docs.pixolution.org) - [Pixolution flow](https://docs.pixolution.org) \* [Soisy](https://doc.soisy.it/)
* [Soisy](https://doc.soisy.it/) - [Vulkan Tutorial](https://vulkan-tutorial.com)
* [Vulkan Tutorial](https://vulkan-tutorial.com) - [3Q](https://docs.3q.video/)
* [3Q](https://docs.3q.video/) - With the default Theme
- With the default Theme - [Daux.io](https://daux.io/)
* [Daux.io](https://daux.io/) _ [DoctrineWatcher](https://dsentker.github.io/WatcherDocumentation/)
* [DoctrineWatcher](https://dsentker.github.io/WatcherDocumentation/) _ [DrupalGap](http://docs.drupalgap.org/8/)
* [DrupalGap](http://docs.drupalgap.org/8/) - [ICADMIN: An admin panel powered by CodeIgniter.](http://istocode.com/shared/ic-admin/)
* [ICADMIN: An admin panel powered by CodeIgniter.](http://istocode.com/shared/ic-admin/) - [Munee: Standalone PHP 5.3 Asset Optimisation & Manipulation](http://mun.ee)
* [Munee: Standalone PHP 5.3 Asset Optimisation & Manipulation](http://mun.ee) - [Nuntius: A PHP framework for bots](https://roysegall.github.io/nuntius-bot/)
* [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. 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 Any parameter valid in the PHP version is valid in the Docker version
### Writing pages ### Writing pages
Creating new pages is very easy: Creating new pages is very easy:
1. Create a markdown file (`*.md` or `*.markdown`) 1. Create a markdown file (`*.md` or `*.markdown`)
2. Start writing 2. Start writing
@ -98,14 +97,14 @@ You must use underscores instead of spaces. Here are some example file names and
**Good:** **Good:**
* 01_Getting_Started.md = Getting Started - 01_Getting_Started.md = Getting Started
* API_Calls.md = API Calls - API_Calls.md = API Calls
* 200_Something_Else-Cool.md = Something Else-Cool - 200_Something_Else-Cool.md = Something Else-Cool
* _5_Ways_to_Be_Happy.md = 5 Ways To Be Happy - \_5_Ways_to_Be_Happy.md = 5 Ways To Be Happy
**Bad:** **Bad:**
* File Name With Space.md = FAIL - File Name With Space.md = FAIL
### See your pages ### 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: 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 to HTML, same as the website, but can be hosted without PHP.
- Export all documentation in a single HTML page - Export all documentation in a single HTML page
- Upload to your Atlassian Confluence server. - Upload to your Atlassian Confluence server.
[See a detailed feature comparison matrix](01_Features/Multiple_Output_Formats.md) [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 ## 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 ### 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. If you encounter an error similar to `utf8_decode() not found` this means that you're missing the `php-xml` package.
## Support ## 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>. 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>.

53
docs/01_Features/CommonMark_compliant.md
View File

@ -1,17 +1,14 @@
As we support CommonMark, a broad range of markdown features is available to you. 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. 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: The above header should be an H2 tag. Now, for a list of fruits:
* Red Apples - Red Apples
* Purple Grapes - Purple Grapes
* Green Kiwifruits - Green Kiwifruits
Let's get crazy: Let's get crazy:
@ -27,18 +24,17 @@ Let's get crazy:
What about some code **in** a list? That's insane, right? 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 } ['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) ['a', 'b'].map(&:uppercase)
Some people seem to like definition lists 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? 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?
&copy; 2004 Foo Corporation &copy; 2004 Foo Corporation
</div> </div>
Set in stone ## Set in stone
------------
Preformatted blocks are useful for ASCII art: Preformatted blocks are useful for ASCII art:
@ -73,8 +68,7 @@ Preformatted blocks are useful for ASCII art:
___|_____________ ___|_____________
</pre> </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: 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 > 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. > as I should be in coming up with one.
Table for two ## Table for two
-------------
ID | Name | Rank | ID | Name | Rank |
---|:------:|------: | --- | :----------------: | ----------------: |
1 | Tom Preston-Werner | Awesome | 1 | Tom Preston-Werner | Awesome |
2 | Albert Einstein | Nearly as awesome | 2 | Albert Einstein | Nearly as awesome |
Crazy linking action ## Crazy linking action
--------------------
I get 10 times more traffic from [Google] [1] than from I get 10 times more traffic from [Google][1] than from
[Yahoo] [2] or [MSN] [3]. [Yahoo][2] or [MSN][3].
[1]: http://google.com/ "Google" [1]: http://google.com/ "Google"
[2]: http://search.yahoo.com/ "Yahoo Search" [2]: http://search.yahoo.com/ "Yahoo Search"
[3]: http://search.msn.com/ "MSN Search" [3]: http://search.msn.com/ "MSN Search"
Images ## Images
------
Here's an image. 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. 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)._

19
docs/01_Features/Edit_on_GitHub_links.md
View File

@ -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. 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. 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 Daux.io will handle the rest
```json ```json
{ {
"html": { "html": {
"edit_on_github": "dauxio/daux.io/blob/master/docs" "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: 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 ```json
{ {
"html": { "html": {
"edit_on": { "edit_on": {
"name": "Bitbucket", "name": "Bitbucket",
"basepath": "https://bitbucket.org/dauxio/daux.io/src/master/docs" "basepath": "https://bitbucket.org/dauxio/daux.io/src/master/docs"
}
} }
}
} }
``` ```

12
docs/01_Features/Landing_page.md
View File

@ -2,9 +2,9 @@ If you want to create a beautiful landing page for your project, create a `_inde
```json ```json
{ {
"title": "Daux.io", "title": "Daux.io",
"tagline": "The Easiest Way To Document Your Project", "tagline": "The Easiest Way To Document Your Project",
"image": "app.png" "image": "app.png"
} }
``` ```
@ -14,8 +14,8 @@ To disable the automatic landing page, you can set `auto_landing` to false in th
```json ```json
{ {
"html": { "html": {
"auto_landing": false "auto_landing": false
} }
} }
``` ```

53
docs/01_Features/Live_mode.md
View File

@ -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> 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 ## Running Remotely
### Clean URLs configuration ### Clean URLs configuration
@ -20,9 +19,9 @@ To enable the same, set the toggle in the `config.json` file in the `/docs` fold
```json ```json
{ {
"live": { "live": {
"clean_urls": true "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: 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 rewrite configuration, for handling clean urls.
* A mime type handler for less files, if using a custom theme. - A mime type handler for less files, if using a custom theme.
### Clean URLs ### Clean URLs
@ -79,20 +78,32 @@ The `web.config` needs an entry for `<rewrite>` under `<system.webServer>`:
```xml ```xml
<configuration> <configuration>
<system.webServer> <system.webServer>
<rewrite> <rewrite>
<rules> <rules>
<rule name="Main Rule" stopProcessing="true"> <rule name="Main Rule" stopProcessing="true">
<match url=".*" /> <match url=".*" />
<conditions logicalGrouping="MatchAll"> <conditions logicalGrouping="MatchAll">
<add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" /> <add
<add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" /> input="{REQUEST_FILENAME}"
</conditions> matchType="IsFile"
<action type="Rewrite" url="index.php" appendQueryString="false" /> negate="true"
</rule> />
</rules> <add
</rewrite> input="{REQUEST_FILENAME}"
</system.webServer> matchType="IsDirectory"
negate="true"
/>
</conditions>
<action
type="Rewrite"
url="index.php"
appendQueryString="false"
/>
</rule>
</rules>
</rewrite>
</system.webServer>
</configuration> </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` 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`

3
docs/01_Features/Multilanguage.md
View File

@ -4,11 +4,12 @@ Add this to your config.json :
```json ```json
{ {
"languages": { "en": "English", "de": "German" } "languages": { "en": "English", "de": "German" }
} }
``` ```
You will the need separate directories for each language in `docs/` folder. You will the need separate directories for each language in `docs/` folder.
``` ```
├── docs/ ├── docs/
│ ├── _index.md │ ├── _index.md

26
docs/01_Features/Multiple_Output_Formats.md
View File

@ -1,21 +1,21 @@
Daux.io is extendable and comes by default with three export formats: Daux.io is extendable and comes by default with three export formats:
- Export to HTML - Export to HTML
- Export all documentation in a single HTML page - Export all documentation in a single HTML page
- Upload to your Atlassian Confluence server - Upload to your Atlassian Confluence server
## Feature Matrix ## Feature Matrix
Feature | HTML | Single Page HTML | Confluence | Feature | HTML | Single Page HTML | Confluence |
--------------:|:----:|:----------------:|:----------: | -----------------------: | :--: | :--------------: | :-------------------------: |
Multilanguage | √ | X (Planned) | X | Multilanguage | √ | X (Planned) | X |
Landing Pages | √ | X | X | Landing Pages | √ | X | X |
Index Pages | √ | √ | √ | Index Pages | √ | √ | √ |
Internal Links | √ | X (Planned) | √ | Internal Links | √ | X (Planned) | √ |
Code Highlight | √ | X (Planned) | √ (Using macros) | Code Highlight | √ | X (Planned) | √ (Using macros) |
Live Mode | √ | X | X | Live Mode | √ | X | X |
Pages Ordering | √ | √ | X (API Limitation) | Pages Ordering | √ | √ | X (API Limitation) |
Google / Piwik analytics | √ | √ | √ (Configured on Conflence) | Google / Piwik analytics | √ | √ | √ (Configured on Conflence) |
## Confluence Example ## Confluence Example

19
docs/01_Features/Navigation_and_Sorting.md
View File

@ -1,4 +1,3 @@
## Navigation ## Navigation
The navigation is generated automatically with all pages that end with `.md` or `.markdown` 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 ## 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`. 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` 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 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. 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 `+`. It works the same for files prefixed with `+`.
Page order priorities are like this: Page order priorities are like this:
- `+` in front of the filename and numbers in front - `+` in front of the filename and numbers in front
- `+` in front of the filename - `+` in front of the filename
- The index page - The index page
- Numbers in the front - Numbers in the front
- Pages without prefix - Pages without prefix
- `-` in front of the filename and numbers in front - `-` in front of the filename and numbers in front
- `-` in front of the filename - `-` in front of the filename

6
docs/01_Features/Search.md
View File

@ -6,8 +6,8 @@ To enable the generated search, you can set `search` to true in the `html` secti
```json ```json
{ {
"html": { "html": {
"search": true "search": true
} }
} }
``` ```

13
docs/01_Features/Static_Site_Generation.md
View File

@ -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
- HTML output - Atlassian Confluence upload
- Single page HTML output
- Atlassian Confluence upload
Generating a complete set of pages, with navigation Generating a complete set of pages, with navigation
@ -13,7 +12,7 @@ daux --destination=[Output Directory Relative Direction]
## Options ## Options
For more options, run For more options, run
```bash ```bash
daux generate --help daux generate --help
@ -32,7 +31,7 @@ daux --format=html
### Specify a processor ### 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 : By running :

8
docs/01_Features/Table_of_contents.md
View File

@ -18,10 +18,8 @@ You can enable this feature in your configuration
```json ```json
{ {
"html": { "html": {
"auto_toc": true "auto_toc": true
} }
} }
``` ```

4078
docs/02_Examples/05_Code_Highlighting.md
View File

File diff suppressed because it is too large Load Diff

3
docs/02_Examples/index.md
View File

@ -1,2 +1,3 @@
### This is a landing page for the Examples section ### 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.

40
docs/05_Configuration/Confluence_upload.md
View File

@ -1,21 +1,23 @@
__Table of contents__ **Table of contents**
[TOC] [TOC]
## Configuring the connection ## 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. 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 ```json
{ {
"confluence": { "confluence": {
"base_url": "http://my_confluence_server.com/", "base_url": "http://my_confluence_server.com/",
"user" : "my_username", "user": "my_username",
"pass" : "my_password" "pass": "my_password"
} }
} }
``` ```
## Where to upload ## Where to upload
Now that the connection is defined, you need to tell it where you want your documentation to be uploaded. 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. 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 ```json
{ {
"confluence": { "confluence": {
"space_id": "my_space", "space_id": "my_space",
"ancestor_id": 50370632 "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. You can use that when you're uploading your documentation to the root of a Confluence Space or if your page already exists.
## Prefix ## Prefix
Because confluence can't have two pages with the same name in a space, I recommend you define a prefix for your pages. Because confluence can't have two pages with the same name in a space, I recommend you define a prefix for your pages.
```json ```json
{ {
"confluence": { "prefix": "DAUX -" } "confluence": { "prefix": "DAUX -" }
} }
``` ```
## Update threshold ## 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. 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 ```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. Setting the value to `0` disables the feature altogether.
## Delete old pages ## 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. 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. By default, it will inform you that some pages aren't needed anymore and you can delete them by hand.
```json ```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. 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 ## Information message
When you create your page. there is no indication that the upload process will override the content of the pages. 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. 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 ```json
{ {
"confluence": { "confluence": {
"header": "These pages are updated automatically, your changes will be overriden." "header": "These pages are updated automatically, your changes will be overriden."
} }
} }
``` ```

89
docs/05_Configuration/Html_export.md
View File

@ -1,24 +1,26 @@
__Table of contents__ **Table of contents**
[TOC] [TOC]
## Analytics ## Analytics
### Google Analytics ### Google Analytics
This will embed the google analytics tracking code. This will embed the google analytics tracking code.
```json ```json
{ {
"html": { "google_analytics": "UA-XXXXXXXXX-XX" } "html": { "google_analytics": "UA-XXXXXXXXX-XX" }
} }
``` ```
### Piwik Analytics ### Piwik Analytics
This will embed the piwik tracking code. This will embed the piwik tracking code.
```json ```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 ```json
{ {
"html": { "piwik_analytics_id": "43" } "html": { "piwik_analytics_id": "43" }
} }
``` ```
### Plausible Analytics ### Plausible Analytics
This will embed the https://plausible.io/ tracking code. This will embed the https://plausible.io/ tracking code.
```json ```json
{ {
"html": { "plausible_domain": "daux.io" } "html": { "plausible_domain": "daux.io" }
} }
``` ```
## Automatic Table of Contents ## 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) You can add a table of contents on each page automatically, read about it [here](../01_Features/Table_of_contents.md)
## Buttons ## Buttons
You can add buttons to the landing page. You can add buttons to the landing page.
```json ```json
{ {
"html": { "html": {
"buttons": { "buttons": {
"My Website": "http://example.com" "My Website": "http://example.com"
}
} }
}
} }
``` ```
## Breadcrumb titles ## 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 ```json
{ {
"html": { "html": {
"breadcrumbs": true, "breadcrumbs": true,
"breadcrumb_separator" : " > " "breadcrumb_separator": " > "
} }
} }
``` ```
## Date Modified ## 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`. To disable this, change the option in your config.json to `false`.
```json ```json
{ {
"html": { "date_modified": false } "html": { "date_modified": false }
} }
``` ```
## GitHub Repo ## GitHub Repo
Add a 'Fork me on GitHub' ribbon. Add a 'Fork me on GitHub' ribbon.
```json ```json
{ {
"html": { "repo": "dauxio/daux.io" } "html": { "repo": "dauxio/daux.io" }
} }
``` ```
## Inherit Index ## 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. This feature will instructs the navigation generator to seek the first available file to use when there is no index in a folder.
```json ```json
{ {
"html": { "inherit_index": true } "html": { "inherit_index": true }
} }
``` ```
## Jump buttons ## Jump buttons
You can have previous/next buttons on each page. You can have previous/next buttons on each page.
They can be disabled by setting `jump_buttons` to `false`. They can be disabled by setting `jump_buttons` to `false`.
```json ```json
{ {
"html": { "jump_buttons": false } "html": { "jump_buttons": false }
} }
``` ```
## Landing page ## 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 ## Links
Include custom links in the sidebar. Include custom links in the sidebar.
```json ```json
{ {
"html": { "html": {
"links": { "links": {
"GitHub Repo": "https://github.com/dauxio/daux.io", "GitHub Repo": "https://github.com/dauxio/daux.io",
"Help/Support/Bugs": "https://github.com/dauxio/daux.io/issues", "Help/Support/Bugs": "https://github.com/dauxio/daux.io/issues",
"Made by Todaymade": "http://todaymade.com" "Made by Todaymade": "http://todaymade.com"
}
} }
}
} }
``` ```
## Search ## Search
Daux has an embedded search engine read all about it [here](../01_Features/Search.md) Daux has an embedded search engine read all about it [here](../01_Features/Search.md)
## Themes ## Themes
We have 4 built-in Bootstrap themes. To use one of the themes, just set the `theme` option to one of the following: 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-blue
* daux-green - daux-green
* daux-navy - daux-navy
* daux-red - daux-red
```json ```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 ```json
{ {
"html": { "theme": "new-theme" } "html": { "theme": "new-theme" }
} }
``` ```
## Toggling Code Blocks ## 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. By setting the `toggle_code` property to `true`, you can offer a toggle button on the page.
```json ```json
{ {
"html": { "toggle_code": true } "html": { "toggle_code": true }
} }
``` ```
## Twitter ## Twitter
Include twitter follow buttons in the sidebar. Include twitter follow buttons in the sidebar.
```json ```json
{ {
"html": { "twitter": ["justin_walsh", "todaymade"] } "html": { "twitter": ["justin_walsh", "todaymade"] }
} }
``` ```

66
docs/05_Configuration/_index.md
View File

@ -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. 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] [TOC]
### Title ### Title
Change the title bar in the docs Change the title bar in the docs
```json ```json
{ {
"title": "Daux.io" "title": "Daux.io"
} }
``` ```
### Tagline ### Tagline
Change the tagline bar in the docs Change the tagline bar in the docs
```json ```json
{ {
"tagline": "The Easiest Way To Document Your Project" "tagline": "The Easiest Way To Document Your Project"
} }
``` ```
### Author ### Author
Change the documentation's author Change the documentation's author
```json ```json
{ {
"author": "Stéphane Goetz" "author": "Stéphane Goetz"
} }
``` ```
### Image ### Image
An image to show on the landing page. A relative path from the documentation root. An image to show on the landing page. A relative path from the documentation root.
```json ```json
{ {
"image": "image.png" "image": "image.png"
} }
``` ```
### Format ### Format
Change the output format. It is recommended you set only formats that support the live mode as this will also 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 be read by the integrated web server. And you set the other formats (like confluence) only by command line
```json ```json
{ {
"format": "html" "format": "html"
} }
``` ```
- __html__ with [its options](./Html_export.md) - **html** with [its options](./Html_export.md)
- __confluence__ with [its options](./Confluence_upload.md) - **confluence** with [its options](./Confluence_upload.md)
Available formats are __HTML__ and __Confluence__ Available formats are **HTML** and **Confluence**
### Ignore ### 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. 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 ```json
{ {
"ignore": { "ignore": {
"files": ["Work_In_Progress.md"], "files": ["Work_In_Progress.md"],
"folders": ["99_Not_Ready"] "folders": ["99_Not_Ready"]
} }
} }
``` ```
### Timezone ### 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). 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 ```json
{ {
"timezone": "America/Los_Angeles" "timezone": "America/Los_Angeles"
} }
``` ```
### Multi-language ### Multi-language
Enables multi-language support which needs separate directories for each language in `docs/` folder. Enables multi-language support which needs separate directories for each language in `docs/` folder.
```json ```json
{ {
"languages": {"en": "English", "de": "German"} "languages": { "en": "English", "de": "German" }
} }
``` ```
Directory structure: Directory structure:
``` ```
├── docs/ ├── docs/
│ ├── _index.md │ ├── _index.md
@ -113,7 +122,7 @@ You can change the default language with the `language` option.
```json ```json
{ {
"language": "fr" "language": "fr"
} }
``` ```
@ -124,27 +133,28 @@ A string that isn't found will fall back to english.
```json ```json
{ {
"strings": { "strings": {
"fr": { "fr": {
"CodeBlocks_show": "Afficher le code", "CodeBlocks_show": "Afficher le code",
"Search_placeholder": "Rechercher...", "Search_placeholder": "Rechercher...",
"Link_previous": "Précédent", "Link_previous": "Précédent",
"Link_next": "Suivant", "Link_next": "Suivant",
"Edit_on": "Editer sur :name:", "Edit_on": "Editer sur :name:",
"View_on_github": "Voir sur GitHub", "View_on_github": "Voir sur GitHub",
"View_documentation": "Voir la Documentation" "View_documentation": "Voir la Documentation"
}
} }
}
} }
``` ```
### Processor ### 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. 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). More information on how to create a Processor can be found [here](!For_Developers/Creating_a_Processor).
```json ```json
{ {
"processor": "MyProcessor" "processor": "MyProcessor"
} }
``` ```

13
docs/10_For_Developers/Creating_a_Processor.md
View File

@ -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. 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. 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. By default, we created a `daux/Processor.php` file to get you started.
## A quick test ? ## 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. 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 ```php
public function manipulateTree(Root $root) 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. 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 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. If the extension is not mapped to a Generator, it will simply create the file as-is without manipulation.
### Extend the Markdown Generator ### Extend the Markdown Generator
@ -82,9 +82,9 @@ See the details on [CommonMark's website](http://commonmark.thephpleague.com/cus
### Add new generators ### Add new generators
You can add new generators to Daux.io and use them right away, they must implement the 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 `\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 have to implement `\Todaymade\Daux\Format\Base\LiveGenerator`.
```php ```php
public function addGenerators() public function addGenerators()
@ -92,4 +92,3 @@ public function addGenerators()
return ['custom_generator' => '\Todaymade\Daux\Extension\MyNewGenerator']; return ['custom_generator' => '\Todaymade\Daux\Extension\MyNewGenerator'];
} }
``` ```

77
docs/10_For_Developers/Creating_a_Theme.md
View File

@ -8,43 +8,45 @@ Here is an example `config.json` file :
```json ```json
{ {
"favicon": "<theme_url>img/favicon.png", "favicon": "<theme_url>img/favicon.png",
"css": ["<theme_url>css/theme.min.css"], "css": ["<theme_url>css/theme.min.css"],
"js": [], "js": [],
"fonts": ["https://fonts.googleapis.com/css?family=Roboto+Slab:400,100,300,700&subset=latin,cyrillic-ext,cyrillic"], "fonts": [
"variants": { "https://fonts.googleapis.com/css?family=Roboto+Slab:400,100,300,700&subset=latin,cyrillic-ext,cyrillic"
"blue": { ],
"favicon": "<theme_url>img/favicon-blue.png", "variants": {
"css": ["<theme_url>css/theme-blue.min.css"] "blue": {
}, "favicon": "<theme_url>img/favicon-blue.png",
"green": { "css": ["<theme_url>css/theme-blue.min.css"]
"favicon": "<theme_url>img/favicon-green.png", },
"css": ["<theme_url>css/theme-green.min.css"] "green": {
"favicon": "<theme_url>img/favicon-green.png",
"css": ["<theme_url>css/theme-green.min.css"]
}
} }
}
} }
``` ```
There are five options : There are five options :
- __`favicon`__: The URL to your favicon - **`favicon`**: The URL to your favicon
- __`css`__: An array of CSS Stylesheets to add to the page - **`css`**: An array of CSS Stylesheets to add to the page
- __`js`__: An array of JavaScript files to load - **`js`**: An array of JavaScript files to load
- __`fonts`__: An array of Font sources, these are added as stylesheets - **`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`) - **`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. This is automatically substituted with the final url to the theme when generating the final page.
There are two possible substitutions : 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 ## Theme variants
Like the default Daux.io theme, you might want to provide variants of your theme. 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. 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. 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 ```json
{ {
"themes_directory": "/home/user/themes", "themes_directory": "/home/user/themes",
"html": { "html": {
"theme": "{theme}-{variant}" "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. 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 : By default, we have the following templates :
- `content.php`: The content page.
- `home.php`: The landing page. - `content.php`: The content page.
- `error.php`: The page to show when a page is not found or some other error happened. - `home.php`: The landing page.
- `partials/navbar_content.php`: The content of the top navigation bar. - `error.php`: The page to show when a page is not found or some other error happened.
- `partials/google_analytics.php`: The script to load Google Analytics. - `partials/navbar_content.php`: The content of the top navigation bar.
- `partials/piwik_analytics.php`: The script to load Piwik Analytics. - `partials/google_analytics.php`: The script to load Google Analytics.
- `layout/00_layout.php`: The master template, containing the `<html>` tag. - `partials/piwik_analytics.php`: The script to load Piwik Analytics.
- `layout/05_page.php`: The page layout, with left navigation. - `layout/00_layout.php`: The master template, containing the `<html>` tag.
- `layout/05_page.php`: The page layout, with left navigation.

42
docs/_index.md
View File

@ -13,37 +13,37 @@
#### For Authors #### For Authors
* [Auto Generated Navigation / Page sorting](01_Features/Navigation_and_Sorting.md) - [Auto Generated Navigation / Page sorting](01_Features/Navigation_and_Sorting.md)
* [Internal documentation links](01_Features/Internal_links.md) - [Internal documentation links](01_Features/Internal_links.md)
* [CommonMark compliant](01_Features/CommonMark_compliant.md) - [CommonMark compliant](01_Features/CommonMark_compliant.md)
* [Auto created homepage/landing page](01_Features/Landing_page.md) - [Auto created homepage/landing page](01_Features/Landing_page.md)
* [Multiple Output Formats](01_Features/Multiple_Output_Formats.md) - [Multiple Output Formats](01_Features/Multiple_Output_Formats.md)
* [Multiple Languages Support](01_Features/Multilanguage.md) - [Multiple Languages Support](01_Features/Multilanguage.md)
* [No Build Step](01_Features/Live_mode.md) - [No Build Step](01_Features/Live_mode.md)
* [Static Output Generation](01_Features/Static_Site_Generation.md) - [Static Output Generation](01_Features/Static_Site_Generation.md)
* [Table of Contents](01_Features/Table_of_contents.md) - [Table of Contents](01_Features/Table_of_contents.md)
</div> </div>
<div class="Row__third"> <div class="Row__third">
#### For Developers #### For Developers
* [Auto Syntax Highlighting](01_Features/Auto_Syntax_Highlight.md) - [Auto Syntax Highlighting](01_Features/Auto_Syntax_Highlight.md)
* [Extend Daux.io with Processors](01_For_Developers/Creating_a_Processor.md) - [Extend Daux.io with Processors](01_For_Developers/Creating_a_Processor.md)
* Full access to the internal API to create new pages programatically - Full access to the internal API to create new pages programatically
* Work with pages metadata - Work with pages metadata
</div> </div>
<div class="Row__third"> <div class="Row__third">
#### For Marketing #### For Marketing
* 100% Mobile Responsive - 100% Mobile Responsive
* 4 Built-In Themes or roll your own - 4 Built-In Themes or roll your own
* Functional, Flat Design Style - Functional, Flat Design Style
* Optional code float layout - Optional code float layout
* Shareable/Linkable SEO Friendly URLs - Shareable/Linkable SEO Friendly URLs
* Supports Google Analytics and Piwik Analytics - Supports Google Analytics and Piwik Analytics
</div> </div>
</div> </div>
@ -52,7 +52,7 @@
### Installation and usage ### Installation and usage
If you have __PHP__ and Composer installed If you have **PHP** and Composer installed
```bash ```bash
composer global require daux/daux.io composer global require daux/daux.io
@ -61,7 +61,7 @@ composer global require daux/daux.io
daux generate daux generate
``` ```
Or if you wish to use __Docker__ Or if you wish to use **Docker**
```bash ```bash
# Next to your `docs` folder, run # Next to your `docs` folder, run