diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 252a914..cdf336c 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -2,7 +2,7 @@ name: Deploy to GitHub Pages on: # Trigger the workflow every time you push to the `main` branch - # Using a different branch name? Replace `main` with your branch’s name + # Using a different branch name? Replace `main` with your branch's name push: branches: [ main ] # Allows you to run this workflow manually from the Actions tab on GitHub. diff --git a/.vscode/doc.code-snippets b/.vscode/doc.code-snippets index 0bfdbb8..a043e85 100644 --- a/.vscode/doc.code-snippets +++ b/.vscode/doc.code-snippets @@ -6,7 +6,7 @@ "title: $1", "author: hyperoot", "pubDatetime: $2 #2024-04-09T12:00:00-05:30", - "# modDatetime: ''", + "# modDatetime: ", "# description: ''", "draft: true", "#tags:", diff --git a/astro.config.mjs b/astro.config.mjs index be0f6b8..ccdb54a 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -29,7 +29,7 @@ export default defineConfig({ applyBaseStyles: false, }), mdx({ - gfm: false, + gfm: true, }), ], }); diff --git a/config.ts b/config.ts index 219deed..6c43497 100644 --- a/config.ts +++ b/config.ts @@ -1,7 +1,7 @@ export const SITE = { website: "https://hyperoot.dev", // replace this with your deployed domain author: "HYP3R00T", - desc: "Documentation theme using Astro and Shadcn", + desc: "Documentation template using Astro and Shadcn", title: "CelestialDocs", ogImage: "og-image.jpg", repo: "https://github.com/HYP3R00T/CelestialDocs", @@ -20,16 +20,22 @@ export const menu_items: { title: string; href: string }[] = [ ]; // Just works with top-level folders and files. For files, don't add extension as it looks for the slug, and not the file name. -export const side_nav_menu_order: string[] = ["getting-started"]; +export const side_nav_menu_order: string[] = [ + "getting-started", + "guides", + "custom-components", + "reference", +]; // Don't delete anything. You can use 'true' or 'false'. // These are global settings export const docconfig = { hide_table_of_contents: false, hide_breadcrumbs: false, - hide_side_navinations: false, + hide_side_navigations: false, hide_datetime: false, hide_time: true, hide_search: false, hide_repo_button: false, + hide_author: false, }; diff --git a/sample.csv b/sample.csv deleted file mode 100644 index dd03c4d..0000000 --- a/sample.csv +++ /dev/null @@ -1,56 +0,0 @@ -Latte -Rosewater ,11 59% 67% -Flamingo ,0 60% 67% -Pink ,316 73% 69% -Mauve ,266 85% 58% -Red ,347 87% 44% -Maroon ,355 76% 59% -Peach ,22 99% 52% -Yellow ,35 77% 49% -Green ,109 58% 40% -Teal ,183 74% 35% -Sky ,197 97% 46% -Sapphire ,189 70% 42% -Blue ,220 91% 54% -Lavender ,231 97% 72% -Text ,234 16% 35% -Subtext 1 ,233 13% 41% -Subtext 0 ,233 10% 47% -Overlay 2 ,232 10% 53% -Overlay 1 ,231 10% 59% -Overlay 0 ,228 11% 65% -Surface 2 ,227 12% 71% -Surface 1 ,225 14% 77% -Surface 0 ,223 16% 83% -Base ,220 23% 95% -Mantle ,220 22% 92% -Crust ,220 21% 89% - - -Macchiato -Rosewater ,10 58% 90% -Flamingo ,0 58% 86% -Pink ,316 74% 85% -Mauve ,267 83% 80% -Red ,351 74% 73% -Maroon ,355 71% 77% -Peach ,21 86% 73% -Yellow ,40 70% 78% -Green ,105 48% 72% -Teal ,171 47% 69% -Sky ,189 59% 73% -Sapphire ,199 66% 69% -Blue ,220 83% 75% -Lavender ,234 82% 85% -Text ,227 68% 88% -Subtext 1 ,228 39% 80% -Subtext 0 ,227 27% 72% -Overlay 2 ,228 20% 65% -Overlay 1 ,228 15% 57% -Overlay 0 ,230 12% 49% -Surface 2 ,230 14% 41% -Surface 1 ,231 16% 34% -Surface 0 ,230 19% 26% -Base ,232 23% 18% -Mantle ,233 23% 15% -Crust ,236 23% 12% \ No newline at end of file diff --git a/src/components/core/HamNavMenu.astro b/src/components/core/HamNavMenu.astro index c0a1c9b..4589eca 100644 --- a/src/components/core/HamNavMenu.astro +++ b/src/components/core/HamNavMenu.astro @@ -55,7 +55,7 @@ const pathname_part: string = pathname.split("/")[1]; )) } { - !docconfig.hide_side_navinations && ( + !docconfig.hide_side_navigations && (
diff --git a/src/components/core/Search.tsx b/src/components/core/Search.tsx index e4f728b..2c358e0 100644 --- a/src/components/core/Search.tsx +++ b/src/components/core/Search.tsx @@ -34,7 +34,7 @@ const options: IFuseOptions = { keys: [ { name: "id", weight: 2.5 }, { name: "slug", weight: 2.5 }, - { name: "body", weight: 1.5 }, + { name: "body", weight: 1 }, { name: "title", weight: 2, @@ -45,6 +45,11 @@ const options: IFuseOptions = { weight: 1.75, getFn: (docs: DocsEntry) => docs.data.description || "", }, + { + name: "tags", + weight: 1.5, + getFn: (docs: DocsEntry) => docs.data.tags.join(" ") || "", + }, ], }; diff --git a/src/components/docs/MainContent.astro b/src/components/docs/MainContent.astro index 2b09e4e..004228f 100644 --- a/src/components/docs/MainContent.astro +++ b/src/components/docs/MainContent.astro @@ -35,6 +35,7 @@ const { /> ) } + {!docconfig.hide_author &&
By {author}
}
diff --git a/src/components/docs/SideNavMenu.astro b/src/components/docs/SideNavMenu.astro index 8b55c9e..4dd0171 100644 --- a/src/components/docs/SideNavMenu.astro +++ b/src/components/docs/SideNavMenu.astro @@ -11,27 +11,29 @@ const { class: className } = Astro.props;
    { - items.map((item) => { - const label = item.title - ? capitalizeFirstLetter(item.title) - : capitalizeFirstLetter(item.slug.split("/").pop() || ""); - const className = ` - ${level === 0 ? "font-bold" : "font-normal"} + items + .filter((item) => !item.draft) + .map((item) => { + const label = item.title + ? capitalizeFirstLetter(item.title) + : capitalizeFirstLetter(item.slug.split("/").pop() || ""); + const className = ` + ${level === 0 ? "font-semibold" : "text-muted-foreground"} ${pathname === "/" + item.slug ? "text-primary" : "no-underline"} `.trim(); - return ( -
  • - - {label} - - {item.children.length > 0 && ( - - )} -
    • - ); - }) + return ( +
  • + + {label} + + {item.children.length > 0 && ( + + )} +
    • + ); + }) }
diff --git a/src/content/docs/Custom Components/Callout.mdx b/src/content/docs/Custom Components/Callout.mdx new file mode 100644 index 0000000..bed7a1f --- /dev/null +++ b/src/content/docs/Custom Components/Callout.mdx @@ -0,0 +1,91 @@ +--- +title: Callout +--- +import Callout from "@/components/Callout.astro"; + + +## Callout + +The `Callout` component is designed to highlight important information, warnings, errors, or successes in your application. It is a versatile alert box with customizable variants and titles. + +### Props + +**`variant`** + +Type: `"info" | "warning" | "danger" | "success"` + +Default: "info" + +Description: Defines the type of alert to display. The variant determines the color, icon, and default title of the alert. + +**`title`** + +Type: `string` + +Default: Default titles based on the variant + +Description: Custom title for the alert. If not provided, the default title for the specified variant will be used. + +### Basic Usage +To use the Callout component, import it and use it in your Astro files with the desired variant and title. + + + This is an info message. + + + + This is a warning message with a custom title. + + + + This is a danger message. + + + + This is a success message with a custom title. + + +```astro +--- +import Callout from './components/Callout.astro'; +--- + + + + This is an info message. + + + + + This is a warning message with a custom title. + + + + + This is a danger message. + + + + + This is a success message with a custom title. + +``` + +### Default Behavior + +If no variant is provided, the info variant will be used by default. Similarly, if no title is provided, the default title for the specified variant will be used. + + + This is an info message using the default settings. + + +```astro +--- +import Callout from './components/Callout.astro'; +--- + + + + This is an info message using the default settings. + +``` \ No newline at end of file diff --git a/src/content/docs/Custom Components/index.mdx b/src/content/docs/Custom Components/index.mdx new file mode 100644 index 0000000..24c5d10 --- /dev/null +++ b/src/content/docs/Custom Components/index.mdx @@ -0,0 +1,14 @@ +--- +title: Components +--- +import Callout from "@/components/Callout.astro"; + +Components let you easily reuse a piece of UI or styling consistently. Examples might include a link card or a YouTube embed. CelestialDocs supports the use of components in [MDX](https://mdxjs.com/) files and provides some common components for you to use. + +## Callout + +The `Callout` component is designed to highlight important information, warnings, errors, or successes in your application. It is a versatile alert box with customizable variants and titles. + + + See the [Callout](/custom-components/callout) for all custom props and their usages. + diff --git a/src/content/docs/Guides/authoring-content-in-md.mdx b/src/content/docs/Guides/authoring-content-in-md.mdx new file mode 100644 index 0000000..20b0ef9 --- /dev/null +++ b/src/content/docs/Guides/authoring-content-in-md.mdx @@ -0,0 +1,166 @@ +--- +title: Authoring Content in Markdown +--- + +CelestialDocs supports the full range of Markdown syntax in `.md` files as well as frontmatter YAML to define metadata such as a tilte and description. + +## Frontmatter + +You can modify individual pages in CelestialDocs by setting values in their fromtmatter. Frontmetter is set at the top of your files between `---` separators. + +```md +--- +title: Sample +--- + +Page content goes here, after `---`. +``` + +Every page must include at least a `title`. See the [frontmatter reference](/reference/frontmatter-ref) for all available fields and how to add custom fields. + +## Inline styles + +Text can be **bold**, _italic_ or ~~strikethrough~~. + +```md +Text can be **bold**, _italic_ or ~~strikethrough~~. +``` + +You can [link to another page](/getting-started). + +```md +You can [link to another page](/getting-started). +``` + +You can highlight `inline code` with backticks. + +```md +You can highlight `inline code` with backticks. +``` + +## Images + +Images in CelestialDocs use [Astro's built-in optimized asset support](https://docs.astro.build/en/guides/images/). + +Markdown and MDX support the Markdown syntax for displaying images that includes alt-text for screen readers and assistive technology. + +![An illustration of planets and stars featuring the word “astro”](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png) + +```md +![An illustration of planets and stars featuring the word “astro”](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png) +``` + +Relative image paths are also supported for images stored locally in your project. + +![A kitty in space](../../../assets/KittyAstronaut.svg) + +```md +![A kitty in space](../../../assets/KittyAstronaut.svg) +``` + +## Headings + +You can structure content using a heading. Headings in Markdown are indicated by a number of # at the start of the line. + +### How to structure page content in CelestialDocs + +CelestialDocs is configured to automatically use your page title as a top-level heading and will include an “Overview” heading at top of each page's table of contents. We recommend starting each page with regular paragraph text content and using on-page headings from `

` and down: + +```md +--- +title: Markdown Guide +description: How to use Markdown in CelestialDocs +--- + +This page describes how to use Markdown in CelestialDocs. + +## Inline Styles + +## Headings +``` + +### Automatic heading anchor links + +Using headings in Markdown will automatically give you anchor links so you can link directly to certain sections of your page: + +``` +--- +title: My page of content +description: How to use CelestialDocs's built-in anchor links +--- + +## Introduction + +I can link to [my conclusion](#conclusion) lower on the same page. + +## Conclusion + +`https://my-site.com/page1/#introduction` navigates directly to my Introduction. +``` + +Level 2 (`

`) and Level 3 (`

`) headings will automatically appear in the page table of contents. + +Learn more about how Astro processes heading ids in the [Astro Documentation](https://docs.astro.build/en/guides/markdown-content/#heading-ids). + +## Blockquotes + +> This is a blockquote, which is commonly used when quoting another person or document. +> +> Blockquotes are indicated by a `>` at the start of each line. + +```md +> This is a blockquote, which is commonly used when quoting another person or document. +> +> Blockquotes are indicated by a `>` at the start of each line. +``` + +## Code blocks + +A code block is indicated by a block with three backticks ``` at the start and end. You can indicate the programming language being used after the opening backticks. + +```js +// Javascript code with syntax highlighting. +var fun = function lang(l) { + dateformat.i18n = require('./lang/' + l); + return true; +}; +``` + + +````text +```js +// Javascript code with syntax highlighting. +var fun = function lang(l) { + dateformat.i18n = require('./lang/' + l); + return true; +}; +``` +```` + +## Details + +Details (also known as “disclosures” or “accordions”) are useful to hide content that is not immediately relevant. Users can click a short summary to expand and view the full content. + +Use the standard HTML `
` and `` elements in your Markdown content to create a disclosure widget. + +You can nest any other Markdown syntax inside a `
` element. + +
+Where and when is the Andromeda constellation most visible? + +The [Andromeda constellation]() is most visible in the night sky during the month of November at latitudes between `+90°` and `-40°`. + +
+ +```html +
+Where and when is the Andromeda constellation most visible? + +The [Andromeda constellation]() is most visible in the night sky during the month of November at latitudes between `+90°` and `-40°`. + +
+``` + +## Other common Markdown features + +CelestialDocs supports all other Markdown authoring syntax, such as lists and tables. See the [Markdown Cheat Sheet from The Markdown Guide](https://www.markdownguide.org/cheat-sheet/) for a quick overview of all the Markdown syntax elements. \ No newline at end of file diff --git a/src/content/docs/Guides/authoring-content-in-mdx.mdx b/src/content/docs/Guides/authoring-content-in-mdx.mdx new file mode 100644 index 0000000..5f6e445 --- /dev/null +++ b/src/content/docs/Guides/authoring-content-in-mdx.mdx @@ -0,0 +1,117 @@ +--- +title: Authoring Content in MDX +--- + +CelestialDocs supports [MDX](https://mdxjs.com/) files, which extend Markdown by allowing the inclusion of React components within your content. This enables dynamic and interactive documentation. We specifically use [GitHub flavored markdown (GFM)](https://mdxjs.com/guides/gfm/). Markdown features, refer to the [Markdown documentation](/guides/authoring-content-in-md). + +## Using a component + +You can use a component by importing it into your MDX file and then rendering it as a JSX tag. These look like HTML tags but start with an uppercase letter matching the name in your import statement: + +```mdx +--- +title: Welcome to my docs +--- + +import Callout from "@/components/Callout.astro"; + + +Sample callout + +``` + +See the [components](/guides/components) for all custom components and their available fields. + +## Using GFM (GitHub-Flavored Markdown) + +MDX in CelestialDocs supports [GitHub flavored markdown (GFM)](https://mdxjs.com/guides/gfm/), which includes additional features such as tables, task lists, and strikethrough text. + +### Task Lists + +You can create task lists using GFM syntax. + +- [x] Task 1 +- [ ] Task 2 +- [ ] Task 3 + +```md +- [x] Task 1 +- [ ] Task 2 +- [ ] Task 3 +``` + +### Tables + +You can also create tables using GFM. + +| Syntax | Description | +| --------- | ----------- | +| Header | Title | +| Paragraph | Text | + +```md +| Syntax | Description | +| --------- | ----------- | +| Header | Title | +| Paragraph | Text | +``` +### Strikethrough + +Strikethrough text can be created using double tilde `~~`. + +This is ~~strikethrough~~ text. + +```md +This is ~~strikethrough~~ text. +``` + +## Frontmatter + +MDX files support frontmatter in the same way as Markdown files. You can define metadata at the top of the file. + +```mdx +--- +title: Sample MDX Page +--- + +Page content goes here, after `---`. +``` + +Refer to the frontmatter reference for all available fields and how to add custom fields. + +## Using JavaScript Expressions + +MDX allows you to use JavaScript expressions within your content. This can be useful for dynamic content and calculations. + +Current year: {new Date().getFullYear()} + +```mdx +Current year: {new Date().getFullYear()} +``` + + +```mdx +**Fibonacci Sequence** + +The first 10 numbers in the Fibonacci sequence are: + +{ + Array.from({ length: 10 }).map((_, i) => ( + {fibonacci(i)} + )) +} +``` + +## Syntax Highlighting + +MDX supports syntax highlighting for code blocks using backticks. You can specify the language for proper highlighting. + +````mdx +```jsx +const MyComponent = () => { + return
Hello, MDX!
; +}; +``` +```` + +MDX combines the best of Markdown and JSX, making it a powerful tool for creating rich, interactive documentation. For more details on Markdown syntax, please see the [Markdown documentation](/guides/authoring-content-in-md). \ No newline at end of file diff --git a/src/content/docs/Guides/breadcrumbs.mdx b/src/content/docs/Guides/breadcrumbs.mdx index c49bd03..3b70b93 100644 --- a/src/content/docs/Guides/breadcrumbs.mdx +++ b/src/content/docs/Guides/breadcrumbs.mdx @@ -22,7 +22,8 @@ export const docconfig = { ### Hide locally To hide ToC for specific pages only, then add `hide_breadcrumbs` in the frontmatter as `true`. -``` + +```yaml --- hide_breadcrumbs: true --- diff --git a/src/content/docs/Guides/index.mdx b/src/content/docs/Guides/index.mdx index a4df17b..9af6bf7 100644 --- a/src/content/docs/Guides/index.mdx +++ b/src/content/docs/Guides/index.mdx @@ -1,8 +1,12 @@ --- title: Guides --- +Our Guides section offers in-depth tutorials and instructions on various features and best practices. Explore these guides to enhance your knowledge and make the most out of your documentation setup. -- [Breadcrumbs](/guides/breadcrumbs) -- [Sidebar Navigation](/guides/sidebar-navigation) -- [Site Search](/guides/site-search) -- [Table of Contents](/guides/table-of-contents) \ No newline at end of file +- [Authoring Content in Markdown](./authoring-content-in-md.mdx): Learn how to author content using Markdown. +- [Authoring Content in MDX](./authoring-content-in-mdx.mdx): Discover how to use MDX for more dynamic content. +- [Breadcrumbs](./breadcrumbs.mdx): Understand how to implement breadcrumbs for better navigation. +- [Pages](./pages.mdx): A guide on managing and creating pages in your documentation. +- [Sidebar Navigation](./sidebar-navigation.mdx): Learn about configuring sidebar navigation for a better user experience. +- [Site Search](./site-search.mdx): Instructions on adding search functionality to your site. +- [Table of Contents](./table-of-contents.mdx): How to add and configure a Table of Contents for your documentation. \ No newline at end of file diff --git a/src/content/docs/Guides/pages.mdx b/src/content/docs/Guides/pages.mdx new file mode 100644 index 0000000..6b262b8 --- /dev/null +++ b/src/content/docs/Guides/pages.mdx @@ -0,0 +1,39 @@ +--- +title: Pages +--- + +CelestialDocs creates your site's HTML pages from your content, offering flexible options through Markdown frontmatter. Additionally, CelestialDocs projects have complete access to [Astro's robust page generation tools](https://docs.astro.build/en/basics/astro-pages/). This guide explains how page generation works in CelestialDocs. + +## Content pages + +### File formats + +CelestialDocs supports authoring content in Markdown and MDX with no configuration required. + +### Add pages + +Add new pages to your site by creating `.md` or `.mdx` files in `src/content/docs/`. Use sub-folders to organize your files and to create multiple path segments. + +### Type-safe frontmatter + +All CelestialDocs pages share a customizable set of frontmatter properties that control their appearance: + +```yaml +--- +title: Sample +author: hyperoot +pubDatetime: 2024-04-09T12:00:00-05:30 +modDatetime: 2024-08-01T12:00:00-05:30 +description: 'Sample description' +draft: true +tags: +- anything +- you +- want +hide_toc: +hide_sidenav: +hide_breadcrumbs: +--- +``` + +A snippet template is also included with this project if you are using vscode. Just type `docs` in any `.md` or `.mdx` file and you will see a suggestion for a template named `docs`. Most of the frontmatter properties are commented. Uncomment them by removing `#`. For date and time we use [standard date-time string format](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format). \ No newline at end of file diff --git a/src/content/docs/Guides/sidebar-navigation.mdx b/src/content/docs/Guides/sidebar-navigation.mdx index 5c47a01..c3796c3 100644 --- a/src/content/docs/Guides/sidebar-navigation.mdx +++ b/src/content/docs/Guides/sidebar-navigation.mdx @@ -23,14 +23,14 @@ You can include `folder-name`, `md` & `mdx` files. If you don't order every item ### Hide globally -In `config.js`, you can hide sidebar navigation by keeping the value of `hide_side_navinations` as `true`. This will hide the sidebar navigation for all pages. +In `config.js`, you can hide sidebar navigation by keeping the value of `hide_side_navigations` as `true`. This will hide the sidebar navigation for all pages. ```js // config.js export const docconfig = { ... - hide_side_navinations: true, + hide_side_navigations: true, ... }; ``` @@ -38,7 +38,8 @@ export const docconfig = { ### Hide locally To hide sidebar navigation for specific pages only, then add `hide_sidenav` in the frontmatter as `true`. -``` + +```yaml --- hide_sidenav: true --- diff --git a/src/content/docs/Guides/table-of-contents.mdx b/src/content/docs/Guides/table-of-contents.mdx index 2f65837..a7b4326 100644 --- a/src/content/docs/Guides/table-of-contents.mdx +++ b/src/content/docs/Guides/table-of-contents.mdx @@ -28,7 +28,8 @@ export const docconfig = { ### Hide locally To hide ToC for specific pages only, then add `hide_toc` in the frontmatter as `true`. -``` + +```yaml --- hide_toc: true --- diff --git a/src/content/docs/Reference/configuration-ref.mdx b/src/content/docs/Reference/configuration-ref.mdx new file mode 100644 index 0000000..30e3fa4 --- /dev/null +++ b/src/content/docs/Reference/configuration-ref.mdx @@ -0,0 +1,132 @@ +--- +title: Configuration Reference +--- + +This document describes the available configuration options for your site. These settings are defined in the `config.ts` file and control various aspects of your site's behavior and appearance. Below is a detailed reference for each configuration property, including examples where applicable. + +## Site Configuration + +### `website` +- **Type**: `string` +- **Description**: The URL of your site. Replace this with the deployed domain of your site to direct users to the correct address. +- **Example**: `"https://hyperoot.dev"` + +### `author` +- **Type**: `string` +- **Description**: The name of the author or creator of the site. This value will be used to attribute content and provide credit. +- **Example**: `"HYP3R00T"` + +### `desc` +- **Type**: `string` +- **Description**: A brief description of your site. This summary provides context and information about the purpose and content of the site. +- **Example**: `"Documentation template using Astro and Shadcn"` + +### `title` +- **Type**: `string` +- **Description**: The title of your site. This will be displayed in the browser tab and used for branding purposes. +- **Example**: `"CelestialDocs"` + +### `ogImage` +- **Type**: `string` +- **Description**: The filename of the image used for Open Graph (OG) sharing. This image will be shown when your site is shared on social media platforms. +- **Example**: `"og-image.jpg"` + +### `repo` +- **Type**: `string` +- **Description**: The URL to the repository hosting the source code of your site. This provides a link to where the site's code can be found. +- **Example**: `"https://github.com/HYP3R00T/CelestialDocs"` + +## Locale Configuration + +### `lang` +- **Type**: `string` +- **Default**: `"en"` +- **Description**: The HTML language code for your site. Set this to specify the language used for the content. If left empty, it defaults to `"en"`. +- **Example**: `"en"` (for English) + +### `langTag` +- **Type**: `array of strings` +- **Default**: `["en-EN"]` +- **Description**: BCP 47 language tags used to specify the language and regional variations. Set this to customize the language settings. An empty array defaults to the environment's default language. +- **Example**: `["en-EN"]` for English (United Kingdom) + +## Menu Configuration + +### `menu_items` +- **Type**: `array of objects` +- **Description**: An array of menu items for the site's navigation. Each item should have a `title` and `href` to define the menu link. This is currently empty but can be populated to create navigation links. +- **Example**: + ```ts + export const menu_items = [ + { title: "Home", href: "/" }, + { title: "About", href: "/about" }, + { title: "Contact", href: "/contact" }, + ]; + ``` + +## Sidebar Navigation Configuration + +### `side_nav_menu_order` +- **Type**: `array of strings` +- **Description**: An array defining the order of items in the sidebar navigation. The list should contain top-level folders and files (without extensions) to organize the sidebar menu. +- **Example**: + ```ts + export const side_nav_menu_order = [ + "getting-started", + "guides", + "custom-components", + "reference", + ]; + ``` + +## Global Settings + +### `hide_table_of_contents` +- **Type**: `boolean` +- **Default**: `false` +- **Description**: Controls whether the Table of Contents (ToC) is hidden. Set this to `true` to prevent the ToC from being displayed. +- **Example**: `true` (to hide the ToC) + +### `hide_breadcrumbs` +- **Type**: `boolean` +- **Default**: `false` +- **Description**: Determines whether breadcrumbs should be hidden. Setting this to `true` will hide breadcrumbs from the site's pages. +- **Example**: `true` (to hide breadcrumbs) + +### `hide_side_navigations` +- **Type**: `boolean` +- **Default**: `false` +- **Description**: Controls whether sidebar navigation should be hidden. Setting this to `true` will hide the sidebar. +- **Example**: `true` (to hide sidebar navigation) + +### `hide_datetime` +- **Type**: `boolean` +- **Default**: `false` +- **Description**: Indicates whether the date and time should be hidden. If set to `true`, date and time information will not be displayed. +- **Example**: `true` (to hide date and time) + +### `hide_time` +- **Type**: `boolean` +- **Default**: `true` +- **Description**: Controls whether the time should be hidden. This is set to `true` by default to omit time information from being shown. +- **Example**: `false` (to show time) + +### `hide_search` +- **Type**: `boolean` +- **Default**: `false` +- **Description**: Determines if the search functionality should be hidden. Setting this to `true` will remove the search feature from the site. +- **Example**: `true` (to hide the search feature) + +### `hide_repo_button` +- **Type**: `boolean` +- **Default**: `false` +- **Description**: Controls whether the repository button is hidden. If set to `true`, the button linking to the repository will not be displayed. +- **Example**: `true` (to hide the repository button) + +### `hide_author` +- **Type**: `boolean` +- **Default**: `false` +- **Description**: Specifies whether the author's information should be hidden. Setting this to `true` will prevent the author's details from being shown. +- **Example**: `true` (to hide author information) + +This reference guide provides a comprehensive overview of the configuration options available for your site. Adjust these settings as needed to customize the appearance and behavior of your site according to your preferences. \ No newline at end of file diff --git a/src/content/docs/Reference/frontmatter-ref.mdx b/src/content/docs/Reference/frontmatter-ref.mdx new file mode 100644 index 0000000..0494a85 --- /dev/null +++ b/src/content/docs/Reference/frontmatter-ref.mdx @@ -0,0 +1,71 @@ +--- +title: Frontmatter Reference +--- + +You can customize individual Markdown and MDX pages in CelestialDocs by setting values in their frontmatter. For example, a regular page might set `title` and `description` fields. + +```md +--- +title: Sample +description: Sample description +--- + +Page content goes here, after `---`. +``` + +This document describes the available frontmatter properties for your content files. Frontmatter is a block of metadata that provides context and configuration for your content. Below is a detailed reference for each property, including their types, default values, and descriptions. + +## Properties + +### `title` +- **Type**: `string` +- **Description**: The title of the content. This is a required field that represents the main heading or name of your document. + +### `author` +- **Type**: `string` +- **Default**: The author defined in the site configuration (`SITE.author`) +- **Description**: The name of the person or entity responsible for creating the content. If not specified, it defaults to the author defined in the site's configuration. + +### `pubDatetime` +- **Type**: `Date` (optional) +- **Description**: The date and time when the content was published. This field is optional and can be used to specify when the content was made available. + +### `modDatetime` +- **Type**: `Date` (optional, nullable) +- **Description**: The date and time when the content was last modified. This field is optional and can be null if no modification has occurred. It helps track the latest changes made to the content. + +### `description` +- **Type**: `string` (optional) +- **Description**: A brief summary or description of the content. This optional field provides additional context or a teaser for the document. + +### `draft` +- **Type**: `boolean` +- **Default**: `false` +- **Description**: Indicates whether the content is a draft. If set to `true`, the content is considered a draft and may not be published or visible on the site. + +### `tags` +- **Type**: `array of strings` +- **Default**: `[]` (empty array) +- **Description**: A list of tags associated with the content. Tags can be used for categorization and filtering purposes. The default is an empty array, meaning no tags are assigned unless specified. + +### `hide_breadcrumbs` +- **Type**: `boolean` (optional) +- **Default**: `false` +- **Description**: Determines whether breadcrumbs should be hidden for the content. If set to `true`, breadcrumbs will not be displayed. This is useful for customizing the navigation experience. + +### `hide_toc` +- **Type**: `boolean` (optional) +- **Default**: `false` +- **Description**: Specifies whether the Table of Contents (ToC) should be hidden. Setting this to `true` will prevent the ToC from being shown, allowing for a cleaner layout if the ToC is not needed. + +### `hide_sidenav` +- **Type**: `boolean` (optional) +- **Default**: `false` +- **Description**: Indicates whether the sidebar navigation should be hidden. If set to `true`, the sidebar will not be displayed, which can be useful for pages where a sidebar is unnecessary. + +### `max_width` +- **Type**: `boolean` (optional) +- **Default**: `false` +- **Description**: Controls whether the content should use the maximum available width. Setting this to `true` allows the content to stretch to the full width of the container, providing a more expansive layout. + +This reference guide should help you configure the frontmatter for your content effectively. Adjust these properties to control various aspects of how your content is presented and organized. \ No newline at end of file diff --git a/src/content/docs/Resources/deployment.mdx b/src/content/docs/Resources/deployment.mdx new file mode 100644 index 0000000..baabcc2 --- /dev/null +++ b/src/content/docs/Resources/deployment.mdx @@ -0,0 +1,65 @@ +--- +title: Deploy your Documentation +--- + +Deploying your site is straightforward with CelestialDocs. This guide will help you set up deployment using GitHub Actions and configure your domain with a CNAME file. Follow the steps below to get your site live. + +## Deploying with GitHub Actions + +CelestialDocs includes a `deploy.yml` file configured for GitHub Actions to automate the deployment process. Here's how you can use it: + +**Steps:** + +- Add the `deploy.yml` File + + Make sure the `deploy.yml` file is included in your project under the .github/workflows directory. This file contains the workflow configuration to handle the deployment. + +- Configure Your GitHub Repository + + Ensure that your GitHub repository is correctly set up to use GitHub Actions. You may need to grant the necessary permissions and configure your repository settings to enable deployments. + +- Set Up Deployment Secrets + +If your deployment requires secrets (e.g., API keys, deployment tokens), add them to your GitHub repository settings: + + - Go to your repository on GitHub. + - Navigate to Settings > Secrets and variables > Actions. + - Add your secrets here. For example, you might need to add deployment tokens or API keys for your hosting provider. + +- Trigger the Deployment + + Once the `deploy.yml` file is in place and your secrets are configured, any push to the main branch (or the branch specified in the workflow) will trigger the deployment. GitHub Actions will automatically build and deploy your site based on the configuration in `deploy.yml`. + +### Adding a CNAME File +If you're using a custom domain, you need to include a CNAME file in the public directory of your project. This file ensures that your site is correctly mapped to your custom domain. + +**Steps:** + +- Create the CNAME File + + In the public directory of your project, create a file named CNAME (with no file extension). + +- Add Your Domain Name + + Open the CNAME file and add your custom domain name. For example: + + ``` + www.yourcustomdomain.com + ``` +- Commit and Push + + After creating the CNAME file, commit your changes and push them to your repository: + + ```bash + git add public/CNAME + git commit -m "Add CNAME file for custom domain" + git push origin main + ``` + +- Verify Domain Configuration + + Ensure that your domain is correctly configured with your DNS provider to point to your deployment. This usually involves setting up DNS records such as A records or CNAME records to match your hosting provider's requirements. + +## Deploy with other services + +Publish your work with the [Deploy your site](https://docs.astro.build/en/guides/deploy/) guide in the Astro docs. \ No newline at end of file diff --git a/src/content/docs/Resources/index.mdx b/src/content/docs/Resources/index.mdx new file mode 100644 index 0000000..55d1983 --- /dev/null +++ b/src/content/docs/Resources/index.mdx @@ -0,0 +1,3 @@ +--- +title: Resources +--- \ No newline at end of file diff --git a/src/content/docs/Resources/site-showcase.mdx b/src/content/docs/Resources/site-showcase.mdx new file mode 100644 index 0000000..a6f4931 --- /dev/null +++ b/src/content/docs/Resources/site-showcase.mdx @@ -0,0 +1,4 @@ +--- +title: CelestialDocs Showcase +draft: true +--- \ No newline at end of file diff --git a/src/content/docs/getting-started.mdx b/src/content/docs/getting-started.mdx index ef8d029..976b5c1 100644 --- a/src/content/docs/getting-started.mdx +++ b/src/content/docs/getting-started.mdx @@ -48,4 +48,7 @@ To add new pages or sections, simply create new markdown files and folders insid ## Next Steps -- **Configure:** Learn about common options in [Guides](/guides) \ No newline at end of file +- **Configure:** Learn about common options in ["Guides"](/guides). +- **Authoring Content in Markdown:** Learn about options and features of ["Markdown"](/guides/authoring-content-in-md) guide. +- **Components:** Discover built-in callout and more in the ["Components"](/custom-components) guide. +- **Deploy:** Publish your work with the ["Deploy your site"](/resources/deployment) guide in the Astro docs. \ No newline at end of file diff --git a/src/layouts/DocsLayout.astro b/src/layouts/DocsLayout.astro index cc41f2b..9c0885a 100644 --- a/src/layouts/DocsLayout.astro +++ b/src/layouts/DocsLayout.astro @@ -50,7 +50,7 @@ const { > { - !docconfig.hide_side_navinations && !hide_sidenav && ( + !docconfig.hide_side_navigations && !hide_sidenav && ( ) } diff --git a/src/styles/globals.css b/src/styles/globals.css index 683c574..55155f1 100644 --- a/src/styles/globals.css +++ b/src/styles/globals.css @@ -95,7 +95,7 @@ h4 { } p { - @apply leading-7 [&:not(:first-child)]:mt-6; + @apply leading-7 [&:not(:first-child)]:mt-2; } a { @@ -192,6 +192,22 @@ td { @apply italic; } +.prose details { + @apply pl-4 border-l-4 border-primary py-2; +} + +.prose summary { + @apply pl-0; +} + +.prose .contains-task-list li { + @apply list-none; +} + +.prose li input { + @apply appearance-none w-3 h-3 border-2 border-Red rounded-sm bg-background checked:bg-Green checked:border-0 mr-2; +} + /* ===== pattern ===== */ .pattern { --dot-bg: hsl(var(--background));