Content and page organization¶

For explicit pages, reusable sections, custom paths and LNCC Theme, see Pages, themes and extensions. The automatic mode below remains supported. For full Markdown articles, numbered mathematics, code, callouts, figures, tables and Jupyter Notebooks, see Scientific writing.

Start from a project generated by sciastro init. Content lives in content/ unless you choose another directory with contentDir.

Home and About¶

kind: group uses Home (Início in Portuguese); kind: individual uses About (Sobre). The name, description, affiliation, languages and theme belong in sciastro.yaml. The introduction is the Markdown file referenced by home.body.

Keep the introduction brief. Detailed descriptions belong on the Research page. Homepage cards are generated from research.yaml, so you do not maintain a second copy of each research summary.

Research¶

Each entry in research.yaml creates a homepage card and a Research section:

- id: numerical-methods
  title:
    pt: Métodos numéricos
    en: Numerical methods
  summary:
    pt: Métodos para modelos de transporte e escoamento.
    en: Methods for transport and flow models.
  body:
    pt: research/numerical.pt.md
    en: research/numerical.en.md

id supplies the anchor, such as /research/#numerical-methods on an English-only site. Keep it stable to preserve links. summary is plain text, limited to 240 characters per language. The Markdown in body supports explanations, lists, figures and citations.

An optional figure belongs in the same entry:

  image:
    src: /images/result.png
    alt:
      pt: Descrição do resultado representado.
      en: Description of the result shown.

Place the image in public/images/result.png. Check usage rights and add attribution when required. The build checks that declared local images exist.

Team and supervision¶

By default, team.yaml supplies the Team page for groups and Supervision for individuals. To choose another name or a subdirectory, configure people.file in sciastro.yaml:

contentDir: content
people:
  file: orientacoes.yaml

Move the existing records to content/orientacoes.yaml; no team.yaml alias or duplicate is needed. The path is relative to contentDir and must stay inside it. The selected file replaces the default source in both automatic pages and composed type: team sections. Existing people.avatarFallback settings can remain alongside file.

An explicitly configured file must exist and pass the usual people validation; a typo fails the build instead of silently hiding the people section. Without people.file, the original optional team.yaml behavior is unchanged. File names do not change navigation labels or URLs; configure those separately.

Each person has one record:

- id: maria-example
  name: Maria Example
  role: student
  status: active
  level: masters
  startYear: 2026
  affiliation: Example University
  topic:
    pt: Discretização de modelos de transporte
    en: Discretization of transport models

Field	Values / behavior
`role`	`faculty`, `researcher`, or `student`
`status`	`active` or `alumni`
`level`	Required for students; must match a configured level
`startYear`, `endYear`	Optional; active members must not have an end year
`affiliation`, `topic`	Optional shared or translated text
`photo`	Optional `src`, localized `alt` and `position: [x, y]`; displayed in a circle
`avatarFallback`	Optional symbol for this person when `photo` is omitted; overrides the site's fallback
`links`	Optional list of objects with `label` and `url`

Active faculty appear first, followed by active researchers and active students organized by level. Alumni appear in a separate section regardless of their former role. Empty sections are hidden.

When a student finishes, change status to alumni and add endYear. Keep level to show the completed degree. That person automatically leaves the active list.

Default levels are undergraduate, masters, phd, and postdoc. To customize them, define the complete list in sciastro.yaml; list order determines display order:

studentLevels:
  - id: undergraduate
    label: { pt: Iniciação científica, en: Undergraduate research }
  - id: masters
    label: { pt: Mestrado, en: Master’s students }
  - id: phd
    label: { pt: Doutorado, en: Doctoral students }
  - id: internship
    label: { pt: Estágio, en: Internships }

Use role: researcher for postdoctoral researchers if that fits your group; the schema does not require treating them as students. Person, research-area and level identifiers must be unique within their respective lists.

Portraits and fallback symbols¶

All people cards use a circular image: faculty, researchers, active students and alumni. This applies to both site kinds, automatic pages and composed type: team sections. Add a photo to a person's entry in content/team.yaml:

- id: maria-example
  name: Maria Example
  role: student
  status: active
  level: masters
  photo:
    src: /images/maria.jpg
    alt: { pt: Retrato de Maria Example, en: Portrait of Maria Example }
    position: [50, 35]

Put the file in public/images/maria.jpg. Photos fill the circle with a centered crop by default, preserving their aspect ratio. position adjusts the crop using horizontal and vertical percentages from 0 to 100; [50, 50] is centered and [50, 35] moves the framing toward the top. The original file is unchanged. Use a shared alt string or provide it in every enabled language.

Set a shared institution symbol without lettering in sciastro.yaml:

people:
  avatarFallback:
    src: /images/institution-symbol.svg
    alt: { pt: Símbolo da instituição, en: Institution symbol }

The resolution order is:

The person's photo.
The person's avatarFallback in team.yaml.
people.avatarFallback in sciastro.yaml.
SciAstro's built-in fictional academic symbol, with no letters or affiliation to an actual institution. It adapts to the theme and requires no image file.

For a multi-institution group, add avatarFallback to individual records with the same fields as the shared setting. The header logo is independent: it may include an institution's full name and is deliberately not reused for people.

If the only available logo includes a wordmark, prepare a symbol-only image or define a crop. For example, for a 400 × 160 image whose symbol occupies the leftmost 160 × 160 pixels:

people:
  avatarFallback:
    src: /images/institution-logo.png
    alt: Institution symbol
    width: 400
    height: 160
    viewBox: 0 0 160 160

width and height are the original image dimensions, required when viewBox is set. viewBox is x y width height for the visible region; adjust it to your file. Fallback symbols fit inside the circle with padding instead of being stretched or cropped like portraits. The crop settings work for individual fallbacks too. SciAstro does not automatically detect or remove lettering from images.

Local paths are relative to public/ and automatically respect the deployment base. HTTP(S) images are also accepted, but their availability is not checked at build time. Fallback selection happens when photo is omitted; a declared local file that is missing fails validation, and an unavailable remote photo is not replaced automatically. Portraits and symbols render without browser JavaScript.

The starter sites include an original fictional symbol and an illustrated portrait as editable examples under public/images/, distributed under the project's MIT license. Replace them with your own authorized images. Existing sites do not need new fields: people without photos now show the built-in symbol instead of initials.

Additional pages¶

Register extra pages in pages.yaml, in navigation order:

- slug: projects
  title: { pt: Projetos, en: Projects }
  icon: lucide:folder-open
  body: { pt: projects.pt.md, en: projects.en.md }

slug stays the same in both languages. With Portuguese as the default, this example generates /projects/ and /en/projects/. Built-in pages have localized paths, such as /pesquisa/ and /en/research/.

Use additional pages for teaching, software, partnerships, CV and contact. The optional icon defaults to lucide:file-text; see the icon guide for menu overrides and language flags.

Downloadable files belong in public/. For example, link to public/files/cv.pdf with [Curriculum vitae](/files/cv.pdf).

Internal Markdown links start with /, without the hosting subdirectory. The generator adds base automatically. External links use https://. Markdown supports headings, lists, links, tables, images and code blocks. Raw HTML is rendered as text rather than executed.

Themes, logo and profile links¶

Choose theme: classic, theme: modern or theme: lncc. Visitors can switch between light and dark modes. The initial choice follows the system; an explicit choice is saved in the browser.

An optional logo in sciastro.yaml replaces the default geometric mark:

logo:
  src: /images/logo.svg
  alt: Research group name
links:
  - label: GitHub
    url: https://github.com/your-group
  - label: ORCID
    url: https://orcid.org/0000-0000-0000-0000

Replace the example identifiers and URLs with real ones. To validate a generated website before building, run pixi run pnpm check in its directory. Validation errors identify the relevant file and field.