Clarify favicon addition instructions in documentation

[chrisdavidmills]

Description

Updated instructions for adding favicons to make them clearer.

Motivation

Additional details

Related issues and pull requests

Fixes #41837

[github-actions]

Preview URLs

• /en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links
• /en-US/docs/Learn_web_development/Core/Structuring_content/Webpage_metadata

Flaws (5)

URL: /en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links
Title: Creating links
Flaw count: 1

• macros:
  • Can't resolve /en-US/curriculum/

---

URL: /en-US/docs/Learn_web_development/Core/Structuring_content/Webpage_metadata
Title: What's in the head? Web page metadata
Flaw count: 4

• macros:
  • Can't resolve /en-US/curriculum/
• unknown:
  • No generic content config found
  • no blog root
  • no blog root

External URLs (1)

URL: /en-US/docs/Learn_web_development/Core/Structuring_content/Creating_links
Title: Creating links

• https://www.mozilla.org/en-US/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2025-11-13 15:53:26)

[Josh-Cena]

I think the main confusion is that we are mixing "directory" and "URL". If you use any framework the "directory" of the site (if there's such a concept at all) is not going to be the same thing as the root URL (such as the OP which has templates as the site directory, but not every file under templates will become the root of the site). Rather, you want to serve the favicon at /favicon.ico via whatever capability your tool provides, such as a static or public folder. Although you can technically place it anywhere, it's canonically at /favicon.ico, because if you do so you don't have to add a <link> at all: all browsers can automatically get this icon. Some external tools might even not read the HTML document at all and assume favicons at this location.

[chrisdavidmills]

Seems to me like you're overthinking this. Here we are talking about basic, static HTML, and by "directory", I'm talking about the physical folder on your computer. The reader of this is unlikely to be using a framework. Maybe I should just say "folder", update the URL to "/favicon.ico", and mention in a note that if it is placed here, most browsers will pick it up automatically?

[Odysseus-GH24]

Hello. I have set up the framework 'Flask' some time ago, and this was indeed what confused me. As time passed, and my experience with web development being quite new, I somehow considered the Flask directories architecture as a basic HTML one. I only heard about the addition of favicons being a thing in Flask a day or two later in its documentation. I guess a small note talking about this would be nice? This was a head scratcher for me. I hope you won't curse me and my family for 10 generations, @chrisdavidmills.

[chrisdavidmills]

@Odysseus-GH24 I stand corrected! I think the curses are all mine ;-)

Seriously, this is really interesting direct reader feedback, and also highlights the danger of making assumptions.

I'll update it tomorrow.

[chrisdavidmills]

Ok, I've made some more updates. I also took this opportunity to update the paths and URLs primer, to add some more details, distinguish between paths and URLs, and show how the two relate. That stuff was originally written about 10 years ago...

[Odysseus-GH24]

Hi, @chrisdavidmills. I read the favicon part and the note you wrote is great! I find it clear and easy to understand.