remoteinclude is an extension for Sphinx that enables RST file inclusion from remote sources.


Including text from a remote source is a security risk, as the text is parsed after inclusion. Include files from trusted sources only.


  1. Install chios, then add remoteinclude to the list of extensions in

    extensions = ['chios.remoteinclude']
  2. Use the remote-include directive to fetch a remote RST file and include it:

    .. remote-include::


    The remote-include directive does not follow references to other remote files within a downloaded file. In other words, toctree, :ref:, and similar markup fails because the referenced files are not locally available.

Using a remote file in a toctree

The toctree directive does not allow include as a child. To use a remote file in a toctree:

  1. Create an RST file in your source directory with an appropriate name:

    $ touch doc/myfile.rst
  2. Use the remote-include directive in that file:

    .. remote-include::
  3. You can now reference the local file in a toctree:

    .. toctree::


If a remote-include is empty in the HTML output, it is likely that the given link could not be resolved. Check the Sphinx build messages for a warning:

index.rst:32: WARNING: Unable to resolve

Code listing

A Sphinx extension that enables RST includes from remote sources.

Copyright (C) 2021 Brian Moss

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <>.

class remoteinclude.RemoteInclude(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Create remote-include directive.


Return rel path to a downloaded file as include node argument.

remoteinclude.setup(app) dict[source]

Set up Sphinx extension.


app – Sphinx application context.