DOCSEARCHbyAlgolia
Submit Docs

Polar SN Learning and Experience Records

website·Indexed 29 days ago

https://polar-sn.github.io

A personal knowledge base and blog by security researcher Polar, featuring documentation on Docusaurus customization, Giscus integration, and technical learning experiences.

Tokens
4K
Snippets
34
Records
39
Agent score
73%

What's inside Polar SN

  1. Overview of Giscus comment system

    Giscus is an open-source comment system that leverages GitHub Discussions to manage comments. Key features include:

    • GitHub Account Based: Reduces spam by requiring a GitHub account for commenting.
    • GitHub Discussions Integration: Automatically creates discussion threads for blog posts.
    • Free: No additional cost as it uses GitHub's infrastructure.
    • Markdown Support: Supports Markdown for comment composition.
    • Reactions: Allows emoji reactions (e.g., 👍, 👎).
    • Dark Mode: Automatically adapts to the website's theme.

  2. Create standalone pages using the src/pages directory

    To create a standalone page, add a Markdown or React file to the src/pages directory. The file path determines the URL route. For example:

    • src/pages/index.js maps to the root URL (/)
    • src/pages/foo.md maps to /foo
    • src/pages/foo/bar.js maps to /foo/bar

  3. Add syntax highlighting and titles to code blocks

    Docusaurus supports Markdown code blocks with syntax highlighting. You can optionally add a title to the code block by adding a title attribute to the language tag.
    ```jsx title="src/components/HelloDocusaurus.js"
function HelloDocusaurus() {
  return <h1>Hello, Docusaurus!</h1>;
}

  4. Build and preview a Docusaurus static site

    Because Docusaurus uses static rendering, you must build the site into static files before deployment. Running npm run build generates these files in the build folder. To test the production build locally before deploying, use npm run serve, which loads the files from the build folder at http://localhost:3000/.
    # Build the site
npm run build

# Preview the build locally
npm run serve

  5. Install and initialize a new Docusaurus site

    To create a new Docusaurus site using the classic template, run the npm init command. This process automatically adds the classic template to your project and installs all necessary dependencies. You must have Node.js version 18.0 or above installed. It is recommended to enable all dependency-related checkboxes during the Node.js installation process.
    npm init docusaurus@latest my-website classic

  7. Use React components in Markdown via MDX

    Docusaurus supports MDX, allowing you to export and use React components directly within your Markdown files to create interactive documentation.
    export const Highlight = ({children, color}) => (
  <span
    style={{
      backgroundColor: color,
      borderRadius: '20px',
      color: '#fff',
      padding: '10px',
      cursor: 'pointer',
    }}
    onClick={() => {
      alert(`You clicked the color ${color} with label ${children}`)
    }}>
    {children}
  </span>
);

This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !

  8. Add Giscus comments to Docusaurus Blog posts via Swizzling

    To display the Giscus component at the bottom of every blog post, wrap the BlogPostItem using Docusaurus Swizzling. This allows you to conditionally render comments based on the post's front matter.
    # Wrap the BlogPostItem component
npm run swizzle @docusaurus/theme-classic BlogPostItem -- --wrap --typescript
    // src/theme/BlogPostItem/index.tsx
import React, {type ReactNode} from 'react';
import BlogPostItem from '@theme-original/BlogPostItem';
import type BlogPostItemType from '@theme/BlogPostItem';
import type {WrapperProps} from '@docusaurus/types';
import { useBlogPost } from "@docusaurus/plugin-content-blog/client";
import Comments from "@site/src/components/Comments";

type Props = WrapperProps<typeof BlogPostItemType>;

export default function BlogPostItemWrapper(props: Props): ReactNode {
  const { metadata, isBlogPostPage } = useBlogPost();
  // Check frontMatter for 'comments' key; defaults to true
  const { comments = true } = metadata.frontMatter;

  return (
    <>
      <BlogPostItem {...props} />
      {comments && isBlogPostPage && <Comments />}
    </>
  );
}

  9. Translate a documentation page

    To translate a document, copy the original markdown file from the docs directory into a specific locale folder within the i18n directory. The folder structure must follow the pattern: i18n/{locale}/docusaurus-plugin-content-docs/current/.
    # Create the directory for French translations
mkdir -p i18n/fr/docusaurus-plugin-content-docs/current/

# Copy the intro page to the translation folder
cp docs/intro.md i18n/fr/docusaurus-plugin-content-docs/current/intro.md

  10. Build a Docusaurus site for production

    Docusaurus is a static-site-generator that compiles the site into static HTML, JavaScript, and CSS files. To generate these production files, run the build command. The resulting static assets are output to the build folder.
    npm run build

  11. Configure GitHub repository for Giscus

    To use Giscus, you must enable GitHub Discussions on the repository where your blog is hosted (e.g., [username].github.io):

    1. Navigate to the repository on GitHub.
    2. Go to Settings > General.
    3. Under the Features section, check the Discussions box.
    4. Install the Giscus app from the GitHub App Marketplace (https://github.com/apps/giscus) and grant it access to your repository.

  12. Run Docusaurus in local development mode

    To start a local development server for Docusaurus, use the npm run start command. This allows you to view the site at http://localhost:3000/ with real-time updates as you modify settings or code. This command is a shortcut for npx docusaurus start as defined in the package.json scripts.
    npm run start