[Archived] Diggie is a Markdown and Django driven wiki application.
Update README
e4c4cb197b54 — Oben Sonne 9 years ago
Simplify blockquote style
b133ae6b2f37 — Oben Sonne 9 years ago
Tweak blockquote style

heads

default
browse log

clone

read-only
https://hg.sr.ht/~obensonne/diggie
read/write
ssh://hg@hg.sr.ht/~obensonne/diggie
-*- restructuredtext -*-

===============================================================================
Diggie
===============================================================================

*Diggie* is a `Markdown`_ and `Django`_ driven wiki application.

*Diggie* is a Django application, i.e. it can be integrated in every Django
driven site. However, it's main use case is to run it as a **personal local
wiki** application. *Diggie* ships with a command line tool which automatically
sets up a local Django site running *Diggie*::

    $ diggie /path/to/wiki --init --name MyWiki
    $ diggie /path/to/wiki --run

is all you need to get your local wiki up and running.

Install *Diggie* by running ``easy_install diggie`` or ``pip install diggie``.

*Diggie* requires

-   *Python* >= 2.6
-   *Django* >= 1.2
-   *python-markdown* >= 2.0.
-   Optionally *LaTeX* and *dvipng* to render in-wiki math formulae.

When using *easy_install* or *pip*, the first 3 requirements get installed
automatically.

.. _Markdown: http://daringfireball.net/projects/markdown/
.. _Django: http://www.djangoproject.com/

-------------------------------------------------------------------------------
Using Diggie as a personal local wiki
-------------------------------------------------------------------------------

This is easy!

1.  Initialize a new wiki::

        $ diggie /path/to/wiki --init --name MyWiki

2.  Run::

        $ diggie /path/to/wiki --run [--port 4000]

3.  Point your browser to http://localhost:4000 .

The new wiki contains a help page about using a *Diggie* wiki.

Structure of a local wiki
~~~~~~~~~~~~~~~~~~~~~~~~~

A new wiki at ``/path/to/wiki`` consists of the following files and directories:

``wiki.db``
  An `SQLite`_ database containing wiki pages.
``media/images``
  Wiki image links refer to files located here (see in-wiki help for details).

The whole wiki is file based which makes it easy to share it across
multiple computers, e.g. using services like `UbuntuOne`_ or `Dropbox`_.

.. _SQLite: http://www.sqlite.org/
.. _UbuntuOne: https://one.ubuntu.com/
.. _Dropbox: http://www.dropbox.com/

-------------------------------------------------------------------------------
Using Diggie in a Django powered site
-------------------------------------------------------------------------------

For a simple example, have a look into the Django site projects created by
the tool *diggie* for local wikis.

The concrete steps depend on the site project but basically it works as
follows:

1.  Add ``diggie`` to ``INSTALLED_APPS`` in the project's ``settings.py``.

2.  Either add ``django.template.loaders.app_directories.Loader`` to
    ``TEMPLATE_LOADERS`` in ``settings.py`` or link to
    ``/path/to/diggie-python-module/templates/diggie`` from one of the
    project's template locations.

3.  Set *Diggie* specific options  in the projects ``settings.py``:

    ``DIGGIE_WIKINAME = "Diggie"``
      Name of the wiki.

    ``DIGGIE_IMAGES = ""``
      Path (relative to ``MEDIA_URL``) where wiki images are located.

    ``DIGGIE_MDX = []``
      List of additional or custom markdown extensions.

4.  Adjust the project's ``urls.py``, for instance::

        urlpatterns = patterns('',
            ...
            (r'diggie/^', include('diggie.urls')),
        )

5.  Sync the project's database::

        $ python manage.py syncdb

Finished.

-------------------------------------------------------------------------------
Import and export
-------------------------------------------------------------------------------

The command line tool *diggie* can be used to import or export pages into or
from a *Diggie* wiki. This is useful to backup wiki pages outside of an
database, migrate between incompatible *Diggie* versions or to migrate
pages from another wiki to a *Diggie* wiki or vice versa.

Run ``diggie --help`` for details.

===============================================================================
Disclaimer
===============================================================================

*Diggie* is a one-person free-time project. My initial motivation for *Diggie*
was twofold: get a simple and clean personal note taking utility and get into
Django. I have several ideas for more cool features and how to make some things
better than I did them initially. I would start right now if I had the time
for.

I'm not able to or willing to check if *Diggie* runs equally pleasant in
all browsers. Indeed *Diggie* uses some rather new CSS and HTML features you'll
probably won't find in older browsers.

Personally I use it in Google Chrome (dev channel version). If you find
something not working in other browsers, feel free to fix this and share your
patches by forking the source repository. I'll happily integrate improvements,
except dirty hacks for old IE versions.

===============================================================================
Feature wish list
===============================================================================

-   Improve page search (search results and page highlights sometimes do not
    match).
-   Combine page listing and managemant interface.
-   Compress page history.
-   Provide a *diff* view for page revisions.
-   Support uploading of files and images. This is not needed when using
    *Diggie* as a local wiki (where you use your file browser to put files into
    a wiki) but when the *Diggie* app runs on a remote machine.

===============================================================================
Changes
===============================================================================

-------------------------------------------------------------------------------
Version 0.?
-------------------------------------------------------------------------------

- Initial release