mzwiki

An English-first mass spectrometry knowledge wiki for beginners and returning practitioners. It connects foundational concepts, instrument principles, experimental methods, and computational reasoning. It is not a publication feed.

Site: https://mzwiki.unimz.org · Repository: https://github.com/UniMZ/mzwiki

Learning collection

Forty-two English Guides and 90 terminology entries, each with a matched Chinese translation. The original eight-Guide sequence is retained; topic navigation groups the expanded collection.

1. What mass spectrometry measures
2. m/z, charge & isotopes
3. How molecules become ions
4. Mass analyzers & resolution
5. Fragmentation & tandem MS
6. Read a spectrum step by step
7. Acquisition: full scan, DDA, DIA & targeted
8. From raw data to reliable results
9. Sample preparation & recovery
10. Liquid chromatography for MS
11. Blanks, carryover & contamination
12. Quantitative measurement & calibration
13. Experimental design & replication
14. QC, batch effects & normalization
15. Bottom-up proteomics: from sample to protein evidence
16. Peptide identification and protein inference
17. PTM analysis and site localization
18. Small-molecule annotation: from features to identity
19. Lipidomics: match structural detail to evidence
20. Ion mobility and collision cross section
21. Crosslinking MS: from peptide pairs to structural restraints
22. Glycoproteomics: evidence and ambiguity
23. Phosphoproteomics: enrichment, localization and quantification
24. Mass spectrometry imaging: principles and interpretation
25. Single-cell proteomics: measurement and statistics
26. Spectrum prediction and machine-learning generalization
27. Benchmarking computational mass spectrometry
28. Open data formats and analysis provenance
29. Ion detection & signal formation
30. Profile, centroid & signal processing
31. LC-MS feature detection and peak integration
32. Cross-run alignment and feature correspondence
33. Spectral library search: from query to defensible match
34. Molecular networking: read connections as evidence
35. Missing-data handling
36. Differential-abundance analysis
37. GC-MS: electron ionization and retention indices
38. Mixed spectra and spectral deconvolution
39. Molecular-formula inference from mass and isotope evidence
40. Stable-isotope tracing: from labeling patterns to metabolic questions
41. PCA and scaling: explore variation without overclaiming
42. Pathway enrichment: connect measured changes to biological hypotheses

The interface and project documentation are English. EN / ZH switches between separate views of the same article and preserves matching section anchors. Search defaults to English and can search Chinese or both languages.

Build and preview

Requires Python 3.10+; the build and link checks use only its standard library. There is no package installation step and no remote asset dependency.

python3 scripts/build.py
python3 scripts/check.py
python3 -m http.server 8000 --bind 127.0.0.1

Open http://127.0.0.1:8000. The generated site is committed at the repository root for GitHub Pages. Do not open HTML through file://: search loads its static index over HTTP.

Optional browser checks require Python Playwright and Chromium:

python3 scripts/browser_check.py

Start the local server first. Set MZWIKI_BASE_URL and MZWIKI_CHROMIUM to override the defaults. The checks exercise every article at desktop/mobile sizes, search, language switching, navigation, and reading without JavaScript. Screenshots are saved outside the repository to /tmp/mzwiki-checks.

Source layout

• content/articles.json: ordered guide metadata, translation titles, prerequisites, related guides, and reference keys.
• content/en/*.html, content/zh/*.html: trusted article-body HTML fragments. Edit these, not the generated pages.
• content/terms.json and content/terms/{en,zh}/*.html: the separate Terminology collection and paired term bodies.
• terms/, zh/terms/: generated terminology index and paired term pages.
• content/term-topics.json: ordered editorial topics and exactly one topic assignment per term.
• content/references.json: shared bibliography with verified source identifiers.
• scripts/build.py: shared templates, homepage, article pages, sitemap, and search-index generation.
• assets/: shared CSS, small progressive-enhancement script, favicon, and generated search index.
• guides/, zh/guides/: generated paired article pages.
• about/, search/, index.html, 404.html: generated supporting pages.

Run the build and checks after each edit and commit the generated output with its source. Article HTML is trusted maintainer content, not user-supplied input. Search renders queries and result text using DOM text APIs.

Scientific teaching example

The charge/isotope worked spectrum is simulated, not experimental. Its assumptions and source constants are in content/examples/charge-isotope-spectrum.json. Validate its arithmetic without additional packages:

python3 scripts/check_science.py

The committed SVG and PNG are generated by scripts/render_spectrum.py using Matplotlib (an optional figure-authoring dependency). Normal site builds need no Matplotlib installation. To regenerate the figure in a writable temporary cache, then rebuild:

MPLCONFIGDIR=/tmp/mzwiki-mpl XDG_CACHE_HOME=/tmp/mzwiki-font-cache python3 scripts/render_spectrum.py
python3 scripts/build.py
python3 scripts/check.py
python3 scripts/check_science.py

Keep figure inputs, plotted labels, article tables, and both translations synchronized. The numeric checks verify published values and language parity; they do not establish the model's validity for real measurements.

The ionization guide has nine constructed ion-form examples in tests/fixtures/ionization.json. After building, check their forward and inverse calculations, ionic constants, and both article tables:

python3 scripts/check_ionization.py

Terminology integration

Terminology entries are a separate collection from the numbered Guides. Their metadata defines ordered references, related_guides, and related_terms. Guide pages derive reciprocal term links from that metadata; Guide source prose remains unchanged. Search records include kind: "guide" or kind: "term", and the search page can filter by collection and language.

After building, validate the supplied terminology fixtures and paired examples:

python3 scripts/check_terms.py

The structural checker includes both collections, citation numbering, generated-body consistency, and exact sitemap coverage. Browser checks cover the term index, same-term language switches, collection filters, cross-links, and reading without JavaScript.

The analyzer Guide and Mass analyzer/Transient entries use the constructed cases in review/analyzers/analyzer-arithmetic-fixtures.json. Validate the ten models and paired published examples with:

python3 scripts/check_analyzers.py

The fragmentation Guide and its three terms use tests/fixtures/fragmentation.json. Validate all thirteen mass/charge, neutral-loss, residue-gap and isolation-window cases with:

python3 scripts/check_fragmentation.py

The acquisition Guide and its three terms use tests/fixtures/acquisition.json. Check all sixteen serial schedules, budgets, selection rules, isolation intervals and XIC calculations with:

python3 scripts/check_acquisition.py
python3 scripts/check_data_analysis.py
python3 scripts/check_reading_bridge.py
python3 scripts/check_expansion.py
python3 scripts/check_advanced_expansion.py
python3 scripts/check_signal.py
python3 scripts/check_terminology.py

GitHub Pages deployment

This version supports Deploy from a branch → main → / (root). The repository root contains index.html, .nojekyll, and CNAME (mzwiki.unimz.org). Preserve the custom domain. No credentials or DNS changes are needed in this repository.

The build output is already committed; no Jekyll or Actions build is required. If the existing Pages configuration uses GitHub Actions or a different source folder, a repository administrator must select main and / (root) or configure an approved deployment workflow. Do not claim publication solely because a push succeeds: inspect the Pages build/deployment and the live domain.

Editorial approach

Each guide includes prerequisites, worked examples, limitations, references, and related concepts. Sources favor standards, official documentation, and primary methodological publications. The homepage spectrum is an original schematic, not measured data. Foundational examples are educational, not validated operating procedures. Scientific and translation improvements are welcome through issues and pull requests; see CONTRIBUTING.md.

This reconstructed first edition has a new commit history; it is not the inaccessible earlier implementation commit. No private workspace or Notion content is included. No analytics, external fonts, or client-side accounts are used.

Terminology browsing

/terms/ is the default By topic directory; /terms/az/ is the complete A–Z directory. Native links preserve the chosen view in the URL, including refresh, Back/Forward and JavaScript-disabled browsing. Both views derive from the same term metadata. Titles use case-insensitive natural ordering, with slug as a stable tie-break. Topic ordering and membership come from content/term-topics.json; adding a term also requires an assignment there. Sidebar and mobile terminology navigation use the same topics and link to both directories.

The directory uses compact multi-column text lists on desktop and single-column lists on narrow screens. Article reading typography is unchanged. az is reserved for the browsing route and cannot be used as a term slug.

The computational learning expansion is preserved in review/expansion-computational-learning/. After building, run python3 scripts/check_computational_integration.py to check the supplied source hashes, metadata, generated bodies, citations and paired anchors. Scientific review of this packet was supplied separately; the integration checks do not replace it.