You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[AMORO-3977] Combine amoro-site to prevent docs loose sync (apache#3979)
* clone site
* remove invalid soft links
* docs soft link
* Update site/README.md with clear structure documentation
- Reorganized documentation to show the versioned and non-versioned content structure
- Provided a clear directory tree representation of the site structure
- Updated instructions for running the documentation site locally
- Added section on testing both sites together
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Update site/README.md with clear structure documentation
- Fixed references to make it clear this is part of the main repository
- Updated section titles to match the new organization
- Clarified paths for versioned and non-versioned content
- Simplified local development instructions
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* github action
* ignore
* rat exclude site
* test
* test please
* Revert "test please"
This reverts commit 7c536fe.
* label
---------
Co-authored-by: Claude <noreply@anthropic.com>
- Licensed to the Apache Software Foundation (ASF) under one
3
+
- or more contributor license agreements. See the NOTICE file
4
+
- distributed with this work for additional information
5
+
- regarding copyright ownership. The ASF licenses this file
6
+
- to you under the Apache License, Version 2.0 (the
7
+
- "License"); you may not use this file except in compliance
8
+
- with the License. You may obtain a copy of the License at
9
+
-
10
+
- http://www.apache.org/licenses/LICENSE-2.0
11
+
-
12
+
- Unless required by applicable law or agreed to in writing,
13
+
- software distributed under the License is distributed on an
14
+
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15
+
- KIND, either express or implied. See the License for the
16
+
- specific language governing permissions and limitations
17
+
- under the License.
18
+
-->
19
+
20
+
# Apache Amoro Documentation Site
21
+
22
+
This directory contains the documentation site infrastructure for Apache Amoro.
23
+
It's built with [Hugo](https://gohugo.io/) and hosted at https://amoro.apache.org.
24
+
25
+
# Structure
26
+
27
+
The Amoro documentation site consists of both versioned and non-versioned content, organized as follows:
28
+
29
+
```
30
+
.
31
+
├── docs (versioned)
32
+
│ ├── admin-guides
33
+
│ ├── concepts
34
+
│ ├── engines
35
+
│ ├── formats
36
+
│ ├── images
37
+
│ └── user-guides
38
+
└── site (non-versioned)
39
+
├── amoro-docs
40
+
│ ├── archetypes
41
+
│ ├── content (symlink to ../../docs)
42
+
│ ├── hugo.toml
43
+
│ └── themes
44
+
├── amoro-site
45
+
│ ├── archetypes
46
+
│ ├── content
47
+
│ ├── hugo.toml
48
+
│ └── themes
49
+
├── amoro-theme
50
+
└── README.md
51
+
```
52
+
53
+
## Organization of Documentation Content
54
+
55
+
The documentation is organized into versioned and non-versioned content:
56
+
57
+
-**Versioned Content** (`/docs`): All markdown pages specific to an Amoro version are maintained in the main repository's `/docs` directory. These include user guides, admin guides, concepts, and other technical documentation.
58
+
59
+
-**Non-versioned Content** (`/site`): The website infrastructure and common pages shared across all versions are maintained in the `/site` directory, which includes:
60
+
-`amoro-site`: Contains the landing page and common content
61
+
-`amoro-docs`: Contains the documentation site that renders versioned content (via symlink to `/docs`)
62
+
-`amoro-theme`: Contains the Hugo theme used by both sites
63
+
64
+
During each new release, the release manager will:
65
+
1. Create a branch from master named for the release version
66
+
2. Update the latest branch HEAD to point to the release branch HEAD
67
+
68
+
# How to Contribute
69
+
70
+
## Submitting Pull Requests
71
+
72
+
-**Version-specific content**: Changes to the markdown contents for version-specific pages should be submitted to the `/docs` directory.
73
+
74
+
-**Non-versioned content**: Changes to common pages, website appearance (HTML, CSS), etc. should be submitted to the `/site` directory.
75
+
76
+
-**Old version documentation**: Changes to documentation of old Amoro versions should be submitted against the specific version branch.
77
+
78
+
## Reporting Issues
79
+
80
+
All issues related to the doc website should be submitted to the [Amoro repository](https://github.com/apache/amoro).
81
+
82
+
## Running Locally
83
+
84
+
To run the website locally:
85
+
86
+
```shell
87
+
# From the root of the repository
88
+
```
89
+
90
+
To start the site page locally, run:
91
+
```shell
92
+
(cd site/amoro-site && hugo serve)
93
+
```
94
+
95
+
To start the documentation site locally, run:
96
+
```shell
97
+
(cd site/amoro-docs && hugo serve)
98
+
```
99
+
100
+
## Testing Both Sites Together
101
+
102
+
In some cases, it's useful to test both the amoro site and the docs site together, especially for testing relative links between the two. This can be achieved by building both sites with custom `baseURL` and `publishDir` values:
103
+
104
+
First, build the main site:
105
+
```
106
+
cd site/amoro-site
107
+
hugo -b http://localhost:5500/ -d ../../public
108
+
```
109
+
110
+
Next, build the docs site:
111
+
```
112
+
cd ../amoro-docs
113
+
hugo -b http://localhost:5500/docs/latest/ -d ../../public/docs/latest
114
+
```
115
+
116
+
You can then serve the combined site from the `public` directory using any local server.
117
+
118
+
## Scanning For Broken Links
119
+
120
+
To scan for broken links, you can use the linkcheck tool available [here](https://github.com/filiph/linkcheck).
0 commit comments