Complete guide to installing and setting up the dotchalk library.

Installation

npm

npm install github:jackhgns/dotchalk

yarn

yarn add github:jackhgns/dotchalk

pnpm

pnpm add github:jackhgns/dotchalk

System Requirements

Node.js Version

TypeScript (Optional)

If you’re using TypeScript in your project:

Basic Setup

1. Import the library

const chalk = require('dotchalk');
// or with ES modules
import chalk from 'dotchalk';

2. Create a basic library

const library = chalk.createLibrary({
  class: 'document',
  bodyPolicy: ['paragraph', 'heading'],
  headerAttributes: [
    { identifier: 'title', type: 'string', required: true }
  ]
});

3. Compile your first document

const chalkSource = `
# My First Document

This is a paragraph in my document.
`;

const result = chalk.compile(chalkSource, library);
if (result.ok) {
  console.log('Success!', result.data);
} else {
  console.error('Error:', result.error);
}

TypeScript Setup

If you’re using TypeScript, the library includes full type definitions:

import chalk, { DocumentDefinition, Library } from 'dotchalk';

const docDef: DocumentDefinition = {
  class: 'article',
  bodyPolicy: ['paragraph', 'heading'],
  headerAttributes: [
    { identifier: 'title', type: 'string', required: true },
    { identifier: 'author', type: 'string', required: true }
  ]
};

const library: Library = chalk.createLibrary(docDef);

Troubleshooting

Common Installation Issues

“Cannot find module ‘dotchalk’”

Problem: The package wasn’t installed correctly.

Solutions:

  1. Check that the package is listed in your package.json
  2. Run npm install or yarn install to ensure dependencies are installed
  3. Clear your node_modules and reinstall: rm -rf node_modules && npm install

“Module not found” in TypeScript

Problem: TypeScript can’t find the type definitions.

Solutions:

  1. Ensure you’re using TypeScript 4.5.0 or higher
  2. Check your tsconfig.json includes the types
  3. Try restarting your TypeScript language server

Runtime Issues

“Invalid document class”

Problem: Your document definition is missing required fields.

Solution: Ensure your document definition includes:

{
  class: 'your-document-type',  // Required: string identifier
  bodyPolicy: ['allowed', 'elements'],  // Required: content policy
  headerAttributes: []  // Optional: metadata attributes
}

“Element not allowed in this context”

Problem: You’re using elements that aren’t permitted by your content policy.

Solution: Update your content policy to include the elements you want to use:

const library = chalk.createLibrary({
  class: 'document',
  bodyPolicy: ['paragraph', 'heading', 'image', 'code-block'],  // Add allowed elements
  // ...
});

Compilation errors with special characters

Problem: Certain characters in your Chalk source are causing parsing issues.

Solution:

Performance Issues

Slow compilation of large documents

Solutions:

  1. Break large documents into smaller files and use @include
  2. Optimize your element definitions to avoid complex parsing
  3. Consider caching compiled results for frequently used libraries

Getting Help

If you encounter issues not covered here:

  1. Check the API Methods reference for detailed usage
  2. Review the Key Concepts for fundamental understanding
  3. Open an issue on GitHub

Next Steps