axl-light - GitLite

KO | EN

gitlite — search

#javascript #hacktoberfest #react #ai #typescript #llm #golang #android #macos #kubernetes #awesome-list #pytorch #mcp #openai

axl-light

(★ 62)

No description available.

파일 탐색기

최종 버전 다운로드 (.zip)

- - build.yml
  - release.yml
- AGENTS.md
- - highlight-with-axl-light.png
  - install-axl-light-command.png
  - install-axl-light.png
  - sticky-notes-overview.png
- - AGENTS.md
  - copy.md
  - generate-linkedin-carousel.mjs
- AGENTS.md
- AGENTS.md
- install.cmd
- install.ps1
- install.sh
- - AGENTS.md
  - fuzzyMatch.ts
  - textAnchor.ts
- - AGENTS.md
  - highlightExtension.ts
  - readingViewHighlight.ts
  - selectionToolbar.ts
- - AGENTS.md
  - pdfAnnotationLayer.ts
- - AGENTS.md
  - settingsTab.ts
- - AGENTS.md
  - annotationStore.ts
  - types.ts
- - AGENTS.md
  - positioning.ts
- - AGENTS.md
  - annotationPopover.ts
  - commentModal.ts
  - sidebarView.ts
  - stickyNoteView.ts
- AGENTS.md
.gitignore
AGENTS.md
annotation-layout-mocks.html
esbuild.config.mjs
LICENSE
main.ts
manifest.json
package-lock.json
package.json
README.md
styles.css
SUBMISSION_CHECKLIST.md
tsconfig.json
versions.json

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/little-pond/axl-light

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd axl-light

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Node.js

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Node.js npm 명령어를 쓰려면 Node.js가 설치되어 있어야 합니다. LTS(장기지원) 버전을 추천합니다.

npm install

package.json에 명시된 라이브러리들을 내려받아 설치합니다.

npm run dev

개발/실행 서버를 켭니다.

npm run build

배포용으로 코드를 최적화해서 빌드 파일을 생성합니다.

✅ 명령어 실행 후 터미널에 나타나는 주소(보통 http://localhost:3000 형태)를 브라우저에서 열어보세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Axl Light

Axl Light is a non-invasive Obsidian reading annotation plugin for Markdown and PDF files. It adds overlay highlights, sticky notes, search, jump, and Markdown export while keeping your original documents clean.

**This plugin never modifies your Markdown or PDF files.** Annotation data is stored separately in sidecar JSON files under `.obsidian-annotations/`.

## Features

- Overlay highlights for Markdown Live Preview, Source Mode, Reading View, and PDFs
- Mobile-friendly Reading View highlight recovery with delayed rendering and DOM observation
- Floating toolbar with six colors, sticky note, copy, and annotation overview actions
- Right-side sticky note lane with Markdown-rendered notes
- Inline editing for sticky notes and sidebar notes
- Sidebar overview with search, color filtering, sorting, jump, delete, add-note, and export
- Sidecar JSON storage with fuzzy text-anchor relocation
- Windows-safe short sidecar filenames with legacy path migration

## Installation

### BRAT

Recommended for Windows users who do not want to touch the terminal.

1. Install the Obsidian BRAT plugin.
2. Run `BRAT: Add a beta plugin for testing`.
3. Paste this repository URL:

```text
https://github.com/little-pond/axl-light
```

4. Enable `Axl Light` in `Settings -> Community plugins`.

### Quick Install

#### macOS / Linux

Run this in Terminal. Replace the path with your Obsidian vault path:

```bash
curl -fsSL https://raw.githubusercontent.com/little-pond/axl-light/main/scripts/install.sh | bash -s -- "$HOME/Documents/Obsidian Vault"
```

Then restart Obsidian, open Settings → Community plugins, and enable Axl Light.

![Install Axl Light from Terminal](https://raw.githubusercontent.com/little-pond/axl-light/main/docs/images/install-axl-light-command.png)

#### Windows

Run this in PowerShell. It will prompt for your Obsidian vault folder and uses your Documents folder as the default when it can:

```powershell
$script = Join-Path $env:TEMP "install-axl-light.ps1"
Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/little-pond/axl-light/main/scripts/install.ps1" -OutFile $script
powershell -NoProfile -ExecutionPolicy Bypass -File $script
```

To skip the prompt, pass the vault path:

```powershell
$script = Join-Path $env:TEMP "install-axl-light.ps1"
Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/little-pond/axl-light/main/scripts/install.ps1" -OutFile $script
powershell -NoProfile -ExecutionPolicy Bypass -File $script "C:\Users\your-name\Documents\Obsidian Vault"
```

If you downloaded this repository for development, you can also double-click `scripts\install.cmd`; it opens the same Windows installer prompt.

If PowerShell still blocks the script, use BRAT or the manual install below.

### Manual Install

1. Download these three files from the latest release:
   https://github.com/little-pond/axl-light/releases/latest

- `main.js`
   - `manifest.json`
   - `styles.css`

2. Move them to the plugin folder:

macOS / Linux:

```text
   <your-vault>/.obsidian/plugins/axl-light/
   ```

Windows:

```text
   C:\Users\your-name\Documents\Obsidian Vault\.obsidian\plugins\axl-light\
   ```

3. Restart Obsidian

4. Settings → Community plugins → Enable "Axl Light"

Do **not** download the source code ZIP from the green `Code` button. Obsidian needs the built release files.

## Usage

### Highlight Text

Select text in Markdown or PDF. Use the floating toolbar to choose a color, add a sticky note, copy the selection, or open the overview.

![Highlight with Axl Light](https://raw.githubusercontent.com/little-pond/axl-light/main/docs/images/highlight-with-axl-light.png)

### Edit Sticky Notes

Open the right-side sticky note lane or the annotation overview. Click the pencil button to edit a note inline. Press `Cmd/Ctrl + Enter` to save.

![Sticky notes and annotation overview](https://raw.githubusercontent.com/little-pond/axl-light/main/docs/images/sticky-notes-overview.png)

### Search, Jump, and Export

Use the annotation overview to search highlights and notes, jump back to the source position, delete annotations, add notes to existing highlights, or export everything into a new Markdown notes file.

## Commands

- `Highlight selected text`: `Cmd/Ctrl + Shift + H`
- `Add sticky note to selection`: `Cmd/Ctrl + Alt + M`
- `Toggle sticky note lane`: `Cmd/Ctrl + Shift + N`
- `Open annotation overview`

## Data Storage

Axl Light stores annotations in your vault:

```text
.obsidian-annotations/
  index.json
  axl--notes__reading__book.md--7b85f6b1c02a41f7.json
  axl--papers__example.pdf--5af1299d722f61e0.json
```

The sidecar files contain anchors, selected text, colors, sticky note content, optional titles, timestamps, and PDF page rectangles.
The filenames are intentionally short and Windows-safe; the original vault path lives inside the JSON and `index.json`. Older long sidecar filenames are migrated automatically when Axl Light reads them.

Your original `.md` and `.pdf` files remain unchanged. If you disable or remove the plugin, your documents stay clean.

## Known Limitations

- Reading View highlights are matched against rendered DOM text, so unusual themes or plugins that heavily rewrite rendered HTML may affect placement.
- PDF support depends on Obsidian's built-in PDF viewer DOM structure.
- PDF text selection and rectangle anchors may need relocation improvements for rotated pages or unusual PDF layouts.
- Very large annotation sets currently render directly in the sidebar; virtual scrolling is planned.

## Development

```bash
npm install
npm run dev
```

For production builds:

```bash
npm run build
```

Copy `main.js`, `manifest.json`, and `styles.css` into:

```text
<your-vault>/.obsidian/plugins/axl-light/
```

## License

MIT. See [LICENSE](LICENSE).