Proof-of-concept: Markdown support for Bukuserver #801
Replies: 2 comments 2 replies
-
|
…Added another comment for some optional modifications that I came up with |
Beta Was this translation helpful? Give feedback.
-
|
…Also added thumbnails support to the script (scaled down to fit x4 in a row; intended to be linked to the full image). Applied by having image alt text starting with
|
Beta Was this translation helpful? Give feedback.
-
|
…Implemented support for (some) Markdown extensions, and particularly custom elements using Directives; including a Thumbnail with Full Image Viewer Dialog directive. Considering the complexity of all these mods (especially the Thumbnail directive), I've also added another file to the gist, containing a fully modded userscript (with all of the mods applied), Screenshotslong example
source: | H1 | H2 | H3 |
|---------|---------|---------|
| This cell spans 3 columns |||
| H1 | H2 |
|--------------|---------|
| This cell | Cell A |
| spans three ^| Cell B |
| rows ^| Cell C |
##[note the :br for linebreak!]
| This header spans two :br || Header A |
| columns _and_ two rows ^|| Header B |
|-------------|--------------|----------|
| Cell A | Cell B | Cell C |
:::::table
::::tr
::td[_This_ table has **no** header!]
:::td
And also...
Paragraphs in cells!
:::
::::
:::::
##[gotta use container mode in order to nest directives]
:::::details{open}
::summary[_Collapsible_ content]
::h1["Centered header" -- with ASCII punctuation...]{.text-center}
:[Abbreviation]{style="color:green"} example: :abbr[HTML]{title="HyperText Markup Language"}.
I. roman numbered list
a. alphabetical
b. numbering
II. 2nd entry
A. Alphabetical
B. Numbering
##[description list]
::::dl
::dt[foo]
:::dd
:[1]{style="color:red"}
###
Because of container mode being used here,
this text will be rendered in a paragraph.
###
:::
::dt[bar]
::dd[2]
::dt[baz]
::dd[3]
::::##[dl (just marking for convenience)]
``Example of how :ins[inline comments] are #[not] rendered.''
:::::##[details]
### ...headings still work
Also, you can escape ::\:directives with `\` -\-- but you need `\\` to escape periods and dashes\\...
and `\\\` to escape a backslash before a dash or a period (for whatever reason)\\\\.thumbnail with full image viewer dialogUsage example: :thumb[https://images.gog-statics.com/585207428de200a4e827011f98bc9ebd2403b9a2f0a69d4017a580f754737edf_prof_gallery_250x140.jpg]{name="Game map", full="https://images.gog-statics.com/585207428de200a4e827011f98bc9ebd2403b9a2f0a69d4017a580f754737edf.jpg"}
|
Beta Was this translation helpful? Give feedback.
-
|
This really looks great! |
Beta Was this translation helpful? Give feedback.
-
Usecase
Suppose you want to have customizable bookmark descriptions (with rich-text styling, tables, additional links, images, etc.)
The simplest (as in, quick-and-dirty) approach for that would be to write bookmark descriptions in some markup language, then render these descriptions as HTML. Sure, it would not allow you to do any complex stuff with it (such as properly searching by some of that information, e.g. by a specific author or last update – unless it's also present in tags, which is not always a viable option); and previously existing descriptions may not always be rendered well, if they were not written with this idea in mind. But aside from these issues, it would give the user a flexible way of customizing any bookmark description(s) to a rather wide extent.
For instance, the data supplied by a custom bookmarklet could be then formatted in a presentable way.
Setup & usage
Here's the gist containing a (proof-of-concept) implementation of a markdown description renderer. (See also the implementation notes at the bottom.)
In order to have it running, you'll need to install a userscript manager in your browser (preferably Tampermonkey); then add the script from the gist as a userscript. (This will likely involve opening the dashboard in your userscript manager, clicking the "New Userscript" button, and replacing the default template with the contents of the file from the gist… and then saving it, of course. Alternatively, just click the "Raw" button on the gist file: it appears to trigger Tampermonkey script installation for
.user.jsfiles.)Additionally, you can apply some optional modifications (by editing the installed script as described within the comment). Alternatively, you can install the modded version of the script instead.
After that, the script code will be executed during load time in any of your Bukuserver pages (as long as it's accessed as
http://localhost:5000/; if you have a different base URL, you may want to adjust the@matchline of the script accordingly). It will parse all plain-text descriptions as Markdown and replace them with their rendered equivalent, keeping track of in-page dialogs to apply the same change within them (i.e. "View Record" dialog). Additionally it will add a preview button to the Description field in the Edit Record form (including the bookmarklet popup).See also Q&A section for extra usage hints.
Screenshots (usage example)
Here's my usage example:
@bukukeywordThere's also a couple extra screenshots to show off how image spacing can be customized.
Full description in this example:
(you can format tables in a more human-readable manner if you like)
…Though you might need to enable monospace font in the Description input (
textarea {font-family: monospace}) if you want such formatting to be accurate 😅creating a description (bookmarklet popup)
(note that the stuff below the form was added by a different userscript)
previewing a description (bookmarklet popup)
(the image is rendered as left-floating because the alt text I've specified for it begins with
<)saved bookmark details (bookmarklet popup)
saved bookmark (bookmarks list, view dialog)
making the image centered
(the image is rendered as a centered block when alt text begins with
^)making the image right-floating
(the image is rendered as right-floating when alt text begins with
>)See also below for thumbnails support.
Q&A
So what is this thing anyway? And how does it work?
It's a userscript (custom script that is injected by a browser extension that runs on arbitrary websites), which loads an external JS library and uses it to parse raw descriptions as Markdown and render the equivalent HTML on page (including in bookmark edit form, as a toggleable preview mode).
Markdown itself is pretty human-readable, so descriptions written in it should not look bad when they aren't run through a renderer – i.e. if you turn it off. …This would apply to CLI output as well, if not for the fact that it strips linebreaks from the printed descriptions 😅
(For more information check out the implementation notes.)
What formatting features exactly do I get here?
Here's a link to the specs of the library I'm using for rendering Markdown.
TL;DR: in addition to the basic Markdown syntax, it appears to support the following extended features:
It also supports HTML fallthrough, which allows for disclosure widgets (aka "accordions"/expandable content).
If you're used to GitHub-flavoured Markdown, keep in mind the fact that a single linebreak in the source is not normally rendered as a linebreak (
<br/>) in the resulting text, unless preceded by a double-space (Note that I'm adding
target="_blank"to all generated hyperlinks in descriptions, so clicking on any of them opens a new tab. (This is necessary for preview and bookmarklet popups… and the script has no direct access to theOPEN_IN_NEW_TABsetting anyway.)What's HTML fallthrough and how do I use it?
You can include raw HTML* in your Markdown. While normally it's something to be avoided, you can have collapsible sections like this:
Note that the blank line is necessary in GitHub-flavoured Markdown (to switch off the raw HTML mode), but not in case of this particular library.
* (The rendering library doesn't really sanitize fallthrough HTML at all; so it's a good thing that Bukuserver is a single-user application 😅 …If you're wondering,
<script>tags seem to have no effect, but<style>tags apparently affect any elements rendered after them.)So what was that thing about image spacing?
I've added some custom styling based on the first character of the image alt text. I.e.:
orwill produce a left-/right-floating image respectivelywill produce a centered image blocknow works as thumbnails, e.g. for screenshotsNote that for those non-inlined images (i.e. centered or floating), you may want to place them in a separate paragraph (i.e. separated with blank lines from surrounding text in Markdown source, like in the example); this is both better semantically and avoids some minor issues with resulting spacing.
I've tried adding an image but it's not loading on Bukuserver page; what do I do?
Not all servers allow their images to be displayed on external sites. Your options here would be as follows:
A recommended way of dealing with the latter issue would be to scale down the image and convert it to WebP with a good compression coefficient first (75% is both smaller in size than the equivalent JPEG, and does not degrade visually unlike said JPEG). This functionality is provided by my custom bookmarklet userscript (it's used for fetching the story image on
fiction.live,forums.spacebattles.com&www.scribblehub.com); all you need here is just copy the link of the image rendered by it below the bookmarklet form.(Note that even for a compressed image, the dataURL is going to be long. I'm talking tens of thousands of characters here. …For non-compressed images it could be millions though 😄)
…Alright, I've checked it out; now what?
Despite being a proof-of-concept, this script is already usable as-is. Its functionality could probably be added later into Bukuserver itself, but that would need to be opt-in; so I'm thinking of implementing it as a plugin (…when I actually get there 😅).
Until then, you can probably just use this script. It shouldn't even break after the Bootstrap4 migration gets merged in.
Beta Was this translation helpful? Give feedback.
All reactions