Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: Reduce the number of apparently broken links on github. 

- Updated 260+ links from ".html" to ".md" to reduce the number of issues
reported about hyperlinks not working when viewing docs on Github.
- Removed temporary workaround that suppressed all warnings reported
by sphinx build for every link ending in ".html".

Details:
The recent upgrade to recommonmark==0.5.0 supports auto-converting
".md" links to ".html" so that the resulting HTML output is correct.

Notice that links pointing to a heading i.e. "../filename.html#heading",
were not updated because recommonmark does not auto-convert them.
These links do not generate build warnings and do not cause any issues.
However, there are about ~100 such links that might still get misreported
as broken links.  This will be a follow-up issue.

Background:
docs: pip upgrade recommonmark and CommonMark #13013
docs: Allow .md links between doc pages #11719

Fixes #11087.
This commit is contained in:
David Rosa 2019-09-30 10:37:56 -07:00 committed by Tim Abbott
parent 5329d24849
commit bdbc384de5
69 changed files with 262 additions and 272 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/conf.py
View File

@ -304,18 +304,8 @@ source_suffix = {
'.md': 'markdown',
}
# Temporary workaround to supress warnings after upgrading to recommonmark==0.5.0
# Otherwise, sphinx build complains about all the links ending in .html
# See PR # for more details
def on_missing_reference(app, env, node, contnode):
if node['reftype'] == 'any':
return contnode
else:
return None
def setup(app: Any) -> None:
app.connect('missing-reference', on_missing_reference)
app.add_config_value('recommonmark_config', {
'enable_eval_rst': True,
# Turn off recommonmark features we aren't using.

2
docs/contributing/chat-zulip-org.md
View File

@ -32,7 +32,7 @@ minutes to a few hours, depending on the time of day.
[gender-neutral language](https://en.wikipedia.org/wiki/Gender-neutral_language).
For example, avoid using a pronoun like her or his in sentences like
"Every developer should clean [their] keyboard at least once a week."
* Follow the community [code of conduct](../code-of-conduct.html).
* Follow the community [code of conduct](../code-of-conduct.md).
* Participate! Zulip is a friendly and welcoming community, and we
love meeting new people, hearing about what brought them to Zulip,
and getting their feedback. If you're not sure where to start,

14
docs/contributing/code-reviewing.md
View File

@ -78,7 +78,7 @@ this?". Good choices include
up a page in the CI that has more details on why the job failed.
For example [this](https://circleci.com/gh/zulip/zulip/16617)
is the page of the `bionic-python-3.6` job. See our docs on
[continuous integration](../testing/continuous-integration.html)
[continuous integration](../testing/continuous-integration.md)
to learn more.
* *Technical design.* There are a lot of considerations here:
@ -105,7 +105,7 @@ this?". Good choices include
change being made. Tests that exclude whole classes of potential
bugs are preferred when possible (e.g., the common test suite
`test_bugdown.py` between the Zulip server's [frontend and backend
Markdown processors](../subsystems/markdown.html), or the `GetEventsTest` test for
Markdown processors](../subsystems/markdown.md), or the `GetEventsTest` test for
buggy race condition handling).
* *Translation.* Make sure that the strings are marked for
@ -194,11 +194,11 @@ We also strongly recommend reviewers to go through the following resources.
* [Code Review - A consolidation of advice and stuff from the
sinternet](https://gist.github.com/porterjamesj/002fb27dd70df003646df46f15e898de)
article by James J. Porter
* [Zulip Code of Conduct](../code-of-conduct.html)
* [Zulip Code of Conduct](../code-of-conduct.md)
[code-style]: ../contributing/code-style.html
[code-style]: ../contributing/code-style.md
[commit-messages]: ../contributing/version-control.html#commit-messages
[test-writing]: ../testing/testing.html
[mypy]: ../testing/mypy.html
[test-writing]: ../testing/testing.md
[mypy]: ../testing/mypy.md
[git tool]: ../git/zulip-tools.html#fetch-a-pull-request-and-rebase
[translation]: ../translating/translating.html
[translation]: ../translating/translating.md

4
docs/contributing/code-style.md
View File

@ -168,7 +168,7 @@ Don't use it:
### Translation tags
Remember to
[tag all user-facing strings for translation](../translating/translating.html), whether
[tag all user-facing strings for translation](../translating/translating.md), whether
they are in HTML templates or JavaScript/TypeScript editing the HTML (e.g. error
messages).
@ -297,5 +297,5 @@ All significant new features should come with tests. See testing.
### Third party code
See [our docs on dependencies](../subsystems/dependencies.html) for discussion of
See [our docs on dependencies](../subsystems/dependencies.md) for discussion of
rules about integrating third-party projects.

18
docs/contributing/gsod-ideas.md
View File

@ -27,7 +27,7 @@ engineers. Since Zulip is a team chat product, your GSoD experience
with the Zulip project will be highly interactive.
As part of that commitment, Zulip has over 150,000 words of
[documentation for developers](../), much of it designed to explain
[documentation for developers](../index.html#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.
### Our history with Google Open Source Programs
@ -37,7 +37,7 @@ generally have 10-15 GSoC students each summer. We have some of the highest
standards of any GSoC organization; successful applications generally
have dozens of commits integrated into Zulip or other open source
projects by the time we review their application. See
[our contributing guide](../overview/contributing.html) for details on
[our contributing guide](../overview/contributing.md) for details on
getting involved with GSoC.
Zulip participated in GSoC 2016 and mentored three successful students
@ -58,7 +58,7 @@ and keeping your eye on
[the GSoD timeline](https://developers.google.com/season-of-docs/docs/timeline). The
application deadline is June 28, 2019.
[Our guide for having a great summer with Zulip](../contributing/summer-with-zulip.html)
[Our guide for having a great summer with Zulip](../contributing/summer-with-zulip.md)
is focused on what one should know once doing a GSoC project with
Zulip; while it is written for the GSoC student audience, it should give
you a feel for how we interact with and mentor committed contributors.
@ -73,7 +73,7 @@ For many of our project ideas, you'll be working inside a Zulip
development environment (because the documentation is implemented as
markdown in the main Zulip repository, and can be previewed using
tools in the Zulip development environment). See
[our documentation on documentation systems](../documentation/overview.html)
[our documentation on documentation systems](../documentation/overview.md)
for details on our various existing documentation systems.
In part due to past work by a technical writer, Zulip has a
@ -83,7 +83,7 @@ project of its scope. Use
to get your Zulip development environment set up. If you have any
trouble, please speak up in
[#documentation](https://chat.zulip.org/#narrow/stream/19-documentation) on
[the Zulip development community server](../contributing/chat-zulip-org.html)
[the Zulip development community server](../contributing/chat-zulip-org.md)
(use your name as the topic).
## Application tips, and how to be a strong candidate
@ -145,7 +145,7 @@ appreciate extra attention on).
We are more interested in candidates if we see them submitting good
bug reports, helping other people on GitHub and on
[chat.zulip.org](../contributing/chat-zulip-org.html), and otherwise
[chat.zulip.org](../contributing/chat-zulip-org.md), and otherwise
being good members of the community.
## Mentors
@ -155,7 +155,7 @@ projects. We usually decide which members are mentoring which
projects based in part on who is a good fit for the needs of each
writer as well as technical expertise. You can reach us via
[#documentation](https://chat.zulip.org/#narrow/stream/19-documentation) on
[the Zulip development community server](../contributing/chat-zulip-org.html),
[the Zulip development community server](../contributing/chat-zulip-org.md),
(compose a new stream message with your name as the topic).
Zulip operates under group mentorship. That means you should
@ -202,7 +202,7 @@ together a complete project proposal. It's also fine for you to come
up with your own project ideas.
For many of our projects, an important skill to develop is a good
command of Git; read [our Git Guide](../git/overview.html) in full to
command of Git; read [our Git Guide](../git/overview.md) in full to
learn how to use it well. Of particular importance is mastering using
Git rebase so that you can construct commits that are readable,
are clearly correct and that explain why they are correct.
@ -211,7 +211,7 @@ are clearly correct and that explain why they are correct.
Fill in the gaps in Zulip's
[REST API documentation](https://zulipchat.com/api). Zulip has a
[nice framework](../documentation/api.html) for
[nice framework](../documentation/api.md) for
writing API documentation built by a student last summer based on the
OpenAPI standard with built-in automated tests, but there are dozens of
endpoints that are missing, several of which are quite important. See

8
docs/development/overview.md
View File

@ -80,13 +80,13 @@ And if you've setup the Zulip development environment on a remote
machine, take a look at our tips for
[developing remotely][dev-remote].
[dev-remote]: remote.html
[dev-remote]: remote.md
[install-direct]: ../development/setup-advanced.html#installing-directly-on-ubuntu-debian-centos-or-fedora
[install-generic]: ../development/setup-advanced.html#installing-manually-on-unix
[install-vagrant]: ../development/setup-vagrant.html
[install-vagrant]: ../development/setup-vagrant.md
[self-install-remote]: #installing-remotely
[self-slow-internet]: #slow-internet-connections
[configure-proxy]: ../development/setup-vagrant.html#specifying-a-proxy
[using-dev-env]: using.html
[testing]: ../testing/testing.html
[using-dev-env]: using.md
[testing]: ../testing/testing.md
[ci]: ../git/cloning.html#step-3-configure-continuous-integration-for-your-fork

10
docs/development/remote.md
View File

@ -130,7 +130,7 @@ don't have a favorite, here are some suggestions:
* [spacemacs](https://github.com/syl20bnr/spacemacs)
* [sublime](https://www.sublimetext.com/)
Next, follow our [Git and GitHub Guide](../git/index.html) to clone and configure
Next, follow our [Git and GitHub Guide](../git/index.md) to clone and configure
your fork of zulip on your local computer.
Once you have cloned your code locally, you can get to work.
@ -257,10 +257,10 @@ Next, read the following to learn more about developing for Zulip:
* [Testing][rtd-testing]
[install-direct]: ../development/setup-advanced.html#installing-directly-on-ubuntu-debian-centos-or-fedora
[install-vagrant]: ../development/setup-vagrant.html
[rtd-git-guide]: ../git/index.html
[rtd-using-dev-env]: using.html
[rtd-testing]: ../testing/testing.html
[install-vagrant]: ../development/setup-vagrant.md
[rtd-git-guide]: ../git/index.md
[rtd-using-dev-env]: using.md
[rtd-testing]: ../testing/testing.md
[git-bash]: https://git-for-windows.github.io/
[codeanywhere]: https://codeanywhere.com/
[img-ca-settings]: ../images/codeanywhere-settings.png

8
docs/development/request-remote.md
View File

@ -67,14 +67,14 @@ Once your remote dev instance is ready:
Once you've confirmed you can connect to your remote server, take a look at:
* [developing remotely](../development/remote.html) for tips on using the remote dev
* [developing remotely](../development/remote.md) for tips on using the remote dev
instance, and
* our [Git & GitHub Guide](../git/index.html) to learn how to use Git with Zulip.
* our [Git & GitHub Guide](../git/index.md) to learn how to use Git with Zulip.
Next, read the following to learn more about developing for Zulip:
* [Using the Development Environment](../development/using.html)
* [Testing](../testing/testing.html)
* [Using the Development Environment](../development/using.md)
* [Testing](../testing/testing.md)
[github-join]: https://github.com/join
[github-help-add-ssh-key]: https://help.github.com/en/articles/adding-a-new-ssh-key-to-your-github-account

2
docs/development/setup-advanced.md
View File

@ -20,7 +20,7 @@ that's running one of:
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](../development/remote.html), see
If you are using a [remote server](../development/remote.md), see
the
[section on creating appropriate user accounts](../development/remote.html#setting-up-user-accounts).

24
docs/development/setup-vagrant.md
View File

@ -27,7 +27,7 @@ Errors](#troubleshooting-and-common-errors). If that doesn't help,
please visit [#provision
help](https://chat.zulip.org/#narrow/stream/21-provision-help) in the
[Zulip development community
server](../contributing/chat-zulip-org.html) for real-time help or
server](../contributing/chat-zulip-org.md) for real-time help or
[file an issue](https://github.com/zulip/zulip/issues).
When reporting your issue, please include the following information:
@ -297,7 +297,7 @@ does the following:
downloads all required dependencies, sets up the python environment for
the Zulip development server, and initializes a default test
database. We call this process "provisioning", and it is documented
in some detail in our [dependencies documentation](../subsystems/dependencies.html).
in some detail in our [dependencies documentation](../subsystems/dependencies.md).
You will need an active internet connection during the entire
process. (See [Specifying a proxy](#specifying-a-proxy) if you need a
@ -309,7 +309,7 @@ documented in the
[Troubleshooting and Common Errors](#troubleshooting-and-common-errors)
section. If that doesn't help, please visit
[#provision help](https://chat.zulip.org/#narrow/stream/21-provision-help)
in the [Zulip development community server](../contributing/chat-zulip-org.html) for
in the [Zulip development community server](../contributing/chat-zulip-org.md) for
real-time help.
On Windows, you will see `The system cannot find the path specified.` message
@ -420,7 +420,7 @@ It's good to have the terminal running `run-dev.py` up as you work since error
messages including tracebacks along with every backend request will be printed
there.
See [Logging](../subsystems/logging.html) for further details on the run-dev.py console
See [Logging](../subsystems/logging.md) for further details on the run-dev.py console
output.
#### Committing and pushing changes with git
@ -449,7 +449,7 @@ After provisioning, you'll want to
If you run into any trouble, the
[#provision help](https://chat.zulip.org/#narrow/stream/21-provision-help)
in the [Zulip development community server](../contributing/chat-zulip-org.html) for
in the [Zulip development community server](../contributing/chat-zulip-org.md) for
is a great place to ask for help.
#### Rebuilding the development environment
@ -547,7 +547,7 @@ If these solutions aren't working for you or you encounter an issue not
documented below, there are a few ways to get further help:
* Ask in [#provision help](https://chat.zulip.org/#narrow/stream/21-provision-help)
in the [Zulip development community server](../contributing/chat-zulip-org.html).
in the [Zulip development community server](../contributing/chat-zulip-org.md).
* [File an issue](https://github.com/zulip/zulip/issues).
When reporting your issue, please include the following information:
@ -1045,12 +1045,12 @@ remove the `GUEST_CPUS` and `GUEST_MEMORY_MB` lines from
[vbox-dl]: https://www.virtualbox.org/wiki/Downloads
[vmware-fusion-dl]: http://www.vmware.com/products/fusion.html
[vagrant-vmware-fusion-dl]: https://www.vagrantup.com/vmware/
[install-advanced]: ../development/setup-advanced.html
[rtd-git-guide]: ../git/index.html
[rtd-testing]: ../testing/testing.html
[rtd-using-dev-env]: using.html
[rtd-dev-remote]: remote.html
[install-advanced]: ../development/setup-advanced.md
[rtd-git-guide]: ../git/index.md
[rtd-testing]: ../testing/testing.md
[rtd-using-dev-env]: using.md
[rtd-dev-remote]: remote.md
[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.html
[set-up-git]: ../git/setup.md
[ci]: ../git/cloning.html#step-3-configure-continuous-integration-for-your-fork

4
docs/development/using.md
View File

@ -49,5 +49,5 @@ restart if it crashes, and `upgrade-zulip` will take care of running
migrations and then cleanly restaring the server for you).
[django-runserver]: https://docs.djangoproject.com/en/1.8/ref/django-admin/#runserver-port-or-address-port
[new-feature-tutorial]: ../tutorials/new-feature-tutorial.html
[testing-docs]: ../testing/testing.html
[new-feature-tutorial]: ../tutorials/new-feature-tutorial.md
[testing-docs]: ../testing/testing.md

6
docs/documentation/api.md
View File

@ -9,11 +9,11 @@ it and helping ensure it stays up to date as Zulip's API changes.
Our API documentation is defined by a few sets of files:
* Most data describing API endpoints and examples is stored in our
[OpenAPI configuration](../documentation/openapi.html) at
[OpenAPI configuration](../documentation/openapi.md) at
`zerver/openapi/zulip.yaml`.
* The top-level templates live under `templates/zerver/api/*`, and are
written using the markdown framework that powers our [user
docs](../documentation/user.html), with some special extensions for
docs](../documentation/user.md), with some special extensions for
rendering nice code blocks and example responses.
* The text for the Python examples comes from a test suite for the
Python API documentation (`zerver/openapi/python_examples.py`; run via
@ -174,7 +174,7 @@ This section offers a step-by-step process for adding documentation
for a new API endpoint. It assumes you've read and understood the
above.
1. Start by adding [OpenAPI format](../documentation/openapi.html)
1. Start by adding [OpenAPI format](../documentation/openapi.md)
data to `zerver/openapi/zulip.yaml` for the endpoint. If you
copy-paste (which is helpful to get the indentation structure
right), be sure to update all the content that you copied to

8
docs/documentation/overview.md
View File

@ -92,19 +92,19 @@ to do the things one does a lot in each type of documentation.
To learn more about Zulip's general user documentation,
[visit it on zulipchat.com](https://zulipchat.com/help/) or
[read our guide on writing user documentation](user.html).
[read our guide on writing user documentation](user.md).
### Integrations documentation
To learn more about Zulip's integrations documentation,
[visit it on zulipchat.com](https://zulipchat.com/integrations/) or
[read our guide on writing user documentation](integrations.html).
[read our guide on writing user documentation](integrations.md).
### API documentation
To learn more about Zulip's API documentation,
[visit it on zulipchat.com](https://zulipchat.com/api/) or
[read our tutorial on writing user documentation](../documentation/api.html).
[read our tutorial on writing user documentation](../documentation/api.md).
## Automated testing
@ -114,7 +114,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).
See the [main linter doc](../testing/linters.html) for more details.
See the [main linter doc](../testing/linters.md) for more details.
* The ReadTheDocs docs are built and the links tested by
`tools/test-documentation`, which runs `build-docs` and then checks

4
docs/git/cheat-sheet.md
View File

@ -111,6 +111,6 @@ See also [fixing commits][fix-commit]
- status
- `git status`: show the working tree status, unstaged and staged files
[fix-commit]: fixing-commits.html
[fix-commit]: fixing-commits.md
[git-config-clone]: cloning.html#step-1b-clone-to-your-machine
[git-overview]: overview.html
[git-overview]: ./overview.md

4
docs/git/cloning.md
View File

@ -152,6 +152,6 @@ Zulip.
[travis-ci]: https://travis-ci.org/
[circle-ci]:https://circleci.com/
[travis-ci-profile]: https://travis-ci.org/profile
[zulip-rtd-dev-first-time]: ../development/setup-vagrant.html
[zulip-rtd-dev-overview]: ../development/overview.html
[zulip-rtd-dev-first-time]: ../development/setup-vagrant.md
[zulip-rtd-dev-overview]: ../development/overview.md
[zulip-rtd-tools-setup]: ../git/zulip-tools.html#set-up-git-repo-script

14
docs/git/overview.md
View File

@ -58,14 +58,14 @@ git workflow, or if you'd like a git refresher.
[github-rebase-pr]: https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request
[github-zulip]: https://github.com/zulip/
[github-zulip-zulip]: https://github.com/zulip/zulip/
[continuous-integration]: ../testing/continuous-integration.html
[continuous-integration]: ../testing/continuous-integration.md
[zulip-git-guide-fork-ci]: ../git/cloning.html#step-3-configure-continuous-integration-for-your-fork
[zulip-rtd-code-style]: ../contributing/code-style.html
[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-dev-overview]: ../development/overview.html
[zulip-rtd-dev-overview]: ../development/overview.md
[zulip-rtd-lint-tools]: ../contributing/code-style.html#lint-tools
[zulip-rtd-mypy]: ../testing/mypy.html
[zulip-rtd-testing]: ../testing/testing.html
[zulip-rtd-zulip-tools]: ../git/zulip-tools.html
[zulip-rtd-zulipbot-usage]: ../contributing/zulipbot-usage.html
[zulip-rtd-mypy]: ../testing/mypy.md
[zulip-rtd-testing]: ../testing/testing.md
[zulip-rtd-zulip-tools]: ../git/zulip-tools.md
[zulip-rtd-zulipbot-usage]: ../contributing/zulipbot-usage.md

2
docs/git/pull-requests.md
View File

@ -148,5 +148,5 @@ for another review.
[images-create-pr]: ../images/zulip-open-pr.png
[keep-up-to-date]: ../git/using.html#keep-your-fork-up-to-date
[push-commits]: ../git/using.html#push-your-commits-to-github
[screenshots-gifs]: ../tutorials/screenshot-and-gif-software.html
[screenshots-gifs]: ../tutorials/screenshot-and-gif-software.md
[wip-prs]: #work-in-progress-pull-requests

2
docs/git/reviewing.md
View File

@ -61,4 +61,4 @@ Display changes you've committed so far since creating a branch from upstream/ma
$ git diff upstream/master...HEAD
```
[zulip-rtd-review]: ../contributing/code-reviewing.html
[zulip-rtd-review]: ../contributing/code-reviewing.md

4
docs/git/using.md
View File

@ -126,7 +126,7 @@ Now you're ready to work on the issue or feature.
## Run linters and tests locally
In addition to having Travis run tests and linters each time you push a new
commit, you can also run them locally. See [testing](../testing/testing.html) for details.
commit, you can also run them locally. See [testing](../testing/testing.md) for details.
## Stage changes
@ -446,7 +446,7 @@ complicated rebase.
[github-help-push]: https://help.github.com/en/articles/pushing-to-a-remote
[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.html
[how-git-is-different]: ./the-git-difference.md
[zulip-git-guide-up-to-date]: ../git/using.html#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

2
docs/git/zulip-tools.md
View File

@ -9,7 +9,7 @@ time when working with Git on the Zulip project.
[zulip/zulip][github-zulip-zulip] you'll find a bash script
`setup-git-repo`. This script installs a pre-commit hook, which will
run each time you `git commit` to automatically run
[Zulip's linter suite](../testing/linters.html) on just the files that
[Zulip's linter suite](../testing/linters.md) on just the files that
the commit modifies (which is really fast!). The hook passes no matter
the result of the linter, but you should still pay attention to any
notices or warnings it displays.

22
docs/overview/architecture-overview.md
View File

@ -9,7 +9,7 @@ contains the Zulip backend (written in Python 3.x and Django), the
webapp (written in JavaScript and TypeScript) and our library of
incoming webhook [integrations](https://zulipchat.com/integrations)
with other services and applications (see [the directory structure
guide](../overview/directory-structure.html)).
guide](../overview/directory-structure.md)).
[Zulip Mobile](https://github.com/zulip/zulip-mobile) is the official
mobile Zulip client supporting both iOS and Android, written in
@ -57,7 +57,7 @@ means that one person might be a user of multiple Zulip realms. The
administrators of an organization have a great deal of control over
who can register an account, what permissions new users have, etc. For
more on security considerations and options, see [the security model
section](../production/security-model.html) and the [Zulip Help
section](../production/security-model.md) and the [Zulip Help
Center](https://zulipchat.com/help).
Components
@ -99,7 +99,7 @@ exception to this is that Zulip uses websockets through Tornado to
minimize latency on the code path for **sending** messages.
There is detailed documentation on the
[real-time push and event queue system](../subsystems/events-system.html); most of
[real-time push and event queue system](../subsystems/events-system.md); most of
the code is in `zerver/tornado`.
#### HTML templates, JavaScript, etc.
@ -112,10 +112,10 @@ live-rendering HTML from JavaScript for things like the main message
feed.
For more details on the frontend, see our documentation on
[translation](../translating/translating.html),
[templates](../subsystems/html-templates.html),
[directory structure](../overview/directory-structure.html), and
[the static asset pipeline](../subsystems/front-end-build-process.html).
[translation](../translating/translating.md),
[templates](../subsystems/html-templates.md),
[directory structure](../overview/directory-structure.md), and
[the static asset pipeline](../subsystems/front-end-build-process.md).
[Jinja2]: http://jinja.pocoo.org/
[Handlebars]: http://handlebarsjs.com/
@ -166,7 +166,7 @@ processes that process event queues. We use event queues for the kinds
of tasks that are best run in the background because they are
expensive (in terms of performance) and don't have to be synchronous
--- e.g., sending emails or updating analytics. Also see [the queuing
guide](../subsystems/queuing.html).
guide](../subsystems/queuing.md).
### memcached
@ -175,7 +175,7 @@ objects. `zerver/lib/cache.py` and `zerver/lib/cache_helpers.py`
manage putting things into memcached, and invalidating the cache when
values change. The memcached configuration is in
`puppet/zulip/files/memcached.conf`. See our
[caching guide](../subsystems/caching.html) to learn how this works in
[caching guide](../subsystems/caching.md) to learn how this works in
detail.
### Redis
@ -233,7 +233,7 @@ processes started by Supervisor are queue processors that continually
pull things out of a RabbitMQ queue and handle them; they are defined
in `zerver/worker/queue_processors.py`.
Also see [the queuing guide](../subsystems/queuing.html).
Also see [the queuing guide](../subsystems/queuing.md).
### PostgreSQL
@ -258,7 +258,7 @@ to create the actual database with its schema.
We use Thumbor, a popular open source thumbnailing server, to serve
images (both for inline URL previews and serving uploaded image
files). See [our thumbnailing docs](../subsystems/thumbnailing.html)
files). See [our thumbnailing docs](../subsystems/thumbnailing.md)
for more details on how this works.
### Nagios

14
docs/overview/changelog.md
View File

@ -13,7 +13,7 @@ in bursts.
improvements that had previously been blocked because they weren't
worth shipping our own upgraded versions of dependencies.
- Significantly improved the email->Zulip gateway, and added [nice
setup documentation](../production/email-gateway.html). It now
setup documentation](../production/email-gateway.md). It now
should be possible to subscribe a Zulip stream to an email list and
have a good experience.
- Added production support for Debian buster.
@ -43,7 +43,7 @@ in bursts.
readable style.
- We merged significant preparatory work for supporting RHEL/CentOS in
production. We're now interested in beta testers for this feature.
- Added [new documentation](../production/modifying-zulip.html) on
- Added [new documentation](../production/modifying-zulip.md) 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).
@ -438,7 +438,7 @@ Zulip installations; it has minimal changes for existing servers.
disruption by running this migration first, before beginning the
user-facing downtime. However, if you'd like to watch the downtime
phase of the upgrade closely, we recommend
[running them first manually](../production/expensive-migrations.html)
[running them first manually](../production/expensive-migrations.md)
and as well as the usual trick of
[doing an apt upgrade first](../production/maintain-secure-upgrade.html#applying-system-updates).
@ -521,7 +521,7 @@ Zulip installations; it has minimal changes for existing servers.
### 1.8.1 -- 2018-05-07
- Added an automated tool (`manage.py register_server`) to sign up for
the [mobile push notifications service](../production/mobile-push-notifications.html).
the [mobile push notifications service](../production/mobile-push-notifications.md).
- Improved rendering of block quotes in mobile push notifications.
- Improved some installer error messages.
- Fixed several minor bugs with the new Slack import feature.
@ -816,7 +816,7 @@ Backend and scaling
minimizes disruption by running these first, before beginning the
user-facing downtime. However, if you'd like to watch the downtime
phase of the upgrade closely, we recommend
[running them first manually](../production/expensive-migrations.html) and as well
[running them first manually](../production/expensive-migrations.md) and as well
as the usual trick of
[doing an apt upgrade first](../production/maintain-secure-upgrade.html#applying-system-updates).
@ -828,7 +828,7 @@ Backend and scaling
This change should have no effect for the vast majority of Zulip
servers that only have one organization. If you manage a server
that hosts multiple organizations, you'll want to read [our guide on
multiple organizations](../production/multiple-organizations.html).
multiple organizations](../production/multiple-organizations.md).
* We simplified the configuration for our password strength checker to
be much more intuitive. If you were using the
@ -976,7 +976,7 @@ Zulip apps.
Hungarian, Polish, Dutch, Russian, Bulgarian, Portuguese,
Serbian, Malayalam, Korean, and Italian).
[mobile-push]: ../production/mobile-push-notifications.html
[mobile-push]: ../production/mobile-push-notifications.md
[electron-app]: https://github.com/zulip/zulip-desktop/releases
[ios-app]: https://itunes.apple.com/us/app/zulip/id1203036395

10
docs/overview/directory-structure.md
View File

@ -4,7 +4,7 @@ This page documents the Zulip directory structure, where to find
things, and how to decide where to put a file.
You may also find the [new application feature
tutorial](../tutorials/new-feature-tutorial.html) helpful for understanding the
tutorial](../tutorials/new-feature-tutorial.md) helpful for understanding the
flow through these files.
### Core Python files
@ -30,11 +30,11 @@ paths will be familiar to Django developers.
* `zerver/tornado/views.py` Tornado views.
* `zerver/worker/queue_processors.py` [Queue workers](../subsystems/queuing.html).
* `zerver/worker/queue_processors.py` [Queue workers](../subsystems/queuing.md).
* `zerver/lib/*.py` Most library code.
* `zerver/lib/bugdown/` [Backend Markdown processor](../subsystems/markdown.html).
* `zerver/lib/bugdown/` [Backend Markdown processor](../subsystems/markdown.md).
* `zproject/backends.py` [Authentication backends](https://docs.djangoproject.com/en/1.8/topics/auth/customizing/).
@ -42,7 +42,7 @@ paths will be familiar to Django developers.
### HTML Templates
See [our docs](../subsystems/html-templates.html) for details on Zulip's
See [our docs](../subsystems/html-templates.md) for details on Zulip's
templating systems.
* `templates/zerver/` For [Jinja2](http://jinja.pocoo.org/) templates
@ -87,7 +87,7 @@ These are distinguished from scripts, below, by needing to run a
Django context (i.e. with database access).
* `zerver/management/commands/`
[Management commands](../subsystems/management-commands.html) one might run at a
[Management commands](../subsystems/management-commands.md) one might run at a
production deployment site (e.g. scripts to change a value or
deactivate a user properly).

28
docs/overview/gsoc-ideas.md
View File

@ -10,7 +10,7 @@ high-quality applications we receive. We have some of the highest
standards of any GSoC organization; successful applications generally
have dozens of commits integrated into Zulip or other open source
projects by the time we review their application. See
[our contributing guide](../overview/contributing.html) for details on
[our contributing guide](../overview/contributing.md) for details on
getting involved.
## About us
@ -39,7 +39,7 @@ the concepts and reasoning behind how Zulip is engineered and how to
make it better.
As part of that commitment, Zulip has over 130,000 words of
[documentation for developers](../), much of it designed to explain
[documentation for developers](../index.html#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.
Zulip participated in GSoC 2016 and mentored three successful students
@ -51,7 +51,7 @@ project today).
### Expectations for GSoC students
[Our guide for having a great summer with Zulip](../contributing/summer-with-zulip.html)
[Our guide for having a great summer with Zulip](../contributing/summer-with-zulip.md)
is focused on what one should know once doing a summer project with
Zulip. But it has a lot of useful advice on how we expect students to
interact, above and beyond what is discussed in Google's materials.
@ -77,7 +77,7 @@ tasks that are great for first-time contributors. Use
to get your Zulip development environment set up and to find your first issue. If you have any
trouble, please speak up in
[#GSoC](https://chat.zulip.org/#narrow/stream/14-GSoC) on
[the Zulip development community server](../contributing/chat-zulip-org.html)
[the Zulip development community server](../contributing/chat-zulip-org.md)
(use your name as the topic).
## Application tips, and how to be a strong candidate
@ -123,7 +123,7 @@ application deadline.
We are more interested in candidates if we see them submitting good
contributions to Zulip projects, helping other applicants on GitHub
and on
[chat.zulip.org](../contributing/chat-zulip-org.html),
[chat.zulip.org](../contributing/chat-zulip-org.md),
learning from our suggestions,
[trying to solve their own obstacles and then asking well-formed
questions](https://blogs.akamai.com/2013/10/you-must-try-and-then-you-must-ask.html),
@ -166,7 +166,7 @@ mentoring projects. We usually decide which contributors are
mentoring which projects based in part on who is a good fit for the
needs of each student as well as technical expertise. You can reach
us via [#GSoC](https://chat.zulip.org/#narrow/stream/14-GSoC) on
[the Zulip development community server](../contributing/chat-zulip-org.html),
[the Zulip development community server](../contributing/chat-zulip-org.md),
(compose a new stream message with your name as the topic).
Zulip operates under group mentorship. That means you should
@ -216,7 +216,7 @@ skills needed, and try to emphasize where strong skills with
particular tools are likely to be important for a given project.
For all of our projects, an important skill to develop is a good
command of Git; read [our Git Guide](../git/overview.html) in full to
command of Git; read [our Git Guide](../git/overview.md) in full to
learn how to use it well. Of particular importance is mastering using
Git rebase so that you can construct commits that are clearly correct
and explain why they are correct.
@ -260,7 +260,7 @@ CSS](https://github.com/zulip/zulip/).
- Fill in the gaps in Zulip's
[REST API documentation](https://zulipchat.com/api). Zulip has a
[nice framework](../documentation/api.html) for
[nice framework](../documentation/api.md) for
writing API documentation built by a student last summer based on
the OpenAPI standard with built-in automated tests, but there are a
few dozen endpoints that are missing, several of which are quite
@ -282,7 +282,7 @@ CSS](https://github.com/zulip/zulip/).
e.g. having built a prototype with
[the Django Oauth toolkit](https://django-oauth-toolkit.readthedocs.io/en/latest/)
would be great to demonstrate as part of an application. The
[Zulip integration writing guide](../documentation/integrations.html)
[Zulip integration writing guide](../documentation/integrations.md)
and
[integration documentation](https://chat.zulip.org/integrations/)
are useful materials for learning about how things currently work,
@ -335,7 +335,7 @@ CSS](https://github.com/zulip/zulip/).
at `contrib_bots/` in the main Zulip repository that can be used for
testing; the design document for the deployment part of this vision
(likely part 1) is
[here](../subsystems/custom-apps.html).
[here](../subsystems/custom-apps.md).
**Skills recommended**: Python and JavaScript/CSS, plus devops
skills (Linux deployment, Docker, puppet etc.) are all useful here.
Experience writing tools using various popular APIs is helpful for
@ -382,7 +382,7 @@ CSS](https://github.com/zulip/zulip/).
semi-duplicate code for each feature. **Skills recommended**: A
good mix of Python/Django and HTML/CSS/JavaScript skill is ideal.
The system for adding new features is
[well documented](../tutorials/new-feature-tutorial.html).
[well documented](../tutorials/new-feature-tutorial.md).
Expert: Shubham Dhama.
- Rebuild the Zulip web UI using a modern reactive layer like vue.js.
@ -390,7 +390,7 @@ CSS](https://github.com/zulip/zulip/).
presence layer), then move on to more complex pieces (like the
subscriptions page), and finally attach the main UI. Definitely worth
reading the vue.js documentation and reading
[how Zulip's real-time sync works](../subsystems/events-system.html).
[how Zulip's real-time sync works](../subsystems/events-system.md).
**Skills recommended**: Strong JavaScript experience, good
communication skills and an eye for detail. We think this would be an
awesome project, but rewrite projects often introduce lots of bugs, so
@ -398,7 +398,7 @@ we're interested in particularly careful candidates who have the
discipline to redo a small component at a time and carefully test for
regressions. Good ways to demonstrate qualification for this are
finding and reporting bugs using
[Zulip's manual UI testing guide](../testing/manual-testing.html)
[Zulip's manual UI testing guide](../testing/manual-testing.md)
and doing
[refactoring projects](https://github.com/zulip/zulip/labels/area%3A%20refactoring).
Expert: Tommy Ip, Tim Abbott.
@ -436,7 +436,7 @@ Expert: Tommy Ip, Tim Abbott.
single area).
A possible specific larger project in this space is working on
adding [mypy](../testing/mypy.html) stubs
adding [mypy](../testing/mypy.md) stubs
for Django in mypy to make our type checking more powerful. Read
[our mypy blog post](https://blog.zulip.org/2016/10/13/static-types-in-python-oh-mypy/)
for details on how mypy works and is integrated into zulip. This

2
docs/overview/roadmap.md
View File

@ -27,7 +27,7 @@ priority projects.
We welcome participation from the community in influencing the Zulip
roadmap. If a bug or missing feature is causing significant pain for your
organization, we appreciate your commenting to that effect, either in
[chat.zulip.org](../contributing/chat-zulip-org.html) or on the
[chat.zulip.org](../contributing/chat-zulip-org.md) or on the
relevant GitHub issue, with an explanation of how the issue impacts
your use case. See [Reporting issues](contributing.html#reporting-issues)
for more information.

6
docs/production/authentication-methods.md
View File

@ -118,7 +118,7 @@ email address, if it isn't the same as the "Zulip username").
**If you are using LDAP for authentication**: you will need to enable
the `zproject.backends.ZulipLDAPAuthBackend` auth backend, in
`AUTHENTICATION_BACKENDS` in `/etc/zulip/settings.py`. After doing
so (and as always [restarting the Zulip server](settings.html) to ensure
so (and as always [restarting the Zulip server](settings.md) to ensure
your settings changes take effect), you should be able to log into
Zulip by entering your email address and LDAP password on the Zulip
login form.
@ -387,9 +387,9 @@ For example, the
was about 30 lines of code, plus some documentation and an
[automatically generated migration][schema-migrations]. We also have
helpful developer documentation on
[testing auth backends](../subsystems/auth.html).
[testing auth backends](../subsystems/auth.md).
[schema-migrations]: ../subsystems/schema-migrations.html
[schema-migrations]: ../subsystems/schema-migrations.md
[python-social-auth]: https://python-social-auth.readthedocs.io/en/latest/
## Development only

4
docs/production/deployment.md
View File

@ -25,7 +25,7 @@ You can also [upgrade Zulip from Git](../production/maintain-secure-upgrade.html
Zulip has an officially supported, experimental
[docker image](https://github.com/zulip/docker-zulip). Please note
that Zulip's [normal installer](../production/install.html) has been
that Zulip's [normal installer](../production/install.md) has been
extremely reliable for years, whereas the Docker image is new and has
rough edges, so we recommend the normal installer unless you have a
specific reason to prefer Docker.
@ -67,7 +67,7 @@ of managing chat.zulip.org and zulipchat.com.
You cannot use most third-party database-as-a-service provides like
Amazon RDS as the database provider with Zulip, because Zulip requires
one of two different [full-text search postgres
extensions](../subsystems/full-text-search.html) to power its search.
extensions](../subsystems/full-text-search.md) to power its search.
Neither is available in Amazon RDS; there should be no issue with
using Zulip with a different database-as-a-service provider as long as
one of those postgres extensions is available.

2
docs/production/email.md
View File

@ -19,7 +19,7 @@ email addresses and send notifications.
example: `email_password = abcd1234`.
Like any other change to the Zulip configuration, be sure to
[restart the server](settings.html) to make your changes take
[restart the server](settings.md) to make your changes take
effect.
1. Configure your SMTP server to allows your Zulip server to send

6
docs/production/export-and-import.md
View File

@ -77,7 +77,7 @@ archive of all the organization's uploaded files.
## Import into a new Zulip server
(1.) [Install a new Zulip server](../production/install.html),
(1.) [Install a new Zulip server](../production/install.md),
skipping "Step 3: Create a Zulip organization, and log in" (you'll
create your Zulip organization via the data import tool instead).
@ -166,7 +166,7 @@ organization using the following procedure:
* Start a [Zulip management shell](../production/maintain-secure-upgrade.html#manage-py-shell)
* In the management shell, run the following commands, replacing `""`
with the subdomain if [you are hosting the organization on a
subdomain](../production/multiple-organizations.html):
subdomain](../production/multiple-organizations.md):
```
realm = Realm.objects.get(string_id="")
@ -181,7 +181,7 @@ Now, exit the management shell and run this to clear Zulip's cache:
```
Assuming you're using the
[local file uploads backend](../production/upload-backends.html), you
[local file uploads backend](../production/upload-backends.md), you
can additionally delete all file uploads, avatars, and custom emoji on
a Zulip server (across **all organizations**) with the following
command:

2
docs/production/install-existing-server.md
View File

@ -82,5 +82,5 @@ We don't provide a convenient way to uninstall a Zulip server.
Most of the limitations are things we'd accept a pull request to fix;
we welcome contributions to shrink this list of gotchas. Chat with us
in the [chat.zulip.org community](../contributing/chat-zulip-org.html) if you're
in the [chat.zulip.org community](../contributing/chat-zulip-org.md) if you're
interested in helping!

20
docs/production/install.md
View File

@ -1,14 +1,14 @@
# Production Installation
You'll need an Ubuntu or Debian system that satisfies
[the installation requirements](../production/requirements.html). Alternatively,
[the installation requirements](../production/requirements.md). Alternatively,
you can use a preconfigured
[Digital Ocean droplet](https://marketplace.digitalocean.com/apps/zulip), or
Zulip's
[experimental Docker image](../production/deployment.html#zulip-in-docker).
Note that if you're developing for Zulip, you should install Zulip's
[development environment](../development/overview.html) instead. If
[development environment](../development/overview.md) instead. If
you're just looking to play around with Zulip and see what it looks like,
you can create a test organization at <https://zulipchat.com/new>.
@ -67,7 +67,7 @@ If the script gives an error, consult [Troubleshooting](#troubleshooting) below.
If you'd prefer to acquire an SSL certificate yourself in any other
way, it's easy to [provide it to Zulip][doc-ssl-manual].
[doc-settings]: ../production/settings.html
[doc-settings]: ../production/settings.md
[doc-certbot]: ../production/ssl-certificates.html#certbot-recommended
[doc-ssl-manual]: ../production/ssl-certificates.html#manual-install
@ -89,14 +89,14 @@ Then, log in!
The link is a secure one-time-use link. If you need another
later, you can generate a new one by running `manage.py
generate_realm_creation_link` on the server. See also our doc on
running [multiple organizations on the same server](multiple-organizations.html)
running [multiple organizations on the same server](multiple-organizations.md)
if that's what you're planning to do.
## Step 4: Configure and use
To really see Zulip in action, you'll need to get the people you work
together with using it with you.
* [Set up outgoing email](email.html) so Zulip can confirm new users'
* [Set up outgoing email](email.md) so Zulip can confirm new users'
email addresses and send notifications.
* Learn how to [get your organization started][realm-admin-docs] using
Zulip at its best.
@ -108,8 +108,8 @@ Learning more:
for server administrators. This extremely low-traffic list is for
important announcements, including new releases and security issues.
* Follow [Zulip on Twitter](https://twitter.com/zulip).
* Learn how to [configure your Zulip server settings](settings.html).
* Learn about [maintaining a production Zulip server](maintain-secure-upgrade.html).
* Learn how to [configure your Zulip server settings](settings.md).
* Learn about [maintaining a production Zulip server](maintain-secure-upgrade.md).
[realm-admin-docs]: https://zulipchat.com/help/getting-your-organization-started-with-zulip
@ -132,7 +132,7 @@ Postgres, RabbitMQ, Memcached and Redis.
* Initializes Zulip's database.
If you'd like to deploy Zulip with these services on different
machines, check out our [deployment options documentation](deployment.html).
machines, check out our [deployment options documentation](deployment.md).
## Troubleshooting
@ -158,13 +158,13 @@ and can just skip that step.
**After the install script.**
If you get an error after `scripts/setup/install` completes, check
the bottom of `/var/log/zulip/errors.log` for a traceback, and consult
the [troubleshooting section](troubleshooting.html) for advice on
the [troubleshooting section](troubleshooting.md) for advice on
how to debug.
**Community.**
If the tips above don't help, please visit
[#production help](https://chat.zulip.org/#narrow/stream/31-production-help)
in the [Zulip development community server](../contributing/chat-zulip-org.html) for
in the [Zulip development community server](../contributing/chat-zulip-org.md) for
realtime help or email zulip-help@googlegroups.com with the full
traceback, and we'll try to help you out! Please provide details like
the full traceback from the bottom of `/var/log/zulip/errors.log` in

24
docs/production/maintain-secure-upgrade.md
View File

@ -13,7 +13,7 @@ secure Zulip installation, including:
You may also want to read this related content:
- [Security Model](../production/security-model.html)
- [Security Model](../production/security-model.md)
## Upgrading
@ -213,7 +213,7 @@ git_repo_url = https://github.com/zulip/zulip.git
```
See also our documentation on [modifying
Zulip](../production/modifying-zulip.html) and [upgrading
Zulip](../production/modifying-zulip.md) and [upgrading
docker-zulip](https://github.com/zulip/docker-zulip#upgrading-from-a-git-repository).
**Systems with limited RAM**: If you are running a minimal Zulip
@ -413,7 +413,7 @@ disrupting service (e.g. `zuliptest.example.com` rather than
`zulip.example.com`).
If you do so, just like any other time you change the hostname, you'll
need to [update `EXTERNAL_HOST`](../production/settings.html) and then
need to [update `EXTERNAL_HOST`](../production/settings.md) and then
restart the Zulip server (after backup restoration completes).
Until you do, your Zulip server will think its user-facing hostname is
@ -432,7 +432,7 @@ extracting the entire archive.
tar -Oaxf /path/to/archive/zulip-backup-rest.tar.gz zulip-backup/zulip-version
```
[install-server]: ../production/install.html
[install-server]: ../production/install.md
### What is included
@ -459,7 +459,7 @@ backup archives, and you may want to backup separately:
compared to the rest of the data for a Zulip server.
* Files uploaded with the Zulip
[S3 file upload backend](../production/upload-backends.html). We
[S3 file upload backend](../production/upload-backends.md). We
don't include these for two reasons. First, the uploaded file data
in S3 can easily be many times larger than the rest of the backup,
and downloading it all to a server doing a backup could easily
@ -515,7 +515,7 @@ more human-readable and easier to parse, and doesn't have the
requirement that the same set of Zulip organizations exist on the two
servers (which is critical for migrations to and from Zulip Cloud).
[export-import]: ../production/export-and-import.html
[export-import]: ../production/export-and-import.md
### Restore from manual backups
@ -630,16 +630,16 @@ running Zulip with larger teams (especially >1000 users).
* For an organization with 100+ users, it's important to have more
than 4GB of RAM on the system. Zulip will install on a system with
2GB of RAM, but with less than 3.5GB of RAM, it will run its
[queue processors](../subsystems/queuing.html) multithreaded to conserve memory;
[queue processors](../subsystems/queuing.md) multithreaded to conserve memory;
this creates a significant performance bottleneck.
* [chat.zulip.org](../contributing/chat-zulip-org.html), with thousands of user
* [chat.zulip.org](../contributing/chat-zulip-org.md), with thousands of user
accounts and thousands of messages sent every week, has 8GB of RAM,
4 cores, and 80GB of disk. The CPUs are essentially always idle,
but the 8GB of RAM is important.
* We recommend using a [remote postgres
database](postgres.html) for isolation, though it is
database](postgres.md) for isolation, though it is
not required. In the following, we discuss a relatively simple
configuration with two types of servers: application servers
(running Django, Tornado, RabbitMQ, Redis, Memcached, etc.) and
@ -698,7 +698,7 @@ welcome! This is an area we are hoping to improve.
## Securing your Zulip server
Zulip's security model is discussed in
[a separate document](../production/security-model.html).
[a separate document](../production/security-model.md).
## Management commands
@ -736,7 +736,7 @@ system-internal bots like `welcome-bot`; you are unlikely to need to
interact with that realm.)
Unless you are
[hosting multiple organizations on your Zulip server](../production/multiple-organizations.html),
[hosting multiple organizations on your Zulip server](../production/multiple-organizations.md),
your single Zulip organization on the root domain will have the empty
string (`''`) as its `string_id`. So you can run e.g.:
```
@ -810,4 +810,4 @@ There are a large number of useful management commands under
## Hosting multiple Zulip organizations
This is explained in detail on [its own page](../production/multiple-organizations.html).
This is explained in detail on [its own page](../production/multiple-organizations.md).

10
docs/production/modifying-zulip.md
View File

@ -9,7 +9,7 @@ modified version of Zulip, please be responsible about communicating
that fact:
* Ideally, you'd reproduce the issue in an unmodified version (e.g. on
[chat.zulip.org](../contributing/chat-zulip-org.html) or
[chat.zulip.org](../contributing/chat-zulip-org.md) or
[zulipchat.com](https://zulipchat.com)).
* Where that is difficult or you think it's very unlikely your changes
are related to the issue, just mention your changes in the issue report.
@ -35,7 +35,7 @@ Instead, we recommend the following GitHub-based workflow (see [our
Git guide][git-guide] if you need a primer):
* Decide where you're going to edit Zulip's code. We recommend [using
the Zulip development environment](../development/overview.html) on
the Zulip development environment](../development/overview.md) on
a desktop or laptop as it will make it extremely convenient for you
to test your changes without deploying them in production. But if
your changes are small or you're OK with risking downtime, you don't
@ -192,7 +192,7 @@ make sure you understand:
for your Zulip server is unacceptable, make sure you have a current
backup in case the upgrade fails.
* Our changelog contains [draft release
notes](../overview/changelog.html) available listing major changes
notes](../overview/changelog.md) available listing major changes
since the last release. The **Upgrade notes** section will always
be current, even if some new features aren't documented.
@ -201,10 +201,10 @@ make sure you understand:
Zulip contains thousands of changes submitted by volunteer
contributors like you. If your changes are likely to be of useful to
other organizations, consider [contributing
them](../overview/contributing.html).
them](../overview/contributing.md).
[fork-clone]: ../git/cloning.html#get-zulip-code
[upgrade-zulip-from-git]: ../production/maintain-secure-upgrade.html#upgrading-from-a-git-repository
[upgrade-zulip]: ../production/maintain-secure-upgrade.html#upgrading
[git-guide]: ../git/index.html
[git-guide]: ../git/index.md
[zulip/zulip]: https://github.com/zulip/zulip/

6
docs/production/multiple-organizations.md
View File

@ -11,7 +11,7 @@ single server.
Throughout this article, we'll assume you're working on a zulip server
with hostname `zulip.example.com`. You may also find the more
[technically focused article on realms](../subsystems/realms.html) to be useful
[technically focused article on realms](../subsystems/realms.md) to be useful
reading.
## Subdomains
@ -33,13 +33,13 @@ things:
file. That setting is the default in 1.7 and later.
* Make sure you have SSL certificates for all of the subdomains you're
going to use. If you're using
[our LetsEncrypt instructions](ssl-certificates.html), it's easy to
[our LetsEncrypt instructions](ssl-certificates.md), it's easy to
just specify multiple subdomains in your certificate request.
* If necessary, modify your `nginx` configuration to use your new
certificates.
* Use `./manage.py generate_realm_creation_link` again to create your
new organization. Review
[the install instructions](install.html) if you need a
[the install instructions](install.md) if you need a
refresher on how this works.
* If you're planning on using GitHub auth or another social
authentication method, review

8
docs/production/requirements.md
View File

@ -25,7 +25,7 @@ strongly recommend using either a fresh machine instance in a cloud
provider, a fresh VM, or a dedicated machine. If you decide to
disregard our advice and use a server that hosts other services, we
can't support you, but
[we do have some notes on issues you'll encounter](install-existing-server.html).
[we do have some notes on issues you'll encounter](install-existing-server.md).
#### Operating System
@ -71,7 +71,7 @@ https://help.ubuntu.com/community/Repositories/Ubuntu
messages sent. We recommend using an SSD and avoiding cloud storage
backends that limit the IOPS per second, since the disk is primarily
used for the database (assuming you're using the
[S3 file uploads backend](../production/upload-backends.html)).
[S3 file uploads backend](../production/upload-backends.md)).
#### Network and Security Specifications
@ -114,7 +114,7 @@ available: [the `--self-signed-cert` option][doc-self-signed] in the
installer.
If you'd rather acquire an SSL certificate another way, see our [SSL
certificate documentation](ssl-certificates.html).
certificate documentation](ssl-certificates.md).
[doc-certbot]: ssl-certificates.html#certbot-recommended
[doc-self-signed]: ssl-certificates.html#self-signed-certificate
@ -129,6 +129,6 @@ certificate documentation](ssl-certificates.html).
[free outgoing SMTP options and options for prototyping](email.html#free-outgoing-email-services).
Once you have met these requirements, see [full instructions for installing
Zulip in production](../production/install.html).
Zulip in production](../production/install.md).
[trusty-eol]: https://wiki.ubuntu.com/Releases

6
docs/production/security-model.md
View File

@ -4,7 +4,7 @@ This section attempts to document the Zulip security model.
It likely does not cover every issue; if
there are details you're curious about, please feel free to ask
questions in [#production help](https://chat.zulip.org/#narrow/stream/31-production-help)
on the [Zulip community server](../contributing/chat-zulip-org.html)
on the [Zulip community server](../contributing/chat-zulip-org.md)
(or if you think
you've found a security bug, please report it to
zulip-security@googlegroups.com so we can do a responsible security
@ -39,7 +39,7 @@ announcement).
* The preferred way to login to Zulip is using an SSO solution like
Google Auth, LDAP, or similar, but Zulip also supports password
authentication. See
[the authentication methods documentation](../production/authentication-methods.html)
[the authentication methods documentation](../production/authentication-methods.md)
for details on Zulip's available authentication methods.
### Passwords
@ -65,7 +65,7 @@ strength allowed is controlled by two settings in
By default, `PASSWORD_MIN_GUESSES` is 10000. This provides
significant protection against online attacks, while limiting the
burden imposed on users choosing a password. See
[password strength](../production/password-strength.html) for an extended
[password strength](../production/password-strength.md) for an extended
discussion on how we chose this value.
Estimating the guessability of a password is a complex problem and

10
docs/production/settings.md
View File

@ -46,7 +46,7 @@ If you want an additional or different authentication backend, you
will need to uncomment one or more and then do any additional
configuration required for that backend as documented in the
`settings.py` file. See the
[section on Authentication](../production/authentication-methods.html) for more
[section on Authentication](../production/authentication-methods.md) for more
detail on the available authentication backends and how to configure
them.
@ -63,7 +63,7 @@ their push notification protocols, the Zulip mobile apps for
[Android](https://play.google.com/store/apps/details?id=com.zulipmobile)
can only receive push notifications from a single Zulip server. We
have configured that server to be `push.zulipchat.com`, and offer a
[push notification forwarding service](mobile-push-notifications.html) that
[push notification forwarding service](mobile-push-notifications.md) that
forwards push notifications through our servers to mobile devices.
Read the linked documentation for instructions on how to register for
and configure this service.
@ -92,7 +92,7 @@ been added in more recent versions of Zulip.
Since Zulip's settings file is a Python script, there are a number of
other things that one can configure that are not documented; ask on
[chat.zulip.org](../contributing/chat-zulip-org.html)
[chat.zulip.org](../contributing/chat-zulip-org.md)
if there's something you'd like to do but can't figure out how to.
[settings-py-template]: https://github.com/zulip/zulip/blob/master/zproject/prod_settings_template.py
@ -100,7 +100,7 @@ if there's something you'd like to do but can't figure out how to.
Some popular settings in `/etc/zulip/settings.py` include:
* The Twitter integration, which provides pretty inline previews of
tweets.
* The [email gateway](../production/email-gateway.html), which lets
* The [email gateway](../production/email-gateway.md), which lets
users send emails into Zulip.
## Zulip announcement list
@ -119,4 +119,4 @@ Zulip documentation cover everything anyone might want to know about
running Zulip in production.
Next: [Maintaining and upgrading Zulip in
production](../production/maintain-secure-upgrade.html).
production](../production/maintain-secure-upgrade.md).

2
docs/production/troubleshooting.md
View File

@ -6,7 +6,7 @@ supervisorctl](#using-supervisorctl), to learn how to use the
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.html), particularly the
overview](../overview/architecture-overview.md), particularly the
[Components](../overview/architecture-overview.html#components) section. This will help you
understand the many services Zulip uses.

2
docs/production/upload-backends.md
View File

@ -140,7 +140,7 @@ need a block like this:
```
The file-uploads bucket should not be world-readable. See the
[documentation on the Zulip security model](security-model.html) for
[documentation on the Zulip security model](security-model.md) for
details on the security model for uploaded files.
## Migrating from local uploads to Amazon S3 backend

4
docs/subsystems/auth.md
View File

@ -6,7 +6,7 @@ environment.
## Testing OAuth in development
Among the many [authentication methods](../production/authentication-methods.html)
Among the many [authentication methods](../production/authentication-methods.md)
we support, a server can be configured to allow users to sign in with
their Google accounts or GitHub accounts, using the OAuth protocol.
@ -61,7 +61,7 @@ Here are the full procedures for dev:
Some OAuth providers (such as Facebook) require HTTPS on the callback
URL they post back to, which isn't supported directly by the Zulip
development environment. If you run a
[remote Zulip development server](../development/remote.html), we have
[remote Zulip development server](../development/remote.md), we have
instructions for
[an nginx reverse proxy with SSL](../development/remote.html#using-an-nginx-reverse-proxy)
that you can use for your development efforts.

2
docs/subsystems/caching.md
View File

@ -247,7 +247,7 @@ avatars, similar details for streams, recent message history, etc.
These days are fetched in the `/register` endpoint (or `page_params`
for the webapp), and kept correct over time. The key to keeping these
state up to date is Zulip's
[real-time events system](../subsystems/events-system.html), which
[real-time events system](../subsystems/events-system.md), which
allows the server to notify clients whenever state that might be
cached by clients is changed. Clients are responsible for handling
the events, updating their state, and rerendering any UI components

2
docs/subsystems/client.md
View File

@ -14,7 +14,7 @@ of Zulip; it's primarily intended to assist debugging.
A `Client` is used to sort messages into client categories such as
`ZulipElectron` on the `/stats`
[page](https://chat.zulip.org/stats). For more information see,
[Analytics](analytics.html).
[Analytics](analytics.md).
## Integrations

18
docs/subsystems/dependencies.md
View File

@ -92,12 +92,12 @@ the backend, but does in JavaScript.
For the third-party services like Postgres, Redis, Nginx, and RabbitMQ
that are documented in the
[architecture overview](../overview/architecture-overview.html), we rely on the
[architecture overview](../overview/architecture-overview.md), we rely on the
versions of those packages provided alongside the Linux distribution
on which Zulip is deployed. Because Zulip
[only supports Ubuntu in production](../production/requirements.html), this
[only supports Ubuntu in production](../production/requirements.md), this
usually means `apt`, though we do support
[other platforms in development](../development/setup-advanced.html). Since
[other platforms in development](../development/setup-advanced.md). Since
we don't control the versions of these dependencies, we avoid relying
on specific versions of these packages wherever possible.
@ -114,7 +114,7 @@ few places:
between development and production.
We also rely on the `pgroonga` PPA for the `pgroonga` postgres
extension, used by our [full-text search](full-text-search.html).
extension, used by our [full-text search](full-text-search.md).
## Python packages
@ -224,7 +224,7 @@ super fast internet. You can use tmux or screen to make sure that the
[script keeps running even if you get disconnected][stack-overflow]
from the SSH session.
[mypy-docs]: ../testing/mypy.html
[mypy-docs]: ../testing/mypy.md
[requirements-readme]: https://github.com/zulip/zulip/blob/master/requirements/README.md#requirements
[stack-overflow]: https://askubuntu.com/questions/8653/how-to-keep-processes-running-after-ending-ssh-session
[caching]: https://help.github.com/en/articles/caching-your-github-password-in-git
@ -248,7 +248,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](../subsystems/front-end-build-process.html) article,
the [static asset pipeline](../subsystems/front-end-build-process.md) 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
@ -292,7 +292,7 @@ Zulip uses the [iamcal emoji data package][iamcal] for its emoji data
and sprite sheets. We download this dependency using `npm`, and then
have a tool, `tools/setup/build_emoji`, which reformats the emoji data
into the files under `static/generated/emoji`. Those files are in
turn used by our [markdown processor](../subsystems/markdown.html) and
turn used by our [markdown processor](../subsystems/markdown.md) and
`tools/update-prod-static` to make Zulip's emoji work in the various
environments where they need to be displayed.
@ -303,11 +303,11 @@ directories, with `scripts/lib/clean_emoji_cache.py` responsible for
garbage-collection. This caching and garbage-collection is required
because a correct emoji implementation involves over 1000 small image
files and a few large ones. There is a more extended article on our
[emoji infrastructure](emoji.html).
[emoji infrastructure](emoji.md).
### Translations data
Zulip's [translations infrastructure](../translating/translating.html) generates
Zulip's [translations infrastructure](../translating/translating.md) generates
several files from the source data, which we manage similar to our
emoji, but without the caching (and thus without the
garbage-collection). New translations data is downloaded from

6
docs/subsystems/email.md
View File

@ -2,7 +2,7 @@
This page has developer documentation on the Zulip email system. If you're
trying to configure your server to send email, you might be looking for our
guide to [sending outgoing email](../production/email.html). If you're trying to
guide to [sending outgoing email](../production/email.md). If you're trying to
configure an email integration to receive incoming email (e.g. so that users
can reply to missed message emails via email), you might be interested in
our instructions for
@ -43,7 +43,7 @@ Email takes about a quarter second per email to process and send. Generally
speaking, if you're sending just one email, doing it in the current process
is fine. If you're sending emails in a loop, you probably want to send it
from a queue. Documentation on our queueing system is available
[here](../subsystems/queuing.html).
[here](../subsystems/queuing.md).
## Development and testing
@ -117,7 +117,7 @@ behavior, or other developers will get test failures until they
provision.
While this model is great for the markup side, it isn't ideal for
[translations](../translating/translating.html). The Django
[translations](../translating/translating.md). The Django
translation system works with exact strings, and having different new
markup can require translators to re-translate strings, which can
result in problems like needing 2 copies of each string (one for

4
docs/subsystems/emoji.md
View File

@ -61,7 +61,7 @@ The `build_emoji` tool generates the set of files under
`static/generated/emoji` is a symlink to that tree; we do this in
order to cache old versions to make provisioning and production
deployments super fast in the common case that we haven't changed the
emoji tooling). See [our dependencies document](../subsystems/dependencies.html)
emoji tooling). See [our dependencies document](../subsystems/dependencies.md)
for more details on this strategy.
The emoji tree generated by this process contains several import elements:
@ -76,7 +76,7 @@ The emoji tree generated by this process contains several import elements:
* `images/emoji/*.png`: A farm of symlinks from emoji names to the
`images/emoji/unicode/` tree. This is used to serve individual emoji
images, as well as for the
[backend markdown processor](../subsystems/markdown.html) to know which emoji
[backend markdown processor](../subsystems/markdown.md) to know which emoji
names exist and what unicode emoji / images they map to. In this
tree, we currently include all of the emoji in `emoji-map.json`;
this means that if you send `:angry_face:`, it won't autocomplete,

6
docs/subsystems/events-system.md
View File

@ -4,7 +4,7 @@ Zulip's "events system" is the server-to-client push system that
powers our real-time sync. This document explains how it works; to
read an example of how a complete feature using this system works,
check out the
[new application feature tutorial](../tutorials/new-feature-tutorial.html).
[new application feature tutorial](../tutorials/new-feature-tutorial.md).
Any single-page web application like Zulip needs a story for how
changes made by one client are synced to other clients, though having
@ -86,7 +86,7 @@ wide range of possible clients, and make it easy for developers.
Zulip's event delivery (real-time push) system is based on Tornado,
which is ideal for handling a large number of open requests. Details
on Tornado are available in the
[architecture overview](../overview/architecture-overview.html), but in short it
[architecture overview](../overview/architecture-overview.md), but in short it
is good at holding open a large number of connections for a long time.
The complete system is about 1500 lines of code in `zerver/tornado/`,
primarily `zerver/tornado/event_queue.py`.
@ -262,4 +262,4 @@ correctly, clients are responsible for discarding events related to
messages that the client has not yet fetched.
Additionally, see
[the master documentation on sending messages](../subsystems/sending-messages.html)
[the master documentation on sending messages](../subsystems/sending-messages.md)

4
docs/subsystems/front-end-build-process.md
View File

@ -3,9 +3,9 @@
This page documents additional information that may be useful when
developing new features for Zulip that require front-end changes,
especially those that involve adding new files. For a more general
overview, see the [new feature tutorial](../tutorials/new-feature-tutorial.html).
overview, see the [new feature tutorial](../tutorials/new-feature-tutorial.md).
Our [dependencies documentation](../subsystems/dependencies.html) has useful
Our [dependencies documentation](../subsystems/dependencies.md) has useful
relevant background as well.
## Primary build process

4
docs/subsystems/hashchange-system.md
View File

@ -118,6 +118,6 @@ browser, Zulip also does a few bookkeeping things on page reload (like
cleaning up its event queue, and saving any text in an open compose
box as a draft).
[testing-with-casper]: ../testing/testing-with-casper.html
[testing-with-casper]: ../testing/testing-with-casper.md
[self-server-reloads]: #server-initiated-reloads
[events-system]: ../subsystems/events-system.html
[events-system]: ../subsystems/events-system.md

2
docs/subsystems/html-templates.md
View File

@ -82,4 +82,4 @@ developers) should be tagged for [translation][].
[helpers]: http://handlebarsjs.com/block_helpers.html
[jconditionals]: http://jinja.pocoo.org/docs/2.9/templates/#list-of-control-structures
[hconditionals]: http://handlebarsjs.com/block_helpers.html
[translation]: ../translating/translating.html
[translation]: ../translating/translating.md

2
docs/subsystems/html_css.md
View File

@ -8,7 +8,7 @@ main third-party CSS library.
Zulip currently does not use any CSS preprocessors, and is organized
into several files. For most pages, the CSS is combined into a single
CSS file by the [static asset pipeline](../subsystems/front-end-build-process.html).
CSS file by the [static asset pipeline](../subsystems/front-end-build-process.md).
The CSS files are:

2
docs/subsystems/logging.md
View File

@ -167,7 +167,7 @@ and report to the server the following whenever a message is sent:
* Whether the message was locally echoed.
* If so, whether there was a disparity between the echoed content and
the server-rendered content, which can be used for statistics on how
effective our [local echo system](../subsystems/markdown.html) is.
effective our [local echo system](../subsystems/markdown.md) is.
The code is all in `zerver/lib/report.py` and `static/js/sent_messages.js`.

2
docs/subsystems/pointer.md
View File

@ -80,7 +80,7 @@ browser), Zulip will preserve the state -- what (if any) narrow the
user was in, the selected message, and even exact scroll position!
For more on the user experience philosophy guiding these decisions,
see [the architectural overview](../overview/architecture-overview.html).
see [the architectural overview](../overview/architecture-overview.md).
## Unread count logic

4
docs/subsystems/realms.md
View File

@ -6,7 +6,7 @@ user documentation as an organization (the name "realm" comes from
[Kerberos](https://web.mit.edu/kerberos/)).
The
[production docs on multiple realms](../production/multiple-organizations.html)
[production docs on multiple realms](../production/multiple-organizations.md)
are likely also relevant reading.
## Creating Realms
@ -52,7 +52,7 @@ job.
We also recommend upgrading to at least Zulip 1.7, since older Zulip
releases had much less nice handling for subdomains. See our
[docs on using subdomains](../production/multiple-organizations.html) for
[docs on using subdomains](../production/multiple-organizations.md) for
user-facing documentation on this.
### Working With Subdomains In Development Environment

4
docs/subsystems/schema-migrations.md
View File

@ -3,7 +3,7 @@
Zulip uses the [standard Django system for doing schema
migrations](https://docs.djangoproject.com/en/1.10/topics/migrations/).
There is some example usage in the [new feature
tutorial](../tutorials/new-feature-tutorial.html).
tutorial](../tutorials/new-feature-tutorial.md).
This page documents some important issues related to writing schema
migrations.
@ -30,7 +30,7 @@ migrations.
fix this, you can either run `./tools/renumber-migrations` which
renumbers your migration(s) and fixes up the "dependencies" entries in your
migration(s), and then rewrite your git history as needed, or you can do it
manually. There is a tutorial [here](migration-renumbering.html) that
manually. There is a tutorial [here](migration-renumbering.md) that
walks you though that process.
* **Atomicity**. By default, each Django migration is run atomically

22
docs/subsystems/sending-messages.md
View File

@ -7,9 +7,9 @@ experience.
This document aims to explain conceptually what happens when a message
is sent in Zulip, and why that is correct behavior. It assumes the
reader is familiar with our
[real-time sync system](../subsystems/events-system.html) for
[real-time sync system](../subsystems/events-system.md) for
server-to-client communication and
[new application feature tutorial](../tutorials/new-feature-tutorial.html),
[new application feature tutorial](../tutorials/new-feature-tutorial.md),
and we generally don't repeat the content discussed there.
## Message lists
@ -45,7 +45,7 @@ stream, etc.).
The backend flow for sending messages is similar in many ways to the
process described in our
[new application feature tutorial](../tutorials/new-feature-tutorial.html).
[new application feature tutorial](../tutorials/new-feature-tutorial.md).
This section details the ways in which it is different:
* There is significant custom code inside the `process_message_event`
@ -57,7 +57,7 @@ number of purposes:
computational work inside the Tornado codebase, this logic aims
to just do the check for whether a notification should be
generated, and then put an event into an appropriate
[queue](../subsystems/queuing.html) to actually send the
[queue](../subsystems/queuing.md) to actually send the
message. See `maybe_enqueue_notifications` and related code for
this part of the logic.
* Splicing user-dependent data (E.g. `flags` such as when the user
@ -73,7 +73,7 @@ number of purposes:
* Following our standard naming convention, input validation is done
inside the `check_message` function, which is responsible for
validating the user can send to the recipient,
[rendering the markdown](../subsystems/markdown.html), etc. --
[rendering the markdown](../subsystems/markdown.md), etc. --
basically everything that can fail due to bad user input.
* The core `do_send_messages` function (which handles actually sending
the message) is one of the most optimized and thus complex parts of
@ -89,7 +89,7 @@ number of purposes:
open organizations.
* Do all the database queries to fetch relevant data for and then
send a `message` event to the
[events system](../subsystems/events-system.html) containing the
[events system](../subsystems/events-system.md) containing the
data it will need for the calculations described above. This
step adds a lot of complexity, because the events system cannot
make queries to the database directly.
@ -114,7 +114,7 @@ library (on the frontend) and `sockjs-tornado` (on the backend). This
ends up calling a handler in our Tornado codebase
(`zerver/tornado/socket.py`), which immediately puts the request into
the `message_sender` queue.
* The `message_sender` [queue processor](../subsystems/queuing.html)
* The `message_sender` [queue processor](../subsystems/queuing.md)
reformats the request into a Django `HttpRequest` object with a fake
`SOCKET` HTTP method (which is why these requests appear as `SOCKET`
in our server logs), calls the Django `get_response` method on that
@ -141,7 +141,7 @@ browser, and then replace it with data from the server when it
changes.
Zulip aims for a near-perfect local echo experience, which requires is
why our [markdown system](../subsystems/markdown.html) requires both
why our [markdown system](../subsystems/markdown.md) requires both
an authoritative (backend) markdown implementation and a secondary
(frontend) markdown implementation, the latter used only for the local
echo feature. Read our markdown documentation for all the tricky
@ -177,7 +177,7 @@ messages.
unique value within that namespace identifying the message.
* The `do_send_messages` backend code path includes the `queue_id` and
`local_id` in the data it passes to the
[events system](../subsystems/events-system.html). The events
[events system](../subsystems/events-system.md). The events
system will extend the `message` event dictionary it delivers to
the client containing the `queue_id` with `local_message_id` field,
containing the `local_id` that the relevant client used when sending
@ -273,7 +273,7 @@ users.
message without including the URL embeds/previews, but it will add a
deferred work item into the `embed_links` queue.
* The [queue processor](../subsystems/queuing.html) for the
* The [queue processor](../subsystems/queuing.md) for the
`embed_links` queue will fetch the URLs, and then if they return
results, rerun the markdown processor and notify clients of the
updated message `rendered_content`.
@ -321,7 +321,7 @@ latency was unacceptable: The server backend was introducing a latency
of about 1 second per 2000 users subscribed to receive the message.
While these delays may not be immediately obvious to users (Zulip,
like many other chat applications,
[local echoes](../subsystems/markdown.html) messages that a user sends
[local echoes](../subsystems/markdown.md) messages that a user sends
as soon as the user hits “send”), latency beyond a second or two
significantly impacts the feeling of interactivity in a chat
experience (i.e. it feels like everyone takes a long time to reply to

2
docs/subsystems/settings.md
View File

@ -143,4 +143,4 @@ replaced with realm settings:
server, and in the realm settings indicating which methods the realm
administrator wants to allow users to login with.
[doc-newfeat]: ../tutorials/new-feature-tutorial.html
[doc-newfeat]: ../tutorials/new-feature-tutorial.md

2
docs/subsystems/thumbnailing.md
View File

@ -69,7 +69,7 @@ The raw Thumbor URLs are ugly, and regardless, have the property that
we might want to change them over time (a classic case is if one moves
the thumbor installation to be hosted by a different server). In
order to avoid encoding these into Zulip messages, we encode in the
[HTML rendered message content](../subsystems/markdown.html) URLs of
[HTML rendered message content](../subsystems/markdown.md) URLs of
the form
`/thumbnail/?url=https://example.com/image.png&size=thumbnail` as the
`src` in our image tags, and that URL serves a

2
docs/subsystems/typing-indicators.md
View File

@ -69,7 +69,7 @@ how long they pause to think, and how frequently they get interrupted.
The server piece of typing notificiations is currently pretty
straightforward, since we take advantage of Zulip's
[events system](../subsystems/events-system.html).
[events system](../subsystems/events-system.md).
We deliberately designed the server piece to be stateless,
which minimizes the possibility of backend bugs and gives clients

12
docs/testing/linters.md
View File

@ -11,7 +11,7 @@ but for other files, we are quite thorough about checking semantic
correctness.
Obviously, a large reason for linting code is to enforce the [Zulip
coding standards](../contributing/code-style.html). But we also use the linters to
coding standards](../contributing/code-style.md). But we also use the linters to
prevent common coding errors.
We borrow some open source tools for much of our linting, and the links
@ -67,7 +67,7 @@ later in this document.
## General considerations
Once you have read the [Zulip coding guidelines](../contributing/code-style.html), you can
Once you have read the [Zulip coding guidelines](../contributing/code-style.md), you can
be pretty confident that 99% of the code that you write will pass through
the linters fine, as long as you are thorough about keeping your code clean.
And, of course, for minor oversights, `lint` is your friend, not your foe.
@ -79,7 +79,7 @@ extreme cases, but often it can be a simple matter of writing your code
in a slightly different style to appease the linter. If you have
problems getting something to lint, you can submit an unfinished PR
and ask the reviewer to help you work through the lint problem, or you
can find other people in the [Zulip Community](../contributing/chat-zulip-org.html)
can find other people in the [Zulip Community](../contributing/chat-zulip-org.md)
to help you.
Also, bear in mind that 100% of the lint code is open source, so if you
@ -87,7 +87,7 @@ find limitations in either the Zulip home-grown stuff or our third party
tools, feedback will be highly appreciated.
Finally, one way to clean up your code is to thoroughly exercise it
with tests. The [Zulip test documentation](../testing/testing.html)
with tests. The [Zulip test documentation](../testing/testing.md)
describes our test system in detail.
## Lint checks
@ -104,10 +104,10 @@ following checks:
- Check CSS for parsability and formatting.
- Check JavaScript code for addClass calls.
- Running `mypy` to check static types in Python code. Our
[documentation on using mypy](../testing/mypy.html) covers mypy in
[documentation on using mypy](../testing/mypy.md) covers mypy in
more detail.
- Running `tsc` to compile TypeScript code. Our [documentation on
TypeScript](typescript.html) covers TypeScript in more detail.
TypeScript](typescript.md) covers TypeScript in more detail.
The rest of this document pertains to the checks that occur in `./tools/lint`.

4
docs/testing/testing-with-node.md
View File

@ -2,7 +2,7 @@
Our node-based unit tests system is the preferred way to test
JavaScript/TypeScript code in Zulip. We prefer it over the [Casper
black-box whole-app testing](../testing/testing-with-casper.html),
black-box whole-app testing](../testing/testing-with-casper.md),
system since it is much (>100x) faster and also easier to do correctly
than the Casper system.
@ -41,7 +41,7 @@ and add your own tests.
## How the node tests work
Unlike the [casper unit tests](../testing/testing-with-casper.html),
Unlike the [casper unit tests](../testing/testing-with-casper.md),
which use the `phantomjs` browser connected to a running Zulip
deveopment server, our node unit tests don't have a browser, don't
talk to a server, and generally don't use a complete virtual DOM (a

18
docs/testing/testing.md
View File

@ -5,18 +5,18 @@
Zulip has a full test suite that includes many components. The most
important components are documented in depth in their own sections:
- [Django](../testing/testing-with-django.html): backend Python tests
- [Casper](../testing/testing-with-casper.html): end-to-end UI tests
- [Node](../testing/testing-with-node.html): unit tests for JS front end code
- [Linters](../testing/linters.html): Our parallel linter suite
- [CI details](continuous-integration.html): How all of these run in CI
- [Django](../testing/testing-with-django.md): backend Python tests
- [Casper](../testing/testing-with-casper.md): end-to-end UI tests
- [Node](../testing/testing-with-node.md): unit tests for JS front end code
- [Linters](../testing/linters.md): Our parallel linter suite
- [CI details](continuous-integration.md): How all of these run in CI
- [Other test suites](#other-test-suites): Our various smaller test suites.
This document covers more general testing issues, such as how to run the
entire test suite, how to troubleshoot database issues, how to manually
test the front end, etc.
We also document [how to manually test the app](manual-testing.html).
We also document [how to manually test the app](manual-testing.md).
## Running tests
@ -60,7 +60,7 @@ Zulip also has about a dozen smaller tests suites:
- `tools/test-migrations`: Checks whether the `zerver/migrations`
migration content the models defined in `zerver/models.py`. See our
[schema migration documentation](../subsystems/schema-migrations.html)
[schema migration documentation](../subsystems/schema-migrations.md)
for details on how to do database migrations correctly.
- `tools/test-documentation`: Checks for broken links in this
ReadTheDocs documentation site.
@ -72,7 +72,7 @@ Zulip also has about a dozen smaller tests suites:
- `test-locked-requirements`: Verifies that developers didn't forget
to run `tools/update-locked-requirements` after modifying
`requirements/*.in`. See
[our dependency documentation](../subsystems/dependencies.html) for
[our dependency documentation](../subsystems/dependencies.md) for
details on the system this is verifying.
- `tools/check-capitalization`: Checks whether translated strings (aka
user-facing strings) correctly follow Zulip's capitalization
@ -223,7 +223,7 @@ it. On Ubuntu:
This section is about troubleshooting your local development environment.
There is a [separate manual testing doc](manual-testing.html) that
There is a [separate manual testing doc](manual-testing.md) that
enumerates things you can test as part of manual QA.
### Clearing the development database

4
docs/testing/typescript.md
View File

@ -4,7 +4,7 @@ Zulip is early in the process of migrating our codebase to use
[TypeScript](https://www.typescriptlang.org/), the leading static type
system for JavaScript. It works as an extension of the ES6 JavaScript
standard, and provides similar benefits to our use of
[the mypy static type system for Python](../testing/mypy.html).
[the mypy static type system for Python](../testing/mypy.md).
We expect to eventually migrate the entire JavaScript codebase to
TypeScript, though our current focus is on getting the tooling and
@ -33,7 +33,7 @@ The following resources are valuable for learning TypeScript:
## Type checking
TypeScript types are checked by the TypeScript compiler, `tsc`, which
is run as part of our [lint checks](linters.html). You can run the
is run as part of our [lint checks](linters.md). You can run the
compiler yourself with `tools/run-tsc`, which will check all the
TypeScript files once, or `tools/run-tsc --watch`, which will
continually recheck the files as you edit them.

2
docs/translating/internationalization.md
View File

@ -305,4 +305,4 @@ organizations from the command line.
[resource]: https://www.i18next.com/add-or-load-translations.html
[Transifex]: https://transifex.com
[transifexrc]: https://docs.transifex.com/client/client-configuration#transifexrc
[html-templates]: ../subsystems/html-templates.html
[html-templates]: ../subsystems/html-templates.md

24
docs/translating/translating.md
View File

@ -11,7 +11,7 @@ greatly appreciated!
If you are interested in knowing about the technical end-to-end
tooling and processes for tagging strings for translation and syncing
translations in Zulip, read about [Internationalization for
Developers](../translating/internationalization.html).
Developers](../translating/internationalization.md).
## Translators' workflow
@ -24,7 +24,7 @@ Transifex](https://www.transifex.com/zulip/zulip/), requesting access
to any languages you'd like to contribute to (or add new ones).
1. Join [#translation][translation-stream] in the [Zulip development
community server](../contributing/chat-zulip-org.html), and say hello.
community server](../contributing/chat-zulip-org.md), and say hello.
That stream is also the right place for any questions, updates on your
progress, reporting problematic strings, etc.
@ -52,7 +52,7 @@ Some useful tips for your translating journey:
- When in doubt, ask for context in
[#translation](https://chat.zulip.org/#narrow/stream/58-translation) in
the [Zulip development community server](../contributing/chat-zulip-org.html).
the [Zulip development community server](../contributing/chat-zulip-org.md).
- If there are multiple possible translations for a term, search for it in
the *Concordance* tool (the button with a magnet in the top right corner).
@ -69,7 +69,7 @@ Some useful tips for your translating journey:
### Testing translations
This section assumes you have a
[Zulip development environment](../development/overview.html) set up;
[Zulip development environment](../development/overview.md) set up;
if setting one up is a problem for you, ask in chat.zulip.org and we
can usually just deploy the latest translations there.
@ -126,18 +126,18 @@ Zulip should be translated into specific languages (e.g. what word to
translate words like "stream" to), with reasoning, so that future
translators can understand and preserve those decisions:
* [Chinese](chinese.html)
* [French](french.html)
* [German](german.html)
* [Hindi](hindi.html)
* [Polish](polish.html)
* [Russian](russian.html)
* [Spanish](spanish.html)
* [Chinese](chinese.md)
* [French](french.md)
* [German](german.md)
* [Hindi](hindi.md)
* [Polish](polish.md)
* [Russian](russian.md)
* [Spanish](spanish.md)
Some translated languages don't have these, but we highly encourage
translators for new languages (or those updating a language) write a
style guide as they work (see [our docs on this
documentation](../documentation/overview.html) for how to submit
documentation](../documentation/overview.md) for how to submit
your changes), since it's easy to take notes as you translate, and
doing so greatly increases the ability of future translators to update
the translations in a consistent way.

4
docs/tutorials/life-of-a-request.md
View File

@ -58,7 +58,7 @@ There are various
[urls.py](https://docs.djangoproject.com/en/1.8/topics/http/urls/)
files throughout the server codebase, which are covered in more detail
in
[the directory structure doc](../overview/directory-structure.html).
[the directory structure doc](../overview/directory-structure.md).
The main Zulip Django app is `zerver`. The routes are found in
```
@ -188,7 +188,7 @@ find the correct view to show:
## The view will authorize the user, extract request variables, and validate them
This is covered in good detail in the [writing views doc](writing-views.html).
This is covered in good detail in the [writing views doc](writing-views.md).
## Results are given as JSON

26
docs/tutorials/new-feature-tutorial.md
View File

@ -8,22 +8,22 @@ data system in real-time to all browsers the user may have open.
As you read this, you may find you need to learn about Zulip's
real-time push system; the
[real-time push and events](../subsystems/events-system.html)
[real-time push and events](../subsystems/events-system.md)
documentation has a detailed explanation of how everything works. You
may also find it beneficial to read Zulip's
[architectural overview](../overview/architecture-overview.html).
[architectural overview](../overview/architecture-overview.md).
Zulip is a web application built using the
[Django framework](https://www.djangoproject.com/), and some of the
processes listed in this tutorial, such as database migrations and
tests, use Django's tooling.
Zulip's [directory structure](../overview/directory-structure.html)
Zulip's [directory structure](../overview/directory-structure.md)
will also be helpful to review when creating a new feature. Many
aspects of the structure will be familiar to Django developers. Visit
[Django's documentation](https://docs.djangoproject.com/en/1.11/#index-first-steps)
for more information about how Django projects are typically
organized. And finally, the
[message sending](../subsystems/sending-messages.html) documentation on
[message sending](../subsystems/sending-messages.md) documentation on
the additional complexity involved in sending messages.
## General Process
@ -74,7 +74,7 @@ following commands:
```
You can read our
[database migration documentation](../subsystems/schema-migrations.html)
[database migration documentation](../subsystems/schema-migrations.md)
to learn more about creating and applying database migrations.
**Test your changes:** Once you've run the migration, flush memcached
@ -130,7 +130,7 @@ precompiled as part of the build/deploy process.
Zulip is fully internationalized, so when writing both HTML templates
or JavaScript/TypeScript code that generates user-facing strings, be sure to
[tag those strings for translation](../translating/translating.html).
[tag those strings for translation](../translating/translating.md).
**Testing:** There are two types of frontend tests: node-based unit
tests and blackbox end-to-end tests. The blackbox tests are run in a
@ -138,14 +138,14 @@ headless browser using Casper.js and are located in
`frontend_tests/casper_tests/`. The unit tests use Node's `assert`
module are located in `frontend_tests/node_tests/`. For more
information on writing and running tests, see the
[testing documentation](../testing/testing.html).
[testing documentation](../testing/testing.md).
### Documentation changes
After implementing the new feature, you should
document it and update any existing documentation that might be
relevant to the new feature. For more information on the kinds of
documentation Zulip has, see [Documentation](../documentation/overview.html).
documentation Zulip has, see [Documentation](../documentation/overview.md).
## Example Feature
@ -266,7 +266,7 @@ initial state. Subsequently, clients subscribe to "events," which can
For the backend piece, we will need our action to make a call to `send_event`
to send the event to clients that are active. We will also need to
modify `fetch_initial_state_data` so that the new field is passed to
clients. See [our event system docs](../subsystems/events-system.html) for all the
clients. See [our event system docs](../subsystems/events-system.md) for all the
gory details.
Anyway, getting back to implementation details...
@ -475,7 +475,7 @@ controls the feature it is supposed to control, however (e.g. for this
example feature, whether sending a message without a topic fails with
the setting enabled).
Visit Zulip's [Django testing](../testing/testing-with-django.html)
Visit Zulip's [Django testing](../testing/testing-with-django.md)
documentation to learn more about the backend testing framework.
### Update the front end
@ -636,8 +636,8 @@ Here are few important cases you should consider when testing your changes:
### Front End Tests
A great next step is to write front end tests. There are two types of
frontend tests: [node-based unit tests](../testing/testing-with-node.html) and
[Casper end-to-end tests](../testing/testing-with-casper.html).
frontend tests: [node-based unit tests](../testing/testing-with-node.md) and
[Casper end-to-end tests](../testing/testing-with-casper.md).
At the minimum, if you created a new function to update UI in
`settings_org.js`, you will need to mock that function in
@ -667,4 +667,4 @@ At the very least, this will involve adding (or modifying) a Markdown file
documenting the feature to `templates/zerver/help/` in the main Zulip
server repository, where the source for Zulip's user documentation is
stored. For information on writing user documentation, see
[Zulip's general user guide documentation](../documentation/user.html).
[Zulip's general user guide documentation](../documentation/user.md).

2
docs/tutorials/reading-list.md
View File

@ -158,7 +158,7 @@ Some titles have been shortened for organizational purposes.
You may want to take a look first at our [Git and GitHub guide][].
[Git and GitHub guide]: ../git/index.html
[Git and GitHub guide]: ../git/index.md
## Computer Science/Algorithms

2
docs/tutorials/shell-tips.md
View File

@ -339,7 +339,7 @@ At first it seems like magic, but once you get the basic concepts you find it
extremely useful and even easy to use (at least the 99% of the time).
To learn more about how to use it, read
[our docs](../git/index.html) on Git and
[our docs](../git/index.md) on Git and
Github.
[This cheatsheet][git-cheat-detailed]

8
docs/tutorials/writing-views.md
View File

@ -3,15 +3,15 @@
## What this covers
This page documents how views work in Zulip. You may want to read the
[new feature tutorial](../tutorials/new-feature-tutorial.html)
[new feature tutorial](../tutorials/new-feature-tutorial.md)
and treat this as a reference.
If you have experience with Django, much of this will be familiar, but
you may want to read about how REST requests are dispatched, and how
request authentication works.
This document supplements the [new feature tutorial](../tutorials/new-feature-tutorial.html)
and the [testing](../testing/testing.html)
This document supplements the [new feature tutorial](../tutorials/new-feature-tutorial.md)
and the [testing](../testing/testing.md)
documentation.
## What is a view?
@ -366,4 +366,4 @@ def api_pagerduty_webhook(request, user_profile,
```
`request.client` will be the result of `get_client("ZulipPagerDutyWebhook")`
in this example and it will be passed to `check_send_stream_message`. For
more information, see [Clients in Zulip](../subsystems/client.html).
more information, see [Clients in Zulip](../subsystems/client.md).