From 82e526729269c9d7c6f46ca7d5a9e47b2765b8fb Mon Sep 17 00:00:00 2001 From: thatmattlove Date: Mon, 26 Dec 2022 13:03:10 -0500 Subject: [PATCH] improve docs --- docs/favicon-formats.ts | 80 +++++++++++++++++++ docs/pages/_meta.json | 32 +++++++- docs/pages/configuration/_meta.json | 6 +- docs/pages/configuration/examples/_meta.json | 2 +- docs/pages/configuration/reference/_meta.json | 5 ++ .../index.mdx => reference/config.mdx} | 0 .../config}/_meta.json | 1 - .../config}/logging.mdx | 0 .../config}/web-ui.mdx | 2 +- .../devices.mdx} | 0 .../directives.mdx} | 0 docs/pages/index.mdx | 45 ++++++++++- docs/pages/introduction.mdx | 44 ---------- docs/theme.config.tsx | 57 ++++++++++++- docs/tsconfig.json | 6 +- 15 files changed, 222 insertions(+), 58 deletions(-) create mode 100644 docs/favicon-formats.ts create mode 100644 docs/pages/configuration/reference/_meta.json rename docs/pages/configuration/{config-file-reference/index.mdx => reference/config.mdx} (100%) rename docs/pages/configuration/{config-file-reference => reference/config}/_meta.json (69%) rename docs/pages/configuration/{config-file-reference => reference/config}/logging.mdx (100%) rename docs/pages/configuration/{config-file-reference => reference/config}/web-ui.mdx (99%) rename docs/pages/configuration/{devices-file-reference.mdx => reference/devices.mdx} (100%) rename docs/pages/configuration/{directives-file-reference.mdx => reference/directives.mdx} (100%) delete mode 100644 docs/pages/introduction.mdx diff --git a/docs/favicon-formats.ts b/docs/favicon-formats.ts new file mode 100644 index 0000000..15bcb9b --- /dev/null +++ b/docs/favicon-formats.ts @@ -0,0 +1,80 @@ +interface Favicon { + rel: string | null; + dimensions: [number, number]; + image_format: string; + prefix: string; +} + +export default [ + { dimensions: [64, 64], image_format: 'ico', prefix: 'favicon', rel: null }, + { dimensions: [16, 16], image_format: 'png', prefix: 'favicon', rel: 'icon' }, + { dimensions: [32, 32], image_format: 'png', prefix: 'favicon', rel: 'icon' }, + { dimensions: [64, 64], image_format: 'png', prefix: 'favicon', rel: 'icon' }, + { dimensions: [96, 96], image_format: 'png', prefix: 'favicon', rel: 'icon' }, + { dimensions: [180, 180], image_format: 'png', prefix: 'favicon', rel: 'icon' }, + { + dimensions: [57, 57], + image_format: 'png', + prefix: 'apple-touch-icon', + rel: 'apple-touch-icon', + }, + { + dimensions: [60, 60], + image_format: 'png', + prefix: 'apple-touch-icon', + rel: 'apple-touch-icon', + }, + { + dimensions: [72, 72], + image_format: 'png', + prefix: 'apple-touch-icon', + rel: 'apple-touch-icon', + }, + { + dimensions: [76, 76], + image_format: 'png', + prefix: 'apple-touch-icon', + rel: 'apple-touch-icon', + }, + { + dimensions: [114, 114], + image_format: 'png', + prefix: 'apple-touch-icon', + rel: 'apple-touch-icon', + }, + { + dimensions: [120, 120], + image_format: 'png', + prefix: 'apple-touch-icon', + rel: 'apple-touch-icon', + }, + { + dimensions: [144, 144], + image_format: 'png', + prefix: 'apple-touch-icon', + rel: 'apple-touch-icon', + }, + { + dimensions: [152, 152], + image_format: 'png', + prefix: 'apple-touch-icon', + rel: 'apple-touch-icon', + }, + { + dimensions: [167, 167], + image_format: 'png', + prefix: 'apple-touch-icon', + rel: 'apple-touch-icon', + }, + { + dimensions: [180, 180], + image_format: 'png', + prefix: 'apple-touch-icon', + rel: 'apple-touch-icon', + }, + { dimensions: [70, 70], image_format: 'png', prefix: 'mstile', rel: null }, + { dimensions: [270, 270], image_format: 'png', prefix: 'mstile', rel: null }, + { dimensions: [310, 310], image_format: 'png', prefix: 'mstile', rel: null }, + { dimensions: [310, 150], image_format: 'png', prefix: 'mstile', rel: null }, + { dimensions: [196, 196], image_format: 'png', prefix: 'favicon', rel: 'shortcut icon' }, +] as Favicon[]; diff --git a/docs/pages/_meta.json b/docs/pages/_meta.json index 83732a9..e80c0f4 100644 --- a/docs/pages/_meta.json +++ b/docs/pages/_meta.json @@ -1,7 +1,33 @@ { - "index": "hyperglass", - "introduction": "Introduction", + "index": { "title": "Introduction", "theme": { "breadcrumb": false } }, + "---": { + "type": "separator" + }, "installation": "Installation", "configuration": "Configuration", - "plugins": "Plugins" + "plugins": "Plugins", + "documentation": { + "title": "Documentation", + "type": "menu", + "items": { + "installation": { + "title": "Installation", + "href": "/installation" + }, + "configuration": { + "title": "Configuration", + "href": "/configuration" + }, + "plugins": { + "title": "Plugins", + "href": "/plugins" + } + } + }, + "demo": { + "title": "Demo", + "type": "page", + "href": "https://demo.hyperglass.dev", + "newWindow": true + } } diff --git a/docs/pages/configuration/_meta.json b/docs/pages/configuration/_meta.json index 35b4016..3c9a166 100644 --- a/docs/pages/configuration/_meta.json +++ b/docs/pages/configuration/_meta.json @@ -1,6 +1,4 @@ { - "examples": "Examples", - "config-file-reference": "Config File Reference", - "devices-file-reference": "Devices File Reference", - "directives-file-reference": "Directives File Reference" + "reference": "Reference", + "examples": "Examples" } diff --git a/docs/pages/configuration/examples/_meta.json b/docs/pages/configuration/examples/_meta.json index c9ce02f..afe5ba9 100644 --- a/docs/pages/configuration/examples/_meta.json +++ b/docs/pages/configuration/examples/_meta.json @@ -1,5 +1,5 @@ { - "add-your-own-command": "Add Your Own Command", "basic-configuration": "Basic Configuration", + "add-your-own-command": "Add Your Own Command", "customize-the-ui": "Customize the UI" } diff --git a/docs/pages/configuration/reference/_meta.json b/docs/pages/configuration/reference/_meta.json new file mode 100644 index 0000000..377c06b --- /dev/null +++ b/docs/pages/configuration/reference/_meta.json @@ -0,0 +1,5 @@ +{ + "config": "Config File", + "devices": "Devices File", + "directives": "Directives File" +} diff --git a/docs/pages/configuration/config-file-reference/index.mdx b/docs/pages/configuration/reference/config.mdx similarity index 100% rename from docs/pages/configuration/config-file-reference/index.mdx rename to docs/pages/configuration/reference/config.mdx diff --git a/docs/pages/configuration/config-file-reference/_meta.json b/docs/pages/configuration/reference/config/_meta.json similarity index 69% rename from docs/pages/configuration/config-file-reference/_meta.json rename to docs/pages/configuration/reference/config/_meta.json index a8cdcad..8124e7b 100644 --- a/docs/pages/configuration/config-file-reference/_meta.json +++ b/docs/pages/configuration/reference/config/_meta.json @@ -1,5 +1,4 @@ { - "index": "Config File", "logging": "Logging & Webhooks", "web-ui": "Web UI" } diff --git a/docs/pages/configuration/config-file-reference/logging.mdx b/docs/pages/configuration/reference/config/logging.mdx similarity index 100% rename from docs/pages/configuration/config-file-reference/logging.mdx rename to docs/pages/configuration/reference/config/logging.mdx diff --git a/docs/pages/configuration/config-file-reference/web-ui.mdx b/docs/pages/configuration/reference/config/web-ui.mdx similarity index 99% rename from docs/pages/configuration/config-file-reference/web-ui.mdx rename to docs/pages/configuration/reference/config/web-ui.mdx index 2a71069..7fa28ce 100644 --- a/docs/pages/configuration/config-file-reference/web-ui.mdx +++ b/docs/pages/configuration/reference/config/web-ui.mdx @@ -1,5 +1,5 @@ import { Callout } from 'nextra-theme-docs'; -import { Color } from '../../../components/color'; +import { Color } from '~/components/color'; ## Web UI diff --git a/docs/pages/configuration/devices-file-reference.mdx b/docs/pages/configuration/reference/devices.mdx similarity index 100% rename from docs/pages/configuration/devices-file-reference.mdx rename to docs/pages/configuration/reference/devices.mdx diff --git a/docs/pages/configuration/directives-file-reference.mdx b/docs/pages/configuration/reference/directives.mdx similarity index 100% rename from docs/pages/configuration/directives-file-reference.mdx rename to docs/pages/configuration/reference/directives.mdx diff --git a/docs/pages/index.mdx b/docs/pages/index.mdx index 8ae0569..f78a72e 100644 --- a/docs/pages/index.mdx +++ b/docs/pages/index.mdx @@ -1 +1,44 @@ -# Test +--- +title: Introduction +description: Get started with hyperglass +--- + +import Link from 'next/link'; +import { Button } from 'nextra/components'; + +## What is hyperglass? + +**hyperglass** is an open source network looking glass written by a network engineer for other network engineers. The purpose of a looking glass is to provide customers, peers, and complete strangers with unattended visibility into the an operator's network. + +hyperglass was created with the lofty goal of benefiting the internet community at-large by providing a faster, easier, and more secure way for operators to provide looking glass services to their customers, peers, and other network operators. + +## Features + +- BGP Route, BGP Community, BGP AS Path, Ping, & Traceroute +- Full IPv6 support +- Customizable everything: features, theme, UI/API text, error messages, commands +- Built in support for: + - Arista EOS + - BIRD + - Cisco IOS-XR + - Cisco IOS/IOS-XE + - Cisco NX-OS + - FRRouting + - Huawei + - Juniper JunOS + - Mikrotik + - Nokia SR OS + - TNSR + - VyOS +- Configurable support for any other [supported platform](platforms.mdx) +- Optionally access devices via an SSH proxy/jump server +- VRF support +- Access List/prefix-list style query control to whitelist or blacklist query targets on a per-VRF basis +- REST API with automatic, configurable OpenAPI documentation +- Modern, responsive UI +- Query multiple devices simultaneously +- Browser-based DNS-over-HTTPS resolution of FQDN queries + + + + diff --git a/docs/pages/introduction.mdx b/docs/pages/introduction.mdx deleted file mode 100644 index 29caff3..0000000 --- a/docs/pages/introduction.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Introduction -description: Welcome to hyperglass ---- - -import Link from 'next/link'; -import { Button } from 'nextra/components'; - -## What is hyperglass? - -**hyperglass** is an open source network looking glass written by a network engineer for other network engineers. The purpose of a looking glass is to provide customers, peers, and complete strangers with unattended visibility into the an operator's network. - -hyperglass was created with the lofty goal of benefiting the internet community at-large by providing a faster, easier, and more secure way for operators to provide looking glass services to their customers, peers, and other network operators. - -## Features - -- BGP Route, BGP Community, BGP AS Path, Ping, & Traceroute -- Full IPv6 support -- Customizable everything: features, theme, UI/API text, error messages, commands -- Built in support for: - - Arista EOS - - BIRD - - Cisco IOS-XR - - Cisco IOS/IOS-XE - - Cisco NX-OS - - FRRouting - - Huawei - - Juniper JunOS - - Mikrotik - - Nokia SR OS - - TNSR - - VyOS -- Configurable support for any other [supported platform](platforms.mdx) -- Optionally access devices via an SSH proxy/jump server -- VRF support -- Access List/prefix-list style query control to whitelist or blacklist query targets on a per-VRF basis -- REST API with automatic, configurable OpenAPI documentation -- Modern, responsive UI -- Query multiple devices simultaneously -- Browser-based DNS-over-HTTPS resolution of FQDN queries - - - - diff --git a/docs/theme.config.tsx b/docs/theme.config.tsx index 804c4e6..f02c0de 100644 --- a/docs/theme.config.tsx +++ b/docs/theme.config.tsx @@ -1,5 +1,7 @@ import styles from './global.module.css'; -import { DocsThemeConfig } from 'nextra-theme-docs'; +import { useRouter } from 'next/router'; +import { useConfig, type DocsThemeConfig } from 'nextra-theme-docs'; +import faviconFormats from './favicon-formats'; const NO_INDEX_FOLLOW = process.env.CF_PAGES_BRANCH !== 'main'; @@ -68,10 +70,61 @@ const config: DocsThemeConfig = { ), + + useNextSeoProps: () => { + const { asPath } = useRouter(); + const { frontMatter, title } = useConfig(); + return { + titleTemplate: '%s | hyperglass', + title: frontMatter.title || title, + openGraph: { + type: 'website', + url: `https://hyperglass.dev${asPath}`, + title: frontMatter.title || title, + description: frontMatter.description || 'hyperglass Documentation', + images: [ + { + url: 'https://hyperglass.dev/opengraph.jpg', + width: 1200, + height: 630, + alt: 'hyperglass', + }, + ], + }, + twitter: { handle: '@thatmattlove', site: '@thatmattlove', cardType: 'summary_large_image' }, + noindex: NO_INDEX_FOLLOW, + nofollow: NO_INDEX_FOLLOW, + additionalLinkTags: faviconFormats.map(fmt => { + const { image_format, dimensions, prefix, rel } = fmt; + const [w, h] = dimensions; + const href = `/img/${prefix}-${w}x${h}.${image_format}`; + return { rel: rel ?? '', href, type: `image/${image_format}` }; + }), + }; + }, + banner: { + dismissible: true, + text: '🎉 hyperglass 2.0 is here!', + }, + feedback: { content: null }, + footer: { text: `© ${new Date().getFullYear()} hyperglass` }, + chat: { + link: 'https://netdev.chat/', + icon: ( + + + + ), + }, project: { link: 'https://github.com/thatmattlove/hyperglass', }, - useNextSeoProps: () => ({ noindex: NO_INDEX_FOLLOW, nofollow: NO_INDEX_FOLLOW }), }; export default config; diff --git a/docs/tsconfig.json b/docs/tsconfig.json index 5ea7cff..4f2a7e0 100644 --- a/docs/tsconfig.json +++ b/docs/tsconfig.json @@ -15,8 +15,12 @@ "resolveJsonModule": true, "isolatedModules": true, "jsx": "preserve", - "incremental": true + "incremental": true, + "paths": { + "~/*": ["./*"] + } }, + "exclude": ["node_modules", ".next"], "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", "next.config.js"] }