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

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)

The Doculisp compiler is bundled with the extension - no separate installation required!

Note: The extension now includes the Doculisp compiler as a bundled dependency, so you no longer need to install doculisp separately!

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:

Snippet Trigger	Description	Scope
dl	Complete Doculisp document structure	All
section-meta	Section metadata block	Doculisp
include	Include block	Doculisp
content	Content block with TOC	Doculisp
dl-comment	HTML comment with Doculisp	Markdown

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

Keyboard Shortcuts

The extension includes powerful refactoring commands with intuitive keyboard shortcuts for efficient markdown-to-Doculisp conversion workflows:

Markdown Heading Conversion

Shortcut	Mac Shortcut	Command	Description
Ctrl+Shift+H	Cmd+Shift+H	Convert Markdown Heading to Doculisp	Converts any selected markdown heading to dynamic Doculisp heading (reduces level by 1)
Ctrl+Shift+T	Cmd+Shift+T	Convert Title to Section-Meta	Converts top-level headings (# Title) to compact section-meta format
Ctrl+Shift+E	Cmd+Shift+E	Convert Title to Expanded Section-Meta	Converts top-level headings to full section-meta with include structure

File Conversion

Shortcut	Mac Shortcut	Command	Description
Ctrl+Shift+C	Cmd+Shift+C	Convert Markdown File to Doculisp	Converts entire markdown files to pure .dlisp format (strict validation)

Usage Examples

Heading Conversion (Ctrl+Shift+H)

Select any markdown heading and press the shortcut:

• Input: ### My Heading
• Output: <!-- (dl (## My Heading)) -->

Title to Section-Meta (Ctrl+Shift+T)

Select a top-level heading:

• Input: # Document Title
• Output: <!-- (dl (section-meta Document Title)) -->

Expanded Section-Meta (Ctrl+Shift+E)

Select a top-level heading for full structure:

• Input: # My Document
• Output:

<!-- (dl
(section-meta
	(title My Document)
	(include
		(Section ./hello.md)
	)
)
) -->

File Conversion (Ctrl+Shift+C)

Convert entire markdown file containing only Doculisp blocks:

• Validates strict structure (section-meta + content only)
• Strips HTML comments and (dl ...) wrappers
• Replaces .md file with .dlisp file
• Opens converted file automatically

Context Requirements

• Heading conversion shortcuts (H, T, E): Require text selection in markdown files
• File conversion shortcut (C): Works on entire active markdown file
• All shortcuts are context-aware and only activate in appropriate file types

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