Skip to content
BranchesTags

Repository files navigation

📘 Markdown Knowledge Graph Builder

A web application that *parses Markdown notes, extracts links and headings, and builds a *visual knowledge graph.
It also detects *orphan pages, **broken links, **hub nodes, and provides various *graph statistics.

This project was originally started in *Django, but later shifted to *Flask for better flexibility, easier JSON-based APIs, and smoother integration with a single-page dashboard front-end.

🚀 Live Features

✔ Markdown File Upload

Upload multiple .md or .markdown files at once.

✔ Automatic Parsing

Extracts:

  • Internal links
  • Headings
  • Page relationships

✔ Knowledge Graph Visualization

An interactive graph (Vis.js) showing:

  • Pages → Nodes
  • Links → Edges

✔ Analysis Tools

The system automatically detects:

  • Orphan pages (no incoming or outgoing links)
  • Broken links (links to non-existing files)
  • Hub pages (high in-degree nodes)
  • Graph statistics (total nodes, edges, avg. connections)

✔ Responsive Frontend Dashboard

Built with Bootstrap 5, featuring:

  • Collapsible sidebar
  • Stats cards
  • Graph preview area
  • Tabs for analysis, orphans, hubs, validations

🛠 Tech Stack

Frontend

  • HTML5
  • CSS3
  • Bootstrap 5
  • Vanilla JavaScript
  • Vis.js (network graph library)

Backend

  • Python
  • Flask
  • NetworkX (graph analysis library)
  • Regex for Markdown parsing

Development Tools

  • VS Code
  • Git / GitHub

📂 Folder Structure

mdgraph_project/ │ ├── app.py # Flask backend entry point ├── parser.py # Markdown parsing logic ├── graph_builder.py # Builds graph & performs analysis │ ├── templates/ │ ├── dashboard.html # Main UI │ └── analysis.html # Detailed analysis page │ ├── static/ │ ├── css/ │ │ └── dashboard.css # Custom styling │ ├── js/ │ │ └── dashboard.js # Handles frontend fetching + graph rendering │ └── images/ # (Optional) │ ├── uploads/ │ └── notes/ # All uploaded .md files │ └── README.md # Project documentation

markdown Copy code

🧠 How It Works

1️⃣ Upload Markdown Files

Files are uploaded through the dashboard UI and saved in uploads/notes/.

2️⃣ Parsing

Using parser.py, the system extracts:

  • Headings (#, ##, etc.)
  • Link references (text)

3️⃣ Graph Construction

graph_builder.py uses NetworkX to:

  • Create nodes for each file
  • Create edges for each link inside the Markdown
  • Compute stats

4️⃣ JSON API Response

Flask returns:

  • Nodes
  • Edges
  • Orphan pages
  • Broken links
  • Stats

5️⃣ Frontend Visualization

JavaScript (Vis.js) renders the graph dynamically without page reload.

🔧 Installation & Setup

1. Clone the repository

bash git clone https://github.com/yourusername/Markdown-Knowledge-Graph-Builder.git cd Markdown-Knowledge-Graph-Builder 2. Create virtual environment bash Copy code python -m venv venv source venv/bin/activate # Linux/Mac venv\Scripts\activate # Windows 3. Install dependencies bash Copy code pip install -r requirements.txt 4. Run the Flask server bash Copy code python app.py 5. Open the app cpp Copy code http://127.0.0.1:5000/ 🧪 API Endpoints Endpoint Method Description / GET Loads dashboard /upload POST Uploads markdown files /graph-json GET Returns graph data as JSON

🖼 Screenshots (Add yours here) Dashboard

Graph View

✨ Future Improvements Add real-time graph updates without refresh

Add support for Markdown folders & subdirectories

Include note preview panel on click

Export graph as PNG or JSON

Add dark mode toggle

Integrate AI summarization for notes

📝 Project Motivation This project was created to help visualize interconnected notes in Markdown format. The shift from Django to Flask was motivated by the need for:

Faster API responses

Cleaner JSON integration

Simpler single-page dashboard architecture

Less boilerplate and more control over the backend

📄 License This project is open-source and available under the MIT License.

💬 Contact For queries or contributions:

Your Name GitHub: yourusername Email: youremail@example.com

yaml Copy code

🎉 Your README is ready for GitHub!

If you want:

📌 A version with GIF animations
📌 A version with emojis removed
📌 A super minimal version
📌 A professional industry-style README

Just tell me — I can generate it!

You said: A professional industry-style README

ChatGPT said: Below is a professional, industry-grade README.md, written in a clean, minimal, engineering-focused style. No unnecessary emojis. No fluff. Straightforward and suitable for portfolio, hiring managers, technical reviewers, and GitHub standards.

README.md (Professional Industry Style) markdown Copy code

Markdown Knowledge Graph Builder

The Markdown Knowledge Graph Builder is a web-based system that processes a collection of Markdown notes, extracts structural relationships, and generates an interactive knowledge graph.
The application also performs validation, provides analytical insights, and helps track the evolution of a note-based knowledge system.

This project initially began with Django but transitioned to Flask due to architectural requirements. Flask provided a more lightweight, API-centric backend that better aligned with the project’s single-page dashboard design and dynamic graph rendering needs.

1. Overview

Modern note-taking workflows often involve Markdown files containing headings, references, and cross-links.
This system automates the analysis of such notes by:

  • Parsing Markdown files to identify links and headings
  • Constructing a directed graph from the extracted relationships
  • Visualizing the graph using an interactive frontend
  • Identifying orphan pages, broken links, and hub nodes
  • Calculating graph-level statistics
  • Displaying all results in a responsive dashboard

The tool assists students, researchers, and developers in understanding how their notes connect and evolve.

2. Key Features

Parsing & Processing

  • Extracts Markdown headings, internal references, and content metadata.
  • Supports multi-file batch uploads.
  • Reports missing files referenced within notes (broken links).

Graph Analysis

  • Builds a directed NetworkX graph representing note relationships.
  • Computes:
    • Total pages
    • Total links
    • Average connectivity
    • Orphan nodes
    • Hub nodes (high in-degree)

Visualization

  • Renders an interactive knowledge graph via Vis.js.
  • Provides zooming, panning, physics simulation, and node interaction.

User Interface

  • Responsive Bootstrap-based dashboard.
  • Collapsible sidebar for navigation and file operations.
  • Live-updating statistics and validation indicators.
  • Clean separation between frontend (HTML/CSS/JS) and backend API (Flask).

3. Architecture

User Upload → Parser → Graph Builder → Flask API → JSON → Frontend Visualization (Vis.js)

yaml Copy code

Backend Components

  • parser.py: Extracts links and headings from Markdown.
  • graph_builder.py: Creates and analyzes the note graph.
  • app.py (Flask): API endpoints for uploads and visualization.

Frontend Components

  • dashboard.html: Main UI for uploads, graph, and stats.
  • dashboard.js: Fetches data and renders graph dynamically.
  • dashboard.css: Layout and styling enhancements.
  • Vis.js: Network visualization library.

4. Folder Structure

project_root/ │ ├── app.py ├── parser.py ├── graph_builder.py │ ├── templates/ │ ├── dashboard.html │ └── analysis.html │ ├── static/ │ ├── css/ │ │ └── dashboard.css │ ├── js/ │ │ └── dashboard.js │ └── images/ │ ├── uploads/ │ └── notes/ # Markdown files uploaded by users │ └── README.md

yaml Copy code

5. Installation

Requirements

  • Python 3.9+
  • Flask
  • NetworkX

Setup Steps

bash git clone https://github.com/yourusername/Markdown-Knowledge-Graph-Builder.git cd Markdown-Knowledge-Graph-Builder

python -m venv venv venv\Scripts\activate # Windows

or

source venv/bin/activate # macOS/Linux

pip install -r requirements.txt 6. Running the Application bash Copy code python app.py The application will run on:

cpp Copy code http://127.0.0.1:5000/ Upload your Markdown files through the dashboard to generate the graph and analysis.

  1. API Endpoints Route Method Description / GET Loads dashboard UI /upload POST Uploads Markdown files /graph-json GET Returns graph structure, stats, orphans, hubs, and broken links as JSON

  2. Example Output (JSON) json Copy code { "nodes": [ {"id": "intro.md", "label": "intro.md"}, {"id": "topic.md", "label": "topic.md"} ], "edges": [ {"from": "intro.md", "to": "topic.md"} ], "stats": { "total_pages": 2, "total_links": 1 }, "orphans": [], "broken_links": [], "hubs": ["topic.md"] }

  3. Future Enhancements Graph export to PNG, PDF, or JSON formats

Real-time Markdown editing inside the dashboard

Note preview panel with rendered Markdown

Versioning and graph comparisons over time

Tag extraction and semantic clustering

AI-powered summarization of notes

  1. License This project is released under the MIT License. See LICENSE for details.

  2. Acknowledgments Flask documentation

NetworkX graph analysis tools

Vis.js for graph visualization

Bootstrap for the responsive interface

  1. Contact For feedback, contributions, or issues, please contact:

Your Name GitHub: https://github.com/ipsitapp8 Email: ipsitapp8@gmail.com

yaml Copy code

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages