diff --git a/.eslintignore b/.eslintignore new file mode 100644 index 00000000..581edad3 --- /dev/null +++ b/.eslintignore @@ -0,0 +1 @@ +**/dist diff --git a/.prettierignore b/.prettierignore index 2d238016..cb6e2fd5 100644 --- a/.prettierignore +++ b/.prettierignore @@ -6,3 +6,4 @@ **/*.yaml **/generated/ **/snippet.* +**/dist diff --git a/README.md b/README.md index f8cbb84d..fef8be84 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,15 @@ Monorepo for web related devfile projects ## Getting started +This project uses [`yarn`](https://classic.yarnpkg.com/lang/en/docs/install). + It is highly recommended to download the [Nx Console](https://nx.dev/using-nx/console#download) extension for your IDE if available. -### Workspace commands +## Workspace commands Run `yarn install` to download dependencies. -#### Specific project commands +### Specific project commands - `yarn nx serve --configuration=`: serves the project's application - `yarn nx build --configuration=`: builds the project's application @@ -18,7 +20,7 @@ Run `yarn install` to download dependencies. - `yarn nx test `: tests the project's application - `yarn nx lint `: lints the project's application -#### Nonspecific project commands +### Nonspecific project commands - `yarn create:component `: creates a React component - `yarn create:hook `: creates a React hook @@ -26,154 +28,4 @@ Run `yarn install` to download dependencies. ## landing-page -Landing Page project for [devfile.io](https://devfile.io/). - -### Configuring navigation - -- Header - - Header navigation can be configured on [`navigation.ts`](https://github.com/devfile/devfile-web/blob/main/apps/landing-page/navigation.ts). - - ```ts - export const headerNavigation: HeaderNavigation = [ - ... - ]; - ``` - - Each element in `headerNavigation` is as follows: - - ```ts - [ - { - name: 'Example', // the name of the link - href: 'https://example.com', // the URI of the link - image: ExampleIcon, // Optional: the image of the link - } - ] - ``` - -- Footer - - Footer navigation can be configured on [`navigation.ts`](https://github.com/devfile/devfile-web/blob/main/apps/landing-page/navigation.ts). - - ```ts - export const footerNavigation: FooterNavigation = { - contributors: [ - ... - ], - links: [ - ... - ], - social: [ - ... - ], - }; - ``` - - - `contributors`: contributors the the devfile project in alphabetical order - - `links`: miscellaneous links related to the devfile project - - `social`: social links for the devfile project - - Each element in `contributors`, `links`, and `social` is as follows: - - ```ts - [ - { - name: 'Example', // the name of the link - href: 'https://example.com', // the URI of the link - image: ExampleIcon, // Optional: the image of the link - }, - ... - ] - ``` - -- Sidebar - - Sidebar navigation can be configured under [`./docs-navigation`](https://github.com/devfile/devfile-web/blob/main/apps/landing-page/public/docs-navigation). - - Each file under `/docs-navigation` corresponds to a version except `no-version.yaml` which allows uniform navigation pages between all versions. - - Whenever you update the sidebar navigation you **MUST** restart the server. - - Each sidebar section requires a `title` and `links`. Each element in `links` requires a `title` and `href`. Currently, sidebar navigation is only supported one layer deep. - - ```yaml - - title: Example section 1 - links: - - title: Element 1 - href: /element1 - - title: Element 2 - href: /element2 - - title: Example section 2 - links: - - title: Element 3 - href: /element3 - - title: Element 3 - href: /element4 - ``` - -### Updating documentation - -To update or add documentation, edit or create a markdown file under [`./docs`](https://github.com/devfile/devfile-web/tree/main/apps/landing-page/pages/docs). The markdown is converted to html pages automatically by the [markdoc](https://markdoc.io/) Next.js addon. Instead of using `.mdx`, markdoc extends markdown by enclosing snippets in curly brackets. - -- [Built-in tags](https://markdoc.io/docs/tags#built-in-tags) - -- Custom tags - - Custom tags can be found under [`./tags.tsx`](https://github.com/devfile/devfile-web/blob/main/apps/landing-page/markdoc/tags.tsx) - - - `fences` - - Curly brackets after specifying the code language is optional. - - ````md - ```yaml {% title="Optional: Example" filename="Optional: devfile.yaml" %} - schemaVersion: 2.2.0 - metadata: - name: mydevfile - components: - - name: mydevfile - volume: - size: 200G - ``` - ```` - - - `callout` - - The children for `callout` can be any valid markdown or snippet. - - ```md - {% callout title="Note!" %} - - All location references to `starterProjects` will change to local - paths relative to the stacks directory. - - - Stack component image references will change to use the offline - accessible image repository. - {% /callout %} - ``` - - - `figure` - - ```md - {% figure src="./example" alt="Example" caption="This is an example caption" /%} - ``` - - - `quick-link` and `quick-links` - - ```md - {% quick-links %} - - {% quick-link title="Installation" icon="installation" href="/" description="Step-by-step guides to setting up your system and installing the library." /%} - - {% quick-link title="Architecture guide" icon="presets" href="/" description="Learn how the internals work and contribute." /%} - - {% quick-link title="Plugins" icon="plugins" href="/" description="Extend the library with third-party plugins or write your own." /%} - - {% quick-link title="API reference" icon="theming" href="/" description="Learn to easily customize and modify your app's visual design to fit your brand." /%} - - {% /quick-links %} - ``` - - After you update any documentation, update the navigation if you added a new page or changed a file name. - -### Releasing a new version +[Landing Page README](https://github.com/devfile/devfile-web/tree/main/apps/landing-page) diff --git a/apps/landing-page/.gitignore b/apps/landing-page/.gitignore index b6a9b785..66eee210 100644 --- a/apps/landing-page/.gitignore +++ b/apps/landing-page/.gitignore @@ -1,2 +1,4 @@ -**/docs -**/devfile-schemas +pages/docs/** +!pages/docs/index.tsx + +public/devfile-schemas diff --git a/apps/landing-page/README.md b/apps/landing-page/README.md new file mode 100644 index 00000000..f26d595a --- /dev/null +++ b/apps/landing-page/README.md @@ -0,0 +1,262 @@ +# landing-page + +Landing Page project for [devfile.io](https://devfile.io/). + +## Additional commands + +- `yarn nx prebuild landing-page`: builds the docs directory and navigation sidebar +- `yarn nx postexport landing-page`: exports the website's sitemap + +## Configuring navigation + +- Header + + Header navigation can be configured in [`navigation.ts`](https://github.com/devfile/devfile-web/blob/main/apps/landing-page/navigation.ts). + + ```ts + export const headerNavigation: HeaderNavigation = [ + ... + ]; + ``` + + Each element in `headerNavigation` is as follows: + + ```ts + [ + { + name: 'Example', // the name of the link + href: 'https://example.com', // the URI of the link + image: ExampleIcon, // Optional: the image of the link + } + ] + ``` + +- Footer + + Footer navigation can be configured in [`navigation.ts`](https://github.com/devfile/devfile-web/blob/main/apps/landing-page/navigation.ts). + + ```ts + export const footerNavigation: FooterNavigation = { + contributors: [ + ... + ], + links: [ + ... + ], + social: [ + ... + ], + }; + ``` + + - `contributors`: contributors the the devfile project in alphabetical order + - `links`: miscellaneous links related to the devfile project + - `social`: social links for the devfile project + + Each element in `contributors`, `links`, and `social` is as follows: + + ```ts + [ + { + name: 'Example', // the name of the link + href: 'https://example.com', // the URI of the link + image: ExampleIcon, // Optional: the image of the link + }, + ... + ] + ``` + +- Sidebar + + The sidebar navigation can be configured under [`navigation/*`](https://github.com/devfile/devfile-web/tree/main/libs/docs/src/navigation). + + Each YAML file under `navigation/` corresponds to a devfile version except `no-version.yaml`, which corresponds to pages that are the same between all versions. + + *Whenever you update the sidebar navigation you **MUST** restart the server or run `yarn nx prebuild landing-page`.* + + Each sidebar section requires a `title` and `links`. Each element in `links` requires a `title` and `href`. Currently, the sidebar only supports navigation one layer deep. + + *`no-version.yaml` has an additional top level `top` or `bottom` attribute which corresponds whether the section is on the top or bottom of the sidebar.* + + ```yaml + - title: Example section 1 + links: + - title: Element 1 + href: /element1 + - title: Element 2 + href: /element2 + - title: Example section 2 + links: + - title: Element 3 + href: /element3 + - title: Element 3 + href: /element4 + ``` + +## Updating documentation + +Documentation can be edited or added under [`docs/*`](https://github.com/devfile/devfile-web/tree/main/libs/docs/src/docs). The markdown is converted to html automatically by the [markdoc](https://markdoc.io/) Next.js addon. Instead of using `.mdx`, markdoc extends CommonMark by enclosing snippets in curly brackets. + +### Tags + +[Built-in tags](https://markdoc.io/docs/tags#built-in-tags) + +Custom tags can be found under [`tags.tsx`](https://github.com/devfile/devfile-web/blob/main/apps/landing-page/markdoc/tags.tsx) + +- `fence` + + - `title`: optional + - `filename`: optional + + ````md + ```yaml + schemaVersion: 2.2.0 + metadata: + name: mydevfile + components: + - name: mydevfile + volume: + size: 200G + ``` + ```` + + ````md + ```yaml {% title="Example" filename="devfile.yaml" %} + schemaVersion: 2.2.0 + metadata: + name: mydevfile + components: + - name: mydevfile + volume: + size: 200G + ``` + ```` + +- `callout` + + - `title`: required + - `type`: optional + - `note` (default) + - `warning` + + ```md + {% callout title="Note!" %} + - All location references to `starterProjects` will change to local + paths relative to the stacks directory. + + - Stack component image references will change to use the offline + accessible image repository. + {% /callout %} + ``` + + ```md + {% callout type="warning" title="Warning!" %} + Listening on any other interface than the local loopback poses a + security risk. Such a server is accessible without the JWT + authentication within the cluster network on the corresponding IP + addresses. + {% /callout %} + ``` + +- `figure` + + - `src`: required + - `alt`: required + - `caption`: required + - `hasBackground`: optional + - `false` (default) + - `true` + + ```md + {% figure src="./example" alt="Example" caption="This is an example caption" /%} + ``` + +- `quick-link` and `quick-links` + + `quick-link` + - `title`: required + - `description`: required + - `icon`: required + - `installation` + - `presets` + - `plugins` + - `theming` + - `lightbulb` + - `warning` + - `href`: required + + ```md + {% quick-links %} + + {% quick-link title="Installation" icon="installation" href="/" description="Step-by-step guides to setting up your system and installing the library." /%} + + {% quick-link title="Architecture guide" icon="presets" href="/" description="Learn how the internals work and contribute." /%} + + {% quick-link title="Plugins" icon="plugins" href="/" description="Extend the library with third-party plugins or write your own." /%} + + {% quick-link title="API reference" icon="theming" href="/" description="Learn to easily customize and modify your app's visual design to fit your brand." /%} + + {% /quick-links %} + ``` + +- `current-version` + + The current devfile version selected based on the version dropdown. + + - `beforeVersion`: optional - text to add before the devfile version + - `afterVersion`: optional - text to add after the devfile version + - `isCodeblock`: optional - change text to inline codeblock + - `false` (default) + - `true` + + ```md + {% current-version beforeVersion="schemaVersion: " isCodeblock="true" /%} + ``` + +### Additional things to note + +- Instead of specifying a version for `schemaVersion` when creating a fence for a devfile, `` can access the current devfile version selected based on the version dropdown. + + ```yaml + schemaVersion: + metadata: + name: devfile-sample + ``` + +- After any documentation changes, update the sidebar navigation if a new file was added or a filename was changed. + +## Releasing a new version + +Steps: + +1. Edit the possible versions - [`docVersions`](https://github.com/devfile/devfile-web/blob/main/libs/docs/src/types/index.ts) + + The version directories under [`docs/*`](https://github.com/devfile/devfile-web/tree/main/libs/docs/src/docs) **MUST** correspond to possible version. + + The version navigation files under [`navigation/*`](https://github.com/devfile/devfile-web/tree/main/libs/docs/src/navigation) **MUST** correspond to possible version. + + The devfile schemas under [`devfile-schemas/*`](https://github.com/devfile/devfile-web/tree/main/libs/docs/src/devfile-schemas) **MUST** correspond to possible version. + +2. Edit the default version - [`defaultVersion`](https://github.com/devfile/devfile-web/blob/main/libs/docs/src/types/index.ts) + + The default version must be a possible version. + +3. Create the new version directory under [`docs/*`](https://github.com/devfile/devfile-web/tree/main/libs/docs/src/docs) + + The new version must be a possible version. + + It is suggested to copy and rename the old version directory to the new version directory. + +4. Create the new version navigation under [`navigation/*`](https://github.com/devfile/devfile-web/tree/main/libs/docs/src/navigation) + + The filename **MUST** follow the convention `.yaml` where new version is a possible version. + + It is suggested to copy and rename the old version navigation to the new version navigation. + +5. Create the new version devfile schema under [`devfile-schemas/*`](https://github.com/devfile/devfile-web/tree/main/libs/docs/src/devfile-schemas). + + The new version devfile schema is located in [`schemas/latest/devfile.json`](https://github.com/devfile/api/blob/main/schemas/latest/devfile.json) under [API](https://github.com/devfile/api) Github repository. + + Copy and rename the devfile schema under [`devfile-schemas/*`](https://github.com/devfile/devfile-web/tree/main/libs/docs/src/devfile-schemas). + + The filename **MUST** follow the convention `.json` where new version is a possible version. diff --git a/apps/landing-page/markdoc/tags.tsx b/apps/landing-page/markdoc/tags.tsx index c233caf0..4dc8f4ba 100644 --- a/apps/landing-page/markdoc/tags.tsx +++ b/apps/landing-page/markdoc/tags.tsx @@ -20,7 +20,6 @@ const tags = { src: { type: String }, alt: { type: String }, caption: { type: String }, - isZoomable: { type: Boolean, default: false }, hasBackground: { type: Boolean, default: false }, }, render: (props: { diff --git a/apps/landing-page/pages/404.tsx b/apps/landing-page/pages/404.tsx index c31f5d01..430eaba9 100644 --- a/apps/landing-page/pages/404.tsx +++ b/apps/landing-page/pages/404.tsx @@ -1,28 +1,12 @@ import { ChevronRightIcon } from '@heroicons/react/solid'; import { DevfileIcon, LandingPageMeta } from '@devfile-web/core'; -import { defaultVersion } from '@devfile-web/docs'; -import { useRouter } from 'next/router'; import Link from 'next/link'; import { custom404Navigation } from '../navigation'; export function Custom404(): JSX.Element { - const router = useRouter(); - - const isDocsPage = router.asPath === '/docs'; - return (
- - {isDocsPage && ( - el.name === 'Documentation').href ?? - `/docs/${defaultVersion}/what-is-a-devfile` - }`} - /> - )} - +
@@ -44,28 +28,28 @@ export function Custom404(): JSX.Element {
    {custom404Navigation.map((link) => ( -
  • -
    - - -
    -
    -

    - +
  • + +
    + + +
    +
    +

    {link.name} - -

    -

    - {link.description} -

    -
    -
    -
    +

    • +

    + {link.description} +

    +
    +
    +
    +
    • ))}
diff --git a/apps/landing-page/pages/docs/index.tsx b/apps/landing-page/pages/docs/index.tsx new file mode 100644 index 00000000..d6ff1424 --- /dev/null +++ b/apps/landing-page/pages/docs/index.tsx @@ -0,0 +1,19 @@ +import { LandingPageMeta } from '@devfile-web/core'; +import { defaultVersion } from '@devfile-web/docs'; +import { custom404Navigation } from '../../navigation'; + +export function Index(): JSX.Element { + return ( + + el.name === 'Documentation').href ?? + `/docs/${defaultVersion}/what-is-a-devfile` + }`} + /> + + ); +} + +export default Index; diff --git a/libs/core/src/components/header/header.tsx b/libs/core/src/components/header/header.tsx index 548ac15e..82e8197a 100644 --- a/libs/core/src/components/header/header.tsx +++ b/libs/core/src/components/header/header.tsx @@ -108,7 +108,9 @@ export function Header(): JSX.Element {
- {currentSection?.title} + + {currentSection?.title} + {currentPage?.title} diff --git a/libs/docs/src/scripts/build-directory/build-directory.ts b/libs/docs/src/scripts/build-directory/build-directory.ts index c956e361..faa91285 100644 --- a/libs/docs/src/scripts/build-directory/build-directory.ts +++ b/libs/docs/src/scripts/build-directory/build-directory.ts @@ -13,6 +13,8 @@ function buildDirectory(): void { fs.rmSync(outputDir, { recursive: true, force: true }); } + fs.copySync(`${nextjsDocsDir}/index.tsx`, `${outputDir}/index.tsx`); + docVersions.forEach((version) => { fs.copySync(`${sourceDir}/${version}`, `${outputDir}/${version}`, { overwrite: true }); fs.copySync(`${sourceDir}/no-version`, `${outputDir}/${version}`, { overwrite: true }); diff --git a/libs/docs/src/types/index.ts b/libs/docs/src/types/index.ts index 21409945..47d60571 100644 --- a/libs/docs/src/types/index.ts +++ b/libs/docs/src/types/index.ts @@ -1,6 +1,5 @@ export const docVersions = ['2.0.0', '2.1.0', '2.2.0-alpha'] as const; -// Update the redirect in app-sre when changing the default version export const defaultVersion: DocVersions = '2.1.0'; export const githubDocsUrl = 'https://github.com/devfile/devfile-web/tree/main/libs/docs/src/docs';