Skip to content

Commit

Permalink
docs: vitepress configuration. Split docs and readme content (#37)
Browse files Browse the repository at this point in the history
* docs: vitepress configuration. Split docs and readme content

This update includes:
- separate github pages deployment flow
- updated test that checks template variables list
- testimonials section with the users' feedback about the plugin
  • Loading branch information
bandantonio authored Jul 21, 2024
1 parent 041d29a commit e154122
Show file tree
Hide file tree
Showing 23 changed files with 7,683 additions and 6,573 deletions.
54 changes: 54 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
name: Deploy documentation
on:
push:
workflow_dispatch:

permissions:
contents: read
pages: write
id-token: write

concurrency:
group: pages
cancel-in-progress: false

jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0

- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 20
cache: npm

- name: Setup Pages
uses: actions/configure-pages@v4
- name: Install dependencies
run: npm ci

- name: Build with VitePress
run: npm run docs:build

- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: docs/.vitepress/dist

deploy:
if: ${{ github.ref == 'refs/heads/master' }}
needs: build
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
name: Deploy
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -22,3 +22,7 @@ data.json

# Exclude macOS Finder (System Explorer) View States
.DS_Store

# Vitepress
docs/.vitepress/dist
docs/.vitepress/cache
154 changes: 22 additions & 132 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
# Obsidian Apple Books highlights import plugin

Import all your Apple Books highlights to Obsidian.

![Plugin banner](plugin-banner.png)
![Plugin preview](./docs/assets/plugin-preview.png)

![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/bandantonio/obsidian-apple-books-highlights-plugin/release.yml?branch=master&style=for-the-badge&logo=github)
![GitHub manifest version](https://img.shields.io/github/manifest-json/v/bandantonio/obsidian-apple-books-highlights-plugin?style=for-the-badge&logo=obsidian&color=%230082FC)
Expand All @@ -16,144 +14,38 @@ Import all your Apple Books highlights to Obsidian.

This plugin aims to be a **fast**, **customizable**, **reliable**, and **up-to-date** solution to import your Apple Books highlights to Obsidian:

- **Fast**: It takes less than 1 second to import ~1000 highlights.
- **Customizable**: Use Handlebars and Markdown to customize the output of your highlights the way you want. Check the [`Template variables`](#template-variables) section below for more information.
- ⚡️ **Fast**: It takes less than 1 second to import ~1000 highlights.
- 🎨 **Customizable**: Use Handlebars and Markdown to customize the output of your highlights the way you want. Check the [`Template variables`](https://mister-gold.pro/obsidian-apple-books-highlights-plugin/customization/templates-and-variables.html#template-variables) section in documentation for more information.

- **Reliable**:
- 🦾 **Reliable**:
- Import actual highlights with only the metadata you need. No visual noise with the deleted but still exported highlights, or, on the contrary, highlights and notes that make no sense without the context.
- Back up your highlights before each import to avoid accidental data loss (optional, but recommended).
- **Dataview-ready**: The default template creates highlights in a format that is compatible with [Dataview](https://blacksmithgu.github.io/obsidian-dataview/), so you can use your highlights in Dataview queries to unleash possible use cases even further (for example, to create a list of books you've read).
- **Up-to-date**: The plugin is updated regularly to support the latest versions of Obsidian, and Apple Books, as well as react to the users' feedback.

## Preview of imported highlights

![Preview](preview.png)

## How to install

### Outside of Obsidian

1. Click the [link](https://obsidian.md/plugins?id=apple-books-import-highlights) (the same link you see in the "About" section of this repository) that will redirect you to the plugin's page on the Obsidian site.
1. Confirm the browser prompt to allow the website to open Obsidian.
1. In the Obsidian app:
1. Click **Install** on the plugin's page.
1. Click **Enable** right after installation.

### Inside Obsidian

1. Open **Settings**.
1. Click **Turn on community plugins**
1. Click **Browse** to list all available community plugins.
1. Search for **Apple Books - Import Highlights**.
1. Click **Install**.
1. Click **Enable** right after installation

Check Obsidian Help for more information about [Community plugins](https://help.obsidian.md/Extending+Obsidian/Community+plugins)

## How to use

- **Command palette**:
- `Cmd+P > Apple Books - Import Highlights: Import all`
- `Cmd+P > Apple Books - Import Highlights: From a specific book...`
- **Ribbon**: Click the plugin icon ![plugin-icon][icon-data-url] in the Ribbon (left sidebar)

## Customization

The plugin uses Handlebars and Markdown to customize the output of your highlights the way you want.
- 📚 **Dataview-ready**: The default template creates highlights in a format that is compatible with [Dataview](https://blacksmithgu.github.io/obsidian-dataview/), so you can use your highlights in Dataview queries to unleash possible use cases even further (for example, to create a list of books you've read).
- 🔄 **Up-to-date**: The plugin is updated regularly to support the latest versions of Obsidian, and Apple Books, as well as react to the users' feedback.

### Template variables
## What users say

- `{{{bookTitle}}}` - The title of the book.
- `{{bookId}}` - A unique identifier of the book. It is used to create a link to the book in Apple Books: `[Apple Books Link](ibooks://assetid/{{bookId}})`.
- `{{{bookAuthor}}}` - The author of the book.
- `{{{bookGenre}}}` - The genre of the book.
- `{{bookLanguage}}` - The language of the book.
- `{{bookLastOpenedDate}}` - The date when you last opened the book. See the [Date formatting](#date-formatting) section for more information.
- `{{bookCoverUrl}}` - The URL of the book cover.
- `{{annotations}}` - An array of all the annotations in the book. You can use `{{annotations.length}}` to get the total number of annotations you made in the book. Each annotation has the following properties:
- `{{{chapter}}}` - The chapter of the highlight in the book. It may not be available for all highlights due to the initial formatting of the book.
- `{{{contextualText}}}` - The text surrounding the highlight to give you more context. For example:
- If you highlight a part of a sentence, the - `contextualText` will contain the whole sentence.
- If you highlight parts of two adjacent sentences, the `contextualText` will contain both sentences.
- `{{{highlight}}}` - The highlighted text.
- `{{{note}}}` - A note you added for the highlight.
- `{{{highlightLocation}}}` - A unique identifier of the highlighted text. It is used to create a link to the highlighted text in Apple Books. For example: `[Apple Books Highlight Link](ibooks://assetid/{{bookId}}#{{highlightLocation}})`.
- `{{highlightStyle}}` - The style of the highlight. It can be one of the following values:
- `0` (underline)
- `1` (green)
- `2` (blue)
- `3` (yellow)
- `4` (pink)
- `5` (violet)
- `{{highlightCreationDate}}` - The date when you created the highlight. See the [Date formatting](#date-formatting) section for more information.
- `{{highlightModificationDate}}` - The date when you last modified the highlight. See the [Date formatting](#date-formatting) section for more information.
- 💬 *Nice work. This is really quick*. - **cmyplay**
- 💬 *I just wanted to say that I love your plugin. It’s exactly what I need with no frills*. - **civilserf**
- 💬 *I am very grateful for the plugin you developed, which has made organizing my reading notes much more convenient*. - **JeffreyGH10**
- 💬 *Love this! great work!* - **dschense**
- 💬 *Thanks for sharing this nice plugin*. - **modatwork**
- 💬 *Your plugin is super fast and useful!* - **weslau**

## Try it out

> [!NOTE]
> When customizing the template, make sure to wrap variables with triple curly braces (`{{{variable}}}`) to avoid escaping the HTML characters in Markdown files (default behavior).
>
> If you want escaped output, use double curly braces: `{{variable}}`.
[![Plugin's page on Obsidian forum](https://img.shields.io/badge/install_plugin-blue?style=for-the-badge&color=%237C3AED&logo=obsidian)](https://obsidian.md/plugins?id=apple-books-import-highlights)

### Date formatting
## Documentation

The plugin uses the `dateFormat` helper that takes a unix timestamp and the [datajs-compatible string of tokens](https://day.js.org/docs/en/display/format#list-of-all-available-formats) to format dates in the template. For example:
- [Get Started][get-started]
- [Settings][settings]
- [Templates and variables][templates-and-variables]

```hbs
// Template
{{dateFormat dateVariable "date format"}}
// Example
{{dateFormat bookLastOpenedDate "YYYY-MM-DD hh:mm:ss A Z"}}
// Result
2024-03-04 05:50:28 PM +01:00
// Example
{{dateFormat bookLastOpenedDate "ddd, MMM DD YYYY, HH:mm:ss Z"}}
Mon, Mar 04 2024, 17:50:28 +02:00
```

### Templates

> [!TIP]
> If you created a template you love and want to share it with others, you're welcome to do it in the [corresponding topic](https://github.com/bandantonio/obsidian-apple-books-highlights-plugin/discussions/32). Your contribution will also help others to get inspired and create their own templates.
#### Template with colored highlights

![template colors](template-colors.png)

```hbs
Title:: 📕 {{{bookTitle}}}
Author:: {{{bookAuthor}}}
Genre:: {{#if bookGenre}}{{{bookGenre}}}{{else}}N/A{{/if}}
Language:: {{#if bookLanguage}}{{bookLanguage}}{{else}}N/A{{/if}}
Last Read:: {{dateFormat bookLastOpenedDate "YYYY-MM-DD hh:mm:ss A Z"}}
Link:: [Apple Books Link](ibooks://assetid/{{bookId}})
{{#if bookCoverUrl}}![Book Cover]({{{bookCoverUrl}}}){{/if}}
## Annotations
Number of annotations:: {{annotations.length}}
{{#each annotations}}
----
- 📖 Chapter:: {{#if chapter}}{{{chapter}}}{{else}}N/A{{/if}}
- 🔖 Context:: {{#if contextualText}}{{{contextualText}}}{{else}}N/A{{/if}}
{{#if (eq highlightStyle "0")}}- 🎯 Highlight:: <u>{{{highlight}}}</u>
{{else if (eq highlightStyle "1")}}- 🎯 Highlight:: <mark style="background:rgb(175,213,151); color:#000; padding:2px;">{{{highlight}}}</mark>
{{else if (eq highlightStyle "2")}}- 🎯 Highlight:: <mark style="background:rgb(181,205,238); color:#000; padding:2px;">{{{highlight}}}</mark>
{{else if (eq highlightStyle "3")}}- 🎯 Highlight:: <mark style="background:rgb(249,213,108); color:#000; padding:2px;">{{{highlight}}}</mark>
{{else if (eq highlightStyle "4")}}- 🎯 Highlight:: <mark style="background:rgb(242,178,188); color:#000; padding:2px;">{{{highlight}}}</mark>
{{else if (eq highlightStyle "5")}}- 🎯 Highlight:: <mark style="background:rgb(214,192,238); color:#000; padding:2px;">{{{highlight}}}</mark>
{{/if}}
- 📝 Note:: {{#if note}}{{{note}}}{{else}}N/A{{/if}}
- <small>📅 Highlight taken on:: {{dateFormat highlightCreationDate "YYYY-MM-DD hh:mm:ss A Z"}}</small>
- <small>📅 Highlight modified on:: {{dateFormat highlightModificationDate "YYYY-MM-DD hh:mm:ss A Z"}}</small>
{{/each}}
```

[get-started]: https://mister-gold.pro/obsidian-apple-books-highlights-plugin/guide/get-started.html
[settings]: https://mister-gold.pro/obsidian-apple-books-highlights-plugin/guide/settings.html
[templates-and-variables]: https://mister-gold.pro/obsidian-apple-books-highlights-plugin/customization/templates-and-variables.html

## Contributing

Expand All @@ -162,5 +54,3 @@ Ready to contribute? Check the [Contributing guidelines](CONTRIBUTING.md) to get
Your feedback and ideas are more than welcome and highly appreciated! Join the discussion in:
- [Obsidian Forum](https://forum.obsidian.md/t/new-plugin-apple-books-import-highlights/76856)
- [GitHub Discussions](https://github.com/bandantonio/obsidian-apple-books-highlights-plugin/discussions)

[icon-data-url]: data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyMCIgaGVpZ2h0PSIyMCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiM5MTkxOTEiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0ibHVjaWRlIGx1Y2lkZS1ib29rLW9wZW4iPjxwYXRoIGQ9Ik0yIDNoNmE0IDQgMCAwIDEgNCA0djE0YTMgMyAwIDAgMC0zLTNIMnoiLz48cGF0aCBkPSJNMjIgM2gtNmE0IDQgMCAwIDAtNCA0djE0YTMgMyAwIDAgMSAzLTNoN3oiLz48L3N2Zz4=
46 changes: 46 additions & 0 deletions docs/.vitepress/config.mts
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
import { defineConfig } from 'vitepress'

// https://vitepress.dev/reference/site-config
export default defineConfig({
lang: 'en-US',
title: "Apple Books\nImport Highlights",
description: "Import your Apple Books highlights and notes to Obsidian",
base: '/obsidian-apple-books-highlights-plugin/',
themeConfig: {
// https://vitepress.dev/reference/default-theme-config
logo: '/logo.svg',
nav: [
{ text: 'Home', link: '/' },
{ text: 'Get Started', link: '/guide/get-started' }
],

search: {
provider: 'local',
},

sidebar: [
{
text: 'Guide',
items: [
{ text: 'Getting Started', link: '/guide/get-started' },
{ text: 'Settings', link: '/guide/settings' }
]
},
{
text: 'Customization',
items: [
{ text: 'Templates and variables', link: '/customization/templates-and-variables' },
]
}
],

socialLinks: [
{ icon: 'github', link: 'https://github.com/bandantonio/obsidian-apple-books-highlights-plugin' }
],

footer: {
message: "Released under the <a href='https://github.com/bandantonio/obsidian-apple-books-highlights-plugin/blob/master/LICENSE' target='_blank'>MIT License</a>.",
copyright: "Copyright © 2024-present <a href='https://github.com/bandantonio' target='_blank'>Anton Zolotukhin</a>",
},
}
})
22 changes: 22 additions & 0 deletions docs/.vitepress/theme/custom.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
:root {
--vp-c-brand-1: #1cb941;
--vp-c-brand-1-bg: #1cb941;
--vp-button-brand-bg: #1cb941;
--vp-c-brand-2: #747bff;
--vp-home-hero-name-color: transparent;
--vp-home-hero-name-background: -webkit-linear-gradient(
120deg,
var(--vp-c-brand-1),
var(--vp-c-brand-2)
);
}


.vp-doc strong {
color: var(--vp-c-brand-2);
}

img[alt="plugin-icon"] {
height: 20px;
display: inline-block;
}
5 changes: 5 additions & 0 deletions docs/.vitepress/theme/index.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import './custom.css'

export default DefaultTheme
Binary file added docs/assets/colored-highlights.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/plugin-preview.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/showcase-dark.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/showcase-light.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit e154122

Please sign in to comment.