mirror of
https://github.com/PR0M3TH3AN/Word-Cloud-from-DocX.git
synced 2026-10-27 08:09:57 +00:00
178 lines
5.3 KiB
Markdown
178 lines
5.3 KiB
Markdown
# Local Word Cloud Tool (DOCX or Ranked CSV)
|
||
|
||
A single-file, local HTML tool that:
|
||
- extracts text from a **DOCX** in your browser,
|
||
- generates a **ranked word list** (word → count),
|
||
- renders a **word cloud**, and
|
||
- exports the result as **CSV**, **SVG**, or **PNG**.
|
||
|
||
No server required. Everything runs client-side in your browser.
|
||
|
||
---
|
||
|
||
## Files
|
||
|
||
- `wordcloud_tool.html` (the only file you need)
|
||
|
||
Optional inputs:
|
||
- Any `.docx` file (e.g., a list of titles, abstracts, bullets, etc.)
|
||
- A ranked `.csv` file with columns: `word,count`
|
||
|
||
---
|
||
|
||
## How to run
|
||
|
||
1. Save the tool as `wordcloud_tool.html`.
|
||
2. Open it in a modern browser (Chrome or Edge recommended).
|
||
3. Choose one input method:
|
||
- **DOCX → Build list from DOCX**
|
||
- **CSV → Build cloud from CSV**
|
||
|
||
> Tip: If your organization blocks external CDNs, see **Offline Mode** below.
|
||
|
||
---
|
||
|
||
## Using a DOCX (recommended workflow)
|
||
|
||
### 1) Load DOCX
|
||
Click **Load DOCX** and select any `.docx` file.
|
||
|
||
You can upload *any* DOCX file—Word documents, exported DOCX from Google Docs, etc.
|
||
The tool extracts the document’s text in-browser (no upload to a server).
|
||
|
||
### 2) Build the word list
|
||
Click **Build list from DOCX**.
|
||
|
||
The tool:
|
||
- extracts text,
|
||
- normalizes punctuation,
|
||
- optionally removes years (e.g., 1987, 2024),
|
||
- tokenizes into words,
|
||
- applies stopwords and filters,
|
||
- counts occurrences,
|
||
- sorts by frequency.
|
||
|
||
### 3) Tune the output (important)
|
||
Use these controls:
|
||
|
||
- **Top N words**
|
||
Limits the ranked list to the top N words after filtering.
|
||
(Typical ranges: 50–200)
|
||
|
||
- **Min word length**
|
||
Filters out short tokens (e.g., “of”, “in”).
|
||
Try 3–4 for academic titles.
|
||
|
||
- **Remove years**
|
||
Removes tokens like 1987 / 2024 if they appear in the text.
|
||
|
||
- **Drop numbers-only tokens**
|
||
Removes pure numeric tokens (still keeps alphanumeric like `SiO2`, `GaAs`).
|
||
|
||
- **Stopwords** (the most important control)
|
||
A list of words to ignore, one per line or comma-separated.
|
||
This includes common English stopwords plus common academic “filler” words.
|
||
|
||
---
|
||
|
||
## Editing the word outputs (how to control what appears)
|
||
|
||
You have **two main ways** to edit the final words in the cloud.
|
||
|
||
### Method A: Edit stopwords (fastest)
|
||
If an unwanted word is dominating the cloud:
|
||
|
||
1. Find it in the cloud or ranked list.
|
||
2. Add it to the **Stopwords** box.
|
||
3. Rebuild (click **Build list from DOCX** again).
|
||
|
||
Examples of common “junk” words to add:
|
||
- `study`, `analysis`, `characterization`, `development`, `effects`, `properties`
|
||
|
||
You can also remove words from stopwords if you *do* want them included.
|
||
|
||
### Method B: Export CSV → edit → reload (most control)
|
||
If you need precise control (e.g., merge synonyms, force counts, remove a few terms):
|
||
|
||
1. Build from DOCX.
|
||
2. Click **Export ranked CSV**.
|
||
3. Edit the CSV in Excel (or any spreadsheet tool).
|
||
- You can delete rows, rename words, or change counts.
|
||
4. Save as CSV (keep `word,count` columns).
|
||
5. Load the edited CSV using **Load Ranked CSV**.
|
||
6. Click **Build cloud from CSV**.
|
||
|
||
This gives full manual control over the final word list.
|
||
|
||
---
|
||
|
||
## Exporting graphics
|
||
|
||
### Export SVG (recommended for design workflows)
|
||
Click **Export SVG** to download `wordcloud.svg`.
|
||
|
||
- Best for Illustrator / InDesign / PowerPoint (vector)
|
||
- You can edit text as objects (unless you later outline it)
|
||
|
||
> Note: The exporter replaces the `system-ui` font keyword with `Helvetica` in the SVG
|
||
> to avoid Illustrator import warnings.
|
||
|
||
### Export PNG
|
||
Click **Export PNG** to download `wordcloud.png`.
|
||
|
||
- Good for quick slide insertion
|
||
- The PNG exporter preserves aspect ratio based on the SVG viewBox (no squishing)
|
||
|
||
If you want a specific slide size (e.g., 1920×1080 or 3840×2160), the PNG export function
|
||
can be adjusted in the script.
|
||
|
||
---
|
||
|
||
## Tips for best results
|
||
|
||
- **Start with Top N = 100–150** and **Min length = 3**
|
||
- Expand stopwords aggressively to remove “academic glue” words
|
||
- If you have chemical formulas/material names:
|
||
- they often appear as alphanumeric tokens (e.g., `GaAs`, `SiO2`) and will be kept
|
||
- Consider exporting CSV and merging synonyms:
|
||
- e.g., `magnetic` + `magnetism`, `diffusion` + `diffusive`
|
||
|
||
---
|
||
|
||
## Offline mode (no internet access)
|
||
|
||
By default, the tool loads libraries from CDNs:
|
||
|
||
- `d3`
|
||
- `d3-cloud`
|
||
- `mammoth` (DOCX parsing)
|
||
|
||
If you need a fully offline version:
|
||
1. Download those JS files.
|
||
2. Place them in the same folder as `wordcloud_tool.html`.
|
||
3. Replace the three `<script src="https://...">` tags with local paths, e.g.:
|
||
|
||
```html
|
||
<script src="./d3.min.js"></script>
|
||
<script src="./d3.layout.cloud.js"></script>
|
||
<script src="./mammoth.browser.min.js"></script>
|
||
```
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
### Illustrator warning on import
|
||
|
||
If Illustrator complains about fonts (e.g., `system-ui`), export SVG again—the tool sanitizes that token to `Helvetica` for compatibility.
|
||
|
||
### “Squished” PNG exports
|
||
|
||
PNG export uses the SVG `viewBox` to preserve aspect ratio. If you still see distortion, verify you’re viewing the PNG at 100% and that the viewer isn’t applying non-uniform scaling.
|
||
|
||
### DOCX content looks incomplete
|
||
|
||
Some Word docs contain text inside tables/text boxes. Mammoth extracts “raw text” best from normal paragraphs. If your content is in tables/text boxes, consider copying it into a simple paragraph/list format first, or export a ranked CSV manually.
|
||
|
||
---
|