markdown-to-json-ld

v1.0.3

Published

6 months ago

Transform Markdown to JSON-LD with Advanced Table & Annotation Support for JavaScript developers optimizing for AI and NLWeb

Downloads

0High
0Medium
0Low

iunera

markdown json-ld schema.org structured-data seo

markdown-to-json-ld

Transform Markdown to JSON-LD with Advanced Table & Annotation Support for JavaScript developers optimizing for AI.

This project of iunera is the npm package for the json-ld-markdown project. This lib is powering the Markdown to Schema.org JSON-LD for AI SEO website.

The idea behind this project is to make it easy for developers to transform Markdown content to JSON-LD, which enhances the processability of their content in AI, Large Language Models (LLMs), and Natural Language Web (NLWeb) contexts. Here's an expanded explanation:

Why JSON-LD Matters for AI and LLMs

JSON-LD (JavaScript Object Notation for Linked Data) provides structured data that can be more easily understood by machines. When content is transformed from Markdown to JSON-LD:

Enhanced AI Understanding: AI systems can better comprehend the semantic meaning of content
Improved Search Engine Visibility: Search engines like Google use structured data for rich results
Better Content Processing: LLMs can process and reason about structured content more effectively
Semantic Relationships: Relationships between content items become explicit rather than implicit

Key Benefits of the Transformation

Semantic Enrichment: Adds meaningful context to content through Schema.org vocabularies
Content Discoverability: Makes content more discoverable by AI systems and search engines
Consistent Structure: Provides a standardized way to represent Markdown content
AI-Ready Content: Prepares content for optimal processing by AI and LLMs
Metadata Preservation: Maintains important metadata from the original Markdown

Use Cases

This transformation is particularly valuable for:

Content Publishers: Blogs, news sites, and documentation platforms seeking AI visibility
Knowledge Bases: Making knowledge repositories more accessible to AI systems
Technical Documentation: Enhancing the machine-readability of technical content
FAQ Systems: Structuring question-answer pairs for better AI consumption
Product Information: Structuring product details for improved search and AI integratio

Installation

npm install markdown-to-json-ld

CDN Usage

You can also use this library directly from a CDN without installing it locally:

<!-- Include the library from unpkg CDN -->
<script src="https://unpkg.com/[email protected]/dist/markdown-to-json-ld.js"></script>

When loaded via CDN, the library is available as a global variable window.MarkdownToJsonLd with the following components:

// Access the components
const EnhancedMarkdownParser = window.MarkdownToJsonLd.EnhancedMarkdownParser;
const JsonLDTransformer = window.MarkdownToJsonLd.JsonLDTransformer;

// Use the transformer
const jsonLd = window.MarkdownToJsonLd.JsonLDTransformer.transform(markdownContent, config);

Example HTML Integration

<!DOCTYPE html>
<html>
<head>
    <title>Markdown to JSON-LD Example</title>
</head>
<body>
<!-- Your HTML content -->

<!-- Include the library from CDN -->
<script src="https://unpkg.com/[email protected]/dist/markdown-to-json-ld.js"></script>

<script>
    // Your markdown content
    const markdown = `# My Article\n\nThis is content.`;

    // Configuration
    const config = {
        type: 'Article',
        author: ['John Doe'],
        publisher: {
            name: 'Example Publisher',
            url: 'https://example.com'
        }
    };

    // Transform markdown to JSON-LD
    const jsonLd = window.MarkdownToJsonLd.JsonLDTransformer.transform(markdown, config);

    // Use the result
    console.log(jsonLd);
</script>
</body>
</html>

Usage

The library provides two main classes:

EnhancedMarkdownParser: Parses Markdown content and extracts various components
JsonLDTransformer: Transforms the parsed Markdown data into JSON-LD

Basic Usage

import {JsonLDTransformer} from 'markdown-to-json-ld';

// Your Markdown content
const markdownContent = `---
title: My Article
type: Article
schema: https://schema.org
date: 2023-08-15
author: John Doe
---

# My Article

This is the content of my article.`;

// Configuration options
const config = {
    baseUrl: 'https://example.com',
    slug: 'my-article',
    descriptionLength: 200,
    type: 'Article',
    date: '2023-08-15',
    author: ['John Doe'],
    publisher: {
        name: 'Example Publisher',
        url: 'https://example.com'
    },
    keywords: ['example', 'article'],
    categories: ['Technology']
};

// Transform Markdown to JSON-LD
const jsonLd = JsonLDTransformer.transform(markdownContent, config);

// Output the JSON-LD
console.log(JSON.stringify(jsonLd, null, 2));

Configuration Options

The transform method accepts the following configuration options:

| Option | Type | Description | Default | |---------------------|--------|------------------------------------------------------|-------------------------| | baseUrl | string | Base URL for the article | 'https://example.com' | | slug | string | Slug for the article URL | '' | | descriptionLength | number | Maximum length for the description | 200 | | type | string | Type of the article (e.g., 'Article', 'NewsArticle') | 'Article' | | date | string | Publication date in ISO format | Current date | | author | array | Array of author names | [] | | publisher | object | Publisher information | {} | | keywords | array | Keywords for the article | [] | | categories | array | Categories for the article | [] |

Advanced Features

YAML Front Matter

The library supports YAML front matter for defining metadata:

---
title: My Article
type: Article
schema: https://schema.org
date: 2023-08-15
author: John Doe
publisher.name: Example Publisher
publisher.url: https://example.com
slug: my-article
keywords: [example, article]
categories: [Technology]
---

# My Article

Content here...

FAQ Sections

FAQ sections are automatically detected and transformed into a separate FAQPage JSON-LD object:

## Frequently Asked Questions

### What is this?

This is an example.

### How does it work?

It works like this...

Tables

Markdown tables are automatically detected and transformed into Table or Dataset JSON-LD objects:

| Name | Price | Description |
|------|-------|-------------|
| Item 1 | $10 | Description 1 |
| Item 2 | $20 | Description 2 |

Lists

Ordered and unordered lists are transformed into ItemList JSON-LD objects:

- Item 1
- Item 2
- Item 3

Links

Links are transformed into appropriate JSON-LD objects based on their URL:

[Example](https://example.com)
[GitHub Repository](https://github.com/example/repo)
[YouTube Video](https://youtube.com/watch?v=123456)

Multiple Types

You can define multiple JSON-LD types in a single Markdown file using the --- separator:

---
type: Article
schema: https://schema.org
---

# My Article

Content here...

---
type: Document
schema: http://purl.org/dc/terms/
---

# Metadata

Additional metadata here...

Examples

For more examples, see the example-articles directory in the main repository.

For a comprehensive example that demonstrates many of the library's features including YAML front matter, FAQ sections, and multiple types, see the License Token Article example.

API Reference

EnhancedMarkdownParser

The EnhancedMarkdownParser class provides methods for parsing Markdown content:

extractMetadata(content): Extracts metadata from YAML front matter
extractContext(content): Extracts the JSON-LD context
extractTables(content): Extracts tables from the content
extractLists(content): Extracts lists from the content
extractLinks(content, articleUrl): Extracts links from the content
extractAnnotations(content): Extracts annotations from the content
extractTitle(content): Extracts the title from the content
extractDescription(content, maxLength): Extracts the description from the content
extractArticleBody(content): Extracts the article body from the content
extractSections(content): Extracts sections from the content
extractFaqQuestions(content): Extracts FAQ questions from the content

JsonLDTransformer

The JsonLDTransformer class provides methods for transforming Markdown to JSON-LD:

transform(markdownContent, config): Transforms Markdown content to JSON-LD
processAuthors(authors, articleUrl): Processes author information
processPublisher(publisher): Processes publisher information

For more information

For full documentation, please see the main repository README.

License

We choose fair code, fair work, fair payment, open collaboration.

Open Compensation Token License

Licensed under the OPEN COMPENSATION TOKEN LICENSE (the "License").

You may not use this file except in compliance with the License.

You may obtain a copy of the License at
[https://github.com/open-compensation-token-license/license/blob/main/LICENSE.md](https://github.com/open-compensation-token-license/license/blob/main/LICENSE.md)

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either expressed or implied.
See the License for the specific language governing permissions and
limitations under the License.

@octl.sid: 5fecd757-5fec-d757-d757-00005fb33b80

@octl.sid: x-octl-sid:5fecd757-5fec-d757-d757-00005fb33b80

Why did we choose the OCTL as alternative to the BSD 3-Clause License?
Why we do NOT apply Apache 2.0 License?

This project is licensed under the Open Compensation Token License (OCTL), with the unique project identifier x-octl-sid:5fecd757-5fec-d757-d757-00005fb33b80. The OCTL enables blockchain-based licensing and royalty distribution via NFTs. View the license token at https://www.license-token.com/license/new-procurement/x-octl-sid%3A5fecd757-5fec-d757-d757-00005fb33b80. See the LICENSE file or OCTL license text for details. For OCTL compliance, ensure contributions are registered with the project’s x-octl-sid using the license token link.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

markdown-to-json-ld

Why JSON-LD Matters for AI and LLMs

Key Benefits of the Transformation

Use Cases

Installation

CDN Usage

Example HTML Integration

Usage

Basic Usage

Configuration Options

Advanced Features

YAML Front Matter

FAQ Sections

Tables

Lists

Links

Multiple Types

Examples

API Reference

EnhancedMarkdownParser

JsonLDTransformer

For more information

License

Open Compensation Token License