From 845b9b4dc13c0ff33e1038231742ec00ba4ed76e Mon Sep 17 00:00:00 2001 From: Joseph Nix Date: Mon, 14 May 2018 23:39:17 -0500 Subject: [PATCH] [missing-events] Document the rest of the Lektor plugin events. --- .../plugins/events/after-prune/contents.lr | 9 +++++ .../plugins/events/before-prune/contents.lr | 9 +++++ .../events/markdown-config/contents.lr | 30 ++++++++++++++ .../events/markdown-lexer-config/contents.lr | 17 ++++++++ .../events/markdown-meta-init/contents.lr | 22 +++++++++++ .../markdown-meta-postprocess/contents.lr | 39 +++++++++++++++++++ 6 files changed, 126 insertions(+) create mode 100644 content/docs/api/plugins/events/after-prune/contents.lr create mode 100644 content/docs/api/plugins/events/before-prune/contents.lr create mode 100644 content/docs/api/plugins/events/markdown-config/contents.lr create mode 100644 content/docs/api/plugins/events/markdown-lexer-config/contents.lr create mode 100644 content/docs/api/plugins/events/markdown-meta-init/contents.lr create mode 100644 content/docs/api/plugins/events/markdown-meta-postprocess/contents.lr diff --git a/content/docs/api/plugins/events/after-prune/contents.lr b/content/docs/api/plugins/events/after-prune/contents.lr new file mode 100644 index 00000000..a32fc650 --- /dev/null +++ b/content/docs/api/plugins/events/after-prune/contents.lr @@ -0,0 +1,9 @@ +title: after-prune +--- +body: This event is emitted after before Lektor searches the build directory for data that does not match a known artifact, and removes that data. This event is also emitted after a `clean`, that is, when the build directory is completely purged of all data. +--- +signature: builder, all +--- +summary: This event is emitted after unused data in the build folder is removed. +--- +type: event diff --git a/content/docs/api/plugins/events/before-prune/contents.lr b/content/docs/api/plugins/events/before-prune/contents.lr new file mode 100644 index 00000000..093d2344 --- /dev/null +++ b/content/docs/api/plugins/events/before-prune/contents.lr @@ -0,0 +1,9 @@ +title: before-prune +--- +body: This event is emitted right before Lektor searches the build directory for data that does not match a known artifact. Orphaned data is then removed. This event is also emitted before a `clean`, that is, when the build directory is completely purged of all data. +--- +signature: builder, all +--- +summary: This event is emitted before unused data in the build folder is removed. +--- +type: event diff --git a/content/docs/api/plugins/events/markdown-config/contents.lr b/content/docs/api/plugins/events/markdown-config/contents.lr new file mode 100644 index 00000000..ceb0db81 --- /dev/null +++ b/content/docs/api/plugins/events/markdown-config/contents.lr @@ -0,0 +1,30 @@ +title: markdown-config +--- +body: + +! Future versions of Lektor may change its Markdown parser away from [Mistune](https://github.com/lepture/mistune), and the various markdown related event hooks may be completely removed or work differently if that happens. + +This event is emitted right after MarkdownConfig is instantiated, in which configuration can be set. This is done before the renderer is made. + +## Example + +[lektor-markdown-header-anchors :ext](https://github.com/lektor/lektor-markdown-header-anchors) uses this to register a renderer mixin: + +```python +def on_markdown_config(self, config, **extra): + class HeaderAnchorMixin(object): + def header(renderer, text, level, raw): + if self.get_config().get('anchor-type') == "random": + anchor = uuid.uuid4().hex[:6] + else: + anchor = slugify(raw) + renderer.meta['toc'].append((level, anchor, Markup(text))) + return '%s' % (level, anchor, text, level) + config.renderer_mixins.append(HeaderAnchorMixin) +``` +--- +signature: config +--- +summary: This event is emitted while the Markdown renderer is configured. +--- +type: event diff --git a/content/docs/api/plugins/events/markdown-lexer-config/contents.lr b/content/docs/api/plugins/events/markdown-lexer-config/contents.lr new file mode 100644 index 00000000..0d460d13 --- /dev/null +++ b/content/docs/api/plugins/events/markdown-lexer-config/contents.lr @@ -0,0 +1,17 @@ +title: markdown-lexer-config +--- +module: +--- +type: event +--- +signature: config, renderer +--- +summary: This event is emitted after the renderer is made, but before it is used. +--- +body: + +! Future versions of Lektor may change its Markdown parser away from [Mistune](https://github.com/lepture/mistune), and the various markdown related event hooks may be completely removed or work differently if that happens. + +This event is emitted right after markdown renderer is made, but before it is used to render markdown. This is where lexer configuration can be set. +--- +version_added: 3.1 diff --git a/content/docs/api/plugins/events/markdown-meta-init/contents.lr b/content/docs/api/plugins/events/markdown-meta-init/contents.lr new file mode 100644 index 00000000..d218650e --- /dev/null +++ b/content/docs/api/plugins/events/markdown-meta-init/contents.lr @@ -0,0 +1,22 @@ +title: markdown-meta-init +--- +body: + +! Future versions of Lektor may change its Markdown parser away from [Mistune](https://github.com/lepture/mistune), and the various markdown related event hooks may be completely removed or work differently if that happens. + +This event is emitted before the markdown meta information is set. This can be used to add custom meta variables to the markdown object. + +## Example + +[lektor-markdown-header-anchors :ext](https://github.com/lektor/lektor-markdown-header-anchors) uses this to initialize a meta var as an empty list: + +```python +def on_markdown_meta_init(self, meta, **extra): + meta['toc'] = [] +``` +--- +signature: meta, record +--- +summary: This event is emitted before the markdown meta information is set. +--- +type: event diff --git a/content/docs/api/plugins/events/markdown-meta-postprocess/contents.lr b/content/docs/api/plugins/events/markdown-meta-postprocess/contents.lr new file mode 100644 index 00000000..4e3cafa5 --- /dev/null +++ b/content/docs/api/plugins/events/markdown-meta-postprocess/contents.lr @@ -0,0 +1,39 @@ +title: markdown-meta-postprocess +--- +body: + +! Future versions of Lektor may change its Markdown parser away from [Mistune](https://github.com/lepture/mistune), and the various markdown related event hooks may be completely removed or work differently if that happens. + +This event is emitted after the markdown has been rendered. This can be used to change the markdown object meta information after the fact. + +## Example + +[lektor-markdown-header-anchors :ext](https://github.com/lektor/lektor-markdown-header-anchors) uses this to populate a meta var: + +```python +def on_markdown_meta_postprocess(self, meta, **extra): + prev_level = None + toc = [] + stack = [toc] + + for level, anchor, title in meta['toc']: + if prev_level is None: + prev_level = level + elif prev_level == level - 1: + stack.append(stack[-1][-1][2]) + prev_level = level + elif prev_level > level: + while prev_level > level: + if len(stack) > 1: + stack.pop() + prev_level -= 1 + stack[-1].append(TocEntry(anchor, title, [])) + + meta['toc'] = toc +``` +--- +signature: meta, record +--- +summary: This event is emitted after the markdown meta information is set. +--- +type: event