actions
/
mdBook
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Apply suggestions from code review 

improved readability and cleared sections which could have caused more confusion

Co-authored-by: Eric Huss <eric@huss.org>
This commit is contained in:
Paul 2021-03-08 20:39:39 +01:00 committed by GitHub
parent 5637a66459
commit dcccd3289d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 11 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
guide/src/for_developers/preprocessors.md
View File

@ -34,8 +34,15 @@ command = "python3 /path/to/foo.py"
renderer = ["html", "epub"] renderer = ["html", "epub"]
``` ```
Once the preprocessor has been defined and the build process has started, MdBook will execute the command defined in the `preprocessor.foo.command` key passing the arguments support and the renderer name, monitoring the status code of the executed command. Once the preprocessor has been defined and the build process starts, mdBook executes the command defined in the `preprocessor.foo.command` key twice.
If the status code retrieved is 0, the library will be sending through stdin both the context and the book representation serialized in JSON format, and it'll be capturing the response from stdout, which will be the modified book which has to also be serialized in json format. The first time it runs the preprocessor to determine if it supports the given renderer.
mdBook passes two arguments to the process: the first argument is the string `supports` and the second argument is the renderer name.
The preprocessor should exit with a status code 0 if it supports the given renderer, or return a non-zero exit code if it does not.
If the preprocessor supports the renderer, then mdbook runs it a second time, passing JSON data into stdin.
The JSON consists of an array of `[context, book]` where `context` is the serialized object [`PreprocessorContext`] and `book` is a [`Book`] object containing the content of the book.
The preprocessor should return the JSON format of the [`Book`] object to stdout, with any modifications it wishes to perform.
The easiest way to get started is by creating your own implementation of the The easiest way to get started is by creating your own implementation of the
`Preprocessor` trait (e.g. in `lib.rs`) and then creating a shell binary which `Preprocessor` trait (e.g. in `lib.rs`) and then creating a shell binary which
@ -107,7 +114,7 @@ fn remove_emphasis(
For everything else, have a look [at the complete example][example]. For everything else, have a look [at the complete example][example].
## implementing a preprocessor with a different language ## implementing a preprocessor with a different language
The fact that MdBook utilizes stdin and stdout to communicate with the preprocessors, makes it easy for developers to implement them in a language different than rust. The fact that mdBook utilizes stdin and stdout to communicate with the preprocessors makes it easy to implement them in a language other than Rust.
The following code shows how to implement a simple preprocessor in python, which will modify the content of the first chapter. The following code shows how to implement a simple preprocessor in python, which will modify the content of the first chapter.
The example will follow the configuration shown above with `preprocessor.foo.command` actually pointing to a python script. The code of said script is below: The example will follow the configuration shown above with `preprocessor.foo.command` actually pointing to a python script. The code of said script is below:
@ -126,7 +133,7 @@ if __name__ == '__main__':
stdin = sys.stdin stdin = sys.stdin
context, book = json.load(stdin) context, book = json.load(stdin)
# and now, we can just modify the content of the first chapter # and now, we can just modify the content of the first chapter
book['sections'][0]['Chapter']['content'] = '<h3>Hello</h3>' book['sections'][0]['Chapter']['content'] = '# Hello'
# we are done with the book's modification, we can just print it to stdout, # we are done with the book's modification, we can just print it to stdout,
print(json.dumps(book)) print(json.dumps(book))
``` ```