hypertxt

KO | EN

gitlite — search

#javascript #hacktoberfest #golang #go #android #rust #linux #nodejs #windows #cli #awesome-list #security #ios #mcp

(★ 11)

Hypertxt is a VS Code–native GTD + PKM system built on plain Markdown, using Todo MD + Kanban views, designed for maximum portability and compatibility on a locked-down corporate environment.

hypertxt Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# hypertxt

Hypertxt is a VS Code–native GTD + PKM system built on plain Markdown, using Todo MD + Kanban views, designed for maximum portability and compatibility in locked-down corporate environments.

⸻

## Overview

A complete Obsidian-style notes + GTD task system built entirely on:

- Plain Markdown (`.md`, optionally `.tdmd`)
- Local files in a Git repo
- VS Code extensions that work in locked-down corporate environments (no external servers required)

This repo documents:

- The **Hypertxt Task Markdown spec** (a Markdown-compatible task format).
- A **Kanban workflow** powered by [KanMark](#kanmark-pd-chkanmark).
- A **PKM / “second brain”** stack using Foam + inline Markdown rendering.
- A **code TODO** workflow that keeps code comments and planning tasks separate by design.

⸻

## Hypertxt Task Markdown Spec

The core idea: one Markdown-compatible task format that can be interpreted by:

- VS Code Markdown preview / WYSIWYG
- Foam (wikilinks, backlinks)
- Todo MD (GTD-style task list)
- KanMark (Kanban board)
- Simple scripts/CLIs in the future

You can use `.md` or `.tdmd` as the file extension; the spec is about **syntax**, not filename.

### Basic syntax

```markdown
## +Project A:

- [ ] Implement feature X {due:2025-12-10} +projA #work
  > Notes about the task
  > More details, steps, or links
  > [[related-design-doc]]

- [ ] Subtask 1
    > Notes for subtask 1

- [ ] Subtask 2

## +Project B:

- [ ] Another task without due date
```

### Conventions

-	\## +Heading:
-	\## = Markdown heading (folding, navigation, TOC).
-	Leading + = “project” tag for Todo MD and KanMark.
-	`- [ ] / - [x]`
-	Standard GitHub-style task checkboxes.
-	{key:value} metadata blocks
-	due:YYYY-MM-DD – due date.
-	You can add others as needed: pr:high, created:2025-12-01, etc.
-	+ProjectName / #tag
-	Todo.txt-style project/context identifiers for filtering and search.
-	\> Note lines under a task
-	Multi-line notes attached to the previous task.
-	Compatible with Markdown blockquotes and easy to fold visually.
-	Indented - [ ] under a parent task
-	Treated as subtasks in both Todo MD (tree view) and KanMark (card subtasks), as long as indentation is consistent.

This single format plays nicely with both Todo MD’s list view and KanMark’s Kanban board while remaining valid Markdown everywhere (GitHub, static sites, Obsidian, etc.).

⸻

## Kanban Syntax with KanMark

KanMark treats headings as columns and tasks as cards.

### Example board:

```markdown
## +Inbox:

- [ ] Capture random idea {due:2025-12-10}
  > Rough sketch of the idea

## +Next Actions:

- [ ] Implement feature X {due:2025-12-15}
  - [ ] Subtask A
  - [ ] Subtask B

## +Waiting:

- [ ] Blocked on API team

## +Done:

- [x] Finish initial prototype {due:2025-12-01}

-	Each ## +Heading: becomes a column.
	-	Each - [ ] or - [x] line becomes a card.
	-	Indented - [ ] lines become subtasks in the card.
	-	> Note lines stay attached to the card as rich Markdown.
```

This keeps one source of truth for both list and Kanban views.

⸻

## Git Integration For Internal Publishing

This section explains how your notes repo should be structured if you want to build your own markdown-based internal wiki for sharing with coworkers (similar to [Obsidian Publish](https://obsidian.md/publish)):

Prerequisites
- A plain-folder notes system (local disk, OneDrive, etc.)
	- Cloud backup is recommended
- A Git repo on your Git hosting provider
	- Assumption is that you'll use your companies [Enterprise Github](https://resources.github.com/demo/) instance
	- Please remember to follow all guidelines and policies established by your companies IT and security departments
- An optional GitHub Wiki (for sidebar navigation, native rendering, easy sharing links)
	- Follow instructions [here](https://docs.github.com/en/communities/documenting-your-project-with-wikis/adding-or-editing-wiki-pages) to create a wiki for the notes repo

The goal: keep using simple Markdown files, but make them easy for others to browse as an internal knowledge base.

⸻

### 1. High-Level Architecture

There are three layers:

```text
Notes/
  private/        # personal-only notes, never pushed
  public/         # git repo: shared notes
  wiki/           # git repo: GitHub wiki, auto-generated from Github, auto-synced from public/
```

**Explanation of file structure**

- `private/` – scratch, tickets, TODOs, accounts, raw feedback, anything you don’t want others to see.
- `public/` – the notes repo: structured Markdown that you’re happy to share.
- `wiki/` – the wiki repo that backs the GitHub “Wiki” tab. It mirrors `public/`, plus a generated sidebar.

GitHub then gives you two views:
	
- Code tab → full repo + folders, rendered Markdown.
- Wiki tab → curated front door into the same content, with a sidebar.

⸻

### 2. Private vs Public Notes

The split is conceptual.

Stays in `private/`:
- Tickets and debug logs
- Account details / credentials
	- Please don't save credentials in plain text, use a password/secrets manager
	- Follow all policies and guidelines of your team, I don't want you getting fired!
- Personal TODOs and planning
- Raw, unsanitized feedback or venting

Lives in `public/`:
- Onboarding notes (org / dev / team)
- Acronyms and glossary
- System overviews (platform, architecture, integrations)
- Role expectations, ladders, policy summaries
- Useful links and “how to” guides
- Anything you’re fine with your manager’s manager reading

Rule of thumb:

If you’d be okay dropping the link into a team channel, it belongs in `public/`.

⸻

### 3. Repo Layout for `public/` (notes repo)

Inside `public/` (the root of your repo), notes are organized by “frames”:

```text
public/
  README.md

onboarding/
    company/
      *.md
    developers/
      *.md
    team/
      *.md

systems/
    *.md

organization/
    *.md

people/
    *.md

meta/
    internal-md-wiki.md    # this file
    ...                    # other meta docs
```

Suggested categories:
- `onboarding/`
	- company wide onboarding
	- developer-specific onboarding
	- team-specific onboarding (if your company has multiple teams of devs)
- `systems/` – platform overviews, architecture, integrations.
- `organization/` – policy notes, role expectations, useful links.
- `people/` – key contacts, “who to talk to about X” (kept high-level, no personal info).
- `meta/` – docs about how your system works.
	- you can fork this doc for your notes, or just link to this repo
	- allows others to create their own internal wiki in the spirit of learning and sharing

`README.md` at the root acts as the landing page for the repo, with links into these folders.

⸻

### 4. Git Basics: Connecting `public/` to the Notes Repo

From the folder that contains `public/`:

```shell
cd Notes/public
```

#### Initialize the repo (only once)

```shell
git init
git branch -M main
```

#### Point at your remote repo (copy SSH/HTTPS URL from your Git hosting UI)

```shell
git remote add origin git@HOSTNAME:OWNER/notes.git
```

*Note: Remember to follow your companies best practicies on authentication, authorization, and connecting your local `git` to the companies Enterprise Github instance.*

#### First commit

```shell
git add .
git commit -m "Initial import of public notes"
```

#### First push (sets upstream)

```shell
git push -u origin main
```

#### Day-to-day loop:

```shell
cd Notes/public
git status
git add .
git commit -m "Update notes"
git push
```

All your structured notes live here and are browsable via the GitHub Code tab.

⸻

### 5. Wiki Repo: `wiki/`

GitHub wikis are separate git repos. If your main repo is:

`git@HOSTNAME:OWNER/notes.git`

the wiki is:

`git@HOSTNAME:OWNER/notes.wiki.git`

Clone it next to `public/`:

```shell
cd Notes
git clone git@HOSTNAME:OWNER/notes.wiki.git wiki
cd wiki
```

Important details:
- The wiki uses `master` as its primary branch, not `main`.
- `Home.md` is the landing page.
- `_Sidebar.md` defines the left-hand navigation.

So at minimum you want:

```text
wiki/
  Home.md
  _Sidebar.md
  ... (mirrored folders/files from public/)
```

⸻

### 6. Syncing `public/` → `wiki/`

To avoid maintaining two separate sets of notes, a sync script mirrors `public/` into `wiki/`, formats file names, and dynamically generates `_Sidebar.md`.

High-level behavior:
- Copy everything from `public/` to `wiki/`.
- Skip `.git`, `_Sidebar.md`, and any paths on a blocklist.
- Ensure `Home.md` exists (often renamed from `README.md`).
- Regenerate `_Sidebar.md` automatically based on the folder tree.

#### Conceptually:

**From `Notes/`**

```shell
./wikiSync.sh   # (or equivalent script)

cd wiki
git status
git add .
git commit -m "Sync wiki from public"
git push
```

After that, the Wiki tab reflects the synced content.

A typical implementation uses:
- `rsync` (or similar) to copy files with a blocklist.
- A call to a sidebar generator to rebuild `_Sidebar.md`.

⸻

### 7. Sidebar Generation (`_Sidebar.md`)

The wiki sidebar is just Markdown in `_Sidebar.md`. GitHub renders it as the persistent right navigation.

A generator script (Python, Node, shell, etc.) walks the `wiki/` directory and produces a nested tree of [[wiki-links]].

Example shape of the generated `_Sidebar.md`:

```text
# Navigation

* [[Home]]

* Onboarding
  * Company
    * [[onboarding/company/overview]]
    * [[onboarding/company/faq]]
  * Developers
    * [[onboarding/developers/bootcamp]]
    * [[onboarding/developers/tooling]]
  * Team
    * [[onboarding/team/role-level-3]]
    * [[onboarding/team/expectations]]

* Systems
  * [[systems/core-platform-overview]]
  * [[systems/other-system]]

* Organization
  * [[organization/policy-notes]]
  * [[organization/useful-links]]

* People
  * [[people/key-contacts]]
```

Key points:
- [[Home]] links to `Home.md`.
- [[path/to/page]] links to `path/to/page.md`.
- Folder names become section headers; nested folders become nested bullets.
- The script can respect a blocklist to exclude scratch/meta folders.

This makes the wiki feel like a real docs site while still being 100% file-based.

⸻

### 8. How to Use This as a Template

To build your own version of this setup:

1. Create the folder structure

```text
Notes/
  private/
  public/
```

2. Organize public notes into `public/` with folders like `onboarding/`, `systems/`, `organization/`, `people/`, `meta/`.
3. Create a remote repo (e.g., `notes`), then:

```shell
cd public
git init
git branch -M main
git remote add origin git@HOSTNAME:OWNER/notes.git
git add .
git commit -m "Initial notes"
git push -u origin main
```

4. Clone the wiki repo next to it:

```shell
cd Notes
git clone git@HOSTNAME:OWNER/notes.wiki.git wiki
```

5. Add a sync script (`wikiSync.sh` or similar) that:
	- Mirrors `public/` → `wiki/` with a blocklist
	- Ensures `Home.md` exists
	- Regenerates `_Sidebar.md`
6. Commit & push from both repos:
	- `public/` → main repo (Code tab view)
	- `wiki/` → wiki (Wiki tab view with sidebar)

After that, you:
- Work in Markdown locally (VS Code / Obsidian / whatever).
- `git push` from `public/` to update the repo.
- Run the sync script + `git push` from `wiki/` to refresh the wiki.

Your team gets a clean, navigable internal wiki built entirely from plain `.md` files.

⸻

This file (or similar) lives in `meta/` so anyone curious about “how the sausage is made” can read it, copy the pattern, or fork their own version of a Markdown-first internal wiki.

> [!CAUTION]
> Github's implementation of the Wiki feature is *abysmal* and poorly documented. I'm holding off on uploading the `wikiSync.sh` file that generates the `_Sidebar.md` until I can better understand the rendering syntax.

⸻
<details>
<summary><h2>Extension Stack - Click To Expand</h2></summary>

Extensions are listed from most to least essential for this setup.

⸻

### Markdown All in One (yzhang.markdown-all-in-one)

Link: https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one

Backbone for Markdown authoring in VS Code:

-	Keyboard shortcuts for headings, lists, tables.
	-	Table of contents generation.
	-	Built-in preview enhancements.

Chosen because it makes Markdown feel like a first-class document editor while staying close to vanilla VS Code.

⸻

### Markless (tejasvi.markless)

Link: https://marketplace.visualstudio.com/items?itemName=tejasvi.markless

Inline Markdown rendering in the main editor:
	-	WYSIWYG-style view while still editing plain Markdown.
	-	Fast enough for large files; uses VS Code’s native editor under the hood.

Chosen because it gives a Typora/Obsidian-like editing experience directly in VS Code without custom UIs or external apps.

⸻

### Foam (foam.foam-vscode)

Link: https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode

Foam turns VS Code into a personal knowledge base:
	-	[[wikilinks]] and backlinks.
	-	Graph view of your notes.
	-	Works entirely on local Markdown files.

Chosen as the “Obsidian-equivalent” PKM layer that integrates cleanly with Git and the rest of the VS Code ecosystem.

⸻

### Todo MD (usernamehw.todo-md)

Link: https://marketplace.visualstudio.com/items?itemName=usernamehw.todo-md

Todo MD is the task engine for your Hypertxt files:
	-	Sidebar/tree view of tasks grouped by project, tag, etc.
	-	Operates directly on todo.md and similar files; no import/export.
	-	Works well with +Project and @context conventions.

Chosen as the primary GTD-style task viewer living on top of the Hypertxt Task Markdown spec.

⸻

### KanMark (Pd-ch.kanmark)

Link: https://marketplace.visualstudio.com/items?itemName=Pd-ch.kanmark

KanMark turns Markdown headings and checkboxes into a Kanban board:
	-	Columns = headings (e.g., ## +Inbox, ## +Next, ## +Waiting, ## +Done).
	-	Cards = tasks (- [ ]) under those headings.
	-	Subtasks and notes render inside cards.

Chosen as the visual Kanban layer over the same Markdown task files, so there is no separate board format to maintain.

⸻

### Todo Tree (Gruntfuggly.todo-tree)

Link: https://marketplace.visualstudio.com/items?itemName=Gruntfuggly.todo-tree

Todo Tree scans the entire workspace for TODO-like comments:
	-	Uses ripgrep to find TODO, FIXME, etc.
	-	Shows them in a sidebar tree grouped by file.
	-	Click to jump directly to the line in code.

Chosen as the dedicated code TODO radar, separate from the Hypertxt planning system. Code comments stay in code; planning stays in todo.md.

⸻

### Markdown Paste Image (telesoho.vscode-markdown-paste-image)

Link: https://marketplace.visualstudio.com/items?itemName=telesoho.vscode-markdown-paste-image

Paste an image from the clipboard and automatically:
	-	Save it into a configured folder.
	-	Insert the correct Markdown image link.

Chosen to keep records, diagrams, and screenshots close to the notes without breaking the “all-local Markdown” constraint.

⸻

### Markdown Table Prettifier (TakumiI.markdowntable)

Link: https://marketplace.visualstudio.com/items?itemName=TakumiI.markdowntable

Helps with:
	-	Creating Markdown tables.
	-	Aligning columns.
	-	Editing table cells without fighting the pipe characters.

Chosen for quick structure around specs, feature matrices, and GTD lists that need tabular layout.

⸻

### Markdown Mermaid (bierner.markdown-mermaid)

Link: https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid

Adds Mermaid diagram support in Markdown preview:
	-	mermaid blocks render as diagrams.
	-	Great for flows, state machines, and architecture sketches.

Chosen to keep lightweight diagrams in the same Markdown files as notes and tasks.

⸻

### Mermaid Markdown Syntax Highlighting (bpruitt-goddard.mermaid-markdown-syntax-highlighting)

Link: https://marketplace.visualstudio.com/items?itemName=bpruitt-goddard.mermaid-markdown-syntax-highlighting

Provides syntax highlighting inside mermaid code blocks.

Chosen as a companion to Markdown Mermaid to make diagram blocks readable in the editor.

⸻

### Draw.io Integration (hediet.vscode-drawio)

Link: https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio

Draw structured diagrams directly in VS Code:
	-	Flowcharts, sequence diagrams, architecture diagrams.
	-	Files remain local (.drawio or embedded SVG/PNG).

Chosen for more formal diagrams than Mermaid, still fully local and Git-friendly.

⸻

### Excalidraw Editor (pomdtr.excalidraw-editor)

Link: https://marketplace.visualstudio.com/items?itemName=pomdtr.excalidraw-editor

Excalidraw-style sketch diagrams inside VS Code:
	-	Hand-drawn look & feel for whiteboard-style thinking.
	-	Files stored alongside Markdown in the repo.

Chosen for quick, informal diagramming that matches “scratchpad” thinking better than rigid nodes-and-arrows.

⸻

### Nord Theme (arcticicestudio.nord-visual-studio-code)

Link: https://marketplace.visualstudio.com/items?itemName=arcticicestudio.nord-visual-studio-code

A calm, high-contrast theme:
	-	Easy on the eyes for long writing/coding sessions.
	-	Works well with Markdown inline rendering and emoji.

Chosen as the base visual style for the whole environment.

⸻

### Prettier (esbenp.prettier-vscode)

Link: https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode

Formatter for code and, optionally, Markdown:
	-	Keeps code consistent when you do need to write scripts or small tools.
	-	Can be configured to leave Markdown alone or format it with specific rules.

Chosen to reduce formatting friction in code and occasional Markdown automation.

⸻

### Vim Keybindings (vscodevim.vim)

Link: https://marketplace.visualstudio.com/items?itemName=vscodevim.vim

Modal editing:
	-	Vim motions for fast navigation in large Markdown and code files.
	-	Works fine with Markless and other Markdown tooling.

Chosen to speed up editing for users already comfortable with Vim semantics.

⸻

### SpellRight (ban.spellright)

Link: https://marketplace.visualstudio.com/items?itemName=ban.spellright

Spell checker for Markdown and text:
	-	Multi-language support.
	-	Works well with Markdown documents and comments.

Chosen to keep long-form writing, specs, and logs clean in a corporate environment where typos in docs can cause confusion.

⸻

### Dictionary Completion (yzhang.dictionary-completion)

Link: https://marketplace.visualstudio.com/items?itemName=yzhang.dictionary-completion

Provides word completions from an English dictionary:
	-	Helps finish words quickly when writing prose in Markdown.
	-	Complements SpellRight (which cares about correctness, not speed).

Chosen to speed up writing notes and tasks without relying on cloud-based AI completions.

⸻

### EmojiSense (bierner.emojisense)

Link: https://marketplace.visualstudio.com/items?itemName=bierner.emojisense

Emoji auto-completion:
	-	Type :smile and get 😊, etc.
	-	Useful for quick visual markers in todo lists and notes.

Chosen as a lightweight way to add visual affordances to tasks without custom glyphs or fonts.

⸻

### Markdown Emoji (bierner.markdown-emoji)

Link: https://marketplace.visualstudio.com/items?itemName=bierner.markdown-emoji

Renders emoji shortcodes in Markdown preview:
	-	:warning: → ⚠️ in preview.
	-	Plays nicely with EmojiSense for a consistent emoji workflow.

Chosen to ensure emoji used in tasks and notes render correctly in preview and exported docs.

⸻

### Markdown Footnotes (bierner.markdown-footnotes)

Link: https://marketplace.visualstudio.com/items?itemName=bierner.markdown-footnotes

Adds footnote syntax support for Markdown:
	-	[^1] and [^1]: style notes.
	-	Useful for essays, specs, or design docs with asides and citations.

Chosen to keep longer-form documents readable without cluttering the main text.

⸻

### PDF Viewer (tomoki1207.pdf)

Link: https://marketplace.visualstudio.com/items?itemName=tomoki1207.pdf

Inline PDF viewing in VS Code:
	-	Open specs, research papers, and corporate PDFs without leaving the editor.
	-	Helpful for referencing documents while taking notes in Markdown next to them.

Chosen to keep the “single window” workflow, especially on locked-down machines where external PDF tools may be restricted.

⸻

### GitDoc (vsls-contrib.gitdoc) — Optional

Link: https://marketplace.visualstudio.com/items?itemName=vsls-contrib.gitdoc

Collaborative, Git-backed documents.

This is optional. It can be useful if you co-edit planning docs or notes with colleagues, but it’s not required for the core GTD + PKM workflow described above.

⸻
</details>

## Recommended Extension Settings & Conventions

A few tweaks make this system behave much better.

### Todo MD (usernamehw.todo-md)

Comment start characters

Set the comment prefix to a Markdown-friendly blockquote so you can have multi-line notes under tasks:

```json
// settings.json
"todo.commentStart": "> "
```

This lets you write:

```markdown
- [ ] Task with notes
  > First note line
  > Second note line
```

Todo MD treats these as comments/notes; Markdown treats them as blockquotes; they fold nicely in the editor.

### Tab size / indentation

For cleaner folding and consistent subtasks:

```json
"[markdown]": {
  "editor.tabSize": 2
}
```

And in your Markdown:

-	Project headings: no indent, e.g. ## +Project:
-	Tasks under a project: indented once (2 spaces) relative to heading.
-	Subtasks: indented twice relative to the heading.

This plays nicely with Todo MD’s project parsing and the tree view.

### KanMark (Pd-ch.kanmark)

-	Keep headings at the top level:

```markdown
## +Inbox:
## +Next:
## +Waiting:
## +Done:
```

-	Keep task lines immediately under those headings (with standard list indentation). Avoid extra spaces or exotic list markers; KanMark expects - [ ] / - [x].

If KanMark reorders cards and mangles indentation, running a Markdown formatter / linter pass can help re-normalize spacing.

### General VS Code / Workspace

Consider a workspace settings file (.vscode/settings.json) that pins:

```json
{
  "[markdown]": {
    "editor.wordWrap": "on",
    "editor.tabSize": 2
  },
  "files.associations": {
    "*.tdmd": "markdown"
  }
}
```

This makes .tdmd files behave exactly like Markdown in the editor and preview, if you choose to use that extension.

⸻

## FAQ

### Why not just use Org-mode?

Org-mode is extremely powerful, but:

-	It’s its own format, not Markdown.
-	The full experience (agenda, exporters, Babel, etc.) really only exists inside Emacs.
-	VS Code Org extensions currently don’t match the depth of the Emacs ecosystem.
-	This system is designed to be:
-	Markdown-native (GitHub, static sites, Obsidian/Foam),
-	VS Code-first, and
-	Friendly to locked-down corporate machines.

So Org is more like a reference design; this repo is a pragmatic Markdown-based implementation in the tools people actually use at work.

⸻

### Why not just use Obsidian?

Obsidian is fantastic, but:

-	Many corporate environments don’t allow installing separate apps or syncing to external services.
-	Some workflows require staying inside VS Code (for policy or convenience).
-	This setup uses:
-	Only VS Code + extensions,
-	Plain Markdown in a Git repo,
-	No external sync services.

You can still open the same folder as an Obsidian vault at home if you want. The Hypertxt spec is compatible with Obsidian’s Markdown.

⸻

### Why not Obsidian Tasks?

Obsidian Tasks has a rich task DSL and query engine, but:

-	It lives entirely inside Obsidian’s plugin ecosystem.
-	There is no equivalent “Obsidian Tasks engine” for VS Code right now.
-	The emoji-based DSL is harder to parse with generic tools or CLIs.

This system instead:

-	Uses simple {key:value} metadata ({due:YYYY-MM-DD}, etc.).
-	Keeps everything compatible with Todo MD, KanMark, Foam, GitHub, and future scripts.

Conceptually, many ideas are borrowed from Obsidian Tasks, but the implementation is tool-agnostic.

⸻

### Where do code TODOs go vs tasks in todo.md?

Code TODOs

-	Short, local comments like // TODO: handle null case.
-	Best kept in the code itself.
-	Surfaced via Todo Tree as bookmarks / landmines.

Planning tasks (todo.md / Hypertxt files)

-	Higher-level work items with due dates, priorities, and notes.
-	Live in todo.md and are shown via Todo MD + KanMark.

If a code TODO becomes important enough to plan around, you can manually promote it into todo.md and optionally add a link back to the file/line.

⸻

### Why .tdmd instead of just .md?

You can use either. .tdmd is just a convenient, optional marker:

“This Markdown file follows the Hypertxt Task Markdown spec.”

To make VS Code treat it like Markdown, add:

```json
"files.associations": {
  "*.tdmd": "markdown"
}
```

⸻

## Known Issues & Quirks

This stack works, but there are some sharp edges.

### Todo MD quirks

-	\## showing up as a tag in the web view
In some views, \## (from headings like \## +Project:) may appear as a “tag-like” artifact in Todo MD’s sidebar/web view. It doesn’t affect behavior, just looks odd.
-	Project heading indentation requirements
For Todo MD to correctly associate tasks with a project:
-	The project heading (## +Project:) must be unindented.
-	Tasks must be consistently indented under it.
-	If tasks are not indented as expected, they may not be grouped correctly in the sidebar.

### KanMark quirks

-	Reordering cards can mangle indentation and tags
When you drag cards between columns or reorder them, KanMark rewrites the underlying Markdown. Sometimes this:
-	Removes or alters top-level tags.
-	Flattens indentation or changes spacing.
A Markdown formatter / linter pass can often fix the damage, but it’s something to watch for in Git diffs.

### Theme / visual bugs

-	Nord theme + Markdown / task UIs
Some minor visual glitches can appear:
-	Checkbox or link contrast in certain views.
-	Slight misalignment in web views or tree views.

These are cosmetic and likely theme-related; if something looks wrong, try temporarily switching to the default VS Code theme to confirm.

⸻

## Usage Overview

-	Planning / GTD:
-	Use todo.md (or .tdmd) with the Hypertxt Task Markdown spec.
-	View tasks as lists in Todo MD and as boards in KanMark.
-	Personal Knowledge Base:
-	Use Foam for notes in notes/, with [[wikilinks]] between them.
-	Edit with inline Markdown rendering via Markless.
-	Code TODOs:
-	Use // TODO: comments in code as local markers.
-	Surface them in a single view with Todo Tree.
-	Only promote important ones into todo.md when they deserve real tracking.
-	Docs & Diagrams:
-	Keep everything in Markdown, enriched with Mermaid, Draw.io, and Excalidraw.
-	Use Markdown Paste Image and PDF viewer to embed references directly into the workspace.

All critical data lives in a Git repo of plain-text Markdown, with VS Code providing the views (list, Kanban, wiki, diagrams) without needing any external cloud services or custom infrastructure.

hypertxt

hypertxt Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

hypertxt

hypertxt Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README