logo
  • Open edX Documentation

User Home Pages

  • Educators
  • Course Operators
  • Site Operators
    • Site Operators: Quick Start
    • Site Operators: How-tos
    • Site Operators: Concepts
    • Site Operators: References
  • Developers
  • Documentators
  • Translators
    • Get Started as a Translator
      • Quick Start: How to start translating for Open edX
    • How to join a review team
    • How to join a translation team
    • How to request a new language for translation
    • Working With HTML
    • Working With Placeholders
    • Translators: Reference

Quick Starts

  • Educators: Build a Course
  • Course Operators: Run a Course
  • Site Operators: Set up Open edX
  • Developers: Contribute to Open edX
    • Quick Start: First Open edX Pull Request
  • Documentors: First Documentation PR

Open Source Community

  • Current Release: Olive
  • All Release Notes
  • How to Contribute
  • OEPs (Open edX Proposals): Community Decision Documents

Educators: Build an Open edX Course

  • Quickstarts
  • How-tos
    • Create a Course
    • Add Course Creators
    • Schedule a Course
    • Create the Course About Page
    • Set Up Course Prerequisites
    • Set Up Certificates
    • Open the Course Outline
    • Create a Section
    • Create a Subsection
    • Add the Course Structure
    • Add Units to the Outline
    • Reorganize the Course Outline
    • Delete Content
    • Add Written Content
    • Add an Image
    • Manage Course Files
    • Prepare Videos
    • Set Up a Hosting Service
    • Create a Video
    • Get a Video Transcript
    • Add a Transcript in Another Language
    • Add a YouTube Video
    • Enable Video and Transcript Downloads
    • Add a Checkbox Problem
    • Add a Dropdown Problem
    • Add a Multiple Choice Problem
    • Add a Numerical Input Problem
    • Add a Text Input Problem
    • Add a Custom JavaScript Display and Grading Problem
    • Add a Write-Your-Own-Grader Problem
    • Add a Math Expression Input Problem
    • Add an Open Response Assessment
    • Create Course-Wide Discussion Topics
    • Create Content-Specific Discussion Topics
    • Allow Anonymous Discussion Posts
    • Set Release Dates
    • Publish Content
    • Hide Content from Learners
    • Set Up Content Groups
    • Set Access Restrictions on a Unit
    • Set Access Restrictions on a Component
    • Set the Grading Policy
    • Set a Subsection to be Graded
    • Add a Course Page
    • Reorder Course Pages
    • Hide a Course Page
    • Preview Draft Content
    • View Your Course
    • View Your Course as a Learner
    • Beta Test Your Course
  • Concepts
    • Instructional Design Concepts
      • Sample Concepts Doc
  • Reference
    • Complex Problem Types
    • Course Dates
    • Course Pacing
    • Course Sections
    • Course Subsections
    • Course Units
    • Simple Problem Types
    • User Roles
    • Instructional Design References
      • Sample Ref Doc

Course Operators: Run Open edX

  • Quickstarts
  • How-tos
  • Concepts
  • References

Site Operators: Set Up Open edX

  • Quickstarts
  • How-tos
  • Concepts
  • Reference

Software Developers: Enhance the Open edX Platform

  • Quickstarts
    • Quick Start: First Open edX Pull Request
  • How-tos
    • How To Add a Catalog File
    • How To Add Sphinx Docs to a Repo
    • How To Enable Python Upgrade Automation
    • How To Get Ready for Frontend Development
    • How To Maintain a Repository
    • How to Switch to the sphinx-book-theme for Documentation
  • Concepts
    • Backend Layout and Approach
    • Platform Overview
  • Reference
    • Running Pull Request Tests
    • Tools for Maintainers
    • Event Reference
      • Events in the Tracking Logs
        • Reviewing a Sample Event
        • Common Fields
        • Student Events
        • Course Team Events
      • xAPI Events
      • Caliper Events
      • Alphabetical Tracking Log Event List
    • Glossary

Documentors

  • Quickstarts
    • Quick Start: First Documentation PR
    • Quick Start: Add Documentation Through Github
    • Quick Start: Update Doc Through GitHub
  • How-tos
    • Add Documentation via Github
    • Update A Doc via GitHub
  • Concepts
    • Documentation Content Types
    • Documentation Audiences
  • References
    • Documentation Checklist
    • Getting Started
    • Add Links in a Topic
    • Documentation Templates
    • Sample Document with Errors
    • Quick Reference: Writing RST

Translators

  • Quickstarts
    • Quick Start: How to start translating for Open edX
  • How-tos
    • How to join a review team
    • How to join a translation team
    • How to request a new language for translation
  • Concepts
    • Translations Process
    • Working With HTML
    • Working With Placeholders
  • References

Other Topics

  • Documentation Feedback Form
  • Getting Help
  • Documentation Decisions
    • 1. Purpose of this Repo
    • 2. Choosing RST
    • 3. Documentation Layout


Open edX Wiki
Open edX website
Cookie Policy
  • repository
  • open issue
  • suggest edit
  • .rst
Contents
  • Links to Sections in the Same Document
    • Use Custom Link Text
    • Use a Custom Anchor
  • Links to External Web Pages
    • Test External Links

Add Links in a Topic

Contents

  • Links to Sections in the Same Document
    • Use Custom Link Text
    • Use a Custom Anchor
  • Links to External Web Pages
    • Test External Links

Add Links in a Topic#

You can include links to other locations in the same document, to locations in other documents and to external websites.

For more information about creating links using RST and Sphinx, see Sphinx Hyperlinks_.

Links to Sections in the Same Document#

You can link from text to a heading in any other part of the document by using the :ref: command with the target heading text as the parameter. For example, this text in another part of this document would link to this section:

:ref:`Cross-References to Locations in the Same Document`

The heading text is printed as the link text.

Note

The heading text in the link must match the heading exactly.

Use Custom Link Text#

For internal links that use text other than the heading for the section that you’re linking to, use :ref:`custom text<Heading Text>` syntax, as in the following example.

Learn how to :ref:`link to a different section<Cross-References to Locations in the Same Document>`.

Note

Do not include a space between the last word of the link text and the opening angle bracket for the anchor text.

In this example, link to a different section is the link text, and Cross-References to Locations in the Same Document is the heading text.

Use a Custom Anchor#

When you have two sections with the same title in a project, you will get build errors when you have a link to either section, because Sphinx does not know which section to link to.

In this case, you can create a custom anchor directly above the title and link to it, instead of the title itself. For example, if you have a section called Overview in each part of your document, you should add a more specific anchor above the section heading.

.. _RST Overview:

Overview
**********

RST Overview content


.. _Sphinx Overview:

Overview
*********

Sphinx Overview content

In a :ref: command, you then use the anchor text. For example:

This is a link to the RST Overview: :ref:`RST Overview`

This is a link to the Sphinx Overview: :ref:`Sphinx Overview`

In both cases, the link text is the section title, Overview, unless you Use Custom Link Text.

Links to External Web Pages#

To link to an external web page, use the following syntax:

`Link text <link URL>`_

For example:

`CNN <http://cnn.com>`_

You can also separate the link and the target definition. For example:

Get the latest news at `CNN`_.

.. _CNN: http://cnn.com/

As a best practice, to avoid duplication, in Open edX documentation, all links are listed together in the source/links.txt file, which is included in every page during the build process.

TO VERIFY

Test External Links#

You can use the built-in Sphinx command, checklinks to test all external links in your document. The command checks that a working web page is accessed at the given URL and reports any errors.

Add the following code to the project Makefile:

LINKCHECKDIR  = build/linkcheck

.PHONY: checklinks
  checklinks:
  $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(LINKCHECKDIR)
  @echo
  @echo "Check finished. Report is in $(LINKCHECKDIR)."

Then, from the command window, enter:

make checklinks

Sphinx compiles the document and tests all links. It shows the results in the command window, and writes results to the file output.txt in the build directory.


Feedback

previous

Getting Started

next

Documentation Templates

© Copyright 2023, The Center for Reimagining Learning.