Skip to content

Home

Jump to bottom
eliselavy edited this page Nov 22, 2024 · 27 revisions

Welcome to the journal-of-digital-history wiki!

How to create a Call For Papers CFP

Create a notebook

Call for papers are notebooks stored in the cfp folder in the jdh-notebook repo. The absolute url of the raw path is stored in the .env file as REACT_APP_NOTEBOOK_CFP_BASE_URL and uses our github proxy. Each folder must contain a notebook having the same name and usually contains ancillary assets, like the social media image for instance.

Insert metadata for the social metadata

Insert the metadata at the notebook level related to the social media. For notebook level: in the Jupyter Notebook Toolbar go to Edit -> Edit Notebook Metadata. Insert the JSON structure with the appropriate values.

  "authors": [],
  "jdh": {
   "helmet": {
    "og:description": "Special issue | Call for Papers",
    "og:image": "https://raw.githubusercontent.com/C2DH/jdh-notebook/master/cfp/history-of-the-web/socialmediacover.png",
    "og:title": "Web History of Society and Social Institutions (History Seeing Through the Web)",
    "twitter:card": "summary_large_image",
    "twitter:data1": "31 May 2022",
    "twitter:data2": "30 November 2022",
    "twitter:label1": "Deadline",
    "twitter:label2": "Full submissions due",
    "twitter:site": "@Journal_DigHist"
   },

You can have a look at our notebook for a special issue on the history of the Web to see how to structure a call for paper notebook.

Generate social media

The template is available here The image need to be inserted in the cfp notebook folder.

How to update the title and the introduction in the Homepage

Introduction on the homepage is loaded from the markdown of the wiki Homepage

Note for the developers:

The url shipping the source markdown has been included in the .env file of the project as REACT_APP_WIKI_HOMEPAGE variable. If the page is renamed or moved, just remember to update the env file.

How to update the News in the home page

News on the homepage are items loaded from the JSON field in the News wiki page. Beware: as soon as the changes are committed to the wiki page, the journal website updates contents accordingly as Github doesn't provide wiki with * git branches*. Please check the JSON syntax of the whole block using one of the JSON linters available online, like e.g; jsonlint

How to update the Guidelines for the authors

The Guidelines structure has been updated by splitting them into sections. Each section is defined by an H2 heading in the main markdown file on the Guidelines page in this wiki. The paragraph below each H2 heading contains a list of links to the section content, pointing to their respective .ipynb files, usually stored in the jdh-notebook repository.

Note that the headings themselves are not used as titles of tabs on the Guidelines page (at least in the current version). Instead, we use the text of the links provided in the paragraph, i.e., the characters between the square brackets [ ]:

## TLDR; Styleguide for the Notebooks
[Introduction](https://github.com/C2DH/jdh-notebook/blob/master/examples/Author_Guideline/AuthorGuideline-introduction.ipynb)
[Styling and make up](https://github.com/C2DH/jdh-notebook/blob/master/examples/Author_Guideline/AuthorGuideline-styling.ipynb)

On the website, you will see "Introduction" and "Styling and make up" as tabs.

Refer to the how to write the contents for the Guidelines page section in the wiki for detailed instructions on writing each .ipynb file. To preview changes in the .ipynb notebooks, use the "preview notebook" page on the Journal website with the URL of the .ipynb file on GitHub.

Note for editors - ONLY if you need to change the title of the Guidelines:

As soon as the changes are committed on the wiki page, the journal website updates contents accordingly. If you want to work on the main guidelines wiki page without immediately publishing it, you should rather create a new wiki page, e.g. Guidelines.V3 and update the REACT_APP_WIKI_GUIDELINES variable on your local instance of journal-of-digital-history to preview the result (see Note for the developers below). Only then you can create and submit a PR and ask the repo maintainer to review your changes.

Note for the developers:

The URL of the wiki page containing all sections of the Guidelines is included in the project's .env file as the REACT_APP_WIKI_GUIDELINES variable. Do not change this unless the file is renamed or moved. If it is, remember to update the .env file.

How to update the template used by the authors?

The .ipynb file for the template used by the authors is available at the following address: author_guideline_template.ipynb.

This template path is referenced in the guidelines and belongs to a template repository that is used by the authors.

How to update the About and Terms of use page contents?

Contents are served via this wiki, resp. About and Terms Of Use pages. The titles and subheading of these pages are stored for the moment being in the translations.json file, but soon they'll move to the related wiki page.

How To update the events in the milestone section of the homepage?

The list of events is in the JSON field of the Event wiki page:

Screenshot 2022-03-22 at 11 34 11 Screenshot 2022-03-22 at 11 36 06

Pay attention to the scrollTop property: this is the offset in px from the horizontal line. It changes its behaviour whether the top property is present, becoming the negative offset in px from the horizontal line.

The title property contains html code, so it is possible to add link using the <a href=""></a> tag.

https://docs.google.com/spreadsheets/d/1KDNVROeocQy2hwqsD_5aoc9imGbC5ytIKGKBIkNq1co/edit#gid=0

How to update the What's news popup

The popup modal dialog window pops up whenever a new entry is added to the Video-Releases wiki inside the JSON code block and always refers to a Vimeo video with chapters, see chapters docs. The JSON is a list of release notifications, each containing the notification date startDate as valid ISO date referring to the Vimeo video. Chapters labels used in Vimeo are then used as

The JSON code block contain a list of release notifications that contains the notification date startDate as valid ISO date and must refer to the Vimeo video and to its chapters. The frontend app only loads the first object, so the JSON block usually looks like this:

[
  {
     "release": "Your awesome release title and version",
     "title": "What's new?",
     "vimeoUrl": "https://player.vimeo.com/video/763441666?h=1efefa8f4c",
     "startDate": "2022-10-28T00:00:00.000Z",
     "chapterContents": {
       "chapter label as it is written in your Vimeo chapter": [
         "chapter description that appears in the popup"
       ]
     }
  }
]

This is how it looks:

Screenshot 2022-10-28 at 10 02 30

Note for the developers:

We included the wiki url that contains the JSON contents in the .env file of the project as REACT_APP_WIKI_VIDEO_RELEASES variable. This corresponds to the wiki .md source file. In our case the source file is Video-Releases.md If the file is renamed or moved place, just remember to update the env file.

Relevant code in the VideoReleaseLazy component, check the console:

if (currentRelease.startDate < releaseNotified) {
    console.info('%creleaseNotified', 'font-weight: bold', 'already notified, skipping.')
    return null
  } else {
    console.info('%creleaseNotified', 'font-weight: bold', 'please notify!',
      '\n - releaseNotified date:', releaseNotified,
      '\n - currentRelease.startTime:', currentRelease.startDate)
  }

How to write "static" pages (e;g. like blogpost or announcements)

To create a static page, such as a blog post or announcement, on our website, you'll need to utilize github wiki pages feature. Begin by drafting your announcement on a wiki page. Ensure that your announcement starts with a second-level heading to maintain consistency with our page style:

## This will be the first paragraph.
Then the rest of the content

Once you've finalized your wiki page, copy the URL from the browser's address bar. Remember to avoid using "-" or any special character in the title of the page to ensure a proper address bar display! Then, navigate to the special wiki page titled Available Pages and paste the copied link there, one link per line, order doesn't matter. Then create a proper markdown link with a good-looking title. Note that this title will be the final one!:

[My beautifully written Page title](https://github.com/C2DH/journal-of-digital-history/wiki/my-awesome-page)
[Another beautifully written Page title](https://github.com/C2DH/journal-of-digital-history/wiki/another-great-page)

This will make your announcement easily accessible to visitors. For an example of a well-drafted announcement, you can refer to this one and its line on Available Pages:

[The Journal of Digital History switches to single‐blind peer review](https://github.com/C2DH/journal-of-digital-history/wiki/The-Journal-of-Digital-History-switches-to-single-blind-peer-review)

Note for the developers:

Relevant code is in /src/pages/Page component. Should you run into issues, make sure that the env variables process.env.REACT_APP_WIKI_AVAILABLE_PAGES and process.env.REACT_APP_WIKI_ROOT are correctly written in the .env file. Current values:

REACT_APP_WIKI_ROOT=https://raw.githubusercontent.com/wiki/c2dh/journal-of-digital-history
REACT_APP_WIKI_AVAILABLE_PAGES=https://raw.githubusercontent.com/wiki/c2dh/journal-of-digital-history/Available-Pages.md

How to write the contents for the Guidelines page

  1. Create a new Jupyter Notebook file (in VS code it is much easier, because it is markdown + python). Add the content and instructions specific to the section of the guideline you want to cover. Include any necessary code snippets, explanations or examples.

  2. Do not use the first header level, but only the second and optionally the third (only if really necessary).

  3. Save the Jupyter Notebook file with a user-friendly file name: only lowercase characters a-z and - instead of spaces. The file name will be used on the web as part of the url, i.e. always imagine the file name in context, e.g. for an imaginary "introduction to figures" we would expect something like https://journalofdigitalhistory.org/en/guidelines/introduction-to-figures.

  4. Then add -raw' to the file name, so that you would have this as file name: introduction-to-figures-raw.ipynb`.

  5. Now, add a correctly identifiable section before the line - name: commit action to the github action defined in ./.github/workflows/prepare-guideline-notebooks.yml, checking the name and id properties:

  - 
    name: Introduction to figures
    id: introduction-to-figures
    uses: c2dh/journal-of-digital-history-ipynb-skim-action@master
    with:
      notebook: 'examples/Author_Guideline/introduction-to-figures-raw.ipynb'
      output_notebook: 'examples/Author_Guideline/introduction-to-figures.ipynb'

As you can see, our skimmed actionc2dh/journal-of-digital-history-ipynb-skim-action will skim the "raw" notebook and will save the results in the file name defined in the output_notebook variable.

  1. Take note of the github url where you can preview the notebook, e.g. https://github.com/C2DH/jdh-notebook/blob/master/examples/Author_Guideline/introduction-to-figures.ipynb

  2. Edit the wiki page Guidelines and add the link to the notebook to the relevant section - feel free to add another section if needed.

## Figures

[Quick introduction to the figures](https://github.com/C2DH/jdh-notebook/blob/master/examples/Author_Guideline/introduction-to-figures.ipynb)

The label of the url, in our case "Quick introduction to the figures" will be displayed in the website in the table of contents.

  1. Finally, run the task from action page
Screenshot 2023-06-08 at 15 36 38

How to publish a new issue / new article

At the issue level

  • Issue need to be define here and set to status PUBLISHED

Note

Following action required to redeploy the frontend

  • A social media cover needs to be generated and store here
  • Path in the index.html needs to take into account this new issue for property og:image / twitter:image

At the article level

  • Article needs to be created here attached to the related issue
  • For copyright assure the document has been signed and save to Atlas
  • Set the article to PUBLISHED and fill the field PUBLICATION DATE

Warning

A social media cover is mandatory - need to be present in the GitHub 's repository

  • Generate the preload information (in order to have the path of the social media cover image registered)
  • Generate the citation
  • Generate the fingerprint
  • Add tag new
  • Generate tag TOOLS/NARRATIVE
Clone this wiki locally