Skip to content

Commit 614dd2b

Browse files
committed
spin docs new toc prototype
Signed-off-by: Ronan Flynn-Curran <[email protected]>
1 parent 194108f commit 614dd2b

21 files changed

+19332
-1780
lines changed

.build/check-broken-links.sh

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
#!/bin/bash
2+
set -euo pipefail
3+
4+
require() {
5+
if ! hash "$1" &>/dev/null; then
6+
echo "'$1' not found in PATH"
7+
exit 1
8+
fi
9+
}
10+
11+
cleanup() {
12+
if [[ "$?" == "124" ]]; then
13+
echo "timeout exceeded waiting for the developer portal to run"
14+
fi
15+
echo "stopping process for $$"
16+
cleanup_with_child $$ false
17+
}
18+
19+
cleanup_with_child() {
20+
local pid="$1"
21+
local and_self="${2:-false}"
22+
23+
echo "cleanup_with_child $pid"
24+
25+
if children="$(pgrep -P "$pid")"; then
26+
for child in $children; do
27+
echo "stopping child $child (parent: $pid)"
28+
cleanup_with_child "$child" true
29+
done
30+
fi
31+
32+
if [[ "$and_self" == true ]]; then
33+
echo "stopping self $pid"
34+
kill -9 "$pid" 2>/dev/null || true
35+
fi
36+
}
37+
38+
trap cleanup EXIT
39+
40+
## add broken-link-checker to PATH
41+
export PATH=$PATH:`pwd`/node_modules/broken-link-checker/bin
42+
43+
require spin
44+
require timeout
45+
require blc
46+
47+
echo "starting developer portal"
48+
49+
## allow unpublished content during broken link checker
50+
export PREVIEW_MODE=1
51+
52+
## start the developer portal in background
53+
npm run spin >/dev/null 2>&1 &
54+
55+
## wait for portal to be up and running
56+
export RESP_CODE="$(mktemp)"
57+
timeout 60s bash -c 'until curl -o /dev/null -s -w "%{http_code}\n" http://localhost:3000 > $RESP_CODE; do sleep 2; done'
58+
59+
echo "checking website health via http://localhost:3000"
60+
61+
[[ "$(< $RESP_CODE)" == "200" ]] && \
62+
(echo "Success: website returned a 200 response code") || \
63+
(echo "Failure: unexpected response code: $(< $RESP_CODE)" && exit 1)
64+
65+
echo "starting link checker"
66+
67+
## Run the broken link checker
68+
report="$(mktemp)"
69+
blc_error=false
70+
blc --recursive http://127.0.0.1:3000 \
71+
\
72+
`## Ignore searching Edit links` \
73+
--exclude 'https://github.com/fermyon/developer/blob/main/content/*' \
74+
\
75+
`## returns 403` \
76+
--exclude 'https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits' \
77+
--exclude 'https://docs.github.com/en/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account' \
78+
--exclude 'https://docs.github.com/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/remembering-your-github-username-or-email' \
79+
--exclude 'https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification' \
80+
--exclude 'https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template' \
81+
--exclude 'https://twitter.com/fermyontech' \
82+
--exclude 'https://twitter.com/fermyontech/status/1641537393818738710' \
83+
--exclude 'https://www.godaddy.com' \
84+
--exclude 'https://linux.die.net/man/1/which' \
85+
\
86+
`## false positives` \
87+
--exclude 'https://www.gnu.org/software/coreutils/' \
88+
--exclude 'https://events.hashicorp.com/hashitalksdeploy' \
89+
--exclude 'https://dotnet.microsoft.com/en-us/download/dotnet/8.0' \
90+
--exclude 'https://www.developerweek.com/' \
91+
--exclude 'https://marketplace.visualstudio.com/items?itemName=fermyon.spin-vscode&ssr=false#overview' \
92+
--exclude 'https://marketplace.visualstudio.com/items?itemName=fermyon.autobindle' \
93+
--exclude 'https://crates.io/' \
94+
--exclude 'https://crates.io/crates/bytes' \
95+
--exclude 'https://crates.io/crates/http' \
96+
--exclude 'https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one' \
97+
--exclude 'https://events.hashicorp.com/hashitalksdeploy' \
98+
--exclude 'https://www.instagram.com/fermyontech/' \
99+
--exclude 'https://www.linkedin.com/company/fermyon/' \
100+
--exclude 'https://support.google.com/webmasters/answer/7552505' \
101+
--exclude 'https://www.namecheap.com/support/knowledgebase/article.aspx/767/10/how-to-change-dns-for-a-domain/' \
102+
--exclude 'https://support.google.com/domains/answer/3290309?hl=en#' \
103+
--exclude 'https://dotnet.microsoft.com/en-us/apps/aspnet/web-apps/blazor' \
104+
--exclude 'https://www.reddit.com/r/Clojure/comments/jkznto/web_assembly_clojure_current_state/' \
105+
--exclude 'https://www.reddit.com/r/Rlanguage/comments/b4izog/compile_r_to_webassembly_and_use_as_a_data/' \
106+
--exclude 'https://www.tutorialspoint.com/webassembly/webassembly_working_with_cplusplus.htm' \
107+
--exclude 'http://localhost:16686/' \
108+
--exclude 'http://localhost:5050/explore' \
109+
--exclude 'http://localhost:5050/explore' \
110+
--exclude 'https://stackshare.io/stackups/powershell-vs-webassembly' \
111+
--exclude 'https://blog.cloudflare.com/cloudflare-workers-now-support-cobol/' \
112+
--exclude 'https://support.google.com/webmasters/answer/9008080?hl=en' | tee "${report}" || blc_error=true
113+
114+
cat "${report}" | grep "├─BROKEN─" > broken_links || true
115+
116+
if [ -s broken_links ]; then
117+
echo "Some links are broken, retrying to check for transient errors"
118+
while read -r line; do
119+
url="$(echo $line | awk '{print $2}')"
120+
if curl --retry 5 --retry-all-errors --retry-delay 1 --output /dev/null --silent --head --fail "$url"; then
121+
echo "$url is not broken"
122+
else
123+
124+
echo "$line" >> final_broken
125+
fi
126+
done <broken_links
127+
if [ -f "final_broken" ]; then
128+
echo -e "The list of broken links are\n"
129+
cat -n final_broken
130+
exit 1
131+
else
132+
echo "All the errors were transient. The links are valid!"
133+
fi
134+
else
135+
if [ "${blc_error}" == "true" ]; then
136+
echo "Failure: error(s) encountered attempting to check website links" && exit 1
137+
fi
138+
echo "All the links are valid!"
139+
fi

.markdownlint-cli2.mjs

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
const options = {
2+
"config": {
3+
"default": false,
4+
"extends": null,
5+
// Headings can increment by only one step (h1 -> h2) and not (h1 -> h3)
6+
"heading-increment": true,
7+
// Multiple blank lines will throw an error
8+
"no-multiple-blanks": true,
9+
// Headings should be surrounded by new lines
10+
"blanks-around-headings": true,
11+
// Headings always start on new lines
12+
"heading-start-left": true,
13+
// Code blocks must have an empty line above and below them
14+
"blanks-around-fences": true,
15+
// There can not be empty spaces in links
16+
"no-space-in-links": true,
17+
// Links must always contain url or "#"
18+
"no-empty-links": true,
19+
// Images must contain alt texts
20+
"no-alt-text": true,
21+
// Enforce consistent style for code blocks
22+
"code-block-style": {
23+
"style": "fenced"
24+
},
25+
// Enforce consistent fence style for code blocks
26+
"code-fence-style": {
27+
"style": "backtick"
28+
},
29+
"titlecase-rule": true
30+
},
31+
"customRules": ["markdownlint-rule-titlecase"]
32+
}
33+
34+
export default options;

content/index.md

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,6 @@ url = "https://github.com/spinframework/spin-docs/blob/main/content/spin/v3/inde
77

88
---
99

10-
{{suh_cards}}
11-
{{card_element "sample" "Checklist Sample App" "A checklist app that persists data in a key value store" "/hub/preview/sample_checklist" "Typescript,Http,Kv" true }}
12-
{{card_element "template" "Zola SSG Template" "A template for using Zola framework to create a static webpage" "/hub/preview/template_zola_ssg" "rust" true }}
13-
{{card_element "sample" "AI-assisted News Summarizer" "Read an RSS newsfeed and have AI summarize it for you" "/hub/preview/sample_newsreader_ai" "Typescript,Javascript,Ai" true }}
14-
{{blockEnd}}
15-
1610
Spin is a framework for building and running event-driven microservice applications with WebAssembly (Wasm) components.
1711

1812
Spin uses Wasm because it is **sandboxed, portable, and fast**. Millisecond cold start times mean no need to keep applications "warm".
@@ -25,5 +19,5 @@ Spin is **open source** and **built on standards**, meaning you can take your Sp
2519

2620
Or dive into the documentation and get started:
2721

28-
- 1. [Quick Start: ](quickstart)
29-
- 2. [Learn how to write Spin applications](writing-apps)
22+
- [Quick Start: ](quickstart)
23+
- [Learn how to write Spin applications](writing-apps)

content/v3/deploying-to-fermyon.md

Lines changed: 0 additions & 31 deletions
This file was deleted.

content/v3/deploying.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
title = "Deploy Options"
2+
template = "main"
3+
date = "2023-11-04T00:00:01Z"
4+
[extra]
5+
url = "https://github.com/spinframework/spin-docs/blob/main/content/spin/v3/deploying-to-fermyon.md"
6+
7+
---
8+
9+
### Running locally on your workstation
10+
11+
For instructions guiding you through running Spin apps on your development workstation,
12+
follow [this guide](/running-app).
13+
14+
### Deploying to Kubernetes
15+
16+
Spin applications can be deployed to a Kubernetes cluster with [SpinKube](https://www.spinkube.dev/docs/overview/) - an open source project that streamlines the experience of developing, deploying, and operating Wasm workloads on Kubernetes. Like Spin, SpinKube is a CNCF Sandbox project.
17+
18+
19+
## Fermyon Cloud
20+
21+
[Fermyon Cloud](/cloud) is a self-service application platform for WebAssembly-based serverless functions and microservices. It enables you to run Spin applications, at scale, in the cloud, without any infrastructure setup or maintenance required.
22+
23+
## Fermyon Platform
24+
25+
[Fermyon Platform](https://www.fermyon.com/platform) is a self-hosted platform for Spin applications.

content/v3/index.md

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,6 @@ url = "https://github.com/spinframework/spin-docs/blob/main/content/spin/v3/inde
77

88
---
99

10-
{{suh_cards}}
11-
{{card_element "sample" "Checklist Sample App" "A checklist app that persists data in a key value store" "https://developer.fermyon.com/hub/preview/sample_checklist" "Typescript,Http,Kv" true }}
12-
{{card_element "template" "Zola SSG Template" "A template for using Zola framework to create a static webpage" "https://developer.fermyon.com/hub/preview/template_zola_ssg" "rust" true }}
13-
{{card_element "sample" "AI-assisted News Summarizer" "Read an RSS newsfeed and have AI summarize it for you" "https://developer.fermyon.com/hub/preview/sample_newsreader_ai" "Typescript,Javascript,Ai" true }}
14-
{{blockEnd}}
15-
1610
Spin is a framework for building and running event-driven microservice applications with WebAssembly (Wasm) components.
1711

1812
Spin uses Wasm because it is **sandboxed, portable, and fast**. Millisecond cold start times mean no need to keep applications "warm".
@@ -27,5 +21,4 @@ Or dive into the documentation and get started:
2721

2822
- [Take Spin for a spin](quickstart)
2923
- [Install Spin](install)
30-
- [Learn how to write Spin applications](writing-apps)
31-
- [Run your Spin applications in the Fermyon Cloud](/cloud/index)
24+
- [Learn how to write Spin applications](writing-apps)

deploy/README.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Deployments
2+
3+
The [Developer](https://developer.fermyon.com) website is deployed via the [deploy.yml](../.github/workflows/deploy.yml) GitHub workflow.
4+
5+
## Auto Deploys
6+
7+
The production version of the website is deployed whenever commits are pushed to the `main` branch.
8+
9+
## Manual Deploys
10+
11+
Deployments may also be [triggered manually](https://github.com/fermyon/developer/actions/workflows/deploy.yml), providing a choice of git
12+
`ref` and `commit`.
13+
14+
## Nomad job
15+
16+
We currently deploy the website via its Nomad job directly. (In the future, we envision running the website as a Fermyon Cloud app.)
17+
18+
The [fermyon-developer](./fermyon-developer.nomad) Nomad job contains configuration for the running website, including the OCI reference to run from.

0 commit comments

Comments
 (0)