view release on metacpan or  search on metacpan

bin/pft-edit  view on Meta::CPAN

=item B<--append>

As for B<--stdin>, but append content instead of replacing it.

If the content file does not exist or is empty, and header will be
automatically defined depending on the given command options.

If the header exists but is corrupted, the command will issue a warning.
No corrective action will be taken.

=item B<--select>=I<id>

Select a certain entry by index, in case of ambiguity.

This option applies when multiple files are matching the parameters for file
selection, and a choice is required.  In these situations, if B<--select> is
not provided the L<pft-edit(1)> command will fail, and the use of
B<--select> will be explicitly requested by an error message.

=item B<--raw>

This option is useful only if B<--stdin> or B<--append> are specified.

If the B<--raw> option is used the header is not maintained: C<pft edit
--stdin --raw> command will behave like C<cat E<gt> $content_file>, while
C<pft edit --append --raw> will behave like C<cat E<gt>E<gt> $content_file>.
The path of C<$content_file> is determined by the previously described file
naming rules.

=item B<--help> | B<-h>

Shows this help.

=back

=head2 Editing

Content entries are in encoded text format.

The expected encoding for the file corresponds to the C<locale>.  On modern
systems I<UTF-8> is the more popular encoding, but you can use the
L<locale(1)> command to figure out.

Each file starts with a header in I<YAML> format. The header is followed
by a line with three dashes (C<--->) which marks the beginning of the
actual content. The content will be parsed as I<Markdown> when the site is
compiled.

The header of a content entry is created automatically by L<pft-edit(1)>
when the accessed entry does not exist. The file gets then opened with a
text editor. The C<$EDITOR> environment variable will be honored unless an
editor is defined in the C<pft.yaml> configuration file (see
L<pft-init(1)>). You may also specify a different editor using the
B<--editor> command line option.

When the editor is terminated the file content is evaluated.  A warning will
be issued if the header is invalid.  If the file completely empty (zero
bytes) it will be removed from the filesystem.  If the header is valid but
not consistent with the position in the filesystem (e.g. the date was
manually changed) the file position is updated according to the header.

=head2 The content header

Each entry starts with a header in I<YAML> format. The header defines the
properties of the entries. Valid properties with their descriptions follow
in this section.

=over

=item I<Author>

The author of the entry. Any string can be entered as value. The default
value of it is taken from the C<pft.yaml> configuration file.

=item I<Date>

The date associated with the entry. This field is required only for blog
entries. Changing the value while editing with L<pft-edit(1)> will result to
the position in the filesystem to be adapted consistently.

=item I<Options>

Some optional properties of the entry:

=over

=item I<hide>

I<This feature is currently broken>.

If set to 1 the entry is not going to be built by L<pft-make(1)>.

The intention is to temporarily hide an entry (e.g. if it is incomplete).

=item I<template>

Each page can specify a different template to use by means of this field.
It is by default defined as C<~> (in I<YAML> that is I<null>) meaning that
the page will use the global template as defined in the C<pft.yaml>
configuration file.

=back

=item I<Slug>

The slug determines how the published file will be named.

The default slug value is derived by removing non-word characters from the
I<Title> field. The purpose is to have a mnemonic file name, which is both
readable and convenient to handle.

The field can be manually changed in the header, and this will result in the
file name to be modified when the editor is terminated.

=item I<Tags>

A list of tags for the entry.

Tags can be specified one per line with a leading C<->: