From 75525f5b53ea81fb514c5df3d3da79cc01442f52 Mon Sep 17 00:00:00 2001 From: Anders Kaseorg Date: Tue, 15 Feb 2022 16:39:15 -0800 Subject: [PATCH] docs: Convert .html#fragment links to .md#fragment. This uses the myst_heading_anchors option to automatically generate header anchors and make Sphinx aware of them. See https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#auto-generated-header-anchors. Note: to be compatible with GitHub, MyST-Parser uses a slightly different convention for .md fragment links than .html fragment links when punctuation is involved. This does not affect the generated fragment links in the HTML output. Fixes #13264. Signed-off-by: Anders Kaseorg --- docs/conf.py | 1 + docs/contributing/code-reviewing.md | 4 +-- docs/contributing/gsoc.md | 8 ++--- docs/contributing/version-control.md | 2 +- docs/development/authentication.md | 6 ++-- docs/development/overview.md | 8 ++--- docs/development/remote.md | 4 +-- docs/development/setup-advanced.md | 12 +++---- docs/development/setup-vagrant.md | 10 +++--- docs/development/using.md | 2 +- docs/documentation/api.md | 2 +- docs/documentation/overview.md | 2 +- docs/git/cheat-sheet.md | 2 +- docs/git/cloning.md | 2 +- docs/git/collaborate.md | 2 +- docs/git/overview.md | 8 ++--- docs/git/pull-requests.md | 6 ++-- docs/git/setup.md | 2 +- docs/git/troubleshooting.md | 4 +-- docs/git/using.md | 6 ++-- docs/git/zulip-tools.md | 4 +-- docs/overview/architecture-overview.md | 4 +-- docs/overview/changelog.md | 36 ++++++++++---------- docs/overview/release-lifecycle.md | 10 +++--- docs/production/authentication-methods.md | 4 +-- docs/production/deployment.md | 30 ++++++++-------- docs/production/email-gateway.md | 2 +- docs/production/export-and-import.md | 8 ++--- docs/production/install.md | 12 +++---- docs/production/maintain-secure-upgrade.md | 10 +++--- docs/production/management-commands.md | 6 ++-- docs/production/mobile-push-notifications.md | 4 +-- docs/production/multiple-organizations.md | 2 +- docs/production/password-strength.md | 2 +- docs/production/postgresql.md | 2 +- docs/production/requirements.md | 20 +++++------ docs/production/security-model.md | 4 +-- docs/production/settings.md | 2 +- docs/production/ssl-certificates.md | 2 +- docs/production/troubleshooting.md | 2 +- docs/production/upgrade-or-modify.md | 16 ++++----- docs/subsystems/dependencies.md | 2 +- docs/subsystems/email.md | 4 +-- docs/subsystems/performance.md | 6 ++-- docs/subsystems/release-checklist.md | 2 +- docs/subsystems/settings.md | 2 +- docs/testing/linters.md | 2 +- docs/testing/testing-with-django.md | 6 ++-- docs/testing/testing.md | 2 +- docs/translating/internationalization.md | 6 ++-- docs/translating/translating.md | 4 +-- docs/tutorials/life-of-a-request.md | 2 +- docs/tutorials/new-feature-tutorial.md | 4 +-- docs/tutorials/shell-tips.md | 2 +- docs/tutorials/writing-views.md | 2 +- 55 files changed, 161 insertions(+), 160 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index d2ef139c8e..44c6a0853a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -36,6 +36,7 @@ myst_enable_extensions = [ "colon_fence", "substitution", ] +myst_heading_anchors = 6 myst_substitutions = { "LATEST_RELEASE_VERSION": LATEST_RELEASE_VERSION, } diff --git a/docs/contributing/code-reviewing.md b/docs/contributing/code-reviewing.md index 7d42f43f58..0c47a9c14a 100644 --- a/docs/contributing/code-reviewing.md +++ b/docs/contributing/code-reviewing.md @@ -237,8 +237,8 @@ We also strongly recommend reviewers to go through the following resources. - [Zulip code of conduct](../code-of-conduct.md) [code-style]: code-style.md -[commit-messages]: version-control.html#commit-messages +[commit-messages]: version-control.md#commit-messages [test-writing]: ../testing/testing.md [mypy]: ../testing/mypy.md -[git tool]: ../git/zulip-tools.html#fetch-a-pull-request-and-rebase +[git tool]: ../git/zulip-tools.md#fetch-a-pull-request-and-rebase [translation]: ../translating/translating.md diff --git a/docs/contributing/gsoc.md b/docs/contributing/gsoc.md index f396af261e..edd368c339 100644 --- a/docs/contributing/gsoc.md +++ b/docs/contributing/gsoc.md @@ -28,7 +28,7 @@ your GSoC experience with the Zulip project will be highly interactive. As part of our commitment to mentorship, Zulip has over 160,000 words of [documentation for -developers](../index.html#welcome-to-the-zulip-documentation), much of it +developers](../index.md#welcome-to-the-zulip-documentation), much of it designed to explain not just how Zulip works, but why Zulip works the way that it does. To learn more about our mission and values, check out [this blog post](https://blog.zulip.com/2021/04/28/why-zulip-is-on-github-sponsors/)! @@ -67,7 +67,7 @@ also give you a feel for what it's like to do GSoC with us. We have an easy-to-set-up development environment, and a library of tasks that are great for first-time contributors. Use -[our first-time Zulip developer guide](../overview/contributing.html#your-first-codebase-contribution) +[our first-time Zulip developer guide](../overview/contributing.md#your-first-codebase-contribution) to get your Zulip development environment set up and to find your first issue. If you have any trouble, please speak up in the [#GSoC](https://chat.zulip.org/#narrow/stream/14-GSoC) stream on the @@ -135,7 +135,7 @@ For the first time in 2022, being a student is not required in order to apply to GSoC. We are happy to accept both student and non-student participants. Our documentation on [what makes a great Zulip -contributor](../overview/contributing.html#what-makes-a-great-zulip-contributor) +contributor](../overview/contributing.md#what-makes-a-great-zulip-contributor) offers some additional helpful information. We also recommend reviewing the [official GSoC resources](https://developers.google.com/open-source/gsoc/resources/), @@ -169,7 +169,7 @@ other contributors learn from reading the conversation. - [Try, Then Ask](https://www.mattringel.com/2013/09/30/you-must-try-and-then-you-must-ask/) - [We Aren’t Just Making Code, We’re Making History](https://www.harihareswara.net/sumana/2016/10/12/0) - [How to Ask Good Questions](https://jvns.ca/blog/good-questions/) -- Understand [what makes a great Zulip contributor](../overview/contributing.html#what-makes-a-great-zulip-contributor) +- Understand [what makes a great Zulip contributor](../overview/contributing.md#what-makes-a-great-zulip-contributor) This is a typical question/response sequence: diff --git a/docs/contributing/version-control.md b/docs/contributing/version-control.md index 02feec9f64..1aca46f655 100644 --- a/docs/contributing/version-control.md +++ b/docs/contributing/version-control.md @@ -139,7 +139,7 @@ commit message. **Tip:** You can set up [Zulip's Git pre-commit hook][commit-hook] to automatically catch common mistakes in the commit message itself. -[commit-hook]: ../git/zulip-tools.html#set-up-git-repo-script +[commit-hook]: ../git/zulip-tools.md#set-up-git-repo-script ### Message body: diff --git a/docs/development/authentication.md b/docs/development/authentication.md index 9eb758ce96..a863298808 100644 --- a/docs/development/authentication.md +++ b/docs/development/authentication.md @@ -140,14 +140,14 @@ URL they post back to, which isn't supported directly by the Zulip development environment. If you run a [remote Zulip development server](remote.md), we have instructions for -[an nginx reverse proxy with SSL](remote.html#using-an-nginx-reverse-proxy) +[an nginx reverse proxy with SSL](remote.md#using-an-nginx-reverse-proxy) that you can use for your development efforts. ## Testing LDAP in development Before Zulip 2.0, one of the more common classes of bug reports with Zulip's authentication was users having trouble getting [LDAP -authentication](../production/authentication-methods.html#ldap-including-active-directory) +authentication](../production/authentication-methods.md#ldap-including-active-directory) working. The root cause was because setting up a local LDAP server for development was difficult, which meant most developers were unable to work on fixing even simple issues with it. @@ -161,7 +161,7 @@ actual flows for LDAP configuration. - To enable fakeldap, set `FAKE_LDAP_MODE` in `zproject/dev_settings.py` to one of the following options. For more information on these modes, refer to - [our production docs](../production/authentication-methods.html#ldap-including-active-directory): + [our production docs](../production/authentication-methods.md#ldap-including-active-directory): - `a`: If users' email addresses are in LDAP and used as username. - `b`: If LDAP only has usernames but email addresses are of the form diff --git a/docs/development/overview.md b/docs/development/overview.md index 7c3f1cad91..efe311808f 100644 --- a/docs/development/overview.md +++ b/docs/development/overview.md @@ -76,12 +76,12 @@ machine, take a look at our tips for [developing remotely][dev-remote]. [dev-remote]: remote.md -[install-direct]: setup-advanced.html#installing-directly-on-ubuntu-debian-centos-or-fedora +[install-direct]: setup-advanced.md#installing-directly-on-ubuntu-debian-centos-or-fedora [install-vagrant]: setup-vagrant.md [self-install-remote]: #installing-remotely [self-slow-internet]: #slow-internet-connections -[configure-proxy]: setup-vagrant.html#specifying-a-proxy +[configure-proxy]: setup-vagrant.md#specifying-a-proxy [using-dev-env]: using.md [testing]: ../testing/testing.md -[ci]: ../git/cloning.html#step-3-configure-continuous-integration-for-your-fork -[install-via-wsl]: setup-advanced.html#installing-directly-on-windows-10-with-wsl-2 +[ci]: ../git/cloning.md#step-3-configure-continuous-integration-for-your-fork +[install-via-wsl]: setup-advanced.md#installing-directly-on-windows-10-with-wsl-2 diff --git a/docs/development/remote.md b/docs/development/remote.md index 27516db347..eac8b7dbf5 100644 --- a/docs/development/remote.md +++ b/docs/development/remote.md @@ -270,7 +270,7 @@ Next, read the following to learn more about developing for Zulip: - [Using the development environment][rtd-using-dev-env] - [Testing][rtd-testing] -[install-direct]: setup-advanced.html#installing-directly-on-ubuntu-debian-centos-or-fedora +[install-direct]: setup-advanced.md#installing-directly-on-ubuntu-debian-centos-or-fedora [install-vagrant]: setup-vagrant.md [rtd-git-guide]: ../git/index.md [rtd-using-dev-env]: using.md @@ -292,7 +292,7 @@ that the user is `zulipdev`; edit accordingly if the situation is different. 1. First, get an SSL certificate; you can use - [our certbot wrapper script used for production](../production/ssl-certificates.html#certbot-recommended) + [our certbot wrapper script used for production](../production/ssl-certificates.md#certbot-recommended) by running the following commands as root: ```bash diff --git a/docs/development/setup-advanced.md b/docs/development/setup-advanced.md index 5eddc9435e..a24d731f03 100644 --- a/docs/development/setup-advanced.md +++ b/docs/development/setup-advanced.md @@ -23,7 +23,7 @@ You can just run the Zulip provision script on your machine. **Note**: You should not use the `root` user to run the installation. If you are using a [remote server](remote.md), see the -[section on creating appropriate user accounts](remote.html#setting-up-user-accounts). +[section on creating appropriate user accounts](remote.md#setting-up-user-accounts). :::{warning} There is no supported uninstallation process with this @@ -50,7 +50,7 @@ source /srv/zulip-py3-venv/bin/activate Once you've done the above setup, you can pick up the [documentation on using the Zulip development -environment](setup-vagrant.html#step-4-developing), +environment](setup-vagrant.md#step-4-developing), ignoring the parts about `vagrant` (since you're not using it). ## Installing directly on Windows 10 with WSL 2 @@ -101,7 +101,7 @@ installation method described here. cd ~ # or cd /home/USERNAME ``` -1. [Create your fork](../git/cloning.html#step-1a-create-your-fork) of +1. [Create your fork](../git/cloning.md#step-1a-create-your-fork) of the [Zulip server repository](https://github.com/zulip/zulip). 1. [Create a new SSH key][create-ssh-key] for the WSL-2 Virtual @@ -151,7 +151,7 @@ installation method described here. to open VSCode connected to your WSL environment. 1. You're done! You can pick up the [documentation on using the - Zulip development environment](setup-vagrant.html#step-4-developing), + Zulip development environment](setup-vagrant.md#step-4-developing), ignoring the parts about `vagrant` (since you're not using it). WSL 2 can be uninstalled by following [Microsoft's documentation][uninstall-wsl] @@ -302,5 +302,5 @@ submit a pull request, or you can ask for help in in [the Zulip development community](https://zulip.com/development-community/), and a core team member can help guide you through adding support for the platform. -[zulip-rtd-git-cloning]: ../git/cloning.html#step-1b-clone-to-your-machine -[zulip-rtd-git-connect]: ../git/cloning.html#step-1c-connect-your-fork-to-zulip-upstream +[zulip-rtd-git-cloning]: ../git/cloning.md#step-1b-clone-to-your-machine +[zulip-rtd-git-connect]: ../git/cloning.md#step-1c-connect-your-fork-to-zulip-upstream diff --git a/docs/development/setup-vagrant.md b/docs/development/setup-vagrant.md index 748cdd38dc..84a57c8153 100644 --- a/docs/development/setup-vagrant.md +++ b/docs/development/setup-vagrant.md @@ -12,7 +12,7 @@ all related services will run. Contents: - [Requirements](#requirements) -- [Step 0: Set up Git & GitHub](#step-0-set-up-git-github) +- [Step 0: Set up Git & GitHub](#step-0-set-up-git--github) - [Step 1: Install prerequisites](#step-1-install-prerequisites) - [Step 2: Get Zulip code](#step-2-get-zulip-code) - [Step 3: Start the development environment](#step-3-start-the-development-environment) @@ -151,7 +151,7 @@ Debian](https://docs.docker.com/install/linux/docker-ce/debian/). #### Windows 10 :::{note} -We recommend using [WSL 2 for Windows development](setup-advanced.html#installing-directly-on-windows-10-with-wsl-2). +We recommend using [WSL 2 for Windows development](setup-advanced.md#installing-directly-on-windows-10-with-wsl-2). ::: 1. Install [Git for Windows][git-bash], which installs _Git BASH_. @@ -236,8 +236,8 @@ projects and to instead follow these instructions exactly.) 2. Open Terminal (macOS/Linux) or Git BASH (Windows; must **run as an Administrator**). 3. In Terminal/Git BASH, - [clone your fork of the Zulip repository](../git/cloning.html#step-1b-clone-to-your-machine) and - [connect the Zulip upstream repository](../git/cloning.html#step-1c-connect-your-fork-to-zulip-upstream): + [clone your fork of the Zulip repository](../git/cloning.md#step-1b-clone-to-your-machine) and + [connect the Zulip upstream repository](../git/cloning.md#step-1c-connect-your-fork-to-zulip-upstream): ```bash git clone --config pull.rebase git@github.com:YOURUSERNAME/zulip.git @@ -1049,4 +1049,4 @@ remove the `GUEST_CPUS` and `GUEST_MEMORY_MB` lines from [git-bash]: https://git-for-windows.github.io/ [bash-admin-setup]: https://superuser.com/questions/1002262/run-applications-as-administrator-by-default-in-windows-10 [set-up-git]: ../git/setup.md -[ci]: ../git/cloning.html#step-3-configure-continuous-integration-for-your-fork +[ci]: ../git/cloning.md#step-3-configure-continuous-integration-for-your-fork diff --git a/docs/development/using.md b/docs/development/using.md index 0f760fbdd3..53141b25a1 100644 --- a/docs/development/using.md +++ b/docs/development/using.md @@ -23,7 +23,7 @@ the development environment][authentication-dev-server]. - After making changes, you'll often want to run the [linters](../testing/linters.md) and relevant [test suites](../testing/testing.md). Consider using our [Git pre-commit - hook](../git/zulip-tools.html#set-up-git-repo-script) to + hook](../git/zulip-tools.md#set-up-git-repo-script) to automatically lint whenever you make a commit. - All of our test suites are designed to support quickly testing just a single file or test case, which you should take advantage of to diff --git a/docs/documentation/api.md b/docs/documentation/api.md index d228a15e5b..81aa313ed4 100644 --- a/docs/documentation/api.md +++ b/docs/documentation/api.md @@ -247,7 +247,7 @@ above. defined OpenAPI schema. Use `test-backend --rerun` for a fast edit/refresh cycle when debugging. - [rest-api-tutorial]: ../tutorials/writing-views.html#writing-api-rest-endpoints + [rest-api-tutorial]: ../tutorials/writing-views.md#writing-api-rest-endpoints 1. Add a function for the endpoint you'd like to document to `zerver/openapi/python_examples.py`, decorated with diff --git a/docs/documentation/overview.md b/docs/documentation/overview.md index ffee6610a7..2d9911215d 100644 --- a/docs/documentation/overview.md +++ b/docs/documentation/overview.md @@ -134,7 +134,7 @@ recommend running locally when making significant edits: - `tools/lint` catches a number of common mistakes, and we highly recommend - [using our linter pre-commit hook](../git/zulip-tools.html#set-up-git-repo-script). + [using our linter pre-commit hook](../git/zulip-tools.md#set-up-git-repo-script). See the [main linter doc](../testing/linters.md) for more details. - The ReadTheDocs docs are built and the links tested by diff --git a/docs/git/cheat-sheet.md b/docs/git/cheat-sheet.md index 878d6ddb6f..4489da73c6 100644 --- a/docs/git/cheat-sheet.md +++ b/docs/git/cheat-sheet.md @@ -112,5 +112,5 @@ See also [fixing commits][fix-commit] - `git status`: show the working tree status, unstaged and staged files [fix-commit]: fixing-commits.md -[git-config-clone]: cloning.html#step-1b-clone-to-your-machine +[git-config-clone]: cloning.md#step-1b-clone-to-your-machine [git-overview]: overview.md diff --git a/docs/git/cloning.md b/docs/git/cloning.md index e40e223e18..676d67b179 100644 --- a/docs/git/cloning.md +++ b/docs/git/cloning.md @@ -137,4 +137,4 @@ You can check the `Actions` tab of your repository to see the builds. [github-actions]: https://docs.github.com/en/actions [zulip-rtd-dev-first-time]: ../development/setup-vagrant.md [zulip-rtd-dev-overview]: ../development/overview.md -[zulip-rtd-tools-setup]: zulip-tools.html#set-up-git-repo-script +[zulip-rtd-tools-setup]: zulip-tools.md#set-up-git-repo-script diff --git a/docs/git/collaborate.md b/docs/git/collaborate.md index e11f81bfdd..fee098f6b3 100644 --- a/docs/git/collaborate.md +++ b/docs/git/collaborate.md @@ -56,4 +56,4 @@ tools/fetch-pull-request ``` [github-help-co-pr-locally]: https://help.github.com/en/articles/checking-out-pull-requests-locally -[tools-pr]: zulip-tools.html#fetch-a-pull-request-and-rebase +[tools-pr]: zulip-tools.md#fetch-a-pull-request-and-rebase diff --git a/docs/git/overview.md b/docs/git/overview.md index 2988f5f92f..0b304453fa 100644 --- a/docs/git/overview.md +++ b/docs/git/overview.md @@ -59,12 +59,12 @@ Git workflow, or if you'd like a Git refresher. [github-zulip]: https://github.com/zulip/ [github-zulip-zulip]: https://github.com/zulip/zulip/ [continuous-integration]: ../testing/continuous-integration.md -[zulip-git-guide-fork-ci]: cloning.html#step-3-configure-continuous-integration-for-your-fork +[zulip-git-guide-fork-ci]: cloning.md#step-3-configure-continuous-integration-for-your-fork [zulip-rtd-code-style]: ../contributing/code-style.md -[zulip-rtd-commit-discipline]: ../contributing/version-control.html#commit-discipline -[zulip-rtd-commit-messages]: ../contributing/version-control.html#commit-messages +[zulip-rtd-commit-discipline]: ../contributing/version-control.md#commit-discipline +[zulip-rtd-commit-messages]: ../contributing/version-control.md#commit-messages [zulip-rtd-dev-overview]: ../development/overview.md -[zulip-rtd-lint-tools]: ../contributing/code-style.html#lint-tools +[zulip-rtd-lint-tools]: ../contributing/code-style.md#lint-tools [zulip-rtd-mypy]: ../testing/mypy.md [zulip-rtd-testing]: ../testing/testing.md [zulip-rtd-zulip-tools]: zulip-tools.md diff --git a/docs/git/pull-requests.md b/docs/git/pull-requests.md index e0288b6602..faf66a99e9 100644 --- a/docs/git/pull-requests.md +++ b/docs/git/pull-requests.md @@ -29,7 +29,7 @@ work from being merged before you're confident in it. ### Step 0: Make sure you're on a feature branch (not `main`) It is important to [work on a feature -branch](using.html#work-on-a-feature-branch) when creating a pull +branch](using.md#work-on-a-feature-branch) when creating a pull request. Your new pull request will be inextricably linked with your branch while it is open, so you will need to reserve your branch only for changes related to your issue, and avoid introducing extraneous @@ -158,7 +158,7 @@ for another review. [github-help-about-pr]: https://help.github.com/en/articles/about-pull-requests [github-help-create-pr-fork]: https://help.github.com/en/articles/creating-a-pull-request-from-a-fork [images-create-pr]: ../images/zulip-open-pr.png -[keep-up-to-date]: using.html#keep-your-fork-up-to-date -[self-push-commits]: using.html#push-your-commits-to-github +[keep-up-to-date]: using.md#keep-your-fork-up-to-date +[self-push-commits]: using.md#push-your-commits-to-github [screenshots-gifs]: ../tutorials/screenshot-and-gif-software.md [wip-prs]: #work-in-progress-pull-requests diff --git a/docs/git/setup.md b/docs/git/setup.md index e5e3e74170..de41fa3762 100644 --- a/docs/git/setup.md +++ b/docs/git/setup.md @@ -49,7 +49,7 @@ text-mode interface to Git. And, if none of the above are to your liking, try [one of these][gitbook-guis]. -[git-bash-admin]: ../development/setup-vagrant.html#running-git-bash-as-an-administrator +[git-bash-admin]: ../development/setup-vagrant.md#running-git-bash-as-an-administrator [gitbook-aliases]: https://git-scm.com/book/en/v2/Git-Basics-Git-Aliases [gitbook-config]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration [gitbook-guis]: https://git-scm.com/downloads/guis diff --git a/docs/git/troubleshooting.md b/docs/git/troubleshooting.md index deef5c7f22..ded896a12e 100644 --- a/docs/git/troubleshooting.md +++ b/docs/git/troubleshooting.md @@ -275,8 +275,8 @@ keep,** you'll need to use `git log FETCH_HEAD` to identify that hashes of the commits you want to keep and then `git cherry-pick ` those commits into whichever branch you need to update. -[clone-to-your-machine]: cloning.html#step-1b-clone-to-your-machine -[connect-upstream]: cloning.html#step-1c-connect-your-fork-to-zulip-upstream +[clone-to-your-machine]: cloning.md#step-1b-clone-to-your-machine +[connect-upstream]: cloning.md#step-1c-connect-your-fork-to-zulip-upstream [gitbook-advanced-merging]: https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging#_advanced_merging [gitbook-basic-merge-conflicts]: https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging#Basic-Merge-Conflicts [gitbook-git-cherry-pick]: https://git-scm.com/docs/git-cherry-pick diff --git a/docs/git/using.md b/docs/git/using.md index 40aa6c5f07..48c137ef79 100644 --- a/docs/git/using.md +++ b/docs/git/using.md @@ -451,7 +451,7 @@ complicated rebase. [github-help-rebase]: https://help.github.com/en/articles/using-git-rebase [github-help-sync-fork]: https://help.github.com/en/articles/syncing-a-fork [how-git-is-different]: the-git-difference.md -[self-multiple-computers]: troubleshooting.html#working-from-multiple-computers +[self-multiple-computers]: troubleshooting.md#working-from-multiple-computers [zulip-git-guide-up-to-date]: #keep-your-fork-up-to-date -[zulip-rtd-commit-discipline]: ../contributing/version-control.html#commit-discipline -[zulip-rtd-commit-messages]: ../contributing/version-control.html#commit-messages +[zulip-rtd-commit-discipline]: ../contributing/version-control.md#commit-discipline +[zulip-rtd-commit-messages]: ../contributing/version-control.md#commit-messages diff --git a/docs/git/zulip-tools.md b/docs/git/zulip-tools.md index 756b3a1869..32f7bc5e69 100644 --- a/docs/git/zulip-tools.md +++ b/docs/git/zulip-tools.md @@ -176,5 +176,5 @@ git rebase --continue ``` [github-zulip-zulip]: https://github.com/zulip/zulip/ -[zulip-git-guide-fetch-pr]: collaborate.html#check-out-a-pull-request-locally -[zulip-git-guide-ci]: cloning.html#step-3-configure-continuous-integration-for-your-fork +[zulip-git-guide-fetch-pr]: collaborate.md#check-out-a-pull-request-locally +[zulip-git-guide-ci]: cloning.md#step-3-configure-continuous-integration-for-your-fork diff --git a/docs/overview/architecture-overview.md b/docs/overview/architecture-overview.md index bba3bb7125..a48dae803c 100644 --- a/docs/overview/architecture-overview.md +++ b/docs/overview/architecture-overview.md @@ -108,9 +108,9 @@ feed. For more details on the frontend, see our documentation on [translation](../translating/translating.md), -[templates](../subsystems/html-css.html#html-templates), +[templates](../subsystems/html-css.md#html-templates), [directory structure](directory-structure.md), and -[the static asset pipeline](../subsystems/html-css.html#static-asset-pipeline). +[the static asset pipeline](../subsystems/html-css.md#static-asset-pipeline). [jinja2]: http://jinja.pocoo.org/ [handlebars]: https://handlebarsjs.com/ diff --git a/docs/overview/changelog.md b/docs/overview/changelog.md index 36e24978b0..c78ff29a50 100644 --- a/docs/overview/changelog.md +++ b/docs/overview/changelog.md @@ -414,8 +414,8 @@ log][commit-log] for an up-to-date list of raw changes. major release. [docker-zulip-manual]: https://github.com/zulip/docker-zulip#manual-configuration -[smokescreen]: ../production/deployment.html#customizing-the-outgoing-http-proxy -[update-settings-docs]: ../production/upgrade-or-modify.html#updating-settings-py-inline-documentation +[smokescreen]: ../production/deployment.md#customizing-the-outgoing-http-proxy +[update-settings-docs]: ../production/upgrade-or-modify.md#updating-settingspy-inline-documentation #### Full feature changelog @@ -534,7 +534,7 @@ log][commit-log] for an up-to-date list of raw changes. codebase with Prettier. - Migrated testing from CircleCI to GitHub Actions. -[zulip-conf-settings]: ../production/deployment.html#system-and-deployment-configuration +[zulip-conf-settings]: ../production/deployment.md#system-and-deployment-configuration ## Zulip 3.x series @@ -703,8 +703,8 @@ log][commit-log] for an up-to-date list of raw changes. - The changelog now has a section that makes it easy to find the Upgrade notes for all releases one is upgrading across. -[manage-shell]: ../production/management-commands.html#manage-py-shell -[postgresql-upgrade]: ../production/upgrade-or-modify.html#upgrading-postgresql +[manage-shell]: ../production/management-commands.md#managepy-shell +[postgresql-upgrade]: ../production/upgrade-or-modify.md#upgrading-postgresql #### Full feature changelog @@ -998,7 +998,7 @@ details. - We merged significant preparatory work for supporting RHEL/CentOS in production. We're now interested in beta testers for this feature. - Reorganized Zulip's documentation for sysadmins, and added [new - documentation](../production/upgrade-or-modify.html#modifying-zulip) + documentation](../production/upgrade-or-modify.md#modifying-zulip) on maintaining a fork of Zulip. - Added new `streams:public` search operator that searches the public history of all streams in the organization (even before you joined). @@ -1034,7 +1034,7 @@ details. Zulip how to look up a user in LDAP given their email address: `AUTH_LDAP_REVERSE_EMAIL_SEARCH` and `AUTH_LDAP_USERNAME_ATTR`. See the [LDAP configuration - instructions](../production/authentication-methods.html#ldap-including-active-directory) + instructions](../production/authentication-methods.md#ldap-including-active-directory) for details. You can use the usual `manage.py query_ldap` method to verify whether your configuration is working correctly. - The Zulip web and desktop apps have been converted to directly count @@ -1302,7 +1302,7 @@ details. and is enabled by default in that case. To disable it, set `SUBMIT_USAGE_STATISTICS = False` in `/etc/zulip/settings.py`. -[mpns-statistics-docs]: ../production/mobile-push-notifications.html#submitting-statistics +[mpns-statistics-docs]: ../production/mobile-push-notifications.md#submitting-statistics #### Full feature changelog @@ -1460,7 +1460,7 @@ Zulip installations; it has minimal changes for existing servers. - Renamed the hotkey for starring a message to Ctrl+S. - Added the new `SOCIAL_AUTH_SUBDOMAIN` setting, which all servers using both GitHub authentication and hosting multiple Zulip organizations - should set (see [the docs for details](../production/multiple-organizations.html#authentication)). + should set (see [the docs for details](../production/multiple-organizations.md#authentication)). - Added automatic thumbnailing of images, powered by thumbor. The new THUMBOR_URL setting controls this feature; it is disabled by default in this release, because the mobile apps don't support it yet. @@ -2462,15 +2462,15 @@ running a version from before 1.7 should upgrade directly to 1.7.1. This section links to the upgrade notes from past releases, so you can easily read them all when upgrading across multiple releases. -- [Draft upgrade notes for 5.0](#upgrade-notes-for-5-0) -- [Upgrade notes for 4.0](#upgrade-notes-for-4-0) -- [Upgrade notes for 3.0](#upgrade-notes-for-3-0) -- [Upgrade notes for 2.1.5](#upgrade-notes-for-2-1-5) -- [Upgrade notes for 2.1.0](#upgrade-notes-for-2-1-0) -- [Upgrade notes for 2.0.0](#upgrade-notes-for-2-0-0) -- [Upgrade notes for 1.9.0](#upgrade-notes-for-1-9-0) -- [Upgrade notes for 1.8.0](#upgrade-notes-for-1-8-0) -- [Upgrade notes for 1.7.0](#upgrade-notes-for-1-7-0) +- [Draft upgrade notes for 5.0](#upgrade-notes-for-50) +- [Upgrade notes for 4.0](#upgrade-notes-for-40) +- [Upgrade notes for 3.0](#upgrade-notes-for-30) +- [Upgrade notes for 2.1.5](#upgrade-notes-for-215) +- [Upgrade notes for 2.1.0](#upgrade-notes-for-210) +- [Upgrade notes for 2.0.0](#upgrade-notes-for-200) +- [Upgrade notes for 1.9.0](#upgrade-notes-for-190) +- [Upgrade notes for 1.8.0](#upgrade-notes-for-180) +- [Upgrade notes for 1.7.0](#upgrade-notes-for-170) [docker-zulip]: https://github.com/zulip/docker-zulip [commit-log]: https://github.com/zulip/zulip/commits/main diff --git a/docs/overview/release-lifecycle.md b/docs/overview/release-lifecycle.md index adb5371bc3..07fbd09a00 100644 --- a/docs/overview/release-lifecycle.md +++ b/docs/overview/release-lifecycle.md @@ -108,7 +108,7 @@ release series except in rare cases involving a security issue or critical bug just after publishing a major release. [blog-major-releases]: https://blog.zulip.com/tag/major-releases/ -[upgrade-from-git]: ../production/upgrade-or-modify.html#upgrading-from-a-git-repository +[upgrade-from-git]: ../production/upgrade-or-modify.md#upgrading-from-a-git-repository ### Security releases @@ -184,7 +184,7 @@ GitHub issue. Please an include an explanation of your use case: such details can be extremely helpful in designing appropriately general solutions, and also helps us identify cases where an existing solution can solve your problem. See [Reporting -issues](contributing.html#reporting-issues) for more details. +issues](contributing.md#reporting-issues) for more details. ## Client apps @@ -227,10 +227,10 @@ core community, like the Python and JavaScript bindings, are released independently as needed. [electron]: https://www.electronjs.org/ -[upgrading-to-main]: ../production/upgrade-or-modify.html#upgrading-to-main -[os-upgrade]: ../production/upgrade-or-modify.html#upgrading-the-operating-system +[upgrading-to-main]: ../production/upgrade-or-modify.md#upgrading-to-main +[os-upgrade]: ../production/upgrade-or-modify.md#upgrading-the-operating-system [chat-zulip-org]: https://zulip.com/development-community/ -[fork-zulip]: ../production/upgrade-or-modify.html#modifying-zulip +[fork-zulip]: ../production/upgrade-or-modify.md#modifying-zulip [zulip-server]: https://github.com/zulip/zulip [mobile-beta]: https://github.com/zulip/zulip-mobile#using-the-beta [label-blocker]: https://github.com/zulip/zulip/issues?q=is%3Aissue+is%3Aopen+label%3A%22priority%3A+blocker%22 diff --git a/docs/production/authentication-methods.md b/docs/production/authentication-methods.md index b5deaaca1a..673e203b19 100644 --- a/docs/production/authentication-methods.md +++ b/docs/production/authentication-methods.md @@ -384,7 +384,7 @@ it as follows: the "SAML ACS url" in SAML terminology. If you're - [hosting multiple organizations](multiple-organizations.html#authentication), + [hosting multiple organizations](multiple-organizations.md#authentication), you need to use `SOCIAL_AUTH_SUBDOMAIN`. For example, if `SOCIAL_AUTH_SUBDOMAIN="auth"` and `EXTERNAL_HOST=zulip.example.com`, this should be `https://auth.zulip.example.com/complete/saml/`. @@ -876,4 +876,4 @@ passwordless login as any user in a development environment. It's mentioned on this page only for completeness. [custom-profile-fields]: https://zulip.com/help/add-custom-profile-fields -[update-inline-comments]: upgrade-or-modify.html#updating-settings-py-inline-documentation +[update-inline-comments]: upgrade-or-modify.md#updating-settingspy-inline-documentation diff --git a/docs/production/deployment.md b/docs/production/deployment.md index 28a440d27d..029ffc41cc 100644 --- a/docs/production/deployment.md +++ b/docs/production/deployment.md @@ -18,8 +18,8 @@ git clone https://github.com/zulip/zulip.git zulip-server-git ``` and then -[continue the normal installation instructions](install.html#step-2-install-zulip). -You can also [upgrade Zulip from Git](upgrade-or-modify.html#upgrading-from-a-git-repository). +[continue the normal installation instructions](install.md#step-2-install-zulip). +You can also [upgrade Zulip from Git](upgrade-or-modify.md#upgrading-from-a-git-repository). The most common use case for this is upgrading to `main` to get a feature that hasn't made it into an official release yet (often @@ -33,8 +33,8 @@ In particular, we are always very glad to investigate problems with installing Zulip from `main`; they are rare and help us ensure that our next major release has a reliable install experience. -[upgrade-to-main]: upgrade-or-modify.html#upgrading-to-main -[upgrade-to-future-release]: upgrade-or-modify.html#upgrading-to-future-releases +[upgrade-to-main]: upgrade-or-modify.md#upgrading-to-main +[upgrade-to-future-release]: upgrade-or-modify.md#upgrading-to-future-releases ## Zulip in Docker @@ -49,7 +49,7 @@ specific reason to prefer Docker. The Zulip installer supports the following advanced installer options as well as those mentioned in the -[install](install.html#installer-options) documentation: +[install](install.md#installer-options) documentation: - `--postgresql-version`: Sets the version of PostgreSQL that will be installed. We currently support PostgreSQL 10, 11, 12, 13, and 14. @@ -269,7 +269,7 @@ In Zulip 4.7 and older, to enable SSRF protection via Smokescreen, you will need to explicitly add the `zulip::profile::smokescreen` Puppet class, and configure the `[http_proxy]` block as above. -[proxy.enable_for_camo]: #enable-for-camo +[proxy.enable_for_camo]: #enable_for_camo [smokescreen]: https://github.com/stripe/smokescreen [smokescreen-acls]: https://github.com/stripe/smokescreen#acls [ssrf]: https://owasp.org/www-community/attacks/Server_Side_Request_Forgery @@ -535,7 +535,7 @@ configuration of `pg_hba.conf` and client certificates on the replica. [warm-standby]: https://www.postgresql.org/docs/current/warm-standby.html -[wal-g]: export-and-import.html#backup-details +[wal-g]: export-and-import.md#backup-details ## System and deployment configuration @@ -565,7 +565,7 @@ Any other value (including the empty string) is considered false. A comma-separated list of the Puppet classes to install on the server. The most common is **`zulip::profile::standalone`**, used for a stand-alone single-host deployment. -[Components](../overview/architecture-overview.html#components) of +[Components](../overview/architecture-overview.md#components) of that include: - **`zulip::profile::app_frontend`** @@ -575,13 +575,13 @@ that include: - **`zulip::profile::rabbitmq`** If you are using a [Apache as a single-sign-on -authenticator](authentication-methods.html#apache-based-sso-with-remote-user), +authenticator](authentication-methods.md#apache-based-sso-with-remote_user), you will need to add **`zulip::apache_sso`** to the list. #### `pgroonga` Set to true if enabling the [multi-language PGroonga search -extension](../subsystems/full-text-search.html#multi-language-full-text-search). +extension](../subsystems/full-text-search.md#multi-language-full-text-search). ### `[deployment]` @@ -604,7 +604,7 @@ for servers that are upgraded frequently by core Zulip developers. #### `git_repo_url` Default repository URL used when [upgrading from a Git -repository](upgrade-or-modify.html#upgrading-from-a-git-repository). +repository](upgrade-or-modify.md#upgrading-from-a-git-repository). ### `[application_server]` @@ -626,7 +626,7 @@ configure `settings.py` and set this to true to configure `nginx`. Remove this field to return to the local uploads backend (any non-empty value is currently equivalent to true). -[s3-uploads]: upload-backends.html#s3-backend-configuration +[s3-uploads]: upload-backends.md#s3-backend-configuration #### `queue_workers_multiprocess` @@ -669,7 +669,7 @@ more than 3.5GiB of RAM, 4 on hosts with less. #### `mailname` The hostname that [Postfix should be configured to receive mail -at](email-gateway.html#local-delivery-setup). +at](email-gateway.md#local-delivery-setup). ### `[postgresql]` @@ -694,7 +694,7 @@ Set to true to enable replication to enable [log shipping replication between PostgreSQL servers](#postgresql-warm-standby). This should be enabled on the primary, as well as any replicas, and further requires configuration of -[wal-g](export-and-import.html#backup-details). +[wal-g](export-and-import.md#backup-details). #### `replication_primary` @@ -726,7 +726,7 @@ connections. #### `version` The version of PostgreSQL that is in use. Do not set by hand; use the -[PostgreSQL upgrade tool](upgrade-or-modify.html#upgrading-postgresql). +[PostgreSQL upgrade tool](upgrade-or-modify.md#upgrading-postgresql). ### `[memcached]` diff --git a/docs/production/email-gateway.md b/docs/production/email-gateway.md index 44274cefe7..8166cd852b 100644 --- a/docs/production/email-gateway.md +++ b/docs/production/email-gateway.md @@ -96,7 +96,7 @@ using an [HTTP reverse proxy][reverse-proxy]). Congratulations! The integration should be fully operational. -[reverse-proxy]: deployment.html#putting-the-zulip-application-behind-a-reverse-proxy +[reverse-proxy]: deployment.md#putting-the-zulip-application-behind-a-reverse-proxy ## Polling setup diff --git a/docs/production/export-and-import.md b/docs/production/export-and-import.md index 52fe0974e7..706ab5ccf8 100644 --- a/docs/production/export-and-import.md +++ b/docs/production/export-and-import.md @@ -48,9 +48,9 @@ service (or back): decommissioning a Zulip organization. - It's possible to set up [PostgreSQL streaming - replication](deployment.html#postgresql-warm-standby) + replication](deployment.md#postgresql-warm-standby) and the [S3 file upload - backend](upload-backends.html#s3-backend-configuration) + backend](upload-backends.md#s3-backend-configuration) as part of a high availability environment. ## Backups @@ -365,7 +365,7 @@ cd /home/zulip/deployments/current This could take several minutes to run depending on how much data you're importing. -[upgrade-zulip-from-git]: upgrade-or-modify.html#upgrading-from-a-git-repository +[upgrade-zulip-from-git]: upgrade-or-modify.md#upgrading-from-a-git-repository #### Import options @@ -411,7 +411,7 @@ delete the test import data from your Zulip server before doing a final import. You can **permanently delete** all data from a Zulip organization using the following procedure: -- Start a [Zulip management shell](management-commands.html#manage-py-shell) +- Start a [Zulip management shell](management-commands.md#managepy-shell) - In the management shell, run the following commands, replacing `""` with the subdomain if [you are hosting the organization on a subdomain](multiple-organizations.md): diff --git a/docs/production/install.md b/docs/production/install.md index 17d14f04b6..69f7f08670 100644 --- a/docs/production/install.md +++ b/docs/production/install.md @@ -5,7 +5,7 @@ You'll need an Ubuntu or Debian system that satisfies you can use a preconfigured [DigitalOcean droplet](https://marketplace.digitalocean.com/apps/zulip?refcode=3ee45da8ee26), or Zulip's -[experimental Docker image](deployment.html#zulip-in-docker). +[experimental Docker image](deployment.md#zulip-in-docker). Note that if you're developing for Zulip, you should install Zulip's [development environment](../development/overview.md) instead. If @@ -27,7 +27,7 @@ tar -xf zulip-server-latest.tar.gz - If you'd like to verify the download, we [publish the sha256sums of our release tarballs](https://download.zulip.com/server/SHA256SUMS.txt). - You can also - [install a pre-release version of Zulip](deployment.html#installing-zulip-from-git) + [install a pre-release version of Zulip](deployment.md#installing-zulip-from-git) using code from our [repository on GitHub](https://github.com/zulip/zulip/). ## Step 2: Install Zulip @@ -73,9 +73,9 @@ You can see the more advanced installer options in our [deployment options][doc- documentation. [doc-settings]: settings.md -[doc-certbot]: ssl-certificates.html#certbot-recommended -[doc-ssl-manual]: ssl-certificates.html#manual-install -[doc-deployment-options]: deployment.html#advanced-installer-options +[doc-certbot]: ssl-certificates.md#certbot-recommended +[doc-ssl-manual]: ssl-certificates.md#manual-install +[doc-deployment-options]: deployment.md#advanced-installer-options ## Step 3: Create a Zulip organization, and log in @@ -85,7 +85,7 @@ or another Zulip server, you should stop here and return to the import instructions. [slack-import]: https://zulip.com/help/import-from-slack -[zulip-backups]: export-and-import.html#backups +[zulip-backups]: export-and-import.md#backups Otherwise, open the link in a browser. Follow the prompts to set up your organization, and your own user account as an administrator. diff --git a/docs/production/maintain-secure-upgrade.md b/docs/production/maintain-secure-upgrade.md index d174cf8371..352bc78331 100644 --- a/docs/production/maintain-secure-upgrade.md +++ b/docs/production/maintain-secure-upgrade.md @@ -9,7 +9,7 @@ have since all moved to dedicated pages: ### Monitoring -Moved to [Troubleshooting](troubleshooting.html#monitoring). +Moved to [Troubleshooting](troubleshooting.md#monitoring). ### Securing your Zulip server @@ -17,21 +17,21 @@ Moved to [Security model](security-model.md). ### Upgrading -Moved to [Upgrading to a release](upgrade-or-modify.html#upgrading-to-a-release). +Moved to [Upgrading to a release](upgrade-or-modify.md#upgrading-to-a-release). ### Upgrading from a Git repository Moved to [Upgrading from a Git -repository](upgrade-or-modify.html#upgrading-from-a-git-repository). +repository](upgrade-or-modify.md#upgrading-from-a-git-repository). ### Upgrading the operating system Moved to [Upgrading the operating -system](upgrade-or-modify.html#upgrading-the-operating-system). +system](upgrade-or-modify.md#upgrading-the-operating-system). ### Scalability -Moved to [Scalability](requirements.html#scalability). +Moved to [Scalability](requirements.md#scalability). ### Management commands diff --git a/docs/production/management-commands.md b/docs/production/management-commands.md index 8d1b281dff..89fa15d31e 100644 --- a/docs/production/management-commands.md +++ b/docs/production/management-commands.md @@ -148,7 +148,7 @@ self-hosted Zulip server: [webhook integration][webhook-integrations] or [bot][writing-bots]. - Writing a program using the [Zulip API][zulip-api]. - [Modifying the Zulip server][modifying-zulip]. -- Using the interactive [management shell](#manage-py-shell), +- Using the interactive [management shell](#managepy-shell), documented above, for one-time work or prototyping. - Writing a custom management command, detailed here. @@ -171,12 +171,12 @@ the Zulip server. Instead, we recommend deploying custom management commands either via the [modifying Zulip][modifying-zulip] process or by storing them in `/etc/zulip` (so they are included in -[backups](export-and-import.html#backups)) and then +[backups](export-and-import.md#backups)) and then symlinking them into `/home/zulip/deployments/current/zerver/management/` after each upgrade. -[modifying-zulip]: upgrade-or-modify.html#modifying-zulip +[modifying-zulip]: upgrade-or-modify.md#modifying-zulip [writing-bots]: https://zulip.com/api/writing-bots [integrations]: https://zulip.com/integrations [zulip-api]: https://zulip.com/api/rest diff --git a/docs/production/mobile-push-notifications.md b/docs/production/mobile-push-notifications.md index 13d7033d31..055862be39 100644 --- a/docs/production/mobile-push-notifications.md +++ b/docs/production/mobile-push-notifications.md @@ -18,7 +18,7 @@ support forwarding push notifications to a central push notification forwarding service. Accessing this service requires outgoing HTTPS access to the public Internet; if that is restricted by a proxy, you will need to [configure Zulip to use your outgoing HTTP -proxy](deployment.html#customizing-the-outgoing-http-proxy) +proxy](deployment.md#customizing-the-outgoing-http-proxy) first. You can enable this for your Zulip server as follows: @@ -27,7 +27,7 @@ You can enable this for your Zulip server as follows: `PUSH_NOTIFICATION_BOUNCER_URL = 'https://push.zulipchat.com'` line in your `/etc/zulip/settings.py` file (i.e. remove the `#` at the start of the line), and [restart your Zulip - server](settings.html#making-changes). If you + server](settings.md#making-changes). If you installed your Zulip server with a version older than 1.6, you'll need to add the line (it won't be there to uncomment). diff --git a/docs/production/multiple-organizations.md b/docs/production/multiple-organizations.md index dccb96253a..1b18f25a9d 100644 --- a/docs/production/multiple-organizations.md +++ b/docs/production/multiple-organizations.md @@ -55,7 +55,7 @@ the homepage for the server is a copy of the Zulip homepage. You'll need to install an SSL certificate valid for all the (sub)domains you're using your Zulip server with. You can get an SSL certificate covering several domains for free by using -[our Certbot wrapper tool](ssl-certificates.html#after-zulip-is-already-installed), +[our Certbot wrapper tool](ssl-certificates.md#after-zulip-is-already-installed), though if you're going to host a large number of organizations, you may want to get a wildcard certificate. You can also get a wildcard certificate for diff --git a/docs/production/password-strength.md b/docs/production/password-strength.md index b5bc844e5f..cba62ec4cc 100644 --- a/docs/production/password-strength.md +++ b/docs/production/password-strength.md @@ -8,7 +8,7 @@ When a user tries to set a password, we use [zxcvbn][zxcvbn] to check that it isn't a weak one. See discussion in [our main docs for server -admins](security-model.html#passwords). This doc explains in more +admins](security-model.md#passwords). This doc explains in more detail how we set the default threshold (`PASSWORD_MIN_GUESSES`) we use. First, read the doc section there. (It's short.) diff --git a/docs/production/postgresql.md b/docs/production/postgresql.md index 2a8ffeb245..ca5f21e4d9 100644 --- a/docs/production/postgresql.md +++ b/docs/production/postgresql.md @@ -10,7 +10,7 @@ included with the base operating system (E.g. PostgreSQL 12 on Ubuntu PostgreSQL releases [upgrade to PostgreSQL 14][upgrade-postgresql], as we may drop support for older PostgreSQL in a future release. -[upgrade-postgresql]: upgrade-or-modify.html#upgrading-postgresql +[upgrade-postgresql]: upgrade-or-modify.md#upgrading-postgresql #### Remote PostgreSQL database diff --git a/docs/production/requirements.md b/docs/production/requirements.md index 2f064751dd..f67d80cc4e 100644 --- a/docs/production/requirements.md +++ b/docs/production/requirements.md @@ -17,7 +17,7 @@ To run a Zulip server, you will need: For details on each of these requirements, see below. -[upgrade-from-git]: upgrade-or-modify.html#upgrading-from-a-git-repository +[upgrade-from-git]: upgrade-or-modify.md#upgrading-from-a-git-repository ## Server @@ -53,7 +53,7 @@ sudo apt update ``` [docker-zulip-homepage]: https://github.com/zulip/docker-zulip#readme -[upgrade-os]: upgrade-or-modify.html#upgrading-the-operating-system +[upgrade-os]: upgrade-or-modify.md#upgrading-the-operating-system [ubuntu-repositories]: https://help.ubuntu.com/community/Repositories/Ubuntu [enable-universe]: https://help.ubuntu.com/community/Repositories/CommandLine#Adding_the_Universe_and_Multiverse_Repositories @@ -78,7 +78,7 @@ on hardware requirements for larger organizations. #### Network and security specifications - Incoming HTTPS access (usually port 443, though this is - [configurable](deployment.html#using-an-alternate-port)) + [configurable](deployment.md#using-an-alternate-port)) from the networks where your users are (usually, the public Internet). - Incoming port 80 access (optional). Zulip only serves content over @@ -112,8 +112,8 @@ on hardware requirements for larger organizations. Zulip supports using that instead. [ssrf]: https://owasp.org/www-community/attacks/Server_Side_Request_Forgery -[smokescreen-proxy]: deployment.html#customizing-the-outgoing-http-proxy -[reverse-proxy]: deployment.html#putting-the-zulip-application-behind-a-reverse-proxy +[smokescreen-proxy]: deployment.md#customizing-the-outgoing-http-proxy +[reverse-proxy]: deployment.md#putting-the-zulip-application-behind-a-reverse-proxy [email-mirror-code]: https://github.com/zulip/zulip/blob/main/zerver/management/commands/email_mirror.py ## Credentials needed @@ -133,8 +133,8 @@ installer. If you'd rather acquire an SSL certificate another way, see our [SSL certificate documentation](ssl-certificates.md). -[doc-certbot]: ssl-certificates.html#certbot-recommended -[doc-self-signed]: ssl-certificates.html#self-signed-certificate +[doc-certbot]: ssl-certificates.md#certbot-recommended +[doc-self-signed]: ssl-certificates.md#self-signed-certificate #### Outgoing email @@ -143,7 +143,7 @@ certificate documentation](ssl-certificates.md). during the signup process, message notification emails, password reset, etc.). If you don't have an existing outgoing SMTP solution, read about - [free outgoing SMTP options and options for prototyping](email.html#free-outgoing-email-services). + [free outgoing SMTP options and options for prototyping](email.md#free-outgoing-email-services). Once you have met these requirements, see [full instructions for installing Zulip in production](install.md). @@ -241,6 +241,6 @@ For readers interested in technical details around what features impact Zulip's scalability, this [performance and scalability design document](../subsystems/performance.md) may also be of interest. -[s3-uploads]: upload-backends.html#s3-backend-configuration -[streaming-replication]: deployment.html#postgresql-warm-standby +[s3-uploads]: upload-backends.md#s3-backend-configuration +[streaming-replication]: deployment.md#postgresql-warm-standby [contact-support]: https://zulip.com/help/contact-support diff --git a/docs/production/security-model.md b/docs/production/security-model.md index 5595783afc..c50df1ea7c 100644 --- a/docs/production/security-model.md +++ b/docs/production/security-model.md @@ -272,8 +272,8 @@ strength allowed is controlled by two settings in [go-camo]: https://github.com/cactus/go-camo [ssrf]: https://owasp.org/www-community/attacks/Server_Side_Request_Forgery -[smokescreen-setup]: deployment.html#customizing-the-outgoing-http-proxy -[proxy.enable_for_camo]: deployment.html#enable-for-camo +[smokescreen-setup]: deployment.md#customizing-the-outgoing-http-proxy +[proxy.enable_for_camo]: deployment.md#enable_for_camo ## Final notes and security response diff --git a/docs/production/settings.md b/docs/production/settings.md index ab614655d2..ac0320e3a3 100644 --- a/docs/production/settings.md +++ b/docs/production/settings.md @@ -28,7 +28,7 @@ from an old version of Zulip, we recommend [carefully updating your comment documentation for new configuration settings after upgrading to each new major release. -[update-settings-docs]: upgrade-or-modify.html#updating-settings-py-inline-documentation +[update-settings-docs]: upgrade-or-modify.md#updating-settingspy-inline-documentation [settings-py-template]: https://github.com/zulip/zulip/blob/main/zproject/prod_settings_template.py Since Zulip's settings file is a Python script, there are a number of diff --git a/docs/production/ssl-certificates.md b/docs/production/ssl-certificates.md index 3bce35cec4..d188e742c5 100644 --- a/docs/production/ssl-certificates.md +++ b/docs/production/ssl-certificates.md @@ -81,7 +81,7 @@ Internet. If you need to configure a multiple domain certificate, you can generate one as described in the section below after installing Zulip. -[doc-install-script]: install.html#step-2-install-zulip +[doc-install-script]: install.md#step-2-install-zulip ### After Zulip is already installed diff --git a/docs/production/troubleshooting.md b/docs/production/troubleshooting.md index 0fae39babc..7d805563b0 100644 --- a/docs/production/troubleshooting.md +++ b/docs/production/troubleshooting.md @@ -7,7 +7,7 @@ Supervisor client to monitor and manage services. If you haven't already, now might be a good time to read Zulip's [architectural overview](../overview/architecture-overview.md), particularly the -[Components](../overview/architecture-overview.html#components) section. This will help you +[Components](../overview/architecture-overview.md#components) section. This will help you understand the many services Zulip uses. If you encounter issues while running Zulip, take a look at Zulip's logs, which diff --git a/docs/production/upgrade-or-modify.md b/docs/production/upgrade-or-modify.md index 9e29444fff..04d30a288e 100644 --- a/docs/production/upgrade-or-modify.md +++ b/docs/production/upgrade-or-modify.md @@ -4,7 +4,7 @@ This page explains how to upgrade, patch, or modify Zulip, including: - [Upgrading to a release](#upgrading-to-a-release) - [Upgrading from a Git repository](#upgrading-from-a-git-repository) -- [Updating `settings.py` inline documentation](#updating-settings-py-inline-documentation) +- [Updating `settings.py` inline documentation](#updating-settingspy-inline-documentation) - [Troubleshooting and rollback](#troubleshooting-and-rollback) - [Preserving local changes to service configuration files](#preserving-local-changes-to-service-configuration-files) - [Upgrading the operating system](#upgrading-the-operating-system) @@ -20,7 +20,7 @@ or have [modified Zulip-managed configuration files](#preserving-local-changes-to-service-configuration-files). To upgrade to a new Zulip release: -1. Read the [upgrade notes](../overview/changelog.html#upgrade-notes) +1. Read the [upgrade notes](../overview/changelog.md#upgrade-notes) for all releases newer than what is currently installed. 1. Download the appropriate release tarball from @@ -60,7 +60,7 @@ involved (these will be documented in the [release notes](../overview/changelog.md), and usually can be avoided with some care). If downtime is problematic for your organization, consider testing the upgrade on a -[backup](export-and-import.html#backups) in advance, +[backup](export-and-import.md#backups) in advance, doing the final upgrade at off hours, or buying a support contract. See the [troubleshooting guide](#troubleshooting-and-rollback) if you @@ -156,7 +156,7 @@ suggest using that updated template to update su zulip -c '/home/zulip/deployments/current/scripts/restart-server' ``` -[backups]: export-and-import.html#backups +[backups]: export-and-import.md#backups [changelog]: ../overview/changelog.md ## Troubleshooting and rollback @@ -365,7 +365,7 @@ instructions for other supported platforms. ``` 8. [Upgrade from Ubuntu 18.04 to - 20.04](#upgrading-from-ubuntu-18-04-bionic-to-20-04-focal), so that + 20.04](#upgrading-from-ubuntu-1804-bionic-to-2004-focal), so that you are running a supported operating system. ### Upgrading from Ubuntu 14.04 Trusty to 16.04 Xenial @@ -408,7 +408,7 @@ instructions for other supported platforms. correctly. 6. [Upgrade from Ubuntu 16.04 to - 18.04](#upgrading-from-ubuntu-16-04-xenial-to-18-04-bionic), so + 18.04](#upgrading-from-ubuntu-1604-xenial-to-1804-bionic), so that you are running a supported operating system. ### Upgrading from Debian 10 to 11 @@ -800,7 +800,7 @@ upgrading to `main`, make sure you understand: - We do not support downgrading from `main` to earlier versions, so if downtime for your Zulip server is unacceptable, make sure you have a current - [backup](export-and-import.html#backups) in case the + [backup](export-and-import.md#backups) in case the upgrade fails. - Our changelog contains [draft release notes](../overview/changelog.md) available listing major changes @@ -821,7 +821,7 @@ contributors like you. If your changes are likely to be of useful to other organizations, consider [contributing them](../overview/contributing.md). -[fork-clone]: ../git/cloning.html#get-zulip-code +[fork-clone]: ../git/cloning.md#get-zulip-code [upgrade-zulip-from-git]: #upgrading-from-a-git-repository [upgrade-zulip]: #upgrading [git-guide]: ../git/index.md diff --git a/docs/subsystems/dependencies.md b/docs/subsystems/dependencies.md index a63fe29c3b..4195288b4e 100644 --- a/docs/subsystems/dependencies.md +++ b/docs/subsystems/dependencies.md @@ -232,7 +232,7 @@ reasoning here. dependencies in the `yarn.lock` file; `yarn install` updates the `yarn.lock` files. - `tools/update-prod-static`. This process is discussed in detail in - the [static asset pipeline](html-css.html#static-asset-pipeline) + the [static asset pipeline](html-css.md#static-asset-pipeline) article, but we don't use the `node_modules` directories directly in production. Instead, static assets are compiled using our static asset pipeline and it is the compiled assets that are served diff --git a/docs/subsystems/email.md b/docs/subsystems/email.md index 1cdd30f11e..cd6a83e483 100644 --- a/docs/subsystems/email.md +++ b/docs/subsystems/email.md @@ -72,9 +72,9 @@ mutate the HTML email one can see previewed on `/emails`. To do this sort of testing, you need to set up an outgoing SMTP provider. Our production advice for -[Gmail](../production/email.html#using-gmail-for-outgoing-email) and +[Gmail](../production/email.md#using-gmail-for-outgoing-email) and [transactional email -providers](../production/email.html#free-outgoing-email-services) are +providers](../production/email.md#free-outgoing-email-services) are relevant; you can ignore the Gmail warning as Gmail's rate limits are appropriate for this sort of low-volume testing. diff --git a/docs/subsystems/performance.md b/docs/subsystems/performance.md index 12cfdfd0e1..0a58efb330 100644 --- a/docs/subsystems/performance.md +++ b/docs/subsystems/performance.md @@ -20,7 +20,7 @@ First, a few notes on philosophy. design/implementation work to make requests fast over the operational work of running 2-5x as much hardware to handle the same load. -See also [scalability for production users](../production/requirements.html#scalability). +See also [scalability for production users](../production/requirements.md#scalability). ## Load profiles @@ -38,7 +38,7 @@ of load profiles: example for this, with more than 15K total user accounts, of which only several hundred have logged in during the last few weeks. Zulip has many important optimizations, including [soft - deactivation](sending-messages.html#soft-deactivation) + deactivation](sending-messages.md#soft-deactivation) to ensure idle users have minimal impact on both server-side scalability and request latency. - Fulltime teams, like your typical corporate Zulip installation, @@ -249,7 +249,7 @@ it does a large number of these requests: zulip.com, this can result in a thundering herd effect for both `/` and `GET /messages`. A great deal of care has been taking in designing this [auto-reload - system](hashchange-system.html#server-initiated-reloads) + system](hashchange-system.md#server-initiated-reloads) to spread most of that herd over several minutes. Typical requests consume 20-100ms to process, much of which is waiting diff --git a/docs/subsystems/release-checklist.md b/docs/subsystems/release-checklist.md index 136f91b144..ec3978d4c5 100644 --- a/docs/subsystems/release-checklist.md +++ b/docs/subsystems/release-checklist.md @@ -13,7 +13,7 @@ preparing a new release. - Upgrade all puppet-installed dependencies (e.g. Smokescreen, go, etc) in `puppet/zulip/manifests/common.pp` - [Upload strings to - Transifex](../translating/internationalization.html#translation-process) + Transifex](../translating/internationalization.md#translation-process) using `push-translations`. Post a Transifex [Announcement](https://www.transifex.com/zulip/zulip/announcements/) notifying translators that we're approaching a release. diff --git a/docs/subsystems/settings.md b/docs/subsystems/settings.md index 9db63818d5..838aaf56b1 100644 --- a/docs/subsystems/settings.md +++ b/docs/subsystems/settings.md @@ -62,7 +62,7 @@ In a production environment, we have: is the main documentation for Zulip settings, we recommend that production installations [carefully update `/etc/zulip/settings.py` every major - release](../production/upgrade-or-modify.html#updating-settings-py-inline-documentation) + release](../production/upgrade-or-modify.md#updating-settingspy-inline-documentation) to pick up new inline documentation. - `/etc/zulip/zulip-secrets.conf` (generated by diff --git a/docs/testing/linters.md b/docs/testing/linters.md index d47bfc34f1..c31e061800 100644 --- a/docs/testing/linters.md +++ b/docs/testing/linters.md @@ -65,7 +65,7 @@ but it is good practice to run lint checks locally. :::{important} We provide a -[Git pre-commit hook](../git/zulip-tools.html#set-up-git-repo-script) +[Git pre-commit hook](../git/zulip-tools.md#set-up-git-repo-script) that can automatically run `tools/lint` on just the files that changed (in a few 100ms) whenever you make a commit. This can save you a lot of time, by automatically detecting linter errors as you diff --git a/docs/testing/testing-with-django.md b/docs/testing/testing-with-django.md index 1f41d49244..50d98a28fa 100644 --- a/docs/testing/testing-with-django.md +++ b/docs/testing/testing-with-django.md @@ -330,7 +330,7 @@ with self.settings(RATE_LIMITING=True): self.assertTrue(rate_limit_mock.called) ``` -Follow [this link](../subsystems/settings.html#testing-non-default-settings) for more +Follow [this link](../subsystems/settings.md#testing-non-default-settings) for more information on the "settings" context manager. Zulip has several features, like outgoing webhooks or social @@ -411,7 +411,7 @@ We use mocks and stubs for all the typical reasons: - to stub out calls to third-party services - to make it so that you can [run the Zulip tests on the airplane without wifi][no-internet] -[no-internet]: testing.html#internet-access-inside-test-suites +[no-internet]: testing.md#internet-access-inside-test-suites A detailed description of mocks, along with useful coded snippets, can be found in the section [Testing with mocks](#testing-with-mocks). @@ -449,7 +449,7 @@ the same data structure as performing an action that generates said event. This is a bit esoteric, but if you read the tests, you will see some of the patterns. You can also learn more about our event system in the -[new feature tutorial](../tutorials/new-feature-tutorial.html#handle-database-interactions). +[new feature tutorial](../tutorials/new-feature-tutorial.md#handle-database-interactions). ### Negative tests diff --git a/docs/testing/testing.md b/docs/testing/testing.md index b980256608..6045e22883 100644 --- a/docs/testing/testing.md +++ b/docs/testing/testing.md @@ -126,7 +126,7 @@ This is easy to do using test fixtures (a fancy word for fixed data used in tests) and the `mock.patch` function to specify what HTTP response should be used by the tests for every outgoing HTTP (or other network) request. Consult -[our guide on mocking](testing-with-django.html#zulip-mocking-practices) to +[our guide on mocking](testing-with-django.md#zulip-mocking-practices) to learn how to mock network requests easily; there are also a number of examples throughout the codebase. diff --git a/docs/translating/internationalization.md b/docs/translating/internationalization.md index d9ee9eae1a..869727d75e 100644 --- a/docs/translating/internationalization.md +++ b/docs/translating/internationalization.md @@ -26,7 +26,7 @@ principles are important in how we think about internationalization: element needs to be built in a way that supports i18n. - This is more about string consistency in general, but we have a "Sentence case" [capitalization - policy](translating.html#capitalization) that we enforce using linters + policy](translating.md#capitalization) that we enforce using linters that check all strings tagged for translation in Zulip. This article aims to provide a brief introduction. We recommend the @@ -108,7 +108,7 @@ The end-to-end tooling process for translations in Zulip is as follows. Transifex API tool, `tx pull`, internally). If you're interested, you may also want to check out the [translators' -workflow](translating.html#translators-workflow), just so you have a +workflow](translating.md#translators-workflow), just so you have a sense of how everything fits together. ## Translation resource files @@ -339,4 +339,4 @@ organizations from the command line. [helpers]: https://handlebarsjs.com/guide/block-helpers.html [transifex]: https://transifex.com [transifexrc]: https://docs.transifex.com/client/client-configuration#transifexrc -[html-templates]: ../subsystems/html-css.html#html-templates +[html-templates]: ../subsystems/html-css.md#html-templates diff --git a/docs/translating/translating.md b/docs/translating/translating.md index 9332c25c1f..eb49fec23a 100644 --- a/docs/translating/translating.md +++ b/docs/translating/translating.md @@ -115,7 +115,7 @@ can usually just deploy the latest translations there. - First, download the updated resource files from Transifex using the `tools/i18n/sync-translations` command (it will require some [initial - setup](internationalization.html#transifex-cli-setup)). This + setup](internationalization.md#transifex-cli-setup)). This command will download the resource files from Transifex and replace your local resource files with them, and then compile them. You can now test your translation work in the Zulip UI. @@ -199,7 +199,7 @@ capitalization in general. This means that: The Zulip test suite enforces these capitalization guidelines in the web app codebase [in our test -suite](../testing/testing.html#other-test-suites) +suite](../testing/testing.md#other-test-suites) (`./tools/check-capitalization`; `tools/lib/capitalization.py` has some exclude lists, e.g. `IGNORED_PHRASES`). diff --git a/docs/tutorials/life-of-a-request.md b/docs/tutorials/life-of-a-request.md index bd5347f5da..8a5345d790 100644 --- a/docs/tutorials/life-of-a-request.md +++ b/docs/tutorials/life-of-a-request.md @@ -39,7 +39,7 @@ location /static/ { ## nginx routes other requests [between Django and Tornado][tornado-django] -[tornado-django]: ../overview/architecture-overview.html#django-and-tornado +[tornado-django]: ../overview/architecture-overview.md#django-and-tornado All our connected clients hold open long-polling connections so that they can receive events (messages, presence notifications, and so on) in diff --git a/docs/tutorials/new-feature-tutorial.md b/docs/tutorials/new-feature-tutorial.md index b042e0c4ae..efc0d396cd 100644 --- a/docs/tutorials/new-feature-tutorial.md +++ b/docs/tutorials/new-feature-tutorial.md @@ -89,7 +89,7 @@ to learn more about creating and applying database migrations. **Test your changes:** Once you've run the migration, flush memcached on your development server (`./scripts/setup/flush-memcached`) and then -[restart the development server](../development/remote.html#running-the-development-server) +[restart the development server](../development/remote.md#running-the-development-server) to avoid interacting with cached objects. ### Backend changes @@ -265,7 +265,7 @@ Running migrations: ``` Once you've run the migration, restart memcached on your development -server (`/etc/init.d/memcached restart`) and then [restart the development server](../development/remote.html#running-the-development-server) +server (`/etc/init.d/memcached restart`) and then [restart the development server](../development/remote.md#running-the-development-server) to avoid interacting with cached objects. ### Handle database interactions diff --git a/docs/tutorials/shell-tips.md b/docs/tutorials/shell-tips.md index eec2e38988..05f310b7f4 100644 --- a/docs/tutorials/shell-tips.md +++ b/docs/tutorials/shell-tips.md @@ -347,4 +347,4 @@ will be useful in your journey, as well. ![Git - XKCD 1597](https://imgs.xkcd.com/comics/git.png) -[git-cheat-detailed]: ../git/cheat-sheet.html#detailed-cheat-sheet +[git-cheat-detailed]: ../git/cheat-sheet.md#detailed-cheat-sheet diff --git a/docs/tutorials/writing-views.md b/docs/tutorials/writing-views.md index 1a919bb797..4d94827c89 100644 --- a/docs/tutorials/writing-views.md +++ b/docs/tutorials/writing-views.md @@ -37,7 +37,7 @@ integrations). The format of the URL patterns in Django is [documented here](https://docs.djangoproject.com/en/3.2/topics/http/urls/), and the Zulip specific details for these are discussed in detail in the -[life of a request doc](life-of-a-request.html#options). +[life of a request doc](life-of-a-request.md#options). We have two Zulip-specific conventions we use for internationalization and for our REST API, respectively.