docs update

Author: Mapaor

ARCHITECTURE.md

@@ -1,8 +1,7 @@
 # Architecture
 
-This document explains the internal architecture of the markdown2typst.
-
 ## Overview
+Here is an overview of the phases the library has when processing Markdown code to Typst code.
 
 ```
 Markdown Input
@@ -28,24 +27,24 @@ The converter uses the unified/remark ecosystem to parse Markdown:
 - **remark-parse**: Parses Markdown to MDAST (Markdown Abstract Syntax Tree)
 - **remark-gfm**: Adds GitHub Flavored Markdown support (tables, strikethrough, code blocks...)
 - **remark-math**: Adds math equation support
-- **remark-frontmatter**: Parses YAML frontmatter
+- **remark-frontmatter (and js-yaml)**: Parses YAML frontmatter
 
 ### 2. AST Processing
 
 After parsing, we process the AST to:
 
 1. **Extract Metadata**:
    - Parse YAML frontmatter for title, authors, date, language, region, description and abstract
-   - Find leading H1 as potential title (metadata only in that case)
-   - Merge with user-provided options and in case of conflict options override front-matter
+   - Find leading H1 as potential title
+   - Merge with custom options if provided and in case of conflict options override front-matter
 
 2. **Collect Definitions**:
    - Link reference definitions: `[id]: url`
    - Footnote definitions: `[^id]: content`
 
 
 ### 3. Rendering
-The rendering phase walks the AST and converts each node to Typst syntax:
+The rendering phase iterates the AST and converts each node to Typst syntax:
 
 #### Block-Level Rendering
 
@@ -70,33 +69,7 @@ The rendering phase walks the AST and converts each node to Typst syntax:
 - **Footnotes**: Inline with `#footnote[]`
 
 
-## Key Design Decisions
-
-### 1. Function Form for Formatting
-
-We use Typst function forms (`#strong[]`, `#emph[]`) instead of markup forms (`*text*`, `_text_`):
-
-**Advantages**:
-- Unambiguous parsing (no conflicts with `*` in comments or math)
-- Consistent with other Typst features
-- Easier to nest and compose
-
-**Trade-off**: Slightly more verbose output
-
-### 2. Reference Resolution
-
-Link and footnote references are resolved at render time:
-
-```typescript
-const definitions = collectDefinitions(tree);
-const footnoteDefinitions = collectFootnotes(tree);
-// Later, during rendering:
-const def = definitions.get(identifier);
-```
-
-This allows reference-style links to work correctly.
-
-### 3. Indentation Handling
+### Note on indentation handling
 
 All rendering functions accept an `indentLevel` parameter for proper nesting:
 
@@ -107,19 +80,14 @@ function renderBlock(node, indentLevel, definitions, footnotes) {
 }
 ```
 
-This ensures nested lists and blockquotes are properly formatted.
-
-### 4. Type Safety
+## Contributing
 
-The codebase uses TypeScript with strict mode for maximum type safety:
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on extending the code.
 
-- All MDAST node types are imported from `@types/mdast`
-- Custom node types (math, mark, etc.) extend standard types
-- Exported options are fully typed
 
-## Extension Points
+### How to add new Markdown features
 
-### Adding New Markdown Features
+Here are some hints:
 
 1. Add remark plugin to parser:
 ```typescript
@@ -128,108 +96,19 @@ const processor = unified()
   .use(remarkNewFeature)
 ```
 
-2. Define custom node type if needed:
+1. Define custom node type if needed:
 ```typescript
 interface NewFeatureNode extends Literal {
   type: 'newFeature';
   // additional fields
 }
 ```
 
-3. Add rendering logic:
+1. Add rendering logic:
 ```typescript
 function renderNewFeature(node: NewFeatureNode): string {
   // Convert to Typst
 }
 ```
 
-4. Update the main switch statement in `renderBlock` or `renderInline`
-
-## Performance Considerations
-
-### Current Performance
-
-The converter is designed for **clarity over performance**, suitable for:
-- Interactive editors (sub-second conversion for typical documents)
-- Build processes (hundreds of documents per minute)
-- Browser environments (client-side conversion)
-
-### Optimization Opportunities
-
-If performance becomes critical:
-
-1. **Memoization**: Cache rendered subtrees
-2. **Streaming**: Process large documents in chunks
-3. **Worker Threads**: Parallelize conversion of multiple files
-4. **AST Caching**: Cache parsed AST for unchanged documents
-
-## Testing Strategy
-
-Currently, the project focuses on:
-
-1. **Manual Testing**: Example files in `examples/`
-2. **Type Checking**: TypeScript used for type safety
-3. **Visual Inspection**: Compare Markdown input with Typst output
-
-### Future Testing
-
-Recommended additions:
-
-1. **Unit Tests**: Test individual rendering functions
-2. **Integration Tests**: Full Markdown → Typst conversion
-3. **Snapshot Tests**: Compare against known-good outputs
-4. **Fuzz Testing**: Random/malformed input handling
-5. **Users Testing**: In the work in progress demo website
-
-## Build System
-
-The build system uses esbuild for fast bundling:
-
-### Output Formats
-
-1. **dist/markdown2typst.min.js**: Production bundle (minified)
-2. **dist/markdown2typst.js**: Development bundle (readable)
-3. **Source maps**: For debugging bundled code
-
-### Configuration
-
-```javascript
-{
-  format: "esm",           // ES modules
-  target: ["es2020"],      // Modern JavaScript
-  platform: "browser",     // Browser-compatible
-  bundle: true             // Single file output
-}
-```
-
-## Dependencies
-
-### Runtime Dependencies
-
-- **unified**: Text processing framework
-- **remark-parse**: Markdown parser
-- **remark-gfm**: GitHub Flavored Markdown
-- **remark-math**: Math equation support
-- **remark-frontmatter**: YAML frontmatter parser
-
-### Development Dependencies
-
-- **typescript**: Type checking and definitions
-- **esbuild**: Fast bundler
-- **@types/mdast**: MDAST type definitions
-
-## Future Enhancements
-
-Potential improvements:
-
-1. **CLI Tool**: Command-line interface for file conversion
-2. **VS Code Extension**: Live preview and conversion
-3. **Custom Templates**: User-provided template system
-4. **Plugin System**: Allow third-party extensions
-5. **Caching**: Improve performance for large documents
-6. **Validation**: Verify Typst output syntax
-7. **Source Maps**: Map Typst back to Markdown for errors
-
-## Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on extending the codebase.
+1. Update the main switch statement in `renderBlock` or `renderInline`

CHANGELOG.md

@@ -5,20 +5,6 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.1 (Unreleased)] - 2026-01-14
-
-### Added
-- Comprehensive documentation with examples
-- JSDoc comments throughout codebase
-- Enhanced build system with multiple output formats
-- Example files demonstrating usage
-- TypeScript support with type definitions
-
-### Changed
-- Improved package.json metadata
-- Enhanced README with API documentation
-- Better project structure
-
 ## [0.1.0] - 2026-01-11
 
 ### Added

CONTRIBUTING.md

@@ -2,10 +2,6 @@
 
 Thank you for considering contributing to markdown2typst! This document provides guidelines for contributing to the project.
 
-## Code of Conduct
-
-Be respectful, constructive, and professional in all interactions.
-
 ## How Can I Contribute?
 
 ### Reporting Bugs
@@ -40,6 +36,9 @@ npm run typecheck
 
 # Or...
 npx tsc --noEmit
+
+# And test
+npm run test
 ```
 
 ## Guidelines
@@ -52,7 +51,7 @@ npx tsc --noEmit
 - Use meaningful variable and function names
 - Provide usage examples if you add a new feature
 
-#### Example:
+#### Example JSDoc comments:
 
 ```typescript
 /**
@@ -74,18 +73,18 @@ export function markdown2typst(markdown: string, options?: Options): string {
 
 ### Testing guidelines
 When adding new features:
-
-  - Test with various Markdown inputs
-  - Verify Typst output is syntactically correct
+  - Ensure all tests pass (`npm run test`)
+  - Test with various Markdown inputs related to your new feature
+  - Verify Typst output is syntactically correct and can compile in the [Typst.app](https://typst.app)
   -  Check edge cases (empty strings, special characters, etc.)
 
 ### Documentation guidelines
-If you add a new features or make important changes to the code
+If you add a new features or make important changes to the code please document them as well
 
-1. Update the main README.md documenting it
+1. Update the main README.md if needed
 2. If possible add examples to the `examples/` directory
 
 ## Questions?
 
-Feel free to open an issue with your question or reach out to pardo.marti@gmail.com.
+Feel free to open an issue with your question or reach out at pardo.marti@gmail.com.