@inkdropapp/live-export
Version:
A library for programmatically exoprting notes to local filesystem from Inkdrop
204 lines (145 loc) • 6.96 kB
Markdown
Inkdrop Live Export
===================
An [Inkdrop](https://www.inkdrop.app/) module which allows you to programmatically export notes to local filesystem via [the local HTTP server](https://docs.inkdrop.app/manual/accessing-the-local-database#accessing-via-http-advanced).
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](https://youtu.be/3_JE76PKBWE)
## How to use it
### Enable the Inkdrop local server
Follow [the instruction in the documentation](https://docs.inkdrop.app/manual/accessing-the-local-database#accessing-via-http-advanced).
Now you should be able to invoke the API like so:
```sh
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.
```sh
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:
```js
import { LiveExporter, toKebabCase } from '@inkdropapp/live-export'
const liveExport = new LiveExporter({
username: 'foo',
password: 'bar',
port: 19840
})
```
Then, start exporting like so:
```js
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:
```js
sub.stop()
```
And run it:
```sh
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`](https://docs.inkdrop.app/reference/data-models#note) - The note to export
* `data.frontmatter`: `Record<string, any>` - The YAML frontmatter of the note
* `data.tags`: An array of [`Tag`](https://docs.inkdrop.app/reference/data-models#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`](https://docs.inkdrop.app/reference/data-models#note) - The note to export
* `data.frontmatter`: `Record<string, any>` - The YAML frontmatter of the note
* `data.tags`: An array of [`Tag`](https://docs.inkdrop.app/reference/data-models#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`](https://docs.inkdrop.app/reference/data-models#note) - The note data
* `data.mdastNode`: [`Image`](https://github.com/syntax-tree/mdast#image) - The mdast node of the image
* `data.file`: [`File`](https://docs.inkdrop.app/reference/data-models#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`](https://docs.inkdrop.app/reference/data-models#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`](https://docs.inkdrop.app/reference/data-models#note) - The note data
* `data.frontmatter`: `Record<string, any>` - The YAML frontmatter of the note
* `data.tags`: An array of [`Tag`](https://docs.inkdrop.app/reference/data-models#tag) - The tags of the note
* `data.mdast`: [`Root`](https://github.com/syntax-tree/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`](https://docs.inkdrop.app/reference/data-models#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](https://docs.inkdrop.app/manual/troubleshooting#enable-logging) 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.