docs(manifest): Improvements to `name`, `short_name`, `start_url`

[dipikabh]

Description

This work is part of improving the web/manifest docs.

Notable changes in this PR:

• name and short_name:

  • Added "Description" (info from spec plus some general guidelines) and "See also" sections
  • Removed reference to dir and lang because they are not implemented (https://developer.mozilla.org/en-US/docs/Web/Manifest)
  • Updated examples and added prose

• start_url:

  • "Description" and "Privacy considerations" sections cover info from the spec
  • Added more explanation in examples

Motivation

To ensure all sections have sufficient explanation, all caveats from spec are covered, and the pages follow a similar template

Additional details

• Spec links:
  • https://w3c.github.io/manifest/#name-member
  • https://w3c.github.io/manifest/#short_name-member
  • https://w3c.github.io/manifest/#start_url-member

Related issues and pull requests

Tracking issue: https://github.com/mdn/mdn/issues/560

[github-actions[bot]]

Preview URLs

• /en-US/docs/Glossary/Application_context
• /en-US/docs/Web/Manifest/name
• /en-US/docs/Web/Manifest/short_name
• /en-US/docs/Web/Manifest/start_url

(comment last updated: 2024-10-22 13:38:54)

[dipikabh]

@hamishwillee, I'll apply whatever we decide in the icons PR (for syntax and keys) here.

[hamishwillee]

Cool. I might need another ping after you do that.

[dipikabh]

Hi @hamishwillee, I've updated the Syntax blocks as per the new format.

[dipikabh]

Thanks Hamish. This took an unexpected turn with start_url and I've gone back and on forth on its content (with clarifications yet to come). Could you please read through "Description" and "Examples" again because I reverted the "Values" section.

Thanks a lot for reviewing the glossary page that I added later in the cycle. I've opened a BCD PR now but we need not hold up landing this.

[hamishwillee]

OK, added a few minor comments.

W.r.t.

For security reasons, the start_url must be same-origin with the manifest URL. If a non-same-origin start_url is specified, browsers will fallback to using the page that links to the manifest as the default starting page.

That's probably correct. My understanding is that usually you'd have the manifest in a folder, and link it from a html file "index.html" in the same folder. YOu can be pretty sure that whatever page you have in that folder is likely to be your intended start page.

[dipikabh]

Thanks, @hamishwillee. I fixed a few nits and reverted some text so that it is closer to what the spec suggests.

I'll merge this now.