1"use strict";(self.webpackChunkelectronjs=self.webpackChunkelectronjs||[]).push([["28837"],{30102(e,t,o){o.r(t),o.d(t,{assets:()=>c,contentTitle:()=>l,default:()=>d,frontMatter:()=>i,metadata:()=>s,toc:()=>a});var s=o(286),n=o(74848),r=o(28453);let i={title:"Electron Documentation",date:new Date("2015-06-04T00:00:00.000Z"),authors:"jlord",slug:"electron-doumentation",tags:["website"]},l,c={authorsImageUrls:[void 0]},a=[{value:"The Technical Bits",id:"the-technical-bits",level:2},{value:"script/docs",id:"scriptdocs",level:3},{value:"Jekyll",id:"jekyll",level:3},{value:"Front matter",id:"front-matter",level:4},{value:"Config and Redirects",id:"config-and-redirects",level:4},{value:"Layouts",id:"layouts",level:4}];function h(e){let t={a:"a",code:"code",h2:"h2",h3:"h3",h4:"h4",hr:"hr",li:"li",p:"p",pre:"pre",ul:"ul",...(0,r.R)(),...e.components};return(0,n.jsxs)(n.Fragment,{children:[(0,n.jsxs)(t.p,{children:["This week we've given Electron's documentation a home on ",(0,n.jsx)(t.a,{href:"https://electronjs.org",children:"electronjs.org"}),". You can visit ",(0,n.jsx)(t.a,{href:"https://electronjs.org/docs/latest",children:"/docs/latest"})," for the latest set of docs. We'll keep versions of older docs, too, so you're able to visit ",(0,n.jsx)(t.a,{href:"https://electronjs.org/docs/v0.26.0",children:"/docs/vX.XX.X"})," for the docs that correlate to the version you're using."]}),"\n",(0,n.jsx)(t.hr,{}),"\n",(0,n.jsxs)(t.p,{children:["You can visit ",(0,n.jsx)(t.a,{href:"https://electronjs.org/docs",children:"/docs"})," to see what versions are available or ",(0,n.jsx)(t.a,{href:"https://electronjs.org/docs/all",children:"/docs/all"})," to see the latest version of docs all on one page (nice for ",(0,n.jsx)(t.code,{children:"cmd"})," + ",(0,n.jsx)(t.code,{children:"f"})," searches)."]}),"\n",(0,n.jsxs)(t.p,{children:["If you'd like to contribute to the docs content, you can do so in the ",(0,n.jsx)(t.a,{href:"https://github.com/electron/electron/tree/main/docs",children:"Electron repository"}),", where the docs are fetched from. We fetch them for each minor release and add them to the ",(0,n.jsx)(t.a,{href:"http://github.com/electron/electronjs.org",children:"Electron site repository"}),", which is made with ",(0,n.jsx)(t.a,{href:"http://jekyllrb.com",children:"Jekyll"}),"."]}),"\n",(0,n.jsxs)(t.p,{children:["If you're interested in learning more about how we pull the docs from one repository to another continue reading below. Otherwise, enjoy the ",(0,n.jsx)(t.a,{href:"https://electronjs.org/latest",children:"docs"}),"!"]}),"\n",(0,n.jsx)(t.h2,{id:"the-technical-bits",children:"The Technical Bits"}),"\n",(0,n.jsxs)(t.p,{children:["We're preserving the documentation within the Electron core repository as is. This means that ",(0,n.jsx)(t.a,{href:"http://github.com/electron/electron",children:"electron/electron"})," will always have the latest version of the docs. When new versions of Electron are released, we duplicate them over on the Electron website repository, ",(0,n.jsx)(t.a,{href:"http://github.com/electron/electronjs.org",children:"electron/electronjs.org"}),"."]}),"\n",(0,n.jsx)(t.h3,{id:"scriptdocs",children:"script/docs"}),"\n",(0,n.jsxs)(t.p,{children:["To fetch the docs we run a ",(0,n.jsx)(t.a,{href:"https://github.com/electron/electronjs.org/blob/0205b5ab26c96a95121bc564c5824f92108677e0/script/docs",children:"script"})," with a command line interface of ",(0,n.jsx)(t.code,{children:"script/docs vX.XX.X"})," with or without the ",(0,n.jsx)(t.code,{children:"--latest"})," option (depending on if the version you're importing is the latest version). Our ",(0,n.jsx)(t.a,{href:"https://github.com/electron/electronjs.org/blob/0205b5ab26c96a95121bc564c5824f92108677e0/lib/fetch-docs.js",children:"script for fetching docs"})," uses a few interesting Node modules:"]}),"\n",(0,n.jsxs)(t.ul,{children:["\n",(0,n.jsxs)(t.li,{children:[(0,n.jsx)(t.a,{href:"http://npmjs.com/nugget",children:(0,n.jsx)(t.code,{children:"nugget"})})," for ",(0,n.jsx)(t.a,{href:"https://github.com/electron/electronjs.org/blob/0205b5ab26c96a95121bc564c5824f92108677e0/lib/fetch-docs.js#L40-L43",children:"getting the release tarball"})," and saving it to a temporay directory."]}),"\n",(0,n.jsxs)(t.li,{children:[(0,n.jsx)(t.a,{href:"http://npmsjs.com/gunzip-maybe",children:(0,n.jsx)(t.code,{children:"gunzip-maybe"})})," to ",(0,n.jsx)(t.a,{href:"https://github.com/electron/electronjs.org/blob/0205b5ab26c96a95121bc564c5824f92108677e0/lib/fetch-docs.js#L95",children:"unzip the tarball"}),"."]}),"\n",(0,n.jsxs)(t.li,{children:[(0,n.jsx)(t.a,{href:"http://npmjs.com/tar-fs",children:(0,n.jsx)(t.code,{children:"tar-fs"})})," for ",(0,n.jsxs)(t.a,{href:"https://github.com/electron/electronjs.org/blob/0205b5ab26c96a95121bc564c5824f92108677e0/lib/fetch-docs.js#L63-L65",children:["streaming just the ",(0,n.jsx)(t.code,{children:"/docs"})," directory"]})," from the tarball and ",(0,n.jsx)(t.a,{href:"https://github.com/electron/electronjs.org/blob/0205b5ab26c96a95121bc564c5824f92108677e0/lib/fetch-docs.js#L68-L78",children:"filtering and processing the files"})," (with the help of ",(0,n.jsx)(t.a,{href:"http://npmjs.com/through2",children:(0,n.jsx)(t.code,{children:"through2"})}),") so that they work nicely with our Jekyll site (more on that below)."]}),"\n"]}),"\n",(0,n.jsxs)(t.p,{children:[(0,n.jsx)(t.a,{href:"https://github.com/electron/electronjs.org/tree/gh-pages/spec",children:"Tests"})," help us know that all the bits and pieces landed as expected."]}),"\n",(0,n.jsx)(t.h3,{id:"jekyll",children:"Jekyll"}),"\n",(0,n.jsxs)(t.p,{children:["The Electron website is a Jekyll site and we make use of the ",(0,n.jsx)(t.a,{href:"http://jekyllrb.com/docs/collections/",children:"Collections"})," feature for the docs with a structure like this:"]}),"\n",(0,n.jsx)(t.pre,{children:(0,n.jsx)(t.code,{className:"language-bash",children:"electron.atom.io\n\u2514\u2500\u2500 _docs\n \u251C\u2500\u2500 latest\n \u251C\u2500\u2500 v0.27.0\n \u251C\u2500\u2500 v0.26.0\n \u251C\u2500\u2500 so on\n \u2514\u2500\u2500 so forth\n"})}),"\n",(0,n.jsx)(t.h4,{id:"front-matter",children:"Front matter"}),"\n",(0,n.jsxs)(t.p,{children:["For Jekyll to render each page it needs at least empty front matter. We're going to make use of front matter on all of our pages so while we're streaming out the ",(0,n.jsx)(t.code,{children:"/docs"})," directory we check to see if a file is the ",(0,n.jsx)(t.code,{children:"README.md"})," file (in which case it receives one front matter configuration) or if it is any other file with a markdown extension (in which case it receives slightly different front matter)."]}),"\n",(0,n.jsx)(t.p,{children:"Each page receives this set of front matter variables:"}),"\n",(0,n.jsx)(t.pre,{children:(0,n.jsx)(t.code,{className:"language-yaml",children:"---\nversion: v0.27.0\ncategory: Tutorial\ntitle: 'Quick Start'\nsource_url: 'https://github.com/electron/electron/blob/master/docs/tutorial/quick-start.md'\n---\n"})}),"\n",(0,n.jsxs)(t.p,{children:["The ",(0,n.jsx)(t.code,{children:"README.md"})," gets an additional ",(0,n.jsx)(t.code,{children:"permalink"})," so that has a URL has a common root of ",(0,n.jsx)(t.code,{children:"index.html"})," rather than an awkward ",(0,n.jsx)(t.code,{children:"/readme/"}),"."]}),"\n",(0,n.jsx)(t.pre,{children:(0,n.jsx)(t.code,{className:"language-yaml",children:"permalink: /docs/v0.27.0/index.html\n"})}),"\n",(0,n.jsx)(t.h4,{id:"config-and-redirects",children:"Config and Redirects"}),"\n",(0,n.jsxs)(t.p,{children:["In the site's ",(0,n.jsx)(t.code,{children:"_config.yml"})," file a variable ",(0,n.jsx)(t.code,{children:"latest_version"})," is set every time the ",(0,n.jsx)(t.code,{children:"--latest"})," flag is used when fetching docs. We also add a list of all the versions that have been added to the site as well as the permalink we'd like for the entire docs collection."]}),"\n",(0,n.jsx)(t.pre,{children:(0,n.jsx)(t.code,{className:"language-yaml",children:"latest_version: v0.27.0\navailable_versions:\n - v0.27.0\ncollections:\n docs: { output: true, permalink: '/docs/:path/' }\n"})}),"\n",(0,n.jsxs)(t.p,{children:["The file ",(0,n.jsx)(t.code,{children:"latest.md"})," in our site root is empty except for this front matter which allows users to see the index (aka ",(0,n.jsx)(t.code,{children:"README"}),") of the latest version of docs by visiting this URL, ",(0,n.jsx)(t.a,{href:"https://electronjs.org/docs/latest",children:"electron.atom.io/docs/latest"}),", rather than using the latest version number specifically (though you can do that, too)."]}),"\n",(0,n.jsx)(t.pre,{children:(0,n.jsx)(t.code,{className:"language-yaml",children:"---\npermalink: /docs/latest/\nredirect_to: /docs/{{ site.data.releases[0].version }}\n---\n"})}),"\n",(0,n.jsx)(t.h4,{id:"layouts",children:"Layouts"}),"\n",(0,n.jsxs)(t.p,{children:["In the ",(0,n.jsx)(t.code,{children:"docs.html"})," layout template we use conditionals to either show or hide information in the header and breadcrumb."]}),"\n",(0,n.jsx)(t.pre,{children:(0,n.jsx)(t.code,{className:"language-html",children:"{% raw %} {% if page.category != 'ignore' %}\n<h6 class=\"docs-breadcrumb\">\n {{ page.version }} / {{ page.category }} {% if page.title != 'README' %} / {{\n page.title }} {% endif %}\n</h6>\n{% endif %} {% endraw %}\n"})}),"\n",(0,n.jsxs)(t.p,{children:["To create a page showing the versions that are available we just loop through the list in our
1config on a file, ",(0,n.jsx)(t.code,{children:"versions.md"}),", in the site's root. Also we give this page a permalink: ",(0,n.jsx)(t.code,{children:"/docs/"})]}),"\n",(0,n.jsx)(t.pre,{children:(0,n.jsx)(t.code,{className:"language-html",children:"{% raw %} {% for version in site.available_versions %} - [{{ version\n}}](/docs/{{ version }}) {% endfor %} {% endraw %}\n"})}),"\n",(0,n.jsxs)(t.p,{children:["Hope you enjoyed these technical bits! If you're interested in more information on using Jekyll for documentation sites, checkout how GitHub's docs team publishes ",(0,n.jsx)(t.a,{href:"https://github.com/blog/1939-how-github-uses-github-to-document-github",children:"GitHub's docs on Jekyll"}),"."]})]})}function d(e={}){let{wrapper:t}={...(0,r.R)(),...e.components};return t?(0,n.jsx)(t,{...e,children:(0,n.jsx)(h,{...e})}):h(e)}},28453(e,t,o){o.d(t,{R:()=>i,x:()=>l});var s=o(96540);let n={},r=s.createContext(n);function i(e){let t=s.useContext(r);return s.useMemo(function(){return"function"==typeof e?e(t):{...t,...e}},[t,e])}function l(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(n):e.components||n:i(e.components),s.createElement(r.Provider,{value:t},e.children)}},286(e){e.exports=JSON.parse('{"permalink":"/blog/electron-doumentation","source":"@site/blog/electron-doumentation.md","title":"Electron Documentation","description":"This week we\'ve given Electron\'s documentation a home on electronjs.org. You can visit /docs/latest for the latest set of docs. We\'ll keep versions of older docs, too, so you\'re able to visit /docs/vX.XX.X for the docs that correlate to the version you\'re using.","date":"2015-06-04T00:00:00.000Z","tags":[{"inline":false,"label":"Website","permalink":"/blog/tags/website","description":"Updates on the electronjs.org website and docs"}],"readingTime":4.22,"hasTruncateMarker":false,"authors":[{"name":"jlord","url":"https://github.com/jlord","imageURL":"https://github.com/jlord.png?size=96","key":"jlord","page":null}],"frontMatter":{"title":"Electron Documentation","date":"2015-06-04T00:00:00.000Z","authors":"jlord","slug":"electron-doumentation","tags":["website"]},"unlisted":false,"prevItem":{"title":"Electron Meetup at GitHub HQ","permalink":"/blog/electron-meetup"},"nextItem":{"title":"Atom Shell is now Electron","permalink":"/blog/electron"}}')}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.