Import any lines, from anywhere
Importer is a CLI tool to allow any file to import other file content, including Markdown, YAML, to name a few. Importer uses Importer Markers, which are often provided as comment, to find the relevant file and import defined lines based on line numbers and other details.
Files such as Markdown and YAML which are meant to be a single file input can pull in other files. Importer aims to provide this extra feature without breaking the language syntax. Importer accomplishes this with a code generation approach, where the Markers are used to update the file in place.
This may seem like an unnecessary layer for simple files such as Markdown and YAML, but this allows better structure and code reuse, while retaining or even enhancing code readability.
You can find more about the details of Importer design here.
You can get Importer with simple Homebrew command.
$ brew install upsidr/tap/importer
You can also find the relevent binary files under releases.
Other Installation Options
You can also use Go to install.
$ go get github.com/upsidr/importer/cmd/importer@v0.1.0
Name | Description |
---|---|
importer preview FILE |
Write before/purged/after preview of how Importer processes the file content to stdout. |
importer update FILE |
Run Importer processing on FILE , and update it in place. |
importer purge FILE |
Parse Importer Markers, remove any content within Importer Markers, and update the file in plcae. |
importer generate FILE |
Run Importer processing on FILE , and write the result to stdout. |
You can find more about the commands here.
Because Importer works by parsing language comments, the below are the list of files supported at the moment.
File Type | Is Supported? | File Extensions | Additional Importer Option |
---|---|---|---|
Markdown | ✅ | .md |
|
YAML | ✅ | .yaml , .yml |
Indentation |
HTML | 🚧 | TBC | |
TOML | 🚧 | TBC |
To request additional file support, please file an issue from here.
Markers are a simple comment with special syntax Importer understands. Importer is a simple CLI tool, and these markers are the key to make all the import and export to happen. There are several types of markers.
Name | Description |
---|---|
Importer Marker | Main marker, used to import data from other file. |
Exporter Marker | Supplemental marker used to define line range in target files. |
Skip Importer Update | Special marker to suppress importer update . |
Auto Generated Note | Special marker for importer generate information. |
You can find more about the markers here.
importer preview
command gives you a quick look at how the file may change when importer update
and importer purge
are run against the provided file. This is meant to be useful for testing and debugging.
importer-preview-yaml-demo.mp4
importer update
imports based on Importer Markers in the given file, and update the file in place. This is useful for having a single file to manage and also import other file contents. If you want to have a template file which only holds Importer Markers and not actually the imported content, you should use importer generate
instead.
importer-update-yaml-demo.mp4
importer purge
removes any lines between Importer Markers in the given file, and update the file in place. The same operation is executed for importer update
before importing all the lines, but this "purge" is sometimes useful to see the file without extra data imported.
importer-purge-yaml-demo.mp4
importer generate
imports based on Importer Markers in the given file, and write the result to stdout or file. This can be used for debugging, or create a template file with Importer Markers but keep the file purely for Importer Markers.
importer-generate-yaml-demo.mp4
You can find more examples:
Because you can install Importer using Homebrew, you can set up GitHub Action definition such as below:
jobs:
importer:
name: Run Importer Generate
runs-on: ubuntu-latest
steps:
- name: Install Importer
run: brew install upsidr/tap/importer
- name: Check out
uses: actions/checkout@v2
with:
fetch-depth: 0
- name: Run Importer against README.md
run: importer update README.md
- name: Check if README.md has any change compared to the branch
run: |
git status --short
git diff-index --quiet HEAD
This repository uses Importer to generate some of the markdown documentation.
You can find actually running CI setup in .github/workflows/importer-ci.yaml
.