|
| 1 | +Deprecating Content on Read the Docs |
| 2 | +==================================== |
| 3 | + |
| 4 | +When you deprecate a feature from your project, |
| 5 | +you may want to deprecate its docs as well, |
| 6 | +and stop your users from reading that content. |
| 7 | + |
| 8 | +Deprecating content may sound as easy as delete it, |
| 9 | +but doing that will break existing links, |
| 10 | +and you don't necessary want to make the content inaccessible. |
| 11 | +Here you'll find some tips on how to use Read the Docs to deprecate your content |
| 12 | +progressively and in non harmful ways. |
| 13 | + |
| 14 | +Deprecating versions |
| 15 | +-------------------- |
| 16 | + |
| 17 | +If you have multiple versions of your project, |
| 18 | +it makes sense to have its :doc:`documentation versioned </versions>` as well. |
| 19 | +For example, if you have the following versions and want to deprecate V1. |
| 20 | + |
| 21 | +- project.readthedocs.io/en/v1/ |
| 22 | +- project.readthedocs.io/en/v2/ |
| 23 | +- project.readthedocs.io/en/v3/ |
| 24 | + |
| 25 | +For cases like this you can *hide* a version, |
| 26 | +hidden versions won't be listed in the versions menu of your docs, |
| 27 | +and they will be listed in a :ref:`robots.txt file <hosting:custom robots.txt pages>` |
| 28 | +to stop search engines of showing results for that version:: |
| 29 | + |
| 30 | + # project.readthedocs.io/robots.txt |
| 31 | + |
| 32 | + User-agent: * |
| 33 | + |
| 34 | + Disallow: /en/v1/ # Hidden version |
| 35 | + |
| 36 | +Users can still see all versions in the dashboard of your project. |
| 37 | +To hide a version go to your project and click on :guilabel:`Versions` > :guilabel:`Edit`, |
| 38 | +and mark the :guilabel:`Hidden` option. Check :ref:`versions:Version States` for more information. |
| 39 | + |
| 40 | +.. note:: |
| 41 | + |
| 42 | + If the versions of your project follow the semver_ convention, |
| 43 | + you can activate the :ref:`versions:version warning` option for your project. |
| 44 | + A banner with a warning and linking to the stable version |
| 45 | + will be shown on all versions that are lower than the stable one. |
| 46 | + |
| 47 | + .. _semver: https://semver.org/ |
| 48 | + |
| 49 | +Deprecating content |
| 50 | +------------------- |
| 51 | + |
| 52 | +You may not always want to deprecate a version, but deprecate some pages. |
| 53 | +For example, if you have documentation about two APIs and you want to deprecate V1: |
| 54 | + |
| 55 | +- project.readthedocs.io/en/latest/api/v1.html |
| 56 | +- project.readthedocs.io/en/latest/api/v2.html |
| 57 | + |
| 58 | +A simple way is just adding a warning at the top of the page, |
| 59 | +this will warn users visiting that page, |
| 60 | +but it won't stop users from being redirected to that page from search results. |
| 61 | +You can add an entry of that page in a :ref:`custom robots.txt <hosting:custom robots.txt pages>` file |
| 62 | +to avoid search engines of showing those results. For example:: |
| 63 | + |
| 64 | + # robots.txt |
| 65 | + |
| 66 | + User-agent: * |
| 67 | + |
| 68 | + Disallow: /en/latest/api/v1.html # Deprecated API |
| 69 | + |
| 70 | +But your users will still see search results from that page if they use the search from your docs. |
| 71 | +With Read the Docs you can set a :ref:`custom rank per pages <config-file/v2:search.ranking>`. |
| 72 | +For example: |
| 73 | + |
| 74 | +.. code-block:: yaml |
| 75 | +
|
| 76 | + # .readthedocs.yaml |
| 77 | +
|
| 78 | + version: 2 |
| 79 | + search: |
| 80 | + ranking: |
| 81 | + api/v1.html: -1 |
| 82 | +
|
| 83 | +This wont hide results from that page, but it will give priority to results from other pages. |
| 84 | + |
| 85 | +.. TODO: mention search.ignore when it's implemented. |
| 86 | +
|
| 87 | +Moving and deleting pages |
| 88 | +------------------------- |
| 89 | + |
| 90 | +After you have deprecated a feature for a while, |
| 91 | +you may want to get rid of its documentation, |
| 92 | +that's OK, you don't have to maintain that content forever. |
| 93 | +But be aware that users may have links of that page saved, |
| 94 | +and it will be frustrating and confusing for them to get a 404. |
| 95 | + |
| 96 | +To solve that problem you can create a redirect to a page with a similar feature/content, |
| 97 | +like redirecting to the docs of the V2 of your API when your users visit the deleted docs from V1, |
| 98 | +this is a :ref:`page redirect <user-defined-redirects:page redirects>` from ``/api/v1.html`` to ``/api/v2.html``. |
| 99 | +See :doc:`/user-defined-redirects`. |
0 commit comments