diff --git a/.gitignore b/.gitignore index 421ce585..28411505 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,5 @@ node_modules/ public/ content/ resources/ +docs/ .DS_Store diff --git a/layouts/_default/content.html b/layouts/_default/content.html index b5587506..2206ec1a 100644 --- a/layouts/_default/content.html +++ b/layouts/_default/content.html @@ -1,7 +1,24 @@

{{ .Title }}

{{ with .Params.description }}
{{ . | markdownify }}
{{ end }} - {{ .Content }} + {{ $out := .Content}} + {{ if not ( in (slice "README.md" "_index.md") .File.LogicalName ) }} + + {{ $out = $out | replaceRE "href=\"\\.\\./" "href=\"../../" }} + {{ $out = $out | replaceRE "href=\"\\./" "href=\"../"}} + {{ end }} + + {{ $out = $out | replaceRE "href=\"([^:\"]*(/[^\"]*)?)\\.md\"" "href=\"$1\""}} + {{ $out = $out | replaceRE "href=\"([^:\"]*(/[^\"]*)?)README\"" "href=\"$1\"" }} + {{ $out | safeHTML}} {{ if (and (not .Params.hide_feedback) (.Site.Params.ui.feedback.enable) (.Site.GoogleAnalytics)) }} {{ partial "feedback.html" .Site.Params.ui.feedback }}
diff --git a/layouts/shortcodes/readfile.md b/layouts/shortcodes/readfile.md index 7f4a1eb1..aaedbd64 100644 --- a/layouts/shortcodes/readfile.md +++ b/layouts/shortcodes/readfile.md @@ -109,7 +109,11 @@ Parameters: {{ else }} {{/* If HTML or Markdown. For Markdown`{{%...%}}`, don't send content to processor again (use safeHTML). */}} -{{ $.Scratch.Get "filepath" | readFile | safeHTML }} +{{/* Look for part of the Markdown link syntax ']' and remove '.md' or 'README' from within those links. */}} +{{ $out := $.Scratch.Get "filepath" | readFile }} +{{ $out = $out | replaceRE "]([^)]+).md" "]$1" }} +{{ $out = $out | replaceRE "]([^)]+)README" "]$1" }} +{{ $out | safeHTML }} {{ end }} diff --git a/scripts/convert-repo-ulrs.sh b/scripts/convert-repo-ulrs.sh index 2d821c2d..f9538362 100755 --- a/scripts/convert-repo-ulrs.sh +++ b/scripts/convert-repo-ulrs.sh @@ -2,6 +2,9 @@ # THIS FILE IS USED BY THE 'processsourcefiles.sh' SCRIPT TO CONVERT URLS TO RELATIVE # ####################################################################################### +# TODO(Evan): move this processing into golang, probably via +# layouts/_default/content.html and/or shortcodes. + echo '------ CONVERT FULLY QUALIFIED REPO URLS TO RELATIVE ------' # Convert fully-qualified URLs that are used in the Knative GitHub repos source files # to link from repo to repo, into relative URLs for publishing to the knative.dev site. diff --git a/scripts/docs-version-settings.sh b/scripts/docs-version-settings.sh index 6ad149cd..1aff27f3 100755 --- a/scripts/docs-version-settings.sh +++ b/scripts/docs-version-settings.sh @@ -7,5 +7,11 @@ # This should be set to the latest docs release/branch DEFAULTBRANCH="release-0.16" +# Latest release version number +LATESTVERSION="16" +# Total number of past versions to publish +NUMOFVERSIONS="3" +OLDESTVERSION=$((LATESTVERSION-NUMOFVERSIONS)) + # An optional value that you can locally override for local builds/testing DEFAULTFORK="knative" diff --git a/scripts/processsourcefiles.sh b/scripts/processsourcefiles.sh index f15dfcf1..0285c1f6 100755 --- a/scripts/processsourcefiles.sh +++ b/scripts/processsourcefiles.sh @@ -30,25 +30,38 @@ then mv content/en/docs content/en/development # DOCS BRANCHES echo '------ Cloning all docs releases ------' + + # TODO(Evan): Avoid the need for `mv` above and make the below just ap + # set of clone + symlink commands + # Get versions of released docs from their branches in "$FORK"/docs - echo 'The /docs/ section is built from the' "$BRANCH" 'branch of' "$FORK" # Latest version is defined in website/scripts/docs-version-settings.sh # If this is a PR build, then build that content as the latest release (assume PR preview builds are always from "latest") - git clone --quiet -b "$BRANCH" https://github.com/"$FORK"/docs.git temp/release/latest - # Only copy and keep the "docs" folder from all branched releases: - mv temp/release/latest/docs content/en/docs echo 'Getting the archived docs releases from branches in:' "$FORK"'/docs' - ############################################################### - # Template for next release: - #git clone -b "release-[VERSION#]" https://github.com/"$FORK"/docs.git temp/release/[VERSION#] - #mv temp/release/[VERSION#]/docs content/en/[VERSION#]-docs - ############################################################### - git clone --quiet -b "release-0.15" https://github.com/"$FORK"/docs.git temp/release/v0.15 - mv temp/release/v0.15/docs content/en/v0.15-docs - git clone --quiet -b "release-0.14" https://github.com/"$FORK"/docs.git temp/release/v0.14 - mv temp/release/v0.14/docs content/en/v0.14-docs - git clone --quiet -b "release-0.13" https://github.com/"$FORK"/docs.git temp/release/v0.13 - mv temp/release/v0.13/docs content/en/v0.13-docs + mkdir -p docs # -p won't fail if the file exists + r=$OLDESTVERSION + while [[ $r -le $LATESTVERSION ]] + do + CLONE="docs/release-0.${r}" + if [[ -e "$CLONE" ]] + then + echo "Skipping ${CLONE}, a copy of those archived docs already exists." + ln -s ../../"$CLONE"/docs content/en/v0."$r"-docs #always recreate symlinks because /content/en always gets wiped out + else + echo 'Getting docs from: release-0.'"${r}" + git clone --quiet -b "release-0.${r}" "https://github.com/${FORK}/docs.git" "$CLONE" + if [ "$r" = "$LATESTVERSION" ] + then + echo 'The /docs/ section is built from:' "$FORK"'/release-0.'"${r}" + mv "$CLONE"/docs content/en/docs + rm -rf "$CLONE" #always get the latest release + else + # Only use the "docs" folder from all branches/releases + ln -s ../../"$CLONE"/docs content/en/v0."$r"-docs + fi + fi + (( r = r + 1 )) + done elif [ "$BUILDSINGLEBRANCH" = "true" ] then @@ -64,6 +77,9 @@ else echo '------ BUILDING ONLY FROM YOUR LOCAL KNATIVE/DOCS CLONE ------' echo 'Copying local clone of knative/docs into the /docs folder under:' pwd + + # TODO(Evan): switch this to just be symlinks? + cp -r ../docs content/en/ if [ -d "../community" ]; then echo 'Also copying the local clone of knative/community into the /community/contributing folder.' @@ -77,6 +93,7 @@ if [ "$LOCALBUILD" = "false" ] then echo '------ Cloning contributor docs ------' # COMMUNITY + # TODO / Known issue: Auto PR builds will fail if remote fork excludes knative/community -> https://app.netlify.com/sites/knative/deploys echo 'Getting Knative contributor guidelines from the master branch of' "$FORK"'/community' git clone --quiet -b master https://github.com/"$FORK"/community.git temp/community # Move files into existing "contributing" folder @@ -97,40 +114,14 @@ source scripts/convert-repo-ulrs.sh ######################################################### # Process content in .md files (MAKE RELATIVE LINKS WORK) # We want users to be able view and use the source files in GitHub as well as on the site. -# Therefore, the following changes need to be made to all docs files prior to Hugo site build. -# Convert GitHub enabled source, into HUGO supported content: -# - For all Markdown files under the /content/ directory: -# - Skip all: -# - Markdown link with fully qualified HTTP(s) URL is 'external' -# - GitHub file (.git* files) -# - non-docs directories -# - Ignore Hugo site related files (avoid "readfile" shortcodes): -# - _index.md files (Hugo 'section' files) -# - API shell files (serving-api.md, eventing-contrib-api.md, eventing-api.md) -# - For all remaining Markdown files: -# - Remove all '.md' file extensions from within Markdown links "[]()" -# - For SEO convert README to index: -# - Replace all in-page URLS from "README.md" to "index.html" -# - Rename all files from "README.md" to "index.md" -# - Adjust relative links by adding additional depth: -# - Exclude all README.md & _index.md files -# - Convert './' to '../' -# - Convert '../' to '../../' -echo 'Converting all links in GitHub source files to Hugo supported relative links...' -# Convert relative links to support Hugo -find . -type f -path '*/content/*.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;s#\.md##g} }' {} + +# +# See layouts/_default/content.html for how this is done. ############################################### # Process file names (HIDE README.md FROM URLS) # For SEO, dont use "README" in the URL # (convert them to index.md OR use a "readfile" shortcode to nest them within a _index.md section file) +# See also https://github.com/gohugoio/hugo/issues/4691 which would resolve this. # # Notes about past docs versions: # v0.6 and earlier doc releases: Use the "readfile" shortcodes to nest all README.md files within the _index.md files. @@ -152,7 +143,7 @@ find . -type f -path '*/content/*/*/*' -name 'README.md' \ ! -path '*/contributing/*' ! -path '*/v0.6-docs/*' ! -path '*/v0.5-docs/*' \ ! -path '*/v0.4-docs/*' ! -path '*/v0.3-docs/*' ! -path '*/.github/*' ! -path '*/hack/*' \ ! -path '*/node_modules/*' ! -path '*/test/*' ! -path '*/themes/*' ! -path '*/vendor/*' \ - -execdir bash -c 'if [ -e _index.md -o -e index.md ]; then echo "_index.md exists - skipping ${PWD#*/}"; else mv "$1" "${1/\README/\index}"; fi' -- {} \; + -execdir bash -c 'if [ -e index.md -o -e _index.md ]; then echo "index.md or _index.md exists - skipping ${PWD#*/}"; else mv "$1" "${1/README/index}"; fi' -- {} \; # GET HANDCRAFTED SITE LANDING PAGE echo 'Copying the override files into the /content/ folder'