Skip to content

Latest commit

 

History

History
113 lines (83 loc) · 5.13 KB

README.md

File metadata and controls

113 lines (83 loc) · 5.13 KB
Raw

Podman.io Website README

This website is built using Docusaurus 2.

Build Locally

Follow these steps to test the site with either a local development server, or by statically generating the site.

  • make sure yarn is installed
  • Install packages
    • $ yarn
  • Run a local development server
    • $ yarn start
  • Generate static content (this is how the site is built for production)
    • $ yarn build
      • After this you can test the local build with:
        • yarn serve

Testing on your Virtual Machine

If you're doing development on a VM there are a few steps to take to test your changes:

  • Set your firewall of your VM to allow access to port 3000. These commands only have to be run once for the lifetime of the VM, or until you reconfigure your firewall settings.
    • # firewall-cmd --permanent --add-port=3000/tcp
    • # firewall-cmd --reload
  • As noted above, build and start your web server after your proposed changes are complete:
    • $ yarn build
    • $ yarn serve
  • On the host machine of your VM, open a web browser and connect to the IP of your VM:
    • http://#.#.#.#:3000
    • Note, http and NOT https, and #.#.#.# is your VM's TCP/IP address, such as 10.0.0.1

Deployment

  • The site is set to automatically deploy when code is pushed to the main branch
    • See `.github/workflows/static.yml
  • Important: prior to merging to main, run yarn build locally

How to Update the Podman.io Website

Page Content

Text and Images

  • Most page data is stored in static/data/<page-name>
    • It is set up so that you can use markdown in the strings for much of the content.
      • If the markdown syntax renders, it needs to be passed into the Markdown component (in components/utilities/)
  • files like static/data/globa.ts, static/data/testimonials.ts, and static/data/meetings.ts are meant to make it easier for people with limited coding experience to be able to quickly update specific and regularly changing content.
    • note: the papaparse library has been added for switching to .csv files in the future.

Page Style and Structure

Pages Pattern

  • Fat arrow notation for sections that only appear on the particular page
    • These sections are organized in an exported function at the end of the file
  • Large sections
    • some content takes up a lot of space and may be useful elsewhere or temporary, they can be found in src/components/content/
      • Components in this directory should be self sufficient for data (but it's not necessary of course)

Components

  • src/components/content: Self-sufficient components, large page content components, temporary components
  • src/components/layout: Headers, grids, and any other sections that organize content
  • src/components/shapes: SVG components such as the wave border
  • src/components/ui: Reusable components, little to no data by default, presentational
  • src/components/utilities: Buttons, links, and other small reusable elements

Typescript

  • a bunch of base types are found in typs.d.ts
    • these are primarily for props. Kept minimal by design and then extended when needed (primarily with style props)

Assets

CSS

  • Podman and Podman Desktop color themes are added in tailwind.config.js
  • A custom radial gradient has also been added to tailwind.config.js (it uses the same breakpoints as other tailwind gradients)
  • changes to the default styles are in src/assets/css/main.css in the following order:
    • imports
    • docusaurus root colors
    • docusarus component style changes
    • font configuration
  • default fonts are set inside @layer base{} in main.css using tailwind's @apply syntax

Configuration Information

How to Update Docusaurus

  • Run the following command to upgrade docusaurus
    • yarn up @docusaurus/core@latest @docusaurus/preset-classic@latest
  • note that the docusaurus site says to use upgrade but it's actually up when using yarn
  • to upgrade tailwind or other packages, similarly use the command:
    • yarn up <package-name>

Plugins and Libraries

  • Icon Library: Iconify
  • CSS Framework: Tailwind (see tailwind.config.js, assets/css/main.css)
  • Code Formatting: Prettier (see .prettierrc, .prettierignore)
  • Linting: Eslint (see .eslintrc, .eslintignore)
  • Rendering markdown from js strings: react markdown parser
    • Use the custom ` component for any markdown strings
      • This component wraps the markdown parser in <BrowserOnly>{() => <ReactMarkdown />}</BrowserOnly> and handles the lazy loading and imports, reducing the amount of code needed on each instance.
  • Rendering html from wordpress: html-react-parser
    • Use this to render any injected html to avoid XSS