SecureSECO DAO documentation

This is the readme for the SecureSECO DAO documentation. This documentation was made using Nextra's docs theme, see their documentation for more information.

The documentation is deployed at docs.secureseco.org.

Installing dependencies and setting up environment variables

1. Copy the .env.example file to .env and fill in the values (if there isn't a env.example, there aren't any environment variables to set)
2. Optional: Install the Prettier, MDX and ESlint plugin in vscode (or your editor of choice), might have to restart your editor.
3. In case you haven't already: Install npm
4. run: npm i

Local development

First, run npm i to install the dependencies.

Then, run npm run dev to start the development server and visit localhost:3000.

Quick start

Folder structure

See Nextra's folder structure guide for more information.

Editing a page

Find the page in the pages folder and edit it. The pages are written in markdown (mdx), so you can use markdown syntax to format the page. Check out Nextra's markdown guide and Nextra's syntax highlighting guide for more information.

Images

Use images like this: ![Hello](/demo.png) in the markdown, it supports automatically optimizing your static image imports with the Markdown syntax, using Next.js Image component under the hood.

Images are rounded by default (see global.css), if you don't want the rounded images, add the no-round-image class to a div around the image like this:

<div className="no-round-image">![Hello](/demo.png)</div>

With Next.js Image, there will be no layout shift, and a beautiful blurry placeholder will be shown by default when loading the images.

You can place images with kebab-case names in the public/img folder and use them like this: ![Hello](/img/demo.png).

Links and navigation

All relative Markdown links are automatically converted to Next.js links. This means that the target page will be prefetched. And when you click on a link, the page will be loaded on the client-side like a SPA, without making a full page load. For example:

[Home](/)

will automatically use Next.js Link component under the hood, and will be prefetched.

Latex

See Nextra's latex guide for more information.

Diagrams

See Nextra's Mermaid guide for more information.

You can ofcourse also just use an image of a diagram.

Tables

See Nextra's table guide for more information.

Icons

This project uses Lucide and svg's for icons. To use an icon import it from the @lucide/react package in icons.tsx. Add it to the object like:

import { IconName } from "@lucide/react";

export const Icons = {
  // ...
  iconName: IconName,
  // or with an svg:
  gitHub: (props: LucideProps) => (
    <svg viewBox="0 0 438.549 438.549" {...props}>
      <path fill="currentColor" d="M409.132 ... "></path>
    </svg>
  ),
};

Then you can use it like this in your mdx or tsx files:

import { Icons } from "../components/icons";

<Icons.iconName className="h-5 w-5" />;

You can do this directly in the mdx or in a tsx component.

This way we keep all the svg and icon imports in one place and have autocomplete for the icons.

Useful components for the mdx

Callout component

Checkout the Callout component for a nice callout component.

Use it like this:

• type: The type of the Callout. Type: 'default' | 'info' | 'warning' | 'error' Default: 'default'

• emoji: Optional emoji to show in the Callout.

import { Callout } from "nextra/components";

<Callout type="error" emoji="️🚫">
  This is a dangerous feature that can cause everything to explode.
</Callout>;

Steps component

Checkout the Steps component for a nice steps component.

Usage:

When using the step component, please provide a h2 heading for the steps title, you can call it x Guide. Otherwise you might have an H1 go straight to an H3.

import { Steps } from "nextra-theme-docs";

<Steps>

### Step 1

Contents for step 1.

### Step 2

Contents for step 2.

</Steps>

Tabs component

Checkout the Tabs component for a nice tabs component.

Usage:

import { Tab, Tabs } from "nextra-theme-docs";

<Tabs items={["pnpm", "npm", "yarn"]} defaultIndex="1">
  <Tab>**pnpm**: Fast, disk space efficient package manager.</Tab>
  <Tab>
    **npm** is a package manager for the JavaScript programming language.
  </Tab>
  <Tab>**Yarn** is a software packaging system.</Tab>
</Tabs>;

defaultIndex is optional and defaults to 0.

Card component

A nice Card component with a cool hover effect that links to a page on the website.

If you want to link to an external website, pass external: true to the props for the card. This will render a smaller card without description, but with an external link icon on the right

Usage:

• For multiple cards rendered automatically in a grid, use the Cards component.

import { Cards } from "../components/cards";

<Cards
  cardData={[
    {
      href: "/joining",
      name: "Joining SecureSECO DAO",
      description:
        "Find out how you can become a part of the SecureSECO DAO and contribute to safer software ecosystems.",
      icon: Icons.doorOpen,
      pattern: {
        y: 16,
        squares: [
          [0, 1],
          [1, 3],
        ],
      },
    },
    {
      href: "/query",
      name: "Making a Query",
      description:
        "Learn how to make queries to check if your repository contains any known vulnerabilities.",
      icon: Icons.search,
      pattern: {
        y: -6,
        squares: [
          [-1, 2],
          [1, 3],
        ],
      },
    },
  ]}
/>;

• For a single card, use the Card component.

import { Card } from "../components/cards";

<Card
  card={{
    href: "/joining",
    name: "Joining SecureSECO DAO",
    description:
      "Find out how you can become a part of the SecureSECO DAO and contribute to safer software ecosystems.",
    icon: Icons.doorOpen,
    pattern: {
      y: 16,
      squares: [
        [0, 1],
        [1, 3],
      ],
    },
  }}
/>;

Styling

Tailwind

This project uses Tailwind CSS for styling. Tailwind is a utility-first CSS framework for rapidly building custom user interfaces. You can use Tailwind classes directly in the mdx files. For example:

<div className="text-red-500">Hello</div>

It is also possible to use Tailwind classes in tsx components.

Darkmode

You need to provide both colors for light mode and darkmode in your tailwind styling in components or mdx directly. For example:

<div className="bg-black dark:bg-white">Hello</div>

Don't worry about things like changing text-white and text-black each time, since those classes are already set by Nextra, unless you want to override them.

Optional classes

We use Clsx + Tailwind-Merge for conditional CSS class application.

Clsx and Tailwind-Merge are used together to create the cn() function, which makes it easier to conditionally apply Tailwind CSS classes. Defined in lib/utils.ts. This function is inspired by the shadcn: https://ui.shadcn.com/docs.

Example use:

import { cn } from "../lib/utils";

const isRed = true;

<div className={cn(isRed ?? "text-red-500", "w-full")}>Hello</div>;

Naming conventions

In this project, we use the following naming conventions:

Kebab-case

For folders, files (both mdx file names and tsx components), images (in the public folder), and css classes.

Title Case

For page titles (in _meta.json files) and h1 headings, we use Title Case. For headings below h1, so h2, h3 and onwards, we use Sentence case.

Title case is a style in which the first letter of each word is capitalized, except for certain short words, such as articles (a, an, the), conjunctions (and, but, or, for, nor), and prepositions (in, to, of, at, by, up, for, off, on). For example:

• Welcome to SecureSECO DAO

PascalCase

For React components itself.

camelCase

For variables, icon and function names.

Formatting

Code style

The code should be formatted as dictated by the automatic formatting tools. It is advised to turn on the Format On Save option in settings if you are using VS Code. Alternatively, you can run npm run format to format all files in the project, however, it is preferable to format only the files that you change.

License

This project is licensed under the MIT License.