Provide an example `use-package’ declaration.
[pelican-mode.git] / README.md
1 pelican-mode is an Emacs minor mode for editing articles and pages in
2 [Pelican][] sites.
3
4 It's intended to be used alongside a major mode for the Pelican
5 document. Currently supported formats are Markdown, reStructuredText,
6 AsciiDoc, and Org. It also assumes you've set up Pelican with
7 `pelican-quickstart` or something like it. In particular it expects:
8
9 * The existence of `pelicanconf.py` and `Makefile` in some ancestor
10 directory.
11 * The first component of the path (e.g. `content`) after that
12 ancestor is irrelevant.
13 * If the next component is `pages`, that indicates a static page
14 rather than a dated post.
15
16
17 ## Quick Guide
18
19 To enable by default on all text files in a Pelican site:
20
21 ``` emacs-lisp
22 (require 'pelican-mode)
23 (pelican-global-mode)
24 ```
25
26 Or with `use-package` and deferred loading:
27
28 ``` emacs-lisp
29 (use-package pelican-mode
30 :after (:any org rst markdown-mode adoc-mode)
31 :config
32 (pelican-global-mode))
33 ```
34
35 Or, register `pelican-mode` or `pelican-mode-enable-if-site`
36 as hook functions for more direct control.
37
38 * `C-c P d` - Update the document’s date
39 * `C-c P f` - Set a metadata field (title, category, etc.)
40 * `C-c P h` - Generate HTML output for a site (equivalent to `make html`)
41 * `C-c P n` - Insert a post or page header
42 * `C-c P p` - Remove draft status from a post (i.e. publish it)
43 * `C-c P u` - Upload a site using rsync (equivalent to `make rsync_upload`)
44
45
46 ## Troubleshooting
47
48 If the commands which invoke `make` can find the Makefile but can't
49 find `pelican`, your `exec-path` may not be set right. Try out
50 [exec-path-from-shell][].
51
52
53 ## License
54
55 This program is free software; you can redistribute it and/or modify
56 it under the terms of the GNU General Public License as published by
57 the Free Software Foundation, either version 3 of the License, or (at
58 your option) any later version.
59
60 [Pelican]: http://getpelican.com/
61 [markdown-mode]: http://jblevins.org/projects/markdown-mode/
62 [rst-mode]: http://docutils.sourceforge.net/docs/user/emacs.html
63 [exec-path-from-shell]: https://github.com/purcell/exec-path-from-shell