====== NavBox Plugin ======

---- plugin ----
description: NavBox brings the core functionality of the NavBox from Wikipedia (and MediaWiki) across to DokuWiki, allowing a clean and easy-to-use way of linking between related pages. It can be placed anywhere on the page at this point in time but it is intended to be displayed at the bottom of a page.
author     : MidgardApps 
email      : hello@midgardapps.com 
type       : syntax
lastupdate : 2018-05-06
compatible : Hrun, Detritus, Elenor of Tsort, Frusterick Manners, !Hogfather
depends    : 
conflicts  : 
similar    : 
tags       : tables, mediawiki

downloadurl: https://github.com/JovinJovinsson/dokuwiki-plugin-navbox/zipball/master
bugtracker : https://github.com/JovinJovinsson/dokuwiki-plugin-navbox/issues
sourcerepo : https://github.com/JovinJovinsson/dokuwiki-plugin-navbox/
donationurl: 

screenshot_img : https://i.imgur.com/2nEF5xp.png
----

===== Installation =====

Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.

===== Examples/Usage =====

See the plugin in action [[https://openwiki.midgardapps.com|here]]. FIXME

===== Syntax =====
The plugin reads each line as a new tag / parameter combination. Only insert a new line if you intend on utilising a new tag.

==== Basic Tags ====
^ Syntax Tag               ^ Example Usage                                                 ^ Result                                                                                                                                                                                                                                    ^
^  <code><navbox></code>   |                                                               | Initiates the NavBox Container.                                                                                                                                                                                                           |
^  <code>#</code>          | <code># My NavBox</code>                                      | Sets the title of the NavBox, at the top.                                                                                                                                                                                                 |
^  <code>##</code>         | <code>## Group 1 Title</code>                                 | Sets the title of a group of links, in the left column.                                                                                                                                                                                   |
^  <code>###</code>        | <code>### SubGroup A Title</code>  or   <code>### !ns</code>  | Sets the title of a subgroup. \\ **Note:** This must follow either a Group Title Tag (##) or a list of links and must also have a list of links following (or one of the [[#Advanced Tags]]), otherwise it will not form a proper group.  |
^  <code>[[links]]</code>  | <code>[[link1|Links]][[another|More]]</code>                  | A list of links, which can be simply listed one after the other (as per example), or separated by <code>,</code>   or    <code>;</code>                                                                                                   |
^  <code></navbox></code>  |                                                               | The closing tag for the container.                                                                                                                                                                                                        |

=== Example of Basic NavBox ===
^ Code Sample                                                                                                                                               ^ Output                               ^
| <code> <navbox> # Animals ## Birds ### Carnivorous Birds [[falcon]],[[eagle]],[[vulture]] ### Little Birds [[hummingbird]],[[canary]] </navbox>  </code>  | {{https://i.imgur.com/H1Q6qjV.png}}  |

==== Advanced Tags ====
Using an advanced tag will create it's own Group (equivalent of the ## tag) unless it is specified as a Sub Group (preceeded by the ### tag). It will close the previously created group, and after the Advanced Tag a new group will need to be created for further links.

Example:
<code>
<navbox>
# Title
## Group 1
[[some links]]
!ns                <<< This creates a new Group
## Group 3
### SubGroup 1
[[sub links]]
### !ns            <<< This creates a Sub Group inside Group 3 after SubGroup 1
</navbox>
</code>
=== Namespace Tag (!ns) ===
Creates a list of links in the current namespace, automatically creates the group name based on the lowest level of the current namespace. For example, if you are building the NavBox on animals:birds:carnivorous:start it will name the group "Carnivorous". There are various modifiers that can be used below.
^ Modifier  ^ Example  ^ Result  |
^  <code>###</code>  |  <code>### !ns</code>  | This is combined with the Sub Group tag, which indicates that the listing should be contained in the previously created group. This can be combined with the below modifiers as well. |
^  <code>+n</code>  |  <code>!ns+n [[other:namespace]]</code> | This will force the plugin to list all pages contained in the specified namespace. |
^  <code>+t</code>  |  <code>!ns+t Different Title</code> | This will override the automatically created title (or subgroup title) for the listing. |
^  <code>+nt</code>  |  <code>!ns+nt [[other:namespace|Custom Title]]</code> | Performs both actions of the +n and +t modifiers. |
===== Configuration and Settings =====

There are no configuration or settings options available at this time.

If you use user stylings you can override any element in the CSS code to provide different colours, fonts or sizes. You can view the CSS code on the GitHub page linked above.

===== Development =====

Ongoing development is always happening in this repository. If you have any issues or requests please log them against the [[https://github.com/JovinJovinsson/dokuwiki-plugin-navbox/issues|GitHub repository]] and I'll respond directly!

=== Change Log ===

{{rss>https://github.com/JovinJovinsson/dokuwiki-plugin-navbox/commits/master.atom 10 author date}}

=== Known Bugs and Issues ===

All bugs & issues are being tracked in the [[https://github.com/JovinJovinsson/dokuwiki-plugin-navbox/issues|GitHub repository]].

=== ToDo/Wish List ===

**Up Next**
  * Table background colour parameter
  * Table width parameter
  * Image column (similar to Wikipedia screenshot at the top of the page)

**Soon**
  * Automatic population of current hierarchy of page/namespaces

**Long Term**
  * Discovery of pages with shared 'tags' and categorize them (Scope to be defined)

===== FAQ =====

None yet!

===== Discussion =====

Please log any discussion points [[plugin:navbox:discussion|here]].