Deep Links And PKM integration

[dragarok]

This is adding deep link integration and pkm integration so that one can create pages, navigate to exports, add page, add books, folders etc. from their pkm of choice: e.g. Obsidian, Logseq, Emacs etc.
Previously, I had added copy links which did some of that partially but needed very domain specific ideas. This just maintains simpler index using json which any system can read with ease and build workflow around it so that the integration just feels awesome.
Example of how I am using this in my emacs workflow on Boox Tab Ultra C as well as my other android devices:
https://github.com/dragarok/doom-emacs-private-config/blob/daa6302f692adf5d2abde1aa1f905980ce8da267/lisp/notable.el

[Ethran]

On first glance looks good. I didn't understand the intention for previous "copy link for obsydian", and it was laying unattached, in messy state. It will be good to replace it.

I added few comments, mostly to move one thing from router to separate file, and some questions. I will do deeper review later.

[Ethran]

is this the only think that changed in db, that requires migration?

I don't see exactly why its needed, where its used. For now, I mostly generated page names to contain "quick pages" or page number in notebook.

It might be useful to have names for separate pages in notebook, but for now I don't see a need for it.

[dragarok]

Quick pages don't have names and can pile up without us understanding what's under the hood. Previous logic works quite well and this doesn't change anything for the end user. If they want to rename manually, then they can. Else, it is exactly the same. And doesn't disrupt older database either.

[Ethran]

Ok, seems ok.

[Ethran]

why some features are boox only?

[Ethran]

Did you fixed it? Don't remove comments not related to your pr (exceptions: very stupid comments.)

[Ethran]

I feel like it should be in separate file.

[Copilot]

Pull request overview

This PR adds deep link integration and a JSON index export system to enable external Personal Knowledge Management (PKM) tools like Emacs, Obsidian, and Logseq to integrate with Notable. The implementation replaces the previous clipboard-based link copying approach with a more maintainable solution.

Changes:

• Implements a deep link API using the notable:// scheme for navigation, creation, export, and sync operations
• Adds a JSON index exporter that generates metadata about folders, notebooks, and pages for external tool consumption
• Introduces page naming support with a UI for renaming pages and displaying page names in the library view

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
docs/deep-links.md	Comprehensive documentation of the deep link API, JSON index structure, and Emacs integration
docs/export-formats.md	Removed references to clipboard-based link copying
app/src/main/java/com/ethran/notable/io/IndexExporter.kt	New JSON index exporter with debounced export scheduling
app/src/main/java/com/ethran/notable/ui/Router.kt	Deep link handler with navigation, creation, and export operations
app/src/main/java/com/ethran/notable/MainActivity.kt	Integration points for index export on startup and app pause
app/src/main/java/com/ethran/notable/io/ExportEngine.kt	Cleanup of clipboard-related code and ExportOptions simplification
app/src/main/java/com/ethran/notable/editor/ui/PageMenu.kt	Added page rename dialog UI
app/src/main/java/com/ethran/notable/ui/components/ShowPagesRow.kt	Display page names below thumbnails
app/src/main/java/com/ethran/notable/data/db/Page.kt	Added nullable name field and getAll() method
app/src/main/java/com/ethran/notable/data/db/Folder.kt	Added getAll() and getByTitle() methods
app/src/main/java/com/ethran/notable/data/db/Notebook.kt	Added getAll() method
app/src/main/java/com/ethran/notable/data/db/Db.kt	Database version bump to 35 with auto-migration
app/src/main/java/com/ethran/notable/data/db/Kv.kt	JSON decoder updated to ignore unknown keys for backward compatibility
app/schemas/com.ethran.notable.data.db.AppDatabase/35.json	New database schema with Page.name field

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The documentation states that creation links require "Onyx Boox system API" but does not explain what happens if these links are invoked on non-Boox devices. Based on the code in Router.kt, the creation operations will execute on any Android device, not just Boox. Either the code should check for Boox devices before allowing creation, or the documentation should be updated to clarify the actual behavior.

[Copilot]

The documentation mentions using folder paths like "Work/Projects" but the deep link handler uses simple folder name lookups without path resolution. This inconsistency between documentation and implementation will confuse users. Either implement hierarchical folder path resolution in the code or update the documentation to clarify that only folder names (not paths) are supported.

[Copilot]

The alignment is hardcoded using the full package path instead of using a predefined constant or the imported Alignment. This is verbose and reduces readability. Consider using Alignment.CenterHorizontally directly since it's already imported.

Suggested change

	horizontalAlignment = androidx.compose.ui.Alignment.CenterHorizontally
	horizontalAlignment = Alignment.CenterHorizontally

[Copilot]

The getByTitle query only returns one folder when multiple folders with the same title can exist. This will cause unpredictable behavior when creating pages in folders via deep links, as the query will arbitrarily select one matching folder. Consider using a combination of folder name and parent path to uniquely identify folders, or document that folder names must be unique in the documentation.

[Copilot]

The deep link handler processes intent data every time the Router is recomposed, even though deepLinkHandled is checked. However, if the intentData parameter changes (e.g., a new intent arrives while the app is running), the deepLinkHandled flag will prevent processing. Consider resetting deepLinkHandled when intentData changes, or using intentData itself as the LaunchedEffect key.

[Copilot]

The folder name parameter lookup in createNewBook uses only title matching, which will fail or return an arbitrary folder if multiple folders have the same name. Consider using the full folder path or implementing hierarchical resolution for consistency with other folder operations.

[Copilot]

The scheduleExport method creates a new CoroutineScope for each call rather than using a shared scope. This could lead to resource leaks if many exports are scheduled rapidly. Consider using a single CoroutineScope tied to the application lifecycle or using the existing lifecycleScope from the calling context.

[Copilot]

The ExportEngine methods are called with context and perform database operations on the IO dispatcher, but there's no error handling or user feedback if the export fails. The export result is only logged. Consider propagating errors to provide user feedback or at least ensure the errors are visible in the logs.

[Copilot]

The exportNow method creates a new CoroutineScope for each call, which is unnecessary and could cause resource leaks. Since this method is already being called from an IO context or doesn't need to be async, consider making it a regular suspend function and removing the CoroutineScope.launch wrapper.

Suggested change

	fun exportNow(context: Context) {
	CoroutineScope(Dispatchers.IO).launch {
	try {
	val index = buildIndex(context)
	writeIndex(index)
	log.d("Index exported: ${index.folders.size} folders, ${index.notebooks.size} notebooks, ${index.pages.size} pages")
	} catch (e: Exception) {
	log.e("Failed to export index", e)
	}
	}
	}
	/**
	* Export the index synchronously (for use in deep link handlers).
	*/
	suspend fun exportNow(context: Context) {
	try {
	val index = buildIndex(context)
	writeIndex(index)
	log.d("Index exported: ${index.folders.size} folders, ${index.notebooks.size} notebooks, ${index.pages.size} pages")
	} catch (e: Exception) {
	log.e("Failed to export index", e)
	}
	}
	/**
	* Export the index synchronously (for use in deep link handlers).
	*/
	* Export the index synchronously (for use in deep link handlers).
	*/

[Copilot]

The page is fetched once during initialization but is not updated if the page is modified elsewhere. If the page is deleted or modified by another process before the user clicks Save, the update will fail silently or use stale data. Consider using a mutableState with a snapshot or re-fetching the page before updating.

[Ethran]

functions:
createNewBook, createNewFolder, createNewPageInFolderByName, createNewPageInBookIfNotExists, createNewPageIfNotExists
seem to be mostly extensions of already existing logic in HomeView.kt.
Namely: onCreateNew, HomeView.kt line 300; and getNextPageIdFromBookAndPageOrCreate in AppRepository line 26.

I would propose to make those functions just a methods in class AppRepository, and making them more generic, cleaning up logic for creation of new pages throughout repo.

Disclaimer: I'm not entirely sure if this is good idea, maybe you will find a better/cleaner solution for it.

[dragarok]

On first glance looks good. I didn't understand the intention for previous "copy link for obsydian", and it was laying unattached, in messy state. It will be good to replace it.

I added few comments, mostly to move one thing from router to separate file, and some questions. I will do deeper review later.

Yeah that was what was added so that text-based note taking and drawing-based note taking tools could be worked together. I had a workflow where I had a deep link that I would create in obsidian and it would open notable to let me draw about that page and auto export it. And for when I worked on the note in notable itself and wanted to link it to some text-based note in obsidian, I could grab the link and copy paste it. That was the intention behind copy link for obsidian when I created it.
Right now as well, The intention is this: Notable has all the awesome features to create hand written notes. If we expose some of the functionalities as deep link and simpler index instead of full database which can grow into unmanageable sizes when there are too many notebooks, too many strokes; then anyone can build the tool they want in their note taking of choice to use that index to navigate to the note they want, create new page, etc. without any other complex functionality on Notable's part. So, this was my first messy take on how we could do it. I can refine it based on your feedback too.

From my end, the summary is this:
I think any solution needs to expose a database like index so that any app can make use of it. And then deep links so that one can take action to and from Notable. I would love your recommendations on how we can make it effective. And then I will either create a new branch altogether with what we can do or make the suggested edits to reflect clarity.

[Ethran]

If we expose some of the functionalities as deep link and simpler index instead of full database which can grow into unmanageable sizes when there are too many notebooks, too many strokes;

For me, db isn't that big, around 500 MB after a year of use (I will check exact number later). Device has a lot of storage, so up to 5 GB of db size is in my opinion acceptable.

One thing that could be reasonable to do, is adding 'workspace': adding ability to lunch app with different db. Other than that I don't see a point in splitting db in smaller pieces.

---

I don't know if any better solution exists for what you want to do. I will do a quick search to see if it's the best way of doing it.

[Ethran]

@dragarok Ok, I checked what can be done. It seems that ContentProvider for creating, and querying the available notebooks would be better, but a little bit more complicated.

For now I see it as follows:

• Deep links for opening the notebooks, pages, etc, but not for creating, modifying existing structure.
• separate PR implementing ContentProvider (or whatever is better for this) for modifications, querying and creations.
  I don't like the json index idea, if I understood it correctly. You meant this index to be updated overtime db changes, so other apps can discover new notebooks, pages, etc?

[dragarok]

@dragarok Ok, I checked what can be done. It seems that ContentProvider for creating, and querying the available notebooks would be better, but a little bit more complicated.

For now I see it as follows:

* Deep links for opening the notebooks, pages, etc, but **not** for creating, modifying existing structure.

* separate PR implementing ContentProvider (or whatever is better for this) for modifications, querying and creations.
  I don't like the json index idea, if I understood it correctly. You meant this index to be updated overtime db changes, so other apps can discover new notebooks, pages, etc?

Yeah in terms of size and storage, I am not saying that its big. And with text based tools like obsidian or logseq or any other for that matter, handling a sqlite database vs handling a json file, the plaintext file always wins. The main advantage is that the plaintext file doesn't need to be synced two way. Its just one way replay of database's current state during only certain actions.
I too will research on how to use content provider or similar logic for modifications. The usefulness of index file comes from being able to use it in devices that don't have notable as well, very simple devices like a kindle.
I too can research on how Obsidian plugins work for note creation etc. as well.
I've been busy this week. I will share a screenshare of how I use it as well so that we can implement something meaningful with a proper structure too.