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: