mairin / website-new

The new podman.io design project

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

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
  • Icones for web based icon library overview
  • Iconify Intellisense vscode extension
• 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