• Inkwell: A Markdown-Powered Blog Engine for Carrd

  Inkwell is a lightweight, JavaScript-powered blog engine designed to be embedded into static website builders like Carrd. It uses a GitHub repository as a headless CMS, allowing you to manage your blog content entirely through Markdown files.

  It's the perfect solution for adding a clean, modern, and dynamic blog to a site where you cannot use a traditional backend.

  Key Features

  • GitHub as a CMS: Write and manage all your blog posts in simple Markdown files within your own GitHub repository.
  • Responsive Card Layout: Posts are automatically displayed in a clean, responsive grid of cards that looks great on any device.
  • Dynamic Modal Viewer: Clicking a card opens the full post in a sleek, non-intrusive modal pop-up, preventing users from navigating away from the main page.
  • Shareable Deep Links: Each post gets a unique, shareable URL. When a user visits this URL, the page automatically opens the correct blog post, making it easy to share your content.
  • Easy to Customise: The look and feel can be easily tweaked using CSS variables, and the content source can be pointed to any public GitHub repository.
  • Zero Dependencies (almost!): Requires no backend, no database, and only one external library (marked.js) to render Markdown, which is loaded automatically from a CDN.

  How It Works

  Inkwell operates on a simple but powerful principle. The script fetches a central index.md file from your GitHub repository. This file acts as a database, containing a list of all your blog posts, along with their metadata (title, date, cover image URL, and tags).

  1. The script parses this index.md file to learn about all available posts.
  2. It dynamically generates a "card" for each post and displays them in a grid.
  3. When a user clicks on a card, the script fetches the content of the corresponding .md file for that specific post.
  4. It then uses the marked.js library to convert the Markdown content into HTML on the fly and displays it inside a modal overlay.
  5. Simultaneously, it updates the browser's URL to create a shareable deep link to that post.

  Installation Guide

  Integrating Inkwell into a Carrd project (or a similar platform) is a two-step process. You will need to create two separate "Embed" blocks.

  Step 1: The Blog Placer

  This block tells the engine where on the page the blog should appear.

  1. Create a new Embed element in Carrd.
  2. Set its Style to Inline.
  3. Paste the following code into it:

  <!-- START BLOG PLACER -->
  <!-- Place this in an 'Inline' embed block before the main Blog Engine script. -->
  <div id="blog-destination-target"></div>

  Place this embed element wherever you want the grid of blog post cards to be displayed on your page.

  Step 2: The Blog Engine

  This block contains the core logic, styling, and HTML structure of the blog.

  1. Create a second Embed element in Carrd.
  2. Set its Code location to Hidden (End of Body). This ensures the rest of your site loads before the script runs.
  3. Copy the entire inkwell.js script (the complete HTML, <style>, and <script> block) and paste it into this embed.

  That's it! The script will automatically find the #blog-destination-target div and inject the blog into it.

  Content Management (Your GitHub Repo)

  Your blog's content is managed entirely within a public GitHub repository. The structure is simple:

  1. An index.md file: This file must be at the root of the location you specify in the script. It lists all your posts.
  2. Your post files: A folder containing all your individual blog posts as .md files.

  index.md Format

  Each line in the index.md file represents one blog post and must follow this exact format:

  * [Post Title](path/to/post-one.md) - YYYY-MM-DD - img:https://url.to/cover/image.jpg - Tag One, Tag Two
  * [Another Post](path/to/post-two.md) - YYYY-MM-DD - img:https://url.to/another/image.png - Tech, Project```

  Breakdown:

  • [Post Title]: The title of your blog post.
  • (path/to/post-one.md): The relative path from the index.md file to the post's Markdown file.
  • YYYY-MM-DD: The publication date.
  • img:https://...: The full, direct URL to the post's cover image.
  • Tag One, Tag Two: A comma-separated list of tags for the post.

  Customisation

  You can easily adapt Inkwell to your needs by editing the script.

  1. Pointing to Your Content

  In the JavaScript section, modify the configuration constants at the top to point to your own repository and website URL.

  // --- CONFIGURATION ---
  // URL for the index file containing the list of all blog posts.
  const INDEX_URL = 'https://raw.githubusercontent.com/your-username/your-repo/main/index.md';
  
  // The base URL of your website, used for creating shareable deep links.
  const BASE_URL = 'https://www.your-website.com/';
  
  // The hash for the section where the blog lives, to keep the user in the right place.
  const BLOG_SECTION_HASH = '#blog'; // Change to your section ID

  Note: The URL for INDEX_URL must be the "raw" content link from GitHub.

  2. Changing the Style

  The appearance of the blog can be changed by editing the CSS variables defined at the top of the <style> block.

  :root {
      --blog-primary-color: #0591C3;
      --blog-font-family: "Your Font Name", sans-serif;
      --blog-card-shadow: 0 4px 15px rgba(0, 0, 0, 0.08);
      /* ... and more ... */
  }

  Roadmap (Future Plans)

  Inkwell is under active development. Planned features include:

  • Search Functionality: A small search bar to quickly find posts by title or content.
  • Advanced Filtering: Buttons or dropdowns to filter posts by tag or year.
  • Pagination: For blogs with many posts, a system to display them across multiple pages instead of all at once.

  License

  This project is licensed under the GPL3 License.