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"]
|
||||
```
|
||||
|
||||
## 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