How to Contribute • Valeon

Dyslexia-friendly font Word highlight Dark mode

Author quick-start

Fork or clone the valeon-posts repository and create a feature branch.
If you need a new or updated author profile, also fork or clone the valeon-authors repository.
Create or refresh your author directory using your author slug, update author.json, and stage supporting assets.
Create your post folder [YYYY]-[MM]-[DD]-[post-slug]/ with post.md, cover.(png|jpg|webp), and an assets/ subfolder for embeds.
Review frontmatter, citations, media, and accessibility using the checklists below.
Push your branch and open linked pull requests (posts and, if needed, authors).

Before you start

Rights, originality, and licensing

Submit only work you created or have explicit written permission to reprint. Keep documentation handy.
By submitting, you warrant that you control the rights to every text, image, and asset you include.
Valeon publishes accepted work under a 30-day exclusive digital license, followed by a perpetual non-exclusive license. You retain copyright at all times.
We comply with DMCA and takedown law. Send removal requests via the contact page with supporting evidence.

Conflicts of interest and sponsorships

Disclose financial ties, sponsorships, advisory roles, affiliate relationships, or holdings mentioned in the piece.
Mark affiliate links clearly (for example, add "(affiliate)" in text).
Explain how potential conflicts are mitigated when it aids reader trust.

Prohibited content and legal compliance

No hate speech, harassment, doxxing, threats, or discriminatory language.
No plagiarism, fabricated sources, or misinformation.
No unsourced medical, legal, or financial advice. Cite qualified expertise when you discuss sensitive claims.
No unlawful content, explicit material, or instructions for illegal activity.
Valeon may decline or remove submissions that violate policy or applicable law.

Repositories you will use

Contributors work exclusively in the Valeon content repositories. Stay focused on Markdown, metadata, and assets—no site build or deployment steps are required.

valeon-posts: https://github.com/sayedhfatimi/valeon-posts (articles, images, frontmatter).
valeon-authors: https://github.com/sayedhfatimi/valeon-authors (author bios, social links, optional avatars).

Use feature branches, keep author and post updates in sync, and cross reference pull requests when both repositories change.

Create your author profile

Slug format: lowercase, hyphenated (for example, alex-lee). The slug must match the author field in every post frontmatter.
Directory layout: place author.json inside [author-slug]/ with any assets in [author-slug]/assets/.
Fill author.json with name, a concise bio, social links, optional gravatar email, and featured publications.
Publication-specific media (covers, diagrams, embeds) live under ./assets/[publication-slug]/*. Keep filenames descriptive.
Valeon auto-generates initials-based avatars. If you prefer a photo, include the email tied to your Gravatar account in author.json and update your Gravatar image.

valeon-authors/
  alex-lee/
    author.json
    assets/
      liquidity-series/
        cover.png
        diagram.svg

Create your post

Each post lives in [YYYY]-[MM]-[DD]-[post-slug]/ with post.md, cover.(png|jpg|webp), and an assets/ folder for embeds referenced relatively.
All headings in post.md start at ##. Keep one idea per section and use subheadings for supporting points.
Valeon auto-generates a table of contents from your headings, so keep the hierarchy clean and consistent.
Acceptable cover formats are PNG, JPG, or WEBP at exactly 1536x1024. Optimise file size while preserving clarity, and supply meaningful coverAlt text.
Avoid text on cover images—keep them purely illustrative so the title and description remain legible across devices and feeds.
Tags: provide 5-15 lowercase, hyphenated slugs (for example, systems-thinking). Avoid duplicates and singular/plural variants.
Use $ delimiters for LaTeX expressions so math renders correctly on Valeon.
Use canonical when cross-posting. Omit the field if Valeon is the original venue.

valeon-posts/
  2025-01-22-market-systems/
    post.md
    cover.png
    assets/
      chart.png
      diagram.svg

Strict frontmatter template

---
title: "Example Title"
pubDate: "2025-01-15T12:00:00Z"
updatedDate: "2025-01-20T12:00:00Z"
excerpt: "Plain text summary at 160 characters or less."
cover: ./cover.png
coverAlt: "Illustration of cash flows moving through a market system."
author: author-slug
series:
  slug: systems-series
  part: 2
featured: false
tts: true # defaults to true; set false only to exclude from TTS/podcast
categories:
  - markets
tags:
  - systems-thinking
  - liquidity-risks
  - narrative-economics
canonical: https://example.com/original
---

Remove canonical when Valeon is the original publisher or replace the URL when cross-posting with permission.

Manual frontmatter validation

title present, concise, plain text.
pubDate (required) and updatedDate (optional) in UTC ISO 8601 (YYYY-MM-DDTHH:MM:SSZ).
excerpt plain text and at or under 160 characters.
cover points to ./cover.(png|jpg|webp).
coverAlt is descriptive and not just a filename.
author equals your author slug.
series omitted unless the post belongs to a defined series, with slug and optional part.
featured either true or false.
tts omitted (defaults to true) or set to false if you are opting out of audio distribution.
categories lists one or more category slugs from the predefined set in src/content/categories.
tags include 5-15 lowercase, hyphenated items with no duplicates.
Include canonical only when syndicating or cross-posting.

Preferred key ordering (manual editors)

If you are not using the repository's Obsidian formatter, sort your YAML keys in this order to match Valeon's automation:

title
pubDate
updatedDate
excerpt
cover
coverAlt
author
series
featured
tts
categories
tags
canonical

Outline example

## Context: What changes in liquidity this quarter?
- Frame the thesis and stakes for the reader.

## Mechanism: How market plumbing amplifies risk
- Explain first-principle mechanics with one core example.

## Implication: What investors should watch
- Offer practical takeaways and forward-looking signals.

## Reflection: Tensions worth interrogating
- Close with an open question or invitation to explore further.

Prefer any editor you like. The valeon-posts repository includes optional Obsidian helpers for slug generation, folder scaffolding, linting, and automatic frontmatter formatting if you want automation.

Quality and accessibility

Citations and fact-checking

Provide sources for factual claims, statistics, and direct quotations. Link inline to primary or authoritative sources.
Use footnotes for longer essays only when inline links disrupt flow. Keep references consistent.
Do not publish unsourced medical, financial, or legal advice. When in doubt, cite or remove the claim.

Voice, tone, and structure

Write reader-first, define jargon, and prefer clear language over insider shorthand.
Recommended word counts: essays 1,200-3,000 words, features 3,000-6,000 words. Poetry is exempt.
Keep sections focused on a single idea and use headings to guide the narrative.

SEO and metadata hygiene

Keep excerpt under 160 characters with straight quotes and plain text.
Use descriptive anchor text for links (avoid "click here").
Provide a canonical URL when syndicating or cross-posting outside Valeon.

Audio and distribution

Valeon's podcast pipeline synthesizes narration with OpenAI's tts-1-hd model using the onyx voice. Each episode credits the author in the intro and description.
To opt out of audio and podcast distribution, set tts: false in your post frontmatter. The pipeline reads this flag and skips synthesis; no additional tooling is required.
Audio-safe writing tips: give phonetic hints for uncommon names, avoid unexplained formulas or figure references, and note when visuals require extra context.

The automation lives in scripts/podcast-pipeline.ts, which handles text-to-speech generation, object storage uploads, and podcast feed updates end-to-end.

Submit for review

Branch and commit conventions

Branches: feat/post: YYYY-MM-DD-slug (new post), fix/post: YYYY-MM-DD-slug (updates), chore/author: add-slug (author profiles).
Commits: feat(post): New Blog Post - Title, fix(post): Update - Title, chore(author): Add - Author Name.

Coordinated pull requests

Open a pull request in valeon-posts for every submission.
When adding or updating an author profile, open a companion pull request in valeon-authors.
Cross-link the PRs and reference the matching branch names in each description.
Note conflicts, and licensing confirmations in the PR body.

Copy-paste PR checklist

- [ ] Correct branch naming convention used.
- [ ] Author slug matches folder name and `author` in frontmatter.
- [ ] One category (from the 8 predefined) + 5-15 hyphenated tags.
- [ ] Cover image is 1536x1024, optimized; all images include alt text.
- [ ] Frontmatter fields present and well-formed; dates are UTC ISO 8601.
- [ ] All factual claims include citations/links.
- [ ] Rights/licensing confirmed; no prohibited content.
- [ ] AI-assistance disclosure included if applicable.
- [ ] `tts: false` set in frontmatter if opting out of TTS/podcast distribution.
- [ ] Linked PR opened in the other repo (if author data changed).

Communication and editorial process

Expect an initial editorial response within 7-10 days. We respond via GitHub review comments or inline suggestions.
Revisions may include clarifying questions, requested rewrites, or fact-check notes. Address them in follow-up commits.
Have a complex or sensitive topic? Reach out through the contact page before drafting to coordinate.
Publication remains at the discretion of Valeon editorial staff.

After publication

Need updates? Open a new branch using fix/post: YYYY-MM-DD-slug and a pull request with fix(post): Update - Title. Update updatedDate in frontmatter.
During the 30-day exclusive window, link to the Valeon page when sharing. After that, you may syndicate elsewhere with a canonical link back to Valeon and an attribution note.
Podcast audio will refresh if substantial edits land. Mention this in your update PR if the narration needs re-generation.
For corrections or takedown requests, contact Valeon editorial with the relevant context and supporting materials.

Extras

Working on a series idea? Share a brief outline and the expected number of posts via the contact form or by opening an issue in valeon-posts so we can coordinate themes and publishing cadence.
Posts with exceptional craft, insight, or research may be featured on the Valeon homepage and highlighted across channels.

Privacy Terms Tech Stack Sitemap