Merge branch 'main' into design

README.md

@@ -2,41 +2,38 @@
 
 [![](https://badgen.net/npm/v/mddb)](https://www.npmjs.com/package/mddb)
 
-MarkdownDB is a javascript library for treating markdown files as a database -- as a "MarkdownDB". Specifically, it:
+MarkdownDB is a javascript library that turns markdown files into structured queryable data. Build rich markdown-powered sites easily and reliably. Specifically it:
 
-- Parses your markdown files to extract structured data (frontmatter, tags etc) and creates an index in a local SQLite database
-- Provides a lightweight javascript API for querying the database and importing files into your application
-
-**🚧 MarkdownDB is in its early development stage**
+- Parses your markdown files to extract structured data (frontmatter, tags etc) and builds a queryable index either in JSON files or a local SQLite database
+- Provides a lightweight javascript API for querying the index and using the data files into your application
 
 ## Features and Roadmap
 
 - [x] **Index a folder of files** - create a db index given a folder of markdown and other files
+  - [x] **Command line tool for indexing**: Create a markdowndb (index) on the command line **v0.1**
+  - [x] SQL(ite) index **v0.2**
+  - [x] JSON index **v0.6**
   - [ ] BONUS Index multiple folders (with support for configuring e.g. prefixing in some way e.g. i have all my blog files in this separate folder over here)
-  - [x] **Command line tool for indexing**: Create a markdowndb (index) on the command line
-  - [ ] SQL(ite) index
-  - [ ] JSON index
 
 Extract structured data like:
 
 - [x] **Frontmatter metadata**: Extract markdown frontmatter and add in a metadata field
-  - [ ] deal with nested frontmatter (? what does this mean?)
   - [ ] deal with casting types e.g. string, number so that we can query in useful ways e.g. find me all blog posts before date X
 - [ ] **Tags**: Extracts tags in markdown pages
-  - [x] Extract tags in frontmatter
-  - [ ] Extract tags in body like `#abc`
-- [ ] **Links**: links between files like `[hello](abc.md)` or wikilink style `[[xyz]]` so we can compute backlinks or deadlinks etc (see #4)
-- [ ] **Tasks**: extract tasks like this `- [ ] this is a task` (See obsidian data view)
+  - [x] Extract tags in frontmatter **v0.1**
+  - [x] Extract tags in body like `#abc` **v0.5**
+- [x] **Links**: links between files like `[hello](abc.md)` or wikilink style `[[xyz]]` so we can compute backlinks or deadlinks etc (see #4) **v0.2**
+- [x] **Tasks**: extract tasks like this `- [ ] this is a task` (See obsidian data view) **v0.4**
 
 Data enhancement and validation
 
-- [ ] **Computed fields**: add new metadata properties based on existing metadata e.g. a slug field computed from title field; or, adding a title based on the first h1 heading in a doc; or, a type field based on the folder of the file (e.g. these are blog posts). cf https://www.contentlayer.dev/docs/reference/source-files/define-document-type#computedfields. #54
-- [ ] **Data validation and Document Types**: validate metadata against a schema/type so that I know the data in the database is "valid" #55
+- [ ] 🚧 **Computed fields**: add new metadata properties based on existing metadata e.g. a slug field computed from title field; or, adding a title based on the first h1 heading in a doc; or, a type field based on the folder of the file (e.g. these are blog posts). cf https://www.contentlayer.dev/docs/reference/source-files/define-document-type#computedfields. #54 🚧
+- [ ] 🚧 **Data validation and Document Types**: validate metadata against a schema/type so that I know the data in the database is "valid" #55 
   - [ ]  BYOT (bring your own types): i want to create my own types ... so that when i get an object out it is cast to the right typescript type
 
 ## Quick start
 
-### You have a folder of markdown content
+### Have a folder of markdown content
 
 For example, your blog posts. Each file can have a YAML frontmatter header with metadata like title, date, tags, etc.
 

examples/nextjs-blog/.gitignore

@@ -0,0 +1,32 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel

examples/nextjs-blog/README.md

@@ -0,0 +1,103 @@
+# MarkdownDB Next.js Blog Tutorial
+
+This tutorial guides you through creating a simple Next.js-based blog using MarkdownDB. MarkdownDB empowers you to treat markdown files as a database, simplifying content management and querying.
+
+## Step 1: Set Up a Next.js Project
+
+Begin by creating a Next.js project. If Next.js is not installed, execute the following command, and make sure to include Tailwind:
+
+```bash
+npx create-next-app nextjs-blog
+cd nextjs-blog
+```
+
+## Step 2: Create a Folder for Blog Posts
+
+Establish a folder to store your blog posts within your project. For instance:
+
+```bash
+mkdir src/content
+cd src/content
+```
+
+Inside the content folder, create two sample blog posts using markdown, such as:
+
+```bash
+- embracing-minimalism.md
+- remote-work-productivity.md
+```
+
+## Step 3: Index Markdown Files into SQLite Database
+
+After preparing markdown files, store their metadata in a database using the MarkdownDB CLI. Execute the following command:
+
+```bash
+npx mddb ./content
+```
+
+## Step 4: Move `.markdowndb` Folder with `files.json` to the src Directory
+
+## Step 5: Load Blog Posts Using MarkdownDB
+
+Edit `pages/index.js`. Use the following code snippet:
+
+### Component 1: BlogList
+
+```jsx
+import fs from "fs";
+import Link from "next/link";
+import styles from "@/styles/Home.module.css";
+
+export default function Home({ posts }) {
+  return (
+    <>
+      <main className={styles.main}>
+        <div>
+          <h2>Blog Posts</h2>
+          <ul>
+            {posts.map((post) => (
+              <li>
+                <h3>{post.metadata.title}</h3>
+              </li>
+            ))}
+          </ul>
+        </div>
+      </main>
+    </>
+  );
+}
+
+export async function getStaticProps() {
+  const filePath = "src/.markdowndb/files.json";
+  const fileContent = fs.readFileSync(filePath, "utf-8");
+  const posts = JSON.parse(fileContent);
+
+  return {
+    props: {
+      posts,
+    },
+  };
+}
+```
+
+## Step 6: Run Your Next.js App
+
+Run your Next.js app to view your blog in action:
+
+```bash
+npm run dev
+```
+
+Visit http://localhost:3000/blog to see your blog posts listed.
+
+Congratulations! You've successfully created a simple Next.js blog using MarkdownDB. Explore more features and customize your blog as needed.
+
+
+### Flag: While `mddb` may not offer significantly more than manual handling, it stands out as a straightforward, extensively tested, and lightweight library.
+
+### Additional Features:
+
+- **Tag Querying:** Easily retrieve tags from all files, streamlining organization and categorization.
+- **Backward/Forward Links:** Establish links for enhanced file interconnectivity and navigation.
+- **Custom Field Calculation:** Automatically calculate custom fields based on file content, reducing manual effort.
+- **Schema Validation:** Ensure file adherence to a predefined schema for data integrity.

examples/nextjs-blog/jsconfig.json

@@ -0,0 +1,7 @@
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}

examples/nextjs-blog/next.config.js

@@ -0,0 +1,6 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+}
+
+module.exports = nextConfig