An easy way to create a website for scientific software project

Size: px

Start display at page:

Download "An easy way to create a website for scientific software project"

Valerie Douglas
5 years ago
Views:

1 An easy way to create a website for scientific software project Gennady Pospelov Scientific Computing Group at MLZ Workshop on Neutron Scattering Data Analysis Software 6-8 June, 2018, Sorangna

2 Choice of technology Content management systems or Static site generators 02

3 Content management systems Generates html dynamically from content written in database Advantages Supports multiple users working in collaborative environment Generates html depending on user type Allows to add/edit content from the browser Disadvantages Very peculiar workflow Crazy learning curve 03

4 Content management systems Generates html dynamically from content written in database Advantages Supports multiple users working in collaborative environment Generates html depending on user type Allows to add/edit content from the browser Disadvantages Very peculiar workflow Crazy learning curve 03

5 Static site generators Generates static html from markdown content Advantages Speed Version control for content Security Less hassle with the hosting Disadvantages No real time content No input from bloggers 04

8 Website requirements for scientific software project Modern Good looking Responsive design 06

9 Website requirements for scientific software project Modern Good looking Responsive design Easy to contribute and maintain Content focused Under git control No database Familiar workflow 06

10 Website requirements for scientific software project Modern Good looking Responsive design Easy to contribute and maintain Content focused Under git control No database Familiar workflow Documentation oriented Automatic generation of navigation elements from content Code highlight Latex support Responsive images and image galleries Automatic update of site content on new release, versioning 06

11 Website requirements for scientific software project Modern Good looking Responsive design Easy to contribute and maintain Content focused Under git control No database Familiar workflow Documentation oriented Automatic generation of navigation elements from content Code highlight Latex support Responsive images and image galleries Automatic update of site content on new release, versioning Should still have all attributes of normal website Landing, Download, About pages Taxonomy 06

16 Outline Choice of technology Necessary introduction to html and css Markdown + Hugo static site generator BornAgain website and its theme Documentation workflow 11

17 Html Markup language for creating web pages Tags to structure the content head, title, body, h1, p, article, nav, figure, img Attributes to steer the behavior of certain tag 12

18 Html in good old days Content is heavily mixed with attributes 13

19 Html nowadays Content is separated from the presentation page.html theme.css 14

20 CSS frameworks Collection of css classes for standards-compliant web design Grid system for responsive web design Web typography Unified styling for all elements (lists, tables, buttons, links etc) Additional UI elements (accordions, tabs, cards) 15

21 Bootstrap css framework World s most popular front-end component library Example of possible layout 16

22 Bootstrap css framework World s most popular front-end component library 17

23 Outline Choice of technology Necessary introduction to html and css Markdown + Hugo static site generator BornAgain website and its theme Documentation workflow 18

24 Markdown Lightweight markup language with plain text formatting syntax Can be converted to html and other formats README.md 19

25 Markdown Lightweight markup language with plain text formatting syntax Can be converted to html and other formats README.html 19

26 Markdown Lightweight markup language with plain text formatting syntax Can be converted to html and other formats README.html + theme.css to style html can give you a modern looking web page, in theory 19

27 Markdown limitations Markup language is very poor No way to define page layout Site menu Site header Page Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. sidebar 20

28 Markdown limitations Markup language is very poor No way to define page layout No way to steer individual object appearance![experimental setup](image.png) 21

29 Static site generators Generate modern looking web site from markdown content Rely on non-markdown inclusions in markdown files 22

30 Static website generators Contains list of static site generators sorted according to a number of given GitHub stars Total number of available generators >

Static website generators Our choice Ultra fast Actively supported Easy to install https://www.staticgen.

31 Static website generators Our choice Ultra fast Actively supported Easy to install Contains list of static site generators sorted according to a number of given GitHub stars Total number of available generators >

32 Outline Choice of technology Necessary introduction to html and css Markdown + Hugo static site generator BornAgain website and its theme Documentation workflow 24

33 BornAgain website and its theme git clone --recurse-submodules Website content Website theme Submodule of Running command hugo in site directory will populate directory public with html version of site 25

34 Content organization 27

35 hugo-theme-scgdoc Documentation theme for Hugo developed by our group hugo-theme-scgdoc Custom layout for all markdown files found in./content/documentation Partials: a single page templates Shortcodes: markdown extensions 28

36 hugo-theme-scgdoc Documentation theme for Hugo developed by our group hugo-theme-scgdoc bootstrap classes Template file for every *.md found in documentation 29

37 hugo-theme-scgdoc Example of Python examples preview embedded-particles.md 30

38 hugo-theme-scgdoc examples-preview.html shortcode responsive layout with bootstrap loop over all children pages Automatic generation of thumbnails for faster page load 31

39 hugo-theme-scgdoc Documentation theme for Hugo developed by our group Contains 900 lines of Hugo templates 500 lines of custom css 10 lines of custom js Functionality Provides multiple page layout Responsive (bootstrap) Automatically generates breadcrumb and menu elements from markdown content Python highlight (snippets, line numbers, embedded files) Responsive galleries Automatic generation of page preview 32

40 Outline Choice of technology Necessary introduction to html and css Markdown + Hugo static site generator BornAgain website and its theme Documentation workflow 33

41 Documentation workflow master branch: markdown content gh-pages branch: html of website GitHub hosting service is configured to show content of gh-pages branch at 34

42 Documentation workflow master branch: markdown content gh-pages branch: html of website GitHub hosting service is configured to show content of gh-pages branch at GitHub hosting merge BornAgain-website Travis pull request Runs Hugo Updates gh-pages Fork push fetch Local 34

43 An easy way to create a website Download latest Hugo Clone our theme git clone Run examplesite locally, modify it to your taste cd hugo-theme-scgdoc/examplesite hugo server -D firefox 35

Doing more with Views. Creating an inline menu

Doing more with Views. Creating an inline menu Doing more with Views Creating an inline menu About Me Caryl Westerberg Web Producer Stanford Web Services Views topics we ll cover Contextual Filters Relationships Global: View result counter Global: