Sandpoints-Obsidian/readme.org

#+title: Readme

* Introduction

This repository is a guide for installing and using Sandpoints in tandem with Obsidian.

Sandpoints is a free software

* Installation Instructions
Follow the [[https://gohugo.io/getting-started/quick-start/][Hugo Quick Start guide]].

After installing Hugo, open a terminal and do:

#+begin_src bash
hugo new site mysite
cd mysite
git init
git submodule add https://dev.sandpoints.org/Drawwell/SandpointsTheme themes/sandpoints
#+end_src

The above will start a new blank side; start a git repository; and install the Sandpoints theme as a submodule.


Next we need to tell the project configuration to use the sandpoints theme:

Open =hugo.toml= and add
#+begin_src toml
theme="sandpoints"
#+end_src

Then, we can go again and start a local server to run and view the site:
#+begin_src toml
hugo server
#+end_src
** Project config: Sandpoints version

At the moment Sandpoints works properly with Hugo version 0.113 --errors have to do with library references and endnote numbering for Print PDFs.

Download [[https://github.com/gohugoio/hugo/releases/tag/v0.113.0][Hugo version 0.113 (GitHub)]].
Place the Hugo executable (=hugo.exe=, or =hugo.bin=, etc.) on the root folder of your project, and rename to, for example, =hugo-113.exe=.

To then run a local server or compile the site do:

#+begin_src bash
hugo-113.exe server
#+end_src
or
#+begin_src bash
hugo-113.exe
#+end_src


* Setup Sandpoints project

** Site config file
*** Enable keywords
Add keyword taxonomy to =hugo.toml=
and enable relative urls
#+begin_src TOML
# Relative URLS
relativeurls = true

# Taxonomy: keyword = "keywords"
[taxonomies]
keyword = "keywords"
#+end_src
*** Setup metadata
#+begin_src TOML
[params]
# Project description
description = "Project description"
## sandpointsHome renders link to predefined home if page not in triad
sandpointsHome = "package/stc.md"
# Enable backlinks for content types
sandpointsMentionedIn = ["annex", "author", "section" ,"item", "thing", "person"]
# sandpointsGiteaUrl = "https://git.sandpoints.org/we/da-component.git" # used in layouts/partials/header.html to generate links in /Preview/ UI
sandpointsCatalogPrefix = "/library/"
sandpointsCatalogName = "custom-sandpoints-project-name"
#+end_src

** Enable URLS

Create =urls/_index.md=
Open the file and add
#+begin_src Markdown
---
title: "List of Urls"
---
#+end_src

Now the site =/urls/= shows a list of internal, outgoing, and bibliographic, links, as well as backlinks.
** Prepare print directory

Crate =print/_index.md=.
Open the file and add
#+begin_src Markdown
---
title: "List of Print Items"
---
#+end_src


* Create content

Create a new entry with
#+begin_src toml
hugo new entry/entry.md
#+end_src

This will be created according to [[#archetypes][archetypes]].
* Archetypes
:PROPERTIES:
:CUSTOM_ID: archetypes
:ID:       8f382044-aeeb-4022-ac35-f7fc88d2a880
:END:

Project archetypes directory at [[file:archetypes/][/archetypes/]].

Theme archetypes directory at [[file:themes/sandpoints/archetypes/][/themes/sandpoints/archetypes/]].
* Sandpoints-Obsidian workflow
** Setup Obsidian

Open the project's =content/= directory as a Vault using Obsidian

Go to settings and:
+ *DISABLE* Wiki links
+ Set New Link Format to *Absolute path in vault*
** Customize Sandpoints theme for Obsidian
By default Sandpoints recognizes internal links in the form of
#+begin_src Markdown
![Link label](type/filename)
#+end_src

or

#+begin_src Markdown
![](type/filename)
#+end_src

In which case the link label is populated dynamically.


Using Obsidian with standard Markdown links (instead of Wiki-type links), internal links would be of the type

#+begin_src Markdown
[Link label](type/filename.md)
#+end_src

Moreover, Obsidian allows spaces in the filenames of notes (e.g. =my note.md=), and replaces space characters with =%20= (as in =my%20note.md=).

***  Create override for render-link.html

Copy =render-link= from theme/layouts

[[file:themes/sandpoints/layouts/_default/_markup/render-link.html]]

to the corresponding directory inside layouts, at the root of the project:

[[file:layouts/_default/_markup/render-link.html]]

This overrides the theme's =render-link= behavior.
*** Edit custom render-link.html

1. Add clause to replace =%20= with =-= (dash).

* Other Sandpoints theme edits
** Edit keyword view (layouts/taxonomy/list)
By default, =/keywords= lists keywords together by creation date, sorted by creation date.
This is edited in [[file:layouts/taxonomy/list.html][/layouts/taxonomy/list.html]] to remove the mention of the creation date, and sort entries alphabetically.