112 lines
4.6 KiB
Markdown
112 lines
4.6 KiB
Markdown
Certainly! Let's create a focused guide on how to use the standardized Markdown template for festival documentation with MkDocs. This guide will help you efficiently create, maintain, and publish detailed festival descriptions using the template we've developed.
|
|
|
|
### Guide to Using the Festival Documentation Template with MkDocs
|
|
|
|
#### Step 1: Prepare Your MkDocs Environment
|
|
|
|
1. **Install MkDocs**: If you haven't already installed MkDocs, install it via pip:
|
|
```bash
|
|
pip install mkdocs
|
|
```
|
|
|
|
2. **Create a New MkDocs Project**:
|
|
- Initialize a new MkDocs project by running:
|
|
```bash
|
|
mkdocs new colombian_festivals
|
|
```
|
|
- This creates a new directory with a basic configuration file (`mkdocs.yml`) and a document folder.
|
|
|
|
3. **Project Structure**:
|
|
Navigate to the `colombian_festivals` directory. You'll see the following structure:
|
|
```
|
|
colombian_festivals/
|
|
├── docs/
|
|
└── mkdocs.yml
|
|
```
|
|
|
|
#### Step 2: Implement the Festival Template
|
|
|
|
1. **Create a Festivals Directory**:
|
|
- Inside the `docs` directory, create a subdirectory named `festivals`.
|
|
- This will host individual Markdown files for each festival.
|
|
|
|
2. **Use the Template**: Reference the standardized Markdown template [provided earlier](#markdown-template-for-festival-documentation). For each festival:
|
|
- Create a new Markdown file within the `festivals` directory (e.g., `Carnaval_de_Barranquilla.md`).
|
|
- Fill in the festival-specific details in place of the placeholder text.
|
|
|
|
#### Step 3: Customize Your MkDocs Configuration
|
|
|
|
1. **Edit `mkdocs.yml`**:
|
|
- Configure your MkDocs settings and navigation by adding entries for each festival document in the `mkdocs.yml` file under the `nav` section:
|
|
```yaml
|
|
site_name: Colombian Festivals
|
|
nav:
|
|
- Home: index.md
|
|
- Festivals:
|
|
- Carnaval de Barranquilla: festivals/Carnaval_de_Barranquilla.md
|
|
- Another Festival: festivals/Another_Festival.md
|
|
```
|
|
|
|
#### Step 4: Writing Content
|
|
|
|
- **Follow the Structure**: When filling out each festival's Markdown file, strictly adhere to the sections outlined in the template to maintain consistency across documents.
|
|
- **Adding Images**: Place images in the `docs/images/` directory and reference them in the Markdown files using relative paths.
|
|
|
|
#### Step 5: Build and Preview Your Site
|
|
|
|
1. **Build the Site**:
|
|
- From the root of your project (`colombian_festivals`), build the static site by running:
|
|
```bash
|
|
mkdocs build
|
|
```
|
|
- This compiles your Markdown files into a static HTML website.
|
|
|
|
2. **Local Preview**:
|
|
- Preview your site locally by running:
|
|
```bash
|
|
mkdocs serve
|
|
```
|
|
- Visit `http://127.0.0.1:8000` in your browser to see how your site looks.
|
|
|
|
#### Step 6: Deploy Your Site
|
|
|
|
- **GitHub Pages**: If you're using GitHub, you can easily deploy your MkDocs site to GitHub Pages:
|
|
- Push your project to a GitHub repository.
|
|
- Enable GitHub Pages in the repository settings and set the branch to `gh-pages`.
|
|
|
|
### Summary
|
|
|
|
This guide provides a straightforward method to document festivals using MkDocs and the predefined Markdown template. By following this structured approach, you can create a comprehensive and navigable documentation site that is easy to maintain and update. Each festival document will be consistent in layout and design, ensuring a professional presentation of the festival information.
|
|
|
|
---
|
|
|
|
---
|
|
name: "Carnaval de Barranquilla"
|
|
location: "Barranquilla, Colombia"
|
|
date: "Pre-Lent (February or March)"
|
|
frequency: "Annually"
|
|
established: "1888"
|
|
attendance: "Over 1 million"
|
|
main_attractions: "Parades, music, dance, costumes"
|
|
---
|
|
|
|
## Overview
|
|
The Carnaval de Barranquilla is one of the most colorful and significant cultural events in Colombia, celebrated with vibrant parades, elaborate costumes, and rhythmic music that fills the city.
|
|
|
|
## History
|
|
The Carnaval has roots that trace back to the 19th century, blending indigenous, African, and European traditions to create a unique and explosive expression of culture and joy.
|
|
|
|
## Photo Gallery
|
|
|
|
|
|
## Event Highlights
|
|
- **Day 1: The Battle of Flowers** - The official opening parade featuring floats decorated with flowers and led by the Carnival Queen.
|
|
- **Day 2: The Grand Parade** - A showcase of dance groups and costumed performers celebrating folkloric traditions.
|
|
|
|
## Visitor Information
|
|
For those planning to attend the Carnaval, it is advisable to book accommodations well in advance, be prepared for large crowds, and stay hydrated in the warm climate.
|
|
|
|
## References
|
|
- [Official Carnaval Website](https://www.carnavaldebarranquilla.org)
|
|
- [Visit Barranquilla Tourism](https://www.visitbarranquilla.com)
|