README
1
2 I. About
3
4 "mnml-blog" is a clean and minimalist template for DokuWiki. It is designed
5 to use DokuWiki as blogging software. The name means "minimalist blog", and
6 it was created for the personal weblog [1] of Andreas Haerter [2].
7
8 Website: <https://www.dokuwiki.org/template:mnml-blog>
9 Maintainer: ARSAVA <https://dev.arsava.com/>
10 Contact: See "IV. Support" and "V. Contact".
11
12 [1] <http://blog.andreas-haerter.com/>
13 [2] <https://andreashaerter.com/>
14
15
16
17 II. Installation and update
18
19 First step:
20 The basic installation works as described [1] on DokuWiki.org. Extract the
21 downloaded archive into your DokuWiki's "lib/tpl/" folder. Then select the
22 template in the Config Manager by adjusting the template option.
23
24 Second step:
25 Check if the BlogTNG plugin [2] is installed and up2date. This template is
26 designed for the usage with the BlogTNG-Plugin *only* (it may work for other
27 purposes, but they are not tested or supported)!
28
29 Third step:
30 The files in "lib/tpl/mnml-blog/blogtng-tpl" are a BlogTNG data
31 template [3]. Please copy these files into all used BlogTNG data template
32 dirs below "lib/plugins/blogtng/tpl".
33 Hint: By default, there is only "lib/plugins/blogtng/tpl/default". You may
34 overwrite the existing files in there (but remember: you have to do
35 this again on every BlogTNG-Update then!).
36
37 Fourth step:
38 Create a wiki <blog list> page where all posting shall appear. Then look
39 where the option "mnmlblog_newpostform_location" (-> "Use following wiki
40 page for the '<blog newform>' form") points to (default is
41 ":wiki:create_new_blogpost") and create a wiki <blog newform> page there
42 (the "New Post" link at the bottom right of the footer is using this link).
43 See the BlogTNG plugin page [2] or my tutorial [4] for details.
44
45 Update:
46 See the mnml-blog template website for instructions [5].
47
48 [1] <https://www.dokuwiki.org/template>
49 [2] <https://www.dokuwiki.org/plugin:blogtng>
50 [3] <https://www.dokuwiki.org/plugin:blogtng#templates>
51 [4] <http://j.mp/in6pfV>
52 [5] <https://www.dokuwiki.org/template:mnml-blog#update>
53
54
55
56 III. Customizing the template
57
58 In order to make updates of your installed "mnml-blog" template easy, follow
59 these hints for customizing the template:
60
61 - Place your files in "mnml-blog/user"
62 The place to store *all* user-defined, custom stuff is the
63 "mnml-blog/user" directory because your files will not be touched or
64 overwritten on template updates! So you normally can copy all new files
65 into "mnml-blog/" to update the template without loosing your changes.
66 Note: There are example files helping you modifying the template.
67 The are delivered with the ".dist" extensions. Just remove the
68 ".dist" extension to use them.
69
70 - Own logo
71 If you want to replace the default logo showed in the upper left, simply
72 create a "logo.[png|gif|jpg]" in "mnml-blog/user". The template recognizes
73 the file automatically and will use it instead of the default text.
74 Note: Do not forget to empty your browser's cache if you cannot see any
75 effect.
76
77 - Own favicon
78 If you want to replace the default favicon, simply create a "favicon.ico"
79 in "mnml-blog/user". The template recognizes the file automatically and
80 will use it instead of the default one. Do not forget to empty your
81 browser's cache afterwards. By the way: you might find the online
82 FavIcon Generator [1] useful.
83 Note: "favicon.png" is also possible but not recommended (because it is
84 not supported by older MSIE versions).
85
86 - Own CSS
87 To apply additional CSS rules, create a
88 - "mnml-blog/user/screen.css" file to influence the normal layout. You
89 can rename the "screen.css.dist" to "screen.css" as starting point.
90 - "mnml-blog/user/print.css" file to influence the print layout. You
91 can rename the "print.css.dist" to "print.css" as starting point.
92 - "mnml-blog/user/rtl.css" file to influences "right-to-left" languages
93 like Hebrew. You can rename the "rtl.css.dist" to "rtl.css" as
94 starting point.
95 The file(s) will be included automatically (as the last ones for the
96 relevant media, therefore you are able to overrule existing styles).
97 Note: Do not forget to empty your browser's cache if you cannot see any
98 effect.
99
100 - Own JavaScript
101 To load additional JavaScript, create a "mnml-blog/user/user.js" file. You
102 can rename the "user.js.dist" to "user.js" as starting point (it contains
103 some examples and useful comments how to define your own JavaScript).
104 ATTENTION: You have to activate the template option "mnml-blog_loaduserjs"
105 (->"Load 'mnml-blog/user/user.js'?") in the DokuWiki Config
106 Manager!
107
108 - Own boxes
109 To apply own boxes in the right column, have a look at
110 "mnml-blog/user/boxes.php". Don't worry: you will find some examples how
111 to define the boxes. If you still have questions after playing with the
112 examples, see "IV. Support" on how to get help.
113 If "mnml-blog/user/boxes.php" does not exist, simply copy it out of the
114 current installation archive.
115
116 - Web analytics software (Piwik, Google Analytics etc.)
117 Tools like Piwik and Google Analytics normally provide a small code
118 snippet ("tag") which you have to include at your website to make
119 everything work. If you want to use such software with this template,
120 create a "mnml-blog/user/tracker.php.dist". You don't have to deliberate
121 where you have to copy and paste the code, simply do it there. You can
122 rename the "tracker.php.dist" to "tracker.php" as a good starting point
123 (it contains some examples and useful comments how to define your own
124 boxes).
125
126 - Own Apple Touch Icon
127 If you want to replace the default Apple Touch Icon, simply create a
128 "apple-touch-icon.png" in "mnml-blog/user". The template recognizes the
129 file automatically and will use it instead of the default one. Have a look
130 at Apple's developer database (cf. "Configuring Web Applications" [2]) if
131 you need more information.
132
133 [1] <http://tools.dynamicdrive.com/favicon/>
134 [2] <http://j.mp/sx3NMT>
135
136
137
138 IV. Support
139
140 If you need help, check the FAQ [1] and try to find useful information by
141 using the DokuWiki Search page [2]. If you found nothing helpful, ask your
142 question at the DokuWiki forum [3] (preferred) or IRC channel [4].
143
144 [1] <https://www.dokuwiki.org/template:mnml-blog#faq>
145 [2] <http://search.dokuwiki.org/>
146 [3] <https://forum.dokuwiki.org/>
147 [4] <https://www.dokuwiki.org/irc>
148
149
150
151 V. Contact
152
153 If you think you have found a bug or have a useful idea (a.k.a. "feature
154 request"), create an issue [1] on GitHub (preferred), or contact us by
155 mail [2].
156
157 Feel free to submit patches as GitHub pull requests (preferred) or by mail
158 as well. However, please try to respect the DokuWiki coding style [3] as
159 this template follows its rules.
160
161 [1] <https://github.com/arsava/dokuwiki-template-mnml-blog/issues>
162 [2] ARSAVA <dokuwiki@dev.arsava.com>
163 [3] <https://www.dokuwiki.org/devel:coding_style>
164
165
166
167 VI. Other notes
168
169 If you like this free project, you might buy us a coffee [1], or get some
170 cool QR Code merchandise [2]. Thank you! :-)
171
172 Do not hesitate to contact ARSAVA [3] if you need professional DokuWiki
173 support, training or if you think we are the ones to get your project done.
174
175 [1] <https://donate.arsava.com/dokuwiki-template-mnml-blog/>
176 [2] <http://goqr.me/>
177 [3] <https://dev.arsava.com/>
178
179
180
181 VII. Explanatory notes about the dirs of this template
182
183 - "mnml-blog/blogtng-tpl"
184 Contains a backup copy of the needed BlogTNG data template files. See
185 "II. Installation and update" of this README for details.
186
187 - "mnml-blog/conf"
188 Contains some configuration files (do NOT edit them!), especially
189 - default.php: default settings [1]
190 - metadata.php: configuration metadata [2]
191
192 - "mnml-blog/lang"
193 Language files (subdir names = language code). You may copy the English
194 language files and translate them if your language is missing. Simply send
195 us the translated files (cf. "V. Contact") and I will include them in the
196 next release :-D.
197
198 - "mnml-blog/css"
199 All Cascading Style Sheets (CSS). See my tutorial [3] for more information
200 about how the CSS is handled.
201
202 - "mnml-blog/images"
203 Images files.
204
205 - "mnml-blog/js"
206 JavaScript files.
207
208 - "mnml-blog/user"
209 Place for userdefined stuff. E.g. if you want use an own logo, simply copy
210 a logo.[png|gif|jpg] in here. See "III. Customizing the template" for
211 details.
212
213 [1] <https://www.dokuwiki.org/devel:configuration#default_settings>
214 [2] <https://www.dokuwiki.org/devel:configuration#configuration_metadata>
215 [3] <http://j.mp/eq8zSo>
216
217
218
219 VIII. Creation transcript
220
221 Some developers may find this interesting. Additionally, I am very oblivious
222 :-P.
223
224 In principle, I followed my own tutorial [1]. There was just no "starter"
225 template [2] when "mnml-blog" was created. Therefore, after ~1 year, I
226 switched the CSS base from DokuWiki's default template to the starter
227 template, but the markup of "main.php" is still based on the default
228 template's "main.php".
229
230 [1] <http://j.mp/eq8zSo>
231 [2] <https://www.dokuwiki.org/template:starter>
232
233
