Create a static documentation website from a hosted README with Sapper

A few weeks earlier, I was ready to share my OS project Restapify with the world (read more about it in this post). The coverage was good, the package published and the GitHub repo had a good and welcoming README. So it was time to create the website to present the features and the documentation of it in a fancy way.

The documentation websites should be a static website (since it's tiny, doesn't change a lot over time and the SEO is better) and the documentation should be generated from a README hosted on GitHub. With this in mind, sapper was the perfect candidate to build this website.

First part was to create the sapper project from his template:

npx degit "sveltejs/sapper-template#rollup" my-app
# or: npx degit "sveltejs/sapper-template#webpack" my-app
cd my-app
npm install

You should then have the following folder structure:

Then lets create two pages: / and /docs. In sapper you only need to add two svelte components in the src/routes folder: index.svelte and docs.svelte.

The home page only render some HTML components that presents the features etc...

<script>
    import Header from '../components/Header.svelte'
    import Features from '../components/Features.svelte'
    import GettingStarted from '../components/GettingStarted.svelte'
    import Footer from '../components/Footer.svelte'
</script>

<svelte:head>
    <title>Restapify • Quickly and easily deploy a mocked REST API</title>
</svelte:head>

<div id="home">
    <Header />
    <section class="container my-5 py-5">
        <Features />
        <hr />
        <GettingStarted />
    </section>
    <Footer />
</div>

The most interesting part is how to get a nice documentation like you can see here from a hosted README file on GitHub. The original documentation file is located on https://github.com/johannchopin/restapify/blob/main/docs/README.md so I'm able to simply fetch it's markdown code in JavaScript by using:

const DOCS_URL = 'https://raw.githubusercontent.com/johannchopin/restapify/main/docs/README.md'
const response = await fetch(DOCS_URL)
const inlineMd = await response.text()

Then I can parse the markdown to Html by using the showdownjs library:

import showdown from 'showdown'

export const getDocsAsHtml = (doc: string): string => {
  const converter = new showdown.Converter({ 
    disableForced4SpacesIndentedSublists: true,
    ghCompatibleHeaderId: true,
    tables: true
  })
  return converter.makeHtml(doc)
}

Then you can easily statically render this Html in sapper by using the native preload function:

/src/routes/docs.svelte

<script context="module">
  import { getDocsAsHtml } from "../docs-generation/getDocs";

  export async function preload(page) {
    const DOCS_URL = 'https://raw.githubusercontent.com/johannchopin/restapify/main/docs/README.md'
    const response = await this.fetch(DOCS_URL)
    const inlineMd = await response.text()
    const htmlContent = getDocsAsHtml(inlineMd)

    return { htmlContent }
  }
</script>

<script>
  export let htmlContent
</script>

<svelte:head>
    <title>Docs • Restapify</title>
</svelte:head>

<div class="row" id="wrapper">
    {@html htmlContent}
</div>

Now just by running the command sapper export you will get a static website with a nice home and documentation page. So if you change on part of the README documentation you will only need to re-export and deploy the static files.

So that was for the core concept of creating a static website from a hosted README. Thanks for reading and hope it will help some of you to deploy a nice and small static website for some open-source project 🚀

You can see a full example of such website source code at https://github.com/johannchopin/restapify-website.

Feel also free to check the Restapify project if you are interested in easily mocking a REST API:

johannchopin / restapify

Quickly and easily deploy a mocked REST API by using an intuitive and developer friendly JSON file structure

Restapify

Restapify is a tool that allows you to quickly and easily deploy a local REST API by using an intuitive and developer friendly JSON file structure.

---

Summary

• Why Restapify
• Features
• Documentation
• Contributing

Why Restapify

When you start a new frontend project when the backend is not yet ready, you quickly come to the question of how to retrieve the data to be displayed. There are then many solutions that come with advantages but also some inconveniences. It's possible to use a tool like postman but it's not 100% free and require an account, to simply fetch local JSON data but it only supports a GET request or use a mocker library like json-server, mocker-api or http-fake-backend.

The problem of most of this libraries is the way you have to define your API endpoints (a single file for all the routes, javascript files that took almost the same…

View on GitHub