inkdropapp / inkdrop-live-export

A library for programmatically exporting notes to local filesystem from Inkdrop

Inkdrop Live Export

An Inkdrop module which allows you to programmatically export notes to local filesystem via the local HTTP server. It supports live export, which continuously exports notes as the changes occur.

Prerequisites

• NodeJS >= 18
• Inkdrop >= 5.5.1

Demo project

A simple blog:

• https://github.com/craftzdog/craftzdog-uses
• Video tutorial

How to use it

Enable the Inkdrop local server

Follow the instruction in the documentation.

Now you should be able to invoke the API like so:

curl http://username:password@localhost:19840/
# => {"version":"5.5.1","ok":true}

Install dev-tools plugin

It helps copy notebook IDs quickly from the context menu.

https://my.inkdrop.app/plugins/dev-tools

Then, copy a bookId of a notebook you'd like to export by right-clicking the notebook on the sidebar and select Copy Notebook ID.

Install live-export

Suppose that you have a static website project such as a blog or a documentation, and you are in its root directory.

cd <PROJECT_ROOT>
npm i -D @inkdropapp/live-export

Example

Create a file import.mjs (It must be an ES Module). Initialize a live exporter:

import { LiveExporter, toKebabCase } from '@inkdropapp/live-export'

const liveExport = new LiveExporter({
  username: 'foo',
  password: 'bar',
  port: 19840
})

Then, start exporting like so:

const sub = await liveExport.start({
  live: true,
  bookId: '<YOUR_BOOK_ID>',
  preProcessNote: ({ note, frontmatter, tags }) => {
    frontmatter.title = note.title
    // Convert note title to kebab case (eg. "kebab-case-note-title")
    frontmatter.slug = toKebabCase(note.title)
    frontmatter.tags = tags.map(t => t.name)
  },
  pathForNote: ({ /* note, */ frontmatter }) => {
    // export only if it's public
    if (frontmatter.public) {
      return `./<PATH_TO_EXPORT_NOTES>/${frontmatter.slug}.md`
    } else return false
  },
  urlForNote: ({ frontmatter }) => {
    if (frontmatter.public) {
      return `/<URL_TO_LINK_NOTES>/${frontmatter.slug}`
    } else return false
  },
  pathForFile: ({ mdastNode, /* note, file, */ extension, frontmatter }) => {
    if (frontmatter.slug && mdastNode.alt) {
      const fn = `${frontmatter.slug}_${toKebabCase(
        mdastNode.alt
      )}${extension}`
      const res = {
        filePath: `./<PATH_TO_EXPORT_IMAGES>/${fn}`,
        url: `./<URL_TO_LINK_IMAGES>/${fn}`
      }
      // If the `alt` attribute of the image is 'thumbnail', use it as a hero image
      if (mdastNode.alt === 'thumbnail') {
        frontmatter.heroImage = res.filePath
      }
      return res
    } else return false
  },
  postProcessNote: ({ md }) => {
    // Remove the thumbnail image from the Markdown body
    const md2 = md.replace(/\!\[thumbnail\]\(.*\)\n/, '')
    return md2
  }
})

If you would like to cancel/stop exporting:

sub.stop()

And run it:

node --experimental-vm-modules import.mjs

start() parameters

bookId: string

The notebook ID to export. Required.

live?: boolean

If true, it continuously exports as you change notes in Inkdrop. If false, it performs one-time export.

false by default.

pathForNote(data)

Generate a path to export the specified note

• data.note: Note - The note to export
• data.frontmatter: Record<string, any> - The YAML frontmatter of the note
• data.tags: An array of Tag - The tags of the note
• Returns: string | false | Promise<...> - A destination path to export. If it returns false, the note will be skipped exporting.

urlForNote(data)

Generate a URL for the specified note. It is necessary to link from the note to another note.

• data.note: Note - The note to export
• data.frontmatter: Record<string, any> - The YAML frontmatter of the note
• data.tags: An array of Tag - The tags of the note
• Returns: string | false | Promise<...> - A url/relative path. If it returns false, the note will be skipped processing.

pathForFile(data)

Generate a path and URL to export the specified image file.

• data.note: Note - The note data
• data.mdastNode: Image - The mdast node of the image
• data.file: File - The attached image file data to export
• data.extension: string - The file extension of the image (e.g., '.jpg', '.png')
• data.frontmatter: Record<string, any> - The YAML frontmatter of the note
• data.tags: An array of Tag - The tags of the note
• Returns: { filePath: string; url: string } | false | Promise<...> - A destination file path to export and url to link. If it returns false, the image will be skipped exporting.

preProcessNote(data)

Pre-process the specified note. It is useful to update the frontmatter information based on the note metadata.

• data.note: Note - The note data
• data.frontmatter: Record<string, any> - The YAML frontmatter of the note
• data.tags: An array of Tag - The tags of the note
• data.mdast: Root - The mdast root node of the note
• Returns: any | Promise<any>

postProcessNote(data)

Post-process the specified note right before writing the note to a file. It is useful to tweak the Markdown data (e.g., deleting unnecessary lines).

• data.md: string - The Markdown data
• data.frontmatter: Record<string, any> - The YAML frontmatter of the note
• data.tags: An array of Tag - The tags of the note
• Returns: string | Promise<string> - Returns the processed Markdown string

Debugging

Set environment variable DEBUG='inkdrop:export:info,inkdrop:export:error' to enable console outputs

FAQ

How can I see the access logs of the local server?

Run the app with a --enable-logging flag. See the documentation for more detail.

Can I import the notes back to Inkdrop?

No. As it transforms the notes for your projects, they are no longer compatible with Inkdrop.