DokuWiki

You've loaded an old revision of the document! If you save it, you will create a new version with this data.

====== Mikio Template ======

---- template ----
description   : Mikio is a Bootstrap 4 style template with a hero element and dark mode support
author        : nomadjimbob
email         : james.collins@outlook.com.au
lastupdate_dt : 2023-06-05
compatible    : Igor, Hogfather, Greebo, Jack Jackrum
depends       :
conflicts     : # prefix templates by template:
similar       :
screenshot_img: https://raw.githubusercontent.com/nomadjimbob/mikio/master/images/screenshot.png
tags          : bootstrap, responsive, sidebar, modern, clean, css3, customizable, dark, dark-mode, mobile, print, semantic, themes, hero

downloadurl   : https://github.com/nomadjimbob/mikio/zipball/master
bugtracker    : https://github.com/nomadjimbob/mikio/issues
sourcerepo    : https://github.com/nomadjimbob/mikio/
----

The 2023-05-13 update fixes a long-standing table styling bug found by RonaldPR. This fix may require updating the styling if your website was relying on this bug.

===== Features =====

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

===== Breadcrumb/You Are Here Change =====

* Breadcrumbs and You Are Here have now been separated 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**

===== Configuration =====

* ''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.
  * ''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

* ''searchButton'' : show the search button as a icon or text
  * ''searchUseTypeahead'' : use [[https://github.com/bassjobsen/Bootstrap-3-Typeahead|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. This replaces the default [[:breadcrumbs#breadcrumb prefixes]] ''Trace:'' for [[:breadcrumbs#tracking breadcrumbs]] and ''You are here:'' for [[:breadcrumbs#hierarchical breadcrumbs]] (including the punctuation) which as of July 2021 cannot be customized by means of the [[:plugin:config|Configuration Manager]] but only within the scope of a [[:template]].
  * ''breadcrumbSep'' : enable changing the breadcrumb seperator
  * ''breadcrumbSepText'' : text to set the breadcrumb seperator. Requires ''breadcrumbSep'' to be enabled
  * ''breadcrumbHome'' : change the breadcrumb home item to none, page title of root page, 'home' or an icon/image. The 'home' text is pulled from the ''home'' language value
  * ''breadcrumbShowLast'' : only show a number of breadcrumbs 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
  * ''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'' : when and if to show page tools in the footer

* ''footerCustomMenuText'' : custom menu to use in the footer. Menu items are in the format of url|title with each item separated 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''.

If the page title is not being displayed in the Hero, make sure that you have correctly set the DokuWiki [[config:useheading]] setting.

===== Hiding Elements =====

Mikio now supports hiding elements using the ''~~hide-parts (parts)~~'' macro. Each element within the hide-parts macro is required to be separated 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 but 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 to the template. Supported icon sets can either be webfonts or individual 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 their 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:

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

or in Javascript using:

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

===== Mikio Plugin =====

The [[plugin:mikioplugin|Mikio Plugin]] 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 =====

==== 2023-06-05 ====
  * Fixed bug with `~~hide-parts~~` no longer working [[https://github.com/nomadjimbob/mikio/issues/52|#52]]. Thanks nathanmcguire.
  * Mikio Control Macros now support the format `-~SETTING~-` as well as the standard `~~SETTING~~`. This fixes an incompatibility with the [[https://www.dokuwiki.org/plugin:commentsyntax|Comment Syntax support]] 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 [[plugin:translation|translate plugin]].

==== 2023-05-13 ====
  * Fixed tables not being styling correctly and incorrect language used in the styling config [[https://github.com/nomadjimbob/mikio/issues/50|#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 [[https://github.com/nomadjimbob/mikio/issues/49|#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 ====

* Removed green debug background that can be seen on slower connections
  * Fixed blank page being displayed instead of media detail [[https://github.com/nomadjimbob/mikio/issues/48|#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 [[https://github.com/nomadjimbob/mikio/issues/47|#47]]. Thanks chrbinder

==== 2022-10-04 ====
  * Cleaned up the code to PHPCS standards
  * Fixed breadcrumb layouts on mobile [[https://github.com/nomadjimbob/mikio/issues/31|#31]]
  * Fixed Media Manager on small displays
  * Fixed layout compatibility on Greebo
  * Fixed search results layout [[https://github.com/nomadjimbob/mikio/issues/41|#41]]
  * Added Dark-mode support [[https://github.com/nomadjimbob/mikio/issues/43|#43]]. Thanks chrbinder
  * Fixed incorrect file names listed [[https://github.com/nomadjimbob/mikio/issues/45|#45]]. Thanks babudro
  * Fixed sidebars not showing [[https://github.com/nomadjimbob/mikio/issues/46|#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 [[https://github.com/nomadjimbob/mikio/issues/42|#42]]. Thanks cmacmackin
  * Added support for the defer js option, previously always deferred [[https://github.com/nomadjimbob/mikio/issues/39|#39]]. Thanks cmacmackin
  * Added typeahead search [[https://github.com/nomadjimbob/mikio/issues/40|#40]]. Thanks cmacmackin
  * Fixed double breadcrumb options on admin pages
  * Added sticky top header, navbar and header options. Thanks chitland

You can view older change release notes on the [[https://github.com/nomadjimbob/mikio/|Github project page]].

===== Third Party Libraries =====

This template uses a [[https://github.com/nomadjimbob/simple_html_dom|modified version]] of [[https://sourceforge.net/projects/simplehtmldom/|simple_html_dom]]

===== Support =====

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

===== Applause =====
This is really a modern, complete template, with very high flexibility and customizability. (Look at those options to customize for style.ini!) Also it's the first template I have seen with "Hero element" support. And there are quite a few positions to insert included pages as page/content header/footers. I appreciate the great work of the developer.  --- [[user>MilchFlasche|milchflasche]] //2020-07-30 03:42//
> I have used this template in my two language learning sites: http://taigi123.ga/ http://hakka123.ga/ (written in some East Asian languages and Hanzi script) --- [[user>MilchFlasche|milchflasche]] //2020-09-17 04:58//

===== Feature requests =====
  * collapsable sidebar toggle --- [[user>dodotori|dodotori]] //2023-09-05 16:32//

Please fill all the letters into the box to prove you're human. N O S L J Please keep this field empty:

Edit summary

Note: By editing this page you agree to license your content under the following license: CC Attribution-Share Alike 4.0 International