DOCSEARCHbyAlgolia
Submit Docs

Nextra Documentation

website·Indexed 29 days ago

https://nextra-mu-seven.vercel.app

Documentation for Nextra, featuring guides on MDX usage for embedding React components, schema-driven development, and integration with Algolia Docsearch.

Tokens
1K
Snippets
4
Records
6
Agent score
25%

What's inside Nextra

  1. Use MDX for interactive documentation

    MDX allows you to write documentation using standard Markdown syntax while directly embedding React components. This enables the creation of rich, interactive content without leaving the Markdown file.

  2. Implement schema-driven development with Python (FastAPI) and Oracle Autonomous Database

    When using Python (FastAPI) with Oracle Autonomous Database, the following toolchain is recommended for schema-driven development:

    • Database Layer: Use SQLAlchemy (the Python ORM standard) with the cx_Oracle driver for Oracle DB support. Use Alembic for migration management. For existing databases, sqlacodegen can be used to automatically generate SQLAlchemy models from the DB.
    • GraphQL Layer: Use Ariadne, Strawberry GraphQL, or Graphene (specifically graphene-oracle for direct Oracle support). Note that automatic generation from DB schema to GraphQL types is limited in Python; manual mapping from ORM models to GraphQL types is common.
    • Frontend/Interface Layer: Use GraphQL Code Generator for generating TypeScript types and React/Next.js hooks, as it remains the industry standard regardless of the backend language.
    • gRPC Layer: Use graphql-to-proto for converting GraphQL schemas to .proto files.
    # Example: Generate SQLAlchemy models from an existing Oracle DB
pip install sqlacodegen
sqlacodegen oracle+cx_oracle://user:pass@host:port/service_name > models.py

  3. Automate artifact generation in schema-driven development

    Schema-driven development allows developers to generate downstream artifacts from a single source of truth. Common automation paths include:

    • Table Definitions (Excel/CSV/DDL) → DB Schema (SQL, ORM): Use ERD tools (ERD Cloud, dbdiagram.io, SQL Power Architect) or ORM CLIs (Prisma Migrate, Sequelize-CLI, TypeORM-CLI).
    • DB Schema → GraphQL Schema: Use Hasura (PostgreSQL), PostGraphile (PostgreSQL), or Prisma + Nexus.
    • GraphQL Schema → gRPC .proto: Use graphql-to-proto or custom scripts (requires careful mapping of type constraints).
    • GraphQL Schema → Resolver Boilerplates: Use GraphQL Code Generator with the typescript-resolvers plugin.
    • GraphQL Schema → Frontend Code (React/Next.js): Use GraphQL Code Generator with typescript, typescript-operations, and typescript-react-apollo plugins to generate types, hooks, and SDKs.

  4. Write basic content using Markdown in MDX

    Standard Markdown syntax is fully supported within MDX files for common formatting tasks such as lists, text styling, and code blocks.
    * Bulleted lists
* **Bold** and _Italic_
* `Inline code`

```js
function greet() {
  console.log("Hello, MDX!");
}

  5. Generate TypeScript types and hooks from GraphQL schemas

    GraphQL Code Generator is the primary tool for automating the frontend development cycle. It can generate type-safe interfaces and Apollo hooks directly from a GraphQL schema, reducing manual type definitions in React or Next.js projects.
    # Example plugins for GraphQL Code Generator
plugins: 
  - "typescript"
  - "typescript-operations"
  - "typescript-react-apollo"
  - "typescript-resolvers"

  6. Integrate Algolia Docsearch into Nextra root layout

    To enable Algolia Docsearch in a Nextra project using the App Router, import your custom Algolia search component and pass it to the search prop of the Layout component in app/layout.tsx.
    // app/layout.tsx
import { Footer, Layout, Navbar } from 'nextra-theme-docs'
import { Banner, Head } from 'nextra/components'
import { getPageMap } from 'nextra/page-map'
import 'nextra-theme-docs/style.css'
import Algolia from './components/Docsearch'

const banner = <Banner storageKey="some-key">Nextra 4.0 is released 🎉</Banner>
const navbar = (
  <Navbar
    logo={<b>Nextra</b>}
  />
)
const footer = <Footer>MIT {new Date().getFullYear()} © Nextra.</Footer>

export default async function RootLayout({ children }) {
  return (
    <html lang="ja" dir="ltr" suppressHydrationWarning>
      <Head>
        {/* Additional tags here */}
      </Head>
      <body>
        <Layout
          banner={banner}
          navbar={navbar}
          search={<Algolia />} // Add the Algolia component here
          pageMap={await getPageMap()}
          docsRepositoryBase="https://github.com/shuding/nextra/tree/main/docs"
          footer={footer}
        >
          {children}
        </Layout>
      </body>
    </html>
  )
}