include-file 0.0.5

Replace {% include 'file.txt' %} with actual file contents

Include File

Managing documentation is always challenging.

1. Some information ([ex] setting up git command) might come up in multiple documentation
   • see Include, path
2. Some files are too large so it's better to put link ([ex] jupyter, data files)
   • see Link
3. Need entire file structure or show different instructions per language ([ex] python, java)
   • see Repo ([Note] in Gitbook syntax)

Usage

• pip install include_file

• Fix images

  • python3 -m include_file -u seanhwangg -p ~/github/home -t README.md -y SUMMARY.md --home

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

glob

• Which glob files to embed
• Default: "**/*"

path

• Where to look for embed file
• Default: ./.include-file/

stem

• Use stem of markdown to overwrite path
• Default: False
• [ex] embeds for REAMD.md are stored in README/embed.txt

validate

• Whether to fail CI in case of embed error
• Default: True

Gitbook Flags

Note: These are completely optional for Gitbook users

deploy_branch

• Change deploy_branch of gitbook
• Default: "deploy"

url_path

• Change url of embeds

Input

• -url / --url_path: https://seanhwangg.gitbook.io/ [default]

toc

• Create table of contents with URL
• Default: "", None

Input

• -t / --toc

<!-- myrepo/SUMMARY.md -->
* [A]()
  * [B](A/B.md)
  * [C](A/C.md)

<!-- myrepo/A/B.md -->
# 1

## 2

<!-- myrepo/A/C.md -->
# 3

## 4

### 5

Output

# Table of Contents

## A

### B.md

* [1](https://seanhwangg.gitbook.io/myrepo/A/B#1)
  * [2](https://seanhwangg.gitbook.io/myrepo/A/B#2)

### C.md

* [3](https://seanhwangg.gitbook.io/myrepo/A/C#3)
  * [4](https://seanhwangg.gitbook.io/myrepo/A/C#4)
    * [5](https://seanhwangg.gitbook.io/myrepo/A/C#5)

Home

Note: This is beta feature

• Fix images
• Default: None

# File structure should be like this
.
├── private
│   └── repo1
│       └── SUMMARY.md
└── public
    └── repo2
        └── SUMMARY.md

Custom Flags

include

• Overwrite default include
• Default: include

Input

<!-- README.md  -->

* List before embed
{% include '.embed.txt' %}
* List after embed

<!-- embed.txt  -->
* I am in embed

Result

<!-- README.md -->
* List before embed
* I am in embed
* List after embed

link

• Overwrite default link
• Default: link

Input

<!-- README.md -->
* List before embed
{% link 'embed.txt' %}
* List after embed

<!-- embed.txt  -->
* I am in embed

Result

<!-- REAMD.md -->
* List before embed
[embed.txt](https://github.com/[user]/[repository]/blob/[deploy_branch]/local.yml)
* List after embed

repo

• Overwrite default repo
• Default: repo

Input

<!-- README.md  -->
* List before embed
{% repo 'embed' %}
* List after embed

<!-- embed/embed1.md  -->
* I am in embed1

<!-- embed/nested/embed2.md  -->
* I am in embed2

Result

<!-- README.md -->
* List before embed

{% tabs %}
{% tab title='embed1.md' %}

* I am in embed1

{% endtab %}
{% tab title='nested/embed2.md' %}

* I am in embed2

{% endtab %}
{% endtabs %}

* List after embed