tzk/docs/configuration.rst

72 lines
2.5 KiB
ReStructuredText
Raw Normal View History

===============
Configuring tzk
===============
2021-08-27 17:52:58 +00:00
Basic setup
===========
2021-08-27 17:52:58 +00:00
1. Change into a directory you'd like to use as your Zettelkasten repository.
The directory should be empty, so you'll probably want to create a new one, e.g.:
::
2021-08-27 17:52:58 +00:00
$ mkdir my_zettelkasten
$ cd my_zettelkasten
2. Run ``tzk init``.
This will create a tzk configuration file,
install TiddlyWiki to this folder,
and set up a Git repository.
3. When ``init`` has completed successfully,
open the ``tzk_config.py`` in your favorite text editor.
Read the comments and make any changes you would like.
See the :ref:`Builders` section of this documentation
for more information about builders --
but you'll most likely want to get started with your wiki now
and worry about builds once you actually have some content to build!
4. Run ``tzk listen`` and confirm that you can access your wiki.
Committing
==========
Many people find that carefully designing atomic Git commits
when editing a TiddlyWiki
is difficult and not all that useful,
so the ``tzk commit`` command is made available
to quickly stage, commit, and (if you wish) push all changes in the repository in one go.
2021-08-27 17:59:24 +00:00
If you want to push your changes to some remote location,
such as a GitHub repository,
2021-08-27 17:52:58 +00:00
add a new Git remote (e.g., ``git remote add origin https://github.com/you/YourRepository``)
and set the ``commit_remote`` option in your tzk config to the remote name
(here, ``origin``).
You can selectively skip pushing for a particular commit
with the ``--local`` switch to ``tzk commit``.
2021-08-27 17:59:24 +00:00
.. note::
If you want to push a wiki that contains only some of your content
to GitHub in a form that others can browse,
don't try to set it up here --
use a :func:`publish_wiki_to_github() <tzk.builders.publish_wiki_to_github>` builder
at the end of the ``public`` build product.
See :ref:`Builders` for more information.
2021-08-27 17:52:58 +00:00
Environment
===========
If you'd like to be able to run ``tzk`` from any directory,
rather than having to change into the directory of your tzk repository,
set the ``TZK_DIRECTORY`` environment variable on your system
to its full path.
If the current directory contains a ``tzk_config.py`` file,
the current directory will still be preferred to the ``TZK_DIRECTORY`` directory.
.. note::
``TZK_DIRECTORY`` is not honored when calling ``tzk init``.
Otherwise tzk would prioritize the ``TZK_DIRECTORY`` over the current directory
since the current directory doesn't contain a config file yet,
and it would be impossible to initialize a second tzk repository.