Coder Legion - Recent posts tagged markdown

Markdown without a back door:

Tue, 27 Oct 2026 18:54:33 +0000

How scrml lets an author write bold instead of , and why nothing inside an block can ever run.

Where this came from
It started with a security review, not a feature request. scrml treats the bodies of

 and  as raw content, and until this week the compiler copied raw content into the page exactly as written. A review then ran these through a real Chromium:

// the handler runs

// a same-origin script runs

// the CSS applies

The fix was a ruling: raw bodies now render as text. < and > are encoded, & is left alone so the many existing <…> code samples keep working, and the common

…

wrapper stays a real element. Across 4,523 raw bodies in 12 repositories, that breaks nothing.

It also closed the last place an author could type formatting tags inside text. so I asked the obvious question: can scrml have a first-class , so an author gets the effect of bold without writing ?

The answer is yes. It took four decisions.

What it looks like
You write

<md>
    ## Filing a good bug report

    Before you file, **search the board**.

    - Say what you *expected*.
    - Paste the exact error in `backticks`.
    - Read the [triage guide](/docs/triage).
</md>

The page gets

…

Before you file,
search the board.

Say what you expected.
… backticks.
… …

The body is dedented the way Java text blocks are: the smallest indentation among the lines, counting the closing tag's line, is stripped. So sits naturally inside indented scrml markup. Static is turned into elements at build time and costs nothing at runtime.

DECISION 1 of 4

A value inside is text, never markdown
Ruled: ${…} inside is text-only.

## Welcome back, ${@user.name} Your last order shipped **${@order.date}**.

Now suppose a user sets their name to this:

Your account is locked

Verify here
If interpolated values were parsed as markdown, that name would render a fake heading and a phishing link. The link is a perfectly valid https URL, so no URL check would stop it. Under the rule we chose, the value goes in as plain text and can never create structure. The page shows the odd name literally.

This is the same contract scrml already uses for SQL. In ?{ … WHERE id = ${id} } the value is a bound parameter: data is never code. applies that rule to prose.

DECISION 2 of 4

Markdown from data gets its own, explicit form
Ruled: is part of , designed now and built second.

Comments, posts and CMS rows hold markdown that arrives at runtime. That is the dangerous case, so it does not happen by accident. It has its own spelling:

= ?{ SELECT body FROM posts WHERE id = ${id} }.get()

It uses the same reader and the same small set of output elements as static . A user's markdown can produce bold and a link, but never a script, an event handler or a javascript: link. Data-driven headings get no generated id, because ids chosen by users can overwrite DOM globals. The parser for this form ships only on pages that use of=; it is estimated at 3–6 KB gzipped, an estimate that has not been measured yet.

DECISION 3 of 4

A small dialect, one way to write each thing
bryan: "one way to do it with lints to guide"

In
paragraphs

headings

em and strong
inline code and fenced code
inline links and images
lists and > quotes
--- rules
tables and ~~strike~~
Out
raw HTML (shown as text)
indented code blocks
underlined === headings
reference-style links
entity references
https://… autolinks
footnotes and task lists
Markdown has several ways to write most things. scrml keeps one. When pasted markdown uses a dropped construct, a W-MD-* warning names the form to use instead, so a cut teaches rather than surprises.

Some cuts are forced. Indented code blocks had to go: lives inside indented source, and an indentation-sensitive construct would misfire constantly. MDX dropped them for the same reason. Others make the dialect safer. Raw HTML is the obvious one, and task lists are out because they would put form controls into the output. Djot, John MacFarlane's cleanup of CommonMark, made the same kinds of cuts.

DECISION 4 of 4

One markdown reader, written in scrml
Ruled: the parser is a single scrml module, scrml:md, used by both compilers.

scrml currently has two compilers: impl#1, written in TypeScript, and the self-hosting bootstrap, written in scrml. The markdown parser is written once, as an ordinary scrml module. impl#1 compiles it like any other stdlib module and uses it twice: at build time to turn static into elements, and as the runtime parser shipped for . The bootstrap uses the same module.

The alternatives were a TypeScript parser now and a scrml one later, or waiting for the bootstrap. The first means two readers of the same text, and two readers that can disagree is exactly the shape that kept producing security bypasses this session. The second means waiting. One reader avoids both. The cost is new machinery: impl#1 needs a hook that runs a scrml module at compile time. That hook gets the same adversarial review as everything else.

Why nothing inside can run
Most markdown renderers produce an HTML string and then clean it, by stripping , blocking javascript:, and so on. Those are lists of known-bad things, and the list is always one entry short. DOMPurify has a long run of mutation-XSS bypasses because what it checks and what the browser re-parses can differ. @nuxtjs/mdc had a CVE (CVE-2025-24981) for javascript: URLs hidden behind hex entities.

works the other way around. The renderer can only build a fixed set of elements, each with a fixed set of attributes: ElementAttributesWhere the value comes from p em strong del blockquote ul li hr br table thead tbody tr prenone— olstartdigits from the list marker th tdstyleone of three compiler constants for alignment h1–h6ida compiler slug, static only codeclasslanguage- plus letters, digits, _+- ahref, titlehref must pass scrml's URL allow-list imgsrc, alt, titlesrc must pass the same allow-list Content reaches the page only as text nodes or as values of those attributes. No HTML string is ever handed to the browser to parse. The URL check is scrml's existing allow-list, which admits http:, https:, mailto: and similar schemes rather than trying to name every dangerous one. A dangerous element the browsers add next year cannot appear, because has no way to build it. Who pays Authors can't put a

or inside . They close the block and write the element in ordinary scrml markup. People pasting from GitHub see raw HTML tags as text, and get a warning for each dropped construct. Pages that render user markdown ship the parser, estimated at 3–6 KB gzipped. Pages with only static ship nothing. The compiler gains a compile-time hook into a scrml module, which is new machinery to get right. Not covered: a comment rendered through of= can still say "click here to re-verify" with a real https link. That is content moderation, and true of every forum. Images in user markdown can also act as tracking pixels; an opt-in image policy is still an open question. Prior art The closest designs are Markdoc, from Stripe, which keeps content declarative and won't mix arbitrary code into it, and elm-markdown, which renders to a typed tree instead of an HTML string and fails loudly on unexpected HTML. Djot shaped the dialect cuts. Most static-site tools, such as Hugo and markdown-it, default to dropping raw HTML. Tools that pass it through, such as marked, leave sanitizing to the user; marked's README says so directly. Status: the four decisions were ruled in S462. The full design, including the prior-art table and the security model, is in scrml-support/docs/deep-dives/md-element-2026-10-11.md. Build phases: 1 is the SPEC section and the scrml:md parser (in progress); 2 is the impl#1 hook for static ; 3 is . This draft should be re-checked against the compiler once phase 2 lands, and every code block compiled before publishing.

Deterministic Formatting Normalization

Sun, 18 Oct 2026 11:14:40 +0000

Deterministic formatting normalization prevents expensive LLM generation retries when a model output fails structural validation due to minor whitespace variations.

Quick solution:

function normalizeQuickSolutionLabel(content: string): string {
  return content.replace(/^([\*\_]{2}Quick solution:[\*\_]{2})\s*(.+)$/gm, '$1\n$2');
}

When a publishing pipeline enforces strict layout rules, a valid model answer often fails review solely because a required label shares a line with prose. As discussed in our previous guide on Building A Remote Only Android Repository, rigid structural checks help maintain consistency across automated pipelines, but they require careful handling of minor syntax drift. For more information on how to Engineering High Intent Activity Landing Pages, consider the importance of consistent formatting in maintaining a seamless user experience.

Understanding the Markdown Formatting Failure

Automated editorial linters frequently require explicit structural markers, such as a standalone bold label marking the start of a quick solution. Models occasionally emit these labels inline with descriptive text, violating parser expectations. Repeating the entire generation request wastes API credits and latency without altering the underlying formatting tendency. You can review the underlying specifications at CommonMark to understand how block boundaries are parsed.

Implementation Trade-Offs

While automated string repair is efficient, it must remain tightly scoped to avoid corrupting code blocks, quotes, or indented lists.

Option	When to Use It	Trade-Off or Failure Risk	Recommendation
Full Generation Retry	When semantic content is missing or incorrect.	High token cost and increased latency for trivial formatting fixes.	Use only for semantic errors.
Deterministic Regex Repair	When layout variations violate strict structural linters.	Can accidentally alter code blocks if not properly scoped.	Use for isolated whitespace and line-break fixes.
Loose Parser Rules	When pipeline strictness can be relaxed.	Risks letting malformed articles reach production review.	Avoid for automated publishing workflows.

Verification Checklist

Confirm that the repair function targets only line-start labels.
Verify that fenced code blocks and inline code remain untouched.
Run local unit tests to ensure that valid layouts pass without modification.
Check that pipeline execution limits, such as those documented by Cloudflare Workers, are respected during string manipulation.

Preserve Captions in Markdown Publishing

Sat, 17 Oct 2026 15:04:18 +0000

Markdown looks simple because it is easy to type. That simplicity can be deceptive when you build an automated publisher.

Quick solution:

def extract_hero_and_caption(ast_nodes):
    hero_index = find_hero_image_node(ast_nodes)
    if hero_index is not None and is_valid_caption_block(ast_nodes[hero_index + 1]):
        return ast_nodes[hero_index + 2:]
    return ast_nodes[hero_index + 1:]

CommonMark 0.31.2 defines link and image syntax; caption handling is an application-level convention that the transform must preserve explicitly.

A regular expression removes a hero image. Another inserts an internal link. A third strips a caption. The pipeline passes unit tests, but the rendered article suddenly contains an orphan caption or an unnatural sentence where one word has been replaced by an entire destination title.

The problem is not Markdown itself. The problem is treating structured editorial text as an unstructured string.

Two transformations deserve particular care:

extracting an image and its visible caption;
inserting contextual links without rewriting the author's voice.

Standard Markdown does not give you a universal caption node

CommonMark defines links and images, but there is no universal native image-plus-visible-caption construct.

Publishers therefore use conventions such as:

![Architecture overview](hero.jpg)

*The pipeline keeps content and deployment state separate.*

or raw HTML:

`<figure>`
  `<img src="hero.jpg" alt="Architecture overview">`
  `<figcaption>`The pipeline keeps content and deployment state separate.`</figcaption>`
`</figure>`

The first form is just an image block followed by a paragraph. Your pipeline may decide that the paragraph is a caption, but that interpretation is application-specific.

That means caption extraction needs an explicit rule.

The greedy whitespace bug

Consider this input:

![A deployment workflow](hero.jpg)

*The publication path has three independent gates.*

The article begins here with a normal paragraph.

A regex designed to remove the image may accidentally consume too much or too little whitespace.

If it removes only the image token, the caption remains at the top of the article as ordinary prose.

If it greedily absorbs multiple following paragraphs, the first real paragraph disappears too.

The dangerous pattern is matching the image, then matching arbitrary whitespace and text.

The safer rule is structural:

locate the image block;
identify exactly the next block;
classify that block as a caption only if it matches your caption convention;
remove those exact blocks;
preserve all other whitespace and prose.

Prefer an AST when transforms become important

For one tightly controlled format, a carefully tested parser can be enough.

As soon as your pipeline performs several Markdown transformations, an abstract syntax tree becomes easier to reason about than stacked regular expressions.

The conceptual flow becomes:

Markdown
  -> parse blocks/nodes
  -> identify hero image node
  -> inspect immediate next paragraph
  -> classify caption
  -> transform nodes
  -> render Markdown or HTML

Now the next paragraph is an actual node, not a substring discovered by a greedy expression.

An AST also helps distinguish links inside paragraphs, headings, code fences, image alt text, and existing link nodes.

That matters for internal-link insertion.

Contextual links should preserve an existing phrase

Imagine the article contains:

A reliable serverless publishing workflow needs explicit retry boundaries.

You want to link serverless publishing workflow to a relevant internal article.

The good result is:

A reliable [serverless publishing workflow](https://raylabs.app/articles/designing-a-reliable-serverless-ai-publishing-workflow/) needs explicit retry boundaries.

A bad automation finds only the word workflow and replaces it with the destination page title:

A reliable serverless publishing [Designing a Reliable Serverless AI Publishing Workflow](https://raylabs.app/articles/designing-a-reliable-serverless-ai-publishing-workflow/) needs explicit retry boundaries.

The URL may be correct, but the sentence no longer sounds authored.

The rule should be simple: link an existing natural phrase, and do not rewrite prose to manufacture an anchor.

Score candidate phrases instead of replacing tokens

A practical link inserter can work from phrase candidates.

For each destination:

collect phrases already present in the article;
reject phrases inside headings, code, existing links, and captions;
prefer multiword phrases with clear semantic overlap;
choose the first contextually useful occurrence;
wrap exactly that phrase;
do not alter surrounding words.

A basic score can favor three-to-six-word phrases, exact topic terms, and body paragraphs over navigation-like text.

The scoring system does not need artificial intelligence. It needs predictable editorial constraints.

Never link inside code, image syntax, or an existing link

String replacement is especially risky because the same phrase may appear in code, image alt text, headings, or a link that already exists.

A syntax-aware transform can exclude those node types.

A regex stack tends to solve this by adding exceptions until maintenance becomes harder than parsing Markdown correctly.

Link insertion should be idempotent

Run your publishing transform twice.

The second run should not:

add a second copy of the same link;
nest Markdown links;
change the anchor phrase;
reinsert a removed caption;
move the hero;
change unrelated whitespace.

Idempotency is one of the strongest tests for editorial automation because production jobs are retried.

If the same draft can be transformed twice with a different output, recovery becomes dangerous.

This is part of the same design problem discussed in Automating Medium Draft Workflows: retries should continue the same artifact rather than mutate it unpredictably.

Separate editorial transformation from privacy validation

A Markdown transformer may also need to reject private repository URLs or internal hostnames.

Keep that as a separate validator.

Caption extraction answers which blocks belong to the hero presentation. Internal-link insertion answers which existing phrase can safely become an anchor. Privacy validation answers whether any forbidden URL or identifier remains in the final document.

RayLabs treats private-link detection as its own boundary in Preventing Private Repository Links in Public Articles.

Verify the rendered result, not only the source

A Markdown file can look correct and still render incorrectly under the target parser.

Your final test should render the transformed document through the same stack used in production and inspect the result.

For caption handling, confirm that exactly one hero exists, the caption appears in the intended location, and the caption does not appear again as the first article paragraph.

For contextual links, verify that anchor text matches the intended phrase, the destination is the expected existing URL, no nested anchors exist, and code and headings remain unchanged.

Execution Checklist

[ ] Confirm caption extraction isolates hero image and caption blocks without consuming subsequent paragraphs.
[ ] Verify contextual link insertion wraps exact natural phrases without altering surrounding text.
[ ] Execute the publishing transform twice to guarantee idempotency.
[ ] Render the final output through the production parser to validate HTML structure.

INTENTIO - Framework

Wed, 07 Oct 2026 20:04:13 +0000

INTENTIO: Reclaiming the Digital Mind with PHP, Small Language Models, and Absolute Data Sovereignty

"Not a chatbot. Not a cloud service. A bounded space where AI pays attention."

1. The Story Behind INTENTIO: The Quiet Rebellion

The Illusion of the Cloud Oracle

The current artificial intelligence landscape has surrendered to a single narrative: that intelligence requires planetary scale, that useful cognition belongs exclusively in hyperscaler data centers, and that the only way to interact with an AI model is to stream your thoughts, proprietary data, and creative work across third-party networks to be logged, indexed, and monetized.

Modern AI products are designed as oracles. They are trained on the unfiltered entropy of the open internet. They attempt to know everything, yet they understand almost nothing about your specific domain, your private notes, your company’s trade secrets, or your intellectual boundary. When you query an oracle, you receive a generalized, smoothed-out consensus. Worse, you pay for that answer with your privacy, accepting the constant risk of hallucinations and the rent-seeking economics of cloud API tokens.

INTENTIO is a direct rejection of that consensus.

Created by Melasistema, INTENTIO began with a clear conviction: Software must run on hardware you own, over data that never leaves your machine, within systems you can read and inspect all the way down.

Private AI is not a toggle in a settings menu. It is not an enterprise compliance checkbox. Private AI is an architectural decision.

INTENTIO does not attempt to know everything. Instead, it creates a disciplined, bounded cognitive space where a Small Language Model (SLM) focuses entirely on your curated knowledge. It acts not as an omniscient oracle, but as a rigorous interpreter of meaning, strictly grounded in the facts and structures you define.

The PHP Anomaly: Why Write a Cognitive Engine in PHP?

In a developer culture intoxicated by multi-gigabyte Python virtual environments, fragile dependency trees, and ephemeral JavaScript runtimes, choosing PHP to build a modern cognitive framework sounds like heresy.

It is, in fact, an intentional design choice.

PHP has spent three decades refining one thing better than almost any other ecosystem on Earth: pragmatic data processing, filesystem manipulation, text parsing, and inspectable architecture.

Modern PHP (8.2+) is fast, typed, rock-solid, and easily deployable.
It does not suffer from virtual environment rot, broken system wheels, or opaque abstraction wrappers.
Every byte of memory, every string transformation, every API interaction, and every filesystem operation can be read, debugged, and understood without magic.

Most local AI workflows do not need Python's deep learning training pipelines; they need orchestration. They need an intelligent, lean command-line engine that reads Markdown files, chunks documents, communicates over clean local protocols, coordinates vector representations, and formats prompts for inference.

PHP handles this orchestration with surgical precision and near-zero runtime overhead. In INTENTIO, PHP acts as the conductor, orchestrating high-performance local inference engines while keeping the application layer clean, inspectable, and human-readable.

The Evolution: Dropping Ollama in INTENTIO 0.3.0

For over a year, INTENTIO relied on Ollama as its primary inference backend. Ollama served the project well during its initial stages: it ran language models, generated vector embeddings, and, starting in version 0.2.1, briefly powered image generation workflows.

However, as INTENTIO pushed deeper into deterministic workflows and multimodal consistency, friction emerged:

The Image Breakdown: Upstream changes in Ollama broke compatibility with the specific image models INTENTIO depended on (such as the Cartoon Universe character consistency package). The image pipeline was effectively stranded.
Architectural Redundancy: Maintaining separate adapters for text, embeddings, and images within Ollama created unnecessary abstraction bloat.
Closer to the Silicon: INTENTIO was developed on Apple Silicon. The macOS unified memory architecture and Neural Engine are among the most power-efficient local AI platforms available. Rather than running through general-purpose abstractions, INTENTIO needed a direct line to Apple’s MLX framework.

With version 0.3.0, INTENTIO dropped Ollama entirely.

Instead of a single heavy backend trying to do everything, INTENTIO split its architecture across two high-performance, MLX-native tools:

oMLX (Text & Embeddings): A lightweight local server built natively on Apple MLX. It serves text generation and vector embeddings with true token-by-token streaming and batched embedding requests. The swap removed 309 lines of Ollama adapter boilerplate and added 309 lines of clean, dedicated oMLX client logic.
mflux (Image Synthesis): A command-line tool built on Apple MLX running FLUX.2 klein 4B. Unlike background servers that sit idle consuming valuable VRAM, mflux runs on demand, renders the image with live terminal progress, saves the output directly into the workspace, and exits cleanly. Crucially, mflux supports rendering from reference images, unlocking reproducible visual styles, consistent characters, and brand logo placement on physical mockups.

The result is a cognitive framework that is faster, leaner, and deeply integrated into local hardware.

       ┌────────────────────────────────────────────────────────┐
       │                INTENTIO Core (PHP CLI)                  │
       │    - Markdown Parser    - Chunking & Ingestion Engine   │
       │    - Spaces & Packages  - Prompt Templates & Intent     │
       └──────────────┬──────────────────────────┬──────────────┘
                      │                          │
        Text & Vector Embeddings          On-Demand Images
                      ▼                          ▼
       ┌────────────────────────┐      ┌────────────────────────┐
       │         oMLX           │      │         mflux          │
       │  (Apple MLX Server)    │      │  (Apple MLX CLI Tool)  │
       │  - SLM Text Generation │      │  - FLUX.2 klein 4B     │
       │  - Batch Embeddings    │      │  - Image-to-Image /    │
       │  - Token Streaming     │      │    Reference Consistency│
       └────────────────────────┘      └────────────────────────┘
                      │                          │
       ┌──────────────┴──────────────────────────┴──────────────┐
       │             Apple Silicon Unified Memory (MLX)         │
       └────────────────────────────────────────────────────────┘

2. How INTENTIO Works: The Cognitive Architecture

INTENTIO operates on a foundational rule: Structure matters more than scale.

When you restrict a Small Language Model (typically between 3B and 8B parameters) to a clean, highly structured, well-embedded knowledge base, it frequently outperforms a 70B or 400B cloud giant that is struggling through a swamp of general internet noise.

Here is how INTENTIO guides local silicon through complex human knowledge:

[ Your Filesystem ]
   spaces/domain/knowledge/
      ├── core-concepts.md
      ├── rules.md
      └── context.md
            │
            ▼  (./intentio ingest)
   [ Intelligent Chunking & Header Preservation ]
            │
            ▼  (Batched Vectorization)
   [ oMLX Embedding Engine ]
            │
            ▼
   [ Local Vector Index (On-Device Storage) ]
            │
            ├───────────────────────────────────────────────┐
            │ User Query: ./intentio ask "..."              │
            ▼                                               ▼
   [ Semantic Similarity Search ]               [ Markdown Prompt Template ]
            │                                               │
            └───────────────────────┬───────────────────────┘
                                    │
                                    ▼
                     [ Grounded Context Assembly ]
                                    │
                                    ▼
                         [ oMLX Local SLM ]
                                    │
                                    ▼  (Real-Time Token Streaming)
                     [ Coherent, Unhallucinated Answer ]

Step 1: The Filesystem as a Semantic Map

In INTENTIO, you do not upload files to a database black box. Your filesystem is your knowledge map.

Knowledge is partitioned into Spaces located under spaces/. Inside each space, you organize your domain knowledge using plain Markdown files:

spaces/
  my_brand/
    knowledge/
      01_brand_voice.md
      02_value_propositions.md
      03_audience_profiles.md
    commands/
      pitch.md
      critique.md
    manifest.json

Because the space is made of plain Markdown files, it remains 100% human-readable, trackable via Git, and editable in any text editor (Vim, Obsidian, VS Code, or Helix). You own the raw knowledge; INTENTIO merely interprets it.

Step 2: Ingestion & Fast Batched Embeddings

When you run:

./intentio ingest my_brand

INTENTIO parses your Markdown files, preserving structural hierarchies (headings, lists, code blocks). It divides content into semantically coherent chunks, retaining the document context inside the chunk metadata.

Under INTENTIO 0.3.0, chunks are embedded in a single batched request via oMLX. The entire space is vectorized in seconds on your Mac's Neural Engine, generating a fast, local index that resides safely inside your space folder.

Step 3: Grounded Retrieval Without Hallucination

When you ask INTENTIO a question:

./intentio ask my_brand "What is our position on third-party data tracking?"

INTENTIO does not let the model generate freely from its training data. Instead:

It converts your query into a vector representation via oMLX.
It performs a cosine similarity search across your local index.
It retrieves the exact sections of your Markdown documents that answer the query.
It injects those sections into a strictly bounded prompt.

The Small Language Model is instructed to act purely as an interpreter of the provided context. If the answer is not in your documents, the model tells you. It does not fabricate sources, invent facts, or fill gaps with random web trivia.

Step 4: Declarative Command Templates

INTENTIO lets you define specialized tasks as Commands. A command is a Markdown template that lives in your space's commands/ directory.

For example, a critique.md command might instruct the model to adopt the persona of a skeptical investor, evaluate an incoming argument against your company's core tenets, and output a structured table of weaknesses.

You execute it effortlessly:

./intentio run my_brand:critique "We are thinking of adding a cloud telemetry dashboard"

The command template sets the tone, posture, and output format; the local space provides the truth; the SLM provides the reasoning.

Step 5: Native Token Streaming

In earlier versions, users waited in silence while the model completed its entire inference cycle before the terminal updated.

With INTENTIO 0.3.0's oMLX integration, tokens stream directly to your terminal the millisecond they are generated. You watch the model's reasoning unfold in real time at the native decode speed of your Apple Silicon hardware.

Step 6: On-Demand, Reference-Grounded Visuals with `mflux`

Generating images with local AI has historically meant either wrestling with complex Python ComfyUI webs or running heavy daemon servers that consume 12 GB of VRAM even when idle.

INTENTIO handles images via mflux with the ultra-efficient FLUX.2 klein 4B model:

Zero Idle Footprint: INTENTIO spawns the CLI process only when you invoke an image command. Once the render completes, the memory is completely freed back to macOS.
Live Progress Feedback: Terminal progress bars show step-by-step rendering progress.
Visual Continuity via Reference Images: mflux allows image generation conditioned on existing reference files. If you generate a character in step one, step two can reuse that character in a new scene. If you have a corporate vector logo, INTENTIO can stamp that logo onto a 3D product mockup without distorting the emblem.

3. Key Features

Feature	What It Delivers	Why It Matters
Complete Data Sovereignty	100% offline, on-device execution. Zero telemetry, zero cloud APIs, zero external requests.	Your intellectual property, code, private thoughts, and legal records never cross a network wire.
Inspectable PHP Core	Clean, modern PHP 8.2+ codebase with clear classes, zero framework bloat, and minimal dependencies.	You can open any file in the framework, understand how it works in 5 minutes, and adapt it to your needs.
Apple Silicon MLX Acceleration	Native integration with `oMLX` (text/embeddings) and `mflux` (FLUX.2 klein 4B images).	Maximizes M-series unified memory bandwidth and Neural Engine efficiency without Python runtime headaches.
Live Token Streaming	Immediate real-time output in the CLI.	Eliminates prompt latency anxiety; read the model's reasoning as it types.
Structured Markdown Knowledge	Knowledge bases and prompt commands are plain `.md` files in your filesystem.	No proprietary database lock-in. Compatible with Git, Obsidian, and standard UNIX text utilities.
Zero Idle Memory Drain	Images render via CLI execution rather than persistent background daemons.	Your laptop stays cool, your battery lasts, and RAM is freed the instant rendering finishes.
Reproducible Image Conditioning	Reference-image rendering support via `mflux`.	Visual consistency across renders—crucial for brand design, storytelling, and UI pitch mockups.
Modular Package System	Pre-packaged domain spaces installed with a single command (`./intentio init <package>`).	Start immediately with curated knowledge systems and tested commands out of the box.

4. The Ecosystem in Action: Ready-Made Packages

INTENTIO is not an empty shell. It ships with ready-made Packages—self-contained spaces featuring curated knowledge bases, purpose-built Markdown commands, and tested prompt structures.

You can initialize any package into your local environment with one command:

./intentio init <package_name>

Here are three packages showcasing what bounded local cognition can do:

1. Hook Analyzer (`hook_analyzer`)

Writing effective copy usually involves guesswork or relying on generic ChatGPT platitudes. hook_analyzer turns INTENTIO into an objective copy auditor.

The Knowledge Base: Encapsulates established psychological models, cognitive biases (curiosity gap, loss aversion, pattern interrupts), and rigorous platform-specific scoring rules.
What It Does: Evaluates marketing hooks, scores them against cognitive retention metrics, contrasts two hooks side-by-side, and produces actionable platform reports (LinkedIn, X, newsletters, landing pages).
The Sovereign Advantage: Test confidential marketing strategies, unpublished book titles, and commercial campaigns without feeding them into corporate training loops.

2. Cartoon Universe (`cartoon_universe`)

Visual storytelling requires persistent character design, recognizable silhouettes, and cohesive styling—something one-shot prompt engines routinely fail at.

The Knowledge Base: Maintains strict style rules, color palettes, world-building lore, and aesthetic constraints.
What It Does: Works alongside mflux to generate stylized, expressive characters and scenes that adhere to unified aesthetic guidelines across multiple frames.
The Sovereign Advantage: Artists and creators retain total control over character model sheets and artistic assets locally on their machines.

3. Product Pitch Lab (`product_pitch_lab`)

Creating marketing collateral for new products requires combining abstract messaging with concrete visual consistency.

The Knowledge Base: Contains pitch structures (problem, solution, unique mechanism, proof), positioning frameworks, and landing page anatomy rules.
What It Does: Refines your value proposition while using mflux's reference image engine to place your authentic logo and product packaging into photorealistic scenes.
The Sovereign Advantage: A founder can iterate from raw product concept to complete investor pitch deck and visual mockups in complete secrecy on a laptop during a flight.

5. Technical Requirements & Configuration

INTENTIO 0.3.0 is built deliberately for developer ergonomics on modern hardware.

System Prerequisites

Hardware: Apple Silicon Mac (M1, M2, M3, M4, or later) with Unified Memory (16 GB+ recommended for running SLMs alongside image models).
Runtime: PHP 8.2 or higher with standard extensions (curl, mbstring, json).
Text & Embedding Engine: oMLX running locally.
Visual Synthesis Tool: mflux installed in your system PATH.

Quick Verification

Once installed, check your local environment directly from the CLI:

./intentio status

INTENTIO will inspect your local oMLX server, verify that the configured text model and embedding model are loaded, check that mflux is available, and flag any missing dependencies before you begin.

[✓] PHP Runtime: 8.3.4
[✓] oMLX Server: Connected (http://127.0.0.1:8000)
    ├── Text Model: Qwen2.5-7B-Instruct-4bit (Loaded)
    └── Embedding Model: bge-large-en-v1.5 (Loaded)
[✓] mflux Engine: Available (/usr/local/bin/mflux)
    └── Default Model: FLUX.2-klein-4B
[✓] Spaces Detected: 4 (my_brand, hook_analyzer, cartoon_universe, product_pitch_lab)

6. How Others Can Get Involved

INTENTIO is open-source, built in public, and dedicated to the philosophy of sovereign computing. We believe the future of AI will not belong to a handful of centralized cloud monopolies, but to an open confederation of local, personal, and domain-specific tools that respect the human mind.

There are many ways to participate in this quiet rebellion:

The highest-leverage way to contribute is by authoring domain-specific Packages:

Are you a lawyer? Build a legal research space containing statutory frameworks and compliance audit commands.
Are you a software architect? Build a refactoring auditor loaded with Clean Architecture rules and design pattern guidelines.
Are you a novelist? Create a narrative world-building space with character registries and continuity checkers.
Any directory with Markdown knowledge files, a commands/ folder, and a clean manifest.json can be packaged and shared with the community.

2. Contribute to the Core Engine

The INTENTIO codebase is deliberately clean and accessible. We welcome contributions on:

Advanced Chunking Strategies: Improving semantic boundary detection for codebases, tabular Markdown, and multi-lingual texts.
Vector Index Optimizations: Exploring even faster local search and indexing mechanisms.
Command Tooling: Expanding CLI developer ergonomics, reporting tools, and interactive inspection modes.
Alternative Local Backends: Refining client adapters and keeping pace with Apple MLX innovations.

3. Test and Benchmark Small Language Models

We are in a golden era of open-weights SLMs (Qwen 2.5, Llama 3.2, Gemma 2, Phi-3.5). Help test which quantization profiles and parameter sizes yield the cleanest reasoning inside bounded spaces. Share your findings and benchmark prompt recipes.

4. Star, Discuss, and Advocate

If you believe that individuals should own their intelligence rather than rent it from cloud vendors:

Repository: github.com/melasistema/intentio
Project Website: intentio.melasistema.com
Author & Studio: melasistema.com — Luca Visciola
Release Article: Dropping Ollama on LinkedIn Pulse

Clone the repository, inspect the code, point it at your private notes, and reclaim your digital mind.

Docx to Markdown Converter for Power Users: Why Client-Side Conversion Beats Uploading Your Files

Tue, 06 Oct 2026 15:57:29 +0000

Docx to Markdown Converter for Power Users converts Word .docx files to Markdown entirely inside your browser, so documents are never uploaded, stored or tracked. You can verify it in DevTools: drop a file and watch the Network tab stay quiet. Version 2.0.0 keeps that promise while adding bulk conversion, beta .doc support and a client-built Download All zip.

Docx to Markdown Converter for Power Users makes one claim louder than any other: your file never leaves your device. Developers should distrust that sentence until they can test it. So this post is a threat model, a verification recipe and an honest list of limits.

The release context is on the main post. The architecture argument starts here.

What Is the Threat Model for Document Converters?

Think of a typical online converter. You pick a file, the browser sends it to a server, the server converts it, and you download the result. Three things can go wrong on the way.

In transit. The file crosses the network.
At rest. The server may store it, even briefly, in logs, temp folders or backups.
In use. The operator, or a compromised host, can read it.

For public text this is a non-issue. For client contracts, internal specs, unreleased drafts or anything under NDA, it is the whole issue.

How does client-side conversion remove those risks?

By deleting the server step. The browser reads the file locally, JavaScript parses it, and the result is written back as a download. There is no upload request, so there is nothing to intercept, store or leak.

The libraries doing the work are mammoth.js for .docx parsing, Turndown with the GFM plugin for Markdown output, and JSZip for the zip export. All of them are plain JavaScript that runs in your tab.

How can you verify a Docx to Markdown Converter for Power Users yourself?

Do not take my word for it. Use DevTools.

Open the converter.
Open DevTools, go to the Network tab, and clear the log.
Drop in a harmless test .docx.
Watch the log. A client-side tool should show no outgoing request carrying your file.
Optionally switch the browser to offline mode after the page loads and convert again.

If step 4 or 5 surprises you on any tool, you have learned something useful.

What Does the Docx to Markdown Converter for Power Users Do to Reduce Attack Surface?

On the live site the conversion libraries are self-hosted, and the site's Content-Security-Policy restricts scripts and styles to its own origin. That means the page is not pulling executable code from third-party CDNs while you drop a confidential file onto it.

The drop-in widget version I keep for other pages loads libraries from CDNs instead, because those pages do not share this policy. If you embed it, review that choice for your own context.

Is a Docx to Markdown Converter for Power Users safe for confidential files?

Local processing removes the upload risk, which is the largest one. It does not remove every risk. Browser extensions can read page content. A compromised device is still a compromised device. Treat the tool as one safeguard, not the whole policy.

What are the honest limits?

Fidelity. Legacy .doc files get text-only extraction, labeled as beta.
Scope. The tool maps structure, not visual formatting.
Trust. You can inspect network behavior, but you still depend on the page's code. If your policy demands it, read the script.

Developer Checklist Before You Convert Sensitive Docs

Confirm the tool is client-side with the DevTools test above.
Convert on a trusted device and an up-to-date browser.
Disable unnecessary extensions for the session.
Spot-check output, then store the Markdown where your policy allows.

Key Takeaways

Client-side conversion deletes the upload, storage and operator-access risks.
You can verify the claim yourself in the Network tab.
Self-hosted libraries and a restrictive CSP on the live page reduce third-party exposure.
Limits remain: beta .doc text extraction and structure-only mapping.

Conclusion

Privacy claims deserve tests, not trust. Run the DevTools check, read the OpenPR release if you want the announcement context, and decide for yourself whether the Docx to Markdown Converter for Power Users fits your policy.

FAQ

Does the converter upload my Word files?

No. Conversion runs in your browser with JavaScript on your own device. Nothing is sent to a server, tracked or stored, in single-file or bulk mode. The Download All zip is also built locally, so the full path from file to Markdown stays inside your browser tab.

How can I confirm no upload happens?

Open your browser's DevTools, select the Network tab, clear the log, then drop a harmless test file. A client-side tool should show no request carrying your document. For a second check, switch the browser offline after the page loads and confirm that conversion still works.

What libraries are involved?

mammoth.js parses .docx into HTML, Turndown with the GFM plugin writes Markdown, and JSZip builds the Download All archive. All three are plain JavaScript libraries that run in the browser, which is why no server is involved at any point in the conversion path.

Is client-side conversion always secure?

It removes upload and server-storage risks, but not every risk. Browser extensions, malware or a shared device can still expose files, and you still depend on the page's own code. Treat client-side conversion as one control inside your security policy, not as the whole policy.

Does it work offline?

Yes, after the page and its libraries have loaded. Conversion is local, so it does not need an active connection to run. That also gives you a simple privacy test: if conversion still works with the network switched off, your document is not being sent anywhere.

Why self-host the libraries?

Self-hosting keeps executable code on the site's own origin, which fits a strict Content-Security-Policy and avoids loading scripts from third-party CDNs while you handle confidential files. On the live page, scripts and styles are limited to the site's own origin as a result.

There is no signup, and conversion does not send your documents anywhere or store them. Ordinary site analytics are covered by the site's privacy policy, which is separate from document handling. If your policy requires it, test the Network tab to confirm what the page requests.

Can I embed the converter on my own site?

A drop-in widget version exists that loads its libraries from CDNs instead of self-hosting them. Review that approach against your own Content-Security-Policy and privacy requirements before embedding it, because a restrictive policy may block third-party script sources and need adjusting.

Does bulk conversion change the privacy model?

No. Every file in a batch is processed locally in your browser, and the Download All zip is built there with JSZip, so the batch never touches a server. Bulk mode changes how many files you convert at once, not where the conversion happens.

What about legacy .doc files?

They are accepted as a beta, with text extracted from the raw bytes locally in your browser. Headings, lists and tables are not preserved, and the result is labeled Beta, text only. For full fidelity, resave the file as .docx in Word or LibreOffice first.

Is the tool open to sponsors?

Sponsorship placements on the converter page are open, first come, first served. Use the Sponsored Placements button in the site footer to get in touch. Sponsorship does not change how files are processed, because conversion stays on your device regardless of who sponsors the page.

Is the converter free?

Yes. It is a free Docx to Markdown tool with no signup, no install and no watermark. The privacy model does not depend on payment either, since conversion runs on your own device, and sponsorship placements on the page help cover upkeep without charging the people who use it.

Separate SEO Title Readability from Ranking Rules

Sat, 03 Oct 2026 21:09:27 +0000

When building automated publishing pipelines, developers frequently encounter constraints around metadata lengths. A common rule of thumb dictates that search engine optimization titles should remain under 60 characters to avoid truncation in search engine result pages. Treating this guideline as a strict algorithmic ranking signal often leads to awkward phrasing, keyword stuffing, and convoluted truncation logic that breaks words mid-syllable. In practice, the sixty-character threshold is an editorial scanability convention rather than a hidden ranking penalty. For a related implementation, see Preventing Search Intent Duplicates In Automated.

Separating human readability from platform display rules allows engineering teams to design cleaner metadata normalizers. This article explores the distinction between search engine display limits and ranking signals, explains why rigid truncation creates poor user experiences, and demonstrates how to implement safe whole-word normalization using a robust publishing pipeline function.

The Origin of Metadata Length Constraints

Search engines allocate a specific pixel width for title elements in search result snippets, typically rendering around 50 to 60 characters depending on character widths and device viewports. When a title exceeds this display boundary, interfaces append an ellipsis to signal that additional text was omitted.

Conflating this visual limitation with a ranking factor is a persistent misconception. Search engines parse and index the entire text of a title element regardless of whether the final output is clipped in the browser viewport. The primary reason to keep titles concise is user comprehension and click-through clarity. A reader scanning a list of search results benefits from a clear, focused title that conveys the page topic instantly. When automation clips a title arbitrarily, it risks removing vital context or splitting a compound term.

Trade-offs in Automated Truncation Strategies

Publishing systems that enforce strict length caps must decide how to handle strings that exceed the limit. Naive character-level slicing creates malformed outputs that undermine professional publishing standards.

Consider a naive slicing implementation that cuts a string at exactly 60 characters:

def naive_truncate(title: str) -> str:
    # Cuts abruptly at character index 60, regardless of word boundaries
    return title[:60]

If applied to a descriptive title, this function might return an incomplete phrase like "Understanding Publishing Pipeline Architecture and Metadata Stand". This output looks broken and degrades the reader experience.

An alternative approach is whole-word normalization. Instead of hard-coding a character limit that slices strings arbitrarily, a robust pipeline can measure length for editorial guidance while ensuring that any automated adjustments preserve word boundaries and grammatical integrity.

Implementing Safe Whole-Word Normalization

To manage metadata lengths reliably within a publishing workflow, developers can implement a normalization function that evaluates word boundaries and avoids abrupt cuts. The following Python example demonstrates how to check title length against a target threshold and truncate safely at the nearest word boundary if necessary.

def normalize_title(title: str, max_length: int = 60) -> dict:
    trimmed_title = title.strip()
    is_within_limit = len(trimmed_title) <= max_length
    
    if is_within_limit:
        return {
            "title": trimmed_title,
            "truncated": False,
            "length": len(trimmed_title)
        }
    
    # Find the last space within the maximum length limit
    truncated = trimmed_title[:max_length]
    last_space = truncated.rfind(" ")
    
    if last_space != -1:
        final_title = truncated[:last_space].rstrip()
    else:
        final_title = truncated
        
    return {
        "title": final_title,
        "truncated": True,
        "length": len(final_title)
    }

input_title = "A Comprehensive Guide to Modern Publishing Pipelines and Metadata Normalization Rules"
result = normalize_title(input_title, 60)
print(result)

When executed against a long input string, this function respects word integrity, preventing awkward character splits while supplying structured metadata to the publishing pipeline. For a related implementation, see Preventing Cloudflare Browser Integrity Check Blocking.

Verifying Pipeline Output

Validating that metadata generation works correctly requires testing both short and long inputs against the normalizer. Pipeline tests should verify three specific conditions:

Titles under the target length remain unmodified.
Titles exceeding the target length are reduced cleanly at the nearest word boundary without leaving trailing punctuation or orphan spaces.
The resulting data structure clearly indicates whether truncation occurred so that human editors can review and refine the source string if needed.

By treating title length checks as a diagnostic aid rather than an absolute rule, engineering teams can build resilient systems that support clean typography and clear human reading habits.

Final Architectural Perspective

Distinguishing between editorial readability conventions and algorithmic constraints prevents unnecessary engineering complexity. While search engines utilize display limits to present clean snippets, your publishing pipeline should prioritize structural integrity and whole-word preservation. Implementing safe truncation logic ensures that automated systems assist human editors rather than undermining the quality of published content.

The .docx Era Is Over: Why I Built an Open-Source Letterhead Engine for the Markdown & AI Age

Sat, 19 Sep 2026 16:01:40 +0000

A few weeks ago, in the calm before the storm of autumn client deadlines, I finalized and open-sourced MelaFreelance—a minimal, local-first time-tracking tool born out of sheer frustration with bloated SaaS apps.

Then reality hit. Client projects piled up, life events took over, and my local AI experiments with S-MoE (Sparse Mixture of Experts) got temporarily put on hold while waiting for more disk storage.

If you are a builder or a freelancer, you know the feeling: you are swamped, your terminal is glowing at 1:00 AM, but the itch to solve persistent friction never stops.

Between client deliveries, I found myself repeatedly running into a classic, infuriating problem that almost every freelancer, developer, and technical writer faces today:

Why are we still copy-pasting Markdown into Microsoft Word or Google Docs just to fix a misaligned logo for 25 minutes?

The Modern Dilemma: Markdown Won, but PDFs Didn’t Get the Memo

We live in the AI era. Almost everything we draft today starts as pure text.

Our LLM prompts output clean Markdown.
Our notes live in Obsidian, VS Code, or plain .md files.
We think in hierarchies: # Headers, - Bullet points, and | Clean | Tables |.

Traditional formats like .docx and .pages are increasingly feeling like bloated relics. Yet, the moment we need to send a formal quotation, a statement of work, an invoice, or an architecture report to a client, we fall into the WYSIWYG trap:

You paste your text into Word or Pages.
The logo shifts 3mm to the left for no reason.
The table gives 60% width to a 4-character column.
The footer with your VAT and IBAN shatters across page 3.
You touch a single sentence on page one, and the entire layout collapses.

As I like to put it: The paper is not the song.

A word processor keeps the room and the music in the same file. Every time you tweak the writing, the walls move.

I wanted a system that separates them completely—and refuses to let them back into the same room.

Introducing Mela Letterhead 🍎

Today, I’m open-sourcing another tool from the Melasistema workshop: Mela Letterhead.

👉 Website: letterhead.melasistema.com

👉 GitHub: github.com/melasistema/mela-letterhead

Mela Letterhead takes a plain Markdown document, wraps it in your bespoke, professional letterhead, and compiles it into a pixel-perfect, publication-grade PDF.

No dragging boxes. No fighting with brittle HTML-to-PDF converters. No layout drift.

How It Works: The Separation of Paper and Prose

The philosophy is straightforward:

Describe your paper once: In a single letterhead.yaml file, you configure your brand: your logo or typographic wordmark, your accent colours, your margins, and your banking/legal footer.
Write pure content: Your quotation.md or report.md contains only text and metadata (Date, Reference, Client). Zero layout code.
Typeset with Pandoc + Typst: Mela Letterhead resolves lengths into points, maps languages, and hands the document to Typst—the modern, ultra-fast typesetting engine that is replacing LaTeX.

The layout is genuinely page-aware:

Page 1: Full header band with your logo, date, and document metadata.
Inner Pages: Clean, minimal running header.
Last Page: Your complete legal and banking footer (IBAN, VAT, contact info).

Three Ways to Make It Yours

Not everyone has a corporate brand book, and you don’t need one:

The Classic Brand: Drop your logo.svg or logo.png into the assets folder. Mela Letterhead handles sizing and placement identically across every document you’ll ever print.
The Typographic Wordmark: Don’t have a logo? Remove it. The tool automatically typesets your name with editorial typography and tracking. Perfect for solo consultants and creators.
The Pre-Printed Sheet: Already have stationery designed by a graphic designer or printer? Tell the tool to use your background artwork and let Typst flow the text precisely inside your margins.

It runs locally with Python 3.9+, requires only one dependency (PyYAML), and operates via three clean commands: init, check, and build.

Building Melasistema in the Open

From MelaFreelance (tracking time without subscription fatigue) to Mela Letterhead (shipping professional documents without WYSIWYG frustration), the goal behind Melasistema is simple:

Build robust, local-first, open-source tools that give freelancers and independent builders their time back.

Even when client work is overwhelming and large AI experiments like S-MoE are waiting on hardware space, releasing these practical utilities keeps the maker spirit alive.

If you write in Markdown and care about how your work looks when it lands on a client’s desk, give Mela Letterhead a spin.

⭐️ Star the project on GitHub: github.com/melasistema/mela-letterhead
🌐 Explore the live preview: letterhead.melasistema.com
🔔 Follow Melasistema to follow upcoming open-source releases and AI tooling experiments.

I’d love to hear your thoughts: How are you currently turning your Markdown drafts into client-facing PDFs?

Free online Markdown editor with built-in cheatsheet

Thu, 14 May 2026 17:32:20 +0000

As someone who writes docs and takes notes frequently, I believe Markdown is one of the best ways to display documents, especially complex ones, and writing Markdown is also fun. But… sometimes I forget the syntax. Especially as I get older, my mind no longer serves me well lol.

Sometimes I had to jump between the editor and the cheatsheet, copying and pasting repeatedly. Sounds boring, huh? :/

So I ended up building a tool myself where the cheatsheet sits right below the editor, so I no longer have to jump around. Every syntax example can be added to the editor with just one click.

Check it out if interested:
https://catssaymeow.org/editor/

mdparser: a native CommonMark + GFM parser for PHP

Fri, 08 May 2026 12:49:49 +0000

Several of my projects do heavy markdown parsing. Comment rendering, documentation pipelines, content management. The volume keeps growing, and I've been hitting the point where pure-PHP parsers (Parsedown, league/commonmark, cebe/markdown, michelf) just can't keep up. They're solid libraries, but parsing thousands of documents per request or chewing through 200 KB files in interpreted PHP is slow no matter how well the code is written.

I wanted something 10x+ faster that could serve as a drop-in replacement for the common cases. The result is mdparser, a native C extension that wraps cmark-gfm (GitHub's CommonMark parser) and exposes it through a clean PHP 8.3+ OO API. I'm releasing it today.

How it works

mdparser vendors a copy of cmark-gfm 0.29.0.gfm.13 directly into the extension's shared object. No external library to link against, no cmake, no runtime dependencies. The entire cmark-gfm codebase compiles alongside the PHP wrapper into a single .so (or .dll on Windows). Four cherry-picked commits from cmark upstream close the 0.29-to-0.31 spec gap, giving full CommonMark 0.31 conformance: 652 out of 652 spec examples pass.

The PHP API is intentionally small. Two classes, one exception:

use MdParser\Parser;
use MdParser\Options;

// Defaults: safe mode on, GFM extensions on.
$parser = new Parser();
echo $parser->toHtml('# Hello');

// Or the static shorthand:
echo Parser::html('# Hello');

// Custom options via named arguments:
$parser = new Parser(new Options(
 smart: true,
 footnotes: true,
 sourcepos: true,
));

// Three output formats:
$html = $parser->toHtml($markdown);
$xml = $parser->toXml($markdown);
$ast = $parser->toAst($markdown); // nested PHP arrays

Options is final readonly with 17 boolean fields. The Parser constructor translates those bools into cmark's internal bitmask once, so every subsequent parse call is pure cmark work with zero per-call overhead. Static factory presets (Options::strict(), Options::github(), Options::permissive()) cover common deployment patterns.

If you're migrating from Parsedown's line() or cebe/markdown's parseParagraph(), there's toInlineHtml(): inline-only HTML without the wrapping <p> tags. Useful for chat messages, table cells, and short user-facing strings.

Performance

This was the primary motivation. Measured on PHP 8.4 with each parser in its default configuration:

Parser	Small (200 B)	Medium (1.8 KB)	Large (200 KB)
mdparser	30,447 ops/s	5,697 ops/s	105 ops/s
Parsedown	1,651 ops/s (18x slower)	325 ops/s (17x)	6 ops/s (17x)
cebe/markdown (GFM)	1,350 ops/s (22x)	374 ops/s (15x)	6 ops/s (16x)
michelf (Extra)	1,006 ops/s (30x)	209 ops/s (27x)	5 ops/s (19x)

15-30x faster, from 200-byte chat messages to 200 KB documents. Your absolute numbers will differ by hardware, but the ratios hold. mdparser processes roughly 100 full CommonMark-spec-sized documents per second on a single core. The pure-PHP parsers manage 5-6.

The benchmark uses hrtime(true) around each parse call, 200 iterations with warm-up, trimmed mean to filter GC pauses. Reproducible scripts are in the bench/ directory.

Feature comparison

mdparser covers CommonMark core plus all five GFM extensions. Here's how it stacks up against the pure-PHP alternatives:

Feature	mdparser	Parsedown	league/cm	cebe GFM	michelf Extra
CommonMark core	full	partial	full	partial	partial
GFM tables	yes	yes	via ext	yes	via Extra
Strikethrough	yes	yes	via ext	yes	no
Task lists	yes	no	via ext	no	no
Autolinks	yes	yes	via ext	yes	no
Tag filter	yes	yes	via ext	partial	no
Smart punctuation	yes	no	via ext	no	no
Footnotes	yes	Extra	via ext	no	yes
Sourcepos	yes	no	yes	no	no
XML output	yes	no	no	no	no
AST output	yes (arrays)	no	yes (objects)	no	no

What mdparser doesn't do

mdparser is scoped to what cmark-gfm supports: CommonMark core plus five GFM extensions. It doesn't cover definition lists, abbreviations, attribute syntax, heading permalinks, table of contents, YAML front matter, mentions, LaTeX math, emoji shortcodes, or custom containers. If you need those, league/commonmark is the right choice. It's the most featureful pure-PHP option and actively maintained. Speed doesn't help if the feature you need isn't there.

Compatibility

mdparser builds and tests on PHP 8.3, 8.4, and 8.5 across Linux (x86_64), macOS (arm64/x86_64), and Windows (x86/x64, both TS and NTS). CI runs on all three platforms, with an ASAN job on Linux to catch memory issues. Pre-built Windows DLLs ship with each GitHub release.

Installation

pie install iliaal/mdparser

PIE handles the download, phpize, configure, make, and install. On a minimal PHP image you'll need git, bison, and libtool-bin as build dependencies.

From source:

git clone https://github.com/iliaal/mdparser.git
cd mdparser
phpize && ./configure --enable-mdparser
make -j && sudo make install

What if a rope data structure used p-adic geometry?

Mon, 20 Apr 2026 13:59:34 +0000

I was building a markdown editor for my platform StringTechHub. At some point I needed to decide how to represent the document internally. I could use a plain string, a gap buffer, or a standard rope. Instead I asked a different question: can number theory give us a better way to organize text than size-balanced trees?

This post is about what that means, what I built, what I measured, and what I learned.

THE PROBLEM WITH STANDARD APPROACHES

A plain string is simple but expensive. Every insert at position i requires shifting all characters after i — O(n) per edit. For a 30,000 character document that becomes noticeable.

A rope solves this by splitting the document into chunks stored in a binary tree. Insert and delete become O(log n) because you only touch the path from root to the affected leaf. Editors like Zed and Helix use rope-based structures internally for this reason.

Standard ropes balance by size — keep subtree weights roughly equal, keep the tree shallow. The size-balancing heuristic is correct but blind. It knows nothing about what the text means. A paragraph and a code block of identical byte length are indistinguishable to a standard rope. I wanted the tree to know the difference.

WHAT P-ADIC NUMBERS ARE

The 2-adic valuation v₂(n) counts how many times 2 divides n:

v₂(8) = 3, because 8 = 2³

v₂(12) = 2, because 12 = 4 × 3

v₂(7) = 0, because 7 is odd

In the 2-adic metric, two numbers are close when their difference is highly divisible by 2. This is a different notion of proximity than the real number line — one based on arithmetic structure rather than magnitude.

The question: what happens when you use this arithmetic structure to decide which nodes in a rope tree should merge together?

THE CORE IDEA

In a standard rope, rebalancing collects all leaf nodes and rebuilds by splitting arrays in half — purely by position. In a p-adic rope, rebalancing collects all leaf nodes and rebuilds by greedily fusing chunks that fit well arithmetically — merging adjacent nodes whose combined size has the highest 2-adic valuation first.

If two adjacent leaves have sizes 174 and 46, their combined size is 220. v₂(220) = 2. If two other adjacent leaves have sizes 171 and 16, their combined size is 187. v₂(187) = 0. The first pair merges first.

The rebuild uses a max-heap ordered by merge score, so the highest valuation pairs always merge first. For p=2, the valuation is a single CPU instruction:

fn valuation(n: usize) -> usize {
    if n == 0 { return usize::MAX; }
    n.trailing_zeros() as usize
}

The result: a tree where subtrees reflect arithmetic affinity between block sizes — not just positional proximity. Certain subtrees become deeper or shallower depending on number-theoretic structure, not size alone.

WHAT I BUILT

The data structure has two node types. Internal nodes are lightweight — they store weight, total size, valuation, cached depth, and two child pointers. No content, no metadata. Leaf nodes are rich — they store raw text, a parsed block from the document parser, a dirty flag, and an AST cache.

pub struct InternalNode {
    pub weight: usize,
    pub total: usize,
    pub valuation: usize,
    pub depth: usize,
    pub left: Box<Node>,
    pub right: Box<Node>,
}

pub struct LeafNode {
    pub text: String,
    pub block: RefCell<Block>,
    pub dirty: Cell<bool>,
    pub ast_cache: RefCell<Option<Block>>,
}

Each leaf corresponds to exactly one semantic block. A heading is one leaf. A paragraph is one leaf. A code block including all indented lines is one leaf. Split operations snap to block boundaries — the rope never cuts mid-paragraph.

The depth cap guarantees O(log n) worst case: max_depth = 2.0 × log₂(total). After every concat, depth is checked. If it exceeds the cap, p-adic rebuild runs. If that still violates the cap, strict size-balanced fallback runs. The guarantee always holds.

THE SEMANTIC EVOLUTION

While building I noticed something: lists and paragraphs have fundamentally different natural groupings. A paragraph is continuous prose — binary splitting fits naturally. An unordered list is a collection of discrete items — ternary grouping fits better.

So I made the prime adaptive:

fn block_prime(node: &Node) -> usize {
    match node {
        Node::Leaf(leaf) => match &leaf.block.borrow().kind {
            BlockKind::UnorderedList |
            BlockKind::OrderedList => 3,
            _ => 2,
        },
        Node::Internal(_) => 2,
    }
}

fn merge_score(left: &Node, right: &Node) -> usize {
    let total = left.total() + right.total();
    let p = block_prime(left).max(block_prime(right));
    valuation_p(total, p)
}

This is where the idea became more interesting: the prime is no longer fixed — it depends on the content. The math adapts to document structure. This is no longer purely p-adic. It is a mathematically inspired adaptive heuristic. I think that is more interesting than mathematical purity, and more honest than pretending the original idea was perfect.

THE CUSTOM DSL

The editor uses a command-based markup language. Every block starts with a dollar-sign command at column zero. Everything indented below belongs to the same block. A new block begins when a $ appears at column zero.

BLOCK COMMANDS
$H1 - heading text

$H2 - heading text

$H3 - heading text

$H4 - heading text

$P - paragraph text

$B - bold block

$I - italic block

$BI - bold italic block

$ST - strikethrough block

$HR

$BQ quote content here -- attribution

$CODE rust fn main() { println!("hello"); }

$UL item one item two item three

$OL first item second item

$IMG - alt text | https://url.com/image.png
$LINK - label text | https://url.com

$FN - footnote content

$TOC

$TB | Header 1 | Header 2 | Header 3 | |----------|----------|----------| | cell | cell | cell | | cell | cell | cell |

Tables are scaffolded automatically. Type $TB and press Enter — the editor generates the header row, separator row, and data rows. Tab moves between cells, Shift+Tab moves back. For custom tables, $TB COLS|ROWS then click enter (ex: $TB 3|3).

INLINE COMMANDS
Inline formatting uses quoted commands anywhere inside block content:

"$I - italic text"

"$B - bold text"

"$BI - bold italic"

"$ST - strikethrough"

ESCAPE
To write a literal dollar sign command without it being parsed in inline:

"!$B" - this renders as plain text, not bold

To write literal quotes inside inline content:

"!!this has literal quotes inside"

The explicit $ prefix at column zero makes block boundary detection trivial and unambiguous. No context-sensitive parsing, no lookahead, no ambiguity. This is why the rope can snap splits to block boundaries cleanly — the boundary is always a $ at column zero.

WHAT THE MEASUREMENTS SHOWED

I built a baseline using standard size-balanced rebuild and ran both on the same document.

Size-balanced baseline: depth 6, total internal nodes 27

valuation distribution: flat, stops at v₂=4

P-adic rope after operations:

depth 9-13, total internal nodes 1528 valuation distribution: geometric decay

v₂=0 → 594 nodes

v₂=1 → 505 nodes

v₂=2 → 240 nodes

v₂=3 → 114 nodes

v₂=4 → 49 nodes

v₂=5 → 19 nodes

v₂=6 → 5 nodes

v₂=7 → 2 nodes

The geometric decay is not accidental. In any distribution of natural numbers, roughly half are odd (v₂=0), a quarter divisible by 2 but not 4 (v₂=1), an eighth by 4 but not 8 (v₂=2), and so on. The histogram follows this pattern exactly — the p-adic rebuild is genuinely organizing nodes by number-theoretic properties. This suggests the structure is not arbitrary — it reflects inherent arithmetic distribution.

The size-balanced tree has no such structure. Its valuation distribution is flat and arbitrary.

Rebalance cost: 17µs for a real document.

1000 inserts: 46ms total, 0.046ms per insert.

I have not yet benchmarked against a production rope implementation like ropey. That is the honest next step. Whether p-adic balancing produces faster trees than size-balanced in real editor workloads is an open question. The tree shapes are measurably different. Whether different is better in practice I cannot yet claim.

THE EDITOR

The parser compiles to WASM via wasm-pack. The editor is a split-pane textarea with live preview. The rope sits between the parser and the renderer.

Each leaf caches its parsed block. Dirty flags mark which leaves need re-parsing after edits. Only dirty leaves get re-parsed on each update — re-parse cost is O(block size) not O(document size). For a 30,000 character document with a 200-character paragraph being edited, only those 200 characters get re-parsed.

Currently the textarea is the source of truth and the rope is rebuilt from it on each debounce. Making the rope the primary source of truth — intercepting every keystroke and updating incrementally — is the next step. The infrastructure is there. The wiring is not complete.

HONEST ASSESSMENT

What works:

P-adic rebuild produces measurably different tree structure from size-balanced
Geometric decay in valuation histogram is real and mathematically explainable
Semantic block-prime scoring connects math to document structure
Dirty flag incremental parsing is implemented and correct
Depth cap guarantee holds under adversarial input
```
46ms for 1000 inserts on a real document
```
Compiles to WASM, runs in browser, handles 30k character documents without lag

What does not work yet:

Rope is not the source of truth — full rebuild on each debounce
True incremental updates not wired end to end
No undo/redo
No benchmark against production rope implementations

WHAT I LEARNED

The most interesting discovery was not the math. It was that the prime should depend on the content type. The moment I realized lists have a natural ternary structure and paragraphs have a natural binary structure — the math stopped being a curiosity and started being a design tool.

The second thing: building something real with an idea is the only way to find out if the idea works. I could have written about p-adic ropes. Instead I built one and wired it into an editor. The measurements are more honest than the theory.

The open question: does p-adic balancing actually improve real editor workloads, or does it just produce different trees? I do not know yet. That is what makes it worth continuing.

Code: github

Note: Early-stage prototype. Core ideas are implemented and tested; editor integration and features are still in progress.

Blazing Fast @m2d/react-markdown

Sat, 12 Jul 2025 07:02:32 +0000

We just benchmarked @m2d/react-markdown against the popular react-markdown — and the results are in:

✅ Competitive speed,
✅ Cleaner architecture,
✅ Purpose-built for MDAST-first workflows like mdast2docx

Why Another Markdown Renderer?

Most renderers are great at one thing: rendering. But if you’re working on docx/pdf export, hybrid output (MDX/HTML/JSX), or unified pipelines, you need something:

Fast
Extensible
MDAST-respecting
SSR/Streaming/Edge-ready

That's exactly what @m2d/react-markdown is for.

Real Benchmarks — No Hype

We ran thorough benchmarks with various markdown types: simple notes, complex nested GFM, large tutorials, and even full-site markdown dumps.

Key Takeaways:

@m2d/react-markdown outperformed or matched react-markdown in several medium/complex files
Bulk rendering (all files in one go) saw better JSX tree handling
Slightly slower in very short/simple cases (which don't matter much in real apps)

Check out the full results here:
benchmark.md

Includes tables, deltas, and even visual charts!

Perfect Companion for `mdast2docx` & Export Tooling

If you're building tools like:

mdast2docx (Markdown → Word)
Hybrid export systems (PDF/HTML from a single source)
Local-first writing tools with output control

Then @m2d/react-markdown is your new best friend.
It retains the full MDAST, supports plugin injection, and gives you full control over rendering + export paths.

Join the Discussion – Shape the Future

We’re actively planning support for:

Inline JSX support in markdown
Better handling of reusable ASTs
Declarative hydration markers for SSR/Edge use

Engage, vote, or suggest improvements here:
https://github.com/md2docx/react-markdown/discussions/3

Build Your Own Library Like This

This library was scaffolded using react18-tools/turborepo-template — a production-grade template for building and publishing modern React libraries.

If you want to:

Build & test across Next.js/Vite
Auto-generate docs & examples
Publish fast and right

Use this template to create your own library in minutes.

Call for Contributors

If you:

Love performance and clean architecture
Use React with Markdown in any serious way
Care about maintainable DX and OSS karma

…then jump in!

Star, fork, or file issues here → https://github.com/md2docx/react-markdown

Or explore mdast2docx to see how this library integrates into real export workflows.

♂️ Built with Care

This isn’t just a library — it’s a piece in a larger mission to simplify dev workflows and bridge content with output in meaningful ways.

Beginner’s Guide to GitHub-Flavoured Markdown

Mon, 02 Jun 2025 16:16:33 +0000

Beginner’s Guide to GitHub-Flavoured Markdown

CoderLegion's markdown has limited rendering features and has no syntax highlighting, consult original post for more: https://wiki.methodox.io/en/KnowledgeBase/Markdown

1. Introduction

1.1 Why Markdown Rocks ✨

Markdown is plain text with super-powers. It lets you jot notes, write docs, craft blog posts, even format PDFs - all without leaving the comfort of your favourite text editor.

Human-friendly – readable in raw form, so your future self (and collaborators) can skim it in any terminal.
Portable – works on GitHub, GitLab, Stack Overflow, Jira, Notion, countless CMSes and static-site generators.
Speedy – no buttons or WYSIWYG mysteries; just type.
Version-control bliss – diffs stay clean because it’s plain text.

1.2 Where You’ll Meet Markdown

README files, issue & PR templates on GitHub.
Technical blogs (Jekyll, Hugo, Astro, etc.).
Docs sites (Docsify, MkDocs, Docusaurus).
Note-taking apps (Obsidian, Logseq, Typora).
Chat & community tools (Telegram, Discord, Slack, Discourse).

1.3 Little Wonders You Can Do

Markdown’s magic is that every one of those tricks is still perfectly legible in raw text.

(CoderLegion's markdown has limited rendering features and has no syntax highlighting, consult original post)

2 · Quick Reference (Cheat Sheet)

Tip: Try every sample in a .md file on GitHub and hit Preview.

2.1 Headings

# H1
## H2
### H3

Rendered ⇒

peek

# H1 ## H2 ### H3

2.2 Emphasis

*italic*   _italic_
**bold**   __bold__
~~strike~~

italic bold ~~strike~~

2.3 Lists

Unordered

- Item A
  - Sub-item
* Asterisks work too

Item A
- Sub-item

Asterisks work too

Ordered

1. First
2. Second

First
Second

2.4 Links

[visible text](https://example.com)
<https://example.com>   <!-- autolink -->

visible text
https://example.com

2.5 Images

![Alt text](https://picsum.photos/200/300)

2.6 Code

Inline

`code` → code

Fenced (with highlight)

```js
function greet() {
  console.log("Hello!");
}
```

2.7 Blockquotes

> One level
>> Nested wisdom

One level

Nested wisdom

2.8 Horizontal Rule (Divider)

(CoderLegion has issue display this)

2.9 Tables

| Col A | Col B |
|-------|-------|
|  1    |  2    |
|  3    |  4    |

Col A	Col B
1	2
3	4

2.10 Task Lists

- [ ] Walk dog
- [x] Write guide

[ ] Walk dog
[x] Write guide

2.11 Emoji

:rocket: :sparkles: :100:

✨

2.12 Strikethrough

~~obsolete~~ now shiny

~~obsolete~~ now shiny

2.13 Inline HTML (Collapsible)

<details>
<summary>Click me</summary>
Surprise! 
</details>

Click me

Surprise!

2.14 Escaping Characters

Need a literal *? Use backslash:

\*not italic\*

*not italic*

2.15 Footnotes

(This feature is not supported on CoderLegion)

Markdown is handy.[^1]

[^1]: And footnotes are too!

Markdown is handy.[^1]

[^1]: And footnotes are too!

That’s a Wrap!

You now wield the essentials of GitHub-flavoured Markdown. Keep this cheat-sheet nearby, and soon you’ll be dashing off beautifully formatted docs at lightspeed. Happy writing!

Explore More️

To truly master Markdown, you should combine it with features from some foundational languages like HTML and CSS, and utilize additional extensions. See Charles' cool demo for some additional features:

HTML
CSS
LaTeX
Mermaid
JavaScript

Notice those features may not be ubiquitously supported depending on the renderer.

References

Adam Pritchard's Markdown Cheatsheet.
Charles Zhang's Markdown is Cool demo.
The super power markup converter tool Pandoc.

Learn Markdown from best and free resources

Tue, 16 Apr 2024 08:24:34 +0000

Learn Markdown for free

What is Markdown?

If you search Markdown on Google you will see this info Markdown is a lightweight, simple, easy to read and easy to write markup language for creating formatted text using a plain-text editor. John Gruber and Aaron Swartz created Markdown in 2004 as a markup language that is appealing to human readers in its source code form.

Which big companies are using markdown?

1310 companies reportedly use Markdown in their tech stacks including Reddit, StackShare, GitHub ,DEV community and much more.

In simple words “Markdown is a text-to-HTML conversion tool for web writers”.

According to me

markdown is a little bit similar to HTML but it doesn’t have lot’s of fancy tags, It has limited tags but useful tags which is enough for a web page. Is easy to read and write because of fewer tags and syntax.

I have learned Markdown from Scrimba.com

Now if you interested and ready to understand and learn Markdown these are the list of some great and FREE resources.

Free Markdown course by Scrimba

Scrimba is a code learning platform it has a great learning combination of video lectures and code. And they have created a free course of Markdown.

https://scrimba.com/learn/markdownblog

Jump to the course

Markdown crash course by Brad Traversy

Brad Traversy has been programming for around 12 years and teaching for almost 5 years. He is the owner of Traversy Media which is a successful web development YouTube channel with over 1M+ subscription. Check out his free Markdown crash course.

From YouTube Traversy Media

Free Markdown editor(HackMD)

HackMd is a free and online markdown editor which is very easy and simple. Even I also understand markdown from this platform If you guy knows a little bit of HTML and you don’t want to waste your valuable time by watching lengthy video tutorials then I personally recommend this platform.

Jump to the Platform

What is markdown?

Markdown is a lightweight, simple, easy to read and easy to write markup language for creating formatted text using a plain-text editor. John Gruber and Aaron Swartz created Markdown in 2004 as a markup language that is appealing to human readers in its source code form.

How Markdown works?

Markdown code is very easy to understand, to write markup language which is much fast to compile(convert) his code to HTML markup.

Markdown how to add image?

code to add image in markdown
example: ![Alt text](image source)

Markdown how to bold?

Just add ** double star from starting and end of the text like this
**my bold text**

Navigation menu with flexbox

Conclusion

So the final goal of this post to aware our community of how Markdown is covering the IT industry and in the first section of this post we have talked about the big industry leaders are already added Markdown to their stack list. I personally recommend you to grab Markdown language.

Coder Legion - Recent posts tagged markdown

Markdown without a back door:

…

Your account is locked

headings

Deterministic Formatting Normalization

Understanding the Markdown Formatting Failure

Implementation Trade-Offs

Verification Checklist

Preserve Captions in Markdown Publishing

Standard Markdown does not give you a universal caption node

The greedy whitespace bug

Prefer an AST when transforms become important

Contextual links should preserve an existing phrase

Score candidate phrases instead of replacing tokens

Never link inside code, image syntax, or an existing link

Link insertion should be idempotent

Separate editorial transformation from privacy validation

Verify the rendered result, not only the source

Execution Checklist

INTENTIO - Framework

INTENTIO: Reclaiming the Digital Mind with PHP, Small Language Models, and Absolute Data Sovereignty

1. The Story Behind INTENTIO: The Quiet Rebellion

The Illusion of the Cloud Oracle

The PHP Anomaly: Why Write a Cognitive Engine in PHP?

The Evolution: Dropping Ollama in INTENTIO 0.3.0

2. How INTENTIO Works: The Cognitive Architecture

Step 1: The Filesystem as a Semantic Map

Step 2: Ingestion & Fast Batched Embeddings

Step 3: Grounded Retrieval Without Hallucination

Step 4: Declarative Command Templates

Step 5: Native Token Streaming

Step 6: On-Demand, Reference-Grounded Visuals with mflux

3. Key Features

4. The Ecosystem in Action: Ready-Made Packages

1. Hook Analyzer (hook_analyzer)

2. Cartoon Universe (cartoon_universe)

3. Product Pitch Lab (product_pitch_lab)

5. Technical Requirements & Configuration

System Prerequisites

Quick Verification

6. How Others Can Get Involved

1. Build and Share Packages

2. Contribute to the Core Engine

3. Test and Benchmark Small Language Models

4. Star, Discuss, and Advocate

Docx to Markdown Converter for Power Users: Why Client-Side Conversion Beats Uploading Your Files

What Is the Threat Model for Document Converters?

How does client-side conversion remove those risks?

How can you verify a Docx to Markdown Converter for Power Users yourself?

What Does the Docx to Markdown Converter for Power Users Do to Reduce Attack Surface?

Is a Docx to Markdown Converter for Power Users safe for confidential files?

What are the honest limits?

Developer Checklist Before You Convert Sensitive Docs

Key Takeaways

Conclusion

FAQ

Does the converter upload my Word files?

How can I confirm no upload happens?

What libraries are involved?

Is client-side conversion always secure?

Does it work offline?

Why self-host the libraries?

Is there any signup or tracking?

Can I embed the converter on my own site?

Does bulk conversion change the privacy model?

What about legacy .doc files?

Is the tool open to sponsors?

Is the converter free?

Separate SEO Title Readability from Ranking Rules

The Origin of Metadata Length Constraints

Trade-offs in Automated Truncation Strategies

Implementing Safe Whole-Word Normalization

Verifying Pipeline Output

Final Architectural Perspective

The .docx Era Is Over: Why I Built an Open-Source Letterhead Engine for the Markdown & AI Age

The Modern Dilemma: Markdown Won, but PDFs Didn’t Get the Memo

Introducing Mela Letterhead 🍎

How It Works: The Separation of Paper and Prose

Three Ways to Make It Yours

Step 6: On-Demand, Reference-Grounded Visuals with `mflux`

1. Hook Analyzer (`hook_analyzer`)

2. Cartoon Universe (`cartoon_universe`)

3. Product Pitch Lab (`product_pitch_lab`)

Perfect Companion for `mdast2docx` & Export Tooling