Skip to content

Commit

Permalink
doc: specify the template feature
Browse files Browse the repository at this point in the history
  • Loading branch information
@lervag
lervag committed Jun 21, 2020
1 parent e0fd090 commit 3ed6ccf
Showing 1 changed file with 128 additions and 19 deletions.
147 changes: 128 additions & 19 deletions doc/wiki.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,22 +29,25 @@ License: MIT license {{{
==============================================================================
CONTENTS *wiki-contents*

Introduction |wiki-intro|
Requirements |wiki-intro-requirements|
Features |wiki-intro-features|
Configuration |wiki-config|
Mappings |wiki-mappings|
Text objects |wiki-mappings-text-obj|
Journal mappings |wiki-mappings-default|
Commands |wiki-commands|
Links |wiki-links|
Link URLs |wiki-links-urls|
Markdown links |wiki-links-markdown|
Wiki links |wiki-links-wiki|
Reference links |wiki-links-reference|
Lists |wiki-lists|
Completion |wiki-completion|
Tags |wiki-tags|
Introduction |wiki-intro|
Requirements |wiki-intro-requirements|
Features |wiki-intro-features|
Configuration |wiki-config|
Mappings |wiki-mappings|
Text objects |wiki-mappings-text-obj|
Journal mappings |wiki-mappings-default|
Commands |wiki-commands|
Links |wiki-links|
Link URLs |wiki-links-urls|
Markdown links |wiki-links-markdown|
Wiki links |wiki-links-wiki|
Reference links |wiki-links-reference|
Lists |wiki-lists|
Completion |wiki-completion|
Tags |wiki-tags|
Templates |wiki-templates|
Template file format |wiki-templates-format|
Journal summaries |wiki-templates-journal-summaries|

==============================================================================
INTRODUCTION *wiki-intro*
Expand Down Expand Up @@ -97,14 +100,14 @@ FEATURES *wiki-intro-features*
- Text objects
- `iu au` Link url
- `it at` Link text
- New page templates
- Support for journal entries
- Navigating the journal back and forth with `<Plug>(wiki-journal-next)`
and `<Plug>(wiki-journal-prev)`.
- Support for parsing journal entries in order to make weekly and monthly
summaries. The parsed result needs manual editing for good results.
- Utility functionality
- Toggling lists (marking as done/undone or add/remove TODO)
- Running code snippets (Note: This needs work)
- |WikiExport| command for exporting to e.g. `pdf` with `pandoc`
- Text objects
- `il al` List items
Expand Down Expand Up @@ -386,6 +389,27 @@ CONFIGURATION *wiki-config*
Default: >
let g:wiki_tags_format_pattern = '\v%(^|\s):\zs[^: ]+\ze:'
*g:wiki_template_files*
A list template files for new pages. Each file should be specified either as
an absolute path or as a path relative to the location of the new page.
The files are searched in order, and the first matching template file will
be used. The format of template files is specified in |wiki-templates-format|.

If the template file path ends with `;`, then the file is searched upwards
similar to the description in the second type of search in |file-searching|.
For example: >
let g:wiki_template_files = [
\ '.mytemplate.md;',
\ '/home/user/templates/fallback.md',
\]
<
Here `.mytemplate.md` file is first searched for in the current directory of
the new page, then in the parent directory, and so on. If it is not found,
then the file `/home/user/templates/fallback.md` is used (if it exists).

Default: `['.template.md']`

*g:wiki_template_title_month*
A string that specifies the title of the month template. The following keys
are interpolated:
Expand All @@ -394,6 +418,8 @@ CONFIGURATION *wiki-config*
`%(month-name)` Name of month (see |g:wiki_month_names|)
`%(year)` Year (4 digits)

See |wiki-templates-journal-summaries| for more info.

Default: `'# Summary, %(year) %(month-name)'`

*g:wiki_template_title_week*
Expand All @@ -403,6 +429,8 @@ CONFIGURATION *wiki-config*
`%(week)` Week number
`%(year)` Year (4 digits)

See |wiki-templates-journal-summaries| for more info.

Default: `'# Summary, %(year) week %(week)'`

*g:wiki_zotero_root*
Expand Down Expand Up @@ -546,13 +574,14 @@ possible.
*<plug>(wiki-journal-toweek)*
*WikiJournalToWeek*
Go to week summary. If not existing, then parse the day entries to make
a first draft. The title is given by |g:wiki_template_title_week|.
a first draft. The title is given by |g:wiki_template_title_week|. For more
info, see |wiki-templates-journal-summaries|.

*<plug>(wiki-journal-tomonth)*
*WikiJournalToMonth*
Go to month summary. If not existing, then parse the day entries and
relevant week summaries to make a first draft. The title is given by
|g:wiki_template_title_month|.
|g:wiki_template_title_month|. See also |wiki-templates-journal-summaries|.

*<plug>(wiki-export)*
[range]*WikiExport* [options] [fname]
Expand Down Expand Up @@ -876,5 +905,85 @@ Related commands:
Related settings:
- |g:wiki_tags|

==============================================================================
TEMPLATES *wiki-templates*

New pages are empty by default. However, it is possible to define templates
for prefilling new pages. Template files are specified in the option
|g:wiki_template_files|, and if any of these files are found, then they are
used to prefill a new page.

Template files are formatted as described in |wiki-templates-format|.

There is also a special kind of journal summary template which is described in
|wiki-templates-journal-summaries|.

Related settings:
- |g:wiki_template_files|

------------------------------------------------------------------------------
TEMPLATE FILE FORMAT *wiki-templates-format*

A template file is essentially a simple text file to your liking. There are
two rules that allow dynamic templates:

1. Variable substitution with `{variable}` strings. The allowed variables
are restricted to a set of pre-defined variables, see below.
2. Function substitution with `{{Function Arg1 Arg2 ...}}` strings. The
function is assumed to return either a string or a list of strings.

The first rule is applied first, which allows the arguments in Rule 2 to be
variable substitutions.

Pre-defined variables:~
`{date}`
`{time}`
`{pagetitle}`
`{pagesection}`
`{last_pagetitle}`
`{last_pagesection}`

Pre-defined functions:~
`wiki#template#case_title(string)`

An example of how these templates could be useful: If you keep a separate blog
directory in your wiki, you could add a `.template.md` file with the following
content to ensure that you follow the same structure: >
# {{wiki#template#case_title {pagetitle}}}
Created: {date} {time}
# Introduction
# Conclusion
------------------------------------------------------------------------------
JOURNAL SUMMARIES *wiki-templates-journal-summaries*

|wiki.vim| supports parsing the journal entries in order to make weekly and
monthly summaries. A summary is automatically created when a summary file is
opened; the format is given by `g:wiki_journal.date_format.weekly` and
`g:wiki_journal.date_format.monthly`. One may also move from a daily entry to
the corresponding week with |WikiJournalToWeek|, and similarly to the
corresponding month with |WikiJournalToMonth|. Again, if these entries do not
exist, they are automatically created and journal entries are parsed to fill
the contents.

The parsed results typically need manual editing, and it currently only works
for a very specific format of journals.

Related settings:
- |g:wiki_journal|
Note: The date format specifies the format for the weekly and monthly
entries.
- |g:wiki_template_title_week|
A string that specifies the title of the weekly summary.
- |g:wiki_template_title_month|
A string that specifies the title of the monthly summary.

Related commands:
- |WikiJournalToWeek|
- |WikiJournalToMonth|

==============================================================================
vim:tw=78:ts=8:ft=help:norl:

0 comments on commit 3ed6ccf

Please sign in to comment.