diff options
| author | Shahbaz Youssefi <ShabbyX@gmail.com> | 2023-04-02 03:15:37 -0400 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2023-04-02 01:15:37 -0600 |
| commit | ed8a5dc529bbadbc6894b65b35d14df1a275a5ef (patch) | |
| tree | 23ebb13b8a07737612281da89cfad1250d88b9b9 /docs/modules/extensions/pages/preprocessor.adoc | |
| parent | e151958d2e9b7a3b6d47ddd9ed45f78bf8911e7b (diff) | |
document Preprocessor and TreeProcessor more thoroughly (PR #4415)
Diffstat (limited to 'docs/modules/extensions/pages/preprocessor.adoc')
| -rw-r--r-- | docs/modules/extensions/pages/preprocessor.adoc | 20 |
1 files changed, 16 insertions, 4 deletions
diff --git a/docs/modules/extensions/pages/preprocessor.adoc b/docs/modules/extensions/pages/preprocessor.adoc index f0e0e551..177ccd6d 100644 --- a/docs/modules/extensions/pages/preprocessor.adoc +++ b/docs/modules/extensions/pages/preprocessor.adoc @@ -1,10 +1,22 @@ -= Preprocessor Extension Example += Preprocessor Extensions :navtitle: Preprocessor +Preprocessors are run after the source text is split into lines and normalized, but before parsing begins. + +Prior to invoking the preprocessor, Asciidoctor splits the source text into lines and normalizes them. The normalize process strips trailing whitespace and the end of line character sequence from each line. + +Asciidoctor passes the document and the document's Reader to the `Asciidoctor::Extensions::Processor#process` method of the Preprocessor instance. The Preprocessor can modify the Reader as necessary and either return the same Reader (or falsy, which is equivalent) or a reference to a substitute Reader. + +Note that in this process, line numbers are not retained. If the preprocessor adds or removes lines, the parser and other extensions could produce misleading line number information. + +Preprocessor implementations must extend the https://www.rubydoc.info/gems/asciidoctor/Asciidoctor/Extensions/Preprocessor[`Preprocessor`] class. + +== Preprocessor Extension Example + Purpose:: Skim off front matter from the top of the document that gets used by site generators like Jekyll and Awestruct. -== sample-with-front-matter.adoc +=== sample-with-front-matter.adoc [source,asciidoc] ---- @@ -23,7 +35,7 @@ content .... ---- -== FrontMatterPreprocessor +=== FrontMatterPreprocessor [source,ruby] ---- @@ -53,7 +65,7 @@ class FrontMatterPreprocessor < Asciidoctor::Extensions::Preprocessor end ---- -== Usage +=== Usage [source,ruby] ---- |