Edit docs to clarify role of static folder (#329)
This commit is contained in:
parent
9e62651777
commit
9dd206d925
|
@ -63,3 +63,42 @@ the public web site. You can achieve this by simply setting `ignored_content` in
|
||||||
```
|
```
|
||||||
ignored_content = ["*.xlsx"]
|
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).
|
||||||
|
|
Loading…
Reference in a new issue