# Foam File Format

This file is an example of a valid Foam file. Essentially it's just a markdown file with a bit of additional support for mediawiki-style `[[wiki-links]]`.

Here are a few specific constraints, mainly because our tooling is a bit fragmented. Most of these should be eventually lifted, and our requirement should just be "Markdown with `[[wiki-links]]`:

- **It needs to have a single top level `# Heading`.**
  - This will be used as document title.
    - [[decision-needed]] Do we need it?
    - [[decision-needed]] How much to deviate from just markdown
- **File name should not contain spaces,** e.g. `foam-file-format.md` is a valid name, but `Foam File Format.md` is not.
  - This is a temporary limitation and will be lifted in future versions.
  - Technically this actually works already, but may have some edge cases you don't want to deal with if you can avoid it.
- **File name should have extension `.md` or `.markdown`**
  - This is a temporary limitation and will be lifted in future versions.
  - At least `.mdx` will be supported, but ideally we'll support any file that you can map to `Markdown` language mode in VS Code
- **In addition to normal Markdown Links syntax you can use `[[media-wiki]]` links.** See [[wiki-links]] for more details.

[//begin]: # "Autogenerated link references for markdown compatibility"
[decision-needed]: decision-needed "Decision Needed"
[wiki-links]: wiki-links "Wiki Links"
[//end]: # "Autogenerated link references"
