diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 673b6538b..3393edbf0 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -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; +} diff --git a/hack/build-with-blog.sh b/hack/build-with-blog.sh index b96282c63..1f844c283 100755 --- a/hack/build-with-blog.sh +++ b/hack/build-with-blog.sh @@ -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). diff --git a/mkdocs.yml b/mkdocs.yml index fa8d8ff31..f246037bb 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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 diff --git a/overrides/main.html b/overrides/main.html new file mode 100644 index 000000000..6fa5ef26c --- /dev/null +++ b/overrides/main.html @@ -0,0 +1,13 @@ +{% extends "base.html" %} + +{% block announce %} +{% if config.extra.version_warning %} +
+

You are viewing documentation for Knative version: {{ config.extra.knative_version }}

+

+ 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 the latest version. +

+
+{% endif %} +{% endblock %} +