feat(plugin-sitemap): add sitemap plugin (#37)

docs/.vuepress/configs/navbar/en.ts

@@ -26,13 +26,17 @@ export const navbarEn: NavbarConfig = [
         ],
       },
       {
-        text: 'Content Search',
+        text: 'Search',
         children: ['/plugins/docsearch', '/plugins/search'],
       },
       {
         text: 'PWA',
         children: ['/plugins/pwa', '/plugins/pwa-popup'],
       },
+      {
+        text: 'SEO',
+        children: ['/plugins/sitemap'],
+      },
       {
         text: 'Syntax Highlighting',
         children: ['/plugins/prismjs', '/plugins/shiki'],

docs/.vuepress/configs/navbar/zh.ts

@@ -26,13 +26,17 @@ export const navbarZh: NavbarConfig = [
         ],
       },
       {
-        text: '内容搜索',
+        text: '搜索',
         children: ['/zh/plugins/docsearch', '/zh/plugins/search'],
       },
       {
         text: 'PWA',
         children: ['/zh/plugins/pwa', '/zh/plugins/pwa-popup'],
       },
+      {
+        text: '搜索引擎增强',
+        children: ['/zh/plugins/sitemap'],
+      },
       {
         text: '语法高亮',
         children: ['/zh/plugins/prismjs', '/zh/plugins/shiki'],

docs/.vuepress/configs/sidebar/en.ts

@@ -22,6 +22,19 @@ export const sidebarEn: SidebarConfig = {
       text: 'PWA',
       children: ['/plugins/pwa', '/plugins/pwa-popup'],
     },
+    {
+      text: 'SEO',
+      children: [
+        {
+          text: 'Sitemap',
+          children: [
+            '/plugins/sitemap/guide',
+            '/plugins/sitemap/config',
+            '/plugins/sitemap/frontmatter',
+          ],
+        },
+      ],
+    },
     {
       text: 'Syntax Highlighting',
       children: ['/plugins/prismjs', '/plugins/shiki'],

docs/.vuepress/configs/sidebar/zh.ts

@@ -15,13 +15,26 @@ export const sidebarZh: SidebarConfig = {
       ],
     },
     {
-      text: '内容搜索',
+      text: '搜索',
       children: ['/zh/plugins/docsearch', '/zh/plugins/search'],
     },
     {
       text: 'PWA',
       children: ['/zh/plugins/pwa', '/zh/plugins/pwa-popup'],
     },
+    {
+      text: '搜索引擎增强',
+      children: [
+        {
+          text: '站点地图',
+          children: [
+            '/zh/plugins/sitemap/guide',
+            '/zh/plugins/sitemap/config',
+            '/zh/plugins/sitemap/frontmatter',
+          ],
+        },
+      ],
+    },
     {
       text: '语法高亮',
       children: ['/zh/plugins/prismjs', '/zh/plugins/shiki'],

docs/plugins/docsearch.md

@@ -48,7 +48,7 @@ new Crawler({
     'https://YOUR_WEBSITE_URL/',
   ],
   sitemaps: [
-    // if you are using sitemap plugins (e.g.: vuepress-plugin-sitemap2), you may provide one
+    // if you are using sitemap plugins (e.g.: @vuepress-plugin/sitemap), you may provide one
     'https://YOUR_WEBSITE_URL/sitemap.xml',
   ],
   ignoreCanonicalTo: false,

docs/plugins/sitemap/README.md

@@ -0,0 +1,21 @@
+# sitemap
+
+<NpmBadge package="@vuepress/plugin-sitemap" />
+
+## Usage
+
+```bash
+npm i -D @vuepress/plugin-sitemap@next
+```
+
+```ts title=".vuepress/config.ts"
+import { sitemapPlugin } from "@vuepress/plugin-sitemap";
+
+export default {
+  plugins: [
+    sitemapPlugin({
+      // options
+    }),
+  ],
+}
+```

docs/plugins/sitemap/config.md

@@ -0,0 +1,94 @@
+# Config
+
+## hostname
+
+- Type: `string`
+- Required: Yes
+
+The domain name where the current site is deployed, the plugin needs this option to work.
+
+## extraUrls
+
+- Type: `string[]`
+- Required: No
+
+Extra links to be included.
+
+If you have some links not including in VuePress Router (normally in public directory or generated by other tools directly), you may need this option.
+
+E.g.: `['/about.html', '/api/']`
+
+## excludeUrls
+
+- Type: `string[]`
+- Default: `['/404.html']`
+
+Urls excluding from sitemap, starting with absolute path.
+
+By default, all the urls generated by VuePress (excluding 404 page) will be added into sitemap.
+
+## devServer
+
+- Type: `boolean`
+- Default: `false`
+
+Whether enabled in devServer.
+
+::: tip
+
+For performance reasons, we do not provide hot reload. Reboot your devServer to sync your changes.
+
+:::
+
+## devHostname
+
+- Type: `string`
+- Default: `"http://localhost:${port}"`
+
+Hostname to use in devServer
+
+## sitemapFilename
+
+- Type: `string`
+- Default value: `"sitemap.xml"`
+
+The output filename, relative to output directory.
+
+## sitemapXSLFilename
+
+- Type: `string`
+- Default value: `"sitemap.xsl"`
+
+Output xsl filename, relative to dest folder.
+
+## sitemapXSLTemplate
+
+- Type: `string`
+- Default value: `"@vuepress/plugin-sitemap/templates/sitemap.xsl"`
+
+XSL content used as template.
+
+## changefreq
+
+- Type: `"always" | "hourly" | "daily" | "weekly" |"monthly" | "yearly" | "never"`
+- Default value: `"daily"`
+
+
+Page default update frequency, will be overridden by [sitemap.changefreq](./frontmatter.md#sitemap-changefreq) in Frontmatter.
+
+
+## priority
+
+- Type: `number`
+
+- Default: `0.5`
+
+Page priority, from `0` to `1`.
+
+## modifyTimeGetter
+
+- Type: `(page: Page, app: App) => string`
+
+- Required: `false`
+
+Last modify time getter. By default, the plugin will use the timestamp generated by git plugin.

docs/plugins/sitemap/frontmatter.md

@@ -0,0 +1,23 @@
+
+# Frontmatter Config
+
+## sitemap
+
+- Type: `SitemapFrontmatterOptions | false`
+- Required: No
+
+`false` means exclude the page from sitemap.
+
+### sitemap.changefreq
+
+- Type: `"always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never"`
+- Default: `"daily"`
+
+Page default update frequency. This will override [changefreq](./config.md#changefreq) in Plugin Options.
+
+### sitemap.priority
+
+- Type: `number`
+- Default: `0.5`
+
+Page priority, range from `0` to `1`.

docs/plugins/sitemap/guide.md

@@ -0,0 +1,75 @@
+# Guide
+
+This plugin will automatically generate a Sitemap for your site. To let this plugin work, you need to pass the deployed domain name to the `hostname` option of the plugin. If you want to preview in devServer, set `devServer` options.
+
+The plugin will automatically generate the last update time of the page based on the Git timestamp of the page, and will also declare the alternative links of the page in other languages according to the locales' config.
+
+## Control Sitemap Link
+
+By default, all site links except 404 page will be added to the Sitemap.
+
+To add other pages to the Sitemap outside the VuePress project page, please turn them into an array and pass to the `extraUrls` plugin option.
+
+If you don't want certain pages to appear in the sitemap, you can turn them into an array and pass them to the `excludeUrls` plugin option, or set `sitemap.exclude` to `true` in the frontmatter of the corresponding page.
+
+## Output Location
+
+You can also control the output link through the `sitemapFilename` option of the plugin, the link is relative to output directory. By default, the plugin will use `sitemap.xml`.
+
+## Change Frequency
+
+The default update cycle of the page is `daily` (every day). To modify the entire page cycle, please set `changefreq` in the plugin options. You can also set `sitemap.changefreq` in the frontmatter of the page. Note that page has a higher priority.
+
+The legal frequencies are:
+
+- `"always"`
+- `"hourly"`
+- `"daily"`
+- `"weekly"`
+- `"monthly"`
+- `"yearly"`
+- `"never"`
+
+## Priority
+
+You can set `priority` in the plugin to provide a default value. At the same time you can set the priority for each page through `sitemap.priority` in frontmatter. Acceptable values are floating point numbers from `0` to `1`.
+
+## Modify Time
+
+You can use option `modifyTimeGetter` to return a time in ISO string format, which is generated by the Git plugin by default.
+
+The following is an example based on the last modification time of a file.
+
+```ts
+// Based on file last modified time
+({
+   modifyTimeGetter: (page, app) =>
+     fs.statSync(app.dir.source(page.filePathRelative)).mtime.toISOString();
+})
+```
+
+## Sitemap Intro
+
+Sitemaps provide SEO (Search Engine Optimization):
+
+- Provide search engine spiders with links of the entire site;
+- Provide some links for search engine spiders to dynamic pages or pages that are difficult to reach by other methods;
+- If a visitor attempts to access a URL that does not exist within the site's domain, the visitor will be directed to a "file not found" error page, and the sitemap can be used as a navigation page.
+
+A sitemap enhances SEO by making all pages findable.
+
+Most search engines only follow a limited number of links within a page, so when the site is very large, a sitemap becomes essential to make everything on the site accessible to search engines and visitors.
+
+Sitemaps is a protocol for site administrators to publish pages that can be crawled on a site to search engine spiders. The content of sitemap files must follow the definition in XML format. Each URL can contain the update period and last update time, the priority of the URL across the site. This allows search engines to crawl site content better and more efficiently.
+
+::: warning Together with robots.txt
+
+Sitemap is basically used by search engines, when using this plugin, you'd better ensure that you have a valid `robots.txt` in the `.vuepress/public` directory to allow search engines spiders to visit your site. The simplest robots.txt is as follows (allow all search engines to access all paths)
+
+```txt
+User-agent: *
+
+Allow: /
+```
+
+:::