github/foam
1
1
Fork 0
mirror of https://github.com/foambubble/foam.git synced 2026-01-10 06:28:12 -05:00
Code Issues Packages Projects Releases Wiki Activity

Standardize on wikilink, MediaWiki, and GitHub (#716)

Browse Source 
* Standardize on `wikilink`

Not `wiki-link`, nor `wiki link`

https://en.wikipedia.org/wiki/Help:Link#Wikilinks

* Standardize on `MediaWiki`

Not `media-wiki`, nor `mediawiki`

https://www.mediawiki.org/wiki/MediaWiki

* Standardize on `GitHub`

Not `Github`

Co-authored-by: Riccardo <code@riccardoferretti.com>
This commit is contained in:
Michael Overmeyer
2021-07-21 18:19:35 -04:00
committed by GitHub
parent 1659fe37d9
commit 721a6cc935
25 changed files with 54 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/dev/foam-core.md
View File

@@ -17,7 +17,7 @@
`foam-core`'s primary responsibility is to build an API on top of a workspace of markdown files, which allows us to:
- Treat files as a graph, based on links
- Can be either [[wiki-links]] or relative `[markdown](links.md)` style
- Can be either [[wikilinks]] or relative `[markdown](links.md)` style
- We need to know about the edges (connections) as well as nodes
- What link points to what other file, etc.
- Needs to have the exact link text, e.g. even if `[[some-page]]` or `[[some-page.md]]` or `[[Some Page]]` point to the same document (`./some-page.md`), we need to know which format was used, so [[link-reference-definitions]] can be generated correctly
@@ -61,7 +61,7 @@ Here are some example use cases that the core should support. They don't need to
- Adding and editing page content
- [[materialized-backlinks]]
- [[link-reference-definitions]] for [[wiki-links]]
- [[link-reference-definitions]] for [[wikilinks]]
- [Frontmatter](https://jekyllrb.com/docs/front-matter/)
- Finding all documents with `#tag`
- Finding all documents with instances of `[[link]]`
@@ -99,7 +99,7 @@ Useful for knowing what needs to be supported. See [[feature-comparison]].
[workspace-janitor]: ../features/workspace-janitor.md "Janitor"
[cli]: ../features/cli.md "Command Line Interface"
[build-vs-assemble]: build-vs-assemble.md "Build vs Assemble"
[wiki-links]: ../wiki-links.md "Wiki Links"
[wikilinks]: ../wikilinks.md "Wikilinks"
[link-reference-definitions]: ../features/link-reference-definitions.md "Link Reference Definitions"
[materialized-backlinks]: materialized-backlinks.md "Materialized Backlinks (stub)"
[todo]: todo.md "Todo"

8
docs/dev/foam-file-format.md
View File

@@ -1,16 +1,16 @@
# 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]]`.
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 `[[wikilinks]]`.
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]]`:
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 `[[wikilinks]]`:
- **The first top level `# Heading` will be used as title for the note.**
- If not available, we will use the file name
- **File name should have extension `.md`**
- 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.
- **In addition to normal Markdown Links syntax you can use `[[MediaWiki]]` links.** See [[wikilinks]] for more details.
[//begin]: # "Autogenerated link references for markdown compatibility"
[wiki-links]: ../wiki-links.md "Wiki Links"
[wikilinks]: ../wikilinks.md "Wikilinks"
[//end]: # "Autogenerated link references"

12
docs/dev/link-reference-definition-improvements.md
View File

@@ -4,13 +4,13 @@
### File-by-file Insertion
For the time being, if you want to get [[wiki-links]] into all files within the workspace, you'll need to generate the link reference definitions yourself file-by-file (with the assistance of Foam).
For the time being, if you want to get [[wikilinks]] into all files within the workspace, you'll need to generate the link reference definitions yourself file-by-file (with the assistance of Foam).
### Wikilinks don't work on GitHub
> **TL;DR;** [workaround](#workaround) in the end of the chapter.
If you click any of the wiki-links on GitHub web UI (such as the `README.md` of a project), you'll notice that the links break with a 404 error.
If you click any of the wikilinks on GitHub web UI (such as the `README.md` of a project), you'll notice that the links break with a 404 error.
At the time of writing (June 28 2020) this is a known, but unsolved error. To understand why this is the case, we need to understand what we are trading off.
@@ -59,7 +59,7 @@ Problem space in essence:
- may clutter the search results
- During build-time (when converting markdown to html for publishing purposes)
- link reference definitions are needed, if the files are published via such tools (or to such platforms) that don't understand wikilinks
- link reference definitions might have to be in different formats depending on the publish target (e.g. Github pages vs Github UI)
- link reference definitions might have to be in different formats depending on the publish target (e.g. GitHub pages vs GitHub UI)
The potential solution:
@@ -122,8 +122,8 @@ The potential solution:
```
- With Foam repo, just use edit-time link reference definitions with '.md' extension - this makes the links work in the Github UI
- Have publish target defined for Github pages, that doesn't use '.md' extension, but still has the link reference definitions. Generate the output into gh-pages branch (or separate repo) with automation.
- With Foam repo, just use edit-time link reference definitions with '.md' extension - this makes the links work in the GitHub UI
- Have publish target defined for GitHub pages, that doesn't use '.md' extension, but still has the link reference definitions. Generate the output into gh-pages branch (or separate repo) with automation.
- This naturally requires first removing the existing link reference definitions during the build
- Other
- To clean up the search results, remove link reference definition section guards (assuming that these are not defined by the markdown spec). Use unifiedjs parse trees to identify if there's missing (or surplus) definitions (check if they are identified properly by the library), and just add the needed definitions to the bottom of the file (without guards) AND remove them if they are not needed (anywhere from the file).
@@ -137,7 +137,7 @@ UI-wise, the publish targets could be picked in some similar fashion as the run/
- [tracking issue on GitHub](https://github.com/foambubble/foam/issues/16)
[//begin]: # "Autogenerated link references for markdown compatibility"
[wiki-links]: ../wiki-links.md "Wiki Links"
[wikilinks]: ../wikilinks.md "Wikilinks"
[link-reference-definitions]: ../features/link-reference-definitions.md "Link Reference Definitions"
[backlinking]: ../features/backlinking.md "Backlinking"
[//end]: # "Autogenerated link references"

4
docs/dev/roadmap.md
View File

@@ -25,7 +25,7 @@ If a roadmap item is a stub, **consider** opening a [GitHub issue](https://githu
- [[improve-default-workspace-settings]]
- Discussion: [foam#270](https://github.com/foambubble/foam/issues/270)
- Improve [[git-integration]]
- Fix [[wiki-links]] compatibility issues
- Fix [[wikilinks]] compatibility issues
- Simplify [[foam-file-format]]
### Core features
@@ -87,7 +87,7 @@ The community is working on a number of automated scripts to help you migrate to
[recipes]: ../recipes/recipes.md "Recipes"
[contribution-guide]: ../contribution-guide.md "Contribution Guide"
[git-integration]: ../features/git-integration.md "Git Integration"
[wiki-links]: ../wiki-links.md "Wiki Links"
[wikilinks]: ../wikilinks.md "Wikilinks"
[foam-file-format]: foam-file-format.md "Foam File Format"
[unlinked-references]: unlinked-references.md "Unlinked references (stub)"
[make-backlinks-more-prominent]: ../recipes/make-backlinks-more-prominent.md "Make Backlinks More Prominent"