Skip to content

Commit

Permalink
Read the Docs vs GitHub pages (#184)
Browse files Browse the repository at this point in the history 
* Rough draft of comparison page :)

* Initial comparison table

* Some small updates

* Second paragraph

* Callout

* Build docs with Material for MkDocs

* Minor copy

* More emphasis :)

* Add logos

* Minor changes

* Add the comparisons menu in the footer

* Small paragraph at the call to action section

---------

Co-authored-by: Eric Holscher <eric@ericholscher.com>
  • Loading branch information
@humitos @ericholscher
humitos and ericholscher authored Mar 20, 2023
1 parent d7a0431 commit 366b41c
Show file tree
Hide file tree
Showing 4 changed files with 343 additions and 0 deletions.
42 changes: 42 additions & 0 deletions content/images/github-logo.svg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
206 changes: 206 additions & 0 deletions content/pages/comparisons/github-pages.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,206 @@
{# View this page at http://localhost:8080/comparisons/github-pages/ #}

<html>
<head>
<title>Read the Docs vs. GitHub Pages comparison</title>
<meta name="template" content="page" />
<meta name="slug" content="comparisons/github-pages" />
<meta name="status" content="hidden" />
<meta name="description" content="" />
</head>
<body>

{% import "partials/basic.html" as basic %}
{% import "partials/technical.html" as technical %}
{% import "partials/homepage.html" as homepage %}
{% import "partials/comparisons.html" as comparison %}

{% block signup_modal %}
{{ homepage.signup_modal("signup_modal") }}
{% endblock signup_modal %}

<section>
{% call basic.header_lead(
header="Read the Docs is the <em><strong>all-in-one</strong></em> solution you're looking for your documentation")
%}
<p>
GitHub Pages is great. We used to use it and <em>we loved it</em>.
However, it's just a static hosting with no features at all.
When talking about documentation, <strong>Read the Docs</strong> is <em>the</em> perfect solution for it.
</p>
<p>
Let's compare it to know what you can expect when deploying your project's documentation to Read the Docs.
</p>
{% endcall %}
</section>


{#
The most important way to think about these two products is what value they provide to you as a user:

* GitHub Pages provides static file hosting, with no backend API or feature set
* Read the Docs is a full platform for documentation hosting, with versions and backend APIs

* **Documentation platform**: Read the Docs provides a full set of features for documentation hosting, instead of just static hosting
* **Open source**: Read the Docs source code is fully open source
* **Hosting Features**:
#}

{#
Compare plan features with a table

* Building: GitHub Actions
* Hosting: GitHub Pages

* Search | Algolia
* Versions | GitHub Actions customization
* PR Previews | GitHub Actions customization
* Page analytics | Google Analytics
* Redirects | Impossible
* Custom 404 pages | Impossible
* Translation | Impossible
* Private docs | Impossible

#}
<section id="compare">
<div class="ui padded container">

{% call comparison.feature_table() %}
{{ comparison.feature_row("Static hosting", "Publish any static content", "fa-page", on_github=True) }}
{{ comparison.feature_row("Build your site on the cloud", "Generate the site's content on the cloud", "fa-gears", on_github=True) }}
{{ comparison.feature_row("Deploy previews", "Solve style-issues before deploying", "fa-rocket-launch") }}
{{ comparison.feature_row("Search", "Always find what you are looking for", "fa-magnifying-glass") }}
{{ comparison.feature_row("Multiple versions", "Publish multiple versions of our documentation", "fa-books") }}
{{ comparison.feature_row("Redirects", "Redirect users to the right page", "fa-arrows-turn-right") }}
{{ comparison.feature_row("Custom 404 pages", "Style 404 pages with context-related information", "fa-xmark") }}
{{ comparison.feature_row("Custom \"robots.txt\"", "Improve your SEO by telling bots how to explore your site", "fa-robot") }}
{{ comparison.feature_row("Page analytics", "Understand how people browse your documentation", "fa-chart-mixed") }}
{{ comparison.feature_row("Search analytics", "Explore what people search for in your docs", "fa-chart-simple") }}
{{ comparison.feature_row("Translations", "Serve translated versions of your docs", "fa-language") }}
{{ comparison.feature_row("Private documention", "Give access only to trusted people", "fa-lock") }}
{{ comparison.feature_row("Open Source", "Maintained by the community", "fa-brands fa-osi") }}
{% endcall %}

</div>
</section>
<div class="ui container">
<div class="ui horizontal divider">Try it out</div>
</div>

<section id="try-it-out">
<div class="ui padded container">
<h2 class="ui huge center aligned header">
Deploy in 5 minutes and compare by yourself
</h2>

<div class="ui very padded centered grid">

<div class="ten wide computer sixteen wide tablet sixteen wide mobile column">
<div class="ui large left aligned basic vertical segment">

{# Stylized code blocks #}
{% call technical.code_block(title="<code>.readthedocs.yaml</code>", icon="fa-file") %}
{% markdown %}

```yaml
version: 2
build:
os: "ubuntu-22.04"
tools:
python: "3"
# You can also specify other tool versions:
# nodejs: "16"
commands:
- pip install mkdocs-material
- mkdocs build --site-dir $READTHEDOCS_OUTPUT/html
```

{% endmarkdown %}
{% endcall %}
</div>
</div>

<div class="middle aligned left aligned six wide computer twelve wide tablet sixteen wide mobile column">
<div class="ui padded basic segment">
<div class="ui relaxed list">

{%- set header_1 = "Create an account" %}
{%- set icon_1 = "fa-square-1" -%}
<span class="ui small teal header item">
<i class="fad {{ icon_1 }} secondary big icon"></i>
<span class="content">
{{ header_1 }}
<span class="sub header">Sign up with GitHub or your email.</span>
</span>
</span>

{%- set header_2 = "Import your project" %}
{%- set icon_2 = "fa-square-2" -%}
<span class="ui small header item">
<i class="fad {{ icon_2 }} secondary big icon"></i>
<span class="content">
{{ header_2 }}
<span class="sub header">Select your existing Git repositories with a 1-click interface.</span>
</span>
</span>

{%- set header_3 = "Add YAML config" %}
{%- set icon_3 = "fa-square-3" -%}
<span class="ui small header item">
<i class="fad {{ icon_3 }} secondary big icon"></i>
<span class="content">
{{ header_3 }}
<span class="sub header">Save this file as <code>.readthedocs.yaml</code>, and update the commands as necessary</span>
</span>
</span>

{%- set header_4 = "Your docs build on every commit" %}
{%- set icon_4 = "fa-square-4" -%}
<span class="ui small header item">
<i class="fad {{ icon_4 }} secondary big icon"></i>
<span class="content">
{{ header_4 }}
<span class="sub header">Like magic.</span>
</span>
</span>
</div>
</div>
</div>
</div>
</div>
</section>

{% block homepage_bottom_callout %}
<section>
<div class="ui very padded container">
<div class="ui grid center aligned">
<div class="row">
<div class="column twelve wide computer sixteen wide tablet">
<div class="ui basic vertical huge segment">
<h2 class="ui center aligned header">
Still not convinced? Try it yourself <i class="fad fa-rocket icon"></i>
</h2>

<p>
GitHub Pages could be pretty useful when talking about static hostings.
However, for publishing <em>good documentation</em> it lacks lot of features that your readers will want.
Read the Docs is the all-in-one solution that gets you started with all those features from the beginning.
</p>

<p>
<a class="ui large teal stackable button"
data-analytics="signup-modal"
onclick="jQuery('#signup_modal').modal('show');">
<i class="fad fa-rocket icon"></i>
Get started for free
</a>
</p>
</div>
</div>
</div>
</div>
</div>
</section>
{% endblock homepage_bottom_callout %}
</body>
</html>
93 changes: 93 additions & 0 deletions content/partials/comparisons.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
{#
The SaaS feature comparison table
#}
{% macro feature_table() %}
<table class="ui mini unstackable celled table" id="feature-table">

{% macro _feature_table_row() %}
<tr>
<th class="eight wide" scope="col"></th>
<th class="two wide center aligned" scope="col">
<img class="center aligned" src="{{ SITE_URL }}/images/github-logo.svg" width="80%" alt="GitHub Pages">
</th>
<th class="two wide center aligned" scope="col">
<img class="center aligned" src="{{ SITE_URL }}/theme/img/logo-wordmark-dark.svg" alt="Read the Docs">
</th>
</tr>
{% endmacro %}

<thead class="ui sticky" data-module="sticky" data-module-context="#feature-table">
{{ _feature_table_row() }}
</thead>
<tbody>
{{ caller() }}
</tbody>
<tfoot>
{{ _feature_table_row() }}
</tfoot>
</table>
{% endmacro %}

{#
Feature row in the feature table

Similar to plan features list above, each item has an icon, header, and
description line of text. The remaining parameters control what is shown
for each plan. These can be binary values to output check marks, `None` to
be blank, or a string to output text to the plan's cell.

Again, this supports the `show_community_features` global, until we confirm
this mixed display is not confusing.
#}
{% macro feature_row(name, description, icon, on_github=False, on_readthedocs=True) %}
<tr>
<td>
<div class="ui small header">
{% if "fa-osi" in icon %}
<i class="{{ icon }} icon"></i>
{% else %}
<i class="fad {{ icon }} icon"></i>
{% endif %}
<div class="content">
{{ name }}
<div class="sub header">
{{ description }}
</div>
</div>
</div>
</td>
{{ feature_row_cell(on_github) }}
{{ feature_row_cell(on_readthedocs) }}
</tr>
{% endmacro %}

{#
Feature row cell helper

This is the logic for each plan's cell for each feature. Values are:

(value, cell_class_name)
Pass in an optional class name for the cell, ``value`` is processed using
the same rules as a non-tuple ``value``.

True
Show a check

Anything truthy
Show the string representation

False
Show an xmark
#}
{% macro feature_row_cell(value) %}
{% if value is iterable and value is not string and value | length == 2 %}
{% set (value, class_name) = value %}
{% endif %}
{% if value == True %}
<td class="center aligned {{ class_name|default("positive") }}"><i class="fad fa-circle-check large icon"></i></td>
{% elif value %}
<td class="center aligned {{ class_name|default("positive") }}">{{ value }}</td>
{% else %}
<td class="center aligned disabled"><i class="fad fa-circle-xmark large icon"></i></td>
{% endif %}
{% endmacro %}
2 changes: 2 additions & 0 deletions readthedocs_theme/templates/includes/footer.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,8 @@ <h4 class="ui sub header">About us</h4>
<a class="item" href="https://dev.readthedocs.io/page/contribute.html">Contributing</a>
<h4 class="ui sub header">Tools</h4>
<a class="item" href="/tools/sphinx/">Sphinx</a>
<h4 class="ui sub header">Comparisons</h4>
<a class="item" href="/comparisons/github-pages/">GitHub Pages</a>
{% endblock menu_about %}
</div>
</div>
Expand Down

0 comments on commit 366b41c

Please sign in to comment.