dwmkerr / dwmkerr/effective-shell

feat(migration): support reference numbers in code blocks

Open
#404 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
780
Forks
93
Avg merge
1d 7h
Merged PRs (30d)
3

Description

## Summary

The book manuscript uses numbered reference annotations in code blocks to explain specific parts of commands or output. For example, in the "pushing and popping the working directory" section, numbers appear inline in the code that correspond to explanations below.

## Example

The book format shows something like:

```
$ pushd ~/effective-shell ①
~/effective-shell ~
$ pushd /var/logs ②
/var/logs ~/effective-shell ~
```

① Explanation for the first command
② Explanation for the second command

## Current Limitation

Our markdown/MDX code blocks don't support inline reference numbers with corresponding annotations.

## Proposed Solution

Investigate options for supporting this pattern:
- Custom MDX component for annotated code blocks
- Docusaurus plugin or extension
- Alternative styling approach

---

Image

## Affected Pages

- [ ] [Shell Basics - Pushing and Popping the Working Directory](https://effective.sh/appendices/shell-basics/#pushing-and-popping-the-working-directory)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.