Skip to content

Export highlights: export backlinks to markdown - #14233

Merged
hius07 merged 10 commits into
koreader:masterfrom
hius07:export-backlinks
Sep 2, 2025
Merged

hius07 merged 10 commits into
koreader:masterfrom
hius07:export-backlinks

Conversation

@hius07

@hius07 hius07 commented Aug 27, 2025 •

Copy link
Copy Markdown
Member

Setting:
1

Highlight in the book:
2

Exported markdown document:
3

Closes #12955.


This change is Reviewable

@hius07 hius07 added the Plugin label Aug 27, 2025
end

-- Check if it is a link to a local file
local linked_filename = link_url:gsub("^file:(//)?", "") -- remove local file protocol if any

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I've seen file:path without the // (ie. file:/mnt/onboard/), may be in other contexts/browsers, so it feels good if we could support file:///mnt/... and file:/mnt/... even if some URI specs say // is required.
So the presence of (//)? in the original code, which seems to have been removed.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will do (the removed regexp doesn't work anyway).

Comment on lines +925 to +938
if pn_xp then
caller_callback = function(ui)
ui.link:addCurrentLocationToStack()
if ui.rolling then
ui.rolling:onGotoXPointer(pn_xp, pn_xp)
else
pn_xp = tonumber(pn_xp)
if pn_xp then
ui.paging:onGotoPage(pn_xp)
end
end
end
else
linked_filename = ffiutil.joinPath(self.document_dir, linked_filename) -- get full path

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No need for this joinPath in the case of ?pn_xp ?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You've supported relative links:

-- For relative local file links
local directory, filename = util.splitFilePathName(self.document.file) -- luacheck: no unused
self.document_dir = directory

Exporter adds full paths (book.file):
table.insert(tbl, "\n" .. T("[%1](<file:///%2?pn_xp=%3>)", _("View in book"), book.file, entry.pn_xp))

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You've supported relative links:

OK to keep supporting relative links.
But I can imagine a user/script using your new trick/api and creating local links in home made HTML files using relative links, href="other.pdf?pn_xp=12".
(Your exporter may not be the only thing ending up using this new pn_xp feature you're adding, so it would be good to keep supporting relative links in this case.)

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was going to distinguish abs/rel paths by the leading slash, but allowing various number of slashes in the prefix file:///, how can we do this?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dunno if the following is correct, but after 30s of thinking:

file:mnt/everest (impossible with proper file://) => relative
file:/mnt/everest (impossible with proper file://) => absolute
file://mnt/everest (having // means it's proper file://) => relative
file:///mnt/everest (having // means it's proper file://) => absolute

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The first two seem wrong but if they occur in the wild I suppose it doesn't hurt.

Comment on lines -925 to -928
else
UIManager:show(InfoMessage:new{
text = T(_("Link to unsupported local file:\n%1"), BD.url(link_url)),
})

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This different and more informative message ("unsupported local file") is gone? Users will get the more generic and less informative Invalid or external link ?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ReaderUI will show "File is not supported".

Comment thread frontend/apps/reader/readerui.lua Outdated
covers_fullscreen = true, -- hint for UIManager:_repaint()
document = document,
reloading = self.reloading,
caller_callback = self.caller_callback,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

May be another more explicite name ? caller_callback works when we call a function, but here, we will instantiate an object, so a more precise name like after_open_callback or post_postReaderReady_callback :) would be clearer.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm good with after_open_callback.

linked_filename = ffiutil.joinPath(self.document_dir, linked_filename) -- get full path
if anchor then
local count
pn_xp, count = anchor:gsub("^?pn_xp=", "") -- page number or xpointer

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are we all OK with this syntax ?
No real better idea.
I would have gone with a #something, but it would not be a real HTML id= (might be good to also support id=, but with EPUBs with multiple fragments, there may be multiple ids with the same name, so no obvious solution.
Are we ok with the name pn_xp (koreader technical) ? Or should it be generic/abstracted as ?pos= ?
Just asking for discussion, as we are defining some "external api" for the future we won't be able to change without breaking some other app or user scripts that will use it :)

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or should it be generic/abstracted as ?pos= ?

Totally agree with that.
I followed the code name, but in the md file it definitely should be more readable.
I'm okay with pos.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you choose the formatting for highlights in Blockquotes? It looks better aesthetically...

@hius07

hius07 commented Aug 28, 2025

Copy link
Copy Markdown
Member Author

Changes:
-position is exported to md file as ?pos=
-support of relative filepaths

Comment on lines 915 to 919
if linked_filename:find("?") then -- remove any query string (including any following anchor)
linked_filename, anchor = linked_filename:match("^(.-)(%?.*)$")
elseif linked_filename:find("#") then -- remove any anchor
linked_filename, anchor = linked_filename:match("^(.-)(#.*)$")
end

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, document.epub#pos=blah will work as well as document.epub?pos=blah.
Dunno if we should allowing that, or not and just handle ?pos= (so #pos=blah could go to the first <div id="pos=blah"> in the epub if one day we want to support that).

@hius07 hius07 Aug 28, 2025 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes: handle bookmark position in the query string only, not in #.

@hius07
hius07 merged commit 2facbef into koreader:master Sep 2, 2025
@hius07
hius07 deleted the export-backlinks branch September 2, 2025 05:54
@hius07 hius07 added this to the 2025.10 milestone Sep 2, 2025
@eduardorodrigues08

Copy link
Copy Markdown

Could you choose the formatting for highlights in Blockquotes? It looks better aesthetically...

0xstillb pushed a commit to 0xstillb/koreader-thai that referenced this pull request May 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

FR: export highlights with backlinks

4 participants