#+title: Org Zettelkasten Manual
#+subtitle: Release {{{version}}}
#+author: Yann Herklotz
#+language: en

#+texinfo: @insertcopying

* Introduction
:PROPERTIES:
:DESCRIPTION: Getting started.
:END:
#+cindex: introduction

Niklas Luhmann’s Zettelkasten is becoming increasingly popular for being a great
note taking technique.  However, it is often misunderstood as taking notes
without any structure, whereas Luhmann actually structured his notes
hierarchically, but also allowed for arbitrary links between notes.  Org
Zettelkasten tries to following the general note-taking workflow that Luhmann
used by using as much of Emacs' built-in Org as possible.

** Inserting new notes
#+cindex: notes
#+cindex: create-notes

There are several possible notes that can be inserted into the Zettelkasten, but
the need for them should arise naturally and one therefore does not have to
think about the separate types of notes directly.  For references I usually use
the fantastic [[https://joostkremers.github.io/ebib/][ebib]] package.

*** Permanent Notes
#+cindex: notes
#+cindex: permanent-notes

Inserting new notes into the Zettelkasten can be done for any new piece of
information one wants to permanently add to the tree of notes and therefore the
network of notes.  These are therefore called “permanent notes,” however, these
are not the only notes that may appear in the network.  The most important thing
to take into consideration is that “permanent notes” should be completely in
your own words, and express an idea that also links to other parts in the
network.  At the start it may be necessary to create a few topics that these
notes fit into, however, eventually one should be able to find notes that are
similar enough which this new note should follow.

*** Index notes
#+cindex: notes
#+cindex: index-notes

Apart from that, there can also be “index notes,” which try to give some
structure to a subsection that may have gotten lost with all of the branches
that may have been added.  In addition to that, these may tie in other notes
from other topics as well that relate to that topic.  These can therefore just
be added whenever you feel like there are too many notes for a subtopic and
cannot keep track of all the possible links.

* Variables for Customisation
:PROPERTIES:
:DESCRIPTION: Variables which are available for customisation.
:END:
#+cindex: customisation

- =org-zettelkasten-directory= :: This is the path to the root of the
  zettelkasten directory.  By default this is set to: ="~/org-zettelkasten"=.

- =org-zettelkasten-mapping= :: A mapping from indices to filenames, which is
  used to keep track of which org-mode files are part of the zettelkasten
  directory.  This is currently a variable because the set of files should be
  quite static, and there should not be that many topics.

- =org-zettelkasten-prefix= :: Prefix used for org-zettelkasten default
  bindings.

- =org-zettelkasten-mode-map= :: Bound to the prefix, and contains the default
  bindings of Org Zettelkasten functions.

* Creating New Topics and Notes
:PROPERTIES:
:DESCRIPTION: Creating new top-level topics to contain new notes.
:END:
#+cindex: topics
#+cindex: notes

- =org-zettelkasten-new-topic= :: Create a new topic file in the current
  Zettelkasten directory.  Bound to =t= by default.

- =org-zettelkasten-create-dwim= :: Create a new note under the current note, by
  either introducing a new level in the current note, or continuing at the same
  level if the current note is the last.  Bound to =n= by default.

* Navigation Org Zettelkasten Links
:PROPERTIES:
:DESCRIPTION: Functions used and provided to navigate org-zettelkasten links.
:END:
#+cindex: navigation

- =org-zettelkasten-goto-id= :: Go to a specific ID in the zettelkasten
  directory.  This will automatically jump to the right file and then go to the
  id.  Bound to =g= by default.

- =org-zettelkasten-search-current-id= :: Search the current ID in the
  org-zettelkasten directory using =grep=.  This will essentially find backlinks
  to the current note.  Bound to =C-s= by default.

- =org-zettelkasten-agenda-search-view= :: Search all the whole Org Zettelkasten
  directory using =agenda-search=.  Bound to =s= by default.

** Navigation With Consult or Counsel
:PROPERTIES:
:DESCRIPTION: Navigating org-zettelkasten using the optional consult or counsel package.
:END:
#+cindex: consult
#+cindex: counsel
#+cindex: navigation

- =org-zettelkasten-consult-search-current-id= :: Alternative to
  =org-zettelkasten-search-current-id= using Ripgrep integration with Consult.

- =org-zettelkasten-counsel-search-current-id= :: Alternative to
  =org-zettelkasten-search-current-id= using Ripgrep integration with Counsel.

* Getting Started
:PROPERTIES:
:DESCRIPTION: Functions used and provided to navigate org-zettelkasten links.
:END:
#+cindex: getting-started

To install =org-zettelkasten=, first make sure that you have the melpa
repository set-up properly.  Then, the following =use-package= declaration will
set-up =org-zettelkasten= including useful hooks to activate it when it enters a
zettelkasten file.

#+begin_src emacs-lisp
  (use-package org-zettelkasten
    :after org
    :config
    (org-zettelkasten-setup))
#+end_src

Once =org-zettelkasten= is installed properly, then you can run
=org-zettelkasten-new-topic= to create your first topic file.  Make sure that
the folder in =org-zettelkasten-directory= exists, which is set to
=~/org-zettelkasten= by default.

This should open a new file with the name that was given in the prompt, and it
should to start experimenting with adding new notes.  In the current file there
should already be a heading with an ID:

#+begin_src org-mode
  #+title:

  * First Note
  :PROPERTIES:
  :CUSTOM_ID: 1a
  :END:
#+end_src

Placing the point anywhere underneath the heading =* First Note=, and pressing
=C-c y n= will create a next note with a new ID, and jump to it.  Going back to
=* First Note= and pressing the keybinding again will create another note, but
this time it is nested in the current note (branching) because there is already
a next note present.

* GNU Free Documentation License
:PROPERTIES:
:APPENDIX: t
:DESCRIPTION: The license for this documentation.
:END:

#+include: fdl.org

* Main Index
:PROPERTIES:
:INDEX:    cp
:DESCRIPTION: An index of Org Zettelkasten concepts and features.
:END:

* Copying
:PROPERTIES:
:copying: t
:END:

This manual is for Org Zettelkasten version {{{version}}}.

Copyright \copy 2023  Yann Herklotz.

#+begin_quote
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover Texts being "A GNU Manual,"
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled "GNU Free Documentation License."

(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
modify this GNU manual."
#+end_quote

* Export Setup :noexport:

#+setupfile: doc-setup.org

#+export_file_name: org-zettelkasten.texi

#+texinfo_dir_category: Zettelkasten
#+texinfo_dir_title: Org Zettelkasten
#+texinfo_dir_desc: A Zettelkasten mode leveraging Org