Skip to content
New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

#

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Jump to bottom

Markdown|OPML export with image assets sidecar folder (macOS) #204

Open
marc-medley opened this issue Sep 26, 2023 · 3 comments
Open

Markdown|OPML export with image assets sidecar folder (macOS) #204

marc-medley opened this issue Sep 26, 2023 · 3 comments

Comments

@marc-medley
Copy link

marc-medley commented Sep 26, 2023 •
edited
Loading

Problem

Both the Markdown *.md and OPML *.opml exported files (on macOS) reference the images used in the outline. However, the images are not actually exported. The absence of the image assets leaves the export as "incomplete".

ExampleOutlineScreen

Example_Outline.md exported image reference:

## Item With Image

![](0422E898-3983-4BE1-B568-B83E1F60A2AD.png)

Example_Outline.opml exported image reference:

<body>
  <outline text="Item With Image" _note="![](0422E898-3983-4BE1-B568-B83E1F60A2AD.png)"/>
</body>

Candidate Solution: Asset Files Sidecar Folder

A candidate solution would be to export the images in original form (e.g., *.jpg, *.png, …) into a sidecar folder. The addition of the sidecar folder with image assets would provide the user with a "complete" export of both text and images in an accessible, editable, and post-processable form.

  1. export the images to a *_files sidecar folder
  2. place relative path image references in the *.md and *.opml files.
.
├── Example_Outline.md
├── Example_Outline.opml
└── Example_Outline_files
    └── 0422E898-3983-4BE1-B568-B83E1F60A2AD.png

Example_Outline.md relative path reference:

## Item With Image

![](Example_Outline_files/0422E898-3983-4BE1-B568-B83E1F60A2AD.png)

Example_Outline.opml relative path reference:

<body>
  <outline text="Item With Image" _note="![](Example_Outline_files/0422E898-3983-4BE1-B568-B83E1F60A2AD.png)"/>
</body>

Sidecar_Screen_00

Discussion

Markdown

Many Markdown renderers will display images directly with a relative address to a sidecard *_files folder …i.e. no additional Markdown postprocessing needed in these scenarios. Contexts where I've successfully used a *_files assets sidecar folder for Markdown are:

  1. Atom Markdown (discontinued)
  2. GitHub
  3. GitLab
  4. MacDown
  5. Visual Studio Code: Markdown Preview Enhanced
  6. VSCodium: Markdown Preview Enhanced

Checkout the GitHub markdown file md_evaluation.md which is an example that uses assets in md_evaluation_files.

OPML

The OPML 2.0 Specification does not provide any expressly stated provisions on how to handle images. Thus, how images are handled is not generally portable between OPML compatible applications. Even so, the export of images into an OPML *_files sidecar folder provides the benefits:

  1. Complete export of text and image data for the user.
    • Complete data makes post-processing by the user possible.
  2. Complete import of OPML+Images is feasible with a *_files sidecar.
    • Other application could elect to also support this sidecar folder plus relative path convention.

Possible Enhancement

Human Readable Image Filenames

Ideally the original filename would also be stored and then later used as the exported image's filename. Reusing the user's original filename aligns with a core Markdown objective to keep Markdown text human readible.

Export filename-collision-avoidance strategies, while still keeping a human readable name, could include:

  1. Consider files with the same original name and size as the same file.
    • It is a convenience to the user to have images which were used in multiple outline locations to be "re-merged" in the sidecar folder.
  2. Append "Width x Heigth" _WxH to images with same name that are of different sizes.
    • The addition of _WxH provides additional useful information to the user.
  3. Add an index to the image names which are not resolved by steps (1) and (2). For example, Book_000.png and Book_001.png

Example_Outline folder tree with human readable image names:

.
├── Example_Outline.md
└── Example_Outline_files
    ├── Aardvark.png
    ├── Book_000.png
    ├── Book_001.png
    ├── Cycle_128x128.png
    └── Cycle_256x256.png

Example_Outline.md with human readable relative path reference:

## Item With Image

![](Example_Outline_files/Cycle_128x128.png)
@vincode-io
Copy link
Owner

Thanks for the detailed and well thought out enhancement request.

I have considered doing something like Sidecar Folders in the past and ruled it out. I can't remember why at the moment though. Most likely it was because the lack of standardization in the respective specs. Certainly the issue is worth revisiting to see if that decision was valid or not.

If you need something like this immediately, you could write a shortcut for it. Look at the Archive Account shortcut in Shortcut Examples to get an idea of how it could be done.

@marc-medley
Copy link
Author

marc-medley commented Sep 28, 2023 •
edited
Loading

Certainly the issue is worth revisiting

Thanks.

… lack of standardization in the respective specs.

Here are some thoughts related to the "standardization" aspect of this issue:

  1. Standards Compatible. Is the proposed approach compatible with the Markdown & OPML standards? Yes, the approach respects and exists within the existing Markdown or OPML markup syntax.

  2. Open & Free. Could other software use the same approach? Yes, it's an open process with both an open content approach and with no license requirements.

  3. Acceptance. How much use will this approach get? Hard to guess. However, the upside potential is quite large. Consider, for example, that John Gruber's 2004 Markdown post on Daring Fireball has had a far reaching impact to content, workflows, and source code. No formal standard committee to review & launch. Markdown was openly published, free, and sensible to use.

  4. text-to-HTML. Markdown was introduced as a "text-to-HTML conversion tool for web writers". Can a *_files sidecar folder be used in a text-to-HTML workflow? Yes. HTML generated from markdown will correctly reference and render the items from a *_files/* path on the local desktop browser. In some cases, the *.html-*_files pair can be published directly. In other cases, the *_files directory path convention can be used to recognize and automate remapping of referenced paths when publishing to a particular remote server. i.e. works out-of-the-box locally and is compatible with more advanced automation.

  5. "De Facto" Basis. Are there any examples of a *_files sidecar approach in wide use today? Yes, with HTML. Look at the Brave, Chrome, Edge, Firefox, and Waterfox web browsers. Their "Save page as" action with "Format: Webpage, complete" creates an *.html file with an associated *_files sidecar folder. That's about 80% of all desktop browsers worldwide according to Statcounter Global Stats.

    Detail Note: The Brave, Chrome, and Edge browsers will prepend ./ to the HTML relative path; however, Firefox and Waterfox do not. The ./ prefix has not been needed in any of the Markdown editors that I have used. As such, I don't add ./ to the relative path just to keep the text less cluttered.

    Workflow Note: The saved "Format: Webpage, complete" *.html-*_files pair can be converted to a functional Markdown *.md-*_files pair with Pandoc.

    File: HtmlToMarkdown.sh.command

    #!/bin/zsh
### Add `.command` extension to make executable script double-clickable on macOS

cd "$(dirname "$0")"

FILE_IN="FileAttachments.html"
FILE_OUT="FileAttachments.md"

pandoc \
  --wrap=none \
  --markdown-headings=atx \
  --from=html \
  --to=markdown_strict+space_in_atx_header \
  --output="$FILE_OUT" \
  "$FILE_IN"

@vincode-io
Copy link
Owner

I'm sold. Look for this in a future release.

@marc-medley marc-medley mentioned this issue Nov 29, 2023
Open
@vincode-io vincode-io mentioned this issue Dec 24, 2023
Closed
# for free to join this conversation on GitHub. Already have an account? # to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@marc-medley @vincode-io