Documentation
¶
Overview ¶
Package importdocs copies a folder of markdown docs, or one web page, into a vault as notes, and keeps the copies in step on every re-run.
The doc is the source of truth; its note is a projection. Each note carries the doc as `paths:` (so reading the doc brings the note) and as `source:` plus `source_hash:` (so a re-run knows what changed). Copying rather than mounting keeps every write inside the vault's confinement — see docs/specs in the research repo, plan item 6.
Index ¶
Constants ¶
const ImportedDir = "imported"
ImportedDir is the vault folder imported notes live under.
Variables ¶
var ErrNoMarkdown = errors.New("no markdown files or readable PDF or Office documents")
ErrNoMarkdown reports a source folder with nothing to import.
var UserAgentVersion = "dev"
UserAgentVersion is the version in the User-Agent. The command sets it from the binary's version string. Empty means "dev".
Functions ¶
This section is empty.
Types ¶
type Action ¶
type Action string
Action is what an import did, or would do, with one doc or note.
const ( Added Action = "added" Updated Action = "updated" Unchanged Action = "unchanged" // Orphaned is a note whose doc is gone. It stays until --prune. Orphaned Action = "orphaned" Pruned Action = "pruned" // Conflict is a note edited by hand whose doc also changed. It is kept; // --force overwrites it. Conflict Action = "conflict" // Skipped is a doc or note the import will not touch: a symlink, a file // it did not write, or an id another doc already took. Skipped Action = "skipped" )
The actions an import reports.
type Entry ¶
type Entry struct {
Action Action `json:"action"`
// Note is the note's vault-relative path. A Skipped entry names what was
// skipped instead: a source path, or, for what git ignores, a count such
// as "32 path(s)" (one entry for the lot, with the first paths in Reason).
Note string `json:"note"`
// Source is the doc as `<repo>:<path>`, empty for a skipped note.
Source string `json:"source,omitempty"`
Reason string `json:"reason,omitempty"`
}
Entry is one line of the report.
type Fetcher ¶ added in v0.10.2
Fetcher retrieves one page. ImportURL takes one so a test can answer without the network; the command passes HTTPFetcher.
func HTTPFetcher ¶ added in v0.10.2
func HTTPFetcher() Fetcher
HTTPFetcher fetches a page with net/http. No cookies are stored. Redirects stop at five and must stay on http or https. A body over 5 MiB, a non-2xx status, or a media type that is not text is an error and nothing is written.
type Options ¶
type Options struct {
DryRun bool
Prune bool
Force bool
// Excludes is the vault's exclude list: a note it would hide from the
// index is not written.
Excludes []string
}
Options change what an import writes.
type Page ¶ added in v0.10.2
Page is one fetched page. Body is UTF-8. FinalURL is where redirects landed; the note's address is the URL the operator named, not this one.
type Result ¶
Result is the whole report.
func ImportFile ¶ added in v0.10.2
ImportFile imports one markdown, PDF or Office file, rel under src.Dir, with the repository and prefix of that folder. There is no orphan pass: this import has one doc, and the folder's other notes are not its to report or prune. A file that cannot become a note is an error here, not a skip — it is the one thing the operator asked for.
func ImportURL ¶ added in v0.10.2
func ImportURL(ctx context.Context, rawURL, vaultRoot string, opts Options, fetch Fetcher) (*Result, error)
ImportURL imports the page at rawURL as one note. fetch retrieves it; HTTPFetcher is what the command passes, and a test passes its own. The note is planned and written by the same syncer as a folder import, so hash re-sync, conflicts, excludes, and unowned files behave the same. Orphans are not considered: this import has one page, and notes from other pages are not its to remove.
type Source ¶
type Source struct {
Dir string
// Repo is the repository name `paths:` entries use.
Repo string
// Prefix is Dir relative to the repository root, "" at the root.
Prefix string
}
Source names the docs to import. The command layer resolves Repo and Prefix from the repository around Dir, as `paths:` does.
Source Files