1# Mikio DokuWiki Template 2 3 4 5## About 6 7`Mikio` is a Bootstrap 4 style template for [DokuWiki](http://dokuwiki.org) 8 9## Features 10 11- [bootstrap styling](http://getbootstrap.com/) 12- Navbar with dropdown support 13- Subnavbar support (using a page named submenu) 14- Right sidebar 15- Hero element 16- Icon support 17- Customizable breadcrumbs 18- Theming support 19- Tags plugin support 20- Mobile friendly 21- Typeahead search support 22 23## Possible Breaking Changes 24 25- 2023-05-13 26 27 - 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. 28 29- 2022-10-04 30 31 - Some elements now have their own color options to allow finer control of your website design. 32 33- 2022-04-25 34 35 - Added support for the defer js option in Hogsfather to override the templates default defer action of always. 36 - The new Typeahead search feature is enabled by default. This can be turned off in the config. 37 38- 2022-03-05 39 40 - 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** 41 42- 2020-09-27 43 - Sidebars now collapse by default on mobile. This can be overridden with the `sidebarMobileDefaultCollapse` option 44 - The mikio LESS stylesheet is now disabled by default, with a precompilied CSS used. This can be reverted using the `useLESS` option 45 46## Incompatibilities 47 48**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. 49 50## Configuration 51 52The configuration can be change with the [Configuration Manager Plugin](https://www.dokuwiki.org/plugin:config) 53 54- `iconTag` : icon tag to use to engage the icon engine. Default to `icon` 55- `customTheme` : the mikio theme to use, located in the `mikio/themes` directory 56- `showNotifications` : where to show site notifications for admin staff 57- `useLESS` : use the LESS compilier or direct CSS for the mikio stylesheet. Requires the ctype PHP extension installed 58- `brandURLGuest` : change the brand URL for guests. Leave blank to use the default 59- `brandURLUser` : change the brand URL for logged in users. Leave blank to use the default 60 61- `navbarUseTitleIcon` : show the site logo in the navbar 62- `navbarUseTitleText` : show the site title in the navbar 63- `navbarUseTaglineText` : show the site tagline in the navbar. Requires the `navbarUseTitleText` to be enabled 64- `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` 65 66- `navbarDWMenuType` : how to show the DokuWiki menu items in the navbar. Can be either icons, text or both 67- `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 68 69- `navbarPosLeft` : what menu to show on the left of the navbar 70- `navbarPosMiddle` : what menu to show in the middle of the navbar 71- `navbarPosRight` : what menu to show on the right of the navbar 72- `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 73 74- `navbarItemShowCreate` : show the Create Page menu item 75- `navbarItemShowShow` : show the Show Page menu item 76- `navbarItemShowRevs` : show the Revisions menu item 77- `navbarItemShowBacklink` : show the Backlinks menu item 78- `navbarItemShowRecent` : show the Recent Changes menu item 79- `navbarItemShowMedia` : show the Media Manager menu item 80- `navbarItemShowIndex` : show the Sitemap menu item 81- `navbarItemShowProfile` : show the Update Profile menu item 82- `navbarItemShowAdmin` : show the Admin menu item 83- `navbarItemShowLogin` : show the Login menu item 84- `navbarItemShowLogout` : show the Logout menu item 85 86- `searchButton` : show the search button as a icon or text 87- `searchUseTypeahead` : use [Typeahead](https://github.com/bassjobsen/Bootstrap-3-Typeahead) page suggestions in search bar 88 89- `heroTitle` : show the hero block on pages 90- `heroImagePropagation` : search for hero images in parent namespaces if none is found in the current namespace 91 92- `tagsConsolidate` : Consolidate tags found in the current page and display it in the hero, content header or sidebar 93 94- `breadcrumbHideHome` : hide breadcrumbs in the root namespace 95- `breadcrumbPosition` : where to display the breadcrumbs, either under the navbar, in the hero element or above the page content 96- `breadcrumbPrefix` : enable changing the breadcrumb prefix 97- `breadcrumbPrefixText` : text to set the breadcrumb prefix. Requires `breadcrumbPrefix` to be enabled 98- `breadcrumbSep` : enable changing the breadcrumb seperator 99- `breadcrumbSepText` : text to set the breadcrumb seperator. Requires `breadcrumbSep` to be enabled 100 101- `youarehereHideHome` : hide you are here in the root namespace 102- `youareherePosition` : where to display the you are here, either under the navbar, in the hero element or above the page content 103- `youareherePrefix` : enable changing the you are here prefix 104- `youareherePrefixText` : text to set the you are here prefix. Requires `you are herePrefix` to be enabled 105- `youarehereSep` : enable changing the you are here seperator 106- `youarehereSepText` : text to set the you are here seperator. Requires `you are hereSep` to be enabled 107- `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 108- `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 109 110- `sidebarShowLeft` : show the left sidebar if content is found 111- `sidebarLeftRow1` : content to show in the first row of the left sidebar 112- `sidebarLeftRow2` : content to show in the second row of the left sidebar 113- `sidebarLeftRow3` : content to show in the third row of the left sidebar 114- `sidebarLeftRow4` : content to show in the forth row of the left sidebar 115- `sidebarMobileDefaultCollapse` : collapse the sidebars by default when viewed on mobile 116- `sidebarShowRight` : show the right sidebar if content is found 117 118- `tocFull` : show the table of contents as a full height item 119 120- `pageToolsFloating` : when and if to show the floating page tools 121- `pageToolsFooter` 122 123- `pageToolsShowCreate` : show the Create Page item 124- `pageToolsShowEdit` : show the Edit Page item 125- `pageToolsShowRevs` : show the Revisions item 126- `pageToolsShowBacklink` : show the Backlinks item 127- `pageToolsShowTop` : show the Back to Top item 128 129- `footerCustomMenuText` : custom menu to use in the footer. Menu items are in the format of url|title with each item seperated by a semicolon 130- `footerSearch` : show the search bar in the footer 131 132- `licenseType` : how to show the license in the footer 133- `licenseImageOnly` : show the license in the footer as an image only. Requires `licenseType` to at least be enabled 134 135- `includePageUseACL` : respect ACL when including pages 136- `includePagePropagate` : search parent namespaces when including pages 137 138## Include Pages 139 140The following pages can be either html files in the root of the template or a page in the namespace. Namespace pages take priority. 141 142- `topheader` : content to include above the navbar 143- `header` : content include below the navbar but above the page content 144- `contentheader` : content to include above the page content 145- `contentfooter` : content to include below the page content 146- `sidebarheader` : content to include above the left sidebar content 147- `sidebarfooter` : content to include below the left sidebar content 148- `rightsidebarheader` : content to include above the right sidebar content 149- `rightsidebarfooter` : content to include below the right sidebar content 150- `footer` : content to include in the footer 151- `bottomfooter` : content to include below the footer 152 153## Include Images 154 155The following images can be used to replace content in the 156template. Images can be in `TEMPLATE_ROOT/images/`, 157`TEMPLATE_ROOT/themes/THEME/images/`, or in the namespace. Images can 158be either png, jpg, gif or svg. 159 160- `logo` : site logo in the navbar 161- `breadcrumb-prefix` breadcrumb prefix 162- `breadcrumb-sep` breadcrumb seperator 163- `hero` hero image for hero element 164 165## Hero Element 166 167- `title` : The hero title is sourced from the page title. The page title is removed from the page content 168- `subtitle` : Pages can set the subtitle by inserting `~~hero-subtitle TEXT~~` in the page content 169- `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. The height of the image area is 240px while the width is 33% of the window width. It is recommended to use an image of at least 480x240 (2:1) 170- `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 171 172Namespaces can also apply the above hero settings in child pages by including the above settings in a page named `theme`. 173 174## Hiding Elements 175 176Mikio 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: 177 178- `topheader` : content above the navbar 179- `navbar` : the main navigation bar 180- `header` : content below the navbar but above the page content 181- `hero` : the page hero bar 182- `contentheader` : content above the page content 183- `contentfooter` : content below the page content 184- `sidebarheader` : content above the left sidebar content 185- `sidebarfooter` : content below the left sidebar content 186- `rightsidebarheader` : content above the right sidebar content 187- `rightsidebarfooter` : content below the right sidebar content 188- `footer` : content in the footer 189- `bottomfooter` : content below the footer 190 191To hide the topheader, navbar and hero, you would use the macro `~~hide-parts topheader navbar hero~~` 192 193## Icon Engine 194 195- Mikio includes an icon engine that allows you to include icons in your pages by using <icon OPTIONS> in your content 196- If the icon tag conflicts with another plugin, you can change the tag from `icon` to a user set value in the settings 197- 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` 198 199Users 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. 200 201## Themes 202 203Themes should be placed in the themes directory, in its own directory. LESS files are supported. 204 205## Dark Mode 206 207Mikio 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`. 208 209You can detect this in CSS using: 210 211``` 212:root[data-theme="theme-dark"] { 213 // CSS selectors here 214} 215``` 216 217or in Javascript using: 218 219``` 220const html = document.querySelector('html'); 221if(html.dataset.theme == 'theme-dark') { 222 // ... 223} 224``` 225 226## Mikio Plugin 227 228The [Mikio Plugin](https://github.com/nomadjimbob/mikioplugin/) is also available to add bootstrap 4 style + more elements to DokuWiki pages. 229 230If the plugin is installed, the **Template Styles Settings** page will be expanded to allow directly editing the plugin element styling. 231 232## Languages 233 234- `sidebar-title` : Text for the collapsable block in the sidebar 235- `tools-menu` : Text for the combined tools DokuWiki menu title 236- `home` : Text for the breadcrumb home title 237 238## Releases 239 240- **_2023-10-20_** 241 242 - Fixed LESS engine not being discovered when DokuWiki is hosted in a sub directory. Thanks Jan. 243 244- **_2023-10-16_** 245 246 - Added color picker selector back to style page. Requested by Jan. 247 248- **_2023-10-14_** 249 250 - Fixed bug where external page tools where not showing in the tool bar. Thanks Jan. 251 252- **_2023-06-05_** 253 254 - Fixed bug with `~~hide-parts~~` no longer working. [#52](https://github.com/nomadjimbob/mikio/issues/52). Thanks nathanmcguire. 255 - 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. 256 257- **_2023-05-19_** 258 259 - Fixed notifications appearing in weird places at times. 260 - Setting `tpl»mikio»showNotifications` to an empty string is the same as setting it to `always`. 261 - Fixed languages not shown in dropdown correctly with the translate plugin when `plugin»translation»dropdown` is turned on. 262 - Fixed some css issues on small screens. 263 264- **_2023-05-18_** 265 266 - Added automatic Light/Dark mode option (disabled by default). 267 - Added support for the [translate plugin](https://www.dokuwiki.org/plugin:translation). 268 269- **_2023-05-13_** 270 271 - Fixed tables not being styling correctly and incorrect language used in the styling config [#50](https://github.com/nomadjimbob/mikio/issues/50). Thanks RonaldPR. 272 - The themes LessC engine will output any exceptions that occur in the fallback CSS to help track issues. 273 274- **_2023-05-11_** 275 276 - Fixed empty scrollbars being shown when TOC is set to full height [#49](https://github.com/nomadjimbob/mikio/issues/49). Thanks vitaprimo and RonaldPR. 277 - Added a `noshadow` subtheme 278 279- **_2022-10-31_** 280 281 - Added support to directly editing Mikio Plugin within Template Style Settings. 282 283- **_2022-10-12_** 284 285 - Fixed blank page being displayed instead of media detail [#48](https://github.com/nomadjimbob/mikio/issues/48). Thanks spratinatin 286 287- **_2022-10-09_** 288 289 - Fixed issue of new elements not being added to CSS when a custom template style is set 290 - Fixed issue of wiki page style (existing and missing) not taking priority of link colouring 291 - 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 292 293- **_2022-10-04_** 294 295 - Cleaned up the code to PHPCS standards 296 - Fixed breadcrumb layouts on mobile [#31](https://github.com/nomadjimbob/mikio/issues/31) 297 - Fixed Media Manager on small displays 298 - Fixed layout compatiblity on Greebo 299 - Fixed search results layout [#41](https://github.com/nomadjimbob/mikio/issues/41) 300 - Added Dark-mode support [#43](https://github.com/nomadjimbob/mikio/issues/43). Thanks chrbinder 301 - Fixed incorrect file names listed [#45](https://github.com/nomadjimbob/mikio/issues/45). Thanks babudro 302 - Fixed sidebars not showing [#46](https://github.com/nomadjimbob/mikio/issues/46). Thanks dasbenjo 303 304- **_2022-05-10_** 305 306 - Added support to directly set title icon width and height in config. Thanks AlexiaR 307 308- **_2022-05-05_** 309 310 - Fixed searching for images in the theme directory [#42](https://github.com/nomadjimbob/mikio/issues/42). Thanks cmacmackin 311 - Added support for the defer js option, previously always deferred [#39](https://github.com/nomadjimbob/mikio/issues/39). Thanks cmacmackin 312 - Added typeahead search [#40](https://github.com/nomadjimbob/mikio/issues/40). Thanks cmacmackin 313 - Fixed double breadcrumb options on admin pages 314 - Added sticky top header, navbar and header options. Thanks chitland 315 316- **_2022-03-05_** 317 318 - Fixed page tools in footer not being horizontal [#38](https://github.com/nomadjimbob/mikio/issues/38). Thanks chitland 319 - Fixed Mikio Config headers disappearing in some cases 320 - Separated Breadcrumbs and You Are Here items [#36](https://github.com/nomadjimbob/mikio/issues/36). Thanks chitland 321 322- **_2021-12-11_** 323 324 - Added table row background styling options 325 - Fixed styling issue when using the indexmenu plugin [#35](https://github.com/nomadjimbob/mikio/issues/35). Thanks 3ole. 326 - Fixed inconsitant tab/spaces in mikio.less and mikio.css 327 - Removed debug logs from mikio.js 328 - Fixed input placeholders not hiding in prepopulated fields [#34](https://github.com/nomadjimbob/mikio/issues/34) 329 - Added option to hide menu and page tool items [#32](https://github.com/nomadjimbob/mikio/issues/32). Thanks annievoss. 330 - Fixed compadibility with BookCreator [#26](https://github.com/nomadjimbob/mikio/issues/26). Thanks johncourtland. 331 - Fixed Greebo styling errors not present in Hogsfather 332 333- **_2021-08-11_** 334 335 - Fixed path check on Windows [#33](https://github.com/nomadjimbob/mikio/issues/33) 336 - Recompilied CSS 337 338- **_2021-06-17_** 339 340 - Added support for navbar title link to use showpageafterlogin setting if installed [#27](https://github.com/nomadjimbob/mikio/issues/27) 341 342- **_2021-06-09_** 343 344 - TOC is now full width on mobile [#25](https://github.com/nomadjimbob/mikio/issues/25) 345 - Hamburger and sidebar icons are now displayed correctly [#23](https://github.com/nomadjimbob/mikio/issues/23), [#24](https://github.com/nomadjimbob/mikio/issues/24) 346 - Site width is now available under Template Style Settings [#22](https://github.com/nomadjimbob/mikio/issues/22) 347 - TOC is now sticky when set to full height [#21](https://github.com/nomadjimbob/mikio/issues/21) 348 - Added support to the theme being linked by a symbolic link [#20](https://github.com/nomadjimbob/mikio/issues/20) 349 - Mikio will now fallback to using CSS when there is the LESS engine is not detected [#20](https://github.com/nomadjimbob/mikio/issues/20) 350 351- **_2021-03-10_** 352 353 - Fixed bad breadcrumb URL formatting on sites using userewrite [#19](https://github.com/nomadjimbob/mikio/issues/19) 354 355- **_2021-03-04_** 356 357 - Added support to hide page elements [#18](https://github.com/nomadjimbob/mikio/issues/18) 358 359- **_2021-01-22_** 360 361 - Fixed a syntax error with the core css 362 363- **_2020-11-12_** 364 365 - Corrected terminology in readme to match Dokuwiki [#17](https://github.com/nomadjimbob/mikio/issues/17) 366 - Fix showing part of the sidebar when it should be hidden in certain conditions [#16](https://github.com/nomadjimbob/mikio/issues/16) 367 - Added option to always show the sidebar, even when there is no content [#16](https://github.com/nomadjimbob/mikio/issues/16) 368 369- **_2020-10-07_** 370 371 - Fixed hero header parsing on some servers 372 - Fixed safari color picker issue [#14](https://github.com/nomadjimbob/mikio/issues/14) 373 - LESS now defaults to enabled with fallback to ctype functions built into mikio for docker apps [#13](https://github.com/nomadjimbob/mikio/issues/13) 374 - Fix for Template Style Settings being ignored [#12](https://github.com/nomadjimbob/mikio/issues/12) 375 376- **_2020-10-01_** 377 378 - 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. 379 380- **_2020-09-27_** 381 382 - Sidebars hidden by default in mobile view [#10](https://github.com/nomadjimbob/mikio/issues/10) 383 - Fixed errors with the LESS compilier on some nginx configurations 384 - Fixed styling and image display thumb size in media manager popup 385 - Fixed text field placeholders not disappearing with text entry 386 - Added support for Hogfather 387 - Added option to use LESS or direct CSS. Some configurations (docker linuxserver/dokuwiki) do not have the required PHP extensions installed 388 - Supports Docker linuxserver/dokuwiki container file structures 389 390- **_2020-09-10_** 391 392 - 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) 393 - Template.info.txt now shows correct release dates [#8](https://github.com/nomadjimbob/mikio/issues/8) 394 - Fixed rightsidebar php warnings 395 - Code/Pre blocks no longer have padding applied on the admin pages 396 397- **_2020-08-26_** 398 399 - Footer is no longer shown outside of page view 400 - Public messages are now displayed on the page 401 - Fixed icon rendering in hero bar 402 - Fixed TOC rendering bug 403 404- **_2020-07-27_** 405 406 - Added option to show wiki footer in page content 407 408- **_2020-07-24_** 409 410 - Fixed image detail bug 411 412- **_2020-07-20_** 413 414 - Fixed prewrap and sidebar search bar margins 415 416- **_2020-07-16_** 417 418 - Merged code block styling with pre 419 - Fixed mediamanager failures on 2018-04-22a "Greebo" [#5](https://github.com/nomadjimbob/mikio/issues/5) 420 - Icon tag is rendered correctly in preview [#4](https://github.com/nomadjimbob/mikio/issues/4) 421 422- **_2020-07-15_** 423 424 - 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) 425 426- **_2020-07-14_** 427 428 - Added id=dokuwiki\_\_content identifier for the page content element 429 - Added styling and fixed overflow issues with pre elements 430 - Fixed page width overflow issues 431 432- **_2020-07-09_** 433 434 - Fixed cosmetic display issues when `input[type=file]` is hidden by plugins [#2](https://github.com/nomadjimbob/mikio/issues/2) 435 436- **_2020-07-07_** 437 - Initial release 438 439## Third Party Libraries 440 441This template uses a [modified 442version](https://github.com/nomadjimbob/simple_html_dom) of 443[simple_html_dom](https://sourceforge.net/projects/simplehtmldom/) and 444[bootstrap-3-typeahead](https://github.com/bassjobsen/Bootstrap-3-Typeahead). 445 446## Support 447 448- 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) 449- If you are a coder, feel free to create a pull request, but please be detailed about your changes! 450
){kind=link}