31:T613,## 1. General Project Structure Generally, the structure of your app may look something like this:

${render_filetree({
  "project_dir/":{
    ".git/": null,
    ".gitignore": null,
    "src/": {
      "index.md": null,
      "(Other .md files)": null,
      "components/": {
        "JavaScript files": null,
        "Data importers": null,
      },
      "data": {
        "(raw json, csv, etc. datasets)": null
      },
      "img/": {
        "(.png, .jpg)": null
      },
      "observable.png": null
    },
    "node_modules/": null,
    "observablehq.config.js": null,
    "package.json": null,
    "package-lock.json": null,
    "README.md": null
  }
})}

Most files will live inside of the `src/` directory. It's generally good practice to separate files based on functionality. - **Markdown files** (`.md`) represent your webpages in your dashboard. They can contain Markdown, JavaScript, and HTML. They will exist as direct children of the `src/` directory. - **JavaScript files** (`.js`) handle under-the-hood operations and are likely to exist in their own `components/` directory. - **Dataset files** (e.g. `.json`, `.csv`, `.xlsx`) also are likely to have their own `data/` directory. - **Image files** (e.g. `.png`, `.jpg`) are also likely to have their own `img/` directory.

[NOTE]: These are not hard-coded requirements - you can technically have JavaScript files alongside Markdown files as siblings within `src/`. Still, it's generally better to stay organized.

32:Tbe1,## 3. Working with Markdown Files - Differences with Observable In _Framework_, Markdown files can juggle [Markdown syntax](https://www.markdownguide.org/), [HTML](https://www.w3schools.com/html/html_intro.asp), and JavaScript simultaneously. Here are two side-by-side comparisons between what an Observable notebook may look like, and what the equivalent would be in a _Framework_ Markdown file: ${await FileAttachment("observable_ex.png").image({width:500})}

# Hello World

```js
const cube = await FileAttachment("./img/cube.png").image({width:300});
display(cube);
```

As you can see, JavaScript portions must be wrapped with a ```js to let _Framework_ know that the content inside must be treated as JavaScript. Furthermore, unlike Observable's cell-based logic, JavaScript segments in your Markdown files 1) don't need to return anything, and 2) require additional steps such as `display()` to render content.

[NOTE]: Why do we use `await` here? This is because the `FileAttachment()` function actually returns a Promise, which is a specific JavaScript handler that is used when working with asynchronous data. Because it can take a while to load data (especially if the data might be very large), _Framework_ considers any kind of data-loading as an asynchronous operation. If you want to learn more, look up Promises and await/async operations.

However, if the `FileAttachment()` function is **isolated to its own JavaScript block**, then the `await` is not needed.

### Rendering JS Outputs: 2 Ways There are two primary ways to render content outputted by JavaScript (i.e. D3 charts, images imported via `FileAttachment()`): #### Method #1: Use JavaScript's `display()` If you saved your content inside a variable (e.g. the `cube` variable inside of the Markdown example above), you can use `display()` within a JavaScript segment to render it. #### Method #2: Use the ${} Syntax Let's say you want to embed your JavaScript output inside of HTML. A common case would be that you want to insert a plot or D3 chart within some HTML that you've coded to fit a specific format. In that case, you can embed the variable within HTML directly. See the example below:

```js
const cube = await FileAttachment("./img/cube.png").image({width:300});
```

<div class="some-formatted-html">${cube}</div>

This will render the same cube image like in the above example.

[NOTE]: Be careful with images. If you use `FileAttachment()` to load images, then it gets wonky working with image widths and CSS styling. I recommend just using normal HTML <img src="" /> to handle images.

33:[{"id":"4f342852d097a2e890ab656fed515fb05f8e460e74fbdae979e31695a58ee444d0962971bff66fad887101c5d27035c1b0f6bb6d57e9d764c529a6db69ebde2d","href":"https://static.observableusercontent.com/files/4f342852d097a2e890ab656fed515fb05f8e460e74fbdae979e31695a58ee444d0962971bff66fad887101c5d27035c1b0f6bb6d57e9d764c529a6db69ebde2d","name":"nav-bar.png","type":"image/png","lastModified":1760706154245.971,"size":19642},{"id":"d1e2633e99696cf8f72ed362c0141d61f2e557e5cab7e782d83777704c520a801fd640baa715b9bc9235ab16c4e4c2d04abf4643ac9f9524e5d05ab8f624bc25","href":"https://static.observableusercontent.com/files/d1e2633e99696cf8f72ed362c0141d61f2e557e5cab7e782d83777704c520a801fd640baa715b9bc9235ab16c4e4c2d04abf4643ac9f9524e5d05ab8f624bc25","name":"framework_ex.png","type":"image/png","lastModified":1760707498289.06,"size":13296},{"id":"bac8637d6c7f43de24a4fdb37a03faf66e170bd4d8c6ca88889067064b4f1c135d2fe67a65d1e770337dcdd03aa3b753e9d40b155494ea37c2881e833fe151d8","href":"https://static.observableusercontent.com/files/bac8637d6c7f43de24a4fdb37a03faf66e170bd4d8c6ca88889067064b4f1c135d2fe67a65d1e770337dcdd03aa3b753e9d40b155494ea37c2881e833fe151d8","name":"observable_ex.png","type":"image/png","lastModified":1760707498319.651,"size":92209}] 2f:{"title":"Framework Guide #2: Project Organization","cells":[{"id":0,"value":"# Framework Guide #2: Project Organization\n\n

Feel free to refer to [_this Github Repository_](https://github.com/kimryan0416/Observable-Framework-Demo), which contains the _Framework_ project that this guide is based off of.

","pinned":false,"hidden":false,"mode":"md"},{"id":64,"value":"In our [_previous guide_](https://observablehq.com/@rk2546/guide-local_observable_setup), we set up the start of a _Framework_ project. This guide covers the following topics:\n\n1. [_General Project Structure_](#cell-9)\n2. [_Page Management_](#cell-55)\n3. [_Working with Markdown Files - Differences with Observable_](#cell-15)\n\n

[NOTE]: At this point, you are expected to have an (close to) empty _Framework_ project setup from our previous guide. You are also expected to be familiar with basic levels of [Markdown syntax](https://www.markdownguide.org/), [HTML](https://www.w3schools.com/html/html_intro.asp), and JavaScript.

\n\nMake sure to run a development preview of your website by running the following command:\n\n

\n# If you're using `npm`\nnpm run dev\n

","pinned":false,"hidden":false,"mode":"md"},{"id":9,"value":"$31","pinned":false,"hidden":false,"mode":"md"},{"id":55,"value":"## 2. Page Management\n\nWhenever you save a change and you are running a development preview (i.e. `npm run dev`), your _Framework_ project will look for and detect any `.md` Markdown files you created. It will consider any `.md` file as its own webpage and will auto-reflect that in the navigation bar that comes with _Framework_ projects.\n\n${await FileAttachment(\"nav-bar.png\").image({width:500})}\n\nIn this example, there are **3** markdown files in this _Framework_ project:\n\n- `index.md`: The landing page of the website\n- `example-dashboard.md`\n- `example-report.md`","pinned":false,"hidden":false,"mode":"md"},{"id":15,"value":"$32","pinned":false,"hidden":false,"mode":"md"},{"id":105,"value":"## What's Next?\n\nThe next step is to practice using D3 to actually load and generate charts directly within a _Framework_ page. Follow us to the next guide in the series: [_Importing Functions, NPM Modules, and Observable Notebooks_](https://observablehq.com/@rk2546/guide-imports).\n\nAlternatively, you can check out other guides in our _Framework_ series:\n\n${framework_guides}\n\n### Additional Materials\n\n- [Framework Documentation: Getting Started](https://observablehq.com/framework/getting-started)\n- [Markdown Syntax](https://www.markdownguide.org/)\n- [HTML Syntax](https://www.w3schools.com/html/html_intro.asp)","pinned":false,"hidden":false,"mode":"md"},{"id":108,"value":"---\n\n## Appendix","pinned":false,"hidden":false,"mode":"md"},{"id":13,"value":"import { css, render_filetree, framework_guides } from '@rk2546/2025-infovis-cse_notebook-gallery';","pinned":false,"hidden":false,"mode":"ojs"},{"id":19,"value":"css","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W33","stdlib":"1","titling":"auto"}