# File Names and Structure

When contributing to the Umbraco documentation, it is useful to know how to structure directories, files, and images.

In this article, you'll get an overview of the file structure and learn about the naming conventions used for elements in the structure.

## File names

How files, directories, and images are named is important for consistency, but also for ensuring continuous compatibility with GitBook, where the Documentation sites are hosted.

* All file and directory names must use **lowercase**.
  * Exception: Name all parent articles `README.md`, and name the surrounding directory using the title of the `README.md` file.
* Use **hyphens** (`-`) instead of spaces.
* Use the **title of the article** when naming the associated file.
* Give images descriptive names matching the content associated with them.

## File structure

The overall structure of the Umbraco documentation is divided by version and product. Each Umbraco version has its own directory, and in those, each product has its own directories with articles and images.

Diving one step deeper, each individual topic is contained in its own directory.

Each directory must have a `README.md` file which will act as a landing page for that directory and a parent page to all other articles added within.

Images are stored in the `.gitbook/assets/` directory at the root of the repository. This is the recommended location for all images.

* `.gitbook` *(directory)*
  * `/assets` *(directory)*
    * `dashboard-view.png`
    * `content-section.png`
* `/topic` *(directory)*
  * `README.md`  (*landing page/parent article*)
  * `another-article.md`
  * `/subtopic` *(directory)*
    * `README.md` (*landing page/parent article*)
    * `article.md`
    * `another-article.md`

{% hint style="info" %}
Many existing articles still reference images from a local `/images/` directory next to the `.md` file. This structure remains valid while the documentation is being migrated to use `.gitbook/assets/` directory.
{% endhint %}

## Documentation Navigation 

Independent of how the files are structured in the directories, it is the `SUMMARY.md` file that ultimately determines how the documentation navigation is displayed.

Each product directory has a `SUMMARY.md` file wherein all articles related to that product are listed.

It is possible to add groups to separate the article into sections. This is done using two `#` symbols followed by the section name: `## Fundamentals` .

{% hint style="warning" %}
An article is not available on the public documentation site unless it is listed within the `SUMMARY.md` file.
{% endhint %}

## Structural Changes

These changes include moving an article to a different section, renaming or deleting an article as well as adding a new article.

When either of the actions above occurs, it needs to be tracked in two files: `.gitbook.yaml` and `SUMMARY.md`.

### Moving an article

When an article is moved to a different section/directory, follow these steps:

1. Update the relative path to the file in the closest `SUMMARY.md` file.
2. Move the article link in the `SUMMARY.md` file to the correct section.
3. Add a redirect to the `redirects` section of the closest `.gitbook.yaml` file.
   1. *Example*: `relative/path/to/current/location: relative/path/to/new/location.md`

### Renaming an article

When an article is renamed, follow these steps to track the changes:

1. Update the Title and the relative path to the file in the closest `SUMMARY.md` file.
2. Add a redirect to the `redirects` section of the closest `.gitbook.yaml` file.
   1. *Example*: `path/to/current-name: path/to/new-name.md`

### Deleting an article

When an article is deleted from the documentation, follow these steps to avoid broken links:

1. Remove the file from the closest `SUMMARY.md` file.
2. Add a redirect to the `redirects` section of the closest `.gitbook.yaml` file.
   1. Point to either the article's replacement or to the parent article.
   2. *Example*: `path/to/article: path/to/new-article-or-parent.md`

### Adding a new article

When a new article is added, it must also be added to the `SUMMARY.md` file to show up in the published documentation:

1. Add the article to the `SUMMARY.md` file like this:
   * Example: `* [Article Title](path/to/article.md)` 


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.umbraco.com/contributing/documentation/style-guide/structure.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.