forked from drowl87/hextra_mirror
b283227046
* feat: enhance image resolving * chore: don't process image path that begins with relative link * docs: add instruction for adding images * chore: update docs * chore: add filenames to images docs
126 lines
4.4 KiB
Markdown
126 lines
4.4 KiB
Markdown
---
|
||
title: Organize Files
|
||
weight: 1
|
||
prev: /docs/guide
|
||
---
|
||
|
||
## Directory Structure
|
||
|
||
By default, Hugo searches for Markdown files in the `content` directory, and the structure of the directory determines the final output structure of your website.
|
||
Take the example site as an example:
|
||
|
||
<!--more-->
|
||
|
||
{{< filetree/container >}}
|
||
{{< filetree/folder name="content" >}}
|
||
{{< filetree/file name="_index.md" >}}
|
||
{{< filetree/folder name="docs" state="open" >}}
|
||
{{< filetree/file name="_index.md" >}}
|
||
{{< filetree/file name="getting-started.md" >}}
|
||
{{< filetree/folder name="guide" state="open" >}}
|
||
{{< filetree/file name="_index.md" >}}
|
||
{{< filetree/file name="organize-files.md" >}}
|
||
{{< /filetree/folder >}}
|
||
{{< /filetree/folder >}}
|
||
{{< filetree/folder name="blog" state="open" >}}
|
||
{{< filetree/file name="_index.md" >}}
|
||
{{< filetree/file name="post-1.md" >}}
|
||
{{< /filetree/folder >}}
|
||
{{< /filetree/folder >}}
|
||
{{< /filetree/container >}}
|
||
|
||
Each of the `_index.md` files is the index page for the corresponding section. The other Markdown files are regular pages.
|
||
|
||
```
|
||
content
|
||
├── _index.md // <- /
|
||
├── docs
|
||
│ ├── _index.md // <- /docs/
|
||
│ ├── getting-started.md // <- /docs/getting-started/
|
||
│ └── guide
|
||
│ ├── _index.md // <- /docs/guide/
|
||
│ └── organize-files.md // <- /docs/guide/organize-files/
|
||
└── blog
|
||
├── _index.md // <- /blog/
|
||
└── post-1.md // <- /blog/post-1/
|
||
```
|
||
|
||
## Sidebar Navigation
|
||
|
||
The sidebar navigation is generated automatically based on the content organization alphabetically. To manually configure the sidebar order, we can use the `weight` parameter in the front matter of the Markdown files.
|
||
|
||
```yaml {filename="content/docs/guide/_index.md"}
|
||
---
|
||
title: Guide
|
||
weight: 2
|
||
---
|
||
```
|
||
|
||
{{< callout emoji="ℹ️">}}
|
||
It is recommended to keep the sidebar not too deep. If you have a lot of content, consider **splitting them into multiple sections**.
|
||
{{< /callout >}}
|
||
|
||
## Configure Content Directory
|
||
|
||
If we need to use a different directory for our content, we can do so by setting the [`contentDir`](https://gohugo.io/getting-started/configuration/#contentdir) parameter in our site configuration file.
|
||
|
||
## Add Images
|
||
|
||
To add images, the easiest way is to put the image files in the same directory as the Markdown file.
|
||
For example, add an image file `image.png` alongside the `my-page.md` file:
|
||
|
||
{{< filetree/container >}}
|
||
{{< filetree/folder name="content" >}}
|
||
{{< filetree/folder name="docs" >}}
|
||
{{< filetree/file name="my-page.md" >}}
|
||
{{< filetree/file name="image.png" >}}
|
||
{{< /filetree/folder >}}
|
||
{{< /filetree/folder >}}
|
||
{{< /filetree/container >}}
|
||
|
||
Then, we can use the following Markdown syntax to add the image to the content:
|
||
|
||
```markdown {filename="content/docs/my-page.md"}
|
||
|
||
```
|
||
|
||
We can also utilize the [page bundles][page-bundles] feature of Hugo to organize the image files together with the Markdown file. To achieve that, turn the `my-page.md` file into a directory `my-page` and put the content into a file named `index.md`, and put the image files inside the `my-page` directory:
|
||
|
||
{{< filetree/container >}}
|
||
{{< filetree/folder name="content" >}}
|
||
{{< filetree/folder name="docs" >}}
|
||
{{< filetree/folder name="my-page" >}}
|
||
{{< filetree/file name="index.md" >}}
|
||
{{< filetree/file name="image.png" >}}
|
||
{{< /filetree/folder >}}
|
||
{{< /filetree/folder >}}
|
||
{{< /filetree/folder >}}
|
||
{{< /filetree/container >}}
|
||
|
||
```markdown {filename="content/docs/my-page/index.md"}
|
||
|
||
```
|
||
|
||
Alternatively, we can also put the image files in the `static` directory, which will make the images available for all pages:
|
||
|
||
{{< filetree/container >}}
|
||
{{< filetree/folder name="static" >}}
|
||
{{< filetree/folder name="images" >}}
|
||
{{< filetree/file name="image.png" >}}
|
||
{{< /filetree/folder >}}
|
||
{{< /filetree/folder >}}
|
||
{{< filetree/folder name="content" >}}
|
||
{{< filetree/folder name="docs" >}}
|
||
{{< filetree/file name="my-page.md" >}}
|
||
{{< /filetree/folder >}}
|
||
{{< /filetree/folder >}}
|
||
{{< /filetree/container >}}
|
||
|
||
Note that the image path begins with a slash `/` and is relative to the static directory:
|
||
|
||
```markdown {filename="content/docs/my-page.md"}
|
||
|
||
```
|
||
|
||
[page-bundles]: https://gohugo.io/content-management/page-bundles/#leaf-bundles
|