@markuxt/markuxt 0.1.4

package/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,168 @@
+# Markuxt
+
+<div align="center">
+  <img src="src/public/images/logo.png" alt="Markuxt" width="360" />
+  <!-- <h1>Markuxt</h1> -->
+</div>
+
+A Markdown-first academic portal framework for laboratories, research groups, and knowledge communities, powered by [Nuxt 3](https://nuxt.com/).
+
+Markuxt provides a complete theme layer — layouts, pages, components, content transformers, and i18n — so that consuming sites only need to provide **content** and **configuration**.
+
+## Features
+
+- **Markdown-driven content** — Pages, members, publications, projects, positions, and news are all authored in Markdown with YAML frontmatter.
+- **Configurable navigation** — Define which pages appear in the header, footer, and route guard via a single `navigation` array in `appConfig`.
+- **Internationalization** — Built-in i18n support via `@nuxtjs/i18n`. Consuming sites provide their own locale files.
+- **Design system** — CSS custom properties for colors, spacing, typography, and more. Easy to override.
+- **Content transformers** — Binary assets (images, videos) placed next to Markdown files are automatically synced to `public/` for static serving.
+- **Mermaid diagrams** — First-class support with proper font loading and overflow handling.
+- **LaTeX / KaTeX** — Math rendering via `remark-math` + `rehype-katex`.
+- **404 page** — Custom error page with header and footer preserved.
+
+## Architecture
+
+```bash
+markuxt/
+├── nuxt.config.ts            # Layer configuration (modules, hooks, vite, etc.)
+├── app.config.d.ts           # TypeScript declarations for markuxt AppConfig
+├── src/
+│   ├── assets/main.css       # Design system & global styles
+│   ├── components/           # Vue components (AppHeader, AppFooter, Hero, etc.)
+│   ├── composables/          # Shared composables
+│   ├── content-transformers/ # Custom Nuxt Content transformers
+│   ├── error.vue             # Custom 404 error page
+│   ├── layouts/default.vue   # Default layout with header + footer
+│   ├── middleware/            # Route middleware (navigation guard)
+│   ├── pages/                # All page routes
+│   │   ├── index.vue         # Homepage
+│   │   ├── members/          # Members listing & detail pages
+│   │   ├── news/             # News listing & detail pages
+│   │   ├── positions/        # Open positions
+│   │   ├── projects/         # Projects listing & detail pages
+│   │   └── publications/     # Publications listing & detail pages
+│   ├── plugins/              # Nuxt plugins
+│   └── server/plugins/       # Server-side Nitro plugins
+└── package.json
+```
+
+## Configuration Reference
+
+Consuming sites configure Markuxt through `appConfig.markuxt` in their `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  appConfig: {
+    markuxt: {
+      // Logo image path
+      logo: {
+        src: '/images/logo.png',
+      },
+
+      // Navigation items — controls header nav, footer quick links,
+      // and route guarding. Pages NOT listed here will return 404.
+      navigation: [
+        { to: '/', labelKey: 'nav.home' },
+        { to: '/members', labelKey: 'nav.members' },
+        { to: '/publications', labelKey: 'nav.publications' },
+        { to: '/projects', labelKey: 'nav.projects' },
+        { to: '/positions', labelKey: 'nav.positions' },
+        { to: '/news', labelKey: 'nav.news' },
+      ],
+
+      // Contact information shown in footer
+      contact: {
+        email: 'lab@example.edu',
+        externalUrl: 'https://www.example.edu',
+        externalLabelKey: 'footer.universityLink', // i18n key
+      },
+
+      // Homepage carousel
+      carousel: {
+        fallbackImage: '/images/logo.png',
+        images: [
+          { src: '/images/photo1.jpg', alt: 'Lab', caption: 'Our Lab' },
+        ],
+      },
+
+      // Research areas on homepage — `icon` references a globally
+      // registered Vue component name (see Icons section below)
+      researchAreas: [
+        { icon: 'IconSearch', titleKey: 'research.aerospace', descKey: 'research.aerospaceDesc' },
+      ],
+    },
+  },
+})
+```
+
+### Navigation Guard
+
+Pages defined in `navigation` are accessible. Any markuxt section page (`/members`, `/publications`, `/projects`, `/positions`, `/news`) that is **not** listed will return a 404. The home page (`/`) is always accessible.
+
+## Icons
+
+Markuxt does **not** bundle any icon library. The consuming site is responsible for registering Vue components globally and referencing them by name in configuration.
+
+Example using `@icon-park/vue-next`:
+
+**`plugins/icons.ts`** (project root, outside `src/` to avoid Content scanning):
+
+```ts
+import Search from '@icon-park/vue-next/es/icons/Search'
+import Robot from '@icon-puxt/vue-next/es/icons/Robot'
+
+export default defineNuxtPlugin((nuxtApp) => {
+  nuxtApp.vueApp.component('IconSearch', Search)
+  nuxtApp.vueApp.component('IconRobot', Robot)
+})
+```
+
+**`nuxt.config.ts`**:
+
+```ts
+export default defineNuxtConfig({
+  plugins: ['~~/plugins/icons.ts'],
+  appConfig: {
+    markuxt: {
+      researchAreas: [
+        { icon: 'IconSearch', titleKey: 'research.search', descKey: 'research.searchDesc' },
+      ],
+    },
+  },
+})
+```
+
+## i18n
+
+Markuxt expects consuming sites to provide translation files. Translation keys used by Markuxt's components (e.g. `nav.home`, `footer.brand`, `members.staff`) must be present in the site's locale JSON files.
+
+## Content Structure
+
+Markuxt uses `@nuxt/content` v2. The consuming site configures the content source directory:
+
+```ts
+content: {
+  sources: {
+    content: {
+      driver: 'fs',
+      base: resolve(process.cwd(), 'src'),
+    },
+  },
+},
+```
+
+Expected content directories under the base:
+
+| Path            | Content Type                    |
+|-----------------|---------------------------------|
+| `members/`      | Member profiles (Markdown)      |
+| `news/`         | News articles (Markdown)        |
+| `publications/` | Publication entries (Markdown)  |
+| `projects/`     | Project descriptions (Markdown) |
+| `positions/`    | Open positions (Markdown)       |
+
+Binary assets (images, videos) placed alongside Markdown files are automatically synced to `public/_markuxt/` during build.
+
+## License
+
+[Apache-2.0](LICENSE)

package/app.config.d.ts

@@ -0,0 +1,33 @@
+declare module 'nuxt/schema' {
+  interface AppConfig {
+    markuxt?: {
+      logo?: {
+        src?: string
+      }
+      navigation?: Array<{
+        to: string
+        labelKey: string
+      }>
+      contact?: {
+        email?: string
+        externalUrl?: string
+        externalLabelKey?: string
+      }
+      carousel?: {
+        fallbackImage?: string
+        images?: Array<{
+          src: string
+          alt?: string
+          caption?: string
+        }>
+      }
+      researchAreas?: Array<{
+        icon: string
+        titleKey: string
+        descKey: string
+      }>
+    }
+  }
+}
+
+export {}

package/nuxt.config.ts

@@ -0,0 +1,170 @@
+// https://nuxt.com/docs/api/configuration/nuxt-config
+import { readdirSync, mkdirSync, existsSync, copyFileSync, rmSync } from 'fs'
+import { join, parse, extname, relative, resolve, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+// Site root directory — content, assets, i18n live here.
+// Override via MARKUXT_ROOT_DIR env var; defaults to 'src/'.
+const ROOT_DIR = process.env.MARKUXT_ROOT_DIR || 'src/'
+
+/**
+ * Sync non-document files (images, videos, etc.) from rootDir to rootDir/public/_markuxt/.
+ * This lets authors place assets next to their markdown files while still serving
+ * them as static files at build time (Nuxt Content v2 ignores binary files).
+ *
+ * Source:  src/members/staff/salman-ijaz.webp
+ * Target:  src/public/_markuxt/members/staff/salman-ijaz.webp
+ * URL:     /_markuxt/members/staff/salman-ijaz.webp
+ */
+function syncContentAssets(rootDir: string) {
+  const docExtensions = new Set(['.md', '.mdx', '.yml', '.yaml', '.json', '.csv'])
+  // Directories to skip (output dir and non-content dirs)
+  const skipDirs = new Set(['public', 'i18n'])
+  const targetDir = join(rootDir, 'public', '_markuxt')
+
+  // Clean previous output so stale files don't linger
+  if (existsSync(targetDir)) {
+    rmSync(targetDir, { recursive: true, force: true })
+  }
+
+  let copiedCount = 0
+
+  function walk(dir: string) {
+    if (!existsSync(dir)) return
+    const entries = readdirSync(dir, { withFileTypes: true })
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        if (!skipDirs.has(entry.name)) {
+          walk(fullPath)
+        }
+      } else if (entry.isFile()) {
+        const ext = extname(entry.name).toLowerCase()
+        if (!docExtensions.has(ext)) {
+          const rel = relative(rootDir, fullPath)
+          const destPath = join(targetDir, rel)
+          const destDir = parse(destPath).dir
+          if (!existsSync(destDir)) {
+            mkdirSync(destDir, { recursive: true })
+          }
+          copyFileSync(fullPath, destPath)
+          copiedCount++
+        }
+      }
+    }
+  }
+
+  walk(rootDir)
+  console.log(`[Markuxt] Synced ${copiedCount} asset(s) → public/_markuxt/`)
+}
+
+export default defineNuxtConfig({
+  compatibilityDate: '2024-11-01',
+  devtools: { enabled: true },
+
+  // Source directory
+  srcDir: 'src/',
+
+  // Nuxt Content module + i18n
+  modules: ['@nuxt/content', '@nuxtjs/i18n'],
+
+  // i18n defaults — consuming site overrides locales and langDir
+  i18n: {
+    defaultLocale: 'en',
+    strategy: 'no_prefix',
+    detectBrowserLanguage: {
+      useCookie: true,
+      cookieKey: 'i18n_locale',
+      redirectOn: 'root'
+    }
+  },
+
+  // Build-time hooks
+  hooks: {
+    // Register a custom transformer for binary assets (images, videos, etc.)
+    // so @nuxt/content does not warn about unsupported file extensions.
+    'content:context': (ctx: { transformers: string[] }) => {
+      ctx.transformers.push(
+        resolve(__dirname, 'src/content-transformers/binary-assets.ts')
+      )
+    },
+    'build:before': () => {
+      const cwd = process.cwd()
+      const rootDir = join(cwd, ROOT_DIR)
+
+      // Sync assets to public/_markuxt/
+      syncContentAssets(rootDir)
+    }
+  },
+
+  // App configuration
+  app: {
+    head: {
+      meta: [
+        { charset: 'utf-8' },
+        { name: 'viewport', content: 'width=device-width, initial-scale=1' }
+      ],
+      link: [
+        { rel: 'icon', type: 'image/png', href: '/images/logo.png' },
+        { rel: 'preconnect', href: 'https://fonts.googleapis.com' },
+        { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' },
+        { rel: 'stylesheet', href: 'https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,400;0,9..40,500;0,9..40,600;0,9..40,700;1,9..40,400&family=Fraunces:ital,opsz,wght@0,9..144,100;0,9..144,200;0,9..144,300;0,9..144,400;0,9..144,500;0,9..144,600;0,9..144,700;0,9..144,800;0,9..144,900;1,9..144,100;1,9..144,200;1,9..144,300;1,9..144,400;1,9..144,500;1,9..144,600;1,9..144,700;1,9..144,800;1,9..144,900&display=swap' }
+      ],
+      script: []
+    },
+    pageTransition: { name: 'page', mode: 'out-in' },
+    baseURL: process.env.NUXT_PUBLIC_BASE_URL || '/'
+  },
+
+  // CSS — resolve relative to layer root, not the consuming site
+  css: [resolve(__dirname, 'src/styles/main.css')],
+
+  // Content module configuration
+  content: {
+    highlight: {
+      theme: {
+        default: 'github-light',
+        dusk: 'github-dark'
+      }
+    },
+    navigation: {
+      fields: ['icon', 'title', 'description']
+    },
+    markdown: {
+      tags: {
+        img: 'ProseImg',
+        video: 'ProseVideo'
+      },
+      remarkPlugins: {
+        'remark-math': {}
+      },
+      rehypePlugins: {
+        'rehype-katex': {
+          output: 'htmlAndMathml',
+          strict: false
+        }
+      }
+    }
+  },
+
+  // Nitro configuration
+  nitro: {
+    baseURL: process.env.NUXT_PUBLIC_BASE_URL || '/'
+  },
+
+  // TypeScript
+  typescript: {
+    strict: true,
+    typeCheck: false
+  },
+
+  // Vite
+  vite: {
+    optimizeDeps: {
+      include: ['@nuxt/content', 'mermaid']
+    }
+  }
+})

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@markuxt/markuxt",
+  "version": "0.1.4",
+  "description": "A Markdown-first academic portal framework for laboratories, research groups, and knowledge communities, powered by Nuxt.",
+  "author": "hnrobert",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./nuxt.config.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/markuxt/markuxt.git"
+  },
+  "publishConfig": {
+  },
+  "files": [
+    "nuxt.config.ts",
+    "app.config.ts",
+    "app.config.d.ts",
+    "src/"
+  ],
+  "scripts": {
+    "dev": "nuxt dev",
+    "build": "nuxt build",
+    "generate": "nuxt generate",
+    "pack:local": "pnpm pack --pack-destination /tmp/markuxt-dist",
+    "postinstall": "nuxt prepare"
+  },
+  "dependencies": {
+    "@icon-park/vue-next": "^1.4.2",
+    "@nuxt/content": "^2.13.2",
+    "@nuxtjs/i18n": "^10.4.0",
+    "katex": "0.16.47",
+    "mermaid": "11.15.0",
+    "nuxt": "^3.15.1",
+    "rehype-katex": "7.0.1",
+    "remark-math": "6.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "typescript": "^5.7.3",
+    "vue-tsc": "^3.2.4"
+  }
+}