summaryrefslogtreecommitdiff
path: root/ikiwiki
diff options
context:
space:
mode:
Diffstat (limited to 'ikiwiki')
-rw-r--r--ikiwiki/website.mdwn283
1 files changed, 283 insertions, 0 deletions
diff --git a/ikiwiki/website.mdwn b/ikiwiki/website.mdwn
new file mode 100644
index 0000000..d6b0711
--- /dev/null
+++ b/ikiwiki/website.mdwn
@@ -0,0 +1,283 @@
+# Ikiwiki for regular websites
+
+[[Ikiwiki]] can be used to administrate regular websites.
+
+## Introduction
+
+Websites built with ikiwiki is more complex than plain static websites,
+but simpler than most web-based content management systems (CMS).
+
+One of the benefits over using static webpages is that text content can
+be edited independent of the webdesign. This means, that...
+
+ * The editor (e.g. owner of the website or a secretary) need not bother
+ the web designer with text-only changes.
+ * The editor can start adding text content even before the visual
+ design is finalized.
+
+One of the benefits compared to using most other CMS or wiki engines is
+that most pages are served as static html.
+
+## Roles
+
+Wiki sites classically is public. Anyone can both read the site and
+edit its pages.
+
+A regular website is meant to only be edited by som website
+administrator.
+
+Ikiwiki offers the possibility to separate different administration
+tasks. You need not be a webdesigner to edit text content, and you need
+not be limited by the user-friendly text editing interface as a web
+designer.
+
+[[graph height=8 width=8 src="""
+{
+ /* roles */
+ reader [shape=house, label="Reader"]
+ editor [shape=house, label="Editor"]
+ designer [shape=house, label="Designer"]
+ {rank=same; reader editor designer}
+
+ /* targets */
+ webpages_static [label="website"]
+ webpages_wiki [label="admin website"]
+ {rank=same; webpages_static webpages_wiki}
+
+ /* input data */
+ txt [shape=plaintext, label="text"]
+ media [shape=plaintext, label="graphics"]
+ tmpl [shape=plaintext, label="templates"]
+ {rank=same; txt tmpl media}
+
+ iki_engine [shape=box, label="web engine"]
+
+ /* paths */
+ reader -> webpages_static [dir=back]
+ editor -> txt -> iki_engine -> webpages_wiki
+ designer -> media -> iki_engine
+ designer -> tmpl -> iki_engine
+ iki_engine -> webpages_static
+}
+"""]]
+
+## Reader
+
+The reader gets served a static website:
+
+[[graph height=8 width=8 src="""
+{
+ reader [shape=house, label="Reader"]
+
+ webpages_static [label="static pages"]
+
+ reader -> webpages_static
+}
+"""]]
+
+The website can have a search routine added.
+
+The reader then interacts both with static pages and with a search
+engine, dynamically generating search result pages:
+
+[[graph height=8 width=8 src="""
+{
+ reader [shape=house, label="Reader"]
+
+ /* targets */
+ webpages_static [label="static pages"]
+ webpages_searchresult [label="search results", style=dotted]
+ {rank=same; webpages_static webpages_searchresult}
+
+ search_query [shape=plaintext, label="search query"]
+
+ search_db [shape=box, label="search index"]
+
+ /* paths */
+ reader -> webpages_static
+ reader -> search_query -> search_db -> webpages_searchresult
+}
+"""]]
+
+## Editor
+
+In addition to the main website, an additional website is generated,
+with the main feature of Ikiwiki - [[wiki]]-like text editing - enabled:
+
+[[graph height=8 width=8 src="""
+{
+ editor [shape=house, label="Editor"]
+
+ webpages_wiki [label="wiki pages"]
+
+ content_form [shape=plaintext, label="edit form"]
+
+ /* stored data */
+ txt_stored [shape=box, label="text content"]
+ media_stored [shape=box, label="graphics files"]
+ tmpl_stored [shape=box, label="html templates"]
+ {rank=same; txt_stored media_stored tmpl_stored}
+
+ /* paths */
+ editor -> webpages_wiki
+ editor -> content_form -> txt_stored -> webpages_wiki
+ media_stored -> webpages_wiki
+ tmpl_stored -> webpages_wiki
+}
+"""]]
+
+Whenever the wiki pages are edited, the static pages are also rebuilt:
+
+[[graph height=8 width=8 src="""
+{
+ /* roles */
+ editor [shape=house, label="Editor"]
+
+ /* targets */
+ webpages_static [label="static pages"]
+ webpages_wiki [label="wiki pages"]
+ {rank=same; webpages_static webpages_wiki}
+
+ /* input data */
+ content_form [shape=plaintext, label="edit form"]
+
+ /* stored data */
+ txt_stored [shape=box, label="text content"]
+ media_stored [shape=box, label="graphics files"]
+ tmpl_stored [shape=box, label="html templates"]
+ {rank=same; txt_stored media_stored tmpl_stored}
+
+ iki_engine [shape=box, label="html renderer (ikiwiki)"]
+
+ /* paths */
+ editor -> content_form -> txt_stored -> iki_engine -> webpages_wiki
+ media_stored -> iki_engine
+ tmpl_stored -> iki_engine
+ iki_engine -> webpages_static
+}
+"""]]
+
+## All
+
+Here's a graph of the interaction between the various parts of ikiwiki itself
+and different kinds of users:
+
+[[graph height=8 width=8 src="""
+{
+// rankdir=LR
+// rotate=90
+ center=1
+
+ /* roles */
+ reader [shape=house, label="Reader"]
+ editor [shape=house, label="Editor"]
+ designer [shape=house, label="Designer"]
+ {rank=same; reader editor designer}
+
+ /* targets */
+ webpages [label="static pages"]
+ webpages_wiki [label="wiki pages"]
+ webpages_searchresult [label="search results", style=dotted]
+ {rank=same; webpages webpages_wiki webpages_searchresult}
+
+ /* input data */
+ search_query [shape=plaintext, label="search query"]
+ txt_editor [shape=plaintext, label="Markdown text"]
+ txt_designer [shape=plaintext, label="Markdown text"]
+ media [shape=plaintext, label="graphics files"]
+ tmpl [shape=plaintext, label="html templates"]
+// {rank=same; search_query txt_editor txt_designer tmpl media}
+
+ /* user tool */
+ browser_reader [label="web browser"]
+ browser_editor [label="web browser"]
+ browser_designer [label="web browser"]
+ vcs_txt_local [shape=egg, label="Git repository"]
+ vcs_tmpl_local [shape=egg, label="Git repository"]
+ fs_local [shape=egg, label="filesystem"]
+
+ /* user interface */
+ txt_form [shape=box, label="web text editor (ikiwiki)"]
+ search_form [shape=box, label="search form (ikiwiki)"]
+ {rank=same; search_form txt_form}
+
+ /* storage types */
+ search_db [shape=egg, label="search index (Hyper Estraier)"]
+ vcs_txt [shape=egg, label="VCS repository (Git)"]
+ vcs_tmpl [shape=egg, label="VCS repository (Git)"]
+ fs [shape=egg, label="filesystem"]
+// {rank=same; search_db vcs_txt vcs_tmpl fs}
+
+ /* stored data */
+ txt_stored [shape=plaintext, label="version-controlled Markdown text"]
+ media_stored [shape=plaintext, label="graphics files"]
+ tmpl_stored [shape=plaintext, label="version-controlled html templates"]
+// {rank=same; txt_stored media_stored tmpl_stored}
+
+ /* engines */
+ iki_engine [shape=box, label="html renderer (Ikiwiki)"]
+ search_engine [shape=box, label="search engine (Hyper Estraier)"]
+ {rank=same; iki_engine search_engine}
+
+ /* groupings */
+ subgraph cluster_clitools {
+ label="commandline editing"
+ style=dashed
+ txt_designer
+ tmpl
+ media
+ vcs_tmpl_local
+ vcs_txt_local
+ fs_local
+ }
+ subgraph cluster_webtools {
+ label="web editing"
+ style=dashed
+ txt_editor
+ search_query
+ {
+ rank=same
+ browser_reader
+ browser_editor
+ browser_designer
+ }
+ }
+ subgraph cluster_storage {
+ label="server storage"
+ style=dashed
+ vcs_tmpl
+ vcs_txt
+ fs
+ search_db
+ txt_stored
+ tmpl_stored
+ media_stored
+ }
+
+ /* paths */
+
+ reader -> search_query -> browser_reader -> search_form -> search_engine -> webpages_searchresult
+ search_db -> search_engine
+ search_db -> iki_engine [dir=back]
+
+ editor -> txt_editor -> browser_editor -> txt_form -> vcs_txt -> txt_stored -> iki_engine -> webpages
+ iki_engine -> webpages_wiki
+
+ designer -> txt_designer -> browser_designer -> txt_form
+ txt_designer -> vcs_txt_local
+
+ vcs_txt_local -> vcs_txt [dir=both]
+
+ designer -> tmpl -> vcs_tmpl_local
+ vcs_tmpl_local -> vcs_tmpl [dir=both]
+ vcs_tmpl -> tmpl_stored -> iki_engine
+
+ designer -> media -> fs_local
+ fs_local -> fs [dir=both]
+ fs -> media_stored -> iki_engine
+}
+"""]]
+
+----
+
+See also the simpler graphs focusing on [[roles|ikiroles]] and on the [[design|ikidesign]].