Add outdated component to outdated documents (#25)

- `git log` needs all commit history to compare latest commit of files, so changed `git clone --depth=1` to `git clone`. This will make the step take longer, so might be improved if there is a better way.

- `src/theme/MDXContent/index.js` is from [ejecting of the component](https://docusaurus.io/docs/swizzling#ejecting) inside `@docusaurus/theme-classic` plugin, and this one is safe to eject according to docusaurus

    ![Screen Shot 2023-06-06 at 12.12.28](/attachments/17a3a84b-cec0-4849-8bd6-9e0471d9536f)

    ![Screen Shot 2023-06-06 at 12.12.15](/attachments/58bba321-3cfb-4a8b-8aeb-84422a06c472)

- [Outdated component style reference](https://mui.com/material-ui/react-alert/)

- Added [`Translate` component](https://docusaurus.io/docs/next/docusaurus-core#translate) to `Outdated` so it can be localized. [reference](https://docusaurus.io/docs/next/i18n/tutorial#translate-your-react-code)

- One way to check for the specific outdated documents:

    search for `lastest commit timestamp` in [prepare nightly docs and prepare 1.19 docs steps](https://gitea.com/gitea/gitea-docusaurus/actions/runs/74)

# After

The Chinese documents that are outdated (latest commit is ealier than laster commit of English version):

![Screen Shot 2023-06-06 at 13.04.24](/attachments/e5d16267-d8d8-434e-89b1-138d04ec92a3)

![Screen Shot 2023-06-06 at 13.05.07](/attachments/af8f996a-5318-4f89-841f-b27a4903a27d)

![Screen Shot 2023-06-06 at 13.05.14](/attachments/e6aba31b-46ba-4a32-ad81-81007e0f711e)

Reviewed-on: https://gitea.com/gitea/gitea-docusaurus/pulls/25
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: HesterG <hestergong@gmail.com>
Co-committed-by: HesterG <hestergong@gmail.com>

Makefile

@@ -13,10 +13,11 @@ create_dir:
 
 .PHONY: clone_main
 clone_main: create_dir
-	git clone --depth=1 --branch=main https://github.com/go-gitea/gitea.git .tmp/upstream-docs-latest
+	git clone --branch=main https://github.com/go-gitea/gitea.git .tmp/upstream-docs-latest
 	cur_path=`pwd`
 	cd .tmp/upstream-docs-latest/docs && make trans-copy
 	cd $(cur_path)
+	bash check_outdated.sh latest zh-cn
 
 .PHONY: prepare-latest
 prepare-latest: clone_main
@@ -37,10 +38,11 @@ prepare-latest-zh-cn:
 
 .PHONY: clone_\#%
 clone_\#%: create_dir
-	git clone --depth=1 --branch=release/v1.$* https://github.com/go-gitea/gitea.git .tmp/upstream-docs-$*
+	git clone --branch=release/v1.$* https://github.com/go-gitea/gitea.git .tmp/upstream-docs-$*
 	cur_path=`pwd`
 	cd .tmp/upstream-docs-$*/docs && make trans-copy
 	cd $(cur_path)
+	bash check_outdated.sh $* zh-cn
 
 .PHONY: prepare\#%
 prepare\#%: clone_\#%

check_outdated.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+
+# The script takes two params: 
+#     version: "latest" or a specific version number
+#     locale
+# This script checks if a specific locale version of document is up to date with English version
+# If latest commit timestamp of English version is greater than the specific locale version,
+# The specific locale version document will be marked as outdated
+
+set -xe
+
+if sed --version 2>/dev/null | grep -q GNU; then
+    SED_INPLACE="sed -i"
+else
+    SED_INPLACE="sed -i ''"
+fi
+version="$1"
+locale="$2"
+cur_path=`pwd`
+cd .tmp/upstream-docs-"$version"
+
+for file in `find ./docs/content/doc -name "*.${locale}.md"`; do
+    file_en="${file/.${locale}/.en-us}"
+    if [ ! -f "$file_en" ]; then
+        continue
+    fi
+    latest_commit_time_en=$(git log -1 --format=%ct "$file_en")
+    latest_commit_time_locale=$(git log -1 --format=%ct "$file")
+    if [ -z "$latest_commit_time_locale" ]; then
+        continue
+    fi
+    if [[ "$latest_commit_time_en" -gt "$latest_commit_time_locale" ]]; then
+        echo "file: $file, lastest commit timestamp: $latest_commit_time_en (en ver), $latest_commit_time_locale ($locale ver)"
+        $SED_INPLACE '1s/---/---\nisOutdated: true/' $file
+    fi
+done
+
+cd "$cur_path"

docusaurus.config.js

@@ -24,12 +24,11 @@ const config = {
   favicon: 'img/favicon.png',
 
   i18n: {
-    defaultLocale: 'en',
+    defaultLocale: 'en-us',
-    locales: ['en', 'zh-cn'/*, 'fr-fr', 'zh-tw'*/], // temporarily disable other locales
+    locales: ['en-us', 'zh-cn'/*, 'fr-fr', 'zh-tw'*/], // temporarily disable other locales
     localeConfigs: {
-      'en': {
+      'en-us': {
         label: 'English',
-        htmlLang: 'en-US',
       },
       'zh-cn': {
         label: '中文',
@@ -47,15 +46,12 @@ const config = {
           sidebarPath: require.resolve('./sidebars.js'),
           routeBasePath: '/', // Serve the docs at the site's root
           editUrl: ({versionDocsDirPath, docPath, locale, version, permalink}) => {
-            let fileName = `doc/${docPath.replace('.md', '')}.en-us.md`;
+            let fileName = `doc/${docPath.replace('.md', '')}.${locale}.md`;
-            if (locale === 'zh-cn') {
-              fileName = `doc/${docPath.replace('.md', '')}.zh-cn.md`;
-            }
             // intro.md has different name from upstream, need to handle this here
             if (docPath.includes('intro.md')) {
-              fileName = locale === 'zh-cn' ? 'page/index.zh-cn.md': 'page/index.en-us.md';
+              fileName = `page/index.${locale}.md`;
             }
-            return `https://github.com/go-gitea/gitea/tree/main/docs/content/${fileName}`;
+            return `https://github.com/go-gitea/gitea/tree/${version === 'current' ? 'main': `release/v${version}`}/docs/content/${fileName}`;
           },
           versions: {
             current: {

i18n/zh-cn/code.json

@@ -0,0 +1,8 @@
+{
+  "outdated.message": {
+    "message": "当前中文文档翻译不是最新版，访问英文版本查看最新内容，或"
+  },
+  "outdated.help": {
+    "message": "帮助我们翻译"
+  }
+}

loop_docs-19-zh-cn.sh

@@ -22,7 +22,7 @@ $SED_INPLACE 's/{{< min-go-version >}}/1.19/' i18n/zh-cn/docusaurus-plugin-conte
 
 $SED_INPLACE 's/"version":.*/"version":"1.19.0"/' static/19-swagger.json
 
-for file in `find ./i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19/ -name "*.md"`; do
+for file in `find ./i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19 -name "*.md"`; do
     # note only works on linux, forget about it when attempting to run on macos
     # hide hugo toc
     $SED_INPLACE 's/{{< toc >}}//' $file
@@ -44,7 +44,7 @@ for file in i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19/*; do
     rm $file
 done
 
-for file in `find ./i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19/ -name "*.zh-cn.md"`; do
+for file in `find ./i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19 -name "*.zh-cn.md"`; do
     mv "${file}" "${file/.zh-cn/}"
 done
 

loop_docs-19.sh

@@ -21,7 +21,7 @@ $SED_INPLACE 's/{{< min-go-version >}}/1.19/' versioned_docs/version-1.19/instal
 
 $SED_INPLACE 's/"version":.*/"version":"1.19.3"/' static/19-swagger.json
 
-for file in `find ./versioned_docs/version-1.19/ -name "*.md"`; do
+for file in `find ./versioned_docs/version-1.19 -name "*.md"`; do
     # hide hugo toc
     $SED_INPLACE 's/{{< toc >}}//' $file
     $SED_INPLACE 's/{{< version >}}/1.19.3/g' $file
@@ -44,7 +44,8 @@ for file in versioned_docs/version-1.19/*; do
     fi
     rm $file
 done
-
+# file names under ./versioned_docs/version-1.19 and i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19/ should be the same for docusaurus 
-for file in `find ./versioned_docs/version-1.19/ -name "*.en-us.md"`; do
+# to recognize them as tanslated.
+for file in `find ./versioned_docs/version-1.19 -name "*.en-us.md"`; do
     mv "${file}" "${file/.en-us/}"
 done

loop_docs-zh-cn.sh

@@ -22,7 +22,7 @@ $SED_INPLACE 's/{{< min-go-version >}}/1.20/' i18n/zh-cn/docusaurus-plugin-conte
 
 $SED_INPLACE 's/"version":.*/"version":"1.20-dev"/' static/latest-swagger.json
 
-for file in `find ./i18n/zh-cn/docusaurus-plugin-content-docs/current/ -name "*.md"`; do
+for file in `find ./i18n/zh-cn/docusaurus-plugin-content-docs/current -name "*.md"`; do
     # note only works on linux, forget about it when attempting to run on macos
     # hide hugo toc
     $SED_INPLACE 's/{{< toc >}}//' $file
@@ -45,7 +45,7 @@ for file in i18n/zh-cn/docusaurus-plugin-content-docs/current/*; do
     rm $file
 done
 
-for file in `find ./i18n/zh-cn/docusaurus-plugin-content-docs/current/ -name "*.zh-cn.md"`; do
+for file in `find ./i18n/zh-cn/docusaurus-plugin-content-docs/current -name "*.zh-cn.md"`; do
     mv "${file}" "${file/.zh-cn/}"
 done
 

loop_docs.sh

@@ -21,7 +21,7 @@ $SED_INPLACE 's/{{< min-go-version >}}/1.20/' docs/installation/from-source.en-u
 
 $SED_INPLACE 's/"version":.*/"version":"1.20-dev"/' static/latest-swagger.json
 
-for file in `find ./docs/ -name "*.md"`; do
+for file in `find ./docs -name "*.md"`; do
     # hide hugo toc
     $SED_INPLACE 's/{{< toc >}}//' $file
     $SED_INPLACE 's/dl.gitea.com\/gitea\/{{< version >}}/dl.gitea.com\/gitea\/main/g' $file
@@ -44,6 +44,8 @@ for file in docs/*; do
     rm $file || true
 done
 
-for file in `find ./docs/ -name "*.en-us.md"`; do
+# file names under docs/ and i18n/zh-cn/docusaurus-plugin-content-docs/current/ should be the same for docusaurus 
+# to recognize them as tanslated.
+for file in `find ./docs -name "*.en-us.md"`; do
     mv "${file}" "${file/.en-us/}"
 done

src/components/Outdated.js

@@ -0,0 +1,17 @@
+import React from 'react'
+import Translate from '@docusaurus/Translate';
+
+export default function Outdated(props) {
+  return (
+    <div className='outdated-text'>
+      <Translate id="outdated.message">
+        The content of current version is not up to date, please check latest English version, or
+      </Translate>
+      <a href={props.editUrl}>
+        <Translate id="outdated.help">
+          Help us to translate
+        </Translate>
+      </a>
+    </div>
+  )
+}

src/css/custom.css

@@ -37,3 +37,24 @@
 [data-theme='dark'] .close {
   color: var(--ifm-color-white);
 }
+
+.outdated-text {
+  margin: 20px 0;
+  transition: box-shadow 300ms cubic-bezier(0.4, 0, 0.2, 1) 0ms;
+  border-radius: 4px;
+  box-shadow: none;
+  font-family: Roboto, Helvetica, Arial, sans-serif;
+  font-weight: 400;
+  font-size: 0.875rem;
+  line-height: 1.43;
+  letter-spacing: 0.01071em;
+  background-color: rgb(229, 246, 253);
+  display: flex;
+  padding: 6px 16px;
+  color: rgb(1, 67, 97);
+}
+
+[data-theme='dark'] .outdated-text {
+  background-color: rgb(7, 19, 24);
+  color: rgb(184, 231, 251);
+}

src/theme/MDXContent/index.js

@@ -0,0 +1,16 @@
+import React from 'react';
+import {MDXProvider} from '@mdx-js/react';
+import MDXComponents from '@theme/MDXComponents';
+// useDoc reference:
+// https://fossies.org/linux/docusaurus/packages/docusaurus-theme-classic/src/theme/DocItem/Content/index.tsx
+import {useDoc} from '@docusaurus/theme-common/internal';
+import Outdated from '@site/src/components/Outdated';
+
+export default function MDXContent({children}) {
+  // {assets, contentTitle, frontMatter, metadata, toc}
+  const {frontMatter, metadata} = useDoc();
+  return <MDXProvider components={MDXComponents}>
+    {frontMatter.isOutdated && <Outdated editUrl={metadata.editUrl}/>}
+    {children}
+  </MDXProvider>;
+}