18F / 18f.gsa.gov

The 18F website
https://18f.gsa.gov
Other
293 stars 311 forks source link

Refine code block styling #3955

Closed beechnut closed 3 months ago

beechnut commented 3 months ago

The technical tutorial I'm drafting for the blog looks kind of rough.

Screenshot of draft blog post

Problems

Nice-to-haves

$ command path/to/file
# ^^^^^^^^^^^^^^^^^^^^ this gets copied, but the $ doesn't
### Acceptance criteria
- [x] There's margin around code blocks and the code doesn't look cramped
- [x] Syntax highlighting for major languages and diff
- [x] One-liner code blocks have a different background color and font to offset them, but the font is the same size as surrounding normal text.
- [x] Bonus: Left rail with non-copyable line numbering
- [x] Bonus: A non-copyable filename that's set apart from but clearly associated with the code
- [ ] Bonus: Syntax highlighting for diff-{language} (e.g. diff-rb)
- [ ] Bonus: Option for non-copyable prompt character (e.g. bash `$` or zsh `%` or irb `>`)
- [ ] Bonus: a copy button to copy all the source code at once
beechnut commented 3 months ago

I think a possible solution here would be an addition to the Markdown filter that parses code blocks somewhat differently than standard.

\```diff-yaml
---
# Adds the filename to the top of the file, but it's not copyable in the same textarea as the code block
filename: docker-compose.yml
line_numbers: true # defaults to true
# Which lines to collapse, useful when showing diffs but wanting to still preserve line numbers
collapse:
  - 7 to 11
  - 14 to 16
  - 22 to end
---
version: "3"

services:

+  oracledb: &oracledb
    image: container-registry.oracle.com/database/express:21.3.0-xe
    volumes:
      - ${FOLDER_WITH_IMPORT_FILE}:/db/data
      - oracle_data_volume:/opt/oracle/
    ports:
      - 1521:1521
+    expose:
+      - 1521
    environment:
      - ORACLE_PWD=${ORACLE_PASSWORD}

+  import:
+    <<: *oracledb
+    profiles: ["utilities"]
+    command: impdp ${ORACLE_USER}/${ORACLE_PASSWORD}@oracledb:1521/XEPDB1 directory=db_data dumpfile=${FILE_TO_IMPORT}

volumes:
  oracle_data_volume:

Would produce something like

|------------------------------------
| docker-compose.yml                | <- copyable, but separate from source code
|------------------------------------
|  1 | version: "3"                                 [Copy icon]
|  2 | 
|  3 | services:
|  4 | 
|  5 | +  oracledb: &oracledb
|  6 |     image: container-registry.oracle.com/database/express:21.3.0-xe
|  ↕ | 
| 12 | +    expose:
| 13 | +      - 1521
|  ↕ | 
| 17 | +  import:
| 18 | +    <<: *oracledb
| 19 | +    profiles: ["utilities"]
| 20 | +    command: impdp ${ORACLE_USER}/${ORACLE_PASSWORD}@oracledb:1521/XEPDB1 directory=db_data dumpfile=${FILE_TO_IMPORT}
| 21 | 
|  ↕ |
      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ copyable source code

^^^^^ non-copyable line numbers