Skip to content
Snippets Groups Projects
Unverified Commit 9c66df5a authored by Bruno BEAUFILS's avatar Bruno BEAUFILS Committed by GitHub
Browse files

Merge pull request #4 from b3/remove-quarto

Remove quarto
parents 6d530141 c10d05ce
No related branches found
No related tags found
No related merge requests found
MIT License
Copyright © 2020–2022 Bruno BEAUFILS, 2022 Sam Edwardes.
Copyright © 2020–2022 Bruno BEAUFILS.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
......
......@@ -13,16 +13,13 @@ FILTER_FILE := include-code-files.lua
# Name of the filter, *without* `.lua` file extension
FILTER_NAME = $(patsubst %.lua,%,$(FILTER_FILE))
# Directory containing the Quarto extension
QUARTO_EXT_DIR = _extensions/$(FILTER_NAME)
# Current version (the latest tag). Used for quarto extension
# Current version (the latest tag).
VERSION = $(shell git tag --sort=-version:refname --merged | head -n1 | \
sed -e 's/^v//' | tr -d "\n")
## Show available targets
# Comments preceding "simple" targets (those which do not user macro
# name) and introduced by two dashes are used as their describtion.
# Comments preceding "simple" targets (those which do not use macro
# name) and introduced by two dashes are used as their description.
.PHONY: help
help:
@tabs 22 ; $(SED) -ne \
......@@ -46,23 +43,9 @@ test/expected.native: $(FILTER_FILE) test/input.md test/test.yml
test/output.html: $(FILTER_FILE) test/input.md
$(PANDOC) -s --lua-filter=$< test/input.md --output=$@
## Creates or updates the quarto extension
.PHONY: quarto-extension
quarto-extension: $(QUARTO_EXT_DIR)/_extension.yml \
$(QUARTO_EXT_DIR)/$(FILTER_FILE)
$(QUARTO_EXT_DIR):
mkdir -p $@
# This may change, so re-create the file every time
.PHONY: $(QUARTO_EXT_DIR)/_extension.yml
$(QUARTO_EXT_DIR)/_extension.yml: _extensions/$(FILTER_NAME)
@printf 'Updating %s\n' $@
@sed -i -e 's/^version:.*$$/version: $(VERSION)/' $@
## Sets a new release using VERSION
.PHONY: release
release: quarto-extension
release:
git commit -am "Release $(FILTER_NAME) $(VERSION)"
git tag v$(VERSION) -m "$(FILTER_NAME) $(VERSION)"
......
......@@ -11,15 +11,14 @@ 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).
## Quick Start
The `include-code-files` filter supports pandoc and quarto.
If you are a Quarto user, please use the official extension from the Quarto team:
<https://github.com/quarto-ext/include-code-files>.
### Pandoc
## Quick Start
Install the extension whether by simply downloading the
[include-code-files.lua](_extensions/include-code-files/include-code-files.lua)
file somewhere on your computer or by cloning this repository:
[include-code-files.lua](include-code-files.lua) file somewhere on
your computer or by cloning this repository:
```bash
git clone https://github.com/b3/include-code-files.git
......@@ -38,35 +37,9 @@ When rendering include the path to `include-code-files.lua`
pandoc -s --lua-filter=include-code-files.lua test/input.md --output test/output.html
```
For complete details see the [Lua filter for pandoc](#lua-filter-for-pandoc) section below.
### Quarto
Install the extension:
```bash
quarto add b3/include-code-files@quarto
```
Use the extension in any `.qmd` file by including the filter in the YAML front matter.
``````markdown
---
filters:
- include-code-files
---
```{.python include="_snippets/hello_world.py"}
```
``````
For complete details see the [Extension for Quarto](#extension-for-quarto) section below.
## Lua filter for pandoc
For complete details see following sections below.
### Installing
## Installing
The filter can be used without special installation, just by passing
the `include-code-files.lua` file path to pandoc via
......@@ -77,12 +50,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:
......@@ -94,7 +67,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`:
......@@ -103,7 +76,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
......@@ -121,69 +94,9 @@ 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](examples/quarto/screenshot.png)
### Installing
```bash
quarto add b3/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:
[examples/quarto/index.qmd](examples/quarto/index.qmd). See a rendered sample here:
<https://samedwardes.quarto.pub/example-for-include-code-files-filter/>.
name: include-code-files
author: Bruno Beaufils, Sam Edwardes
version: 1.0.0
quarto-required: ">=1.2.0"
contributes:
filters:
- include-code-files.lua
--- include-code-files.lua – filter to include code from source files
---
--- Copyright: © 2020 Bruno BEAUFILS
--- License: MIT – see LICENSE file for details
--- Dedent a line
local function dedent (line, n)
return line:sub(1,n):gsub(" ","") .. line:sub(n+1)
end
--- Filter function for code blocks
local function transclude (cb)
if cb.attributes.include then
local content = ""
local fh = io.open(cb.attributes.include)
if not fh then
io.stderr:write("Cannot open file " .. cb.attributes.include .. " | Skipping includes\n")
else
local number = 1
local start = 1
-- change hyphenated attributes to PascalCase
for i,pascal in pairs({"startLine", "endLine"})
do
local hyphen = pascal:gsub("%u", "-%0"):lower()
if cb.attributes[hyphen] then
cb.attributes[pascal] = cb.attributes[hyphen]
cb.attributes[hyphen] = nil
end
end
if cb.attributes.startLine then
cb.attributes.startFrom = cb.attributes.startLine
start = tonumber(cb.attributes.startLine)
end
for line in fh:lines ("L")
do
if cb.attributes.dedent then
line = dedent(line, cb.attributes.dedent)
end
if number >= start then
if not cb.attributes.endLine or number <= tonumber(cb.attributes.endLine) then
content = content .. line
end
end
number = number + 1
end
fh:close()
end
-- remove key-value pair for used keys
cb.attributes.include = nil
cb.attributes.startLine = nil
cb.attributes.endLine = nil
cb.attributes.dedent = nil
-- return final code block
return pandoc.CodeBlock(content, cb.attr)
end
end
return {
{ CodeBlock = transclude }
}
index.html
index_files/*
name: include-code-files
author: Sam Edwardes
version: 1.0.0
quarto-required: ">=1.2.0"
contributes:
filters:
- include-code-files.lua
--- include-code-files.lua – filter to include code from source files
---
--- Copyright: © 2020 Bruno BEAUFILS
--- License: MIT – see LICENSE file for details
--- Dedent a line
local function dedent (line, n)
return line:sub(1,n):gsub(" ","") .. line:sub(n+1)
end
--- Filter function for code blocks
local function transclude (cb)
if cb.attributes.include then
local content = ""
local fh = io.open(cb.attributes.include)
if not fh then
io.stderr:write("Cannot open file " .. cb.attributes.include .. " | Skipping includes\n")
else
local number = 1
local start = 1
-- change hyphenated attributes to PascalCase
for i,pascal in pairs({"startLine", "endLine"})
do
local hyphen = pascal:gsub("%u", "-%0"):lower()
if cb.attributes[hyphen] then
cb.attributes[pascal] = cb.attributes[hyphen]
cb.attributes[hyphen] = nil
end
end
if cb.attributes.startLine then
cb.attributes.startFrom = cb.attributes.startLine
start = tonumber(cb.attributes.startLine)
end
for line in fh:lines ("L")
do
if cb.attributes.dedent then
line = dedent(line, cb.attributes.dedent)
end
if number >= start then
if not cb.attributes.endLine or number <= tonumber(cb.attributes.endLine) then
content = content .. line
end
end
number = number + 1
end
fh:close()
end
-- remove key-value pair for used keys
cb.attributes.include = nil
cb.attributes.startLine = nil
cb.attributes.endLine = nil
cb.attributes.dedent = nil
-- return final code block
return pandoc.CodeBlock(content, cb.attr)
end
end
return {
{ CodeBlock = transclude }
}
- source: index.qmd
quarto-pub:
- id: 509ab2f5-de97-45f6-b5e8-bb1304c1797d
url: 'https://quartopub.com/sites/samedwardes/example-for-include-code-files-filter'
for name in ["Sam", "Jake"]:
print(f"Hello {name}!")
\ No newline at end of file
---
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
examples/quarto/screenshot.png

1.67 MiB

_extensions/include-code-files/include-code-files.lua
\ No newline at end of file
--- include-code-files.lua – filter to include code from source files
---
--- Copyright: © 2020 Bruno BEAUFILS
--- License: MIT – see LICENSE file for details
--- Dedent a line
local function dedent (line, n)
return line:sub(1,n):gsub(" ","") .. line:sub(n+1)
end
--- Filter function for code blocks
local function transclude (cb)
if cb.attributes.include then
local content = ""
local fh = io.open(cb.attributes.include)
if not fh then
io.stderr:write("Cannot open file " .. cb.attributes.include .. " | Skipping includes\n")
else
local number = 1
local start = 1
-- change hyphenated attributes to PascalCase
for i,pascal in pairs({"startLine", "endLine"})
do
local hyphen = pascal:gsub("%u", "-%0"):lower()
if cb.attributes[hyphen] then
cb.attributes[pascal] = cb.attributes[hyphen]
cb.attributes[hyphen] = nil
end
end
if cb.attributes.startLine then
cb.attributes.startFrom = cb.attributes.startLine
start = tonumber(cb.attributes.startLine)
end
for line in fh:lines ("L")
do
if cb.attributes.dedent then
line = dedent(line, cb.attributes.dedent)
end
if number >= start then
if not cb.attributes.endLine or number <= tonumber(cb.attributes.endLine) then
content = content .. line
end
end
number = number + 1
end
fh:close()
end
-- remove key-value pair for used keys
cb.attributes.include = nil
cb.attributes.startLine = nil
cb.attributes.endLine = nil
cb.attributes.dedent = nil
-- return final code block
return pandoc.CodeBlock(content, cb.attr)
end
end
return {
{ CodeBlock = transclude }
}
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment