Import System

Share docs and templates across projects from Git, npm, or local sources

6 min read

Import System

Import and sync documentation and templates from external sources.

Overview

The Import System allows you to:

Import docs and templates from Git repositories, npm packages, or local folders
Keep imports synced with their sources
Share patterns and conventions across multiple projects
Reference imported content with @doc/imports/<name>/<path>

Quick Start

# Import from GitHub
knowns import github:knowns-dev/templates --name templates
 
# List all imports
knowns import list
 
# Sync to get updates
knowns import sync
 
# Reference imported docs
# @doc/imports/templates/patterns/component

Source Types

Git Repositories

# GitHub shorthand
knowns import github:user/repo --name my-patterns
 
# GitLab shorthand
knowns import gitlab:user/repo --name patterns
 
# Full URL (any Git host)
knowns import https://github.com/org/knowledge-base.git --name kb
 
# Specific branch or tag
knowns import github:org/templates --ref main --name templates
knowns import github:org/templates --ref v1.0.0 --name templates-v1

NPM Packages

# Latest version
knowns import npm:@myorg/patterns --name patterns
 
# Specific version
knowns import npm:@myorg/patterns --ref ^1.0.0 --name patterns
 
# Exact version
knowns import npm:@myorg/patterns --ref 1.2.3 --name patterns

Local Folders

# Copy files
knowns import ./shared-docs --name shared
 
# Symlink (changes reflect immediately)
knowns import ./shared-docs --name shared --link
 
# Relative to home
knowns import ~/company/patterns --name company

CLI Commands

`knowns import add`

Add a new import. Shorthand: knowns import <source>.

knowns import add <source> [options]
knowns import <source> [options]  # shorthand

Option	Description
`-n, --name <name>`	Custom name for the import
`-t, --type <type>`	Force source type: `git`, `npm`, `local`
`-r, --ref <ref>`	Git branch/tag or npm version
`--include <patterns...>`	Include only matching files (glob patterns)
`--exclude <patterns...>`	Exclude matching files (glob patterns)
`--link`	Symlink local imports instead of copying
`-f, --force`	Overwrite existing import
`--dry-run`	Preview without writing files
`--plain`	Plain text output (for AI)

Examples:

# Import only markdown docs
knowns import github:org/repo --name docs --include "**/*.md"
 
# Exclude tests
knowns import github:org/repo --name patterns --exclude "**/*.test.*"
 
# Preview what would be imported
knowns import github:org/repo --name preview --dry-run

`knowns import list`

List all configured imports with their status.

knowns import list [options]

Option	Description
`--plain`	Plain text output (for AI)

Output includes:

Import name and source
Last sync date
Number of files
Sync status

`knowns import sync`

Update imports from their sources.

knowns import sync [name] [options]

Option	Description
`-f, --force`	Overwrite locally modified files
`--dry-run`	Preview changes without applying
`--plain`	Plain text output (for AI)

Examples:

# Sync all imports
knowns import sync
 
# Sync specific import
knowns import sync patterns
 
# Preview sync changes
knowns import sync --dry-run
 
# Force sync (overwrite local changes)
knowns import sync patterns --force

`knowns import remove`

Remove an import configuration.

knowns import remove <name> [options]

Option	Description
`--delete`	Also delete the imported files
`--plain`	Plain text output (for AI)

Examples:

# Remove config only (keep files)
knowns import remove old-patterns
 
# Remove config and files
knowns import remove old-patterns --delete

Import Structure

When you import content, it's organized as:

.knowns/
├── imports.json              # Import configurations
├── docs/
│   └── imports/
│       ├── patterns/         # Import named "patterns"
│       │   ├── auth.md
│       │   └── api.md
│       └── templates/        # Import named "templates"
│           └── component.md
└── templates/
    └── patterns/             # Templates from "patterns" import
        └── react-component/

`imports.json`

Stores import metadata:

{
  "patterns": {
    "source": "github:myorg/patterns",
    "type": "git",
    "ref": "main",
    "lastSync": "2025-01-25T10:30:00Z",
    "files": 15
  }
}

Referencing Imported Content

In Tasks

knowns task create "Add auth" \
  -d "Implement auth following @doc/imports/patterns/auth"

In Documentation

# API Guidelines
 
See our shared patterns: @doc/imports/patterns/api
 
Related: @doc/imports/templates/rest-endpoint

In Templates

Link imported documentation in _template.yaml:

description: "API endpoint generator"
doc: "imports/patterns/api"  # References imported doc

Workflows

Team Pattern Library

Share patterns across all team projects:

# In each project
knowns import github:myorg/patterns --name patterns
 
# Keep updated
knowns import sync patterns

Monorepo Shared Docs

Share docs between packages in a monorepo:

# In packages/app
knowns import ../../shared/docs --name shared --link
 
# Changes in shared/docs reflect immediately

Versioned Templates

Use specific versions of templates:

# Production: stable version
knowns import npm:@myorg/templates --ref ^1.0.0 --name templates
 
# Development: latest
knowns import npm:@myorg/templates --ref latest --name templates-dev

Best Practices

1. Use Meaningful Names

# Good: descriptive names
knowns import github:org/api-patterns --name api-patterns
knowns import github:org/ui-components --name ui-components
 
# Avoid: generic names
knowns import github:org/stuff --name stuff

2. Pin Versions for Stability

# Production: pin to specific version
knowns import npm:@org/patterns --ref 1.2.3 --name patterns
 
# Development: allow minor updates
knowns import npm:@org/patterns --ref ^1.2.0 --name patterns

3. Use Include/Exclude Filters

Import only what you need:

# Only docs, no tests or examples
knowns import github:org/repo \
  --name patterns \
  --include "docs/**/*.md" \
  --exclude "**/*.test.*"

4. Sync Regularly

Add to your workflow:

# Before starting work
knowns import sync
 
# Or automate in CI/CD
knowns import sync --force

5. Preview Before Importing

Always preview first:

# See what would be imported
knowns import github:org/large-repo --name test --dry-run
 
# Then import
knowns import github:org/large-repo --name patterns

Troubleshooting

Import Failed

# Check source is accessible
git ls-remote https://github.com/org/repo
 
# For npm, check package exists
npm view @org/package
 
# Try with verbose output
knowns import github:org/repo --name test --plain

Sync Conflicts

When local files were modified:

# Preview conflicts
knowns import sync patterns --dry-run
 
# Force overwrite local changes
knowns import sync patterns --force
 
# Or backup and re-import
knowns import remove patterns
knowns import github:org/patterns --name patterns

Large Imports

For large repositories:

# Filter to specific folders
knowns import github:org/large-repo \
  --name docs \
  --include "docs/**/*"
 
# Or specific file types
knowns import github:org/repo \
  --name patterns \
  --include "**/*.md"