diff --git a/docs/content/documentation/content/overview.md b/docs/content/documentation/content/overview.md index c5eac346..c2e30d1a 100644 --- a/docs/content/documentation/content/overview.md +++ b/docs/content/documentation/content/overview.md @@ -63,3 +63,42 @@ the public web site. You can achieve this by simply setting `ignored_content` in ``` ignored_content = ["*.xlsx"] ``` + +## Static assets + +In addition to placing content files in the `content` directory, you may also place content +files in the `static` directory. Any files/folders that you place in the `static` directory +will be copied, without modification, to the public directory. + +Typically, you might put site-wide assets (such as the site favicon, site logos or site-wide +JavaScript) in the root of the static directory. You can also place any HTML or other files that +you wish to be included without modification (that is, without being parsed as Markdown files) +into the static directory. + +Note that the static folder provides an _alternative_ to colocation. For example, imagine that you +had the following directory structure (a simplified version of the structure presented above): + +```bash +. +└── content + └── blog +    ├── configuration + │    └── index.md // -> https://mywebsite.com/blog/configuration/ +    └── _index.md // -> https://mywebsite.com/blog/ +``` + +If you wanted to add an image to the `https://mywebsite.com/blog/configuration` page, you would +have three options: + * You could save the image to the `content/blog/configuration` folder and then link it with a + relative path from the `index.md` page. This is the approach described under **colocation**, + above. + * You could save the image to a `static/blog/configuration` folder and link it in exactly the + same way as if you had colocated it. If you do this, the generated files will be identical to + if you had colocated; the only difference will be that all static files will be saved in the + static folder rather than in the content folder. Depending on your organizational needs, this + may be better or worse. + * Or you could save the image to some arbitrary folder within the static folder. For example, + you could save all images to `static/images`. Using this approach, you would no longer be able + to use relative links, but could use an absolute link to `images/[filename]` to access your + image. This might be preferable for small sites or for sites that associate images with + multiple pages (e.g., logo images that appear on every page).