Doculisp VS Code Extension

Table of Contents

1. Section: What is Doculisp?
2. Section: Doculisp VS Code Extension Setup Guide
3. Section: Supported File Types
4. Section: Usage Examples
5. Section: Commands
6. Section: License
7. Section: Related
8. Section: Release Notes

What is Doculisp?

Doculisp is a Lisp-based domain-specific language designed to make readme files and documentation easier to edit and maintain. It allows you to:

• Break documentation into multiple smaller, manageable files
• Use includes to compose complex documents from parts
• Generate dynamic table of contents with various styles
• Create cross-document links that adapt to file structure changes
• Use dynamic headings that adjust based on document context

Example Doculisp Syntax

(section-meta
    (title My Documentation)
    (author John Doe)
    (include
        (Introduction ./intro.md)
        (Getting-Started ./getting-started.md)
        (API-Reference ./api.md)
    )
)

(# Overview)

(content
    (toc
        (label Table of Contents)
        (style numbered-labeled)
    )
)

Doculisp VS Code Extension Setup Guide

Installation and Configuration Guide

Overview

The Doculisp Language Support extension provides comprehensive language features for the Doculisp DSL (Domain Specific Language) within Visual Studio Code. This extension enables syntax highlighting, IntelliSense, snippets, and language server features for both standalone .dlisp files and embedded Doculisp code within markdown files.

Prerequisites

Before installing the Doculisp VS Code extension, ensure you have:

• Visual Studio Code version 1.104.0 or higher
• Node.js (if building from source)
• Git (for cloning the repository)
• doculisp npm package
  • Install globally: npm i -g doculisp
  • Or as a dev dependency: npm i doculisp --save-dev

Installation Methods

Method 1: Install from VS Code Marketplace (Recommended)

1. Open Visual Studio Code
2. Navigate to the Extensions view (Ctrl+Shift+X or Cmd+Shift+X)
3. Search for "Doculisp Language Support"
4. Click Install on the extension by the Doculisp Development Team
5. Reload VS Code when prompted

Method 2: Install from VSIX Package

1. Download the latest .vsix file from the releases page
2. Open VS Code
3. Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P)
4. Type "Extensions: Install from VSIX"
5. Select the downloaded .vsix file
6. Restart VS Code

Method 3: Build and Install from Source

# Clone the repository
git clone https://github.com/your-org/doculisp-vscode-extension.git
cd doculisp-vscode-extension

# Install dependencies
npm install

# Build the extension
npm run package

# Install the generated .vsix file
code --install-extension doculisp-language-support-*.vsix

Features

Syntax Highlighting

The extension provides rich syntax highlighting for:

• Keywords: dl, section-meta, title, include, content, toc
• Comments: S-expression comments using (* syntax
• Strings: Quoted and unquoted string literals
• Atoms: Function names and identifiers
• Block structures: Properly nested parentheses with color coding

IntelliSense and Autocomplete

Get intelligent code completion with:

• Context-aware keyword suggestions
• Snippet-style completions for common patterns
• Hover documentation for Doculisp keywords
• Parameter hints for built-in functions

Code Snippets

The extension includes predefined snippets for common Doculisp patterns:

Embedded Markdown Support

Use Doculisp within markdown files using HTML comment syntax:

<!-- (dl
(section-meta
    (title My Document)
    (include
        (Chapter ./chapter1.md)
        (Chapter ./chapter2.md)
    )
)

(content (toc numbered-labeled))
) -->

Configuration

Extension Settings

The extension can be configured through VS Code settings:

{
  "doculisp.enableInMarkdown": true,
  "doculisp.syntaxHighlighting": true,
  "doculisp.intelliSense": true,
  "doculisp.autoComplete": true
}

File Associations

To enable Doculisp support for additional file extensions:

{
  "files.associations": {
    "*.mydlisp": "doculisp",
    "*.myproject": "doculisp-project"
  }
}

Troubleshooting

Common Issues

Syntax highlighting not working in markdown:

• Ensure the Doculisp code is wrapped in HTML comments: <!-- (dl ... ) -->
• Check that the extension is activated for markdown files

Autocomplete not appearing:

• Verify you're inside a Doculisp block (parentheses)
• Try triggering manually with Ctrl+Space

Extension not activating:

• Check VS Code version compatibility (requires 1.104.0+)
• Reload the window: Developer: Reload Window command

Getting Help

• Documentation: Visit the official Doculisp documentation
• Issues: Report bugs on GitHub Issues
• Discussions: Coming

Development Commands

npm run compile         # Compile TypeScript
npm run watch           # Watch mode for development
npm run package         # Package extension
npm run test            # Run test suite

Happy coding with Doculisp! 🎉

Supported File Types

The extension automatically activates for the following file types:

• .dlisp - Pure Doculisp files
• .dlproj - Doculisp project configuration files
• .md - Markdown files (for embedded Doculisp support)

Usage Examples

Creating a Basic Doculisp Document

<!-- (dl
(section-meta
    (title Example Document Structure)
    (*include
        (Example "./example-basic.dlisp")
    )
    (include
        (Chapter "./getting-started.md")
        (Chapter "./advanced-features.md")
    )
)

(content
    (toc
        (style numbered-labeled)
        (label "Table of Contents")
    )
)
) -->

1. Create a new file with .dlisp extension
2. Start typing dl and select the snippet
3. Fill in the template placeholders
4. Use Ctrl+Space for autocomplete suggestions

Working with Project Files

Create .dlproj files to manage multiple documents:

(documents
    (document
        (source ./readme.md)
        (output ./dist/readme.html)
    )
    (document
        (source ./guide.dlisp)
        (output ./dist/guide.html)
    )
)

Commands

The extension provides the following commands accessible via Command Palette (Ctrl+Shift+P):

• Doculisp: Compile Document - Compile current Doculisp file
• Doculisp: Validate Syntax - Check syntax of current file
• Doculisp: Show Document Outline - Display document structure

License

This extension is released under the MIT License. See the LICENSE file for details.

Related

• Doculisp Compiler - The core Doculisp compiler
• Doculisp Documentation - Full language reference
• Extension Guidelines

Release Notes

0.1.0

New Features:

• Clickable File Paths: Added document link providers that make file paths clickable in both .dlproj and .dlisp files
  • In .dlproj files: source and output parameters are now clickable links
  • In .dlisp and .md files: File paths in include statements are clickable
  • Ctrl+Click (Cmd+Click on Mac) to navigate directly to referenced files
  • Automatic path resolution relative to the current file's directory
  • Tooltips show the target file path on hover

0.0.1

Initial release of Doculisp Language Support:

• Syntax highlighting for .dlisp files and Markdown injection
• Basic IntelliSense with hover information
• Document symbols and outline support
• Comprehensive snippet library
• Command palette integration
• Language configuration with auto-closing pairs and smart indentation