Edit docs to clarify role of static folder (#329)

This commit is contained in:
Daniel Sockwell 2018-07-14 03:07:36 -04:00 committed by Vincent Prouillet
parent 9e62651777
commit 9dd206d925

View file

@ -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).