-
Notifications
You must be signed in to change notification settings - Fork 1
/
foam-docs-2020-07-16.json
7989 lines (7989 loc) · 320 KB
/
foam-docs-2020-07-16.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
{
"_isDirected": true,
"_isMultigraph": false,
"_isCompound": false,
"_nodes": {
"mobile-apps": {
"id": "mobile-apps",
"title": "Mobile Apps",
"source": "# Mobile Apps\n\nWe must always ask ourselves, [[build-vs-assemble]]. \n\nThis Roadmap item discusses existing assembled solutions, and some thoughts on future Foam mobile experience.\n\n## Existing solutions\n\n### [GitJournal](https://gitjournal.io/)\n\n#### Pros\n- Open source\n- Already a usable solution. \n- Provides functionality to edit, create, and browser markdown files.\n- Support journal mode, todo lists, and free writing\n- Syncs to GitHub repo\n\n#### Cons\n- Doesn't support [[wiki-links]] **(deal breaker, but support [coming soon](https://twitter.com/GitJournal_io/status/1280194357296062466))**\n- Doesn't generate link reference lists (but this is ok, since [[workspace-janitor]] as a GitHub action can solve this)\n- Not as sleek as Apple/Google notes, some keyboard state glitching on Android, etc.\n- Lack of control over roadmap. Established product with a paid plan, so may not be open to Foam-supportive changes and additions that don't benefit most users.\n\nVerdict: Good. By far best effort/outcome ratio would be to help improve GitJournal rather than building a [bespoke mobile app](#bespoke-mobile-app-for-foam).\n\n## Bespoke mobile app for Foam\n\nGiven we already have a solution, why would we spend time and effort building a bespoke mobile app?\n\n- Taking notes on the go is a key part of a good note taking process, and the process should feel effortless\n- Having a custom app could help us support key user workflows in a more Foam-specific manner\n\nIf such an app was worth building, it would have to have the following features:\n\n- Instant loading and syncing for quick notes\n- Sleek, simple, beautifully designed user experience.\n- Ability to search and navigate forward links and back links (onlly in paid GitJournal version)\n- Killer feature that makes it the best note taking tool for Foam (?)\n\nGiven the effort vs reward ratio, it's a low priority for core team, but if someone wants to work on this, we can provide support! Talk to us on the #mobile-apps channel on [Foam Discord](https://discord.gg/rtdZKgj).\n\n\n[//begin]: # \"Autogenerated link references for markdown compatibility\"\n[todo]: todo \"Todo\"\n[roadmap]: roadmap \"Roadmap\"\n[build-vs-assemble]: build-vs-assemble \"Build vs Assemble\"\n[wiki-links]: wiki-links \"Wiki Links\"\n[workspace-janitor]: workspace-janitor \"Workspace Janitor (stub)\"\n[//end]: # \"Autogenerated link references\"",
"path": "/Users/swanson/dev/foam/docs/mobile-apps.md",
"links": [
{
"to": "build-vs-assemble",
"text": "build-vs-assemble",
"position": {
"start": {
"line": 3,
"column": 31,
"offset": 45
},
"end": {
"line": 3,
"column": 52,
"offset": 66
},
"indent": []
}
},
{
"to": "wiki-links",
"text": "wiki-links",
"position": {
"start": {
"line": 19,
"column": 19,
"offset": 475
},
"end": {
"line": 19,
"column": 33,
"offset": 489
},
"indent": []
}
},
{
"to": "workspace-janitor",
"text": "workspace-janitor",
"position": {
"start": {
"line": 20,
"column": 64,
"offset": 661
},
"end": {
"line": 20,
"column": 85,
"offset": 682
},
"indent": []
}
}
]
},
"build-vs-assemble": {
"id": "build-vs-assemble",
"title": "Build vs Assemble",
"source": "# Build vs Assemble\n\nThe Foam prototype is built by assembling third-party extensions, which seems like a good strategy because\n\n- It supports picking and mixing of tools and workflows\n- Less code to write an maintain\n\nBut there's also a bunch of roadmap items that are hard to implement this way, as the third party plugins don't do exactly what we want them to do (e.g. Markdown All In One is not compatible with [[referencing-notes-by-title]].\n\nOverall, we should strive to build big things from small things. Focused, interoperable modules are better, because they allow users to pick and mix which features work for them. A good example of why this matters is the Markdown All In One extension we rely on: While it provides many of the things we need, a few of its features are incompatible with how I would like to work, and therefore it becomes a limiter of how well I can improve my own workflow.\n\nHowever, there becomes a point where we may benefit from implementing a centralised solution, e.g. a syntax, an extension or perhaps a VSCode language server. As much as possible, we should allow users to operate in a decentralised manner.\n\n[//begin]: # \"Autogenerated link references for markdown compatibility\"\n[referencing-notes-by-title]: referencing-notes-by-title \"Referencing notes by title\"\n[//end]: # \"Autogenerated link references\"\n",
"path": "/Users/swanson/dev/foam/docs/build-vs-assemble.md",
"links": [
{
"to": "referencing-notes-by-title",
"text": "referencing-notes-by-title",
"position": {
"start": {
"line": 8,
"column": 197,
"offset": 415
},
"end": {
"line": 8,
"column": 227,
"offset": 445
},
"indent": []
}
}
]
},
"wiki-links": {
"id": "wiki-links",
"title": "Wiki Links",
"source": "# Wiki Links\n\nFoam enables you to Link pages together using `[[file-name]]` annotations (i.e. `[[media-wiki]]` links).\n\n- Both `[[file-name]]` and `[[file-name.md]]` work\n- Type `[[` and start typing a file name for autocompletion.\n- `Cmd` + `Click` ( `Ctrl` + `Click` on Windows ) on file name to navigate to file (`F12` also works while your cursor is on the file name)\n- `Cmd` + `Click` ( `Ctrl` + `Click` on Windows ) on non-existent file to create that file in the workspace.\n\n> If the `F12` shortcut feels unnatural you can rebind it at File > Preferences > Keyboard Shortcuts by searching for `editor.action.revealDefinition`.\n\n## Required extensions\n\n - [Markdown Notes](https://marketplace.visualstudio.com/items?itemName=kortina.vscode-markdown-notes) (core functionality)\n - [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode) (for Markdown compatibility)\n\n## Markdown compatibility\n\nThe [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode) extension automatically generates [[link-reference-definitions]] at the bottom of the file to make wiki-links compatible with Markdown tools and parsers.\n\n## Read more\n\n- [[foam-file-format]]\n- See [[link-reference-definition-improvements]] for further discussion on current problems and potential solutions.\n\n[//begin]: # \"Autogenerated link references for markdown compatibility\"\n[link-reference-definitions]: link-reference-definitions \"Link Reference Definitions\"\n[foam-file-format]: foam-file-format \"Foam File Format\"\n[link-reference-definition-improvements]: link-reference-definition-improvements \"Link Reference Definition Improvements\"\n[//end]: # \"Autogenerated link references\"\n",
"path": "/Users/swanson/dev/foam/docs/wiki-links.md",
"links": [
{
"to": "link-reference-definitions",
"text": "link-reference-definitions",
"position": {
"start": {
"line": 19,
"column": 127,
"offset": 1057
},
"end": {
"line": 19,
"column": 157,
"offset": 1087
},
"indent": []
}
},
{
"to": "foam-file-format",
"text": "foam-file-format",
"position": {
"start": {
"line": 23,
"column": 3,
"offset": 1194
},
"end": {
"line": 23,
"column": 23,
"offset": 1214
},
"indent": []
}
},
{
"to": "link-reference-definition-improvements",
"text": "link-reference-definition-improvements",
"position": {
"start": {
"line": 24,
"column": 7,
"offset": 1221
},
"end": {
"line": 24,
"column": 49,
"offset": 1263
},
"indent": []
}
}
]
},
"workspace-janitor": {
"id": "workspace-janitor",
"title": "Workspace Janitor",
"source": "# Workspace Janitor\n\n## What is it?\n\nTo store your personal knowledge graph in markdown files instead of a database, we need some additional tooling to create and maintain:\n\n- Relationships between notes\n - link references for [[wiki-links]]/markdown compatibility\n - [[materialized-backlinks]]\n - etc.\n- Format and structure of each note (e.g. title)\n- Renaming and refactoring files and directories\n- Linting related functionality\n - File names\n - Note links\n - Zettelkasten linking\n- Visibility for orphaned notes\n\nThis is necessary:\n\n- When migrating to Foam\n- To maintain your workspace health over long period of time\n\n## Problem\n\nCurrently, the VS Code extension is very naive, and only updates the currently active editor. This isn't sufficient, because:\n\n- For e.g. [[materialized-backlinks]] to work, files need to update in the background.\n - Separation of clean vs generated workspace for publishing?\n - Support for standard markdown tools\n - Output to a /build directory\n - Would have to implement a custom previewer\n - [[todo]] **Janne Ojanaho! Write a short proposal for this.**\n- If VS Code extension bugs our or is not ran, the workspace can lead in an inconsistent state\n- In collaboration scenarios, two people may change the same file, causing incomplete updates\n- If someone pushes changes from outside VS Code (Obsidian, Git Journal, etc.) links aren't updated\n\n## Proposal\n\nImplement a note janitor (working title, named after Andy Matuschak's [note-link-janitor](https://github.com/andymatuschak/note-link-janitor)), which ensures all files are correctly linked and updated, no matter how changes happen.\n\nJanitor should be runnable:\n\n- From VS Code\n - Replaces the existing logic in extension.ts\n - In theory, we could do this using the [VS Code Tasks](https://code.visualstudio.com/docs/editor/tasks), exposing it from foam-vscode with a [TaskProvider](https://code.visualstudio.com/api/extension-guides/task-provider)\n - It's not clear to me whether modifying the file in the active VS Code buffer from a background task is problematic for e.g. focus/selection management. I think this is how e.g. Prettier works, but not sure if there's some special case for the active editor.\n - VS Code provides its own workspace watching functionality. Not sure it would be beneficial to use this over just chokidar-style file watching in the background\n- As a pre-push Git Hook (is this a good idea?) to ensure we send fully formed note graphs, even if you had to do some editing outside vs code\n- As a GitHub Action (for incoming changes via PRs and other apps like GitJournal)\n - Run the \"build\" and push back to master/gh-pages\n- As a NPM script/dependency for any other purpose\n\n## Software architecture\n\n- It's not really clear to me whether the workspace janitor should be its own package, or if the Janitor should just be the [[cli]] package, or the [[foam-core]] package.\n- Ideally the janitor should be lightweight so installing it on CI is quick\n- It would be cool if it didn't have many weird node-specific dependencies, maybe it could be even ran INSIDE a mobile application?\n- We don't want to pollute foam-core, but janitor might actually get quite diverse in use cases.\n\nDecoupling things like the core janitor API from the CLI API would help potentially with situations where we might want to have a separate file watcher strategy for CLI and active VS Code workspaces (see above).\n\n[//begin]: # \"Autogenerated link references for markdown compatibility\"\n[wiki-links]: wiki-links \"Wiki Links\"\n[materialized-backlinks]: materialized-backlinks \"Materialized Backlinks (stub)\"\n[cli]: cli \"Command Line Interface\"\n[foam-core]: foam-core \"Foam Core\"\n[todo]: todo \"Todo\"\n[//end]: # \"Autogenerated link references\"\n",
"path": "/Users/swanson/dev/foam/docs/workspace-janitor.md",
"links": [
{
"to": "wiki-links",
"text": "wiki-links",
"position": {
"start": {
"line": 8,
"column": 25,
"offset": 228
},
"end": {
"line": 8,
"column": 39,
"offset": 242
},
"indent": []
}
},
{
"to": "materialized-backlinks",
"text": "materialized-backlinks",
"position": {
"start": {
"line": 9,
"column": 5,
"offset": 270
},
"end": {
"line": 9,
"column": 31,
"offset": 296
},
"indent": []
}
},
{
"to": "materialized-backlinks",
"text": "materialized-backlinks",
"position": {
"start": {
"line": 28,
"column": 12,
"offset": 781
},
"end": {
"line": 28,
"column": 38,
"offset": 807
},
"indent": []
}
},
{
"to": "todo",
"text": "todo",
"position": {
"start": {
"line": 33,
"column": 7,
"offset": 1050
},
"end": {
"line": 33,
"column": 15,
"offset": 1058
},
"indent": []
}
},
{
"to": "cli",
"text": "cli",
"position": {
"start": {
"line": 56,
"column": 125,
"offset": 2871
},
"end": {
"line": 56,
"column": 132,
"offset": 2878
},
"indent": []
}
},
{
"to": "foam-core",
"text": "foam-core",
"position": {
"start": {
"line": 56,
"column": 149,
"offset": 2895
},
"end": {
"line": 56,
"column": 162,
"offset": 2908
},
"indent": []
}
}
]
},
"daily-notes": {
"id": "daily-notes",
"title": "Daily notes",
"source": "# Daily notes\n\nThe idea is to make it easier for people to be able to create Daily notes.\n\nThis feature is open for discussion at [foambubble/foam#54](https://github.com/foambubble/foam/issues/54).\n\n## Must have\n\n- Should exist as part of [foam-vscode](https://github.com/foambubble/foam/tree/master/packages/foam-vscode) extension \n- A new command \"Foam: Open Daily Note\", which creates new file and focuses into it, or opens the existing file for today if it exists already.\n - File should have a Level 1 `# Heading`\n- Extension should define a hotkey for it (TBD? What do other apps do?)\n\n## Should have\n\n- Settings to customise:\n - Format of file name, default to `yyyy-mm-dd`\n - Format of title\n - Default to same as file name\n - Allow override e.g. `MMMMM D, YYYY`, to July 8. 2020 (locale specific)\n - Extension of file, default to `.md`\n - Directory into which file should be created, default to `./` (workspace root)\n - Should create directory if needed\n\n## Could have\n- Automatically update a \"daily notes\" index file, newest first. Format TBD\n - A custom note template .md file that could be stored in `.vscode/` directory (would supercede having to format the title)\n - This could be useful for people who e.g. want there to be a format for every day's notes with fixed questions and stuff.\n - Maybe we could do it with just back links or tags, by putting e.g. `[[daily]]` into the note template\n - If files were named in alphabetic sortable order, and back links would display in reverse order, newest would always come on top\n\n[//begin]: # \"Autogenerated link references for markdown compatibility\"\n[todo]: todo \"Todo\"\n[roadmap]: roadmap \"Roadmap\"\n[//end]: # \"Autogenerated link references\"\n\n",
"path": "/Users/swanson/dev/foam/docs/daily-notes.md",
"links": []
},
"eleventy-and-netlify": {
"id": "eleventy-and-netlify",
"title": "Eleventy and Netlify",
"source": "# Eleventy and Netlify\n\nYou can use [foam-eleventy-template](https://github.com/juanfrank77/foam-eleventy-template) to generate a static site with [Eleventy](https://www.11ty.dev/), and host it online on [Netlify](https://www.netlify.com/). \n\nWith this template you can\n- Have control over what to publish and what to keep private \n- Customize the styling of the site to your own liking\n\n## Publishing your foam\n\nWhen you're ready to publish, import the GitHub repository you created with **foam-eleventy-template** into your Netlify account. (Create one if you don't have it already.)\n\nOnce that's done, all you have to do is make changes to your workspace in VS COde and push them to the main branch on GitHub. Netlify will recognize the changes, deploy them automatically and give you a link where your Foam is published.\n\n\nThat's it!\n\nYou can now see it online and use that link to share it with your friends, so that they can see it too.\n\n",
"path": "/Users/swanson/dev/foam/docs/eleventy-and-netlify.md",
"links": []
},
"foam-linter": {
"id": "foam-linter",
"title": "Foam Linter (stub)",
"source": "# Foam Linter (stub)\n\n**[[todo]] This [[roadmap]] item needs more specification work.** \n\nIf you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).\n\n\n[//begin]: # \"Autogenerated link references for markdown compatibility\"\n[todo]: todo \"Todo\"\n[roadmap]: roadmap \"Roadmap\"\n[//end]: # \"Autogenerated link references\"",
"path": "/Users/swanson/dev/foam/docs/foam-linter.md",
"links": [
{
"to": "todo",
"text": "todo",
"position": {
"start": {
"line": 3,
"column": 3,
"offset": 24
},
"end": {
"line": 3,
"column": 11,
"offset": 32
},
"indent": []
}
},
{
"to": "roadmap",
"text": "roadmap",
"position": {
"start": {
"line": 3,
"column": 17,
"offset": 38
},
"end": {
"line": 3,
"column": 28,
"offset": 49
},
"indent": []
}
}
]
},
"todo": {
"id": "todo",
"title": "Todo",
"source": "# Todo\n\nFeatures belong on the [[roadmap]].\n\n- [ ] Write out Roadmap\n - [ ] Isolate tasks for MLH fellows\n- [ ] Create better structure for Recipes\n- [ ] Connect to folks at GitHub\n- [ ] Learn more about VS Code Extension APIs\n - [ ] Workspace fs/events\n - [ ] Reloading changes from outside vscode\n - [ ] Expanding, editable snippets\n\nFor more things to do, check backlinks for Pages that annotate [[todo]].\n\n[//begin]: # \"Autogenerated link references for markdown compatibility\"\n[roadmap]: roadmap \"Roadmap\"\n[todo]: todo \"Todo\"\n[//end]: # \"Autogenerated link references\"\n",
"path": "/Users/swanson/dev/foam/docs/todo.md",
"links": [
{
"to": "roadmap",
"text": "roadmap",
"position": {
"start": {
"line": 3,
"column": 24,
"offset": 31
},
"end": {
"line": 3,
"column": 35,
"offset": 42
},
"indent": []
}
},
{
"to": "todo",
"text": "todo",
"position": {
"start": {
"line": 14,
"column": 64,
"offset": 403
},
"end": {
"line": 14,
"column": 72,
"offset": 411
},
"indent": []
}
}
]
},
"roadmap": {
"id": "roadmap",
"title": "Roadmap",
"source": "# Roadmap\n\nSome of these items can be achieved by combining existing tools, but others may require us to build bespoke software solutions. See [[build-vs-assemble]] to understand trade-offs between these approaches. If a feature can be implemented by contributing to [[recipes]], it should.\n\n## In progress\n\nItems that are already being worked on. Roadmap items in this stage should have an owner.\n\n- [@jevakallio](https://github.com/jevakallio): [[cli]]\n\n## High priority\n\nItems we plan on working next. Items in this stage don't need to have an owner, but before we start working on them should have enough specification that they can be picked up and worked on without having to seek consensus.\n\nIf you want to pick up work in this category, you should have a plan on how long the implementation will approximately take so we don't block progress by sitting on high priority issues.\n\n- [[workspace-janitor]]\n \n## Backlog\n\nEverything else, categorised into themes. Just because something is on this list doesn't mean it'll get done. If you're interested in working on items in this category, check the [[contribution-guide]] for how to get started.\n\nIf a roadmap item is a stub, **consider** opening a [GitHub issue](https://github.com/foambubble/foam/issues) to start a conversation to avoid situations where the implementation does not fit long term vision and roadmap. _Note that this is optional. The only centralised governance in Foam is to decide what ends up in the official [template](https://github.com/foambubble/foam-template), [documentation](https://github.com/foambubble/foam) and [extension](https://github.com/foambubble/foam/tree/master/packages/foam-vscode). You are free to build whatever you want for yourself, and we'd love if you shared it with us, but you are by no means obligated to do so!_\n\n**When creating GitHub issues to discuss roadmap items, link them here.**\n\n### Known issues\n\n- [[improve-default-workspace-settings]]\n- Improve [[git-integration]]\n- Fix [[wiki-links]] compatibility issues\n- Simplify [[foam-file-format]]\n\n### Core features\n\n- [[renaming-files]]\n- [[unlinked-references]]\n- [[daily-notes]]\n- [[block-references]]\n- [[improved-backlinking]]\n - UX: [[make-backlinks-more-prominent]]\n- [[materialized-backlinks]]\n- [[automatic-git-syncing]]\n- [[git-flows-for-teams]]\n- [[user-settings]]\n- [[link-reference-definitions]]\n\n### Publishing\n\n- [[officially-support-alternative-templates]]\n- [[improved-static-site-generation]]\n- [[mdx-by-default]]\n- [[search-in-published-workspace]]\n- [[graph-in-published-workspace]]\n - Discussion: [foam#58](https://github.com/foambubble/foam/issues/58)\n- [[linking-between-published-workspaces]]\n - Discussion: [foam#59](https://github.com/foambubble/foam/issues/59)\n- [[publishing-permissions]]\n\n### Platforms\n\n- [[cli]]\n- [[mobile-apps]]\n- [[packaged-desktop-app]]\n- [[web-editor]]\n\n### Migration\n\n- [[migrating-from-roam]]\n - Discussion: [foam#55](https://github.com/foambubble/foam/issues/55)\n- [[migrating-from-obsidian]]\n - Discussion: [foam#46](https://github.com/foambubble/foam/issues/46)\n- _Migration from other tools..._\n\n### integration\n- _Integrations to third party tools_...\n \n### Wild ideas\n\n- [[foam-linter]]\n- [[refactoring-via-language-server-protocol]]\n\n[//begin]: # \"Autogenerated link references for markdown compatibility\"\n[build-vs-assemble]: build-vs-assemble \"Build vs Assemble\"\n[recipes]: recipes \"Recipes\"\n[cli]: cli \"Command Line Interface\"\n[workspace-janitor]: workspace-janitor \"Workspace Janitor\"\n[contribution-guide]: contribution-guide \"Contribution Guide\"\n[improve-default-workspace-settings]: improve-default-workspace-settings \"Improve Default Workspace Settings (stub)\"\n[git-integration]: git-integration \"Git integration\"\n[wiki-links]: wiki-links \"Wiki Links\"\n[foam-file-format]: foam-file-format \"Foam File Format\"\n[renaming-files]: renaming-files \"Renaming files (stub)\"\n[unlinked-references]: unlinked-references \"Unlinked references (stub)\"\n[daily-notes]: daily-notes \"Daily notes\"\n[block-references]: block-references \"Block References (stub)\"\n[improved-backlinking]: improved-backlinking \"Improved Backlinking (stub)\"\n[materialized-backlinks]: materialized-backlinks \"Materialized Backlinks (stub)\"\n[automatic-git-syncing]: automatic-git-syncing \"Automatic Git Syncing (stub)\"\n[git-flows-for-teams]: git-flows-for-teams \"Git Flows for Teams (stub)\"\n[officially-support-alternative-templates]: officially-support-alternative-templates \"Officially Support Alternative Templates (stub)\"\n[improved-static-site-generation]: improved-static-site-generation \"Improved Static Site Generation (stub)\"\n[mdx-by-default]: mdx-by-default \"MDX by Default(stub)\"\n[search-in-published-workspace]: search-in-published-workspace \"Search in Published Workspace (stub)\"\n[graph-in-published-workspace]: graph-in-published-workspace \"Graph in Published Workspace (stub)\"\n[linking-between-published-workspaces]: linking-between-published-workspaces \"Linking between Published Workspaces (stub)\"\n[publishing-permissions]: publishing-permissions \"Publishing Permissions(stub)\"\n[mobile-apps]: mobile-apps \"Mobile Apps\"\n[packaged-desktop-app]: packaged-desktop-app \"Packaged Desktop App (stub)\"\n[web-editor]: web-editor \"Web Editor (stub)\"\n[migrating-from-roam]: migrating-from-roam \"Migrating from Roam (stub)\"\n[migrating-from-obsidian]: migrating-from-obsidian \"Migrating from Obsidian (stub)\"\n[foam-linter]: foam-linter \"Foam Linter (stub)\"\n[refactoring-via-language-server-protocol]: refactoring-via-language-server-protocol \"Refactoring via Language Server Protocol (stub)\"\n[make-backlinks-more-prominent]: make-backlinks-more-prominent \"Make Backlinks More Prominent\"\n[//end]: # \"Autogenerated link references\"",
"path": "/Users/swanson/dev/foam/docs/roadmap.md",
"links": [
{
"to": "build-vs-assemble",
"text": "build-vs-assemble",
"position": {
"start": {
"line": 3,
"column": 133,
"offset": 143
},
"end": {
"line": 3,
"column": 154,
"offset": 164
},
"indent": []
}
},
{
"to": "recipes",
"text": "recipes",
"position": {
"start": {
"line": 3,
"column": 257,
"offset": 267
},
"end": {
"line": 3,
"column": 268,
"offset": 278
},
"indent": []
}
},
{
"to": "cli",
"text": "cli",
"position": {
"start": {
"line": 9,
"column": 49,
"offset": 447
},
"end": {
"line": 9,
"column": 56,
"offset": 454
},
"indent": []
}
},
{
"to": "workspace-janitor",
"text": "workspace-janitor",
"position": {
"start": {
"line": 17,
"column": 3,
"offset": 889
},
"end": {
"line": 17,
"column": 24,
"offset": 910
},
"indent": []
}
},
{
"to": "contribution-guide",
"text": "contribution-guide",
"position": {
"start": {
"line": 21,
"column": 180,
"offset": 1105
},
"end": {
"line": 21,
"column": 202,
"offset": 1127
},
"indent": []
}
},
{
"to": "improve-default-workspace-settings",
"text": "improve-default-workspace-settings",
"position": {
"start": {
"line": 29,
"column": 3,
"offset": 1916
},
"end": {
"line": 29,
"column": 41,
"offset": 1954
},
"indent": []
}
},
{
"to": "git-integration",
"text": "git-integration",
"position": {
"start": {
"line": 30,
"column": 11,
"offset": 1965
},
"end": {
"line": 30,
"column": 30,
"offset": 1984
},
"indent": []
}
},
{
"to": "wiki-links",
"text": "wiki-links",
"position": {
"start": {
"line": 31,
"column": 7,
"offset": 1991
},
"end": {
"line": 31,
"column": 21,
"offset": 2005
},
"indent": []
}
},
{
"to": "foam-file-format",
"text": "foam-file-format",
"position": {
"start": {
"line": 32,
"column": 12,
"offset": 2038
},
"end": {
"line": 32,
"column": 32,
"offset": 2058
},
"indent": []
}
},
{
"to": "renaming-files",
"text": "renaming-files",
"position": {
"start": {
"line": 36,
"column": 3,
"offset": 2081
},
"end": {
"line": 36,
"column": 21,
"offset": 2099
},
"indent": []
}
},
{
"to": "unlinked-references",
"text": "unlinked-references",
"position": {
"start": {
"line": 37,
"column": 3,
"offset": 2102
},
"end": {
"line": 37,
"column": 26,
"offset": 2125
},
"indent": []
}
},
{
"to": "daily-notes",
"text": "daily-notes",
"position": {
"start": {
"line": 38,
"column": 3,
"offset": 2128
},
"end": {
"line": 38,
"column": 18,
"offset": 2143
},
"indent": []
}
},
{
"to": "block-references",
"text": "block-references",
"position": {
"start": {
"line": 39,
"column": 3,
"offset": 2146
},
"end": {
"line": 39,
"column": 23,
"offset": 2166
},
"indent": []
}
},
{
"to": "improved-backlinking",
"text": "improved-backlinking",
"position": {
"start": {
"line": 40,
"column": 3,
"offset": 2169
},
"end": {
"line": 40,
"column": 27,
"offset": 2193
},
"indent": []
}
},
{
"to": "make-backlinks-more-prominent",
"text": "make-backlinks-more-prominent",
"position": {
"start": {
"line": 41,
"column": 9,
"offset": 2202
},
"end": {
"line": 41,
"column": 42,
"offset": 2235
},
"indent": []
}
},
{
"to": "materialized-backlinks",
"text": "materialized-backlinks",
"position": {
"start": {
"line": 42,
"column": 3,
"offset": 2238
},
"end": {
"line": 42,
"column": 29,
"offset": 2264
},
"indent": []
}
},
{
"to": "automatic-git-syncing",
"text": "automatic-git-syncing",
"position": {
"start": {
"line": 43,
"column": 3,
"offset": 2267
},
"end": {
"line": 43,
"column": 28,
"offset": 2292
},
"indent": []
}
},
{
"to": "git-flows-for-teams",
"text": "git-flows-for-teams",
"position": {
"start": {
"line": 44,
"column": 3,
"offset": 2295
},
"end": {
"line": 44,
"column": 26,
"offset": 2318
},
"indent": []
}
},
{
"to": "user-settings",
"text": "user-settings",
"position": {
"start": {
"line": 45,
"column": 3,
"offset": 2321
},
"end": {
"line": 45,
"column": 20,
"offset": 2338
},
"indent": []
}
},
{
"to": "link-reference-definitions",
"text": "link-reference-definitions",
"position": {
"start": {
"line": 46,
"column": 3,
"offset": 2341
},
"end": {
"line": 46,
"column": 33,
"offset": 2371
},
"indent": []
}
},
{
"to": "officially-support-alternative-templates",
"text": "officially-support-alternative-templates",
"position": {
"start": {
"line": 50,
"column": 3,
"offset": 2391
},
"end": {
"line": 50,
"column": 47,
"offset": 2435
},
"indent": []
}
},
{
"to": "improved-static-site-generation",
"text": "improved-static-site-generation",
"position": {
"start": {
"line": 51,
"column": 3,
"offset": 2438
},
"end": {
"line": 51,
"column": 38,
"offset": 2473
},
"indent": []
}
},
{
"to": "mdx-by-default",
"text": "mdx-by-default",
"position": {
"start": {
"line": 52,
"column": 3,
"offset": 2476
},
"end": {
"line": 52,
"column": 21,
"offset": 2494
},
"indent": []
}
},
{
"to": "search-in-published-workspace",
"text": "search-in-published-workspace",
"position": {
"start": {
"line": 53,
"column": 3,
"offset": 2497
},
"end": {
"line": 53,
"column": 36,
"offset": 2530
},
"indent": []
}
},
{
"to": "graph-in-published-workspace",
"text": "graph-in-published-workspace",
"position": {
"start": {
"line": 54,
"column": 3,
"offset": 2533
},
"end": {
"line": 54,
"column": 35,
"offset": 2565
},
"indent": []
}
},
{
"to": "linking-between-published-workspaces",
"text": "linking-between-published-workspaces",
"position": {
"start": {
"line": 56,
"column": 3,
"offset": 2640
},
"end": {
"line": 56,
"column": 43,
"offset": 2680
},
"indent": []
}
},
{
"to": "publishing-permissions",
"text": "publishing-permissions",
"position": {
"start": {
"line": 58,
"column": 3,
"offset": 2755
},
"end": {
"line": 58,
"column": 29,
"offset": 2781
},
"indent": []
}
},
{
"to": "cli",
"text": "cli",
"position": {
"start": {
"line": 62,
"column": 3,
"offset": 2800
},
"end": {
"line": 62,
"column": 10,
"offset": 2807
},
"indent": []
}
},
{
"to": "mobile-apps",
"text": "mobile-apps",
"position": {
"start": {
"line": 63,
"column": 3,
"offset": 2810
},
"end": {
"line": 63,
"column": 18,
"offset": 2825
},
"indent": []
}
},
{
"to": "packaged-desktop-app",
"text": "packaged-desktop-app",
"position": {
"start": {
"line": 64,
"column": 3,
"offset": 2828
},
"end": {
"line": 64,
"column": 27,
"offset": 2852
},
"indent": []
}
},
{
"to": "web-editor",
"text": "web-editor",
"position": {
"start": {
"line": 65,
"column": 3,
"offset": 2855
},
"end": {
"line": 65,
"column": 17,
"offset": 2869
},
"indent": []
}
},
{
"to": "migrating-from-roam",
"text": "migrating-from-roam",
"position": {
"start": {
"line": 69,
"column": 3,
"offset": 2888
},
"end": {
"line": 69,
"column": 26,
"offset": 2911
},
"indent": []
}
},
{
"to": "migrating-from-obsidian",
"text": "migrating-from-obsidian",
"position": {
"start": {
"line": 71,
"column": 3,
"offset": 2986
},
"end": {
"line": 71,
"column": 30,
"offset": 3013
},
"indent": []
}
},
{
"to": "foam-linter",
"text": "foam-linter",
"position": {
"start": {
"line": 80,
"column": 3,
"offset": 3199
},
"end": {
"line": 80,
"column": 18,
"offset": 3214
},
"indent": []
}
},
{
"to": "refactoring-via-language-server-protocol",
"text": "refactoring-via-language-server-protocol",
"position": {
"start": {
"line": 81,
"column": 3,
"offset": 3217
},
"end": {
"line": 81,
"column": 47,
"offset": 3261
},
"indent": []
}
}
]
},
"link-reference-definitions": {
"id": "link-reference-definitions",
"title": "Link Reference Definitions",
"source": "# Link Reference Definitions\n\n## Introduction\n\nWhen you use `[[wiki-links]]`, the [foam-vscode](https://github.com/foambubble/foam/tree/master/packages/foam-vscode) extension will automatically generate [Markdown Link Reference Definitions](https://spec.commonmark.org/0.29/#link-reference-definitions) at the bottom of the file. This is done to make the content of the file compatible with various Markdown tools (e.g. parsers, static site generators, VS code plugins etc), which don't support `[[wiki-links]]`.\n\n## Example\n\nThe following example:\n ```md\n - [[wiki-links]]\n - [[github-pages]]\n ```\n...generates the following link reference definitions to the bottom of the file:\n ```md\n [wiki-links]: wiki-links \"Wiki Links\"\n [github-pages]: github-pages \"Github Pages\"\n ```\nYou can open the [raw markdown](https://raw.githubusercontent.com/foambubble/foam/master/foam-file-format.md) to see them at the bottom of this file\n\n## Specification\n\nThe three components of a link reference definition are `[link-label]: link-target \"Link Title\"`\n\n- **link label:** The link text to match in the surrounding markdown document. This matches the inner bracket of the double-bracketed `[[wiki-link]]` notation\n- **link destination** The target of the matched link\n - Right now we generate link destinations without file extension. This is a choice, see [discussion here](https://foambubble.github.io/foam/wiki-links#why-dont-wiki-links-work-on-github).\n- **\"Link Title\"** Optional title for link (The Foam template has a snippet of JavaScript to replace this on the website at runtime)\n\nSee [[link-reference-definition-improvements]] for further discussion on current problems and potential solutions.\n\n\n[//begin]: # \"Autogenerated link references for markdown compatibility\"\n[wiki-links]: wiki-links \"Wiki Links\"\n[roadmap]: roadmap \"Roadmap\"\n[link-reference-definition-improvements]: link-reference-definition-improvements \"Link Reference Definition Improvements\"\n[//end]: # \"Autogenerated link references\"",
"path": "/Users/swanson/dev/foam/docs/link-reference-definitions.md",
"links": [
{
"to": "link-reference-definition-improvements",
"text": "link-reference-definition-improvements",
"position": {
"start": {
"line": 30,
"column": 5,
"offset": 1591
},
"end": {
"line": 30,
"column": 47,
"offset": 1633
},
"indent": []
}
}
]
},
"link-reference-definition-improvements": {
"id": "link-reference-definition-improvements",
"title": "Link Reference Definition Improvements",
"source": "# Link Reference Definition Improvements\n\n## Current Problems\n\n### File-by-file Insertion\n\nFor 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).\n\n### Wikilinks don't work on GitHub\n\n> **TL;DR;** [workaround](#workaround) in the end of the chapter.\n\nIf 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.\n\nAt 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.\n\nSo, why don't they work on GitHub?\n\nThe three components of [[link-reference-definitions]] are link label, link destination and Link Title.\n\nThe issue is the middle **link destination** component. It's configured to point to the file name **without file extension**, i.e. \"file-name\" instead of \"file-name.md\". This is to make the GitHub Pages rendering work, because if we generated the links to `file-name.md`, the links would point to the raw markdown files instead of their generated HTML versions.\n\n| Environment | `file-name` | `file-name.md` |\n| ---------------- | ----------- | -------------- |\n| **VS Code** | Works | Works |\n| **GitHub pages** | Works | Breaks |\n| **GitHub UI** | Breaks | Works |\n\nSo as you can see, we've prioritised GitHub Pages over GitHub Web UI for the time being.\n\nIdeally, we'd like a solution that works with both, but it's not defined yet (see [[link-reference-definitions]] for more details)\n\n#### Workaround\n\nFor the time being, you can use relative `[markdown links](markdown-link.md)` syntax.\n\n**Pros:**\n\n- This will work on all platforms.\n\n**Cons:**\n\n- It will break the Markdown Notes [[backlinking]] support\n- Less convenient to write\n\n### Finding certain words clutter the VS Code search results\n\nSince link reference definitions have `[//begin]` and `[//end]` guards with explanatory text that use certain words, these words (like \"generate\") appear in VS Code search results if you happen to search matching strings from the workspace.\n\n## Improvement Proposal\n\nProblem space in essence:\n\n- During edit-time (when modifying the markdown files in an editor)\n - link reference definitions are needed if user uses editor extensions that don't understand wikilinks\n - link reference definitions may be annoying since they \n - add content to files that the user hasn't typed in by themselves\n - get out of date if user uses a tool that doesn't autogenerate them\n - may clutter the search results\n- During build-time (when converting markdown to html for publishing purposes)\n - link reference definitions are needed, if the files are published via such tools (or to such platforms) that don't understand wikilinks\n - link reference definitions might have to be in different formats depending on the publish target (e.g. Github pages vs Github UI)\n\nThe potential solution:\n\n- For edit-time\n - Make edit-time link reference definition generation optional via user settings. They should be on by default, and generating valid markdown links with a relative path to a `.md` file.\n - Make format of the link reference definition configurable (whether to include '.md' or not)\n - Out of recommended extensions, currently only \"markdown links\" doesn't support them (?). However even its [code](https://github.com/tchayen/markdown-links/blob/master/src/parsing.ts#L25) seems to include wikilink parser, so it might just be a bug?\n- For build-time\n - To satisfy mutually incompatible constraints between GitHub UI, VSCode UI, and GitHub Pages, we should add a pre-processing/build step for pushing to GitHub Pages. \n - This would be a GitHub action (or a local script, ran via foam-cli) that outputs publish-friendly markdown format for static site generators and other publishing tools\n - This build step should be pluggable, so that other transformations could be ran during it\n - Have publish targets defined in settings, that support both turning the link reference definitions on/off and defining their format (.md or not). Example draft (including also edit-time aspect):\n ```typescript\n // settings json\n // see enumerations below for explanations on values\n {\n \"foam\": {\n \"publish\": [\n {\n \"name\": \"Gitlab Mirror\", // name of the publish target\n \"linkTranspilation\": \"Off\",\n \"linkReferenceDefinitions\": \"withExtensions\"\n },\n {\n \"name\": \"GitHub Pages\",\n \"linkTranspilation\": \"Off\",\n \"linkReferenceDefinitions\": \"withoutExtensions\"\n },\n {\n \"name\": \"Blog\",\n \"linkTranspilation\": \"Off\",\n \"linkReferenceDefinitions\": \"Off\"\n },\n {\n \"name\": \"My Amazing PDF book\",\n \"linkTranspilation\": \"WikiLinksToMarkdown\"\n }\n ],\n \"edit\": {\n \"linkReferenceDefinitions\": \"Off\"\n }\n }\n }\n\n // Defines if and how links in markdown files are somehow converted (in-place) during build time\n // Note that this enumeration is not valid edit-time, since we (probably) don't want to change text like this while user is editing it\n enum LinkTranspilation {\n Off, // links are not transpiled\n WikiLinksToMarkdown, // links using wiki-format [[link]] are converted to normal md links: [link](./some/file.md)\n // if this is set, not link reference definitions are generated (not needed)\n }\n \n // Defines if and how link reference definition section is generated\n enum LinkReferenceDefinitions {\n Off, // link reference definitions are not generated\n WithExtensions, // link reference definitions contain .md (or similar) file extensions\n WithoutExtensions // link reference definitions do not contain file extenions\n }\n\n ```\n - With Foam repo, just use edit-time link reference definitions with '.md' extension - this makes the links work in the Github UI\n - 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.\n - This naturally requires first removing the existing link reference definitions during the build\n- Other\n - 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).\n\nNote that the proposal above supports both (build-time) inline transpilation of wikilinks as well as creation reference definitions. Depending on the direction of Foam, also only one of them could be selected. In that case the other could be implemented at later point of time.\n\nUI-wise, the publish targets could be picked in some similar fashion as the run/debug targets in vscode by implementing a separate panel, or maybe through command execution (CTRL+SHIFT+P) - not yet defined at this point.\n\n## Links\n\n- [tracking issue on GitHub](https://github.com/foambubble/foam/issues/16)\n\n[//begin]: # \"Autogenerated link references for markdown compatibility\"\n[wiki-links]: wiki-links \"Wiki Links\"\n[roadmap]: roadmap \"Roadmap\"\n[link-reference-definitions]: link-reference-definitions \"Link Reference Definitions\"\n[backlinking]: backlinking \"Backlinking\"\n[//end]: # \"Autogenerated link references\"\n",
"path": "/Users/swanson/dev/foam/docs/link-reference-definition-improvements.md",
"links": [
{
"to": "wiki-links",
"text": "wiki-links",
"position": {
"start": {
"line": 7,
"column": 40,
"offset": 130
},
"end": {