The _static directory and how to use it for images and other static resources

[72757373656c6c]

I have all static resources under the "_static" directory, which was created by sphinx-quickstart.

Under the "_static" directory there is a "css" subdirectory and then multiple subdirectories that reflect the markdown directory structure and are used to contain everything but markdown (all static resources), like images, pdfs, html, that are required by my markdown file(s).

Example "source" directory structure

 source_dir   
     _static_dir
         css_dir
             files.css
         topic1_dir
             sub_topic_dir
                 images.webp
                 pdfs.pdf
                 texts.txt
             images.webp
             pdfs.pdf
             texts.txt
             sub_topic_dir
                 images.webp
                 pdfs.pdf
                 texts.txt
         topic2_dir
     conf.py
     index.md
     markdowns.md
     topic1_dir
         sub_topic_dir
             index.md
             markdowns.md
         sub_topic_dir
             index.md
             markdowns.md
         index.md
         markdowns.md    
     topic2_dir
         index.md
         markdowns.md 

I noticed that during the html build, images are copied from "source/_static/directories/" to "build/html/_images/". If there are duplicate names from the "_static/directories" when copied, a number is appended to the basename (device.webp, device1.webp, ...).

Also, the entire "source/_static" directory is copied to "build/html/_static", so the images now reside in two places in the build directory.

There is an option in conf.py to specify the logo location:

html_logo = "_static/img/mylogo.webp"

There is an option in conf.py to speciy the css location:

html_css_files = [ "css/main.css", ]

Note

html_css_files is relative to html_static_path

I didn't find any option to control image location. Is there?

During the html build, the location is converted from the "_static/directories" location to the "_image" location.

A file.md might contain:

 :::{image} /_static/system/device/image.webp
 :::

And the make html becomes:

  <img alt="..." src="../../_images/image.webp">

When I look at the Images and figures examples, the markdown shows "img/fun-fish.png" which get converted to "../_images/fun-fish.png" in the html. Looking at MyST-Parser at github, I do see "docs/syntax/img" directory. "docs/_static" seems to only contain the css and the logo images.

The stackoverflow¹ topic below said it was a "convention" to have a _static directory in every folder. "Ruh Roh ❓" 😖 It referenced html_static_path. Mine is set to _static. The SO¹ is almost 2 years old, so I'm wondering how should things work now.

To access those static resources, like pdfs or html, I use the .external class. In the issues, it seemed like users were using "<a href" html.²

[Some text](/docroot/_static/dir/file.pdf){.external}

Am I using the "_static" directory as intended?

---

Footnotes

1. Prevent MyST from changing .md image paths ↩ ↩²

2. How to refer to a static resource ↩

[chrisjsewell]

Heya just a quick note; you may get better off asking this in https://github.com/orgs/sphinx-doc/discussions, as obviously this side of things are mainly out of the control of myst-parser itself

[72757373656c6c]

Ok. Thank you.

It's sometimes difficult to know exactly where to go with these things 😄 I just want to layout the structure in the way that works best using sphinx-mystparser.

I have found the {.external} class useful. There seems to be multiple ways to do cross references (accessing resources, linking) and there are side effects to some of them. I've converted a couple of documents from asciidoc.py, so learned a lot, found some things out, and now tweaking.