Wiki Management

Overview

The Wiki Management feature in the WikiSmith repository allows users to create, edit, and share wikis. This feature facilitates the generation of structured documentation from codebases, enabling developers to navigate and understand the features and functionalities of a repository effectively.

User-facing behavior

• Wiki Creation: Users can create wikis for their repositories, which are populated with structured documentation based on the codebase.
• Wiki Viewing: Users can view wikis through a dedicated interface that presents the documentation in a user-friendly manner, including navigation elements like sidebars and breadcrumbs.
• Wiki Editing: Users can edit existing wikis, allowing for updates and improvements to the documentation as the codebase evolves.
• Wiki Sharing: Users can share wikis with others, providing a link to the live documentation for easy access.

Architecture and data flow

The Wiki Management feature consists of several components that interact with each other to provide a seamless experience:

1. API Layer: Handles requests related to wiki data, including fetching, creating, and deleting wikis. For example, the GET method in apps/web/src/app/api/wiki/[owner]/[repo]/route.ts fetches wiki data based on repository parameters.
2. Client-side Components: These components render the wiki pages and manage user interactions. The WikiPageClient component in apps/web/src/components/wiki/wiki-page-client.tsx fetches and displays the wiki content, handling loading states and errors.
3. Data Store: Manages the retrieval and storage of wiki data, ensuring that users receive the most up-to-date information. The getWiki function is responsible for fetching the wiki data based on the owner, repository, and user session.
4. Navigation: Provides a user-friendly interface for navigating through wiki content, including sidebar navigation and links to related pages.

Key implementation details

• Fetching Wiki Data: The API layer fetches wiki data using a structured approach to validate parameters and handle errors.

const parsedParams = apiContracts.wiki.get.params.safeParse(await params);
if (!parsedParams.success) {
  return jsonResponse(apiContracts.wiki.get.error, {
    error: 'Invalid wiki route parameters',
    code: 'INVALID_PARAMS',
  }, { status: 400 });
}

This snippet from apps/web/src/app/api/wiki/[owner]/[repo]/route.ts ensures that only valid requests are processed.

• Deleting a Wiki: The deletion process requires user authentication and handles various error scenarios.

const session = await getSession();
if (!session) {
  return NextResponse.json({
    error: 'Authentication required',
    code: 'UNAUTHENTICATED',
    signInPath: '/sign-in?redirect=%2Fdashboard',
  }, { status: 401 });
}

This code from apps/web/src/app/api/repos/[owner]/[repo]/wiki/route.ts checks for user authentication before allowing wiki deletion.

• Client-side Data Fetching: The WikiPageClient component uses React Query to manage data fetching and caching.

const wikiQuery = useQuery({
  queryKey: ['wiki', owner, repo],
  queryFn: () => apiClient.getWiki(owner, repo),
  staleTime: 5 * 60_000,
});

This snippet from apps/web/src/components/wiki/wiki-page-client.tsx demonstrates how the component fetches wiki data and manages loading states.

• Rendering Wiki Content: The WikiReaderShell component organizes the display of wiki content, including navigation and page structure.

const currentPage = getCurrentPage(wiki, slug);
if (!currentPage) {
  return (
    <div className="min-h-screen bg-zinc-950 flex items-center justify-center">
      <p className="text-zinc-400">Page not found</p>
    </div>
  );
}

This code from apps/web/src/components/wiki/wiki-reader-shell.tsx handles cases where the requested page does not exist.

Key files

• apps/web/src/app/api/wiki/[owner]/[repo]/route.ts - Manages fetching wiki data for a specific repository, including parameter validation and error handling. View code
• apps/web/src/app/api/repos/[owner]/[repo]/wiki/route.ts - Handles the deletion of wikis, including authentication checks and error responses. View code
• apps/web/src/components/wiki/wiki-page-client.tsx - Client-side component that fetches and displays wiki content, managing loading states and errors. View code
• apps/web/src/components/wiki/wiki-reader-shell.tsx - Shell component that organizes the display of wiki content, including navigation and page structure. View code