Add use as a Quarto extension documentation

README.md

@@ -11,8 +11,9 @@ This repository exists thanks to the work of [Albert
 KREWINKEL](https://github.com/tarleb/) among other things in
 [pandoc/lua-filters](https://github.com/pandoc/lua-filters/issues/207).
 
+## Lua filter for pandoc
 
-## Installing
+### Installing
 
 The filter can be used without special installation, just by passing
 the `include-code-files.lua` file path to pandoc via
@@ -23,12 +24,12 @@ filters directory of pandoc's user data directory. This allows to use
 the filter just by using the filename, without having to specify the
 full file path.
 
-## Using
+### Using
 
 The filter recognizes code blocks with the `include` attribute present. It
 swaps the content of the code block with contents from a file.
 
-### Including Files
+#### Including Files
 
 The simplest way to use this filter is to include an entire file:
 
@@ -40,7 +41,7 @@ You can still use other attributes, and classes, to control the code blocks:
     ```{.c include="hello.c" numberLines}
     ```
 
-### Ranges
+#### Ranges
 
 If you want to include a specific range of lines, use `startLine` and `endLine`:
 
@@ -49,7 +50,7 @@ If you want to include a specific range of lines, use `startLine` and `endLine`:
 
 `start-line` and `end-line` alternatives are also recognized.
 
-### Dedent
+#### Dedent
 
 Using the `dedent` attribute, you can have whitespaces removed on each line,
 where possible (non-whitespace character will not be removed even if they occur
@@ -67,10 +68,69 @@ location in the source file.
     ```{include="hello.c" startLine=35 endLine=80 .numberLines}
     ```
 
-## Example
+### Example
 
 An HTML version of [input.md](test/input.md) can be produced as
 [output.html](test/output.html) with this command:
 
     pandoc -s --lua-filter=include-code-files.lua test/input.md --output test/output.html
 
+
+## Extension for Quarto
+
+![Screenshot of an example output using include-code-files](docs/example-screenshot.png)
+
+
+### Installing
+
+```bash
+quarto add SamEdwardes/include-code-files
+```
+
+This will install the extension under the `_extensions`
+subdirectory. You will want to check in this directory if you're using
+version control.
+
+### Using
+
+To use the include-code-files filter, add it to your documents YAML
+front matter:
+
+```yaml
+---
+title: "My doc"
+filters:
+  - include-code-files
+---
+```
+
+With the include-code-files filter, you can include code snippets
+directly from a file using `include`. For example, you may have a
+python script like this:
+
+```python
+# _snippets/hello_world.py
+for name in ["Sam", "Jake"]:
+    print(f"Hello {name}!")
+```
+
+To render this file in a code chunk, use the `include` attribute:
+
+``````markdown
+```{.python include="_snippets/hello_world.py"}
+```
+``````
+
+You can combine this with other quarto attributes like `filename` or `code-line-numbers`:
+
+``````markdown
+```{.python include="_snippets/hello_world.py" filename="hello_world.py" code-line-numbers="true"}
+```
+``````
+
+### Example
+
+Here is the source code for a minimal example:
+[example.qmd](docs/example.qmd). See a rendered sample here:
+<https://samedwardes.quarto.pub/example-for-include-code-files-filter/>.
+

docs/_publish.yml

+- source: example.qmd
+  quarto-pub:
+    - id: 509ab2f5-de97-45f6-b5e8-bb1304c1797d
+      url: 'https://quartopub.com/sites/samedwardes/example-for-include-code-files-filter'

docs/_snippets/hello_world.py

+for name in ["Sam", "Jake"]:
+    print(f"Hello {name}!")
\ No newline at end of file

docs/example.qmd

+---
+title: "Example for include-code-files filter"
+filters:
+  - include-code-files
+---
+
+With the include-code-files filter, you can include code snippets directly from a file using the `include` attribute.
+
+```{.python include="_snippets/hello_world.py"}
+```
+
+You can combine this with other quarto attributes like `filename` or `code-line-numbers`:
+
+```{.python include="_snippets/hello_world.py" filename="hello_world.py" code-line-numbers="true"}
+```
\ No newline at end of file