From 8e4428e2f8b90e28fab64e9335f9541f6f0f9981 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Demenech?= Date: Tue, 6 Jun 2023 07:28:51 -0300 Subject: [PATCH] github-backed-catalog: improve documentation (#925) * [examples/github-backed-catalog][m]: improve documentation * [examples/github-backed-catalog][m]: add info about editing the deployment created on Vercel --- .../docs/examples/github-backed-catalog.md | 43 +++++++++++++++---- 1 file changed, 34 insertions(+), 9 deletions(-) diff --git a/site/content/docs/examples/github-backed-catalog.md b/site/content/docs/examples/github-backed-catalog.md index de09da3a..c25c951d 100644 --- a/site/content/docs/examples/github-backed-catalog.md +++ b/site/content/docs/examples/github-backed-catalog.md @@ -23,33 +23,58 @@ Below are some screenshots: ## How to use this example as a template -- Create a new app with `create-next-app`: -``` +> [!tip] +> You can also create a new project by clicking on the "Deploy" button below. Vercel will clone the example on a new repo under your user or organization on GitHub and set up a deployment for it. +> Then, you can clone the new repo on your machine and start editing it. + +### Create a new app with `create-next-app` + +Run the following commands: + + +```bash npx create-next-app --example https://github.com/datopian/portaljs/tree/main/examples/github-backed-catalog cd ``` -- This project uses the github api, which for anonymous users will cap at 50 requests per hour, so you might want to get a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) and add it to a `.env` file inside the folder like so +### Setup a GitHub token -``` +This project uses the GitHub API, which for anonymous users will cap at 50 requests per hour, so you might want to get a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) and add it to a `.env` file inside the folder, like so: + +```bash GITHUB_PAT= ``` -- Edit the file `datasets.json` to your liking, some examples can be found inside this [repo](https://github.com/datasets) -- Run the app using: +### Setup the datasets list -``` +The `datasets.json` file serves as a list of datasets that should be in your data portal. Edit the this file to your liking. Some examples can be found inside this [repo](https://github.com/datasets): + +### Run the app + +Run the app by executing the following command: + +```bash npm run dev ``` -Congratulations, you now have something similar to this running on `http://localhost:3000` +Congratulations, your new app is now running at http://localhost:3000. ## Deployment [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fdatopian%2Fportaljs%2Ftree%2Fmain%2Fexamples%2Fgithub-backed-catalog) -By clicking on this button, you will be redirected to a page which will allow you to clone the content into your own github/gitlab/bitbucket account and automatically deploy everything. +By clicking on this button, you will be redirected to a page which will allows you to clone the example into your own GitHub/GitLab/BitBucket account and automatically deploy it. +### GitHub token + +You have to set up `GITHUB_PATH` as an environment variable on Vercel. To do that, go to the project's page on Vercel, then click settings, look for "Environment variables" and create a new environment variable. Refer back to the [previous section](#setup-a-github-token) if you are not sure about how to create a GitHub token. + +### Editing the new deployment + +You can now clone the new repo on your machine and start changing it. Simply follow the ["How to use this example as a template" section](#how-to-use-this-example-as-a-template) skipping the first step. + +> [!tip] +> Note that whenever you push changes to the new repo these are going to be automatically deployed by Vercel. ## Structure of `datasets.json`