CodeCorn Shebang Markdown

CodeCorn Shebang Markdown is a tiny Visual Studio Code extension that detects a custom shebang on the first line of a file and switches the editor language mode to Markdown.

It is designed for workflows where Markdown-like operational files, scripts, notes or generated artifacts do not use the .md extension, but still need to be handled as Markdown by VS Code, markdownlint, formatters and language-aware tooling.

Italian documentation: README_IT.md

Why

VS Code file associations are path/name based. They are great when a file extension or filename is predictable, but they do not inspect the first line of a document.

This extension fills that gap with a small content-based rule:

first line contains a CodeCorn Markdown shebang
→ switch document language mode to markdown

Example:

#!/usr/bin/env cc-md

# Deployment checklist

- backup database
- dump environment
- apply patch
- verify logs

Even if the file has no .md extension, VS Code will treat it as Markdown.

Features

• Detects custom Markdown shebangs on the first line.
• Forces VS Code language mode to markdown.
• Works with untitled files, extensionless files and script-like notes.
• Configurable regex pattern.
• Configurable target VS Code language id.
• Useful with markdownlint, Markdown formatters and editor tooling.
• No runtime dependencies.
• Minimal extension footprint.

Default shebangs

The default pattern is:

^#!.*\bcc-(md|markdown)\b

Supported examples:

#!/usr/bin/env cc-md

#!cc-md

#!/usr/bin/env cc-markdown

#!cc-markdown

Installation

Local VSIX install

This package is primarily a VS Code extension. For local development or internal usage:

npm install
npm run reinstall

This builds the .vsix package and installs it in VS Code.

npm package

The package is also published on npm for traceability, reuse and source distribution:

npm install cc-vscode-shebang-markdown

Installing from npm does not automatically install the extension into VS Code. For actual editor installation, use a generated .vsix file or publish the extension to the Visual Studio Code Marketplace.

Usage

Create or open any file whose first line matches the configured shebang pattern:

#!/usr/bin/env cc-md

# Server audit

## Build log

- collect build output
- inspect warnings
- normalize report

When the document opens, the extension switches its language mode to:

markdown

You can verify this in the bottom-right language selector in VS Code.

Configuration

ccShebangMarkdown.pattern

Regex applied to the first line of the document.

Default:

{
  "ccShebangMarkdown.pattern": "^#!.*\\bcc-(md|markdown)\\b"
}

ccShebangMarkdown.targetLanguage

VS Code language id to apply when the pattern matches.

Default:

{
  "ccShebangMarkdown.targetLanguage": "markdown"
}

Advanced example:

{
  "ccShebangMarkdown.pattern": "^#!.*\\bcompany-doc\\b",
  "ccShebangMarkdown.targetLanguage": "markdown"
}

markdownlint note

Some lint configurations require the first line of a Markdown document to be a heading. A shebang intentionally violates that rule.

For shebang-based Markdown files, you may want to disable MD041:

{
  "markdownlint.config": {
    "MD041": false
  }
}

Development

Clone the repository and install dependencies:

npm install

Package the VS Code extension:

npm run pack:vsix

Install it locally:

npm run reinstall

Check npm package contents before publishing:

npm run pack:npm

Release flow

Bump the version in package.json, then run:

npm install
npm run pack:vsix
npm run pack:npm
npm publish

For scoped npm packages, npm requires public scoped packages to be published with npm publish --access public. This package is intentionally unscoped, so plain npm publish is enough.

Design principles

• Do one thing.
• Avoid filename conventions when the contract belongs in the file content.
• Keep the rule explicit and visible.
• Do not hijack unrelated files.
• Prefer configurable detection over hardcoded project paths.

Security

This extension only reads the first line of open text documents and changes VS Code language mode through the VS Code API.

It does not:

• execute file contents;
• send telemetry;
• perform network requests;
• read secrets;
• modify files on disk.

Please report security issues privately when possible. See SECURITY.md.

Contributing

Issues and pull requests are welcome.

See CONTRIBUTING.md.

License

MIT. See LICENSE.

Maintainer

Built and maintained by Federico Girolami / CodeCorn Technology.

CodeCorn™ — We build software that Corn.

Language fallback rules

Besides CodeCorn Markdown shebangs, the extension also ships with defensive fallback rules for common script/config files.

Shell scripts

The extension reinforces VS Code detection for:

#!/bin/bash
#!/bin/zsh
#!/bin/sh
#!/usr/bin/bash
#!/usr/bin/zsh
#!/usr/bin/sh
#!/usr/local/bin/bash
#!/usr/bin/env bash
#!/usr/bin/env zsh
#!/usr/bin/env sh
#!/usr/bin/env -S bash -euo pipefail

Matching files are switched to:

shellscript

nginx

The extension includes a defensive fallback for:

nginx.conf
conf.d/*.conf

and for files containing common nginx blocks near the top:

events {
}

http {
}

server {
}

upstream backend {
}

Matching files are switched to:

nginx

If the nginx language id is not available in the current VS Code installation, the rule falls back to plaintext instead of throwing.