Using SVG format instead of .png images

[bsmth]

Hi all 👋🏻

I think that using SVG for images (mainly diagrams) is something that would bring a lot of benefits for authors and readers.
I see these pros:

1. Maintenance: Authors can edit vector formats (e.g., fix a typo) using all kinds of tools (your IDE / online tools) and edit text or styles directly. Editing a .png usually involves recreating an asset from scratch or overlaying new or fixed content with image editing software - this can be fiddly, sometimes introduces visual or compression artifacts etc.
2. Git: SVG can be diffed by git. Editing a line of an SVG means the diff is constrained to that line. With binaries, the entire file is diffed, so a .png that's 1MB will increase the repository size by 1MB on each edit / check-in.
3. General asset size: A few of the SVG files I have converted from .png are around half the size of the original binaries. This is another reduction of the amount of data stored in git per asset file, and our built pages are more lightweight for readers.

My ask:

If you are working on pages that have .png assets and you think they can be converted:

• Recreate the diagram. If you're using Mermaid (https://www.mermaidchart.com);
  • Export as .svg and .mmd
  • Check the .mmd file in to https://github.com/mdn/shared-assets
• replace the image with the SVG in the page markdown
• Use SVGO to optimize the SVG
• add the label reduce binary assets to your pull request

Before:

└── example_page
    ├── index.md
    └── my_diagram.png <-- Binary

After:

└── example_page
    ├── index.md
    └── my_diagram.svg <-- SVG of "my_diagram.mmd"

If you're stuck, or would like someone else to convert it for you, ask us for help!

Labels:

I've created a label reduce binary assets which we can use to easily find issues and PRs for this initiative.

Example PR:

• feat: Add SVG diagrams for HTTP sequences content#31812

About Mermaid syntax:

There is a proposal for us to use Mermaid in content, and while we don't support it yet, there's potential for us to keep track of the Mermaid equivalents of diagrams until it is supported in future.

Sharing and editing diagrams when you have the Mermaid source is straightforward, for example, try copying and pasting the following mermaid source into https://www.mermaidchart.com:

```mermaid
%%{init: { "sequence": { "wrap": true, "width":250, "noteAlign": "center", "messageAlign": "center" }} }%%


sequenceDiagram
    participant Client
    participant Server

    Note left of Client: Request resource
    Client->>Server: GET /doc HTTP/1.1
    Note right of Server: Resource moved<br>Respond with new location
    Server-->>Client: HTTP/1.1 301 Moved Permanently<br/>Location: /doc_new

    Note left of Client: Request resource at new location
    Client->>Server: GET /doc_new HTTP/1.1
    Note right of Server: Return resource
    Server-->>Client: HTTP/1.1 200 OK
```

It renders in GFM anyway:

Example chart rendered in GFM:

%%{init: { "sequence": { "wrap": true, "width":250, "noteAlign": "center", "messageAlign": "center" }} }%%


sequenceDiagram
    participant Client
    participant Server

    Note left of Client: Request resource
    Client->>Server: GET /doc HTTP/1.1
    Note right of Server: Resource moved<br>Respond with new location
    Server-->>Client: HTTP/1.1 301 Moved Permanently<br/>Location: /doc_new

    Note left of Client: Request resource at new location
    Client->>Server: GET /doc_new HTTP/1.1
    Note right of Server: Return resource
    Server-->>Client: HTTP/1.1 200 OK

Loading

Focus area:

I think the HTTP docs are a great place to focus some effort. There are a few great candidates (sequence diagrams in PNG format). For those who are interested, I will reply to this discussion with a list of files that we can take a look at.

Thanks!

Thanks a lot, looking forward to your thoughts!

[bsmth]

I think the sequence diagrams under HTTP are a really great opportunity for housekeeping and optimization.
Aside from the fact that a lot of these diagrams are in need of a visual refresh in general, we can loop in some asset optimization for future us in the process.

Currently this looks like 42 images (not all are sequence diagrams, though):

find ./files/en-us/web/http -type f -name '*.png' | wc -l
      42

update:

There are 14 remaining as of Nov 2024:

find ./files/en-us/web/http -type f -name '*.png'

./files/en-us/web/http/content_negotiation/httpnego3.png
./files/en-us/web/http/content_negotiation/httpnegoserver.png
./files/en-us/web/http/content_negotiation/httpnego.png
./files/en-us/web/http/messages/binary_framing2.png
./files/en-us/web/http/messages/httpmsg2.png
./files/en-us/web/http/messages/httpmsgstructure2.png
./files/en-us/web/http/messages/http_request_headers3.png
./files/en-us/web/http/messages/http_response_headers3.png
./files/en-us/web/http/connection_management_in_http_1.x/http1_x_connections.png
./files/en-us/web/http/connection_management_in_http_1.x/httpsharding.png
./files/en-us/web/http/cors/errors/cors-error2.png
./files/en-us/web/http/caching/request-collapse.png
./files/en-us/web/http/caching/type-of-cache.png
./files/en-us/web/http/cookies/cookie-basic-example.png

[teoli2003]

For diagrams authored with mermaid, it will be more efficient to re-edit mermaid if we want to make changes.

We should store this mermaid code next to the generated .svg file. In the same repo. Obviously yari, should be smart enough not to deploy the mermaid file.

That way the svg file and the mermaid file will be next to each other.

[bsmth]

Thanks for the suggestion

For diagrams authored with mermaid, it will be more efficient to re-edit mermaid if we want to make changes.
We should store this mermaid code next to the generated .svg file. In the same repo.

I think that makes sense. If we end up with Mermaid support in markdown, we can get rid of the SVGs altogether and have them built/embedded into the rendered HTML at build time.

[bsmth]

After discussing this with the team & with engineering, we're going to put the .mmd files in https://github.com/mdn/shared-assets for now and we'll revisit putting them in the content repo in future.

[teoli2003]

Nobody will know they are there, so they'll be forgotten.

[bsmth]

Nobody will know they are there, so they'll be forgotten.

I also share that concern, but eng would like to keep .mmd out of the content repo until it's known whether we can inline them in markdown / include them as image sources, so we have to pump the brakes on adding the Mermaid for now, unfortunately.

[teoli2003]

I understand.

These files are PNGs because SVGs were not allowed back then, and the source files were stored elsewhere and… lost.

I'm really happy to see something like Mermaid coming. It will also help us unify the look and feel of diagrams throughout MDN.

[yin1999]

A note here: when we go ahead to use svg format instead of png images, we need to to notify the localization teams (as in mdn/translated-content we have a lot of fallback references to the images in mdn/content)

[bsmth]

At the moment, I think I can close this with a recommendation to use SVG where possible, and some information on where to put the assets. Adding this hint to writing guidelines in:

• feat: add info about where to put SVG assets content#37824

Thanks to everyone for the input and help!