knight/datahub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
datahub/site/content/guide/index.md
Ola Rubaj c5ae365a20 [site/content/guide][m]: tutorial 3 overview
2023-07-28 15:55:09 +02:00

5.5 KiB
Raw Permalink Blame History

showToc, showSidebar, title, disableTitle, description
showToc showSidebar title disableTitle description
false false Markdown-based Websites Guide true Create markdown-based websites and data portals, update it, add collaborators and discover markdown superpowers with Flowershow and PortalJS

Tutorials

Tutorial 1: Create a website from scratch using markdown and PortalJS

In this tutorial we will walk you through creating an elegant, fully functional website written in simple markdown and published with PortalJS.

By the end of this tutorial you will:

  • have a working markdown-based website powered by PortalJS.
  • be able to edit the text and add pages, all from an online interface without installing anything.

Below is a screenshot of how the final website will look like: !tutorial-1-result.png

Setup a sandbox website including live publishing

  • Prerequisites: sign up for GitHub and Vercel
  • Navigate to datopian/flowershow repository
  • Click on "Deploy"
  • Let the site build on Vercel
  • Visit the site! Yay! Your site is working! 🎉

Now, let's edit the front page

  • Navigate to content/index.md file in the site repository
  • Add some text to it
  • Save and watch the site redeploy
  • Visit the site! Yay! Your changes are live! 🎉

Let's add a page: e.g. about page

  • Navigate to the content folder in the site repository
  • Add about.md file with some text
  • Save and watch the site redeploy
  • Visit the site! Yay! Your changes are live! 🎉

Tip

Read full tutorial create-a-website-from-scratch

Tutorial 2: Editing your site locally on your computer

In this tutorial, we will walk you through the process of editing your Flowershow website locally on your computer.

By the end of this tutorial, you will:

  • Understand what is Markdown and why you should use Obsidian to edit content on your Flowershow websites in most cases.
  • Gain a deeper understanding of working with Git and GitHub Desktop.
  • Learn how to clone your website's repository to your computer.
  • Learn how to edit content using Obsidian and what are the benefits of it.
  • Learn how to commit (save) your changes locally and push them back to the GitHub repository.

Below is a screenshot of how the final website will look like:

!tutorial-2-result.png

Clone the repository to your computer

  • Setup GitHub Desktop app with your GitHub account
  • Grab your site's repository URL
  • Open GitHub Desktop app and clone the repository
  • Yay! You have a copy of your website's repository on your computer! 🎉

Now, let's edit in Obsidian

  • Open the /content folder of the cloned repository in Obsidian
  • Edit the home page and the about page
  • Create a folder with the reviews of books you've read

Commit your changes

  • Commit the changes in GitHub Desktop app
  • Push the changes to the remote repository
  • Watch the site redeploy
  • Visit the site! Yay! Your changes are live! 🎉

Tip

Read full tutorial edit-a-website-locally

Tutorial 3: Collaborating with others on your website project

In this tutorial, we will guide you through collaborating with others on the same website project using GitHub.

By the end of this tutorial, you will:

  • Understand what a branch is and how to create one.
  • Understand what a pull request (PR) is and how to create one.
  • Learn how to review and merge a PR.
  • Know how to resolve conflicts if they arise.
  • Collaborate with others using GitHub, following best practices.

Create a new branch

  • Navigate to your site's repository on GitHub
  • Click on the 'Branch' dropdown menu, type a new branch name and press Enter
  • Yay! You've created a new branch! 🎉

Now, let's make changes in the new branch

  • Switch to the new branch in GitHub Desktop
  • Open the /content folder of the repository in Obsidian
  • Edit the about page
  • Commit the changes in GitHub Desktop app and push them to the remote repository on GitHub

Create a pull request (PR)

  • Go back to your site's repository on GitHub
  • Click on 'New pull request'
  • Select your branch from the dropdown menu
  • Write a brief description of your changes, then click on 'Create pull request'
  • Yay! Your changes are ready to be reviewed! 🎉

Review and merge a pull request

  • Navigate to the 'Pull requests' tab in your repository
  • Open the newly created pull request
  • Review the changes, add comments if necessary
  • If everything is in order, click 'Merge pull request', then 'Confirm merge'
  • Yay! You've merged your changes into the main branch! 🎉

Resolving conflicts

  • In case of conflicts between your changes and those on the main branch, GitHub will alert you
  • Follow the on-screen instructions to resolve the conflicts and merge your changes

Tip

Read full tutorial collaborate-on-website-project (TBD)

Howtos