This repository has been archived on 2023-06-11. You can view files and clone it, but cannot push or open issues or pull requests.
blog.lazkani.io-20200902-hi.../plugins/orgmode/README.md

52 lines
2.1 KiB
Markdown

This plugin implements an Emacs Org-mode based compiler for Nikola.
## Setup
If your emacs does not ship with org-mode (>=8.x), you will have to edit the
`init.el` file supplied with this plugin, and load a newer version of org-mode.
You will also need to add the orgmode compiler to your list of compilers, and
modify your POSTS & PAGES variables. (See the sample conf file provided.)
### Syntax highlighting with pygments
By default, the plugin uses `pygments` for syntax highlighting. You can disable
this by setting `nikola-use-pygments` to `nil` in `init.el` or `conf.el` (see
Customization section below).
To get proper syntax highlighting, you will need to add custom CSS to your
theme. You can generate this CSS using the `pygmentize` command as follows:
mkdir -p files/assets/css
pygmentize -S <PYGMENTS_STYLE> -a .highlight -f html >> files/assets/css/custom.css
and make sure that `custom.css` is included in your site by your
theme. The various available style options for `<PYGMENTS_STYLE>` can be found
using the command `pygmentize -L style`.
## Customization
You can add any customization variables that you wish to add, to modify the
output generated by org-mode to `conf.el` inside the plugin directory. This
lets you have custom configuration, that doesn't get wiped out each time the
plugin is updated.
## Teasers
You may use teasers by enabling `INDEX_TEASERS = True` in conf.py, and
use `{{{TEASER_END}}}` to generate `<!-- TEASER_END -->` in org posts.
## Image URLs
The image url in ox-html is a little fuzzy. For example, `[[/images/test.jpg]]` will be
generated as `<img src="file:///images/test.jpg" alt="test.jpg">`
because the path is considered as an absolute file path.
If you add inline images with built-in file scheme to see them on your
Emacs orgmode, the references are resolved. For examples, you may
refer with `[[file:../images/test.jpg]]` to review an image stored on
images directory during writing, then it will be generated as `<img
src="images/test.jpg" alt="test.jpg">`.
Alternatively, you may write `[[img-url:/images/test.jpg]]`, and then
it should be generated as `<img src="/images/test.jpg" alt="test.jpg">`.