summaryrefslogtreecommitdiff
path: root/ikiwiki
diff options
context:
space:
mode:
Diffstat (limited to 'ikiwiki')
-rw-r--r--ikiwiki/tech.mdwn124
-rw-r--r--ikiwiki/website.mdwn244
2 files changed, 186 insertions, 182 deletions
diff --git a/ikiwiki/tech.mdwn b/ikiwiki/tech.mdwn
new file mode 100644
index 0000000..38bd42b
--- /dev/null
+++ b/ikiwiki/tech.mdwn
@@ -0,0 +1,124 @@
+# Ikiwiki for regular websites - technical details
+
+Here's a graph of the interaction between the various parts of ikiwiki itself
+and different kinds of users (see also the [[introduction|website]]):
+
+[[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_static [label="static pages"]
+ webpages_wiki [label="wiki pages"]
+ webpages_searchresult [label="search results", style=dotted]
+ {rank=same; webpages_static 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_static
+ 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]].
diff --git a/ikiwiki/website.mdwn b/ikiwiki/website.mdwn
index c13469c..c2b3284 100644
--- a/ikiwiki/website.mdwn
+++ b/ikiwiki/website.mdwn
@@ -1,105 +1,110 @@
# Ikiwiki for regular websites
-[[Ikiwiki]] can be used to administrate regular websites.
-
-## Introduction
+[[Ikiwiki]] can be used to build and administrate regular websites.
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.
+This page provides a short introduction to using ikiwiki-based websites,
+aimed at website owners and webdesigners (but not [[technicians|tech]]).
-One of the benefits compared to using most other CMS or wiki engines is
-that most pages are served as static html.
+[[!toc ]]
-## Roles
+## Static web pages for static content
-Wiki sites classically is public. Anyone can both read the site and
-edit its pages.
+Static content is information that is identical for any user reading it.
-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.
+Static web pages are created once and then served by the web server to
+all readers of the website:
[[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"]
+ webpages_static [label="static pages"]
- /* 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 -> webpages_static
}
"""]]
-## Reader
+ikiwiki produce static web pages for all static content.
+
-The reader gets served a static website:
+## Dynamic web pages for temporary content
+
+The website can have a search routine added. The form to do a search
+can be static, but the web page showing the search results is unique to
+each search:
[[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
}
"""]]
-The website can have a search routine added.
+## Administration access
+
+Websites are normally meant to be published to the whole world, but only
+edited by a select few.
-The reader then interacts both with static pages and with a search
-engine, dynamically generating search result pages:
+ikiwiki-based websites have a separate address (typically replacing the
+leading "www" with "admin") with administration access added on top of
+all pages.
+
+## Administration roles
+
+Often the website owner writes the text content themselves, but hire
+external web designers to structure the site and apply graphical "makeup".
+
+Typically, editors need simple access only to edit their texts, while
+web designers need freedom to express their creative ideas.
+
+ikiwiki-based websites are setup to reflect that:
[[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="static pages"]
- webpages_searchresult [label="search results", style=dotted]
- {rank=same; webpages_static webpages_searchresult}
+ webpages_static [label="website"]
+ webpages_wiki [label="admin website"]
+ {rank=same; webpages_static webpages_wiki}
- search_query [shape=plaintext, label="search query"]
+ /* input data */
+ txt [shape=plaintext, label="text"]
+ media [shape=plaintext, label="graphics"]
+ tmpl [shape=plaintext, label="templates"]
+ {rank=same; txt tmpl media}
- search_db [shape=box, label="search index"]
+ iki_engine [shape=box, label="web engine"]
/* paths */
- reader -> webpages_static
- reader -> search_query -> search_db -> webpages_searchresult
+ reader -> webpages_static [dir=back]
+ editor -> txt -> iki_engine -> webpages_wiki
+ designer -> media -> iki_engine
+ designer -> tmpl -> iki_engine
+ iki_engine -> webpages_static
}
"""]]
-## Editor
+## Editing
In addition to the main website, an additional website is generated,
with the main feature of Ikiwiki - [[wiki]]-like text editing - enabled:
@@ -156,128 +161,3 @@ Whenever the wiki pages are edited, the static pages are also rebuilt:
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_static [label="static pages"]
- webpages_wiki [label="wiki pages"]
- webpages_searchresult [label="search results", style=dotted]
- {rank=same; webpages_static 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_static
- 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]].