docs: add website

.github/workflows/deploy-docs.yml

@@ -0,0 +1,68 @@
+name: deploy-docs
+on:
+ push:
+ branches:
+ - main
+ paths:
+ - '.github/workflows/deploy-docs.yaml'
+ - 'website/**'
+ pull_request:
+ branches:
+ - main
+ paths:
+ - '.github/workflows/deploy-docs.yaml'
+ - 'website/**'
+
+permissions:
+ contents: read
+
+jobs:
+ deploy:
+ name: Generate docs website to GitHub Pages
+ runs-on: ubuntu-latest
+ permissions:
+ contents: write
+ defaults:
+ run:
+ working-directory: website
+ steps:
+ - uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2
+
+ - name: Harden Runner
+ uses: step-security/harden-runner@63c24ba6bd7ba022e95695ff85de572c04a18142
+ with:
+ disable-sudo: true
+ egress-policy: block
+ allowed-endpoints: >
+ github.com:443
+ registry.yarnpkg.com:443
+ *.githubusercontent.com:443
+ *.blob.core.windows.net:443
+
+ - name: Setup Node
+ uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+ with:
+ node-version: 20.x
+
+ - name: Get yarn cache
+ id: yarn-cache
+ run: echo "dir=$(yarn cache dir)" > $GITHUB_OUTPUT
+
+ - name: Cache dependencies
+ uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9 # v4.0.2
+ with:
+ path: ${{ steps.yarn-cache.outputs.dir }}
+ key: ${{ runner.os }}-website-${{ hashFiles('**/yarn.lock') }}
+ restore-keys: |
+ ${{ runner.os }}-website-
+
+ - run: yarn install --frozen-lockfile
+ - run: yarn build
+
+ - name: Deploy to GitHub Pages
+ if: github.ref == 'refs/heads/main' && github.event_name == 'push' && github.repository == 'Azure/dalec'
+ uses: peaceiris/actions-gh-pages@373f7f263a76c20808c831209c920827a82a2847 # v3.9.3
+ with:
+ github_token: ${{ secrets.GITHUB_TOKEN }}
+ publish_dir: ./website/build
+ destination_dir: ./docs

website/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

website/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

website/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+ presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/editor-support.md → website/docs/editor-support.md

@@ -1,6 +1,8 @@
-# Editor Support
+---
+title: Editor Support
+---
 
-There is a [json schema file](spec.schema.json) which can be used in coms ecases to integrate with your editor.
+There is a [json schema file](https://github.com/Azure/dalec/blob/main/docs/spec.schema.json) which can be used to integrate with your editor.
 This will help validate your yaml files and provide intellisense for the spec.
 
 ## VSCode

docs/intro.md → website/docs/intro.md

@@ -1,4 +1,7 @@
-# Intro
+---
+title: Introduction
+slug: /
+---
 
 Dalec is a tool for producing container images by first building packages
 targeting the linux distribution used by the container image.
@@ -21,7 +24,7 @@ for creating a package that is just a collection of dependencies.
 
 ### Example
 
-In this examnple wee'll build a virtual package that just installs other packages as dependencies.
+In this example we'll build a virtual package that just installs other packages as dependencies.
 
 ```yaml
 # syntax=ghcr.io/azure/dalec/frontend:latest
@@ -81,7 +84,7 @@ targets:
 You can also set other image settings like entrypoint/cmd, environment
 variables, working directory, labels, and more.
 For now, the best place to find what all is available to set is to look at the
-[code](../spec.go).
+[code](https://github.com/Azure/dalec/blob/main/spec.go).
 
 ```yaml
 # syntax=ghcr.io/azure/dalec/frontend:latest
@@ -124,7 +127,7 @@ To do this we'll need a few things:
 Here we'll pull from a github repo.
 It will use the `go-md2man` repo and build the `go-md2man` from the v2.0.3 tag in the repo.
 
-*Note*: See the full example from [examples/go-md2man.yml](examples/go-md2man-1.yml)
+*Note*: See the full example from [examples/go-md2man.yml](https://github.com/Azure/dalec/blob/main/docs/examples/go-md2man-1.yml)
 
 ```yaml
 # syntax=ghcr.io/azure/dalec/frontend:latest
@@ -188,7 +191,7 @@ list of sources. We'll accomplish this by add a source which will run `go mod
 download` in a docker image with the `src` source mounted and then extract the
 go modules from the resulting filesystem.
 
-*Note*: See the full example from [examples/go-md2man.yml](examples/go-md2man-2.yml)
+*Note*: See the full example from [examples/go-md2man.yml](https://github.com/Azure/dalec/blob/main/docs/examples/go-md2man-2.yml)
 
 ```yaml
 # syntax=ghcr.io/azure/dalec/frontend:latest

website/docusaurus.config.ts

@@ -0,0 +1,91 @@
+import { themes as prismThemes } from 'prism-react-renderer';
+import type { Config } from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+
+const config: Config = {
+ title: 'Dalec',
+ tagline: 'Exterminate!',
+ favicon: 'img/favicon.ico',
+
+ // Set the production url of your site here
+ url: 'https://Azure.github.io',
+ // Set the /<baseUrl>/ pathname under which your site is served
+ // For GitHub pages deployment, it is often '/<projectName>/'
+ baseUrl: '/',
+
+ // GitHub pages deployment config.
+ // If you aren't using GitHub pages, you don't need these.
+ organizationName: 'Azure', // Usually your GitHub org/user name.
+ projectName: 'dalec', // Usually your repo name.
+
+ onBrokenLinks: 'throw',
+ onBrokenMarkdownLinks: 'warn',
+
+ // Even if you don't use internationalization, you can use this field to set
+ // useful metadata like html lang. For example, if your site is Chinese, you
+ // may want to replace "en" with "zh-Hans".
+ i18n: {
+ defaultLocale: 'en',
+ locales: ['en'],
+ },
+
+ presets: [
+ [
+ 'classic',
+ {
+ docs: {
+ routeBasePath: '/',
+ sidebarPath: './sidebars.ts',
+ // Please change this to your repo.
+ // Remove this to remove the "edit this page" links.
+ editUrl:
+ 'https://github.com/Azure/dalec/blob/main/website/docs/',
+ },
+ theme: {
+ customCss: './src/css/custom.css',
+ },
+ } satisfies Preset.Options,
+ ],
+ ],
+
+ themeConfig: {
+ // Replace with your project's social card
+ image: 'img/logo.png',
+ navbar: {
+ title: 'Dalec',
+ logo: {
+ alt: 'Dalec logo',
+ src: 'img/logo.svg',
+ },
+ items: [
+ {
+ href: 'https://github.com/Azure/dalec',
+ position: 'right',
+ className: 'header-github-link',
+ 'aria-label': 'GitHub repository',
+ },
+ ],
+ },
+ footer: {
+ style: 'dark',
+ links: [],
+ copyright: `Copyright © ${new Date().getFullYear()} Azure Container Upstream.`,
+ },
+ prism: {
+ theme: prismThemes.github,
+ darkTheme: prismThemes.dracula,
+ additionalLanguages: ['bash', 'json', 'yaml'],
+ },
+ colorMode: {
+ defaultMode: 'light',
+ disableSwitch: false,
+ respectPrefersColorScheme: true,
+ },
+ announcementBar: {
+ id: 'announcementBar-1', // Increment on change
+ content: `⭐️ If you like Dalec, please give it a star on <a target="_blank" rel="noopener noreferrer" href="https://github.com/Azure/dalec">GitHub</a>!</a>`,
+ },
+ } satisfies Preset.ThemeConfig,
+};
+
+export default config;

website/package.json

@@ -0,0 +1,47 @@
+{
+ "name": "website",
+ "version": "0.0.0",
+ "private": true,
+ "scripts": {
+ "docusaurus": "docusaurus",
+ "start": "docusaurus start",
+ "build": "docusaurus build",
+ "swizzle": "docusaurus swizzle",
+ "deploy": "docusaurus deploy",
+ "clear": "docusaurus clear",
+ "serve": "docusaurus serve",
+ "write-translations": "docusaurus write-translations",
+ "write-heading-ids": "docusaurus write-heading-ids",
+ "typecheck": "tsc"
+ },
+ "dependencies": {
+ "@docusaurus/core": "3.2.1",
+ "@docusaurus/preset-classic": "3.2.1",
+ "@mdx-js/react": "^3.0.0",
+ "clsx": "^2.0.0",
+ "prism-react-renderer": "^2.3.0",
+ "react": "^18.0.0",
+ "react-dom": "^18.0.0"
+ },
+ "devDependencies": {
+ "@docusaurus/module-type-aliases": "3.2.1",
+ "@docusaurus/tsconfig": "3.2.1",
+ "@docusaurus/types": "3.2.1",
+ "typescript": "~5.2.2"
+ },
+ "browserslist": {
+ "production": [
+ ">0.5%",
+ "not dead",
+ "not op_mini all"
+ ],
+ "development": [
+ "last 3 chrome version",
+ "last 3 firefox version",
+ "last 5 safari version"
+ ]
+ },
+ "engines": {
+ "node": ">=18.0"
+ }
+}

website/sidebars.ts

@@ -0,0 +1,27 @@
+import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
+
+/**
+ * Creating a sidebar enables you to:
+ - create an ordered group of docs
+ - render a sidebar for each doc of that group
+ - provide next/previous navigation
+
+ The sidebars can be generated from the filesystem, or explicitly defined here.
+
+ Create as many sidebars as you want.
+ */
+const sidebars: SidebarsConfig = {
+ sidebar: [
+ {
+ type: 'category',
+ label: 'Getting Started',
+ items: [
+ 'intro',
+ 'editor-support',
+ 'testing'
+ ],
+ },
+ ],
+};
+
+export default sidebars;