Skip to content

Getting Started

Jump to bottom
Muhammad Usman edited this page Jul 12, 2023 · 9 revisions

To get started with the Rose template, first go check out the example site here: Demo site.

Prerequisites

  1. Github account
  2. Familiarity with markdown (learn more here)
  3. Ability to run node.js and npm on your computer
  4. Optional: a domain name.

Principles

  1. Hosting this should be virtually free, Github pages, Cloudflare pages, and many other places allow hosting a static website for free without any bandwidth limits.
  2. Configuration should be minimal at first, and zero on-going maintenance. The following instructions will cover what needs to be configured.

Get started

  • Click the "Use this template" button on the repo homepage.
  • Once you have the project on your computer, run npm install in your terminal
  • Run npm run dev to make sure everything looks good. If you are able to see the example projects, images, and clicking around doesn't break anything, you're good to go. If not, file an issue or start a discussion: https://github.com/usmanity/rose/issues
  • See deployment instructions below, this will be required when initially setting up.

Adding your own content and info

  • There are two main places where your content will live: public/ and content/.

Editing the homepage

All the content within the homepage is contained in the content/about.json file. Take a look at start modifying things as you see them fit.

For social networks, delete the key/value pair if you don't want to show it on your website.

Adding images

To keep the configuration simple, the images are stored in the public/images directory. Referencing images in the .json files simply requires the filename, e.g. "photo": "rose.webp" will work.

Referencing images in the markdown files (for project details) requires the /images/ prefix, e.g. /images/rose.webp.

Adding projects

Projects are organized in two places, content/projects.json contains the high-level overview of your project and public/projects contains the markdown files. Most of this information will show up on the homepage. There is also the details_file field, this can be used to add project details. In order to allow easy writing and editing, markdown files are used to present the project details page. To reference the project details in projects.json, use just the file name, e.g. "details_file": "large-corp-2.md".

Previewing your site locally

To see your site as you edit it, use the npm run dev command, this will live reload your site as you make changes. To see the production version of it, run npm run build && npm run preview. This is recommended to make sure when you want to go live, it shows what you expect to see and there are no broken or incorrectly linked images.

Deploying to Github Pages

By committing your changes and then pushing them up to Github, you will kick off a new build based on the .github/deploy.yaml file. After a successful build, you will be able to visit your website and see it.

Adding your own domain

Github Pages has a good overview of how to enable a custom domain for your website, you can read that here: https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site

The CNAME file is included as an example, it should work with minimal set up.

Submit your own site

If you've created a website using this template, create an issue or PR and I will add it to the readme. 😄

Clone this wiki locally