|
1 |
| -# Include Code Files Extension For Quarto |
| 1 | +# Add Code Files Extension For Quarto |
2 | 2 |
|
3 |
| -This extension provides filter that to include code from source files. |
| 3 | +This extension provides filter that to add code from source files. |
4 | 4 |
|
5 |
| -:information_source: This filter is an alternative to the [include-code-files](https://github.com/quarto-ext/include-code-files) by [@quarto-ext](https://github.com/quarto-ext) with [`code-fold`](https://quarto.org/docs/output-formats/html-code.html#folding-code)-ing capability. If you just want to include contents from another file and do not care about code-folding you probably want to use the former filter, which is simpler to use. |
| 5 | +:information_source: This filter is an alternative to the [include-code-files](https://github.com/quarto-ext/include-code-files) by [@quarto-ext](https://github.com/quarto-ext) with [`code-fold`](https://quarto.org/docs/output-formats/html-code.html#folding-code)-ing capability. If you just want to add contents from another file and do not care about code-folding you probably want to use the former filter, which is simpler to use. |
6 | 6 |
|
7 | 7 | ## Installing
|
8 | 8 |
|
9 | 9 | :warning: This extension requires quarto version at least to be 1.2.
|
10 | 10 |
|
11 | 11 | ```bash
|
12 |
| -quarto add shafayetShafe/include-code-files |
| 12 | +quarto add shafayetShafe/add-code-files |
13 | 13 | ```
|
14 | 14 |
|
15 | 15 | This will install the extension under the `_extensions` subdirectory.
|
16 | 16 | If you're using version control, you will want to check in this directory.
|
17 | 17 |
|
18 | 18 | ## Usage
|
19 | 19 |
|
20 |
| -The filter recognizes [Divs](https://quarto.org/docs/authoring/markdown-basics.html#divs-and-spans) or code-chunk with the `include-from` attribute present. It swaps the content of the code block with contents from a file. |
| 20 | +The filter recognizes [Divs](https://quarto.org/docs/authoring/markdown-basics.html#divs-and-spans) or code-chunk with the `add-from` attribute present. It swaps the content of the code block with contents from a file. |
21 | 21 |
|
22 | 22 | Here is how you add the filter to a quarto document,
|
23 | 23 |
|
24 | 24 | ```
|
25 | 25 | ---
|
26 | 26 | title: "Quarto"
|
27 | 27 | filters:
|
28 |
| - - include-code-files |
| 28 | + - add-code-files |
29 | 29 | ---
|
30 | 30 | ```
|
31 | 31 |
|
32 | 32 | ### Including Files
|
33 | 33 |
|
34 |
| -Once adding the filter to the quarto document, use the `include-from` attribute in a Div containing a empty code-block. For example, |
| 34 | +Once adding the filter to the quarto document, use the `add-from` attribute in a Div containing a empty code-block. For example, |
35 | 35 |
|
36 | 36 | ````
|
37 |
| -::: {include-from=hello-world.cpp} |
| 37 | +::: {add-from=hello-world.cpp} |
38 | 38 | ```{.cpp}
|
39 | 39 | ```
|
40 | 40 | :::
|
41 | 41 | ````
|
42 | 42 |
|
43 |
| -would include the codes from `hello-world.cpp` within that `.cpp` code block. And you need to use `.cpp` to get correct syntax highlighting for added c++ code. Run `quarto pandoc --list-highlight-languages` to get the list of languages for which syntax highlighting is supported. |
| 43 | +would add the codes from `hello-world.cpp` within that `.cpp` code block. And you need to use `.cpp` to get correct syntax highlighting for added c++ code. Run `quarto pandoc --list-highlight-languages` to get the list of languages for which syntax highlighting is supported. |
44 | 44 |
|
45 | 45 | You can also use the following options,
|
46 | 46 |
|
47 |
| -- **`start-line`**, **`end-line`**: To include a specific range of lines. |
| 47 | +- **`start-line`**, **`end-line`**: To add a specific range of lines. |
48 | 48 | - **`code-line-numbers`**: To enable source code line numbering.
|
49 | 49 | - **dedent**: using this you can have whitespaces removed on each line, where possible (non-whitespace character will not be removed even if they occur in the dedent area).
|
50 | 50 |
|
51 | 51 | ````
|
52 |
| -::: {include-from=hello-world.cpp start-line=1 end-line=8 code-line-numbers="true"} |
| 52 | +::: {add-from=hello-world.cpp start-line=1 end-line=8 code-line-numbers="true"} |
53 | 53 | ```{.cpp}
|
54 | 54 | ```
|
55 | 55 | :::
|
56 | 56 | ````
|
57 | 57 |
|
58 | 58 | View the live demo of
|
59 | 59 |
|
60 |
| -- [document rendered with `jupyter`](https://shafayetshafee.github.io/include-code-files/example.html) |
| 60 | +- [document rendered with `jupyter`](https://shafayetshafee.github.io/add-code-files/example.html) |
61 | 61 |
|
62 |
| -- [document rendered with `knitr`](https://shafayetshafee.github.io/include-code-files/example_knitr.html) |
| 62 | +- [document rendered with `knitr`](https://shafayetshafee.github.io/add-code-files/example_knitr.html) |
63 | 63 |
|
64 | 64 | ### filename and code-filename
|
65 | 65 |
|
66 |
| -You can also use the `filename` attribute to show a name of the file the included code is associated with. But the issue is, the attribute `filename` does not work with `code-folding` as intended for that code block. This filter provides another option `code-filename` which works with `code-folding`. |
| 66 | +You can also use the `filename` attribute to show a name of the file the added code is associated with. But the issue is, the attribute `filename` does not work with `code-folding` as intended for that code block. This filter provides another option `code-filename` which works with `code-folding`. |
67 | 67 |
|
68 | 68 | Therefore, use `code-filename` only when using `code-fold: true`, otherwise use `filename` (for non HTML format or for html format without `code-fold: true`)
|
69 | 69 |
|
70 | 70 | **`code-filename` only works with `code-folding`. For othercases, use `filename`**
|
71 | 71 |
|
72 |
| -View a [live demo of this issue](https://shafayetshafee.github.io/include-code-files/example_filename.html) |
| 72 | +View a [live demo of this issue](https://shafayetshafee.github.io/add-code-files/example_filename.html) |
73 | 73 |
|
0 commit comments