Update the project page

(Clarify how non-maintainers can help)

Below is my proposal for the Project page. I'll leave it open for comments for a week or so, and if I don't hear anything, then I'll publish it.

The Sitemap module displays one or more a human-readable lists of links (menu-items, taxonomy-term pages, book hierarchies, etc.) on a page. A sitemap is an alternative way for visitors to navigate your website: a sitemap is an overview/directory of notable pages on the site. Sitemaps tend to be useful for sites with lots of lightly-organized content, for example, colleges and universities, governments, or organizations with many lines-of-business.

Features

The Sitemap module displays a page at /sitemap, but you can change the path. You can customize the Title of this page, and add a rich-text description to the top of the page.

You can choose which sections to display on the Sitemap using a set of plugins that can be displayed in whatever order you choose. By default, a Site front page plugin is displayed (with a link to the site's front page), but you can enable more plugins as you require. Plugins can be configured to display their output in a different way.

There are plugins for each menu on the site (e.g.: Menu: Main navigation, Menu: Footer, etc.). If Drupal core's Taxonomy module is enabled, there will be plugins for each vocabulary (e.g.: Vocabulary: Tags). If both the the Book module → and the Sitemap book sub-module are enabled, you will see plugins for each Book (e.g.: Book: Products, if you have a book named "Products").

Developers can write their own Sitemap plugins to display whatever you want, using Drupal's Plugin API → .

Post-Installation

Install as you would normally install a contributed Drupal module → .

After installation, you can view the (not-yet-configured) sitemap at /sitemap. Configure the sitemap at /admin/config/search/sitemap. Set permissions for viewing and administering the sitemap at /admin/people/permissions/module/sitemap.

See the module's README.md file for detailed configuration instructions.

Additional Requirements

To display a link to the front-page, to display the contents of menus on your site, and to display links to terms in a vocabulary, then this module requires no additional modules outside of Drupal core.

To display links to pages in a book, you will need to install the Book module → (which was part of Drupal core in Drupal 10 and earlier; but is only available as a contributed module in Drupal 11 and later).

Recommended modules/libraries

If you maintain any contributed modules that enhance the functionality of Sitemap, please add it to Sitemap's ecosystem → by referencing it in the Ecosystem field on your project's page.

Here are some modules that extend Sitemap (that the Sitemap maintainers are aware of):

• Micro Sitemap → , which integrates Sitemap and the Micro Site module →

Similar projects

The Sitemap module (and its predecessor, Site map → ) aim to provide human-readable sitemaps: they do not aim to provide machine-readable sitemaps.

If you want to generate machine-readable sitemaps, consider the XML sitemap module → , the Simple XML sitemap module → , and the modules that extend them.

If you'd prefer to display a sitemap in your site's footer, instead of a standalone page, the Footer sitemap → renders a sitemap in a block that you can place in your theme's footer region. The Menu Manipulator Sitemap module → also displays the contents of a menu in a block, filtered by language, in order to work around the Drupal core bug 🐛 Untranslated menu items are displayed in menus Needs work .

If the Sitemap module is not powerful enough for you, and you would prefer to build an entirely custom sitemap, try combining the Field Menu module → (which lets you display the contents of a menu hierarchy in a field), with the Entity Views Attachment module → (which lets you display the contents of a View in a field) and Drupal Core's Views module (which provides many ways to list taxonomy terms and the entities associated with those terms).

Supporting this Module

The best way to support this module is to contribute to it! Contributions to add automated tests → are always welcome; and including tests in your bug reports, feature requests, etc. is a great way to fast-track your contributions! Automated tests allow the Sitemap maintainers to work faster, and they also help you, by detecting if a proposed change to Sitemap would break your site (i.e.: by detecting regressions)!

The Drupal Association (DA) → pays for the infrastructure that the Sitemap module maintainers use. Consider donating to the DA → to help keep Drupal.org → , the Drupal composer repository → , and automated tests running smoothly.

If you would like to hire a maintainer to add a feature to Sitemap that you want, please reach out to the maintainer through their contact form or their organization.

You asked for someone with technical writing experience to make suggestions, so I proofread it for you:

The Sitemap module displays one or more a human-readable lists of links on a page. A sitemap is a way for visitors to navigate your website via an overview of notable pages on the site. Sitemaps tend to be useful for sites with lots of lightly-organized content, for example, colleges and universities, governments, or organizations with many different units.

Features

• Configurable sitemap page path (default: /sitemap), title, and description.
• An extensible plugin API for displaying links to content based on Drupal entities. The module ships with plugins for these entity types:
  • Menus
  • Taxonomy vocabularies
  • Books (requires the sitemap_book submodule)

Installation

• Install as you would normally install a contributed Drupal module. →
• Configure the sitemap at /admin/config/search/sitemap.
• Set permissions for viewing and administering the sitemap at /admin/people/permissions/module/sitemap.

See the module's README.md file for detailed configuration instructions.

Extending modules

If you maintain any contributed modules that enhance the functionality of Sitemap, please add it to Sitemap's ecosystem by referencing it in the Ecosystem field on your project's page.

Similar projects

The Sitemap module provides human-readable sitemaps, not machine-readable sitemaps. If you want to generate machine-readable sitemaps, consider these options:

• XML sitemap →
• Simple XML sitemap →

Supporting this Module

The best way to support this module is to contribute to it! Contributions to add automated tests [7 issues] → are always welcome; and including tests in your bug reports, feature requests, etc. is a great way to fast-track your contributions! Automated tests allow the Sitemap maintainers to work faster, and they also help you, by detecting if a proposed change to Sitemap would break your site (i.e.: by detecting regressions)!

The Drupal Association (DA) → pays for the infrastructure that the Sitemap module maintainers use. Consider donating to the DA → to help keep Drupal.org → , the Drupal composer repository → , and automated tests running smoothly.

If you would like to hire a maintainer to add a feature to Sitemap that you want, please reach out to the maintainer through their contact form or their organization.

Notes:

• I mostly cut down on the amount of text. It was a lot to read.
• IMO, lists are good for people trying to ingest information quickly. Paragraphs are harder to parse.
• You can assume a certain level of knowledge already or that the information can be ignored. For instance, people don't need to be told about the Book module. If they need sitemaps for Books, then they'll already have Book installed. But if they don't need books, then you don't need to explain it.
• You're being overly generous by linking to Micro Sitemap, a module that has never been released and was never marked compatible with D10. I'd only link to serious projects or you waste the time of anyone who is looking for real extending modules. The same applies to Footer Sitemap (D7 only) and Menu Manipulator sitemap (D8 only, unmaintained, no releases).
• Noting that this module only does human-readable sitemaps is a good idea.
• Don't include the information about using Views and other modules to hack together sitemaps unless you want to field support questions about it.
• I left the Support section alone, but I would remove most of it except where you're implying that people can contact you about hiring you. But as for the rest: most serious contributors will know how to contribute already, but you could replace that paragraph with "Contact a maintainer or post an issue in the queue if you would like to know how you can help maintain the Sitemap module" or something similar. It's cool that you're promoting the DA, but to me it's just extra words to scroll past on what was already a really long page. It adds nothing to the information about the module, which is what this page is for.

@dcam, awesome, thank you! This looks great!

As mentioned at the top of #3, I'm going to give other maintainers/users until Wednesday, August 14th, 2024 to make any comments/suggestions before publishing.

(Since I also made a release yesterday, that should give users a bit of time to upgrade and/or report any bugs)

I hope to copy the intro bit from the project page to the README.md as well; and then hopefully I can create a release candidate.

I've deployed the new page! But I'm going to copy the opening blurb back to the README, so I'll open an MR with those changes shortly.

Updated the remaining tasks

Some outstanding items...

1. Submission guidelines
2. Module categories

For the submission guidelines, I think I'd like to say something about all only accepting patches/merge-requests if they include tests.

For the Module categories, we're currently using "Content Display", "Search Engine Optimization (SEO)", and "Site Structure". A full list of module categories and what they mean is documented in the Maintainership section of the Drupal documentation → .

For the module categories, I've gone through the list → and I think the existing 3 makes sense (I can only pick 3):

1. Content Display ("Configure the layout and format of content and data presented to site visitors.")
2. Search Engine Optimization (SEO) ("Manage or improve the site's search engine ranking by running audits, assessing metrics, or making the site’s content and data more digestible by search engines.")
3. Site Structure ("Extend the structure of the site by way of content models, data storage, field types, and navigation, so it is more understandable to users.")

For submission guidelines, I want them to be clear, short, and to-the-point. I am proposing...

The Sitemap maintainers would prefer to only accept patches/merge-requests that have passing automated tests. Automated tests ultimately benefit you, by ensuring that future changes will not break the functionality that your site depends on.

If you need help writing tests, please ask us!

... but if anyone (@dcam?) is able to proofread this and make suggestions, I would gladly accept them. I worry that this comes off as too blunt — I definitely do not want to put people off from contributing — but I do want to be upfront that I check that submissions have tests, and that all tests pass before merging them (unless there are exceptional circumstances).

Submission guidelines are displayed as a status message at the top of the page when you create a new issue, below the Security Issues warning, and below the "How to report an issue" help block, but before the "Issue metadata" section. At time-of-writing, the Drupal.org theme shows status messages with a green checkbox and a green background.

I have seen Submission Guidelines on various projects but — off the top of my head — the only project that I know for certain has them is Webform. Webform's Submission Guidelines are more elaborate than I need for Sitemap (e.g.: Webform's has nested error/warning messages, headings, blocks, and more). You can see by going to  https://www.drupal.org/node/add/project-issue/webform →

I realize submission guidelines are currently only shown when the issue is created, but I'd prefer something. Maybe I can copy them to the project page for more visibility.

The Sitemap maintainers prefer to only accept merge requests that have passing automated tests. Automated tests ultimately benefit you. They ensure future changes will not break the functionality your site depends on.

If you need help writing tests, please ask us!

I just tightened it up a bit. And I removed "patches" since the patch workflow no longer functions. I wouldn't imply that it's ok for people to submit patches, which would add more work for you.

@dcam, thank you very much! I'll create the first release candidate shortly!

Automatically closed - issue fixed for 2 weeks with no activity.