Importer

Import any lines, from anywhere

🌄 What is Importer?

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.

✨ Install

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

Install with Go

You can also use Go to install.

$ go get github.com/upsidr/importer/cmd/importer@v0.1.0

🎮 Commands

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.

🧩 Supported Files

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

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.

🚀 Examples

`importer preview`

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`

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`

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`

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:

GitHub Action Integration

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.