diff --git a/.circleci/config.yml b/.circleci/config.yml index 13419b5e928b7..1d20947e6bab6 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -17,28 +17,48 @@ jobs: # Download and cache dependencies - restore_cache: keys: - - v3-dependencies-{{ checksum "Gemfile.lock" }} + - v4-dependencies-{{ checksum "Gemfile.lock" }} # fallback to using the latest cache if no exact match is found - - v3-dependencies- + - v4-dependencies- - run: - name: install dependencies + name: Installing proofer dependencies command: | gem install bundler - bundle install --jobs=4 --retry=3 --path vendor/bundle + bundle install --jobs=4 --retry=3 --path .vendor/bundle - save_cache: paths: - - ./vendor/bundle - key: v3-dependencies-{{ checksum "Gemfile.lock" }} + - ./.vendor/bundle + key: v4-dependencies-{{ checksum "Gemfile.lock" }} - restore_cache: keys: - htmlproofer-cache-v3 - # Run the test/html checker - - run: bundle exec rake test + + - run: + name: Proofing HTML + command: + bundle exec rake test + # save the external URLs cache - save_cache: key: htmlproofer-cache-v3 paths: - tmp/.htmlproofer + + - run: + name: Installing speller dependencies + command: | + mkdir -p .vendor/node + npm install --prefix .vendor/node markdown-spellcheck + + - run: + name: Checking markdown spelling + command: + .vendor/node/node_modules/markdown-spellcheck/bin/mdspell --en-us --ignore-acronyms --ignore-numbers --no-suggestions --report *.md */*.md */*/*.md */*/*/*.md */*/*/*/*.md + + - run: + name: Checking markdown style + command: + mdl --ignore-front-matter --style mdl_style.rb . diff --git a/.firebaserc b/.firebaserc deleted file mode 100644 index 8b215d77067c9..0000000000000 --- a/.firebaserc +++ /dev/null @@ -1,6 +0,0 @@ -{ - "projects": { - "default": "istio-io", - "v01": "istiodocs-v01" - } -} diff --git a/.gitignore b/.gitignore index e2ecac6289f31..ffc759f48fa19 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ _site +_rakesite _static_site .bundle config_override.yml diff --git a/.spelling b/.spelling new file mode 100644 index 0000000000000..3ebda772d1cfc --- /dev/null +++ b/.spelling @@ -0,0 +1,554 @@ +# markdown-spellcheck spelling configuration file +# Format - lines beginning # are comments +# global dictionary is at the start, file overrides afterwards +# one word per line, to define a file override use ' - filename' +# where filename is relative to this configuration file +0.1.x +0.2.x +0.8.x +1.x +10s +123456789012.my +15ms +1qps +243ms +24ms +290ms +2x +3s +404s +4s +5000qps +50Mb +6s +7Mb +7s +ACLs +API +APIs +Ansible +AppOptics +AuthPolicy +Autoscalers +Bookinfo +Budinsky +CAP_NET_ADMIN +CAs +CDNs +CIDRs +CIOs +Costin +CSRs +Chrony +Circonus +CloudWatch +Cmd +Config +ConfigMap +Ctrl +CustomResourceDefinition +D3.js +DaemonSet +Datadog +Datawire +DestinationRule +EgressRule +Elasticsearch +ExecAction +Exfiltrating +ExternalName +Fluentd +FQDNs +GATEWAY_URL +GCP-IAM +GCP_OPTS +GKE-IAM +GKE-Istio +GKE-Workloads +GitHub +GlueCon +Gmail +Grafana +Graphviz +Hystrix +ILBs +IPs +IPv4 +ISTIO_INBOUND_PORTS +Incrementality +Initializers +Istio +IstioMesh +IstioRBAC.svg +Istiofied +JSON-formatted +JWT +JWTs +Kibana +Kops +Kuat +Kube +Kubecon +Kubelet +Kubernetes +L3-4 +L4-L6 +LabelDescription +LoadBalancers +LoadBalancing.svg +Lyft +MacOS +Manolache +Memquota +Mesos +Minikube +MongoDB +Multicloud +Multicluster +MutatingWebhookConfiguration +MySQL +Mysql +NamespaceSelector +NodePort +OAuth2 +OP_QUERY +OpenID_Connect +OpenSSL +OpenShift +Ostrowski +PaaS +Papertrail +PilotAdapters.svg +Rajagopalan +RawVM +Redis +Redis-based +Redisquota +Registrator +Reviewer1 +Reviewer2 +SREs +ServiceEntry +ServiceGraph +ServiceModel_RequestFlow.svg +ServiceModel_Versions.svg +ServiceRole +Servicegraph +Sharding +Shriram +Snell-Feikema +SolarWinds +StatefulSets +TCP-level +TLS-secured +Tcpdump +Tigera +TrafficManagementOverview.svg +USE_ORIGIN +USE_ORIGIN +USE_PEER +Undeploy +VMware +VM-based +VMs +ValueType +VirtualService +WeaveWorks +WebSocket +Webhooks +X.509 +X.509. +Yessenov +Zack +Zipkin +_CA_ +_OK_ +_V2_ +_blog +_data +_docs +_help +_proxy +_v2_ +_v3_ +a.k.a. +abc +abcde12345 +accounts.my +adapters.svg +addon +addons +admissionregistration +admissionregistration.k8s.io +analytics +api-server +api.operation +api.protocol +api.service +api.version +apiVersion +arch.svg +archive.istio.io +archive.istio.io. +attach_policies.png +auth.svg +authn.svg +autoscaler +autoscalers +autoscaling +backend +backends +base64 +bind-productpager-viewer +bookinfo +booksale +bookstore.default.svc.cluster.local +boolean +bt +camelCase +canaried +canarying +check.error_code +check.error_message +cluster.local +colocated +concepts.yaml +config +configmap +configmaps +connection.duration +connection.id +connection.received.bytes +connection.received.bytes_total +connection.sent.bytes +connection.sent.bytes_total +containerID +context.protocol +context.time +coreos +create_policy.png +createpolicyjson.png +createpolicystart.png +current.istio.io +current.istio.io. +datastore +debian +default.svc.cluster.local +destination.domain +destination.ip +destination.labels +destination.name +destination.namespace +destination.port +destination.service +destination.uid +destination.user +dev +dm_bookinfo.png +dm_gcp_iam.png +dm_gcp_iam_role.png +dm_grafana.png +dm_kubernetes.png +dm_kubernetes_workloads.png +dm_launcher.png +dm_prometheus.png +dm_servicegraph.png +dm_zipkin.png +docker.io +e.g. +eBPF +enablement +endUser-to-Service +env +envars.yaml +errorFetchingBookDetails.png +errorFetchingBookRating.png +etcd +example.com +externalBookDetails.png +externalMySQLRatings.png +facto +failovers +faq +faq.md +fcm.googleapis.com +filename +filenames +fluentd +fortio +frontend +gRPC +gateways.svg +gbd +gcloud +gdb +getPetsById +git +golang +googleapis.com +googlegroups.com +goroutine +goroutines +grafana-istio-dashboard +grpc +helloworld +hostIP +hostname +hotspots +html +http +http2 +httpReqTimeout +httpbin +httpbin.org +httpbin.yaml +https +https_from_the_app.svg +hyperkube +i.e. +image.html +img +ingressgateway +initializer +initializers +int64 +intermediation +interoperate +intra-cluster +ip_address +iptables +istio +istio-apiserver +istio-system1 +istio.github.io +istio.github.io. +istio.io +istio.io. +istio.yaml +istio_auth_overview.svg +istio_auth_workflow.svg +istio_grafana_dashboard-new +istio_grafana_disashboard-new +istio_zipkin_dashboard.png +istioctl +jaeger_dashboard.png +jaeger_trace.png +jason +json +k8s +key.pem +kube-api +kube-apiserver +kube-dns +kube-inject +kube-proxy +kube-public +kube-system +kubectl +kubelet +kubernetes +kubernetes.default +learnings +lifecycle +listchecker +liveness +mTLS +machine.svg +machineSetup +memcached +memquota +mesos-dns +metadata +metadata.initializers.pending +methodName +microservice +microservices +middleboxes +minikube +misconfigured +mixer-spof-myth-1 +mixer-spof-myth-2 +mongodb +mtls_excluded_services +multicloud +multicluster +mutual-tls +my-svc +my-svc-234443-5sffe +mysql +mysqldb +namespace +namespaces +natively +nginx +nginx-proxy +nodePorts +nodeport +noistio.svg +non-sandboxed +ns +oc +ok +onwards +openssl +packageName.serviceName +parenthesization +pem +phases.svg +platform-specific +pluggable +png +pprof +pre-specified +preconfigured +prefetching +preformatted +preliminary.istio.io +preliminary.istio.io. +prepends +prober +productpage +productpage.ns.svc.cluster.local +products.default.svc.cluster.local +prometheus +prometheus_query_result.png +proto +protobuf +protos +proxied +proxy_http_version +proxying +pwd +qps +quay.io +radis +ratelimit-handler +raw.githubusercontent.com +raw.githubusercontent.com) +reachability +readinessProbe +redis +redis-master-2353460263-1ecey +referer +registrator +reinject +repo +request.api_key +request.auth.audiences +request.auth.claims +request.auth.presenter +request.auth.principal +request.headers +request.host +request.id +request.method +request.path +request.reason +request.referer +request.responseheaders +request.scheme +request.size +request.time +request.useragent +requestcontext +response.code +response.duration +response.headers +response.size +response.time +reviews.abc.svc.cluster.local +roadmap +roleRef +roles_summary.png +rollout +rollouts +routable +runtime +runtimes +sa +sayin +schemas +secretName +serviceaccount +servicegraph-example +setupIstioVM.sh +setupMeshEx.sh +sharded +sharding +sidecar.env +sleep.legacy +sleep.yaml +source.domain +source.ip +source.labels +source.name +source.namespace +source.principal +source.service +source.uid +source.user +spiffe +stackdriver +statsd +stdout +struct +subdomains +substring +svc.cluster.local +svc.com +svg +tcp +team1 +team1-ns +team2 +team2-ns +templated +test-api +timeframe +timestamp +traffic.svg +trustability +ulimit +uncomment +uncommented +unencrypted +unmanaged +untrusted +uptime +url +user +user1 +v1 +v1.7.4 +v1.7.6_coreos.0 +v1alpha1 +v1alpha3 +v1beta1#MutatingWebhookConfiguration +v2 +v2-mysql +v3 +versioned +versioning +virtualservices-destrules +vm-1 +webhook +webhooks +whitelist +whitelists +wikipedia.org +wildcard +withistio.svg +www.google.com +x-envoy-upstream-rq-timeout-ms +x.509 +xDS +yaml +yamls +yournamespace +zipkin_dashboard.png +zipkin_span.png + +qcc + - search.md +searchresults +gcse diff --git a/404.md b/404.md index dcc6ccd1e0faf..8eb11d0d4eca8 100644 --- a/404.md +++ b/404.md @@ -1,16 +1,15 @@ --- title: Page Not Found -overview: Page redirection +description: Page redirection -order: 0 +weight: 1 layout: notfound -type: markdown --- {% include home.html %}
- Warning + Warning
diff --git a/CNAME b/CNAME index 5d3be932f2f95..1a3ca76186416 100644 --- a/CNAME +++ b/CNAME @@ -1 +1 @@ -istio.io +preliminary.istio.io diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4696c8e6ee195..7950e85dc2ae9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,7 @@ -# Contribution guidelines +## Contribution guidelines -So, you want to hack on the Istio web site? Yay! Please refer to Istio's overall +So, you want to hack on the Istio web site? Cool! Please refer to Istio's overall [contribution guidelines](https://github.com/istio/community/blob/master/CONTRIBUTING.md) to find out how you can help. + +For specifics on hacking on our site, check this [info](https://istio.io/about/contribute/) diff --git a/Gemfile b/Gemfile index af8715d432024..7b231be9a2199 100644 --- a/Gemfile +++ b/Gemfile @@ -3,5 +3,6 @@ source "https://rubygems.org" gem "github-pages", group: :jekyll_plugins gem "jekyll-include-cache", "~> 0.1" gem "nokogiri", ">= 1.8.1" -gem "html-proofer", :git => "https://github.com/ldemailly/html-proofer.git" +gem "html-proofer", ">= 3.8.0" gem "rake" +gem "mdl" diff --git a/Gemfile.lock b/Gemfile.lock index 344a041bbf928..662aeaac0897a 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,17 +1,3 @@ -GIT - remote: https://github.com/ldemailly/html-proofer.git - revision: a9fd7130ddf4bffc54ef938783d09a110e46574b - specs: - html-proofer (3.7.5) - activesupport (>= 4.2, < 6.0) - addressable (~> 2.3) - colorize (~> 0.8) - mercenary (~> 0.3.2) - nokogiri (~> 1.7) - parallel (~> 1.3) - typhoeus (~> 0.7) - yell (~> 2.0) - GEM remote: https://rubygems.org/ specs: @@ -28,38 +14,42 @@ GEM coffee-script-source (1.11.1) colorator (1.1.0) colorize (0.8.1) - commonmarker (0.17.7) + commonmarker (0.17.9) ruby-enum (~> 0.5) concurrent-ruby (1.0.5) + em-websocket (0.5.1) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0.6.0) ethon (0.11.0) ffi (>= 1.3.0) + eventmachine (1.2.5) execjs (2.7.0) - faraday (0.13.1) + faraday (0.14.0) multipart-post (>= 1.2, < 3) - ffi (1.9.18) + ffi (1.9.23) forwardable-extended (2.6.0) gemoji (3.0.0) - github-pages (172) + github-pages (180) activesupport (= 4.2.9) - github-pages-health-check (= 1.3.5) - jekyll (= 3.6.2) + github-pages-health-check (= 1.4.0) + jekyll (= 3.7.3) jekyll-avatar (= 0.5.0) - jekyll-coffeescript (= 1.0.2) - jekyll-commonmark-ghpages (= 0.1.3) + jekyll-coffeescript (= 1.1.1) + jekyll-commonmark-ghpages (= 0.1.5) jekyll-default-layout (= 0.1.4) - jekyll-feed (= 0.9.2) - jekyll-gist (= 1.4.1) - jekyll-github-metadata (= 2.9.3) - jekyll-mentions (= 1.2.0) + jekyll-feed (= 0.9.3) + jekyll-gist (= 1.5.0) + jekyll-github-metadata (= 2.9.4) + jekyll-mentions (= 1.3.0) jekyll-optional-front-matter (= 0.3.0) jekyll-paginate (= 1.1.0) jekyll-readme-index (= 0.2.0) - jekyll-redirect-from (= 0.12.1) - jekyll-relative-links (= 0.5.2) + jekyll-redirect-from (= 0.13.0) + jekyll-relative-links (= 0.5.3) jekyll-remote-theme (= 0.2.3) - jekyll-sass-converter (= 1.5.0) - jekyll-seo-tag (= 2.3.0) - jekyll-sitemap (= 1.1.1) + jekyll-sass-converter (= 1.5.2) + jekyll-seo-tag (= 2.4.0) + jekyll-sitemap (= 1.2.0) jekyll-swiss (= 0.4.0) jekyll-theme-architect (= 0.1.0) jekyll-theme-cayman (= 0.1.0) @@ -74,61 +64,74 @@ GEM jekyll-theme-slate (= 0.1.0) jekyll-theme-tactile (= 0.1.0) jekyll-theme-time-machine (= 0.1.0) - jekyll-titles-from-headings (= 0.5.0) - jemoji (= 0.8.1) - kramdown (= 1.14.0) + jekyll-titles-from-headings (= 0.5.1) + jemoji (= 0.9.0) + kramdown (= 1.16.2) liquid (= 4.0.0) - listen (= 3.0.6) + listen (= 3.1.5) mercenary (~> 0.3) - minima (= 2.1.1) + minima (= 2.4.0) + nokogiri (>= 1.8.1, < 2.0) rouge (= 2.2.1) terminal-table (~> 1.4) - github-pages-health-check (1.3.5) + github-pages-health-check (1.4.0) addressable (~> 2.3) net-dns (~> 0.8) octokit (~> 4.0) public_suffix (~> 2.0) - typhoeus (~> 0.7) + typhoeus (~> 1.3) html-pipeline (2.7.1) activesupport (>= 2) nokogiri (>= 1.4) - i18n (0.9.1) + html-proofer (3.8.0) + activesupport (>= 4.2, < 6.0) + addressable (~> 2.3) + colorize (~> 0.8) + mercenary (~> 0.3.2) + nokogiri (~> 1.8.1) + parallel (~> 1.3) + typhoeus (~> 1.3) + yell (~> 2.0) + http_parser.rb (0.6.0) + i18n (0.9.5) concurrent-ruby (~> 1.0) - jekyll (3.6.2) + jekyll (3.7.3) addressable (~> 2.4) colorator (~> 1.0) + em-websocket (~> 0.5) + i18n (~> 0.7) jekyll-sass-converter (~> 1.0) - jekyll-watch (~> 1.1) + jekyll-watch (~> 2.0) kramdown (~> 1.14) liquid (~> 4.0) mercenary (~> 0.3.3) pathutil (~> 0.9) - rouge (>= 1.7, < 3) + rouge (>= 1.7, < 4) safe_yaml (~> 1.0) jekyll-avatar (0.5.0) jekyll (~> 3.0) - jekyll-coffeescript (1.0.2) + jekyll-coffeescript (1.1.1) coffee-script (~> 2.2) coffee-script-source (~> 1.11.1) - jekyll-commonmark (1.1.0) + jekyll-commonmark (1.2.0) commonmarker (~> 0.14) jekyll (>= 3.0, < 4.0) - jekyll-commonmark-ghpages (0.1.3) + jekyll-commonmark-ghpages (0.1.5) commonmarker (~> 0.17.6) jekyll-commonmark (~> 1) rouge (~> 2) jekyll-default-layout (0.1.4) jekyll (~> 3.0) - jekyll-feed (0.9.2) + jekyll-feed (0.9.3) jekyll (~> 3.3) - jekyll-gist (1.4.1) + jekyll-gist (1.5.0) octokit (~> 4.2) - jekyll-github-metadata (2.9.3) + jekyll-github-metadata (2.9.4) jekyll (~> 3.1) octokit (~> 4.0, != 4.4.0) jekyll-include-cache (0.1.0) jekyll (~> 3.3) - jekyll-mentions (1.2.0) + jekyll-mentions (1.3.0) activesupport (~> 4.0) html-pipeline (~> 2.3) jekyll (~> 3.0) @@ -137,19 +140,19 @@ GEM jekyll-paginate (1.1.0) jekyll-readme-index (0.2.0) jekyll (~> 3.0) - jekyll-redirect-from (0.12.1) + jekyll-redirect-from (0.13.0) jekyll (~> 3.3) - jekyll-relative-links (0.5.2) + jekyll-relative-links (0.5.3) jekyll (~> 3.3) jekyll-remote-theme (0.2.3) jekyll (~> 3.5) rubyzip (>= 1.2.1, < 3.0) typhoeus (>= 0.7, < 2.0) - jekyll-sass-converter (1.5.0) + jekyll-sass-converter (1.5.2) sass (~> 3.4) - jekyll-seo-tag (2.3.0) + jekyll-seo-tag (2.4.0) jekyll (~> 3.3) - jekyll-sitemap (1.1.1) + jekyll-sitemap (1.2.0) jekyll (~> 3.3) jekyll-swiss (0.4.0) jekyll-theme-architect (0.1.0) @@ -192,45 +195,56 @@ GEM jekyll-theme-time-machine (0.1.0) jekyll (~> 3.5) jekyll-seo-tag (~> 2.0) - jekyll-titles-from-headings (0.5.0) + jekyll-titles-from-headings (0.5.1) jekyll (~> 3.3) - jekyll-watch (1.5.1) + jekyll-watch (2.0.0) listen (~> 3.0) - jemoji (0.8.1) + jemoji (0.9.0) activesupport (~> 4.0, >= 4.2.9) gemoji (~> 3.0) html-pipeline (~> 2.2) - jekyll (>= 3.0) - kramdown (1.14.0) + jekyll (~> 3.0) + kramdown (1.16.2) liquid (4.0.0) - listen (3.0.6) - rb-fsevent (>= 0.9.3) - rb-inotify (>= 0.9.7) + listen (3.1.5) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) + ruby_dep (~> 1.2) + mdl (0.4.0) + kramdown (~> 1.12, >= 1.12.0) + mixlib-cli (~> 1.7, >= 1.7.0) + mixlib-config (~> 2.2, >= 2.2.1) mercenary (0.3.6) mini_portile2 (2.3.0) - minima (2.1.1) - jekyll (~> 3.3) - minitest (5.10.3) + minima (2.4.0) + jekyll (~> 3.5) + jekyll-feed (~> 0.9) + jekyll-seo-tag (~> 2.1) + minitest (5.11.3) + mixlib-cli (1.7.0) + mixlib-config (2.2.6) + tomlrb multipart-post (2.0.0) net-dns (0.8.0) - nokogiri (1.8.1) + nokogiri (1.8.2) mini_portile2 (~> 2.3.0) - octokit (4.7.0) + octokit (4.8.0) sawyer (~> 0.8.0, >= 0.5.3) - parallel (1.12.0) - pathutil (0.16.0) + parallel (1.12.1) + pathutil (0.16.1) forwardable-extended (~> 2.6) public_suffix (2.0.5) - rake (12.3.0) - rb-fsevent (0.10.2) + rake (12.3.1) + rb-fsevent (0.10.3) rb-inotify (0.9.10) ffi (>= 0.5.0, < 2) rouge (2.2.1) - ruby-enum (0.7.1) + ruby-enum (0.7.2) i18n + ruby_dep (1.5.0) rubyzip (1.2.1) safe_yaml (1.0.4) - sass (3.5.3) + sass (3.5.6) sass-listen (~> 4.0.0) sass-listen (4.0.0) rb-fsevent (~> 0.9, >= 0.9.4) @@ -241,9 +255,10 @@ GEM terminal-table (1.8.0) unicode-display_width (~> 1.1, >= 1.1.1) thread_safe (0.3.6) - typhoeus (0.8.0) - ethon (>= 0.8.0) - tzinfo (1.2.4) + tomlrb (1.2.6) + typhoeus (1.3.0) + ethon (>= 0.9.0) + tzinfo (1.2.5) thread_safe (~> 0.1) unicode-display_width (1.3.0) yell (2.0.7) @@ -253,10 +268,11 @@ PLATFORMS DEPENDENCIES github-pages - html-proofer! + html-proofer (>= 3.8.0) jekyll-include-cache (~> 0.1) + mdl nokogiri (>= 1.8.1) rake BUNDLED WITH - 1.16.0 + 1.16.1 diff --git a/OWNERS b/OWNERS new file mode 100644 index 0000000000000..b682f960cff78 --- /dev/null +++ b/OWNERS @@ -0,0 +1,4 @@ + +approvers: + - geeknoid + - linsun diff --git a/README.md b/README.md index 06edc37c58c22..688321aebfa5e 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,31 @@ -# istio.github.io +## istio.github.io -This repository contains the source code for the [istio.io](https://istio.io) web site. +This repository contains the source code for the [istio.io](https://istio.io), +[preliminary.istio.io](https://preliminary.istio.io) and [archive.istio.io](https://archive.istio.io) sites. Please see the main Istio [README](https://github.com/istio/istio/blob/master/README.md) file to learn about the overall Istio project and how to get in touch with us. To learn how you can contribute to any of the Istio components, please see the Istio [contribution guidelines](https://github.com/istio/community/blob/master/CONTRIBUTING.md). -The website uses [Jekyll](https://jekyllrb.com/) templates and is hosted on GitHub Pages. Please make sure you are -familiar with these before editing. +* [Working with the site](#working-with-the-site) +* [Linting](#linting) +* [Versions and releases](#versions-and-releases) + * [How versioning works](#how-versioning-works) + * [Publishing content immediately](#publishing-content-immediately) + * [Creating a version](#creating-a-version) -To run the site locally with Docker, use the following command from the toplevel directory for this git repo +## Working with the site + +We use [Jekyll](https://jekyllrb.com/) to generate our sites. + +To run the site locally with Docker, use the following command from the top level directory for this git repo (e.g. pwd must be `~/github/istio.github.io` if you were in `~/github` when you issued `git clone https://github.com/istio/istio.github.io.git`) ```bash # First time: (slow) -docker run --name istio-jekyll --volume=$(pwd):/srv/jekyll -it -p 4000:4000 jekyll/jekyll:3.5.2 sh -c "bundle install && rake test && bundle exec jekyll serve --incremental --host 0.0.0.0" +docker run --name istio-jekyll --volume=$(pwd):/srv/jekyll -w /srv/jekyll -it -p 4000:4000 jekyll/jekyll:3.7.3 sh -c "bundle install && rake test && bundle exec jekyll serve --incremental --host 0.0.0.0" # Then open browser with url 127.0.0.1:4000 to see the change. # Subsequent, each time you want to see a new change and you stopped the previous run by ctrl+c: (much faster) docker start istio-jekyll -a -i @@ -24,23 +33,24 @@ docker start istio-jekyll -a -i docker rm istio-jekyll ``` -The `rake test` part is to make sure you are not introducing html errors or bad links, you should see -``` +The `rake test` part is to make sure you are not introducing HTML errors or bad links, you should see + +```bash HTML-Proofer finished successfully. ``` -in the output - -> In some cases the `--incremental` may not work properly and you might have to remove it. -## Local/Native Jekyll install: +in the output. -Alternatively, if you just want to develop locally w/o Docker/Kubernetes/Minikube, you can try installing Jekyll locally. You may need to install other prerequisites manually (which is where using the docker image shines). Here's an example of doing so for Mac OS X: +Alternatively, if you just want to develop locally w/o Docker/Kubernetes/Minikube, you can try installing Jekyll locally. +You may need to install other prerequisites manually (which is where using the docker image shines). Here's an example of doing +so for Mac OS X: -``` +```bash xcode-select --install sudo xcodebuild -license brew install ruby gem update --system +gem install mdspell gem install bundler gem install jekyll cd istio.github.io @@ -48,3 +58,117 @@ bundle install bundle exec rake test bundle exec jekyll serve ``` + +## Linting + +You should run `scripts/linters.sh` prior to checking in your changes. +This will run 3 tests: + +* HTML proofing, which ensures all your links are valid along with other checks. + +* Spell checking. + +* Style checking, which makes sure your markdown file complies with some common style rules. + +If you get a spelling error, you have three choices to address it: + +* It's a real typo, so fix your markdown. + +* It's a command/field/symbol name, so stick some `backticks` around it. + +* It's really valid, so go add the word to the .spelling file at the root of the repo. + +## Versions and releases + +Istio maintains three variations of its public site: + +* [istio.io](https://istio.io) is the main site, showing documentation for the current release of the product. +This site is currently hosted on Firebase. + +* [archive.istio.io](https://archive.istio.io) contains snapshots of the documentation for previous releases of the product. +This is useful for customers still using these older releases. +This site is currently hosted on Firebase. + +* [preliminary.istio.io](https://preliminary.istio.io) contains the actively updated documentation for the next release of the product. +This site is hosted by GitHub Pages. + +The user can trivially navigate between the different variations of the site using the gear menu in the top right +of each page. + +### How versioning works + +* Documentation changes are primarily committed to the master branch of istio.github.io. Changes committed to this branch +are automatically reflected on preliminary.istio.io. + +* The content of istio.io is taken from the latest release-XXX branch. The specific branch that +is used is determined by the `BRANCH` variable in this [script](https://github.com/istio/admin-sites/blob/master/current.istio.io/build.sh) + +* The content of archive.istio.io is taken from the older release-XXX branches. The set of branches that +are included on archive.istio.io is determined by the `TOBUILD` variable in this +[script](https://github.com/istio/admin-sites/blob/master/archive.istio.io/build.sh) + +> The above means that if you want to do a change to the main istio.io site, you will need +to make the change in the master branch of istio.github.io and then merge that change into the +release branch. + +### Publishing content immediately + +Checking in updates to the master branch will automatically update preliminary.istio.io, and will only be reflected on +istio.io the next time a release is created, which can be several weeks in the future. If you'd like some changes to be +immediately reflected on istio.io, you need to check your changes both to the master branch and to the +current release branch (named release-XXX such as release-0.7). + +### Creating a version + +Here are the steps necessary to create a new documentation version. Let's assume the current +version of Istio is 0.6 and you wish to introduce 0.7 which has been under development. + +1. Create a new release branch off of master, named as release-*major*.*minor*, which in this case would be +release-0.7. There is one such branch for every release. + +1. In the **master** branch, edit the file `_data/istio.yml` and update the `version` field to have the version +of the next release of Istio. In this case, you would set the field to 0.8. + +1. In the **master** branch, edit the file `_data/releases.yml` and add a new entry at the top of the file +for version 0.8. You'll need to make sure the URLs are updated for the first few entries. The top +entry (0.8) should point to preliminary.istio.io. The second entry (0.7) should point to istio.io. The third +and subsequent entries should point to archive.istio.io. + +1. Commit the previous two edits to GitHub. + +1. In the **release** branch you created, edit the file `_data/istio.yml`. Set the `preliminary` field to `false`. + +1. Commit the previous edit to GitHub. + +1. Go to the Google Search Console and create a new search engine that searches the archive.istio.io/V<major>.<minor> +directory. This search engine will be used to perform version-specific searches on archive.istio.io. + +1. In the **previous release's** branch (in this case release-0.6), edit the file `_data/istio.yml`. Set the +`archive` field to true, the `archive_date` field to the current date, and the `search_engine_id` field +to the ID of the search engine you created in the prior step. + +1. Switch to the istio/admin-sites repo. + +1. Navigate to the archive.istio.io directory. + +1. Edit the `build.sh` script to add the newest archive version (in this case +release-0.6) to the `TOBUILD` variable. + +1. Commit the previous edit to GitHub. + +1. Run the `build.sh` script. + +1. Once the script completes, run `firebase deploy`. This will update archive.istio.io to contain the +right set of archives, based on the above steps. + +1. Navigate to the current.istio.io directory. + +1. Edit the `build.sh` script to set the `BRANCH` variable to the current release branch (in this case release-0.7) + +1. Run the `build.sh` script. + +1. Once the script completes, run 'firebase deploy`. This will update the content of istio.io to reflect what is the new release +branch you created. + +Once all this is done, browse the three sites (preliminary.istio.io, istio.io, and archive.istio.io) to make sure +everything looks good. diff --git a/Rakefile b/Rakefile index 3582bd8fc57a1..3cfb235b8ea97 100644 --- a/Rakefile +++ b/Rakefile @@ -1,7 +1,9 @@ require 'html-proofer' task :test do - sh "bundle exec jekyll build --incremental" + sh "rm -fr _rakesite" + sh "mkdir _rakesite" + sh "bundle exec jekyll build --config _config.yml,_rake_config_override.yml" typhoeus_configuration = { :timeout => 30, # :verbose => true @@ -17,5 +19,5 @@ task :test do :url_ignore => [/localhost|github\.com\/istio\/istio\.github\.io\/edit\/master\//], :typhoeus => typhoeus_configuration, } - HTMLProofer.check_directory("./_site", options).run + HTMLProofer.check_directory("./_rakesite", options).run end diff --git a/_about/contribute/creating-a-pull-request.md b/_about/contribute/creating-a-pull-request.md index 8c05dc8c67660..59b0eebf86976 100644 --- a/_about/contribute/creating-a-pull-request.md +++ b/_about/contribute/creating-a-pull-request.md @@ -1,23 +1,21 @@ --- title: Creating a Pull Request -overview: Shows you how to create a GitHub pull request in order to submit your docs for approval. +description: Shows you how to create a GitHub pull request in order to submit your docs for approval. -order: 20 +weight: 20 -layout: about -type: markdown redirect_from: /docs/welcome/contribute/creating-a-pull-request.html --- To contribute to Istio documentation, create a pull request against the -[istio/istio.github.io](https://github.com/istio/istio.github.io){: target="_blank"} +[istio/istio.github.io](https://github.com/istio/istio.github.io) repository. This page shows the steps necessary to create a pull request. ## Before you begin -1. Create a [GitHub account](https://github.com){: target="_blank"}. +1. Create a [GitHub account](https://github.com). -1. Sign the [Contributor License Agreement](https://github.com/istio/community/blob/master/CONTRIBUTING.md#contributor-license-agreements) +1. Sign the [Contributor License Agreement](https://github.com/istio/community/blob/master/CONTRIBUTING.md#contributor-license-agreements). Documentation will be published under the [Apache 2.0](https://github.com/istio/istio.github.io/blob/master/LICENSE) license. @@ -26,7 +24,7 @@ Documentation will be published under the [Apache 2.0](https://github.com/istio/ Before you can edit documentation, you need to create a fork of Istio's documentation GitHub repository: 1. Go to the -[istio/istio.github.io](https://github.com/istio/istio.github.io){: target="_blank"} +[istio/istio.github.io](https://github.com/istio/istio.github.io) repository. 1. In the upper-right corner, click **Fork**. This creates a copy of Istio's @@ -57,3 +55,6 @@ repository. This opens a page that shows the status of your pull request. 1. During the next few days, check your pull request for reviewer comments. If needed, revise your pull request by committing changes to your new branch in your fork. + +> Once your changes have been committed, they will show up immediately on [preliminary.istio.io](https://preliminary.istio.io), but +will only show up on [istio.io](http://istio.io) the next time we produce a new release, which happens around once a month. diff --git a/_about/contribute/editing.md b/_about/contribute/editing.md index 78eaa56d8d10c..28d7b8fbab598 100644 --- a/_about/contribute/editing.md +++ b/_about/contribute/editing.md @@ -1,17 +1,18 @@ --- title: Editing Docs -overview: Lets you start editing this site's documentation. - -order: 10 +description: Lets you start editing this site's documentation. + +weight: 10 -layout: about -type: markdown redirect_from: /docs/welcome/contribute/editing.html --- Click the button below to visit the GitHub repository for this whole web site. You can then click the -**Fork** button in the upper-right area of the screen to +**Fork** button in the upper-right area of the screen to create a copy of our site in your GitHub account called a _fork_. Make any changes you want in your fork, and when you are ready to send those changes to us, go to the index page for your fork and click **New Pull Request** to let us know about it. Browse this site's source code + +> Once your changes have been committed, they will show up immediately on [preliminary.istio.io](https://preliminary.istio.io), but +will only show up on [istio.io](http://istio.io) the next time we produce a new release, which happens around once a month. diff --git a/_about/contribute/index.md b/_about/contribute/index.md index 7a81d0c780592..16c808dc5be06 100644 --- a/_about/contribute/index.md +++ b/_about/contribute/index.md @@ -1,13 +1,11 @@ --- title: Contributing to the Docs -overview: Learn how to contribute to improve and expand the Istio documentation. +description: Learn how to contribute to improve and expand the Istio documentation. -order: 100 +weight: 100 -layout: about -type: markdown toc: false redirect_from: /docs/welcome/contribute/index.html --- -{% include section-index.html docs=site.docs %} +{% include section-index.html docs=site.about %} diff --git a/_about/contribute/reviewing-doc-issues.md b/_about/contribute/reviewing-doc-issues.md index f1d17af5928b7..5c2ef7df21bf5 100644 --- a/_about/contribute/reviewing-doc-issues.md +++ b/_about/contribute/reviewing-doc-issues.md @@ -1,16 +1,14 @@ --- title: Doc Issues -overview: Explains the process involved in accepting documentation updates. - -order: 60 +description: Explains the process involved in accepting documentation updates. + +weight: 60 -layout: about -type: markdown redirect_from: /docs/welcome/contribute/reviewing-doc-issues.html --- This page explains how documentation issues are reviewed and prioritized for the -[istio/istio.github.io](https://github.com/istio/istio.github.io){: target="_blank"} repository. +[istio/istio.github.io](https://github.com/istio/istio.github.io) repository. The purpose is to provide a way to organize issues and make it easier to contribute to Istio documentation. The following should be used as the standard way of prioritizing, labeling, and interacting with issues. @@ -25,7 +23,7 @@ the issue with your reasoning for the change. P1