File conventions

Our docs have a few conventions around files.

Naming

When creating new files, follow specific conventions for your naming.

Filenames should:

• Semantically communicate the purpose of the file
• Be lowercased
• Use dashes between words
• Only use _index.md for a single file under folders

Acceptable file names

/fundamentals/concepts/what-is-cloudflare.md
/assets/images/api-shield/api-shield-call-sequence.png

Unacceptable file names

/fundamentals/concepts/What is Cloudflare.md
/fundamentals/concepts/What-is-Cloudflare.md
/fundamentals/concepts/what-is-cloudflare/index.md
/assets/images/api-shield/API_Image_1.png

These conventions are important for user readibility, SEO conventions, and making sure our GitHub actions do not break.

Folders

Each folder should have a file named _index.md.

/fundamentals/concepts/_index.md

This convention ensures that Hugo - our static site generator - treats the content as a section. The content at /fundamentals/concepts/_index.md will also be rendered at https://developers.cloudflare.com/fundamentals/concepts/.

Content files

Add regular content files to the /content/{product_folder}/ directory.

/content/fundamentals/concepts/what-is-cloudflare.md

Image files

Add image files to the /assets/images/{product_folder}/ directory.

/assets/images/api-shield/api-shield-call-sequence.png