If you're creating a single-page guide, create a single markdown file in the
guides directory:

```bash
# Create the file
touch content/guides/my-docker-guide.md
# or if you have Hugo installed:
hugo new content/guides/my-docker-guide.md
```

To create a multi-page guide, create a directory where each page is a markdown
file, with an `_index.md` file representing the introduction to the guide.

```bash
# Create the index page for the guide
mkdir content/guides/my-docker-guide.md
touch content/guides/my-docker-guide/_index.md
# or if you have Hugo installed:
hugo new content/guides/my-docker-guide/_index.md
```

Then create the pages for the guide under `content/guides/<dir>/<page>.md` as
needed. The [metadata](#metadata-for-guides) lives on the `_index.md` page (you
don't need to assign metadata to individual pages).

### Guides for specific frameworks or languages

For guides that demonstrate how to use Docker with a particular framework or
programming language, consider the following outline:

1. **Introduction**
   - Briefly introduce the framework or language in the context of Docker.
   - Explain what the user will achieve by the end of the guide.
   - List required software, tools, and knowledge.
2. **Development setup**
   - Guide the user through setting up a development environment.
   - Include instructions on writing or obtaining sample code.
   - Show how to run containers for local development.
3. **Building the application**
   - Explain how to create a Dockerfile tailored to the application.
   - Provide step-by-step instructions for building the Docker image.
   - If applicable, show how to test the application using Docker.
4. **Deploying with Docker**
   - Show how to run the application in a Docker container.
   - Discuss configuration options and best practices.
5. **Best practices and conclusions**
   - Offer tips for optimizing Docker usage with the framework or language.
   - Summarize key takeaways, suggest next steps, and further reading.

### Use-case guides

For guides focused on accomplishing a specific goal or use case with Docker
(e.g., deploying a machine learning model), use a flexible outline that ensures
a logical flow.

The following outline is an example. The structure should be adjusted to best
fit the content and ensure a clear, logical progression. Depending on the
subject matter of your use-case guide, the exact structure will vary.

1. **Introduction**
   - Describe the problem or goal.
   - Explain the benefits of using Docker in this context.
2. **Prerequisites**
   - List required tools, technologies, and prior knowledge.
3. **Setup**
   - Provide instructions for setting up the environment.
   - Include any necessary configuration steps.
4. **Implementation**
   - Walk through the process step by step.
   - Use code snippets and explanations to illustrate key points.
5. **Running or deploying the application**
   - Guide the user on how to execute or deploy the solution.
   - Discuss any verification steps to ensure success.
6. **Conclusion**
   - Recap what was achieved.
   - Suggest further reading or advanced topics.

## Example code

If you create an example repository with source code to accompany your guide,
we strongly encourage you to publish that repository under the
[dockersamples](https://github.com/dockersamples) organization on GitHub.
Publishing your source code under this organization, rather than your personal
account, ensures that the source code remains accessible to the maintainers of
the documentation site after publishing. In the event of a bug or an issue in
the guide, the documentation team can more easily update the guide and its
corresponding example repository.

Hosting the examples in the official samples namespace also helps secure trust
with users who are reading the guide.

### Publish a repository under `dockersamples`

To publish your repository under the `dockersamples` organization, use the