mdquiz 0.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-PRESENT Aleksander Fidelus <https://github.com/FidelusAleksander>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# mdquiz
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![bundle][bundle-src]][bundle-href]
+[![License][license-src]][license-href]
+
+Parse markdown quiz files into structured objects. Supports YAML frontmatter, checkbox answers, code blocks, and hint blockquotes.
+
+## Install
+
+```bash
+npm install mdquiz
+```
+
+## Usage
+
+### Parse a single file
+
+```ts
+import { readFileSync } from 'node:fs'
+import { parseQuestionFile } from 'mdquiz'
+
+const md = readFileSync('question-001.md', 'utf-8')
+const question = parseQuestionFile(md, 'question-001')
+
+console.log(question.question) // "Which syntax defines a job?"
+console.log(question.answers) // [{ id: 'a1', text: '...', isCorrect: true }, ...]
+console.log(question.isMultiSelect) // false
+console.log(question.hint) // "https://docs.github.com/..."
+```
+
+### Parse a directory
+
+```ts
+import { parseDirectory } from 'mdquiz'
+
+const questions = parseDirectory('./questions', {
+  filePrefix: 'question-', // only parse files starting with this prefix
+  recursive: false, // walk subdirectories (default: false)
+})
+```
+
+## Markdown Format
+
+```markdown
+---
+question: "Which GitHub Actions syntax correctly defines a job that runs on Ubuntu?"
+---
+
+> https://docs.github.com/en/actions/using-workflows
+
+- [x] `runs-on: ubuntu-latest`
+- [ ] `os: ubuntu-latest`
+- [ ] `platform: ubuntu-latest`
+- [ ] `environment: ubuntu-latest`
+```
+
+Only the `question` field is required in frontmatter. Any additional fields you include (e.g. `title`, `category`, `difficulty`) are accessible via `question.frontmatter`:
+
+```markdown
+---
+question: "What is a pull request?"
+difficulty: easy
+tags: ["git", "collaboration"]
+---
+```
+
+### Structure
+
+| Section | Required | Description |
+|---------|----------|-------------|
+| Frontmatter | Yes | YAML with `question` field (and any custom fields) |
+| Blockquote | No | Hint text or URL (lines starting with `>`) |
+| Code block | No | Context code shown before answers |
+| Answers | Yes | Checkbox list: `- [x]` correct, `- [ ]` incorrect |
+
+### Answer formats
+
+Both ordered and unordered lists work:
+
+```markdown
+- [x] Correct answer
+- [ ] Wrong answer
+
+1. [x] Correct answer
+1. [ ] Wrong answer
+```
+
+Multiple `[x]` marks make the question multi-select automatically.
+
+## API
+
+### `parseQuestionFile(content: string, id: string): Question`
+
+Parse a markdown string into a Question object.
+
+### `parseDirectory(dir: string, options?: ParseDirOptions): Question[]`
+
+Parse all `.md` files in a directory. Skips files starting with `_`.
+
+### Types
+
+```ts
+interface Question {
+  id: string
+  question: string
+  answers: AnswerOption[]
+  isMultiSelect: boolean
+  hint?: string
+  codeBlock?: string
+  frontmatter: Record<string, unknown>
+}
+
+interface AnswerOption {
+  id: string
+  text: string
+  isCorrect: boolean
+}
+
+interface ParseDirOptions {
+  recursive?: boolean
+  filePrefix?: string
+}
+```
+
+## License
+
+[MIT](./LICENSE.md) License
+
+
+[npm-version-src]: https://img.shields.io/npm/v/mdquiz?style=flat&colorA=080f12&colorB=1fa669
+[npm-version-href]: https://npmjs.com/package/mdquiz
+[npm-downloads-src]: https://img.shields.io/npm/dm/mdquiz?style=flat&colorA=080f12&colorB=1fa669
+[npm-downloads-href]: https://npmjs.com/package/mdquiz
+[bundle-src]: https://img.shields.io/bundlephobia/minzip/mdquiz?style=flat&colorA=080f12&colorB=1fa669&label=minzip
+[bundle-href]: https://bundlephobia.com/result?p=mdquiz
+[license-src]: https://img.shields.io/github/license/FidelusAleksander/mdquiz.svg?style=flat&colorA=080f12&colorB=1fa669
+[license-href]: https://github.com/FidelusAleksander/mdquiz/blob/main/LICENSE.md

package/dist/index.d.mts

@@ -0,0 +1,59 @@
+//#region src/types.d.ts
+/** A single answer option */
+interface AnswerOption {
+  id: string;
+  text: string;
+  isCorrect: boolean;
+}
+/** A parsed quiz question */
+interface Question {
+  /** Unique identifier derived from filename */
+  id: string;
+  /** The question text (from frontmatter) */
+  question: string;
+  /** Available answers */
+  answers: AnswerOption[];
+  /** Whether multiple answers are correct */
+  isMultiSelect: boolean;
+  /** Optional hint URL or text (from blockquote before answers) */
+  hint?: string;
+  /** Optional code block shown before answers (question context) */
+  codeBlock?: string;
+  /** All frontmatter fields (title, question, and any custom fields) */
+  frontmatter: Record<string, unknown>;
+}
+//#endregion
+//#region src/loader.d.ts
+interface ParseDirOptions {
+  /** Walk subdirectories recursively. Default: false */
+  recursive?: boolean;
+  /** Glob-like prefix filter for filenames. Default: none (all .md files) */
+  filePrefix?: string;
+}
+/**
+ * Parse all markdown question files in a directory.
+ *
+ * Each .md file is parsed via `parseQuestionFile`. The filename (without
+ * extension) becomes the question ID.
+ *
+ * @param dir - Path to directory containing .md files
+ * @param options - Optional config for recursion and filtering
+ * @returns Array of parsed questions
+ */
+declare function parseDirectory(dir: string, options?: ParseDirOptions): Question[];
+//#endregion
+//#region src/parser.d.ts
+
+/**
+ * Parse a markdown string into a Question object.
+ *
+ * Expected format: YAML frontmatter with a `question` field,
+ * followed by optional hints (blockquotes), optional code blocks,
+ * and checkbox-list answers (`- [x]` or `- [ ]`).
+ *
+ * @param content - Raw markdown string
+ * @param id - Unique identifier for this question (e.g. derived from filename)
+ */
+declare function parseQuestionFile(content: string, id: string): Question;
+//#endregion
+export { type AnswerOption, type ParseDirOptions, type Question, parseDirectory, parseQuestionFile };

package/dist/index.mjs

@@ -0,0 +1,138 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import matter from "gray-matter";
+
+//#region src/parser.ts
+/** Matches an answer line: `- [x] text` or `1. [x] text` */
+const ANSWER_RE = /^(?:\d+\.|-) \[([x ])\] (.*)$/i;
+/** Matches a blockquote line */
+const BLOCKQUOTE_RE = /^> ?(.*)$/;
+/** Matches a code fence open/close */
+const FENCE_RE = /^```/;
+/**
+* Parse a markdown string into a Question object.
+*
+* Expected format: YAML frontmatter with a `question` field,
+* followed by optional hints (blockquotes), optional code blocks,
+* and checkbox-list answers (`- [x]` or `- [ ]`).
+*
+* @param content - Raw markdown string
+* @param id - Unique identifier for this question (e.g. derived from filename)
+*/
+function parseQuestionFile(content, id) {
+	const { data, content: body } = matter(content);
+	const questionText = data.question;
+	if (!questionText) throw new Error(`Missing 'question' in frontmatter for ${id}`);
+	const lines = body.split("\n");
+	const answerStarts = [];
+	let inFence = false;
+	for (let i = 0; i < lines.length; i++) {
+		if (FENCE_RE.test(lines[i])) {
+			inFence = !inFence;
+			continue;
+		}
+		if (!inFence && ANSWER_RE.test(lines[i])) answerStarts.push(i);
+	}
+	if (answerStarts.length === 0) throw new Error(`No answers found in ${id}`);
+	const preambleLines = lines.slice(0, answerStarts[0]);
+	let hint;
+	const codeBlockLines = [];
+	let inPreambleFence = false;
+	for (const line of preambleLines) {
+		if (FENCE_RE.test(line)) {
+			inPreambleFence = !inPreambleFence;
+			codeBlockLines.push(line);
+			continue;
+		}
+		if (inPreambleFence) {
+			codeBlockLines.push(line);
+			continue;
+		}
+		const bqMatch = line.match(BLOCKQUOTE_RE);
+		if (bqMatch && bqMatch[1].trim()) hint = bqMatch[1].trim();
+	}
+	const codeBlock = codeBlockLines.length > 0 ? codeBlockLines.join("\n") : void 0;
+	const answers = [];
+	for (let a = 0; a < answerStarts.length; a++) {
+		const startIdx = answerStarts[a];
+		const endIdx = a + 1 < answerStarts.length ? answerStarts[a + 1] : lines.length;
+		const match = lines[startIdx].match(ANSWER_RE);
+		const isCorrect = match[1].toLowerCase() === "x";
+		let text = match[2].trim();
+		const continuation = [];
+		let contFence = false;
+		for (let j = startIdx + 1; j < endIdx; j++) {
+			const l = lines[j];
+			if (FENCE_RE.test(l)) {
+				contFence = !contFence;
+				continuation.push(l);
+				continue;
+			}
+			if (contFence) {
+				continuation.push(l);
+				continue;
+			}
+			if (BLOCKQUOTE_RE.test(l)) continue;
+			if (l.trim() === "") continue;
+			continuation.push(l);
+		}
+		if (continuation.length > 0) text += `\n${continuation.join("\n")}`;
+		answers.push({
+			isCorrect,
+			text
+		});
+	}
+	const correctCount = answers.filter((a) => a.isCorrect).length;
+	return {
+		id,
+		question: questionText,
+		answers: answers.map((a, i) => ({
+			id: `a${i + 1}`,
+			text: a.text,
+			isCorrect: a.isCorrect
+		})),
+		isMultiSelect: correctCount > 1,
+		hint,
+		codeBlock,
+		frontmatter: data
+	};
+}
+
+//#endregion
+//#region src/loader.ts
+/**
+* Parse all markdown question files in a directory.
+*
+* Each .md file is parsed via `parseQuestionFile`. The filename (without
+* extension) becomes the question ID.
+*
+* @param dir - Path to directory containing .md files
+* @param options - Optional config for recursion and filtering
+* @returns Array of parsed questions
+*/
+function parseDirectory(dir, options = {}) {
+	const { recursive = false, filePrefix } = options;
+	const questions = [];
+	const entries = readdirSync(dir);
+	for (const entry of entries.sort()) {
+		const fullPath = join(dir, entry);
+		if (statSync(fullPath).isDirectory() && recursive) {
+			questions.push(...parseDirectory(fullPath, options));
+			continue;
+		}
+		if (!entry.endsWith(".md")) continue;
+		if (entry.startsWith("_")) continue;
+		if (filePrefix && !entry.startsWith(filePrefix)) continue;
+		const id = basename(entry, ".md");
+		const content = readFileSync(fullPath, "utf-8");
+		try {
+			questions.push(parseQuestionFile(content, id));
+		} catch (err) {
+			console.warn(`Skipping ${fullPath}: ${err.message}`);
+		}
+	}
+	return questions;
+}
+
+//#endregion
+export { parseDirectory, parseQuestionFile };

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "mdquiz",
+  "type": "module",
+  "version": "0.0.0",
+  "packageManager": "pnpm@10.33.0",
+  "description": "Parse markdown quiz files into structured objects. Supports YAML frontmatter, checkbox answers, code blocks, and hint blockquotes.",
+  "author": "Aleksander Fidelus",
+  "license": "MIT",
+  "homepage": "https://github.com/FidelusAleksander/mdquiz#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FidelusAleksander/mdquiz.git"
+  },
+  "bugs": "https://github.com/FidelusAleksander/mdquiz/issues",
+  "keywords": [
+    "markdown",
+    "quiz",
+    "parser",
+    "questions",
+    "frontmatter",
+    "exam"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "lint": "eslint",
+    "prepublishOnly": "nr build",
+    "release": "bumpp",
+    "start": "tsx src/index.ts",
+    "test": "vitest",
+    "typecheck": "tsc",
+    "prepare": "simple-git-hooks"
+  },
+  "dependencies": {
+    "gray-matter": "catalog:deps"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "catalog:cli",
+    "@antfu/ni": "catalog:cli",
+    "@types/node": "catalog:types",
+    "bumpp": "catalog:cli",
+    "eslint": "catalog:cli",
+    "lint-staged": "catalog:cli",
+    "publint": "catalog:cli",
+    "simple-git-hooks": "catalog:cli",
+    "tsdown": "catalog:cli",
+    "tsnapi": "catalog:testing",
+    "tsx": "catalog:cli",
+    "typescript": "catalog:cli",
+    "vite": "catalog:cli",
+    "vitest": "catalog:testing"
+  },
+  "simple-git-hooks": {
+    "pre-commit": "pnpm i --frozen-lockfile --ignore-scripts --offline && pnpm run build && npx lint-staged"
+  },
+  "lint-staged": {
+    "*": "eslint --fix"
+  }
+}