Skip to content

Commit

Permalink
Merge pull request obsidianmd#6 from obsidianmd/master
Browse files Browse the repository at this point in the history
Update
  • Loading branch information
11-check-it-out authored Jan 29, 2021
2 parents dcdb18a + 1f5846c commit 3154d65
Show file tree
Hide file tree
Showing 146 changed files with 1,929 additions and 628 deletions.
48 changes: 47 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,49 @@
To contribute: Open a vault in the `/en/` folder (or your language of choice once translations are available).

Image attachments: Please use `.png` and compress the image using a compression tool like https://compresspng.com/ in order to keep the whole package small.
Image attachments: Please use `.png` and compress the image using a compression tool like https://compresspng.com/ in order to keep the whole package small.

## Typos and mistakes

For correcting typos and other small mistakes, you can directly submit a pull request.

Note that you don't have to clone your fork onto your hard disk to make the edits; you can do everything on GitHub's web UI. Simply open a file in your own forked repository and click on the pencil icon to start editing. After that, [submit a pull request](https://guides.github.com/activities/forking/).

## Missing or outdated content

We recommend opening an issue with us if you find missing or outdated content.

If you'd like to try your hand at contributing the article, we appreciate it too! Please follow the same instructions under "Typos and mistakes" to submit a pull request.

Please try to be consistent with the style of the existing documentation when adding new articles. Notably, when writing a title or a heading, do not capitalize the second or subsequent words, unless it is a proper name.

## Translating

### Translate existing languages

To contributing to an existing language, clone the entire forked repository onto your hard disk, and open that folder as a vault with Obsidian and proceed to translate. For example, if you're translating Italian, open the `/it/` folder.

### Add your language

If the language you're trying to contribute does not exist, simply copy the entire English docs (everything under `/en/`) and start translating.

### Make completed languages available in app

Once the language you're working on is complete, open an issue to let us know. That way we can include it in the Obsidian app, so that users who set their Obsidian language to that language can see the translated documentation instead of English documentation.

### Staying up-to-update

Once the documentation get translated into a language, the English documentation will still occasionally get updated to include new features and to be more comprehensive.

There's no simple way to stay up-to-update, but in general you can browse your language folder to check out when it's last updated, and compare that with the English documentation.

If it's only a few versions behind, you can look at those changes individually, translate them, and fit them into the documentation of your language.

If your language is months behind, we recommend opening the English documentation and the documentation of your language side by side in two vaults with Obsidian, and go through each article carefully.

### Adding yourself to credit

Thanks for contributing to Obsidian's documentation! To feature yourself on our [[Credits]] page, simply create a pull request to the `/en/Obsidian/Credits` file. You can update the `YOUR LANGUAGE/Obsidian/Credits` file as well.

## Handling image attachments

Please use `.png` extensions and compress the image using a compression tool like [Compress PNG](https://compresspng.com/) in order to keep the whole package small.
16 changes: 16 additions & 0 deletions Release notes/v0.10.7.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
Released on 2020/01/07.

## Shiny new things

- Tags can now be clicked on Obsidian Publish to show a list of other pages containing the same tag.
- You can now `Ctrl/Cmd` click tags in the tag pane to toggle them as a search filter, instead of replacing the search query.

## Improvements

- You can now unlink and pin backlink, outline, or local graph panes to have them stay on the file that was open, instead of navigating along with the current active pane.
- Daily notes will now only check for the daily note inside the selected folder.
- `tag:#mytag` will now always use case-insensitive mode, since tags are always insensitively matched. For case sensitive match, use a plain `#mytag` query instead.

## No longer broken

- Tags with underscore `_` will now auto-complete properly.
30 changes: 30 additions & 0 deletions Release notes/v0.10.8.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
Released on 2020/01/11.

## Shiny new things

- Obsidian Publish can now restrict site access with one or multiple passwords.
- You can now choose to store attachments in the same folder as the current note, or in a subfolder relative to the current note.
- Huge PDF improvements:
- PDF files will now render when embedded inside a note.
- PDF files are now rendered using a native PDF viewer, which can scroll, zoom, select and copy text.
- You can now link to a page of a PDF file by adding `#page=number` at the end. For example `[[My file.pdf#page=3]]`. This also works for embedded PDFs. Typing `#` while auto-completing a PDF file will automatically add `#page=` for you.

## Improvements

- Folders now shows the number of files and subfolders when you hover over them.
- The hover tooltips for the file explorer has been reprimanded for being too eager to show up on time. They will now only display once you stop your mouse over it.
- An unlinked pinned outline pane will now attempt to open the file if it's not already open.
- Audio recorder will now generate file names with timestamps similar to pasted images.
- Word count has been improved to handle numbers better.

## No longer broken

- Changing active panes with hotkeys will now properly focus on them.
- Tooltips no longer leave behind a lingering line sometimes.
- Tooltips now appear on the correct side for backlinks and file explorer.
- The editor text should now always stay clear using subpixel-antialiasing, instead of jumping to blurry grayscale from time to time.

## Developers

- The `file-open` event is now fired in a debounced frame instead of synchronously running while the `activeLeaf` is being set.
- The `layout-ready` event will now only fire once when the app finish loading the workspace, instead of also triggering when loading a different workspace.
2 changes: 1 addition & 1 deletion en/Advanced topics/Accepted file formats.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,4 @@ Obsidian recognizes the following file formats right now:
4. Video files: `mp4`, `webm`, `ogv`;
5. PDF files: `pdf`.

Everything except for PDFs can be [[Embed files|embedded]].
All these types of files can be [[Embed files|embedded]] in a note.
13 changes: 13 additions & 0 deletions en/Advanced topics/Customizing CSS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
If you are building or modifying your own css, you can open the developer tools by using `Ctrl+Shift+I` on Windows/Linux or `Cmd+Opt+I` on macOS to get information on the elements you want to customize.

Changes to themes and snippets will be detected automatically and reapplied. You do not need to restart the app.

### New to CSS

If you're new to CSS, our community has put together a quick guide to get comfortable with CSS:

> [Getting Comfortable with CSS](https://forum.obsidian.md/t/getting-comfortable-with-obsidian-css/133)
Klaas also put together a helpful index of common CSS snippets that you can feel free to mix and match:

> [Obsidian CSS Snippets (on GitHub)](https://github.com/Dmitriy-Shulha/obsidian-css-snippets/tree/master/Snippets)
2 changes: 0 additions & 2 deletions en/Advanced topics/How Obsidian stores data.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,6 @@ We believe [[Obsidian#How we're different|your data is always yours to own and c

There is, however, some data that is needed by the software that is not stored in markdown. Obsidian creates a directory called `.obsidian` in the root of any vault you create. This contains your configuration, including custom hotkeys and which plugins are enabled. Any directory starting with a `.` is invisible on most systems, so you will probably never see it unless you try. If you delete this directory, none of your data will be gone, but you will lose your custom settings. It will be recreated when you open that vault in Obsidian again. If you are using `git`, it's probably best to `ignore` the `.obsidian` directory, because the cache changes quickly enough that commits can get ugly, but we haven't observed any other issues with including it.

If you use custom css, Obsidian creates a file named `obsidian.css` in the root of your vault. For more on this, see [[Custom CSS]].

Obsidian also stores some information in the system directory. This is different per Operating System; on Mac it's `/Users/yourusername/Library/Application Support/obsidian`, on Windows `%APPDATA%\Obsidian\`, and `$XDG_CONFIG_HOME/Obsidian/` or `~/.config/Obsidian/` on Linux. As a result, we recommend against creating a vault in this directory.

Aside from that, though, you can create a Vault anywhere your operating system will allow. Obsidian files sync fine with Dropbox, iCloud, OneDrive, git, and every other syncing service we've tried thus far.
1 change: 1 addition & 0 deletions en/Advanced topics/Using obsidian URI.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ obsidian://action?param1=value&param2=value
==Important==

Ensure that your values are properly URI encoded. For example, forward slash characters `/` must be encoded as `%2F` and space characters must be encoded as `%20`.

This is especially important because an improperly encoded "reserved" character may break the interpretation of the URI. [See here for details](https://en.wikipedia.org/wiki/Percent-encoding)

### Available actions
Expand Down
37 changes: 37 additions & 0 deletions en/How to/Add custom styles.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
When you want to add custom styles to your vault, there are two main ways to do this:

## Vault styles

### Themes

Themes allow you to toggle the appearance of your vault with a dropdown menu once they have been added to your vault's theme directory.

This configuration can be found in `Settings` > `Appearance` > `Themes` section of your vault settings.

### Create a custom theme

If you are creating your own theme, you can do this by:

1. Creating your custom theme CSS file in the themes directory `YOUR_VAULT/.obsidian/themes/YOUR_CUSTOM_THEME.css`
2. Enabling it in the theme dropdown under `Settings` > `Appearance` > `Themes`

For more information on how to customize styles of the graph, you can find more information in [[Graph view]].

### Use 'obsidian.css'

> This is currently marked as a legacy setting.
This configuration can be found in `Settings` > `Appearance` > `Apply custom CSS` as a toggle in your vault settings.

## Obsidian Publish styles

At this time, [[Obsidian Publish]] is unable to automatically detect the vault's configured [[Add custom styles#Themes|theme]] and publish the respective styles.

A workaround for this limitation is to:

1. Go into `YOUR_VAULT/.obsidian/themes/CURRENT_THEME_FOLDER`;
2. Copy the primary CSS file `CURRENT_THEME.css` in the folder;
3. Paste it in the root directory of your vault (`YOUR_VAULT`);
4. Rename the CSS file as `publish.css`;
5. In the publish plugin, upload the `publish.css` file;
6. If your CSS doesn't take effect in a few minutes, try refreshing the browser cache as the stale CSS might have been cached.
15 changes: 15 additions & 0 deletions en/How to/Capture information.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
### Copy and paste

When you see something useful online, you can simply select the text, copy, and pate in Obsidian. Obsidian will try to convert it into proper Markdown so that it fits right in.

If you only wish to copy the text without the formatting, please use `Ctrl-Shift-V` on Windows and Linux and `Cmd-Shift-V` on macOS to do so.

### Use a clipper extension

Because Obsidian accepts any Markdown file, you can clip entire web pages by clipping to Markdown files and downloading them into your vault.

death_au's "MarkDownload" browser extension works well for this purpose. You can get it for:

- [Google Chrome](https://chrome.google.com/webstore/detail/markdownload-markdown-web/pcmpcfapbekmbjjkdalcgopdkipoggdi)
- [Firefox](https://addons.mozilla.org/en-GB/firefox/addon/markdownload/)
- [Microsoft Edge](https://microsoftedge.microsoft.com/addons/detail/markdownload-markdown-w/hajanaajapkhaabfcofdjgjnlgkdkknm)
2 changes: 1 addition & 1 deletion en/How to/Settings.md → en/How to/Change settings.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
The settings can be found by clicking the gear in the bottom left corner, or by hitting `Ctrl/Cmd-,`. Most of them are fairly self-explanatory, but here are some notes that might be helpful.

- Most of the settings are toggle switches. If there are more details to a setting, it may have a gear next to the switch for additional settings. For example, the gear next to Spell Check reveals the custom dictionary, so you can remove words you may have accidentally added.
- Enabling plugins will cause their settings to appear in the list of tabs. For example, when you enable Custom CSS, a community themes tab will appear that allows for choosing a custom CSS theme.
- Enabling plugins will cause their settings to appear in the list of tabs. For example, if you have the Daily Note plugin enabled, a setting tab will appear that allows you to further configure it.
20 changes: 20 additions & 0 deletions en/How to/Drag and drop to speed things up.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
In Obsidian, drag and drop is used in plenty situations to speed things up.

Other than [[Working with multiple notes#5 Panes can be rearranged by dragging|dragging panes]], you can also drag files to perform many tasks.

You can drag files from:

- [[File explorer]]
- [[Starred notes]]
- [[Search]] results
- [[Backlinks]]
- Links in a note
- Files in your system explorer

After dragging them, you can drop them into places for various purposes:

- Onto a note to insert link at cursor position
- Onto pane header to open file in that pane
- [[File explorer]] to move the file into a folder
- [[Starred notes]] to star the file
- An external text editor program to insert Obsidian URI to the file
45 changes: 44 additions & 1 deletion en/How to/Embed files.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,57 @@
### Embed attachments

You can embed attachment files like images or audio in your notes. Use the `![[filename.png]]` syntax like so:

![[Engelbart.jpg]]

![[Excerpt from Mother of All Demos (1968).ogg]]

You can embed a PDF file in your notes with the same syntax. Additionally, you can write `![[My File.pdf#page=number]]` to open to that specific page of the PDF directly.

### Embed notes

You can embed a note also, with the same syntax:

![[Accepted file formats]]

If you drag and drop an image it will be copied to your default attachment directory. The image is there as a normal file and can still be accessed through the file system. You can define the directory that images will be saved to by right clicking on it in the File explorer, and finding that option on the context menu.
### iframe

"iframe" is a way to embed a web page in another. It's useful because Markdown can accept HTML, which is a simple language to construct the web pages we see every day.

For example:

```html
<iframe src="https://www.youtube.com/embed/NnTvZWp5Q7o"></iframe>
```

Produces:

<iframe src="https://www.youtube.com/embed/NnTvZWp5Q7o"></iframe>

The basic syntax is:

```html
<iframe src="INSERT YOUR URL HERE"></iframe>
```

Some websites have quirks that don't allow you to embed them. For example, you can't embed a YouTube video by using its normal URL, but you can use its embed URL which is `https://www.youtube.com/embed/VIDEO_ID`.

If you want to embed a website, try searching for "{website} embed iframe".

For example, you can embed Twitter tweets like so as suggested by search results:

```html
<iframe
border=0
frameborder=0
height=250
width=550
src="https://twitframe.com/show?url=https%3A%2F%2Ftwitter.com%2Fjack%2Fstatus%2F20">
</iframe>
```

<iframe border=0 frameborder=0 height=250 width=550
src="https://twitframe.com/show?url=https%3A%2F%2Ftwitter.com%2Fjack%2Fstatus%2F20"></iframe>

---

Expand Down
42 changes: 41 additions & 1 deletion en/How to/Format your notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,10 @@ Example of this above image resized to 100 pixels wide:

### Links

#### External links

Markdown style links can be used to refer to either external objects, such as web pages, or an internal page or image.

```md
http://obsidian.md - automatic!
[Obsidian](http://obsidian.md)
Expand All @@ -131,7 +135,43 @@ http://obsidian.md - automatic!
http://obsidian.md - automatic!
[Obsidian](http://obsidian.md)

Markdown style links can be used to refer to either external objects, such as web pages, or an internal page or image. If there are spaces in the url, they can be escaped by either using `%20` as a space, such as [Export options](Pasted%20image), or by enclosing the target in `<>`, such as [Slides Demo](<Slides Demo>).
#### Obsidian URI links

[[Using obsidian URI|Obsidian URI]] links can be used to open notes in Obsidian either from another Obsidian vault or another program.

For example, you can link to a file in a vault like so (please note the [[Using obsidian URI#Encoding|required encoding]]):

```md
[Link to note](obsidian://open?path=D:%2Fpath%2Fto%2Ffile.md)
```

[Link to note](obsidian://open?path=D:%2Fpath%2Fto%2Ffile.md)

You can link to a note by its vault name and file name instead of path as well:

```md
[Link to note](obsidian://open?vault=MainVault&file=MyNote.md)
```

[Link to note](obsidian://open?vault=MainVault&file=MyNote.md)

#### Escaping

If there are spaces in the url, they can be escaped by either using `%20` as a space, such as:

```md
[Export options](Pasted%20image)
```

[Export options](Pasted%20image)

Or you can enclose the target in `<>`, such as:

```md
[Slides Demo](<Slides Demo>)
```

[Slides Demo](<Slides Demo>)

---

Expand Down
File renamed without changes.
49 changes: 49 additions & 0 deletions en/How to/Manage attachments.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
## Add an attachment

There are several ways to include attachments in your notes:

1. Copy and paste;
2. Drag and drop;
3. Download or copy file to vault folder.

After being added, these attachment files are just normal files and can still be accessed through your file system.

Please note that only [[Accepted file formats]] are handled.

### Copy and paste

Pasting a local file from your system explorer or your clipboard will put the file into your vault.

This is very handy when combined with screenshot tools.

### Drag and drop

If you drag and drop a file from your file explorer, it will be copied to your vault as well.

### Download or copy to vault folder

This can work well when paired with [[Capture information#Use a clipper extension|clipper extensions]].

You can also download images from your browser into your vault folder directly for later reference.

## Change default attachment location

By default, new attachments will be dropped in the root of your vault. You can fine tune this setting in Settings -> Files & Links -> "Default location for new attachments".

### Choose a folder

You can choose a fixed folder to always place your attachments in. To do this, choose "In the folder specified below", and choose a folder in your vault in the new field that appears.

Alternatively, you can right click on a folder in [[File explorer]] and choose "Set as attachment folder".

### Same folder as current file

Sometimes, you may want the attachment files to always be in the same folder as the note you're working on. In this case, choose "Same folder as current file".

### Under the current folder

You can also choose to save attachments to a folder underneath the folder that the current file is in.

To do this, choose the "Subfolder under current folder" option, and write the name of the subfolder in the field that appears. For example, if you write `assets`, and your note is in `VAULT/folder/path/`, the attachments will be added to `VAULT/folder/path/assets` when you're working on this note.

You don't need to create the subfolder beforehand; if it doesn't exist, Obsidian will create it for you.
Loading

0 comments on commit 3154d65

Please sign in to comment.