upcontent 0.1.3 → 0.1.4
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/.upcontent/config.json +1 -1
- package/index.md +126 -4
- package/package.json +1 -1
- package/src/lib/sidebar.ts +2 -2
package/.upcontent/config.json
CHANGED
package/index.md
CHANGED
|
@@ -5,15 +5,137 @@ sidebar:
|
|
|
5
5
|
order: 1
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
Upcontent turns
|
|
8
|
+
Upcontent turns the documentation repository you already have into a fast, searchable, customizable portal.
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
[](https://github.com/lumamontes/upcontent/actions/workflows/ci.yml)
|
|
11
|
+
[](https://www.npmjs.com/package/upcontent)
|
|
11
12
|
|
|
12
|
-
##
|
|
13
|
+
## Explore Upcontent
|
|
13
14
|
|
|
15
|
+
- [See the live portal](https://lumamontes.github.io/upcontent/)
|
|
16
|
+
- [Explore the capability showcase](showcase/)
|
|
14
17
|
- [Set up a consumer repository](getting-started/consumer-repository/)
|
|
15
18
|
- [Run your first build](getting-started/first-build/)
|
|
19
|
+
- [Configure content](customization/content/)
|
|
20
|
+
- [Configure navigation](customization/navigation/)
|
|
16
21
|
- [Customize the portal](customization/)
|
|
17
22
|
- [Validate before publishing](guides/validate-your-site/)
|
|
23
|
+
- [Publish to GitHub Pages](deployment/github-pages/)
|
|
24
|
+
- [Publish to another static host](deployment/static-hosts/)
|
|
25
|
+
- [Publish releases through npm](deployment/npm/)
|
|
18
26
|
|
|
19
|
-
|
|
27
|
+
## See the result
|
|
28
|
+
|
|
29
|
+
This is the real Upcontent portal generated from this repository and deployed to GitHub Pages.
|
|
30
|
+
|
|
31
|
+
<p align="center">
|
|
32
|
+
<a href="https://lumamontes.github.io/upcontent/"><img src="assets/readme/portal-home.png" alt="Upcontent documentation portal home page" width="900"></a>
|
|
33
|
+
</p>
|
|
34
|
+
|
|
35
|
+
The same build includes a capability showcase for technical content, structured data, callouts, diagrams, navigation, and search.
|
|
36
|
+
|
|
37
|
+
<p align="center">
|
|
38
|
+
<a href="showcase/"><img src="assets/readme/portal-showcase.png" alt="Upcontent capability showcase page" width="900"></a>
|
|
39
|
+
</p>
|
|
40
|
+
|
|
41
|
+
## From repository to portal
|
|
42
|
+
|
|
43
|
+
Upcontent keeps your source of truth in Git and adds the publishing layer: clear navigation, full-text search, technical content rendering, consumer-owned branding, and a repeatable static build.
|
|
44
|
+
|
|
45
|
+
If your Markdown already lives in a GitHub repository, the flow is:
|
|
46
|
+
|
|
47
|
+
```sh
|
|
48
|
+
pnpm dlx upcontent init
|
|
49
|
+
pnpm dlx upcontent dev
|
|
50
|
+
pnpm dlx upcontent check
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
The first command creates `.upcontent/` and a GitHub Pages workflow. The second starts a local portal using the repository you are already in. The third builds the consumer portal and validates the generated site. You do not need to clone the Upcontent renderer into your documentation repository.
|
|
54
|
+
|
|
55
|
+
Push the generated workflow and your documentation is published as a static site. The source repository remains the source of truth; Upcontent does not require a database, a companion server, or a new authoring system.
|
|
56
|
+
|
|
57
|
+
## What you get
|
|
58
|
+
|
|
59
|
+
- A responsive [Starlight](https://starlight.astro.build/) portal with navigation, search, themes, and table of contents.
|
|
60
|
+
- A `.upcontent/config.json` file for identity, navigation, rendering, and content boundaries.
|
|
61
|
+
- Consumer-owned logos, favicon, CSS, site identity, and navigation.
|
|
62
|
+
- Rendered callouts, Mermaid diagrams, JSON, YAML, CSV, and wiki links.
|
|
63
|
+
- A static `dist/` directory deployable to GitHub Pages or any static host.
|
|
64
|
+
- Build checks that catch broken wiki links and excluded content before publication.
|
|
65
|
+
|
|
66
|
+
## Is it a good fit?
|
|
67
|
+
|
|
68
|
+
Upcontent is a good fit when:
|
|
69
|
+
|
|
70
|
+
- Your documentation already lives in Markdown or MDX.
|
|
71
|
+
- Your team wants to keep writing in Git.
|
|
72
|
+
- You want the portal to be owned and deployed by the documentation repository.
|
|
73
|
+
- You need more than raw Markdown, but do not need a dynamic application.
|
|
74
|
+
- You want branding and navigation without maintaining a custom docs frontend.
|
|
75
|
+
|
|
76
|
+
It is not the right fit when your site needs runtime authentication, server-rendered personalization, or review comments inside the published portal.
|
|
77
|
+
|
|
78
|
+
## Explore this repository locally
|
|
79
|
+
|
|
80
|
+
Clone this repository, then start the included golden consumer:
|
|
81
|
+
|
|
82
|
+
```sh
|
|
83
|
+
git clone https://github.com/lumamontes/upcontent.git
|
|
84
|
+
cd upcontent
|
|
85
|
+
pnpm install
|
|
86
|
+
make dev CONTENT_PATH=.
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Then open the local URL printed by Astro. The [capability showcase](showcase/) is the fastest way to see the complete rendering and customization surface.
|
|
90
|
+
|
|
91
|
+
## Configure your portal
|
|
92
|
+
|
|
93
|
+
The consumer configuration is deliberately small:
|
|
94
|
+
|
|
95
|
+
```json
|
|
96
|
+
{
|
|
97
|
+
"site": {
|
|
98
|
+
"title": "Engineering Docs",
|
|
99
|
+
"description": "Documentation for the engineering team.",
|
|
100
|
+
"socialImage": "https://docs.example.com/social-card.png",
|
|
101
|
+
"locale": "en-US",
|
|
102
|
+
"logo": {
|
|
103
|
+
"src": ".upcontent/logo.svg",
|
|
104
|
+
"alt": "Engineering Docs"
|
|
105
|
+
},
|
|
106
|
+
"favicon": ".upcontent/favicon.svg"
|
|
107
|
+
},
|
|
108
|
+
"seo": {
|
|
109
|
+
"enabled": true
|
|
110
|
+
},
|
|
111
|
+
"repo": {
|
|
112
|
+
"url": "https://github.com/acme/engineering-docs"
|
|
113
|
+
},
|
|
114
|
+
"theme": {
|
|
115
|
+
"customCss": [".upcontent/theme.css"]
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Follow [Set up a consumer repository](getting-started/consumer-repository/) for the complete setup, then use [Customization](customization/) to shape the portal.
|
|
121
|
+
|
|
122
|
+
## Build for production
|
|
123
|
+
|
|
124
|
+
```sh
|
|
125
|
+
make build CONTENT_PATH=/path/to/your-consumer-repo
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
The generated site is written to `dist/` and includes the Pagefind search index. Before publishing, run:
|
|
129
|
+
|
|
130
|
+
```sh
|
|
131
|
+
pnpm test
|
|
132
|
+
pnpm check
|
|
133
|
+
make build CONTENT_PATH=.
|
|
134
|
+
make check-external
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Read the [deployment guide](deployment/) for GitHub Pages and other static hosts.
|
|
138
|
+
|
|
139
|
+
## Built on Astro and Starlight
|
|
140
|
+
|
|
141
|
+
Upcontent uses the official [Astro](https://astro.build/) framework and [Starlight](https://starlight.astro.build/) documentation theme as its rendering foundation. Upcontent adds the consumer-repository contract, content integrity checks, configuration surface, and deployment workflow around them.
|
package/package.json
CHANGED
package/src/lib/sidebar.ts
CHANGED
|
@@ -113,8 +113,8 @@ export function buildSidebar(docsRoot: string): SidebarEntry[] {
|
|
|
113
113
|
}
|
|
114
114
|
}
|
|
115
115
|
|
|
116
|
-
// A homepage fica fixa em primeiro, com o label configurável
|
|
117
|
-
//
|
|
116
|
+
// A homepage fica fixa em primeiro, com o label configurável, sem competir
|
|
117
|
+
// alfabeticamente com as outras páginas.
|
|
118
118
|
const homepageIndex = entries.findIndex(e => !isSidebarGroup(e) && e.slug === 'index')
|
|
119
119
|
const homepageEntry = homepageIndex >= 0 ? entries.splice(homepageIndex, 1)[0] : undefined
|
|
120
120
|
const sorted = sortEntries(entries)
|