---
author: ~ben
published: true
title: logarion
description: how to use logarion for plain-text publishing
category:
- publishing
- guides
- technical
---

To file and exchange texts, `txt` uses plain-text headers on the top of
text files. The basic headers include an
identifier, topics, authors and a date. It also needs to know basic repository information.

## Initialise

`txt init` will initialise a text repository in the current directory.
A `.logarion` directory is created, containing a configuration file, which is
editable with a text editor.
That's where you can name the text repository and declare the archivists'
names, which will also function as the default author name for new texts.

## New texts

To create new text files with the header fields to populate, use
`txt new "title"`, replacing `title` with the text's title.
The command will return the filename of the new text.
The filename starts with a part of the ID and the title of the text.
Use the file name to open it with your text editor.

## Filing

New texts can be filed in different subdirectories to create sub-repositories
of finished texts.
One use of that is to separate some of the texts to share with others.
Use `txt file ..`, replacing the dots with text file names and directories,
and txt will file (hard-link) each text into every directory specified.

Note, this is different from using the Topics header field to declare the
text's subjects.

## Convert

Generate web sites and Gemini capsuled of a text collection using
`txt convert`.
First `txt file` some texts in a subdirectory
(`txt file a.txt b.txt .. some/`) then call `txt convert somedir`.
It will scan all text files in there and convert them to other formats.
It will also produce index files for those formats and also generate an
`index.pck` file.
This index pack is a feed for other people using `txt`.
Upload the `index.pck` and the text files of the subdirectory to a host of
your choice.
If the host provides HTTP or Gemini access, upload `.htm` and `.gem` files
respectively.

## Pull

To use `txt` to clone remote repositories, add the URLs of the repositories in
`peers.priv.conf` or `peers.pub.conf`.
Both files must be created first.
Once the files are populated with the URLs, run `txt pull` and it will clone
all of the text files shared in those repositories in a local `peers/`
subdirectory.

As the name suggests, `peers.priv.conf` is private and the URLs contained in it will not be copied into `index.pck`.
On the other hand, URLs in `peers.pub.conf` will be included in the
`index.pck`, providing a way to discover other text repositories.