feat: academic rendering design and zero-config bibliography (v0.1.2)

Author: leonardosalasd

.gitignore

@@ -204,7 +204,204 @@ cython_debug/
 .cursorignore
 .cursorindexingignore
 
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
 # Marimo
 marimo/_static/
 marimo/_lsp/
 __marimo__/
+
+refs.bib

README.md

@@ -51,6 +51,18 @@ That's it. Zero configuration required.
 
 ---
 
+## 🎓 Academic Features (v0.1.2+)
+
+`doc-engine-cli` ships with a premium scientific layout (using Linux Libertine and Inter font-families) and **Zero-Config Bibliography** handling. 
+
+To add an IEEE-styled bibliography to your PDF:
+1. Create a `refs.bib`, `references.bib`, or `bibliography.bib` file in your repository.
+2. In your `README.md`, cite using standard syntax: `[@citation-key]`.
+
+When you run `doc-engine build`, the CLI will automatically detect your `.bib` file, securely bind it to the sandbox, and inject a formatted References page at the end of the document.
+
+---
+
 ## Quick Start
 
 ### Installation

doc_engine/__init__.py

@@ -1 +1,2 @@
-__version__ = "0.1.1"
+"""doc-engine-cli: Modern Markdown to Typst compiler."""
+__version__ = "0.1.2"

doc_engine/cli.py

@@ -14,6 +14,7 @@
 console = Console()
 
 _README_CANDIDATES = ("README.md", "readme.md", "Readme.md", "README.MD")
+_BIB_CANDIDATES = ("refs.bib", "references.bib", "bibliography.bib")
 
 
 def _detect_git_user() -> str:
@@ -30,8 +31,8 @@ def _detect_git_user() -> str:
         return "Anonymous"
 
 
-def _find_readme(directory: Path) -> Path | None:
-    for name in _README_CANDIDATES:
+def _find_file(directory: Path, candidates: tuple[str, ...]) -> Path | None:
+    for name in candidates:
         candidate = directory / name
         if candidate.exists():
             return candidate
@@ -51,12 +52,14 @@ def cli(ctx: click.Context) -> None:
 @click.option("-o", "--output", default=None, help="Output PDF file path.")
 @click.option("-t", "--title", default=None, help="Document title override.")
 @click.option("-a", "--author", default=None, help="Author name override.")
+@click.option("--bib", default=None, help="Path to custom .bib file.")
 @click.option("--open", "open_pdf", is_flag=True, help="Open PDF after generation.")
 def build(
     input_file: str | None,
     output: str | None,
     title: str | None,
     author: str | None,
+    bib: str | None,
     open_pdf: bool,
 ) -> None:
     console.print(
@@ -67,10 +70,12 @@ def build(
         )
     )
 
+    cwd = Path.cwd()
+
     if input_file:
         input_path = Path(input_file)
     else:
-        input_path = _find_readme(Path.cwd())
+        input_path = _find_file(cwd, _README_CANDIDATES)
         if not input_path:
             console.print(
                 "[bold red]Error:[/bold red] No README.md found in current directory.\n"
@@ -83,15 +88,27 @@ def build(
         console.print(f"[bold red]Error:[/bold red] File not found — {input_path}")
         raise SystemExit(1)
 
+    # Detect Bibliography
+    resolved_bib = None
+    if bib:
+        resolved_bib = Path(bib)
+        if not resolved_bib.exists():
+            console.print(f"[bold yellow]Warning:[/bold yellow] Bibliography file not found — {bib}")
+            resolved_bib = None
+    else:
+        resolved_bib = _find_file(cwd, _BIB_CANDIDATES)
+        if resolved_bib:
+            console.print(f"  [dim]Auto-detected bib:[/dim] [cyan]{resolved_bib.name}[/cyan]")
+
     markdown_content = input_path.read_text(encoding="utf-8")
 
     resolved_title = title or extract_title(markdown_content)
     resolved_author = author or _detect_git_user()
     resolved_output = output or f"{input_path.stem}_doc.pdf"
 
-    console.print(f"  [dim]Title:[/dim]  [white]{resolved_title}[/white]")
-    console.print(f"  [dim]Author:[/dim] [white]{resolved_author}[/white]")
-    console.print(f"  [dim]Output:[/dim] [cyan]{resolved_output}[/cyan]")
+    console.print(f"  [dim]Title:[/dim]   [white]{resolved_title}[/white]")
+    console.print(f"  [dim]Author:[/dim]  [white]{resolved_author}[/white]")
+    console.print(f"  [dim]Output:[/dim]  [cyan]{resolved_output}[/cyan]")
     console.print()
 
     with console.status("[bold blue]Converting Markdown → Typst…[/bold blue]"):
@@ -105,6 +122,7 @@ def build(
                 title=resolved_title,
                 author=resolved_author,
                 output_path=resolved_output,
+                bib_file=str(resolved_bib.resolve()) if resolved_bib else None,
             )
         except Exception as exc:
             console.print(f"\n[bold red]Compilation failed:[/bold red] {exc}")

doc_engine/compiler.py

@@ -1,3 +1,4 @@
+import shutil
 import tempfile
 from pathlib import Path
 
@@ -11,28 +12,38 @@ def compile_pdf(
     title: str,
     author: str,
     output_path: str,
+    bib_file: str | None = None,
 ) -> None:
-    template_src = _TEMPLATE_PATH.read_text(encoding="utf-8")
-    main_src = _build_main(typst_body, title, author)
     resolved_output = str(Path(output_path).resolve())
 
     with tempfile.TemporaryDirectory() as tmpdir:
         tmp = Path(tmpdir)
-        (tmp / "report.typ").write_text(template_src, encoding="utf-8")
+        (tmp / "report.typ").write_text(_TEMPLATE_PATH.read_text(encoding="utf-8"), encoding="utf-8")
+        
         main_file = tmp / "main.typ"
+        bib_inject = "none"
+        
+        if bib_file:
+            bib_path = Path(bib_file)
+            if bib_path.exists():
+                shutil.copy(bib_path, tmp / bib_path.name)
+                bib_inject = f'"{bib_path.name}"'
+                
+        main_src = _build_main(typst_body, title, author, bib_inject)
         main_file.write_text(main_src, encoding="utf-8")
 
         typst.compile(str(main_file), output=resolved_output)
 
 
-def _build_main(body: str, title: str, author: str) -> str:
+def _build_main(body: str, title: str, author: str, bib_inject: str) -> str:
     safe_title = title.replace('"', '\\"')
     safe_author = author.replace('"', '\\"')
     return (
         '#import "report.typ": setup_doc\n\n'
         "#show: setup_doc.with(\n"
         f'  title: "{safe_title}",\n'
         f'  author: "{safe_author}",\n'
+        f"  bibliography_file: {bib_inject},\n"
         ")\n\n"
         f"{body}"
     )

doc_engine/converter.py

@@ -184,7 +184,10 @@ def convert(markdown: str) -> str:
         renderer=renderer,
         plugins=["table", "strikethrough"],
     )
-    return md(markdown)
+    typst_str = md(markdown)
+    # Translate Pandoc syntax [@citation_key] back to native Typst @citation_key
+    typst_str = re.sub(r'\[\\@([a-zA-Z0-9_\-]+)\]', r'@\1', typst_str)
+    return typst_str
 
 
 def extract_title(markdown: str) -> str: