From 287d973fae7eda144eb5880a009a40cb26f370c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Viktor=20S=C3=B6derqvist?= Date: Tue, 25 Jun 2024 11:49:40 +0200 Subject: [PATCH 1/3] Remove /docs/ from /topics/ URLs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit We've decided earlier that we want short URLs on the form https://valkey.io/topics/acl The URLs (before this patch) contain /docs/topics/ and a trailing slash, like this: https://valkey.io/docs/topics/acl/ This is to make the URLs shorter and more close to what's been decided. In the docs repo, the links between the command pages and the topics pages are on the form "../topics/acl.md" and "../commands/client-kill.md" so by putting "topics" at the same level as "commands" on the website too makes editing the docs more intuitive. I can't get rid of the trailing slash right now, so with this patch, the URLs look like https://valkey.io/topics/acl/ Redirects are added for the /docs/topics/ URLs. Signed-off-by: Viktor Söderqvist --- README.md | 6 ++-- build/init-topics.sh | 11 +++--- config.toml | 66 +++++++++++++++++------------------ content/docs/index.md | 10 +++--- content/docs/topics/_index.md | 5 --- templates/default.html | 2 +- templates/macros/command.html | 8 ++--- templates/macros/docs.html | 8 ++--- 8 files changed, 56 insertions(+), 60 deletions(-) delete mode 100644 content/docs/topics/_index.md diff --git a/README.md b/README.md index 42cc9280..056379af 100644 --- a/README.md +++ b/README.md @@ -39,11 +39,11 @@ The instructions show how to use scripts that create symbolic links to the `valk ### Building the documentation topics -Documentation 'topics' (i.e. `/docs/topics/keyspace/`, `/docs/topics/encryption/`, `/docs/topics/transactions/`) sources content from `valkey-io/valkey-doc`. +Documentation 'topics' (i.e. `/topics/keyspace/`, `/topics/encryption/`, `/topics/transactions/`) sources content from `valkey-io/valkey-doc`. ```mermaid flowchart TD - A[Webpage: /docs/topics/keyspace/ ] + A[Webpage: /topics/keyspace/ ] A --> B[Template: valkey-io/valkey-website] B --> H[Repo: valkey-io/valkey-doc ] --> I[File: /topics/keyspace.md ] --> Y[Topic content] ``` @@ -58,7 +58,7 @@ From the root directory of this repo run: ``` Then, restart Zola. -Point your browser at `http://127.0.0.1:1111/docs/topics/` and you should see the fully populated list of topics. +Point your browser at `http://127.0.0.1:1111/topics/` and you should see the fully populated list of topics. All files created in this process are ignored by git. Commit your changes to your local copy of `valkey-io/valkey-doc`. diff --git a/build/init-topics.sh b/build/init-topics.sh index 05c3c21a..7116fcd7 100755 --- a/build/init-topics.sh +++ b/build/init-topics.sh @@ -1,6 +1,6 @@ #!/bin/bash # See README for usage -# This file will create stub files for all the docs/topics. +# This file will create stub files for all the topics. # first check to make sure there are arguments if [ -z "$1" ]; then @@ -21,11 +21,12 @@ for fname in $(find $1 -maxdepth 1 -iname "*.md") do base=${fname##*/} topic=${base%.*} - if [[ "$topic" != "index" ]]; then - cat << EOF > "./content/docs/topics/$topic.md" + if [[ "$topic" != "index" ]]; then + cat << EOF > "./content/topics/$topic.md" +++ # This is a generated stub file. # To edit the content see /topic/$topic.md in the 'valkey-doc' repo +aliases = ["/docs/topics/$topic/"] +++ EOF fi @@ -36,6 +37,6 @@ echo "Topic stub files created." for fname in $(find $1 -maxdepth 1 -iname "*.png" -o -iname "*.jpg" -o -iname "*.jpeg" -o -iname "*.gif") do base=${fname##*/} - cp ${fname} ./content/docs/topics/${base} + cp ${fname} ./content/topics/${base} done -echo "Copied images to topics directory." \ No newline at end of file +echo "Copied images to topics directory." diff --git a/config.toml b/config.toml index 261232b7..69ed53b7 100644 --- a/config.toml +++ b/config.toml @@ -17,40 +17,40 @@ command_json_path = "../build-command-json/" doc_topic_path = "../build-topics/" review_list = [ - "/docs/topics/license/", - "/docs/topics/admin/", - "/docs/topics/distlock/", - "/docs/topics/eval-intro/", - "/docs/topics/faq/", - "/docs/topics/functions-intro/", - "/docs/topics/hashes/", - "/docs/topics/internals-eventlib/", - "/docs/topics/internals-vm/", - "/docs/topics/internals/", - "/docs/topics/latency/", - "/docs/topics/lua-api/", - "/docs/topics/modules-blocking-ops/", - "/docs/topics/modules-intro/", - "/docs/topics/pipelining/", - "/docs/topics/programmability/", - "/docs/topics/protocol/", - "/docs/topics/pubsub/", - "/docs/topics/rdd/", - "/docs/topics/replication/", - "/docs/topics/security/", - "/docs/topics/sentinel-clients/", - "/docs/topics/sentinel/", - "/docs/topics/transactions/", - "/docs/topics/cluster-spec/", - "/docs/topics/history/" + "/topics/license/", + "/topics/admin/", + "/topics/distlock/", + "/topics/eval-intro/", + "/topics/faq/", + "/topics/functions-intro/", + "/topics/hashes/", + "/topics/internals-eventlib/", + "/topics/internals-vm/", + "/topics/internals/", + "/topics/latency/", + "/topics/lua-api/", + "/topics/modules-blocking-ops/", + "/topics/modules-intro/", + "/topics/pipelining/", + "/topics/programmability/", + "/topics/protocol/", + "/topics/pubsub/", + "/topics/rdd/", + "/topics/replication/", + "/topics/security/", + "/topics/sentinel-clients/", + "/topics/sentinel/", + "/topics/transactions/", + "/topics/cluster-spec/", + "/topics/history/" ] publish_hold = [ - "/docs/topics/protocol/", - "/docs/topics/license/", - "/docs/topics/internals-eventlib/", - "/docs/topics/internals-vm/", - "/docs/topics/internals/", - "/docs/topics/protocol/", - "/docs/topics/rdd/" + "/topics/protocol/", + "/topics/license/", + "/topics/internals-eventlib/", + "/topics/internals-vm/", + "/topics/internals/", + "/topics/protocol/", + "/topics/rdd/" ] \ No newline at end of file diff --git a/content/docs/index.md b/content/docs/index.md index 8ef7a6a8..5aea63e8 100644 --- a/content/docs/index.md +++ b/content/docs/index.md @@ -4,11 +4,11 @@ template = "fullwidth.html" page_template = "docs-page.html" +++ -* [Command Reference](../commands/) -* [All Documentation Topics](./topics/) +* [Command Reference](/commands/) +* [All Documentation Topics](/topics/) * Management - * [Persistence](/docs/topics/persistence/) + * [Persistence](/topics/persistence/) * Security - * [ACL](/docs/topics/acl/) + * [ACL](/topics/acl/) * Valkey Manual - * [Keyspace Notifications](/docs/topics/keyspace/) + * [Keyspace Notifications](/topics/keyspace/) diff --git a/content/docs/topics/_index.md b/content/docs/topics/_index.md deleted file mode 100644 index 25877766..00000000 --- a/content/docs/topics/_index.md +++ /dev/null @@ -1,5 +0,0 @@ -+++ -title = "Topics" -template = "docs.html" -page_template = "docs-page.html" -+++ diff --git a/templates/default.html b/templates/default.html index 245a80fe..85244469 100644 --- a/templates/default.html +++ b/templates/default.html @@ -55,4 +55,4 @@

Contact

- \ No newline at end of file + diff --git a/templates/macros/command.html b/templates/macros/command.html index 06bac9b3..17fd1570 100644 --- a/templates/macros/command.html +++ b/templates/macros/command.html @@ -53,9 +53,9 @@ {%- endmacro load_command_json -%} {%- macro fix_links(content) -%} -{{ content - | regex_replace(pattern=`\]\(\.\./topics/(?P.*?).md#(?P.*?)\)`, rep=`](/docs/topics/$fname#$hash)`) - | regex_replace(pattern=`\]\(\.\./topics/(?P.*?).md\)`, rep=`](/docs/topics/$fname)`) - | regex_replace(pattern=`\[(?P.*?)\]:\s+\.\./topics/(?P.*?).md`, rep=`[$token]: /docs/topics/$fname`) +{{ content + | regex_replace(pattern=`\]\(\.\./topics/(?P.*?).md#(?P.*?)\)`, rep=`](/topics/$fname#$hash)`) + | regex_replace(pattern=`\]\(\.\./topics/(?P.*?).md\)`, rep=`](/topics/$fname)`) + | regex_replace(pattern=`\[(?P.*?)\]:\s+\.\./topics/(?P.*?).md`, rep=`[$token]: /topics/$fname`) }} {%- endmacro fix_links -%} diff --git a/templates/macros/docs.html b/templates/macros/docs.html index 0ee54abd..2e7bb677 100644 --- a/templates/macros/docs.html +++ b/templates/macros/docs.html @@ -29,10 +29,10 @@ | regex_replace(pattern=`\]\(\.\./commands/(?P\w.*?)(.md)?#(?P.*?)\)`, rep=`](/commands/$fname#$hash)`) | regex_replace(pattern=`\]\(\.\./commands/(?P\w.*?)(.md)?\)`, rep=`](/commands/$fname)`) | regex_replace(pattern=`\]\(\.\./commands/#(?P\w.*?)\)`, rep=`](/commands/#$hash)`) - | regex_replace(pattern=`\]\((?P\w.*?)(.md)?#(?P.*?)\)`, rep=`](/docs/topics/$fname#$hash)`) - | regex_replace(pattern=`\]\((?P.*?).png\)`, rep=`](/docs/topics/$fname.png)`) - | regex_replace(pattern=`\]\((?P.*?).gif\)`, rep=`](/docs/topics/$fname.gif)`) - | regex_replace(pattern=`\]\((?P\w.*?)(.md)?\)`, rep=`](/docs/topics/$fname)`) + | regex_replace(pattern=`\]\((?P\w.*?)(.md)?#(?P.*?)\)`, rep=`](/topics/$fname#$hash)`) + | regex_replace(pattern=`\]\((?P.*?).png\)`, rep=`](/topics/$fname.png)`) + | regex_replace(pattern=`\]\((?P.*?).gif\)`, rep=`](/topics/$fname.gif)`) + | regex_replace(pattern=`\]\((?P\w.*?)(.md)?\)`, rep=`](/topics/$fname)`) | regex_replace(pattern=`\]\(\-(?Phttps?:\/\/.*?\))`, rep=`]($url`) | regex_replace(pattern=`\]\(\--(?P.*?\))`, rep=`](#$hash`) }} From b050009325a196ed4bd97be2ee92e9a30c2c3e1b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Viktor=20S=C3=B6derqvist?= Date: Thu, 27 Jun 2024 02:20:34 +0200 Subject: [PATCH 2/3] Add missnig file content/topics/_index.md and update gitignore MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Viktor Söderqvist --- .gitignore | 4 ++-- content/topics/_index.md | 6 ++++++ 2 files changed, 8 insertions(+), 2 deletions(-) create mode 100644 content/topics/_index.md diff --git a/.gitignore b/.gitignore index 025317d1..d5cc9397 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,6 @@ build-command-json build-topics content/commands/* !content/commands/_index.md -content/docs/topics/* -!content/docs/topics/_index.md +content/topics/* +!content/topics/_index.md _site \ No newline at end of file diff --git a/content/topics/_index.md b/content/topics/_index.md new file mode 100644 index 00000000..c759c280 --- /dev/null +++ b/content/topics/_index.md @@ -0,0 +1,6 @@ ++++ +title = "Topics" +template = "docs.html" +page_template = "docs-page.html" +aliases = ["/docs/topics/"] ++++ From 1872fb3c66015471ea6b6a2bd245097d092f70e2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Viktor=20S=C3=B6derqvist?= Date: Wed, 3 Jul 2024 15:50:22 +0200 Subject: [PATCH 3/3] Error out if old docs/topics stup files exist MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Additionally, silence the error from ln when trying to overwrite the symlink 'build-topics' with an identical symlink to the same target. Signed-off-by: Viktor Söderqvist --- build/init-topics.sh | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/build/init-topics.sh b/build/init-topics.sh index 7116fcd7..d2e083c9 100755 --- a/build/init-topics.sh +++ b/build/init-topics.sh @@ -14,8 +14,16 @@ if [ ! -d "$1" ]; then exit 1 fi +# check for old style /docs/topics +if [ -e "content/docs/topics" ]; then + echo "Documentation topic files have moved. Delete content/docs/topics before proceeding." + exit 1 +fi -ln -s $1 ./build-topics +# Create symlink to topics, except if it already exists and points to the same directory. +if [ ! -L build-topics -o "$(readlink build-topics)" != "$1" ]; then + ln -s $1 ./build-topics +fi for fname in $(find $1 -maxdepth 1 -iname "*.md") do @@ -32,7 +40,7 @@ EOF fi done -echo "Topic stub files created." +echo "Topic stub files created at content/topics." for fname in $(find $1 -maxdepth 1 -iname "*.png" -o -iname "*.jpg" -o -iname "*.jpeg" -o -iname "*.gif") do