Skip to content
New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Jump to bottom

Add option to export annotations in markdown #6141

Closed
wants to merge 1 commit into from
Closed

Add option to export annotations in markdown #6141

wants to merge 1 commit into from

Conversation

acelaya
Copy link
Contributor

@acelaya acelaya commented Jan 25, 2024 •
edited

Closes #6111

This PR adds a new annotations export format, Markdown.

Some decisions

  • I initially considered using the HTML format and parsing it to Markdown for simplicity, but it presented some problems:

    • We don't have a dependency to do that. The most used and up-to-date one seems to be turndown, however, in order to render tables, we needed a plugin to add GitHub markdown flavor, and the only one is very outdated (6 years since last release) and lacks TS definitions, even via "definitely typed" project, and ultimately, it didn't work, leaving table markup unparsed.
      I looked for other options, but none of them seemed great.
    • The HTML structure seemed a bit too complex for markdown. A result which is between the plain text and the HTML ones, seems more sensible.

    This made me decide to manually render the markdown instead, as we do with other formats.

  • As mentioned above, and in order to have something closer to the text format, I decided to use bullet points for the summary and annotations info, as opposed to tables as we do in HTML.

  • Since annotations text contains markdown, I decided to keep it like that, as it is consistent with the export format. However, I wrapped in a pre, as a way to "escape" it and avoid breaking the overall format.

  • Quotes are wrapped in a blockquote, but trimming every line, otherwise their meaning changes and can potentially render differently depending on where the markdown is used.
    For example, GitHub interprets extra indentation as a pre block.

Testing steps

  1. Open the export annotations panel.
  2. Select Markdown from the format dropdown.
  3. Click "Export" -> You should get a file with md extension containing the markdown.
  4. Click "Copy to clipboard" -> It should copy the same markdown to the clipboard.
  5. Paste the result in a new GitHub issue and click "Preview" -> It should properly render everything.

Todo

  • Add tests
  • Come up with a description for Markdown.
  • Decide the right short title. Currently used just MD as Markdown does not fit the size of the dropdown, but maybe we want to increase that size instead.

@codecov Codecov
Copy link

codecov bot commented Jan 25, 2024 •
edited

Codecov Report

Attention: 21 lines in your changes are missing coverage. Please review.

Comparison is base (acfcd6b) 99.44% compared to head (3d210e0) 99.24%.

Files Patch % Lines
src/sidebar/services/annotations-exporter.tsx 12.50% 21 Missing ⚠️
Additional details and impacted files 
@@            Coverage Diff             @@
##             main    #6141      +/-   ##
==========================================
- Coverage   99.44%   99.24%   -0.21%     
==========================================
  Files         263      263              
  Lines       10115    10137      +22     
  Branches     2412     2421       +9     
==========================================
+ Hits        10059    10060       +1     
- Misses         56       77      +21

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

@acelaya acelaya force-pushed the export-annotations-markdown branch 2 times, most recently from a2389e6 to 3257bf7 Compare January 25, 2024 15:42
@robertknight
Copy link
Member

I suggest adding a new feature flag for this, so that we can refine it independently of the other export formats.

@robertknight
Copy link
Member

I left some general feedback about the whole concept of feature in https://hypothes-is.slack.com/archives/C1M8NH76X/p1706524246864219?thread_ts=1706179435.023739&cid=C1M8NH76X. In short, I think the initial stab at an implementation here shows that there are a bunch of design decisions about the export that we need to work through.

I think these undermine the idea that this is could be "easy" to do well. We could instead leave the issue open and collect input on things like how users would like to use the markdown export, and which tools they want to import into. This will affect things like whether we produce something that is very like the existing HTML export (eg. with a bunch of tables grouped into sections) or something different.

@acelaya
Copy link
Contributor Author

acelaya commented Jan 30, 2024

I will close this PR for now, until further discussions have happened and there's more clarity about how we want to address the different issues.

@acelaya acelaya closed this Jan 30, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
project: export formats
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Support exporting annotations in Markdown format
2 participants
@acelaya @robertknight