Skip to content

Home

Jump to bottom
SHADIL AM edited this page Jul 5, 2025 · 1 revision

AcademiaDrive Explorer - GitHub Wiki

Welcome to the AcademiaDrive Explorer project! This wiki serves as a guide for understanding the project, setting it up, and contributing. AcademiaDrive Explorer is a Next.js-based app that allows users to browse, explore, and download academic PDFs stored in a directory structure.

Table of Contents

Overview

AcademiaDrive Explorer is a Next.js application designed to help users navigate and download academic PDFs stored in a nested directory structure. The app automatically generates paths based on the folder contents and enables easy browsing of directories and PDF files.

Features

  • Dynamic Path Generation: Automatically generates paths based on the folder structure in the public/academiadrive directory.
  • Recursive Directory Navigation: Users can browse nested directories and view their contents.
  • PDF Download Links: Displays PDF files with direct download links.
  • Error Handling: If no directories or PDFs are found, it shows a message indicating the lack of content in that section.
  • Responsive UI: The design is simple, clean, and works well across devices.

Installation

To set up and run the project locally, follow these steps:

  1. Clone the Repository:

    git clone https://github.com/yourusername/academiadrive-explorer.git

  2. Install Dependencies: Navigate into the project directory and install the necessary dependencies:

    cd academiadrive-explorer
npm install

  3. Run the Development Server: Start the Next.js development server:

    npm run dev

  4. Open the App: Visit http://localhost:3000/ in your browser to see the app in action.

Project Structure

Here’s an overview of the project structure:

/academiadrive-explorer
├── /public/academiadrive      # Folder containing academic PDFs and directories
├── /pages                     # Next.js pages
│   ├── /explorer/[...slug].tsx # Explorer page for browsing directories and PDFs
│   ├── /index.tsx            # Homepage displaying top-level directories
├── /styles                    # CSS styling
│   └── Explorer.module.css    # CSS module for the Explorer page
├── /node_modules              # Node.js dependencies
├── package.json               # Project metadata, dependencies, and scripts
├── tsconfig.json              # TypeScript configuration
├── tailwind.config.js         # Tailwind CSS configuration
└── next.config.js             # Next.js configuration

Key Components

ExplorerPage Component

The ExplorerPage component is responsible for displaying the content of a directory. It shows subdirectories and PDFs, as well as a breadcrumb-style path.

Props:

  • params: Contains the slug (current path) for the directory being viewed.
  • directories: List of subdirectories to navigate through.
  • pdfs: List of available PDFs in the current directory.

It renders:

  • A breadcrumb trail showing the current path.
  • Links to navigate to subdirectories.
  • Links to download PDFs.

getStaticPaths and getStaticProps

  • getStaticPaths: This function recursively gathers all directories in public/academiadrive and generates dynamic paths for each directory.
  • getStaticProps: Fetches the directories and PDFs for the current path. If the path is invalid (e.g., a non-existent directory), it returns a 404 error.

HomePage Component

The HomePage component shows the top-level directories in public/academiadrive. It passes this data to the ExplorerPage as props.

How It Works

  1. Dynamic Routing: The app uses dynamic routing to generate paths like /explorer/category/subcategory. These paths correspond to the directories on the file system.
  2. Directory Listing: The app reads the contents of public/academiadrive using the fs module, identifying directories and PDFs.
  3. Displaying Content: The app renders a list of directories and PDFs on the page, allowing users to navigate or download them.
  4. Downloading PDFs: PDFs are displayed as links that users can click to download the files.

Development Setup

This project uses the following key technologies:

  • Next.js: For building the app and handling server-side rendering.
  • TypeScript: For static type checking and better developer experience.
  • Tailwind CSS: For styling the app with a utility-first approach.
  • Jest: For testing the application and ensuring correctness.

Development Dependencies:

"devDependencies": {
  "@tailwindcss/postcss": "^4.1.11",
  "@testing-library/jest-dom": "^6.6.3",
  "@testing-library/react": "^16.3.0",
  "@types/jest": "^30.0.0",
  "@types/node": "^20.19.4",
  "@types/react": "^19",
  "@types/react-dom": "^19",
  "@types/testing-library__react": "^10.0.1",
  "autoprefixer": "^10.4.21",
  "jest": "^29.7.0",
  "postcss": "^8.5.6",
  "tailwindcss": "^4.1.11",
  "ts-jest": "^29.4.0",
  "typescript": "^5"
}

Contributing

We welcome contributions to the project! If you would like to contribute, follow the steps below:

Branching Strategy

All development happens in the dev branch. Feature branches should be created from dev and merged back into it.

Steps to Contribute

  1. Fork the Repository: Click the “Fork” button on GitHub to create a copy of the repo.

  2. Clone Your Fork: Clone the forked repository to your local machine.

    git clone https://github.com/yourusername/academiadrive-explorer.git
cd academiadrive-explorer

  3. Create a New Branch: Always create a new branch for the feature or fix you’re working on.

    git checkout -b feature/your-feature-name

  4. Make Your Changes: Implement your changes or new features.

  5. Test Locally: Run the app locally to make sure everything works as expected.

  6. Commit Your Changes: Commit your changes with a descriptive message.

    git commit -am "Add feature X"

  7. Push to Your Fork: Push the branch to your GitHub fork.

    git push origin feature/your-feature-name

  8. Create a Pull Request: Go to the original repository and create a pull request from your feature branch to the dev branch.

License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for more details.

Clone this wiki locally