upcontent 0.1.5 → 0.1.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/customization/config-json.md +1 -1
- package/customization/seo.md +106 -0
- package/index.md +1 -0
- package/package.json +1 -1
|
@@ -88,7 +88,7 @@ The optional fields below cover navigation, Starlight presentation, and content
|
|
|
88
88
|
| Group | Controls |
|
|
89
89
|
| --- | --- |
|
|
90
90
|
| `site` | Name, description, URL, social image, locale, logo, and favicon. |
|
|
91
|
-
| `seo` | Explicitly enables search-engine discoverability. Defaults to disabled. |
|
|
91
|
+
| `seo` | Explicitly enables search-engine discoverability. Defaults to disabled. See [Search engine visibility](seo/). |
|
|
92
92
|
| `repo` | Source repository links. |
|
|
93
93
|
| `theme` | Consumer-owned local CSS. |
|
|
94
94
|
| `starlight` | Safe layout, social, table of contents, pagination, and code options. |
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Search engine visibility
|
|
3
|
+
description: Configure discoverability, metadata, canonical URLs, robots, and sitemaps for a portal.
|
|
4
|
+
sidebar:
|
|
5
|
+
order: 3
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
Upcontent treats search-engine discoverability as an explicit site-level policy. SEO is disabled by default so a new portal is not indexed accidentally.
|
|
9
|
+
|
|
10
|
+
## Enable discoverability
|
|
11
|
+
|
|
12
|
+
Set `seo.enabled` to `true` and provide the canonical site URL:
|
|
13
|
+
|
|
14
|
+
```json
|
|
15
|
+
{
|
|
16
|
+
"site": {
|
|
17
|
+
"title": "Engineering Docs",
|
|
18
|
+
"description": "Documentation for the engineering team.",
|
|
19
|
+
"url": "https://docs.example.com"
|
|
20
|
+
},
|
|
21
|
+
"seo": {
|
|
22
|
+
"enabled": true
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
The `site.url` value must be an absolute HTTP(S) URL. `SITE_URL` can provide the URL at build time and takes precedence for the Astro site configuration.
|
|
28
|
+
|
|
29
|
+
When SEO is enabled, Upcontent generates indexable page metadata, canonical URLs, structured data, `robots.txt`, and a sitemap. The sitemap is published at `sitemap-index.xml`.
|
|
30
|
+
|
|
31
|
+
## Keep a portal unlisted
|
|
32
|
+
|
|
33
|
+
Omit `seo.enabled` or set it to `false` when the portal should be publicly accessible but not discoverable. Upcontent then emits:
|
|
34
|
+
|
|
35
|
+
- `noindex, nofollow` page directives.
|
|
36
|
+
- `Disallow: /` in `robots.txt`.
|
|
37
|
+
- No indexable sitemap URLs.
|
|
38
|
+
|
|
39
|
+
This is an unlisted portal, not a private portal. It does not prevent visitors from accessing pages. Use access-controlled hosting when the content must be private.
|
|
40
|
+
|
|
41
|
+
## Exclude individual pages
|
|
42
|
+
|
|
43
|
+
An enabled portal can exclude individual pages with page frontmatter:
|
|
44
|
+
|
|
45
|
+
```yaml
|
|
46
|
+
---
|
|
47
|
+
title: Internal migration notes
|
|
48
|
+
noindex: true
|
|
49
|
+
---
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
The page remains available at its normal route, but it is emitted with `noindex, nofollow` and is omitted from the sitemap.
|
|
53
|
+
|
|
54
|
+
## Page metadata
|
|
55
|
+
|
|
56
|
+
Use these optional frontmatter fields when a page needs metadata different from the site defaults:
|
|
57
|
+
|
|
58
|
+
```yaml
|
|
59
|
+
---
|
|
60
|
+
title: Consumer repository setup
|
|
61
|
+
canonical: https://docs.example.com/getting-started/consumer-repository/
|
|
62
|
+
image: https://docs.example.com/social-cards/consumer-repository.png
|
|
63
|
+
---
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
- `title` controls the page title and generated heading metadata.
|
|
67
|
+
- `description` supplies search and social description metadata.
|
|
68
|
+
- `canonical` overrides the generated canonical URL and `og:url`. It must be an absolute HTTP(S) URL.
|
|
69
|
+
- `image` overrides the site-level social image for that page.
|
|
70
|
+
- `noindex` excludes the page from indexing and the sitemap.
|
|
71
|
+
|
|
72
|
+
## Social previews
|
|
73
|
+
|
|
74
|
+
Set a default social preview image in the site configuration:
|
|
75
|
+
|
|
76
|
+
```json
|
|
77
|
+
{
|
|
78
|
+
"site": {
|
|
79
|
+
"socialImage": "https://docs.example.com/social-card.png",
|
|
80
|
+
"locale": "en-US"
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Page-level `image` takes precedence over `site.socialImage`. Relative image paths resolve from the content repository and are converted to absolute URLs when a canonical site URL is available.
|
|
86
|
+
|
|
87
|
+
## Deployment paths
|
|
88
|
+
|
|
89
|
+
Set `BASE_PATH` when the portal is served below the domain root:
|
|
90
|
+
|
|
91
|
+
```sh
|
|
92
|
+
BASE_PATH=/engineering-docs SITE_URL=https://example.com pnpm exec astro build
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Generated canonical URLs, sitemap entries, robots output, and internal links include the configured base path. Set `SITE_URL` or `site.url` when the host supports canonical URLs and sitemap generation.
|
|
96
|
+
|
|
97
|
+
## Validate SEO output
|
|
98
|
+
|
|
99
|
+
Before publishing, verify:
|
|
100
|
+
|
|
101
|
+
```sh
|
|
102
|
+
pnpm check
|
|
103
|
+
make build CONTENT_PATH=/path/to/your-consumer-repo
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Inspect `dist/robots.txt`, `dist/sitemap-index.xml`, and a representative page in `dist/` to confirm that the SEO policy matches the intended portal visibility.
|
package/index.md
CHANGED
|
@@ -18,6 +18,7 @@ Upcontent turns the documentation repository you already have into a fast, searc
|
|
|
18
18
|
- [Run your first build](getting-started/first-build/)
|
|
19
19
|
- [Configure content](customization/content/)
|
|
20
20
|
- [Configure navigation](customization/navigation/)
|
|
21
|
+
- [Configure search visibility](customization/seo/)
|
|
21
22
|
- [Customize the portal](customization/)
|
|
22
23
|
- [Validate before publishing](guides/validate-your-site/)
|
|
23
24
|
- [Publish to GitHub Pages](deployment/github-pages/)
|