mirror of https://github.com/knative/docs.git
Add branch-based versioning (#3580)
* Branch-based versioning * Tidy, add version warning * Use shallow clones * use npx * Tidy, optimise * update branches * Looks like we need this bit of processresourcefiles.sh * Use array instead of function * Allow specifying community repo commit/branch * Allow overriding repos * Document prereqs * Add explicit path for hugo build * Relative latest version url
This commit is contained in:
Julian Friedman
GitHub
parent
db9e4a4d3e
commit
ca829a5ac5
|
|
@ -32,3 +32,13 @@
|
|||
.md-nav__title .md-nav__button.md-logo svg {
|
||||
width: auto;
|
||||
}
|
||||
|
||||
.md-version__list li:nth-last-child(1) a {
|
||||
color: gray;
|
||||
}
|
||||
|
||||
/* bit of a hack to stop the banner taking space when empty */
|
||||
.md-announce .md-announce__inner {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,53 +1,118 @@
|
|||
#!/bin/bash
|
||||
|
||||
# Builds blog and community into the site by cloning the website repo, copying blog/community dirs in, running hugo.
|
||||
# - Results are written to site/ as normal.
|
||||
# - Run as "./hack/build-with-blog.sh serve" to run a local preview server on site/ afterwards (requires `npm install -g http-server`).
|
||||
|
||||
# Quit on error
|
||||
set -e
|
||||
# Echo each line
|
||||
set -x
|
||||
|
||||
# First, build the main site with mkdocs
|
||||
rm -rf site/
|
||||
mkdocs build -d site/docs
|
||||
# Builds blog and community into the site by cloning the website repo, copying blog/community dirs in, running hugo.
|
||||
# Also builds previous versions unless BUILD_VERSIONS=no.
|
||||
# - Results are written to site/ as normal.
|
||||
# - Run as "./hack/build-with-blog.sh serve" to run a local preview server on site/ afterwards (requires `npm install -g http-server`).
|
||||
#
|
||||
# PREREQS (Unless BUILD_BLOG=no is set):
|
||||
# 1. Install Hugo: https://www.docsy.dev/docs/getting-started/#install-hugo
|
||||
# 2. For Mac OSX: The script uses the `gnu` version of `sed`. To install `gnu-sed`, you use brew:
|
||||
# 1. Run `brew install gnu-sed`
|
||||
# 2. Add it to your `PATH`. For example, add the following line to your `~/.bash_profile`:
|
||||
# `PATH="/usr/local/opt/gnu-sed/libexec/gnubin:$PATH"`
|
||||
|
||||
# Releasing a new version:
|
||||
# 1) Make a release-NN branch as normal.
|
||||
# 2) Update VERSIONS below (on main) to include the new version.
|
||||
# Order matters :-), Most recent first.
|
||||
VERSIONS=("0.23" "0.22" "0.21")
|
||||
# 3) For now, set branches too. (This will go away when all branches are release-NN).
|
||||
BRANCHES=("mkrelease-0.23" "mkrelease-0.22" "mkrelease-0.22")
|
||||
REPOS=("julz" "julz" "julz")
|
||||
# 4) PR the result to main.
|
||||
# 5) Party.
|
||||
|
||||
community_branch=${COMMUNITY_BRANCH:-main}
|
||||
community_repo=${COMMUNITY_REPO:-knative}
|
||||
latest=${VERSIONS[0]}
|
||||
previous=("${VERSIONS[@]:1}")
|
||||
|
||||
# Re-Clone
|
||||
# TODO(jz) Cache this and just do a pull/update for local dev flow.
|
||||
# Maybe also support local checkout in siblings?
|
||||
rm -rf temp
|
||||
mkdir temp
|
||||
git clone --recurse-submodules https://github.com/knative/website temp/website
|
||||
git clone https://github.com/knative/community temp/community
|
||||
rm -rf site/
|
||||
|
||||
# Move blog files into position
|
||||
mkdir -p temp/website/content/en
|
||||
cp -r blog temp/website/content/en/
|
||||
if [ "$BUILD_VERSIONS" == "no" ]; then
|
||||
# HEAD to /docs if we're not doing versioning.
|
||||
mkdocs build -f mkdocs.yml -d site/docs
|
||||
else
|
||||
# Versioning: pre-release (HEAD): docs => development/
|
||||
mkdocs build -f mkdocs.yml -d site/development
|
||||
|
||||
# Clone community/ in to position too
|
||||
# This is pretty weird: the base community is in docs, but then the
|
||||
# community repo is overlayed into the community/contributing subdir.
|
||||
cp -r community temp/website/content/en/
|
||||
cp -r temp/community/* temp/website/content/en/community/contributing/
|
||||
rm -r temp/website/content/en/community/contributing/elections/2021-TOC # Temp fix for markdown that confuses hugo.
|
||||
# Latest release branch to /docs
|
||||
git clone --depth 1 -b ${BRANCHES[0]} https://github.com/${REPOS[0]}/docs "temp/docs-$latest"
|
||||
pushd "temp/docs-$latest"
|
||||
KNATIVE_VERSION=$latest mkdocs build -d ../../site/docs
|
||||
popd
|
||||
|
||||
# Run the hugo build as normal!
|
||||
# Previous release branches release-$version to /v$version-docs
|
||||
versionjson=""
|
||||
for i in "${!previous[@]}"; do
|
||||
version=${previous[$i]}
|
||||
versionjson+="{\"version\": \"v$version-docs\", \"title\": \"v$version\", \"aliases\": [\"\"]},"
|
||||
git clone --depth 1 -b ${BRANCHES[$i+1]} https://github.com/${REPOS[i+1]}/docs "temp/docs-$version"
|
||||
pushd "temp/docs-$version"
|
||||
KNATIVE_VERSION=$version VERSION_WARNING=true mkdocs build -d "../../site/v$version-docs"
|
||||
popd
|
||||
done
|
||||
|
||||
# need postcss cli in PATH
|
||||
PATH=${PATH}:${PWD}/node_modules/.bin
|
||||
pushd temp/website
|
||||
hugo
|
||||
popd
|
||||
# Set up the version file to point to the built docs.
|
||||
cat << EOF > site/versions.json
|
||||
[
|
||||
{"version": "docs", "title": "v$latest", "aliases": [""]},
|
||||
$versionjson
|
||||
{"version": "development", "title": "(Pre-release)", "aliases": [""]}
|
||||
]
|
||||
EOF
|
||||
fi
|
||||
|
||||
# Hugo builds to public/, just copy over to site/ to match up with mkdocs
|
||||
mv temp/website/public/blog site/
|
||||
mv temp/website/public/community site/
|
||||
mv temp/website/public/css site/
|
||||
mv temp/website/public/scss site/
|
||||
mv temp/website/public/webfonts site/
|
||||
mv temp/website/public/images site/
|
||||
mv temp/website/public/js site/
|
||||
if [ -z "$SKIP_BLOG" ]; then
|
||||
# Clone out the website and community repos for the hugo bits.
|
||||
# TODO(jz) Cache this and just do a pull/update/use siblings for local dev flow.
|
||||
git clone --depth 1 https://github.com/knative/website temp/website
|
||||
pushd temp/website; git submodule update --init --recursive --depth 1; popd
|
||||
git clone -b ${community_branch} --depth 1 https://github.com/${community_repo}/community temp/community
|
||||
|
||||
# Move blog files into position
|
||||
mkdir -p temp/website/content/en
|
||||
cp -r blog temp/website/content/en/
|
||||
|
||||
# Clone community/ in to position too
|
||||
# This is pretty weird: the base community is in docs, but then the
|
||||
# community repo is overlayed into the community/contributing subdir.
|
||||
cp -r community temp/website/content/en/
|
||||
cp -r temp/community/* temp/website/content/en/community/contributing/
|
||||
rm -r temp/website/content/en/community/contributing/elections/2021-TOC # Temp fix for markdown that confuses hugo.
|
||||
|
||||
# See https://github.com/knative/website/blob/main/scripts/processsourcefiles.sh#L125
|
||||
# For the reasoning behind all this.
|
||||
echo 'Converting all links in GitHub source files to Hugo supported relative links...'
|
||||
pushd temp/website
|
||||
# Convert relative links to support Hugo
|
||||
find . -type f -path '*/content/*.md' ! -name '*_index.md' ! -name '*index.md' ! -name '*README.md' \
|
||||
! -name '*serving-api.md' ! -name '*eventing-contrib-api.md' ! -name '*eventing-api.md' \
|
||||
! -name '*build-api.md' ! -name '*.git*' ! -path '*/.github/*' ! -path '*/hack/*' \
|
||||
! -path '*/node_modules/*' ! -path '*/test/*' ! -path '*/themes/*' ! -path '*/vendor/*' \
|
||||
-exec sed -i '/](/ { s#(\.\.\/#(../../#g; s#(\.\/#(../#g; }' {} +
|
||||
# Convert all relative links from README.md to index.html
|
||||
find . -type f -path '*/content/*.md' ! -name '_index.md' \
|
||||
-exec sed -i '/](/ { /http/ !{s#README\.md#index.html#g} }' {} +
|
||||
# Convert all Markdown links to HTML
|
||||
find . -type f -path '*/content/*.md' \
|
||||
-exec sed -i '/](/ { /http/ !{s#\.md##g} }' {} +
|
||||
|
||||
# Run the hugo build as normal!
|
||||
PATH=${PATH}:${PWD}/node_modules/.bin hugo
|
||||
popd
|
||||
|
||||
# Hugo builds to public/, just copy over to site/ to match up with mkdocs
|
||||
for d in blog community css scss webfonts images js; do
|
||||
mv temp/website/public/$d site/
|
||||
done
|
||||
fi
|
||||
|
||||
# Home page is served from docs, so add a redirect.
|
||||
# TODO(jz) in production this should be done with a netlify 301 (or maybe just copy docs/index up with a base set).
|
||||
|
|
|
|||
|
|
@ -231,6 +231,7 @@ markdown_extensions:
|
|||
emoji_index: !!python/name:materialx.emoji.twemoji
|
||||
emoji_generator: !!python/name:materialx.emoji.to_svg
|
||||
- attr_list
|
||||
- meta
|
||||
- pymdownx.superfences
|
||||
- pymdownx.tabbed
|
||||
- pymdownx.details
|
||||
|
|
@ -250,8 +251,6 @@ copyright: "Copyright © 2021 The Knative Authors"
|
|||
|
||||
extra:
|
||||
branch: v0.23.0 # Branch to use for examples
|
||||
# version for download links, empty or "dev" to use googlestorage nightlies.
|
||||
# version: v0.23.0
|
||||
social:
|
||||
- icon: fontawesome/brands/twitter
|
||||
link: https://twitter.com/KnativeProject
|
||||
|
|
@ -261,5 +260,8 @@ extra:
|
|||
- icon: fontawesome/brands/slack
|
||||
link: https://slack.knative.dev
|
||||
name: Slack
|
||||
# TODO: Replace with https://github.com/mkdocs/mkdocs/pull/2267 once mkdocs 1.2 is out.
|
||||
version_warning: !!python/object/apply:os.getenv ["VERSION_WARNING"]
|
||||
knative_version: !!python/object/apply:os.getenv ["KNATIVE_VERSION"]
|
||||
version:
|
||||
provider: mike
|
||||
|
|
|
|||
|
|
@ -0,0 +1,13 @@
|
|||
{% extends "base.html" %}
|
||||
|
||||
{% block announce %}
|
||||
{% if config.extra.version_warning %}
|
||||
<div class="versionwarning" style="margin: .6rem auto; padding: 0 .8rem">
|
||||
<h1 style="color: #ffcc00">You are viewing documentation for Knative version: {{ config.extra.knative_version }}</h1>
|
||||
<p>
|
||||
Knative {{ config.extra.knative_version }} documentation is no longer actively maintained. The version you are currently viewing is a static snapshot. For up-to-date documentation, see <a href="{{ base_url }}/../docs/">the latest version</a>.
|
||||
</p>
|
||||
</div>
|
||||
{% endif %}
|
||||
{% endblock %}
|
||||
|
||||
Loading…
Reference in New Issue