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 #2466553: Untranslated menu items are displayed in menus.

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.

@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 paragraph 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.

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