DOCSEARCHbyAlgolia
Submit Docs

Astro-Nomy

repository·master·Indexed 19 days ago

https://github.com/mickasmt/astro-nomy

A theme and project built on Astro that leverages MDX to mix Markdown content with interactive UI components. It includes a comprehensive configuration system for site metadata, landing page content, and navigation menus, as well as a WaitlistForm component that integrates with a /api/waitlist endpoint.

Tokens
10K
Snippets
50
Records
57
Agent score
67%

What's inside astro-nomy

  1. Overview of Astronomy documentation features

    master

    The Astronomy documentation site is built using Markdown and MDX, leveraging Contentlayer for content transformation and validation. Key out-of-the-box features include:

    • Content Authoring: Write content using MDX.
    • Content Processing: Transform and validate content via Contentlayer.
    • MDX Components: Pre-built components like <Callout /> and <Card />.
    • Navigation: Support for Table of Contents and custom navigation with prev and next pagers.
    • Code Presentation: Beautiful code blocks powered by rehype-pretty-code and syntax highlighting via shiki.
    • In-Progress Features: Built-in search and Dark mode.

  2. Advanced Code Block Features with rehype-pretty-code

    master

    The documentation and blog use rehype-pretty-code (powered by shiki) to provide advanced code block features. Highlighting is performed at build time, meaning no client-side JavaScript is required for syntax highlighting.

    Key features include:

    • Syntax highlighting using VS Code themes.
    • Support for hundreds of languages.
    • Line and word highlighting.
    • Line numbers.
    • Code block titles via meta strings.

  3. Supported typographic elements in `prose`

    master

    The prose class provides out-of-the-box styling for a wide range of standard typographic elements, including:

    • Headings: h1 through h4 (Note: h5 and h6 are not styled by default as they are similar in size to body copy).
    • Text Styles: Bold, italics, and inline code.
    • Lists: Unordered lists, ordered lists, and nested lists.
    • Block Elements: Paragraphs (p), blockquotes, and images.
    • Code Blocks: Default styling for code blocks (even without syntax highlighting).
    • Tables: Styled tables with headers and borders.
    • Links: Styled links (defaulting to a dark gray in this implementation).
    • GitHub Flavored Markdown: Support for features like autolink literals (e.g., converting URLs and email addresses into <a> tags) via remark-gfm.

  5. Style MDX content with Tailwind CSS

    master

    You can use Tailwind CSS classes directly on elements within MDX files.

    Important: To ensure Tailwind processes your MDX files, you must include the path to your content directory in the content array of your tailwind.config.js file.

    <p className="text-red-600">This text will be red.</p>
    /** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./app/**/*.{ts,tsx}",
    "./components/**/*.{ts,tsx}",
    "./content/**/*.{md,mdx}",
  ],
}

  6. Enable or disable MDX support

    master

    This project includes the @astrojs/mdx integration by default, which is configured in your astro.config.mjs file.

    To disable MDX support, simply remove the @astrojs/mdx integration from the integrations array in your astro.config.mjs configuration file.

    // astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [mdx()], // Remove this line to disable MDX
});

  8. Use HTML elements for abbr, sub, sup, kbd, and mark

    master

    Standard HTML tags can be used within Markdown to achieve specific formatting:

    • <abbr title="..."> for abbreviations.
    • <sub> for subscript.
    • <sup> for superscript.
    • <kbd> for keyboard input.
    • <mark> for highlighted text.
    <abbr title="Graphics Interchange Format">GIF</abbr> is a bitmap image format.

H<sub>2</sub>O

X<sup>n</sup> + Y<sup>n</sup> = Z<sup>n</sup>

Press <kbd><kbd>CTRL</kbd>+<kbd>ALT</kbd>+<kbd>Delete</kbd></kbd> to end the session.

Most <mark>salamanders</mark> are nocturnal.

  9. Create syntax-highlighted code blocks

    master

    To create a code block, use three backticks (```) on a new line. To enable syntax highlighting, specify the language name (e.g., html, javascript, css, markdown, typescript, txt, bash) immediately after the first three backticks.

    <!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Example HTML5 Document</title>
  </head>
  <body>
    <p>Test</p>
  </body>
</html>

  10. Use the @tailwindcss/typography plugin for content styling

    master

    Tailwind CSS removes default browser styling from elements like h1, p, and ul. To style rich-text content (from a CMS or Markdown file) without manually undoing these resets, use the @tailwindcss/typography plugin.

    Applying the prose class to a container element will automatically apply beautiful, well-formatted typography to all vanilla HTML content inside that container.

    <article class="prose">
  <h1>Garlic bread with cheese: What the science tells us</h1>
  <p>
    For years parents have espoused the health benefits of eating garlic bread
    with cheese to their children...
  </p>
</article>

  12. Use UI components in MDX

    master

    MDX allows you to import and embed JavaScript and JSX syntax directly into your Markdown content. This is useful for adding interactive elements like charts, alerts, or custom buttons to your blog posts or documentation.

    Important: By default, all components rendered in MDX are treated as static HTML. To make a component interactive (i.e., to enable its JavaScript), you must use Astro Client Directives such as client:load, client:idle, or client:visible.

    import MyComponent from '../components/MyComponent.astro';

# My Post

Here is an interactive component:

<MyComponent client:load />