#+TITLE: Getting Started #+ORGA_PUBLISH_KEYWORD: PUBLISHED DONE #+TODO: DRAFT | PUBLISHED #+TODO: TODO | DONE * PUBLISHED First Thing First :tutorial: CLOSED: [2020-11-10 Tue 16:00] :PROPERTIES: :SUMMARY: when you are reading this from =localhost=, you can skip this part now. :END: When you are reading this post from =http://localhost:8000=, you can skip this one now... But if you are reading this org file directly. Here you go. Instead of pointing you to [[https://www.gatsbyjs.com/docs/quick-start/][gatsby's awesome official quick start page]], I am going to list all the necessary commands here, so you don't have to jump away. ** Install Gatsby CLI #+BEGIN_SRC sh npm install -g gatsby-cli #+END_SRC ** Create new site with this starter #+BEGIN_SRC shell gatsby new gatsby-site https://github.com/orgapp/gatsby-starter-blorg #+END_SRC ** start up your site #+BEGIN_SRC shell cd gatsby-site yarn run develop #+END_SRC Now you have your site at http://localhost:8000. * PUBLISHED Config and Options :tutorial: CLOSED: [2020-11-10 Tue 15:55] :PROPERTIES: :SUMMARY: Options for the plugin, explained :ID: 049aea8c-19b4-40ba-940f-c52562d678cf :END: All configuration details are in your =gatsby-config.js= file. ** Site Metadata There's a set of website metadata to customize. You can customize it in =gatsby-config.js= file. #+BEGIN_SRC javascript siteMetadata: { title: `Blog Title Placeholder`, // website default title siteUrl: `https://orga.js.org`, // domain of your site author: `Name Placeholder`, // your name description: `Description placeholder`, // description of website, for SEO twitter: 'xiaoxinghu', // your twitter handle, you can set it to false or ignore it to get rid of the "Tweet this." button social: [ // your social badges, in your bio { name: 'twitter', url: 'https://twitter.com/xiaoxinghu' }, { name: 'website', url: 'https://huxiaoxing.com' }, { name: 'email', url: 'mailto:contact@huxiaoxing.com' }, ], }, #+END_SRC ** Post Metadata Each post has a set of metadata. Here is how it looks like. #+BEGIN_SRC typescript interface Metadata { title: string; date: Date; category: string; tags: string[]; export_file_name: string; } #+END_SRC These are the mandatory properties, you can expand it by simply adding PROPERTIES to the headline or by adding in-buffer settings. E.g. in your org file: #+BEGIN_SRC org ,* hello world :PROPERTIES: :IMAGE: ./images/dog.png :END: #+END_SRC You can find more details about Post Metadata in [[id:3c77e9cf-c23f-4a22-886c-c3b345d0b7d5][About Your Org Files]]. ** Options You can customize a set of options in your =gatsby-config.js= file. Here is the list. | Option | Type | Default Value | |---------------------+----------+----------------------------------------------------| | =contentPath= | String | 'content' | | =filter= | Function | =() => true= | | =pagination= | Number | 0 | | =columns= | Number | 2 | | =indexPath= | String | '/' | | =imageMaxWidth= | Number | 1380 | | =categoryIndexPath= | Function | =(category) => `/${category}`= | | =tagIndexPath= | Function | =tag => `/:${tag}:`= | | =slug= | Function | =({ export_file_name }) => `/${export_file_name}`= | | =postRedirect= | Function | =() => []= | | =preset= | String | 'orga-theme-ui-preset' | *** =contentPath= Where your org files located. You can use relative path like: =../notes=. *** =filter= A function that decides whether a =OrgContent= should be ignored. An example would be: #+BEGIN_SRC javascript { resolve: `gatsby-theme-blorg`, options: { filter: ({ keyword }) => keyword === 'PUBLISHED' || keyword === 'DONE', // other options... }, }, #+END_SRC **** Parameters - Post Metadata **** Returns - =true= (include) or =false= (exclude) *** =pagination= If you have lots of posts, you are going to want to enable pagination. The value is max posts per page on the index pages. You will get slugs like =domain.com/1=, =domain.com/2= for the index pages. For category links =domian.com/emacs/1=, =domian.com/emacs/2=... *** =columns= Number of columns for index pages. *** =indexPath= Path for index page. Set to =false= to disable. *** =categoryIndexPath= Category index page path. Parameter of the function is the category. Set to =false= to disable. Or return =false= conditionally to disable certain category. *** =slug= Generate slug for posts, with post metadata as input. *** =preset= [[https://theme-ui.com][theme-ui]] preset. * DONE About Your Org Files CLOSED: [2020-11-10 Tue 15:50] :PROPERTIES: :ID: 3c77e9cf-c23f-4a22-886c-c3b345d0b7d5 :END: You can organize your posts in two ways: per file or per headline. ** File Based Posts You just simply create org files, give it a =#+TITLE= and a =#+DATE=. Add a =#+SUMMARY= if you want to. You have a post. ** Headline Based Posts Tell Orga which headlines should be published via in buffer setting =#+ORGA_PUBLISH_KEYWORD=. It could be an array (separated by spaces). Then the headlines with matching keyword will be consider posts. Check out [[https://raw.githubusercontent.com/orgapp/gatsby-starter-blorg/master/content/getting-started.org][an example org file]] (yes, it's this page). ** Property Metadata Map Ordered by priority. #+CAPTION: essential property mapping | metadata field | headline based | file based | |------------------+------------------------------+----------------------| | title | headline content | =#+TITLE= | | | =EXPORT_TITLE= | | |------------------+------------------------------+----------------------| | date | =DATE= | =#+DATE= | | | =EXPORT_DATE= | =#+EXPORT_DATE= | | | =PUBLISH_DATE= | =#+PUBLISH_DATE= | | | "CLOSED" planning timestamp | | |------------------+------------------------------+----------------------| | category | =CATEGORY= | =#+CATEGORY= | | | file name | | |------------------+------------------------------+----------------------| | tags | tags of headline | N/A | |------------------+------------------------------+----------------------| | export_file_name | =EXPORT_FILE_NAME= | =#+EXPORT_FILE_NAME= | | | headline content (sanitised) | file name | |------------------+------------------------------+----------------------| | excerpt | =EXCERPT= | =EXCERPT= | | | =SUMMARY= | =SUMMARY= | | | =DESCRIPTION= | =DESCRIPTION= | All other properties will be available for graphql queries. ** =SELECT_TAGS= and =EXCLUDE_TAGS= [[https://orgmode.org/manual/Export-Settings.html][org-mode has these useful properties]] that can help you select or ignore sections when exporting your content into html. You can do the same with orgajs. There's actually another section after this one in the current org file, but you won't be able to see it because it's ignored with due to tag =noexport=. Again check out [[https://raw.githubusercontent.com/orgapp/gatsby-starter-blorg/master/content/getting-started.org][this org file]] for an real life example. | option | default value | details | |--------------+---------------+----------------------------------------------------------------------------| | SELECT_TAGS | [] | when set (none-empty array), only sections with matching tags are included | | EXCLUDE_TAGS | ['noexport'] | | I try to stick as close to org-mode syntax as possible. So array is always string separated by spaces. You can customize these settings on a per file basis, just like in org-mode. ** You are not suppose to see this section :noexport: This section is ignored when building the website.