Replace {% include 'file.txt' %} with actual file contents
Project description
Include File
- Managing documentation is challenging as
- Some information ([ex] setting up git command) might come up in multiple documentation
- put overlaped info in common areas include
- Hard to edit
- Some files are too large so it's better to put link ([ex] jupyter, data files)
- convert link to
- Need entire file structure or show different instructions per language ([ex] python, java)
- convert repository into file tab in gitbook
Usage
- See before and after in tests folder
make e2etest
Github CI
- This pipeline will push to deploy branch
# .github/workflows/main.yml
name: Deploy to deploy branch with include_file
on:
push:
branches: ["main"]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Set up Python 3.9
uses: actions/setup-python@v2
with:
python-version: "3.9"
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install include_file
- name: Include File
run: |
python -m include_file -u $GITHUB_ACTOR -y SUMMARY.md -d deploy -t README.md --stem
# For deployment add following lines
- uses: EndBug/add-and-commit@v7
with:
message: "Committed by seanhwangg/include_file"
pull_strategy: NO-PULL
branch: deploy
push: origin deploy --force -u
Flags
user
- -u: github user id used for link ([ex] seanhwangg)
glob
- -g: Which glob files to include ([ex] "**/*", **/*.md)
path
- -p: Where to look for include file ([ex] ./.include-file/)
stem
- -s: Use stem of markdown to overwrite path ([ex] False)
- includes for
REAMD.md
are stored inREADME/include.txt
validate
- -v: Whether to fail CI in case of include error ([ex] True)
Gitbook Only Flags
Note: These are completely optional for Gitbook users
deploy_branch
- -d: Change deploy_branch of gitbook ([ex] "deploy")
url_path
- -url: Change url of includes ([ex] https://seanhwangg.gitbook.io/)
table_of_contents
- -toc: Create table of contents with URL ([ex] "", "table_of_contents.md")
relocate_include
- -r: Relocate images and include files ([ex] None)
images_overwrite
- -images: Overwrite default
images
([ex] images)
include_overwrite
- -include: Overwrite default
include
([ex] include)
Input
<!-- README.md -->
* List before include
{% include '.include.txt' %}
* List after include
<!-- include.txt -->
* I am in include
Result
<!-- README.md -->
* List before include
* I am in include
* List after include
link_overwrite
- -link: Overwrite default
link
([ex] link)
Example
- Input
<!-- README.md -->
* List before include
{% link 'include.txt' %}
* List after include
<!-- include.txt -->
* I am in include
- Result
<!-- REAMD.md -->
* List before include
[include.txt](https://github.com/[user]/[repository]/blob/[deploy_branch]/local.yml)
* List after include
repo_overwrite
- -repo: Overwrite default
repo
- Default: repo
Input
<!-- README.md -->
* List before include
{% repo 'include' %}
* List after include
<!-- include/include1.md -->
* I am in include1
<!-- include/nested/include2.md -->
* I am in include2
Result
<!-- README.md -->
* List before include
{% tabs %}
{% tab title='include1.md' %}
* I am in include1
{% endtab %}
{% tab title='nested/include2.md' %}
* I am in include2
{% endtab %}
{% endtabs %}
* List after include
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
include-file-0.0.15.tar.gz
(7.2 kB
view hashes)
Built Distribution
Close
Hashes for include_file-0.0.15-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b4d6090c4230c5bd233744e03fedfde9a77264227626db18b0f0e8ddc52e93f5 |
|
MD5 | b353f4ac172ea1a151e041229f64ee99 |
|
BLAKE2b-256 | 97319fef24ba732c69a1937a2318893a47f02f6a8b99ac50d0c2226dcd9916e2 |