danishcake / marked-annotated-hexdump

A markedjs extension for creating annotated hex dumps

marked-annotated-hexdump

Generate annotated hexdumps using markdown. Supports marked and markdown-it

Give marked support a try in your browser

Give markdown-it support a try in your browser

Syntax

Annotated hexdumps are created with an annotated-hexdump code-block.

```annotated-hexdump
0000 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
0010 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
```

You can omit the address, and it'll assume data starts at offset 0.

```annotated-hexdump
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
```

Addresses do not need to be contiguous, or in any particular order. The only restriction is that you cannot define a range twice. Space will be left for any missing characters.

```annotated-hexdump
0010 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
0100 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
0028 28 29 30
```

The character used to replace missing bytes can be controlled with /missing.

```annotated-hexdump
/missing ?

0010 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
0100 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
0028 28 29 30
```

The width of the data and address elements in the hexdump can be controlled with /width and /awidth. /width accepts values between 2 and 32. /awidth accepts values between 2 and 8. Both are measured in bytes.

```annotated-hexdump
/width 4
/awidth 3
0000 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
```

You can highlight regions of a hexdump with /highlight. This takes two arguments:

• An inclusive range of addresses to highlight. This is enclosed in square brackets [], and can contain single addresses, or ranges delimited with a colon. Multiple ranges (or single addresses) can be combined with commas.
  • [1] - defines a address 0x01 only
  • [1,2,3] - defines a highlight over 0x01, 0x02 and 0x03. This will be rendered with gaps between the highlights.
  • [1:3] - defines a contiguous highlight over the same three bytes.
  • [1:3, 100:200] - defines two contiguous highlights.
• A style in the form /N, where N is a number between 0 and 15.

```annotated-hexdump
0010 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
0100 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
0028 28 29 30

/highlight [10,11,12,16:19] /1
/highlight [1F:101] /2
/highlight [104:106] /3
```

You can leave comments by starting a line with #. This only works if it's the first character in a line.

You can leave visible notes with the /note command. This takes two arguments:

• A style in the form of /N, where N is a number between 0 and 15.
• A block of text, which will be formatted in this style.

Usage with marked

import { marked } from "marked";
import { annotatedHex } from "marked-annotated-hexdump/marked";

// or UMD script
// <script src="https://cdn.jsdelivr.net/npm/marked/lib/marked.umd.js"></script>
// <script src="https://cdn.jsdelivr.net/npm/marked-annotated-hexdump/lib/index.umd.js"></script>

marked.use(annotatedHex());

marked.parse("```annotated-hexdump\nAA BB CC DD\n```");

Usage with markdown-it

import markdownIt from "../../node_modules/markdown-it/dist/markdown-it";
import { extendMarkdownIt } from "marked-annotated-hexdump/markdown-it";

const md = markdownIt();
extendMarkdownIt(md);

md.render("```annotated-hexdump\nAA BB CC DD\n```");

Limitations

• If you configure your markdown to wrap, the highlighted regions will be at incorrect positions.
  This might be better expressed using spans rather than an svg overlay

marked-annotated-hexdump's Issues

The automated release is failing 🚨

🚨 The automated release from the main branch failed. 🚨

I recommend you give this issue a high priority, so other packages depending on you can benefit from your bug fixes and new features again.

You can find below the list of errors reported by semantic-release. Each one of them has to be resolved in order to automatically publish your package. I’m sure you can fix this 💪.

Errors are usually caused by a misconfiguration or an authentication problem. With each error reported below you will find explanation and guidance to help you to resolve it.

Once all the errors are resolved, semantic-release will release your package the next time you push a commit to the main branch. You can also manually restart the failed CI job that runs semantic-release.

If you are not sure how to resolve this, here are some links that can help you:

• Usage documentation
• Frequently Asked Questions
• Support channels

If those don’t help, or if this issue is reporting something you think isn’t right, you can always ask the humans behind semantic-release.

---

Invalid npm token.

The npm token configured in the NPM_TOKEN environment variable must be a valid token allowing to publish to the registry https://registry.npmjs.org/.

If you are using Two Factor Authentication for your account, set its level to "Authorization only" in your account settings. semantic-release cannot publish with the default "
Authorization and writes" level.

Please make sure to set the NPM_TOKEN environment variable in your CI with the exact value of the npm token.

---

Good luck with your project ✨

Your semantic-release bot 📦🚀

Automatically deploy latest version to github pages

I've got a hand-cranked github pages page. Link to it from the readme, and have it automatically update

Handle commands other than highlight

When walking the tokens, handle the following commands

• \width: Change the number of bytes per line
• \lower: Output as lowercase
• \upper: Output as uppercase
• \missing: Fill missing bytes with this character

Add BaseAddress command

A /baseaddress XX should cause the zero address to become XX.

This will allow a hexdump where the offsets are zero, and highlights use small numbers, but with the outputs at some large values

Implement tokenisation

Parse the input and tokenise into

1. Comments (start with #)
2. Commands (start with )
3. Blanks
4. Hex with or without leading position

Add examples of use

Add examples of use via screenshots

Create a VSCode extension

Create a VSCode extension to allow previewing of hexdumps

Add visible comment

Figure out how to do the actually annotation bits

• Figure out what the markup should be
• Figure out what the output should look like

Handle highlight command

After walking the tokens, walk them again and handle the \highlight commands. Generate an SVG or similar that overlays the hexdump

Add support for markdown-it

https://github.com/markdown-it/markdown-it is used for VSCode highlighting. Add support for this too.

Make marked and markdown-it optional peer dependencies and update build instructions.

Walk tokens and produce unannotated output

Initially create unannotated hex output - just the hex digits, offsets and spacing

Stub the extension

Stub the extension

1. Support older markedjs versions
2. Handle code with annotated-hexdump infostring
3. Output placeholder content
4. Unit tests to demonstrate

Enable automatic deployment to NPM

Publish automatically to NPM

Implicit zero offset fails if first character is non-numeric

The following fails

```annotated-hexdump
AA 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 1E 1F
```