From c9fba7b729d00f120a3e4bdc01eecb34d961a4dd Mon Sep 17 00:00:00 2001 From: wesley chun Date: Sat, 26 Aug 2023 01:32:05 -0700 Subject: [PATCH] fix: update README --- README.md | 69 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 46 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 220fdcc..da8a061 100644 --- a/README.md +++ b/README.md @@ -16,30 +16,60 @@ Then get your OAuth client ID credentials: * Create (or reuse) a developer project at * Enable Google Slides API at [API library page](https://console.developers.google.com/apis/library) * Go to [Credentials page](https://console.developers.google.com/apis/credentials) and click "+ Create credentials" at the top -* Select "OAuth client ID" authorization credentials +* Create "OAuth client ID" type of credentials. * Choose type "Computer Application" and give it some name. -* Download client credentials file. -* Copy it to `client_id.json` (name has to match) and save to `~/.md2googleslides`. +* Download client ID/secret file and shorten the name to: `client_id.json`. +* Move `client_id.json` (name has to be exact) to `~/.md2googleslides`. After installing, import your slides by running: +```sh +md2gslides slides.md +``` + +You'll get a slide deck named "slides.md". + +> NOTE: The first time you run the `md2gslides` command, you will be prompted for authorization. OAuth token credentials are stored in `~/.md2googleslides/credentials.json`. You may get a "scary-looking" screen that says, "Google hasn't verified this app." Click "Advanced" then "Go to _APP-NAME_ (unsafe)" if you trust yourself as the author of the app that's requesting to access your Slides files in Drive. + + +If you want to give the presentation a different name, use the `--title` option: + ```sh md2gslides slides.md --title "Talk Title" ``` This will generate new Google Slides in your account with title `Talk Title`. -NOTE: The first time the command is run you will be prompted for authorization. OAuth token -credentials are stored locally in a file named `~/.md2googleslides/credentials.json`. +Each time you run `md2gslides`, a new slide deck will be generated. If you want to append to or replace an existing slide deck, get the Drive file ID of that deck. The file ID is the 44-character string in a presentation's URL. For example, for this slide deck URL: `https://docs.google.com/presentation/d/1EAYk18WDjIG-zp_0vLm3CsfQh_i8eXc67Jo2O9C6Vuc/edit`, its file ID is `1EAYk18WDjIG-zp_0vLm3CsfQh_i8eXc67Jo2O9C6Vuc`. + +Let's say you made some additional slides in `slides2.md`. To generate those slides and append to your existing deck, run: + +```sh +md2gslides slides2.md --append FILE_ID +``` + +To regenerate and replace a deck you've created with file ID `FILE_ID`, run: + +```sh +md2gslides slides.md --erase --append FILE_ID +``` -Each time you will run the above comment, new slide deck will be generated. In order to work on exactly the same -deck, just get the ID of the already generated slides. For example, you can use following command: +Each time you run the `md2gslides` command, the newly-created or edited slide deck will open in a new browser tab. If you want to suppress that from happening because you already have it open in an existing tab, issue the `--no-browser` option. This command replaces an existing deck but doesn't open up a new browser tab: +```sh +md2gslides slides.md --no-browser --erase --append FILE_ID ``` -# To reuse deck available at: https://docs.google.com/presentation/d//edit# -md2gslides slides.md --title "Talk Title" --append --erase + +If you're an advanced user, you can use the shorter alternative 1-character options: + +```sh +md2gslides slides.md -nea FILE_ID -t "Talk Title" ``` + +Images (see syntax below) are expected to be online (have URLs), but if you have local files you wish you use the `--use-fileio` option. More info on this option down below in the [Local images](#local-images) section. + + ## Supported markdown rules md2gslides uses a subset of the [CommonMark](http://spec.commonmark.org/0.26/) and @@ -157,11 +187,7 @@ Even if you will use `--append` option for deck reuse, theme will be not changed #### Inline images -Images can be placed on slides using image tags. Multiple images -can be included. Mulitple images in a single paragraph are arranged in columns, -mutiple paragraphs arranged as rows. - -Note: Images are currently scaled and centered to fit the +Images can be placed on slides using image tags. Multiple images can be included. Mulitple images in a single paragraph are arranged in columns, multiple paragraphs arranged as rows. **NOTE:** Images are currently scaled and centered to fit the slide template. 
@@ -322,6 +348,7 @@ console.log('Hello world');
 ```{style="font-size: 36pt"}
+ ### Tables Tables are supported via @@ -343,22 +370,18 @@ Dogs | 75 million Birds | 16 million + ### Local images -Images referencing local paths temporarily uploaded and hosted to [file.io](https://file.io). File.io -is an emphemeral file serving service that generates short-lived random URLs to the upload file and deletes -content shortly after use. +Images referencing local paths temporarily uploaded and hosted to [file.io](https://file.io). File.io is an ephemeral file serving service that generates short-lived random URLs to the upload file and deletes content shortly after use. -Since local images are uploaded to a thrid party, explicit opt-in is required to use this feature. -Include the `--use-fileio` option to opt-in to uploading images. This applies to file-based images as well +Since local images are uploaded to a third party, explicit opt-in is required to use this feature. Include the `--use-fileio` option to opt-in to uploading images. This applies to file-based images as well as automatically rasterized content like math expressions and SVGs. + ### Image rasterization -Slides can also include generated images, using `$$$` fenced blocks -for the data. Currently supported generated images are math expression (TeX -and MathML) as well as SVG. Rasterized images are treated like local images are require -opt-in to uploading images to a 3rd party service via the `--use-fileio` option. +Slides can also include generated images, using `$$$` fenced blocks for the data. Currently supported generated images are math expression (TeX and MathML) as well as SVG. Rasterized images are treated like local images are require opt-in to uploading images to a 3rd party service via the `--use-fileio` option. Using TeX: