1# Read the Dokus - Dokuwiki Template
2
3This is a Dokuwiki theme that imitates "Read the Docs".
4
5![c7467c9c43ba585265cf829dd5d1c230 media](https://user-images.githubusercontent.com/49435291/164868953-d272c665-57e4-4c17-87c1-8b238b5ea5d3.png)
6
7Featuring:
8- “Read the Docs” appearance
9- Embedded foldable TOC in the sidebar
10- Auto generated “Previous”, “Next” buttons to follow the pages on the sidebar
11
12## Installtion
13
14Use Dokuwiki's Extention Manager to install the template. If you want to install manually, you can download from [here.](https://github.com/my17560/dokuwiki-template-readthedokus/archive/refs/heads/main.zip)
15
16## Settings
17
18### Template settings ###
19
20These are template settings for this theme.
21
22|Option|Description|
23-------|------------
24|Sidebar position|"left" for left sidebar, "right" for right sidebar. |
25|Use Dokuwiki breadcrums|Use Dokuwiki style breadcrumbs.|
26|Start Page|Set start page url.|
27
28### Template variables ###
29
30These are some of the options on "Template Style Settings".
31
32|Option|Description|
33-------|------------
34|Site width|Width of the whole content including the sidebar. By setting this value, the contents will be centered.|
35|Content width|Content width. This is a maximum width so the actual size could be less than this value.|
36|Side bar width|Sidebar width.|
37|Header height|Header height. The theme puts padding on the top of the page according to this value.|
38|Footer height|Footer height. The theme puts padding on the bottom of the page according to this value.|
39|CSS breakpoint for smart phones|Screen size less than this value will be treated as a smartphone.|
40|CSS breakpoint for tablets|Screen size less than this value will be treated as a tablet. |
41
42## Notes
43
44#### Sidebar format ####
45
46Use strong for captions, lists of links for items. Anything other than that won't be styled, so use your own styles for them.
47
48E.g.
49```
50** Caption1 **
51  * [[page1]]
52  * [[page2]]
53** Caption2 **
54  * [[page3]]
55  * [[page4]]
56```
57
58#### Previous/Next buttons ####
59
60Previous/Next buttons follow links to dokuwiki on the sidebar, picked up by using querySelector(".aside > #sidebar a[data-wiki-id]"). The previous button on the first page will jump to root(/) by default. You can change this in "Start Page" option in the settings.
61
62#### No link to login page ####
63
64This theme doesn't have any links to the login page. Go directly to the login page by appending "&do=login" to the current URL.
65
66#### Admonitions ####
67
68This theme has "Read The Docs" style admonitions. To use them, wrap a content with a div that has a class "admonition" and a type.
69
70E.g.
71```
72<html><div class="admonition note">
73<p>Note!</p>
74</div></html>
75```
76
77Types are:
78- danger
79- caution
80- note
81- tip
82
83You can use "Wrap Plugin" to make it a bit simpler.
84
85```
86<WRAP admonition note>
87Note!
88</WRAP>
89```
90
91If you use the plugin, do not forget to add classes (admonition,danger,caution,note,tip) to the "noPrefix" plugin option otherwise admonitions will not be styled correctly. You need to add four types listed above and "admonition" to the option value.
92
93## Customization
94
95### Using Font Awesome ###
96
97Even though this theme works without Font Awesome, you can use Font Awesome for better looking. If you decide to use it, check the option in the configuration manager to enable it. Do not forget to set the correct tag in the following option.
98
99A home icon will appear beside the title, and +/- buttons on TOC, a mobile menu button will be replaced by Font Awesome.
100
101### Using Google Fonts ###
102
103Also, you can use google fonts for better looking. Lato and Robot fonts are set in font-family in this theme CSS. If you decide to use it, check the option in the configuration manager to enable it. Change the tags in the following option.
104
105### Adding a fixed header/footer ###
106
107This theme supports a fixed header and footer. On the "Template Style Setting" page, enter a header height in the "Header height" option, a footer height in the "Footer height" option. The theme will add paddings according to those options on top for header, bottom for footer. You can put your own header/footer in "header.html"/"footer.html" in the "lib/tbl/readthedokus/" directory.
108
109#### 1. Set header/footer height in "Template Style Settings" ####
110
111These values must be valid css values.
112
113e.g. "50px"
114
115#### 2. Create header.html/footer.html ####
116
117Create a file "header.html"/"footer.html" under (dokuwiki folder)/lib/tpl/readthedokus/.
118
119Here is a sample header.html. This example also shows how to toggle a sidebar. Clicking the string "Header" toggles the sidebar.
120
121```
122<div onclick="toggleMenu();">Header</div>
123<style>
124header > div {
125	background-color: khaki;
126	position: fixed;
127	height: 50px;
128	left: 0;
129	top: 0;
130	right: 0;
131}
132</style>
133<script>
134function toggleMenu()
135{
136	dokus.toggleSidebar();
137}
138</script>
139```
140
141You might want to hide a mobile menu since both the sticky header and the mobile menu are displayed at the same time on mobile devices. To hide the mobile menu add below to CSS file (dokuwiki folder)/conf/userall.css
142
143```
144#mobileheader {
145display: none;
146}
147```
148
149### Centering the content ###
150
151To center the content, enter the content width in the "Site width" option on the "Template Style Settings".
152
153### Include Hooks ###
154
155The theme has some include-hooks.
156
157```
158+--------------------------------------------------+
159|                       [1]                        |
160+-------------+------------------------------------+
161|    Title    | Docs > Page Title                  |
162|(           )|                [6]                 |
163|     [2]     | ---------------------------------- |
164+-------------+                                    |
165|     [3]     |                                    |
166|             |                                    |
167|             |                                    |
168|             |                                    |
169|             |                                    |
170|             |                                    |
171|             |                                    |
172|             |                                    |
173|             |                                    |
174|     [4]     | <Previous                    Next> |
175+-------------+                                    |
176|     [5]     |                [7]                 |
177+-------------+------------------------------------+
178|                       [8]                        |
179+--------------------------------------------------+
180
181
182[1] ... header.html
183[2] ... sidebarheader.html
184[3] ... sidebartop.html
185[4] ... sidebarbottom.html
186[5] ... sidebarfooter.html
187[6] ... pageheader.html
188[7] ... pagefooter.html
189[8] ... footer.html
190```
191