Skip to content

Add sphinx_copybutton extension to allow copying from code blocks - #846

Open
nathandyer wants to merge 4 commits into
mainfrom
copybutton
Open

Add sphinx_copybutton extension to allow copying from code blocks#846
nathandyer wants to merge 4 commits into
mainfrom
copybutton

Conversation

@nathandyer

Copy link
Copy Markdown
Contributor

I'm filing this PR so we can begin a discussion about whether or not this is something we want to include in our docs.

As part of the docs re-org and the new Book theme (🙏️ @ChumOfChance), it was previously mentioned that it would be really nice if we could include a copy button within code blocks in our docs. This PR enables that functionality via the sphinx-copybutton extension.

For example:

Screenshot From 2026-08-31 10-58-42

Although this extension hasn't seen an update in a few years, I think that's because it's a relatively minimal extension with only a small amount of Javascript + CSS to make it work. I'm not sure there's really that much to update or maintain.

This is nice because for people who are setting up SecureDrop from a daily driver system with Javascript enabled, this provides copy/paste functionality for longer commands. And in environments where Javascript is not enabled, this fails gracefully (there's just not a copy/paste button displayed).

Is this something we might want to consider?

Test plan

  • CI is happy
  • Visual review
  • Discussion outcome is that the team is OK with moving forward with these changes

Checklist

This change accounts for:

  • local preview of changes beyond typo-level edits

@nathandyer nathandyer moved this to Ready For Review in SecureDrop Aug 31, 2026
@legoktm

legoktm commented Aug 31, 2026

Copy link
Copy Markdown
Member

+1 to adding the functionality, neutral on the package itself vs writing/forking/vibecoding our own, clipboard.js seems pretty overkill for what we need here (but no actual issues other than it using deprecated functionality).

@ChumOfChance

Copy link
Copy Markdown
Contributor

I'm +1 for this. Big quality of life improvement. I would err on whatever solution is the easiest to integrate, so an old reliable extension seems best! I have not looked at it in a local build, but I'd want to make sure it looks OK on different sized devices, doesn't bug out on any unusual code blocks, etc.

@zenmonkeykstop zenmonkeykstop left a comment

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.

extension itself looks good! If possible, enabling its prompt detection features to not display it for non-command-line snippets (eg the gpg output in /admin/installation/prepare_sdw.html), and display it only for cut-n-pasteable commands would be cool. (It also needs a rebase.)

@nathandyer nathandyer moved this from Ready For Review to Under Review in SecureDrop Sep 2, 2026
@nathandyer

Copy link
Copy Markdown
Contributor Author

Thanks @zenmonkeykstop! I've taken another pass here, and have disabled the copy button on blocks that should not be copy-and-pasted from. This should be ready for another review.

I'll wait to hear your feedback from this approach before doing the same in the related dev docs PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Under Review

Development

Successfully merging this pull request may close these issues.

4 participants