xref: /template/mikio/README.md (revision d0d6c4508842277934722d6eacd1ce1e1e598fb5)

# Mikio DokuWiki Template

![screenshot](https://github.com/nomadjimbob/mikio/blob/main/images/screenshot.png)

## About

`Mikio` is a Bootstrap 4 style template for [DokuWiki](http://dokuwiki.org)

## Features

-   [bootstrap styling](http://getbootstrap.com/)
-   Navbar with dropdown support
-   Subnavbar support (using a page named submenu)
-   Right sidebar
-   Hero element
-   Icon support
-   Customizable breadcrumbs
-   Theming support
-   Tags plugin support
-   Mobile friendly
-   Typeahead search support

## Possible Breaking Changes

-   2023-05-13

    -   Table styling had a long-standing bug found by RonaldPR which has been fixed. This fix may require updating the styling if your website was relying on this bug.

-   2022-10-04

    -   Some elements now have their own color options to allow finer control of your website design.

-   2022-04-25

    -   Added support for the defer js option in Hogsfather to override the templates default defer action of always.
    -   The new Typeahead search feature is enabled by default. This can be turned off in the config.

-   2022-03-05

    -   Breadcrumbs and You Are Here have now been seperated instead of combined. This removed the options `breadcrumbHome` and `breadcrumbShowLast` for the breadcrumbs as it only applies to the you are here bar. **Breadcrumbs and You Are Here options may have reset**

-   2020-09-27
    -   Sidebars now collapse by default on mobile. This can be overridden with the `sidebarMobileDefaultCollapse` option
    -   The mikio LESS stylesheet is now disabled by default, with a precompilied CSS used. This can be reverted using the `useLESS` option

## Incompadibilities

**Comment Syntax support** converts custom control macros such as the Mikio macro `~~hero-image ...~~` into comments. If you plan to use this extension on your site, you will need to use the alternative macro format of `-~hero-image ...~-` for Mikio to detect the information.

## Configuration

The configuration can be change with the [Configuration Manager Plugin](https://www.dokuwiki.org/plugin:config)

-   `iconTag` : icon tag to use to engage the icon engine. Default to `icon`
-   `customTheme` : the mikio theme to use, located in the `mikio/themes` directory
-   `showNotifications` : where to show site notifications for admin staff
-   `useLESS` : use the LESS compilier or direct CSS for the mikio stylesheet. Requires the ctype PHP extension installed
-   `brandURLGuest` : change the brand URL for guests. Leave blank to use the default
-   `brandURLUser` : change the brand URL for logged in users. Leave blank to use the default

-   `navbarUseTitleIcon` : show the site logo in the navbar
-   `navbarUseTitleText` : show the site title in the navbar
-   `navbarUseTaglineText` : show the site tagline in the navbar. Requires the `navbarUseTitleText` to be enabled
-   `navbarCustomMenuText` : custom menu to use in the navbar. Menu items are in the format of url|title with each item seperated by a semicolon. Requires one of the `navbarPos` to be set to `custom`

-   `navbarDWMenuType` : how to show the DokuWiki menu items in the navbar. Can be either icons, text or both
-   `navbarDWMenuCombine` : how to show the DokuWiki menu in the navbar. Can be either category dropdowns, single items or a combined dropdown. The combined menu title is pulled from the `tools-menu` language value

-   `navbarPosLeft` : what menu to show on the left of the navbar
-   `navbarPosMiddle` : what menu to show in the middle of the navbar
-   `navbarPosRight` : what menu to show on the right of the navbar
-   `navbarShowSub` : show the sub navbar. This menu is pulled from the `submenu` page in the current or parent namespaces. The menu is also shown on child pages. If no page is found, the sub navbar is automatically hidden

-   `navbarItemShowCreate` : show the Create Page menu item
-   `navbarItemShowShow` : show the Show Page menu item
-   `navbarItemShowRevs` : show the Revisions menu item
-   `navbarItemShowBacklink` : show the Backlinks menu item
-   `navbarItemShowRecent` : show the Recent Changes menu item
-   `navbarItemShowMedia` : show the Media Manager menu item
-   `navbarItemShowIndex` : show the Sitemap menu item
-   `navbarItemShowProfile` : show the Update Profile menu item
-   `navbarItemShowAdmin` : show the Admin menu item
-   `navbarItemShowLogin` : show the Login menu item
-   `navbarItemShowLogout` : show the Logout menu item

-   `searchButton` : show the search button as a icon or text
-   `searchUseTypeahead` : use [Typeahead](https://github.com/bassjobsen/Bootstrap-3-Typeahead) page suggestions in search bar

-   `heroTitle` : show the hero block on pages
-   `heroImagePropagation` : search for hero images in parent namespaces if none is found in the current namespace

-   `tagsConsolidate` : Consolidate tags found in the current page and display it in the hero, content header or sidebar

-   `breadcrumbHideHome` : hide breadcrumbs in the root namespace
-   `breadcrumbPosition` : where to display the breadcrumbs, either under the navbar, in the hero element or above the page content
-   `breadcrumbPrefix` : enable changing the breadcrumb prefix
-   `breadcrumbPrefixText` : text to set the breadcrumb prefix. Requires `breadcrumbPrefix` to be enabled
-   `breadcrumbSep` : enable changing the breadcrumb seperator
-   `breadcrumbSepText` : text to set the breadcrumb seperator. Requires `breadcrumbSep` to be enabled

-   `youarehereHideHome` : hide you are here in the root namespace
-   `youareherePosition` : where to display the you are here, either under the navbar, in the hero element or above the page content
-   `youareherePrefix` : enable changing the you are here prefix
-   `youareherePrefixText` : text to set the you are here prefix. Requires `you are herePrefix` to be enabled
-   `youarehereSep` : enable changing the you are here seperator
-   `youarehereSepText` : text to set the you are here seperator. Requires `you are hereSep` to be enabled
-   `youarehereHome` : change the you are here home item to none, page title of root page, 'home' or an icon/image. The 'home' text is pulled from the `home` language value
-   `youarehereShowLast` : only show an amount of you are here from the last. Will also show the home item in the list if enabled. Set this to `0` to show all items

-   `sidebarShowLeft` : show the left sidebar if content is found
-   `sidebarLeftRow1` : content to show in the first row of the left sidebar
-   `sidebarLeftRow2` : content to show in the second row of the left sidebar
-   `sidebarLeftRow3` : content to show in the third row of the left sidebar
-   `sidebarLeftRow4` : content to show in the forth row of the left sidebar
-   `sidebarMobileDefaultCollapse` : collapse the sidebars by default when viewed on mobile
-   `sidebarShowRight` : show the right sidebar if content is found

-   `tocFull` : show the table of contents as a full height item

-   `pageToolsFloating` : when and if to show the floating page tools
-   `pageToolsFooter`

-   `pageToolsShowCreate` : show the Create Page item
-   `pageToolsShowEdit` : show the Edit Page item
-   `pageToolsShowRevs` : show the Revisions item
-   `pageToolsShowBacklink` : show the Backlinks item
-   `pageToolsShowTop` : show the Back to Top item

-   `footerCustomMenuText` : custom menu to use in the footer. Menu items are in the format of url|title with each item seperated by a semicolon
-   `footerSearch` : show the search bar in the footer

-   `licenseType` : how to show the license in the footer
-   `licenseImageOnly` : show the license in the footer as an image only. Requires `licenseType` to at least be enabled

-   `includePageUseACL` : respect ACL when including pages
-   `includePagePropagate` : search parent namespaces when including pages

## Include Pages

The following pages can be either html files in the root of the template or a page in the namespace. Namespace pages take priority.

-   `topheader` : content to include above the navbar
-   `header` : content include below the navbar but above the page content
-   `contentheader` : content to include above the page content
-   `contentfooter` : content to include below the page content
-   `sidebarheader` : content to include above the left sidebar content
-   `sidebarfooter` : content to include below the left sidebar content
-   `rightsidebarheader` : content to include above the right sidebar content
-   `rightsidebarfooter` : content to include below the right sidebar content
-   `footer` : content to include in the footer
-   `bottomfooter` : content to include below the footer

## Include Images

The following images can be used to replace content in the
template. Images can be in `TEMPLATE_ROOT/images/`,
`TEMPLATE_ROOT/themes/THEME/images/`, or in the namespace. Images can
be either png, jpg, gif or svg.

-   `logo` : site logo in the navbar
-   `breadcrumb-prefix` breadcrumb prefix
-   `breadcrumb-sep` breadcrumb seperator
-   `hero` hero image for hero element

## Hero Element

-   `title` : The hero title is sourced from the page title. The page title is removed from the page content
-   `subtitle` : Pages can set the subtitle by inserting `~~hero-subtitle TEXT~~` in the page content
-   `image` : The hero image is sourced from an image named hero in the current or parental namespace. Namespace searching can be confined by the `includePagePropagate` setting. Pages can also override the image by inserting `~~hero-image URL~~` in the page content. DokuWiki and external URLs are supported
-   `colors` : Colors can be overridden by including `~~hero-colors BACKGROUND_COLOR HERO_TITLE_COLOR HERO_SUBTITLE_COLOR BREADCRUMB_TEXT_COLOR BREADCRUMB_HOVER_COLOR~~`. You do not need to include all the color options. Use 'initial' to skip a color override

Namespaces can also apply the above hero settings in child pages by including the above settings in a page named `theme`.

## Hiding Elements

Mikio now supports hiding elements using the `~~hide-parts (parts)~~` macro. Each element within the hide-parts macro is required to be seperated by spaces. Currently the following parts are supported:

-   `topheader` : content above the navbar
-   `navbar` : the main navigation bar
-   `header` : content below the navbar but above the page content
-   `hero` : the page hero bar
-   `contentheader` : content above the page content
-   `contentfooter` : content below the page content
-   `sidebarheader` : content above the left sidebar content
-   `sidebarfooter` : content below the left sidebar content
-   `rightsidebarheader` : content above the right sidebar content
-   `rightsidebarfooter` : content below the right sidebar content
-   `footer` : content in the footer
-   `bottomfooter` : content below the footer

To hide the topheader, navbar and hero, you would use the macro `~~hide-parts topheader navbar hero~~`

## Icon Engine

-   Mikio includes an icon engine that allows you to include icons in your pages by using <icon OPTIONS> in your content
-   If the icon tag conflicts with another plugin, you can change the tag from `icon` to a user set value in the settings
-   By default, Mikio enables FontAwesome 4 by also includes FontAwesome 5, Elusive 2 and Bootstrap Icons which can be enabled by uncommenting their inclusions in `/icons/icons.php`

Users can also add their own icon sets into the template. Supported icon sets can either be webfonts or indivial files (such as a SVG library). Instructions can be found in the `/icons/icons.php` file.

## Themes

Themes should be placed in the themes directory, in its own directory. LESS files are supported.

## Dark Mode

Mikio now supports dark mode! When the user prefers a dark theme, or has selected dark mode, the html tag will set the theme dataset to `theme-dark`, else it will be `theme-light`.

You can detect this in CSS using:

```
:root[data-theme="theme-dark"] {
  // CSS selectors here
}
```

or in Javascript using:

```
const html = document.querySelector('html');
if(html.dataset.theme == 'theme-dark') {
  // ...
}
```

## Mikio Plugin

The [Mikio Plugin](https://github.com/nomadjimbob/mikioplugin/) is also available to add bootstrap 4 style + more elements to DokuWiki pages.

If the plugin is installed, the **Template Styles Settings** page will be expanded to allow directly editing the plugin element styling.

## Languages

-   `sidebar-title` : Text for the collapsable block in the sidebar
-   `tools-menu` : Text for the combined tools DokuWiki menu title
-   `home` : Text for the breadcrumb home title

## Releases

-   **_NEXT_**

    -   Mikio Control Macros now support the format `-~SETTING~-` as well as the standard `~~SETTING~~`. This fixes an incompatibility with the [Comment Syntax support](https://www.dokuwiki.org/plugin:commentsyntax) extension.

-   **_2023-05-19_**

    -   Fixed notifications appearing in weird places at times.
    -   Setting `tpl»mikio»showNotifications` to an empty string is the same as setting it to `always`.
    -   Fixed languages not shown in dropdown correctly with the translate plugin when `plugin»translation»dropdown` is turned on.
    -   Fixed some css issues on small screens.

-   **_2023-05-18_**

    -   Added automatic Light/Dark mode option (disabled by default).
    -   Added support for the [translate plugin](https://www.dokuwiki.org/plugin:translation).

-   **_2023-05-13_**

    -   Fixed tables not being styling correctly and incorrect language used in the styling config [#50](https://github.com/nomadjimbob/mikio/issues/50). Thanks RonaldPR.
    -   The themes LessC engine will output any exceptions that occur in the fallback CSS to help track issues.

-   **_2023-05-11_**

    -   Fixed empty scrollbars being shown when TOC is set to full height [#49](https://github.com/nomadjimbob/mikio/issues/49). Thanks vitaprimo and RonaldPR.
    -   Added a `noshadow` subtheme

-   **_2022-10-31_**

    -   Added support to directly editing Mikio Plugin within Template Style Settings.

-   **_2022-10-12_**

    -   Fixed blank page being displayed instead of media detail [#48](https://github.com/nomadjimbob/mikio/issues/48). Thanks spratinatin

-   **_2022-10-09_**

    -   Fixed issue of new elements not being added to CSS when a custom template style is set
    -   Fixed issue of wiki page style (existing and missing) not taking priority of link colouring
    -   Added support for styling link pseudo classes (visited, hover, active) for links and page links [#47](https://github.com/nomadjimbob/mikio/issues/47). Thanks chrbinder

-   **_2022-10-04_**

    -   Cleaned up the code to PHPCS standards
    -   Fixed breadcrumb layouts on mobile [#31](https://github.com/nomadjimbob/mikio/issues/31)
    -   Fixed Media Manager on small displays
    -   Fixed layout compatiblity on Greebo
    -   Fixed search results layout [#41](https://github.com/nomadjimbob/mikio/issues/41)
    -   Added Dark-mode support [#43](https://github.com/nomadjimbob/mikio/issues/43). Thanks chrbinder
    -   Fixed incorrect file names listed [#45](https://github.com/nomadjimbob/mikio/issues/45). Thanks babudro
    -   Fixed sidebars not showing [#46](https://github.com/nomadjimbob/mikio/issues/46). Thanks dasbenjo

-   **_2022-05-10_**

    -   Added support to directly set title icon width and height in config. Thanks AlexiaR

-   **_2022-05-05_**

    -   Fixed searching for images in the theme directory [#42](https://github.com/nomadjimbob/mikio/issues/42). Thanks cmacmackin
    -   Added support for the defer js option, previously always deferred [#39](https://github.com/nomadjimbob/mikio/issues/39). Thanks cmacmackin
    -   Added typeahead search [#40](https://github.com/nomadjimbob/mikio/issues/40). Thanks cmacmackin
    -   Fixed double breadcrumb options on admin pages
    -   Added sticky top header, navbar and header options. Thanks chitland

-   **_2022-03-05_**

    -   Fixed page tools in footer not being horizontal [#38](https://github.com/nomadjimbob/mikio/issues/38). Thanks chitland
    -   Fixed Mikio Config headers disappearing in some cases
    -   Separated Breadcrumbs and You Are Here items [#36](https://github.com/nomadjimbob/mikio/issues/36). Thanks chitland

-   **_2021-12-11_**

    -   Added table row background styling options
    -   Fixed styling issue when using the indexmenu plugin [#35](https://github.com/nomadjimbob/mikio/issues/35). Thanks 3ole.
    -   Fixed inconsitant tab/spaces in mikio.less and mikio.css
    -   Removed debug logs from mikio.js
    -   Fixed input placeholders not hiding in prepopulated fields [#34](https://github.com/nomadjimbob/mikio/issues/34)
    -   Added option to hide menu and page tool items [#32](https://github.com/nomadjimbob/mikio/issues/32). Thanks annievoss.
    -   Fixed compadibility with BookCreator [#26](https://github.com/nomadjimbob/mikio/issues/26). Thanks johncourtland.
    -   Fixed Greebo styling errors not present in Hogsfather

-   **_2021-08-11_**

    -   Fixed path check on Windows [#33](https://github.com/nomadjimbob/mikio/issues/33)
    -   Recompilied CSS

-   **_2021-06-17_**

    -   Added support for navbar title link to use showpageafterlogin setting if installed [#27](https://github.com/nomadjimbob/mikio/issues/27)

-   **_2021-06-09_**

    -   TOC is now full width on mobile [#25](https://github.com/nomadjimbob/mikio/issues/25)
    -   Hamburger and sidebar icons are now displayed correctly [#23](https://github.com/nomadjimbob/mikio/issues/23), [#24](https://github.com/nomadjimbob/mikio/issues/24)
    -   Site width is now available under Template Style Settings [#22](https://github.com/nomadjimbob/mikio/issues/22)
    -   TOC is now sticky when set to full height [#21](https://github.com/nomadjimbob/mikio/issues/21)
    -   Added support to the theme being linked by a symbolic link [#20](https://github.com/nomadjimbob/mikio/issues/20)
    -   Mikio will now fallback to using CSS when there is the LESS engine is not detected [#20](https://github.com/nomadjimbob/mikio/issues/20)

-   **_2021-03-10_**

    -   Fixed bad breadcrumb URL formatting on sites using userewrite [#19](https://github.com/nomadjimbob/mikio/issues/19)

-   **_2021-03-04_**

    -   Added support to hide page elements [#18](https://github.com/nomadjimbob/mikio/issues/18)

-   **_2021-01-22_**

    -   Fixed a syntax error with the core css

-   **_2020-11-12_**

    -   Corrected terminology in readme to match Dokuwiki [#17](https://github.com/nomadjimbob/mikio/issues/17)
    -   Fix showing part of the sidebar when it should be hidden in certain conditions [#16](https://github.com/nomadjimbob/mikio/issues/16)
    -   Added option to always show the sidebar, even when there is no content [#16](https://github.com/nomadjimbob/mikio/issues/16)

-   **_2020-10-07_**

    -   Fixed hero header parsing on some servers
    -   Fixed safari color picker issue [#14](https://github.com/nomadjimbob/mikio/issues/14)
    -   LESS now defaults to enabled with fallback to ctype functions built into mikio for docker apps [#13](https://github.com/nomadjimbob/mikio/issues/13)
    -   Fix for Template Style Settings being ignored [#12](https://github.com/nomadjimbob/mikio/issues/12)

-   **_2020-10-01_**

    -   Fix for `sidebarMobileDefaultCollapse` option being inconsistent in code and not working correctly [#11](https://github.com/nomadjimbob/mikio/issues/11). Thanks to GJRobert for catching that.

-   **_2020-09-27_**

    -   Sidebars hidden by default in mobile view [#10](https://github.com/nomadjimbob/mikio/issues/10)
    -   Fixed errors with the LESS compilier on some nginx configurations
    -   Fixed styling and image display thumb size in media manager popup
    -   Fixed text field placeholders not disappearing with text entry
    -   Added support for Hogfather
    -   Added option to use LESS or direct CSS. Some configurations (docker linuxserver/dokuwiki) do not have the required PHP extensions installed
    -   Supports Docker linuxserver/dokuwiki container file structures

-   **_2020-09-10_**

    -   Floating page tools is now a UL element with classes applied from getType and getLinkAttributes. Fixes popup dialogs initiated from the a page menu [#7](https://github.com/nomadjimbob/mikio/issues/7)
    -   Template.info.txt now shows correct release dates [#8](https://github.com/nomadjimbob/mikio/issues/8)
    -   Fixed rightsidebar php warnings
    -   Code/Pre blocks no longer have padding applied on the admin pages

-   **_2020-08-26_**

    -   Footer is no longer shown outside of page view
    -   Public messages are now displayed on the page
    -   Fixed icon rendering in hero bar
    -   Fixed TOC rendering bug

-   **_2020-07-27_**

    -   Added option to show wiki footer in page content

-   **_2020-07-24_**

    -   Fixed image detail bug

-   **_2020-07-20_**

    -   Fixed prewrap and sidebar search bar margins

-   **_2020-07-16_**

    -   Merged code block styling with pre
    -   Fixed mediamanager failures on 2018-04-22a "Greebo" [#5](https://github.com/nomadjimbob/mikio/issues/5)
    -   Icon tag is rendered correctly in preview [#4](https://github.com/nomadjimbob/mikio/issues/4)

-   **_2020-07-15_**

    -   Fixed an issue with the simple_html_dom library when editing a section of a page caused page corruption [#3](https://github.com/nomadjimbob/mikio/issues/3)

-   **_2020-07-14_**

    -   Added id=dokuwiki\_\_content identifier for the page content element
    -   Added styling and fixed overflow issues with pre elements
    -   Fixed page width overflow issues

-   **_2020-07-09_**

    -   Fixed cosmetic display issues when `input[type=file]` is hidden by plugins [#2](https://github.com/nomadjimbob/mikio/issues/2)

-   **_2020-07-07_**
    -   Initial release

## Third Party Libraries

This template uses a [modified
version](https://github.com/nomadjimbob/simple_html_dom) of
[simple_html_dom](https://sourceforge.net/projects/simplehtmldom/) and
[bootstrap-3-typeahead](https://github.com/bassjobsen/Bootstrap-3-Typeahead).

## Support

-   If you think you have found a problem, or would like to see a feature, please [open an issue](https://github.com/nomadjimbob/mikio/issues)
-   If you are a coder, feel free to create a pull request, but please be detailed about your changes!